documcp

import { describe, it, expect, beforeEach, afterEach } from '@jest/globals'; import { promises as fs } from 'fs'; import { join } from 'path'; import { analyzeReadme } from '../../src/tools/analyze-readme.js'; import { tmpdir } from 'os'; describe('analyze_readme', () => { let testDir: string; let readmePath: string; beforeEach(async () => { // Create temporary test directory testDir = join(tmpdir(), `test-readme-${Date.now()}`); await fs.mkdir(testDir, { recursive: true }); readmePath = join(testDir, 'README.md'); }); afterEach(async () => { // Cleanup test directory try { await fs.rm(testDir, { recursive: true, force: true }); } catch { // Ignore cleanup errors } }); describe('input validation', () => { it('should require project_path parameter', async () => { const result = await analyzeReadme({}); expect(result.success).toBe(false); expect(result.error?.code).toBe('ANALYSIS_FAILED'); }); it('should handle non-existent project directory', async () => { const result = await analyzeReadme({ project_path: '/non/existent/path', }); expect(result.success).toBe(false); expect(result.error?.code).toBe('README_NOT_FOUND'); }); }); describe('README detection', () => { it('should find README.md file', async () => { const readmeContent = `# Test Project\n\n> A simple test project\n\n## Installation\n\n\`\`\`bash\nnpm install\n\`\`\`\n\n## Usage\n\nExample usage here.`; await fs.writeFile(readmePath, readmeContent); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis).toBeDefined(); }); it('should find alternative README file names', async () => { const readmeContent = `# Test Project\n\nBasic content`; await fs.writeFile(join(testDir, 'readme.md'), readmeContent); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); }); }); describe('length analysis', () => { it('should analyze README length correctly', async () => { const longReadme = Array(400).fill('# Section\n\nContent here.\n').join('\n'); await fs.writeFile(readmePath, longReadme); const result = await analyzeReadme({ project_path: testDir, max_length_target: 300, }); expect(result.success).toBe(true); expect(result.data?.analysis.lengthAnalysis.exceedsTarget).toBe(true); expect(result.data?.analysis.lengthAnalysis.reductionNeeded).toBeGreaterThan(0); }); it('should handle README within target length', async () => { const shortReadme = `# Project\n\n## Quick Start\n\nInstall and use.`; await fs.writeFile(readmePath, shortReadme); const result = await analyzeReadme({ project_path: testDir, max_length_target: 300, }); expect(result.success).toBe(true); expect(result.data?.analysis.lengthAnalysis.exceedsTarget).toBe(false); expect(result.data?.analysis.lengthAnalysis.reductionNeeded).toBe(0); }); }); describe('structure analysis', () => { it('should evaluate scannability score', async () => { const wellStructuredReadme = `# Project Title > Clear description ## Installation \`\`\`bash npm install \`\`\` ## Usage - Feature 1 - Feature 2 - Feature 3 ### Advanced Usage More details here. ## Contributing Guidelines here.`; await fs.writeFile(readmePath, wellStructuredReadme); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.structureAnalysis.scannabilityScore).toBeGreaterThan(50); expect(result.data?.analysis.structureAnalysis.headingHierarchy.length).toBeGreaterThan(0); }); it('should detect poor structure', async () => { const poorStructure = `ProjectTitle\nSome text without proper headings or spacing.More text.Even more text without breaks.`; await fs.writeFile(readmePath, poorStructure); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.structureAnalysis.scannabilityScore).toBeLessThan(50); }); }); describe('content analysis', () => { it('should detect TL;DR section', async () => { const readmeWithTldr = `# Project\n\n## TL;DR\n\nQuick overview here.\n\n## Details\n\nMore info.`; await fs.writeFile(readmePath, readmeWithTldr); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.contentAnalysis.hasTldr).toBe(true); }); it('should detect quick start section', async () => { const readmeWithQuickStart = `# Project\n\n## Quick Start\n\nGet started quickly.\n\n## Installation\n\nDetailed setup.`; await fs.writeFile(readmePath, readmeWithQuickStart); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.contentAnalysis.hasQuickStart).toBe(true); }); it('should count code blocks and links', async () => { const readmeWithCodeAndLinks = `# Project ## Installation \`\`\`bash npm install \`\`\` ## Usage \`\`\`javascript const lib = require('lib'); \`\`\` See [documentation](https://example.com) and [API reference](https://api.example.com).`; await fs.writeFile(readmePath, readmeWithCodeAndLinks); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.contentAnalysis.codeBlockCount).toBe(2); expect(result.data?.analysis.contentAnalysis.linkCount).toBe(2); }); }); describe('community readiness', () => { it('should detect community files', async () => { const readmeContent = `# Project\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).`; await fs.writeFile(readmePath, readmeContent); await fs.writeFile(join(testDir, 'CONTRIBUTING.md'), 'Contributing guidelines'); await fs.writeFile(join(testDir, 'CODE_OF_CONDUCT.md'), 'Code of conduct'); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.communityReadiness.hasContributing).toBe(true); expect(result.data?.analysis.communityReadiness.hasCodeOfConduct).toBe(true); }); it('should count badges', async () => { const readmeWithBadges = `# Project [](https://travis-ci.org/user/repo) [](https://badge.fury.io/js/package) Description here.`; await fs.writeFile(readmePath, readmeWithBadges); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.communityReadiness.badgeCount).toBe(2); }); }); describe('optimization opportunities', () => { it('should identify length reduction opportunities', async () => { const longReadme = Array(500) .fill('# Section\n\nLong content here that exceeds target length.\n') .join('\n'); await fs.writeFile(readmePath, longReadme); const result = await analyzeReadme({ project_path: testDir, max_length_target: 200, optimization_level: 'aggressive', }); expect(result.success).toBe(true); expect(result.data?.analysis.optimizationOpportunities.length).toBeGreaterThan(0); expect( result.data?.analysis.optimizationOpportunities.some( (op) => op.type === 'length_reduction', ), ).toBe(true); }); it('should identify content enhancement opportunities', async () => { const basicReadme = `# Project\n\nBasic description.\n\n## Installation\n\nnpm install`; await fs.writeFile(readmePath, basicReadme); const result = await analyzeReadme({ project_path: testDir, target_audience: 'community_contributors', }); expect(result.success).toBe(true); expect( result.data?.analysis.optimizationOpportunities.some( (op) => op.type === 'content_enhancement', ), ).toBe(true); }); }); describe('scoring system', () => { it('should calculate overall score', async () => { const goodReadme = `# Excellent Project > Clear, concise description of what this project does [](https://travis-ci.org/user/repo) [](https://opensource.org/licenses/MIT) ## TL;DR This project solves X problem for Y users. Perfect for Z use cases. ## Quick Start \`\`\`bash npm install excellent-project \`\`\` \`\`\`javascript const project = require('excellent-project'); project.doSomething(); \`\`\` ## Prerequisites - Node.js 16+ - npm or yarn ## Usage Detailed usage examples here. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License MIT © Author`; await fs.writeFile(readmePath, goodReadme); await fs.writeFile(join(testDir, 'CONTRIBUTING.md'), 'Guidelines'); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.overallScore).toBeGreaterThan(70); }); it('should provide lower score for poor README', async () => { const poorReadme = `ProjectName\nSome description\nInstall it\nUse it`; await fs.writeFile(readmePath, poorReadme); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis.overallScore).toBeLessThan(50); }); }); describe('recommendations and next steps', () => { it('should provide relevant recommendations', async () => { const basicReadme = `# Project\n\nDescription`; await fs.writeFile(readmePath, basicReadme); const result = await analyzeReadme({ project_path: testDir, target_audience: 'community_contributors', optimization_level: 'moderate', }); expect(result.success).toBe(true); expect(result.data?.analysis.recommendations.length).toBeGreaterThan(0); expect(result.data?.nextSteps.length).toBeGreaterThan(0); }); it('should tailor recommendations to target audience', async () => { const readmeContent = `# Enterprise Tool\n\nBasic description`; await fs.writeFile(readmePath, readmeContent); const result = await analyzeReadme({ project_path: testDir, target_audience: 'enterprise_users', }); expect(result.success).toBe(true); expect( result.data?.analysis.recommendations.some( (rec) => rec.includes('enterprise') || rec.includes('security') || rec.includes('support'), ), ).toBe(true); }); }); describe('project context detection', () => { it('should detect JavaScript project', async () => { const readmeContent = `# JS Project\n\nA JavaScript project`; await fs.writeFile(readmePath, readmeContent); await fs.writeFile(join(testDir, 'package.json'), '{"name": "test"}'); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); // Should analyze successfully with project context expect(result.data?.analysis).toBeDefined(); }); it('should handle projects without specific type indicators', async () => { const readmeContent = `# Generic Project\n\nSome project`; await fs.writeFile(readmePath, readmeContent); const result = await analyzeReadme({ project_path: testDir, }); expect(result.success).toBe(true); expect(result.data?.analysis).toBeDefined(); }); }); });