#!/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();

Blockchain
Arbitrum
Avalanche
Base
Ethereum
Monad
OP Mainnet
Polygon PoS
Unichain

Blockchain
Arbitrum Sepolia
Arc Testnet
Avalanche Fuji
Base Sepolia
Ethereum Sepolia
Monad Testnet
OP Sepolia
Polygon PoS Amoy
Unichain Sepolia

Wallets

Contracts

Paymaster

​Mainnet

​Testnet

Mainnet

Testnet