documcp

import { describe, it, expect, beforeEach, afterEach } from '@jest/globals'; import { promises as fs } from 'fs'; import * as path from 'path'; import * as tmp from 'tmp'; import { validateReadmeChecklist, ReadmeChecklistValidator, ValidateReadmeChecklistSchema, } from '../../src/tools/validate-readme-checklist'; describe('README Checklist Validator', () => { let tempDir: string; let validator: ReadmeChecklistValidator; beforeEach(() => { tempDir = tmp.dirSync({ unsafeCleanup: true }).name; validator = new ReadmeChecklistValidator(); }); afterEach(async () => { try { await fs.rmdir(tempDir, { recursive: true }); } catch { // Ignore cleanup errors } }); async function createTestReadme(content: string, filename = 'README.md'): Promise<string> { const readmePath = path.join(tempDir, filename); await fs.writeFile(readmePath, content, 'utf-8'); return readmePath; } async function createProjectFile(filename: string, content = ''): Promise<void> { await fs.writeFile(path.join(tempDir, filename), content, 'utf-8'); } describe('Input Validation', () => { it('should validate required fields', () => { expect(() => ValidateReadmeChecklistSchema.parse({})).toThrow(); expect(() => ValidateReadmeChecklistSchema.parse({ readmePath: '', }), ).toThrow(); }); it('should accept valid input with defaults', () => { const input = ValidateReadmeChecklistSchema.parse({ readmePath: '/path/to/README.md', }); expect(input.strict).toBe(false); expect(input.outputFormat).toBe('console'); }); it('should validate output format options', () => { const validFormats = ['json', 'markdown', 'console']; for (const format of validFormats) { expect(() => ValidateReadmeChecklistSchema.parse({ readmePath: '/test/README.md', outputFormat: format, }), ).not.toThrow(); } expect(() => ValidateReadmeChecklistSchema.parse({ readmePath: '/test/README.md', outputFormat: 'invalid', }), ).toThrow(); }); }); describe('Essential Sections Validation', () => { it('should detect project title', async () => { const goodReadme = await createTestReadme( '# My Project\n\nDescription here', 'good-README.md', ); const badReadme = await createTestReadme( '## Not a main title\n\nNo main heading', 'bad-README.md', ); const goodInput = ValidateReadmeChecklistSchema.parse({ readmePath: goodReadme }); const badInput = ValidateReadmeChecklistSchema.parse({ readmePath: badReadme }); const result = await validateReadmeChecklist(goodInput); const result2 = await validateReadmeChecklist(badInput); const titleCheck = result.categories['Essential Sections'].results.find( (r) => r.item.id === 'title', ); const badTitleCheck = result2.categories['Essential Sections'].results.find( (r) => r.item.id === 'title', ); expect(titleCheck?.passed).toBe(true); expect(badTitleCheck?.passed).toBe(false); }); it('should detect project description', async () => { const withSubtitle = await createTestReadme( '# Project\n\n> A great project description', 'subtitle-README.md', ); const withParagraph = await createTestReadme( '# Project\n\nThis is a description paragraph', 'paragraph-README.md', ); const withoutDesc = await createTestReadme( '# Project\n\n## Installation', 'no-desc-README.md', ); const subtitleResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withSubtitle }), ); const paragraphResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withParagraph }), ); const noDescResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withoutDesc }), ); const getDescCheck = (result: any) => result.categories['Essential Sections'].results.find( (r: any) => r.item.id === 'description', ); expect(getDescCheck(subtitleResult)?.passed).toBe(true); expect(getDescCheck(paragraphResult)?.passed).toBe(true); expect(getDescCheck(noDescResult)?.passed).toBe(false); }); it('should detect TL;DR section', async () => { const withTldr = await createTestReadme( '# Project\n\n## TL;DR\n\nQuick summary', 'tldr-README.md', ); const withQuickStart = await createTestReadme( '# Project\n\n## Quick Start\n\nQuick summary', 'quickstart-README.md', ); const withoutTldr = await createTestReadme( '# Project\n\n## Installation', 'no-tldr-README.md', ); const tldrInput = ValidateReadmeChecklistSchema.parse({ readmePath: withTldr }); const quickStartInput = ValidateReadmeChecklistSchema.parse({ readmePath: withQuickStart }); const noTldrInput = ValidateReadmeChecklistSchema.parse({ readmePath: withoutTldr }); const result = await validateReadmeChecklist(tldrInput); const result2 = await validateReadmeChecklist(quickStartInput); const result3 = await validateReadmeChecklist(noTldrInput); const getTldrCheck = (result: any) => result.categories['Essential Sections'].results.find((r: any) => r.item.id === 'tldr'); expect(getTldrCheck(result)?.passed).toBe(true); expect(getTldrCheck(result2)?.passed).toBe(true); expect(getTldrCheck(result3)?.passed).toBe(false); }); it('should detect installation instructions with code blocks', async () => { const goodInstall = await createTestReadme( ` # Project ## Installation \`\`\`bash npm install project \`\`\` `, 'good-install-README.md', ); const noCodeBlocks = await createTestReadme( ` # Project ## Installation Just install it somehow `, 'no-code-README.md', ); const noInstallSection = await createTestReadme( '# Project\n\nSome content', 'no-install-README.md', ); const goodResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: goodInstall }), ); const noCodeResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: noCodeBlocks }), ); const noSectionResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: noInstallSection }), ); const getInstallCheck = (result: any) => result.categories['Essential Sections'].results.find( (r: any) => r.item.id === 'installation', ); expect(getInstallCheck(goodResult)?.passed).toBe(true); expect(getInstallCheck(noCodeResult)?.passed).toBe(true); // This should pass because it has Installation section expect(getInstallCheck(noSectionResult)?.passed).toBe(false); }); it('should detect usage examples', async () => { const goodUsage = await createTestReadme( ` # Project ## Usage \`\`\`javascript const lib = require('lib'); lib.doSomething(); \`\`\` `, 'good-usage-README.md', ); const noUsage = await createTestReadme('# Project\n\nNo usage section', 'no-usage-README.md'); const goodResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: goodUsage }), ); const noUsageResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: noUsage }), ); const getUsageCheck = (result: any) => result.categories['Essential Sections'].results.find((r: any) => r.item.id === 'usage'); expect(getUsageCheck(goodResult)?.passed).toBe(true); expect(getUsageCheck(noUsageResult)?.passed).toBe(false); }); it('should detect license information', async () => { const readmeWithLicense = await createTestReadme( '# Project\n\n## License\n\nMIT', 'license-README.md', ); const readmeWithoutLicense = await createTestReadme( '# Project\n\nNo license info', 'no-license-README.md', ); // Test without LICENSE file first const withLicenseResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readmeWithLicense, projectPath: tempDir, }), ); const withoutLicenseResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readmeWithoutLicense, projectPath: tempDir, }), ); // Test with LICENSE file await createProjectFile('LICENSE', 'MIT License...'); const readmeWithLicenseFile = await createTestReadme( '# Project\n\nSome content', 'license-file-README.md', ); const withLicenseFileResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readmeWithLicenseFile, projectPath: tempDir, }), ); const getLicenseCheck = (result: any) => result.categories['Essential Sections'].results.find((r: any) => r.item.id === 'license'); expect(getLicenseCheck(withLicenseResult)?.passed).toBe(true); expect(getLicenseCheck(withoutLicenseResult)?.passed).toBe(false); expect(getLicenseCheck(withLicenseFileResult)?.passed).toBe(true); }); }); describe('Community Health Validation', () => { it('should detect contributing guidelines', async () => { const readmeWithContributing = await createTestReadme( '# Project\n\n## Contributing\n\nSee CONTRIBUTING.md', ); await createProjectFile('CONTRIBUTING.md', 'Contributing guidelines...'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readmeWithContributing, projectPath: tempDir, }), ); const contributingCheck = result.categories['Community Health'].results.find( (r) => r.item.id === 'contributing', ); expect(contributingCheck?.passed).toBe(true); }); it('should detect code of conduct', async () => { await createProjectFile('CODE_OF_CONDUCT.md', 'Code of conduct...'); const readme = await createTestReadme('# Project\n\nSome content'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme, projectPath: tempDir }), ); const cocCheck = result.categories['Community Health'].results.find( (r) => r.item.id === 'code-of-conduct', ); expect(cocCheck?.passed).toBe(true); }); it('should detect security policy', async () => { await createProjectFile('SECURITY.md', 'Security policy...'); const readme = await createTestReadme('# Project\n\nSome content'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme, projectPath: tempDir }), ); const securityCheck = result.categories['Community Health'].results.find( (r) => r.item.id === 'security', ); expect(securityCheck?.passed).toBe(true); }); }); describe('Visual Elements Validation', () => { it('should detect status badges', async () => { const withBadges = await createTestReadme( ` # Project [](https://travis-ci.org/user/repo) [](https://badge.fury.io/js/package) `, 'with-badges-README.md', ); const withoutBadges = await createTestReadme( '# Project\n\nNo badges here', 'no-badges-README.md', ); const withBadgesResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withBadges }), ); const withoutBadgesResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withoutBadges }), ); const getBadgeCheck = (result: any) => result.categories['Visual Elements'].results.find((r: any) => r.item.id === 'badges'); expect(getBadgeCheck(withBadgesResult)?.passed).toBe(true); expect(getBadgeCheck(withoutBadgesResult)?.passed).toBe(false); }); it('should detect screenshots and images', async () => { const withScreenshots = await createTestReadme( ` # Project   `, 'with-screenshots-README.md', ); const withoutScreenshots = await createTestReadme( '# Project\n\nNo images', 'no-screenshots-README.md', ); const withScreenshotsResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withScreenshots }), ); const withoutScreenshotsResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withoutScreenshots }), ); const getScreenshotCheck = (result: any) => result.categories['Visual Elements'].results.find((r: any) => r.item.id === 'screenshots'); expect(getScreenshotCheck(withScreenshotsResult)?.passed).toBe(true); expect(getScreenshotCheck(withoutScreenshotsResult)?.passed).toBe(false); }); it('should validate markdown formatting', async () => { const goodFormatting = await createTestReadme( ` # Main Title ## Section 1 ### Subsection ## Section 2 `, 'good-formatting-README.md', ); const poorFormatting = await createTestReadme( ` # Title #Another Title ##Poor Spacing `, 'poor-formatting-README.md', ); const goodResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: goodFormatting }), ); const poorResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: poorFormatting }), ); const getFormattingCheck = (result: any) => result.categories['Visual Elements'].results.find((r: any) => r.item.id === 'formatting'); expect(getFormattingCheck(goodResult)?.passed).toBe(true); expect(getFormattingCheck(poorResult)?.passed).toBe(false); }); }); describe('Content Quality Validation', () => { it('should detect working code examples', async () => { const withCodeExamples = await createTestReadme( ` # Project \`\`\`javascript const lib = require('lib'); lib.doSomething(); \`\`\` \`\`\`bash npm install lib \`\`\` `, 'with-code-README.md', ); const withoutCodeExamples = await createTestReadme( '# Project\n\nNo code examples', 'no-code-examples-README.md', ); const withCodeResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withCodeExamples }), ); const withoutCodeResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: withoutCodeExamples }), ); const getCodeCheck = (result: any) => result.categories['Content Quality'].results.find( (r: any) => r.item.id === 'working-examples', ); expect(getCodeCheck(withCodeResult)?.passed).toBe(true); expect(getCodeCheck(withoutCodeResult)?.passed).toBe(false); }); it('should validate appropriate length', async () => { const shortReadme = await createTestReadme('# Project\n\nShort content', 'short-README.md'); const longContent = '# Project\n\n' + 'Long line of content.\n'.repeat(350); const longReadme = await createTestReadme(longContent, 'long-README.md'); const shortResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: shortReadme }), ); const longResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: longReadme }), ); const getLengthCheck = (result: any) => result.categories['Content Quality'].results.find( (r: any) => r.item.id === 'appropriate-length', ); expect(getLengthCheck(shortResult)?.passed).toBe(true); expect(getLengthCheck(longResult)?.passed).toBe(false); }); it('should validate scannable structure', async () => { const goodStructure = await createTestReadme( ` # Main Title ## Section 1 ### Subsection 1.1 - Item 1 - Item 2 ### Subsection 1.2 ## Section 2 ### Subsection 2.1 - Another item - Yet another item `, 'good-structure-README.md', ); const poorStructure = await createTestReadme( ` # Title #### Skipped levels ## Back to level 2 `, 'poor-structure-README.md', ); const goodResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: goodStructure }), ); const poorResult = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: poorStructure }), ); const getStructureCheck = (result: any) => result.categories['Content Quality'].results.find( (r: any) => r.item.id === 'scannable-structure', ); expect(getStructureCheck(goodResult)?.passed).toBe(true); expect(getStructureCheck(poorResult)?.passed).toBe(false); }); }); describe('Report Generation', () => { it('should generate comprehensive report with all categories', async () => { const readme = await createTestReadme(` # Test Project > A test project description ## TL;DR Quick summary of the project. ## Quick Start \`\`\`bash npm install test-project \`\`\` ## Usage \`\`\`javascript const test = require('test-project'); test.run(); \`\`\` ## License MIT `); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme }), ); expect(result.overallScore).toBeGreaterThan(0); expect(result.totalItems).toBeGreaterThan(0); expect(result.passedItems).toBeGreaterThan(0); expect(result.categories).toHaveProperty('Essential Sections'); expect(result.categories).toHaveProperty('Community Health'); expect(result.categories).toHaveProperty('Visual Elements'); expect(result.categories).toHaveProperty('Content Quality'); expect(result.wordCount).toBeGreaterThan(0); expect(result.estimatedReadTime).toBeGreaterThan(0); }); it('should calculate scores correctly', async () => { const perfectReadme = await createTestReadme(` # Perfect Project > An amazing project that does everything right [](https://travis-ci.org/user/repo) ## TL;DR This project is perfect and demonstrates all best practices. ## Quick Start \`\`\`bash npm install perfect-project \`\`\` ## Usage \`\`\`javascript const perfect = require('perfect-project'); perfect.doSomething(); \`\`\` ## Contributing See CONTRIBUTING.md for guidelines. ## License MIT © Author `); await createProjectFile('CONTRIBUTING.md', 'Guidelines...'); await createProjectFile('LICENSE', 'MIT License...'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: perfectReadme, projectPath: tempDir }), ); expect(result.overallScore).toBeGreaterThan(70); expect(result.categories['Essential Sections'].score).toBeGreaterThan(80); }); it('should provide helpful recommendations', async () => { const poorReadme = await createTestReadme('# Poor Project\n\nMinimal content'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: poorReadme }), ); expect(result.recommendations.length).toBeGreaterThan(0); expect(result.overallScore).toBeLessThan(50); }); }); describe('Output Formatting', () => { it('should format console output correctly', async () => { const readme = await createTestReadme('# Test\n\nContent'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme, outputFormat: 'console' }), ); const formatted = validator.formatReport(result, 'console'); expect(formatted).toContain('📋 README Checklist Report'); expect(formatted).toContain('Overall Score:'); expect(formatted).toContain('Essential Sections'); expect(formatted).toContain('✅'); expect(formatted).toContain('❌'); }); it('should format markdown output correctly', async () => { const readme = await createTestReadme('# Test\n\nContent'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme, outputFormat: 'markdown' }), ); const formatted = validator.formatReport(result, 'markdown'); expect(formatted).toContain('# README Checklist Report'); expect(formatted).toContain('## Overall Score:'); expect(formatted).toContain('### Essential Sections'); expect(formatted).toContain('- ✅'); expect(formatted).toContain('- ❌'); }); it('should format JSON output correctly', async () => { const readme = await createTestReadme('# Test\n\nContent'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme, outputFormat: 'json' }), ); const formatted = validator.formatReport(result, 'json'); const parsed = JSON.parse(formatted); expect(parsed).toHaveProperty('overallScore'); expect(parsed).toHaveProperty('categories'); expect(parsed).toHaveProperty('recommendations'); }); }); describe('Error Handling', () => { it('should handle non-existent README file', async () => { const nonExistentPath = path.join(tempDir, 'nonexistent.md'); await expect( validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: nonExistentPath }), ), ).rejects.toThrow(); }); it('should handle invalid project path gracefully', async () => { const readme = await createTestReadme('# Test\n\nContent'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: readme, projectPath: '/invalid/path' }), ); // Should still work, just without project file context expect(result.overallScore).toBeGreaterThan(0); }); it('should handle empty README file', async () => { const emptyReadme = await createTestReadme('', 'empty-README.md'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: emptyReadme }), ); // Empty README should pass length test (0 words <= 300) and external links test (no links to fail) // but fail most other tests, resulting in a low overall score expect(result.overallScore).toBeLessThan(20); // Very low score due to missing content expect(result.passedItems).toBe(2); // Only length and external-links should pass expect(result.failedItems).toBe(15); // Most checks should fail }); }); describe('Suggestions Generation', () => { it('should provide specific suggestions for failed checks', async () => { const incompleteReadme = await createTestReadme('# Project\n\nMinimal content'); const result = await validateReadmeChecklist( ValidateReadmeChecklistSchema.parse({ readmePath: incompleteReadme }), ); const failedChecks = Object.values(result.categories) .flatMap((cat) => cat.results) .filter((r) => !r.passed && r.suggestions); expect(failedChecks.length).toBeGreaterThan(0); for (const check of failedChecks) { expect(check.suggestions).toBeDefined(); expect(check.suggestions!.length).toBeGreaterThan(0); } }); }); });