documcp

import { z } from "zod"; import { promises as fs } from "fs"; // Input schema export const ValidateReadmeChecklistSchema = z.object({ readmePath: z.string().min(1, "README path is required"), projectPath: z.string().optional(), strict: z.boolean().default(false), outputFormat: z.enum(["json", "markdown", "console"]).default("console"), }); export type ValidateReadmeChecklistInput = z.infer< typeof ValidateReadmeChecklistSchema >; interface ChecklistItem { id: string; category: string; name: string; description: string; required: boolean; weight: number; } interface ValidationResult { item: ChecklistItem; passed: boolean; details: string; suggestions?: string[]; } interface ChecklistReport { overallScore: number; totalItems: number; passedItems: number; failedItems: number; categories: { [category: string]: { score: number; passed: number; total: number; results: ValidationResult[]; }; }; recommendations: string[]; estimatedReadTime: number; wordCount: number; } export class ReadmeChecklistValidator { private checklist: ChecklistItem[] = []; constructor() { this.initializeChecklist(); } private initializeChecklist(): void { this.checklist = [ // Essential Sections { id: "title", category: "Essential Sections", name: "Project Title", description: "Clear, descriptive project title as main heading", required: true, weight: 10, }, { id: "description", category: "Essential Sections", name: "Project Description", description: "Brief one-liner describing what the project does", required: true, weight: 10, }, { id: "tldr", category: "Essential Sections", name: "TL;DR Section", description: "2-3 sentence summary of the project", required: true, weight: 8, }, { id: "quickstart", category: "Essential Sections", name: "Quick Start Guide", description: "Instructions to get running in under 5 minutes", required: true, weight: 10, }, { id: "installation", category: "Essential Sections", name: "Installation Instructions", description: "Clear installation steps with code examples", required: true, weight: 9, }, { id: "usage", category: "Essential Sections", name: "Basic Usage Examples", description: "Simple working code examples", required: true, weight: 9, }, { id: "license", category: "Essential Sections", name: "License Information", description: "Clear license information", required: true, weight: 7, }, // Community Health { id: "contributing", category: "Community Health", name: "Contributing Guidelines", description: "Link to CONTRIBUTING.md or inline guidelines", required: false, weight: 6, }, { id: "code-of-conduct", category: "Community Health", name: "Code of Conduct", description: "Link to CODE_OF_CONDUCT.md", required: false, weight: 4, }, { id: "security", category: "Community Health", name: "Security Policy", description: "Link to SECURITY.md or security reporting info", required: false, weight: 4, }, // Visual Elements { id: "badges", category: "Visual Elements", name: "Status Badges", description: "Build status, version, license badges", required: false, weight: 3, }, { id: "screenshots", category: "Visual Elements", name: "Screenshots/Demos", description: "Visual representation for applications/tools", required: false, weight: 5, }, { id: "formatting", category: "Visual Elements", name: "Consistent Formatting", description: "Proper markdown formatting and structure", required: true, weight: 6, }, // Content Quality { id: "working-examples", category: "Content Quality", name: "Working Code Examples", description: "All code examples are functional and tested", required: true, weight: 8, }, { id: "external-links", category: "Content Quality", name: "Functional External Links", description: "All external links are working", required: true, weight: 5, }, { id: "appropriate-length", category: "Content Quality", name: "Appropriate Length", description: "README under 300 lines for community projects", required: false, weight: 4, }, { id: "scannable-structure", category: "Content Quality", name: "Scannable Structure", description: "Good heading hierarchy and organization", required: true, weight: 7, }, ]; } async validateReadme( input: ValidateReadmeChecklistInput, ): Promise<ChecklistReport> { const readmeContent = await fs.readFile(input.readmePath, "utf-8"); const projectFiles = input.projectPath ? await this.getProjectFiles(input.projectPath) : []; const results: ValidationResult[] = []; const categories: { [key: string]: ValidationResult[] } = {}; // Run validation for each checklist item for (const item of this.checklist) { const result = await this.validateItem( item, readmeContent, projectFiles, input, ); results.push(result); if (!categories[item.category]) { categories[item.category] = []; } categories[item.category].push(result); } return this.generateReport(results, readmeContent); } private async validateItem( item: ChecklistItem, content: string, projectFiles: string[], _input: ValidateReadmeChecklistInput, ): Promise<ValidationResult> { let passed = false; let details = ""; const suggestions: string[] = []; switch (item.id) { case "title": { const titleRegex = /^#\s+.+/m; const hasTitle = titleRegex.test(content); passed = hasTitle; details = passed ? "Project title found" : "No main heading (# Title) found"; if (!passed) suggestions.push( "Add a clear project title as the first heading: # Your Project Name", ); break; } case "description": { const descRegex = /(^>\s+.+|^[^#\n].{20,})/m; const hasDesc = descRegex.test(content); passed = hasDesc; details = passed ? "Project description found" : "Missing project description"; if (!passed) suggestions.push( "Add a brief description using > quote syntax or paragraph after title", ); break; } case "tldr": { const tldrRegex = /##?\s*(tl;?dr|quick start|at a glance)/i; const hasTldr = tldrRegex.test(content); passed = hasTldr; details = passed ? "TL;DR section found" : "Missing TL;DR or quick overview"; if (!passed) suggestions.push( "Add a ## TL;DR section with 2-3 sentences explaining what your project does", ); break; } case "quickstart": passed = /##\s*(Quick\s*Start|Getting\s*Started|Installation)/i.test( content, ); details = passed ? "Quick start section found" : "No quick start section found"; if (!passed) suggestions.push( "Add a ## Quick Start section with immediate setup instructions", ); break; case "installation": { const installRegex = /##?\s*(install|installation|setup)/i; const hasInstall = installRegex.test(content); passed = hasInstall; details = passed ? "Installation instructions found" : "Missing installation instructions"; if (!passed) suggestions.push( "Add installation instructions with code blocks showing exact commands", ); break; } case "usage": { const usageRegex = /##?\s*(usage|example|getting started)/i; const hasUsage = usageRegex.test(content); passed = hasUsage; details = passed ? "Usage examples found" : "Missing usage examples"; if (!passed) suggestions.push("Add usage examples with working code snippets"); break; } case "license": { const licenseRegex = /##?\s*license/i; const hasLicense = licenseRegex.test(content); const hasLicenseFile = projectFiles.includes("LICENSE") || projectFiles.includes("LICENSE.md"); passed = hasLicense || hasLicenseFile; details = passed ? "License information found" : "Missing license information"; if (!passed) suggestions.push("Add a ## License section or LICENSE file"); break; } case "contributing": { const hasContributing = /##\s*Contribut/i.test(content); const hasContributingFile = projectFiles.includes("CONTRIBUTING.md"); passed = hasContributing || hasContributingFile; details = passed ? "Contributing guidelines found" : "No contributing guidelines found"; if (!passed) suggestions.push( "Add contributing guidelines or link to CONTRIBUTING.md", ); break; } case "code-of-conduct": { const hasCodeOfConduct = /code.of.conduct/i.test(content); const hasCodeFile = projectFiles.includes("CODE_OF_CONDUCT.md"); passed = hasCodeOfConduct || hasCodeFile; details = passed ? "Code of conduct found" : "No code of conduct found"; break; } case "security": { const hasSecurity = /security/i.test(content); const hasSecurityFile = projectFiles.includes("SECURITY.md"); passed = hasSecurity || hasSecurityFile; details = passed ? "Security information found" : "No security policy found"; break; } case "badges": { const badgeRegex = /\[!\[.*?\]\(.*?\)\]\(.*?\)|!\[.*?\]\(.*?badge.*?\)/i; const hasBadges = badgeRegex.test(content); passed = hasBadges; details = passed ? "Status badges found" : "Consider adding status badges"; if (!passed) suggestions.push( "Consider adding badges for build status, version, license", ); break; } case "screenshots": { const imageRegex = /!\[.*?\]\(.*?\.(png|jpg|jpeg|gif|svg).*?\)/i; const hasImages = imageRegex.test(content); passed = hasImages; details = passed ? "Screenshots/images found" : "Consider adding screenshots or images"; if (!passed && content.includes("application")) { suggestions.push( "Consider adding screenshots or demo GIFs for visual applications", ); } break; } case "formatting": { const hasHeaders = (content.match(/^##?\s+/gm) || []).length >= 3; const hasProperSpacing = !/#{1,6}\s*\n\s*#{1,6}/.test(content); passed = hasHeaders && hasProperSpacing; details = passed ? "Good markdown formatting" : "Improve markdown formatting and structure"; if (!passed) suggestions.push( "Improve markdown formatting with proper heading hierarchy and spacing", ); break; } case "working-examples": { const codeRegex = /```[\s\S]*?```/g; const codeBlocks = content.match(codeRegex) || []; passed = codeBlocks.length > 0; details = `${codeBlocks.length} code examples found`; if (!passed) suggestions.push("Add working code examples to demonstrate usage"); break; } case "external-links": { const links = content.match(/\[.*?\]\((https?:\/\/.*?)\)/g) || []; passed = true; // Assume links work unless we can verify details = `${links.length} external links found`; break; } case "appropriate-length": { const wordCount = content.split(/\s+/).length; passed = wordCount <= 300; details = `${wordCount} words (target: ≤300)`; if (!passed) suggestions.push( "Consider shortening README or moving detailed content to separate docs", ); break; } case "scannable-structure": { const sections = (content.match(/^##?\s+/gm) || []).length; const lists = (content.match(/^\s*[-*+]\s+/gm) || []).length; passed = sections >= 3 && lists >= 2; details = passed ? "Good scannable structure" : "Improve structure with more sections and lists"; if (!passed) suggestions.push( "Improve heading structure with logical hierarchy (H1 → H2 → H3)", ); break; } default: passed = false; details = "Validation not implemented"; } return { item, passed, details, suggestions: suggestions.length > 0 ? suggestions : undefined, }; } private async getProjectFiles(projectPath: string): Promise<string[]> { try { const files = await fs.readdir(projectPath); return files; } catch { return []; } } private generateReport( results: ValidationResult[], content: string, ): ChecklistReport { const categories: { [category: string]: { score: number; passed: number; total: number; results: ValidationResult[]; }; } = {}; let totalWeight = 0; let passedWeight = 0; let passedItems = 0; const totalItems = results.length; // Group results by category and calculate scores for (const result of results) { const category = result.item.category; if (!categories[category]) { categories[category] = { score: 0, passed: 0, total: 0, results: [] }; } categories[category].results.push(result); categories[category].total++; totalWeight += result.item.weight; if (result.passed) { categories[category].passed++; passedWeight += result.item.weight; passedItems++; } } // Calculate category scores for (const category in categories) { const cat = categories[category]; cat.score = Math.round((cat.passed / cat.total) * 100); } const overallScore = Math.round((passedWeight / totalWeight) * 100); const wordCount = content.split(/\s+/).length; const estimatedReadTime = Math.ceil(wordCount / 200); // 200 words per minute // Generate recommendations const recommendations: string[] = []; if (overallScore < 70) { recommendations.push( "README needs significant improvement to meet community standards", ); } if (categories["Essential Sections"]?.score < 80) { recommendations.push("Focus on completing essential sections first"); } if (wordCount > 2000) { recommendations.push( "Consider breaking up content into separate documentation files", ); } if (!results.find((r) => r.item.id === "badges")?.passed) { recommendations.push("Add status badges to improve project credibility"); } return { overallScore, totalItems, passedItems, failedItems: totalItems - passedItems, categories, recommendations, estimatedReadTime, wordCount, }; } formatReport( report: ChecklistReport, format: "json" | "markdown" | "console", ): string { switch (format) { case "json": return JSON.stringify(report, null, 2); case "markdown": return this.formatMarkdownReport(report); case "console": default: return this.formatConsoleReport(report); } } private formatMarkdownReport(report: ChecklistReport): string { let output = "# README Checklist Report\n\n"; output += `## Overall Score: ${report.overallScore}%\n\n`; output += `- **Passed**: ${report.passedItems}/${report.totalItems} items\n`; output += `- **Word Count**: ${report.wordCount} words\n`; output += `- **Estimated Read Time**: ${report.estimatedReadTime} minutes\n\n`; output += "## Category Breakdown\n\n"; for (const [categoryName, category] of Object.entries(report.categories)) { output += `### ${categoryName} (${category.score}%)\n\n`; for (const result of category.results) { const status = result.passed ? "✅" : "❌"; output += `- ${status} **${result.item.name}**: ${result.details}\n`; if (result.suggestions) { for (const suggestion of result.suggestions) { output += ` - 💡 ${suggestion}\n`; } } } output += "\n"; } if (report.recommendations.length > 0) { output += "## Recommendations\n\n"; for (const rec of report.recommendations) { output += `- ${rec}\n`; } } return output; } private formatConsoleReport(report: ChecklistReport): string { let output = "\n📋 README Checklist Report\n"; output += "=".repeat(50) + "\n"; const scoreColor = report.overallScore >= 80 ? "🟢" : report.overallScore >= 60 ? "🟡" : "🔴"; output += `${scoreColor} Overall Score: ${report.overallScore}%\n`; output += `✅ Passed: ${report.passedItems}/${report.totalItems} items\n`; output += `📄 Word Count: ${report.wordCount} words\n`; output += `⏱️ Read Time: ${report.estimatedReadTime} minutes\n\n`; for (const [categoryName, category] of Object.entries(report.categories)) { const catColor = category.score >= 80 ? "🟢" : category.score >= 60 ? "🟡" : "🔴"; output += `${catColor} ${categoryName} (${category.score}%)\n`; output += "-".repeat(30) + "\n"; for (const result of category.results) { const status = result.passed ? "✅" : "❌"; output += `${status} ${result.item.name}: ${result.details}\n`; if (result.suggestions) { for (const suggestion of result.suggestions) { output += ` 💡 ${suggestion}\n`; } } } output += "\n"; } if (report.recommendations.length > 0) { output += "🎯 Recommendations:\n"; for (const rec of report.recommendations) { output += `• ${rec}\n`; } } return output; } } export async function validateReadmeChecklist( input: ValidateReadmeChecklistInput, ): Promise<ChecklistReport> { const validatedInput = ValidateReadmeChecklistSchema.parse(input); const validator = new ReadmeChecklistValidator(); return await validator.validateReadme(validatedInput); }