#!/usr/bin/env node /** * Documentation readability measurement tool. * * Calculates Flesch-Kincaid Grade Level, Flesch Reading Ease, * Coleman-Liau Index, and Automated Readability Index for each * MDX file, then aggregates by product and site-wide. * * Usage: * node scripts/measure_readability.js [options] * * Options: * --json Output raw JSON instead of formatted tables * --csv Output CSV instead of formatted tables * --files Include per-file breakdown in output * --sort Sort products by metric: fkgl (default), fre, cli, ari * --product Show only one product (case-insensitive partial match) * --min-words Minimum word count to include a file (default: 50) */ const fs = require("fs"); const path = require("path"); // --------------------------------------------------------------------------- // Product mapping: directory prefix → product name // --------------------------------------------------------------------------- const PRODUCT_MAP = { "bridge-kit": "Bridge Kit", "cctp/v1": "CCTP V1 (Legacy)", cctp: "CCTP", gateway: "Gateway", wallets: "Wallets", contracts: "Contracts", paymaster: "Paymaster", w3s: "Developer Services", stablecoins: "Stablecoins", xreserve: "xReserve", tokenized: "USYC", "circle-mint": "Mint", cpn: "Circle Payments Network", stablefx: "StableFX", ai: "AI", sdks: "SDKs", "release-notes": "Release Notes", }; // Sorted longest-first so sub-path prefixes match before parents const PRODUCT_PREFIXES = Object.keys(PRODUCT_MAP).sort( (a, b) => b.length - a.length ); const EXCLUDED_DIRS = ["api-reference", "snippets", "templates", "images"]; // --------------------------------------------------------------------------- // CLI argument parsing // --------------------------------------------------------------------------- function parseArgs() { const args = process.argv.slice(2); const opts = { json: false, csv: false, files: false, sort: "fkgl", product: null, minWords: 50, }; for (let i = 0; i < args.length; i++) { switch (args[i]) { case "--json": opts.json = true; break; case "--csv": opts.csv = true; break; case "--files": opts.files = true; break; case "--sort": opts.sort = args[++i]; break; case "--product": opts.product = args[++i]; break; case "--min-words": opts.minWords = parseInt(args[++i], 10); break; case "--help": case "-h": console.log(fs.readFileSync(__filename, "utf8").match(/\/\*\*[\s\S]*?\*\//)[0]); process.exit(0); } } return opts; } // --------------------------------------------------------------------------- // Text extraction: strip MDX / Markdown to plain prose // --------------------------------------------------------------------------- function stripToProseText(raw) { let text = raw; // Remove YAML frontmatter text = text.replace(/^---[\s\S]*?---\n?/, ""); // Remove fenced code blocks (``` or ~~~) text = text.replace(/(`{3,}|~{3,})[\s\S]*?\1/g, ""); // Remove MDX import/export statements text = text.replace(/^(import|export)\s.+$/gm, ""); // Remove MDX/JSX components (self-closing and block-level) text = text.replace(/<[A-Z][A-Za-z]*\b[^>]*\/>/g, ""); text = text.replace(/<[A-Z][A-Za-z]*\b[^>]*>[\s\S]*?<\/[A-Z][A-Za-z]*>/g, ""); // Remove HTML tags but keep inner text text = text.replace(/<\/?[a-z][a-z0-9]*\b[^>]*>/gi, ""); // Remove markdown images ![alt](url) text = text.replace(/!\[[^\]]*\]$[^)]*$/g, ""); // Convert markdown links [text](url) → text text = text.replace(/\[([^\]]*)\]$[^)]*$/g, "$1"); // Remove reference-style link definitions text = text.replace(/^\[[^\]]+\]:\s.*$/gm, ""); // Remove inline code text = text.replace(/`[^`]+`/g, ""); // Remove heading markers text = text.replace(/^#{1,6}\s+/gm, ""); // Remove blockquote markers text = text.replace(/^>\s*/gm, ""); // Remove emphasis/bold markers text = text.replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2"); // Remove horizontal rules text = text.replace(/^[-*_]{3,}\s*$/gm, ""); // Remove markdown table rows (pipes with content) text = text.replace(/^\|.*\|$/gm, ""); text = text.replace(/^[-|:\s]+$/gm, ""); // Remove list markers (-, *, numbered) text = text.replace(/^\s*[-*+]\s+/gm, ""); text = text.replace(/^\s*\d+\.\s+/gm, ""); // Remove bare URLs text = text.replace(/https?:\/\/\S+/g, ""); // Collapse whitespace text = text.replace(/\n{2,}/g, "\n"); text = text.trim(); return text; } // --------------------------------------------------------------------------- // Syllable counter (heuristic) // --------------------------------------------------------------------------- function countSyllables(word) { word = word.toLowerCase().replace(/[^a-z]/g, ""); if (word.length <= 2) return word.length > 0 ? 1 : 0; // Common suffixes that don't add syllables word = word.replace(/(?:es|ed)$/, ""); if (word.length === 0) return 1; // Remove trailing e (silent e) word = word.replace(/e$/, ""); if (word.length === 0) return 1; // Count vowel groups const matches = word.match(/[aeiouy]+/g); let count = matches ? matches.length : 1; return Math.max(1, count); } // --------------------------------------------------------------------------- // Readability metrics // --------------------------------------------------------------------------- function computeMetrics(text) { const sentences = text .split(/[.!?]+/) .map((s) => s.trim()) .filter((s) => s.length > 0); const words = text .split(/\s+/) .map((w) => w.replace(/[^a-zA-Z0-9'-]/g, "")) .filter((w) => w.length > 0); const totalSentences = Math.max(sentences.length, 1); const totalWords = words.length; if (totalWords === 0) { return null; } const totalSyllables = words.reduce((sum, w) => sum + countSyllables(w), 0); const totalChars = words.reduce( (sum, w) => sum + w.replace(/[^a-zA-Z]/g, "").length, 0 ); const avgWordsPerSentence = totalWords / totalSentences; const avgSyllablesPerWord = totalSyllables / totalWords; const avgCharsPerWord = totalChars / totalWords; // Flesch Reading Ease (higher = easier, target 60-70 for general public) const fre = 206.835 - 1.015 * avgWordsPerSentence - 84.6 * avgSyllablesPerWord; // Flesch-Kincaid Grade Level (US grade level, target 8-12 for tech docs) const fkgl = 0.39 * avgWordsPerSentence + 11.8 * avgSyllablesPerWord - 15.59; // Coleman-Liau Index const L = (totalChars / totalWords) * 100; const S = (totalSentences / totalWords) * 100; const cli = 0.0588 * L - 0.296 * S - 15.8; // Automated Readability Index const ari = 4.71 * avgCharsPerWord + 0.5 * avgWordsPerSentence - 21.43; return { wordCount: totalWords, sentenceCount: totalSentences, avgWordsPerSentence: round(avgWordsPerSentence), fre: round(fre), fkgl: round(fkgl), cli: round(cli), ari: round(ari), }; } function round(n) { return Math.round(n * 10) / 10; } // --------------------------------------------------------------------------- // File discovery and product assignment // --------------------------------------------------------------------------- function findMdxFiles(rootDir) { const results = []; function walk(dir) { for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const fullPath = path.join(dir, entry.name); const relPath = path.relative(rootDir, fullPath); if (entry.isDirectory()) { if ( entry.name.startsWith(".") || entry.name === "node_modules" || EXCLUDED_DIRS.includes(entry.name) ) { continue; } walk(fullPath); } else if (entry.isFile() && entry.name.endsWith(".mdx")) { results.push(relPath); } } } walk(rootDir); return results; } function getProduct(relPath) { const normalized = relPath.split(path.sep).join("/"); for (const prefix of PRODUCT_PREFIXES) { if (normalized === prefix || normalized.startsWith(prefix + "/")) { return PRODUCT_MAP[prefix]; } } // Top-level .mdx files (landing pages) if (!normalized.includes("/")) { return "Landing Pages"; } return "Other"; } // --------------------------------------------------------------------------- // Aggregation helpers // --------------------------------------------------------------------------- function aggregateMetrics(fileResults) { if (fileResults.length === 0) return null; const totalWords = fileResults.reduce((s, f) => s + f.metrics.wordCount, 0); const agg = { fileCount: fileResults.length, totalWords }; for (const key of ["fre", "fkgl", "cli", "ari", "avgWordsPerSentence"]) { // Weighted average by word count so longer files count more const weighted = fileResults.reduce( (s, f) => s + f.metrics[key] * f.metrics.wordCount, 0 ); agg[key] = round(weighted / totalWords); } return agg; } // --------------------------------------------------------------------------- // Output formatters // --------------------------------------------------------------------------- function gradeLabel(fkgl) { if (fkgl <= 6) return "Easy"; if (fkgl <= 8) return "Fairly Easy"; if (fkgl <= 10) return "Standard"; if (fkgl <= 12) return "Fairly Difficult"; if (fkgl <= 14) return "Difficult"; return "Very Difficult"; } function printTable(products, siteAgg, opts) { const sortKey = opts.sort; const sorted = [...products].sort( (a, b) => (a.agg[sortKey] ?? 0) - (b.agg[sortKey] ?? 0) ); const header = [ "Product".padEnd(30), "Files".padStart(5), "Words".padStart(8), "FKGL".padStart(6), "FRE".padStart(6), "CLI".padStart(6), "ARI".padStart(6), "Avg W/S".padStart(8), "Level", ].join(" "); const divider = "─".repeat(header.length); console.log("\n" + divider); console.log(" DOCUMENTATION READABILITY REPORT"); console.log(divider); console.log(); console.log(" Metrics legend:"); console.log(" FKGL = Flesch-Kincaid Grade Level (US grade, lower = simpler)"); console.log(" FRE = Flesch Reading Ease (0-100, higher = easier)"); console.log(" CLI = Coleman-Liau Index (US grade level)"); console.log(" ARI = Automated Readability Index (US grade level)"); console.log(" W/S = Average words per sentence"); console.log(); console.log(divider); console.log(header); console.log(divider); for (const p of sorted) { const row = [ p.name.padEnd(30), String(p.agg.fileCount).padStart(5), String(p.agg.totalWords).padStart(8), String(p.agg.fkgl).padStart(6), String(p.agg.fre).padStart(6), String(p.agg.cli).padStart(6), String(p.agg.ari).padStart(6), String(p.agg.avgWordsPerSentence).padStart(8), gradeLabel(p.agg.fkgl), ].join(" "); console.log(row); } console.log(divider); const siteRow = [ "SITE AVERAGE".padEnd(30), String(siteAgg.fileCount).padStart(5), String(siteAgg.totalWords).padStart(8), String(siteAgg.fkgl).padStart(6), String(siteAgg.fre).padStart(6), String(siteAgg.cli).padStart(6), String(siteAgg.ari).padStart(6), String(siteAgg.avgWordsPerSentence).padStart(8), gradeLabel(siteAgg.fkgl), ].join(" "); console.log(siteRow); console.log(divider); console.log(); } function printFileBreakdown(products, opts) { console.log("─".repeat(100)); console.log(" PER-FILE BREAKDOWN"); console.log("─".repeat(100)); for (const p of products) { if (opts.product && !p.name.toLowerCase().includes(opts.product.toLowerCase())) { continue; } console.log(`\n ${p.name} (${p.files.length} files)`); const sorted = [...p.files].sort( (a, b) => b.metrics.fkgl - a.metrics.fkgl ); for (const f of sorted) { const m = f.metrics; console.log( ` ${f.file.padEnd(65)} FKGL=${String(m.fkgl).padStart(5)} FRE=${String(m.fre).padStart(5)} (${m.wordCount} words)` ); } } console.log(); } function printJson(products, siteAgg) { const output = { generated: new Date().toISOString(), siteAverage: siteAgg, products: products.map((p) => ({ name: p.name, ...p.agg, files: p.files.map((f) => ({ path: f.file, ...f.metrics, })), })), }; console.log(JSON.stringify(output, null, 2)); } function printCsv(products) { console.log("product,file,words,sentences,fkgl,fre,cli,ari,avg_words_per_sentence"); for (const p of products) { for (const f of p.files) { const m = f.metrics; console.log( `"${p.name}","${f.file}",${m.wordCount},${m.sentenceCount},${m.fkgl},${m.fre},${m.cli},${m.ari},${m.avgWordsPerSentence}` ); } } } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- function main() { const opts = parseArgs(); const rootDir = path.resolve(__dirname, ".."); const files = findMdxFiles(rootDir); // Group files by product and compute metrics const productFiles = {}; let skipped = 0; for (const relFile of files) { const product = getProduct(relFile); const raw = fs.readFileSync(path.join(rootDir, relFile), "utf8"); const prose = stripToProseText(raw); const metrics = computeMetrics(prose); if (!metrics || metrics.wordCount < opts.minWords) { skipped++; continue; } if (!productFiles[product]) { productFiles[product] = []; } productFiles[product].push({ file: relFile, metrics }); } // Build product summaries let products = Object.entries(productFiles) .map(([name, files]) => ({ name, files, agg: aggregateMetrics(files), })) .filter((p) => p.agg !== null); if (opts.product) { products = products.filter((p) => p.name.toLowerCase().includes(opts.product.toLowerCase()) ); } // Site-wide aggregate const allFiles = products.flatMap((p) => p.files); const siteAgg = aggregateMetrics(allFiles); if (!siteAgg) { console.error("No files with sufficient prose content found."); process.exit(1); } // Output if (opts.json) { printJson(products, siteAgg); } else if (opts.csv) { printCsv(products); } else { printTable(products, siteAgg, opts); if (opts.files) { printFileBreakdown(products, opts); } console.log(` Analyzed ${allFiles.length} files across ${products.length} products (${skipped} files skipped below ${opts.minWords}-word threshold)`); console.log(); } } main();

Build with AI