Fixture
\n![](\"/missing-alt.png\")
\n 🔗\n Focusable
\n (?!\\s*\\/>)/;\n\n files.forEach((filePath) => {\n const content = readFileSafe(filePath);\n if (!content) return;\n const lines = content.split('\\n');\n\n lines.forEach((line, idx) => {\n if (!/^\\s*\\|/.test(line)) return;\n if (!rawBrPattern.test(line)) return;\n errors.push({\n file: toRelative(filePath, rootDir),\n rule: 'Raw
in markdown table',\n line: idx + 1,\n message: 'Use
in markdown table cells.'\n });\n });\n });\n\n return files.length;\n}\n\nfunction runTests() {\n errors = [];\n warnings = [];\n const rootDir = getRepoRoot();\n\n const scannedCounts = [];\n scannedCounts.push(checkLatestVersionAliasing(rootDir));\n scannedCounts.push(checkGlobalsImportPath(rootDir));\n scannedCounts.push(checkLptMathDelimiters(rootDir));\n scannedCounts.push(checkRawBrInMarkdownTables(rootDir));\n\n return {\n errors,\n warnings,\n passed: errors.length === 0,\n total: scannedCounts.reduce((acc, count) => acc + count, 0)\n };\n}\n\nif (require.main === module) {\n const result = runTests();\n\n if (result.errors.length > 0) {\n console.error('\\n❌ MDX Guardrail Errors:\\n');\n result.errors.forEach((err) => {\n console.error(` ${err.file}:${err.line} - ${err.rule}: ${err.message}`);\n });\n }\n\n if (result.warnings.length > 0) {\n console.warn('\\n⚠️ MDX Guardrail Warnings:\\n');\n result.warnings.forEach((warn) => {\n console.warn(` ${warn.file}:${warn.line || 1} - ${warn.message}`);\n });\n }\n\n if (result.passed) {\n console.log(`\\n✅ MDX guardrails passed (${result.total} file scans)`);\n process.exit(0);\n }\n\n console.error(`\\n❌ ${result.errors.length} guardrail error(s) found`);\n process.exit(1);\n}\n\nmodule.exports = { runTests };\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "runner", + "caller": "tests/run-all.js", + "pipeline": "P1" + }, + { + "type": "runner", + "caller": "tests/run-pr-checks.js", + "pipeline": "P3" + }, + { + "type": "script", + "caller": "tests/run-all.js", + "pipeline": "indirect" + }, + { + "type": "script", + "caller": "tests/run-pr-checks.js", + "pipeline": "indirect" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:mdx:guards" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "P1 via run-all; P3 via run-pr-checks; indirect via tests/run-all.js; indirect via tests/run-pr-checks.js; manual (npm script: test:mdx:guards)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "P1" + }, + { + "path": "tests/unit/mdx-safe-markdown.test.js", + "script": "mdx-safe-markdown.test", + "category": "validator", + "purpose": "qa:content-quality", + "scope": "tests/unit, tests/fixtures/mdx-safe-markdown, tools/lib, tools/scripts/remediators/content, tools/scripts/validators/content", + "owner": "docs", + "needs": "E-R1, R-R11", + "purpose_statement": "Fixture-driven unit tests for repo-wide MDX-safe markdown repair and validation helpers.", + "pipeline_declared": "P1 (commit, via run-all)", + "usage": "node tests/unit/mdx-safe-markdown.test.js", + "header": "#!/usr/bin/env node\n/**\n * @script mdx-safe-markdown.test\n * @category validator\n * @purpose qa:content-quality\n * @scope tests/unit, tests/fixtures/mdx-safe-markdown, tools/lib, tools/scripts/remediators/content, tools/scripts/validators/content\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Fixture-driven unit tests for repo-wide MDX-safe markdown repair and validation helpers.\n * @pipeline P1 (commit, via run-all)\n * @usage node tests/unit/mdx-safe-markdown.test.js\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst path = require('path');\n\nconst { repairMarkdownContent, validateMarkdownContent } = require('../../tools/lib/mdx-safe-markdown');\n\nconst REPO_ROOT = path.resolve(__dirname, '../..');\nconst FIXTURE_DIR = path.join(REPO_ROOT, 'tests', 'fixtures', 'mdx-safe-markdown');\n\nlet errors = [];\nlet warnings = [];\n\nfunction loadJson(fileName) {\n return JSON.parse(fs.readFileSync(path.join(FIXTURE_DIR, fileName), 'utf8'));\n}\n\nfunction runCase(name, fn) {\n try {\n fn();\n console.log(` ✓ ${name}`);\n } catch (error) {\n errors.push({\n file: 'tests/unit/mdx-safe-markdown.test.js',\n line: 1,\n rule: 'mdx-safe-markdown unit',\n message: `${name}: ${error.message}`\n });\n }\n}\n\nfunction runTests() {\n errors = [];\n warnings = [];\n\n console.log('🧪 MDX-safe Markdown Unit Tests');\n\n loadJson('repair-cases.json').forEach((testCase) => {\n runCase(testCase.name, () => {\n const input = testCase.inputLines.join('\\n');\n const expected = testCase.expectedLines.join('\\n');\n const result = repairMarkdownContent(input, testCase.filePath);\n\n assert.strictEqual(result.content, expected);\n assert.deepStrictEqual(\n result.changes.map((change) => change.rule),\n testCase.expectedRules\n );\n });\n });\n\n loadJson('validator-cases.json').forEach((testCase) => {\n runCase(testCase.name, () => {\n const input = testCase.contentLines.join('\\n');\n const result = validateMarkdownContent(input, testCase.filePath);\n\n assert.deepStrictEqual(\n result.findings.map((finding) => finding.rule),\n testCase.expectedRules\n );\n });\n });\n\n return {\n errors,\n warnings,\n passed: errors.length === 0,\n total: loadJson('repair-cases.json').length + loadJson('validator-cases.json').length\n };\n}\n\nif (require.main === module) {\n const result = runTests();\n\n if (result.errors.length > 0) {\n console.error('\\n❌ MDX-safe markdown unit test failures:\\n');\n result.errors.forEach((error) => {\n console.error(` ${error.file}:${error.line} - ${error.rule}: ${error.message}`);\n });\n } else {\n console.log(`\\n✅ MDX-safe markdown unit tests passed (${result.total} cases checked)`);\n }\n\n process.exit(result.passed ? 0 : 1);\n}\n\nmodule.exports = { runTests };\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "runner", + "caller": "tests/run-all.js", + "pipeline": "P1" + }, + { + "type": "script", + "caller": "tests/run-all.js", + "pipeline": "indirect" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:mdx:safe:unit" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "P1 via run-all; indirect via tests/run-all.js; manual (npm script: test:mdx:safe:unit)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "P1" + }, + { + "path": "tests/unit/mdx.test.js", + "script": "mdx.test", + "category": "validator", + "purpose": "qa:content-quality", + "scope": "tests", + "owner": "docs", + "needs": "E-R1, R-R11", + "purpose_statement": "Validates MDX syntax and structure — checks for parse errors, invalid JSX, broken components", + "pipeline_declared": "P1, P3", + "usage": "node tests/unit/mdx.test.js [flags]", + "header": "#!/usr/bin/env node\n/**\n * @script mdx.test\n * @category validator\n * @purpose qa:content-quality\n * @scope tests\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Validates MDX syntax and structure — checks for parse errors, invalid JSX, broken components\n * @pipeline P1, P3\n * @usage node tests/unit/mdx.test.js [flags]\n */\n/**\n * MDX validation tests\n */\n\nconst { getMdxFiles, getStagedDocsPageFiles, readFile } = require('../utils/file-walker');\nconst { validateMdx } = require('../utils/mdx-parser');\n\nlet errors = [];\nlet warnings = [];\n\n/**\n * Run MDX validation tests\n */\nfunction runTests(options = {}) {\n errors = [];\n warnings = [];\n \n const { files = null, stagedOnly = false } = options;\n \n let testFiles = files;\n if (!testFiles) {\n if (stagedOnly) {\n testFiles = getStagedDocsPageFiles().filter(f => f.endsWith('.mdx'));\n } else {\n testFiles = getMdxFiles();\n }\n }\n \n testFiles.forEach(file => {\n const content = readFile(file);\n if (!content) return;\n \n const result = validateMdx(content, file);\n errors.push(...result.errors.map(err => ({\n file,\n ...(typeof err === 'string' ? { message: err } : err)\n })));\n warnings.push(...result.warnings.map(warn => ({\n file,\n message: warn\n })));\n });\n \n return {\n errors,\n warnings,\n passed: errors.length === 0,\n total: testFiles.length\n };\n}\n\n// Run if called directly\nif (require.main === module) {\n const args = process.argv.slice(2);\n const stagedOnly = args.includes('--staged');\n \n const result = runTests({ stagedOnly });\n \n if (result.errors.length > 0) {\n console.error('\\n❌ MDX Validation Errors:\\n');\n result.errors.forEach(err => {\n const line = err.line ? `:${err.line}` : '';\n console.error(` ${err.file}${line} - ${err.message || err}`);\n });\n }\n \n if (result.warnings.length > 0) {\n console.warn('\\n⚠️ MDX Warnings:\\n');\n result.warnings.forEach(warn => {\n console.warn(` ${warn.file} - ${warn.message}`);\n });\n }\n \n if (result.passed) {\n console.log(`\\n✅ MDX validation passed (${result.total} files checked)`);\n process.exit(0);\n } else {\n console.error(`\\n❌ ${result.errors.length} error(s) found`);\n process.exit(1);\n }\n}\n\nmodule.exports = { runTests };\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "runner", + "caller": "tests/run-all.js", + "pipeline": "P1" + }, + { + "type": "runner", + "caller": "tests/run-pr-checks.js", + "pipeline": "P3" + }, + { + "type": "script", + "caller": "tests/run-all.js", + "pipeline": "indirect" + }, + { + "type": "script", + "caller": "tests/run-pr-checks.js", + "pipeline": "indirect" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:mdx" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "test:mdx" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "P1 via run-all; P3 via run-pr-checks; indirect via tests/run-all.js; indirect via tests/run-pr-checks.js; manual (npm script: test:mdx); manual (npm script: test:mdx)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "P1" + }, + { + "path": "tests/unit/quality.test.js", + "script": "quality.test", + "category": "validator", + "purpose": "qa:content-quality", + "scope": "tests", + "owner": "docs", + "needs": "E-R1, R-R11", + "purpose_statement": "Content quality checks — validates frontmatter completeness, thin content detection, placeholder flagging", + "pipeline_declared": "P1, P3", + "usage": "node tests/unit/quality.test.js [flags]", + "header": "#!/usr/bin/env node\n/**\n * @script quality.test\n * @category validator\n * @purpose qa:content-quality\n * @scope tests\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Content quality checks — validates frontmatter completeness, thin content detection, placeholder flagging\n * @pipeline P1, P3\n * @usage node tests/unit/quality.test.js [flags]\n */\n/**\n * Quality checks: alt text, links, frontmatter, SEO\n */\n\nconst path = require('path');\nconst { getMdxFiles, getStagedDocsPageFiles, readFile } = require('../utils/file-walker');\nconst { extractFrontmatter } = require('../utils/mdx-parser');\n\nconst ENFORCE_OG_IMAGE = process.env.ENFORCE_OG_IMAGE === '1';\nconst VALID_PAGE_TYPES = ['quickstart', 'tutorial', 'reference', 'conceptual', 'portal', 'api', 'guide', 'overview', 'index'];\nconst VALID_AUDIENCES = ['developer', 'orchestrator', 'gateway', 'delegator', 'community', 'all'];\nconst VALID_STATUSES = ['draft', 'published', 'review', 'deprecated'];\n\nlet errors = [];\nlet warnings = [];\n\nfunction report(severity, file, message, rule = 'Frontmatter') {\n const issue = { file, rule, message };\n if (severity === 'error') {\n errors.push(issue);\n return;\n }\n warnings.push(issue);\n}\n\nfunction collectFilesFromArgs(args) {\n const files = [];\n\n for (let i = 0; i < args.length; i += 1) {\n const token = args[i];\n if (token === '--files' || token === '--file') {\n const raw = String(args[i + 1] || '').trim();\n if (raw) {\n raw\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((part) => {\n files.push(path.isAbsolute(part) ? part : path.resolve(part));\n });\n }\n i += 1;\n }\n }\n\n return [...new Set(files)];\n}\n\n/**\n * Check for image alt text\n */\nfunction checkImageAltText(files) {\n files.forEach(file => {\n const content = readFile(file);\n if (!content) return;\n \n // Check for img tags without alt\n const imgRegex = /
table breaks, raw comparison operators, code-like table cells, and angle-bracket placeholders.',\n ' - Skips fenced code blocks and inline code spans.',\n ' - Leaves ambiguous prose rewrites untouched.'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n mode: 'dry-run',\n stagedOnly: false,\n files: [],\n stage: false,\n help: false\n };\n\n let explicitModeCount = 0;\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n if (token === '--dry-run') {\n args.mode = 'dry-run';\n explicitModeCount += 1;\n continue;\n }\n\n if (token === '--write') {\n args.mode = 'write';\n explicitModeCount += 1;\n continue;\n }\n\n if (token === '--staged') {\n args.stagedOnly = true;\n continue;\n }\n\n if (token === '--stage') {\n args.stage = true;\n continue;\n }\n\n if (token === '--files') {\n const raw = String(argv[index + 1] || '').trim();\n if (!raw) {\n throw new Error('Missing value for --files');\n }\n raw\n .split(',')\n .map((entry) => entry.trim())\n .filter(Boolean)\n .forEach((entry) => args.files.push(entry));\n index += 1;\n continue;\n }\n\n if (token.startsWith('--files=')) {\n token\n .slice('--files='.length)\n .split(',')\n .map((entry) => entry.trim())\n .filter(Boolean)\n .forEach((entry) => args.files.push(entry));\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (explicitModeCount > 1) {\n throw new Error('Choose only one mode: --dry-run or --write');\n }\n\n if (args.stagedOnly && args.files.length > 0) {\n throw new Error('Use either --staged or --files, not both');\n }\n\n if (args.stage && args.mode !== 'write') {\n throw new Error('--stage requires --write');\n }\n\n args.files = [...new Set(args.files)];\n return args;\n}\n\nfunction stageFiles(files) {\n if (!files.length) return;\n const relFiles = files.map((filePath) => normalizeRepoPath(path.relative(REPO_ROOT, filePath)));\n const result = spawnSync('git', ['add', '--', ...relFiles], {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n\n if (result.status !== 0) {\n throw new Error(result.stderr || result.stdout || 'Failed to stage repaired files');\n }\n}\n\nfunction summariseRepairsByRule(repairs) {\n return repairs.reduce((accumulator, repair) => {\n repair.changes.forEach((change) => {\n accumulator[change.rule] = (accumulator[change.rule] || 0) + 1;\n });\n return accumulator;\n }, {});\n}\n\nfunction run(options = {}) {\n const args = options.args || parseArgs([]);\n const quiet = options.quiet === true;\n const files = Array.isArray(options.files) && options.files.length > 0\n ? options.files\n : collectTargetMarkdownFiles({\n rootDir: REPO_ROOT,\n stagedOnly: args.stagedOnly,\n files: args.files\n });\n\n const repairs = [];\n const changedFiles = [];\n\n files.forEach((filePath) => {\n const content = readFileSafe(filePath);\n if (!content) return;\n\n const result = repairMarkdownContent(content, normalizeRepoPath(path.relative(REPO_ROOT, filePath)));\n if (!result.changed) return;\n\n repairs.push({\n file: filePath,\n changes: result.changes,\n nextContent: result.content\n });\n\n if (args.mode === 'write') {\n fs.writeFileSync(filePath, result.content, 'utf8');\n changedFiles.push(filePath);\n }\n });\n\n if (args.mode === 'write' && args.stage && changedFiles.length > 0) {\n stageFiles(changedFiles);\n }\n\n const byRule = summariseRepairsByRule(repairs);\n const summary = {\n mode: args.mode,\n scannedFiles: files.length,\n changedFiles: repairs.length,\n stagedFiles: changedFiles.length,\n proposedRepairs: repairs.reduce((total, repair) => total + repair.changes.length, 0),\n byRule,\n repairs\n };\n\n if (!quiet) {\n const verb = args.mode === 'write' ? 'Applied' : 'Proposed';\n console.log(`\\n${verb} ${summary.proposedRepairs} MDX-safe markdown repair(s) across ${summary.changedFiles} file(s) (${summary.scannedFiles} scanned).`);\n Object.entries(byRule)\n .sort((left, right) => left[0].localeCompare(right[0]))\n .forEach(([rule, count]) => {\n console.log(` - ${rule}: ${count}`);\n });\n repairs.forEach((repair) => {\n console.log(` ${normalizeRepoPath(path.relative(REPO_ROOT, repair.file))}`);\n repair.changes.forEach((change) => {\n console.log(` line ${change.line}: ${change.rule}`);\n });\n });\n }\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "pre-commit", + "caller": ".githooks/pre-commit", + "pipeline": "P1" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "repair:mdx-safe-markdown" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "repair:mdx-safe-markdown:dry-run" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "P1 (pre-commit); manual (npm script: repair:mdx-safe-markdown); manual (npm script: repair:mdx-safe-markdown:dry-run)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "P1" + }, + { + "path": "tools/scripts/validators/content/check-mdx-safe-markdown.js", + "script": "check-mdx-safe-markdown", + "category": "validator", + "purpose": "qa:content-quality", + "scope": "tools/scripts/validators/content, first-party markdown/mdx files", + "owner": "docs", + "needs": "E-R1, R-R11", + "purpose_statement": "Validates first-party markdown and MDX content for repo-wide MDX-safe syntax, including parse failures and deterministic unsafe patterns.", + "pipeline_declared": "P1, P3", + "usage": "node tools/scripts/validators/content/check-mdx-safe-markdown.js [--staged|--files a,b] [--json]", + "header": "#!/usr/bin/env node\n/**\n * @script check-mdx-safe-markdown\n * @category validator\n * @purpose qa:content-quality\n * @scope tools/scripts/validators/content, first-party markdown/mdx files\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Validates first-party markdown and MDX content for repo-wide MDX-safe syntax, including parse failures and deterministic unsafe patterns.\n * @pipeline P1, P3\n * @dualmode --staged (changed-file scope) | --files (explicit scope) | default full-repo\n * @usage node tools/scripts/validators/content/check-mdx-safe-markdown.js [--staged|--files a,b] [--json]\n */\n\nconst path = require('path');\nconst {\n REPO_ROOT,\n collectTargetMarkdownFiles,\n normalizeRepoPath,\n readFileSafe,\n validateMarkdownContent\n} = require('../../../lib/mdx-safe-markdown');\n\nfunction printHelp() {\n console.log(\n [\n 'Usage:',\n ' node tools/scripts/validators/content/check-mdx-safe-markdown.js [--staged|--files a,b] [--json]',\n '',\n 'Scope:',\n ' --staged Validate staged first-party .md/.mdx files only.',\n ' --files Validate explicit repo-relative files or directories (comma-separated, repeatable).',\n '',\n 'Output:',\n ' --json Emit machine-readable JSON findings.'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n stagedOnly: false,\n files: [],\n json: false,\n help: false\n };\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n if (token === '--staged') {\n args.stagedOnly = true;\n continue;\n }\n\n if (token === '--json') {\n args.json = true;\n continue;\n }\n\n if (token === '--files') {\n const raw = String(argv[index + 1] || '').trim();\n if (!raw) throw new Error('Missing value for --files');\n raw\n .split(',')\n .map((entry) => entry.trim())\n .filter(Boolean)\n .forEach((entry) => args.files.push(entry));\n index += 1;\n continue;\n }\n\n if (token.startsWith('--files=')) {\n token\n .slice('--files='.length)\n .split(',')\n .map((entry) => entry.trim())\n .filter(Boolean)\n .forEach((entry) => args.files.push(entry));\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (args.stagedOnly && args.files.length > 0) {\n throw new Error('Use either --staged or --files, not both');\n }\n\n args.files = [...new Set(args.files)];\n return args;\n}\n\nfunction run(options = {}) {\n const args = options.args || parseArgs([]);\n const files = Array.isArray(options.files) && options.files.length > 0\n ? options.files\n : collectTargetMarkdownFiles({\n rootDir: REPO_ROOT,\n stagedOnly: args.stagedOnly,\n files: args.files\n });\n\n const findings = [];\n\n files.forEach((filePath) => {\n const content = readFileSafe(filePath);\n if (!content) return;\n\n const relPath = normalizeRepoPath(path.relative(REPO_ROOT, filePath));\n const result = validateMarkdownContent(content, relPath);\n result.findings.forEach((finding) => {\n findings.push({\n file: relPath,\n line: finding.line || 1,\n column: finding.column || 1,\n rule: finding.rule || 'mdx-safe-markdown',\n message: finding.message || 'Unknown MDX-safe markdown violation'\n });\n });\n });\n\n return {\n files,\n findings,\n errors: findings,\n warnings: [],\n passed: findings.length === 0,\n total: files.length\n };\n}\n\nif (require.main === module) {\n try {\n const args = parseArgs(process.argv.slice(2));\n if (args.help) {\n printHelp();\n process.exit(0);\n }\n\n const result = run({ args });\n if (args.json) {\n process.stdout.write(`${JSON.stringify(result, null, 2)}\\n`);\n } else if (result.findings.length > 0) {\n console.error('\\n❌ MDX-safe Markdown Violations:\\n');\n result.findings.forEach((finding) => {\n console.error(` ${finding.file}:${finding.line}:${finding.column} - ${finding.rule}: ${finding.message}`);\n });\n console.error(`\\n❌ ${result.findings.length} violation(s) found across ${result.total} file(s)`);\n } else {\n console.log(`\\n✅ MDX-safe markdown validation passed (${result.total} files checked)`);\n }\n\n process.exit(result.passed ? 0 : 1);\n } catch (error) {\n console.error(`❌ ${error.message}`);\n process.exit(1);\n }\n}\n\nmodule.exports = {\n parseArgs,\n run\n};\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "pre-commit", + "caller": ".githooks/pre-commit", + "pipeline": "P1" + }, + { + "type": "runner", + "caller": "tests/run-all.js", + "pipeline": "P1" + }, + { + "type": "runner", + "caller": "tests/run-pr-checks.js", + "pipeline": "P3" + }, + { + "type": "script", + "caller": "tests/run-all.js", + "pipeline": "indirect" + }, + { + "type": "script", + "caller": "tests/run-pr-checks.js", + "pipeline": "indirect" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:mdx:safe" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "test:mdx:safe" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "P1 (pre-commit); P1 via run-all; P3 via run-pr-checks; indirect via tests/run-all.js; indirect via tests/run-pr-checks.js; manual (npm script: test:mdx:safe); manual (npm script: test:mdx:safe)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "P1" + }, + { + "path": "tests/integration/v2-link-audit.js", + "script": "v2-link-audit", + "category": "validator", + "purpose": "qa:link-integrity", + "scope": "tests", + "owner": "docs", + "needs": "E-R12, E-R14", + "purpose_statement": "Comprehensive V2 MDX link audit — checks internal links, external links, anchor refs. Supports --staged, --full, --strict, --write-links modes.", + "pipeline_declared": "P1, P5, P6", + "usage": "node tests/integration/v2-link-audit.js [flags]", + "header": "#!/usr/bin/env node\n/**\n * @script v2-link-audit\n * @category validator\n * @purpose qa:link-integrity\n * @scope tests\n * @owner docs\n * @needs E-R12, E-R14\n * @purpose-statement Comprehensive V2 MDX link audit — checks internal links, external links, anchor refs. Supports --staged, --full, --strict, --write-links modes.\n * @pipeline P1, P5, P6\n * @dualmode --full (validator) | --write-links (remediator)\n * @usage node tests/integration/v2-link-audit.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst { extractImports } = require('../utils/mdx-parser');\nconst {\n getStagedFiles,\n isExcludedV2ExperimentalPath,\n filterPathsByMintIgnore\n} = require('../utils/file-walker');\n\nconst REPO_ROOT = getRepoRoot();\nconst LEGACY_V2_PAGES_DIR = path.join(REPO_ROOT, 'v2', 'pages');\nconst MODERN_V2_PAGES_DIR = path.join(REPO_ROOT, 'v2');\nconst V2_PAGES_DIR = fs.existsSync(LEGACY_V2_PAGES_DIR) ? LEGACY_V2_PAGES_DIR : MODERN_V2_PAGES_DIR;\nconst INDEX_PATH = path.join(V2_PAGES_DIR, 'index.mdx');\nconst DOCS_CONFIG_PATH = path.join(REPO_ROOT, 'docs.json');\nconst DEFAULT_REPORT = path.join(REPO_ROOT, 'tasks', 'reports', 'navigation-links', 'LINK_TEST_REPORT.md');\nconst DEFAULT_REPORT_JSON = path.join(REPO_ROOT, 'tasks', 'reports', 'navigation-links', 'LINK_TEST_REPORT.json');\nconst LINKABLE_ATTRS = ['href', 'src', 'srcset', 'poster', 'action', 'data', 'to', 'image', 'url'];\nconst EXCLUDED_ATTRS = new Set(['icon']);\nconst FILE_EXT_CANDIDATES = ['.mdx', '.md', '.jsx', '.js', '.tsx', '.ts', '.json'];\nconst INDEX_CANDIDATES = ['index.mdx', 'index.md', 'README.mdx', 'README.md'];\nconst EXTERNAL_UNTESTED = '🟡 untested-external';\nconst EXTERNAL_PENDING = 'external-pending';\nconst EXTERNAL_OK = 'external-ok';\nconst EXTERNAL_SOFT_FAIL = 'external-soft-fail';\nconst EXTERNAL_HARD_FAIL = 'external-hard-fail';\nconst EXTERNAL_POLICY_VALUES = new Set(['classify', 'validate']);\nconst EXTERNAL_LINK_TYPES_VALUES = new Set(['navigational', 'media', 'all']);\nconst HEAD_FALLBACK_STATUSES = new Set([401, 403, 405, 501]);\nconst TRANSIENT_STATUSES = new Set([429, 500, 502, 503, 504]);\nconst MEDIA_ATTRS = new Set(['src', 'srcset', 'poster', 'image']);\nconst NAV_ATTRS = new Set(['href', 'to']);\nconst MIGRATED_V2_DOMAIN_DIRS = new Set([\n 'home',\n 'about',\n 'solutions',\n 'community',\n 'developers',\n 'gateways',\n 'orchestrators',\n 'lpt',\n 'resources',\n 'internal',\n 'deprecated',\n 'experimental',\n 'notes'\n]);\nconst MISSING_LINK_ALLOWLIST = new Set([\n '/gateways/run-a-gateway/test/test-gateway',\n './protocol-economics'\n]);\nconst EXTRA_V2_DIRS = (() => {\n if (!fs.existsSync(LEGACY_V2_PAGES_DIR)) return [];\n const dirs = [];\n for (const domain of MIGRATED_V2_DOMAIN_DIRS) {\n const candidate = path.join(MODERN_V2_PAGES_DIR, domain);\n if (fs.existsSync(candidate)) dirs.push(candidate);\n }\n return dirs;\n})();\n\nfunction getRepoRoot() {\n try {\n return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n } catch (_error) {\n return process.cwd();\n }\n}\n\nfunction toPosix(p) {\n return String(p || '').split(path.sep).join('/');\n}\n\nfunction relFromRoot(absPath) {\n return toPosix(path.relative(REPO_ROOT, absPath));\n}\n\nfunction relNoExt(absPath) {\n const rel = relFromRoot(absPath);\n return toPosix(rel.replace(/\\.(mdx|md)$/i, ''));\n}\n\nfunction isExcludedV2AbsPath(absPath) {\n const rel = relFromRoot(absPath);\n return isExcludedV2ExperimentalPath(rel);\n}\n\nfunction isActiveV2DocRel(relPath) {\n const rel = toPosix(String(relPath || ''));\n if (rel.startsWith('v2/pages/')) return true;\n if (!rel.startsWith('v2/')) return false;\n if (isExcludedV2ExperimentalPath(rel)) return false;\n const first = rel.slice('v2/'.length).split('/')[0];\n return MIGRATED_V2_DOMAIN_DIRS.has(first);\n}\n\nfunction stripV2DocsRoot(relPath) {\n const rel = toPosix(String(relPath || ''));\n if (rel.startsWith('v2/pages/')) return rel.slice('v2/pages/'.length);\n if (rel.startsWith('v2/')) return rel.slice('v2/'.length);\n return rel;\n}\n\nfunction parseIntegerFlag(raw, fallback, { min = 0 } = {}) {\n const parsed = Number(raw);\n if (!Number.isFinite(parsed)) return fallback;\n const floored = Math.floor(parsed);\n if (floored < min) return fallback;\n return floored;\n}\n\nfunction deriveJsonReportPath(reportPath) {\n const parsed = path.parse(path.resolve(REPO_ROOT, reportPath || DEFAULT_REPORT));\n if (!parsed.ext) {\n return path.join(parsed.dir, `${parsed.base}.json`);\n }\n return path.join(parsed.dir, `${parsed.name}.json`);\n}\n\nfunction parseArgs(argv) {\n const args = {\n mode: 'full',\n report: DEFAULT_REPORT,\n reportJson: DEFAULT_REPORT_JSON,\n respectMintIgnore: true,\n strict: false,\n strictRootsOnly: false,\n writeLinks: undefined,\n externalPolicy: 'classify',\n externalLinkTypes: 'navigational',\n externalTimeoutMs: 10000,\n externalConcurrency: 12,\n externalPerHostConcurrency: 2,\n externalRetries: 1,\n files: []\n };\n let reportExplicit = false;\n let reportJsonExplicit = false;\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--full') args.mode = 'full';\n else if (token === '--staged') args.mode = 'staged';\n else if (token === '--files' || token === '--file') {\n const raw = String(argv[i + 1] || '').trim();\n if (raw) {\n raw\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((part) => args.files.push(part));\n }\n i += 1;\n }\n else if (token === '--strict') args.strict = true;\n else if (token === '--strict-roots-only') args.strictRootsOnly = true;\n else if (token === '--no-mintignore') args.respectMintIgnore = false;\n else if (token === '--write-links') args.writeLinks = true;\n else if (token === '--no-write-links') args.writeLinks = false;\n else if (token === '--report') {\n args.report = path.resolve(REPO_ROOT, argv[i + 1] || '');\n reportExplicit = true;\n i += 1;\n } else if (token === '--report-json') {\n args.reportJson = path.resolve(REPO_ROOT, argv[i + 1] || '');\n reportJsonExplicit = true;\n i += 1;\n } else if (token === '--external-policy') {\n args.externalPolicy = String(argv[i + 1] || '').trim().toLowerCase();\n i += 1;\n } else if (token === '--external-link-types') {\n args.externalLinkTypes = String(argv[i + 1] || '').trim().toLowerCase();\n i += 1;\n } else if (token === '--external-timeout-ms') {\n args.externalTimeoutMs = parseIntegerFlag(argv[i + 1], args.externalTimeoutMs, { min: 1 });\n i += 1;\n } else if (token === '--external-concurrency') {\n args.externalConcurrency = parseIntegerFlag(argv[i + 1], args.externalConcurrency, { min: 1 });\n i += 1;\n } else if (token === '--external-per-host-concurrency') {\n args.externalPerHostConcurrency = parseIntegerFlag(argv[i + 1], args.externalPerHostConcurrency, { min: 1 });\n i += 1;\n } else if (token === '--external-retries') {\n args.externalRetries = parseIntegerFlag(argv[i + 1], args.externalRetries, { min: 0 });\n i += 1;\n } else {\n throw new Error(`Unknown option: ${token}`);\n }\n }\n\n if (!EXTERNAL_POLICY_VALUES.has(args.externalPolicy)) {\n throw new Error('Invalid --external-policy value. Use classify|validate.');\n }\n\n if (!EXTERNAL_LINK_TYPES_VALUES.has(args.externalLinkTypes)) {\n throw new Error('Invalid --external-link-types value. Use navigational|media|all.');\n }\n\n args.files = [...new Set(args.files)];\n if (args.files.length > 0) {\n args.mode = 'files';\n }\n\n if (typeof args.writeLinks === 'undefined') {\n args.writeLinks = args.mode === 'full';", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "pre-commit", + "caller": ".githooks/pre-commit", + "pipeline": "P1" + }, + { + "type": "workflow-schedule", + "caller": ".github/workflows/v2-external-link-audit.yml", + "workflow": "V2 External Link Audit (Advisory)", + "pipeline": "P5", + "cron": "0 4 * * *" + }, + { + "type": "workflow-dispatch", + "caller": ".github/workflows/v2-external-link-audit.yml", + "workflow": "V2 External Link Audit (Advisory)", + "pipeline": "P6" + }, + { + "type": "script", + "caller": "tests/integration/v2-link-audit.selftest.js", + "pipeline": "indirect" + }, + { + "type": "script", + "caller": "tests/unit/create-codex-pr.test.js", + "pipeline": "indirect" + }, + { + "type": "script", + "caller": "tests/unit/v2-link-audit.test.js", + "pipeline": "indirect" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:link-audit" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:link-audit:staged" + }, + { + "type": "npm-script", + "caller": "tests/package.json", + "pipeline": "manual", + "script_name": "test:link-audit:external" + } + ], + "outputs": [ + { + "output_path": "tests/integration/hrefs.jsx", + "type": "generated-output", + "call": "writeFileSync" + } + ], + "outputs_display": "tests/integration/hrefs.jsx", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "P1 (pre-commit); P5 (V2 External Link Audit (Advisory) cron 0 4 * * *); P6 (V2 External Link Audit (Advisory)); indirect via tests/integration/v2-link-audit.selftest.js; indirect via tests/unit/create-codex-pr.test.js; indirect via tests/unit/v2-link-audit.test.js; manual (npm script: test:link-audit); manual (npm script: test:link-audit:staged); manual (npm script: test:link-audit:external)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "P1" + }, + { + "path": "tests/unit/links-imports.test.js", + "script": "links-imports.test", + "category": "validator", + "purpose": "qa:link-integrity", + "scope": "tests", + "owner": "docs", + "needs": "E-R12, E-R14", + "purpose_statement": "Validates MDX internal links and snippet import paths are resolvable", + "pipeline_declared": "P1, P3", + "usage": "node tests/unit/links-imports.test.js [flags]", + "header": "#!/usr/bin/env node\n/**\n * @script links-imports.test\n * @category validator\n * @purpose qa:link-integrity\n * @scope tests\n * @owner docs\n * @needs E-R12, E-R14\n * @purpose-statement Validates MDX internal links and snippet import paths are resolvable\n * @pipeline P1, P3\n * @usage node tests/unit/links-imports.test.js [flags]\n */\n/**\n * Broken links and imports validation\n * Checks that all internal links and imports resolve to existing files\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\nconst { getMdxFiles, getStagedDocsPageFiles, readFile } = require('../utils/file-walker');\nconst { extractImports } = require('../utils/mdx-parser');\n\nlet errors = [];\nlet warnings = [];\nconst GENERATED_EXTERNAL_DOCS = [\n 'awesome-livepeer-readme.mdx',\n 'box-additional-config.mdx',\n 'gwid-readme.mdx',\n 'whitepaper.mdx',\n 'wiki-readme.mdx'\n];\nconst V2_DOMAIN_DIRS = new Set([\n 'home',\n 'about',\n 'solutions',\n 'community',\n 'developers',\n 'gateways',\n 'orchestrators',\n 'lpt',\n 'resources',\n 'internal',\n 'deprecated',\n 'experimental',\n 'notes'\n]);\n\nfunction ensureExternalDocs() {\n const repoRoot = process.cwd();\n const externalDir = path.join(repoRoot, 'snippets', 'external');\n const missingFiles = GENERATED_EXTERNAL_DOCS.filter(\n (fileName) => !fs.existsSync(path.join(externalDir, fileName))\n );\n\n if (missingFiles.length === 0) {\n return;\n }\n\n const fetchScript = path.join(repoRoot, 'tools', 'scripts', 'snippets', 'fetch-external-docs.sh');\n if (!fs.existsSync(fetchScript)) {\n warnings.push({\n file: 'tools/scripts/snippets/fetch-external-docs.sh',\n message: `Missing external-doc bootstrap script; generated imports may fail: ${missingFiles.join(', ')}`\n });\n return;\n }\n\n const result = spawnSync('bash', [fetchScript], {\n cwd: repoRoot,\n encoding: 'utf8',\n env: {\n ...process.env,\n LC_ALL: process.env.LC_ALL || 'C',\n LANG: process.env.LANG || 'C'\n }\n });\n\n if (result.status !== 0) {\n const detail = String(result.stderr || result.stdout || '')\n .trim()\n .split('\\n')\n .slice(-3)\n .join(' ');\n errors.push({\n file: 'tools/scripts/snippets/fetch-external-docs.sh',\n rule: 'External docs fetch',\n message: `Failed to fetch generated external docs required for import validation.${detail ? ` ${detail}` : ''}`\n });\n }\n}\n\nfunction isStyleGuideExampleFile(file) {\n return file.includes('style-guide.mdx');\n}\n\n/**\n * Resolve a file path relative to the repository root\n */\nfunction resolveFilePath(filePath, rootDir = process.cwd()) {\n if (path.isAbsolute(filePath)) {\n return path.join(rootDir, filePath);\n }\n return path.resolve(rootDir, filePath);\n}\n\n/**\n * Check if a file exists (tries multiple extensions/variations)\n */\nfunction fileExists(filePath) {\n // Try exact path\n if (fs.existsSync(filePath)) {\n return { exists: true, path: filePath };\n }\n \n // Try with .mdx extension\n const withMdx = filePath.endsWith('.mdx') ? filePath : `${filePath}.mdx`;\n if (fs.existsSync(withMdx)) {\n return { exists: true, path: withMdx };\n }\n \n // Try as directory with index.mdx\n const dirIndex = path.join(filePath, 'index.mdx');\n if (fs.existsSync(dirIndex)) {\n return { exists: true, path: dirIndex };\n }\n \n // Try as directory with README.mdx\n const dirReadme = path.join(filePath, 'README.mdx');\n if (fs.existsSync(dirReadme)) {\n return { exists: true, path: dirReadme };\n }\n \n return { exists: false, path: null };\n}\n\n/**\n * Convert link path to file path\n */\nfunction linkToFilePath(linkPath, currentFile) {\n const rootDir = process.cwd();\n const normalizedLinkPath = linkPath\n .split('#')[0]\n .split('?')[0]\n .trim()\n .replace(/^['\"]+|['\"]+$/g, '');\n \n // Skip external links\n if (normalizedLinkPath.startsWith('http://') ||\n normalizedLinkPath.startsWith('https://') ||\n normalizedLinkPath.startsWith('mailto:') ||\n normalizedLinkPath.startsWith('#') ||\n normalizedLinkPath.length === 0) {\n return null;\n }\n \n // Get repo root directory (where .git is) - same fix as getStagedFiles\n const { execSync } = require('child_process');\n let repoRoot;\n try {\n repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n } catch (e) {\n repoRoot = rootDir; // Fallback to rootDir if not in git repo\n }\n \n // Absolute path from root (starts with /)\n if (normalizedLinkPath.startsWith('/')) {\n // Remove leading slash and normalize trailing slash\n const repoRelativePath = normalizedLinkPath.replace(/^\\//, '').replace(/\\/$/, '');\n if (!repoRelativePath) {\n return null;\n }\n\n // Prefer repository-root absolute links when they already exist.\n const directRepoPath = path.join(repoRoot, repoRelativePath);\n if (fileExists(directRepoPath).exists) {\n return directRepoPath;\n }\n\n // If it already starts with v2/, treat it as a repo-relative docs path.\n if (repoRelativePath.startsWith('v2/')) {\n return path.join(repoRoot, repoRelativePath);\n }\n\n // Support migrated v2 domain folders, e.g. /home/... or /about/...\n const firstSegment = repoRelativePath.split('/')[0];\n if (V2_DOMAIN_DIRS.has(firstSegment)) {\n return path.join(repoRoot, 'v2', repoRelativePath);\n }\n\n // Fallback: treat bare absolute docs links as v2/pages-relative.\n return path.join(repoRoot, `v2/pages/${repoRelativePath}`);\n }\n \n // Relative path\n const currentDir = path.dirname(currentFile);\n const resolved = path.resolve(currentDir, normalizedLinkPath);\n\n // If this resolves into v2/pages/
{/* #123456 */}
;'\n ].join('\\n'),\n 'utf8'\n );\n\n const violations = scanStylingViolations(tempFile);\n assert.equal(violations.banned.length, 0);\n assert.equal(violations.advisory.length, 1);\n } catch (error) {\n errors.push(`scanStylingViolations failed: ${error.message}`);\n }\n\n try {\n const componentFiles = getComponentFiles();\n assert(componentFiles.length > 0, 'component file discovery should find governed files');\n assert(componentFiles.every((file) => !file.displayPath.includes('/_archive/')));\n } catch (error) {\n errors.push(`getComponentFiles failed: ${error.message}`);\n }\n\n return { errors, warnings };\n}\n\nif (require.main === module) {\n const result = runTests();\n result.errors.forEach((error) => console.error(error));\n result.warnings.forEach((warning) => console.warn(warning));\n process.exit(result.errors.length > 0 ? 1 : 0);\n}\n\nmodule.exports = { runTests };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "runner",
+ "caller": "tests/run-all.js",
+ "pipeline": "P1"
+ },
+ {
+ "type": "script",
+ "caller": "tests/run-all.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:components:governance"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tests/unit/styling-scan.jsx",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tests/unit/styling-scan.jsx",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P1 via run-all; indirect via tests/run-all.js; manual (npm script: test:components:governance)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P1"
+ },
+ {
+ "path": "tests/unit/docs-navigation.test.js",
+ "script": "docs-navigation.test",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": "tests, docs.json",
+ "owner": "docs",
+ "needs": "E-C1, R-R14",
+ "purpose_statement": "Validates docs.json page-entry syntax, reports missing routes, warns on orphaned canonical v2 pages, suggests remaps, and optionally applies approved remaps",
+ "pipeline_declared": "P1, P3, P6",
+ "usage": "node tests/unit/docs-navigation.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script docs-navigation.test\n * @category validator\n * @purpose qa:repo-health\n * @scope tests, docs.json\n * @owner docs\n * @needs E-C1, R-R14\n * @purpose-statement Validates docs.json page-entry syntax, reports missing routes, warns on orphaned canonical v2 pages, suggests remaps, and optionally applies approved remaps\n * @pipeline P1, P3, P6\n * @dualmode dual-mode (document flags)\n * @usage node tests/unit/docs-navigation.test.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst readline = require('readline');\nconst { execSync } = require('child_process');\nconst { listMintIgnoredRepoPaths } = require('../utils/mintignore');\n\nconst REPORT_MD_REL = 'tasks/reports/navigation-links/navigation-report.md';\nconst REPORT_JSON_REL = 'tasks/reports/navigation-links/navigation-report.json';\nconst I18N_CONFIG_REL = 'tools/i18n/config.json';\nconst DEFAULT_REMAP_THRESHOLD = 0.85;\nconst RESOURCE_HUB_REDIRECT_ROUTE = 'v2/resources/redirect';\nconst RESOURCE_HUB_PORTAL_ROUTE = 'v2/resources/resources-portal';\nconst LEGACY_RESOURCE_HUB_ROUTE = 'v2/pages/07_resources/redirect';\n\nlet errors = [];\nlet warnings = [];\n\nfunction getRepoRoot() {\n try {\n return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n } catch (_error) {\n return process.cwd();\n }\n}\n\nfunction toPosix(filePath) {\n return String(filePath || '').split(path.sep).join('/');\n}\n\nfunction parseArgs(argv) {\n const args = {\n strictMissing: false,\n writeRemaps: false,\n writeReport: false,\n remapThreshold: DEFAULT_REMAP_THRESHOLD\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--strict-missing') {\n args.strictMissing = true;\n continue;\n }\n if (token === '--write-remaps') {\n args.writeRemaps = true;\n continue;\n }\n if (token === '--write-report') {\n args.writeReport = true;\n continue;\n }\n if (token === '--no-write-report') {\n args.writeReport = false;\n continue;\n }\n if (token === '--remap-threshold') {\n const parsed = Number(argv[i + 1]);\n if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 1) {\n args.remapThreshold = parsed;\n i += 1;\n }\n }\n }\n\n return args;\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction walkDocsFiles(dirPath, out = []) {\n if (!fs.existsSync(dirPath)) return out;\n const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n for (const entry of entries) {\n const fullPath = path.join(dirPath, entry.name);\n if (entry.isDirectory()) {\n walkDocsFiles(fullPath, out);\n } else if (/\\.(md|mdx)$/i.test(entry.name)) {\n out.push(fullPath);\n }\n }\n return out;\n}\n\nfunction collectExistingRoutes(repoRoot) {\n const roots = [path.join(repoRoot, 'v1'), path.join(repoRoot, 'v2', 'pages'), path.join(repoRoot, 'v2')];\n const routeSet = new Set();\n\n roots.forEach((rootPath) => {\n const files = walkDocsFiles(rootPath);\n files.forEach((filePath) => {\n const relPath = toPosix(path.relative(repoRoot, filePath));\n const withoutExt = relPath.replace(/\\.(md|mdx)$/i, '');\n routeSet.add(withoutExt);\n\n if (withoutExt.endsWith('/index')) {\n routeSet.add(withoutExt.replace(/\\/index$/i, ''));\n }\n if (withoutExt.endsWith('/README')) {\n routeSet.add(withoutExt.replace(/\\/README$/i, ''));\n }\n });\n });\n\n return [...routeSet];\n}\n\nfunction collectPageEntries(node, pointer, out = []) {\n if (Array.isArray(node)) {\n node.forEach((item, index) => collectPageEntries(item, `${pointer}[${index}]`, out));\n return out;\n }\n\n if (!node || typeof node !== 'object') {\n return out;\n }\n\n if (Array.isArray(node.pages)) {\n node.pages.forEach((entry, index) => {\n const entryPointer = `${pointer}.pages[${index}]`;\n if (typeof entry === 'string') {\n out.push({ value: entry, pointer: entryPointer });\n return;\n }\n collectPageEntries(entry, entryPointer, out);\n });\n }\n\n Object.entries(node).forEach(([key, value]) => {\n if (key === 'pages') return;\n collectPageEntries(value, `${pointer}.${key}`, out);\n });\n\n return out;\n}\n\nfunction collectObjectNodes(node, pointer, out = []) {\n if (Array.isArray(node)) {\n node.forEach((item, index) => collectObjectNodes(item, `${pointer}[${index}]`, out));\n return out;\n }\n\n if (!node || typeof node !== 'object') return out;\n out.push({ node, pointer });\n\n Object.entries(node).forEach(([key, value]) => {\n collectObjectNodes(value, `${pointer}.${key}`, out);\n });\n\n return out;\n}\n\nfunction normalizeRoute(rawValue) {\n let value = String(rawValue || '').trim();\n value = value.replace(/^\\/+/, '');\n value = value.replace(/\\.(md|mdx)$/i, '');\n value = value.replace(/\\/+$/, '');\n return value;\n}\n\nfunction normalizeOrphanRouteKey(rawValue) {\n let value = toPosix(String(rawValue || '').trim());\n value = value.replace(/^\\/+/, '');\n value = value.replace(/\\.(md|mdx)$/i, '');\n value = value.replace(/\\/index$/i, '');\n value = value.replace(/\\/README$/i, '');\n value = value.replace(/\\/+$/, '');\n return value;\n}\n\nfunction loadI18nTargetLanguages(repoRoot) {\n const configPath = path.join(repoRoot, I18N_CONFIG_REL);\n if (!fs.existsSync(configPath)) return new Set();\n\n try {\n const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));\n const languages = Array.isArray(config?.targetLanguages) ? config.targetLanguages : [];\n return new Set(\n languages\n .map((language) => String(language || '').trim())\n .filter(Boolean)\n );\n } catch (_error) {\n return new Set();\n }\n}\n\nfunction getV2EnglishNavigationRouteKeys(docsJson) {\n const versions = Array.isArray(docsJson?.navigation?.versions) ? docsJson.navigation.versions : [];\n const v2VersionIndex = versions.findIndex((versionNode) => versionNode?.version === 'v2');\n if (v2VersionIndex === -1) return new Set();\n\n const languages = Array.isArray(versions[v2VersionIndex]?.languages) ? versions[v2VersionIndex].languages : [];\n const englishLanguageIndex = languages.findIndex((languageNode) => languageNode?.language === 'en');\n if (englishLanguageIndex === -1) return new Set();\n\n const pointer = `navigation.versions[${v2VersionIndex}].languages[${englishLanguageIndex}]`;\n const entries = collectPageEntries(languages[englishLanguageIndex], pointer);\n const routeKeys = new Set();\n\n entries.forEach(({ value }) => {\n const normalized = normalizeOrphanRouteKey(value);\n if (normalized.startsWith('v2/')) {\n routeKeys.add(normalized);\n }",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "runner",
+ "caller": "tests/run-all.js",
+ "pipeline": "P1"
+ },
+ {
+ "type": "runner",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "P3"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/translate-docs.yml",
+ "workflow": "Docs Translation Pipeline",
+ "pipeline": "P6"
+ },
+ {
+ "type": "script",
+ "caller": "tests/run-all.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:docs-nav"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:docs-nav:write"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tests/unit/tasks/reports/navigation-links/navigation-report.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tests/unit/tasks/reports/navigation-links/navigation-report.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tests/unit/tasks/reports/navigation-links/navigation-report.json, tests/unit/tasks/reports/navigation-links/navigation-report.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P1 via run-all; P3 via run-pr-checks; P6 (Docs Translation Pipeline); indirect via tests/run-all.js; indirect via tests/run-pr-checks.js; manual (npm script: test:docs-nav); manual (npm script: test:docs-nav:write)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P1"
+ },
+ {
+ "path": "tests/unit/script-docs.test.js",
+ "script": "script-docs-test",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": ".githooks, .github/scripts, tests, tools/scripts, tasks/scripts, docs-guide/indexes/scripts-index.mdx",
+ "owner": "docs",
+ "needs": "E-C1, R-R14",
+ "purpose_statement": "Enforces script header schema, keeps group script indexes in sync, and builds aggregate script index",
+ "pipeline_declared": "P1, P3",
+ "usage": "node tests/unit/script-docs.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script script-docs-test\n * @category validator\n * @purpose qa:repo-health\n * @scope .githooks, .github/scripts, tests, tools/scripts, tasks/scripts, docs-guide/indexes/scripts-index.mdx\n * @owner docs\n * @needs E-C1, R-R14\n * @purpose-statement Enforces script header schema, keeps group script indexes in sync, and builds aggregate script index\n * @pipeline P1, P3\n * @dualmode --check (validator) | --write --rebuild-indexes (generator)\n * @usage node tests/unit/script-docs.test.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst {\n buildGeneratedFrontmatterLines,\n buildGeneratedHiddenBannerLines,\n buildGeneratedNoteLines\n} = require('../../tools/lib/generated-file-banners');\nconst {\n AGGREGATE_INDEX_PATH,\n CLASSIFICATION_DATA_PATH,\n GOVERNED_ROOTS,\n GROUP_INDEX_MAP,\n INDEXED_ROOTS,\n LEGACY_AGGREGATE_INDEX_PATH,\n SCRIPT_EXTENSIONS: GOVERNED_SCRIPT_EXTENSIONS,\n isWithinRoots,\n normalizeRepoPath,\n shouldExcludeScriptPath\n} = require('../../tools/lib/script-governance-config');\n\nconst REPO_ROOT = path.resolve(__dirname, '../..');\nconst INDEX_START = '{/* SCRIPT-INDEX:START */}';\nconst INDEX_END = '{/* SCRIPT-INDEX:END */}';\n\nconst LEGACY_REQUIRED_TAGS = [\n '@script',\n '@summary',\n '@owner',\n '@scope',\n '@usage',\n '@inputs',\n '@outputs',\n '@exit-codes',\n '@examples',\n '@notes'\n];\n\nconst LEGACY_INLINE_REQUIRED_TAGS = ['@script', '@summary', '@owner', '@scope'];\nconst LEGACY_BLOCK_REQUIRED_TAGS = ['@usage', '@inputs', '@outputs', '@exit-codes', '@examples', '@notes'];\nconst FRAMEWORK_REQUIRED_TAGS = [\n '@script',\n '@category',\n '@purpose',\n '@scope',\n '@owner',\n '@needs',\n '@purpose-statement',\n '@pipeline',\n '@usage'\n];\nconst FRAMEWORK_INLINE_REQUIRED_TAGS = FRAMEWORK_REQUIRED_TAGS;\nconst PLACEHOLDER_PATTERNS = [\n /^<.*>$/,\n /^todo\\b/i,\n /^tbd\\b/i,\n /^fill\\b/i,\n /^replace$/i,\n /^replace me$/i,\n /^n\\/a$/i,\n /^none$/i,\n /^placeholder$/i\n];\n\nconst SCRIPT_EXTENSIONS = new Set(GOVERNED_SCRIPT_EXTENSIONS);\nconst VALIDATION_ROOTS = GOVERNED_ROOTS;\nconst CLASSIFICATION_ROOTS = GOVERNED_ROOTS;\nconst AGGREGATE_FRONTMATTER_LINES = buildGeneratedFrontmatterLines({\n title: 'Scripts Index',\n sidebarTitle: 'Scripts Index',\n description: 'This page provides an aggregate catalog inventory of repository scripts generated from group script indexes.',\n keywords: ['livepeer', 'scripts index', 'aggregate inventory', 'repository', 'scripts']\n});\nconst AGGREGATE_DETAILS = {\n script: 'tests/unit/script-docs.test.js',\n purpose: 'Enforce script header schema, keep group script indexes in sync, and build aggregate script index.',\n runWhen: 'Script metadata changes in validation roots or script changes in indexed roots.',\n runCommand: 'node tests/unit/script-docs.test.js --write --rebuild-indexes'\n};\n\nfunction readFileSafe(repoPath) {\n try {\n return fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8');\n } catch (_err) {\n return '';\n }\n}\n\nfunction escapeRegExp(value) {\n return value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\nfunction shouldExclude(repoPath) {\n const p = normalizeRepoPath(repoPath);\n return shouldExcludeScriptPath(p) || p.includes('/.venv/') || p.startsWith('.venv/') || p.includes('/tmp/') || p.startsWith('tmp/');\n}\n\nfunction isScriptFile(repoPath) {\n if (shouldExclude(repoPath)) return false;\n const ext = path.extname(repoPath).toLowerCase();\n if (SCRIPT_EXTENSIONS.has(ext)) return true;\n const content = readFileSafe(repoPath);\n return content.startsWith('#!/usr/bin/env') || content.startsWith('#!/bin/');\n}\n\nfunction walkFiles(dirPath, out = []) {\n const full = path.join(REPO_ROOT, dirPath);\n if (!fs.existsSync(full)) return out;\n\n const entries = fs.readdirSync(full, { withFileTypes: true });\n for (const entry of entries) {\n const rel = normalizeRepoPath(path.join(dirPath, entry.name));\n if (shouldExclude(rel)) continue;\n if (entry.isDirectory()) {\n walkFiles(rel, out);\n } else {\n out.push(rel);\n }\n }\n return out;\n}\n\nfunction getScriptsForRoots(roots) {\n const scripts = [];\n for (const root of roots) {\n walkFiles(root, scripts);\n }\n return [...new Set(scripts)].filter(isScriptFile).sort();\n}\n\nfunction getAllValidationScripts() {\n return getScriptsForRoots(VALIDATION_ROOTS);\n}\n\nfunction getAllIndexedScripts() {\n return getScriptsForRoots(INDEXED_ROOTS);\n}\n\nfunction getAllClassificationScripts() {\n return getScriptsForRoots(CLASSIFICATION_ROOTS);\n}\n\nfunction isManagedRootPath(repoPath) {\n return isWithinRoots(repoPath, CLASSIFICATION_ROOTS);\n}\n\nfunction fileExists(repoPath) {\n const fullPath = path.join(REPO_ROOT, repoPath);\n return fs.existsSync(fullPath) && fs.statSync(fullPath).isFile();\n}\n\nfunction loadClassificationData() {\n const fullPath = path.join(REPO_ROOT, CLASSIFICATION_DATA_PATH);\n const raw = fs.readFileSync(fullPath, 'utf8');\n const parsed = JSON.parse(raw);\n\n if (!Array.isArray(parsed)) {\n throw new Error('Classification data must be a JSON array.');\n }\n\n return parsed.map((row, index) => {\n if (!row || typeof row !== 'object' || Array.isArray(row)) {\n throw new Error(`classification[${index}] must be an object.`);\n }\n\n const repoPath = normalizeRepoPath(String(row.path || '').trim());\n if (!repoPath) {\n throw new Error(`classification[${index}].path is required.`);\n }\n\n return { ...row, path: repoPath };\n });\n}\n\nfunction validateClassificationCoverage(scopedScripts, classificationRows) {\n const errors = [];\n const liveScripts = [...new Set(scopedScripts.map(normalizeRepoPath))].sort();\n const managedRows = classificationRows\n .filter((row) => isManagedRootPath(row.path))\n .sort((a, b) => a.path.localeCompare(b.path));\n const classifiedPaths = new Set(managedRows.map((row) => row.path));\n\n for (const scriptPath of liveScripts) {\n if (!classifiedPaths.has(scriptPath)) {\n errors.push({\n file: CLASSIFICATION_DATA_PATH,\n rule: 'Script classification coverage',\n message: `Missing classification row for managed script: ${scriptPath}`,\n line: 1\n });\n }\n }\n\n for (const row of managedRows) {\n if (!fileExists(row.path)) {\n errors.push({\n file: CLASSIFICATION_DATA_PATH,\n rule: 'Script classification coverage',\n message: `Classification row points to a missing file: ${row.path}`,\n line: 1\n });\n }\n }\n\n for (const row of classificationRows) {\n if (row.path === 'tools/scripts/archive' || row.path.startsWith('tools/scripts/archive/')) {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "pre-commit",
+ "caller": ".githooks/pre-commit",
+ "pipeline": "P1"
+ },
+ {
+ "type": "runner",
+ "caller": "tests/run-all.js",
+ "pipeline": "P1"
+ },
+ {
+ "type": "runner",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "P3"
+ },
+ {
+ "type": "script",
+ "caller": "tests/run-all.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:scripts"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P1 (pre-commit); P1 via run-all; P3 via run-pr-checks; indirect via tests/run-all.js; indirect via tests/run-pr-checks.js; manual (npm script: test:scripts)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P1"
+ },
+ {
+ "path": "tools/scripts/validators/components/check-component-css.js",
+ "script": "check-component-css",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R10",
+ "purpose_statement": "Validates component files against component governance styling rules.",
+ "pipeline_declared": "P1, P2, P3",
+ "usage": "node tools/scripts/validators/components/check-component-css.js [--path snippets/components] [--staged] [--fix] [--help]",
+ "header": "#!/usr/bin/env node\n/**\n * @script check-component-css\n * @category validator\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R10\n * @purpose-statement Validates component files against component governance styling rules.\n * @pipeline P1, P2, P3\n * @usage node tools/scripts/validators/components/check-component-css.js [--path snippets/components] [--staged] [--fix] [--help]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\nconst {\n getComponentFiles,\n scanStylingViolations,\n isArchivePath\n} = require('../../../lib/component-governance-utils');\n\nconst DEFAULT_TARGET = 'snippets/components';\nconst FIX_REPLACEMENTS = [\n [/ !important/g, ''],\n [/#fff\\b/gi, 'var(--lp-color-on-accent)'],\n [/#3b82f6\\b/gi, 'var(--lp-color-link)'],\n [/#5965f3\\b/gi, 'var(--lp-color-brand-discord)'],\n [/#5865f2\\b/gi, 'var(--lp-color-brand-discord)'],\n [/#00aeef\\b/gi, 'var(--lp-color-brand-forum)'],\n [/#ef1a73\\b/gi, 'var(--lp-color-brand-coming-soon)'],\n [/#b636dd\\b/gi, 'var(--lp-color-brand-preview)'],\n [/rgba?\\(\\s*0\\s*,\\s*0\\s*,\\s*0\\s*,\\s*0\\.5\\s*\\)/gi, 'var(--lp-color-bg-overlay)'],\n [/rgba?\\(\\s*255\\s*,\\s*255\\s*,\\s*255\\s*,\\s*0\\.5\\s*\\)/gi, 'var(--lp-color-border-inverse)'],\n [/rgba?\\(\\s*255\\s*,\\s*255\\s*,\\s*255\\s*,\\s*0\\.4\\s*\\)/gi, 'var(--lp-color-text-muted)'],\n [/rgba?\\(\\s*255\\s*,\\s*255\\s*,\\s*255\\s*,\\s*0\\.1\\s*\\)/gi, 'var(--lp-color-bg-subtle)']\n];\n\nfunction usage() {\n console.log(\n [\n 'Usage: node tools/scripts/validators/components/check-component-css.js [options]',\n '',\n 'Options:',\n ` --path $1
\");\n cleanHTML = cleanHTML.replace(/$1
\");\n cleanHTML = cleanHTML.replace(/$1
\");\n cleanHTML = cleanHTML.replace(/$1
\");\n\n // Clean up images and their references\n cleanHTML = cleanHTML.replace(//g, \"
\");\n cleanHTML = cleanHTML.replace(/<\\/p>/g, \"
\");\n cleanHTML = cleanHTML.replace(/- /g, \"
- /g, \"
- \");\n cleanHTML = cleanHTML.replace(/<\\/li>/g, \" \");\n cleanHTML = cleanHTML.replace(\n /(.*?)<\\/strong>/g,\n \"$1\"\n );\n cleanHTML = cleanHTML.replace(/(.*?)<\\/em>/g, \"$1\");\n cleanHTML = cleanHTML.replace(/
- /i, xml, xml)\n\n const title = decodeEntities(\n firstMatch(/
([\\s\\S]*?)<\\/title>/i, channelBlock, 'RSS Feed')\n )\n const description = stripHtml(\n firstMatch(/<description>([\\s\\S]*?)<\\/description>/i, channelBlock, '')\n )\n const feedLink =\n firstMatch(/<atom:link[^>]*href=\"([^\"]+)\"/i, channelBlock, '') ||\n firstMatch(/<link>([\\s\\S]*?)<\\/link>/i, channelBlock, '')\n const author = decodeEntities(\n firstMatch(/<author>([\\s\\S]*?)<\\/author>/i, channelBlock, '') ||\n firstMatch(\n /<itunes:author>([\\s\\S]*?)<\\/itunes:author>/i,\n channelBlock,\n ''\n )\n )\n const language = decodeEntities(\n firstMatch(/<language>([\\s\\S]*?)<\\/language>/i, channelBlock, '')\n )\n const lastBuildDate = firstMatch(\n /<lastBuildDate>([\\s\\S]*?)<\\/lastBuildDate>/i,\n channelBlock,\n ''\n )\n\n const itemBlocks = [...xml.matchAll(/<item>([\\s\\S]*?)<\\/item>/gi)].map(\n (m) => m[1]\n )\n\n const episodes = itemBlocks.map((block, index) => {\n const episodeTitle = decodeEntities(\n firstMatch(/<title>([\\s\\S]*?)<\\/title>/i, block, `Episode ${index + 1}`)\n ).trim()\n\n return {\n title: episodeTitle,\n pubDate: firstMatch(/<pubDate>([\\s\\S]*?)<\\/pubDate>/i, block, ''),\n duration: firstMatch(\n /<itunes:duration>([\\s\\S]*?)<\\/itunes:duration>/i,\n block,\n ''\n ),\n explicit: firstMatch(\n /<itunes:explicit>([\\s\\S]*?)<\\/itunes:explicit>/i,\n block,\n ''\n ),\n link: firstMatch(/<link>([\\s\\S]*?)<\\/link>/i, block, ''),\n audioUrl: firstMatch(/<enclosure[^>]*url=\"([^\"]+)\"/i, block, ''),\n summary: stripHtml(\n firstMatch(/<description>([\\s\\S]*?)<\\/description>/i, block, '') ||\n firstMatch(/<itunes:summary>([\\s\\S]*?)<\\/itunes:summary>/i, block, '')\n ),\n }\n })\n\n return {\n title,\n description,\n feedLink,\n author,\n language,\n lastBuildDate,\n episodes,\n }\n}\n\nfunction buildMdx(feed) {\n const lines = []\n\n lines.push('---')\n lines.push(`title: '${escapeYamlSingleQuoted(feed.title)}'`)\n lines.push(\"sidebarTitle: 'RSS Feed'\")\n lines.push(\n `description: '${escapeYamlSingleQuoted(feed.description || 'Converted from RSS to MDX')}'`\n )\n lines.push(\"keywords: ['rss', 'podcast', 'transcript', 'feed']\")\n lines.push('---')\n lines.push('')\n\n lines.push(`# ${feed.title}`)\n lines.push('')\n\n if (feed.description) {\n lines.push(feed.description)\n lines.push('')\n }\n\n if (feed.feedLink) lines.push(`- Feed URL: ${feed.feedLink}`)\n if (feed.author) lines.push(`- Author: ${feed.author}`)\n if (feed.language) lines.push(`- Language: ${feed.language}`)\n if (feed.lastBuildDate) lines.push(`- Last build date: ${feed.lastBuildDate}`)\n lines.push(`- Episode count: ${feed.episodes.length}`)\n lines.push('')\n lines.push('## Episodes')\n lines.push('')\n\n feed.episodes.forEach((episode) => {\n lines.push(`### ${episode.title}`)\n lines.push('')\n if (episode.pubDate) lines.push(`- Published: ${episode.pubDate}`)\n if (episode.duration) lines.push(`- Duration: ${episode.duration}`)\n if (episode.explicit) lines.push(`- Explicit: ${episode.explicit}`)\n if (episode.link) lines.push(`- Episode link: ${episode.link}`)\n if (episode.audioUrl) lines.push(`- Audio: ${episode.audioUrl}`)\n lines.push('')\n if (episode.summary) {\n lines.push(episode.summary)\n lines.push('')\n }\n })\n\n return `${lines.join('\\n')}\\n`\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2))\n\n if (args.help || !args.input || !args.output) {\n console.log(\n 'Usage: node tools/scripts/convert-rss-to-mdx.js --input <rssPath> --output <mdxPath>'\n )\n process.exit(args.help ? 0 : 1)\n }\n\n const inputPath = toAbsolutePath(args.input)\n const outputPath = toAbsolutePath(args.output)\n\n if (!fs.existsSync(inputPath)) {\n throw new Error(`Input file not found: ${inputPath}`)\n }\n\n const xml = fs.readFileSync(inputPath, 'utf8')\n const feed = parseRss(xml)\n const mdx = buildMdx(feed)\n\n fs.mkdirSync(path.dirname(outputPath), { recursive: true })\n fs.writeFileSync(outputPath, mdx, 'utf8')\n\n console.log(`✓ Converted RSS to MDX`)\n console.log(` Input: ${inputPath}`)\n console.log(` Output: ${outputPath}`)\n console.log(` Episodes: ${feed.episodes.length}`)\n}\n\ntry {\n main()", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "manual", + "caller": "none", + "pipeline": "manual" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "manual (none)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "Manual" + }, + { + "path": "tools/scripts/snippets/fetch-lpt-exchanges.sh", + "script": "fetch-lpt-exchanges", + "category": "automation", + "purpose": "infrastructure:data-feeds", + "scope": "tools/scripts", + "owner": "docs", + "needs": "F-R1", + "purpose_statement": "LPT exchange data fetcher — pulls exchange listing data for LPT token pages", + "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines", + "usage": "bash tools/scripts/snippets/fetch-lpt-exchanges.sh [flags]", + "header": "#!/bin/bash\n# @script fetch-lpt-exchanges\n# @category automation\n# @purpose infrastructure:data-feeds\n# @scope tools/scripts\n# @owner docs\n# @needs F-R1\n# @purpose-statement LPT exchange data fetcher — pulls exchange listing data for LPT token pages\n# @pipeline manual — interactive developer tool, not suited for automated pipelines\n# @usage bash tools/scripts/snippets/fetch-lpt-exchanges.sh [flags]\n# Fetch LPT exchange listings from CoinGecko API and append to lpt-exchanges.mdx\n# Usage: ./tools/scripts/snippets/fetch-lpt-exchanges.sh\n\nset -e\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nCONFIG_FILE=\"$SCRIPT_DIR/paths.config.json\"\n\n# Try to detect repo root via git, fallback to config file\nif git rev-parse --show-toplevel &>/dev/null; then\n REPO_ROOT=\"$(git rev-parse --show-toplevel)\"\nelif [ -f \"$CONFIG_FILE\" ]; then\n echo \"Warning: Not in a git repo, using paths.config.json\"\n REPO_ROOT=\"$(dirname \"$(dirname \"$SCRIPT_DIR\")\")\"\nelse\n echo \"Error: Cannot determine repo root. Run from git repo or ensure paths.config.json exists.\"\n exit 1\nfi\n\n# Read path from config or use default\nif [ -f \"$CONFIG_FILE\" ] && command -v node &>/dev/null; then\n OUTPUT_FILE=\"$REPO_ROOT/$(node -pe \"require('$CONFIG_FILE').paths.lptExchanges\")\"\nelse\n if [ -f \"$REPO_ROOT/v2/lpt/resources/exchanges.mdx\" ]; then\n OUTPUT_FILE=\"$REPO_ROOT/v2/lpt/resources/exchanges.mdx\"\n else\n OUTPUT_FILE=\"$REPO_ROOT/v2/lpt/resources/exchanges.mdx\"\n fi\nfi\n\n# Fetch data from CoinGecko\necho \"Fetching LPT exchange data from CoinGecko...\"\nAPI_RESPONSE=$(curl -s \"https://api.coingecko.com/api/v3/coins/livepeer\")\n\nif [ -z \"$API_RESPONSE\" ]; then\n echo \"Error: Failed to fetch data from CoinGecko API\"\n exit 1\nfi\n\n# Generate the exchange content using Node.js\nnode - \"$API_RESPONSE\" \"$OUTPUT_FILE\" << 'NODEJS_SCRIPT'\nconst fs = require('fs');\nconst path = require('path');\n\nconst apiResponse = process.argv[2];\nconst outputFile = process.argv[3];\n\nconst data = JSON.parse(apiResponse);\nconst tickers = data.tickers || [];\n\n// Group by exchange and deduplicate\nconst exchangeMap = new Map();\n\nfor (const ticker of tickers) {\n const exchangeName = ticker.market?.name;\n const exchangeId = ticker.market?.identifier;\n const tradeUrl = ticker.trade_url;\n const trustScore = ticker.trust_score;\n const isStale = ticker.is_stale;\n const target = ticker.target;\n const volume = ticker.converted_volume?.usd || 0;\n \n if (!exchangeName || isStale) continue;\n \n if (!exchangeMap.has(exchangeId)) {\n exchangeMap.set(exchangeId, {\n name: exchangeName,\n url: tradeUrl,\n trustScore: trustScore,\n pairs: [],\n totalVolume: 0\n });\n }\n \n const exchange = exchangeMap.get(exchangeId);\n if (!exchange.pairs.includes(target)) {\n exchange.pairs.push(target);\n }\n exchange.totalVolume += volume;\n \n // Keep the best trust score\n if (trustScore === 'green' || (trustScore === 'yellow' && exchange.trustScore !== 'green')) {\n exchange.trustScore = trustScore;\n exchange.url = tradeUrl;\n }\n}\n\n// Sort by volume (highest first)\nconst sortedExchanges = Array.from(exchangeMap.values())\n .filter(e => e.totalVolume > 0)\n .sort((a, b) => b.totalVolume - a.totalVolume);\n\n// Get trust score badge\nfunction getTrustBadge(score) {\n if (score === 'green') return '🟢';\n if (score === 'yellow') return '🟡';\n if (score === 'red') return '🔴';\n return '⚪';\n}\n\n// Generate MDX content\nconst lastUpdated = new Date().toISOString().split('T')[0];\n\nlet content = `\n\n---\n\n## Centralized Exchanges (CEX)\n\n<Info>\n **Last Updated:** ${lastUpdated} | Data sourced from [CoinGecko](https://www.coingecko.com/en/coins/livepeer)\n</Info>\n\n<Note>\n **Trust Score Legend:** 🟢 High | 🟡 Medium | 🔴 Low | ⚪ Unknown\n</Note>\n\n<div style={{ overflowX: 'auto', marginBottom: '24px' }}>\n<table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '0.9rem' }}>\n <thead>\n <tr style={{ backgroundColor: '#2d9a67', color: '#fff' }}>\n <th style={{ padding: '12px 16px', textAlign: 'left', fontWeight: '600' }}>Exchange</th>\n <th style={{ padding: '12px 16px', textAlign: 'left', fontWeight: '600' }}>Trading Pairs</th>\n <th style={{ padding: '12px 16px', textAlign: 'right', fontWeight: '600' }}>24h Volume (USD)</th>\n <th style={{ padding: '12px 16px', textAlign: 'center', fontWeight: '600' }}>Trust</th>\n </tr>\n </thead>\n <tbody>\n`;\n\nsortedExchanges.forEach((exchange, index) => {\n const bgColor = index % 2 === 0 ? '#1a1a1a' : 'transparent';\n const volumeFormatted = exchange.totalVolume >= 1000000 \n ? `$${(exchange.totalVolume / 1000000).toFixed(2)}M`\n : exchange.totalVolume >= 1000 \n ? `$${(exchange.totalVolume / 1000).toFixed(2)}K`\n : `$${exchange.totalVolume.toFixed(2)}`;\n \n const pairsDisplay = exchange.pairs.slice(0, 5).join(', ') + (exchange.pairs.length > 5 ? '...' : '');\n const trustBadge = getTrustBadge(exchange.trustScore);\n \n content += ` <tr style={{ borderBottom: '1px solid #333', backgroundColor: '${bgColor}' }}>\n <td style={{ padding: '10px 16px' }}><a href=\"${exchange.url || '#'}\" target=\"_blank\" style={{ color: '#2d9a67', fontWeight: '500' }}>${exchange.name}</a></td>\n <td style={{ padding: '10px 16px', fontFamily: 'monospace', fontSize: '0.85rem' }}>${pairsDisplay}</td>\n <td style={{ padding: '10px 16px', textAlign: 'right' }}>${volumeFormatted}</td>\n <td style={{ padding: '10px 16px', textAlign: 'center' }}>${trustBadge}</td>\n </tr>\n`;\n});\n\ncontent += ` </tbody>\n</table>\n</div>\n\n<Tip>\n Trading volumes are approximate 24-hour figures. Always verify current data on the exchange.\n</Tip>\n\n## Decentralized Exchanges (DEX)\n\n<CardGroup cols={2}>\n <Card title=\"Uniswap V3\" icon=\"unicorn\" href=\"https://app.uniswap.org/explore/tokens/ethereum/0x58b6a8a3302369daec383334672404ee733ab239\" horizontal arrow>\n Trade LPT on Ethereum mainnet\n </Card>\n <Card title=\"Uniswap V2\" icon=\"unicorn\" href=\"https://app.uniswap.org/explore/tokens/ethereum/0x58b6a8a3302369daec383334672404ee733ab239\" horizontal arrow>\n Legacy Uniswap pool on Ethereum\n </Card>\n</CardGroup>\n\n## Contract Addresses\n\n<div style={{ overflowX: 'auto', marginBottom: '24px' }}>\n<table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '0.9rem' }}>\n <thead>\n <tr style={{ backgroundColor: '#2d9a67', color: '#fff' }}>\n <th style={{ padding: '12px 16px', textAlign: 'left', fontWeight: '600' }}>Network</th>\n <th style={{ padding: '12px 16px', textAlign: 'left', fontWeight: '600' }}>Contract Address</th>\n </tr>\n </thead>\n <tbody>\n <tr style={{ borderBottom: '1px solid #333', backgroundColor: '#1a1a1a' }}>\n <td style={{ padding: '10px 16px', color: '#2d9a67', fontWeight: '500' }}>Ethereum</td>\n <td style={{ padding: '10px 16px', fontFamily: 'monospace', fontSize: '0.85rem' }}><code>0x58b6a8a3302369daec383334672404ee733ab239</code></td>\n </tr>\n <tr style={{ borderBottom: '1px solid #333', backgroundColor: 'transparent' }}>\n <td style={{ padding: '10px 16px', color: '#2d9a67', fontWeight: '500' }}>Arbitrum One</td>\n <td style={{ padding: '10px 16px', fontFamily: 'monospace', fontSize: '0.85rem' }}><code>0x289ba1701c2f088cf0faf8b3705246331cb8a839</code></td>\n </tr>\n </tbody>\n</table>\n</div>\n`;\n\n// Read existing file and find where to append (after the Danger block)\nconst existingContent = fs.readFileSync(outputFile, 'utf8');\nconst dangerEndIndex = existingContent.indexOf('</Danger>');\n\nif (dangerEndIndex === -1) {\n console.error('Could not find </Danger> tag in the file');\n process.exit(1);\n}\n\n// Get content up to and including </Danger>\nconst headerContent = existingContent.substring(0, dangerEndIndex + '</Danger>'.length);\n\n// Write the new file\nfs.writeFileSync(outputFile, headerContent + content);\n\nconsole.log(`✅ Updated ${outputFile} with ${sortedExchanges.length} exchanges`);\nNODEJS_SCRIPT", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "manual", + "caller": "none", + "pipeline": "manual" + } + ], + "outputs": [ + { + "output_path": "stdout", + "type": "stdout", + "call": "console" + } + ], + "outputs_display": "stdout only", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "manual (none)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "Manual" + }, + { + "path": "tools/scripts/snippets/update-component-library.sh", + "script": "update-component-library", + "category": "automation", + "purpose": "infrastructure:data-feeds", + "scope": "tools/scripts", + "owner": "docs", + "needs": "F-R1", + "purpose_statement": "Component library updater — syncs component library documentation from source", + "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines", + "usage": "bash tools/scripts/snippets/update-component-library.sh [flags]", + "header": "#!/bin/bash\n# @script update-component-library\n# @category automation\n# @purpose infrastructure:data-feeds\n# @scope tools/scripts\n# @owner docs\n# @needs F-R1\n# @purpose-statement Component library updater — syncs component library documentation from source\n# @pipeline manual — interactive developer tool, not suited for automated pipelines\n# @usage bash tools/scripts/snippets/update-component-library.sh [flags]\n# Auto-updates snippets/snippetsWiki/componentLibrary/index.mdx\n# Run this script after changes to snippets/components/\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nCONFIG_FILE=\"$SCRIPT_DIR/paths.config.json\"\n\n# Try to detect repo root via git, fallback to config file\nif git rev-parse --show-toplevel &>/dev/null; then\n REPO_ROOT=\"$(git rev-parse --show-toplevel)\"\nelif [ -f \"$CONFIG_FILE\" ]; then\n echo \"Warning: Not in a git repo, using paths.config.json\"\n REPO_ROOT=\"$(dirname \"$(dirname \"$SCRIPT_DIR\")\")\"\nelse\n echo \"Error: Cannot determine repo root. Run from git repo or ensure paths.config.json exists.\"\n exit 1\nfi\n\n# Read paths from config or use defaults\nif [ -f \"$CONFIG_FILE\" ] && command -v node &>/dev/null; then\n COMPONENTS_DIR=\"$REPO_ROOT/$(node -pe \"require('$CONFIG_FILE').paths.snippetsComponents\")\"\n OUTPUT_FILE=\"$REPO_ROOT/$(node -pe \"require('$CONFIG_FILE').paths.snippetsWikiComponentLibrary\")\"\nelse\n COMPONENTS_DIR=\"$REPO_ROOT/snippets/components\"\n OUTPUT_FILE=\"$REPO_ROOT/snippets/snippetsWiki/componentLibrary/index.mdx\"\nfi\n\n# Generate tree structure from the live component directory instead of hardcoded folders.\nget_top_level_dirs() {\n find \"$COMPONENTS_DIR\" -mindepth 1 -maxdepth 1 -type d \\\n ! -name \"_archive\" \\\n ! -name \"examples\" \\\n -print | sort\n}\n\nget_child_dirs() {\n local dir=\"$1\"\n find \"$dir\" -mindepth 1 -maxdepth 1 -type d \\\n ! -name \"_archive\" \\\n ! -name \"examples\" \\\n -print | sort\n}\n\nget_component_files() {\n local dir=\"$1\"\n find \"$dir\" -mindepth 1 -maxdepth 1 -type f \\( \\\n -name \"*.jsx\" -o -name \"*.tsx\" -o -name \"*.js\" \\\n \\) -print | sort\n}\n\nrender_folder() {\n local dir=\"$1\"\n local indent=\"$2\"\n local name\n name=\"$(basename \"$dir\")\"\n\n echo \"${indent}<Tree.Folder name=\\\"$name\\\">\"\n\n while IFS= read -r file; do\n [ -n \"$file\" ] || continue\n echo \"${indent} <Tree.File name=\\\"$(basename \"$file\")\\\" />\"\n done < <(get_component_files \"$dir\")\n\n while IFS= read -r child_dir; do\n [ -n \"$child_dir\" ] || continue\n render_folder \"$child_dir\" \"${indent} \"\n done < <(get_child_dirs \"$dir\")\n\n echo \"${indent}</Tree.Folder>\"\n}\n\n# Build the new content\nbuild_content() {\n cat << 'HEADER'\n---\ntitle: Component Library\ndescription: Library of custom components used in Livepeer documentation\nsidebarTitle: Component Library\n---\n\n{/* AUTO-GENERATED: Do not edit below this line. Run tools/scripts/snippets/update-component-library.sh to update. */}\n\n## Components Structure\n\nBelow is the current list of components found under `snippets/components/`.\n\n<Tree>\n <Tree.Folder name=\"components\" defaultOpen>\nHEADER\n\n while IFS= read -r dir; do\n [ -n \"$dir\" ] || continue\n render_folder \"$dir\" \" \"\n done < <(get_top_level_dirs)\n\n cat << 'FOOTER'\n </Tree.Folder>\n</Tree>\n\n{/* END AUTO-GENERATED */}\n\n---\n\n## Component Examples\n\n{/* Add component examples below */}\n\nFOOTER\n}\n\n# Run and save\nbuild_content > \"$OUTPUT_FILE\"\necho \"Updated $OUTPUT_FILE\"\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "manual", + "caller": "none", + "pipeline": "manual" + } + ], + "outputs": [], + "outputs_display": "none detected", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "manual (none)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "Manual" + }, + { + "path": ".githooks/pre-commit-no-deletions", + "script": "pre-commit-no-deletions", + "category": "orchestrator", + "purpose": "infrastructure:pipeline-orchestration", + "scope": ".githooks", + "owner": "docs", + "needs": "R-R29", + "purpose_statement": "Variant pre-commit hook that blocks file deletions (safety net for content preservation)", + "pipeline_declared": "manual — not yet in pipeline", + "usage": "bash .githooks/pre-commit-no-deletions [flags]", + "header": "#!/bin/bash\n# @script pre-commit-no-deletions\n# @category orchestrator\n# @purpose infrastructure:pipeline-orchestration\n# @scope .githooks\n# @owner docs\n# @needs R-R29\n# @purpose-statement Variant pre-commit hook that blocks file deletions (safety net for content preservation)\n# @pipeline manual — not yet in pipeline\n# @usage bash .githooks/pre-commit-no-deletions [flags]\n# Pre-commit hook: PREVENT DELETIONS\n# This hook blocks any file deletions to prevent accidental data loss\n\n# Get list of deleted files\nDELETED_FILES=$(git diff --cached --name-only --diff-filter=D)\nBLOCKED_DELETED_FILES=$(echo \"$DELETED_FILES\" | grep -Ev '^snippets/data/[^/]+/hrefs\\.jsx$' || true)\nALLOWED_GENERATED_DELETIONS=$(echo \"$DELETED_FILES\" | grep -E '^snippets/data/[^/]+/hrefs\\.jsx$' || true)\n\nif [ ! -z \"$ALLOWED_GENERATED_DELETIONS\" ]; then\n echo \"\"\n echo \"ℹ️ Allowing generated domain link map deletions:\"\n echo \"$ALLOWED_GENERATED_DELETIONS\" | sed 's/^/ ↺ /'\nfi\n\nif [ ! -z \"$BLOCKED_DELETED_FILES\" ]; then\n echo \"\"\n echo \"╔═══════════════════════════════════════════════════════════════╗\"\n echo \"║ ❌ FILE DELETIONS DETECTED - COMMIT BLOCKED ║\"\n echo \"╚═══════════════════════════════════════════════════════════════╝\"\n echo \"\"\n echo \"🚫 DELETIONS ARE NOT ALLOWED\"\n echo \"\"\n echo \"The following files are being deleted:\"\n echo \"$BLOCKED_DELETED_FILES\" | sed 's/^/ ❌ /'\n echo \"\"\n echo \"📋 INSTRUCTIONS:\"\n echo \" 1. If you need to move files, use 'git mv' instead of delete+add\"\n echo \" 2. If files should be removed, use 'git rm --cached' to unstage\"\n echo \" 3. If this is intentional, use: git commit --no-verify\"\n echo \" (But this should be VERY rare - deletions are dangerous!)\"\n echo \"\"\n echo \"⚠️ If you really need to delete files, you must:\"\n echo \" 1. Document WHY in the commit message\"\n echo \" 2. Verify files are backed up\"\n echo \" 3. Use: git commit --no-verify\"\n echo \"\"\n exit 1\nfi\n\nexit 0\n", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "manual", + "caller": "none", + "pipeline": "manual" + } + ], + "outputs": [], + "outputs_display": "none detected", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "manual (none)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "Manual" + }, + { + "path": "tools/scripts/repo-audit-orchestrator.js", + "script": "repo-audit-orchestrator", + "category": "orchestrator", + "purpose": "infrastructure:pipeline-orchestration", + "scope": "tools/scripts, ai-tools/ai-skills/catalog, tasks/reports/repo-ops", + "owner": "docs", + "needs": "R-R29", + "purpose_statement": "Repo audit orchestrator — dispatches all static analysis validators in sequence. Supports --mode (static/full), --scope (full/changed), --quarantine, --agent-pack.", + "pipeline_declared": "manual", + "usage": "node tools/scripts/repo-audit-orchestrator.js [flags]", + "header": "#!/usr/bin/env node\n/**\n * @script repo-audit-orchestrator\n * @category orchestrator\n * @purpose infrastructure:pipeline-orchestration\n * @scope tools/scripts, ai-tools/ai-skills/catalog, tasks/reports/repo-ops\n * @owner docs\n * @needs R-R29\n * @purpose-statement Repo audit orchestrator — dispatches all static analysis validators in sequence. Supports --mode (static/full), --scope (full/changed), --quarantine, --agent-pack.\n * @pipeline manual\n * @usage node tools/scripts/repo-audit-orchestrator.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst STAGE_ID = 'repo-audit-orchestrator';\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_OUTPUT_DIR = 'tasks/reports/repo-ops';\nconst DEFAULT_CATALOG_PATH = 'ai-tools/ai-skills/catalog/skill-catalog.json';\nconst DEFAULT_MANIFEST_PATH = 'ai-tools/ai-skills/catalog/execution-manifest.json';\n\nconst VALID_MODES = new Set(['static', 'runtime', 'full']);\nconst VALID_SCOPES = new Set(['changed', 'full']);\nconst VALID_AGENT_PACKS = new Set(['codex', 'cursor', 'claude', 'windsurf', 'all', 'none']);\n\nconst SCORE_BUCKET_WEIGHTS = {\n critical: 12,\n high: 6,\n medium: 3,\n low: 1,\n info: 0\n};\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction parseArgs(argv) {\n const out = {\n mode: 'static',\n scope: 'full',\n outputDir: DEFAULT_OUTPUT_DIR,\n quarantine: false,\n agentPack: 'none',\n catalogPath: DEFAULT_CATALOG_PATH,\n manifestPath: DEFAULT_MANIFEST_PATH\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--mode') {\n out.mode = String(argv[i + 1] || out.mode).trim() || out.mode;\n i += 1;\n continue;\n }\n if (token.startsWith('--mode=')) {\n out.mode = token.slice('--mode='.length).trim() || out.mode;\n continue;\n }\n if (token === '--scope') {\n out.scope = String(argv[i + 1] || out.scope).trim() || out.scope;\n i += 1;\n continue;\n }\n if (token.startsWith('--scope=')) {\n out.scope = token.slice('--scope='.length).trim() || out.scope;\n continue;\n }\n if (token === '--output-dir') {\n out.outputDir = String(argv[i + 1] || out.outputDir).trim() || out.outputDir;\n i += 1;\n continue;\n }\n if (token.startsWith('--output-dir=')) {\n out.outputDir = token.slice('--output-dir='.length).trim() || out.outputDir;\n continue;\n }\n if (token === '--quarantine') {\n out.quarantine = true;\n continue;\n }\n if (token === '--agent-pack') {\n out.agentPack = String(argv[i + 1] || out.agentPack).trim() || out.agentPack;\n i += 1;\n continue;\n }\n if (token.startsWith('--agent-pack=')) {\n out.agentPack = token.slice('--agent-pack='.length).trim() || out.agentPack;\n continue;\n }\n if (token === '--catalog') {\n out.catalogPath = String(argv[i + 1] || out.catalogPath).trim() || out.catalogPath;\n i += 1;\n continue;\n }\n if (token.startsWith('--catalog=')) {\n out.catalogPath = token.slice('--catalog='.length).trim() || out.catalogPath;\n continue;\n }\n if (token === '--manifest') {\n out.manifestPath = String(argv[i + 1] || out.manifestPath).trim() || out.manifestPath;\n i += 1;\n continue;\n }\n if (token.startsWith('--manifest=')) {\n out.manifestPath = token.slice('--manifest='.length).trim() || out.manifestPath;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!VALID_MODES.has(out.mode)) {\n throw new Error(`Invalid --mode: ${out.mode}`);\n }\n if (!VALID_SCOPES.has(out.scope)) {\n throw new Error(`Invalid --scope: ${out.scope}`);\n }\n if (!VALID_AGENT_PACKS.has(out.agentPack)) {\n throw new Error(`Invalid --agent-pack: ${out.agentPack}`);\n }\n\n return out;\n}\n\nfunction readJson(repoPath) {\n return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8'));\n}\n\nfunction severitySortValue(severity) {\n switch (severity) {\n case 'critical':\n return 0;\n case 'high':\n return 1;\n case 'medium':\n return 2;\n case 'low':\n return 3;\n default:\n return 4;\n }\n}\n\nfunction computeSummary(issues) {\n const summary = {\n critical: 0,\n high: 0,\n medium: 0,\n low: 0,\n info: 0,\n total: issues.length\n };\n\n issues.forEach((issue) => {\n if (Object.prototype.hasOwnProperty.call(summary, issue.severity)) {\n summary[issue.severity] += 1;\n }\n });\n\n return summary;\n}\n\nfunction runCommand(label, command, args, cwd) {\n const result = spawnSync(command, args, {\n cwd,\n encoding: 'utf8'\n });\n\n return {\n label,\n command: [command, ...args].join(' '),\n status: Number(result.status || 0),\n stdout: result.stdout || '',\n stderr: result.stderr || '',\n ok: Number(result.status || 0) === 0\n };\n}\n\nfunction stageReportPath(stageId, outputDirAbs) {\n if (stageId === 'cleanup-quarantine-manager') {\n return path.join(outputDirAbs, 'cleanup-quarantine-manifest.json');\n }\n\n if (stageId === 'cross-agent-packager') {\n return '';\n }\n\n return path.join(outputDirAbs, `${stageId}.json`);\n}\n\nfunction buildStageCommands(stageId, options) {\n const outputDirRel = toPosix(path.relative(REPO_ROOT, options.outputDirAbs));\n\n if (stageId === 'cleanup-quarantine-manager') {\n const commands = [\n {\n label: `${stageId}:classify`,\n command: 'node',\n args: ['tools/scripts/cleanup-quarantine-manager.js', '--output-dir', outputDirRel]\n }\n ];\n\n if (options.quarantine) {\n commands.push({\n label: `${stageId}:apply`,\n command: 'node',\n args: ['tools/scripts/cleanup-quarantine-manager.js', '--output-dir', outputDirRel, '--apply']\n });\n }\n\n return commands;\n }", + "header_field_count": 8, + "has_any_header": true, + "has_framework_header": true, + "category_valid": true, + "purpose_valid": true, + "scope_valid": false, + "triggers": [ + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "audit:repo" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "audit:repo:changed" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "audit:repo:full" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "audit:repo:quarantine" + }, + { + "type": "npm-script", + "caller": "tools/package.json", + "pipeline": "manual", + "script_name": "audit:repo:pack-all" + } + ], + "outputs": [ + { + "output_path": "tools/scripts/repo-audit-summary.json", + "type": "generated-output", + "call": "writeFileSync" + }, + { + "output_path": "tools/scripts/repo-audit-summary.md", + "type": "generated-output", + "call": "writeFileSync" + } + ], + "outputs_display": "tools/scripts/repo-audit-summary.json, tools/scripts/repo-audit-summary.md", + "downstream_consumers": [], + "downstream_display": "No", + "in_json": true, + "category_match": true, + "purpose_match": true, + "pipeline_verified": "MATCH", + "declared_pipeline_set": {}, + "actual_pipeline_set": {}, + "pipeline_actual": "manual (npm script: audit:repo); manual (npm script: audit:repo:changed); manual (npm script: audit:repo:full); manual (npm script: audit:repo:quarantine); manual (npm script: audit:repo:pack-all)", + "grade": "C", + "flags": [ + "invalid-scope" + ], + "trigger_group": "Manual" + }, + { + "path": "tests/integration/v2-wcag-audit.selftest.js", + "script": "v2-wcag-audit.selftest", + "category": "validator", + "purpose": "qa:content-quality", + "scope": "tests/integration, v2, git index", + "owner": "docs", + "needs": "E-R1, R-R11", + "purpose_statement": "Self-test suite for v2-wcag-audit.js — validates WCAG audit logic against known fixtures", + "pipeline_declared": "manual — not yet in pipeline", + "usage": "node tests/integration/v2-wcag-audit.selftest.js [flags]", + "header": "#!/usr/bin/env node\n/**\n * @script v2-wcag-audit.selftest\n * @category validator\n * @purpose qa:content-quality\n * @scope tests/integration, v2, git index\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Self-test suite for v2-wcag-audit.js — validates WCAG audit logic against known fixtures\n * @pipeline manual — not yet in pipeline\n * @usage node tests/integration/v2-wcag-audit.selftest.js [flags]\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst http = require('http');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\nconst puppeteer = require('puppeteer');\nconst wcag = require('./v2-wcag-audit');\n\nfunction getRepoRoot() {\n return process.cwd();\n}\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nasync function withHttpFixture(html, fn) {\n const server = http.createServer((req, res) => {\n res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });\n res.end(html);\n });\n\n await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));\n const addr = server.address();\n const url = `http://127.0.0.1:${addr.port}`;\n\n try {\n return await fn(url);\n } finally {\n await new Promise((resolve) => server.close(resolve));\n }\n}\n\nfunction runGit(args) {\n const cmd = spawnSync('git', args, { cwd: getRepoRoot(), encoding: 'utf8' });\n return {\n status: cmd.status,\n stdout: (cmd.stdout || '').trim(),\n stderr: (cmd.stderr || '').trim()\n };\n}\n\nasync function testBrowserAxeFixture() {\n const html = `<!doctype html>\n<html>\n <head>\n <meta charset=\"utf-8\" />\n <title>WCAG Fixture \n \n \n\n \n \n\n 🔗\n
- \");\n cleanHTML = cleanHTML.replace(/<\\/ul>/g, \"
- /g, \"
- \");\n cleanHTML = cleanHTML.replace(/<\\/ol>/g, \"
(.*?)<\\/code>/g, \"$1\");\n\n // Simplify links\n cleanHTML = cleanHTML.replace(\n /]*href=\"([^\"]*)\"[^>]*>(.*?)<\\/a>/g,\n '$2'\n );\n\n // Decode HTML entities\n cleanHTML = cleanHTML.replace(/&/g, \"&\");\n cleanHTML = cleanHTML.replace(/</g, \"<\");\n cleanHTML = cleanHTML.replace(/>/g, \">\");\n cleanHTML = cleanHTML.replace(/"/g, '\"');\n cleanHTML = cleanHTML.replace(/'/g, \"'\");\n cleanHTML = cleanHTML.replace(/ /g, \" \");\n\n // Clean up whitespace\n cleanHTML = cleanHTML.replace(/\\s+/g, \" \");\n cleanHTML = cleanHTML.replace(/\\s*<\\/p>/g, \"\");\n\n return cleanHTML.trim();\n}\n\nasync function main() {\n console.log(\"Fetching latest topics...\");\n const latestData = await fetchJSON(\"https://forum.livepeer.org/latest.json\");\n\n const topics = latestData.topic_list?.topics || [];\n console.log(`Found ${topics.length} topics`);\n\n // Filter out old pinned topics\n const filteredTopics = topics.filter((t) => !isOldPinned(t));\n console.log(`After filtering: ${filteredTopics.length} topics`);\n\n // Get top 4\n const top4 = filteredTopics.slice(0, 4);\n console.log(`Processing top 4 topics...`);\n\n const processedTopics = [];\n\n for (const topic of top4) {\n console.log(`Processing topic ${topic.id}: ${topic.title}`);\n\n // Fetch full topic data\n const topicData = await fetchJSON(\n `https://forum.livepeer.org/t/${topic.id}.json`\n );\n\n // Extract first post\n const firstPost = topicData.post_stream?.posts?.find(\n (p) => p.post_number === 1\n );\n\n if (!firstPost) {\n console.log(` No first post found, skipping`);\n continue;\n }\n\n const htmlContent = cleanAndFormatHTML(firstPost.cooked || \"\");\n const datePosted = topic.created_at\n ? new Date(topic.created_at).toLocaleDateString(\"en-US\", {\n year: \"numeric\",\n month: \"short\",\n day: \"numeric\",\n })\n : \"\";\n\n processedTopics.push({\n title: topic.title,\n href: `https://forum.livepeer.org/t/${topic.id}`,\n author: `By ${firstPost.name || firstPost.username || \"Unknown\"} (@${\n firstPost.username || \"unknown\"\n })`,\n content: htmlContent,\n replyCount: (topic.posts_count || 1) - 1,\n datePosted: datePosted,\n });\n }\n\n console.log(`Processed ${processedTopics.length} topics`);\n\n // Generate JavaScript export with exact formatting\n let jsExport = \"export const forumData = [\\n\";\n\n processedTopics.forEach((item, index) => {\n jsExport += \" {\\n\";\n jsExport += ` title: \"${item.title\n .replace(/\\\\/g, \"\\\\\\\\\")\n .replace(/\"/g, '\\\\\"')}\",\\n`;\n jsExport += ` href: \"${item.href}\",\\n`;\n jsExport += ` author: \"${item.author\n .replace(/\\\\/g, \"\\\\\\\\\")\n .replace(/\"/g, '\\\\\"')}\",\\n`;\n\n // Content with proper escaping and indentation\n const escapedContent = item.content\n .replace(/\\\\/g, \"\\\\\\\\\")\n .replace(/\"/g, '\\\\\"')\n .replace(/\\n/g, \" \");\n\n jsExport += ` content:\\n \"${escapedContent}\",\\n`;\n jsExport += ` replyCount: ${item.replyCount},\\n`;\n jsExport += ` datePosted: \"${item.datePosted}\",\\n`;\n jsExport += \" }\";\n\n if (index < processedTopics.length - 1) {\n jsExport += \",\";\n }\n jsExport += \"\\n\";\n });\n\n jsExport += \"];\\n\";\n\n // Write to file\n const outputPath = \"snippets/automations/forum/forumData.jsx\";\n fs.mkdirSync(\"snippets/automations/forum\", { recursive: true });\n fs.writeFileSync(outputPath, jsExport);\n console.log(`Written to ${outputPath}`);\n}\n\nmain().catch((err) => {\n console.error(\"Error:\", err);\n process.exit(1);\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/update-forum-data.yml",
+ "workflow": "Update Forum Data",
+ "pipeline": "P5",
+ "cron": "0 0 * * *"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/update-forum-data.yml",
+ "workflow": "Update Forum Data",
+ "pipeline": "P6"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": ".github/scripts/snippets/automations/forum",
+ "type": "directory",
+ "call": "mkdirSync"
+ },
+ {
+ "output_path": ".github/scripts/snippets/automations/forum/forumData.jsx",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": ".github/scripts/snippets/automations/forum, .github/scripts/snippets/automations/forum/forumData.jsx",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Update Forum Data cron 0 0 * * *); P6 (Update Forum Data)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ },
+ {
+ "path": ".github/scripts/fetch-ghost-blog-data.js",
+ "script": "fetch-ghost-blog-data",
+ "category": "automation",
+ "purpose": "infrastructure:data-feeds",
+ "scope": ".github/scripts",
+ "owner": "docs",
+ "needs": "F-R1",
+ "purpose_statement": "Fetches blog posts from Ghost CMS API, writes to snippets/automations/blog/",
+ "pipeline_declared": "P5, P6",
+ "usage": "node .github/scripts/fetch-ghost-blog-data.js [flags]",
+ "header": "/**\n * @script fetch-ghost-blog-data\n * @category automation\n * @purpose infrastructure:data-feeds\n * @scope .github/scripts\n * @owner docs\n * @needs F-R1\n * @purpose-statement Fetches blog posts from Ghost CMS API, writes to snippets/automations/blog/\n * @pipeline P5, P6\n * @usage node .github/scripts/fetch-ghost-blog-data.js [flags]\n */\nconst https = require(\"https\");\nconst fs = require(\"fs\");\n\n// Fetch JSON from URL\nfunction fetchJSON(url) {\n return new Promise((resolve, reject) => {\n https\n .get(url, (res) => {\n let data = \"\";\n res.on(\"data\", (chunk) => {\n data += chunk;\n });\n res.on(\"end\", () => {\n try {\n resolve(JSON.parse(data));\n } catch (e) {\n reject(e);\n }\n });\n })\n .on(\"error\", reject);\n });\n}\n\n// Safe HTML escape - only escape backticks for template literals\nfunction safeHTML(html) {\n return (html || \"\").replace(/`/g, \"\\\\`\");\n}\n\n// Format date\nfunction formatDate(iso) {\n return new Date(iso).toLocaleDateString(\"en-US\", {\n month: \"short\",\n day: \"numeric\",\n year: \"numeric\",\n });\n}\n\nasync function main() {\n console.log(\"Fetching Ghost blog posts...\");\n\n const apiKey = process.env.GHOST_CONTENT_API_KEY;\n if (!apiKey) {\n throw new Error(\n \"GHOST_CONTENT_API_KEY environment variable is not set. Please configure your Ghost Content API key.\"\n );\n }\n\n const apiUrl =\n `https://livepeer-studio.ghost.io/ghost/api/content/posts/?key=${apiKey}&limit=4&include=tags,authors`;\n\n const response = await fetchJSON(apiUrl);\n\n if (!response.posts || response.posts.length === 0) {\n console.log(\"No posts found\");\n return;\n }\n\n console.log(`Found ${response.posts.length} posts`);\n\n // Process posts\n const posts = response.posts.map((p) => ({\n title: p.title,\n href: p.url,\n author: p.primary_author?.name\n ? `By ${p.primary_author.name}`\n : \"By Livepeer Team\",\n content: safeHTML(p.html),\n datePosted: formatDate(p.published_at),\n img: p.feature_image || \"\",\n excerpt: safeHTML(p.excerpt),\n readingTime: p.reading_time || 0,\n }));\n\n // Generate JavaScript export with template literals\n let jsExport = \"export const ghostData = [\\n\";\n\n posts.forEach((post, index) => {\n jsExport += \"{\\n\";\n jsExport += ` title: \\`${post.title}\\`,\\n`;\n jsExport += ` href: \\`${post.href}\\`,\\n`;\n jsExport += ` author: \\`${post.author}\\`,\\n`;\n jsExport += ` content: \\`${post.content}\\`,\\n`;\n jsExport += ` datePosted: \\`${post.datePosted}\\`,\\n`;\n jsExport += ` img: \\`${post.img}\\`,\\n`;\n jsExport += ` excerpt: \\`${post.excerpt}\\`,\\n`;\n jsExport += ` readingTime: ${post.readingTime}\\n`;\n jsExport += \"}\";\n\n if (index < posts.length - 1) {\n jsExport += \",\";\n }\n jsExport += \"\\n\";\n });\n\n jsExport += \"];\\n\";\n\n // Write to file\n const outputPath = \"snippets/automations/blog/ghostBlogData.jsx\";\n fs.mkdirSync(\"snippets/automations/blog\", { recursive: true });\n fs.writeFileSync(outputPath, jsExport);\n console.log(`Written to ${outputPath}`);\n}\n\nmain().catch((err) => {\n console.error(\"Error:\", err);\n process.exit(1);\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/update-ghost-blog-data.yml",
+ "workflow": "Update Ghost Blog Data",
+ "pipeline": "P5",
+ "cron": "0 0 * * *"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/update-ghost-blog-data.yml",
+ "workflow": "Update Ghost Blog Data",
+ "pipeline": "P6"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": ".github/scripts/snippets/automations/blog",
+ "type": "directory",
+ "call": "mkdirSync"
+ },
+ {
+ "output_path": ".github/scripts/snippets/automations/blog/ghostBlogData.jsx",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": ".github/scripts/snippets/automations/blog, .github/scripts/snippets/automations/blog/ghostBlogData.jsx",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Update Ghost Blog Data cron 0 0 * * *); P6 (Update Ghost Blog Data)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ },
+ {
+ "path": ".github/scripts/fetch-youtube-data.js",
+ "script": "fetch-youtube-data",
+ "category": "automation",
+ "purpose": "infrastructure:data-feeds",
+ "scope": ".github/scripts",
+ "owner": "docs",
+ "needs": "F-R1",
+ "purpose_statement": "Fetches video data from YouTube Data API, writes to snippets/automations/youtube/",
+ "pipeline_declared": "P5, P6",
+ "usage": "node .github/scripts/fetch-youtube-data.js [flags]",
+ "header": "/**\n * @script fetch-youtube-data\n * @category automation\n * @purpose infrastructure:data-feeds\n * @scope .github/scripts\n * @owner docs\n * @needs F-R1\n * @purpose-statement Fetches video data from YouTube Data API, writes to snippets/automations/youtube/\n * @pipeline P5, P6\n * @usage node .github/scripts/fetch-youtube-data.js [flags]\n */\nconst https = require(\"https\");\nconst fs = require(\"fs\");\n\nconst YOUTUBE_API_KEY = process.env.YOUTUBE_API_KEY;\nconst CHANNEL_ID = process.env.CHANNEL_ID || \"UCzfHtZnmUzMbJDxGCwIgY2g\";\n\nfunction httpsGet(url) {\n return new Promise((resolve, reject) => {\n https\n .get(url, (res) => {\n let data = \"\";\n res.on(\"data\", (chunk) => (data += chunk));\n res.on(\"end\", () => resolve(JSON.parse(data)));\n })\n .on(\"error\", reject);\n });\n}\n\nfunction parseDuration(duration) {\n const match = duration.match(/PT(?:(\\d+)H)?(?:(\\d+)M)?(?:(\\d+)S)?/);\n if (!match) return 0;\n\n const hours = parseInt(match[1] || 0);\n const minutes = parseInt(match[2] || 0);\n const seconds = parseInt(match[3] || 0);\n\n return hours * 3600 + minutes * 60 + seconds;\n}\n\nfunction escapeForJSX(str) {\n return str\n .replace(/\\\\/g, \"\\\\\\\\\")\n .replace(/'/g, \"\\\\'\")\n .replace(/\"/g, '\\\\\"')\n .replace(/\\n/g, \" \")\n .replace(/\\r/g, \"\")\n .replace(/\\t/g, \" \");\n}\n\nasync function main() {\n // Step 1: Get recent videos\n console.log(\"Fetching recent videos...\");\n const searchUrl = `https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=${CHANNEL_ID}&maxResults=50&order=date&type=video&key=${YOUTUBE_API_KEY}`;\n const searchResults = await httpsGet(searchUrl);\n\n if (!searchResults.items || searchResults.items.length === 0) {\n console.log(\"No videos found\");\n return;\n }\n\n // Step 2: Get video details for each video\n console.log(\n `Found ${searchResults.items.length} videos, fetching details...`\n );\n const videoIds = searchResults.items.map((item) => item.id.videoId).join(\",\");\n const detailsUrl = `https://www.googleapis.com/youtube/v3/videos?part=contentDetails,snippet&id=${videoIds}&key=${YOUTUBE_API_KEY}`;\n const detailsResults = await httpsGet(detailsUrl);\n\n // Step 3: Process and filter videos\n const videos = [];\n for (const video of detailsResults.items) {\n const duration = video.contentDetails.duration;\n const durationSeconds = parseDuration(duration);\n const snippet = video.snippet;\n\n // Check if it's a livestream\n const isLivestream =\n snippet.liveBroadcastContent === \"live\" ||\n snippet.liveBroadcastContent === \"upcoming\" ||\n duration === \"PT0S\" ||\n snippet.title.toLowerCase().includes(\"watercooler\") ||\n snippet.title.toLowerCase().includes(\"fireside\");\n\n // Filter out Shorts (≤60 seconds and not livestreams)\n const isShort =\n durationSeconds <= 60 && durationSeconds > 0 && !isLivestream;\n\n if (!isShort) {\n videos.push({\n title: snippet.title,\n href: `https://www.youtube.com/watch?v=${video.id}`,\n author: `By ${snippet.channelTitle || \"Livepeer\"}`,\n content: (snippet.description || \"\").substring(0, 500),\n publishedDate: new Date(snippet.publishedAt).toLocaleDateString(\n \"en-US\",\n { month: \"short\", day: \"numeric\", year: \"numeric\" }\n ),\n duration: duration,\n thumbnailUrl: snippet.thumbnails.high.url,\n });\n }\n }\n\n console.log(`Filtered to ${videos.length} non-Short videos`);\n\n // Step 4: Generate JSX content\n const jsxContent = `export const youtubeData = [\n${videos\n .map(\n (v) => ` {\n title: '${escapeForJSX(v.title)}',\n href: '${v.href}',\n author: '${v.author}',\n content: '${escapeForJSX(v.content)}...',\n publishedDate: '${v.publishedDate}',\n duration: '${v.duration}',\n thumbnailUrl: '${v.thumbnailUrl}'\n }`\n )\n .join(\",\\n\")}\n];\n`;\n\n // Step 5: Write to file\n fs.writeFileSync(\"snippets/automations/youtube/youtubeData.jsx\", jsxContent);\n console.log(\"Successfully wrote youtubeData.jsx\");\n}\n\nmain().catch((err) => {\n console.error(\"Error:\", err);\n process.exit(1);\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/update-youtube-data.yml",
+ "workflow": "Update YouTube Data",
+ "pipeline": "P5",
+ "cron": "0 0 * * 0"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/update-youtube-data.yml",
+ "workflow": "Update YouTube Data",
+ "pipeline": "P6"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": ".github/scripts/snippets/automations/youtube/youtubeData.jsx",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": ".github/scripts/snippets/automations/youtube/youtubeData.jsx",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Update YouTube Data cron 0 0 * * 0); P6 (Update YouTube Data)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ },
+ {
+ "path": ".github/scripts/project-showcase-sync.js",
+ "script": "project-showcase-sync",
+ "category": "automation",
+ "purpose": "infrastructure:data-feeds",
+ "scope": ".github/scripts",
+ "owner": "docs",
+ "needs": "F-R1",
+ "purpose_statement": "Fetches project showcase data from external source, writes to snippets/automations/showcase/",
+ "pipeline_declared": "P5, P6",
+ "usage": "node .github/scripts/project-showcase-sync.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script project-showcase-sync\n * @category automation\n * @purpose infrastructure:data-feeds\n * @scope .github/scripts\n * @owner docs\n * @needs F-R1\n * @purpose-statement Fetches project showcase data from external source, writes to snippets/automations/showcase/\n * @pipeline P5, P6\n * @usage node .github/scripts/project-showcase-sync.js [flags]\n */\n/*\n * Project Showcase sync job for GitHub Actions.\n *\n * Modes:\n * - poll: process new submissions + pending review decisions from Sheets\n * - dispatch: process one decision from repository_dispatch payload\n */\n\nconst crypto = require('crypto');\nconst fs = require('fs');\n\nconst REQUIRED_ENVS = [\n 'GOOGLE_SERVICE_ACCOUNT_JSON',\n 'GOOGLE_SHEET_ID',\n 'DISCORD_BOT_TOKEN',\n 'DISCORD_REVIEWER_USER_ID'\n];\n\nconst cfg = {\n mode: process.env.SHOWCASE_SYNC_MODE || 'poll',\n googleSheetId: process.env.GOOGLE_SHEET_ID,\n submissionsSheetName: process.env.SUBMISSIONS_SHEET_NAME || 'Form Responses 1',\n submissionsSheetUrl: process.env.SUBMISSIONS_SHEET_URL || '',\n reviewSheetName: process.env.REVIEW_SHEET_NAME || 'Review Responses',\n transformedSheetName: process.env.TRANSFORMED_SHEET_NAME || 'Transformed Responses',\n reviewProcessedColumn: process.env.REVIEW_PROCESSED_COLUMN || 'Processed',\n approvalFormBaseUrl: process.env.APPROVAL_FORM_BASE_URL || '',\n githubOwner: process.env.GITHUB_OWNER || process.env.GITHUB_REPOSITORY?.split('/')[0],\n githubRepo: process.env.GITHUB_REPO || process.env.GITHUB_REPOSITORY?.split('/')[1],\n githubDataBranch: process.env.GITHUB_DATA_BRANCH || 'docs-v2-preview',\n githubAssetsBranch: process.env.GITHUB_ASSETS_BRANCH || 'docs-v2-assets',\n showcaseDataPath:\n process.env.SHOWCASE_DATA_FILE_PATH || 'snippets/automations/showcase/showcaseData.jsx',\n showcaseAssetsBasePath:\n process.env.SHOWCASE_ASSETS_BASE_PATH || 'snippets/assets/domain/00_HOME/showcase',\n discordApiBaseUrl: process.env.DISCORD_API_BASE_URL || 'https://discord.com/api/v10',\n discordReviewerUserId: process.env.DISCORD_REVIEWER_USER_ID,\n githubToken: process.env.GITHUB_TOKEN,\n maxRowsPerRun: Number(process.env.MAX_ROWS_PER_RUN || 10)\n};\n\nconst serviceAccount = JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_JSON || '{}');\n\nfunction log(msg, obj) {\n if (obj !== undefined) {\n console.log(msg, JSON.stringify(obj));\n } else {\n console.log(msg);\n }\n}\n\nfunction assertEnv() {\n const missing = REQUIRED_ENVS.filter((key) => !process.env[key]);\n if (missing.length > 0) {\n throw new Error(`Missing required env vars: ${missing.join(', ')}`);\n }\n if (!cfg.githubOwner || !cfg.githubRepo || !cfg.githubToken) {\n throw new Error('Missing GitHub config: GITHUB_OWNER/GITHUB_REPO/GITHUB_TOKEN');\n }\n}\n\nfunction base64url(input) {\n return Buffer.from(input)\n .toString('base64')\n .replace(/=/g, '')\n .replace(/\\+/g, '-')\n .replace(/\\//g, '_');\n}\n\nfunction sanitizePathSegment(input) {\n return String(input || '')\n .trim()\n .replace(/[^a-zA-Z0-9._-]+/g, '-')\n .replace(/^-+|-+$/g, '')\n .slice(0, 120) || 'untitled-project';\n}\n\nfunction getDriveFileId(url) {\n if (!url) return null;\n const patterns = [\n /\\/file\\/d\\/([a-zA-Z0-9_-]+)/,\n /[?&]id=([a-zA-Z0-9_-]+)/,\n /\\/uc\\?export=download&id=([a-zA-Z0-9_-]+)/\n ];\n for (const p of patterns) {\n const m = String(url).match(p);\n if (m?.[1]) return m[1];\n }\n return null;\n}\n\nfunction isValidUrl(value) {\n try {\n new URL(String(value));\n return true;\n } catch {\n return false;\n }\n}\n\nfunction findHeader(headers, candidates) {\n const map = new Map(headers.map((h) => [String(h).toLowerCase().trim(), h]));\n for (const c of candidates) {\n const hit = map.get(String(c).toLowerCase().trim());\n if (hit) return hit;\n }\n return null;\n}\n\nfunction getCell(row, headers, candidates) {\n const header = findHeader(headers, candidates);\n if (!header) return '';\n return row[header] || '';\n}\n\nfunction toObjects(values) {\n if (!values.length) return { headers: [], rows: [] };\n const headers = values[0];\n const rows = values.slice(1).map((raw, i) => {\n const json = {};\n headers.forEach((h, idx) => {\n json[h] = raw[idx] || '';\n });\n json.__rowIndex = i + 2;\n return json;\n });\n return { headers, rows };\n}\n\nfunction colToA1(colIndexZeroBased) {\n let n = colIndexZeroBased + 1;\n let result = '';\n while (n > 0) {\n const rem = (n - 1) % 26;\n result = String.fromCharCode(65 + rem) + result;\n n = Math.floor((n - 1) / 26);\n }\n return result;\n}\n\nfunction parseDecision(raw) {\n const value = String(raw || '').trim().toLowerCase();\n if (['yes', 'approve', 'approved'].includes(value)) return 'yes';\n if (['no', 'deny', 'denied'].includes(value)) return 'no';\n return null;\n}\n\nasync function getGoogleAccessToken() {\n const now = Math.floor(Date.now() / 1000);\n const header = { alg: 'RS256', typ: 'JWT' };\n const payload = {\n iss: serviceAccount.client_email,\n scope: 'https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly',\n aud: 'https://oauth2.googleapis.com/token',\n exp: now + 3600,\n iat: now\n };\n\n const unsignedToken = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;\n const signer = crypto.createSign('RSA-SHA256');\n signer.update(unsignedToken);\n signer.end();\n const signature = signer.sign(serviceAccount.private_key, 'base64url');\n const assertion = `${unsignedToken}.${signature}`;\n\n const body = new URLSearchParams({\n grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',\n assertion\n });\n\n const res = await fetch('https://oauth2.googleapis.com/token', {\n method: 'POST',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body\n });\n\n if (!res.ok) {\n throw new Error(`Failed to get Google access token: ${res.status} ${await res.text()}`);\n }\n\n return (await res.json()).access_token;\n}\n\nasync function sheetsGetValues(accessToken, range) {\n const url = `https://sheets.googleapis.com/v4/spreadsheets/${cfg.googleSheetId}/values/${encodeURIComponent(\n range\n )}`;\n const res = await fetch(url, { headers: { Authorization: `Bearer ${accessToken}` } });\n if (!res.ok) {\n throw new Error(`Sheets read failed for ${range}: ${res.status} ${await res.text()}`);\n }\n return (await res.json()).values || [];\n}\n\nasync function sheetsUpdateValue(accessToken, range, value) {\n const url = `https://sheets.googleapis.com/v4/spreadsheets/${cfg.googleSheetId}/values/${encodeURIComponent(\n range\n )}?valueInputOption=RAW`;\n const res = await fetch(url, {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${accessToken}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ values: [[value]] })\n });\n if (!res.ok) {\n throw new Error(`Sheets update failed for ${range}: ${res.status} ${await res.text()}`);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/project-showcase-sync.yml",
+ "workflow": "Project Showcase Sync",
+ "pipeline": "P5",
+ "cron": "*/15 * * * *"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/project-showcase-sync.yml",
+ "workflow": "Project Showcase Sync",
+ "pipeline": "P6"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Project Showcase Sync cron */15 * * * *); P6 (Project Showcase Sync)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ },
+ {
+ "path": "tools/scripts/docs-quality-and-freshness-audit.js",
+ "script": "docs-quality-and-freshness-audit",
+ "category": "validator",
+ "purpose": "qa:content-quality",
+ "scope": "tools/scripts, v2, tasks/reports/quality-accessibility",
+ "owner": "docs",
+ "needs": "E-R1, R-R11",
+ "purpose_statement": "Content freshness audit — checks for TODO/TBD/Coming Soon markers, thin pages, stale content",
+ "pipeline_declared": "P5, P6",
+ "usage": "node tools/scripts/docs-quality-and-freshness-audit.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script docs-quality-and-freshness-audit\n * @category validator\n * @purpose qa:content-quality\n * @scope tools/scripts, v2, tasks/reports/quality-accessibility\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Content freshness audit — checks for TODO/TBD/Coming Soon markers, thin pages, stale content\n * @pipeline P5, P6\n * @usage node tools/scripts/docs-quality-and-freshness-audit.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst STAGE_ID = 'docs-quality-and-freshness-audit';\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_OUTPUT_DIR = 'tasks/reports/repo-ops';\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction parseArgs(argv) {\n const out = { scope: 'full', outputDir: DEFAULT_OUTPUT_DIR };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--scope') {\n out.scope = String(argv[i + 1] || out.scope).trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--scope=')) {\n out.scope = token.slice('--scope='.length).trim() || out.scope;\n continue;\n }\n if (token === '--output-dir') {\n out.outputDir = String(argv[i + 1] || out.outputDir).trim() || out.outputDir;\n i += 1;\n continue;\n }\n if (token.startsWith('--output-dir=')) {\n out.outputDir = token.slice('--output-dir='.length).trim() || out.outputDir;\n continue;\n }\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!['changed', 'full'].includes(out.scope)) {\n throw new Error(`Invalid --scope: ${out.scope}`);\n }\n\n return out;\n}\n\nfunction addIssue(issues, issue) {\n issues.push({\n id: issue.id,\n title: issue.title,\n severity: issue.severity,\n evidence: issue.evidence,\n recommendation: issue.recommendation,\n path: issue.path || '',\n line: Number.isFinite(Number(issue.line)) ? Number(issue.line) : 1\n });\n}\n\nfunction summarize(issues) {\n const summary = {\n critical: 0,\n high: 0,\n medium: 0,\n low: 0,\n info: 0,\n total: issues.length\n };\n\n for (const issue of issues) {\n if (Object.prototype.hasOwnProperty.call(summary, issue.severity)) {\n summary[issue.severity] += 1;\n }\n }\n\n return summary;\n}\n\nfunction shouldExclude(relPath) {\n const rel = toPosix(relPath);\n if (!rel.startsWith('v2/')) return true;\n if (rel.startsWith('v2/es/') || rel.startsWith('v2/fr/') || rel.startsWith('v2/cn/')) return true;\n if (rel.startsWith('v2/internal/')) return true;\n if (rel.includes('/x-')) return true;\n if (rel.includes('/_contextData_/') || rel.includes('/_context_data_/')) return true;\n if (rel.includes('/_move_me/') || rel.includes('/_tests-to-delete/')) return true;\n if (rel.endsWith('todo.txt') || rel.endsWith('todo.mdx') || rel.endsWith('NOTES_V2.md')) return true;\n return false;\n}\n\nfunction walkFiles(dirPath, out = []) {\n if (!fs.existsSync(dirPath)) return out;\n const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n for (const entry of entries) {\n const full = path.join(dirPath, entry.name);\n const rel = toPosix(path.relative(REPO_ROOT, full));\n\n if (entry.isDirectory()) {\n if (entry.name === '.git' || entry.name === 'node_modules') continue;\n walkFiles(full, out);\n continue;\n }\n\n if (!/\\.mdx$/i.test(entry.name)) continue;\n if (shouldExclude(rel)) continue;\n out.push({ absPath: full, relPath: rel });\n }\n return out;\n}\n\nfunction getChangedEnglishFiles() {\n try {\n const output = execSync('git diff --name-only --diff-filter=ACMR HEAD', {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n\n return output\n .split('\\n')\n .map((line) => toPosix(line.trim()))\n .filter(Boolean)\n .filter((line) => line.startsWith('v2/'))\n .filter((line) => /\\.mdx$/i.test(line))\n .filter((line) => !shouldExclude(line))\n .map((line) => ({ relPath: line, absPath: path.join(REPO_ROOT, line) }));\n } catch (_error) {\n return [];\n }\n}\n\nfunction countWords(content) {\n return String(content || '')\n .replace(/^---[\\s\\S]*?---\\s*/m, ' ')\n .replace(/```[\\s\\S]*?```/g, ' ')\n .replace(/`[^`]+`/g, ' ')\n .replace(/<[^>]+>/g, ' ')\n .replace(/\\[[^\\]]+\\]\\([^)]+\\)/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim()\n .split(' ')\n .filter(Boolean).length;\n}\n\nfunction loadUsefulnessSignal(issues) {\n const metadataPath = path.join(\n REPO_ROOT,\n 'tasks/reports/quality-accessibility/docs-usefulness/latest/run-metadata.json'\n );\n\n if (!fs.existsSync(metadataPath)) {\n addIssue(issues, {\n id: 'usefulness-metadata-missing',\n title: 'Docs usefulness metadata not found',\n severity: 'low',\n path: 'tasks/reports/quality-accessibility/docs-usefulness/latest/run-metadata.json',\n evidence: 'No usefulness metadata snapshot found for cross-check.',\n recommendation: 'Run `node tools/scripts/audit-v2-usefulness.js --mode full` for a fresh baseline.'\n });\n return;\n }\n\n try {\n const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));\n const pages = Number(metadata?.counts?.processed_pages || metadata?.processed_pages || 0);\n if (pages === 0) {\n addIssue(issues, {\n id: 'usefulness-empty-run',\n title: 'Usefulness metadata reports zero processed pages',\n severity: 'low',\n path: 'tasks/reports/quality-accessibility/docs-usefulness/latest/run-metadata.json',\n evidence: 'Processed pages count is zero in latest usefulness metadata.',\n recommendation: 'Verify usefulness run mode and regenerate metadata with a full run.'\n });\n }\n } catch (_error) {\n addIssue(issues, {\n id: 'usefulness-metadata-parse-failed',\n title: 'Unable to parse usefulness metadata',\n severity: 'low',\n path: 'tasks/reports/quality-accessibility/docs-usefulness/latest/run-metadata.json',\n evidence: 'Metadata JSON could not be parsed.',\n recommendation: 'Regenerate usefulness outputs to restore machine-readable state.'\n });\n }\n}\n\nfunction analyzeFileMarkers(issues, file) {\n const content = fs.readFileSync(file.absPath, 'utf8');\n const lines = content.split('\\n');\n const markerRules = [\n { id: 'todo-marker', label: 'TODO marker detected', regex: /\\bTODO\\b/i, severity: 'medium' },\n { id: 'tbd-marker', label: 'TBD marker detected', regex: /\\bTBD\\b/i, severity: 'medium' },\n { id: 'coming-soon-marker', label: 'Coming Soon marker detected', regex: /Coming Soon/i, severity: 'high' },\n { id: 'preview-callout-marker', label: 'PreviewCallout marker detected', regex: / {\n let count = 0;\n lines.forEach((line, index) => {\n if (!rule.regex.test(line)) return;\n count += 1;\n addIssue(issues, {\n id: rule.id,\n title: rule.label,\n severity: rule.severity,",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/content-health.yml",
+ "workflow": "Content Health Check",
+ "pipeline": "P5",
+ "cron": "0 6 * * 1"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/content-health.yml",
+ "workflow": "Content Health Check",
+ "pipeline": "P6"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "audit:docs-quality"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/${STAGE_ID}.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/${STAGE_ID}.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/${STAGE_ID}.json, tools/scripts/${STAGE_ID}.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Content Health Check cron 0 6 * * 1); P6 (Content Health Check); manual (npm script: audit:docs-quality)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ },
+ {
+ "path": "tools/scripts/audit-component-usage.js",
+ "script": "audit-component-usage",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-C1, R-R14",
+ "purpose_statement": "Component usage auditor — scans pages for component usage patterns and reports statistics",
+ "pipeline_declared": "P5, P6",
+ "usage": "node tools/scripts/audit-component-usage.js [flags]",
+ "header": "/**\n * @script audit-component-usage\n * @category validator\n * @purpose qa:repo-health\n * @scope tools/scripts\n * @owner docs\n * @needs E-C1, R-R14\n * @purpose-statement Component usage auditor — scans pages for component usage patterns and reports statistics\n * @pipeline P5, P6\n * @usage node tools/scripts/audit-component-usage.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst REPORT_PATH = path.join(__dirname, '..', '..', 'tasks', 'reports', 'repo-ops', 'component-usage-audit.json');\n\nconst V2_DOC_ROOTS = [\n 'v2/pages',\n 'v2/home',\n 'v2/solutions',\n 'v2/about',\n 'v2/community',\n 'v2/developers',\n 'v2/gateways',\n 'v2/orchestrators',\n 'v2/lpt',\n 'v2/resources',\n 'v2/internal',\n 'v2/deprecated',\n 'v2/experimental',\n 'v2/notes'\n].filter((root) => fs.existsSync(root));\n\nfunction resolveFirstExistingPath(candidates) {\n for (const candidate of candidates) {\n if (fs.existsSync(candidate)) return candidate;\n }\n return candidates[0];\n}\n\n// Get all exported components from snippets/components\nfunction getAllExportedComponents() {\n const components = new Map();\n \n // Read all .jsx files in snippets/components\n const componentFiles = execSync('find snippets/components -name \"*.jsx\" -o -name \"*.mdx\" | grep -E \"(components|\\.jsx|\\.mdx)$\"', { encoding: 'utf8' })\n .trim()\n .split('\\n')\n .filter(f => f);\n \n componentFiles.forEach(file => {\n try {\n const content = fs.readFileSync(file, 'utf8');\n \n // Find inline exports: export const ComponentName\n const inlineExports = content.matchAll(/^export (const|function|default) (\\w+)/gm);\n for (const match of inlineExports) {\n const componentName = match[2];\n const relativePath = path.relative('snippets/components', file);\n components.set(componentName, {\n name: componentName,\n file: file,\n relativePath: relativePath,\n category: getCategory(relativePath)\n });\n }\n \n // Find export statements at end: export { Component1, Component2 }\n const exportStatements = content.matchAll(/^export\\s*{([^}]+)}/gm);\n for (const match of exportStatements) {\n const exports = match[1].split(',').map(e => e.trim());\n exports.forEach(exp => {\n const componentName = exp.trim();\n if (componentName) {\n const relativePath = path.relative('snippets/components', file);\n components.set(componentName, {\n name: componentName,\n file: file,\n relativePath: relativePath,\n category: getCategory(relativePath)\n });\n }\n });\n }\n } catch (e) {\n // Skip files that can't be read\n }\n });\n \n return components;\n}\n\nfunction getCategory(filePath) {\n if (filePath.includes('primitives/')) return 'primitives';\n if (filePath.includes('display/')) return 'display';\n if (filePath.includes('content/')) return 'content';\n if (filePath.includes('layout/')) return 'layout';\n if (filePath.includes('integrations/')) return 'integrations';\n if (filePath.includes('domain/')) return 'domain';\n return 'unknown';\n}\n\n// Get components used in component library pages\nfunction getComponentLibraryComponents() {\n const used = new Set();\n const commented = new Set();\n \n const libFiles = [\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library.mdx',\n 'v2/resources/documentation-guide/component-library.mdx'\n ]),\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library/primitives.mdx',\n 'v2/resources/documentation-guide/component-library/primitives.mdx'\n ]),\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library/display.mdx',\n 'v2/resources/documentation-guide/component-library/display.mdx'\n ]),\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library/content.mdx',\n 'v2/resources/documentation-guide/component-library/content.mdx'\n ]),\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library/layout.mdx',\n 'v2/resources/documentation-guide/component-library/layout.mdx'\n ]),\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library/integrations.mdx',\n 'v2/resources/documentation-guide/component-library/integrations.mdx'\n ]),\n resolveFirstExistingPath([\n 'v2/resources/documentation-guide/component-library/domain.mdx',\n 'v2/resources/documentation-guide/component-library/domain.mdx'\n ])\n ];\n \n libFiles.forEach(file => {\n if (!fs.existsSync(file)) return;\n const content = fs.readFileSync(file, 'utf8');\n \n // Find imports\n const importMatches = content.matchAll(/import\\s+{([^}]+)}\\s+from\\s+['\"]\\/snippets\\/components\\/([^'\"]+)['\"]/g);\n for (const match of importMatches) {\n const imports = match[1].split(',').map(i => i.trim());\n imports.forEach(imp => {\n const name = imp.replace(/\\/\\*.*?\\*\\//g, '').trim();\n if (name && !name.startsWith('//')) {\n used.add(name);\n }\n });\n }\n \n // Find commented out imports\n const commentedMatches = content.matchAll(/\\/\\/\\s*import\\s+{([^}]+)}\\s+from/g);\n for (const match of commentedMatches) {\n const imports = match[1].split(',').map(i => i.trim());\n imports.forEach(imp => {\n const name = imp.replace(/\\/\\*.*?\\*\\//g, '').trim();\n if (name) {\n commented.add(name);\n }\n });\n }\n \n // Find JSX comments\n const jsxCommentMatches = content.matchAll(/{\\/\\*\\s*([^*]+)\\s*\\*\\/}/g);\n for (const match of jsxCommentMatches) {\n const comment = match[1];\n // Extract component names from comments\n const nameMatches = comment.matchAll(/([A-Z][a-zA-Z0-9]+)/g);\n for (const nameMatch of nameMatches) {\n const name = nameMatch[1];\n if (name.length > 3 && !['This', 'These', 'They', 'That'].includes(name)) {\n commented.add(name);\n }\n }\n }\n });\n \n return { used, commented };\n}\n\n// Get components used in v2 pages\nfunction getV2PageComponents() {\n const used = new Map(); // component -> [files]\n const searchRoots = V2_DOC_ROOTS.length > 0 ? V2_DOC_ROOTS : ['v2/pages'];\n const findCommand = `find ${searchRoots.join(' ')} -name \"*.mdx\" -type f`;\n const v2Files = execSync(findCommand, { encoding: 'utf8' })\n .trim()\n .split('\\n')\n .filter((f) => f && !f.includes('component-library'));\n \n v2Files.forEach(file => {\n try {\n const content = fs.readFileSync(file, 'utf8');\n const importMatches = content.matchAll(/import\\s+{([^}]+)}\\s+from\\s+['\"]\\/snippets\\/components\\/([^'\"]+)['\"]/g);\n \n for (const match of importMatches) {\n const imports = match[1].split(',').map(i => i.trim().replace(/\\/\\*.*?\\*\\//g, '').trim());\n imports.forEach(imp => {\n if (imp && !imp.startsWith('//')) {\n if (!used.has(imp)) {\n used.set(imp, []);\n }\n used.get(imp).push(file);\n }\n });\n }\n } catch (e) {\n // Skip\n }\n });\n \n return used;\n}\n\n// Get components used in snippets",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/content-health.yml",
+ "workflow": "Content Health Check",
+ "pipeline": "P5",
+ "cron": "0 6 * * 1"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/content-health.yml",
+ "workflow": "Content Health Check",
+ "pipeline": "P6"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/component-usage-audit.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/component-usage-audit.json",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Content Health Check cron 0 6 * * 1); P6 (Content Health Check)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ },
+ {
+ "path": "tools/scripts/component-layout-governance.js",
+ "script": "component-layout-governance",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": "tools/scripts, v2, tools/config/component-layout-profile.json",
+ "owner": "docs",
+ "needs": "E-C1, R-R14",
+ "purpose_statement": "Component layout governance validator — checks v2 page layouts against approved component contracts",
+ "pipeline_declared": "P5, P6",
+ "usage": "node tools/scripts/component-layout-governance.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script component-layout-governance\n * @category validator\n * @purpose qa:repo-health\n * @scope tools/scripts, v2, tools/config/component-layout-profile.json\n * @owner docs\n * @needs E-C1, R-R14\n * @purpose-statement Component layout governance validator — checks v2 page layouts against approved component contracts\n * @pipeline P5, P6\n * @usage node tools/scripts/component-layout-governance.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst STAGE_ID = 'component-layout-governance';\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_OUTPUT_DIR = 'tasks/reports/repo-ops';\nconst DEFAULT_PROFILE_PATH = 'tools/config/component-layout-profile.json';\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction parseArgs(argv) {\n const out = {\n scope: 'full',\n outputDir: DEFAULT_OUTPUT_DIR,\n profilePath: DEFAULT_PROFILE_PATH\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--scope') {\n out.scope = String(argv[i + 1] || out.scope).trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--scope=')) {\n out.scope = token.slice('--scope='.length).trim() || out.scope;\n continue;\n }\n if (token === '--output-dir') {\n out.outputDir = String(argv[i + 1] || out.outputDir).trim() || out.outputDir;\n i += 1;\n continue;\n }\n if (token.startsWith('--output-dir=')) {\n out.outputDir = token.slice('--output-dir='.length).trim() || out.outputDir;\n continue;\n }\n if (token === '--profile') {\n out.profilePath = String(argv[i + 1] || out.profilePath).trim() || out.profilePath;\n i += 1;\n continue;\n }\n if (token.startsWith('--profile=')) {\n out.profilePath = token.slice('--profile='.length).trim() || out.profilePath;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!['changed', 'full'].includes(out.scope)) {\n throw new Error(`Invalid --scope: ${out.scope}`);\n }\n\n return out;\n}\n\nfunction readJsonFile(repoPath) {\n return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8'));\n}\n\nfunction shouldExclude(relPath) {\n const rel = toPosix(relPath);\n if (!rel.startsWith('v2/')) return true;\n if (!/\\.mdx$/i.test(rel)) return true;\n if (rel.startsWith('v2/es/') || rel.startsWith('v2/fr/') || rel.startsWith('v2/cn/')) return true;\n if (rel.startsWith('v2/internal/')) return true;\n if (rel.includes('/x-')) return true;\n if (rel.includes('/_contextData_/') || rel.includes('/_context_data_/')) return true;\n if (rel.includes('/_tests-to-delete/') || rel.includes('/_move_me/')) return true;\n if (rel.endsWith('todo.mdx') || rel.endsWith('NOTES_V2.md')) return true;\n return false;\n}\n\nfunction walkFiles(dirPath, out = []) {\n if (!fs.existsSync(dirPath)) return out;\n\n const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n for (const entry of entries) {\n const fullPath = path.join(dirPath, entry.name);\n const relPath = toPosix(path.relative(REPO_ROOT, fullPath));\n\n if (entry.isDirectory()) {\n if (entry.name === '.git' || entry.name === 'node_modules') continue;\n walkFiles(fullPath, out);\n continue;\n }\n\n if (shouldExclude(relPath)) continue;\n out.push({ absPath: fullPath, relPath });\n }\n\n return out;\n}\n\nfunction getChangedFiles() {\n try {\n const output = execSync('git diff --name-only --diff-filter=ACMR HEAD', {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n\n return output\n .split('\\n')\n .map((line) => toPosix(line.trim()))\n .filter(Boolean)\n .filter((line) => !shouldExclude(line))\n .map((line) => ({ relPath: line, absPath: path.join(REPO_ROOT, line) }));\n } catch (_error) {\n return [];\n }\n}\n\nfunction normalizeHeading(value) {\n return String(value || '')\n .replace(/[`*_~]/g, '')\n .replace(/<[^>]+>/g, '')\n .replace(/\\s+/g, ' ')\n .trim()\n .toLowerCase();\n}\n\nfunction extractHeadings(content) {\n const lines = String(content || '').split('\\n');\n const headings = [];\n\n lines.forEach((line) => {\n const match = line.match(/^#{1,6}\\s+(.+)$/);\n if (!match) return;\n headings.push(normalizeHeading(match[1]));\n });\n\n return headings;\n}\n\nfunction extractComponents(content) {\n const names = new Set();\n const regex = /<([A-Z][A-Za-z0-9]*)\\b/g;\n let match = regex.exec(content);\n\n while (match) {\n names.add(match[1]);\n match = regex.exec(content);\n }\n\n return [...names].sort();\n}\n\nfunction findPageType(relPath, pageTypes) {\n const lowerPath = String(relPath || '').toLowerCase();\n\n for (const pageType of pageTypes) {\n const patterns = Array.isArray(pageType?.match?.path_contains) ? pageType.match.path_contains : [];\n const matched = patterns.some((pattern) => lowerPath.includes(String(pattern || '').toLowerCase()));\n if (matched) return pageType;\n }\n\n return null;\n}\n\nfunction addIssue(issues, issue) {\n issues.push({\n id: issue.id,\n title: issue.title,\n severity: issue.severity,\n evidence: issue.evidence,\n recommendation: issue.recommendation,\n path: issue.path || '',\n line: Number.isFinite(Number(issue.line)) ? Number(issue.line) : 1\n });\n}\n\nfunction summarize(issues) {\n const summary = {\n critical: 0,\n high: 0,\n medium: 0,\n low: 0,\n info: 0,\n total: issues.length\n };\n\n for (const issue of issues) {\n if (Object.prototype.hasOwnProperty.call(summary, issue.severity)) {\n summary[issue.severity] += 1;\n }\n }\n\n return summary;\n}\n\nfunction analyzeFile(issues, file, pageType, governedComponents) {\n const content = fs.readFileSync(file.absPath, 'utf8');\n const headings = extractHeadings(content);\n const components = extractComponents(content);\n\n const requiredSections = Array.isArray(pageType.required_sections) ? pageType.required_sections : [];\n requiredSections.forEach((section) => {\n const needle = normalizeHeading(section);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-schedule",
+ "caller": ".github/workflows/content-health.yml",
+ "workflow": "Content Health Check",
+ "pipeline": "P5",
+ "cron": "0 6 * * 1"
+ },
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/content-health.yml",
+ "workflow": "Content Health Check",
+ "pipeline": "P6"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "audit:component-layout"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/${STAGE_ID}.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/${STAGE_ID}.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/${STAGE_ID}.json, tools/scripts/${STAGE_ID}.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P5 (Content Health Check cron 0 6 * * 1); P6 (Content Health Check); manual (npm script: audit:component-layout)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P5"
+ }
+ ],
+ "count": 7
+ },
+ "P6": {
+ "label": "P6 - On-demand",
+ "scripts": [
+ {
+ "path": "tools/scripts/snippets/generate-seo.js",
+ "script": "generate-seo",
+ "category": "generator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "SEO generator — generates SEO metadata (title, description, keywords) for v2 pages from content analysis",
+ "pipeline_declared": "P6 (on-demand, SEO refresh)",
+ "usage": "node tools/scripts/snippets/generate-seo.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-seo\n * @category generator\n * @purpose feature:seo\n * @scope tools/scripts\n * @owner docs\n * @needs E-R19, F-R7\n * @purpose-statement SEO generator — generates SEO metadata (title, description, keywords) for v2 pages from content analysis\n * @pipeline P6 (on-demand, SEO refresh)\n * @usage node tools/scripts/snippets/generate-seo.js [flags]\n */\n/**\n * SEO Generator for Livepeer Documentation\n *\n * Automatically generates and updates SEO and AEO (Answer Engine Optimization)\n * metadata for MDX documentation pages:\n * - keywords: Generated from file path, title, and content\n * - description: Generated from first paragraph when missing (AEO: helps LLMs/snippets)\n * - og:image / twitter:image: Uses default or domain-specific images\n *\n * AEO = optimizing for AI/answer engines (structured metadata, clear summaries).\n *\n * Usage: node tools/scripts/snippets/generate-seo.js [--dry-run] [--file=path/to/file.mdx]\n */\n\nconst fs = require(\"fs\");\nconst path = require(\"path\");\n\n// Configuration\nconst PAGES_DIRS = [\n path.join(__dirname, \"../../v2/pages\"),\n path.join(__dirname, \"../../v2\"),\n].filter((candidate) => fs.existsSync(candidate));\nconst DEFAULT_SOCIAL_IMAGE =\n \"/snippets/assets/social/livepeer-social-preview.jpg\";\n\n// Domain-specific images (can be expanded)\nconst DOMAIN_IMAGES = {\n home: \"/snippets/assets/domain/00_HOME/social-preview-home.jpg\",\n about: \"/snippets/assets/domain/01_ABOUT/social-preview-about.jpg\",\n community: \"/snippets/assets/domain/03_COMMUNITY/social-preview-community.jpg\",\n developers:\n \"/snippets/assets/domain/02_DEVELOPERS/social-preview-developers.jpg\",\n gateways:\n \"/snippets/assets/domain/04_GATEWAYS/social-preview-gateways.jpg\",\n orchestrators:\n \"/snippets/assets/domain/05_ORCHESTRATORS/social-preview-orchestrators.jpg\",\n lpt: \"/snippets/assets/domain/06_DELEGATORS/social-preview-delegators.jpg\",\n resources: \"/snippets/assets/domain/07_RESOURCES/social-preview-resources.jpg\",\n internal: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\",\n solutions: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\",\n deprecated: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\",\n experimental: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\",\n notes: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\",\n \"00_home\": \"/snippets/assets/domain/00_HOME/social-preview-home.jpg\",\n \"01_about\": \"/snippets/assets/domain/01_ABOUT/social-preview-about.jpg\",\n \"02_community\":\n \"/snippets/assets/domain/03_COMMUNITY/social-preview-community.jpg\",\n \"03_developers\":\n \"/snippets/assets/domain/02_DEVELOPERS/social-preview-developers.jpg\",\n \"04_gateways\":\n \"/snippets/assets/domain/04_GATEWAYS/social-preview-gateways.jpg\",\n \"05_orchestrators\":\n \"/snippets/assets/domain/05_ORCHESTRATORS/social-preview-orchestrators.jpg\",\n \"06_lptoken\":\n \"/snippets/assets/domain/06_DELEGATORS/social-preview-delegators.jpg\",\n \"07_resources\":\n \"/snippets/assets/domain/07_RESOURCES/social-preview-resources.jpg\",\n};\n\n// Parse command line arguments\nconst args = process.argv.slice(2);\nconst isDryRun = args.includes(\"--dry-run\");\nconst specificFile = args\n .find((arg) => arg.startsWith(\"--file=\"))\n ?.split(\"=\")[1];\n\n/**\n * Extract frontmatter from MDX content\n * Handles broken YAML like og: 'image': '' by skipping invalid lines\n */\nfunction extractFrontmatter(content) {\n const match = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n if (!match) return { frontmatter: {}, content, hasYaml: false };\n\n const yamlContent = match[1];\n const restContent = content.slice(match[0].length);\n\n // Parse YAML-like frontmatter\n const frontmatter = {};\n const lines = yamlContent.split(\"\\n\");\n\n for (let i = 0; i < lines.length; i++) {\n const line = lines[i].trim();\n if (!line) continue;\n\n // Skip broken YAML lines like: og: 'image': '' or 'og:image': ''\n // Check for multiple colons that aren't part of a valid quoted key\n const colonCount = (line.match(/:/g) || []).length;\n if (colonCount > 1) {\n // Valid format: \"og:image\": \"value\" or \"twitter:image\": \"value\"\n const validQuotedKey = line.match(/^\"([^\"]+)\":\\s*\"([^\"]*)\"/);\n if (!validQuotedKey) {\n console.log(`⚠️ Skipping invalid YAML line: ${line}`);\n continue; // Skip this broken line\n }\n // Parse the valid quoted key\n const [, key, value] = validQuotedKey;\n frontmatter[key] = value;\n continue;\n }\n\n // Handle key: value or key: [array]\n const colonIndex = line.indexOf(\":\");\n if (colonIndex === -1) continue;\n\n const key = line\n .slice(0, colonIndex)\n .trim()\n .replace(/^[\"']|[\"']$/g, \"\");\n let value = line.slice(colonIndex + 1).trim();\n\n // Handle arrays\n if (value.startsWith(\"[\") && value.endsWith(\"]\")) {\n value = value\n .slice(1, -1)\n .split(\",\")\n .map((v) => v.trim().replace(/^[\"']|[\"']$/g, \"\"));\n } else {\n value = value.replace(/^[\"']|[\"']$/g, \"\");\n }\n\n frontmatter[key] = value;\n }\n\n return { frontmatter, content: restContent, hasYaml: true, yamlContent };\n}\n\n/**\n * Generate keywords from file path and content\n */\nfunction generateKeywords(filePath, frontmatter, content) {\n const keywords = new Set();\n\n // Add 'livepeer' as base keyword\n keywords.add(\"livepeer\");\n\n // Extract from path - only use meaningful parts\n const pathParts = filePath.split(\"/\").filter((p) => {\n // Filter out system paths and keep only meaningful directory/file names\n const lower = p.toLowerCase();\n return (\n p &&\n !lower.includes(\"users\") &&\n !lower.includes(\"documents\") &&\n !lower.includes(\"livepeer-docs\") &&\n !lower.includes(\"current\") &&\n p !== \"v2\" &&\n p !== \"pages\" &&\n p !== \"tests\"\n );\n });\n pathParts.forEach((part) => {\n // Remove number prefixes and file extensions\n const cleaned = part\n .replace(/^\\d+_/, \"\")\n .replace(/\\.mdx?$/, \"\")\n .replace(/-/g, \" \")\n .toLowerCase();\n // Skip common words and user-specific paths\n if (\n cleaned &&\n cleaned.length > 2 &&\n ![\"readme\", \"summary\"].includes(cleaned)\n ) {\n keywords.add(cleaned);\n }\n });\n\n // Extract from title\n if (frontmatter.title) {\n const titleWords = frontmatter.title\n .toLowerCase()\n .replace(/[^\\w\\s]/g, \" \")\n .split(/\\s+/)\n .filter(\n (w) =>\n w.length > 3 && ![\"this\", \"that\", \"with\", \"from\", \"have\"].includes(w),\n );\n titleWords.forEach((w) => keywords.add(w));\n }\n\n // Extract from description\n if (frontmatter.description) {\n const descWords = frontmatter.description\n .toLowerCase()\n .replace(/[^\\w\\s]/g, \" \")\n .split(/\\s+/)\n .filter(\n (w) =>\n w.length > 4 &&\n ![\"this\", \"that\", \"with\", \"from\", \"have\", \"about\"].includes(w),\n );\n descWords.slice(0, 3).forEach((w) => keywords.add(w));\n }\n\n // Limit to 10 keywords\n return Array.from(keywords).slice(0, 10);\n}\n\n/**\n * Generate AEO-friendly description from content when missing.\n * Uses first paragraph or first heading + following text; keeps to 50–160 chars for SEO/AEO.\n */\nfunction generateDescription(content) {\n if (!content || typeof content !== \"string\") return null;\n // Strip frontmatter\n const withoutFrontmatter = content.replace(/^---\\n[\\s\\S]*?\\n---\\n?/, \"\");\n // First block of text: lines that are not empty and not starting with # or < or import",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/seo-refresh.yml",
+ "workflow": "SEO Metadata Refresh",
+ "pipeline": "P6"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "generate-seo"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "generate-seo:dry-run"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P6 (SEO Metadata Refresh); manual (npm script: generate-seo); manual (npm script: generate-seo:dry-run)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P6"
+ },
+ {
+ "path": "tools/scripts/i18n/generate-localized-docs-json.js",
+ "script": "generate-localized-docs-json",
+ "category": "generator",
+ "purpose": "feature:translation",
+ "scope": "docs.json, tools/scripts/i18n",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Locale docs.json generator — produces localised docs.json variants from route-map and source docs.json",
+ "pipeline_declared": "P6 (on-demand, translation pipeline)",
+ "usage": "node tools/scripts/i18n/generate-localized-docs-json.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-localized-docs-json\n * @category generator\n * @purpose feature:translation\n * @scope docs.json, tools/scripts/i18n\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Locale docs.json generator — produces localised docs.json variants from route-map and source docs.json\n * @pipeline P6 (on-demand, translation pipeline)\n * @usage node tools/scripts/i18n/generate-localized-docs-json.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { parseCommonCliArgs, loadI18nConfig, buildRuntimeOptions } = require('./lib/config');\nconst { getRepoRoot, readJson, writeJson, writeTextIfChanged } = require('./lib/common');\nconst { createTranslator } = require('./lib/providers');\nconst { generateLocalizedDocsJson } = require('./lib/docs-json-localizer');\nconst { collectExistingLocalizedRouteMapEntries } = require('./lib/docs-routes');\n\nfunction printHelp() {\n console.log(\n [\n 'Usage: node tools/scripts/i18n/generate-localized-docs-json.js [options]',\n '',\n 'Options:',\n ' --languages Target languages (default from config)',\n ' --route-map Route-map artifact from translate-docs.js',\n ' --provider openrouter | mock',\n ' --write Update docs.json in place',\n ' --dry-run Compute report only (no write)',\n ' --allow-mock-write Allow mock provider in write mode (dangerous; testing only)',\n ' --report-json Write docs.json generation report',\n ' --config Alternate i18n config JSON',\n ' --help, -h Show this help'\n ].join('\\n')\n );\n}\n\nfunction assertMockWriteAllowed({ translator, runtime, config, cliArgs }) {\n const writeMode = Boolean(cliArgs.write && !runtime.dryRun);\n if (!writeMode) return;\n if (translator?.name !== 'mock') return;\n if (runtime.allowMockWrite) return;\n if (config?.qualityGates?.blockMockProviderWrites === false) return;\n throw new Error(\n 'Refusing to write docs.json with mock provider. Use --dry-run for mock testing or pass --allow-mock-write only for deliberate fixture generation.'\n );\n}\n\nfunction loadRouteMapEntries(repoRoot, routeMapPath, config, runtime) {\n if (routeMapPath) {\n const abs = path.resolve(repoRoot, routeMapPath);\n const parsed = readJson(abs);\n return {\n path: abs,\n entries: Array.isArray(parsed.entries) ? parsed.entries : [],\n metadata: {\n provider: parsed.provider || null,\n runtime: parsed.runtime || null,\n scope: parsed.scope || null,\n warnings: Array.isArray(parsed.warnings) ? parsed.warnings : []\n }\n };\n }\n return {\n path: '',\n entries: collectExistingLocalizedRouteMapEntries(repoRoot, config.generatedRoot, {\n generatedPathStyle: config.generatedPathStyle,\n sourceRoot: config.sourceRoot,\n knownLanguages: runtime.languages\n }),\n metadata: {\n provider: null,\n runtime: null,\n scope: null,\n warnings: []\n }\n };\n}\n\nasync function run(argv = process.argv.slice(2)) {\n const cliArgs = parseCommonCliArgs(argv);\n if (cliArgs.help || argv.includes('--help') || argv.includes('-h')) {\n printHelp();\n return { help: true };\n }\n const { repoRoot, configPath, config } = loadI18nConfig({\n repoRoot: getRepoRoot(),\n configPath: cliArgs.configPath || undefined\n });\n const runtime = buildRuntimeOptions(cliArgs, config);\n const translator = createTranslator({ config, providerNameOverride: runtime.providerNameOverride });\n assertMockWriteAllowed({ translator, runtime, config, cliArgs });\n const docsJsonPath = path.join(repoRoot, 'docs.json');\n const docsJson = readJson(docsJsonPath);\n const routeMap = loadRouteMapEntries(repoRoot, cliArgs.routeMapPath, config, runtime);\n const result = await generateLocalizedDocsJson({\n docsJson,\n repoRoot,\n targetLanguages: runtime.languages,\n translator,\n translationRules: config.translationRules || {},\n routeMapEntries: routeMap.entries,\n routeMapMetadata: routeMap.metadata || {},\n qualityGates: config.qualityGates || {},\n reporting: config.reporting || {},\n runtime,\n languageCodeMap: config.languageCodeMap || {},\n writeMode: Boolean(cliArgs.write && !runtime.dryRun),\n allowMockWrite: runtime.allowMockWrite\n });\n\n const nextText = `${JSON.stringify(result.docsJson, null, 2)}\\n`;\n let changed = false;\n if (cliArgs.write && !runtime.dryRun) {\n changed = writeTextIfChanged(docsJsonPath, nextText);\n }\n\n const report = {\n generatedAt: new Date().toISOString(),\n repoRoot,\n configPath,\n docsJsonPath,\n routeMapPath: routeMap.path,\n dryRun: runtime.dryRun || !cliArgs.write,\n wroteDocsJson: Boolean(cliArgs.write && !runtime.dryRun && changed),\n provider: {\n name: translator.name,\n mode: translator.name\n },\n warnings: result.report.warnings || [],\n perLanguage: result.report.perLanguage\n };\n\n if (runtime.reportJsonPath) {\n writeJson(path.resolve(repoRoot, runtime.reportJsonPath), report);\n }\n\n console.log(\n [\n 'i18n generate-localized-docs-json summary',\n `- languages: ${runtime.languages.join(', ')}`,\n `- provider: ${translator.name}`,\n `- route-map entries: ${routeMap.entries.length}`,\n `- write mode: ${cliArgs.write && !runtime.dryRun ? 'enabled' : 'disabled'}`,\n `- docs.json changed: ${changed ? 'yes' : 'no'}`\n ].join('\\n')\n );\n\n return report;\n}\n\nif (require.main === module) {\n run().catch((error) => {\n console.error(`❌ ${error.message}`);\n process.exit(1);\n });\n}\n\nmodule.exports = { run };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/translate-docs.yml",
+ "workflow": "Docs Translation Pipeline",
+ "pipeline": "P6"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/cli-guardrails.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "i18n:docs-json"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P6 (Docs Translation Pipeline); indirect via tools/scripts/i18n/test/cli-guardrails.test.js; manual (npm script: i18n:docs-json)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P6"
+ },
+ {
+ "path": "tools/scripts/i18n/translate-docs.js",
+ "script": "translate-docs",
+ "category": "generator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts/i18n, docs.json, v2",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Translation generator — translates v2 MDX pages to target languages via OpenRouter API",
+ "pipeline_declared": "P6 (on-demand, translation pipeline)",
+ "usage": "node tools/scripts/i18n/translate-docs.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script translate-docs\n * @category generator\n * @purpose feature:translation\n * @scope tools/scripts/i18n, docs.json, v2\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Translation generator — translates v2 MDX pages to target languages via OpenRouter API\n * @pipeline P6 (on-demand, translation pipeline)\n * @usage node tools/scripts/i18n/translate-docs.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst { buildRuntimeOptions, loadI18nConfig, parseCommonCliArgs } = require('./lib/config');\nconst { buildV2EnglishRouteInventory, collectExistingLocalizedRouteMapEntries, selectScopeItems } = require('./lib/docs-routes');\nconst { parseMdxFileWithFrontmatter, translateFrontmatterFields } = require('./lib/frontmatter');\nconst { rewriteInternalLinksInBody, rewriteInternalLinksInJsx, translateMdxBody } = require('./lib/mdx-translate');\nconst { repoFileRelToLocalizedFileRel, normalizeRouteKey } = require('./lib/path-utils');\nconst {\n buildProvenanceComment,\n classifyLocalizedArtifactProvenance,\n injectOrReplaceProvenanceComment,\n parseProvenanceComment,\n sha256\n} = require('./lib/provenance');\nconst { hasGeneratedNote, removeGeneratedNotes } = require('../../lib/generated-file-banners');\nconst { createTranslator } = require('./lib/providers');\nconst { getRepoRoot, normalizeRepoRel, writeJson, writeTextIfChanged } = require('./lib/common');\n\nfunction printHelp() {\n console.log(\n [\n 'Usage: node tools/scripts/i18n/translate-docs.js [options]',\n '',\n 'Options:',\n ' --languages Target languages (default from tools/i18n/config.json)',\n ' --scope-mode changed_since_ref | prefixes | paths_file | full_v2_nav',\n ' --base-ref Base ref for changed_since_ref mode',\n ' --prefixes Repo prefixes for prefixes mode',\n ' --paths-file File containing explicit routes/files (paths_file mode)',\n ' --max-pages Max selected pages to process',\n ' --max-concurrency Max concurrent source files to translate (capped at 5)',\n ' --provider openrouter | mock',\n ' --dry-run Do not write localized files',\n ' --force Retranslate even when source hash matches',\n ' --allow-mock-write Allow mock provider in non-dry runs (dangerous; testing only)',\n ' --route-map Write route-map artifact JSON',\n ' --report-json Write run report JSON',\n ' --cleanup-only Skip translation and only run cleanup/link rewrite',\n ' --rewrite-links Rewrite internal links for localized files (default true in cleanup-only)',\n ' --rewrite-scope all | moved (default all for cleanup-only)',\n ' --config Alternate i18n config JSON',\n ' --help, -h Show this help'\n ].join('\\n')\n );\n}\n\nfunction isMockWriteBlocked({ translator, runtime, config }) {\n if (translator?.name !== 'mock') return false;\n if (runtime.dryRun) return false;\n if (runtime.allowMockWrite) return false;\n if (config?.qualityGates?.blockMockProviderWrites === false) return false;\n return true;\n}\n\nfunction assertMockWriteAllowed({ translator, runtime, config, action }) {\n if (!isMockWriteBlocked({ translator, runtime, config })) return;\n throw new Error(\n [\n `Refusing to run ${action} with mock provider in write mode.`,\n 'The mock provider prefixes content (for smoke tests) and can contaminate localized MDX/docs.json.',\n 'Use --dry-run for mock provider smoke tests, or pass --allow-mock-write only for deliberate fixture generation.'\n ].join(' ')\n );\n}\n\nfunction artifactClassForProvider(providerName) {\n return String(providerName || '').trim().toLowerCase() === 'mock' ? 'translated_mock' : 'translated_real';\n}\n\nfunction requestedLanguageForEffective(runtime, effectiveLanguage) {\n const hit = (runtime.languageAliasesApplied || []).find((entry) => entry.effectiveLanguage === effectiveLanguage);\n return hit?.requestedLanguage || effectiveLanguage;\n}\n\nfunction buildRouteMapIndex(entries) {\n const index = new Map();\n for (const entry of entries) {\n const sourceRoute = normalizeRouteKey(entry.sourceRoute);\n const language = String(entry.effectiveLanguage || entry.language || '').trim();\n const localizedRoute = normalizeRouteKey(entry.localizedRoute);\n if (!sourceRoute || !language || !localizedRoute) continue;\n if (!index.has(sourceRoute)) index.set(sourceRoute, new Map());\n index.get(sourceRoute).set(language, localizedRoute);\n }\n return index;\n}\n\nfunction normalizeFileKey(value) {\n return normalizeRepoRel(String(value || '').replace(/\\\\/g, '/'));\n}\n\nfunction normalizeMaxConcurrency(value, fallback = 5) {\n const parsed = Number(value);\n if (!Number.isFinite(parsed) || parsed <= 0) return fallback;\n return Math.min(parsed, fallback);\n}\n\nfunction chunkArray(items, size) {\n if (!Array.isArray(items) || items.length === 0) return [];\n const normalized = normalizeMaxConcurrency(size);\n const batches = [];\n for (let i = 0; i < items.length; i += normalized) {\n batches.push(items.slice(i, i + normalized));\n }\n return batches;\n}\n\nfunction isQuarantinedLocalizedFile(localizedFile) {\n const normalized = normalizeFileKey(localizedFile);\n return /^v2\\/[^/]+\\/group\\/x-orphaned\\//.test(normalized);\n}\n\nfunction resolveSolutionsEquivalent(localizedFile) {\n const normalized = normalizeFileKey(localizedFile);\n if (!normalized.includes('/platforms/')) return '';\n let next = normalized.replace('/platforms/', '/solutions/');\n if (next.endsWith('/ecosystem-products.mdx')) {\n next = next.replace('/ecosystem-products.mdx', '/solution-providers.mdx');\n }\n if (next.endsWith('/ecosystem-products.md')) {\n next = next.replace('/ecosystem-products.md', '/solution-providers.md');\n }\n return next;\n}\n\nfunction resolveOrphanQuarantinePath(localizedFile, language) {\n const normalized = normalizeFileKey(localizedFile);\n if (!normalized.startsWith('v2/')) return '';\n const parts = normalized.split('/');\n const lang = parts[1] || String(language || '').trim();\n const suffix = parts.slice(2).join('/');\n if (!lang || !suffix) return '';\n return `v2/${lang}/group/x-orphaned/${suffix}`;\n}\n\nfunction resolveQuarantineBasePath(localizedFile, language) {\n const normalized = normalizeFileKey(localizedFile);\n if (isQuarantinedLocalizedFile(normalized)) return normalized;\n return resolveOrphanQuarantinePath(normalized, language);\n}\n\nfunction moveLocalizedToQuarantine({ repoRoot, localizedFile, language, reason }) {\n const normalized = normalizeFileKey(localizedFile);\n const absPath = path.join(repoRoot, normalized);\n if (!fs.existsSync(absPath)) {\n return { movedTo: '', warning: `${reason} (missing file): ${localizedFile}` };\n }\n const basePath = resolveQuarantineBasePath(normalized, language);\n if (!basePath) {\n return { movedTo: '', warning: `${reason} (invalid quarantine path): ${localizedFile}` };\n }\n const raw = fs.readFileSync(absPath, 'utf8');\n const hash = sha256(`${normalized}:${raw}`).slice(0, 8);\n let target = basePath;\n const targetAbs = path.join(repoRoot, target);\n const hadCollision = fs.existsSync(targetAbs);\n fs.mkdirSync(path.dirname(targetAbs), { recursive: true });\n const forceFlag = hadCollision ? '-f ' : '';\n execSync(`git -C ${JSON.stringify(repoRoot)} mv ${forceFlag}${JSON.stringify(normalized)} ${JSON.stringify(target)}`, {\n stdio: 'ignore'\n });\n const collisionNote = hadCollision ? ` (replaced existing ${hash})` : '';\n return { movedTo: target, warning: `${reason}: ${localizedFile} -> ${target}${collisionNote}` };\n}\n\nfunction findRenameTarget(repoRoot, sourcePath) {\n if (!sourcePath) return '';\n try {\n const output = execSync(\n `git -C ${JSON.stringify(repoRoot)} log --follow --name-status --diff-filter=R -- ${JSON.stringify(sourcePath)}`,\n { encoding: 'utf8' }\n );\n for (const line of output.split('\\n')) {\n if (!line.startsWith('R')) continue;\n const parts = line.split('\\t');\n if (parts.length >= 3) {\n return normalizeRepoRel(parts[2]);\n }\n }\n } catch (_err) {\n return '';\n }\n return '';\n}\n\nconst STATIC_RENAME_MAP = new Map(\n [\n [\n 'v2/gateways/run-a-gateway/quickstart/get-AI-to-setup-the-gateway.mdx',\n 'v2/gateways/quickstart/AI-prompt.mdx'\n ],\n [\n 'v2/gateways/run-a-gateway/quickstart/quickstart-a-gateway.mdx',\n 'v2/gateways/quickstart/gateway-setup.mdx'\n ],\n [\n 'v2/gateways/references/artibtrum-exchanges.mdx',\n 'v2/gateways/references/arbitrum-exchanges.mdx'\n ],\n [\n 'v2/developers/livepeer-real-time-video/video-streaming-on-livepeer/README.mdx',\n 'v2/developers/quickstart/video/video-streaming.mdx'\n ]\n ].map(([from, to]) => [normalizeRepoRel(from), normalizeRepoRel(to)])\n);\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/translate-docs.yml",
+ "workflow": "Docs Translation Pipeline",
+ "pipeline": "P6"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/cli-guardrails.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "i18n:translate"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeJson"
+ }
+ ],
+ "outputs_display": "",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P6 (Docs Translation Pipeline); indirect via tools/scripts/i18n/test/cli-guardrails.test.js; manual (npm script: i18n:translate)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P6"
+ },
+ {
+ "path": "tools/scripts/i18n/validate-generated.js",
+ "script": "validate-generated",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts/i18n, v2",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Generated localisation validator — checks generated translated MDX files and route-map outputs for integrity",
+ "pipeline_declared": "P6",
+ "usage": "node tools/scripts/i18n/validate-generated.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script validate-generated\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts/i18n, v2\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Generated localisation validator — checks generated translated MDX files and route-map outputs for integrity\n * @pipeline P6\n * @usage node tools/scripts/i18n/validate-generated.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { parseCommonCliArgs, loadI18nConfig, buildRuntimeOptions } = require('./lib/config');\nconst { getRepoRoot, readJson, writeJson } = require('./lib/common');\nconst { collectExistingLocalizedRouteMapEntries } = require('./lib/docs-routes');\nconst { parseMdxFileWithFrontmatter } = require('./lib/frontmatter');\nconst { parseMdx } = require('./lib/mdx-parser');\nconst { parseProvenanceComment, classifyLocalizedArtifactProvenance } = require('./lib/provenance');\n\nfunction printHelp() {\n console.log(\n [\n 'Usage: node tools/scripts/i18n/validate-generated.js [options]',\n '',\n 'Options:',\n ' --languages Languages to validate (default from config)',\n ' --route-map Validate only entries from route-map artifact',\n ' --report-json Write validation report JSON',\n ' --fail-on-mock-artifacts Exit non-zero if generated files contain mock provenance',\n ' --fail-on-missing-provenance Exit non-zero if generated files are missing codex-i18n provenance',\n ' --config Alternate i18n config JSON',\n ' --help, -h Show this help'\n ].join('\\n')\n );\n}\n\nfunction loadEntries(repoRoot, routeMapPath, config, runtime) {\n if (routeMapPath) {\n const abs = path.resolve(repoRoot, routeMapPath);\n const parsed = readJson(abs);\n return { path: abs, entries: Array.isArray(parsed.entries) ? parsed.entries : [] };\n }\n return {\n path: '',\n entries: collectExistingLocalizedRouteMapEntries(repoRoot, config.generatedRoot, {\n generatedPathStyle: config.generatedPathStyle,\n sourceRoot: config.sourceRoot,\n knownLanguages: runtime.languages\n })\n };\n}\n\nasync function run(argv = process.argv.slice(2)) {\n const cliArgs = parseCommonCliArgs(argv);\n if (cliArgs.help || argv.includes('--help') || argv.includes('-h')) {\n printHelp();\n return { help: true };\n }\n const { repoRoot, config } = loadI18nConfig({\n repoRoot: getRepoRoot(),\n configPath: cliArgs.configPath || undefined\n });\n const runtime = buildRuntimeOptions(cliArgs, config);\n const routeMap = loadEntries(repoRoot, cliArgs.routeMapPath, config, runtime);\n const languageSet = new Set(runtime.languages.length ? runtime.languages : config.targetLanguages);\n\n const entries = routeMap.entries.filter(\n (entry) =>\n languageSet.has(entry.language) &&\n ['translated', 'unchanged_write', 'skipped_up_to_date', 'existing'].includes(entry.status)\n );\n\n const report = {\n generatedAt: new Date().toISOString(),\n checked: 0,\n failures: [],\n mockArtifactsDetected: 0,\n artifactsMissingProvenance: 0,\n provenanceParseFailures: 0,\n samples: []\n };\n\n function pushSample(type, payload) {\n if (report.samples.length >= 20) return;\n report.samples.push({ type, ...payload });\n }\n\n for (const entry of entries) {\n const rel = entry.localizedFile || `${entry.localizedRoute}.mdx`;\n const abs = path.join(repoRoot, rel);\n report.checked += 1;\n try {\n const raw = fs.readFileSync(abs, 'utf8');\n const provenance = parseProvenanceComment(raw);\n const hasProvenanceMarker = raw.includes('codex-i18n:');\n if (!provenance) {\n if (hasProvenanceMarker) {\n report.provenanceParseFailures += 1;\n pushSample('provenance_parse_failure', { localizedFile: rel, language: entry.language });\n } else {\n report.artifactsMissingProvenance += 1;\n pushSample('missing_provenance', { localizedFile: rel, language: entry.language });\n }\n } else {\n const meta = classifyLocalizedArtifactProvenance(provenance);\n if (meta.artifactClass === 'translated_mock') {\n report.mockArtifactsDetected += 1;\n pushSample('mock_artifact', { localizedFile: rel, language: entry.language, provider: meta.provider });\n }\n }\n const parsed = parseMdxFileWithFrontmatter(raw);\n await parseMdx(parsed.body);\n } catch (error) {\n report.failures.push({\n localizedFile: rel,\n language: entry.language,\n sourceRoute: entry.sourceRoute,\n error: error.message\n });\n }\n }\n\n if (runtime.reportJsonPath) {\n writeJson(path.resolve(repoRoot, runtime.reportJsonPath), report);\n }\n\n console.log(\n [\n 'i18n validate-generated summary',\n `- checked: ${report.checked}`,\n `- failures: ${report.failures.length}`,\n `- mock artifacts: ${report.mockArtifactsDetected}`,\n `- missing provenance: ${report.artifactsMissingProvenance}`,\n `- provenance parse failures: ${report.provenanceParseFailures}`\n ].join('\\n')\n );\n\n if (report.failures.length > 0) {\n throw new Error(`Generated MDX validation failed for ${report.failures.length} file(s)`);\n }\n if (runtime.failOnMockArtifacts && report.mockArtifactsDetected > 0) {\n throw new Error(`Generated validation found ${report.mockArtifactsDetected} mock artifact(s)`);\n }\n if (runtime.failOnMissingProvenance && report.artifactsMissingProvenance > 0) {\n throw new Error(`Generated validation found ${report.artifactsMissingProvenance} file(s) missing provenance`);\n }\n\n return report;\n}\n\nif (require.main === module) {\n run().catch((error) => {\n console.error(`❌ ${error.message}`);\n process.exit(1);\n });\n}\n\nmodule.exports = { run };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/translate-docs.yml",
+ "workflow": "Docs Translation Pipeline",
+ "pipeline": "P6"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "i18n:validate"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P6 (Docs Translation Pipeline); manual (npm script: i18n:validate)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P6"
+ },
+ {
+ "path": "tools/scripts/style-and-language-homogenizer-en-gb.js",
+ "script": "style-and-language-homogenizer-en-gb",
+ "category": "remediator",
+ "purpose": "tooling:dev-tools",
+ "scope": "tools/scripts, v2, tools/config/style-language-profile-en-gb.json",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "EN-GB style homogeniser — finds and fixes American English spellings, style guide violations, and formatting inconsistencies across v2 content",
+ "pipeline_declared": "P6 (on-demand, repair)",
+ "usage": "node tools/scripts/style-and-language-homogenizer-en-gb.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script style-and-language-homogenizer-en-gb\n * @category remediator\n * @purpose tooling:dev-tools\n * @scope tools/scripts, v2, tools/config/style-language-profile-en-gb.json\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement EN-GB style homogeniser — finds and fixes American English spellings, style guide violations, and formatting inconsistencies across v2 content\n * @pipeline P6 (on-demand, repair)\n * @usage node tools/scripts/style-and-language-homogenizer-en-gb.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst STAGE_ID = 'style-and-language-homogenizer-en-gb';\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_OUTPUT_DIR = 'tasks/reports/repo-ops';\nconst DEFAULT_PROFILE_PATH = 'tools/config/style-language-profile-en-gb.json';\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction parseArgs(argv) {\n const out = {\n scope: 'full',\n outputDir: DEFAULT_OUTPUT_DIR,\n profilePath: DEFAULT_PROFILE_PATH\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--scope') {\n out.scope = String(argv[i + 1] || out.scope).trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--scope=')) {\n out.scope = token.slice('--scope='.length).trim() || out.scope;\n continue;\n }\n if (token === '--output-dir') {\n out.outputDir = String(argv[i + 1] || out.outputDir).trim() || out.outputDir;\n i += 1;\n continue;\n }\n if (token.startsWith('--output-dir=')) {\n out.outputDir = token.slice('--output-dir='.length).trim() || out.outputDir;\n continue;\n }\n if (token === '--profile') {\n out.profilePath = String(argv[i + 1] || out.profilePath).trim() || out.profilePath;\n i += 1;\n continue;\n }\n if (token.startsWith('--profile=')) {\n out.profilePath = token.slice('--profile='.length).trim() || out.profilePath;\n continue;\n }\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!['changed', 'full'].includes(out.scope)) {\n throw new Error(`Invalid --scope: ${out.scope}`);\n }\n\n return out;\n}\n\nfunction loadProfile(profilePath) {\n const absPath = path.resolve(REPO_ROOT, profilePath);\n return JSON.parse(fs.readFileSync(absPath, 'utf8'));\n}\n\nfunction addIssue(issues, issue) {\n issues.push({\n id: issue.id,\n title: issue.title,\n severity: issue.severity,\n evidence: issue.evidence,\n recommendation: issue.recommendation,\n path: issue.path || '',\n line: Number.isFinite(Number(issue.line)) ? Number(issue.line) : 1\n });\n}\n\nfunction summarize(issues) {\n const summary = {\n critical: 0,\n high: 0,\n medium: 0,\n low: 0,\n info: 0,\n total: issues.length\n };\n\n for (const issue of issues) {\n if (Object.prototype.hasOwnProperty.call(summary, issue.severity)) {\n summary[issue.severity] += 1;\n }\n }\n\n return summary;\n}\n\nfunction shouldExclude(relPath, profile) {\n const rel = toPosix(relPath);\n if (!rel.startsWith('v2/')) return true;\n\n const defaults = ['v2/es/', 'v2/fr/', 'v2/cn/', 'v2/internal/'];\n if (defaults.some((prefix) => rel.startsWith(prefix))) return true;\n if (rel.includes('/x-')) return true;\n\n const extraExcludes = Array.isArray(profile.exclude_globs) ? profile.exclude_globs : [];\n if (extraExcludes.some((glob) => glob.endsWith('/**') && rel.startsWith(glob.slice(0, -3)))) return true;\n\n return false;\n}\n\nfunction walkEnglishV2Files(profile, out = []) {\n const root = path.join(REPO_ROOT, 'v2');\n if (!fs.existsSync(root)) return out;\n\n function walk(dirPath) {\n const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n for (const entry of entries) {\n const fullPath = path.join(dirPath, entry.name);\n const relPath = toPosix(path.relative(REPO_ROOT, fullPath));\n\n if (entry.isDirectory()) {\n if (entry.name === '.git' || entry.name === 'node_modules') continue;\n walk(fullPath);\n continue;\n }\n\n if (!/\\.mdx$/i.test(entry.name)) continue;\n if (shouldExclude(relPath, profile)) continue;\n\n out.push({ absPath: fullPath, relPath });\n }\n }\n\n walk(root);\n return out;\n}\n\nfunction getChangedEnglishFiles(profile) {\n try {\n const output = execSync('git diff --name-only --diff-filter=ACMR HEAD', {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n\n return output\n .split('\\n')\n .map((line) => toPosix(line.trim()))\n .filter(Boolean)\n .filter((line) => line.startsWith('v2/'))\n .filter((line) => /\\.mdx$/i.test(line))\n .filter((line) => !shouldExclude(line, profile))\n .map((line) => ({ relPath: line, absPath: path.join(REPO_ROOT, line) }));\n } catch (_error) {\n return [];\n }\n}\n\nfunction getScannableLines(content) {\n const lines = String(content || '').split('\\n');\n const out = [];\n\n let inFrontmatter = lines[0] && lines[0].trim() === '---';\n let inCodeFence = false;\n\n lines.forEach((lineText, index) => {\n const trimmed = String(lineText || '').trim();\n\n if (inFrontmatter) {\n if (index > 0 && trimmed === '---') {\n inFrontmatter = false;\n }\n return;\n }\n\n if (/^```/.test(trimmed)) {\n inCodeFence = !inCodeFence;\n return;\n }\n\n if (inCodeFence) return;\n\n out.push({\n lineText,\n line: index + 1\n });\n });\n\n return out;\n}\n\nfunction shouldSkipLanguageLine(lineText) {\n const trimmed = String(lineText || '').trim();\n if (!trimmed) return true;\n if (trimmed.startsWith('import ') || trimmed.startsWith('export ')) return true;\n if (trimmed.startsWith('//')) return true;\n if (trimmed.includes('`')) return true;\n if (/\\[[^\\]]+\\]\\([^)]+\\)/.test(trimmed)) return true;\n if (/^<[^>]+>$/.test(trimmed)) return true;\n if (/^\\|.*\\|$/.test(trimmed)) return true;\n return false;\n}\n\nfunction scanForbiddenTerms(issues, file, terms) {\n if (!Array.isArray(terms) || terms.length === 0) return;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "workflow-dispatch",
+ "caller": ".github/workflows/style-homogenise.yml",
+ "workflow": "EN-GB Style Homogenisation",
+ "pipeline": "P6"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "audit:language-en-gb"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/${STAGE_ID}.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/${STAGE_ID}.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/${STAGE_ID}.json, tools/scripts/${STAGE_ID}.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "P6 (EN-GB Style Homogenisation); manual (npm script: audit:language-en-gb)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "P6"
+ }
+ ],
+ "count": 5
+ },
+ "Indirect": {
+ "label": "Indirect - Library",
+ "scripts": [
+ {
+ "path": "tools/scripts/dev/seo-generator-safe.js",
+ "script": "seo-generator-safe",
+ "category": "generator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "Safe SEO generator — generates SEO metadata with dry-run and rollback safety",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/dev/seo-generator-safe.js [flags]",
+ "header": "/**\n * @script seo-generator-safe\n * @category generator\n * @purpose feature:seo\n * @scope tools/scripts\n * @owner docs\n * @needs E-R19, F-R7\n * @purpose-statement Safe SEO generator — generates SEO metadata with dry-run and rollback safety\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/dev/seo-generator-safe.js [flags]\n */\nconst fs = require(\"fs\");\nconst path = require(\"path\");\nconst { execSync } = require(\"child_process\");\n\n/**\n * SAFE SEO Generator Script\n *\n * This script ONLY modifies:\n * 1. keywords field - adds if missing, updates if present\n * 2. og:image field - fixes broken syntax, adds if missing\n *\n * It PRESERVES:\n * - All other frontmatter fields (title, description, sidebarTitle, etc.)\n * - All content below frontmatter\n * - Original formatting and structure\n */\n\n// Configuration\nconst DRY_RUN = true; // Set to false to actually write files\nconst VERBOSE = true;\n\nfunction extractFrontmatter(content) {\n const match = content.match(/^---\\n([\\s\\S]*?)\\n---\\n([\\s\\S]*)$/);\n if (!match) {\n return null;\n }\n return {\n frontmatter: match[1],\n body: match[2],\n fullMatch: match[0],\n };\n}\n\nfunction generateKeywords(filePath, currentKeywords) {\n // Extract meaningful keywords from file path and name\n const parts = filePath.split(\"/\").filter((p) => p && !p.match(/^\\d+_/));\n const fileName = path.basename(filePath, \".mdx\");\n\n const keywords = new Set();\n\n // Add existing keywords if any\n if (currentKeywords && Array.isArray(currentKeywords)) {\n currentKeywords.forEach((k) => keywords.add(k));\n }\n\n // Add path-based keywords\n parts.forEach((part) => {\n const cleaned = part.replace(/[-_]/g, \" \").toLowerCase();\n if (cleaned && cleaned !== \"pages\" && cleaned !== \"mdx\") {\n keywords.add(cleaned);\n }\n });\n\n // Add filename keywords\n const fileKeywords = fileName.replace(/[-_]/g, \" \").toLowerCase();\n if (fileKeywords && fileKeywords !== \"readme\" && fileKeywords !== \"index\") {\n keywords.add(fileKeywords);\n }\n\n return Array.from(keywords).slice(0, 10); // Limit to 10 keywords\n}\n\nfunction getOgImagePath(filePath) {\n // Determine og:image based on directory structure\n const pathParts = filePath.split(\"/\");\n\n if (pathParts.includes(\"00_home\") || pathParts.includes(\"home\")) {\n return \"/snippets/assets/domain/00_HOME/social-preview-home.jpg\";\n } else if (pathParts.includes(\"01_about\") || pathParts.includes(\"about\")) {\n return \"/snippets/assets/domain/01_ABOUT/social-preview-about.jpg\";\n } else if (pathParts.includes(\"02_community\") || pathParts.includes(\"community\")) {\n return \"/snippets/assets/domain/02_COMMUNITY/social-preview-community.jpg\";\n } else if (pathParts.includes(\"03_developers\") || pathParts.includes(\"developers\")) {\n return \"/snippets/assets/domain/03_DEVELOPERS/social-preview-developers.jpg\";\n } else if (pathParts.includes(\"04_gateways\") || pathParts.includes(\"gateways\")) {\n return \"/snippets/assets/domain/04_GATEWAYS/social-preview-gateways.jpg\";\n } else if (pathParts.includes(\"05_orchestrators\") || pathParts.includes(\"orchestrators\")) {\n return \"/snippets/assets/domain/05_ORCHESTRATORS/social-preview-orchestrators.jpg\";\n } else if (pathParts.includes(\"06_lptoken\") || pathParts.includes(\"lpt\")) {\n return \"/snippets/assets/domain/06_DELEGATORS/social-preview-delegators.jpg\";\n } else if (pathParts.includes(\"07_resources\") || pathParts.includes(\"resources\")) {\n return \"/snippets/assets/domain/07_RESOURCES/social-preview-resources.jpg\";\n }\n\n return \"/snippets/assets/domain/social-preview-default.jpg\";\n}\n\nfunction parseFrontmatterFields(frontmatter) {\n const fields = {};\n const lines = frontmatter.split(\"\\n\");\n let currentField = null;\n let currentValue = [];\n let inMultiLine = false;\n\n for (let i = 0; i < lines.length; i++) {\n const line = lines[i];\n\n // Check if this is a new field\n const fieldMatch = line.match(/^([a-zA-Z_-]+|[\"']?og:image[\"']?):\\s*(.*)$/);\n\n if (fieldMatch && !inMultiLine) {\n // Save previous field\n if (currentField) {\n fields[currentField] = currentValue.join(\"\\n\");\n }\n\n currentField = fieldMatch[1].replace(/[\"']/g, \"\");\n const value = fieldMatch[2];\n\n // Check if it's a multi-line value\n if (value.includes(\"[\") && !value.includes(\"]\")) {\n inMultiLine = true;\n currentValue = [value];\n } else {\n currentValue = [value];\n inMultiLine = false;\n }\n } else if (currentField) {\n currentValue.push(line);\n if (line.includes(\"]\")) {\n inMultiLine = false;\n }\n }\n }\n\n // Save last field\n if (currentField) {\n fields[currentField] = currentValue.join(\"\\n\");\n }\n\n return fields;\n}\n\nfunction rebuildFrontmatter(fields, newKeywords, newOgImage) {\n const lines = [];\n\n // Add all fields EXCEPT keywords and og:image variants\n for (const [key, value] of Object.entries(fields)) {\n if (key === \"keywords\" || key === \"og:image\" || key === \"og\") {\n continue; // Skip, we'll add these at the end\n }\n lines.push(`${key}: ${value}`);\n }\n\n // Add keywords in proper format\n if (newKeywords && newKeywords.length > 0) {\n const keywordsJson = JSON.stringify(newKeywords);\n lines.push(`keywords: ${keywordsJson}`);\n }\n\n // Add og:image in proper format (no quotes on key)\n if (newOgImage) {\n lines.push(`og:image: '${newOgImage}'`);\n }\n\n return lines.join(\"\\n\");\n}\n\nfunction processFile(filePath) {\n const fullPath = path.join(process.cwd(), filePath);\n\n if (!fs.existsSync(fullPath)) {\n return { success: false, error: \"File not found\" };\n }\n\n const content = fs.readFileSync(fullPath, \"utf8\");\n const extracted = extractFrontmatter(content);\n\n if (!extracted) {\n return { success: false, error: \"No frontmatter found\" };\n }\n\n // Parse existing frontmatter\n const fields = parseFrontmatterFields(extracted.frontmatter);\n\n // Extract current keywords if they exist\n let currentKeywords = [];\n if (fields.keywords) {\n try {\n const keywordsStr = fields.keywords.trim();\n if (keywordsStr.startsWith(\"[\")) {\n currentKeywords = JSON.parse(keywordsStr);\n }\n } catch (e) {\n // Ignore parse errors\n }\n }\n\n // Generate new keywords\n const newKeywords = generateKeywords(filePath, currentKeywords);\n\n // Get og:image path\n const newOgImage = getOgImagePath(filePath);\n\n // Rebuild frontmatter\n const newFrontmatter = rebuildFrontmatter(fields, newKeywords, newOgImage);\n const newContent = `---\\n${newFrontmatter}\\n---\\n${extracted.body}`;\n\n // Write file if not dry run\n if (!DRY_RUN) {\n fs.writeFileSync(fullPath, newContent, \"utf8\");\n }\n\n return {\n success: true,\n filePath,\n oldKeywords: currentKeywords,\n newKeywords,\n ogImage: newOgImage,",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/dev/test-seo-generator.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/dev/test-seo-generator.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/dev/update-og-image.js",
+ "script": "update-og-image",
+ "category": "remediator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "Single OG image updater — updates og:image for one page",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/dev/update-og-image.js [flags]",
+ "header": "/**\n * @script update-og-image\n * @category remediator\n * @purpose feature:seo\n * @scope tools/scripts\n * @owner docs\n * @needs E-R19, F-R7\n * @purpose-statement Single OG image updater — updates og:image for one page\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/dev/update-og-image.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst NEW_OG_IMAGE = '/snippets/assets/domain/SHARED/LivepeerDocsHero.svg';\nconst EXCLUDE_FILES = ['mission-control.mdx'];\nconst V2_DOC_ROOTS = [\n 'v2/pages',\n 'v2/home',\n 'v2/solutions',\n 'v2/about',\n 'v2/community',\n 'v2/developers',\n 'v2/gateways',\n 'v2/orchestrators',\n 'v2/lpt',\n 'v2/resources',\n 'v2/internal',\n 'v2/deprecated',\n 'v2/experimental',\n 'v2/notes'\n].filter((root) => fs.existsSync(root));\n\n// Get all MDX files\nconst files = execSync(`find ${V2_DOC_ROOTS.join(' ')} -name \"*.mdx\" -type f`, { encoding: 'utf8' })\n .trim()\n .split('\\n');\n\nconsole.log(`Found ${files.length} MDX files`);\nconsole.log(`New og:image: ${NEW_OG_IMAGE}`);\nconsole.log(`Excluded: ${EXCLUDE_FILES.join(', ')}\\n`);\n\nlet changed = 0;\nlet skipped = 0;\nlet errors = 0;\n\nfiles.forEach(filePath => {\n try {\n const fileName = path.basename(filePath);\n \n // Skip excluded files\n if (EXCLUDE_FILES.includes(fileName)) {\n console.log(`⊘ ${filePath} - Excluded`);\n skipped++;\n return;\n }\n \n const content = fs.readFileSync(filePath, 'utf8');\n \n // Check if file has frontmatter with og:image\n if (!content.match(/^---\\n[\\s\\S]*?\\nog:image:/m)) {\n skipped++;\n return;\n }\n \n // Replace og:image value\n const newContent = content.replace(\n /(og:image:\\s*)[\"'].*?[\"']/g,\n `$1\"${NEW_OG_IMAGE}\"`\n );\n \n if (newContent !== content) {\n fs.writeFileSync(filePath, newContent, 'utf8');\n console.log(`✓ ${filePath}`);\n changed++;\n } else {\n skipped++;\n }\n } catch (error) {\n console.error(`✗ ${filePath}: ${error.message}`);\n errors++;\n }\n});\n\nconsole.log(`\\n========== SUMMARY ==========`);\nconsole.log(`Changed: ${changed}`);\nconsole.log(`Skipped: ${skipped}`);\nconsole.log(`Errors: ${errors}`);\nconsole.log(`=============================`);\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/dev/batch-update-og-image.sh",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/dev/batch-update-og-image.sh",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/common.js",
+ "script": "common",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "i18n shared utilities — common helper functions for translation pipeline",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/common.js [flags]",
+ "header": "/**\n * @script common\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement i18n shared utilities — common helper functions for translation pipeline\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/common.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction normalizeRepoRel(repoRelPath) {\n return toPosix(String(repoRelPath || '').replace(/^\\.\\//, '').replace(/^\\/+/, ''));\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction ensureDirForFile(filePath) {\n ensureDir(path.dirname(filePath));\n}\n\nfunction readJson(filePath) {\n return JSON.parse(fs.readFileSync(filePath, 'utf8'));\n}\n\nfunction writeJson(filePath, value) {\n ensureDirForFile(filePath);\n fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\\n`, 'utf8');\n}\n\nfunction writeTextIfChanged(filePath, nextContent) {\n let prev = null;\n try {\n prev = fs.readFileSync(filePath, 'utf8');\n } catch (_err) {\n prev = null;\n }\n if (prev === nextContent) return false;\n ensureDirForFile(filePath);\n fs.writeFileSync(filePath, nextContent, 'utf8');\n return true;\n}\n\nfunction getRepoRoot(cwd = process.cwd()) {\n try {\n return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf8' }).trim();\n } catch (_err) {\n return cwd;\n }\n}\n\nfunction chunkArray(items, maxItems, maxChars = Infinity, getSize = (item) => String(item || '').length) {\n const chunks = [];\n let current = [];\n let currentChars = 0;\n\n for (const item of items) {\n const size = getSize(item);\n const wouldOverflowItems = current.length >= maxItems;\n const wouldOverflowChars = current.length > 0 && currentChars + size > maxChars;\n if (wouldOverflowItems || wouldOverflowChars) {\n chunks.push(current);\n current = [];\n currentChars = 0;\n }\n current.push(item);\n currentChars += size;\n }\n if (current.length > 0) chunks.push(current);\n return chunks;\n}\n\nfunction parseCsv(value) {\n return String(value || '')\n .split(',')\n .map((s) => s.trim())\n .filter(Boolean);\n}\n\nfunction isExternalHref(href) {\n return /^(https?:\\/\\/|mailto:|#)/i.test(String(href || '').trim());\n}\n\nmodule.exports = {\n chunkArray,\n ensureDir,\n ensureDirForFile,\n getRepoRoot,\n isExternalHref,\n normalizeRepoRel,\n parseCsv,\n readJson,\n toPosix,\n writeJson,\n writeTextIfChanged\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/generate-localized-docs-json.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/config.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/docs-json-localizer.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/docs-routes.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/path-utils.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/provider-openrouter.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/validate-generated.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/generate-localized-docs-json.js; indirect via tools/scripts/i18n/lib/config.js; indirect via tools/scripts/i18n/lib/docs-json-localizer.js; indirect via tools/scripts/i18n/lib/docs-routes.js; indirect via tools/scripts/i18n/lib/path-utils.js; indirect via tools/scripts/i18n/lib/provider-openrouter.js; indirect via tools/scripts/i18n/translate-docs.js; indirect via tools/scripts/i18n/validate-generated.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/config.js",
+ "script": "config",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "i18n configuration — language codes, locale paths, translation settings",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/config.js [flags]",
+ "header": "/**\n * @script config\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement i18n configuration — language codes, locale paths, translation settings\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/config.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { getRepoRoot, parseCsv, readJson } = require('./common');\n\nconst DEFAULT_CONFIG_REPO_REL = 'tools/i18n/config.json';\n\nfunction loadI18nConfig(options = {}) {\n const repoRoot = options.repoRoot || getRepoRoot();\n const configPath = options.configPath\n ? path.resolve(repoRoot, options.configPath)\n : path.join(repoRoot, DEFAULT_CONFIG_REPO_REL);\n\n if (!fs.existsSync(configPath)) {\n throw new Error(`i18n config not found: ${configPath}`);\n }\n\n const config = readJson(configPath);\n validateI18nConfig(config, { configPath });\n return { repoRoot, configPath, config };\n}\n\nfunction validateI18nConfig(config, context = {}) {\n const configPath = context.configPath || DEFAULT_CONFIG_REPO_REL;\n if (!config || typeof config !== 'object') {\n throw new Error(`Invalid i18n config at ${configPath}: expected object`);\n }\n\n const requiredStringKeys = ['sourceLanguage', 'sourceRoot', 'generatedRoot'];\n for (const key of requiredStringKeys) {\n if (typeof config[key] !== 'string' || !config[key].trim()) {\n throw new Error(`Invalid i18n config at ${configPath}: missing \"${key}\"`);\n }\n }\n\n if (!Array.isArray(config.targetLanguages) || config.targetLanguages.length === 0) {\n throw new Error(`Invalid i18n config at ${configPath}: targetLanguages must be a non-empty array`);\n }\n\n if (config.languageCodeMap != null && (typeof config.languageCodeMap !== 'object' || Array.isArray(config.languageCodeMap))) {\n throw new Error(`Invalid i18n config at ${configPath}: languageCodeMap must be an object when provided`);\n }\n\n if (config.generatedPathStyle != null) {\n const style = String(config.generatedPathStyle || '').trim();\n if (!['v2_i18n_legacy', 'v2_language_prefix'].includes(style)) {\n throw new Error(\n `Invalid i18n config at ${configPath}: generatedPathStyle must be \"v2_i18n_legacy\" or \"v2_language_prefix\"`\n );\n }\n }\n\n if (!config.provider || typeof config.provider !== 'object') {\n throw new Error(`Invalid i18n config at ${configPath}: missing provider`);\n }\n\n const models = config.provider.modelCandidates;\n if (!Array.isArray(models) || models.length === 0 || models.some((m) => !String(m || '').trim())) {\n throw new Error(`Invalid i18n config at ${configPath}: provider.modelCandidates must be a non-empty array`);\n }\n}\n\nfunction normalizeLanguageCode(language, config = {}) {\n const raw = String(language || '').trim();\n if (!raw) return '';\n const map = config.languageCodeMap || {};\n if (typeof map[raw] === 'string' && map[raw].trim()) return map[raw].trim();\n const lowerMap = new Map(Object.entries(map).map(([k, v]) => [String(k).toLowerCase(), String(v).trim()]));\n return lowerMap.get(raw.toLowerCase()) || raw;\n}\n\nfunction normalizeLanguageList(languages, config = {}) {\n const out = [];\n const seen = new Set();\n const aliasesApplied = [];\n for (const value of languages || []) {\n const requestedLanguage = String(value || '').trim();\n if (!requestedLanguage) continue;\n const effectiveLanguage = normalizeLanguageCode(requestedLanguage, config);\n if (!effectiveLanguage) continue;\n if (requestedLanguage !== effectiveLanguage) {\n aliasesApplied.push({ requestedLanguage, effectiveLanguage });\n }\n if (seen.has(effectiveLanguage)) continue;\n seen.add(effectiveLanguage);\n out.push(effectiveLanguage);\n }\n return { languages: out, aliasesApplied };\n}\n\nfunction buildRuntimeOptions(cliArgs = {}, config = {}) {\n const defaults = config.scopeDefaults || {};\n const requestedLanguages =\n cliArgs.languages && cliArgs.languages.length ? [...cliArgs.languages] : [...(config.targetLanguages || [])];\n const normalizedLanguages = normalizeLanguageList(requestedLanguages, config);\n const runtime = {\n requestedLanguages,\n languages: normalizedLanguages.languages,\n languageAliasesApplied: normalizedLanguages.aliasesApplied,\n scopeMode: cliArgs.scopeMode || defaults.defaultMode || 'changed_since_ref',\n baseRef: cliArgs.baseRef || defaults.defaultBaseRef || 'docs-v2',\n prefixes: cliArgs.prefixes || [],\n pathsFile: cliArgs.pathsFile || '',\n maxPages: Number.isFinite(cliArgs.maxPages) ? cliArgs.maxPages : Number(defaults.maxPagesPerRun) || 50,\n dryRun: Boolean(cliArgs.dryRun),\n force: Boolean(cliArgs.force),\n routeMapPath: cliArgs.routeMapPath || '',\n reportJsonPath: cliArgs.reportJsonPath || '',\n configPath: cliArgs.configPath || '',\n providerNameOverride: cliArgs.providerName || '',\n allowMockWrite: Boolean(cliArgs.allowMockWrite),\n failOnMockArtifacts: Boolean(cliArgs.failOnMockArtifacts),\n failOnMissingProvenance: Boolean(cliArgs.failOnMissingProvenance),\n cleanupOnly: Boolean(cliArgs.cleanupOnly),\n rewriteLinks: typeof cliArgs.rewriteLinks === 'boolean' ? cliArgs.rewriteLinks : null,\n rewriteScope: cliArgs.rewriteScope || '',\n help: Boolean(cliArgs.help)\n };\n return runtime;\n}\n\nfunction parseCommonCliArgs(argv) {\n const args = {\n languages: [],\n prefixes: [],\n dryRun: false,\n force: false,\n maxPages: null,\n scopeMode: '',\n baseRef: '',\n pathsFile: '',\n routeMapPath: '',\n reportJsonPath: '',\n configPath: '',\n providerName: '',\n write: false,\n allowMockWrite: false,\n failOnMockArtifacts: false,\n failOnMissingProvenance: false,\n cleanupOnly: false,\n rewriteLinks: null,\n rewriteScope: '',\n help: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n const next = argv[i + 1];\n switch (token) {\n case '--languages':\n args.languages = parseCsv(next);\n i += 1;\n break;\n case '--prefixes':\n args.prefixes = parseCsv(next);\n i += 1;\n break;\n case '--scope-mode':\n args.scopeMode = String(next || '').trim();\n i += 1;\n break;\n case '--base-ref':\n args.baseRef = String(next || '').trim();\n i += 1;\n break;\n case '--paths-file':\n args.pathsFile = String(next || '').trim();\n i += 1;\n break;\n case '--max-pages': {\n const parsed = Number(next);\n if (Number.isFinite(parsed) && parsed > 0) args.maxPages = parsed;\n i += 1;\n break;\n }\n case '--route-map':\n args.routeMapPath = String(next || '').trim();\n i += 1;\n break;\n case '--report-json':\n args.reportJsonPath = String(next || '').trim();\n i += 1;\n break;\n case '--config':\n args.configPath = String(next || '').trim();\n i += 1;\n break;\n case '--provider':\n args.providerName = String(next || '').trim();\n i += 1;\n break;\n case '--dry-run':\n args.dryRun = true;\n break;\n case '--force':\n case '--force-retranslate':\n args.force = true;\n break;\n case '--write':\n args.write = true;\n break;\n case '--allow-mock-write':\n args.allowMockWrite = true;\n break;\n case '--cleanup-only':\n args.cleanupOnly = true;\n break;\n case '--rewrite-links':\n args.rewriteLinks = true;\n break;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/enforce-generated-file-banners.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/generate-localized-docs-json.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/validate-generated.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/enforce-generated-file-banners.js; indirect via tools/scripts/i18n/generate-localized-docs-json.js; indirect via tools/scripts/i18n/translate-docs.js; indirect via tools/scripts/i18n/validate-generated.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/docs-json-localizer.js",
+ "script": "docs-json-localizer",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "docs.json localiser engine — transforms docs.json navigation for locale variants",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/docs-json-localizer.js [flags]",
+ "header": "/**\n * @script docs-json-localizer\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement docs.json localiser engine — transforms docs.json navigation for locale variants\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/docs-json-localizer.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { chunkArray } = require('./common');\nconst { normalizeRouteKey } = require('./path-utils');\nconst { protectText, restoreProtectedText } = require('./mdx-translate');\n\nconst MOCK_LABEL_PREFIX_RE = /^\\[[a-z]{2,5}(?:-[A-Z]{2})?\\]\\s+/;\n\nfunction deepClone(value) {\n return JSON.parse(JSON.stringify(value));\n}\n\nfunction normalizeLanguageAlias(language, languageCodeMap = {}) {\n const raw = String(language || '').trim();\n if (!raw) return '';\n if (typeof languageCodeMap[raw] === 'string' && languageCodeMap[raw].trim()) return languageCodeMap[raw].trim();\n const lower = raw.toLowerCase();\n for (const [key, value] of Object.entries(languageCodeMap || {})) {\n if (String(key).toLowerCase() === lower && String(value || '').trim()) return String(value).trim();\n }\n return raw;\n}\n\nfunction collectLabelFields(node, labelKeys, out = []) {\n if (Array.isArray(node)) {\n node.forEach((item) => collectLabelFields(item, labelKeys, out));\n return out;\n }\n if (!node || typeof node !== 'object') return out;\n\n for (const key of Object.keys(node)) {\n if (labelKeys.has(key) && typeof node[key] === 'string' && node[key].trim() && node[key].trim() !== ' ') {\n out.push({ target: node, key, value: node[key] });\n }\n collectLabelFields(node[key], labelKeys, out);\n }\n return out;\n}\n\nfunction detectMockPrefixedLabels(node, labelKeys) {\n const labels = collectLabelFields(node, labelKeys);\n const matches = [];\n for (const label of labels) {\n const value = String(label.target?.[label.key] || '');\n if (MOCK_LABEL_PREFIX_RE.test(value)) {\n matches.push({\n key: label.key,\n value\n });\n }\n }\n return matches;\n}\n\nfunction normalizeArtifactClass(entry) {\n const explicit = String(entry?.artifactClass || '').trim();\n if (explicit) return explicit;\n const provider = String(entry?.provider || '').trim().toLowerCase();\n if (provider === 'mock') return 'translated_mock';\n if (provider) return 'translated_real';\n return 'existing_unknown';\n}\n\nfunction buildRouteMapIndex(routeMapEntries) {\n const index = new Map();\n for (const rawEntry of routeMapEntries || []) {\n const status = String(rawEntry.status || '').trim();\n if (status && !['translated', 'unchanged_write', 'skipped_up_to_date', 'existing', 'translated_dry_run'].includes(status)) {\n continue;\n }\n const sourceRoute = normalizeRouteKey(rawEntry.sourceRoute);\n const language = String(rawEntry.effectiveLanguage || rawEntry.language || '').trim();\n const localizedRoute = normalizeRouteKey(rawEntry.localizedRoute);\n if (!sourceRoute || !language || !localizedRoute) continue;\n const entry = {\n ...rawEntry,\n sourceRoute,\n language,\n localizedRoute,\n effectiveLanguage: String(rawEntry.effectiveLanguage || rawEntry.language || '').trim(),\n requestedLanguage: String(rawEntry.requestedLanguage || ''),\n localizedRouteStyle: String(rawEntry.localizedRouteStyle || ''),\n provider: String(rawEntry.provider || '').trim().toLowerCase(),\n modelUsed: String(rawEntry.modelUsed || ''),\n provenanceKind: String(rawEntry.provenanceKind || ''),\n artifactClass: normalizeArtifactClass(rawEntry)\n };\n if (!index.has(sourceRoute)) index.set(sourceRoute, new Map());\n index.get(sourceRoute).set(language, entry);\n }\n return index;\n}\n\nfunction shouldPreservePageEntry(value) {\n const trimmed = String(value || '').trim();\n if (!trimmed || trimmed === ' ') return true;\n if (/^(https?:\\/\\/|mailto:|#)/i.test(trimmed)) return true;\n return false;\n}\n\nfunction buildStats() {\n return {\n rewrittenRoutes: 0,\n fallbackRoutes: 0,\n fallbackRoutesWithinSelectedScope: 0,\n fallbackRoutesOutsideSelectedScope: 0,\n rewrittenRoutesFromMockArtifacts: 0,\n blockedMockArtifactRoutes: 0,\n fallbackByLocation: new Map()\n };\n}\n\nfunction trimLabel(value) {\n const text = String(value || '').trim();\n return text || '';\n}\n\nfunction locationKeyFromTrail(trail = {}) {\n const tab = trimLabel(trail.tab) || '(tab:unknown)';\n const anchor = trimLabel(trail.anchor) || '(anchor:unknown)';\n const group = trimLabel(trail.group) || '(group:ungrouped)';\n return `${tab} > ${anchor} > ${group}`;\n}\n\nfunction recordFallback(stats, context, trail, sourceRoute) {\n stats.fallbackRoutes += 1;\n const selectedSet = context.selectedScopeRoutes;\n if (selectedSet && selectedSet.size > 0) {\n if (selectedSet.has(sourceRoute)) stats.fallbackRoutesWithinSelectedScope += 1;\n else stats.fallbackRoutesOutsideSelectedScope += 1;\n } else {\n stats.fallbackRoutesOutsideSelectedScope += 1;\n }\n\n const key = locationKeyFromTrail(trail);\n const nextCount = (stats.fallbackByLocation.get(key) || 0) + 1;\n stats.fallbackByLocation.set(key, nextCount);\n}\n\nfunction maybeRewriteRoute(entry, sourceRoute, context, stats, trail) {\n if (!entry) {\n recordFallback(stats, context, trail, sourceRoute);\n return { rewritten: false, route: null };\n }\n\n if (context.rejectMockArtifactsForRouteRewrite && entry.artifactClass === 'translated_mock') {\n stats.blockedMockArtifactRoutes += 1;\n recordFallback(stats, context, trail, sourceRoute);\n return { rewritten: false, route: null };\n }\n\n const localizedRoute = normalizeRouteKey(entry.localizedRoute);\n if (!localizedRoute) {\n recordFallback(stats, context, trail, sourceRoute);\n return { rewritten: false, route: null };\n }\n\n if (context.requireLocalizedFileForRouteRewrite) {\n const abs = path.join(context.repoRoot, `${localizedRoute}.mdx`);\n const absAlt = path.join(context.repoRoot, `${localizedRoute}.md`);\n if (!fs.existsSync(abs) && !fs.existsSync(absAlt)) {\n recordFallback(stats, context, trail, sourceRoute);\n return { rewritten: false, route: null };\n }\n }\n\n stats.rewrittenRoutes += 1;\n if (entry.artifactClass === 'translated_mock') {\n stats.rewrittenRoutesFromMockArtifacts += 1;\n }\n return { rewritten: true, route: localizedRoute };\n}\n\nfunction localizePagesInNode(node, context, stats, trail = {}) {\n if (Array.isArray(node)) {\n node.forEach((item) => localizePagesInNode(item, context, stats, trail));\n return;\n }\n if (!node || typeof node !== 'object') return;\n\n const nextTrail = { ...trail };\n if (typeof node.tab === 'string' && node.tab.trim() && node.tab.trim() !== ' ') nextTrail.tab = node.tab;\n if (typeof node.anchor === 'string' && node.anchor.trim() && node.anchor.trim() !== ' ') nextTrail.anchor = node.anchor;\n if (typeof node.group === 'string' && node.group.trim() && node.group.trim() !== ' ') nextTrail.group = node.group;\n\n if (Array.isArray(node.pages)) {\n node.pages = node.pages.map((entry) => {\n if (typeof entry !== 'string') {\n localizePagesInNode(entry, context, stats, nextTrail);\n return entry;\n }\n if (shouldPreservePageEntry(entry)) return entry;\n\n const normalized = normalizeRouteKey(entry);\n if (!normalized.startsWith('v2/')) return entry;\n\n const mapped = context.routeMapIndex.get(normalized)?.get(context.language) || null;\n const rewrite = maybeRewriteRoute(mapped, normalized, context, stats, nextTrail);\n if (!rewrite.rewritten || !rewrite.route) return entry;\n\n if (String(entry).trim().startsWith('/')) {\n return `/${rewrite.route}`;\n }\n return rewrite.route;\n });\n }\n\n Object.keys(node).forEach((key) => {\n if (key === 'pages') return;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/generate-localized-docs-json.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/docs-json-localizer.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/generate-localized-docs-json.js; indirect via tools/scripts/i18n/test/docs-json-localizer.test.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/docs-routes.js",
+ "script": "docs-routes",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "docs route resolver — maps page paths to locale-aware routes",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/docs-routes.js [flags]",
+ "header": "/**\n * @script docs-routes\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement docs route resolver — maps page paths to locale-aware routes\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/docs-routes.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst { normalizeRepoRel, readJson, toPosix } = require('./common');\nconst { fileToRouteKey, normalizeRouteKey, resolveLocalizedPathStyle, resolveRouteToFile } = require('./path-utils');\nconst { parseProvenanceComment, classifyLocalizedArtifactProvenance } = require('./provenance');\n\nfunction collectPageStrings(node, out = []) {\n if (typeof node === 'string') {\n out.push(node);\n return out;\n }\n if (Array.isArray(node)) {\n node.forEach((item) => collectPageStrings(item, out));\n return out;\n }\n if (!node || typeof node !== 'object') return out;\n if (Array.isArray(node.pages)) {\n node.pages.forEach((item) => collectPageStrings(item, out));\n }\n Object.values(node).forEach((value) => collectPageStrings(value, out));\n return out;\n}\n\nfunction getDocsJson(repoRoot) {\n return readJson(path.join(repoRoot, 'docs.json'));\n}\n\nfunction getV2EnglishLanguageNode(docsJson) {\n const versions = docsJson?.navigation?.versions || [];\n const v2 = versions.find((versionNode) => versionNode?.version === 'v2');\n if (!v2) throw new Error('v2 version not found in docs.json');\n const en = (v2.languages || []).find((langNode) => langNode?.language === 'en');\n if (!en) throw new Error('v2 English language node not found in docs.json');\n return { v2, en };\n}\n\nfunction getV2EnglishRoutes(repoRoot) {\n const docsJson = getDocsJson(repoRoot);\n const { en } = getV2EnglishLanguageNode(docsJson);\n const rawEntries = collectPageStrings(en);\n const seen = new Set();\n const routes = [];\n for (const raw of rawEntries) {\n const trimmed = String(raw || '').trim();\n if (!trimmed || trimmed === ' ') continue;\n if (!trimmed.startsWith('v2/')) continue;\n const normalized = normalizeRouteKey(trimmed);\n if (!normalized || seen.has(normalized)) continue;\n seen.add(normalized);\n routes.push(normalized);\n }\n return routes;\n}\n\nfunction buildV2EnglishRouteInventory(repoRoot) {\n const routes = getV2EnglishRoutes(repoRoot);\n const items = [];\n const unresolved = [];\n\n for (const route of routes) {\n const fileRel = resolveRouteToFile(repoRoot, route);\n if (!fileRel) {\n unresolved.push(route);\n continue;\n }\n if (!fileRel.startsWith('v2/')) continue;\n if (fileRel.startsWith('v2/x-')) continue;\n items.push({\n route,\n fileRel,\n fileAbs: path.join(repoRoot, fileRel)\n });\n }\n\n return { items, unresolved };\n}\n\nfunction getChangedFilesSinceRef(repoRoot, baseRef) {\n const candidates = [`origin/${baseRef}...HEAD`, `${baseRef}...HEAD`];\n for (const range of candidates) {\n try {\n const output = execSync(`git diff --name-only ${range}`, { cwd: repoRoot, encoding: 'utf8' });\n return output\n .split('\\n')\n .map((line) => line.trim())\n .filter(Boolean)\n .map((line) => normalizeRepoRel(line));\n } catch (_err) {\n // Try next range.\n }\n }\n return [];\n}\n\nfunction loadPathsFile(repoRoot, filePath) {\n const abs = path.resolve(repoRoot, filePath);\n const content = fs.readFileSync(abs, 'utf8');\n return content\n .split(/\\r?\\n/)\n .map((line) => line.trim())\n .filter((line) => line && !line.startsWith('#'))\n .map((line) => normalizeRepoRel(line));\n}\n\nfunction toInventoryItemFromFile(repoRoot, fileRel) {\n const normalizedFile = normalizeRepoRel(fileRel);\n const fileAbs = path.join(repoRoot, normalizedFile);\n if (!fs.existsSync(fileAbs)) return null;\n const stat = fs.statSync(fileAbs);\n if (!stat.isFile()) return null;\n if (!/\\.(md|mdx)$/i.test(normalizedFile)) return null;\n\n let route = fileToRouteKey(repoRoot, fileAbs);\n route = route.replace(/\\/README$/i, '');\n route = normalizeRouteKey(route);\n if (!route) return null;\n\n return {\n route,\n fileRel: normalizedFile,\n fileAbs\n };\n}\n\nfunction selectScopeItems(options) {\n const {\n repoRoot,\n inventory,\n scopeMode,\n baseRef,\n prefixes = [],\n pathsFile = '',\n maxPages = 50\n } = options;\n\n const items = inventory.items || [];\n let selected = [];\n\n if (scopeMode === 'full_v2_nav') {\n selected = items;\n } else if (scopeMode === 'prefixes') {\n const normalizedPrefixes = prefixes.map((p) => normalizeRepoRel(p)).filter(Boolean);\n selected = items.filter((item) =>\n normalizedPrefixes.some((prefix) => item.fileRel.startsWith(prefix) || item.route.startsWith(normalizeRouteKey(prefix)))\n );\n } else if (scopeMode === 'paths_file') {\n const entries = loadPathsFile(repoRoot, pathsFile);\n const routeSet = new Set(entries.map((entry) => normalizeRouteKey(entry)));\n const fileSet = new Set(entries.map((entry) => normalizeRepoRel(entry)));\n const selectedByFile = new Map();\n selected = items.filter((item) => routeSet.has(item.route) || fileSet.has(item.fileRel));\n for (const item of selected) selectedByFile.set(item.fileRel, item);\n\n for (const entry of entries) {\n if (!entry) continue;\n\n // Explicit file path, including non-v2 docs such as docs-guide/* or contribute/*.\n let candidate = toInventoryItemFromFile(repoRoot, entry);\n\n // Route entry outside the existing v2 inventory.\n if (!candidate) {\n const resolvedFile = resolveRouteToFile(repoRoot, entry);\n if (resolvedFile) candidate = toInventoryItemFromFile(repoRoot, resolvedFile);\n }\n\n if (!candidate) continue;\n if (selectedByFile.has(candidate.fileRel)) continue;\n selectedByFile.set(candidate.fileRel, candidate);\n selected.push(candidate);\n }\n } else {\n const changedFiles = new Set(getChangedFilesSinceRef(repoRoot, baseRef));\n selected = items.filter((item) => changedFiles.has(item.fileRel));\n }\n\n return {\n selected: selected.slice(0, Math.max(1, Number(maxPages) || 50)),\n truncated: selected.length > (Math.max(1, Number(maxPages) || 50)),\n totalCandidateCount: selected.length\n };\n}\n\nfunction collectExistingLocalizedRouteMapEntries(repoRoot, generatedRoot = 'v2/i18n', options = {}) {\n const out = [];\n const pathStyle = resolveLocalizedPathStyle(generatedRoot, options.generatedPathStyle || options.pathStyle || '');\n const sourceRoot = normalizeRepoRel(options.sourceRoot || 'v2');\n const knownLanguages = new Set((options.knownLanguages || []).map((lang) => String(lang || '').trim()).filter(Boolean));\n\n function walk(dirAbs) {\n const entries = fs.readdirSync(dirAbs, { withFileTypes: true });\n for (const entry of entries) {\n const childAbs = path.join(dirAbs, entry.name);\n if (entry.isDirectory()) {\n walk(childAbs);\n continue;\n }\n if (!/\\.(md|mdx)$/i.test(entry.name)) continue;\n const rel = normalizeRepoRel(path.relative(repoRoot, childAbs));\n const parts = rel.split('/');\n let language = '';\n let suffix = '';\n if (pathStyle === 'v2_language_prefix') {\n if (parts.length < 3 || parts[0] !== sourceRoot) continue;\n if (knownLanguages.size > 0 && !knownLanguages.has(parts[1])) continue;\n language = parts[1];\n suffix = parts.slice(2).join('/');\n } else {\n if (parts.length < 4 || parts[0] !== sourceRoot || parts[1] !== 'i18n') continue;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/generate-localized-docs-json.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/validate-generated.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/generate-localized-docs-json.js; indirect via tools/scripts/i18n/translate-docs.js; indirect via tools/scripts/i18n/validate-generated.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/frontmatter.js",
+ "script": "frontmatter",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Frontmatter parser/writer — reads and writes MDX frontmatter for translation",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/frontmatter.js [flags]",
+ "header": "/**\n * @script frontmatter\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Frontmatter parser/writer — reads and writes MDX frontmatter for translation\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/frontmatter.js [flags]\n */\nconst matter = require('gray-matter');\nconst { protectText, restoreProtectedText } = require('./mdx-translate');\n\nfunction parseMdxFileWithFrontmatter(rawContent) {\n const parsed = matter(String(rawContent || ''));\n const hasFrontmatter = String(rawContent || '').startsWith('---');\n return {\n data: parsed.data || {},\n body: parsed.content || '',\n hasFrontmatter,\n stringify(nextBody, nextData) {\n const body = String(nextBody || '');\n const data = nextData || {};\n if (!hasFrontmatter && Object.keys(data).length === 0) {\n return body;\n }\n return matter.stringify(body, data);\n }\n };\n}\n\nasync function translateFrontmatterFields({ data, language, translator, rules, translateKeywords = false }) {\n const next = { ...data };\n const keys = Array.isArray(rules?.translateFrontmatterKeys) ? rules.translateFrontmatterKeys : [];\n const stringTargets = [];\n const placements = [];\n\n for (const key of keys) {\n if (typeof next[key] !== 'string' || !next[key].trim()) continue;\n const protectedValue = protectText(next[key], rules);\n if (protectedValue.skip) continue;\n stringTargets.push(protectedValue.text);\n placements.push({ key, placeholders: protectedValue.placeholders });\n }\n\n if (translateKeywords && Array.isArray(next.keywords)) {\n for (let i = 0; i < next.keywords.length; i += 1) {\n if (typeof next.keywords[i] !== 'string' || !next.keywords[i].trim()) continue;\n const protectedValue = protectText(next.keywords[i], rules);\n if (protectedValue.skip) continue;\n stringTargets.push(protectedValue.text);\n placements.push({ key: 'keywords', index: i, placeholders: protectedValue.placeholders });\n }\n }\n\n if (stringTargets.length === 0) {\n return { data: next, translatedCount: 0, modelUsed: '' };\n }\n\n const result = await translator.translateStrings({\n language,\n strings: stringTargets,\n kind: 'frontmatter'\n });\n\n placements.forEach((placement, idx) => {\n const restored = restoreProtectedText(result.strings[idx], placement.placeholders);\n if (placement.key === 'keywords') {\n next.keywords[placement.index] = restored;\n } else {\n next[placement.key] = restored;\n }\n });\n\n return {\n data: next,\n translatedCount: stringTargets.length,\n modelUsed: result.modelUsed || ''\n };\n}\n\nmodule.exports = {\n parseMdxFileWithFrontmatter,\n translateFrontmatterFields\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/frontmatter.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/provenance.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/validate-generated.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/test/frontmatter.test.js; indirect via tools/scripts/i18n/test/provenance.test.js; indirect via tools/scripts/i18n/translate-docs.js; indirect via tools/scripts/i18n/validate-generated.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/mdx-parser.js",
+ "script": "mdx-parser",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "MDX parser for i18n — extracts translatable content blocks from MDX",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/mdx-parser.js [flags]",
+ "header": "/**\n * @script mdx-parser\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement MDX parser for i18n — extracts translatable content blocks from MDX\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/mdx-parser.js [flags]\n */\nlet parserPromise = null;\n\nasync function createParser() {\n const [{ unified }, { default: remarkParse }, { default: remarkMdx }, { default: remarkGfm }] =\n await Promise.all([import('unified'), import('remark-parse'), import('remark-mdx'), import('remark-gfm')]);\n return unified().use(remarkParse).use(remarkGfm).use(remarkMdx);\n}\n\nasync function getParser() {\n if (!parserPromise) {\n parserPromise = createParser();\n }\n return parserPromise;\n}\n\nasync function parseMdx(content) {\n const parser = await getParser();\n return parser.parse(String(content || ''));\n}\n\nmodule.exports = { parseMdx };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/mdx-translate.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/validate-generated.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/remediators/content/repair-spelling.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/lib/mdx-translate.js; indirect via tools/scripts/i18n/validate-generated.js; indirect via tools/scripts/remediators/content/repair-spelling.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/mdx-translate.js",
+ "script": "mdx-translate",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "MDX translation engine — applies translations to MDX content blocks",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/mdx-translate.js [flags]",
+ "header": "/**\n * @script mdx-translate\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement MDX translation engine — applies translations to MDX content blocks\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/mdx-translate.js [flags]\n */\nconst path = require('path');\nconst { parseMdx } = require('./mdx-parser');\nconst { normalizeRouteKey } = require('./path-utils');\n\nconst BLOCKED_TYPES = new Set([\n 'code',\n 'inlineCode',\n 'html',\n 'yaml',\n 'definition',\n 'mdxjsEsm',\n 'mdxFlowExpression',\n 'mdxTextExpression',\n 'mdxJsxFlowElement',\n 'mdxJsxTextElement'\n]);\n\nfunction escapeRegExp(value) {\n return String(value || '').replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\nfunction walk(node, parents, visitor) {\n if (!node || typeof node !== 'object') return;\n visitor(node, parents);\n if (BLOCKED_TYPES.has(node.type)) return;\n\n if (Array.isArray(node.children)) {\n const nextParents = parents.concat(node);\n node.children.forEach((child) => walk(child, nextParents, visitor));\n }\n}\n\nfunction canTranslateTextNode(node, parents) {\n if (!node || node.type !== 'text') return false;\n if (!node.position || typeof node.position.start?.offset !== 'number' || typeof node.position.end?.offset !== 'number') {\n return false;\n }\n if (!String(node.value || '').trim()) return false;\n if (parents.some((p) => BLOCKED_TYPES.has(p.type))) return false;\n return true;\n}\n\nasync function extractTranslatableTextSegments(body) {\n const tree = await parseMdx(body);\n const segments = [];\n let counter = 0;\n\n walk(tree, [], (node, parents) => {\n if (!canTranslateTextNode(node, parents)) return;\n const start = node.position.start.offset;\n const end = node.position.end.offset;\n if (typeof start !== 'number' || typeof end !== 'number' || end <= start) return;\n segments.push({\n id: `seg_${counter++}`,\n start,\n end,\n text: String(node.value || '')\n });\n });\n\n segments.sort((a, b) => a.start - b.start || a.end - b.end);\n return segments.filter((segment, index) => {\n if (index === 0) return true;\n return segment.start >= segments[index - 1].end;\n });\n}\n\nfunction applySegmentTranslations(body, translatedSegments) {\n let next = String(body || '');\n const ordered = [...translatedSegments].sort((a, b) => b.start - a.start);\n for (const segment of ordered) {\n next = `${next.slice(0, segment.start)}${segment.text}${next.slice(segment.end)}`;\n }\n return next;\n}\n\nfunction protectText(text, rules = {}) {\n const source = String(text ?? '');\n const preserveRegexes = Array.isArray(rules.preserveRegexes) ? rules.preserveRegexes : [];\n for (const pattern of preserveRegexes) {\n try {\n const regex = new RegExp(pattern);\n if (regex.test(source)) {\n return { text: source, placeholders: [], skip: true };\n }\n } catch (_err) {\n // Ignore invalid regex in config.\n }\n }\n\n const placeholders = [];\n let next = source;\n let index = 0;\n\n const replaceWithPlaceholder = (regex) => {\n next = next.replace(regex, (match) => {\n const token = `__I18N_PH_${index++}__`;\n placeholders.push({ token, value: match });\n return token;\n });\n };\n\n replaceWithPlaceholder(/https?:\\/\\/[^\\s)]+/g);\n replaceWithPlaceholder(/mailto:[^\\s)]+/g);\n replaceWithPlaceholder(/\\/snippets\\/[^\\s)]+/g);\n replaceWithPlaceholder(/\\bv\\d+\\/[^\\s)]+/g);\n replaceWithPlaceholder(/`[^`]+`/g);\n\n const brandTerms = Array.isArray(rules.preserveBrandTerms) ? rules.preserveBrandTerms : [];\n for (const term of brandTerms) {\n const escaped = escapeRegExp(term);\n next = next.replace(new RegExp(`\\\\b${escaped}\\\\b`, 'g'), (match) => {\n const token = `__I18N_PH_${index++}__`;\n placeholders.push({ token, value: match });\n return token;\n });\n }\n\n return { text: next, placeholders, skip: false };\n}\n\nfunction restoreProtectedText(text, placeholders = []) {\n let next = String(text ?? '');\n for (const placeholder of placeholders) {\n if (!next.includes(placeholder.token)) {\n throw new Error(`Missing placeholder in translation output: ${placeholder.token}`);\n }\n next = next.split(placeholder.token).join(placeholder.value);\n }\n return next;\n}\n\nfunction resolveLinkUrlToRoute(sourceRoute, url) {\n const raw = String(url || '').trim();\n if (!raw || raw === ' ' || raw.startsWith('#')) return '';\n if (/^(https?:\\/\\/|mailto:)/i.test(raw)) return '';\n if (raw.startsWith('/snippets/')) return '';\n\n let target = raw;\n if (target.startsWith('/')) {\n target = target.slice(1);\n } else if (!/^v\\d+\\//i.test(target)) {\n const baseDir = path.posix.dirname(normalizeRouteKey(sourceRoute));\n target = path.posix.join(baseDir, target);\n }\n return normalizeRouteKey(target);\n}\n\nfunction buildRelativeLink(fromRoute, toRoute) {\n const fromDir = path.posix.dirname(normalizeRouteKey(fromRoute));\n const rel = path.posix.relative(fromDir, normalizeRouteKey(toRoute));\n if (!rel) return './';\n if (rel.startsWith('.')) return rel;\n return `./${rel}`;\n}\n\nfunction rewriteUrlForLanguage({ sourceRoute, sourceLocalizedRoute, url, localizedTargetRoute }) {\n const raw = String(url || '');\n const trimmed = raw.trim();\n if (!trimmed) return raw;\n if (trimmed.startsWith('/')) {\n return `/${normalizeRouteKey(localizedTargetRoute)}`;\n }\n if (/^v\\d+\\//i.test(trimmed)) {\n return normalizeRouteKey(localizedTargetRoute);\n }\n const rel = buildRelativeLink(sourceLocalizedRoute || sourceRoute, localizedTargetRoute);\n if (trimmed.startsWith('./')) return rel;\n if (trimmed.startsWith('../')) return rel;\n return rel.replace(/^\\.\\//, '');\n}\n\nfunction rewriteMarkdownLinks(body, rewriter) {\n return String(body || '').replace(/\\[([^\\]]*)\\]\\(([^)]+)\\)/g, (full, label, destination) => {\n const inner = String(destination);\n const trimmed = inner.trim();\n if (!trimmed) return full;\n\n let urlPart = trimmed;\n let remainder = '';\n const titleMatch = trimmed.match(/^(\\S+)(\\s+[\"'][\\s\\S]*[\"'])$/);\n if (titleMatch) {\n urlPart = titleMatch[1];\n remainder = titleMatch[2];\n }\n\n const rewritten = rewriter(urlPart);\n if (!rewritten || rewritten === urlPart) return full;\n return `[${label}](${rewritten}${remainder})`;\n });\n}\n\nfunction rewriteJsxHrefAttributes(body, rewriter) {\n return String(body || '').replace(/\\bhref=([\"'])([^\"']+)\\1/g, (full, quote, url) => {\n const trimmed = String(url || '').trim();\n if (!trimmed) return full;\n const rewritten = rewriter(trimmed);\n if (!rewritten || rewritten === trimmed) return full;\n return `href=${quote}${rewritten}${quote}`;\n });\n}\n\nfunction rewriteInternalLinksInBody(body, options) {\n const {\n sourceRoute,\n language,\n sourceLocalizedRoute,\n routeMapBySourceRoute\n } = options;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/docs-json-localizer.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/frontmatter.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/mdx-translate.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/lib/docs-json-localizer.js; indirect via tools/scripts/i18n/lib/frontmatter.js; indirect via tools/scripts/i18n/test/mdx-translate.test.js; indirect via tools/scripts/i18n/translate-docs.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/path-utils.js",
+ "script": "path-utils",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Path utilities for i18n — locale-aware path resolution and mapping",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/path-utils.js [flags]",
+ "header": "/**\n * @script path-utils\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Path utilities for i18n — locale-aware path resolution and mapping\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/path-utils.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\nconst { normalizeRepoRel, toPosix, isExternalHref } = require('./common');\n\nfunction normalizeRouteKey(value) {\n let normalized = String(value || '').trim();\n normalized = normalized.replace(/^\\/+/, '');\n normalized = normalized.replace(/\\.(md|mdx)$/i, '');\n normalized = normalized.replace(/\\/index$/i, '');\n normalized = normalized.replace(/\\/+$/, '');\n return normalized;\n}\n\nfunction routeToFileCandidates(routeValue) {\n const route = normalizeRouteKey(routeValue);\n if (!route) return [];\n return [\n `${route}.mdx`,\n `${route}.md`,\n `${route}/index.mdx`,\n `${route}/index.md`,\n `${route}/README.mdx`,\n `${route}/README.md`\n ];\n}\n\nfunction resolveRouteToFile(repoRoot, routeValue) {\n for (const candidate of routeToFileCandidates(routeValue)) {\n const abs = path.join(repoRoot, candidate);\n if (fs.existsSync(abs)) return normalizeRepoRel(candidate);\n }\n return '';\n}\n\nfunction fileToRouteKey(repoRoot, filePath) {\n const rel = normalizeRepoRel(path.relative(repoRoot, filePath));\n return normalizeRouteKey(rel);\n}\n\nfunction resolveLocalizedPathStyle(generatedRoot, generatedPathStyle) {\n const explicit = String(generatedPathStyle || '').trim();\n if (explicit) return explicit;\n return normalizeRepoRel(generatedRoot) === 'v2' ? 'v2_language_prefix' : 'v2_i18n_legacy';\n}\n\nfunction repoFileRelToLocalizedFileRel(sourceRepoFileRel, language, generatedRoot = 'v2/i18n', generatedPathStyle = '') {\n const normalized = normalizeRepoRel(sourceRepoFileRel);\n const suffix = normalized.startsWith('v2/') ? normalized.slice('v2/'.length) : normalized;\n const style = resolveLocalizedPathStyle(generatedRoot, generatedPathStyle);\n if (style === 'v2_language_prefix') {\n return normalizeRepoRel(path.posix.join('v2', language, suffix));\n }\n return normalizeRepoRel(path.posix.join(generatedRoot, language, suffix));\n}\n\nfunction repoRouteToLocalizedRoute(sourceRoute, language, generatedRoot = 'v2/i18n', generatedPathStyle = '') {\n const route = normalizeRouteKey(sourceRoute);\n if (!route.startsWith('v2/')) return route;\n const suffix = route.slice('v2/'.length);\n const style = resolveLocalizedPathStyle(generatedRoot, generatedPathStyle);\n if (style === 'v2_language_prefix') {\n return normalizeRepoRel(path.posix.join('v2', language, suffix));\n }\n return normalizeRepoRel(path.posix.join(generatedRoot, language, suffix));\n}\n\nfunction routeStringLooksInternalDocs(routeValue) {\n const trimmed = String(routeValue || '').trim();\n if (!trimmed) return false;\n if (trimmed === ' ') return false;\n if (isExternalHref(trimmed)) return false;\n return /^v\\d+\\//i.test(trimmed) || trimmed.startsWith('/');\n}\n\nmodule.exports = {\n fileToRouteKey,\n normalizeRouteKey,\n repoFileRelToLocalizedFileRel,\n repoRouteToLocalizedRoute,\n resolveLocalizedPathStyle,\n resolveRouteToFile,\n routeStringLooksInternalDocs\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/docs-json-localizer.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/docs-routes.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/mdx-translate.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/lib/docs-json-localizer.js; indirect via tools/scripts/i18n/lib/docs-routes.js; indirect via tools/scripts/i18n/lib/mdx-translate.js; indirect via tools/scripts/i18n/translate-docs.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/provenance.js",
+ "script": "provenance",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Translation provenance tracker — records source, timestamp, and provider for each translated segment",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/provenance.js [flags]",
+ "header": "/**\n * @script provenance\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Translation provenance tracker — records source, timestamp, and provider for each translated segment\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/provenance.js [flags]\n */\nconst crypto = require('crypto');\n\nconst PROVENANCE_PREFIX = 'codex-i18n';\n\nfunction sha256(value) {\n return crypto.createHash('sha256').update(String(value || ''), 'utf8').digest('hex');\n}\n\nfunction buildProvenanceComment(metadata) {\n const payload = {\n kind: PROVENANCE_PREFIX,\n version: 1,\n ...metadata\n };\n const encoded = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');\n return `{/* ${PROVENANCE_PREFIX}: ${encoded} */}`;\n}\n\nfunction parseProvenanceComment(content) {\n const source = String(content || '');\n const jsxMatch = source.match(new RegExp(`\\\\{\\\\/\\\\*\\\\s*${PROVENANCE_PREFIX}:\\\\s*([A-Za-z0-9+/=]+)\\\\s*\\\\*\\\\/\\\\}`));\n if (jsxMatch) {\n try {\n const decoded = Buffer.from(jsxMatch[1], 'base64').toString('utf8');\n const parsed = JSON.parse(decoded);\n if (parsed && parsed.kind === PROVENANCE_PREFIX) return parsed;\n } catch (_err) {\n return null;\n }\n }\n\n const legacyHtmlMatch = source.match(new RegExp(``));\n if (legacyHtmlMatch) {\n try {\n const parsed = JSON.parse(legacyHtmlMatch[1]);\n if (parsed && parsed.kind === PROVENANCE_PREFIX) return parsed;\n } catch (_err) {\n return null;\n }\n }\n\n return null;\n}\n\nfunction classifyLocalizedArtifactProvenance(provenance) {\n if (!provenance || typeof provenance !== 'object') {\n return {\n provenancePresent: false,\n provenanceKind: '',\n provider: '',\n modelUsed: '',\n sourceHash: '',\n artifactClass: 'existing_unknown'\n };\n }\n\n const provider = String(provenance.provider || '').trim().toLowerCase();\n let artifactClass = 'translated_real';\n if (provider === 'mock') artifactClass = 'translated_mock';\n if (!provider) artifactClass = 'existing_unknown';\n\n return {\n provenancePresent: true,\n provenanceKind: String(provenance.kind || ''),\n provider,\n modelUsed: String(provenance.model || ''),\n sourceHash: String(provenance.sourceHash || ''),\n artifactClass\n };\n}\n\nfunction injectOrReplaceProvenanceComment(content, comment) {\n const source = String(content || '');\n const hasFrontmatter = source.startsWith('---\\n') || source.startsWith('---\\r\\n');\n const provenancePattern = new RegExp(\n `(?:|\\\\{\\\\/\\\\*\\\\s*${PROVENANCE_PREFIX}:\\\\s*[A-Za-z0-9+/=]+\\\\s*\\\\*\\\\/\\\\})`\n );\n if (!hasFrontmatter) {\n if (provenancePattern.test(source)) {\n return source.replace(provenancePattern, comment);\n }\n return `${comment}\\n${source}`;\n }\n\n const end = findFrontmatterEndOffset(source);\n if (end < 0) {\n return `${comment}\\n${source}`;\n }\n\n const before = source.slice(0, end);\n const after = source.slice(end);\n const replacedAfter = after.replace(\n new RegExp(\n `^\\\\s*(?:|\\\\{\\\\/\\\\*\\\\s*${PROVENANCE_PREFIX}:\\\\s*[A-Za-z0-9+/=]+\\\\s*\\\\*\\\\/\\\\})\\\\s*\\\\n?`\n ),\n ''\n );\n const prefix = before.endsWith('\\n') ? before : `${before}\\n`;\n return `${prefix}${comment}\\n${replacedAfter.replace(/^\\n*/, '')}`;\n}\n\nfunction findFrontmatterEndOffset(content) {\n const text = String(content || '');\n if (!text.startsWith('---')) return -1;\n const lineBreak = text.includes('\\r\\n') ? '\\r\\n' : '\\n';\n const marker = `${lineBreak}---`;\n const markerIndex = text.indexOf(marker, 3);\n if (markerIndex < 0) return -1;\n const afterMarker = markerIndex + marker.length;\n if (text.startsWith(lineBreak, afterMarker)) return afterMarker + lineBreak.length;\n return afterMarker;\n}\n\nmodule.exports = {\n classifyLocalizedArtifactProvenance,\n buildProvenanceComment,\n injectOrReplaceProvenanceComment,\n parseProvenanceComment,\n sha256\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/enforce-generated-file-banners.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/docs-routes.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/provenance.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/validate-generated.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/enforce-generated-file-banners.js; indirect via tools/scripts/i18n/lib/docs-routes.js; indirect via tools/scripts/i18n/test/provenance.test.js; indirect via tools/scripts/i18n/translate-docs.js; indirect via tools/scripts/i18n/validate-generated.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/provider-mock.js",
+ "script": "provider-mock",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Mock translation provider — returns placeholder translations for testing without API calls",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/provider-mock.js [flags]",
+ "header": "/**\n * @script provider-mock\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Mock translation provider — returns placeholder translations for testing without API calls\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/provider-mock.js [flags]\n */\nfunction createMockTranslator() {\n return {\n name: 'mock',\n async translateStrings({ language, strings }) {\n return {\n strings: (strings || []).map((value) => `[${language}] ${String(value ?? '')}`),\n modelUsed: 'mock',\n attempts: 0\n };\n }\n };\n}\n\nmodule.exports = { createMockTranslator };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/providers.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/lib/providers.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/provider-openrouter.js",
+ "script": "provider-openrouter",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "OpenRouter translation provider — calls OpenRouter API for actual translations",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/provider-openrouter.js [flags]",
+ "header": "/**\n * @script provider-openrouter\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement OpenRouter translation provider — calls OpenRouter API for actual translations\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/provider-openrouter.js [flags]\n */\nconst { chunkArray } = require('./common');\n\nfunction sleep(ms) {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction assertOpenRouterConfig(config) {\n if (!config || typeof config !== 'object') throw new Error('Missing OpenRouter config');\n const models = config.modelCandidates || [];\n if (!Array.isArray(models) || models.length === 0) {\n throw new Error('OpenRouter modelCandidates must be a non-empty array');\n }\n}\n\nfunction getOpenRouterAuthHeaders(config = {}) {\n const apiKey = process.env.OPENROUTER_API_KEY || '';\n if (!apiKey) {\n throw new Error('OPENROUTER_API_KEY is required');\n }\n const headers = {\n Authorization: `Bearer ${apiKey}`,\n 'Content-Type': 'application/json'\n };\n const referer = process.env.OPENROUTER_HTTP_REFERER || process.env.GITHUB_SERVER_URL || '';\n if (referer) headers['HTTP-Referer'] = referer;\n const title = process.env.OPENROUTER_APP_NAME || 'livepeer-docs-i18n';\n if (title) headers['X-Title'] = title;\n return headers;\n}\n\nfunction buildPromptMessages({ language, kind, segments, rules }) {\n const preserveTerms = (rules?.preserveBrandTerms || []).join(', ');\n const system = [\n 'You translate documentation text while preserving Markdown/MDX syntax and placeholders.',\n 'Return strict JSON only.',\n 'Do not translate URLs, routes, code syntax, placeholders, or brand/product names that must be preserved.',\n preserveTerms ? `Preserve these exact terms: ${preserveTerms}` : ''\n ]\n .filter(Boolean)\n .join(' ');\n\n const userPayload = {\n task: 'translate_segments',\n language,\n kind,\n instructions: [\n 'Return a JSON object with key \"segments\".',\n 'segments must be an array of objects with keys: id, text.',\n 'Preserve ids exactly and keep segment count unchanged.',\n 'Preserve placeholders like __I18N_PH_#__ exactly.'\n ],\n segments: segments.map((segment) => ({ id: segment.id, text: segment.text }))\n };\n\n return [\n { role: 'system', content: system },\n { role: 'user', content: JSON.stringify(userPayload) }\n ];\n}\n\nfunction parseJsonFromModelContent(content) {\n const raw = String(content || '').trim();\n if (!raw) throw new Error('OpenRouter response content was empty');\n try {\n return JSON.parse(raw);\n } catch (_err) {\n const fenced = raw.match(/```(?:json)?\\s*([\\s\\S]*?)```/i);\n if (fenced) {\n return JSON.parse(fenced[1]);\n }\n const objectStart = raw.indexOf('{');\n const objectEnd = raw.lastIndexOf('}');\n if (objectStart >= 0 && objectEnd > objectStart) {\n return JSON.parse(raw.slice(objectStart, objectEnd + 1));\n }\n throw new Error('OpenRouter response was not valid JSON');\n }\n}\n\nfunction validateSegmentResponse(payload, requestSegments) {\n const responseSegments = payload?.segments;\n if (!Array.isArray(responseSegments)) {\n throw new Error('OpenRouter JSON response missing segments array');\n }\n if (responseSegments.length !== requestSegments.length) {\n throw new Error(`Segment count mismatch: expected ${requestSegments.length}, received ${responseSegments.length}`);\n }\n\n const byId = new Map();\n responseSegments.forEach((segment) => {\n byId.set(String(segment?.id), String(segment?.text ?? ''));\n });\n\n return requestSegments.map((segment) => {\n const key = String(segment.id);\n if (!byId.has(key)) {\n throw new Error(`Missing translated segment id \"${key}\"`);\n }\n return { id: segment.id, text: byId.get(key) };\n });\n}\n\nasync function requestCompletion({ config, model, messages }) {\n const controller = new AbortController();\n const timeoutMs = Number(config.requestTimeoutMs) || 60000;\n const timer = setTimeout(() => controller.abort(), timeoutMs);\n try {\n const response = await fetch(`${config.baseUrl || 'https://openrouter.ai/api/v1'}/chat/completions`, {\n method: 'POST',\n headers: getOpenRouterAuthHeaders(config),\n signal: controller.signal,\n body: JSON.stringify({\n model,\n temperature: Number.isFinite(config.temperature) ? config.temperature : 0.1,\n messages,\n response_format: { type: 'json_object' }\n })\n });\n\n if (!response.ok) {\n const body = await response.text();\n const error = new Error(`OpenRouter request failed (${response.status}): ${body.slice(0, 500)}`);\n error.status = response.status;\n error.headers =\n response.headers && typeof response.headers.entries === 'function'\n ? Object.fromEntries(response.headers.entries())\n : {};\n throw error;\n }\n\n const data = await response.json();\n const content = data?.choices?.[0]?.message?.content;\n return { data, content };\n } finally {\n clearTimeout(timer);\n }\n}\n\nfunction parseResetEpochMsFromError(error) {\n if (!error) return 0;\n const headers = error.headers || {};\n const headerReset = Number(headers['x-ratelimit-reset'] || headers['X-RateLimit-Reset'] || 0);\n if (Number.isFinite(headerReset) && headerReset > 0) {\n return headerReset > 1e12 ? headerReset : headerReset * 1000;\n }\n\n const message = String(error.message || '');\n const headerMatch = message.match(/X-RateLimit-Reset\\\\?\":\\\\?\"?(\\d{10,13})\"?/i);\n if (headerMatch) {\n const parsed = Number(headerMatch[1]);\n if (Number.isFinite(parsed) && parsed > 0) {\n return parsed > 1e12 ? parsed : parsed * 1000;\n }\n }\n return 0;\n}\n\nfunction getRetryDelayMs(error, attempt) {\n const status = Number(error?.status);\n const baseDelay = Math.min(30000, 2000 * 2 ** Math.max(0, attempt - 1));\n if (status !== 429) return baseDelay;\n\n const resetEpochMs = parseResetEpochMsFromError(error);\n if (resetEpochMs > 0) {\n const now = Date.now();\n const untilReset = resetEpochMs - now;\n if (untilReset > 0) {\n return Math.min(70000, untilReset + 750);\n }\n }\n return Math.min(60000, Math.max(baseDelay, 10000));\n}\n\nfunction isRetryableError(error) {\n if (!error) return false;\n if (error.name === 'AbortError') return true;\n const status = Number(error.status);\n const message = String(error.message || '');\n if (/OpenRouter response (content was empty|was not valid JSON)/i.test(message)) {\n return true;\n }\n if (/Segment count mismatch|Missing translated segment id/i.test(message)) {\n return true;\n }\n return status === 429 || (status >= 500 && status < 600);\n}\n\nfunction isModelFailoverError(error) {\n if (!error) return false;\n const status = Number(error.status);\n const message = String(error.message || '');\n if (/OpenRouter response (content was empty|was not valid JSON)/i.test(message)) {\n return true;\n }\n if (/Segment count mismatch|Missing translated segment id/i.test(message)) {\n return true;\n }\n if (\n status === 400 &&\n /(Developer instruction is not enabled|INVALID_ARGUMENT|response_format)/i.test(message)\n ) {\n return true;\n }\n // OpenRouter/provider-specific capacity or billing responses can be model/provider dependent.\n return status === 402 || status === 403 || status === 429 || (status >= 500 && status < 600);\n}\n\nfunction createOpenRouterTranslator(providerConfig, translationRules = {}) {\n assertOpenRouterConfig(providerConfig);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/lib/providers.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/provider-openrouter.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/lib/providers.js; indirect via tools/scripts/i18n/test/provider-openrouter.test.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/i18n/lib/providers.js",
+ "script": "providers",
+ "category": "utility",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Provider registry — selects translation provider (OpenRouter or mock) based on configuration",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/scripts/i18n/lib/providers.js [flags]",
+ "header": "/**\n * @script providers\n * @category utility\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Provider registry — selects translation provider (OpenRouter or mock) based on configuration\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/scripts/i18n/lib/providers.js [flags]\n */\nconst { createOpenRouterTranslator } = require('./provider-openrouter');\nconst { createMockTranslator } = require('./provider-mock');\n\nfunction createTranslator({ config, providerNameOverride = '' }) {\n const providerConfig = { ...(config.provider || {}) };\n const name = String(providerNameOverride || providerConfig.name || '').trim().toLowerCase();\n\n if (name === 'mock') {\n return createMockTranslator();\n }\n if (name === 'openrouter' || !name) {\n return createOpenRouterTranslator(providerConfig, config.translationRules || {});\n }\n\n throw new Error(`Unsupported i18n provider: ${name}`);\n}\n\nmodule.exports = { createTranslator };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/generate-localized-docs-json.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/test/provider-openrouter.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/i18n/generate-localized-docs-json.js; indirect via tools/scripts/i18n/test/provider-openrouter.test.js; indirect via tools/scripts/i18n/translate-docs.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/codex/task-preflight.js",
+ "script": "codex/task-preflight",
+ "category": "generator",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts/codex, .codex/task-contract.yaml, .codex/locks-local",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex task preflight — generates task setup files and validates preconditions",
+ "pipeline_declared": "manual — codex setup tool referenced by .githooks/pre-commit guidance, not auto-executed",
+ "usage": "node tools/scripts/codex/task-preflight.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex/task-preflight\n * @category generator\n * @purpose governance:agent-governance\n * @scope tools/scripts/codex, .codex/task-contract.yaml, .codex/locks-local\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex task preflight — generates task setup files and validates preconditions\n * @pipeline manual — codex setup tool referenced by .githooks/pre-commit guidance, not auto-executed\n * @usage node tools/scripts/codex/task-preflight.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst os = require('os');\nconst { spawnSync } = require('child_process');\n\nconst DEFAULT_BASE = 'docs-v2';\nconst DEFAULT_CONTRACT = '.codex/task-contract.yaml';\nconst LOCK_DIR_REL = '.codex/locks-local';\n\nconst REPO_ROOT = getRepoRoot();\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction slugify(value) {\n return String(value || '')\n .trim()\n .toLowerCase()\n .replace(/[^a-z0-9-]+/g, '-')\n .replace(/-{2,}/g, '-')\n .replace(/^-+|-+$/g, '');\n}\n\nfunction runGit(args, options = {}) {\n const result = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8', ...options });\n if (result.status !== 0) {\n const stderr = String(result.stderr || '').trim();\n const stdout = String(result.stdout || '').trim();\n throw new Error(stderr || stdout || `git ${args.join(' ')} failed`);\n }\n return String(result.stdout || '').trim();\n}\n\nfunction tryRunGit(args) {\n try {\n return runGit(args);\n } catch (_error) {\n return '';\n }\n}\n\nfunction parseArgs(argv) {\n const args = {\n taskId: null,\n slug: '',\n base: DEFAULT_BASE,\n scope: [],\n scopeFile: '',\n owner: `${process.env.USER || 'unknown'}@${os.hostname()}`,\n worktree: '',\n expiresHours: 8,\n contractPath: DEFAULT_CONTRACT,\n dryRun: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--task') {\n args.taskId = Number(argv[i + 1]);\n i += 1;\n continue;\n }\n if (token.startsWith('--task=')) {\n args.taskId = Number(token.slice('--task='.length));\n continue;\n }\n if (token === '--slug') {\n args.slug = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--slug=')) {\n args.slug = token.slice('--slug='.length).trim();\n continue;\n }\n if (token === '--base') {\n args.base = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--base=')) {\n args.base = token.slice('--base='.length).trim();\n continue;\n }\n if (token === '--scope') {\n args.scope = String(argv[i + 1] || '')\n .split(',')\n .map((entry) => toPosix(entry.trim()))\n .filter(Boolean);\n i += 1;\n continue;\n }\n if (token.startsWith('--scope=')) {\n args.scope = token\n .slice('--scope='.length)\n .split(',')\n .map((entry) => toPosix(entry.trim()))\n .filter(Boolean);\n continue;\n }\n if (token === '--scope-file') {\n args.scopeFile = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--scope-file=')) {\n args.scopeFile = token.slice('--scope-file='.length).trim();\n continue;\n }\n if (token === '--owner') {\n args.owner = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--owner=')) {\n args.owner = token.slice('--owner='.length).trim();\n continue;\n }\n if (token === '--worktree') {\n args.worktree = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--worktree=')) {\n args.worktree = token.slice('--worktree='.length).trim();\n continue;\n }\n if (token === '--expires-hours') {\n args.expiresHours = Number(argv[i + 1]);\n i += 1;\n continue;\n }\n if (token.startsWith('--expires-hours=')) {\n args.expiresHours = Number(token.slice('--expires-hours='.length));\n continue;\n }\n if (token === '--contract') {\n args.contractPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--contract=')) {\n args.contractPath = token.slice('--contract='.length).trim();\n continue;\n }\n if (token === '--dry-run') {\n args.dryRun = true;\n continue;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n return args;\n}\n\nfunction usage() {\n console.log('Usage: node tools/scripts/codex/task-preflight.js --task --slug (--scope | --scope-file ) [--base docs-v2] [--worktree ] [--dry-run]');\n}\n\nfunction readScopeFromFile(scopeFile) {\n if (!scopeFile) return [];\n const abs = path.resolve(REPO_ROOT, scopeFile);\n if (!fs.existsSync(abs)) {\n throw new Error(`Scope file not found: ${toPosix(path.relative(REPO_ROOT, abs))}`);\n }\n return fs\n .readFileSync(abs, 'utf8')\n .split(/\\r?\\n/)\n .map((line) => line.trim())\n .filter((line) => line && !line.startsWith('#'))\n .map((line) => toPosix(line));\n}\n\nfunction writeYamlContract(contractAbs, data) {\n const content = [\n `task_id: ${data.taskId}`,\n `branch: ${data.branch}`,\n `base_branch: ${data.base}`,\n 'scope_in:',\n ...data.scope.map((entry) => ` - ${entry}`),\n 'scope_out: []',\n 'allowed_generated:',\n ' - .codex/pr-body.generated.md',\n 'acceptance_checks:',\n ` - node tests/run-pr-checks.js --base-ref ${data.base}`,\n 'risk_flags:',\n ' - workflow-governance',\n 'follow_up_issues: []',\n ''\n ].join('\\n');\n\n fs.mkdirSync(path.dirname(contractAbs), { recursive: true });",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": ".githooks/pre-commit",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/codex/.codex/locks-local",
+ "type": "directory",
+ "call": "mkdirSync"
+ },
+ {
+ "output_path": "tools/scripts/codex/${lock.lock_id}.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": ", tools/scripts/codex/.codex/locks-local, tools/scripts/codex/${lock.lock_id}.json",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via .githooks/pre-commit",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-index-utils.js",
+ "script": "docs-index-utils",
+ "category": "utility",
+ "purpose": "governance:index-management",
+ "scope": "tools/lib, tools/scripts, v2",
+ "owner": "docs",
+ "needs": "R-R16, R-R17",
+ "purpose_statement": "Shared utilities for docs-index.json generation — path resolution, frontmatter extraction, index merging",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/lib/docs-index-utils.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script docs-index-utils\n * @category utility\n * @purpose governance:index-management\n * @scope tools/lib, tools/scripts, v2\n * @owner docs\n * @needs R-R16, R-R17\n * @purpose-statement Shared utilities for docs-index.json generation — path resolution, frontmatter extraction, index merging\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/lib/docs-index-utils.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst yaml = require('js-yaml');\n\nconst DOMAIN_RENAME_MAP = {\n '00_home': 'home',\n '010_products': 'solutions',\n '01_about': 'about',\n '02_community': 'community',\n '03_developers': 'developers',\n '04_gateways': 'gateways',\n '05_orchestrators': 'orchestrators',\n '06_lptoken': 'lpt',\n '07_resources': 'resources',\n '09_internal': 'internal',\n deprecated: 'deprecated',\n experimental: 'experimental',\n notes: 'notes'\n};\n\nconst DOMAIN_REVERSE_MAP = Object.fromEntries(\n Object.entries(DOMAIN_RENAME_MAP).map(([legacy, modern]) => [modern, legacy])\n);\n\nconst DIFFICULTY_BEGINNER = ['quickstart', 'getting-started', 'overview', 'intro', 'primer'];\nconst DIFFICULTY_ADVANCED = ['advanced', 'architecture', 'reference', 'api-reference', 'cli', 'sdk'];\n\nfunction getRepoRoot() {\n try {\n return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n } catch (_err) {\n return process.cwd();\n }\n}\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction normalizeRel(relPath) {\n return toPosix(relPath).replace(/^\\.\\//, '').replace(/^\\//, '');\n}\n\nfunction normalizeDocPathForUrl(relPath) {\n let normalized = normalizeRel(relPath);\n normalized = normalized.replace(/\\.(md|mdx)$/i, '');\n normalized = normalized.replace(/\\/index$/i, '');\n normalized = normalized.replace(/\\/+$/, '');\n return normalized;\n}\n\nfunction mapLegacyRepoPathToModern(repoRelPath) {\n const normalized = normalizeRel(repoRelPath);\n if (!normalized.startsWith('v2/pages/')) return normalized;\n const rest = normalized.slice('v2/pages/'.length);\n const [legacyDomain, ...tail] = rest.split('/').filter(Boolean);\n const modernDomain = DOMAIN_RENAME_MAP[legacyDomain] || legacyDomain;\n return normalizeRel(path.posix.join('v2', modernDomain, ...tail));\n}\n\nfunction mapModernRepoPathToLegacy(repoRelPath) {\n const normalized = normalizeRel(repoRelPath);\n if (!normalized.startsWith('v2/') || normalized.startsWith('v2/pages/')) return normalized;\n const rest = normalized.slice('v2/'.length);\n const [modernDomain, ...tail] = rest.split('/').filter(Boolean);\n const legacyDomain = DOMAIN_REVERSE_MAP[modernDomain];\n if (!legacyDomain) return normalized;\n return normalizeRel(path.posix.join('v2/pages', legacyDomain, ...tail));\n}\n\nfunction resolveDocPathCandidates(pagePath) {\n const normalized = normalizeRel(pagePath);\n const candidates = [];\n\n function pushVariants(p) {\n candidates.push(`${p}.mdx`);\n candidates.push(`${p}.md`);\n candidates.push(path.posix.join(p, 'index.mdx'));\n candidates.push(path.posix.join(p, 'index.md'));\n }\n\n pushVariants(normalized);\n const modern = mapLegacyRepoPathToModern(normalized);\n if (modern !== normalized) pushVariants(modern);\n const legacy = mapModernRepoPathToLegacy(normalized);\n if (legacy !== normalized) pushVariants(legacy);\n\n return [...new Set(candidates.map((candidate) => normalizeRel(candidate)))];\n}\n\nfunction resolveDocPath(pagePath, repoRoot) {\n const root = repoRoot || getRepoRoot();\n const candidates = resolveDocPathCandidates(pagePath);\n for (const candidate of candidates) {\n const absPath = path.join(root, candidate);\n if (fs.existsSync(absPath) && fs.statSync(absPath).isFile()) {\n return candidate;\n }\n }\n return null;\n}\n\nfunction extractFrontmatter(content) {\n const rawContent = String(content || '');\n const match = rawContent.match(/^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n?/);\n if (!match) {\n return { exists: false, data: null, raw: null, body: rawContent };\n }\n try {\n return {\n exists: true,\n data: yaml.load(match[1]) || {},\n raw: match[1],\n body: rawContent.slice(match[0].length)\n };\n } catch (error) {\n return {\n exists: true,\n data: null,\n raw: match[1],\n error: error.message,\n body: rawContent.slice(match[0].length)\n };\n }\n}\n\nfunction stripCodeFences(lines) {\n const result = [];\n let inFence = false;\n let fenceToken = null;\n for (const line of lines) {\n const fenceMatch = line.match(/^(```|~~~)/);\n if (fenceMatch) {\n const token = fenceMatch[1];\n if (!inFence) {\n inFence = true;\n fenceToken = token;\n } else if (token === fenceToken) {\n inFence = false;\n fenceToken = null;\n }\n continue;\n }\n if (!inFence) result.push(line);\n }\n return result;\n}\n\nfunction extractHeadings(body) {\n const lines = stripCodeFences(String(body || '').split('\\n'));\n return lines\n .map((line) => line.match(/^(#{1,6})\\s+(.+)$/))\n .filter(Boolean)\n .map((match) => ({ level: match[1].length, text: match[2].trim() }));\n}\n\nfunction extractCodeLanguages(content) {\n const lines = String(content || '').split('\\n');\n const languages = new Set();\n let inFence = false;\n let fenceToken = null;\n\n for (const line of lines) {\n const fenceMatch = line.match(/^(\\s*)(```|~~~)([^\\s]*)/);\n if (fenceMatch) {\n const token = fenceMatch[2];\n const lang = fenceMatch[3] ? fenceMatch[3].trim() : '';\n if (!inFence) {\n inFence = true;\n fenceToken = token;\n if (lang) languages.add(lang);\n } else if (token === fenceToken) {\n inFence = false;\n fenceToken = null;\n }\n }\n }\n\n return [...languages];\n}\n\nfunction stripForWordCount(body) {\n return String(body || '')\n .replace(/^import\\s.+$/gm, ' ')\n .replace(/```[\\s\\S]*?```/g, ' ')\n .replace(/~~~[\\s\\S]*?~~~/g, ' ')\n .replace(/`[^`]+`/g, ' ')\n .replace(/\\{\\/\\*[\\s\\S]*?\\*\\/\\}/g, ' ')\n .replace(/<[^>]+>/g, ' ')\n .replace(/\\[[^\\]]+\\]\\([^)]+\\)/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\nfunction countWords(text) {\n return String(text || '')\n .split(/\\s+/)\n .filter(Boolean).length;\n}\n\nfunction buildGitLastModifiedMap(repoRoot) {\n const root = repoRoot || getRepoRoot();\n const trackedRoots = ['v2/', 'docs-guide/', 'contribute/'];\n try {\n const output = execSync('git log --name-only --format=%cI -- v2 docs-guide contribute', {\n cwd: root,",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/notion/sync-v2-en-canonical.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-ai-sitemap.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-content-gap-reconciliation.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-docs-index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/notion/sync-v2-en-canonical.js; indirect via tools/scripts/generate-ai-sitemap.js; indirect via tools/scripts/generate-content-gap-reconciliation.js; indirect via tools/scripts/generate-docs-index.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/generated-file-banners.js",
+ "script": "generated-file-banners",
+ "category": "utility",
+ "purpose": "governance:index-management",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "R-R16, R-R17",
+ "purpose_statement": "Generated file banner template — provides standard banner text for auto-generated files",
+ "pipeline_declared": "indirect — library module imported by other scripts, not invoked directly",
+ "usage": "node tools/lib/generated-file-banners.js [flags]",
+ "header": "/**\n * @script generated-file-banners\n * @category utility\n * @purpose governance:index-management\n * @scope full-repo\n * @owner docs\n * @needs R-R16, R-R17\n * @purpose-statement Generated file banner template — provides standard banner text for auto-generated files\n * @pipeline indirect — library module imported by other scripts, not invoked directly\n * @usage node tools/lib/generated-file-banners.js [flags]\n */\nconst GENERATED_HIDDEN_MARKER = 'generated-file-banner:v1';\n\nfunction normalizeInline(value) {\n return String(value || '')\n .replace(/\\r?\\n/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\nfunction escapeYamlSingle(value) {\n return String(value || '').replace(/'/g, \"''\");\n}\n\nfunction asQuotedYaml(value) {\n return `'${escapeYamlSingle(value)}'`;\n}\n\nfunction parseFrontmatter(content) {\n const raw = String(content || '');\n if (!raw.startsWith('---')) {\n return {\n hasFrontmatter: false,\n frontmatter: '',\n body: raw\n };\n }\n\n const lineBreak = raw.includes('\\r\\n') ? '\\r\\n' : '\\n';\n const marker = `${lineBreak}---`;\n const markerIndex = raw.indexOf(marker, 3);\n if (markerIndex < 0) {\n return {\n hasFrontmatter: false,\n frontmatter: '',\n body: raw\n };\n }\n\n const frontmatter = raw.slice(0, markerIndex + marker.length);\n let body = raw.slice(markerIndex + marker.length);\n if (body.startsWith(lineBreak)) body = body.slice(lineBreak.length);\n\n return {\n hasFrontmatter: true,\n frontmatter,\n body\n };\n}\n\nfunction buildGeneratedFrontmatterLines(options = {}) {\n const title = normalizeInline(options.title);\n const sidebarTitle = normalizeInline(options.sidebarTitle);\n const description = normalizeInline(options.description);\n const pageType = normalizeInline(options.pageType);\n const keywords = Array.isArray(options.keywords) ? options.keywords.map((item) => normalizeInline(item)).filter(Boolean) : [];\n const keywordsStyle = options.keywordsStyle === 'multiline' ? 'multiline' : 'inline';\n const lines = ['---'];\n\n if (title) lines.push(`title: ${asQuotedYaml(title)}`);\n if (sidebarTitle) lines.push(`sidebarTitle: ${asQuotedYaml(sidebarTitle)}`);\n if (description) lines.push(`description: ${asQuotedYaml(description)}`);\n if (pageType) lines.push(`pageType: ${pageType}`);\n\n if (keywords.length > 0) {\n if (keywordsStyle === 'multiline') {\n lines.push('keywords:');\n lines.push(' [');\n keywords.forEach((keyword) => {\n lines.push(` ${asQuotedYaml(keyword)},`);\n });\n lines.push(' ]');\n } else {\n lines.push(`keywords: [${keywords.map((keyword) => asQuotedYaml(keyword)).join(', ')}]`);\n }\n }\n\n lines.push('---');\n return lines;\n}\n\nfunction buildGeneratedHiddenBannerLines(details = {}) {\n const marker = normalizeInline(details.marker) || GENERATED_HIDDEN_MARKER;\n return [\n '{/*',\n `generated-file-banner: ${marker}`,\n `Generation Script: ${normalizeInline(details.script)}`,\n `Purpose: ${normalizeInline(details.purpose)}`,\n `Run when: ${normalizeInline(details.runWhen)}`,\n `Run command: ${normalizeInline(details.runCommand)}`,\n '*/}'\n ];\n}\n\nfunction buildGeneratedNoteLines(details = {}) {\n return [\n '',\n `**Generation Script**: This file is generated from script(s): \\`${normalizeInline(details.script)}\\`.
`,\n `**Purpose**: ${normalizeInline(details.purpose)}
`,\n `**Run when**: ${normalizeInline(details.runWhen)}
`,\n `**Important**: Do not manually edit this file; run \\`${normalizeInline(details.runCommand)}\\`.
`,\n ' '\n ];\n}\n\nfunction parseGeneratedHiddenBanner(content) {\n const parsed = parseFrontmatter(content);\n const body = String(parsed.body || '');\n const commentRe = /\\{\\/\\*([\\s\\S]*?)\\*\\/\\}/g;\n let match;\n while ((match = commentRe.exec(body)) !== null) {\n const lines = match[1]\n .split('\\n')\n .map((line) => line.trim())\n .filter(Boolean);\n const map = new Map();\n lines.forEach((line) => {\n const idx = line.indexOf(':');\n if (idx < 0) return;\n const key = line.slice(0, idx).trim().toLowerCase();\n const value = line.slice(idx + 1).trim();\n map.set(key, value);\n });\n\n if (!map.has('generated-file-banner')) continue;\n\n return {\n found: true,\n marker: map.get('generated-file-banner') || '',\n script: map.get('generation script') || '',\n purpose: map.get('purpose') || '',\n runWhen: map.get('run when') || '',\n runCommand: map.get('run command') || '',\n raw: match[0]\n };\n }\n\n return {\n found: false,\n marker: '',\n script: '',\n purpose: '',\n runWhen: '',\n runCommand: '',\n raw: ''\n };\n}\n\nfunction hasGeneratedNote(content) {\n return /[\\s\\S]*?\\*\\*Generation Script\\*\\*:[\\s\\S]*?<\\/Note>/m.test(String(content || ''));\n}\n\nfunction extractGeneratedNote(content) {\n const match = String(content || '').match(/[\\s\\S]*?\\*\\*Generation Script\\*\\*:[\\s\\S]*?<\\/Note>/m);\n return match ? match[0] : '';\n}\n\nfunction removeGeneratedNotes(content) {\n return String(content || '').replace(/[\\s\\S]*?\\*\\*Generation Script\\*\\*:[\\s\\S]*?<\\/Note>\\s*/gm, '');\n}\n\nfunction hasFrontmatterKey(content, key) {\n const parsed = parseFrontmatter(content);\n if (!parsed.hasFrontmatter) return false;\n const re = new RegExp(`^\\\\s*${key}\\\\s*:`, 'm');\n return re.test(parsed.frontmatter);\n}\n\nmodule.exports = {\n GENERATED_HIDDEN_MARKER,\n buildGeneratedFrontmatterLines,\n buildGeneratedHiddenBannerLines,\n buildGeneratedNoteLines,\n parseFrontmatter,\n parseGeneratedHiddenBanner,\n hasGeneratedNote,\n extractGeneratedNote,\n removeGeneratedNotes,\n hasFrontmatterKey\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/script-docs.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/enforce-generated-file-banners.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-component-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-docs-guide-components-index.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-docs-guide-indexes.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-docs-guide-pages-index.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-pages-index.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/i18n/translate-docs.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/script-docs.test.js; indirect via tools/scripts/enforce-generated-file-banners.js; indirect via tools/scripts/generate-component-docs.js; indirect via tools/scripts/generate-docs-guide-components-index.js; indirect via tools/scripts/generate-docs-guide-indexes.js; indirect via tools/scripts/generate-docs-guide-pages-index.js; indirect via tools/scripts/generate-pages-index.js; indirect via tools/scripts/i18n/translate-docs.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/generate-component-docs.js",
+ "script": "generate-component-docs",
+ "category": "generator",
+ "purpose": "governance:index-management",
+ "scope": "generated-output",
+ "owner": "docs",
+ "needs": "R-R10",
+ "purpose_statement": "Generates published component library MDX pages from the registry.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/scripts/generate-component-docs.js [--template-only] [--category ]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-component-docs\n * @category generator\n * @purpose governance:index-management\n * @scope generated-output\n * @owner docs\n * @needs R-R10\n * @purpose-statement Generates published component library MDX pages from the registry.\n * @pipeline manual\n * @usage node tools/scripts/generate-component-docs.js [--template-only] [--category ]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { VALID_CATEGORIES } = require('../lib/component-governance-utils');\nconst {\n buildGeneratedHiddenBannerLines,\n buildGeneratedNoteLines\n} = require('../lib/generated-file-banners');\n\nconst REPO_ROOT = path.resolve(__dirname, '..', '..');\nconst REGISTRY_PATH = path.join(REPO_ROOT, 'docs-guide', 'component-registry.json');\nconst ENGLISH_OUTPUT_DIR = path.join(\n REPO_ROOT,\n 'v2',\n 'resources',\n 'documentation-guide',\n 'component-library'\n);\nconst LOCALE_DIRS = [\n path.join(REPO_ROOT, 'v2', 'es', 'resources', 'documentation-guide', 'component-library'),\n path.join(REPO_ROOT, 'v2', 'fr', 'resources', 'documentation-guide', 'component-library'),\n path.join(REPO_ROOT, 'v2', 'cn', 'resources', 'documentation-guide', 'component-library')\n];\n\nconst CATEGORY_LABELS = {\n primitives: 'Primitives',\n layout: 'Layout',\n content: 'Content',\n data: 'Data',\n 'page-structure': 'Page Structure'\n};\n\nconst CATEGORY_DESCRIPTIONS = {\n primitives: 'Standalone visual atoms used across authored documentation.',\n layout: 'Containers and arrangements that define spacing, grouping, and page flow.',\n content: 'Renderers for reader-facing media, code, quotations, and structured content.',\n data: 'Components that are coupled to feeds, release data, or other external sources.',\n 'page-structure': 'Portal and frame-mode scaffolding components that shape whole sections.'\n};\n\nfunction usage() {\n console.log(\n [\n 'Usage: node tools/scripts/generate-component-docs.js [options]',\n '',\n 'Options:',\n ' --template-only Use template prose only (default for this phase)',\n ' --category Regenerate one category page only',\n ' --help, -h Show this help message'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n templateOnly: true,\n category: '',\n help: false\n };\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n if (token === '--template-only') {\n args.templateOnly = true;\n continue;\n }\n if (token === '--category') {\n args.category = String(argv[index + 1] || '').trim();\n index += 1;\n continue;\n }\n if (token.startsWith('--category=')) {\n args.category = token.slice('--category='.length).trim();\n continue;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (args.category && !VALID_CATEGORIES.includes(args.category)) {\n throw new Error(`Unknown category: ${args.category}`);\n }\n\n return args;\n}\n\nfunction loadRegistry() {\n if (!fs.existsSync(REGISTRY_PATH)) {\n throw new Error('Missing docs-guide/component-registry.json. Run generate-component-registry first.');\n }\n\n return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));\n}\n\nfunction escapePipes(value) {\n return String(value || '').replace(/\\|/g, '\\\\|');\n}\n\nfunction renderGeneratedNote(scriptPath, runCommand) {\n const details = {\n script: scriptPath,\n purpose: 'Generated component-library MDX pages derived from docs-guide/component-registry.json.',\n runWhen: 'Component governance metadata, registry outputs, or published component-library templates change.',\n runCommand\n };\n\n return [...buildGeneratedHiddenBannerLines(details), '', ...buildGeneratedNoteLines(details), ''].join('\\n');\n}\n\nfunction renderDecisionTree() {\n return [\n '1. Bound to an external data source or automation pipeline? `data/`',\n '2. Only makes sense on frame-mode or portal pages? `page-structure/`',\n '3. Accepts children and arranges them spatially? `layout/`',\n '4. Formats or renders content for the reader? `content/`',\n '5. Otherwise: `primitives/`'\n ].join('\\n');\n}\n\nfunction renderPropsTable(params) {\n if (!params.length) {\n return 'No documented props.\\n';\n }\n\n const lines = [\n '| Prop | Type | Required | Default | Description |',\n '| --- | --- | --- | --- | --- |'\n ];\n\n params.forEach((param) => {\n lines.push(\n `| \\`${escapePipes(param.name)}\\` | \\`${escapePipes(param.type || 'any')}\\` | ${\n param.required ? 'Yes' : 'No'\n } | \\`${escapePipes(param.defaultValue || '')}\\` | ${escapePipes(param.description || '')} |`\n );\n });\n\n return `${lines.join('\\n')}\\n`;\n}\n\nfunction renderExample(example) {\n if (!example) return '';\n return ['```jsx', example.trim(), '```', ''].join('\\n');\n}\n\nfunction renderUsageSummary(component) {\n if (!component.usedIn.length) {\n return '`@usedIn`: none';\n }\n\n const preview = component.usedIn.slice(0, 6).map((entry) => `\\`${entry}\\``).join(', ');\n if (component.usedIn.length <= 6) {\n return `\\`@usedIn\\`: ${preview}`;\n }\n\n return `\\`@usedIn\\`: ${preview}, and ${component.usedIn.length - 6} more page(s)`;\n}\n\nfunction renderComponentSection(component) {\n return [\n `### ${component.name}`,\n '',\n component.description,\n '',\n `- File: \\`/${component.file}\\``,\n `- Tier: \\`${component.tier}\\``,\n `- Status: \\`${component.status}\\``,\n `- Risk: \\`${component.breakingChangeRisk}\\``,\n `- Decision: \\`${component.decision}\\``,\n `- Owner: \\`${component.owner}\\``,\n `- Content affinity: ${\n component.contentAffinity.length ? component.contentAffinity.map((value) => `\\`${value}\\``).join(', ') : '`none`'\n }`,\n `- Dependencies: ${\n component.dependencies.length ? component.dependencies.map((value) => `\\`${value}\\``).join(', ') : '`none`'\n }`,\n `- Data source: \\`${component.dataSource || 'none'}\\``,\n `- Duplicates: ${\n component.duplicates.length ? component.duplicates.map((value) => `\\`${value}\\``).join(', ') : '`none`'\n }`,\n `- Last meaningful change: \\`${component.lastMeaningfulChange}\\``,\n `- ${renderUsageSummary(component)}`,\n component.status === 'deprecated' && component.deprecated\n ? `- Deprecation note: ${component.deprecated}${component.see ? ` See \\`${component.see}\\`.` : ''}`\n : null,\n '',\n '**Import**',\n '',\n '```jsx',\n `import { ${component.name} } from '/${component.file}'`,\n '```',\n '',\n '**Props**',\n '',\n renderPropsTable(component.params),\n component.examples.length\n ? ['**Example**', '', renderExample(component.examples[0])].join('\\n')\n : ''\n ]\n .filter(Boolean)\n .join('\\n');\n}\n\nfunction renderCategoryPage(category, components) {\n const label = CATEGORY_LABELS[category];",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/component-governance-generators.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-docs-guide-components-index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/component-governance-generators.test.js; indirect via tools/scripts/generate-docs-guide-components-index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/scan-component-imports.js",
+ "script": "scan-component-imports",
+ "category": "generator",
+ "purpose": "governance:index-management",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "R-R10",
+ "purpose_statement": "Scans MDX imports to produce component-usage-map.json and detect @usedIn drift.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/scripts/scan-component-imports.js [--verify]",
+ "header": "#!/usr/bin/env node\n/**\n * @script scan-component-imports\n * @category generator\n * @purpose governance:index-management\n * @scope full-repo\n * @owner docs\n * @needs R-R10\n * @purpose-statement Scans MDX imports to produce component-usage-map.json and detect @usedIn drift.\n * @pipeline manual\n * @usage node tools/scripts/scan-component-imports.js [--verify]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst {\n extractExports,\n getComponentFiles,\n parseJSDocBlock,\n scanMDXImports\n} = require('../lib/component-governance-utils');\nconst { buildRegistry } = require('./generate-component-registry');\n\nconst REPO_ROOT = path.resolve(__dirname, '..', '..');\nconst OUTPUT_PATH = path.join(REPO_ROOT, 'docs-guide', 'component-usage-map.json');\nconst REGISTRY_PATH = path.join(REPO_ROOT, 'docs-guide', 'component-registry.json');\n\nfunction isPublishedDocsPath(filePath) {\n return !/^v2(?:\\/(?:cn|es|fr))?\\/x-(archived|deprecated|experimental|notes)\\//.test(\n String(filePath || '').trim()\n );\n}\n\nfunction usage() {\n console.log(\n [\n 'Usage: node tools/scripts/scan-component-imports.js [options]',\n '',\n 'Options:',\n ' --verify Compare live imports with @usedIn declarations and fail on drift',\n ' --help, -h Show this help message'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n verify: false,\n help: false\n };\n\n argv.forEach((token) => {\n if (token === '--verify') {\n args.verify = true;\n return;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n return;\n }\n throw new Error(`Unknown argument: ${token}`);\n });\n\n return args;\n}\n\nfunction sortStrings(values) {\n return [...new Set(values)].sort((left, right) =>\n left.localeCompare(right, 'en', { sensitivity: 'base' })\n );\n}\n\nfunction readRegistry() {\n if (fs.existsSync(REGISTRY_PATH)) {\n return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));\n }\n\n return buildRegistry().registry;\n}\n\nfunction collectDeclaredUsage() {\n const usage = new Map();\n\n getComponentFiles().forEach((file) => {\n extractExports(file.displayPath).forEach((entry) => {\n if (!entry.jsDocBlock) return;\n const parsed = parseJSDocBlock(entry.jsDocBlock);\n usage.set(\n entry.name,\n sortStrings(\n String(parsed.usedIn || '')\n .split(',')\n .map((value) => value.trim())\n .filter((value) => value && value.toLowerCase() !== 'none' && isPublishedDocsPath(value))\n )\n );\n });\n });\n\n return usage;\n}\n\nfunction buildUsageMap() {\n const registry = readRegistry();\n const liveImports = scanMDXImports('v2/**/*.mdx');\n const declaredUsage = collectDeclaredUsage();\n\n const components = registry.components.map((component) => {\n const actual = liveImports.get(component.name) || {\n pages: [],\n count: 0,\n localeBreakdown: { en: 0, es: 0, fr: 0, cn: 0, other: 0 }\n };\n const actualPages = sortStrings(actual.pages);\n const declaredPages = declaredUsage.get(component.name) || [];\n const missingFromJsDoc = actualPages.filter((page) => !declaredPages.includes(page));\n const staleInJsDoc = declaredPages.filter((page) => !actualPages.includes(page));\n\n return {\n name: component.name,\n file: component.file,\n category: component.category,\n count: actual.count,\n pages: actualPages,\n localeBreakdown: actual.localeBreakdown,\n declaredUsedIn: declaredPages,\n drift: {\n missingFromJsDoc,\n staleInJsDoc\n }\n };\n });\n\n const orphaned = components\n .filter((component) => component.pages.length === 0)\n .map((component) => ({\n name: component.name,\n file: component.file,\n category: component.category\n }));\n\n const mostImported = [...components]\n .sort((left, right) => {\n if (right.count !== left.count) return right.count - left.count;\n return left.name.localeCompare(right.name, 'en', { sensitivity: 'base' });\n })\n .slice(0, 25)\n .map((component, index) => ({\n rank: index + 1,\n name: component.name,\n category: component.category,\n count: component.count\n }));\n\n const drift = components\n .filter((component) => component.drift.missingFromJsDoc.length || component.drift.staleInJsDoc.length)\n .map((component) => ({\n name: component.name,\n file: component.file,\n missingFromJsDoc: component.drift.missingFromJsDoc,\n staleInJsDoc: component.drift.staleInJsDoc\n }));\n\n return {\n usageMap: {\n _meta: {\n generated: new Date().toISOString(),\n generator: 'tools/scripts/scan-component-imports.js',\n componentCount: components.length\n },\n components,\n orphaned,\n mostImported\n },\n drift\n };\n}\n\nfunction run(argv = process.argv.slice(2)) {\n let args;\n try {\n args = parseArgs(argv);\n } catch (error) {\n console.error(`❌ ${error.message}`);\n usage();\n return 1;\n }\n\n if (args.help) {\n usage();\n return 0;\n }\n\n const { usageMap, drift } = buildUsageMap();\n fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });\n fs.writeFileSync(OUTPUT_PATH, `${JSON.stringify(usageMap, null, 2)}\\n`, 'utf8');\n console.log(`Wrote ${path.relative(REPO_ROOT, OUTPUT_PATH)}`);\n\n if (args.verify && drift.length > 0) {\n console.error('❌ @usedIn drift detected:');\n drift.forEach((entry) => {\n if (entry.missingFromJsDoc.length > 0) {\n console.error(`- ${entry.file} :: ${entry.name} missing from @usedIn: ${entry.missingFromJsDoc.join(', ')}`);\n }\n if (entry.staleInJsDoc.length > 0) {\n console.error(`- ${entry.file} :: ${entry.name} stale @usedIn entries: ${entry.staleInJsDoc.join(', ')}`);\n }\n });\n return 1;\n }\n\n if (args.verify) {\n console.log('No @usedIn drift detected.');\n }\n\n return 0;\n}\n\nif (require.main === module) {\n process.exit(run());",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/component-governance-generators.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/component-usage-map.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/component-usage-map.json",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/component-governance-generators.test.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/component-governance-utils.js",
+ "script": "component-governance-utils",
+ "category": "utility",
+ "purpose": "governance:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R10",
+ "purpose_statement": "Shared parsing and validation utilities for component governance scripts.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const utils = require('../lib/component-governance-utils');",
+ "header": "/**\n * @script component-governance-utils\n * @category utility\n * @purpose governance:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R10\n * @purpose-statement Shared parsing and validation utilities for component governance scripts.\n * @pipeline indirect -- library module\n * @usage const utils = require('../lib/component-governance-utils');\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst VALID_CATEGORIES = ['primitives', 'layout', 'content', 'data', 'page-structure'];\nconst VALID_STATUSES = ['stable', 'experimental', 'deprecated', 'broken', 'placeholder'];\nconst VALID_TIERS = ['primitive', 'composite', 'pattern'];\nconst VALID_RISKS = ['low', 'medium', 'high'];\nconst VALID_DECISIONS = ['KEEP', 'MOVE', 'SPLIT', 'MERGE', 'REMOVE'];\nconst VALID_CONTENT_AFFINITY = [\n 'landing',\n 'overview',\n 'tutorial',\n 'how_to',\n 'concept',\n 'reference',\n 'faq',\n 'troubleshooting',\n 'changelog',\n 'glossary',\n 'universal'\n];\nconst GOVERNANCE_FIELDS = [\n 'component',\n 'category',\n 'tier',\n 'status',\n 'description',\n 'contentAffinity',\n 'owner',\n 'dependencies',\n 'usedIn',\n 'breakingChangeRisk',\n 'decision',\n 'dataSource',\n 'duplicates',\n 'lastMeaningfulChange'\n];\nconst COMPONENT_IMPORT_RE = /import\\s*\\{([\\s\\S]*?)\\}\\s*from\\s*['\"]([^'\"]+)['\"]/g;\nconst COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\\b|\\brgba?\\([^)]*\\)|\\bhsla?\\([^)]*\\)/g;\nconst COLOR_CONTEXT_RE = /\\b(?:accentcolor|background(?:color)?|border(?:color)?|caretcolor|color|fill|floodcolor|icon|lightingcolor|outlinecolor|stopcolor|stroke|textdecorationcolor)\\b/;\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nconst REPO_ROOT = getRepoRoot();\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction compactWhitespace(value) {\n return String(value || '').replace(/\\s+/g, ' ').trim();\n}\n\nfunction lineNumberAt(content, index) {\n return String(content || '').slice(0, Math.max(0, index)).split('\\n').length;\n}\n\nfunction normalizeRepoPath(inputPath) {\n const raw = String(inputPath || '').trim();\n const absolute = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(REPO_ROOT, raw);\n return toPosix(path.relative(REPO_ROOT, absolute));\n}\n\nfunction isArchivePath(filePath) {\n return toPosix(filePath).split('/').includes('_archive');\n}\n\nfunction getCategoryFromPath(filePath) {\n const parts = toPosix(filePath).split('/');\n const index = parts.findIndex((part) => part === 'components');\n if (index === -1) return '';\n const candidate = parts[index + 1] || '';\n return VALID_CATEGORIES.includes(candidate) ? candidate : '';\n}\n\nfunction walkFiles(targetPath, predicate, files = []) {\n if (!fs.existsSync(targetPath)) return files;\n const stat = fs.statSync(targetPath);\n if (stat.isFile()) {\n if (predicate(targetPath)) files.push(targetPath);\n return files;\n }\n\n const entries = fs.readdirSync(targetPath, { withFileTypes: true });\n entries.forEach((entry) => {\n if (entry.name === '.git' || entry.name === 'node_modules') return;\n walkFiles(path.join(targetPath, entry.name), predicate, files);\n });\n return files;\n}\n\nfunction getComponentFiles(baseDir = 'snippets/components') {\n const absoluteBase = path.isAbsolute(baseDir) ? baseDir : path.join(REPO_ROOT, baseDir);\n return walkFiles(\n absoluteBase,\n (absolutePath) =>\n absolutePath.endsWith('.jsx') &&\n !isArchivePath(absolutePath) &&\n VALID_CATEGORIES.includes(getCategoryFromPath(absolutePath))\n )\n .map((absolutePath) => ({\n absolutePath,\n displayPath: normalizeRepoPath(absolutePath)\n }))\n .sort((a, b) => a.displayPath.localeCompare(b.displayPath, 'en', { sensitivity: 'base' }));\n}\n\nfunction stripComments(value) {\n return String(value || '')\n .replace(/\\/\\*[\\s\\S]*?\\*\\//g, '')\n .replace(/\\/\\/.*$/gm, '')\n .trim();\n}\n\nfunction splitTopLevel(input, separator = ',') {\n const parts = [];\n let current = '';\n let depthParen = 0;\n let depthBrace = 0;\n let depthBracket = 0;\n let quote = null;\n let escaped = false;\n\n for (let index = 0; index < input.length; index += 1) {\n const char = input[index];\n\n if (quote) {\n current += char;\n if (!escaped && char === '\\\\') {\n escaped = true;\n } else if (!escaped && char === quote) {\n quote = null;\n } else {\n escaped = false;\n }\n continue;\n }\n\n if (char === '\"' || char === \"'\" || char === '`') {\n quote = char;\n current += char;\n continue;\n }\n\n if (char === '(') depthParen += 1;\n else if (char === ')') depthParen = Math.max(0, depthParen - 1);\n else if (char === '{') depthBrace += 1;\n else if (char === '}') depthBrace = Math.max(0, depthBrace - 1);\n else if (char === '[') depthBracket += 1;\n else if (char === ']') depthBracket = Math.max(0, depthBracket - 1);\n\n if (\n char === separator &&\n depthParen === 0 &&\n depthBrace === 0 &&\n depthBracket === 0\n ) {\n parts.push(current.trim());\n current = '';\n continue;\n }\n\n current += char;\n }\n\n if (current.trim()) {\n parts.push(current.trim());\n }\n\n return parts;\n}\n\nfunction splitTopLevelOnce(input, separator) {\n const parts = splitTopLevel(input, separator);\n if (parts.length <= 1) return [input.trim(), ''];\n const first = parts.shift();\n return [first, parts.join(separator).trim()];\n}\n\nfunction findMatchingBracket(input, startIndex, openChar, closeChar) {\n let depth = 0;\n let quote = null;\n let escaped = false;\n\n for (let index = startIndex; index < input.length; index += 1) {\n const char = input[index];\n\n if (quote) {\n if (!escaped && char === '\\\\') {\n escaped = true;\n } else if (!escaped && char === quote) {\n quote = null;\n } else {\n escaped = false;\n }\n continue;\n }\n\n if (char === '\"' || char === \"'\" || char === '`') {\n quote = char;\n continue;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/component-governance-utils.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-component-docs.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-component-registry.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-docs-guide-components-index.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/scan-component-imports.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/components/check-component-css.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/components/check-component-docs.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/component-governance-utils.test.js; indirect via tools/scripts/generate-component-docs.js; indirect via tools/scripts/generate-component-registry.js; indirect via tools/scripts/generate-docs-guide-components-index.js; indirect via tools/scripts/scan-component-imports.js; indirect via tools/scripts/validators/components/check-component-css.js; indirect via tools/scripts/validators/components/check-component-docs.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/script-governance-config.js",
+ "script": "script-governance-config",
+ "category": "utility",
+ "purpose": "governance:repo-health",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "R-R14, R-R18, R-C6",
+ "purpose_statement": "Shared governance constants for script discovery, indexing, classification, and pipeline normalisation across the repo.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const config = require('../lib/script-governance-config');",
+ "header": "/**\n * @script script-governance-config\n * @category utility\n * @purpose governance:repo-health\n * @scope full-repo\n * @owner docs\n * @needs R-R14, R-R18, R-C6\n * @purpose-statement Shared governance constants for script discovery, indexing, classification, and pipeline normalisation across the repo.\n * @pipeline indirect -- library module\n * @usage const config = require('../lib/script-governance-config');\n */\n\nconst path = require('path');\n\nconst DISCOVERY_ROOTS = [\n '.githooks',\n '.github/scripts',\n 'tasks/scripts',\n 'tests/unit',\n 'tests/integration',\n 'tests/utils',\n 'tests',\n 'tools/scripts',\n 'tools/lib',\n 'tools/notion',\n 'tools/config',\n 'snippets/automations'\n];\n\nconst GOVERNED_ROOTS = [\n '.githooks',\n '.github/scripts',\n 'tests',\n 'tools/scripts',\n 'tools/lib',\n 'tools/notion',\n 'tools/config',\n 'tasks/scripts',\n 'snippets/automations'\n];\n\nconst INDEXED_ROOTS = [\n '.githooks',\n '.github/scripts',\n 'tests',\n 'tools/scripts',\n 'tools/lib',\n 'tools/notion',\n 'tools/config',\n 'tasks/scripts',\n 'snippets/automations'\n];\n\nconst GROUP_INDEX_MAP = [\n { root: '.githooks', index: '.githooks/script-index.md' },\n { root: '.github/scripts', index: '.github/script-index.md' },\n { root: 'tests', index: 'tests/script-index.md' },\n { root: 'tools/scripts', index: 'tools/script-index.md' },\n { root: 'tools/lib', index: 'tools/lib/script-index.md' },\n { root: 'tools/notion', index: 'tools/notion/script-index.md' },\n { root: 'tools/config', index: 'tools/config/script-index.md' },\n { root: 'tasks/scripts', index: 'tasks/scripts/script-index.md' },\n { root: 'snippets/automations', index: 'snippets/automations/script-index.md' }\n];\nconst GROUP_INDEX_PATHS = GROUP_INDEX_MAP.map((entry) => entry.index);\n\nconst AGGREGATE_INDEX_PATH = 'docs-guide/indexes/scripts-index.mdx';\nconst LEGACY_AGGREGATE_INDEX_PATH = 'docs-guide/indexes/scripts-index.md';\nconst CLASSIFICATION_DATA_PATH = 'tasks/reports/script-classifications.json';\n\nconst SCRIPT_EXTENSIONS = ['.js', '.sh', '.py'];\nconst SCRIPT_EXTENSIONS_SET = new Set(SCRIPT_EXTENSIONS);\n\nconst EXCLUDED_PREFIXES = ['node_modules/', '.git/', 'tools/scripts/archive/'];\nconst EXCLUDED_SEGMENTS = ['node_modules', '.git'];\n\nconst FRAMEWORK_FIELDS = [\n { key: 'script', tag: '@script' },\n { key: 'category', tag: '@category' },\n { key: 'purpose', tag: '@purpose' },\n { key: 'scope', tag: '@scope' },\n { key: 'owner', tag: '@owner' },\n { key: 'needs', tag: '@needs' },\n { key: 'purpose_statement', tag: '@purpose-statement' },\n { key: 'pipeline', tag: '@pipeline' },\n { key: 'usage', tag: '@usage' }\n];\n\nconst REQUIRED_FRAMEWORK_KEYS = ['script', 'category', 'purpose', 'scope', 'owner', 'usage'];\n\nconst CATEGORY_ENUM = [\n 'validator',\n 'enforcer',\n 'remediator',\n 'generator',\n 'automation',\n 'utility',\n 'orchestrator'\n];\n\nconst PURPOSE_ENUM = [\n 'qa:content-quality',\n 'qa:link-integrity',\n 'qa:repo-health',\n 'governance:index-management',\n 'governance:agent-governance',\n 'governance:repo-health',\n 'feature:translation',\n 'feature:seo',\n 'infrastructure:data-feeds',\n 'infrastructure:pipeline-orchestration',\n 'tooling:api-spec',\n 'tooling:dev-tools'\n];\n\nconst SCOPE_ENUM = [\n 'staged',\n 'changed',\n 'full-repo',\n 'v2-content',\n 'single-domain',\n 'single-file',\n 'external',\n 'generated-output'\n];\n\nconst GROUP_LABELS = {\n Unmanaged: 'Unmanaged',\n Orphaned: 'Orphaned',\n P1: 'P1 - Commit gate',\n P2: 'P2 - Push gate',\n P3: 'P3 - PR gate',\n P5: 'P5 - Scheduled',\n P6: 'P6 - On-demand',\n Indirect: 'Indirect - Library',\n Manual: 'Manual - CLI only'\n};\n\nconst GROUP_ORDER = ['Unmanaged', 'Orphaned', 'P1', 'P2', 'P3', 'P5', 'P6', 'Indirect', 'Manual'];\nconst PIPELINE_ORDER = ['P1', 'P2', 'P3', 'P5', 'P6', 'indirect', 'manual'];\n\nfunction normalizeRepoPath(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction pathHasExcludedSegment(repoPath) {\n const parts = normalizeRepoPath(repoPath).split('/');\n return parts.some((part) => EXCLUDED_SEGMENTS.includes(part));\n}\n\nfunction shouldExcludeScriptPath(repoPath) {\n const normalized = normalizeRepoPath(repoPath);\n if (!normalized) return true;\n if (EXCLUDED_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return true;\n if (pathHasExcludedSegment(normalized)) return true;\n return normalized.includes('.bak') || normalized.endsWith('.disabled');\n}\n\nfunction isWithinRoots(repoPath, roots) {\n const normalized = normalizeRepoPath(repoPath);\n return roots.some((root) => normalized === root || normalized.startsWith(`${root}/`));\n}\n\nfunction isHookScriptPath(repoPath) {\n const normalized = normalizeRepoPath(repoPath);\n return normalized.startsWith('.githooks/') && path.extname(normalized) === '';\n}\n\nfunction isDiscoveredScriptPath(repoPath) {\n const normalized = normalizeRepoPath(repoPath);\n if (shouldExcludeScriptPath(normalized)) return false;\n if (!isWithinRoots(normalized, DISCOVERY_ROOTS)) return false;\n const ext = path.extname(normalized).toLowerCase();\n return SCRIPT_EXTENSIONS_SET.has(ext) || isHookScriptPath(normalized);\n}\n\nfunction parseDeclaredPipelines(rawValue) {\n const raw = String(rawValue || '').trim();\n const found = new Set();\n if (!raw) return found;\n for (const match of raw.match(/\\bP[1-6]\\b/g) || []) {\n found.add(match);\n }\n if (/manual/i.test(raw)) found.add('manual');\n if (/indirect/i.test(raw)) found.add('indirect');\n return found;\n}\n\nmodule.exports = {\n AGGREGATE_INDEX_PATH,\n CATEGORY_ENUM,\n CLASSIFICATION_DATA_PATH,\n DISCOVERY_ROOTS,\n EXCLUDED_PREFIXES,\n FRAMEWORK_FIELDS,\n GOVERNED_ROOTS,\n GROUP_INDEX_MAP,\n GROUP_INDEX_PATHS,\n GROUP_LABELS,\n GROUP_ORDER,\n INDEXED_ROOTS,\n LEGACY_AGGREGATE_INDEX_PATH,\n PIPELINE_ORDER,\n PURPOSE_ENUM,\n REQUIRED_FRAMEWORK_KEYS,\n SCOPE_ENUM,\n SCRIPT_EXTENSIONS,\n isDiscoveredScriptPath,\n isHookScriptPath,\n isWithinRoots,\n normalizeRepoPath,\n parseDeclaredPipelines,\n shouldExcludeScriptPath\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/script-docs.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/governance/audit-script-inventory.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/run-pr-checks.js; indirect via tests/unit/script-docs.test.js; indirect via tools/scripts/validators/governance/audit-script-inventory.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/audit-media-assets.js",
+ "script": "audit-media-assets",
+ "category": "utility",
+ "purpose": "governance:repo-health",
+ "scope": "tools/scripts, tasks/reports/media-audit",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Audits repo media assets, references, ignore leakage, and externalized asset branch inventory.",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/audit-media-assets.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script audit-media-assets\n * @category utility\n * @purpose governance:repo-health\n * @scope tools/scripts, tasks/reports/media-audit\n * @owner docs\n * @needs R-R14\n * @purpose-statement Audits repo media assets, references, ignore leakage, and externalized asset branch inventory.\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/audit-media-assets.js [flags]\n */\n\nconst fs = require('fs')\nconst path = require('path')\nconst { execSync, spawnSync } = require('child_process')\n\nconst REPO_ROOT = process.cwd()\nconst DEFAULT_MANIFEST_PATH = 'tasks/reports/media-audit/media-audit-manifest.json'\nconst DEFAULT_SUMMARY_PATH = 'tasks/reports/media-audit/media-audit-summary.md'\nconst DEFAULT_ASSETS_BRANCH_REF = 'origin/docs-v2-assets'\nconst ONE_MB = 1024 * 1024\nconst FIVE_MB = 5 * ONE_MB\nconst TARGET_EXTENSIONS = new Set([\n '.mp4',\n '.mov',\n '.webm',\n '.gif',\n '.png',\n '.jpg',\n '.jpeg',\n '.webp',\n '.pdf',\n])\nconst SOURCE_EXTENSIONS = new Set(['.mdx', '.jsx'])\nconst RAW_ASSET_BRANCH_NAMES = ['assets', 'docs-v2-assets']\n\nfunction usage() {\n console.log(\n 'Usage: node tools/scripts/audit-media-assets.js [--manifest ] [--summary ] [--assets-branch-ref ] [--check-staged]'\n )\n}\n\nfunction parseArgs(argv) {\n const options = {\n manifestPath: DEFAULT_MANIFEST_PATH,\n summaryPath: DEFAULT_SUMMARY_PATH,\n assetsBranchRef: DEFAULT_ASSETS_BRANCH_REF,\n checkStaged: false,\n }\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i]\n\n if (token === '--help' || token === '-h') {\n usage()\n process.exit(0)\n }\n\n if (token === '--check-staged') {\n options.checkStaged = true\n continue\n }\n\n if (token === '--manifest') {\n options.manifestPath = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n\n if (token.startsWith('--manifest=')) {\n options.manifestPath = token.slice('--manifest='.length).trim()\n continue\n }\n\n if (token === '--summary') {\n options.summaryPath = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n\n if (token.startsWith('--summary=')) {\n options.summaryPath = token.slice('--summary='.length).trim()\n continue\n }\n\n if (token === '--assets-branch-ref') {\n options.assetsBranchRef = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n\n if (token.startsWith('--assets-branch-ref=')) {\n options.assetsBranchRef = token.slice('--assets-branch-ref='.length).trim()\n continue\n }\n\n console.error(`Unknown argument: ${token}`)\n usage()\n process.exit(1)\n }\n\n if (!options.manifestPath) {\n console.error('Missing --manifest value')\n usage()\n process.exit(1)\n }\n\n if (!options.summaryPath) {\n console.error('Missing --summary value')\n usage()\n process.exit(1)\n }\n\n if (!options.assetsBranchRef) {\n console.error('Missing --assets-branch-ref value')\n usage()\n process.exit(1)\n }\n\n return options\n}\n\nfunction normalizeRepoPath(value) {\n return String(value || '')\n .replace(/^\\.\\//, '')\n .split(path.sep)\n .join('/')\n}\n\nfunction absoluteFromRepoPath(repoPath) {\n return path.join(REPO_ROOT, normalizeRepoPath(repoPath))\n}\n\nfunction ensureDirForFile(repoPath) {\n fs.mkdirSync(path.dirname(absoluteFromRepoPath(repoPath)), { recursive: true })\n}\n\nfunction fileExists(repoPath) {\n try {\n return fs.statSync(absoluteFromRepoPath(repoPath)).isFile()\n } catch (_err) {\n return false\n }\n}\n\nfunction readFileUtf8(repoPath) {\n return fs.readFileSync(absoluteFromRepoPath(repoPath), 'utf8')\n}\n\nfunction escapeRegExp(value) {\n return String(value || '').replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n}\n\nfunction uniqueSorted(values) {\n return [...new Set(values.map((value) => normalizeRepoPath(value)).filter(Boolean))].sort()\n}\n\nfunction runShell(command, options = {}) {\n const allowFailure = Boolean(options.allowFailure)\n try {\n return execSync(command, {\n cwd: REPO_ROOT,\n encoding: 'utf8',\n stdio: ['ignore', 'pipe', 'pipe'],\n })\n } catch (error) {\n if (allowFailure) return ''\n const stderr = String(error.stderr || '').trim()\n const stdout = String(error.stdout || '').trim()\n const detail = stderr || stdout || error.message\n throw new Error(`Command failed: ${command}\\n${detail}`)\n }\n}\n\nfunction runCommand(command, args, options = {}) {\n const allowFailure = Boolean(options.allowFailure)\n const result = spawnSync(command, args, {\n cwd: REPO_ROOT,\n encoding: options.encoding === 'buffer' ? null : 'utf8',\n stdio: ['ignore', 'pipe', 'pipe'],\n })\n\n if (result.status === 0) {\n return options.encoding === 'buffer' ? result.stdout : String(result.stdout || '')\n }\n\n if (allowFailure) {\n return options.encoding === 'buffer' ? Buffer.alloc(0) : ''\n }\n\n const stderr = options.encoding === 'buffer'\n ? String(result.stderr || '')\n : String(result.stderr || '').trim()\n const stdout = options.encoding === 'buffer'\n ? String(result.stdout || '')\n : String(result.stdout || '').trim()\n const detail = stderr || stdout || `exit ${result.status}`\n throw new Error(`Command failed: ${command} ${args.join(' ')}\\n${detail}`)\n}\n\nfunction splitNullDelimited(value) {\n return String(value || '')\n .split('\\0')\n .map((entry) => normalizeRepoPath(entry.trim()))\n .filter(Boolean)\n}\n\nfunction getTrackedFiles() {\n return splitNullDelimited(runCommand('git', ['ls-files', '-z']))\n}\n\nfunction getStagedFiles() {\n return splitNullDelimited(\n runCommand('git', ['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMR'])\n )\n}\n\nfunction collectUniverseFiles(checkStaged) {\n return checkStaged ? getStagedFiles() : getTrackedFiles()",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/remediators/assets/migrate-assets-to-branch.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": false,
+ "purpose_match": false,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/remediators/assets/migrate-assets-to-branch.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope",
+ "header-json-category-mismatch",
+ "header-json-purpose-mismatch"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/remediators/assets/migrate-assets-to-branch.js",
+ "script": "migrate-assets-to-branch",
+ "category": "remediator",
+ "purpose": "governance:repo-health",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Reads the media-audit manifest and migrates flagged assets to the",
+ "pipeline_declared": "manual",
+ "usage": "node tools/scripts/remediators/assets/migrate-assets-to-branch.js \\",
+ "header": "#!/usr/bin/env node\n/**\n * @script migrate-assets-to-branch\n * @category remediator\n * @purpose governance:repo-health\n * @scope full-repo\n * @owner docs\n * @needs R-R14\n * @purpose-statement Reads the media-audit manifest and migrates flagged assets to the\n * docs-v2-assets branch, then rewrites MDX/JSX references to raw\n * GitHub URLs. Repair-lifecycle script: run after audit-media-assets.js\n * flags violations.\n * @pipeline manual\n * @dualmode --dry-run (show what would change) | --write (execute migration)\n * @usage node tools/scripts/remediators/assets/migrate-assets-to-branch.js \\\n * --manifest tasks/reports/media-audit/media-audit-manifest.json \\\n * --target migrate_r2,migrate_cloudinary \\\n * --dry-run\n */\n\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst auditMediaAssets = require('../../audit-media-assets');\n\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_TARGETS = ['migrate_r2', 'migrate_cloudinary'];\nconst DEFAULT_MANIFEST_PATH = auditMediaAssets.DEFAULT_MANIFEST_PATH;\nconst DEFAULT_ASSETS_BRANCH = 'docs-v2-assets';\nconst DEFAULT_ASSETS_BRANCH_REF = `origin/${DEFAULT_ASSETS_BRANCH}`;\nconst RAW_GITHUB_BASE = `https://raw.githubusercontent.com/livepeer/docs/${DEFAULT_ASSETS_BRANCH}`;\nconst LOG_DIR = 'tasks/reports/media-audit';\n\nfunction printHelp() {\n console.log(\n [\n 'Usage:',\n ' node tools/scripts/remediators/assets/migrate-assets-to-branch.js [options]',\n '',\n 'Options:',\n ` --manifest Path to manifest (default: ${DEFAULT_MANIFEST_PATH})`,\n ` --target Comma-separated migration_target values (default: ${DEFAULT_TARGETS.join(',')})`,\n ' --dry-run Show planned changes without executing (default).',\n ' --write Execute copy, ref rewrite, test, and delete phases.',\n ' --skip-copy Skip copying files to docs-v2-assets.',\n ' --skip-refs Skip MDX/JSX reference rewrites.',\n ' --file Restrict processing to a single repo-relative asset path.',\n ' --help Show this help output.',\n '',\n 'Notes:',\n ' - GIF references are rewritten to raw GitHub URLs in-place; they are not transcoded to video.',\n ' - Bare filename-only references are treated as ambiguous and skipped for manual review.'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n manifestPath: DEFAULT_MANIFEST_PATH,\n targets: [...DEFAULT_TARGETS],\n mode: 'dry-run',\n skipCopy: false,\n skipRefs: false,\n file: '',\n help: false\n };\n\n let explicitModeCount = 0;\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n if (token === '--dry-run') {\n args.mode = 'dry-run';\n explicitModeCount += 1;\n continue;\n }\n if (token === '--write') {\n args.mode = 'write';\n explicitModeCount += 1;\n continue;\n }\n if (token === '--skip-copy') {\n args.skipCopy = true;\n continue;\n }\n if (token === '--skip-refs') {\n args.skipRefs = true;\n continue;\n }\n if (token === '--manifest') {\n args.manifestPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--manifest=')) {\n args.manifestPath = token.slice('--manifest='.length).trim();\n continue;\n }\n if (token === '--target') {\n args.targets = parseCsvList(argv[i + 1] || '');\n i += 1;\n continue;\n }\n if (token.startsWith('--target=')) {\n args.targets = parseCsvList(token.slice('--target='.length));\n continue;\n }\n if (token === '--file') {\n args.file = normalizeOptionalRepoPath(argv[i + 1] || '');\n i += 1;\n continue;\n }\n if (token.startsWith('--file=')) {\n args.file = normalizeOptionalRepoPath(token.slice('--file='.length));\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (explicitModeCount > 1) {\n throw new Error('Choose only one mode: --dry-run or --write');\n }\n if (!args.manifestPath) {\n throw new Error('Missing --manifest value');\n }\n if (!Array.isArray(args.targets) || args.targets.length === 0) {\n throw new Error('At least one --target value is required');\n }\n\n args.manifestPath = auditMediaAssets.normalizeRepoPath(args.manifestPath);\n return args;\n}\n\nfunction parseCsvList(raw) {\n return [...new Set(\n String(raw || '')\n .split(',')\n .map((entry) => String(entry || '').trim())\n .filter(Boolean)\n )];\n}\n\nfunction normalizeOptionalRepoPath(value) {\n const trimmed = String(value || '').trim();\n return trimmed ? auditMediaAssets.normalizeRepoPath(trimmed) : '';\n}\n\nfunction absoluteRepoPath(repoPath) {\n return path.join(REPO_ROOT, auditMediaAssets.normalizeRepoPath(repoPath));\n}\n\nfunction ensureDirForFile(repoPath) {\n fs.mkdirSync(path.dirname(absoluteRepoPath(repoPath)), { recursive: true });\n}\n\nfunction readJson(repoPath) {\n return JSON.parse(fs.readFileSync(absoluteRepoPath(repoPath), 'utf8'));\n}\n\nfunction writeJson(repoPath, value) {\n ensureDirForFile(repoPath);\n fs.writeFileSync(absoluteRepoPath(repoPath), `${JSON.stringify(value, null, 2)}\\n`);\n}\n\nfunction writeText(repoPath, value) {\n ensureDirForFile(repoPath);\n fs.writeFileSync(absoluteRepoPath(repoPath), value);\n}\n\nfunction runCommand(command, args, options = {}) {\n const result = spawnSync(command, args, {\n cwd: options.cwd || REPO_ROOT,\n encoding: options.encoding === 'buffer' ? null : 'utf8',\n stdio: options.stdio || ['ignore', 'pipe', 'pipe']\n });\n\n const stdout = options.encoding === 'buffer' ? result.stdout : String(result.stdout || '');\n const stderr = options.encoding === 'buffer' ? result.stderr : String(result.stderr || '');\n\n if (result.status !== 0 && !options.allowFailure) {\n const detail = String(stderr || stdout || `exit ${result.status}`).trim();\n throw new Error(`Command failed: ${command} ${args.join(' ')}\\n${detail}`);\n }\n\n return {\n status: result.status,\n stdout,\n stderr\n };\n}\n\nfunction runGit(args, options = {}) {\n return runCommand('git', args, options);\n}\n\nfunction hasCachedChanges(cwd) {\n const result = spawnSync('git', ['diff', '--cached', '--quiet'], {\n cwd,\n stdio: 'ignore'\n });\n return result.status === 1;\n}\n\nfunction buildCanonicalAssetUrl(assetPath) {\n return `${RAW_GITHUB_BASE}/${encodeURI(auditMediaAssets.normalizeRepoPath(assetPath))}`;\n}\n\nfunction buildRawUrlRegex(assetPath) {\n return auditMediaAssets.buildRawGitHubRegex(assetPath, \"[^/\\\"'\\\\s)]+\");\n}\n\nfunction buildDirectTokens(sourcePath, assetPath) {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/migrate-assets-to-branch.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/migrate-assets-to-branch.test.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tests/integration/mdx-component-runtime-smoke.js",
+ "script": "mdx-component-runtime-smoke",
+ "category": "validator",
+ "purpose": "qa:content-quality",
+ "scope": "tests/integration, .githooks/server-manager.js, tests/run-pr-checks.js",
+ "owner": "docs",
+ "needs": "E-R1, R-R29",
+ "purpose_statement": "Smoke-tests sentinel MDX routes for runtime component failures, focused on page-killing render errors from MDX-imported JSX modules.",
+ "pipeline_declared": "manual",
+ "usage": "node tests/integration/mdx-component-runtime-smoke.js [--routes route[,route...]] [--base-url http://localhost:3000]",
+ "header": "#!/usr/bin/env node\n/**\n * @script mdx-component-runtime-smoke\n * @category validator\n * @purpose qa:content-quality\n * @scope tests/integration, .githooks/server-manager.js, tests/run-pr-checks.js\n * @owner docs\n * @needs E-R1, R-R29\n * @purpose-statement Smoke-tests sentinel MDX routes for runtime component failures, focused on page-killing render errors from MDX-imported JSX modules.\n * @pipeline manual\n * @usage node tests/integration/mdx-component-runtime-smoke.js [--routes route[,route...]] [--base-url http://localhost:3000]\n */\n\nconst path = require('path');\n\nlet puppeteer;\ntry {\n puppeteer = require('puppeteer');\n} catch (_error) {\n puppeteer = require(path.join(process.cwd(), 'tools', 'node_modules', 'puppeteer'));\n}\nconst {\n ensureServerRunning,\n stopServer,\n getServerUrl\n} = require('../../.githooks/server-manager');\n\nconst DEFAULT_TIMEOUT_MS = 30000;\nconst SENTINEL_ROUTES = [\n '/v2/home/mission-control',\n '/v2/about/portal',\n '/v2/developers/portal',\n '/v2/gateways/gateways-portal',\n '/v2/resources/documentation-guide/component-library/primitives'\n];\nconst SENTINEL_ROUTE_FILES = new Set([\n 'v2/home/mission-control.mdx',\n 'v2/about/portal.mdx',\n 'v2/developers/portal.mdx',\n 'v2/gateways/gateways-portal.mdx',\n 'v2/resources/documentation-guide/component-library/primitives.mdx'\n]);\nconst BLOCKING_CONSOLE_PATTERNS = [\n /ReferenceError/i,\n /Cannot access/i,\n /is not defined/i,\n /BlinkingIcon/i,\n /normalizeIconName/i,\n /normalizeIconSize/i\n];\nconst BLOCKING_BODY_PATTERNS = [\n /Failed to render/i,\n /ReferenceError/i,\n /normalizeIconName/i,\n /normalizeIconSize/i\n];\nconst COMPONENT_CHANGE_RE = /^snippets\\/components\\/.+\\.jsx$/;\n\nfunction toPosix(value) {\n return String(value || '').replace(/\\\\/g, '/');\n}\n\nfunction usage() {\n console.log(\n [\n 'Usage: node tests/integration/mdx-component-runtime-smoke.js [options]',\n '',\n 'Options:',\n ` --routes Override sentinel routes (default: ${SENTINEL_ROUTES.join(', ')})`,\n ' --base-url Use an existing Mintlify base URL instead of server-manager discovery',\n ' --help, -h Show this message'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n routes: [],\n baseUrl: String(process.env.MINT_BASE_URL || '').trim(),\n help: false\n };\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n if (token === '--routes') {\n const raw = String(argv[index + 1] || '').trim();\n if (raw) {\n raw\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((route) => args.routes.push(route));\n }\n index += 1;\n continue;\n }\n\n if (token.startsWith('--routes=')) {\n token\n .slice('--routes='.length)\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((route) => args.routes.push(route));\n continue;\n }\n\n if (token === '--base-url') {\n args.baseUrl = String(argv[index + 1] || '').trim();\n index += 1;\n continue;\n }\n\n if (token.startsWith('--base-url=')) {\n args.baseUrl = token.slice('--base-url='.length).trim();\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n args.routes = [...new Set(args.routes)];\n return args;\n}\n\nfunction normalizeRoute(route) {\n const raw = String(route || '').trim();\n if (!raw) return '';\n return raw.startsWith('/') ? raw : `/${raw}`;\n}\n\nfunction getRoutes(args = {}) {\n const routes = Array.isArray(args.routes) && args.routes.length > 0 ? args.routes : SENTINEL_ROUTES;\n return [...new Set(routes.map(normalizeRoute).filter(Boolean))];\n}\n\nfunction isBlockingConsoleMessage(type, text) {\n if (String(type || '').toLowerCase() !== 'error') return false;\n return BLOCKING_CONSOLE_PATTERNS.some((pattern) => pattern.test(String(text || '')));\n}\n\nfunction isBlockingPageError(message) {\n return BLOCKING_CONSOLE_PATTERNS.some((pattern) => pattern.test(String(message || '')));\n}\n\nfunction classifyDomFailure(snapshot) {\n const status = Number(snapshot?.status || 0);\n const bodyText = String(snapshot?.bodyText || '');\n const bodyLength = Number(snapshot?.bodyLength || 0);\n\n if (status === 404) {\n return `Route returned HTTP 404`;\n }\n\n if (snapshot?.is404) {\n return 'Page rendered a 404 state';\n }\n\n if (snapshot?.hasErrorBoundary) {\n return 'Page rendered an error boundary';\n }\n\n if (bodyLength < 500) {\n return `Page appears empty or failed to render (${bodyLength} chars)`;\n }\n\n const blockingBodyPattern = BLOCKING_BODY_PATTERNS.find((pattern) => pattern.test(bodyText));\n if (blockingBodyPattern) {\n return `Page body includes blocking runtime error text (${blockingBodyPattern})`;\n }\n\n return '';\n}\n\nfunction shouldRunForChangedFiles(changedFiles) {\n return changedFiles.some((filePath) => {\n const relPath = toPosix(filePath);\n return (\n COMPONENT_CHANGE_RE.test(relPath) ||\n relPath === 'tools/scripts/validators/components/check-mdx-component-scope.js' ||\n relPath === 'tests/integration/mdx-component-runtime-smoke.js' ||\n SENTINEL_ROUTE_FILES.has(relPath)\n );\n });\n}\n\nasync function testRoute(browser, route, baseUrl) {\n const page = await browser.newPage();\n const consoleErrors = [];\n const pageErrors = [];\n\n await page.setViewport({ width: 1440, height: 900 });\n\n page.on('console', (msg) => {\n const type = msg.type();\n const text = msg.text();\n if (isBlockingConsoleMessage(type, text)) {\n consoleErrors.push(`Console ${type}: ${text}`);\n }\n });\n\n page.on('pageerror', (error) => {\n if (isBlockingPageError(error.message)) {\n pageErrors.push(`Page error: ${error.message}`);\n }\n });\n\n let response;\n try {\n response = await page.goto(`${baseUrl}${route}`, {\n waitUntil: 'networkidle2',\n timeout: DEFAULT_TIMEOUT_MS\n });\n await new Promise((resolve) => setTimeout(resolve, 1500));",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/mdx-component-runtime-smoke.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/mdx-component-runtime-smoke.test.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tests/utils/spell-checker.js",
+ "script": "spell-checker",
+ "category": "validator",
+ "purpose": "qa:content-quality",
+ "scope": "tests",
+ "owner": "docs",
+ "needs": "E-R1, R-R11",
+ "purpose_statement": "Spell checker utility — checks text against custom dictionary with en-GB locale support",
+ "pipeline_declared": "indirect — library module",
+ "usage": "node tests/utils/spell-checker.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script spell-checker\n * @category validator\n * @purpose qa:content-quality\n * @scope tests\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Spell checker utility — checks text against custom dictionary with en-GB locale support\n * @pipeline indirect — library module\n * @dualmode dual-mode (document flags)\n * @usage node tests/utils/spell-checker.js [flags]\n */\n/**\n * Spell checking utilities using cspell\n */\n\nconst { execSync, execFileSync } = require('child_process');\nconst path = require('path');\nconst fs = require('fs');\n\nfunction getRepoRoot() {\n try {\n return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n } catch (_error) {\n return process.cwd();\n }\n}\n\nfunction resolveCspellConfig(configPath = null) {\n if (configPath && fs.existsSync(configPath)) {\n return configPath;\n }\n\n const repoRoot = getRepoRoot();\n const candidates = [\n path.join(process.cwd(), 'cspell.json'),\n path.join(repoRoot, 'cspell.json'),\n path.join(repoRoot, 'tools', 'config', 'cspell.json')\n ];\n\n for (const candidate of candidates) {\n if (fs.existsSync(candidate)) {\n return candidate;\n }\n }\n\n return path.join(repoRoot, 'tools', 'config', 'cspell.json');\n}\n\nfunction resolveCspellBinary() {\n if (process.env.CSPELL_BIN) {\n return { bin: process.env.CSPELL_BIN, viaNpx: false };\n }\n\n const repoRoot = getRepoRoot();\n const candidates = [\n path.join(repoRoot, 'tools', 'node_modules', '.bin', 'cspell'),\n path.join(repoRoot, 'tests', 'node_modules', '.bin', 'cspell')\n ];\n\n for (const candidate of candidates) {\n if (fs.existsSync(candidate)) {\n return { bin: candidate, viaNpx: false };\n }\n }\n\n return { bin: 'npx', viaNpx: true };\n}\n\n/**\n * Check spelling in a file\n */\nfunction checkSpelling(filePath, configPath = null) {\n const cspellConfig = resolveCspellConfig(configPath);\n const cspell = resolveCspellBinary();\n \n try {\n let result;\n if (cspell.viaNpx) {\n result = execSync(\n `npx cspell --no-progress --config \"${cspellConfig}\" \"${filePath}\"`,\n { encoding: 'utf8', stdio: 'pipe' }\n );\n } else {\n result = execFileSync(\n cspell.bin,\n ['--no-progress', '--config', cspellConfig, filePath],\n { encoding: 'utf8', stdio: 'pipe' }\n );\n }\n return { errors: [], output: result };\n } catch (error) {\n // Parse cspell output\n const output = error.stdout || error.stderr || error.message;\n const errors = parseCspellOutput(output, filePath);\n return { errors, output };\n }\n}\n\n/**\n * Parse cspell output to extract errors\n */\nfunction parseCspellOutput(output, filePath) {\n const errors = [];\n const lines = output.split('\\n');\n \n for (const line of lines) {\n // cspell output format: filePath:line:col - Unknown word: \"word\"\n const match = line.match(/:(\\d+):(\\d+)\\s*-\\s*Unknown word:\\s*\"([^\"]+)\"/);\n if (match) {\n errors.push({\n line: parseInt(match[1]),\n column: parseInt(match[2]),\n word: match[3],\n file: filePath\n });\n }\n }\n \n return errors;\n}\n\n/**\n * Check multiple files\n */\nfunction checkMultipleFiles(filePaths, configPath = null) {\n const results = [];\n \n for (const filePath of filePaths) {\n if (fs.existsSync(filePath)) {\n const result = checkSpelling(filePath, configPath);\n results.push({\n file: filePath,\n ...result\n });\n }\n }\n \n return results;\n}\n\nmodule.exports = {\n checkSpelling,\n checkMultipleFiles,\n parseCspellOutput,\n resolveCspellBinary,\n resolveCspellConfig\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/spelling.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/remediators/content/repair-spelling.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/spelling.test.js; indirect via tools/scripts/remediators/content/repair-spelling.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/scoring.js",
+ "script": "scoring",
+ "category": "utility",
+ "purpose": "qa:content-quality",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Aggregates rule scores into a final usefulness score per page.",
+ "pipeline_declared": "indirect — library module",
+ "usage": "const { score } = require('../lib/docs-usefulness/scoring');",
+ "header": "'use strict';\n/**\n * @script scoring\n * @category utility\n * @purpose qa:content-quality\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement Aggregates rule scores into a final usefulness score per page.\n * @pipeline indirect — library module\n * @usage const { score } = require('../lib/docs-usefulness/scoring');\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst {\n extractFrontmatter,\n extractImports,\n validateMdx\n} = require('../../../tests/utils/mdx-parser');\nconst {\n loadRubric,\n getRulesForPage\n} = require('./rubric-loader');\nconst { EVALUATORS } = require('./rule-evaluators');\nconst { runQualityGate } = require('./quality-gate');\n\nfunction toPosix(filePath) {\n return String(filePath || '').split(path.sep).join('/');\n}\n\nfunction firstOf(...values) {\n for (const value of values) {\n if (value !== undefined && value !== null) return value;\n }\n return null;\n}\n\nfunction getFrontmatterValues(page) {\n if (!page) return {};\n if (page.frontmatter && page.frontmatter.data && typeof page.frontmatter.data === 'object') {\n return page.frontmatter.data;\n }\n if (page.frontmatter && typeof page.frontmatter === 'object') {\n return page.frontmatter;\n }\n if (page.frontmatterData && typeof page.frontmatterData === 'object') {\n return page.frontmatterData;\n }\n return {};\n}\n\nfunction stripFrontmatter(content) {\n return String(content || '').replace(/^---\\s*\\n[\\s\\S]*?\\n---\\s*\\n?/, '');\n}\n\nfunction stripMdxToText(content) {\n return String(content || '')\n .replace(/```[\\s\\S]*?```/g, ' ')\n .replace(/`[^`]+`/g, ' ')\n .replace(/^import\\s.+$/gm, ' ')\n .replace(/\\{\\/\\*[\\s\\S]*?\\*\\/\\}/g, ' ')\n .replace(/<[^>]+>/g, ' ')\n .replace(/\\[[^\\]]+\\]\\(([^)]+)\\)/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\nfunction parseHeadings(content) {\n const headings = [];\n String(content || '')\n .split('\\n')\n .forEach((line) => {\n const match = line.match(/^(#{1,6})\\s+(.+)$/);\n if (match) {\n headings.push({ level: match[1].length, text: match[2].trim() });\n }\n });\n return headings;\n}\n\nfunction parseCodeBlocks(content) {\n const blocks = [];\n const regex = /```([A-Za-z0-9_-]+)?\\n([\\s\\S]*?)```/g;\n let match;\n while ((match = regex.exec(String(content || ''))) !== null) {\n blocks.push({\n language: String(match[1] || '').toLowerCase(),\n content: String(match[2] || '')\n });\n }\n return blocks;\n}\n\nfunction parseTables(content) {\n const tables = [];\n const lines = String(content || '').split('\\n');\n for (let i = 0; i < lines.length - 1; i += 1) {\n const line = lines[i].trim();\n const next = lines[i + 1].trim();\n if (!line.includes('|') || !next.includes('|')) continue;\n if (!/^\\|?\\s*:?-{3,}/.test(next)) continue;\n tables.push({\n startLine: i + 1,\n header: line,\n separator: next\n });\n }\n return tables;\n}\n\nfunction parseMarkdownLinks(content) {\n const links = [];\n const regex = /\\[[^\\]]+\\]\\(([^)]+)\\)/g;\n let match;\n while ((match = regex.exec(String(content || ''))) !== null) {\n links.push(match[1].trim());\n }\n return links;\n}\n\nfunction parseHrefLinks(content) {\n const links = [];\n const regex = /\\bhref\\s*=\\s*[\"']([^\"']+)[\"']/gi;\n let match;\n while ((match = regex.exec(String(content || ''))) !== null) {\n links.push(match[1].trim());\n }\n return links;\n}\n\nfunction parseImages(content) {\n const images = [];\n\n const markdown = /!\\[([^\\]]*)\\]\\(([^)]+)\\)/g;\n let match;\n while ((match = markdown.exec(String(content || ''))) !== null) {\n images.push({ alt: String(match[1] || '').trim(), src: String(match[2] || '').trim() });\n }\n\n const jsxImg = /<(?:img|Image)\\b[^>]*>/g;\n while ((match = jsxImg.exec(String(content || ''))) !== null) {\n const tag = match[0];\n const src = (tag.match(/\\bsrc\\s*=\\s*[\"']([^\"']+)[\"']/i) || [])[1] || '';\n const alt = (tag.match(/\\balt\\s*=\\s*[\"']([^\"']+)[\"']/i) || [])[1] || '';\n if (src) {\n images.push({ alt: String(alt || '').trim(), src: String(src || '').trim() });\n }\n }\n\n return images;\n}\n\nfunction parseComponents(content) {\n const components = new Set();\n const regex = /<([A-Z][A-Za-z0-9]*)\\b/g;\n let match;\n while ((match = regex.exec(String(content || ''))) !== null) {\n components.add(match[1]);\n }\n return [...components];\n}\n\nfunction parseSectionFromPath(filePath) {\n const rel = toPosix(filePath).replace(/^\\/+/, '');\n const parts = rel.split('/');\n if (parts[0] === 'v2' && parts[1]) return parts[1];\n return parts[0] || 'unknown';\n}\n\nfunction resolveImportPath(repoRoot, currentFile, importPath) {\n const relImport = String(importPath || '');\n if (!relImport) return null;\n\n const candidates = [];\n if (relImport.startsWith('/')) {\n candidates.push(path.join(repoRoot, relImport));\n } else {\n const dir = path.dirname(path.join(repoRoot, currentFile));\n candidates.push(path.join(dir, relImport));\n }\n\n return candidates.some((candidate) => {\n const withExt = [candidate, `${candidate}.js`, `${candidate}.jsx`, `${candidate}.ts`, `${candidate}.tsx`, `${candidate}.mdx`, `${candidate}.md`, path.join(candidate, 'index.js'), path.join(candidate, 'index.mdx')];\n return withExt.some((target) => fs.existsSync(target));\n });\n}\n\nfunction analyzeMdxPage({ content, filePath, routePath, repoRoot = process.cwd() }) {\n const rawContent = String(content || '');\n const frontmatterMeta = extractFrontmatter(rawContent);\n const frontmatterValues = frontmatterMeta?.data && typeof frontmatterMeta.data === 'object' ? frontmatterMeta.data : {};\n const body = stripFrontmatter(rawContent);\n const textContent = stripMdxToText(body);\n const headings = parseHeadings(body);\n const codeBlocks = parseCodeBlocks(rawContent);\n const tables = parseTables(rawContent);\n const images = parseImages(rawContent);\n const links = [...parseMarkdownLinks(rawContent), ...parseHrefLinks(rawContent)];\n const internalLinks = [...new Set(links.filter((link) => !/^https?:\\/\\//i.test(link) && !/^mailto:/i.test(link)))];\n const externalLinks = [...new Set(links.filter((link) => /^https?:\\/\\//i.test(link)))];\n const components = parseComponents(rawContent);\n const imports = extractImports(rawContent);\n const parseValidation = validateMdx(rawContent, filePath);\n\n const flags = [];\n if (!rawContent.trim()) flags.push('empty');\n if (!frontmatterMeta.exists) flags.push('missing_frontmatter');\n if (frontmatterMeta.exists && frontmatterMeta.data === null) flags.push('invalid_frontmatter');\n if (frontmatterMeta.exists && frontmatterValues && !frontmatterValues.title) flags.push('missing_title');\n if (frontmatterMeta.exists && frontmatterValues && !frontmatterValues.description) flags.push('missing_description');\n if (/\\bTODO\\b|\\bTBD\\b/i.test(rawContent)) flags.push('todo_marker');\n if (/Coming Soon/i.test(rawContent)) flags.push('coming_soon');\n if (/\\/v2\\/pages\\//i.test(rawContent)) flags.push('legacy_v2_pages_link');\n\n const unresolvedImports = imports.filter((imp) => {\n const impPath = String(imp.path || '');\n if (impPath.startsWith('http')) return false;\n if (/^(react|next|fs|path|os|crypto|assert|child_process|node:)/.test(impPath)) return false;\n return !resolveImportPath(repoRoot, filePath, impPath);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-rubric.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/notion/sync-v2-en-canonical.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/assign-purpose-metadata.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/audit-v2-usefulness.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-rubric.test.js; indirect via tools/notion/sync-v2-en-canonical.js; indirect via tools/scripts/assign-purpose-metadata.js; indirect via tools/scripts/audit-v2-usefulness.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/mdx-safe-markdown.js",
+ "script": "mdx-safe-markdown",
+ "category": "utility",
+ "purpose": "qa:content-quality",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "E-R1, R-R11",
+ "purpose_statement": "Shared MDX-safe markdown helpers that collect first-party markdown files, detect unsafe patterns, and apply deterministic repairs.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "node tools/lib/mdx-safe-markdown.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script mdx-safe-markdown\n * @category utility\n * @purpose qa:content-quality\n * @scope full-repo\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Shared MDX-safe markdown helpers that collect first-party markdown files, detect unsafe patterns, and apply deterministic repairs.\n * @pipeline indirect -- library module\n * @usage node tools/lib/mdx-safe-markdown.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst { unified } = require('unified');\n\nfunction loadPlugin(name) {\n const plugin = require(name);\n return plugin.default || plugin;\n}\n\nconst remarkParse = loadPlugin('remark-parse');\nconst remarkGfm = loadPlugin('remark-gfm');\nconst remarkMath = loadPlugin('remark-math');\nconst remarkMdx = loadPlugin('remark-mdx');\n\nconst REPO_ROOT = path.resolve(__dirname, '..', '..');\nconst STAGED_SNAPSHOT_ENV = 'LPD_STAGED_FILES_SNAPSHOT';\nconst MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);\nconst PLACEHOLDER_TAG_RE = /<([a-z][a-z0-9-]{1,})>/g;\nconst RAW_BR_RE = /
(?!\\s*\\/>)/g;\nconst COMPARISON_RE = /(^|[\\s([{])(<={0,1}|>={0,1})(?=\\s*\\d)/g;\nconst HTML_TAG_ALLOWLIST = new Set([\n 'a',\n 'abbr',\n 'b',\n 'blockquote',\n 'body',\n 'br',\n 'caption',\n 'code',\n 'dd',\n 'del',\n 'details',\n 'div',\n 'dl',\n 'dt',\n 'em',\n 'figcaption',\n 'figure',\n 'h1',\n 'h2',\n 'h3',\n 'h4',\n 'h5',\n 'h6',\n 'head',\n 'hr',\n 'html',\n 'i',\n 'img',\n 'kbd',\n 'li',\n 'main',\n 'mark',\n 'ol',\n 'p',\n 'picture',\n 'pre',\n 'q',\n 's',\n 'section',\n 'select',\n 'small',\n 'source',\n 'span',\n 'strong',\n 'style',\n 'sub',\n 'summary',\n 'sup',\n 'table',\n 'tbody',\n 'td',\n 'tfoot',\n 'th',\n 'thead',\n 'time',\n 'tr',\n 'u',\n 'ul',\n 'option'\n]);\nconst PLACEHOLDER_ALIASES = {\n issue: 'ISSUE_ID',\n 'issue-id': 'ISSUE_ID',\n slug: 'TASK_SLUG',\n task: 'TASK_ID',\n 'task-id': 'TASK_ID',\n id: 'ID',\n path: 'TARGET_PATH',\n 'file-path': 'FILE_PATH',\n file: 'FILE_PATH',\n branch: 'BRANCH_NAME',\n scope: 'PATH_SCOPE'\n};\nconst MDX_PROCESSOR = unified()\n .use(remarkParse)\n .use(remarkGfm)\n .use(remarkMath)\n .use(remarkMdx);\n\nfunction normalizeRepoPath(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction normalizeInline(value) {\n return String(value || '')\n .replace(/\\r?\\n/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\nfunction escapeRegExp(value) {\n return String(value || '').replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\nfunction isMarkdownFile(repoPath) {\n return MARKDOWN_EXTENSIONS.has(path.extname(String(repoPath || '')).toLowerCase());\n}\n\nfunction shouldExcludeMarkdownPath(repoPath) {\n const relPath = normalizeRepoPath(repoPath).replace(/^\\/+/, '');\n if (!relPath) return true;\n if (!isMarkdownFile(relPath)) return true;\n\n return (\n relPath.startsWith('.git/') ||\n relPath.startsWith('node_modules/') ||\n relPath.includes('/.git/') ||\n relPath.includes('/node_modules/') ||\n relPath.startsWith('.venv/') ||\n relPath.includes('/.venv/') ||\n relPath.startsWith('tmp/') ||\n relPath.includes('/tmp/') ||\n relPath.includes('/__pycache__/') ||\n relPath.includes('/.next/') ||\n relPath.endsWith('.bak') ||\n relPath.endsWith('.disabled')\n );\n}\n\nfunction isEligibleRepoMarkdownPath(repoPath) {\n return !shouldExcludeMarkdownPath(repoPath);\n}\n\nfunction getRepoRoot(rootDir = REPO_ROOT) {\n try {\n return execSync('git rev-parse --show-toplevel', {\n cwd: rootDir,\n encoding: 'utf8'\n }).trim();\n } catch (_error) {\n return rootDir;\n }\n}\n\nfunction readFileSafe(filePath) {\n try {\n return fs.readFileSync(filePath, 'utf8');\n } catch (_error) {\n return '';\n }\n}\n\nfunction walkMarkdownFiles(dirPath, repoRoot, out = []) {\n if (!fs.existsSync(dirPath)) return out;\n const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n\n for (const entry of entries) {\n if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.venv' || entry.name === '__pycache__' || entry.name === '.next') {\n continue;\n }\n\n const absPath = path.join(dirPath, entry.name);\n if (entry.isDirectory()) {\n walkMarkdownFiles(absPath, repoRoot, out);\n continue;\n }\n\n const relPath = normalizeRepoPath(path.relative(repoRoot, absPath));\n if (isEligibleRepoMarkdownPath(relPath)) {\n out.push(absPath);\n }\n }\n\n return out;\n}\n\nfunction getAllRepoMarkdownFiles(rootDir = REPO_ROOT) {\n const repoRoot = getRepoRoot(rootDir);\n return walkMarkdownFiles(repoRoot, repoRoot).sort((left, right) =>\n normalizeRepoPath(path.relative(repoRoot, left)).localeCompare(normalizeRepoPath(path.relative(repoRoot, right)))\n );\n}\n\nfunction getStagedRepoMarkdownFiles(rootDir = REPO_ROOT) {\n const repoRoot = getRepoRoot(rootDir);\n const snapshot = String(process.env[STAGED_SNAPSHOT_ENV] || '')\n .split(/\\r?\\n/)\n .map((entry) => entry.trim())\n .filter(Boolean);\n\n const relFiles = snapshot.length > 0\n ? snapshot\n : String(\n execSync('git diff --cached --name-only --diff-filter=ACMR', {\n cwd: repoRoot,",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/mdx-safe-markdown.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-component-governance-remediation-reports.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/remediators/content/repair-mdx-safe-markdown.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/content/check-mdx-safe-markdown.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/run-pr-checks.js; indirect via tests/unit/mdx-safe-markdown.test.js; indirect via tools/scripts/generate-component-governance-remediation-reports.js; indirect via tools/scripts/remediators/content/repair-mdx-safe-markdown.js; indirect via tools/scripts/validators/content/check-mdx-safe-markdown.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/audit-v2-usefulness.js",
+ "script": "audit-v2-usefulness",
+ "category": "validator",
+ "purpose": "qa:content-quality",
+ "scope": "tools/scripts, v2, tasks/reports, tools/config",
+ "owner": "docs",
+ "needs": "E-R1, R-R11",
+ "purpose_statement": "Usefulness auditor — scores v2 MDX pages on human and agent usefulness with source-weighted 2026 accuracy verification",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/audit-v2-usefulness.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script audit-v2-usefulness\n * @category validator\n * @purpose qa:content-quality\n * @scope tools/scripts, v2, tasks/reports, tools/config\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Usefulness auditor — scores v2 MDX pages on human and agent usefulness with source-weighted 2026 accuracy verification\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/audit-v2-usefulness.js [flags]\n */\n\n'use strict';\n\nconst fs = require('fs');\nconst path = require('path');\nconst crypto = require('crypto');\nconst { execSync } = require('child_process');\nconst {\n getDocsJsonRouteKeys,\n toDocsRouteKeyFromFileV2Aware\n} = require('../../tests/utils/file-walker');\nconst { analyzeMdxPage, scorePage, computeBand } = require('../lib/docs-usefulness/scoring');\nconst { getRulesForPage } = require('../lib/docs-usefulness/rubric-loader');\nconst { checkJourneys } = require('../lib/docs-usefulness/journey-check');\nconst { LlmEvaluator } = require('../lib/docs-usefulness/llm-evaluator');\nconst prompts = require('../lib/docs-usefulness/prompts');\nconst { loadAndValidateUsefulnessConfig } = require('../lib/docs-usefulness/config-validator');\n\nconst REMOVED_FLAGS = new Set([\n '--accuracy-mode',\n '--as-of',\n '--verify-sources',\n '--github-repos',\n '--deepwiki-enabled',\n '--deepwiki-base-url',\n '--official-docs-base-url',\n '--github-results-per-repo',\n '--verification-cache-dir',\n '--verification-max-requests',\n '--verification-timeout-ms',\n '--verification-fixture',\n '--scoring-engine'\n]);\n\nconst BASELINE_DEFAULT_REL = path.join(\n 'tools',\n 'config',\n 'usefulness-baselines',\n 'full-run-2026-02-23-page-matrix.csv'\n);\n\nfunction getRepoRoot() {\n try {\n return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n } catch (_error) {\n return process.cwd();\n }\n}\n\nfunction toPosix(filePath) {\n return String(filePath || '').split(path.sep).join('/');\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction parseCsv(raw, fallback = []) {\n if (!raw) return [...fallback];\n return String(raw)\n .split(',')\n .map((value) => value.trim())\n .filter(Boolean);\n}\n\nfunction parseBoolean(raw, fallback) {\n if (raw === undefined || raw === null) return fallback;\n const value = String(raw).trim().toLowerCase();\n if (['1', 'true', 'yes', 'on'].includes(value)) return true;\n if (['0', 'false', 'no', 'off'].includes(value)) return false;\n return fallback;\n}\n\nfunction parseArgs(argv, repoRoot) {\n for (const token of argv) {\n if (REMOVED_FLAGS.has(token)) {\n throw new Error(`Deprecated flag ${token} is removed. Run without accuracy-verification options; usefulness audit is now purpose-aware by default.`);\n }\n }\n\n const args = {\n mode: 'full',\n files: [],\n outDir: path.join(repoRoot, 'tasks', 'reports', 'quality-accessibility', 'docs-usefulness', 'latest'),\n format: ['jsonl', 'csv', 'json', 'md'],\n maxPages: null,\n llm: false,\n llmTier: 'free',\n llmBudget: null,\n llmSample: 100,\n llmResume: true,\n journey: true,\n purposeAware: true,\n legacyRubric: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--mode') {\n args.mode = String(argv[i + 1] || args.mode).trim();\n i += 1;\n continue;\n }\n if (token === '--files' || token === '--file') {\n args.files.push(...parseCsv(argv[i + 1], []));\n i += 1;\n continue;\n }\n if (token === '--out-dir') {\n const raw = String(argv[i + 1] || '').trim();\n if (raw) args.outDir = path.resolve(repoRoot, raw);\n i += 1;\n continue;\n }\n if (token === '--format') {\n args.format = parseCsv(argv[i + 1], args.format);\n i += 1;\n continue;\n }\n if (token === '--max-pages') {\n const parsed = Number(argv[i + 1]);\n if (Number.isFinite(parsed) && parsed > 0) {\n args.maxPages = parsed;\n }\n i += 1;\n continue;\n }\n if (token === '--llm') {\n args.llm = true;\n continue;\n }\n if (token === '--llm-tier') {\n args.llmTier = String(argv[i + 1] || args.llmTier).trim();\n i += 1;\n continue;\n }\n if (token === '--llm-budget') {\n const parsed = Number(argv[i + 1]);\n if (Number.isFinite(parsed) && parsed >= 0) args.llmBudget = parsed;\n i += 1;\n continue;\n }\n if (token === '--llm-sample') {\n const parsed = Number(argv[i + 1]);\n if (Number.isFinite(parsed) && parsed >= 1 && parsed <= 100) args.llmSample = parsed;\n i += 1;\n continue;\n }\n if (token === '--llm-resume') {\n const next = argv[i + 1];\n if (next && !next.startsWith('--')) {\n args.llmResume = parseBoolean(next, true);\n i += 1;\n } else {\n args.llmResume = true;\n }\n continue;\n }\n if (token === '--journey') {\n args.journey = true;\n continue;\n }\n if (token === '--no-journey') {\n args.journey = false;\n continue;\n }\n if (token === '--purpose-aware') {\n args.purposeAware = true;\n continue;\n }\n if (token === '--legacy-rubric') {\n args.legacyRubric = true;\n continue;\n }\n }\n\n args.files = [...new Set(args.files)];\n if (args.files.length > 0) {\n args.mode = 'files';\n }\n if (args.mode === 'files') {\n args.journey = false;\n }\n if (args.legacyRubric) {\n args.purposeAware = false;\n }\n\n return args;\n}\n\nfunction normalizeRouteKey(value) {\n let route = toPosix(value || '').trim();\n route = route.replace(/^\\/+/, '');\n route = route.replace(/\\.(md|mdx)$/i, '');\n route = route.replace(/\\/index$/i, '');\n route = route.replace(/\\/+/g, '/');\n route = route.replace(/\\s+$/g, '');\n return route;\n}\n\nfunction collectPagesFromNode(node, out = []) {\n if (typeof node === 'string') {\n const value = normalizeRouteKey(node);\n if (value.startsWith('v2/')) out.push(value);\n return out;\n }\n\n if (Array.isArray(node)) {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-rubric.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/docs-quality-and-freshness-audit.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-rubric.test.js; indirect via tools/scripts/docs-quality-and-freshness-audit.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/dev/add-callouts.js",
+ "script": "add-callouts",
+ "category": "remediator",
+ "purpose": "qa:content-quality",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R1, R-R11",
+ "purpose_statement": "Callout inserter — adds Note/Tip/Warning callout components to MDX files based on content patterns",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/dev/add-callouts.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script add-callouts\n * @category remediator\n * @purpose qa:content-quality\n * @scope tools/scripts\n * @owner docs\n * @needs E-R1, R-R11\n * @purpose-statement Callout inserter — adds Note/Tip/Warning callout components to MDX files based on content patterns\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/dev/add-callouts.js [flags]\n */\n\n/**\n * Script to add callouts to MDX pages\n * \n * This script processes all MDX files in v2 docs folders and adds appropriate callouts:\n * - ComingSoonCallout for pages with no content (only metadata/title)\n * - PreviewCallout for pages with content\n * \n * Usage: node add-callouts.js [--dry-run] [--remove]\n */\n\nconst fs = require('fs');\nconst path = require('path');\n\nconst REPO_ROOT = path.join(__dirname, '../../../');\nconst DOCS_JSON_PATH = path.join(REPO_ROOT, 'docs.json');\n\nconst COMING_SOON_IMPORT = \"import {ComingSoonCallout} from '/snippets/components/primitives/previewCallouts.jsx'\";\nconst COMING_SOON_COMPONENT = ']*\\/>/g, '')\n .replace(/]*\\/>/g, '')\n .trim();\n \n // Check if there's meaningful content (more than just whitespace or a single heading)\n const lines = withoutCallouts.split('\\n').filter(line => line.trim().length > 0);\n \n // If only one line and it's a heading, consider it as no content\n if (lines.length === 0 || (lines.length === 1 && lines[0].trim().startsWith('#'))) {\n return false;\n }\n \n return true;\n}\n\n/**\n * Collect v2 English nav page paths from docs.json.\n * @returns {string[]} - Array of page paths like \"v2/...\"\n */\nfunction getV2EnglishNavPages() {\n if (!fs.existsSync(DOCS_JSON_PATH)) {\n throw new Error(`docs.json not found at ${DOCS_JSON_PATH}`);\n }\n\n const docsJson = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, 'utf8'));\n const versions = (docsJson.navigation && docsJson.navigation.versions) || [];\n const v2 = versions.find((version) => version.version === 'v2');\n if (!v2) return [];\n\n const languages = v2.languages || [];\n const en = languages.find((lang) => lang.language === 'en');\n if (!en) return [];\n\n const pages = new Set();\n\n function collect(node) {\n if (!node) return;\n if (Array.isArray(node)) {\n node.forEach(collect);\n return;\n }\n if (typeof node === 'string') {\n const value = node.trim();\n if (value && value.startsWith('v2/')) {\n pages.add(value);\n }\n return;\n }\n if (typeof node === 'object') {\n collect(node.pages);\n collect(node.groups);\n collect(node.anchors);\n collect(node.tabs);\n }\n }\n\n collect(en.tabs);\n\n return Array.from(pages);\n}\n\n/**\n * Check if file already has a callout\n * @param {string} content - The file content\n * @returns {boolean} - True if callout exists\n */\nfunction hasCallout(content) {\n return content.includes(' {\n const match = line.match(importRegex);\n if (!match) return line;\n\n const quote = match[2];\n const hasSemicolon = line.trim().endsWith(';');\n const items = match[1]\n .split(',')\n .map((item) => item.trim())\n .filter(Boolean);\n\n const filtered = items.filter((item) => {\n if (item === 'PreviewCallout') return usage.keepPreview;\n if (item === 'ComingSoonCallout') return usage.keepComing;\n return true;\n });\n\n if (filtered.length === 0) return null;\n\n return `import { ${filtered.join(', ')} } from ${quote}/snippets/components/primitives/previewCallouts.jsx${quote}${hasSemicolon ? ';' : ''}`;\n })\n .filter((line) => line !== null)\n .join('\\n');\n}\n\n/**\n * Remove top-level Preview/ComingSoon callout block (import + first callout tag).\n * @param {string} content - The file content\n * @returns {{ content: string, removed: boolean }}\n */\nfunction removeTopLevelCallout(content) {\n const parts = content.split('---');\n if (parts.length < 3) return { content, removed: false };\n\n const beforeMetadata = parts[0];\n const metadata = parts[1];\n const afterMetadata = parts.slice(2).join('---');\n\n const lines = afterMetadata.split('\\n');\n const importRegex = /^\\s*import\\s+\\{[^}]*\\}\\s+from\\s+['\"]\\/snippets\\/components\\/primitives\\/previewCallouts\\.jsx['\"];?\\s*$/;\n const calloutRegex = /^\\s*<\\s*(PreviewCallout|ComingSoonCallout)\\b[^>]*\\/>\\s*$/;\n\n let firstNonImportIndex = -1;\n for (let i = 0; i < lines.length; i++) {\n const trimmed = lines[i].trim();\n if (!trimmed) continue;\n if (/^\\s*import\\s+/.test(lines[i])) continue;\n firstNonImportIndex = i;\n break;\n }\n\n let calloutIndex = -1;\n if (firstNonImportIndex !== -1 && calloutRegex.test(lines[firstNonImportIndex])) {\n calloutIndex = firstNonImportIndex;\n }\n\n let importIndex = -1;\n if (calloutIndex !== -1) {\n for (let i = 0; i < calloutIndex; i++) {\n if (importRegex.test(lines[i]) && /(PreviewCallout|ComingSoonCallout)/.test(lines[i])) {\n importIndex = i;\n break;\n }\n }\n }\n\n if (calloutIndex === -1 && importIndex === -1) {\n return { content, removed: false };\n }\n\n const filteredLines = lines.filter((_, index) => index !== calloutIndex && index !== importIndex);\n let newAfter = filteredLines.join('\\n');\n\n const usage = {\n keepPreview: /]',\n '',\n 'Modes:',\n ' --dry-run Show deterministic spelling repairs without modifying files (default).',\n ' --write Apply deterministic spelling repairs and print per-file diffs.',\n '',\n 'Scope:',\n ' --staged Limit to staged routable v2 MDX files.',\n ' --files Limit to explicit MDX files (comma-separated, repeatable).',\n '',\n 'Safety:',\n ' - Repairs only prose ranges parsed from MDX text nodes.',\n ' - Never edits frontmatter, inline code, fenced code, or URL substrings.',\n ' - Applies a correction only when cspell gives a deterministic, dictionary-backed choice.'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n mode: 'dry-run',\n stagedOnly: false,\n files: [],\n help: false\n };\n\n let explicitModeCount = 0;\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n if (token === '--dry-run') {\n args.mode = 'dry-run';\n explicitModeCount += 1;\n continue;\n }\n if (token === '--write') {\n args.mode = 'write';\n explicitModeCount += 1;\n continue;\n }\n if (token === '--staged') {\n args.stagedOnly = true;\n continue;\n }\n if (token === '--files') {\n const raw = String(argv[i + 1] || '').trim();\n if (!raw) throw new Error('Missing value for --files');\n raw\n .split(',')\n .map((item) => item.trim())\n .filter(Boolean)\n .forEach((item) => args.files.push(item));\n i += 1;\n continue;\n }\n if (token.startsWith('--files=')) {\n token\n .slice('--files='.length)\n .split(',')\n .map((item) => item.trim())\n .filter(Boolean)\n .forEach((item) => args.files.push(item));\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (explicitModeCount > 1) {\n throw new Error('Choose only one mode: --dry-run or --write');\n }\n\n if (args.stagedOnly && args.files.length > 0) {\n throw new Error('Use either --staged or --files, not both');\n }\n\n args.files = [...new Set(args.files)];\n return args;\n}\n\nfunction splitLeadingFrontmatter(content) {\n const text = String(content || '');\n const match = text.match(/^---\\r?\\n[\\s\\S]*?\\r?\\n---(?:\\r?\\n|$)/);\n if (!match) {\n return {\n frontmatter: '',\n body: text,\n bodyOffset: 0\n };\n }\n\n return {\n frontmatter: match[0],\n body: text.slice(match[0].length),\n bodyOffset: match[0].length\n };\n}\n\nfunction mergeRanges(ranges) {\n if (!Array.isArray(ranges) || ranges.length === 0) return [];\n const ordered = ranges\n .filter((range) => Number.isFinite(range.start) && Number.isFinite(range.end) && range.end > range.start)\n .sort((a, b) => a.start - b.start || a.end - b.end);\n\n const out = [ordered[0]];\n for (let i = 1; i < ordered.length; i += 1) {\n const current = ordered[i];\n const previous = out[out.length - 1];\n if (current.start <= previous.end) {\n previous.end = Math.max(previous.end, current.end);\n continue;\n }\n out.push({ start: current.start, end: current.end });\n }\n return out;\n}\n\nfunction splitTextRangeByUrls(baseStart, value) {\n const text = String(value || '');\n const ranges = [];\n let cursor = 0;\n let match;\n let foundUrl = false;\n\n URL_REGEX.lastIndex = 0;\n while ((match = URL_REGEX.exec(text)) !== null) {\n foundUrl = true;\n if (match.index > cursor) {\n ranges.push({\n start: baseStart + cursor,\n end: baseStart + match.index\n });\n }\n cursor = match.index + match[0].length;\n }\n\n if (cursor < text.length) {\n ranges.push({\n start: baseStart + cursor,\n end: baseStart + text.length\n });\n }\n\n if (!foundUrl && ranges.length === 0 && text.length > 0) {\n ranges.push({\n start: baseStart,\n end: baseStart + text.length\n });\n }\n\n return ranges;\n}\n\nfunction walkTextNodes(node, visitor) {\n if (!node || typeof node !== 'object') return;\n\n if (node.type === 'text') {\n visitor(node);\n }\n\n if (Array.isArray(node.children)) {\n node.children.forEach((child) => walkTextNodes(child, visitor));\n }\n}\n\nasync function collectEligibleRanges(content) {\n const { body, bodyOffset } = splitLeadingFrontmatter(content);\n if (!body.trim()) return [];\n\n const tree = await parseMdx(body);\n const ranges = [];\n\n walkTextNodes(tree, (node) => {\n const startOffset = node?.position?.start?.offset;\n const endOffset = node?.position?.end?.offset;\n if (!Number.isFinite(startOffset) || !Number.isFinite(endOffset) || endOffset <= startOffset) {\n return;\n }\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/repair-spelling.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/remediators/content/before.mdx",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/remediators/content/after.mdx",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/remediators/content/before.mdx, tools/scripts/remediators/content/after.mdx",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/repair-spelling.test.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/config-validator.js",
+ "script": "config-validator",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14, R-C6",
+ "purpose_statement": "Validates docs-usefulness config structure and field completeness.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { validateConfig } = require('../lib/docs-usefulness/config-validator');",
+ "header": "'use strict';\n/**\n * @script config-validator\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14, R-C6\n * @purpose-statement Validates docs-usefulness config structure and field completeness.\n * @pipeline indirect -- library module\n * @usage const { validateConfig } = require('../lib/docs-usefulness/config-validator');\n */\n\nconst {\n PURPOSE_ENUM,\n AUDIENCE_ENUM,\n loadRubric,\n loadJourneys,\n loadAudienceNormalization,\n loadLlmTiers\n} = require('./rubric-loader');\n\nfunction validateRubricPromptKeys(rubric, prompts) {\n const referenced = new Set();\n Object.entries(rubric).forEach(([purpose, rules]) => {\n if (!PURPOSE_ENUM.includes(purpose)) {\n throw new Error(`Invalid rubric purpose key: ${purpose}`);\n }\n\n const tier1 = rules?.tier1_rules || {};\n Object.entries(tier1).forEach(([ruleName, rule]) => {\n if (typeof rule.weight !== 'number') {\n throw new Error(`Rubric rule missing numeric weight: ${purpose}.${ruleName}`);\n }\n if (!rule.type) {\n throw new Error(`Rubric rule missing type: ${purpose}.${ruleName}`);\n }\n });\n\n const tier2 = rules?.tier2_llm || {};\n Object.entries(tier2).forEach(([criterion, config]) => {\n if (typeof config.weight !== 'number') {\n throw new Error(`Tier2 criterion missing numeric weight: ${purpose}.${criterion}`);\n }\n if (!config.prompt_key) {\n throw new Error(`Tier2 criterion missing prompt_key: ${purpose}.${criterion}`);\n }\n referenced.add(config.prompt_key);\n });\n });\n\n referenced.forEach((promptKey) => {\n if (!prompts[promptKey]) {\n throw new Error(`Rubric references unknown prompt key: ${promptKey}`);\n }\n });\n}\n\nfunction validateJourneyConfig(journeys) {\n Object.entries(journeys).forEach(([personaKey, journey]) => {\n if (!Array.isArray(journey.steps) || journey.steps.length === 0) {\n throw new Error(`Journey ${personaKey} has no steps`);\n }\n\n journey.steps.forEach((step) => {\n if (!Array.isArray(step.path_patterns) || step.path_patterns.length === 0) {\n throw new Error(`Journey ${personaKey} step ${step.position} missing path_patterns`);\n }\n step.path_patterns.forEach((pattern) => {\n if (String(pattern).includes('v2/platforms/')) {\n throw new Error(`Journey ${personaKey} step ${step.position} uses forbidden pattern: ${pattern}`);\n }\n });\n });\n });\n}\n\nfunction validateAudienceConfig(config) {\n const canonical = config.canonical_audiences || [];\n AUDIENCE_ENUM.forEach((audience) => {\n if (!canonical.includes(audience)) {\n throw new Error(`Audience normalization missing canonical value: ${audience}`);\n }\n });\n\n if (!config.section_defaults || !config.section_defaults.solutions) {\n throw new Error('Audience normalization missing section default for solutions');\n }\n\n if (config.section_defaults.platforms) {\n throw new Error('Audience normalization must not define deprecated platforms section');\n }\n}\n\nfunction validateLlmTiers(config) {\n if (!config.default_tier) {\n throw new Error('LLM tiers config missing default_tier');\n }\n if (!config.tiers || !config.tiers[config.default_tier]) {\n throw new Error(`LLM tiers missing default tier definition: ${config.default_tier}`);\n }\n\n ['free', 'good', 'optimal'].forEach((tier) => {\n if (!config.tiers[tier]) {\n throw new Error(`LLM tiers missing required tier: ${tier}`);\n }\n if (!Array.isArray(config.tiers[tier].models) || config.tiers[tier].models.length === 0) {\n throw new Error(`LLM tier has no models: ${tier}`);\n }\n });\n}\n\nfunction validateUsefulnessConfig({ rubric, journeys, audience, llmTiers, prompts }) {\n validateRubricPromptKeys(rubric, prompts);\n validateJourneyConfig(journeys);\n validateAudienceConfig(audience);\n validateLlmTiers(llmTiers);\n}\n\nfunction loadAndValidateUsefulnessConfig(prompts) {\n const rubric = loadRubric();\n const journeys = loadJourneys();\n const audience = loadAudienceNormalization();\n const llmTiers = loadLlmTiers();\n validateUsefulnessConfig({ rubric, journeys, audience, llmTiers, prompts });\n return { rubric, journeys, audience, llmTiers };\n}\n\nmodule.exports = {\n validateUsefulnessConfig,\n loadAndValidateUsefulnessConfig\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-journey.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-rubric.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/assign-purpose-metadata.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/audit-v2-usefulness.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-journey.test.js; indirect via tests/unit/usefulness-rubric.test.js; indirect via tools/scripts/assign-purpose-metadata.js; indirect via tools/scripts/audit-v2-usefulness.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/journey-check.js",
+ "script": "journey-check",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14, R-C6",
+ "purpose_statement": "Evaluates docs pages against user journey completeness criteria.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { checkJourney } = require('../lib/docs-usefulness/journey-check');",
+ "header": "'use strict';\n/**\n * @script journey-check\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14, R-C6\n * @purpose-statement Evaluates docs pages against user journey completeness criteria.\n * @pipeline indirect -- library module\n * @usage const { checkJourney } = require('../lib/docs-usefulness/journey-check');\n */\n\nconst { minimatch } = require('minimatch');\nconst { loadJourneys } = require('./rubric-loader');\n\nfunction chooseBestPage(pages) {\n if (!Array.isArray(pages) || pages.length === 0) return null;\n return [...pages].sort((a, b) => {\n const scoreA = Number(a.combined_score || 0);\n const scoreB = Number(b.combined_score || 0);\n if (scoreA !== scoreB) return scoreB - scoreA;\n return String(a.path || '').localeCompare(String(b.path || ''));\n })[0];\n}\n\nfunction hasNavLinkToNext(currentPage, nextPagePath) {\n if (!currentPage || !Array.isArray(currentPage.internalLinks) || !nextPagePath) return false;\n const normalizedNext = String(nextPagePath).replace(/\\.mdx$/i, '').replace(/\\/index$/i, '');\n return currentPage.internalLinks.some((link) => {\n const normalizedLink = String(link || '').replace(/^\\/+/, '').replace(/\\.mdx$/i, '').replace(/\\/index$/i, '');\n return normalizedNext.includes(normalizedLink) || normalizedLink.includes(normalizedNext);\n });\n}\n\nfunction checkJourneys(pageScores, journeysConfig = loadJourneys()) {\n const reports = [];\n\n Object.entries(journeysConfig).forEach(([persona, journey]) => {\n const stepResults = (journey.steps || []).map((step) => {\n const patterns = Array.isArray(step.path_patterns) ? step.path_patterns : [];\n const matching = pageScores.filter((page) =>\n patterns.some((pattern) => minimatch(String(page.path || ''), pattern, { nocase: true }))\n );\n\n if (matching.length === 0) {\n return {\n ...step,\n status: 'missing',\n reason: 'no_page',\n page: null,\n score: null,\n has_link_to_next: false\n };\n }\n\n const allowedPurposes = Array.isArray(step.purpose) ? step.purpose : [step.purpose];\n const purposeMatched = matching.filter((page) => allowedPurposes.includes(page.purpose));\n\n if (purposeMatched.length === 0) {\n const best = chooseBestPage(matching);\n return {\n ...step,\n status: 'weak',\n reason: 'wrong_purpose',\n page: best?.path || null,\n score: best?.combined_score || 0,\n has_link_to_next: false\n };\n }\n\n const best = chooseBestPage(purposeMatched);\n const score = Number(best?.combined_score || 0);\n return {\n ...step,\n status: score >= 50 ? 'complete' : 'weak',\n reason: score >= 50 ? null : 'low_score',\n page: best?.path || null,\n score,\n has_link_to_next: false\n };\n });\n\n for (let i = 0; i < stepResults.length - 1; i += 1) {\n const current = stepResults[i];\n const next = stepResults[i + 1];\n if (!current.page || !next.page) continue;\n const currentPage = pageScores.find((page) => page.path === current.page);\n current.has_link_to_next = hasNavLinkToNext(currentPage, next.page);\n }\n\n const complete = stepResults.filter((step) => step.status === 'complete').length;\n const weak = stepResults.filter((step) => step.status === 'weak').length;\n const missing = stepResults.filter((step) => step.status === 'missing').length;\n\n const blockers = stepResults\n .filter((step) => step.status === 'missing')\n .map((step) => {\n const purpose = Array.isArray(step.purpose) ? step.purpose.join('/') : step.purpose;\n return `Step ${step.position} (${purpose}): NO PAGE FOUND`;\n });\n\n const verdict = missing === 0 && weak === 0 ? 'COMPLETE' : missing === 0 ? 'MOSTLY_COMPLETE' : 'BLOCKED';\n\n reports.push({\n persona,\n label: journey.label,\n maps_to: journey.maps_to || null,\n success_criteria: journey.success_criteria,\n priority: Number(journey.priority || 999),\n steps_total: stepResults.length,\n steps_complete: complete,\n steps_weak: weak,\n steps_missing: missing,\n verdict,\n blockers,\n steps: stepResults\n });\n });\n\n return reports.sort((a, b) => a.priority - b.priority || String(a.persona).localeCompare(String(b.persona)));\n}\n\nmodule.exports = {\n checkJourneys\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-journey.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/audit-v2-usefulness.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-journey.test.js; indirect via tools/scripts/audit-v2-usefulness.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/llm-evaluator.js",
+ "script": "llm-evaluator",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Wraps LLM API calls for rubric-based page quality evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { evaluate } = require('../lib/docs-usefulness/llm-evaluator');",
+ "header": "'use strict';\n/**\n * @script llm-evaluator\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement Wraps LLM API calls for rubric-based page quality evaluation.\n * @pipeline indirect -- library module\n * @usage const { evaluate } = require('../lib/docs-usefulness/llm-evaluator');\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst crypto = require('crypto');\nconst { loadLlmTiers } = require('./rubric-loader');\n\nconst OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';\nconst CACHE_DIR = path.join(__dirname, '../../../.cache/llm-usefulness');\n\nfunction ensureCacheDir() {\n fs.mkdirSync(CACHE_DIR, { recursive: true });\n}\n\nfunction clampScore(value) {\n const numeric = Number(value);\n if (!Number.isFinite(numeric)) return 0;\n if (numeric < 0) return 0;\n if (numeric > 100) return 100;\n return Math.round(numeric);\n}\n\nclass LlmEvaluator {\n constructor(apiKey, options = {}) {\n if (!apiKey) throw new Error('OPENROUTER_API_KEY is required when --llm is enabled.');\n ensureCacheDir();\n\n const tierConfig = loadLlmTiers();\n const tierName = options.tier || tierConfig.default_tier || 'free';\n const tier = tierConfig.tiers?.[tierName];\n if (!tier) {\n throw new Error(`Unknown llm tier: ${tierName}`);\n }\n\n this.apiKey = apiKey;\n this.tierName = tierName;\n this.tier = tier;\n this.maxRetries = Number(options.maxRetries || 2);\n this.batchInterval = this.tierName === 'free' ? 3200 : 1000;\n this.lastCallMs = 0;\n this.callCount = 0;\n this.spentUsd = 0;\n\n const defaultBudget = Number(this.tier.default_budget_usd ?? 0);\n const budgetInput = Number(options.budget);\n this.budget = this.tierName === 'free' ? 0 : Number.isFinite(budgetInput) && budgetInput >= 0 ? budgetInput : defaultBudget;\n\n this.modelIndex = 0;\n this.modelDailyCounts = {};\n this.modelMinuteCounts = {};\n this.minuteWindowStart = Date.now();\n\n this._loadDailyCounts();\n }\n\n _dailyFile() {\n const date = new Date().toISOString().slice(0, 10);\n return path.join(CACHE_DIR, `daily-counts-${date}.json`);\n }\n\n _loadDailyCounts() {\n const file = this._dailyFile();\n if (!fs.existsSync(file)) return;\n try {\n this.modelDailyCounts = JSON.parse(fs.readFileSync(file, 'utf8')) || {};\n } catch (_error) {\n this.modelDailyCounts = {};\n }\n }\n\n _saveDailyCounts() {\n fs.writeFileSync(this._dailyFile(), JSON.stringify(this.modelDailyCounts, null, 2));\n }\n\n _cacheKey(page, promptKey) {\n const body = String(page.content || page.textContent || '');\n const hash = crypto.createHash('md5').update(body).digest('hex').slice(0, 12);\n const safePath = String(page.path || 'unknown').replace(/[\\\\/]/g, '_');\n return `${safePath}__${hash}__${promptKey}.json`;\n }\n\n _cacheFile(key) {\n return path.join(CACHE_DIR, key);\n }\n\n _readCache(key) {\n const file = this._cacheFile(key);\n if (!fs.existsSync(file)) return null;\n try {\n return JSON.parse(fs.readFileSync(file, 'utf8'));\n } catch (_error) {\n return null;\n }\n }\n\n _writeCache(key, data) {\n fs.writeFileSync(this._cacheFile(key), JSON.stringify(data, null, 2));\n }\n\n _minuteLimit() {\n return Number(this.tier.rate_limit?.per_minute || 60);\n }\n\n _dailyLimit() {\n const limit = this.tier.rate_limit?.per_day;\n return limit === null || limit === undefined ? null : Number(limit);\n }\n\n _resetMinuteWindowIfNeeded() {\n if (Date.now() - this.minuteWindowStart > 60000) {\n this.minuteWindowStart = Date.now();\n this.modelMinuteCounts = {};\n }\n }\n\n _modelMinuteCount(model) {\n this._resetMinuteWindowIfNeeded();\n return Number(this.modelMinuteCounts[model] || 0);\n }\n\n _modelDailyCount(model) {\n return Number(this.modelDailyCounts[model] || 0);\n }\n\n _recordCall(model) {\n this.callCount += 1;\n this.modelDailyCounts[model] = this._modelDailyCount(model) + 1;\n this.modelMinuteCounts[model] = this._modelMinuteCount(model) + 1;\n this._saveDailyCounts();\n }\n\n _remainingCapacity() {\n const perDay = this._dailyLimit();\n if (perDay === null) return null;\n return (this.tier.models || []).reduce((sum, model) => sum + Math.max(0, perDay - this._modelDailyCount(model)), 0);\n }\n\n _selectModel() {\n const models = this.tier.models || [];\n if (models.length === 0) return null;\n\n const perDay = this._dailyLimit();\n for (let offset = 0; offset < models.length; offset += 1) {\n const idx = (this.modelIndex + offset) % models.length;\n const model = models[idx];\n\n if (perDay !== null && this._modelDailyCount(model) >= perDay) {\n continue;\n }\n\n const minuteLimit = this._minuteLimit();\n if (this._modelMinuteCount(model) >= minuteLimit) {\n continue;\n }\n\n this.modelIndex = idx;\n return model;\n }\n\n return null;\n }\n\n async _respectRateLimit() {\n const elapsed = Date.now() - this.lastCallMs;\n if (elapsed < this.batchInterval) {\n await this._sleep(this.batchInterval - elapsed);\n }\n this.lastCallMs = Date.now();\n }\n\n _interpolate(template, page, audience, purpose) {\n return String(template || '')\n .replace('{content}', String(page.textContent || '').slice(0, 4000))\n .replace('{frontmatter}', JSON.stringify(page.frontmatter || {}, null, 2))\n .replace('{audience}', String(audience || page.frontmatter?.audience || page.section || 'unknown'))\n .replace('{purpose}', String(purpose || page.frontmatter?.purpose || 'unknown'));\n }\n\n _extractJson(text) {\n const raw = String(text || '').trim();\n const cleaned = raw.replace(/^```json\\s*/i, '').replace(/```$/i, '').trim();\n try {\n return JSON.parse(cleaned);\n } catch (_error) {\n const match = cleaned.match(/\\{[\\s\\S]*\\}/);\n if (match) {\n try {\n return JSON.parse(match[0]);\n } catch (_inner) {\n return null;\n }\n }\n return null;\n }\n }\n\n async evaluate(page, criterion, promptTemplate, context = {}) {\n const cacheKey = this._cacheKey(page, criterion);\n if (context.resume !== false) {\n const cached = this._readCache(cacheKey);\n if (cached) return { ...cached, cached: true };\n }\n\n if (this.tierName !== 'free' && this.spentUsd >= this.budget) {\n return { status: 'budget_exceeded' };\n }\n\n let model = this._selectModel();\n if (!model) {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-rubric.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/audit-v2-usefulness.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": ".cache/llm-usefulness",
+ "type": "directory",
+ "call": "mkdirSync"
+ }
+ ],
+ "outputs_display": ".cache/llm-usefulness",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-rubric.test.js; indirect via tools/scripts/audit-v2-usefulness.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/changelog.js",
+ "script": "prompts/changelog",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for changelog page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/changelog');",
+ "header": "'use strict';\n/**\n * @script prompts/changelog\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for changelog page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/changelog');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n changelog_clear: {\n system: `${SYSTEM_BASE} Evaluate changelog summary clarity.`,\n user: `Evaluate this changelog page.\n\nCriteria:\n- Entries clearly describe what changed.\n- Time/version context is clear.\n\nPAGE CONTENT:\n{content}`\n },\n changelog_actionable: {\n system: `${SYSTEM_BASE} Evaluate changelog actionability for implementers.`,\n user: `Evaluate whether this changelog tells developers what action they should take.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/concept.js",
+ "script": "prompts/concept",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for concept page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/concept');",
+ "header": "'use strict';\n/**\n * @script prompts/concept\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for concept page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/concept');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n concept_focus: {\n system: `${SYSTEM_BASE} Evaluate concept-page focus.`,\n user: `Evaluate if this page stays focused on one primary concept.\n\nPAGE CONTENT:\n{content}`\n },\n concept_jargon: {\n system: `${SYSTEM_BASE} Evaluate jargon definition quality.`,\n user: `Evaluate if jargon is defined on first use or clearly linked.\n\nDeclared audience: {audience}\n\nPAGE CONTENT:\n{content}`\n },\n concept_practical: {\n system: `${SYSTEM_BASE} Evaluate practical relevance of conceptual explanation.`,\n user: `Evaluate if this concept page connects ideas to practical usage.\n\nPAGE CONTENT:\n{content}`\n },\n concept_clarity: {\n system: `${SYSTEM_BASE} Evaluate conceptual clarity.`,\n user: `Evaluate explanation quality, coherence, and readability.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/faq.js",
+ "script": "prompts/faq",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for faq page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/faq');",
+ "header": "'use strict';\n/**\n * @script prompts/faq\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for faq page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/faq');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n faq_real_questions: {\n system: `${SYSTEM_BASE} Evaluate realism of FAQ questions.`,\n user: `Evaluate this FAQ page.\n\nCriteria:\n- Questions reflect real user concerns.\n- Questions are not placeholder or invented fluff.\n\nPAGE CONTENT:\n{content}`\n },\n faq_direct_answers: {\n system: `${SYSTEM_BASE} Evaluate directness of FAQ answers.`,\n user: `Evaluate this FAQ page.\n\nCriteria:\n- Answers address the question directly first.\n- Avoids vague or circular responses.\n\nPAGE CONTENT:\n{content}`\n },\n faq_organised: {\n system: `${SYSTEM_BASE} Evaluate thematic organization in FAQ pages.`,\n user: `Evaluate this FAQ page for thematic grouping and scanability.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/glossary.js",
+ "script": "prompts/glossary",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for glossary page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/glossary');",
+ "header": "'use strict';\n/**\n * @script prompts/glossary\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for glossary page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/glossary');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n glossary_no_marketing: {\n system: `${SYSTEM_BASE} Evaluate glossary neutrality.`,\n user: `Evaluate this glossary page.\n\nCriteria:\n- Definitions are neutral and non-marketing.\n- Terms are concise and factual.\n\nPAGE CONTENT:\n{content}`\n },\n glossary_newcomer: {\n system: `${SYSTEM_BASE} Evaluate glossary coverage for newcomers.`,\n user: `Evaluate whether this glossary helps newcomers understand essential terms.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/how_to.js",
+ "script": "prompts/how_to",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for how_to page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/how_to');",
+ "header": "'use strict';\n/**\n * @script prompts/how_to\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for how_to page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/how_to');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n howto_action_result: {\n system: `${SYSTEM_BASE} Evaluate action/result pairing for how-to pages.`,\n user: `Evaluate this how-to page.\n\nCriteria:\n- Steps specify concrete actions.\n- Steps include expected outputs/results.\n- User can verify success after each stage.\n\nPAGE CONTENT:\n{content}`\n },\n audience_knowledge: {\n system: `${SYSTEM_BASE} Evaluate audience knowledge fit.`,\n user: `Evaluate whether this page matches declared audience knowledge.\n\nDeclared audience: {audience}\nDeclared purpose: {purpose}\n\nPAGE CONTENT:\n{content}`\n },\n howto_troubleshooting: {\n system: `${SYSTEM_BASE} Evaluate troubleshooting coverage for how-to pages.`,\n user: `Evaluate this how-to page.\n\nCriteria:\n- Mentions common failures.\n- Provides recovery guidance or links.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/landing.js",
+ "script": "prompts/landing",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for landing page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/landing');",
+ "header": "'use strict';\n/**\n * @script prompts/landing\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for landing page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/landing');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n landing_routing_clarity: {\n system: `${SYSTEM_BASE} Evaluate routing clarity for landing pages.`,\n user: `Evaluate if this landing page routes users clearly.\n\nCriteria:\n- Users can choose where to go next.\n- Navigation options are explicit.\n- No ambiguity about recommended next clicks.\n\nPAGE CONTENT:\n{content}`\n },\n audience_signal: {\n system: `${SYSTEM_BASE} Evaluate audience signaling strength.`,\n user: `Evaluate whether this page clearly states who it is for.\n\nDeclared audience: {audience}\n\nCriteria:\n- Audience cues are visible in title/opening copy.\n- Terminology matches the audience.\n\nPAGE CONTENT:\n{content}`\n },\n landing_no_teaching: {\n system: `${SYSTEM_BASE} Evaluate that landing pages avoid deep instructional teaching.`,\n user: `Evaluate whether this landing page avoids deep tutorial content.\n\nCriteria:\n- Mostly orientation/routing.\n- Limited procedural depth.\n- No long step-by-step instruction blocks.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/overview.js",
+ "script": "prompts/overview",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for overview page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/overview');",
+ "header": "'use strict';\n/**\n * @script prompts/overview\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for overview page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/overview');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n overview_benefit: {\n system: `${SYSTEM_BASE} Evaluate whether overview pages explain reader benefit.`,\n user: `Evaluate this overview page.\n\nCriteria:\n- Why this topic matters is clear early.\n- Reader benefit is concrete.\n\nPAGE CONTENT:\n{content}`\n },\n overview_next_context: {\n system: `${SYSTEM_BASE} Evaluate whether overview pages provide context for next steps.`,\n user: `Evaluate this overview page.\n\nCriteria:\n- Mentions what to read/do next.\n- Links to next resources are contextualized.\n\nPAGE CONTENT:\n{content}`\n },\n overview_no_detail: {\n system: `${SYSTEM_BASE} Evaluate that overview pages avoid exhaustive implementation detail.`,\n user: `Evaluate this overview page.\n\nCriteria:\n- Stays high-level.\n- Avoids deep exhaustive procedures/reference dumps.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/reference.js",
+ "script": "prompts/reference",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for reference page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/reference');",
+ "header": "'use strict';\n/**\n * @script prompts/reference\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for reference page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/reference');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n reference_params: {\n system: `${SYSTEM_BASE} Evaluate parameter completeness for reference pages.`,\n user: `Evaluate this reference page.\n\nCriteria:\n- Parameters/fields are complete and clearly named.\n- Required/optional/default/type details are present where expected.\n\nPAGE CONTENT:\n{content}`\n },\n reference_examples: {\n system: `${SYSTEM_BASE} Evaluate example quality for reference pages.`,\n user: `Evaluate this reference page.\n\nCriteria:\n- Includes realistic examples.\n- Examples align with documented parameters/fields.\n\nPAGE CONTENT:\n{content}`\n },\n reference_no_prose: {\n system: `${SYSTEM_BASE} Evaluate whether the page remains lookup-oriented and avoids narrative drift.`,\n user: `Evaluate this reference page for lookup orientation.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/troubleshooting.js",
+ "script": "prompts/troubleshooting",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for troubleshooting page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/troubleshooting');",
+ "header": "'use strict';\n/**\n * @script prompts/troubleshooting\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for troubleshooting page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/troubleshooting');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n troubleshooting_symptom_first: {\n system: `${SYSTEM_BASE} Evaluate symptom-first troubleshooting structure.`,\n user: `Evaluate this troubleshooting page.\n\nCriteria:\n- Entries are structured by symptom/error users observe.\n- Cause-only structure without symptom entrypoints scores low.\n\nPAGE CONTENT:\n{content}`\n },\n troubleshooting_actionable: {\n system: `${SYSTEM_BASE} Evaluate actionability of troubleshooting fixes.`,\n user: `Evaluate this troubleshooting page.\n\nCriteria:\n- Fixes are explicit and executable.\n- Steps are concrete enough to attempt immediately.\n\nPAGE CONTENT:\n{content}`\n },\n troubleshooting_searchable: {\n system: `${SYSTEM_BASE} Evaluate searchability of errors and symptoms.`,\n user: `Evaluate if errors/symptoms are represented in searchable phrasing.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/prompts/tutorial.js",
+ "script": "prompts/tutorial",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "LLM prompt template for tutorial page-type usefulness evaluation.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { getPrompt } = require('../lib/docs-usefulness/prompts/tutorial');",
+ "header": "'use strict';\n/**\n * @script prompts/tutorial\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement LLM prompt template for tutorial page-type usefulness evaluation.\n * @pipeline indirect -- library module\n * @usage const { getPrompt } = require('../lib/docs-usefulness/prompts/tutorial');\n */\n\nconst SYSTEM_BASE = 'You are a documentation quality evaluator for Livepeer docs. Return ONLY JSON: {\"score\":0-100,\"pass\":true/false,\"reasoning\":\"one sentence\"}.';\n\nmodule.exports = {\n tutorial_steps_complete: {\n system: `${SYSTEM_BASE} Evaluate tutorial step completeness.`,\n user: `Evaluate if this tutorial can be completed end-to-end by following only this page.\n\nPAGE CONTENT:\n{content}`\n },\n tutorial_newcomer: {\n system: `${SYSTEM_BASE} Evaluate newcomer accessibility.`,\n user: `Evaluate if this tutorial is accessible to newcomers to the domain.\n\nPAGE CONTENT:\n{content}`\n },\n tutorial_error_recovery: {\n system: `${SYSTEM_BASE} Evaluate error recovery guidance in tutorials.`,\n user: `Evaluate whether this tutorial includes recovery paths when steps fail.\n\nPAGE CONTENT:\n{content}`\n },\n tutorial_context: {\n system: `${SYSTEM_BASE} Evaluate contextual explanations for why actions are performed.`,\n user: `Evaluate whether this tutorial explains why each major step matters.\n\nPAGE CONTENT:\n{content}`\n }\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/prompts/index.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/prompts/index.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/quality-gate.js",
+ "script": "quality-gate",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14, R-C6",
+ "purpose_statement": "Applies pass/fail thresholds to usefulness scores.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { applyGate } = require('../lib/docs-usefulness/quality-gate');",
+ "header": "'use strict';\n/**\n * @script quality-gate\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14, R-C6\n * @purpose-statement Applies pass/fail thresholds to usefulness scores.\n * @pipeline indirect -- library module\n * @usage const { applyGate } = require('../lib/docs-usefulness/quality-gate');\n */\n\nfunction runQualityGate(page) {\n const details = {};\n let fails = 0;\n let warns = 0;\n\n details.mdx_parses = !(page.flags || []).includes('mdx_parse_error');\n if (!details.mdx_parses) fails += 1;\n\n details.frontmatter_exists = !(page.flags || []).includes('missing_frontmatter');\n if (!details.frontmatter_exists) fails += 1;\n\n details.frontmatter_valid = !(page.flags || []).includes('invalid_frontmatter');\n if (!details.frontmatter_valid) fails += 1;\n\n details.has_title = Boolean(page.frontmatter?.title);\n if (!details.has_title) fails += 1;\n\n details.has_description = Boolean(page.frontmatter?.description);\n if (!details.has_description) fails += 1;\n\n details.imports_resolve = !(page.flags || []).includes('broken_import');\n if (!details.imports_resolve) fails += 1;\n\n details.no_broken_links = !(page.flags || []).includes('broken_links');\n if (!details.no_broken_links) fails += 1;\n\n details.no_todo_markers = !(page.flags || []).includes('todo_marker');\n if (!details.no_todo_markers) warns += 1;\n\n details.no_coming_soon = !(page.flags || []).includes('coming_soon');\n if (!details.no_coming_soon) warns += 1;\n\n details.no_legacy_links = !(page.flags || []).includes('legacy_v2_pages_link');\n if (!details.no_legacy_links) warns += 1;\n\n details.images_have_alt =\n !Array.isArray(page.images) ||\n page.images.length === 0 ||\n page.images.every((image) => Boolean(String(image.alt || '').trim()));\n if (!details.images_have_alt) warns += 1;\n\n const status = fails > 0 ? 'fail' : warns > 0 ? 'warn' : 'pass';\n return {\n status,\n errors: fails + warns,\n fails,\n warns,\n details\n };\n}\n\nmodule.exports = {\n runQualityGate\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/scoring.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/lib/docs-usefulness/scoring.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/rubric-loader.js",
+ "script": "rubric-loader",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Loads and parses rubric YAML/JSON for page-type scoring rules.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { loadRubric } = require('../lib/docs-usefulness/rubric-loader');",
+ "header": "'use strict';\n/**\n * @script rubric-loader\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement Loads and parses rubric YAML/JSON for page-type scoring rules.\n * @pipeline indirect -- library module\n * @usage const { loadRubric } = require('../lib/docs-usefulness/rubric-loader');\n */\n\nconst fs = require('fs');\nconst path = require('path');\n\nconst PURPOSE_ENUM = [\n 'landing',\n 'overview',\n 'concept',\n 'how_to',\n 'tutorial',\n 'reference',\n 'faq',\n 'glossary',\n 'changelog',\n 'troubleshooting'\n];\n\nconst AUDIENCE_ENUM = [\n 'developer',\n 'gateway-operator',\n 'orchestrator',\n 'delegator',\n 'platform-builder',\n 'community',\n 'internal',\n 'general',\n 'everyone'\n];\n\nconst SECTION_DEFAULT_AUDIENCE = {\n home: 'everyone',\n about: 'general',\n developers: 'developer',\n gateways: 'gateway-operator',\n orchestrators: 'orchestrator',\n lpt: 'delegator',\n community: 'community',\n solutions: 'platform-builder',\n internal: 'internal',\n resources: 'everyone'\n};\n\nconst cache = new Map();\n\nfunction loadJson(filePath) {\n const abs = path.resolve(filePath);\n if (cache.has(abs)) return cache.get(abs);\n const parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));\n cache.set(abs, parsed);\n return parsed;\n}\n\nfunction getFrontmatterValues(page) {\n if (!page) return {};\n if (page.frontmatter && page.frontmatter.data && typeof page.frontmatter.data === 'object') {\n return page.frontmatter.data;\n }\n if (page.frontmatter && typeof page.frontmatter === 'object') {\n return page.frontmatter;\n }\n if (page.frontmatterData && typeof page.frontmatterData === 'object') {\n return page.frontmatterData;\n }\n return {};\n}\n\nfunction configPath(relativePath) {\n return path.join(__dirname, '../../config', relativePath);\n}\n\nfunction loadRubric(filePath = configPath('usefulness-rubric.json')) {\n return loadJson(filePath);\n}\n\nfunction loadJourneys(filePath = configPath('usefulness-journeys.json')) {\n return loadJson(filePath);\n}\n\nfunction loadAudienceNormalization(filePath = configPath('usefulness-audience-normalization.json')) {\n return loadJson(filePath);\n}\n\nfunction loadLlmTiers(filePath = configPath('usefulness-llm-tiers.json')) {\n return loadJson(filePath);\n}\n\nfunction normalizeAudienceToken(token, normalization) {\n const value = String(token || '').trim().toLowerCase();\n if (!value) return null;\n if (AUDIENCE_ENUM.includes(value)) return value;\n if (normalization?.synonyms && normalization.synonyms[value]) {\n return normalization.synonyms[value];\n }\n return null;\n}\n\nfunction audienceTokensFromRaw(raw, normalization) {\n if (!raw && raw !== 0) return [];\n if (Array.isArray(raw)) {\n return raw\n .map((item) => normalizeAudienceToken(item, normalization))\n .filter(Boolean);\n }\n\n const text = String(raw).trim();\n if (!text) return [];\n\n const separators = normalization?.token_separators || [',', ';', '|'];\n let tokens = [text];\n separators.forEach((sep) => {\n tokens = tokens.flatMap((token) => token.split(sep));\n });\n\n return tokens\n .map((token) => normalizeAudienceToken(token, normalization))\n .filter(Boolean);\n}\n\nfunction selectAudience(tokens, page, normalization) {\n if (!tokens.length) return null;\n if (tokens.length === 1) return tokens[0];\n\n const sectionDefault =\n (normalization?.section_defaults && normalization.section_defaults[page.section]) ||\n SECTION_DEFAULT_AUDIENCE[page.section];\n if (sectionDefault && tokens.includes(sectionDefault)) return sectionDefault;\n\n const precedence = normalization?.deterministic_precedence || AUDIENCE_ENUM;\n for (const candidate of precedence) {\n if (tokens.includes(candidate)) return candidate;\n }\n return tokens[0] || null;\n}\n\nfunction resolveAudience(page, normalization = loadAudienceNormalization()) {\n const frontmatter = getFrontmatterValues(page);\n const rawAudience = frontmatter.audience;\n const tokens = audienceTokensFromRaw(rawAudience, normalization);\n const selected = selectAudience(tokens, page, normalization);\n\n if (selected && AUDIENCE_ENUM.includes(selected)) {\n return {\n audience: selected,\n source: 'frontmatter',\n audienceRaw: rawAudience,\n audienceCandidates: tokens\n };\n }\n\n const fallback =\n (normalization?.section_defaults && normalization.section_defaults[page.section]) ||\n SECTION_DEFAULT_AUDIENCE[page.section] ||\n 'everyone';\n return {\n audience: fallback,\n source: 'inferred',\n audienceRaw: rawAudience,\n audienceCandidates: tokens\n };\n}\n\nfunction resolvePurpose(page) {\n const frontmatter = getFrontmatterValues(page);\n const frontmatterPurpose = String(frontmatter.purpose || '').trim();\n if (frontmatterPurpose) {\n if (PURPOSE_ENUM.includes(frontmatterPurpose)) {\n return { purpose: frontmatterPurpose, source: 'frontmatter', invalid: false };\n }\n return { purpose: null, source: 'none', invalid: true };\n }\n\n const base = path.basename(String(page.path || ''), path.extname(String(page.path || '')));\n const route = String(page.path || '').toLowerCase();\n\n if (/portal|mission-control/i.test(base) || base === 'index') return { purpose: 'landing', source: 'inferred', invalid: false };\n if (/quickstart|get-started|primer|^first-/i.test(base)) return { purpose: 'tutorial', source: 'inferred', invalid: false };\n if (/^faq/i.test(base)) return { purpose: 'faq', source: 'inferred', invalid: false };\n if (/troubleshoot/i.test(base)) return { purpose: 'troubleshooting', source: 'inferred', invalid: false };\n if (/glossary/i.test(base)) return { purpose: 'glossary', source: 'inferred', invalid: false };\n if (/changelog|release-notes/i.test(base)) return { purpose: 'changelog', source: 'inferred', invalid: false };\n if (/api-reference|config-flags/i.test(base)) return { purpose: 'reference', source: 'inferred', invalid: false };\n if (/overview/i.test(base)) return { purpose: 'overview', source: 'inferred', invalid: false };\n if (/\\/references?\\//i.test(route)) return { purpose: 'reference', source: 'inferred', invalid: false };\n\n if ((page.components || []).includes('Steps')) return { purpose: 'how_to', source: 'inferred', invalid: false };\n\n if ((page.wordCount || 0) < 150 && (page.components || []).some((component) => ['Card', 'CardGroup', 'GotoCard', 'DisplayCard'].includes(component))) {\n return { purpose: 'landing', source: 'inferred', invalid: false };\n }\n\n const accordionCount = (String(page.content || '').match(/]/g) || []).length;\n if (accordionCount >= 5) return { purpose: 'faq', source: 'inferred', invalid: false };\n\n if ((page.wordCount || 0) > 300 && (page.headings || []).length >= 3 && !(page.components || []).includes('Steps')) {\n return { purpose: 'concept', source: 'inferred', invalid: false };\n }\n\n return { purpose: null, source: 'none', invalid: false };\n}\n\nfunction getRulesForPage(rubric, page, normalization = loadAudienceNormalization()) {\n const purposeResolution = resolvePurpose(page);\n const audienceResolution = resolveAudience(page, normalization);\n\n if (!purposeResolution.purpose || !rubric[purposeResolution.purpose]) {\n return {\n purpose: null,\n purposeSource: purposeResolution.source,",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-rubric.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/config-validator.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/journey-check.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/llm-evaluator.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/scoring.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/assign-purpose-metadata.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/audit-v2-usefulness.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-rubric.test.js; indirect via tools/lib/docs-usefulness/config-validator.js; indirect via tools/lib/docs-usefulness/journey-check.js; indirect via tools/lib/docs-usefulness/llm-evaluator.js; indirect via tools/lib/docs-usefulness/scoring.js; indirect via tools/scripts/assign-purpose-metadata.js; indirect via tools/scripts/audit-v2-usefulness.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/lib/docs-usefulness/rule-evaluators.js",
+ "script": "rule-evaluators",
+ "category": "utility",
+ "purpose": "qa:repo-health",
+ "scope": "single-domain",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Evaluates individual rubric rules against page content.",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "const { evaluateRule } = require('../lib/docs-usefulness/rule-evaluators');",
+ "header": "'use strict';\n/**\n * @script rule-evaluators\n * @category utility\n * @purpose qa:repo-health\n * @scope single-domain\n * @owner docs\n * @needs R-R14\n * @purpose-statement Evaluates individual rubric rules against page content.\n * @pipeline indirect -- library module\n * @usage const { evaluateRule } = require('../lib/docs-usefulness/rule-evaluators');\n */\n\nfunction toText(value) {\n return String(value || '').toLowerCase();\n}\n\nfunction countMatches(content, re) {\n return (String(content || '').match(re) || []).length;\n}\n\nfunction getSignalValue(page, signal) {\n const extractors = {\n internal_link_count: () => (page.internalLinks || []).length,\n code_block_count: () => (page.codeBlocks || []).length,\n word_count: () => Number(page.wordCount || 0),\n heading_count: () => (page.headings || []).length,\n max_heading_level: () => {\n const levels = (page.headings || []).map((heading) => Number(heading.level || 0)).filter(Boolean);\n if (levels.length === 0) return 0;\n return Math.max(...levels);\n },\n steps_component: () => ((page.components || []).includes('Steps') ? 1 : 0),\n h2_or_accordion_count: () => {\n const h2Count = (page.headings || []).filter((heading) => Number(heading.level) === 2).length;\n const accordionCount = countMatches(page.content, /]/g);\n return Math.max(h2Count, accordionCount);\n },\n code_inline_dense: () => countMatches(page.content, /`[^`]+`/g),\n error_keyword: () => (/\\b(error|fail|exception|timeout|refused|denied|cannot|unable)\\b/i.test(page.textContent || '') ? 1 : 0)\n };\n\n const extractor = extractors[signal];\n if (!extractor) {\n throw new Error(`Unknown signal: ${signal}`);\n }\n return extractor();\n}\n\nconst JARGON_TERMS = [\n 'orchestrator',\n 'delegator',\n 'transcoding',\n 'transcode',\n 'lpt',\n 'arbitrum',\n 'clearinghouse',\n 'byoc',\n 'go-livepeer',\n 'aiserviceregistry',\n 'pipeline',\n 'epoch',\n 'round',\n 'bonding',\n 'unbonding',\n 'slashing',\n 'erc-20',\n 'wei',\n 'gwei',\n 'mainnet',\n 'testnet'\n];\n\nconst DEFINITION_SIGNALS = ['is a', 'refers to', 'means', 'defined as', 'also known as', 'i.e.'];\n\nconst BOOLEAN_CHECKS = {\n first_para_has_value_prop(page) {\n const firstPara = String(page.textContent || '').split(/\\n\\n/)[0] || '';\n const hasAudienceSignal = /you|developer|operator|delegat|build|run|stake|community/i.test(firstPara);\n const hasActionSignal = /learn|find|get started|discover|explore|choose|set up|start/i.test(firstPara);\n return hasAudienceSignal && hasActionSignal;\n },\n\n all_internal_links_resolve(page) {\n return !(page.flags || []).includes('broken_links');\n }\n};\n\nfunction splitByH2(page) {\n const text = String(page.textContent || '');\n const parts = text.split(/(?=^## )/m);\n return parts\n .map((part) => part.trim())\n .filter(Boolean)\n .map((part) => {\n const lines = part.split('\\n');\n const heading = lines[0].replace(/^##\\s*/, '').trim();\n const body = lines.slice(1).join('\\n').trim();\n const wordCount = body ? body.split(/\\s+/).filter(Boolean).length : 0;\n return { heading, content: body, wordCount };\n });\n}\n\nconst EVALUATORS = {\n boolean(page, rule) {\n const fn = BOOLEAN_CHECKS[rule.check];\n if (!fn) throw new Error(`Unknown boolean check: ${rule.check}`);\n return Boolean(fn(page));\n },\n\n threshold(page, rule) {\n const value = getSignalValue(page, rule.signal);\n if (rule.min !== undefined && value < rule.min) return false;\n if (rule.max !== undefined && value > rule.max) return false;\n return true;\n },\n\n absence(page, rule) {\n return getSignalValue(page, rule.signal) === 0;\n },\n\n presence(page, rule) {\n const components = Array.isArray(rule.components) ? rule.components : [];\n return components.some((component) => (page.components || []).includes(component));\n },\n\n heading_keyword(page, rule) {\n const keywords = (rule.keywords || []).map((keyword) => toText(keyword));\n return (page.headings || []).some((heading) => {\n const text = toText(heading.text);\n return keywords.some((keyword) => text.includes(keyword));\n });\n },\n\n content_keyword(page, rule) {\n const text = toText(page.textContent);\n return (rule.keywords || []).some((keyword) => text.includes(toText(keyword)));\n },\n\n presence_any(page, rule) {\n const signals = Array.isArray(rule.signals) ? rule.signals : [];\n return signals.some((signal) => {\n switch (signal) {\n case 'mermaid':\n return String(page.content || '').includes('```mermaid') || (page.components || []).includes('Mermaid');\n case 'image':\n return (page.images || []).length > 0;\n case 'table':\n return (page.tables || []).length > 0;\n case 'parameter_list':\n return /\\|\\s*(parameter|name|field|flag|option)\\s*\\|/i.test(page.content || '');\n case 'openapi_marker':\n return Boolean(page.frontmatter?.openapi) || /openapi/i.test(String(page.content || ''));\n case 'code_inline_dense':\n return countMatches(page.content, /`[^`]+`/g) > 5;\n case 'error_keyword':\n return /\\b(error|fail|exception|timeout|cannot|unable)\\b/i.test(page.textContent || '');\n default:\n return false;\n }\n });\n },\n\n content_check(page, rule) {\n if (rule.check !== 'first_200_words_no_jargon') {\n return true;\n }\n\n const words = String(page.textContent || '').split(/\\s+/).slice(0, 200);\n const first200 = words.join(' ').toLowerCase();\n let undefinedJargon = 0;\n for (const term of JARGON_TERMS) {\n const idx = first200.indexOf(term);\n if (idx === -1) continue;\n const window = first200.slice(Math.max(0, idx - 80), idx + term.length + 80);\n const defined = DEFINITION_SIGNALS.some((signal) => window.includes(signal));\n if (!defined) undefinedJargon += 1;\n }\n return undefinedJargon <= 1;\n },\n\n heading_pattern(page, rule) {\n const headings = (page.headings || []).filter((heading) => Number(heading.level) <= 3);\n if (headings.length < 2) return false;\n\n switch (rule.pattern) {\n case 'question':\n return (\n headings.filter((heading) => {\n const text = String(heading.text || '').trim();\n return /\\?$/.test(text) || /^(how|what|why|when|where|can|do|is|should|will)\\b/i.test(text);\n }).length >= 3\n );\n case 'error_or_symptom':\n return (\n headings.filter((heading) => {\n const text = String(heading.text || '');\n return (\n /\\b(error|fail|cannot|unable|timeout|crash|not working|issue|warning)\\b/i.test(text) ||\n /^`[^`]+`/.test(text)\n );\n }).length >= 2\n );\n case 'alphabetical': {\n const h2 = (page.headings || [])\n .filter((heading) => Number(heading.level) === 2)\n .map((heading) => toText(heading.text));\n if (h2.length < 5) return true;\n let ordered = 0;\n for (let i = 1; i < h2.length; i += 1) {\n if (h2[i] >= h2[i - 1]) ordered += 1;\n }\n return ordered / (h2.length - 1) >= 0.7;\n }\n default:\n return true;\n }\n },\n\n avg_section_words(page, rule) {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/usefulness-rubric.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/scoring.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/usefulness-rubric.test.js; indirect via tools/lib/docs-usefulness/scoring.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/audit-scripts.js",
+ "script": "audit-scripts",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": "tools/scripts, tasks/README.md, tasks/reports, tests/unit/script-docs.test.js, tests/README.md",
+ "owner": "docs",
+ "needs": "E-C1, R-R14",
+ "purpose_statement": "Script auditor — analyses all repo scripts, categorises usage/overlap, generates SCRIPT_AUDIT reports",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/audit-scripts.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script audit-scripts\n * @category validator\n * @purpose qa:repo-health\n * @scope tools/scripts, tasks/README.md, tasks/reports, tests/unit/script-docs.test.js, tests/README.md\n * @owner docs\n * @needs E-C1, R-R14\n * @purpose-statement Script auditor — analyses all repo scripts, categorises usage/overlap, generates SCRIPT_AUDIT reports\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/audit-scripts.js [flags]\n */\n\nconst fs = require('fs')\nconst path = require('path')\nconst crypto = require('crypto')\nconst { execSync } = require('child_process')\n\nlet yaml = null\ntry {\n // Optional dependency; parser falls back to text heuristics if unavailable.\n yaml = require('js-yaml')\n} catch (_err) {\n yaml = null\n}\n\nconst REPO_ROOT = process.cwd()\nconst DEFAULT_FORMAT = 'both'\nconst DEFAULT_OUTPUT_DIR = 'tasks/reports/repo-ops'\nconst REPORTS_INDEX_PATH = path.join('tasks', 'reports', 'INDEX.md')\n\nconst RULES_SOURCE = ['tests/unit/script-docs.test.js', 'tests/README.md']\n\nconst LEGACY_REQUIRED_TAGS = [\n '@script',\n '@summary',\n '@owner',\n '@scope',\n '@usage',\n '@inputs',\n '@outputs',\n '@exit-codes',\n '@examples',\n '@notes',\n]\n\nconst FRAMEWORK_REQUIRED_TAGS = [\n '@script',\n '@category',\n '@purpose',\n '@scope',\n '@owner',\n '@needs',\n '@purpose-statement',\n '@pipeline',\n]\n\nconst LEGACY_INLINE_REQUIRED_TAGS = ['@script', '@summary', '@owner', '@scope']\nconst FRAMEWORK_INLINE_REQUIRED_TAGS = FRAMEWORK_REQUIRED_TAGS\nconst LEGACY_BLOCK_REQUIRED_TAGS = [\n '@usage',\n '@inputs',\n '@outputs',\n '@exit-codes',\n '@examples',\n '@notes',\n]\nconst PLACEHOLDER_PATTERNS = [\n /^<.*>$/,\n /^todo\\b/i,\n /^tbd\\b/i,\n /^fill\\b/i,\n /^replace$/i,\n /^replace me$/i,\n /^n\\/a$/i,\n /^none$/i,\n /^placeholder$/i,\n]\n\nconst SCRIPT_EXTENSIONS = new Set([\n '.js',\n '.cjs',\n '.mjs',\n '.ts',\n '.tsx',\n '.sh',\n '.bash',\n '.py',\n])\nconst PACKAGE_JSON_PATHS = [\n 'tests/package.json',\n 'tools/package.json',\n\n 'tools/scripts/snippets/generate-data/scripts/package.json',\n]\nconst WORKFLOW_DIR = '.github/workflows'\nconst HOOK_FILES = ['.githooks/pre-commit', '.githooks/verify.sh']\n\nconst IGNORED_DIR_SEGMENTS = new Set([\n 'node_modules',\n '.git',\n '.venv',\n 'tmp',\n 'notion',\n])\nconst SCRIPT_COMMAND_NAMES = new Set([\n 'node',\n 'bash',\n 'sh',\n 'python',\n 'python3',\n 'npm',\n 'npx',\n 'pnpm',\n 'yarn',\n])\n\nfunction usage() {\n console.log(\n 'Usage: node tools/scripts/audit-scripts.js [--format both|md|json] [--output-dir ] [--strict]'\n )\n}\n\nfunction parseArgs(argv) {\n const out = {\n format: DEFAULT_FORMAT,\n outputDir: DEFAULT_OUTPUT_DIR,\n strict: false,\n }\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i]\n if (token === '--strict') {\n out.strict = true\n continue\n }\n\n if (token === '--format') {\n out.format = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n\n if (token.startsWith('--format=')) {\n out.format = token.slice('--format='.length).trim()\n continue\n }\n\n if (token === '--output-dir') {\n out.outputDir = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n\n if (token.startsWith('--output-dir=')) {\n out.outputDir = token.slice('--output-dir='.length).trim()\n continue\n }\n\n console.error(`Unknown argument: ${token}`)\n usage()\n process.exit(1)\n }\n\n if (!['both', 'md', 'json'].includes(out.format)) {\n console.error(`Invalid --format value: ${out.format}`)\n usage()\n process.exit(1)\n }\n\n if (!out.outputDir) {\n console.error('Missing --output-dir value')\n usage()\n process.exit(1)\n }\n\n return out\n}\n\nfunction normalizeRepoPath(value) {\n return String(value || '')\n .split(path.sep)\n .join('/')\n}\n\nfunction ensureWithinRepo(absPath) {\n const rel = normalizeRepoPath(path.relative(REPO_ROOT, absPath))\n if (!rel || rel === '.' || rel.startsWith('..')) return ''\n return rel\n}\n\nfunction fileExists(repoPath) {\n const full = path.join(REPO_ROOT, repoPath)\n return fs.existsSync(full) && fs.statSync(full).isFile()\n}\n\nfunction readFileSafe(repoPath) {\n try {\n return fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8')\n } catch (_err) {\n return ''\n }\n}\n\nfunction shouldExclude(repoPath) {\n const p = normalizeRepoPath(repoPath)\n if (p.startsWith('tools/scripts/archive/')) return true\n const parts = p.split('/')\n if (parts.some((part) => IGNORED_DIR_SEGMENTS.has(part))) return true\n if (p.endsWith('.disabled')) return true\n if (path.basename(p).includes('.bak')) return true\n return false\n}\n\nfunction hasShebang(repoPath) {\n try {\n const content = fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8')\n return content.startsWith('#!')\n } catch (_err) {\n return false",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/script-footprint-and-usage-audit.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/script-footprint-and-usage-audit.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/validators/components/check-mdx-component-scope.js",
+ "script": "check-mdx-component-scope",
+ "category": "validator",
+ "purpose": "qa:repo-health",
+ "scope": "tools/scripts/validators/components, tests/run-all.js, tests/run-pr-checks.js, snippets/components, tests/utils",
+ "owner": "docs",
+ "needs": "R-R10, R-R29",
+ "purpose_statement": "Validates MDX-facing component modules do not depend on private file-scope helper bindings from exported components.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/scripts/validators/components/check-mdx-component-scope.js [--files path[,path...]] [--staged]",
+ "header": "#!/usr/bin/env node\n/**\n * @script check-mdx-component-scope\n * @category validator\n * @purpose qa:repo-health\n * @scope tools/scripts/validators/components, tests/run-all.js, tests/run-pr-checks.js, snippets/components, tests/utils\n * @owner docs\n * @needs R-R10, R-R29\n * @purpose-statement Validates MDX-facing component modules do not depend on private file-scope helper bindings from exported components.\n * @pipeline manual\n * @usage node tools/scripts/validators/components/check-mdx-component-scope.js [--files path[,path...]] [--staged]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\nconst {\n getMdxFiles,\n getStagedDocsPageFiles,\n getStagedFiles\n} = require('../../../../tests/utils/file-walker');\nconst { extractImports } = require('../../../../tests/utils/mdx-parser');\n\nconst RULE_LABEL = '[4.12]';\nconst DEFAULT_COMPONENT_ROOT = 'snippets/components';\nconst COMPONENT_EXPORT_NAME_RE = /^[A-Z][A-Za-z0-9]*$/;\nconst KNOWN_GLOBALS = new Set([\n 'Array',\n 'Boolean',\n 'Date',\n 'Error',\n 'Function',\n 'JSON',\n 'Map',\n 'Math',\n 'Number',\n 'Object',\n 'Promise',\n 'Reflect',\n 'RegExp',\n 'Set',\n 'String',\n 'Symbol',\n 'URL',\n 'URLSearchParams',\n 'WeakMap',\n 'WeakSet',\n 'BigInt',\n 'Infinity',\n 'NaN',\n 'undefined',\n 'console',\n 'document',\n 'window',\n 'navigator',\n 'location',\n 'history',\n 'localStorage',\n 'sessionStorage',\n 'requestAnimationFrame',\n 'cancelAnimationFrame',\n 'setTimeout',\n 'clearTimeout',\n 'setInterval',\n 'clearInterval',\n 'fetch',\n 'Headers',\n 'Request',\n 'Response',\n 'AbortController',\n 'IntersectionObserver',\n 'MutationObserver',\n 'ResizeObserver',\n 'HTMLElement',\n 'Node',\n 'process',\n '__dirname',\n '__filename',\n 'require',\n 'module',\n 'exports',\n 'global',\n 'globalThis',\n 'Intl'\n]);\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nconst REPO_ROOT = getRepoRoot();\nif (process.cwd() !== REPO_ROOT) {\n process.chdir(REPO_ROOT);\n}\n\nfunction loadBabelParser() {\n try {\n return require('@babel/parser');\n } catch (_error) {\n return require(path.join(REPO_ROOT, 'tools', 'node_modules', '@babel', 'parser'));\n }\n}\n\nconst { parse } = loadBabelParser();\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction usage() {\n console.log(\n [\n 'Usage: node tools/scripts/validators/components/check-mdx-component-scope.js [options]',\n '',\n 'Options:',\n ` --files Limit validation to specific component files under ${DEFAULT_COMPONENT_ROOT}`,\n ' --staged Validate changed component files plus components imported by staged routable MDX pages',\n ' --help, -h Show this message'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n files: [],\n staged: false,\n help: false\n };\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n if (token === '--staged') {\n args.staged = true;\n continue;\n }\n\n if (token === '--files' || token === '--file') {\n const raw = String(argv[index + 1] || '').trim();\n if (raw) {\n raw\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((part) => args.files.push(part));\n }\n index += 1;\n continue;\n }\n\n if (token.startsWith('--files=')) {\n token\n .slice('--files='.length)\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((part) => args.files.push(part));\n continue;\n }\n\n if (token.startsWith('--file=')) {\n token\n .slice('--file='.length)\n .split(',')\n .map((part) => part.trim())\n .filter(Boolean)\n .forEach((part) => args.files.push(part));\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n args.files = [...new Set(args.files)];\n return args;\n}\n\nfunction normalizeRepoPath(inputPath) {\n const raw = String(inputPath || '').trim();\n if (!raw) return '';\n const absolute = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(REPO_ROOT, raw);\n return toPosix(path.relative(REPO_ROOT, absolute));\n}\n\nfunction isSafeRepoRelative(relPath) {\n return relPath && relPath !== '..' && !relPath.startsWith('../');\n}\n\nfunction resolveImportTarget(importPath, importerFile) {\n const raw = String(importPath || '').trim();\n if (!raw) return '';\n\n let basePath = '';\n if (raw.startsWith('/')) {\n basePath = path.resolve(REPO_ROOT, raw.replace(/^\\/+/, ''));\n } else if (raw.startsWith('.')) {\n basePath = path.resolve(path.dirname(importerFile), raw);\n } else {\n return '';\n }\n\n const candidates = [];\n if (path.extname(basePath)) {\n candidates.push(basePath);\n } else {\n candidates.push(basePath);\n candidates.push(`${basePath}.jsx`);\n candidates.push(`${basePath}.js`);\n candidates.push(path.join(basePath, 'index.jsx'));\n candidates.push(path.join(basePath, 'index.js'));\n }",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/mdx-component-scope.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/generate-component-governance-remediation-reports.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/mdx-component-scope.test.js; indirect via tools/scripts/generate-component-governance-remediation-reports.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tests/utils/openapi-rolling-issue.js",
+ "script": "openapi-rolling-issue",
+ "category": "validator",
+ "purpose": "tooling:api-spec",
+ "scope": "tests/utils, tests/unit, .github/workflows/openapi-reference-validation.yml",
+ "owner": "docs",
+ "needs": "F-R17",
+ "purpose_statement": "OpenAPI rolling issue utility — creates/updates GitHub issues for persistent OpenAPI audit findings",
+ "pipeline_declared": "indirect -- library module",
+ "usage": "node tests/utils/openapi-rolling-issue.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script openapi-rolling-issue\n * @category validator\n * @purpose tooling:api-spec\n * @scope tests/utils, tests/unit, .github/workflows/openapi-reference-validation.yml\n * @owner docs\n * @needs F-R17\n * @purpose-statement OpenAPI rolling issue utility — creates/updates GitHub issues for persistent OpenAPI audit findings\n * @pipeline indirect -- library module\n * @usage node tests/utils/openapi-rolling-issue.js [flags]\n */\n\nconst ROLLING_ISSUE_MARKER = '';\nconst ROLLING_ISSUE_TITLE = '[tooling]: OpenAPI reference validation failures';\nconst ROLLING_ISSUE_LABELS = ['docs-v2', 'help wanted', 'status: needs-triage', 'type: bug', 'area: ci-cd'];\n\nfunction compareFindings(a, b) {\n const fileA = String(a?.file || '');\n const fileB = String(b?.file || '');\n if (fileA !== fileB) return fileA.localeCompare(fileB);\n\n const lineA = Number(a?.line || 0);\n const lineB = Number(b?.line || 0);\n if (lineA !== lineB) return lineA - lineB;\n\n const typeA = String(a?.type || '');\n const typeB = String(b?.type || '');\n if (typeA !== typeB) return typeA.localeCompare(typeB);\n\n const refA = String(a?.reference || '');\n const refB = String(b?.reference || '');\n if (refA !== refB) return refA.localeCompare(refB);\n\n const specA = String(a?.resolvedSpec || '');\n const specB = String(b?.resolvedSpec || '');\n return specA.localeCompare(specB);\n}\n\nfunction formatFindingLine(finding) {\n const ref = finding?.reference ? ` (${finding.reference})` : '';\n const spec = finding?.resolvedSpec ? ` [${finding.resolvedSpec}]` : '';\n return `- ${finding.type}: ${finding.file}:${finding.line}${ref}${spec}`;\n}\n\nfunction buildTopFindings(findings, limit = 30) {\n const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 30;\n const sorted = Array.isArray(findings)\n ? findings.slice().sort(compareFindings)\n : [];\n const lines = sorted.slice(0, safeLimit).map(formatFindingLine);\n return lines.length > 0 ? lines.join('\\n') : '- none';\n}\n\nfunction findMarkerIssue(items, marker = ROLLING_ISSUE_MARKER) {\n if (!Array.isArray(items) || items.length === 0) return null;\n\n const matches = items.filter((item) => String(item?.body || '').includes(marker));\n if (matches.length === 0) return null;\n\n matches.sort((a, b) => {\n const aOpen = a?.state === 'open' ? 1 : 0;\n const bOpen = b?.state === 'open' ? 1 : 0;\n if (aOpen !== bOpen) return bOpen - aOpen;\n return Number(b?.number || 0) - Number(a?.number || 0);\n });\n\n return matches[0] || null;\n}\n\nfunction buildIssueBody({\n runUrl,\n topFindings,\n totalFailures,\n totalFiles,\n totalReferences,\n marker = ROLLING_ISSUE_MARKER\n}) {\n return [\n marker,\n '',\n '### Area',\n 'area: ci-cd',\n '',\n '### Failing command or workflow',\n '.github/workflows/openapi-reference-validation.yml',\n '',\n '### Script or workflow path',\n 'tests/integration/openapi-reference-audit.js and .github/workflows/openapi-reference-validation.yml',\n '',\n '### Full error output',\n '```text',\n topFindings || '- none',\n '```',\n '',\n '### Reproduction conditions',\n [\n '- Triggered by CI OpenAPI Reference Validation workflow.',\n '- Scope: v2 + locales (`v2/es`, `v2/fr`, `v2/cn`).',\n `- Workflow run: ${runUrl}`\n ].join('\\n'),\n '',\n '### Expected behavior',\n 'All OpenAPI endpoint references should resolve to the canonical mapped spec and pass strict validation.',\n '',\n '### Action requested from maintainers',\n 'Review reported references, apply required content corrections, and re-run the OpenAPI reference audit workflow.',\n '',\n '### Classification',\n 'classification: high',\n '',\n '### Priority',\n 'priority: high',\n '',\n '### Additional context',\n [\n `- Total failures: ${totalFailures}`,\n `- Files analyzed: ${totalFiles}`,\n `- References analyzed: ${totalReferences}`\n ].join('\\n')\n ].join('\\n');\n}\n\nfunction buildResolutionComment(runUrl) {\n return [\n 'OpenAPI reference validation is passing again.',\n '',\n `Resolved in run: ${runUrl}`\n ].join('\\n');\n}\n\nfunction getIssueAction({ existingIssue, totalFailures }) {\n const failures = Number(totalFailures || 0);\n const hasExisting = Boolean(existingIssue);\n const existingOpen = hasExisting && existingIssue.state === 'open';\n\n if (failures === 0) {\n return existingOpen ? 'close' : 'noop';\n }\n\n return hasExisting ? 'update' : 'create';\n}\n\nmodule.exports = {\n ROLLING_ISSUE_MARKER,\n ROLLING_ISSUE_TITLE,\n ROLLING_ISSUE_LABELS,\n buildTopFindings,\n findMarkerIssue,\n buildIssueBody,\n buildResolutionComment,\n getIssueAction\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/openapi-rolling-issue.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/openapi-rolling-issue.test.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": ".githooks/server-manager.js",
+ "script": "server-manager",
+ "category": "utility",
+ "purpose": "tooling:dev-tools",
+ "scope": ".githooks",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "Manages Mintlify dev server lifecycle for browser tests (start/stop/health-check)",
+ "pipeline_declared": "indirect — legacy browser-validation module imported by .githooks/verify-browser.js",
+ "usage": "node .githooks/server-manager.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script server-manager\n * @category utility\n * @purpose tooling:dev-tools\n * @scope .githooks\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement Manages Mintlify dev server lifecycle for browser tests (start/stop/health-check)\n * @pipeline indirect — legacy browser-validation module imported by .githooks/verify-browser.js\n * @usage node .githooks/server-manager.js [flags]\n */\n/**\n * Server management utility for browser tests\n * Automatically starts mint dev if not running and manages the process lifecycle\n */\n\nconst { spawn, execSync } = require('child_process');\nconst http = require('http');\nconst fs = require('fs');\nconst path = require('path');\nconst os = require('os');\n\n// Use a dedicated port for browser validation tests (unlikely to be in use)\nconst TEST_PORT = 3145;\nconst BASE_URL = process.env.MINT_BASE_URL || `http://localhost:${TEST_PORT}`;\nconst PORT = new URL(BASE_URL).port || TEST_PORT;\nconst PID_FILE = path.join(os.tmpdir(), 'mint-dev-test.pid');\nconst LOG_FILE = path.join(os.tmpdir(), 'mint-dev-test.log');\n\nlet serverProcess = null;\nlet serverStartedByUs = false;\nlet actualServerUrl = BASE_URL; // Will be updated if port is detected from log\nlet detectedServerPort = null; // Port where server was actually found\n\n/**\n * Check if server is already running (on expected port, detected port, or common ports)\n */\nasync function isServerRunning(options = {}) {\n const { probePath, allowCommonPorts = true } = options;\n // Check expected port first (3145)\n if (await isServerRunningOnPort(PORT, probePath)) {\n return true;\n }\n \n // Check common mint dev ports (3000, 3001, 3002, etc.)\n // Mint dev often uses these ports if 3000 is in use\n if (allowCommonPorts) {\n for (let commonPort = 3000; commonPort <= 3010; commonPort++) {\n if (await isServerRunningOnPort(commonPort, probePath)) {\n // Found server on common port - store it for getServerUrl()\n detectedServerPort = commonPort;\n console.log(` Found existing server on port ${commonPort}, using it`);\n return true;\n }\n }\n }\n \n // Check if log shows server on different port\n if (allowCommonPorts) {\n const detectedPort = detectPortFromLog();\n if (detectedPort && detectedPort !== PORT) {\n return await isServerRunningOnPort(detectedPort, probePath);\n }\n }\n \n return false;\n}\n\n/**\n * Parse log file to detect actual port mint dev is using\n * Looks for patterns like \"local → http://localhost:3001\" or \"port 3000 is already in use. trying 3001 instead\"\n */\nfunction detectPortFromLog() {\n if (!fs.existsSync(LOG_FILE)) {\n return null;\n }\n \n try {\n const logContent = fs.readFileSync(LOG_FILE, 'utf8');\n \n const lastMatch = (regex) => {\n const matches = [...logContent.matchAll(regex)];\n if (!matches.length) return null;\n const last = matches[matches.length - 1];\n return last && last[1] ? parseInt(last[1], 10) : null;\n };\n \n // Pattern 1: \"local → http://localhost:XXXX\"\n const localPort = lastMatch(/local\\s*→\\s*http:\\/\\/localhost:(\\d+)/gi);\n if (localPort) {\n return localPort;\n }\n \n // Pattern 2: \"port XXXX is already in use. trying YYYY instead\"\n const portPort = lastMatch(/port\\s+\\d+\\s+is\\s+already\\s+in\\s+use\\.\\s+trying\\s+(\\d+)\\s+instead/gi);\n if (portPort) {\n return portPort;\n }\n \n // Pattern 3: \"preview ready\" followed by port info\n const previewPort = lastMatch(/preview\\s+ready[^\\n]*localhost:(\\d+)/gi);\n if (previewPort) {\n return previewPort;\n }\n } catch (e) {\n // Ignore errors reading log\n }\n \n return null;\n}\n\n/**\n * Check if server is running on a specific port\n */\nfunction normalizeProbePath(probePath) {\n if (!probePath) {\n return '';\n }\n return probePath.startsWith('/') ? probePath : `/${probePath}`;\n}\n\nasync function isServerRunningOnPort(port, probePath) {\n const pathSuffix = normalizeProbePath(probePath);\n const url = `http://localhost:${port}${pathSuffix}`;\n return new Promise((resolve) => {\n const req = http.get(url, { timeout: 2000 }, (res) => {\n if (!Number.isInteger(res.statusCode)) {\n resolve(false);\n return;\n }\n if (pathSuffix) {\n // Treat 404 on probe paths as a mismatch (not the expected server).\n resolve(res.statusCode !== 404);\n return;\n }\n // Any HTTP response means the server is up (Mint may return redirects during startup).\n resolve(res.statusCode > 0);\n });\n \n req.on('error', () => resolve(false));\n req.on('timeout', () => {\n req.destroy();\n resolve(false);\n });\n });\n}\n\n/**\n * Wait for server to be ready, checking expected port, common ports, and detected port from log\n */\nasync function waitForServer(maxAttempts = 60, interval = 2000, options = {}) {\n const { probePath, allowCommonPorts = true } = options;\n for (let i = 0; i < maxAttempts; i++) {\n // First check expected port (3145)\n if (await isServerRunningOnPort(PORT, probePath)) {\n return true;\n }\n \n // Check common ports (3000-3010) - mint dev often uses these if 3145 is unavailable\n if (allowCommonPorts) {\n for (let commonPort = 3000; commonPort <= 3010; commonPort++) {\n if (await isServerRunningOnPort(commonPort, probePath)) {\n detectedServerPort = commonPort;\n console.log(` Server started on port ${commonPort} (expected ${PORT})`);\n return true;\n }\n }\n }\n \n // If not on expected or common ports, try to detect from log (after a few attempts to let log populate)\n if (allowCommonPorts && i >= 3) {\n const detectedPort = detectPortFromLog();\n if (detectedPort && detectedPort !== PORT) {\n // Check detected port\n if (await isServerRunningOnPort(detectedPort, probePath)) {\n detectedServerPort = detectedPort;\n console.log(` Server detected on port ${detectedPort} from log (expected ${PORT})`);\n return true;\n }\n }\n }\n \n if (i < maxAttempts - 1) {\n await new Promise(resolve => setTimeout(resolve, interval));\n }\n }\n return false;\n}\n\n/**\n * Start mint dev server\n */\nfunction startServer() {\n // Check if already running from a previous test\n if (fs.existsSync(PID_FILE)) {\n try {\n const existingPid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim());\n // Check if process is still running\n try {\n process.kill(existingPid, 0); // Signal 0 just checks if process exists\n console.log(`⚠️ Found existing mint dev process (PID: ${existingPid}), reusing...`);\n serverStartedByUs = false;\n return existingPid;\n } catch (e) {\n // Process doesn't exist, remove stale PID file\n fs.unlinkSync(PID_FILE);\n }\n } catch (e) {\n // Ignore errors reading PID file\n }\n }\n\n console.log(`🚀 Starting mint dev server on port ${PORT}...`);\n \n // Start mint dev in background with specific port via environment variable\n // Use 'pipe' instead of WriteStream directly to avoid stdio issues\n serverProcess = spawn('mint', ['dev', '--port', PORT.toString(), '--no-open'], {\n stdio: ['ignore', 'pipe', 'pipe'],\n detached: true,",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": ".githooks/verify-browser.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/browser.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/mdx-component-runtime-smoke.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/v2-wcag-audit.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": ".githooks/mint-dev-test.log",
+ "type": "generated-output",
+ "call": "createWriteStream"
+ },
+ {
+ "output_path": ".githooks/mint-dev-test.pid",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": ".githooks/mint-dev-test.log, .githooks/mint-dev-test.pid",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via .githooks/verify-browser.js; indirect via tests/integration/browser.test.js; indirect via tests/integration/mdx-component-runtime-smoke.js; indirect via tests/integration/v2-wcag-audit.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tests/utils/file-walker.js",
+ "script": "file-walker",
+ "category": "utility",
+ "purpose": "tooling:dev-tools",
+ "scope": "tests",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "File tree walker — recursively finds files matching patterns. Used by pre-commit hook and validators.",
+ "pipeline_declared": "indirect — library module",
+ "usage": "node tests/utils/file-walker.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script file-walker\n * @category utility\n * @purpose tooling:dev-tools\n * @scope tests\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement File tree walker — recursively finds files matching patterns. Used by pre-commit hook and validators.\n * @pipeline indirect — library module\n * @dualmode dual-mode (document flags)\n * @usage node tests/utils/file-walker.js [flags]\n */\n/**\n * File traversal utilities for testing\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\nconst { filterPathsByMintIgnore } = require('./mintignore');\n\nfunction toPosix(filePath) {\n return String(filePath || '').split(path.sep).join('/');\n}\n\nfunction getRepoRoot(rootDir = process.cwd()) {\n try {\n return execSync('git rev-parse --show-toplevel', {\n encoding: 'utf8',\n cwd: rootDir\n }).trim();\n } catch (_error) {\n return rootDir;\n }\n}\n\nfunction resolveRepoRoot(rootDir = null) {\n return getRepoRoot(rootDir || process.cwd());\n}\n\nfunction normalizeDocsRouteKey(routePath) {\n let normalized = toPosix(routePath).trim();\n normalized = normalized.replace(/^\\/+/, '');\n normalized = normalized.replace(/\\.(md|mdx)$/i, '');\n normalized = normalized.replace(/\\/index$/i, '');\n normalized = normalized.replace(/\\/+$/, '');\n return normalized;\n}\n\nfunction isExcludedV2ExperimentalPath(relPath) {\n const rel = toPosix(relPath).replace(/^\\/+/, '');\n if (!rel.startsWith('v2/')) return false;\n return rel\n .split('/')\n .some((segment) => segment.toLowerCase().startsWith('x-'));\n}\n\nfunction collectDocsPageEntries(node, out = []) {\n if (typeof node === 'string') {\n const value = node.trim();\n const normalizedValue = value.replace(/^\\/+/, '');\n if (normalizedValue.startsWith('v1/')) {\n out.push(normalizedValue);\n } else if (\n normalizedValue.startsWith('v2/') &&\n !isExcludedV2ExperimentalPath(normalizedValue)\n ) {\n out.push(normalizedValue);\n }\n return out;\n }\n\n if (Array.isArray(node)) {\n node.forEach((item) => collectDocsPageEntries(item, out));\n return out;\n }\n\n if (!node || typeof node !== 'object') {\n return out;\n }\n\n if (Array.isArray(node.pages)) {\n node.pages.forEach((item) => collectDocsPageEntries(item, out));\n }\n\n Object.values(node).forEach((value) => collectDocsPageEntries(value, out));\n return out;\n}\n\nfunction getDocsJsonRouteKeys(rootDir = null) {\n const repoRoot = resolveRepoRoot(rootDir);\n const docsJsonPath = path.join(repoRoot, 'docs.json');\n if (!fs.existsSync(docsJsonPath)) {\n return new Set();\n }\n\n const docsJson = JSON.parse(fs.readFileSync(docsJsonPath, 'utf8'));\n const versions = docsJson?.navigation?.versions || [];\n const entries = [];\n\n versions.forEach((versionNode) => {\n if (versionNode?.languages) {\n collectDocsPageEntries(versionNode.languages, entries);\n }\n });\n\n const keys = new Set();\n entries.forEach((entry) => {\n const key = normalizeDocsRouteKey(entry);\n if (key) {\n keys.add(key);\n }\n });\n return keys;\n}\n\nfunction toDocsRouteKeyFromFile(filePath, rootDir = null) {\n const repoRoot = resolveRepoRoot(rootDir);\n const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(repoRoot, filePath);\n const relPath = toPosix(path.relative(repoRoot, absPath));\n if (!(relPath.startsWith('v1/') || relPath.startsWith('v2/'))) {\n return '';\n }\n if (relPath.startsWith('v2/') && isExcludedV2ExperimentalPath(relPath)) {\n return '';\n }\n return normalizeDocsRouteKey(relPath);\n}\n\nfunction toDocsRouteKeyFromFileV2Aware(filePath, rootDir = null) {\n const repoRoot = resolveRepoRoot(rootDir);\n const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(repoRoot, filePath);\n const relPath = toPosix(path.relative(repoRoot, absPath));\n if (!(relPath.startsWith('v1/') || relPath.startsWith('v2/'))) {\n return '';\n }\n if (relPath.startsWith('v2/') && isExcludedV2ExperimentalPath(relPath)) {\n return '';\n }\n return normalizeDocsRouteKey(relPath);\n}\n\nfunction collectFiles(dir, pattern, fileList = []) {\n const files = fs.readdirSync(dir);\n\n files.forEach((file) => {\n const filePath = path.join(dir, file);\n const stat = fs.statSync(filePath);\n\n if (stat.isDirectory()) {\n // Skip node_modules and .git\n if (!file.startsWith('.') && file !== 'node_modules') {\n collectFiles(filePath, pattern, fileList);\n }\n } else if (pattern.test(file)) {\n fileList.push(filePath);\n }\n });\n\n return fileList;\n}\n\n/**\n * Recursively get all files matching a pattern\n */\nfunction getFiles(dir, pattern, options = {}) {\n const { rootDir = null, respectMintIgnore = true } = options;\n const repoRoot = resolveRepoRoot(rootDir || dir);\n const files = collectFiles(dir, pattern, []);\n return filterPathsByMintIgnore(files, { rootDir: repoRoot, respectMintIgnore });\n}\n\n/**\n * Get all routable MDX files in v2\n */\nfunction getMdxFiles(rootDir = null, options = {}) {\n const { respectMintIgnore = true } = options;\n const repoRoot = resolveRepoRoot(rootDir);\n const docsRouteKeys = getDocsJsonRouteKeys(repoRoot);\n const v2DocsFiles = getV2DocsFiles({ rootDir: repoRoot, respectMintIgnore });\n const mdxFiles = v2DocsFiles.filter((filePath) => filePath.endsWith('.mdx'));\n\n if (docsRouteKeys.size === 0) {\n return mdxFiles;\n }\n\n return mdxFiles.filter((filePath) => {\n const key = toDocsRouteKeyFromFileV2Aware(filePath, repoRoot);\n return key && docsRouteKeys.has(key);\n });\n}\n\n/**\n * Get all JSX files in snippets/components\n */\nfunction getJsxFiles(rootDir = null, options = {}) {\n const { respectMintIgnore = true } = options;\n const repoRoot = resolveRepoRoot(rootDir);\n const componentsDir = path.join(repoRoot, 'snippets', 'components');\n if (!fs.existsSync(componentsDir)) {\n return [];\n }\n return getFiles(componentsDir, /\\.jsx$/, { rootDir: repoRoot, respectMintIgnore });\n}\n\n/**\n * Get staged files from git\n * Returns absolute paths relative to repo root (not cwd)\n */\nfunction getStagedFiles(rootDir = null) {\n try {\n // Get repo root directory (where .git is)\n const repoRoot = resolveRepoRoot(rootDir);\n \n const output = execSync('git diff --cached --name-only --diff-filter=ACMR', {\n encoding: 'utf8',\n cwd: repoRoot\n });\n return output",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": ".githooks/verify-browser.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/browser.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/domain-pages-audit.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/v2-link-audit.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/integration/v2-wcag-audit.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/run-pr-checks.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/links-imports.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/mdx.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/quality.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/spelling.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/style-guide.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/v2-wcag-audit.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/assign-purpose-metadata.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/audit-v2-usefulness.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/remediators/content/repair-spelling.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/components/check-mdx-component-scope.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/content/check-double-headers.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/content/check-proper-nouns.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via .githooks/verify-browser.js; indirect via tests/integration/browser.test.js; indirect via tests/integration/domain-pages-audit.js; indirect via tests/integration/v2-link-audit.js; indirect via tests/integration/v2-wcag-audit.js; indirect via tests/run-pr-checks.js; indirect via tests/unit/links-imports.test.js; indirect via tests/unit/mdx.test.js; indirect via tests/unit/quality.test.js; indirect via tests/unit/spelling.test.js; indirect via tests/unit/style-guide.test.js; indirect via tests/unit/v2-wcag-audit.test.js; indirect via tools/scripts/assign-purpose-metadata.js; indirect via tools/scripts/audit-v2-usefulness.js; indirect via tools/scripts/remediators/content/repair-spelling.js; indirect via tools/scripts/validators/components/check-mdx-component-scope.js; indirect via tools/scripts/validators/content/check-double-headers.js; indirect via tools/scripts/validators/content/check-proper-nouns.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tests/utils/mdx-parser.js",
+ "script": "mdx-parser",
+ "category": "validator",
+ "purpose": "tooling:dev-tools",
+ "scope": "tests",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "MDX parser utility — extracts frontmatter, components, content blocks from MDX files",
+ "pipeline_declared": "indirect — library module",
+ "usage": "node tests/utils/mdx-parser.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script mdx-parser\n * @category validator\n * @purpose tooling:dev-tools\n * @scope tests\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement MDX parser utility — extracts frontmatter, components, content blocks from MDX files\n * @pipeline indirect — library module\n * @usage node tests/utils/mdx-parser.js [flags]\n */\n/**\n * MDX parsing utilities for validation\n */\n\nconst path = require('path');\n\nlet yaml;\ntry {\n yaml = require('js-yaml');\n} catch (_error) {\n yaml = require(path.join(process.cwd(), 'tools', 'node_modules', 'js-yaml'));\n}\n\nfunction getIgnoredRanges(content) {\n const ignoredRanges = [];\n const ignoreRegexes = [\n /```[\\s\\S]*?```/g,\n /~~~[\\s\\S]*?~~~/g,\n /\\{\\/\\*[\\s\\S]*?\\*\\/\\}/g,\n //g\n ];\n\n ignoreRegexes.forEach((regex) => {\n let match;\n\n while ((match = regex.exec(content)) !== null) {\n ignoredRanges.push({\n start: match.index,\n end: match.index + match[0].length\n });\n }\n });\n\n return ignoredRanges;\n}\n\nfunction isIgnoredIndex(index, ignoredRanges) {\n return ignoredRanges.some((range) => index >= range.start && index < range.end);\n}\n\n/**\n * Extract frontmatter from MDX file\n */\nfunction extractFrontmatter(content) {\n const frontmatterRegex = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n/;\n const match = content.match(frontmatterRegex);\n \n if (!match) {\n return { exists: false, data: null, raw: null };\n }\n \n try {\n const data = yaml.load(match[1]);\n return { exists: true, data, raw: match[1] };\n } catch (error) {\n return { exists: true, data: null, raw: match[1], error: error.message };\n }\n}\n\n/**\n * Extract imports from MDX file\n */\nfunction extractImports(content) {\n const importRegex = /^import\\s+(?:(?:\\{[^}]*\\}|\\*\\s+as\\s+\\w+|\\w+)(?:\\s*,\\s*(?:\\{[^}]*\\}|\\*\\s+as\\s+\\w+|\\w+))*\\s+from\\s+)?['\"]([^'\"]+)['\"];?/gm;\n const imports = [];\n const ignoredRanges = getIgnoredRanges(content);\n let match;\n \n while ((match = importRegex.exec(content)) !== null) {\n if (isIgnoredIndex(match.index, ignoredRanges)) {\n continue;\n }\n\n imports.push({\n full: match[0],\n path: match[1],\n line: content.substring(0, match.index).split('\\n').length\n });\n }\n \n return imports;\n}\n\n/**\n * Check for unclosed JSX tags\n */\nfunction checkUnclosedTags(content) {\n const errors = [];\n const tagStack = [];\n const ignoreRanges = [];\n const ignoreRegexes = [\n /```[\\s\\S]*?```/g, // markdown code blocks\n /`[^`\\n]*`/g, // inline code spans\n /\\{\\/\\*[\\s\\S]*?\\*\\/\\}/g, // JSX comments\n //g // HTML comments\n ];\n\n ignoreRegexes.forEach((regex) => {\n let match;\n while ((match = regex.exec(content)) !== null) {\n ignoreRanges.push({\n start: match.index,\n end: match.index + match[0].length\n });\n }\n });\n\n function isInIgnoredRange(pos) {\n return ignoreRanges.some((range) => pos >= range.start && pos < range.end);\n }\n\n function getLineNumber(pos) {\n return content.slice(0, pos).split('\\n').length;\n }\n\n function findTagEnd(startIndex) {\n let quote = null;\n let braceDepth = 0;\n\n for (let i = startIndex + 1; i < content.length; i++) {\n const ch = content[i];\n const prev = content[i - 1];\n\n // Inside JSX expression braces, only track nested braces.\n // This avoids treating apostrophes in JSX text (e.g. Livepeer's)\n // as string delimiters, which can hide the real closing '>'.\n if (braceDepth > 0) {\n if (ch === '{') {\n braceDepth += 1;\n continue;\n }\n\n if (ch === '}') {\n braceDepth -= 1;\n continue;\n }\n\n continue;\n }\n\n if (quote) {\n if (ch === quote && prev !== '\\\\') {\n quote = null;\n }\n continue;\n }\n\n if (ch === '\"' || ch === '\\'' || ch === '`') {\n quote = ch;\n continue;\n }\n\n if (ch === '{') {\n braceDepth += 1;\n continue;\n }\n\n if (ch === '>' && braceDepth === 0) {\n return i;\n }\n }\n\n return -1;\n }\n\n for (let cursor = 0; cursor < content.length; ) {\n const tagStart = content.indexOf('<', cursor);\n if (tagStart === -1) {\n break;\n }\n\n if (isInIgnoredRange(tagStart)) {\n cursor = tagStart + 1;\n continue;\n }\n\n let nameStart = tagStart + 1;\n let isClosing = false;\n\n if (content[nameStart] === '/') {\n isClosing = true;\n nameStart += 1;\n }\n\n if (!/[A-Z]/.test(content[nameStart] || '')) {\n cursor = tagStart + 1;\n continue;\n }\n\n let nameEnd = nameStart + 1;\n while (/[A-Za-z0-9]/.test(content[nameEnd] || '')) {\n nameEnd += 1;\n }\n\n const tagName = content.slice(nameStart, nameEnd);\n const lineNumber = getLineNumber(tagStart);\n const tagEnd = findTagEnd(tagStart);\n\n if (tagEnd === -1) {\n errors.push({\n line: lineNumber,\n message: `Unclosed tag <${tagName}>`,\n tag: tagName\n });\n break;\n }\n\n const fullTag = content.slice(tagStart, tagEnd + 1);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/integration/v2-link-audit.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/links-imports.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/mdx.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/unit/quality.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/lib/docs-usefulness/scoring.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/scripts/validators/components/check-mdx-component-scope.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/integration/v2-link-audit.js; indirect via tests/unit/links-imports.test.js; indirect via tests/unit/mdx.test.js; indirect via tests/unit/quality.test.js; indirect via tools/lib/docs-usefulness/scoring.js; indirect via tools/scripts/validators/components/check-mdx-component-scope.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tests/utils/mintignore.js",
+ "script": "mintignore",
+ "category": "validator",
+ "purpose": "tooling:dev-tools",
+ "scope": "tests",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "Mintignore utility — reads .mintignore patterns and filters file lists",
+ "pipeline_declared": "indirect — library module",
+ "usage": "node tests/utils/mintignore.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script mintignore\n * @category validator\n * @purpose tooling:dev-tools\n * @scope tests\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement Mintignore utility — reads .mintignore patterns and filters file lists\n * @pipeline indirect — library module\n * @usage node tests/utils/mintignore.js [flags]\n */\n\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { execFileSync } = require('child_process');\n\nconst tempRepoCache = new Map();\nconst trackedTempRepos = new Set();\nconst GIT_ENV_STRIP_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX'];\n\nfunction getSanitizedGitEnv(overrides = {}) {\n const env = { ...process.env, ...overrides };\n GIT_ENV_STRIP_KEYS.forEach((key) => {\n delete env[key];\n });\n return env;\n}\n\nfunction toPosix(filePath) {\n return String(filePath || '').split(path.sep).join('/');\n}\n\nfunction getRepoRoot(rootDir = process.cwd()) {\n try {\n return execFileSync('git', ['rev-parse', '--show-toplevel'], {\n cwd: rootDir,\n encoding: 'utf8',\n env: getSanitizedGitEnv()\n }).trim();\n } catch (_error) {\n return rootDir;\n }\n}\n\nfunction normalizeRepoRelativePath(filePath, repoRoot) {\n if (!filePath) return '';\n const raw = String(filePath).trim();\n if (!raw) return '';\n\n const absolutePath = path.isAbsolute(raw)\n ? path.resolve(raw)\n : path.resolve(repoRoot, raw);\n\n let rel = toPosix(path.relative(repoRoot, absolutePath));\n if (!rel) return '';\n rel = rel.replace(/^\\.\\//, '');\n rel = rel.replace(/^\\/+/, '');\n return rel;\n}\n\nfunction getMintIgnorePath(rootDir = null) {\n const repoRoot = getRepoRoot(rootDir || process.cwd());\n const mintIgnorePath = path.join(repoRoot, '.mintignore');\n return fs.existsSync(mintIgnorePath) ? mintIgnorePath : '';\n}\n\nfunction ensureTempGitRepo(repoRoot) {\n const cached = tempRepoCache.get(repoRoot);\n if (cached && fs.existsSync(cached)) {\n return cached;\n }\n\n const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mintignore-check-'));\n execFileSync('git', ['init', '-q'], { cwd: tempDir, env: getSanitizedGitEnv() });\n tempRepoCache.set(repoRoot, tempDir);\n trackedTempRepos.add(tempDir);\n return tempDir;\n}\n\nfunction parseCheckIgnoreOutput(output, mintIgnorePath) {\n const ignored = new Set();\n if (!output) return ignored;\n\n const mintIgnoreAbs = path.resolve(mintIgnorePath);\n const lines = output.split('\\n').filter(Boolean);\n\n lines.forEach((line) => {\n const tabIndex = line.indexOf('\\t');\n if (tabIndex < 0) return;\n\n const meta = line.slice(0, tabIndex);\n const relPath = toPosix(line.slice(tabIndex + 1).trim())\n .replace(/^\\.\\//, '')\n .replace(/^\\/+/, '');\n\n if (!relPath || meta === '::') return;\n\n const sourceMatch = meta.match(/^(.*):(\\d+):([^\\t]*)$/);\n if (!sourceMatch) return;\n\n const sourceFile = path.resolve(sourceMatch[1]);\n const pattern = String(sourceMatch[3] || '').trim();\n\n if (sourceFile === mintIgnoreAbs && !pattern.startsWith('!')) {\n ignored.add(relPath);\n } else {\n ignored.delete(relPath);\n }\n });\n\n return ignored;\n}\n\nfunction listMintIgnoredRepoPaths(paths, options = {}) {\n const { rootDir = null } = options;\n const repoRoot = getRepoRoot(rootDir || process.cwd());\n const mintIgnorePath = getMintIgnorePath(repoRoot);\n if (!mintIgnorePath) return new Set();\n\n const uniqueRelPaths = [...new Set(\n (paths || [])\n .map((entry) => normalizeRepoRelativePath(entry, repoRoot))\n .filter(Boolean)\n )];\n\n if (!uniqueRelPaths.length) {\n return new Set();\n }\n\n try {\n const checkerRepo = ensureTempGitRepo(repoRoot);\n const output = execFileSync(\n 'git',\n [\n '-c',\n `core.excludesfile=${mintIgnorePath}`,\n 'check-ignore',\n '--verbose',\n '--non-matching',\n '--no-index',\n '--stdin'\n ],\n {\n cwd: checkerRepo,\n encoding: 'utf8',\n input: `${uniqueRelPaths.join('\\n')}\\n`,\n maxBuffer: 64 * 1024 * 1024,\n env: getSanitizedGitEnv()\n }\n );\n\n return parseCheckIgnoreOutput(output, mintIgnorePath);\n } catch (_error) {\n return new Set();\n }\n}\n\nfunction filterPathsByMintIgnore(paths, options = {}) {\n const { rootDir = null, respectMintIgnore = true } = options;\n if (!respectMintIgnore) {\n return [...(paths || [])];\n }\n\n const repoRoot = getRepoRoot(rootDir || process.cwd());\n const rows = (paths || []).map((entry) => ({\n original: entry,\n rel: normalizeRepoRelativePath(entry, repoRoot)\n }));\n\n const ignored = listMintIgnoredRepoPaths(rows.map((row) => row.rel), {\n rootDir: repoRoot\n });\n\n return rows\n .filter((row) => !row.rel || !ignored.has(row.rel))\n .map((row) => row.original);\n}\n\nprocess.on('exit', () => {\n trackedTempRepos.forEach((tempDir) => {\n try {\n fs.rmSync(tempDir, { recursive: true, force: true });\n } catch (_error) {\n // Best-effort cleanup only.\n }\n });\n});\n\nmodule.exports = {\n toPosix,\n getRepoRoot,\n normalizeRepoRelativePath,\n getMintIgnorePath,\n listMintIgnoredRepoPaths,\n filterPathsByMintIgnore\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/docs-navigation.test.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tests/utils/file-walker.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/docs-navigation.test.js; indirect via tests/utils/file-walker.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/config/v2-internal-report-pages.js",
+ "script": "v2-internal-report-pages",
+ "category": "config",
+ "purpose": "tooling:dev-tools",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "Configuration data — list of internal report page paths for publish-v2-internal-reports.js",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/config/v2-internal-report-pages.js [flags]",
+ "header": "/**\n * @script v2-internal-report-pages\n * @category config\n * @purpose tooling:dev-tools\n * @scope full-repo\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement Configuration data — list of internal report page paths for publish-v2-internal-reports.js\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/config/v2-internal-report-pages.js [flags]\n */\nmodule.exports = {\n categories: [\n {\n slug: 'navigation-links',\n groupTitle: 'Navigation & Links',\n },\n {\n slug: 'quality-accessibility',\n groupTitle: 'Quality & Accessibility',\n },\n {\n slug: 'page-audits',\n groupTitle: 'Page Audits',\n },\n {\n slug: 'repo-ops',\n groupTitle: 'Repo Ops',\n },\n ],\n docsGroups: [\n {\n slug: 'navigation-links',\n groupTitle: 'Navigation & Links',\n },\n {\n slug: 'quality-accessibility',\n groupTitle: 'Quality & Accessibility',\n },\n {\n slug: 'page-audits',\n groupTitle: 'Page Audits',\n },\n {\n slug: 'repo-ops',\n groupTitle: 'Repo Ops',\n },\n {\n slug: 'tests',\n groupTitle: 'Tests',\n },\n ],\n entries: [\n {\n publish: true,\n categorySlug: 'navigation-links',\n docsGroupSlugs: ['navigation-links', 'tests'],\n scriptId: 'docs-navigation.test',\n scriptPath: 'tests/unit/docs-navigation.test.js',\n title: 'Docs Navigation Route Report',\n sidebarTitle: 'Docs Navigation',\n description:\n 'Generated docs.json route validation report from tests/unit/docs-navigation.test.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/navigation-links/navigation-report.md',\n targetSlug: 'docs-navigation',\n },\n {\n publish: true,\n categorySlug: 'navigation-links',\n docsGroupSlugs: ['navigation-links', 'tests'],\n scriptId: 'v2-link-audit',\n scriptPath: 'tests/integration/v2-link-audit.js',\n title: 'V2 Link Audit Report',\n sidebarTitle: 'Link Audit',\n description:\n 'Generated V2 MDX link audit report from tests/integration/v2-link-audit.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/navigation-links/LINK_TEST_REPORT.md',\n targetSlug: 'v2-link-audit',\n },\n {\n publish: true,\n categorySlug: 'quality-accessibility',\n docsGroupSlugs: ['quality-accessibility', 'tests'],\n scriptId: 'v2-wcag-audit',\n scriptPath: 'tests/integration/v2-wcag-audit.js',\n title: 'V2 WCAG Audit Report',\n sidebarTitle: 'WCAG Audit',\n description:\n 'Generated WCAG audit report from tests/integration/v2-wcag-audit.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/quality-accessibility/v2-wcag-audit-report.md',\n targetSlug: 'v2-wcag-audit',\n },\n {\n publish: true,\n categorySlug: 'quality-accessibility',\n scriptId: 'wcag-repair-common',\n scriptPath: 'tools/scripts/wcag-repair-common.js',\n title: 'WCAG Repair Common Report',\n sidebarTitle: 'WCAG Repair',\n description:\n 'Generated WCAG repair report from tools/scripts/wcag-repair-common.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/quality-accessibility/v2-wcag-repair-common-report.md',\n targetSlug: 'wcag-repair-common',\n },\n {\n publish: true,\n categorySlug: 'quality-accessibility',\n scriptId: 'audit-v2-usefulness',\n scriptPath: 'tools/scripts/audit-v2-usefulness.js',\n title: 'V2 Usefulness Audit Summary',\n sidebarTitle: 'Usefulness Audit',\n description:\n 'Generated usefulness audit summary from tools/scripts/audit-v2-usefulness.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/quality-accessibility/docs-usefulness/latest/summary.md',\n sourceFallbackGlobs: [\n 'tasks/reports/quality-accessibility/docs-usefulness/*/summary.md',\n ],\n targetSlug: 'audit-v2-usefulness',\n },\n {\n publish: true,\n categorySlug: 'page-audits',\n scriptId: 'test-all-pages-comprehensive',\n scriptPath: 'tools/scripts/archive/legacy/test-all-pages-comprehensive.js',\n title: 'All Pages Comprehensive Browser Report',\n sidebarTitle: 'Browser Report',\n description:\n 'Generated browser report from tools/scripts/archive/legacy/test-all-pages-comprehensive.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/page-audits/browser-test-report.md',\n targetSlug: 'test-all-pages-comprehensive',\n },\n {\n publish: true,\n categorySlug: 'page-audits',\n scriptId: 'audit-all-pages',\n scriptPath: 'tools/scripts/archive/legacy/audit-all-pages.js',\n title: 'All Pages Audit (Legacy Browser Script)',\n sidebarTitle: 'Audit All Pages',\n description:\n 'Generated audit report from tools/scripts/archive/legacy/audit-all-pages.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/page-audits/page-audit-latest.md',\n targetSlug: 'audit-all-pages',\n },\n {\n publish: true,\n categorySlug: 'page-audits',\n scriptId: 'audit-all-pages-simple',\n scriptPath: 'tools/scripts/archive/legacy/audit-all-pages-simple.js',\n title: 'All Pages Audit Simple (File Checks)',\n sidebarTitle: 'Audit Simple',\n description:\n 'Generated file-check audit report from tools/scripts/archive/legacy/audit-all-pages-simple.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/page-audits/page-audit-simple-latest.md',\n targetSlug: 'audit-all-pages-simple',\n },\n {\n publish: true,\n categorySlug: 'page-audits',\n scriptId: 'audit-python',\n scriptPath: 'tasks/scripts/audit-python.py',\n title: 'All Pages Audit (Python)',\n sidebarTitle: 'Audit Python',\n description:\n 'Generated Python audit report from tasks/scripts/audit-python.py.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/page-audits/page-audit-python-latest.md',\n targetSlug: 'audit-python',\n },\n {\n publish: true,\n categorySlug: 'page-audits',\n docsGroupSlugs: ['page-audits', 'tests'],\n scriptId: 'domain-pages-audit',\n scriptPath: 'tests/integration/domain-pages-audit.js',\n title: 'Domain Page Load Audit Report',\n sidebarTitle: 'Domain Pages',\n description:\n 'Generated deployed page load audit report from tests/integration/domain-pages-audit.js.',\n sourceType: 'file',\n sourcePath: 'tests/reports/domain-page-load-report.md',\n targetSlug: 'domain-pages-audit',\n },\n {\n publish: true,\n categorySlug: 'repo-ops',\n scriptId: 'audit-scripts',\n scriptPath: 'tools/scripts/audit-scripts.js',\n title: 'Script Audit Report',\n sidebarTitle: 'Script Audit',\n description:\n 'Generated script inventory audit report from tools/scripts/audit-scripts.js.',\n sourceType: 'file',\n sourcePath: 'tasks/reports/repo-ops/SCRIPT_AUDIT.md',\n targetSlug: 'audit-scripts',\n },\n {\n publish: true,\n categorySlug: 'repo-ops',\n scriptId: 'audit-tasks-folders',\n scriptPath: 'tools/scripts/audit-tasks-folders.js',\n title: 'Tasks Folder Audit Reports',\n sidebarTitle: 'Tasks Folder Audits',\n description:\n 'Generated tasks folder audit reports from tools/scripts/audit-tasks-folders.js.',\n sourceType: 'glob',\n sourceGlob: 'tasks/reports/repo-ops/*_audit.md',\n sourceBasenameAllowList: [\n 'errors_audit.md',\n 'reports_navigation-links_audit.md',\n 'reports_page-audits_audit.md',\n 'reports_quality-accessibility_audit.md',\n 'reports_quality-accessibility_docs-usefulness_audit.md',",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": false,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/publish-v2-internal-reports.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/publish-v2-internal-reports.js",
+ "grade": "C",
+ "flags": [
+ "invalid-category"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/notion/1-read-notion-to-csv.js",
+ "script": "1-read-notion-to-csv",
+ "category": "automation",
+ "purpose": "tooling:dev-tools",
+ "scope": "external",
+ "owner": "docs",
+ "needs": "node, @notionhq/client, dotenv, NOTION_API_KEY, NOTION_DATABASE_ID",
+ "purpose_statement": "Reads the Notion pages database, filters v2 rows, and writes CSV/JSON exports for downstream sync steps.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/notion/1-read-notion-to-csv.js [flags]",
+ "header": "/**\n * @script 1-read-notion-to-csv\n * @category automation\n * @purpose tooling:dev-tools\n * @scope external\n * @owner docs\n * @needs node, @notionhq/client, dotenv, NOTION_API_KEY, NOTION_DATABASE_ID\n * @purpose-statement Reads the Notion pages database, filters v2 rows, and writes CSV/JSON exports for downstream sync steps.\n * @pipeline manual\n * @usage node tools/notion/1-read-notion-to-csv.js [flags]\n */\n\nrequire(\"dotenv\").config();\nconst { Client } = require(\"@notionhq/client\");\nconst fs = require(\"fs\");\n\nasync function readNotionToCSV() {\n const notion = new Client({ auth: process.env.NOTION_API_KEY });\n const databaseId = process.env.NOTION_DATABASE_ID;\n\n console.log(\"Fetching all pages from Notion database...\");\n\n const allPages = [];\n let hasMore = true;\n let startCursor = undefined;\n\n while (hasMore) {\n const response = await notion.databases.query({\n database_id: databaseId,\n start_cursor: startCursor,\n });\n\n response.results.forEach((page) => {\n const pageName =\n page.properties[\"Page Name\"]?.title?.[0]?.plain_text || \"\";\n const tabGroup = page.properties[\"Tab Group\"]?.select?.name || \"\";\n const sectionGroup = page.properties[\"Section Group\"]?.select?.name || \"\";\n const subGroup = page.properties[\"Sub Section\"]?.select?.name || \"\";\n const pageStatus =\n page.properties[\"Page Status\"]?.multi_select?.[0]?.plain_text || \"\";\n const notes = page.properties[\"Notes\"]?.rich_text?.[0]?.plain_text || \"\";\n const relativePath = page.properties[\"Relative path URL\"]?.url || \"\";\n\n // ONLY INCLUDE V2 PAGES\n if (relativePath && relativePath.startsWith(\"v2/\")) {\n allPages.push({\n id: page.id,\n pageName,\n tabGroup,\n sectionGroup,\n subGroup,\n pageStatus,\n notes,\n relativePath,\n });\n }\n });\n\n hasMore = response.has_more;\n startCursor = response.next_cursor;\n console.log(`Fetched ${allPages.length} pages...`);\n }\n\n console.log(`\\nTotal pages fetched: ${allPages.length}`);\n\n // Write to CSV\n const csvHeader =\n \"ID,Page Name,Tab Group,Section Group,Sub Group,Page Status,Notes,Relative Path URL\\n\";\n const csvRows = allPages.map(\n (p) =>\n `\"${p.id}\",\"${p.pageName}\",\"${p.tabGroup}\",\"${p.sectionGroup}\",\"${p.subGroup}\",\"${p.pageStatus}\",\"${p.notes}\",\"${p.relativePath}\"`\n );\n const csvContent = csvHeader + csvRows.join(\"\\n\");\n\n // Create data directory if it doesn't exist\n const dataDir = __dirname + \"/data\";\n if (!fs.existsSync(dataDir)) {\n fs.mkdirSync(dataDir, { recursive: true });\n }\n\n const outputPath = dataDir + \"/notion-read.csv\";\n fs.writeFileSync(outputPath, csvContent);\n console.log(`\\nCSV exported to: ${outputPath}`);\n\n // Also write JSON for easier processing\n const jsonPath = dataDir + \"/notion-read.json\";\n fs.writeFileSync(jsonPath, JSON.stringify(allPages, null, 2));\n console.log(`JSON exported to: ${jsonPath}`);\n}\n\nreadNotionToCSV().catch(console.error);\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/notion/3-check-duplicates.js",
+ "pipeline": "indirect"
+ },
+ {
+ "type": "script",
+ "caller": "tools/notion/5-export-to-notion.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/notion/3-check-duplicates.js; indirect via tools/notion/5-export-to-notion.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/notion/2-read-docs-to-csv.js",
+ "script": "2-read-docs-to-csv",
+ "category": "generator",
+ "purpose": "tooling:dev-tools",
+ "scope": "external",
+ "owner": "docs",
+ "needs": "node",
+ "purpose_statement": "Parses docs.json v2 navigation and writes CSV/JSON exports with section-group metadata for Notion sync.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/notion/2-read-docs-to-csv.js [flags]",
+ "header": "/**\n * @script 2-read-docs-to-csv\n * @category generator\n * @purpose tooling:dev-tools\n * @scope external\n * @owner docs\n * @needs node\n * @purpose-statement Parses docs.json v2 navigation and writes CSV/JSON exports with section-group metadata for Notion sync.\n * @pipeline manual\n * @usage node tools/notion/2-read-docs-to-csv.js [flags]\n */\n\nconst fs = require(\"fs\");\nconst path = require(\"path\");\n\nfunction readDocsToCSV() {\n console.log(\"Starting docs.json export...\");\n\n const docsJsonPath = path.join(__dirname, \"../docs.json\");\n console.log(`Reading docs.json from: ${docsJsonPath}`);\n\n const docsJson = JSON.parse(fs.readFileSync(docsJsonPath, \"utf8\"));\n console.log(\"docs.json loaded successfully\");\n\n const pages = [];\n const sectionGroupColors = new Map();\n\n function processItem(\n item,\n tabGroup = \"\",\n sectionGroup = \"\",\n subGroup = \"\",\n depth = 0\n ) {\n // Handle string pages (direct page paths)\n if (typeof item === \"string\") {\n const pageName = path.basename(item, \".mdx\");\n const relativePath = item;\n const pageStatus = \"Active\";\n const notes = \"\";\n\n // ONLY INCLUDE V2 PAGES\n // EXCLUDE redirect pages (these are navigation hacks, not real content)\n if (\n relativePath &&\n relativePath.startsWith(\"v2/\") &&\n !relativePath.includes(\"/redirect\")\n ) {\n pages.push({\n pageName,\n tabGroup,\n sectionGroup,\n subGroup,\n pageStatus,\n notes,\n relativePath,\n });\n }\n return;\n }\n\n // Handle arrays\n if (Array.isArray(item)) {\n item.forEach((subItem) =>\n processItem(subItem, tabGroup, sectionGroup, subGroup, depth)\n );\n return;\n }\n\n // Handle groups\n if (item.group) {\n // depth 0 = top-level group under anchor (Section Group)\n // depth 1+ = nested group (Sub Group)\n if (depth === 0) {\n // This is a Section Group (top-level)\n const newSectionGroup = item.group;\n if (!sectionGroupColors.has(newSectionGroup)) {\n sectionGroupColors.set(\n newSectionGroup,\n getColorForIndex(sectionGroupColors.size)\n );\n }\n item.pages?.forEach((page) =>\n processItem(page, tabGroup, newSectionGroup, \"\", depth + 1)\n );\n } else {\n // This is a Sub Group (nested)\n const newSubGroup = item.group;\n item.pages?.forEach((page) =>\n processItem(page, tabGroup, sectionGroup, newSubGroup, depth + 1)\n );\n }\n return;\n }\n\n // Handle tabs\n if (item.tab) {\n const newTabGroup = item.tab;\n item.anchors?.forEach((anchor) =>\n processItem(anchor, newTabGroup, sectionGroup)\n );\n }\n\n // Handle anchors\n if (item.anchor) {\n // If anchor has groups, process groups (which will handle pages)\n // Groups under anchors are depth 0 (Section Groups)\n if (item.groups && item.groups.length > 0) {\n item.groups.forEach((group) => processItem(group, tabGroup, \"\", \"\", 0));\n } else {\n // Only process pages directly if there are no groups\n item.pages?.forEach((page) => processItem(page, tabGroup, \"\", \"\", 0));\n }\n }\n }\n\n // Navigate through the nested structure\n if (docsJson.navigation?.versions) {\n docsJson.navigation.versions.forEach((version) => {\n if (version.languages) {\n version.languages.forEach((language) => {\n if (language.tabs) {\n language.tabs.forEach((tab) => processItem(tab));\n }\n });\n }\n });\n }\n\n console.log(`Found ${pages.length} pages`);\n console.log(`Assigned colors to ${sectionGroupColors.size} section groups`);\n\n // Create data directory if it doesn't exist\n const dataDir = path.join(__dirname, \"data\");\n if (!fs.existsSync(dataDir)) {\n fs.mkdirSync(dataDir, { recursive: true });\n }\n\n // Write to CSV\n const csvHeader =\n \"Page Name,Tab Group,Section Group,Sub Group,Page Status,Notes,Relative Path URL\\n\";\n const csvRows = pages.map(\n (p) =>\n `\"${p.pageName}\",\"${p.tabGroup}\",\"${p.sectionGroup}\",\"${p.subGroup}\",\"${p.pageStatus}\",\"${p.notes}\",\"${p.relativePath}\"`\n );\n const csvContent = csvHeader + csvRows.join(\"\\n\");\n\n const csvPath = path.join(dataDir, \"docs-read.csv\");\n fs.writeFileSync(csvPath, csvContent);\n console.log(`CSV exported to: ${csvPath}`);\n\n // Write JSON with colors\n const jsonPath = path.join(dataDir, \"docs-read.json\");\n const jsonData = {\n pages,\n sectionGroupColors: Object.fromEntries(sectionGroupColors),\n };\n fs.writeFileSync(jsonPath, JSON.stringify(jsonData, null, 2));\n console.log(`JSON exported to: ${jsonPath}`);\n}\n\nfunction getColorForIndex(index) {\n const colors = [\n \"blue\",\n \"brown\",\n \"default\",\n \"gray\",\n \"green\",\n \"orange\",\n \"pink\",\n \"purple\",\n \"red\",\n \"yellow\",\n ];\n return colors[index % colors.length];\n}\n\nreadDocsToCSV();\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/notion/5-export-to-notion.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/notion/data",
+ "type": "directory",
+ "call": "mkdirSync"
+ },
+ {
+ "output_path": "tools/notion/docs-read.csv",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/notion/docs-read.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/notion/data, tools/notion/docs-read.csv, tools/notion/docs-read.json",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/notion/5-export-to-notion.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/notion/3-check-duplicates.js",
+ "script": "3-check-duplicates",
+ "category": "validator",
+ "purpose": "tooling:dev-tools",
+ "scope": "external",
+ "owner": "docs",
+ "needs": "node",
+ "purpose_statement": "Analyzes the exported Notion snapshot for duplicate page keys and writes JSON and Markdown reports.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/notion/3-check-duplicates.js [flags]",
+ "header": "/**\n * @script 3-check-duplicates\n * @category validator\n * @purpose tooling:dev-tools\n * @scope external\n * @owner docs\n * @needs node\n * @purpose-statement Analyzes the exported Notion snapshot for duplicate page keys and writes JSON and Markdown reports.\n * @pipeline manual\n * @usage node tools/notion/3-check-duplicates.js [flags]\n */\n\nconst fs = require(\"fs\");\nconst path = require(\"path\");\n\nfunction checkDuplicates() {\n console.log(\"Checking for duplicates in Notion database...\\n\");\n\n const notionJsonPath = path.join(__dirname, \"data\", \"notion-read.json\");\n\n if (!fs.existsSync(notionJsonPath)) {\n console.error(\"ERROR: data/notion-read.json not found!\");\n console.error(\"Please run: node 1-read-notion-to-csv.js first\");\n process.exit(1);\n }\n\n const notionPages = JSON.parse(fs.readFileSync(notionJsonPath, \"utf8\"));\n\n console.log(`Total pages in Notion: ${notionPages.length}`);\n\n // Group by unique key: Page Name + Tab Group + Section Group\n const pageGroups = new Map();\n\n notionPages.forEach((page) => {\n const uniqueKey = `${page.pageName}|||${page.tabGroup}|||${page.sectionGroup}`;\n\n if (!pageGroups.has(uniqueKey)) {\n pageGroups.set(uniqueKey, []);\n }\n pageGroups.get(uniqueKey).push(page);\n });\n\n // Find duplicates\n const duplicates = [];\n pageGroups.forEach((pages, key) => {\n if (pages.length > 1) {\n duplicates.push({ key, pages });\n }\n });\n\n console.log(`\\nUnique page combinations: ${pageGroups.size}`);\n console.log(`Duplicate groups found: ${duplicates.length}\\n`);\n\n if (duplicates.length > 0) {\n // Report duplicates\n console.log(\"DUPLICATES FOUND:\\n\");\n duplicates.forEach((dup, index) => {\n const [pageName, tabGroup, sectionGroup] = dup.key.split(\"|||\");\n console.log(\n `${\n index + 1\n }. \"${pageName}\" | Tab: \"${tabGroup}\" | Section: \"${sectionGroup}\"`\n );\n console.log(` Found ${dup.pages.length} copies:`);\n dup.pages.forEach((page, i) => {\n console.log(` ${i + 1}. ID: ${page.id} | Path: ${page.relativePath}`);\n });\n console.log();\n });\n } else {\n console.log(\"✓ No duplicates found!\");\n }\n\n // Create reports directory if it doesn't exist\n const reportsDir = path.join(__dirname, \"reports\");\n if (!fs.existsSync(reportsDir)) {\n fs.mkdirSync(reportsDir, { recursive: true });\n }\n\n // Write duplicates report as JSON\n const jsonReportPath = path.join(reportsDir, \"duplicates-report.json\");\n fs.writeFileSync(jsonReportPath, JSON.stringify(duplicates, null, 2));\n\n // Write duplicates report as Markdown\n let mdReport = `# Duplicates Report\\n\\n`;\n mdReport += `**Generated:** ${new Date().toISOString()}\\n\\n`;\n mdReport += `**Total pages in Notion:** ${notionPages.length}\\n`;\n mdReport += `**Unique page combinations:** ${pageGroups.size}\\n`;\n mdReport += `**Duplicate groups found:** ${duplicates.length}\\n\\n`;\n\n if (duplicates.length === 0) {\n mdReport += `✓ **No duplicates found!**\\n`;\n } else {\n mdReport += `## Duplicates Found\\n\\n`;\n duplicates.forEach((dup, index) => {\n const [pageName, tabGroup, sectionGroup] = dup.key.split(\"|||\");\n mdReport += `### ${index + 1}. \"${pageName}\"\\n\\n`;\n mdReport += `- **Tab Group:** \"${tabGroup}\"\\n`;\n mdReport += `- **Section Group:** \"${sectionGroup}\"\\n`;\n mdReport += `- **Copies found:** ${dup.pages.length}\\n\\n`;\n mdReport += `| # | Notion ID | Relative Path |\\n`;\n mdReport += `|---|-----------|---------------|\\n`;\n dup.pages.forEach((page, i) => {\n mdReport += `| ${i + 1} | \\`${page.id}\\` | ${\n page.relativePath || \"(empty)\"\n } |\\n`;\n });\n mdReport += `\\n`;\n });\n }\n\n const mdReportPath = path.join(reportsDir, \"Duplicates.md\");\n fs.writeFileSync(mdReportPath, mdReport);\n\n console.log(`\\nJSON report saved to: ${jsonReportPath}`);\n console.log(`Markdown report saved to: ${mdReportPath}`);\n\n if (duplicates.length > 0) {\n console.log(`\\nTo remove duplicates, run: node 4-remove-duplicates.js`);\n }\n}\n\ncheckDuplicates();\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/notion/4-remove-duplicates.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/notion/reports",
+ "type": "directory",
+ "call": "mkdirSync"
+ },
+ {
+ "output_path": "tools/notion/duplicates-report.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/notion/Duplicates.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/notion/reports, tools/notion/duplicates-report.json, tools/notion/Duplicates.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/notion/4-remove-duplicates.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/notion/4-remove-duplicates.js",
+ "script": "4-remove-duplicates",
+ "category": "remediator",
+ "purpose": "tooling:dev-tools",
+ "scope": "external",
+ "owner": "docs",
+ "needs": "node, @notionhq/client, dotenv, NOTION_API_KEY",
+ "purpose_statement": "Archives duplicate Notion pages from the duplicate report while keeping the first record in each group.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/notion/4-remove-duplicates.js [flags]",
+ "header": "/**\n * @script 4-remove-duplicates\n * @category remediator\n * @purpose tooling:dev-tools\n * @scope external\n * @owner docs\n * @needs node, @notionhq/client, dotenv, NOTION_API_KEY\n * @purpose-statement Archives duplicate Notion pages from the duplicate report while keeping the first record in each group.\n * @pipeline manual\n * @usage node tools/notion/4-remove-duplicates.js [flags]\n */\n\nrequire(\"dotenv\").config();\nconst { Client } = require(\"@notionhq/client\");\nconst fs = require(\"fs\");\nconst path = require(\"path\");\n\nasync function removeDuplicates() {\n const reportPath = path.join(__dirname, \"reports\", \"duplicates-report.json\");\n\n if (!fs.existsSync(reportPath)) {\n console.error(\"ERROR: reports/duplicates-report.json not found!\");\n console.error(\"Please run: node 3-check-duplicates.js first\");\n process.exit(1);\n }\n\n const duplicates = JSON.parse(fs.readFileSync(reportPath, \"utf8\"));\n\n if (duplicates.length === 0) {\n console.log(\"No duplicates to remove!\");\n return;\n }\n\n console.log(`Found ${duplicates.length} duplicate groups`);\n console.log(\"Strategy: Keep the FIRST entry, delete the rest\\n\");\n\n const notion = new Client({ auth: process.env.NOTION_API_KEY });\n\n let deletedCount = 0;\n let errorCount = 0;\n\n for (const dup of duplicates) {\n const [pageName, tabGroup, sectionGroup] = dup.key.split(\"|||\");\n console.log(\n `Processing: \"${pageName}\" | Tab: \"${tabGroup}\" | Section: \"${sectionGroup}\"`\n );\n console.log(` Keeping: ${dup.pages[0].id}`);\n\n // Delete all except the first one\n for (let i = 1; i < dup.pages.length; i++) {\n const pageToDelete = dup.pages[i];\n try {\n await notion.pages.update({\n page_id: pageToDelete.id,\n archived: true,\n });\n console.log(` ✓ Deleted: ${pageToDelete.id}`);\n deletedCount++;\n } catch (error) {\n console.error(\n ` ✗ Failed to delete ${pageToDelete.id}:`,\n error.message\n );\n errorCount++;\n }\n }\n console.log();\n }\n\n console.log(`\\nDeletion complete:`);\n console.log(` Deleted: ${deletedCount}`);\n console.log(` Errors: ${errorCount}`);\n\n // Write cleanup report\n const reportsDir = path.join(__dirname, \"reports\");\n if (!fs.existsSync(reportsDir)) {\n fs.mkdirSync(reportsDir, { recursive: true });\n }\n\n const cleanupReport = {\n timestamp: new Date().toISOString(),\n duplicateGroupsProcessed: duplicates.length,\n pagesDeleted: deletedCount,\n errors: errorCount,\n };\n\n const cleanupReportPath = path.join(reportsDir, \"notion-clean.json\");\n fs.writeFileSync(cleanupReportPath, JSON.stringify(cleanupReport, null, 2));\n console.log(`\\nCleanup report saved to: ${cleanupReportPath}`);\n console.log(`\\nRun 'node 1-read-notion-to-csv.js' to verify the cleanup.`);\n}\n\nremoveDuplicates().catch(console.error);\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/notion/5-export-to-notion.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/notion/reports",
+ "type": "directory",
+ "call": "mkdirSync"
+ },
+ {
+ "output_path": "tools/notion/notion-clean.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/notion/reports, tools/notion/notion-clean.json",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/notion/5-export-to-notion.js",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/dev/ensure-mint-watcher-patch.sh",
+ "script": "ensure-mint-watcher-patch",
+ "category": "utility",
+ "purpose": "tooling:dev-tools",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "Mint watcher patcher — applies patch to fix Mintlify file watcher issues in dev mode",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "bash tools/scripts/dev/ensure-mint-watcher-patch.sh [flags]",
+ "header": "#!/usr/bin/env bash\n# @script ensure-mint-watcher-patch\n# @category utility\n# @purpose tooling:dev-tools\n# @scope tools/scripts\n# @owner docs\n# @needs E-C6, F-C1\n# @purpose-statement Mint watcher patcher — applies patch to fix Mintlify file watcher issues in dev mode\n# @pipeline manual — interactive developer tool, not suited for automated pipelines\n# @usage bash tools/scripts/dev/ensure-mint-watcher-patch.sh [flags]\nset -euo pipefail\n\nMODE=\"apply\"\nif [ \"${1:-}\" = \"--check\" ]; then\n MODE=\"check\"\nelif [ \"${1:-}\" = \"--apply\" ] || [ \"${1:-}\" = \"\" ]; then\n MODE=\"apply\"\nelif [ \"${1:-}\" = \"--help\" ] || [ \"${1:-}\" = \"-h\" ]; then\n cat <<'EOF'\nUsage:\n bash tools/scripts/dev/ensure-mint-watcher-patch.sh --check\n bash tools/scripts/dev/ensure-mint-watcher-patch.sh --apply\nEOF\n exit 0\nelse\n echo \"Error: Unknown option: $1\" >&2\n exit 2\nfi\n\nif ! command -v mint >/dev/null 2>&1; then\n echo \"Error: mint CLI not found in PATH.\" >&2\n exit 2\nfi\n\nMINT_BIN=\"$(command -v mint)\"\nMINT_ENTRY_REALPATH=\"$(node -e 'const fs=require(\"fs\"); console.log(fs.realpathSync(process.argv[1]));' \"$MINT_BIN\")\"\nMINT_ROOT=\"$(cd \"$(dirname \"$MINT_ENTRY_REALPATH\")\" && pwd)\"\nLISTENER_PATH=\"$MINT_ROOT/node_modules/@mintlify/previewing/dist/local-preview/listener/index.js\"\n\nif [ ! -f \"$LISTENER_PATH\" ]; then\n echo \"Error: Mint listener file not found at: $LISTENER_PATH\" >&2\n exit 2\nfi\n\nif rg -q \"disableGlobbing:\\\\s*true\" \"$LISTENER_PATH\"; then\n echo \"Mint watcher patch present: $LISTENER_PATH\"\n exit 0\nfi\n\nif [ \"$MODE\" = \"check\" ]; then\n echo \"Mint watcher patch missing: $LISTENER_PATH\" >&2\n exit 1\nfi\n\nif ! rg -q \"^\\\\s*ignoreInitial:\\\\s*true,\" \"$LISTENER_PATH\"; then\n echo \"Error: Could not find expected watcher option in listener file.\" >&2\n exit 2\nfi\n\nif ! node -e '\nconst fs = require(\"fs\");\nconst path = process.argv[1];\nconst src = fs.readFileSync(path, \"utf8\");\nif (src.includes(\"disableGlobbing: true\")) {\n process.exit(0);\n}\nconst needle = \" ignoreInitial: true,\\n\";\nconst injected = \" ignoreInitial: true,\\n disableGlobbing: true,\\n\";\nif (!src.includes(needle)) {\n console.error(\"Unsupported listener format: ignoreInitial block not found.\");\n process.exit(2);\n}\nconst next = src.replace(needle, injected);\nif (next === src) {\n console.error(\"Patch was not applied.\");\n process.exit(2);\n}\ntry {\n fs.writeFileSync(path, next, \"utf8\");\n} catch (err) {\n console.error(err && err.message ? err.message : String(err));\n process.exit(3);\n}\n' \"$LISTENER_PATH\"; then\n echo \"Error: Failed to apply Mint watcher patch at: $LISTENER_PATH\" >&2\n exit 3\nfi\n\necho \"Mint watcher patch applied: $LISTENER_PATH\"\nexit 0\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tools/scripts/mint-dev.sh",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tools/scripts/mint-dev.sh",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ },
+ {
+ "path": "tools/scripts/dev/generate-mint-dev-scope.js",
+ "script": "generate-mint-dev-scope",
+ "category": "generator",
+ "purpose": "tooling:dev-tools",
+ "scope": "tools/scripts/dev, docs.json, .mintignore",
+ "owner": "docs",
+ "needs": "E-C6, F-C1",
+ "purpose_statement": "Mint dev scope generator — creates a scoped docs.json for running mint dev on a subset of pages",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/dev/generate-mint-dev-scope.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-mint-dev-scope\n * @category generator\n * @purpose tooling:dev-tools\n * @scope tools/scripts/dev, docs.json, .mintignore\n * @owner docs\n * @needs E-C6, F-C1\n * @purpose-statement Mint dev scope generator — creates a scoped docs.json for running mint dev on a subset of pages\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/dev/generate-mint-dev-scope.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst os = require('os');\nconst crypto = require('crypto');\nconst readline = require('readline');\n\nconst STRUCTURAL_ARRAY_KEYS = ['versions', 'languages', 'tabs', 'anchors', 'groups', 'pages'];\n\nfunction printUsage() {\n console.log(\n [\n 'Usage: node tools/scripts/dev/generate-mint-dev-scope.js [options]',\n '',\n 'Options:',\n ' --repo-root ',\n ' --workspace-base ',\n ' --scope-file ',\n ' --versions (repeatable)',\n ' --languages (repeatable)',\n ' --tabs (repeatable)',\n ' --prefixes (repeatable)',\n ' --interactive',\n ' --disable-openapi',\n ' --print-only',\n ' --help'\n ].join('\\n')\n );\n}\n\nfunction splitCsv(value) {\n return String(value || '')\n .split(',')\n .map((item) => item.trim())\n .filter(Boolean);\n}\n\nfunction uniqStrings(values) {\n return [...new Set((values || []).map((entry) => String(entry || '').trim()).filter(Boolean))];\n}\n\nfunction normalizeRoute(value) {\n return String(value || '')\n .trim()\n .replace(/^\\/+/, '')\n .replace(/\\/+$/, '');\n}\n\nfunction normalizeForCompare(value) {\n return String(value || '').trim().toLowerCase();\n}\n\nfunction routeMatchesPrefix(route, prefix) {\n const normalizedRoute = normalizeRoute(route);\n const normalizedPrefix = normalizeRoute(prefix);\n if (!normalizedRoute || !normalizedPrefix) return false;\n return normalizedRoute === normalizedPrefix || normalizedRoute.startsWith(`${normalizedPrefix}/`);\n}\n\nfunction isLanguageSegment(value) {\n const segment = String(value || '').trim();\n return /^[a-z]{2}(?:-[A-Za-z]{2})?$/.test(segment);\n}\n\nfunction isLikelyRouteEntry(value) {\n const route = normalizeRoute(value);\n if (!route) return false;\n if (route.startsWith('http://') || route.startsWith('https://')) return false;\n if (route === '-') return false;\n return route.includes('/');\n}\n\nfunction isOpenapiRoute(route) {\n const normalized = normalizeRoute(route);\n return normalized.includes('/api-reference/') || normalized.endsWith('/api-reference');\n}\n\nfunction shouldKeepRouteEntry(routeValue, context) {\n const route = normalizeRoute(routeValue);\n if (!route) return false;\n if (!isLikelyRouteEntry(route)) return false;\n if (context.disableOpenapi && isOpenapiRoute(route)) return false;\n if (context.prefixes.length === 0) return true;\n return context.prefixes.some((prefix) => routeMatchesPrefix(route, prefix));\n}\n\nfunction deriveSectionPrefix(routeValue) {\n const route = normalizeRoute(routeValue);\n if (!route) return '';\n const segments = route.split('/').filter(Boolean);\n if (segments.length < 2) return route;\n if (/^v\\d+$/.test(segments[0])) {\n if (segments.length >= 3 && isLanguageSegment(segments[1])) {\n return segments.slice(0, 3).join('/');\n }\n return segments.slice(0, 2).join('/');\n }\n return segments.slice(0, 2).join('/');\n}\n\nfunction collectRoutesFromPages(pages, outSet) {\n if (!Array.isArray(pages)) return;\n for (const entry of pages) {\n if (typeof entry === 'string') {\n const route = normalizeRoute(entry);\n if (isLikelyRouteEntry(route)) outSet.add(route);\n continue;\n }\n if (entry && typeof entry === 'object') {\n visitNavigationNode(entry, outSet);\n }\n }\n}\n\nfunction visitNavigationNode(node, outSet) {\n if (!node || typeof node !== 'object') return;\n if (Array.isArray(node.pages)) collectRoutesFromPages(node.pages, outSet);\n if (Array.isArray(node.groups)) node.groups.forEach((group) => visitNavigationNode(group, outSet));\n if (Array.isArray(node.anchors)) node.anchors.forEach((anchor) => visitNavigationNode(anchor, outSet));\n if (Array.isArray(node.tabs)) node.tabs.forEach((tab) => visitNavigationNode(tab, outSet));\n if (Array.isArray(node.languages)) node.languages.forEach((language) => visitNavigationNode(language, outSet));\n if (Array.isArray(node.versions)) node.versions.forEach((version) => visitNavigationNode(version, outSet));\n}\n\nfunction collectRoutesFromNavigation(navigation) {\n const routes = new Set();\n visitNavigationNode(navigation, routes);\n return [...routes].sort();\n}\n\nfunction parseArgs(argv) {\n const out = {\n repoRoot: process.cwd(),\n workspaceBase: path.join(os.tmpdir(), 'lpd-mint-dev'),\n scopeFile: '',\n versions: [],\n languages: [],\n tabs: [],\n prefixes: [],\n interactive: false,\n disableOpenapi: false,\n printOnly: false,\n help: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--help' || token === '-h') {\n out.help = true;\n continue;\n }\n if (token === '--repo-root') {\n out.repoRoot = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--repo-root=')) {\n out.repoRoot = token.slice('--repo-root='.length).trim();\n continue;\n }\n if (token === '--workspace-base') {\n out.workspaceBase = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--workspace-base=')) {\n out.workspaceBase = token.slice('--workspace-base='.length).trim();\n continue;\n }\n if (token === '--scope-file') {\n out.scopeFile = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--scope-file=')) {\n out.scopeFile = token.slice('--scope-file='.length).trim();\n continue;\n }\n if (token === '--versions' || token === '--scope-version') {\n out.versions.push(...splitCsv(argv[i + 1] || ''));\n i += 1;\n continue;\n }\n if (token.startsWith('--versions=') || token.startsWith('--scope-version=')) {\n out.versions.push(...splitCsv(token.split('=').slice(1).join('=')));\n continue;\n }\n if (token === '--languages' || token === '--scope-language') {\n out.languages.push(...splitCsv(argv[i + 1] || ''));\n i += 1;\n continue;\n }\n if (token.startsWith('--languages=') || token.startsWith('--scope-language=')) {\n out.languages.push(...splitCsv(token.split('=').slice(1).join('=')));\n continue;\n }\n if (token === '--tabs' || token === '--scope-tab') {\n out.tabs.push(...splitCsv(argv[i + 1] || ''));\n i += 1;\n continue;\n }\n if (token.startsWith('--tabs=') || token.startsWith('--scope-tab=')) {\n out.tabs.push(...splitCsv(token.split('=').slice(1).join('=')));\n continue;\n }\n if (token === '--prefixes' || token === '--scope-prefix') {\n out.prefixes.push(...splitCsv(argv[i + 1] || ''));\n i += 1;",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "script",
+ "caller": "tests/unit/lpd-scoped-mint-dev.test.js",
+ "pipeline": "indirect"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "indirect via tests/unit/lpd-scoped-mint-dev.test.js",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Indirect"
+ }
+ ],
+ "count": 60
+ },
+ "Manual": {
+ "label": "Manual - CLI only",
+ "scripts": [
+ {
+ "path": "tools/scripts/dev/batch-update-og-image.sh",
+ "script": "batch-update-og-image",
+ "category": "remediator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "Batch OG image updater — updates og:image meta tags across multiple pages",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "bash tools/scripts/dev/batch-update-og-image.sh [flags]",
+ "header": "#!/bin/bash\n# @script batch-update-og-image\n# @category remediator\n# @purpose feature:seo\n# @scope tools/scripts\n# @owner docs\n# @needs E-R19, F-R7\n# @purpose-statement Batch OG image updater — updates og:image meta tags across multiple pages\n# @pipeline manual — interactive developer tool, not suited for automated pipelines\n# @usage bash tools/scripts/dev/batch-update-og-image.sh [flags]\nOLD_IMAGE='og:image: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\"'\nNEW_IMAGE='og:image: \"/snippets/assets/domain/SHARED/LivepeerDocsHero.svg\"'\n\necho \"Finding files with old og:image...\"\nroots=(v2/pages v2/home v2/solutions v2/about v2/community v2/developers v2/gateways v2/orchestrators v2/lpt v2/resources v2/internal v2/deprecated v2/experimental v2/notes)\nexisting_roots=()\nfor root in \"${roots[@]}\"; do\n if [ -d \"$root\" ]; then\n existing_roots+=(\"$root\")\n fi\ndone\n\nfiles=$(grep -rl \"$OLD_IMAGE\" \"${existing_roots[@]}\" --include=\"*.mdx\" 2>/dev/null | grep -v \"mission-control.mdx\" || true)\n\ncount=0\nfor file in $files; do\n echo \"Updating: $file\"\n # Use perl for in-place replacement\n perl -pi -e \"s|og:image: \\\"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\\\"|og:image: \\\"/snippets/assets/domain/SHARED/LivepeerDocsHero.svg\\\"|g\" \"$file\"\n ((count++))\ndone\n\necho \"\"\necho \"========== SUMMARY ==========\"\necho \"Updated: $count files\"\necho \"=============================\"\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/dev/replace-og-image.py",
+ "script": "replace-og-image",
+ "category": "remediator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "OG image replacer — replaces og:image path in a single page frontmatter",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "python3 tools/scripts/dev/replace-og-image.py [flags]",
+ "header": "#!/usr/bin/env python3\n# @script replace-og-image\n# @category remediator\n# @purpose feature:seo\n# @scope tools/scripts\n# @owner docs\n# @needs E-R19, F-R7\n# @purpose-statement OG image replacer — replaces og:image path in a single page frontmatter\n# @pipeline manual — interactive developer tool, not suited for automated pipelines\n# @usage python3 tools/scripts/dev/replace-og-image.py [flags]\nimport os\nimport sys\n\nOLD_IMAGE = 'og:image: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\"'\nNEW_IMAGE = 'og:image: \"/snippets/assets/domain/SHARED/LivepeerDocsHero.svg\"'\nEXCLUDE_FILES = ['mission-control.mdx']\n\nchanged = 0\nskipped = 0\n\nroots = [\n 'v2/pages',\n 'v2/home',\n 'v2/solutions',\n 'v2/about',\n 'v2/community',\n 'v2/developers',\n 'v2/gateways',\n 'v2/orchestrators',\n 'v2/lpt',\n 'v2/resources',\n 'v2/internal',\n 'v2/deprecated',\n 'v2/experimental',\n 'v2/notes',\n]\n\nfor doc_root in roots:\n if not os.path.isdir(doc_root):\n continue\n for root, dirs, files in os.walk(doc_root):\n for file in files:\n if file.endswith('.mdx'):\n filepath = os.path.join(root, file)\n\n # Skip excluded files\n if file in EXCLUDE_FILES:\n print(f\"⊘ {filepath} - Excluded\")\n skipped += 1\n continue\n\n try:\n with open(filepath, 'r', encoding='utf-8') as f:\n content = f.read()\n\n if OLD_IMAGE in content:\n new_content = content.replace(OLD_IMAGE, NEW_IMAGE)\n\n with open(filepath, 'w', encoding='utf-8') as f:\n f.write(new_content)\n\n print(f\"✓ {filepath}\")\n changed += 1\n else:\n skipped += 1\n\n except Exception as e:\n print(f\"✗ {filepath}: {e}\")\n\nprint(f\"\\n========== SUMMARY ==========\")\nprint(f\"Changed: {changed}\")\nprint(f\"Skipped: {skipped}\")\nprint(f\"=============================\")\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/dev/test-seo-generator.js",
+ "script": "test-seo-generator",
+ "category": "generator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "Test for seo-generator — validates SEO generation logic",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/dev/test-seo-generator.js [flags]",
+ "header": "/**\n * @script test-seo-generator\n * @category generator\n * @purpose feature:seo\n * @scope tools/scripts\n * @owner docs\n * @needs E-R19, F-R7\n * @purpose-statement Test for seo-generator — validates SEO generation logic\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/dev/test-seo-generator.js [flags]\n */\nconst fs = require('fs')\nconst path = require('path')\nconst {\n extractFrontmatter,\n generateKeywords,\n getOgImagePath,\n parseFrontmatterFields,\n rebuildFrontmatter,\n processFile,\n} = require('./seo-generator-safe.js')\n\nconsole.log('Testing SEO Generator Script\\n')\n\n// Test files\nconst testFiles = [\n fs.existsSync('v2/home/mission-control.mdx')\n ? 'v2/home/mission-control.mdx'\n : 'v2/home/mission-control.mdx',\n fs.existsSync('v2/about/portal.mdx')\n ? 'v2/about/portal.mdx'\n : 'v2/about/portal.mdx',\n fs.existsSync('v2/gateways/gateways-portal.mdx')\n ? 'v2/gateways/gateways-portal.mdx'\n : 'v2/gateways/gateways-portal.mdx',\n]\n\nlet allTestsPassed = true\n\ntestFiles.forEach((testFile) => {\n console.log(`\\n========== Testing: ${testFile} ==========`)\n\n const fullPath = path.join(process.cwd(), testFile)\n const originalContent = fs.readFileSync(fullPath, 'utf8')\n const originalExtracted = extractFrontmatter(originalContent)\n\n if (!originalExtracted) {\n console.error('❌ Failed to extract frontmatter')\n allTestsPassed = false\n return\n }\n\n // Parse original frontmatter\n const originalFields = parseFrontmatterFields(originalExtracted.frontmatter)\n\n // Process file (dry run)\n const result = processFile(testFile)\n\n if (!result.success) {\n console.error(`❌ Processing failed: ${result.error}`)\n allTestsPassed = false\n return\n }\n\n // Simulate what the new content would be\n const newKeywords = result.newKeywords\n const newOgImage = result.ogImage\n const newFrontmatter = rebuildFrontmatter(\n originalFields,\n newKeywords,\n newOgImage\n )\n const newContent = `---\\n${newFrontmatter}\\n---\\n${originalExtracted.body}`\n\n // Parse new frontmatter\n const newExtracted = extractFrontmatter(newContent)\n const newFields = parseFrontmatterFields(newExtracted.frontmatter)\n\n // Verify all fields except keywords and og:image are preserved\n let fieldsPreserved = true\n for (const key in originalFields) {\n if (key === 'keywords' || key === 'og:image' || key === 'og') {\n continue // These are expected to change\n }\n\n if (originalFields[key] !== newFields[key]) {\n console.error(`❌ Field \"${key}\" was modified!`)\n console.error(` Original: ${originalFields[key]}`)\n console.error(` New: ${newFields[key]}`)\n fieldsPreserved = false\n allTestsPassed = false\n }\n }\n\n // Verify body content is unchanged\n if (originalExtracted.body !== newExtracted.body) {\n console.error('❌ Body content was modified!')\n console.error(` Original length: ${originalExtracted.body.length}`)\n console.error(` New length: ${newExtracted.body.length}`)\n allTestsPassed = false\n } else {\n console.log('✓ Body content preserved')\n }\n\n if (fieldsPreserved) {\n console.log(\n '✓ All frontmatter fields preserved (except keywords and og:image)'\n )\n }\n\n // Show what changed\n console.log('\\nChanges:')\n console.log(\n ` Keywords: ${JSON.stringify(result.oldKeywords)} → ${JSON.stringify(result.newKeywords)}`\n )\n console.log(` og:image: ${newOgImage}`)\n\n // Show preserved fields\n console.log('\\nPreserved fields:')\n for (const key in originalFields) {\n if (key !== 'keywords' && key !== 'og:image' && key !== 'og') {\n const value =\n originalFields[key].length > 50\n ? originalFields[key].substring(0, 50) + '...'\n : originalFields[key]\n console.log(` ${key}: ${value}`)\n }\n }\n})\n\nconsole.log('\\n\\n========== TEST SUMMARY ==========')\nif (allTestsPassed) {\n console.log('✅ ALL TESTS PASSED')\n console.log('The script correctly:')\n console.log(\n ' - Preserves all frontmatter fields except keywords and og:image'\n )\n console.log(' - Preserves all body content')\n console.log(' - Only modifies keywords and og:image fields')\n} else {\n console.log('❌ SOME TESTS FAILED')\n console.log('DO NOT USE THIS SCRIPT until all tests pass!')\n}\nconsole.log('==================================')\n\nprocess.exit(allTestsPassed ? 0 : 1)\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/dev/update-all-og-images.js",
+ "script": "update-all-og-images",
+ "category": "remediator",
+ "purpose": "feature:seo",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "E-R19, F-R7",
+ "purpose_statement": "Bulk OG image updater — updates og:image across all v2 pages",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/dev/update-all-og-images.js [flags]",
+ "header": "/**\n * @script update-all-og-images\n * @category remediator\n * @purpose feature:seo\n * @scope tools/scripts\n * @owner docs\n * @needs E-R19, F-R7\n * @purpose-statement Bulk OG image updater — updates og:image across all v2 pages\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/dev/update-all-og-images.js [flags]\n */\nconst fs = require('fs');\nconst path = require('path');\n\nconst OLD_IMAGE = 'og:image: \"/snippets/assets/domain/SHARED/LivepeerDocsLogo.svg\"';\nconst NEW_IMAGE = 'og:image: \"/snippets/assets/domain/SHARED/LivepeerDocsHero.svg\"';\nconst EXCLUDE_FILES = ['mission-control.mdx'];\nconst V2_DOC_ROOTS = [\n 'v2/pages',\n 'v2/home',\n 'v2/solutions',\n 'v2/about',\n 'v2/community',\n 'v2/developers',\n 'v2/gateways',\n 'v2/orchestrators',\n 'v2/lpt',\n 'v2/resources',\n 'v2/internal',\n 'v2/deprecated',\n 'v2/experimental',\n 'v2/notes'\n].filter((root) => fs.existsSync(root));\n\nfunction getAllMdxFiles(dir, fileList = []) {\n const files = fs.readdirSync(dir);\n \n files.forEach(file => {\n const filePath = path.join(dir, file);\n const stat = fs.statSync(filePath);\n \n if (stat.isDirectory()) {\n getAllMdxFiles(filePath, fileList);\n } else if (file.endsWith('.mdx')) {\n fileList.push(filePath);\n }\n });\n \n return fileList;\n}\n\nconst allFiles = V2_DOC_ROOTS.flatMap((root) => getAllMdxFiles(root));\nlet changed = 0;\nlet skipped = 0;\nlet errors = 0;\n\nconsole.log(`Found ${allFiles.length} MDX files\\n`);\n\nallFiles.forEach(filePath => {\n try {\n const fileName = path.basename(filePath);\n \n // Skip excluded files\n if (EXCLUDE_FILES.includes(fileName)) {\n console.log(`⊘ ${filePath} - Excluded`);\n skipped++;\n return;\n }\n \n const content = fs.readFileSync(filePath, 'utf8');\n \n if (content.includes(OLD_IMAGE)) {\n const newContent = content.replace(OLD_IMAGE, NEW_IMAGE);\n fs.writeFileSync(filePath, newContent, 'utf8');\n console.log(`✓ ${filePath}`);\n changed++;\n } else {\n skipped++;\n }\n } catch (error) {\n console.error(`✗ ${filePath}: ${error.message}`);\n errors++;\n }\n});\n\nconsole.log(`\\n========== SUMMARY ==========`);\nconsole.log(`Changed: ${changed}`);\nconsole.log(`Skipped: ${skipped}`);\nconsole.log(`Errors: ${errors}`);\nconsole.log(`=============================`);\n\n// Write summary to file\nfs.writeFileSync('og-image-update-summary.txt', `Changed: ${changed}\\nSkipped: ${skipped}\\nErrors: ${errors}\\n`);\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/dev/og-image-update-summary.txt",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/dev/og-image-update-summary.txt",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test-mintlify-version-language-toggle.js",
+ "script": "test-mintlify-version-language-toggle",
+ "category": "enforcer",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts/i18n, docs.json, v2",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Mintlify language toggle checker — validates Mintlify version supports language toggle feature",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test-mintlify-version-language-toggle.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script test-mintlify-version-language-toggle\n * @category enforcer\n * @purpose feature:translation\n * @scope tools/scripts/i18n, docs.json, v2\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Mintlify language toggle checker — validates Mintlify version supports language toggle feature\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/i18n/test-mintlify-version-language-toggle.js [flags]\n */\n\nconst puppeteer = require('puppeteer');\n\nfunction parseArgs(argv) {\n const args = {\n baseUrl: 'http://localhost:3000',\n timeoutMs: 120000,\n strictMenus: false\n };\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n const next = argv[i + 1];\n if (token === '--base-url') {\n args.baseUrl = String(next || args.baseUrl).trim();\n i += 1;\n } else if (token === '--timeout-ms') {\n const parsed = Number(next);\n if (Number.isFinite(parsed) && parsed > 0) args.timeoutMs = parsed;\n i += 1;\n } else if (token === '--strict-menus') {\n args.strictMenus = true;\n } else if (token === '--help' || token === '-h') {\n console.log(\n [\n 'Usage: node tools/scripts/i18n/test-mintlify-version-language-toggle.js [options]',\n '',\n 'Options:',\n ' --base-url Mint preview base URL (default http://localhost:3000)',\n ' --timeout-ms Navigation timeout (default 120000)',\n ' --strict-menus Fail if menu contents cannot be confirmed in headless mode',\n ' --help, -h Show help'\n ].join('\\n')\n );\n process.exit(0);\n }\n }\n return args;\n}\n\nfunction buildTextMatchers(values) {\n return values.map((value) => String(value || '').trim()).filter(Boolean);\n}\n\nfunction textListContains(texts, expected) {\n const needle = String(expected || '').trim();\n if (!needle) return false;\n return texts.some((text) => {\n const value = String(text || '').trim();\n if (!value) return false;\n return value === needle || value.includes(needle) || value.startsWith(`${needle}\\n`) || value.endsWith(`\\n${needle}`);\n });\n}\n\nasync function collectTexts(page, { visibleOnly = false } = {}) {\n return page.evaluate((opts) => {\n const els = Array.from(document.querySelectorAll('button,a,[role=\"menuitem\"]'));\n const isVisible = (el) => {\n const rect = el.getBoundingClientRect();\n const styles = window.getComputedStyle(el);\n return rect.width > 0 && rect.height > 0 && styles.display !== 'none' && styles.visibility !== 'hidden';\n };\n return els\n .filter((el) => (opts.visibleOnly ? isVisible(el) : true))\n .map((el) => (el.innerText || el.textContent || '').trim())\n .filter(Boolean);\n }, { visibleOnly });\n}\n\nasync function findVersionTriggerText(page) {\n return page.evaluate(() => {\n const btns = Array.from(document.querySelectorAll('button'));\n const isVisible = (el) => {\n const rect = el.getBoundingClientRect();\n const styles = window.getComputedStyle(el);\n return rect.width > 0 && rect.height > 0 && styles.display !== 'none' && styles.visibility !== 'hidden';\n };\n const trigger =\n btns.find((b) => isVisible(b) && /^(v1|v2)$/i.test((b.innerText || b.textContent || '').trim())) ||\n btns.find((b) => /^(v1|v2)$/i.test((b.innerText || b.textContent || '').trim()));\n return trigger ? (trigger.innerText || trigger.textContent || '').trim() : '';\n });\n}\n\nasync function clickTrigger(page, patternSource) {\n return page.evaluate((source) => {\n const pattern = new RegExp(source, 'i');\n const btns = Array.from(document.querySelectorAll('button'));\n const isVisible = (el) => {\n const rect = el.getBoundingClientRect();\n const styles = window.getComputedStyle(el);\n return rect.width > 0 && rect.height > 0 && styles.display !== 'none' && styles.visibility !== 'hidden';\n };\n const btn =\n btns.find((b) => isVisible(b) && pattern.test((b.innerText || b.textContent || '').trim())) ||\n btns.find((b) => pattern.test((b.innerText || b.textContent || '').trim()));\n if (!btn) return { ok: false, text: '' };\n btn.click();\n return { ok: true, text: (btn.innerText || btn.textContent || '').trim() };\n }, patternSource);\n}\n\nasync function clickVersionTrigger(page) {\n return clickTrigger(page, '^(v1|v2)$');\n}\n\nasync function clickLanguageTrigger(page) {\n return clickTrigger(page, '(English|Espa\\u00f1ol|Fran\\u00e7ais|\\u4e2d\\u6587|Chinese|Spanish|French)');\n}\n\nfunction assertCondition(condition, message, failures) {\n if (!condition) failures.push(message);\n}\n\nfunction normalizeUrl(url) {\n return String(url || '').replace(/\\/+$/, '');\n}\n\nfunction expectedTargetVersion(currentVersion) {\n return currentVersion === 'v2' ? 'v1' : 'v2';\n}\n\nasync function maybeAssertMenuItems({ scenario, page, failures, warnings, strictMenus }) {\n const versionClick = await clickVersionTrigger(page);\n if (!versionClick.ok) {\n if (strictMenus) failures.push(`${scenario.name}: version trigger not found for menu check`);\n else warnings.push(`${scenario.name}: version trigger menu could not be opened in headless preview`);\n return;\n }\n await new Promise((r) => setTimeout(r, 500));\n const menuTexts = await collectTexts(page);\n const expectedItems = buildTextMatchers(scenario.requiredVersionMenuItems || []);\n for (const item of expectedItems) {\n if (!textListContains(menuTexts, item)) {\n if (strictMenus) failures.push(`${scenario.name}: version menu missing \"${item}\"`);\n else warnings.push(`${scenario.name}: could not confirm version menu item \"${item}\" in headless preview`);\n }\n }\n}\n\nasync function maybeAssertLanguageItems({ scenario, page, failures, warnings, strictMenus }) {\n const languageClick = await clickLanguageTrigger(page);\n if (!languageClick.ok) {\n if (strictMenus) failures.push(`${scenario.name}: language trigger not found`);\n else warnings.push(`${scenario.name}: language trigger could not be opened in headless preview`);\n return;\n }\n await new Promise((r) => setTimeout(r, 500));\n const menuTexts = await collectTexts(page);\n const expectedItems = buildTextMatchers(scenario.requiredLanguageMenuItems || []);\n for (const item of expectedItems) {\n if (!textListContains(menuTexts, item)) {\n if (strictMenus) failures.push(`${scenario.name}: language menu missing \"${item}\"`);\n else warnings.push(`${scenario.name}: could not confirm language menu item \"${item}\" in headless preview`);\n }\n }\n}\n\nasync function tryVersionSwitch(page, scenario, failures, warnings, timeoutMs, strictMenus) {\n const currentVersion = scenario.expectedVersionTrigger;\n const targetVersion = expectedTargetVersion(currentVersion);\n const versionClick = await clickVersionTrigger(page);\n if (!versionClick.ok) {\n if (strictMenus) failures.push(`${scenario.name}: version trigger not found for switch attempt`);\n else warnings.push(`${scenario.name}: version switch not attempted (trigger not found in headless preview)`);\n return null;\n }\n await new Promise((r) => setTimeout(r, 500));\n const targetClicked = await page.evaluate((target) => {\n const nodes = Array.from(document.querySelectorAll('button,a,[role=\"menuitem\"]'));\n const isVisible = (el) => {\n const rect = el.getBoundingClientRect();\n const styles = window.getComputedStyle(el);\n return rect.width > 0 && rect.height > 0 && styles.display !== 'none' && styles.visibility !== 'hidden';\n };\n const pick =\n nodes.find((node) => isVisible(node) && new RegExp(`^${target}$`, 'i').test((node.innerText || node.textContent || '').trim())) ||\n nodes.find((node) => new RegExp(`^${target}$`, 'i').test((node.innerText || node.textContent || '').trim()));\n if (!pick) return false;\n pick.click();\n return true;\n }, targetVersion);\n\n if (!targetClicked) {\n if (strictMenus) failures.push(`${scenario.name}: could not click version menu item ${targetVersion}`);\n else warnings.push(`${scenario.name}: could not click version menu item ${targetVersion} in headless preview`);\n return null;\n }\n\n try {\n await page.waitForNavigation({ waitUntil: 'networkidle2', timeout: timeoutMs });\n } catch {\n await new Promise((r) => setTimeout(r, 1200));\n }\n\n const switchedUrl = page.url();\n if (!String(switchedUrl).includes(`/${targetVersion}/`)) {\n failures.push(`${scenario.name}: version switch did not navigate to /${targetVersion}/ (got ${switchedUrl})`);\n }\n return switchedUrl;\n}\n\nasync function runScenario(page, scenario, failures, warnings, timeoutMs, strictMenus) {\n const pageErrors = [];\n page.removeAllListeners('pageerror');\n page.on('pageerror', (err) => pageErrors.push(err.message));\n\n await page.goto(scenario.url, { waitUntil: 'networkidle2', timeout: timeoutMs });\n await new Promise((r) => setTimeout(r, 800));",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test/cli-guardrails.test.js",
+ "script": "cli-guardrails.test",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Tests i18n CLI guardrails — validates argument validation and safety checks",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test/cli-guardrails.test.js [flags]",
+ "header": "/**\n * @script cli-guardrails.test\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Tests i18n CLI guardrails — validates argument validation and safety checks\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @dualmode dual-mode (document flags)\n * @usage node tools/scripts/i18n/test/cli-guardrails.test.js [flags]\n */\nconst test = require('node:test');\nconst assert = require('node:assert/strict');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\n\nconst { run: runTranslateDocs } = require('../translate-docs');\nconst { run: runGenerateDocsJson } = require('../generate-localized-docs-json');\n\ntest('translate-docs blocks mock provider non-dry runs without --allow-mock-write', async () => {\n await assert.rejects(\n () => runTranslateDocs(['--provider', 'mock']),\n /mock provider.*write mode|Refusing to run translate-docs with mock provider/i\n );\n});\n\ntest('translate-docs allows mock provider non-dry runs with --allow-mock-write (guard path)', async () => {\n const tmpFile = path.join(os.tmpdir(), `i18n-empty-paths-${Date.now()}.txt`);\n fs.writeFileSync(tmpFile, 'v2/does-not-exist\\n', 'utf8');\n\n const report = await runTranslateDocs([\n '--provider',\n 'mock',\n '--allow-mock-write',\n '--languages',\n 'es',\n '--scope-mode',\n 'paths_file',\n '--paths-file',\n tmpFile,\n '--max-pages',\n '1'\n ]);\n\n assert.equal(report.counts.failed, 0);\n assert.equal(report.counts.successfulPageLanguagePairs, 0);\n});\n\ntest('generate-localized-docs-json blocks mock provider write runs without --allow-mock-write', async () => {\n await assert.rejects(\n () => runGenerateDocsJson(['--provider', 'mock', '--write', '--languages', 'es']),\n /Refusing to write docs\\.json with mock provider/i\n );\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/i18n/test/i18n-empty-paths-${Date.now()}.txt",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/i18n/test/i18n-empty-paths-${Date.now()}.txt",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test/docs-json-localizer.test.js",
+ "script": "docs-json-localizer.test",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Tests docs-json-localizer — validates locale docs.json transformation logic",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test/docs-json-localizer.test.js [flags]",
+ "header": "/**\n * @script docs-json-localizer.test\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Tests docs-json-localizer — validates locale docs.json transformation logic\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/i18n/test/docs-json-localizer.test.js [flags]\n */\nconst test = require('node:test');\nconst assert = require('node:assert/strict');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { generateLocalizedDocsJson } = require('../lib/docs-json-localizer');\n\nfunction fixtureDocsJson() {\n return {\n navigation: {\n versions: [\n {\n version: 'v1',\n languages: [\n {\n language: 'en',\n dropdowns: [\n {\n dropdown: 'Developers',\n anchors: [{ anchor: 'Docs', groups: [{ group: 'Start', pages: ['v1/developers/introduction'] }] }]\n }\n ]\n }\n ]\n },\n {\n version: 'v2',\n languages: [\n {\n language: 'en',\n tabs: [\n {\n tab: 'About',\n anchors: [\n {\n anchor: 'Livepeer Network',\n groups: [\n {\n group: 'Pages',\n pages: [\n 'v2/about/livepeer-network/actors',\n 'v2/about/livepeer-network/job-lifecycle',\n ' '\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n };\n}\n\ntest('generateLocalizedDocsJson clones v2 english node, translates labels, and rewrites localized routes', async () => {\n const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'i18n-docs-json-'));\n fs.mkdirSync(path.join(tmp, 'v2', 'es', 'about', 'livepeer-network'), { recursive: true });\n fs.writeFileSync(path.join(tmp, 'v2', 'es', 'about', 'livepeer-network', 'actors.mdx'), '# actors');\n fs.writeFileSync(path.join(tmp, 'v2', 'es', 'about', 'livepeer-network', 'job-lifecycle.mdx'), '# job');\n\n const translator = {\n name: 'openrouter',\n async translateStrings({ language, strings }) {\n return { strings: strings.map((s) => `${language.toUpperCase()}: ${s}`), modelUsed: 'stub-openrouter' };\n }\n };\n\n const routeMapEntries = [\n {\n sourceRoute: 'v2/about/livepeer-network/actors',\n localizedRoute: 'v2/es/about/livepeer-network/actors',\n localizedFile: 'v2/es/about/livepeer-network/actors.mdx',\n language: 'es',\n status: 'translated',\n provider: 'openrouter',\n artifactClass: 'translated_real'\n },\n {\n sourceRoute: 'v2/about/livepeer-network/job-lifecycle',\n localizedRoute: 'v2/es/about/livepeer-network/job-lifecycle',\n localizedFile: 'v2/es/about/livepeer-network/job-lifecycle.mdx',\n language: 'es',\n status: 'translated',\n provider: 'openrouter',\n artifactClass: 'translated_real'\n }\n ];\n\n const result = await generateLocalizedDocsJson({\n docsJson: fixtureDocsJson(),\n repoRoot: tmp,\n targetLanguages: ['es'],\n translator,\n translationRules: {\n translateDocsJsonLabelKeys: ['tab', 'anchor', 'group'],\n preserveBrandTerms: [],\n preserveRegexes: []\n },\n routeMapEntries,\n routeMapMetadata: {\n runtime: { scopeMode: 'full_v2_nav' },\n scope: {\n scopeMode: 'full_v2_nav',\n selectedRoutes: [\n 'v2/about/livepeer-network/actors',\n 'v2/about/livepeer-network/job-lifecycle'\n ]\n }\n },\n qualityGates: {\n requireLocalizedFileForRouteRewrite: true\n },\n reporting: {\n warnRouteRewriteCoverageBelowPct: 80,\n warnOnMixedLanguageLocaleUi: true\n },\n writeMode: false,\n allowMockWrite: false\n });\n\n const v2 = result.docsJson.navigation.versions.find((v) => v.version === 'v2');\n assert.deepEqual(\n v2.languages.map((l) => l.language),\n ['en', 'es']\n );\n\n const es = v2.languages.find((l) => l.language === 'es');\n assert.match(es.tabs[0].tab, /^ES:/);\n assert.doesNotMatch(es.tabs[0].tab, /^\\[es\\]/);\n assert.equal(es.tabs[0].anchors[0].groups[0].pages[0], 'v2/es/about/livepeer-network/actors');\n assert.equal(es.tabs[0].anchors[0].groups[0].pages[1], 'v2/es/about/livepeer-network/job-lifecycle');\n assert.equal(es.tabs[0].anchors[0].groups[0].pages[2], ' ');\n assert.equal(result.report.perLanguage[0].rewrittenRoutes, 2);\n assert.equal(result.report.perLanguage[0].fallbackRoutes, 0);\n assert.equal(result.report.perLanguage[0].routeCoverageOverallPct, 100);\n assert.equal(result.report.perLanguage[0].routeCoverageScope, 'full_v2_nav');\n assert.deepEqual(result.report.perLanguage[0].warnings, []);\n const v1 = result.docsJson.navigation.versions.find((v) => v.version === 'v1');\n assert.deepEqual(\n v1.languages.map((l) => l.language),\n ['en']\n );\n assert.equal(v1.languages[0].dropdowns[0].dropdown, 'Developers');\n});\n\ntest('generateLocalizedDocsJson rejects mock provenance routes for rewrite and reports fallback diagnostics', async () => {\n const translator = {\n name: 'openrouter',\n async translateStrings({ language, strings }) {\n return { strings: strings.map((s) => `${language}:${s}`), modelUsed: 'stub' };\n }\n };\n\n const routeMapEntries = [\n {\n sourceRoute: 'v2/about/livepeer-network/actors',\n localizedRoute: 'v2/es/about/livepeer-network/actors',\n localizedFile: 'v2/es/about/livepeer-network/actors.mdx',\n language: 'es',\n status: 'existing',\n provider: 'mock',\n artifactClass: 'translated_mock'\n }\n ];\n\n const result = await generateLocalizedDocsJson({\n docsJson: fixtureDocsJson(),\n repoRoot: process.cwd(),\n targetLanguages: ['es'],\n translator,\n translationRules: {\n translateDocsJsonLabelKeys: ['tab', 'anchor', 'group'],\n preserveBrandTerms: [],\n preserveRegexes: []\n },\n routeMapEntries,\n routeMapMetadata: {\n runtime: { scopeMode: 'prefixes' },\n scope: {\n scopeMode: 'prefixes',\n selectedRoutes: [\n 'v2/about/livepeer-network/actors',\n 'v2/about/livepeer-network/job-lifecycle'\n ]\n }\n },\n qualityGates: {\n requireLocalizedFileForRouteRewrite: false,\n rejectMockArtifactsForRouteRewrite: true\n },\n reporting: {\n warnRouteRewriteCoverageBelowPct: 80,\n warnOnMixedLanguageLocaleUi: true\n },\n writeMode: false,\n allowMockWrite: false\n });\n\n const v2 = result.docsJson.navigation.versions.find((v) => v.version === 'v2');\n const es = v2.languages.find((l) => l.language === 'es');\n assert.equal(es.tabs[0].anchors[0].groups[0].pages[0], 'v2/about/livepeer-network/actors');\n\n const report = result.report.perLanguage[0];\n assert.equal(report.rewrittenRoutes, 0);\n assert.equal(report.fallbackRoutes, 2);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test/frontmatter.test.js",
+ "script": "frontmatter.test",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Tests frontmatter parser — validates frontmatter read/write roundtrip",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test/frontmatter.test.js [flags]",
+ "header": "/**\n * @script frontmatter.test\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Tests frontmatter parser — validates frontmatter read/write roundtrip\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/i18n/test/frontmatter.test.js [flags]\n */\nconst test = require('node:test');\nconst assert = require('node:assert/strict');\nconst { parseMdxFileWithFrontmatter, translateFrontmatterFields } = require('../lib/frontmatter');\n\ntest('translateFrontmatterFields only translates allowlisted string keys', async () => {\n const translator = {\n name: 'mock',\n async translateStrings({ language, strings }) {\n return { strings: strings.map((s) => `[${language}] ${s}`), modelUsed: 'mock' };\n }\n };\n\n const raw = [\n '---',\n 'title: Actors Overview',\n 'sidebarTitle: Actors',\n 'description: Who participates',\n 'keywords:',\n ' - livepeer',\n 'og:image: /snippets/assets/logo.svg',\n '---',\n '',\n 'Body'\n ].join('\\n');\n\n const parsed = parseMdxFileWithFrontmatter(raw);\n const result = await translateFrontmatterFields({\n data: parsed.data,\n language: 'fr',\n translator,\n rules: {\n translateFrontmatterKeys: ['title', 'sidebarTitle', 'description'],\n preserveBrandTerms: [],\n preserveRegexes: ['^/snippets/']\n },\n translateKeywords: false\n });\n\n assert.match(result.data.title, /^\\[fr\\]/);\n assert.match(result.data.sidebarTitle, /^\\[fr\\]/);\n assert.match(result.data.description, /^\\[fr\\]/);\n assert.deepEqual(result.data.keywords, ['livepeer']);\n assert.equal(result.data['og:image'], '/snippets/assets/logo.svg');\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test/mdx-translate.test.js",
+ "script": "mdx-translate.test",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Tests MDX translation — validates content block translation logic",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test/mdx-translate.test.js [flags]",
+ "header": "/**\n * @script mdx-translate.test\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Tests MDX translation — validates content block translation logic\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/i18n/test/mdx-translate.test.js [flags]\n */\nconst test = require('node:test');\nconst assert = require('node:assert/strict');\nconst {\n extractTranslatableTextSegments,\n protectText,\n restoreProtectedText,\n translateMdxBody\n} = require('../lib/mdx-translate');\n\ntest('extractTranslatableTextSegments skips code and MDX JSX text', async () => {\n const mdx = [\n '# Heading',\n '',\n 'Paragraph with `inline` code and [link](./target).',\n '',\n '```js',\n 'const value = \"do not translate\";',\n '```',\n '',\n 'Do not translate JSX children in v1 '\n ].join('\\n');\n\n const segments = await extractTranslatableTextSegments(mdx);\n const combined = segments.map((s) => s.text).join(' | ');\n\n assert.match(combined, /Heading/);\n assert.match(combined, /Paragraph with /);\n assert.match(combined, /link/);\n assert.doesNotMatch(combined, /do not translate/);\n assert.doesNotMatch(combined, /JSX children/);\n});\n\ntest('protectText preserves URLs/routes/brand terms and restores placeholders', () => {\n const rules = {\n preserveBrandTerms: ['Livepeer'],\n preserveRegexes: []\n };\n const input = 'Use Livepeer at https://example.com and route v2/about/livepeer-network/actors';\n const protectedValue = protectText(input, rules);\n assert.equal(protectedValue.skip, false);\n assert.match(protectedValue.text, /__I18N_PH_/);\n const restored = restoreProtectedText(protectedValue.text, protectedValue.placeholders);\n assert.equal(restored, input);\n});\n\ntest('translateMdxBody rewrites internal markdown links when localized targets exist', async () => {\n const translator = {\n name: 'mock',\n async translateStrings({ language, strings }) {\n return { strings: strings.map((s) => `${language.toUpperCase()}: ${s}`), modelUsed: 'mock' };\n }\n };\n\n const routeMap = new Map([\n ['v2/about/livepeer-network/actors', new Map([['es', 'v2/es/about/livepeer-network/actors']])],\n ['v2/about/livepeer-network/job-lifecycle', new Map([['es', 'v2/es/about/livepeer-network/job-lifecycle']])]\n ]);\n\n const body = 'See [Job Lifecycle](./job-lifecycle) and [External](https://example.com).';\n const result = await translateMdxBody({\n body,\n language: 'es',\n translator,\n rules: { preserveBrandTerms: [], preserveRegexes: [] },\n routeContext: {\n sourceRoute: 'v2/about/livepeer-network/actors',\n language: 'es',\n sourceLocalizedRoute: 'v2/es/about/livepeer-network/actors',\n routeMapBySourceRoute: routeMap\n }\n });\n\n assert.match(result.body, /\\[[^\\]]*Job Lifecycle[^\\]]*\\]\\(\\.\\/job-lifecycle\\)/);\n assert.match(result.body, /\\[[^\\]]*External[^\\]]*\\]\\(https:\\/\\/example\\.com\\)/);\n assert.equal(result.linkRewrite.rewrittenCount, 1);\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test/provenance.test.js",
+ "script": "provenance.test",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Tests provenance tracker — validates translation provenance recording",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test/provenance.test.js [flags]",
+ "header": "/**\n * @script provenance.test\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Tests provenance tracker — validates translation provenance recording\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/i18n/test/provenance.test.js [flags]\n */\nconst test = require('node:test');\nconst assert = require('node:assert/strict');\nconst { parseMdxFileWithFrontmatter } = require('../lib/frontmatter');\nconst {\n buildProvenanceComment,\n injectOrReplaceProvenanceComment,\n parseProvenanceComment\n} = require('../lib/provenance');\n\ntest('provenance comment is MDX-safe, replaceable, and parseable after frontmatter', () => {\n const raw = [\n '---',\n 'title: Example',\n 'description: Example',\n '---',\n '',\n '# Heading',\n '',\n 'Body'\n ].join('\\n');\n\n const first = buildProvenanceComment({\n sourcePath: 'v2/example.mdx',\n sourceRoute: 'v2/example',\n sourceHash: 'abc',\n language: 'es',\n provider: 'openrouter',\n model: 'model-a',\n generatedAt: '2026-02-24T00:00:00.000Z'\n });\n const second = buildProvenanceComment({\n sourcePath: 'v2/example.mdx',\n sourceRoute: 'v2/example',\n sourceHash: 'def',\n language: 'es',\n provider: 'openrouter',\n model: 'model-b',\n generatedAt: '2026-02-24T01:00:00.000Z'\n });\n\n const withFirst = injectOrReplaceProvenanceComment(raw, first);\n const withSecond = injectOrReplaceProvenanceComment(withFirst, second);\n\n const parsedDoc = parseMdxFileWithFrontmatter(withSecond);\n assert.match(parsedDoc.body, /\\{\\/\\* codex-i18n:/);\n const provenance = parseProvenanceComment(withSecond);\n assert.equal(provenance.sourceHash, 'def');\n assert.equal(provenance.model, 'model-b');\n assert.equal((withSecond.match(/codex-i18n:/g) || []).length, 1);\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/i18n/test/provider-openrouter.test.js",
+ "script": "provider-openrouter.test",
+ "category": "validator",
+ "purpose": "feature:translation",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "F-R6, F-R7",
+ "purpose_statement": "Tests OpenRouter provider — validates API call logic and response parsing",
+ "pipeline_declared": "manual — diagnostic/investigation tool, run on-demand only",
+ "usage": "node tools/scripts/i18n/test/provider-openrouter.test.js [flags]",
+ "header": "/**\n * @script provider-openrouter.test\n * @category validator\n * @purpose feature:translation\n * @scope tools/scripts\n * @owner docs\n * @needs F-R6, F-R7\n * @purpose-statement Tests OpenRouter provider — validates API call logic and response parsing\n * @pipeline manual — diagnostic/investigation tool, run on-demand only\n * @usage node tools/scripts/i18n/test/provider-openrouter.test.js [flags]\n */\nconst test = require('node:test');\nconst assert = require('node:assert/strict');\nconst {\n createOpenRouterTranslator,\n isModelFailoverError,\n parseJsonFromModelContent,\n validateSegmentResponse\n} = require('../lib/provider-openrouter');\nconst { createTranslator } = require('../lib/providers');\n\ntest('parseJsonFromModelContent parses plain JSON and fenced JSON', () => {\n const plain = parseJsonFromModelContent('{\"segments\":[{\"id\":0,\"text\":\"hola\"}]}');\n assert.equal(plain.segments[0].text, 'hola');\n\n const fenced = parseJsonFromModelContent('```json\\n{\"segments\":[{\"id\":\"1\",\"text\":\"bonjour\"}]}\\n```');\n assert.equal(fenced.segments[0].text, 'bonjour');\n});\n\ntest('validateSegmentResponse preserves ordering by request ids and rejects count mismatch', () => {\n const request = [\n { id: 'b', text: 'beta' },\n { id: 'a', text: 'alpha' }\n ];\n const response = {\n segments: [\n { id: 'a', text: 'A' },\n { id: 'b', text: 'B' }\n ]\n };\n const normalized = validateSegmentResponse(response, request);\n assert.deepEqual(normalized, [\n { id: 'b', text: 'B' },\n { id: 'a', text: 'A' }\n ]);\n\n assert.throws(\n () => validateSegmentResponse({ segments: [{ id: 'a', text: 'A' }] }, request),\n /Segment count mismatch/\n );\n});\n\ntest('isModelFailoverError treats provider incompatibility and capacity errors as failover eligible', () => {\n assert.equal(\n isModelFailoverError({ status: 400, message: 'Developer instruction is not enabled for this model' }),\n true\n );\n assert.equal(\n isModelFailoverError({ status: 400, message: 'totally unrelated validation error' }),\n false\n );\n assert.equal(isModelFailoverError({ status: 429, message: 'rate limited' }), true);\n assert.equal(isModelFailoverError({ status: 503, message: 'provider down' }), true);\n});\n\ntest('createTranslator defaults to openrouter and reports provider name', () => {\n const translator = createTranslator({\n config: {\n provider: { name: 'openrouter', modelCandidates: ['test/model:free'] },\n translationRules: {}\n }\n });\n assert.equal(translator.name, 'openrouter');\n});\n\ntest('createOpenRouterTranslator fails over across models and returns final modelUsed', async () => {\n const originalFetch = global.fetch;\n const originalApiKey = process.env.OPENROUTER_API_KEY;\n let callCount = 0;\n global.fetch = async (_url, options) => {\n callCount += 1;\n const body = JSON.parse(String(options.body || '{}'));\n if (body.model === 'bad/model:free') {\n return {\n ok: false,\n status: 400,\n text: async () => '{\"error\":{\"message\":\"Developer instruction is not enabled\"}}'\n };\n }\n return {\n ok: true,\n json: async () => ({\n choices: [\n {\n message: {\n content: JSON.stringify({\n segments: [{ id: 0, text: 'hola' }]\n })\n }\n }\n ]\n })\n };\n };\n\n process.env.OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY || 'test-key';\n\n try {\n const translator = createOpenRouterTranslator(\n {\n modelCandidates: ['bad/model:free', 'good/model:free'],\n baseUrl: 'https://example.invalid',\n maxRetriesPerRequest: 1,\n requestTimeoutMs: 1000,\n temperature: 0.1\n },\n {}\n );\n const result = await translator.translateStrings({ language: 'es', strings: ['hello'] });\n assert.deepEqual(result.strings, ['hola']);\n assert.equal(result.modelUsed, 'good/model:free');\n assert.equal(callCount, 2);\n } finally {\n global.fetch = originalFetch;\n if (originalApiKey === undefined) delete process.env.OPENROUTER_API_KEY;\n else process.env.OPENROUTER_API_KEY = originalApiKey;\n }\n});\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tests/unit/codex-commit.test.js",
+ "script": "codex-commit.test",
+ "category": "validator",
+ "purpose": "governance:agent-governance",
+ "scope": "tests/unit, tools/scripts/codex-commit.js",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Tests codex-commit.js — validates commit message generation and contract compliance",
+ "pipeline_declared": "manual — not yet in pipeline",
+ "usage": "node tests/unit/codex-commit.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex-commit.test\n * @category validator\n * @purpose governance:agent-governance\n * @scope tests/unit, tools/scripts/codex-commit.js\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Tests codex-commit.js — validates commit message generation and contract compliance\n * @pipeline manual — not yet in pipeline\n * @dualmode dual-mode (document flags)\n * @usage node tests/unit/codex-commit.test.js [flags]\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst REPO_ROOT = process.cwd();\nconst SCRIPT_PATH = path.join(REPO_ROOT, 'tools/scripts/codex-commit.js');\n\nfunction run(cmd, args, cwd) {\n return spawnSync(cmd, args, { cwd, encoding: 'utf8' });\n}\n\nfunction runGit(args, cwd) {\n const out = run('git', args, cwd);\n if (out.status !== 0) {\n throw new Error(`git ${args.join(' ')} failed: ${out.stderr || out.stdout}`);\n }\n return (out.stdout || '').trim();\n}\n\nfunction writeFile(absPath, content) {\n fs.mkdirSync(path.dirname(absPath), { recursive: true });\n fs.writeFileSync(absPath, content, 'utf8');\n}\n\nfunction mkRepo(prefix) {\n const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));\n runGit(['init', '-b', 'main'], dir);\n runGit(['config', 'user.email', 'tests@example.com'], dir);\n runGit(['config', 'user.name', 'test-runner'], dir);\n writeFile(path.join(dir, 'file.txt'), 'init\\n');\n runGit(['add', 'file.txt'], dir);\n runGit(['commit', '-m', 'init'], dir);\n return dir;\n}\n\nfunction runScript(args, cwd) {\n return run('node', [SCRIPT_PATH, ...args], cwd);\n}\n\nasync function runTests() {\n const failures = [];\n const cases = [];\n\n cases.push(async () => {\n const repo = mkRepo('codex-commit-normal-');\n writeFile(path.join(repo, 'file.txt'), 'normal\\n');\n runGit(['add', 'file.txt'], repo);\n\n const exec = runScript(['--message', 'chore: normal commit'], repo);\n assert.strictEqual(exec.status, 0, exec.stderr || exec.stdout);\n const body = runGit(['log', '-1', '--pretty=%B'], repo);\n assert.match(body, /chore: normal commit/);\n });\n\n cases.push(async () => {\n const repo = mkRepo('codex-commit-reject-');\n writeFile(path.join(repo, 'file.txt'), 'reject\\n');\n runGit(['add', 'file.txt'], repo);\n\n const exec = runScript(['--message', 'chore: should fail', '--no-verify'], repo);\n assert.strictEqual(exec.status, 1, 'no-verify without override must fail');\n const output = `${exec.stdout}\\n${exec.stderr}`;\n assert.match(output, /requires --human-override true/i);\n });\n\n cases.push(async () => {\n const repo = mkRepo('codex-commit-override-');\n writeFile(path.join(repo, 'file.txt'), 'override\\n');\n runGit(['add', 'file.txt'], repo);\n\n const exec = runScript(\n [\n '--message',\n 'chore: override commit',\n '--no-verify',\n '--human-override',\n 'true',\n '--override-note',\n 'User said no-verify is allowed for this commit.'\n ],\n repo\n );\n assert.strictEqual(exec.status, 0, exec.stderr || exec.stdout);\n\n const body = runGit(['log', '-1', '--pretty=%B'], repo);\n assert.match(body, /\\[override-audit\\]/);\n assert.match(body, /override_type: no-verify/);\n assert.match(body, /requested_by: human/);\n assert.match(body, /User said no-verify is allowed/);\n });\n\n for (let i = 0; i < cases.length; i += 1) {\n const name = `case-${i + 1}`;\n try {\n // eslint-disable-next-line no-await-in-loop\n await cases[i]();\n console.log(` ✓ ${name}`);\n } catch (error) {\n failures.push(`${name}: ${error.message}`);\n }\n }\n\n return {\n passed: failures.length === 0,\n total: cases.length,\n errors: failures\n };\n}\n\nif (require.main === module) {\n runTests()\n .then((result) => {\n if (result.passed) {\n console.log(`\\n✅ codex-commit tests passed (${result.total} cases)`);\n process.exit(0);\n }\n console.error(`\\n❌ ${result.errors.length} codex-commit test failure(s)`);\n result.errors.forEach((entry) => console.error(` - ${entry}`));\n process.exit(1);\n })\n .catch((error) => {\n console.error(`\\n❌ codex-commit tests crashed: ${error.message}`);\n process.exit(1);\n });\n}\n\nmodule.exports = { runTests };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tests/unit/codex-safe-merge-with-stash.test.js",
+ "script": "codex-safe-merge-with-stash.test",
+ "category": "utility",
+ "purpose": "governance:agent-governance",
+ "scope": "tests/unit, tools/scripts/codex-safe-merge-with-stash.js",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Tests codex-safe-merge-with-stash.js — validates safe merge logic with stash handling",
+ "pipeline_declared": "manual — developer tool",
+ "usage": "node tests/unit/codex-safe-merge-with-stash.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex-safe-merge-with-stash.test\n * @category utility\n * @purpose governance:agent-governance\n * @scope tests/unit, tools/scripts/codex-safe-merge-with-stash.js\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Tests codex-safe-merge-with-stash.js — validates safe merge logic with stash handling\n * @pipeline manual — developer tool\n * @dualmode dual-mode (document flags)\n * @usage node tests/unit/codex-safe-merge-with-stash.test.js [flags]\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst REPO_ROOT = process.cwd();\nconst SCRIPT_PATH = path.join(REPO_ROOT, 'tools/scripts/codex-safe-merge-with-stash.js');\n\nfunction run(cmd, args, cwd) {\n return spawnSync(cmd, args, { cwd, encoding: 'utf8' });\n}\n\nfunction runGit(args, cwd) {\n const out = run('git', args, cwd);\n if (out.status !== 0) {\n throw new Error(`git ${args.join(' ')} failed: ${out.stderr || out.stdout}`);\n }\n return (out.stdout || '').trim();\n}\n\nfunction writeFile(absPath, content) {\n fs.mkdirSync(path.dirname(absPath), { recursive: true });\n fs.writeFileSync(absPath, content, 'utf8');\n}\n\nfunction mkRepo(prefix) {\n const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));\n runGit(['init', '-b', 'main'], dir);\n runGit(['config', 'user.email', 'tests@example.com'], dir);\n runGit(['config', 'user.name', 'test-runner'], dir);\n writeFile(path.join(dir, 'app.txt'), 'base\\n');\n runGit(['add', 'app.txt'], dir);\n runGit(['commit', '-m', 'init'], dir);\n runGit(['checkout', '-b', 'feature'], dir);\n return dir;\n}\n\nfunction runScript(args, cwd) {\n return run('node', [SCRIPT_PATH, ...args], cwd);\n}\n\nasync function runTests() {\n const failures = [];\n const cases = [];\n\n cases.push(async () => {\n const repo = mkRepo('codex-safe-merge-clean-');\n runGit(['checkout', 'main'], repo);\n writeFile(path.join(repo, 'app.txt'), 'base\\nmain-change\\n');\n runGit(['add', 'app.txt'], repo);\n runGit(['commit', '-m', 'main change'], repo);\n runGit(['checkout', 'feature'], repo);\n\n const exec = runScript(['--target', 'main'], repo);\n assert.strictEqual(exec.status, 0, exec.stderr || exec.stdout);\n const merged = fs.readFileSync(path.join(repo, 'app.txt'), 'utf8');\n assert.match(merged, /main-change/, 'feature should include merged change');\n });\n\n cases.push(async () => {\n const repo = mkRepo('codex-safe-merge-dirty-');\n runGit(['checkout', 'main'], repo);\n writeFile(path.join(repo, 'app.txt'), 'base\\nmain-change\\n');\n runGit(['add', 'app.txt'], repo);\n runGit(['commit', '-m', 'main change'], repo);\n runGit(['checkout', 'feature'], repo);\n\n writeFile(path.join(repo, 'local.txt'), 'local-dirty\\n');\n writeFile(path.join(repo, 'temp-untracked.txt'), 'temp\\n');\n runGit(['add', 'local.txt'], repo);\n\n const exec = runScript(['--target', 'main'], repo);\n assert.strictEqual(exec.status, 0, exec.stderr || exec.stdout);\n\n const localTracked = fs.readFileSync(path.join(repo, 'local.txt'), 'utf8');\n const localUntracked = fs.readFileSync(path.join(repo, 'temp-untracked.txt'), 'utf8');\n assert.match(localTracked, /local-dirty/, 'tracked local file should be restored');\n assert.match(localUntracked, /temp/, 'untracked local file should be restored');\n });\n\n cases.push(async () => {\n const repo = mkRepo('codex-safe-merge-conflict-');\n runGit(['checkout', 'main'], repo);\n writeFile(path.join(repo, 'app.txt'), 'main-version\\n');\n runGit(['add', 'app.txt'], repo);\n runGit(['commit', '-m', 'main update'], repo);\n runGit(['checkout', 'feature'], repo);\n writeFile(path.join(repo, 'app.txt'), 'feature-version\\n');\n runGit(['add', 'app.txt'], repo);\n runGit(['commit', '-m', 'feature update'], repo);\n\n writeFile(path.join(repo, 'dirty.txt'), 'dirty\\n');\n runGit(['add', 'dirty.txt'], repo);\n\n const exec = runScript(['--target', 'main'], repo);\n assert.strictEqual(exec.status, 1, 'merge conflict should fail');\n\n const stashList = runGit(['stash', 'list'], repo);\n assert.match(stashList, /codex-safe-merge:/, 'stash should be preserved when merge fails');\n });\n\n for (let i = 0; i < cases.length; i += 1) {\n const name = `case-${i + 1}`;\n try {\n // eslint-disable-next-line no-await-in-loop\n await cases[i]();\n console.log(` ✓ ${name}`);\n } catch (error) {\n failures.push(`${name}: ${error.message}`);\n }\n }\n\n return {\n passed: failures.length === 0,\n total: cases.length,\n errors: failures\n };\n}\n\nif (require.main === module) {\n runTests()\n .then((result) => {\n if (result.passed) {\n console.log(`\\n✅ codex-safe-merge-with-stash tests passed (${result.total} cases)`);\n process.exit(0);\n }\n console.error(`\\n❌ ${result.errors.length} codex-safe-merge-with-stash test failure(s)`);\n result.errors.forEach((entry) => console.error(` - ${entry}`));\n process.exit(1);\n })\n .catch((error) => {\n console.error(`\\n❌ codex-safe-merge-with-stash tests crashed: ${error.message}`);\n process.exit(1);\n });\n}\n\nmodule.exports = { runTests };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tests/unit/codex-skill-sync.test.js",
+ "script": "codex-skill-sync.test",
+ "category": "validator",
+ "purpose": "governance:agent-governance",
+ "scope": "tests/unit, tools/scripts/sync-codex-skills.js, ai-tools/ai-skills/templates",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Tests sync-codex-skills.js — validates skill file synchronisation between sources",
+ "pipeline_declared": "manual — not yet in pipeline",
+ "usage": "node tests/unit/codex-skill-sync.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex-skill-sync.test\n * @category validator\n * @purpose governance:agent-governance\n * @scope tests/unit, tools/scripts/sync-codex-skills.js, ai-tools/ai-skills/templates\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Tests sync-codex-skills.js — validates skill file synchronisation between sources\n * @pipeline manual — not yet in pipeline\n * @dualmode dual-mode (document flags)\n * @usage node tests/unit/codex-skill-sync.test.js [flags]\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst REPO_ROOT = process.cwd();\nconst SYNC_SCRIPT = path.join(REPO_ROOT, 'tools/scripts/sync-codex-skills.js');\n\nlet errors = [];\n\nfunction runNode(args, options = {}) {\n return spawnSync('node', [SYNC_SCRIPT, ...args], {\n cwd: REPO_ROOT,\n encoding: 'utf8',\n env: {\n ...process.env,\n ...(options.env || {})\n }\n });\n}\n\nfunction mkTmpDir(prefix) {\n return fs.mkdtempSync(path.join(os.tmpdir(), prefix));\n}\n\nfunction writeFile(absPath, content) {\n fs.mkdirSync(path.dirname(absPath), { recursive: true });\n fs.writeFileSync(absPath, content, 'utf8');\n}\n\nfunction createTemplate(sourceDir, number, name, description) {\n const fileName = `${String(number).padStart(2, '0')}-${name}.template.md`;\n const absPath = path.join(sourceDir, fileName);\n const content = [\n '---',\n `name: ${name}`,\n `description: ${description}`,\n 'tier: 1',\n 'triggers:',\n ' - \"trigger one\"',\n ' - \"trigger two\"',\n ' - \"trigger three\"',\n 'primary_paths:',\n ' - \"README.md\"',\n ' - \"tools/scripts\"',\n 'primary_commands:',\n ' - \"bash lpd setup --yes\"',\n ' - \"bash lpd doctor --strict\"',\n '---',\n '',\n `SKILL: ${name}`,\n '',\n 'Goal',\n 'Execute the workflow safely.',\n '',\n 'Constraints',\n '- Keep v1 immutable.',\n '',\n 'Workflow',\n '1. Run command one.',\n '2. Run command two.',\n '',\n 'Deliverable Format',\n '- Provide concise status and next actions.',\n '',\n 'Failure Modes / Fallback',\n '- If command fails, report exact remediation.',\n '',\n 'Validation Checklist',\n '- [ ] Required checks were run.',\n ''\n ].join('\\n');\n writeFile(absPath, content);\n return { absPath, content };\n}\n\nfunction readUtf8(absPath) {\n return fs.readFileSync(absPath, 'utf8');\n}\n\nasync function runCase(name, fn) {\n try {\n await fn();\n console.log(` ✓ ${name}`);\n } catch (error) {\n errors.push({\n name,\n message: error.message\n });\n }\n}\n\nasync function runTests() {\n errors = [];\n console.log('🧪 Codex Skill Sync Unit Tests');\n\n await runCase('Sync installs templates and generates openai.yaml', async () => {\n const root = mkTmpDir('codex-skill-sync-install-');\n const sourceDir = path.join(root, 'source');\n const destDir = path.join(root, 'dest');\n\n const t1 = createTemplate(sourceDir, 1, 'alpha-skill', 'Alpha skill synchronization workflow.');\n createTemplate(sourceDir, 2, 'beta-skill', 'Beta skill synchronization workflow.');\n\n const result = runNode(['--source-dir', sourceDir, '--dest', destDir]);\n assert.strictEqual(result.status, 0, `sync exited non-zero: ${result.stderr || result.stdout}`);\n\n const skillPath = path.join(destDir, 'alpha-skill', 'SKILL.md');\n const openaiPath = path.join(destDir, 'alpha-skill', 'agents', 'openai.yaml');\n assert.ok(fs.existsSync(skillPath), 'alpha SKILL.md should exist');\n assert.ok(fs.existsSync(openaiPath), 'alpha openai.yaml should exist');\n assert.strictEqual(readUtf8(skillPath), t1.content, 'SKILL.md should match canonical template exactly');\n\n const openai = readUtf8(openaiPath);\n assert.ok(openai.includes('display_name: \"Alpha Skill\"'), 'openai.yaml should include deterministic display_name');\n assert.ok(openai.includes('short_description: \"'), 'openai.yaml should include short_description');\n assert.ok(openai.includes('$alpha-skill'), 'openai.yaml default_prompt should include explicit $skill reference');\n });\n\n await runCase('Check mode fails on drift', async () => {\n const root = mkTmpDir('codex-skill-sync-check-');\n const sourceDir = path.join(root, 'source');\n const destDir = path.join(root, 'dest');\n\n createTemplate(sourceDir, 1, 'drift-skill', 'Detect drift in check mode.');\n const syncResult = runNode(['--source-dir', sourceDir, '--dest', destDir]);\n assert.strictEqual(syncResult.status, 0, `initial sync failed: ${syncResult.stderr || syncResult.stdout}`);\n\n writeFile(path.join(destDir, 'drift-skill', 'SKILL.md'), 'tampered');\n const checkResult = runNode(['--source-dir', sourceDir, '--dest', destDir, '--check']);\n assert.strictEqual(checkResult.status, 1, 'check mode should fail on drift');\n assert.ok((checkResult.stdout + checkResult.stderr).includes('drift'), 'check output should include drift signal');\n });\n\n await runCase('Safe upsert preserves unmanaged skills', async () => {\n const root = mkTmpDir('codex-skill-sync-upsert-');\n const sourceDir = path.join(root, 'source');\n const destDir = path.join(root, 'dest');\n createTemplate(sourceDir, 1, 'managed-skill', 'Managed skill from templates.');\n\n const unmanagedPath = path.join(destDir, 'custom-local-skill', 'SKILL.md');\n writeFile(unmanagedPath, '---\\nname: custom-local-skill\\ndescription: local\\n---\\n\\nSKILL: Custom\\n');\n\n const result = runNode(['--source-dir', sourceDir, '--dest', destDir]);\n assert.strictEqual(result.status, 0, `sync failed: ${result.stderr || result.stdout}`);\n assert.ok(fs.existsSync(unmanagedPath), 'unmanaged skill should remain');\n assert.strictEqual(readUtf8(unmanagedPath).includes('custom-local-skill'), true, 'unmanaged content should remain intact');\n });\n\n await runCase('Subset install writes only selected skills', async () => {\n const root = mkTmpDir('codex-skill-sync-subset-');\n const sourceDir = path.join(root, 'source');\n const destDir = path.join(root, 'dest');\n createTemplate(sourceDir, 1, 'subset-one', 'Subset one.');\n createTemplate(sourceDir, 2, 'subset-two', 'Subset two.');\n\n const result = runNode(['--source-dir', sourceDir, '--dest', destDir, '--skills', 'subset-two']);\n assert.strictEqual(result.status, 0, `subset sync failed: ${result.stderr || result.stdout}`);\n assert.ok(!fs.existsSync(path.join(destDir, 'subset-one')), 'subset-one should not be installed');\n assert.ok(fs.existsSync(path.join(destDir, 'subset-two', 'SKILL.md')), 'subset-two should be installed');\n });\n\n await runCase('Dry-run does not mutate destination', async () => {\n const root = mkTmpDir('codex-skill-sync-dryrun-');\n const sourceDir = path.join(root, 'source');\n const destDir = path.join(root, 'dest');\n createTemplate(sourceDir, 1, 'dry-run-skill', 'Dry-run should not write files.');\n\n const result = runNode(['--source-dir', sourceDir, '--dest', destDir, '--dry-run']);\n assert.strictEqual(result.status, 0, `dry-run failed: ${result.stderr || result.stdout}`);\n assert.ok(!fs.existsSync(path.join(destDir, 'dry-run-skill')), 'dry-run should not create skill files');\n });\n\n return {\n passed: errors.length === 0,\n total: 5,\n errors\n };\n}\n\nif (require.main === module) {\n runTests()\n .then((result) => {\n if (result.passed) {\n console.log(`\\n✅ Codex skill sync unit tests passed (${result.total} cases)`);\n process.exit(0);\n }\n console.error(`\\n❌ ${result.errors.length} codex skill sync unit test failure(s)`);\n result.errors.forEach((entry) => {\n console.error(` - ${entry.name}: ${entry.message}`);\n });\n process.exit(1);\n })\n .catch((error) => {\n console.error(`\\n❌ Codex skill sync unit tests crashed: ${error.message}`);\n process.exit(1);\n });\n}\n\nmodule.exports = { runTests };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:codex-skills-sync"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tests/unit/${String(number).padStart(2, '0')}-${name}.template.md",
+ "type": "generated-output",
+ "call": "writeFile"
+ },
+ {
+ "output_path": "tests/unit/${String(number).padStart(2, '0')}-${name}.template.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tests/unit/SKILL.md",
+ "type": "generated-output",
+ "call": "writeFile"
+ }
+ ],
+ "outputs_display": "tests/unit/${String(number).padStart(2, '0')}-${name}.template.md, tests/unit/${String(number).padStart(2, '0')}-${name}.template.md, tests/unit/SKILL.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: test:codex-skills-sync)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tests/unit/create-codex-pr.test.js",
+ "script": "create-codex-pr.test",
+ "category": "generator",
+ "purpose": "governance:agent-governance",
+ "scope": "tests/unit, tools/scripts/create-codex-pr.js",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Tests create-codex-pr.js — validates PR creation logic and branch naming",
+ "pipeline_declared": "manual — not yet in pipeline",
+ "usage": "node tests/unit/create-codex-pr.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script create-codex-pr.test\n * @category generator\n * @purpose governance:agent-governance\n * @scope tests/unit, tools/scripts/create-codex-pr.js\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Tests create-codex-pr.js — validates PR creation logic and branch naming\n * @pipeline manual — not yet in pipeline\n * @dualmode dual-mode (document flags)\n * @usage node tests/unit/create-codex-pr.test.js [flags]\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst REPO_ROOT = process.cwd();\nconst SCRIPT_PATH = path.join(REPO_ROOT, 'tools/scripts/create-codex-pr.js');\n\nfunction runScript(args) {\n return spawnSync('node', [SCRIPT_PATH, ...args], {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n}\n\nfunction mkTmpDir(prefix) {\n return fs.mkdtempSync(path.join(os.tmpdir(), prefix));\n}\n\nfunction writeFile(absPath, content) {\n fs.mkdirSync(path.dirname(absPath), { recursive: true });\n fs.writeFileSync(absPath, content, 'utf8');\n}\n\nfunction makeContract(absPath, taskId = 3456) {\n const content = [\n `task_id: ${taskId}`,\n 'base_branch: docs-v2',\n `branch: codex/${taskId}-auto-pr-body`,\n 'scope_in:',\n ' - v2/community/',\n ' - docs.json',\n 'scope_out:',\n ' - v1/',\n 'allowed_generated:',\n ' - docs-index.json',\n 'acceptance_checks:',\n ' - node tests/run-pr-checks.js --base-ref docs-v2',\n ' - node tests/integration/v2-link-audit.js --files v2/community/faq.mdx --strict',\n 'follow_up_issues:',\n ` - ${taskId + 1}`,\n ''\n ].join('\\n');\n writeFile(absPath, content);\n}\n\nasync function runTests() {\n const failures = [];\n const cases = [];\n\n cases.push(async () => {\n const tmp = mkTmpDir('codex-pr-body-');\n const contractPath = path.join(tmp, 'task-contract.yaml');\n const outputPath = path.join(tmp, 'pr-body.md');\n makeContract(contractPath);\n\n const run = runScript([\n '--contract',\n contractPath,\n '--output',\n outputPath,\n '--head',\n 'codex/3456-auto-pr-body',\n '--base',\n 'docs-v2',\n '--changed-files',\n 'v2/community/faq.mdx,docs.json'\n ]);\n\n assert.strictEqual(run.status, 0, `generator failed: ${run.stderr || run.stdout}`);\n const body = fs.readFileSync(outputPath, 'utf8');\n assert.match(body, /codex-pr-body-generated:/, 'body should include generated marker');\n assert.match(body, /^Fixes #3456$/m, 'body should include closing keyword for task issue');\n assert.match(body, /^## Scope/m, 'body should include Scope section');\n assert.match(body, /^## Validation/m, 'body should include Validation section');\n assert.match(body, /^## Follow-up Tasks/m, 'body should include Follow-up section');\n assert.match(body, /`v2\\/community\\/faq\\.mdx`/, 'body should include changed file list');\n assert.match(body, /#3457/, 'body should include follow-up issue id');\n });\n\n cases.push(async () => {\n const tmp = mkTmpDir('codex-pr-dry-run-');\n const contractPath = path.join(tmp, 'task-contract.yaml');\n const outputPath = path.join(tmp, 'pr-body.md');\n makeContract(contractPath, 4567);\n\n const run = runScript([\n '--contract',\n contractPath,\n '--output',\n outputPath,\n '--head',\n 'codex/4567-auto-pr-body',\n '--base',\n 'docs-v2',\n '--changed-files',\n 'docs.json',\n '--create',\n '--dry-run'\n ]);\n\n assert.strictEqual(run.status, 0, `dry-run create failed: ${run.stderr || run.stdout}`);\n const output = `${run.stdout}\\n${run.stderr}`;\n assert.match(output, /DRY RUN: gh pr create/, 'dry-run should print gh create command');\n });\n\n for (let index = 0; index < cases.length; index += 1) {\n const name = `case-${index + 1}`;\n try {\n // eslint-disable-next-line no-await-in-loop\n await cases[index]();\n console.log(` ✓ ${name}`);\n } catch (error) {\n failures.push(`${name}: ${error.message}`);\n }\n }\n\n return {\n passed: failures.length === 0,\n total: cases.length,\n errors: failures\n };\n}\n\nif (require.main === module) {\n runTests()\n .then((result) => {\n if (result.passed) {\n console.log(`\\n✅ create-codex-pr tests passed (${result.total} cases)`);\n process.exit(0);\n }\n console.error(`\\n❌ ${result.errors.length} create-codex-pr test failure(s)`);\n result.errors.forEach((entry) => console.error(` - ${entry}`));\n process.exit(1);\n })\n .catch((error) => {\n console.error(`\\n❌ create-codex-pr tests crashed: ${error.message}`);\n process.exit(1);\n });\n}\n\nmodule.exports = { runTests };\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:codex-pr-create"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: test:codex-pr-create)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tests/unit/validate-codex-task-contract.test.js",
+ "script": "validate-codex-task-contract.test",
+ "category": "enforcer",
+ "purpose": "governance:agent-governance",
+ "scope": "tests/unit, tools/scripts/validate-codex-task-contract.js",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Tests validate-codex-task-contract.js — validates contract checking logic",
+ "pipeline_declared": "manual — not yet in pipeline",
+ "usage": "node tests/unit/validate-codex-task-contract.test.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script validate-codex-task-contract.test\n * @category enforcer\n * @purpose governance:agent-governance\n * @scope tests/unit, tools/scripts/validate-codex-task-contract.js\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Tests validate-codex-task-contract.js — validates contract checking logic\n * @pipeline manual — not yet in pipeline\n * @dualmode dual-mode (document flags)\n * @usage node tests/unit/validate-codex-task-contract.test.js [flags]\n */\n\nconst assert = require('assert');\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst REPO_ROOT = process.cwd();\nconst SCRIPT_PATH = path.join(REPO_ROOT, 'tools/scripts/validate-codex-task-contract.js');\n\nfunction mkTmpDir(prefix) {\n return fs.mkdtempSync(path.join(os.tmpdir(), prefix));\n}\n\nfunction writeFile(absPath, content, mode = 0o644) {\n fs.mkdirSync(path.dirname(absPath), { recursive: true });\n fs.writeFileSync(absPath, content, { encoding: 'utf8', mode });\n}\n\nfunction runScript(args, env = {}) {\n return spawnSync('node', [SCRIPT_PATH, ...args], {\n cwd: REPO_ROOT,\n encoding: 'utf8',\n env: {\n ...process.env,\n ...env\n }\n });\n}\n\nfunction writeContract(absPath, taskId, branchName) {\n const content = [\n `task_id: ${taskId}`,\n 'base_branch: docs-v2',\n `branch: ${branchName}`,\n 'scope_in:',\n ' - .codex/task-contract.yaml',\n 'scope_out:',\n ' - v1/',\n 'allowed_generated: []',\n 'acceptance_checks:',\n ' - node tests/run-pr-checks.js --base-ref docs-v2',\n 'risk_flags: []',\n 'follow_up_issues: []',\n ''\n ].join('\\n');\n writeFile(absPath, content);\n}\n\nfunction writeIssuePolicy(absPath) {\n const policy = {\n required_labels: ['docs-v2'],\n required_label_prefixes: ['type:', 'area:', 'classification:', 'priority:'],\n forbidden_labels: ['status: needs-info'],\n required_state: 'open'\n };\n writeFile(absPath, `${JSON.stringify(policy, null, 2)}\\n`);\n}\n\nfunction buildIssuePayload({ state = 'open', labels = [] }) {\n return JSON.stringify({\n state,\n labels: labels.map((name) => ({ name }))\n });\n}\n\nfunction assertFailedWith(result, regex, msg) {\n assert.strictEqual(result.status, 1, msg || 'expected command to fail');\n const combined = `${result.stdout}\\n${result.stderr}`;\n assert.match(combined, regex, `expected output to match ${regex}, got:\\n${combined}`);\n}\n\nasync function runTests() {\n const failures = [];\n\n try {\n const tmp = mkTmpDir('validate-codex-contract-');\n const taskId = 5678;\n const branchName = 'codex/5678-marker-enforcement';\n const contractPath = path.join(tmp, 'task-contract.yaml');\n const prBodyOk = path.join(tmp, 'pr-ok.md');\n const prBodyMissing = path.join(tmp, 'pr-missing.md');\n const prBodyNoClosing = path.join(tmp, 'pr-no-closing.md');\n const prBodyWrongClosing = path.join(tmp, 'pr-wrong-closing.md');\n const issuePolicy = path.join(tmp, 'issue-policy.json');\n\n writeContract(contractPath, taskId, branchName);\n writeIssuePolicy(issuePolicy);\n\n writeFile(\n prBodyOk,\n [\n ``,\n '',\n `Fixes #${taskId}`,\n '',\n '## Scope',\n '',\n '- scope details',\n '',\n '## Validation',\n '',\n '- validation details',\n '',\n '## Follow-up Tasks',\n '',\n '- none',\n ''\n ].join('\\n')\n );\n\n writeFile(\n prBodyNoClosing,\n [\n ``,\n '',\n '## Scope',\n '',\n '- scope details',\n '',\n '## Validation',\n '',\n '- validation details',\n '',\n '## Follow-up Tasks',\n '',\n '- none',\n ''\n ].join('\\n')\n );\n\n writeFile(\n prBodyWrongClosing,\n [\n ``,\n '',\n 'Fixes #9999',\n '',\n '## Scope',\n '',\n '- scope details',\n '',\n '## Validation',\n '',\n '- validation details',\n '',\n '## Follow-up Tasks',\n '',\n '- none',\n ''\n ].join('\\n')\n );\n\n writeFile(\n prBodyMissing,\n [\n '## Scope',\n '',\n '- scope details',\n '',\n '## Validation',\n '',\n '- validation details',\n '',\n '## Follow-up Tasks',\n '',\n '- none',\n ''\n ].join('\\n')\n );\n\n const baseArgs = [\n '--branch',\n branchName,\n '--contract',\n contractPath,\n '--issue-source',\n 'gh',\n '--issue-policy',\n issuePolicy,\n '--issue-number',\n String(taskId),\n '--issue-repo',\n 'livepeer/docs',\n '--validate-contract-only',\n '--require-issue-state'\n ];\n\n const baseEnv = {\n PATH: process.env.PATH\n };\n\n // Marker success\n const ok = runScript([\n '--branch',\n branchName,\n '--contract',\n contractPath,\n '--require-pr-body',\n '--pr-body-file',\n prBodyOk,\n '--files',\n '.codex/task-contract.yaml'\n ]);\n assert.strictEqual(ok.status, 0, `expected marker-valid run to pass: ${ok.stderr || ok.stdout}`);\n console.log(' ✓ marker-valid case passed');\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tests/package.json",
+ "pipeline": "manual",
+ "script_name": "test:codex-task-contract"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: test:codex-task-contract)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/codex-commit.js",
+ "script": "codex-commit",
+ "category": "generator",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts, .githooks, ai-tools/ai-rules",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex commit helper — audits codex branch state and generates compliant commit messages",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/codex-commit.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex-commit\n * @category generator\n * @purpose governance:agent-governance\n * @scope tools/scripts, .githooks, ai-tools/ai-rules\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex commit helper — audits codex branch state and generates compliant commit messages\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @dualmode dual-mode (document flags)\n * @usage node tools/scripts/codex-commit.js [flags]\n */\n\nconst { spawnSync } = require('child_process')\n\nfunction parseArgs(argv) {\n const args = {\n message: '',\n noVerify: false,\n humanOverride: '',\n overrideNote: '',\n trailers: [],\n }\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i]\n if (token === '--message') {\n args.message = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n if (token.startsWith('--message=')) {\n args.message = token.slice('--message='.length).trim()\n continue\n }\n if (token === '--no-verify') {\n args.noVerify = true\n continue\n }\n if (token === '--human-override') {\n args.humanOverride = String(argv[i + 1] || '')\n .trim()\n .toLowerCase()\n i += 1\n continue\n }\n if (token.startsWith('--human-override=')) {\n args.humanOverride = token\n .slice('--human-override='.length)\n .trim()\n .toLowerCase()\n continue\n }\n if (token === '--override-note') {\n args.overrideNote = String(argv[i + 1] || '').trim()\n i += 1\n continue\n }\n if (token.startsWith('--override-note=')) {\n args.overrideNote = token.slice('--override-note='.length).trim()\n continue\n }\n if (token === '--trailer') {\n args.trailers.push(String(argv[i + 1] || '').trim())\n i += 1\n continue\n }\n if (token.startsWith('--trailer=')) {\n args.trailers.push(token.slice('--trailer='.length).trim())\n continue\n }\n if (token === '--help' || token === '-h') {\n args.help = true\n continue\n }\n\n throw new Error(`Unknown argument: ${token}`)\n }\n\n return args\n}\n\nfunction usage() {\n console.log(\n 'Usage: node tools/scripts/codex-commit.js --message [--no-verify --human-override true --override-note ] [--trailer ]'\n )\n}\n\nfunction validateArgs(args) {\n if (!args.message) {\n throw new Error('--message is required')\n }\n\n if (!args.noVerify) {\n return\n }\n\n if (args.humanOverride !== 'true') {\n throw new Error('--human-override true is required when using --no-verify')\n }\n\n if (!args.overrideNote) {\n throw new Error('--override-note is required when using --no-verify')\n }\n\n if (String(process.env.ALLOW_HUMAN_NO_VERIFY || '').trim() !== '1') {\n throw new Error(\n 'ALLOW_HUMAN_NO_VERIFY=1 is required for --no-verify override path'\n )\n }\n}\n\nfunction runCommit(args) {\n const gitArgs = ['commit', '-m', args.message]\n\n if (args.noVerify) {\n gitArgs.push('--no-verify')\n gitArgs.push('--trailer', 'human-override=no-verify')\n gitArgs.push('--trailer', `override-note=${args.overrideNote}`)\n }\n\n args.trailers.forEach((trailer) => {\n if (!trailer) return\n gitArgs.push('--trailer', trailer)\n })\n\n const result = spawnSync('git', gitArgs, { stdio: 'inherit' })\n return result.status === 0\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2))\n if (args.help) {\n usage()\n process.exit(0)\n }\n\n validateArgs(args)\n const ok = runCommit(args)\n if (!ok) {\n process.exit(1)\n }\n\n if (args.noVerify) {\n console.log('✅ Commit created with audited human no-verify override')\n } else {\n console.log('✅ Commit created')\n }\n}\n\nif (require.main === module) {\n try {\n main()\n } catch (error) {\n console.error(`❌ ${error.message}`)\n process.exit(1)\n }\n}\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/codex-safe-merge-with-stash.js",
+ "script": "codex-safe-merge-with-stash",
+ "category": "utility",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex merge utility — safely merges branches with stash handling to avoid codex conflicts",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/codex-safe-merge-with-stash.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex-safe-merge-with-stash\n * @category utility\n * @purpose governance:agent-governance\n * @scope tools/scripts\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex merge utility — safely merges branches with stash handling to avoid codex conflicts\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/codex-safe-merge-with-stash.js [flags]\n */\n\nconst { spawnSync } = require('child_process');\n\nfunction parseArgs(argv) {\n const args = {\n target: '',\n stashUntracked: true,\n dryRun: false,\n json: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--target') {\n args.target = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--target=')) {\n args.target = token.slice('--target='.length).trim();\n continue;\n }\n if (token === '--stash-untracked') {\n args.stashUntracked = true;\n continue;\n }\n if (token === '--no-stash-untracked') {\n args.stashUntracked = false;\n continue;\n }\n if (token === '--dry-run') {\n args.dryRun = true;\n continue;\n }\n if (token === '--json') {\n args.json = true;\n continue;\n }\n if (token === '--help' || token === '-h') {\n printUsage();\n process.exit(0);\n }\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!args.target) {\n throw new Error('Missing required --target ');\n }\n\n return args;\n}\n\nfunction printUsage() {\n console.log('Usage: node tools/scripts/codex-safe-merge-with-stash.js --target [--dry-run] [--json]');\n}\n\nfunction runGit(args, options = {}) {\n const res = spawnSync('git', args, {\n encoding: 'utf8',\n ...options\n });\n return {\n status: res.status,\n stdout: String(res.stdout || ''),\n stderr: String(res.stderr || ''),\n ok: res.status === 0\n };\n}\n\nfunction runGitOrThrow(args, options = {}) {\n const res = runGit(args, options);\n if (!res.ok) {\n const detail = (res.stderr || res.stdout).trim() || `git ${args.join(' ')} failed`;\n throw new Error(detail);\n }\n return res.stdout.trim();\n}\n\nfunction hasOriginRemote() {\n const res = runGit(['remote', 'get-url', 'origin']);\n return res.ok;\n}\n\nfunction getStashRefByMessage(marker) {\n const list = runGitOrThrow(['stash', 'list', '--format=%gd|%s']);\n if (!list) return '';\n const line = list\n .split('\\n')\n .map((entry) => entry.trim())\n .find((entry) => entry.includes(marker));\n if (!line) return '';\n return line.split('|')[0].trim();\n}\n\nfunction getGitStatusPorcelain() {\n return runGitOrThrow(['status', '--porcelain']);\n}\n\nfunction printResult(result, jsonMode) {\n if (jsonMode) {\n process.stdout.write(`${JSON.stringify(result, null, 2)}\\n`);\n return;\n }\n\n const statusIcon = result.passed ? '✅' : '❌';\n console.log(`${statusIcon} ${result.message}`);\n if (result.actions && result.actions.length > 0) {\n result.actions.forEach((action) => console.log(` - ${action}`));\n }\n if (result.recovery && result.recovery.length > 0) {\n console.log('Recovery steps:');\n result.recovery.forEach((line) => console.log(` - ${line}`));\n }\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2));\n const actions = [];\n const recovery = [];\n\n try {\n const branch = runGitOrThrow(['rev-parse', '--abbrev-ref', 'HEAD']);\n const dirty = getGitStatusPorcelain().trim().length > 0;\n const marker = `codex-safe-merge:${new Date().toISOString()}:${args.target}`;\n let stashRef = '';\n\n if (args.dryRun) {\n actions.push(`would evaluate dirty tree on branch ${branch}`);\n if (dirty) {\n actions.push(\n `would run git stash push ${args.stashUntracked ? '-u ' : ''}-m \"${marker}\"`\n );\n }\n if (hasOriginRemote()) {\n actions.push(`would run git fetch origin ${args.target}`);\n }\n actions.push(`would run git merge --no-edit ${args.target}`);\n if (dirty) {\n actions.push('would run git stash pop after successful merge');\n }\n\n printResult(\n {\n passed: true,\n message: 'Dry-run completed.',\n branch,\n target: args.target,\n dirty,\n actions,\n recovery\n },\n args.json\n );\n process.exit(0);\n }\n\n if (dirty) {\n const stashArgs = ['stash', 'push'];\n if (args.stashUntracked) stashArgs.push('-u');\n stashArgs.push('-m', marker);\n runGitOrThrow(stashArgs);\n stashRef = getStashRefByMessage(marker);\n actions.push(`stashed local changes as ${stashRef || marker}`);\n }\n\n if (hasOriginRemote()) {\n const fetchRes = runGit(['fetch', 'origin', args.target]);\n if (!fetchRes.ok) {\n actions.push(`fetch skipped/failed for target ${args.target}; proceeding with local refs`);\n } else {\n actions.push(`fetched target from origin: ${args.target}`);\n }\n }\n\n const mergeRes = runGit(['merge', '--no-edit', args.target]);\n if (!mergeRes.ok) {\n actions.push(`merge failed for target ${args.target}`);\n recovery.push('Resolve or abort merge explicitly (for example: git merge --abort).');\n if (stashRef) {\n recovery.push(`Stashed changes are preserved in ${stashRef}. Apply later with: git stash pop ${stashRef}`);\n }\n\n printResult(\n {\n passed: false,\n message: `Merge failed for target ${args.target}.`,\n branch,\n target: args.target,\n dirty,\n stashRef,\n actions,\n recovery\n },\n args.json\n );\n process.exit(1);\n }\n\n actions.push(`merged target ${args.target} into ${branch}`);\n\n if (stashRef) {\n const popRes = runGit(['stash', 'pop', stashRef]);\n if (!popRes.ok) {\n actions.push(`stash pop failed for ${stashRef}`);\n recovery.push('Resolve stash-pop conflicts and stage resolved files manually.');\n recovery.push(`If needed, stash remains available as ${stashRef}.`);\n\n printResult(",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/codex/lock-release.js",
+ "script": "codex/lock-release",
+ "category": "utility",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts/codex, .codex/locks-local, .codex/task-contract.yaml",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex lock release utility — releases stale codex lock files",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/codex/lock-release.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex/lock-release\n * @category utility\n * @purpose governance:agent-governance\n * @scope tools/scripts/codex, .codex/locks-local, .codex/task-contract.yaml\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex lock release utility — releases stale codex lock files\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/codex/lock-release.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\nconst yaml = require('js-yaml');\n\nconst LOCK_DIR_REL = '.codex/locks-local';\nconst DEFAULT_CONTRACT = '.codex/task-contract.yaml';\n\nconst REPO_ROOT = getRepoRoot();\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction runGit(args) {\n const result = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });\n if (result.status !== 0) {\n const stderr = String(result.stderr || '').trim();\n const stdout = String(result.stdout || '').trim();\n throw new Error(stderr || stdout || `git ${args.join(' ')} failed`);\n }\n return String(result.stdout || '').trim();\n}\n\nfunction parseArgs(argv) {\n const args = {\n branch: '',\n lockId: '',\n contractPath: DEFAULT_CONTRACT\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--branch') {\n args.branch = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--branch=')) {\n args.branch = token.slice('--branch='.length).trim();\n continue;\n }\n if (token === '--lock-id') {\n args.lockId = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--lock-id=')) {\n args.lockId = token.slice('--lock-id='.length).trim();\n continue;\n }\n if (token === '--contract') {\n args.contractPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--contract=')) {\n args.contractPath = token.slice('--contract='.length).trim();\n continue;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n return args;\n}\n\nfunction usage() {\n console.log('Usage: node tools/scripts/codex/lock-release.js [--branch ] [--lock-id ] [--contract ]');\n}\n\nfunction detectBranch(args) {\n if (args.branch) return args.branch;\n\n const contractAbs = path.resolve(REPO_ROOT, args.contractPath);\n if (fs.existsSync(contractAbs)) {\n try {\n const parsed = yaml.load(fs.readFileSync(contractAbs, 'utf8'));\n const contractBranch = String(parsed && parsed.branch ? parsed.branch : '').trim();\n if (contractBranch) return contractBranch;\n } catch (_error) {\n // ignore and fallback to git branch detection\n }\n }\n\n return runGit(['rev-parse', '--abbrev-ref', 'HEAD']);\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2));\n if (args.help) {\n usage();\n process.exit(0);\n }\n\n const branch = detectBranch(args);\n const lockDirAbs = path.join(REPO_ROOT, LOCK_DIR_REL);\n if (!fs.existsSync(lockDirAbs)) {\n throw new Error(`Lock directory not found: ${LOCK_DIR_REL}`);\n }\n\n const entries = fs.readdirSync(lockDirAbs, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith('.json'));\n let releasedCount = 0;\n\n entries.forEach((entry) => {\n const abs = path.join(lockDirAbs, entry.name);\n let lock;\n try {\n lock = JSON.parse(fs.readFileSync(abs, 'utf8'));\n } catch (_error) {\n return;\n }\n\n if (args.lockId && String(lock.lock_id || '') !== args.lockId) {\n return;\n }\n\n if (!args.lockId && String(lock.branch || '') !== branch) {\n return;\n }\n\n if (String(lock.status || '') === 'released') {\n releasedCount += 1;\n return;\n }\n\n lock.status = 'released';\n lock.released_at = new Date().toISOString();\n fs.writeFileSync(abs, `${JSON.stringify(lock, null, 2)}\\n`, 'utf8');\n releasedCount += 1;\n });\n\n if (releasedCount === 0) {\n throw new Error(args.lockId ? `No lock found for lock_id=${args.lockId}` : `No active lock found for branch ${branch}`);\n }\n\n console.log(`✅ Released ${releasedCount} lock(s) for ${args.lockId ? `lock_id=${args.lockId}` : branch}`);\n}\n\nif (require.main === module) {\n try {\n main();\n } catch (error) {\n console.error(`❌ ${error.message}`);\n process.exit(1);\n }\n}\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/codex/.codex/locks-local",
+ "type": "directory",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/codex/.codex/locks-local",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/codex/task-finalize.js",
+ "script": "codex/task-finalize",
+ "category": "enforcer",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts/codex, tools/scripts/validate-codex-task-contract.js, tools/scripts/verify-pay-orc-gate-finalize.sh",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex task finaliser — enforces task completion requirements before closing",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/codex/task-finalize.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script codex/task-finalize\n * @category enforcer\n * @purpose governance:agent-governance\n * @scope tools/scripts/codex, tools/scripts/validate-codex-task-contract.js, tools/scripts/verify-pay-orc-gate-finalize.sh\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex task finaliser — enforces task completion requirements before closing\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/codex/task-finalize.js [flags]\n */\n\nconst { spawnSync } = require('child_process');\nconst path = require('path');\n\nconst REPO_ROOT = getRepoRoot();\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nfunction run(command, args) {\n const result = spawnSync(command, args, { cwd: REPO_ROOT, encoding: 'utf8' });\n if (result.stdout) process.stdout.write(result.stdout);\n if (result.stderr) process.stderr.write(result.stderr);\n return result.status === 0;\n}\n\nfunction parseArgs(argv) {\n const args = {\n branch: '',\n contractPath: '.codex/task-contract.yaml',\n baseRef: '',\n profile: ''\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--branch') {\n args.branch = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--branch=')) {\n args.branch = token.slice('--branch='.length).trim();\n continue;\n }\n if (token === '--contract') {\n args.contractPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--contract=')) {\n args.contractPath = token.slice('--contract='.length).trim();\n continue;\n }\n if (token === '--base-ref') {\n args.baseRef = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--base-ref=')) {\n args.baseRef = token.slice('--base-ref='.length).trim();\n continue;\n }\n if (token === '--profile') {\n args.profile = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--profile=')) {\n args.profile = token.slice('--profile='.length).trim();\n continue;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n return args;\n}\n\nfunction usage() {\n console.log('Usage: node tools/scripts/codex/task-finalize.js [--branch ] [--contract ] [--base-ref ] [--profile pay-orc-gate]');\n}\n\nfunction detectBranch(explicitBranch) {\n if (explicitBranch) return explicitBranch;\n const fromEnv = String(process.env.GITHUB_HEAD_REF || '').trim();\n if (fromEnv) return fromEnv;\n const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: REPO_ROOT, encoding: 'utf8' });\n return result.status === 0 ? String(result.stdout || '').trim() : '';\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2));\n if (args.help) {\n usage();\n process.exit(0);\n }\n\n const branch = detectBranch(args.branch);\n if (!branch) {\n throw new Error('Unable to detect branch; pass --branch explicitly');\n }\n\n const contractCheckArgs = ['tools/scripts/validate-codex-task-contract.js', '--branch', branch, '--contract', args.contractPath];\n if (args.baseRef) {\n contractCheckArgs.push('--base-ref', args.baseRef);\n }\n\n console.log('🔍 Running contract scope check...');\n if (!run('node', contractCheckArgs)) {\n throw new Error('Contract scope check failed');\n }\n\n console.log('🔍 Running local lock check...');\n if (!run('node', ['tools/scripts/codex/validate-locks.js', '--branch', branch])) {\n throw new Error('Local lock check failed');\n }\n\n if (args.profile) {\n if (args.profile === 'pay-orc-gate') {\n console.log('🔍 Running finalize profile: pay-orc-gate...');\n if (!run('bash', ['tools/scripts/verify-pay-orc-gate-finalize.sh'])) {\n throw new Error('Finalize profile pay-orc-gate failed');\n }\n } else {\n throw new Error(`Unknown finalize profile: ${args.profile}`);\n }\n }\n\n console.log('✅ Codex task finalize checks passed');\n console.log('ℹ️ Next step: node tools/scripts/codex/lock-release.js');\n}\n\nif (require.main === module) {\n try {\n main();\n } catch (error) {\n console.error(`❌ ${error.message}`);\n process.exit(1);\n }\n}\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/create-codex-pr.js",
+ "script": "create-codex-pr",
+ "category": "generator",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts, .codex/task-contract.yaml",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex PR creator — generates codex PR with correct branch naming, labels, and body template",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/create-codex-pr.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script create-codex-pr\n * @category generator\n * @purpose governance:agent-governance\n * @scope tools/scripts, .codex/task-contract.yaml\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex PR creator — generates codex PR with correct branch naming, labels, and body template\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/create-codex-pr.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\nconst yaml = require('js-yaml');\n\nconst DEFAULT_CONTRACT_PATH = '.codex/task-contract.yaml';\nconst DEFAULT_OUTPUT_PATH = '.codex/pr-body.generated.md';\nconst DEFAULT_BASE_BRANCH = 'docs-v2';\nconst CODEX_BRANCH_RE = /^codex\\/(\\d+)-([a-z0-9][a-z0-9-]*)$/;\nconst PR_GENERATOR_MARKER_PREFIX = 'codex-pr-body-generated';\n\nconst REPO_ROOT = getRepoRoot();\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction parseCsv(raw) {\n if (!raw) return [];\n return [...new Set(String(raw).split(',').map((entry) => toPosix(entry.trim())).filter(Boolean))];\n}\n\nfunction usage() {\n const lines = [\n 'Usage: node tools/scripts/create-codex-pr.js [options]',\n '',\n 'Options:',\n ' --contract Task contract path (default: .codex/task-contract.yaml)',\n ' --output PR body output path (default: .codex/pr-body.generated.md)',\n ' --title Optional PR title override',\n ' --base Optional base branch override',\n ' --head Optional head branch override',\n ' --changed-files Optional explicit changed file list',\n ' --create Run gh pr create with generated body',\n ' --draft Create PR as draft (requires --create)',\n ' --dry-run Print gh command instead of executing',\n ' --json Emit JSON output',\n ' --help Show this help message'\n ];\n console.log(lines.join('\\n'));\n}\n\nfunction parseArgs(argv) {\n const args = {\n contractPath: DEFAULT_CONTRACT_PATH,\n outputPath: DEFAULT_OUTPUT_PATH,\n title: '',\n base: '',\n head: '',\n changedFiles: null,\n create: false,\n draft: false,\n dryRun: false,\n json: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n if (token === '--contract') {\n args.contractPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--contract=')) {\n args.contractPath = token.slice('--contract='.length).trim();\n continue;\n }\n\n if (token === '--output') {\n args.outputPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--output=')) {\n args.outputPath = token.slice('--output='.length).trim();\n continue;\n }\n\n if (token === '--title') {\n args.title = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--title=')) {\n args.title = token.slice('--title='.length).trim();\n continue;\n }\n\n if (token === '--base') {\n args.base = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--base=')) {\n args.base = token.slice('--base='.length).trim();\n continue;\n }\n\n if (token === '--head') {\n args.head = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--head=')) {\n args.head = token.slice('--head='.length).trim();\n continue;\n }\n\n if (token === '--changed-files') {\n args.changedFiles = parseCsv(argv[i + 1] || '');\n i += 1;\n continue;\n }\n if (token.startsWith('--changed-files=')) {\n args.changedFiles = parseCsv(token.slice('--changed-files='.length));\n continue;\n }\n\n if (token === '--create') {\n args.create = true;\n continue;\n }\n if (token === '--draft') {\n args.draft = true;\n continue;\n }\n if (token === '--dry-run') {\n args.dryRun = true;\n continue;\n }\n if (token === '--json') {\n args.json = true;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (args.draft && !args.create) {\n throw new Error('--draft requires --create');\n }\n\n return args;\n}\n\nfunction runGit(args) {\n const result = spawnSync('git', args, {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n if (result.status !== 0) {\n const stderr = String(result.stderr || '').trim();\n const stdout = String(result.stdout || '').trim();\n throw new Error(stderr || stdout || `git ${args.join(' ')} failed`);\n }\n return String(result.stdout || '').trim();\n}\n\nfunction tryRunGit(args) {\n try {\n return runGit(args);\n } catch (_error) {\n return '';\n }\n}\n\nfunction normalizeStringArray(value, fieldName, required = false) {\n if (value == null) {\n if (required) throw new Error(`\"${fieldName}\" is required and must be a non-empty array`);\n return [];\n }\n\n if (!Array.isArray(value)) {\n throw new Error(`\"${fieldName}\" must be an array`);\n }\n\n const normalized = value\n .map((entry) => String(entry == null ? '' : entry).trim())\n .filter(Boolean);\n\n if (required && normalized.length === 0) {\n throw new Error(`\"${fieldName}\" must include at least one entry`);\n }\n\n return normalized;\n}\n\nfunction normalizeIntegerArray(value, fieldName) {\n if (value == null) return [];\n if (!Array.isArray(value)) {\n throw new Error(`\"${fieldName}\" must be an array of integers`);\n }\n const normalized = [];\n value.forEach((entry) => {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "codex:pr"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: codex:pr)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/cross-agent-packager.js",
+ "script": "cross-agent-packager",
+ "category": "generator",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts, ai-tools/ai-skills/catalog, ai-tools/agent-packs",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Cross-agent packager — bundles audit reports and repo state into agent-consumable packages",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/cross-agent-packager.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script cross-agent-packager\n * @category generator\n * @purpose governance:agent-governance\n * @scope tools/scripts, ai-tools/ai-skills/catalog, ai-tools/agent-packs\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Cross-agent packager — bundles audit reports and repo state into agent-consumable packages\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/cross-agent-packager.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\n\nconst STAGE_ID = 'cross-agent-packager';\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_OUTPUT_DIR = 'ai-tools/agent-packs';\nconst DEFAULT_CATALOG_PATH = 'ai-tools/ai-skills/catalog/skill-catalog.json';\nconst DEFAULT_MANIFEST_PATH = 'ai-tools/ai-skills/catalog/execution-manifest.json';\nconst VALID_PACKS = new Set(['codex', 'cursor', 'claude', 'windsurf', 'all']);\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction parseArgs(argv) {\n const out = {\n agentPack: 'all',\n outputDir: DEFAULT_OUTPUT_DIR,\n catalogPath: DEFAULT_CATALOG_PATH,\n manifestPath: DEFAULT_MANIFEST_PATH\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--agent-pack') {\n out.agentPack = String(argv[i + 1] || out.agentPack).trim() || out.agentPack;\n i += 1;\n continue;\n }\n if (token.startsWith('--agent-pack=')) {\n out.agentPack = token.slice('--agent-pack='.length).trim() || out.agentPack;\n continue;\n }\n if (token === '--output-dir') {\n out.outputDir = String(argv[i + 1] || out.outputDir).trim() || out.outputDir;\n i += 1;\n continue;\n }\n if (token.startsWith('--output-dir=')) {\n out.outputDir = token.slice('--output-dir='.length).trim() || out.outputDir;\n continue;\n }\n if (token === '--catalog') {\n out.catalogPath = String(argv[i + 1] || out.catalogPath).trim() || out.catalogPath;\n i += 1;\n continue;\n }\n if (token.startsWith('--catalog=')) {\n out.catalogPath = token.slice('--catalog='.length).trim() || out.catalogPath;\n continue;\n }\n if (token === '--manifest') {\n out.manifestPath = String(argv[i + 1] || out.manifestPath).trim() || out.manifestPath;\n i += 1;\n continue;\n }\n if (token.startsWith('--manifest=')) {\n out.manifestPath = token.slice('--manifest='.length).trim() || out.manifestPath;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!VALID_PACKS.has(out.agentPack)) {\n throw new Error(`Invalid --agent-pack value: ${out.agentPack}`);\n }\n\n return out;\n}\n\nfunction readJson(repoPath) {\n return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8'));\n}\n\nfunction mdEscape(value) {\n return String(value || '').replace(/\\|/g, '\\\\|').replace(/\\n/g, ' ');\n}\n\nfunction pickPipelineSkills(catalog, manifest) {\n const skillMap = new Map((catalog.skills || []).map((skill) => [skill.id, skill]));\n const pipeline = Array.isArray(manifest.pipeline) ? manifest.pipeline : [];\n\n return pipeline\n .slice()\n .sort((a, b) => Number(a.run_order || 0) - Number(b.run_order || 0))\n .map((entry) => ({\n ...entry,\n skill: skillMap.get(entry.id) || null\n }))\n .filter((entry) => entry.skill);\n}\n\nfunction buildTopReadme(pipelineSkills) {\n const lines = [];\n lines.push('# Agent Packs');\n lines.push('');\n lines.push('This folder contains generated packs for running the same docs audit pipeline across supported coding agents.');\n lines.push('');\n lines.push('## Pipeline Stages');\n lines.push('');\n lines.push('| Order | Skill ID | Goal |');\n lines.push('|---:|---|---|');\n\n pipelineSkills.forEach((entry) => {\n lines.push(`| ${entry.run_order} | \\`${mdEscape(entry.id)}\\` | ${mdEscape(entry.skill.goal)} |`);\n });\n\n lines.push('');\n lines.push('Generated by: `node tools/scripts/cross-agent-packager.js --agent-pack all`');\n lines.push('');\n return `${lines.join('\\n')}\\n`;\n}\n\nfunction writeCodexPack(baseDirAbs, pipelineSkills, catalog, manifest) {\n const packDir = path.join(baseDirAbs, 'codex');\n ensureDir(packDir);\n\n const payload = {\n generated_at: new Date().toISOString(),\n source_catalog: DEFAULT_CATALOG_PATH,\n source_manifest: DEFAULT_MANIFEST_PATH,\n pipeline: pipelineSkills.map((entry) => ({\n run_order: entry.run_order,\n id: entry.id,\n goal: entry.skill.goal,\n commands: entry.skill.commands,\n outputs: entry.skill.outputs,\n severity_model: entry.skill.severity_model,\n autofix_mode: entry.skill.autofix_mode\n })),\n catalog_version: catalog.version,\n manifest_version: manifest.version\n };\n\n const manifestPath = path.join(packDir, 'skills-manifest.json');\n fs.writeFileSync(manifestPath, `${JSON.stringify(payload, null, 2)}\\n`);\n\n return [toPosix(path.relative(REPO_ROOT, manifestPath))];\n}\n\nfunction buildRulePackMarkdown(agentName, pipelineSkills) {\n const lines = [];\n lines.push(`# ${agentName} Repo Audit Pack`);\n lines.push('');\n lines.push('Use these stages in order for a static-first docs infrastructure audit pipeline.');\n lines.push('');\n\n pipelineSkills.forEach((entry) => {\n lines.push(`## ${entry.run_order}. ${entry.id}`);\n lines.push('');\n lines.push(`- Goal: ${entry.skill.goal}`);\n lines.push(`- Severity Model: ${entry.skill.severity_model}`);\n lines.push(`- Autofix Mode: ${entry.skill.autofix_mode}`);\n lines.push('- Commands:');\n (entry.skill.commands || []).forEach((command) => {\n lines.push(` - \\`${command.run}\\``);\n });\n lines.push('- Outputs:');\n (entry.skill.outputs || []).forEach((output) => {\n lines.push(` - \\`${output}\\``);\n });\n lines.push('');\n });\n\n lines.push('Run source: `node tools/scripts/cross-agent-packager.js --agent-pack all`');\n lines.push('');\n return `${lines.join('\\n')}\\n`;\n}\n\nfunction writeCursorPack(baseDirAbs, pipelineSkills) {\n const packDir = path.join(baseDirAbs, 'cursor');\n ensureDir(packDir);\n\n const rulesPath = path.join(packDir, 'rules.md');\n fs.writeFileSync(rulesPath, buildRulePackMarkdown('Cursor', pipelineSkills));\n\n return [toPosix(path.relative(REPO_ROOT, rulesPath))];\n}\n\nfunction writeClaudePack(baseDirAbs, pipelineSkills) {\n const packDir = path.join(baseDirAbs, 'claude');\n ensureDir(packDir);\n\n const claudePath = path.join(packDir, 'CLAUDE.md');\n fs.writeFileSync(claudePath, buildRulePackMarkdown('Claude Code', pipelineSkills));\n\n return [toPosix(path.relative(REPO_ROOT, claudePath))];\n}\n\nfunction writeWindsurfPack(baseDirAbs, pipelineSkills) {\n const packDir = path.join(baseDirAbs, 'windsurf');\n ensureDir(packDir);\n\n const rulesPath = path.join(packDir, 'rules.md');\n fs.writeFileSync(rulesPath, buildRulePackMarkdown('Windsurf', pipelineSkills));\n\n return [toPosix(path.relative(REPO_ROOT, rulesPath))];\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2));",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "pack:agents"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/skills-manifest.json",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/rules.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/CLAUDE.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ },
+ {
+ "output_path": "tools/scripts/README.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/skills-manifest.json, tools/scripts/rules.md, tools/scripts/CLAUDE.md, tools/scripts/README.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: pack:agents)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/sync-codex-skills.js",
+ "script": "sync-codex-skills",
+ "category": "automation",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts, ai-tools/ai-skills/templates, tests/unit/codex-skill-sync.test.js",
+ "owner": "docs",
+ "needs": "R-R27, R-R30",
+ "purpose_statement": "Codex skills sync — synchronises skill definition files between local and remote sources. Supports --check mode.",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/sync-codex-skills.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script sync-codex-skills\n * @category automation\n * @purpose governance:agent-governance\n * @scope tools/scripts, ai-tools/ai-skills/templates, tests/unit/codex-skill-sync.test.js\n * @owner docs\n * @needs R-R27, R-R30\n * @purpose-statement Codex skills sync — synchronises skill definition files between local and remote sources. Supports --check mode.\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/sync-codex-skills.js [flags]\n */\n\nconst fs = require('fs');\nconst os = require('os');\nconst path = require('path');\nconst yaml = require('js-yaml');\n\nconst REPO_ROOT = process.cwd();\nconst DEFAULT_SOURCE_DIR = 'ai-tools/ai-skills/templates';\nconst TEMPLATE_SUFFIX = '.template.md';\nconst TEMPLATE_FILE_RE = /^\\d{2}-[a-z0-9-]+\\.template\\.md$/;\nconst SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;\n\nconst REQUIRED_FRONTMATTER_KEYS = [\n 'name',\n 'description',\n 'tier',\n 'triggers',\n 'primary_paths',\n 'primary_commands'\n];\n\nconst REQUIRED_SECTIONS = [\n 'SKILL:',\n 'Goal',\n 'Constraints',\n 'Workflow',\n 'Deliverable Format',\n 'Failure Modes / Fallback',\n 'Validation Checklist'\n];\n\nconst ACRONYMS = new Set(['GH', 'MCP', 'API', 'CI', 'CLI', 'LLM', 'PDF', 'PR', 'UI', 'URL', 'SQL', 'SEO', 'MDX', 'WCAG', 'LPD', 'N8N']);\nconst BRANDS = new Map([\n ['openai', 'OpenAI'],\n ['openapi', 'OpenAPI'],\n ['github', 'GitHub'],\n ['mintlify', 'Mintlify'],\n ['codex', 'Codex'],\n ['cspell', 'cspell']\n]);\nconst SMALL_WORDS = new Set(['and', 'or', 'to', 'up', 'with', 'of', 'for']);\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction usage() {\n const msg = [\n 'Usage: node tools/scripts/sync-codex-skills.js [options]',\n '',\n 'Options:',\n ' --source-dir Canonical template directory',\n ' --dest Destination Codex skills directory',\n ' --check Validation-only mode (no writes; fails on drift)',\n ' --dry-run Print planned changes without writing',\n ' --skills Optional subset by template frontmatter name',\n ' --openai-yaml Generate/open update agents/openai.yaml (default)',\n ' --no-openai-yaml Skip agents/openai.yaml generation',\n ' --help Show this message'\n ];\n console.log(msg.join('\\n'));\n}\n\nfunction parseSkillsList(raw) {\n if (!raw) return null;\n const values = String(raw)\n .split(',')\n .map((item) => item.trim())\n .filter(Boolean);\n if (values.length === 0) return null;\n return [...new Set(values)];\n}\n\nfunction resolveDefaultDest() {\n const codexHome = String(process.env.CODEX_HOME || '').trim();\n if (codexHome) return path.join(codexHome, 'skills');\n return path.join(os.homedir(), '.codex', 'skills');\n}\n\nfunction parseArgs(argv) {\n const out = {\n sourceDir: path.resolve(REPO_ROOT, DEFAULT_SOURCE_DIR),\n dest: path.resolve(resolveDefaultDest()),\n check: false,\n dryRun: false,\n skills: null,\n openaiYaml: true\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--help' || token === '-h') {\n out.help = true;\n continue;\n }\n\n if (token === '--source-dir') {\n out.sourceDir = path.resolve(REPO_ROOT, String(argv[i + 1] || '').trim());\n i += 1;\n continue;\n }\n if (token.startsWith('--source-dir=')) {\n out.sourceDir = path.resolve(REPO_ROOT, token.slice('--source-dir='.length).trim());\n continue;\n }\n\n if (token === '--dest') {\n out.dest = path.resolve(REPO_ROOT, String(argv[i + 1] || '').trim());\n i += 1;\n continue;\n }\n if (token.startsWith('--dest=')) {\n out.dest = path.resolve(REPO_ROOT, token.slice('--dest='.length).trim());\n continue;\n }\n\n if (token === '--skills') {\n out.skills = parseSkillsList(argv[i + 1] || '');\n i += 1;\n continue;\n }\n if (token.startsWith('--skills=')) {\n out.skills = parseSkillsList(token.slice('--skills='.length));\n continue;\n }\n\n if (token === '--check') {\n out.check = true;\n continue;\n }\n if (token === '--dry-run') {\n out.dryRun = true;\n continue;\n }\n if (token === '--openai-yaml') {\n out.openaiYaml = true;\n continue;\n }\n if (token === '--no-openai-yaml') {\n out.openaiYaml = false;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n return out;\n}\n\nfunction splitFrontmatter(content, filePath) {\n const match = content.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n/);\n if (!match) {\n throw new Error(`${toPosix(filePath)}: missing or invalid YAML frontmatter`);\n }\n return {\n frontmatterRaw: match[1],\n body: content.slice(match[0].length)\n };\n}\n\nfunction escapeRegExp(value) {\n return String(value || '').replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\nfunction requireSection(body, sectionTitle, filePath) {\n const re = new RegExp(`^${escapeRegExp(sectionTitle)}(?:\\\\b|\\\\s|:)`, 'm');\n if (!re.test(body)) {\n throw new Error(`${toPosix(filePath)}: missing required section \"${sectionTitle}\"`);\n }\n}\n\nfunction assertArrayCount(value, minCount, field, filePath) {\n if (!Array.isArray(value)) {\n throw new Error(`${toPosix(filePath)}: frontmatter \"${field}\" must be an array`);\n }\n if (value.length < minCount) {\n throw new Error(`${toPosix(filePath)}: frontmatter \"${field}\" must have at least ${minCount} entries`);\n }\n}\n\nfunction parseTemplateFile(filePathAbs) {\n const content = fs.readFileSync(filePathAbs, 'utf8');\n const { frontmatterRaw, body } = splitFrontmatter(content, filePathAbs);\n let frontmatter;\n\n try {\n frontmatter = yaml.load(frontmatterRaw);\n } catch (error) {\n throw new Error(`${toPosix(filePathAbs)}: invalid frontmatter YAML (${error.message})`);\n }\n\n if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {\n throw new Error(`${toPosix(filePathAbs)}: frontmatter must be a YAML object`);\n }\n\n for (const key of REQUIRED_FRONTMATTER_KEYS) {\n if (!(key in frontmatter)) {\n throw new Error(`${toPosix(filePathAbs)}: missing required frontmatter key \"${key}\"`);\n }\n }\n\n const name = String(frontmatter.name || '').trim();\n if (!name) {\n throw new Error(`${toPosix(filePathAbs)}: frontmatter \"name\" must be non-empty`);\n }\n if (!SKILL_NAME_RE.test(name)) {\n throw new Error(`${toPosix(filePathAbs)}: frontmatter \"name\" must match ${SKILL_NAME_RE}`);\n }",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "skills:sync:codex"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "skills:sync:codex:check"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/SKILL.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/SKILL.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: skills:sync:codex); manual (npm script: skills:sync:codex:check)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/validators/governance/check-agent-docs-freshness.js",
+ "script": "check-agent-docs-freshness",
+ "category": "validator",
+ "purpose": "governance:agent-governance",
+ "scope": "tools/scripts/validators/governance, .github, ai-tools/ai-skills, contribute",
+ "owner": "docs",
+ "needs": "R-R14, R-R18",
+ "purpose_statement": "Validates that required agent governance docs exist and have been touched within a freshness threshold",
+ "pipeline_declared": "manual, ci",
+ "usage": "node tools/scripts/validators/governance/check-agent-docs-freshness.js [--threshold ] [--json]",
+ "header": "#!/usr/bin/env node\n/**\n * @script check-agent-docs-freshness\n * @category validator\n * @purpose governance:agent-governance\n * @scope tools/scripts/validators/governance, .github, ai-tools/ai-skills, contribute\n * @owner docs\n * @needs R-R14, R-R18\n * @purpose-statement Validates that required agent governance docs exist and have been touched within a freshness threshold\n * @pipeline manual, ci\n * @usage node tools/scripts/validators/governance/check-agent-docs-freshness.js [--threshold ] [--json]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { spawnSync } = require('child_process');\n\nconst DEFAULT_THRESHOLD_DAYS = 90;\nconst REPO_ROOT = getRepoRoot();\n\nfunction getRepoRoot() {\n const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n if (result.status === 0 && String(result.stdout || '').trim()) {\n return String(result.stdout || '').trim();\n }\n return process.cwd();\n}\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction usage() {\n console.log(\n 'Usage: node tools/scripts/validators/governance/check-agent-docs-freshness.js [--threshold ] [--json]'\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n thresholdDays: DEFAULT_THRESHOLD_DAYS,\n json: false\n };\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n\n if (token === '--threshold') {\n args.thresholdDays = Number(argv[index + 1]);\n index += 1;\n continue;\n }\n\n if (token.startsWith('--threshold=')) {\n args.thresholdDays = Number(token.slice('--threshold='.length));\n continue;\n }\n\n if (token === '--json') {\n args.json = true;\n continue;\n }\n\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!Number.isFinite(args.thresholdDays) || args.thresholdDays < 0) {\n throw new Error('Threshold must be a non-negative number of days');\n }\n\n return args;\n}\n\nfunction runGit(args) {\n const result = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });\n if (result.status !== 0) {\n return '';\n }\n return String(result.stdout || '').trim();\n}\n\nfunction getGitTimestamp(repoPath) {\n const output = runGit(['log', '-1', '--format=%ct', '--', repoPath]);\n if (!output) return null;\n const timestamp = Number(output);\n return Number.isFinite(timestamp) ? timestamp : null;\n}\n\nfunction resolveFirstExisting(candidates) {\n for (const candidate of candidates) {\n if (fs.existsSync(path.join(REPO_ROOT, candidate))) {\n return candidate;\n }\n }\n return '';\n}\n\nfunction getSkillDocs() {\n const skillsDir = path.join(REPO_ROOT, 'ai-tools', 'ai-skills');\n if (!fs.existsSync(skillsDir)) return [];\n\n return fs\n .readdirSync(skillsDir, { withFileTypes: true })\n .filter((entry) => entry.isFile() && /\\.md$/i.test(entry.name))\n .map((entry) => toPosix(path.join('ai-tools/ai-skills', entry.name)))\n .sort((left, right) => left.localeCompare(right));\n}\n\nfunction buildRequiredEntries() {\n const required = [\n {\n label: 'AGENTS',\n candidates: ['AGENTS.md', 'ai-tools/ai-rules/AGENTS.md', '.github/AGENTS.md']\n },\n {\n label: 'ASSISTANT',\n candidates: ['ASSISTANT.md']\n },\n {\n label: 'AGENT-INSTRUCTIONS',\n candidates: ['AGENT-INSTRUCTIONS.md', 'contribute/CONTRIBUTING/AGENT-INSTRUCTIONS.md']\n }\n ];\n\n const records = required.map((entry) => ({\n label: entry.label,\n candidates: entry.candidates,\n resolvedPath: resolveFirstExisting(entry.candidates)\n }));\n\n const skillDocs = getSkillDocs();\n if (skillDocs.length === 0) {\n records.push({\n label: 'AI-SKILLS-TOPLEVEL',\n candidates: ['ai-tools/ai-skills/*.md'],\n resolvedPath: ''\n });\n } else {\n skillDocs.forEach((skillDoc) => {\n records.push({\n label: `AI-SKILL:${path.basename(skillDoc)}`,\n candidates: [skillDoc],\n resolvedPath: skillDoc\n });\n });\n }\n\n return records;\n}\n\nfunction buildRecord(entry, thresholdDays) {\n if (!entry.resolvedPath) {\n return {\n label: entry.label,\n candidates: entry.candidates,\n path: '',\n status: 'ERROR',\n ageDays: null,\n lastTouched: '',\n message: `Missing required file. Checked: ${entry.candidates.join(', ')}`\n };\n }\n\n const timestamp = getGitTimestamp(entry.resolvedPath);\n if (!timestamp) {\n return {\n label: entry.label,\n candidates: entry.candidates,\n path: entry.resolvedPath,\n status: 'ERROR',\n ageDays: null,\n lastTouched: '',\n message: 'File exists but has no git history'\n };\n }\n\n const ageDays = Math.floor((Date.now() - timestamp * 1000) / 86400000);\n const lastTouched = new Date(timestamp * 1000).toISOString().slice(0, 10);\n const status = ageDays > thresholdDays ? 'WARNING' : 'INFO';\n const message =\n status === 'WARNING'\n ? `Last updated ${ageDays} days ago`\n : `Touched within ${thresholdDays}-day threshold`;\n\n return {\n label: entry.label,\n candidates: entry.candidates,\n path: entry.resolvedPath,\n status,\n ageDays,\n lastTouched,\n message\n };\n}\n\nfunction summarize(records) {\n const summary = {\n info: 0,\n warnings: 0,\n errors: 0,\n total: records.length,\n thresholdDays: 0\n };\n\n records.forEach((record) => {\n if (record.status === 'INFO') summary.info += 1;\n if (record.status === 'WARNING') summary.warnings += 1;\n if (record.status === 'ERROR') summary.errors += 1;\n });\n\n return summary;\n}\n\nfunction writeHumanReport(records, summary) {\n records.forEach((record) => {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/generate-content-gap-reconciliation.js",
+ "script": "generate-content-gap-reconciliation",
+ "category": "generator",
+ "purpose": "governance:index-management",
+ "scope": "tools/scripts, tools/config, tools/lib, v2, tasks/reports/content-gap",
+ "owner": "docs",
+ "needs": "R-R16, R-R17",
+ "purpose_statement": "Content-gap reconciliation generator — compares blueprint coverage against v2 MDX and writes reconciliation artefacts",
+ "pipeline_declared": "manual — not yet in pipeline",
+ "usage": "node tools/scripts/generate-content-gap-reconciliation.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-content-gap-reconciliation\n * @category generator\n * @purpose governance:index-management\n * @scope tools/scripts, tools/config, tools/lib, v2, tasks/reports/content-gap\n * @owner docs\n * @needs R-R16, R-R17\n * @purpose-statement Content-gap reconciliation generator — compares blueprint coverage against v2 MDX and writes reconciliation artefacts\n * @pipeline manual — not yet in pipeline\n * @usage node tools/scripts/generate-content-gap-reconciliation.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst {\n extractFrontmatter,\n stripForWordCount,\n countWords,\n normalizeRel\n} = require('../lib/docs-index-utils');\n\nconst REPO_ROOT = process.cwd();\n\nconst DEFAULTS = {\n blueprintPagesPath: 'tools/config/blueprint-pages.json',\n blueprintMappingPath: 'tools/config/blueprint-mapping.json',\n v2Root: 'v2',\n outDir: 'tasks/reports/content-gap'\n};\n\nconst CSV_COLUMNS = [\n 'source',\n 'tab',\n 'position',\n 'blueprint_name',\n 'blueprint_type',\n 'blueprint_phase',\n 'repo_file',\n 'status',\n 'word_count',\n 'has_title',\n 'has_description',\n 'brand_violations',\n 'decision',\n 'notes'\n];\n\nconst DECISION_OPTIONS_COMMENT = '# decision options: KEEP, CREATE, EXPAND, MERGE, RENAME, DELETE, ADD_TO_BLUEPRINT';\n\nconst EXCLUDED_REPO_ONLY_SEGMENTS = new Set([\n 'cn',\n 'es',\n 'fr',\n 'x-deprecated',\n 'x-experimental',\n 'x-notes',\n 'views',\n 'groups'\n]);\n\nconst TEMPLATE_EXPANSIONS = {\n '[Platform]': ['Studio', 'Daydream'],\n '[Provider]': ['Cloud SPE', 'Daydream', 'Studio']\n};\n\nconst REPO_TAB_MAP = {\n home: 'HOME',\n developers: 'DEVELOPERS',\n solutions: 'SOLUTIONS',\n gateways: 'GATEWAYS',\n orchestrators: 'GPU NODES',\n lpt: 'LP TOKEN',\n community: 'COMMUNITY',\n about: 'ABOUT',\n resources: 'RESOURCE HUB',\n internal: 'INTERNAL'\n};\n\nconst BANNED_WORD_PATTERNS = [\n { label: 'simply', regex: /\\bsimply\\b/i },\n { label: 'just', regex: /\\bjust\\b/i },\n { label: 'easily', regex: /\\beasily\\b/i },\n { label: 'utilize', regex: /\\butilize\\b/i },\n { label: 'leverage', regex: /\\bleverage\\b/i },\n { label: 'seamless', regex: /\\bseamless\\b/i },\n { label: 'best-in-class', regex: /\\bbest[\\s-]in[\\s-]class\\b/i }\n];\n\nconst DEPRECATED_WORD_PATTERNS = [\n { label: 'broadcaster->gateway', regex: /\\bbroadcasters?\\b/i },\n { label: 'miner->orchestrator', regex: /\\bminers?\\b/i }\n];\n\nconst PLACEHOLDER_PATTERN = /Coming Soon|\\bTODO\\b|\\bTBD\\b|PreviewCallout/i;\n\nfunction toPosix(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction parseArgs(argv) {\n const out = { ...DEFAULTS };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n if (token === '--help' || token === '-h') {\n printUsage();\n process.exit(0);\n }\n\n if (token === '--blueprint-pages') {\n out.blueprintPagesPath = String(argv[i + 1] || out.blueprintPagesPath).trim() || out.blueprintPagesPath;\n i += 1;\n continue;\n }\n if (token.startsWith('--blueprint-pages=')) {\n out.blueprintPagesPath = token.slice('--blueprint-pages='.length).trim() || out.blueprintPagesPath;\n continue;\n }\n\n if (token === '--blueprint-mapping') {\n out.blueprintMappingPath = String(argv[i + 1] || out.blueprintMappingPath).trim() || out.blueprintMappingPath;\n i += 1;\n continue;\n }\n if (token.startsWith('--blueprint-mapping=')) {\n out.blueprintMappingPath = token.slice('--blueprint-mapping='.length).trim() || out.blueprintMappingPath;\n continue;\n }\n\n if (token === '--v2-root') {\n out.v2Root = String(argv[i + 1] || out.v2Root).trim() || out.v2Root;\n i += 1;\n continue;\n }\n if (token.startsWith('--v2-root=')) {\n out.v2Root = token.slice('--v2-root='.length).trim() || out.v2Root;\n continue;\n }\n\n if (token === '--out-dir') {\n out.outDir = String(argv[i + 1] || out.outDir).trim() || out.outDir;\n i += 1;\n continue;\n }\n if (token.startsWith('--out-dir=')) {\n out.outDir = token.slice('--out-dir='.length).trim() || out.outDir;\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n return out;\n}\n\nfunction printUsage() {\n console.log('Usage: node tools/scripts/generate-content-gap-reconciliation.js [options]');\n console.log('');\n console.log('Options:');\n console.log(` --blueprint-pages Default: ${DEFAULTS.blueprintPagesPath}`);\n console.log(` --blueprint-mapping Default: ${DEFAULTS.blueprintMappingPath}`);\n console.log(` --v2-root Default: ${DEFAULTS.v2Root}`);\n console.log(` --out-dir Default: ${DEFAULTS.outDir}`);\n}\n\nfunction readJsonFile(repoPath) {\n const absPath = path.resolve(REPO_ROOT, repoPath);\n const raw = fs.readFileSync(absPath, 'utf8');\n return JSON.parse(raw);\n}\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction expandBlueprintName(name) {\n let expanded = [String(name || '')];\n for (const [token, replacements] of Object.entries(TEMPLATE_EXPANSIONS)) {\n const next = [];\n for (const value of expanded) {\n if (!value.includes(token)) {\n next.push(value);\n continue;\n }\n replacements.forEach((replacement) => {\n next.push(value.replaceAll(token, replacement));\n });\n }\n expanded = next;\n }\n return expanded;\n}\n\nfunction buildMappedFileSet(blueprintMapping) {\n const mapped = new Set();\n Object.values(blueprintMapping).forEach((tabMap) => {\n if (!tabMap || typeof tabMap !== 'object') return;\n Object.values(tabMap).forEach((repoFile) => {\n if (!repoFile) return;\n mapped.add(normalizeRel(repoFile));\n });\n });\n return mapped;\n}\n\nfunction cleanTextForWordCount(body) {\n return String(stripForWordCount(body))\n .replace(/^export\\s.+$/gm, ' ')\n .replace(//g, ' ')\n .replace(/\\{[^{}]*\\}/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\nfunction findBrandViolations(rawContent) {\n const violations = [];\n for (const entry of BANNED_WORD_PATTERNS) {\n if (entry.regex.test(rawContent)) violations.push(`banned:${entry.label}`);\n }",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "tools/scripts/reconciliation-summary.md",
+ "type": "generated-output",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "tools/scripts/reconciliation-summary.md",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/generate-docs-guide-components-index.js",
+ "script": "generate-docs-guide-components-index",
+ "category": "generator",
+ "purpose": "governance:index-management",
+ "scope": "generated-output",
+ "owner": "docs",
+ "needs": "R-R10, R-R16, R-R17",
+ "purpose_statement": "Generates docs-guide and published component overview indexes from the governed component registry.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/scripts/generate-docs-guide-components-index.js [--write|--check]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-docs-guide-components-index\n * @category generator\n * @purpose governance:index-management\n * @scope generated-output\n * @owner docs\n * @needs R-R10, R-R16, R-R17\n * @purpose-statement Generates docs-guide and published component overview indexes from the governed component registry.\n * @pipeline manual\n * @usage node tools/scripts/generate-docs-guide-components-index.js [--write|--check]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { VALID_CATEGORIES } = require('../lib/component-governance-utils');\nconst { buildRegistry } = require('./generate-component-registry');\nconst { renderOverviewPage } = require('./generate-component-docs');\nconst {\n buildGeneratedFrontmatterLines,\n buildGeneratedHiddenBannerLines,\n buildGeneratedNoteLines\n} = require('../lib/generated-file-banners');\n\nconst REPO_ROOT = path.resolve(__dirname, '..', '..');\nconst OUTPUT_PATHS = [\n 'docs-guide/indexes/components-index.mdx',\n 'v2/resources/documentation-guide/component-library/overview.mdx'\n];\n\nconst CATEGORY_LABELS = {\n primitives: 'Primitives',\n layout: 'Layout',\n content: 'Content',\n data: 'Data',\n 'page-structure': 'Page Structure'\n};\n\nconst CATEGORY_DESCRIPTIONS = {\n primitives: 'Standalone visual atoms reused across authored docs.',\n layout: 'Arrangement and grouping components that shape flow and spacing.',\n content: 'Reader-facing renderers for code, media, response fields, and structured content.',\n data: 'Components bound to feeds, release metadata, or external datasets.',\n 'page-structure': 'Portal and frame-mode scaffolding for whole sections or hero treatments.'\n};\n\nfunction usage() {\n console.log(\n [\n 'Usage: node tools/scripts/generate-docs-guide-components-index.js [options]',\n '',\n 'Options:',\n ' --write Write generated output files',\n ' --check Verify generated output files are current',\n ' --help, -h Show this help message'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n write: false,\n check: false,\n help: false\n };\n\n argv.forEach((token) => {\n if (token === '--write') {\n args.write = true;\n return;\n }\n if (token === '--check') {\n args.check = true;\n return;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n return;\n }\n throw new Error(`Unknown argument: ${token}`);\n });\n\n if (!args.write && !args.check) {\n args.write = true;\n }\n\n return args;\n}\n\nfunction normalizeFileContent(content) {\n return `${String(content || '').trim()}\\n`;\n}\n\nfunction renderComponentsIndex(registry) {\n const details = {\n script: 'tools/scripts/generate-docs-guide-components-index.js',\n purpose: 'Aggregate inventory of governed component exports from snippets/components for docs-guide maintenance.',\n runWhen: 'Governed component files, exported signatures, or registry metadata change.',\n runCommand: 'node tools/scripts/generate-docs-guide-components-index.js --write'\n };\n\n const summaryLines = [\n '| Category | Exports | Primary purpose |',\n '| --- | --- | --- |'\n ];\n\n VALID_CATEGORIES.forEach((category) => {\n summaryLines.push(\n `| [${CATEGORY_LABELS[category]}](#${category}) | ${registry.categories[category].count} | ${CATEGORY_DESCRIPTIONS[category]} |`\n );\n });\n\n const sections = VALID_CATEGORIES.map((category) => {\n const components = registry.components.filter((component) => component.category === category);\n const table = [\n '| Component | Status | Tier | File |',\n '| --- | --- | --- | --- |'\n ];\n\n components.forEach((component) => {\n table.push(\n `| ${component.name} | \\`${component.status}\\` | \\`${component.tier}\\` | \\`/${component.file}\\` |`\n );\n });\n\n return [\n `## ${category}`,\n '',\n CATEGORY_DESCRIPTIONS[category],\n '',\n table.join('\\n')\n ].join('\\n');\n });\n\n return normalizeFileContent(\n [\n ...buildGeneratedFrontmatterLines({\n title: 'Components Index',\n sidebarTitle: 'Components Index',\n description: 'Aggregate inventory of governed component exports from snippets/components.',\n pageType: 'overview',\n keywords: ['livepeer', 'components index', 'snippets', 'registry', 'inventory']\n }),\n '',\n ...buildGeneratedHiddenBannerLines(details),\n '',\n ...buildGeneratedNoteLines(details),\n '',\n `The governed component library currently exposes **${registry._meta.componentCount}** named export(s).`,\n '',\n '## Category Summary',\n '',\n summaryLines.join('\\n'),\n '',\n ...sections.flatMap((section, index) => (index === 0 ? [section] : ['', section]))\n ].join('\\n')\n );\n}\n\nfunction buildOutputs() {\n const { registry, issues } = buildRegistry();\n if (issues.length > 0) {\n throw new Error(issues.join('\\n'));\n }\n\n return new Map([\n ['docs-guide/indexes/components-index.mdx', renderComponentsIndex(registry)],\n ['v2/resources/documentation-guide/component-library/overview.mdx', normalizeFileContent(renderOverviewPage(registry))]\n ]);\n}\n\nfunction writeOutputs(outputs) {\n outputs.forEach((content, relativePath) => {\n const absolutePath = path.join(REPO_ROOT, relativePath);\n fs.mkdirSync(path.dirname(absolutePath), { recursive: true });\n fs.writeFileSync(absolutePath, content, 'utf8');\n });\n}\n\nfunction checkOutputs(outputs) {\n const stale = [];\n\n outputs.forEach((expected, relativePath) => {\n const absolutePath = path.join(REPO_ROOT, relativePath);\n const actual = fs.existsSync(absolutePath) ? fs.readFileSync(absolutePath, 'utf8') : '';\n if (normalizeFileContent(actual) !== expected) {\n stale.push(relativePath);\n }\n });\n\n return stale;\n}\n\nfunction run(argv = process.argv.slice(2)) {\n let args;\n try {\n args = parseArgs(argv);\n } catch (error) {\n console.error(`❌ ${error.message}`);\n usage();\n return 1;\n }\n\n if (args.help) {\n usage();\n return 0;\n }\n\n let outputs;\n try {\n outputs = buildOutputs();\n } catch (error) {\n console.error(`❌ ${error.message}`);\n return 1;\n }\n\n if (args.check) {\n const stale = checkOutputs(outputs);\n if (stale.length > 0) {\n stale.forEach((filePath) => console.error(`Components index is out of date: ${filePath}`));",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/generate-docs-guide-indexes.js",
+ "script": "generate-docs-guide-indexes",
+ "category": "generator",
+ "purpose": "governance:index-management",
+ "scope": "tools/scripts, docs-guide, .github/workflows, .github/ISSUE_TEMPLATE",
+ "owner": "docs",
+ "needs": "R-R16, R-R17",
+ "purpose_statement": "Generates docs-guide workflow/template indexes and optionally verifies freshness",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/generate-docs-guide-indexes.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-docs-guide-indexes\n * @category generator\n * @purpose governance:index-management\n * @scope tools/scripts, docs-guide, .github/workflows, .github/ISSUE_TEMPLATE\n * @owner docs\n * @needs R-R16, R-R17\n * @purpose-statement Generates docs-guide workflow/template indexes and optionally verifies freshness\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @dualmode dual-mode (document flags)\n * @usage node tools/scripts/generate-docs-guide-indexes.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst {\n buildGeneratedFrontmatterLines,\n buildGeneratedHiddenBannerLines,\n buildGeneratedNoteLines\n} = require('../lib/generated-file-banners');\n\nlet yaml = null;\ntry {\n yaml = require('js-yaml');\n} catch (_err) {\n yaml = null;\n}\n\nconst REPO_ROOT = process.cwd();\nconst WORKFLOWS_DIR = '.github/workflows';\nconst ISSUE_TEMPLATE_DIR = '.github/ISSUE_TEMPLATE';\nconst PR_TEMPLATE_FILES = ['.github/pull-request-template-v2.md', '.github/pull_request_template.md'];\n\nconst OUTPUT_FILES = {\n workflows: 'docs-guide/indexes/workflows-index.mdx',\n templates: 'docs-guide/indexes/templates-index.mdx'\n};\n\nconst LEGACY_OUTPUT_FILES = {\n workflows: 'docs-guide/indexes/workflows-index.md',\n templates: 'docs-guide/indexes/templates-index.md'\n};\n\nconst WORKFLOWS_INDEX_FRONTMATTER_LINES = buildGeneratedFrontmatterLines({\n title: 'Workflows Index',\n sidebarTitle: 'Workflows Index',\n description: 'Aggregate inventory of repository GitHub workflows',\n keywords: ['livepeer', 'workflows index', 'aggregate inventory', 'repository', 'github', 'workflows'],\n keywordsStyle: 'multiline'\n});\n\nconst TEMPLATES_INDEX_FRONTMATTER_LINES = buildGeneratedFrontmatterLines({\n title: 'Templates Index',\n sidebarTitle: 'Templates Index',\n description: 'Aggregate inventory of repository templates',\n keywords: ['livepeer', 'templates index', 'aggregate inventory', 'repository', 'templates'],\n keywordsStyle: 'multiline'\n});\n\nfunction normalizeRepoPath(value) {\n return String(value || '').split(path.sep).join('/');\n}\n\nfunction readFileSafe(repoPath) {\n try {\n return fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8');\n } catch (_err) {\n return '';\n }\n}\n\nfunction fileExists(repoPath) {\n const full = path.join(REPO_ROOT, repoPath);\n return fs.existsSync(full) && fs.statSync(full).isFile();\n}\n\nfunction listFiles(dirRepoPath, predicate) {\n const full = path.join(REPO_ROOT, dirRepoPath);\n if (!fs.existsSync(full) || !fs.statSync(full).isDirectory()) return [];\n\n return fs\n .readdirSync(full)\n .filter((name) => (predicate ? predicate(name) : true))\n .map((name) => normalizeRepoPath(path.join(dirRepoPath, name)))\n .sort();\n}\n\nfunction parseYaml(content) {\n if (!yaml) return null;\n try {\n return yaml.load(content);\n } catch (_err) {\n return null;\n }\n}\n\nfunction mdEscape(value) {\n return String(value || '').replace(/\\|/g, '\\\\|').replace(/\\n/g, ' ');\n}\n\nfunction inferWorkflowTriggers(doc, content) {\n const tags = [];\n const triggerMap = {\n pull_request: 'pull_request',\n push: 'push',\n schedule: 'schedule',\n workflow_dispatch: 'workflow_dispatch',\n repository_dispatch: 'repository_dispatch'\n };\n\n const onValue = doc && Object.prototype.hasOwnProperty.call(doc, 'on') ? doc.on : null;\n\n if (typeof onValue === 'string' && triggerMap[onValue]) {\n tags.push(triggerMap[onValue]);\n } else if (Array.isArray(onValue)) {\n onValue.forEach((name) => {\n if (triggerMap[name]) tags.push(triggerMap[name]);\n });\n } else if (onValue && typeof onValue === 'object') {\n Object.keys(onValue).forEach((name) => {\n if (triggerMap[name]) tags.push(triggerMap[name]);\n });\n }\n\n if (tags.length === 0) {\n const raw = String(content || '');\n Object.keys(triggerMap).forEach((key) => {\n const re = new RegExp(`\\\\b${key}\\\\b`);\n if (re.test(raw)) tags.push(triggerMap[key]);\n });\n }\n\n return [...new Set(tags)].sort();\n}\n\nfunction inferWorkflowOutputs(content) {\n const outputs = [];\n const raw = String(content || '');\n\n if (/upload-artifact/i.test(raw)) outputs.push('artifact upload');\n if (/GITHUB_STEP_SUMMARY/.test(raw)) outputs.push('step summary');\n if (/gh\\s+pr\\s+comment|pull-requests:\\s*write/i.test(raw)) outputs.push('PR comments/metadata');\n if (/git\\s+push/i.test(raw)) outputs.push('repository commits');\n\n if (outputs.length === 0) outputs.push('workflow logs');\n return outputs.join(', ');\n}\n\nfunction inferWorkflowBlocking(content) {\n const raw = String(content || '');\n if (/continue-on-error:\\s*true/.test(raw)) {\n return 'advisory or partial-advisory';\n }\n return 'blocking by default (subject to branch protection)';\n}\n\nfunction firstSentence(value) {\n const text = String(value || '').replace(/\\s+/g, ' ').trim();\n if (!text) return '';\n const idx = text.indexOf('. ');\n if (idx > 0) return text.slice(0, idx + 1).trim();\n return text;\n}\n\nfunction inferWorkflowPurpose(doc, workflowPath) {\n const name = doc && doc.name ? String(doc.name).trim() : path.basename(workflowPath);\n return firstSentence(name) || `Workflow for ${workflowPath}.`;\n}\n\nfunction buildWorkflowsIndex() {\n const workflowFiles = listFiles(WORKFLOWS_DIR, (name) => /\\.(yml|yaml)$/i.test(name));\n\n const rows = workflowFiles.map((workflowPath) => {\n const content = readFileSafe(workflowPath);\n const doc = parseYaml(content) || {};\n const workflowName = String(doc.name || path.basename(workflowPath));\n const triggers = inferWorkflowTriggers(doc, content);\n const purpose = inferWorkflowPurpose(doc, workflowPath);\n const outputs = inferWorkflowOutputs(content);\n const blocking = inferWorkflowBlocking(content);\n\n return {\n workflowName,\n workflowPath,\n triggers: triggers.length ? triggers.join(', ') : 'unknown',\n purpose,\n blocking,\n outputs,\n owner: 'docs'\n };\n });\n\n const lines = [];\n const bannerDetails = {\n script: 'tools/scripts/generate-docs-guide-indexes.js',\n purpose: 'Workflow inventory for docs-guide maintenance.',\n runWhen: 'GitHub workflows are added, removed, or changed.',\n runCommand: 'node tools/scripts/generate-docs-guide-indexes.js --write'\n };\n WORKFLOWS_INDEX_FRONTMATTER_LINES.forEach((line) => lines.push(line));\n lines.push('');\n buildGeneratedHiddenBannerLines(bannerDetails).forEach((line) => lines.push(line));\n lines.push('');\n buildGeneratedNoteLines(bannerDetails).forEach((line) => lines.push(line));\n lines.push('');\n lines.push('| Workflow | File | Triggers | Purpose | Blocking Policy | Outputs | Owner |');\n lines.push('|---|---|---|---|---|---|---|');\n\n rows.forEach((row) => {\n lines.push(\n `| ${mdEscape(row.workflowName)} | \\`${mdEscape(row.workflowPath)}\\` | ${mdEscape(row.triggers)} | ${mdEscape(row.purpose)} | ${mdEscape(row.blocking)} | ${mdEscape(row.outputs)} | ${mdEscape(row.owner)} |`\n );\n });\n\n lines.push('');\n return `${lines.join('\\n')}`;\n}\n\nfunction inferTemplatePurposeFromMarkdown(content, fallback) {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "docs-guide:indexes"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: docs-guide:indexes)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/generate-docs-guide-pages-index.js",
+ "script": "generate-docs-guide-pages-index",
+ "category": "generator",
+ "purpose": "governance:index-management",
+ "scope": "tools/scripts, docs-guide/indexes/pages-index.mdx, v2/index.mdx, docs.json",
+ "owner": "docs",
+ "needs": "R-R16, R-R17",
+ "purpose_statement": "Generates the docs-guide pages index",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/generate-docs-guide-pages-index.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script generate-docs-guide-pages-index\n * @category generator\n * @purpose governance:index-management\n * @scope tools/scripts, docs-guide/indexes/pages-index.mdx, v2/index.mdx, docs.json\n * @owner docs\n * @needs R-R16, R-R17\n * @purpose-statement Generates the docs-guide pages index\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/generate-docs-guide-pages-index.js [flags]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst {\n buildGeneratedFrontmatterLines,\n buildGeneratedHiddenBannerLines,\n buildGeneratedNoteLines\n} = require('../lib/generated-file-banners');\n\nconst REPO_ROOT = process.cwd();\nconst SOURCE_INDEX_PATH = 'v2/index.mdx';\nconst DOCS_JSON_PATH = 'docs.json';\nconst OUTPUT_PATH = 'docs-guide/indexes/pages-index.mdx';\n\nconst FRONTMATTER_LINES = buildGeneratedFrontmatterLines({\n title: 'Pages Index',\n sidebarTitle: 'Pages Index',\n description: 'Tree inventory of docs pages included in docs.json navigation, generated from v2 index data.',\n keywords: ['livepeer', 'pages index', 'tree', 'docs.json', 'v2']\n});\n\nconst GENERATED_DETAILS = {\n script: 'tools/scripts/generate-docs-guide-pages-index.js',\n purpose: 'Tree inventory of docs pages included in docs.json navigation, generated from v2 index data.',\n runWhen: '`v2/index.mdx` links or docs.json navigation entries change.',\n runCommand: 'node tools/scripts/generate-docs-guide-pages-index.js --write'\n};\n\nfunction normalizeRepoPath(value) {\n return String(value || '').split(path.sep).join('/').replace(/^\\.?\\//, '');\n}\n\nfunction normalizeRouteKey(routePath) {\n let normalized = normalizeRepoPath(routePath).replace(/^\\/+/, '');\n normalized = normalized.replace(/\\.(md|mdx)$/i, '');\n normalized = normalized.replace(/\\/index$/i, '');\n normalized = normalized.replace(/\\/+$/, '');\n return normalized;\n}\n\nfunction sortAlpha(values) {\n return [...values].sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));\n}\n\nfunction readFileSafe(repoPath) {\n try {\n return fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8');\n } catch (_err) {\n return '';\n }\n}\n\nfunction fileExists(repoPath) {\n const fullPath = path.join(REPO_ROOT, repoPath);\n return fs.existsSync(fullPath) && fs.statSync(fullPath).isFile();\n}\n\nfunction collectDocsPageEntries(node, out = []) {\n if (typeof node === 'string') {\n const value = node.trim();\n if (value.startsWith('v1/') || value.startsWith('v2/')) {\n out.push(value);\n }\n return out;\n }\n\n if (Array.isArray(node)) {\n node.forEach((item) => collectDocsPageEntries(item, out));\n return out;\n }\n\n if (!node || typeof node !== 'object') return out;\n\n Object.values(node).forEach((value) => collectDocsPageEntries(value, out));\n return out;\n}\n\nfunction getDocsJsonRouteKeys() {\n const raw = readFileSafe(DOCS_JSON_PATH);\n if (!raw.trim()) {\n throw new Error(`Missing or empty ${DOCS_JSON_PATH}`);\n }\n\n const docsJson = JSON.parse(raw);\n const entries = collectDocsPageEntries(docsJson, []);\n const keys = new Set();\n entries.forEach((entry) => {\n const key = normalizeRouteKey(entry);\n if (key) keys.add(key);\n });\n return keys;\n}\n\nfunction isExternalHref(href) {\n return /^(https?:\\/\\/|mailto:|#|\\/)/i.test(String(href || '').trim());\n}\n\nfunction cleanHref(href) {\n return String(href || '').split('#')[0].split('?')[0].trim();\n}\n\nfunction parseV2IndexLinks() {\n const content = readFileSafe(SOURCE_INDEX_PATH);\n if (!content.trim()) {\n throw new Error(`Missing or empty ${SOURCE_INDEX_PATH}`);\n }\n\n const links = [];\n const lines = content.split('\\n');\n lines.forEach((rawLine) => {\n const line = rawLine.trim();\n const match = line.match(/^- \\[(.+?)\\]\\((.+?)\\)$/);\n if (!match) return;\n const title = String(match[1] || '').trim();\n const href = cleanHref(match[2]);\n if (!href) return;\n if (title.includes('⚠️')) return;\n if (isExternalHref(href)) return;\n links.push(href);\n });\n\n return [...new Set(links)];\n}\n\nfunction resolveRepoPathFromHref(href) {\n const sourceDir = path.posix.dirname(SOURCE_INDEX_PATH);\n const cleanedHref = cleanHref(href);\n if (!cleanedHref) return '';\n\n const joined = normalizeRepoPath(path.posix.normalize(path.posix.join(sourceDir, cleanedHref)));\n if (!joined || joined.startsWith('..') || joined.includes('/../')) return '';\n\n const hasExtension = /\\.(md|mdx)$/i.test(joined);\n const candidates = hasExtension\n ? [joined]\n : [`${joined}.mdx`, `${joined}.md`, path.posix.join(joined, 'index.mdx'), path.posix.join(joined, 'index.md')];\n\n for (const candidate of candidates) {\n const normalizedCandidate = normalizeRepoPath(candidate);\n if (!normalizedCandidate.startsWith('v2/')) continue;\n if (fileExists(normalizedCandidate)) return normalizedCandidate;\n }\n\n return '';\n}\n\nfunction buildTree(paths) {\n const root = { name: 'v2', folders: new Map(), files: new Set() };\n\n sortAlpha(paths).forEach((repoPath) => {\n const segments = normalizeRepoPath(repoPath).split('/').filter(Boolean);\n if (segments.length < 2 || segments[0] !== 'v2') return;\n\n let current = root;\n for (let i = 1; i < segments.length - 1; i += 1) {\n const folderName = segments[i];\n if (!current.folders.has(folderName)) {\n current.folders.set(folderName, { name: folderName, folders: new Map(), files: new Set() });\n }\n current = current.folders.get(folderName);\n }\n\n current.files.add(segments[segments.length - 1]);\n });\n\n return root;\n}\n\nfunction escapeJsxAttribute(value) {\n return String(value || '').replace(/&/g, '&').replace(/\"/g, '"');\n}\n\nfunction renderTreeFolder(node, indent, defaultOpen = false) {\n const attrs = [`name=\"${escapeJsxAttribute(node.name)}\"`];\n if (defaultOpen) attrs.push('defaultOpen');\n\n const lines = [`${indent}`];\n const folderNames = sortAlpha([...node.folders.keys()]);\n const fileNames = sortAlpha([...node.files]);\n\n folderNames.forEach((folderName) => {\n lines.push(...renderTreeFolder(node.folders.get(folderName), `${indent} `, false));\n });\n\n fileNames.forEach((fileName) => {\n lines.push(`${indent} `);\n return lines;\n}\n\nfunction renderTree(paths) {\n const tree = buildTree(paths);\n const lines = [''];\n\n const hasChildren = tree.folders.size > 0 || tree.files.size > 0;\n if (!hasChildren) {\n lines.push(' ');\n return lines;\n}\n\nfunction buildContent() {",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/add-framework-headers.js",
+ "script": "add-framework-headers",
+ "category": "generator",
+ "purpose": "governance:repo-health",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "R-R14",
+ "purpose_statement": "Inserts or extends framework headers on all repo scripts from classification data.",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/add-framework-headers.js --data script-classifications.json --dry-run",
+ "header": "#!/usr/bin/env node\n/**\n * @script add-framework-headers\n * @summary Insert or verify governance framework metadata headers from classification JSON.\n * @category generator\n * @purpose governance:repo-health\n * @scope full-repo\n * @owner docs\n * @needs R-R14\n * @purpose-statement Inserts or extends framework headers on all repo scripts from classification data.\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/add-framework-headers.js --data script-classifications.json --dry-run\n *\n * @inputs\n * --data --dry-run|--write|--verify [--filter ] [--exclude-subdirs] [--force]\n *\n * @outputs\n * - Console summary with files processed, updated, skipped, and errors\n *\n * @exit-codes\n * 0 = success\n * 1 = argument, I/O, parse, or verification failure\n *\n * @examples\n * node tools/scripts/add-framework-headers.js --data script-classifications.json --dry-run\n * node tools/scripts/add-framework-headers.js --data script-classifications.json --filter tools/scripts --write\n *\n * @notes\n * Tool-only migration utility; it does not execute repo-wide header rewrites unless explicitly run.\n */\n\nconst fs = require('fs');\nconst path = require('path');\n\nconst REPO_ROOT = process.cwd();\nconst JS_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.ts', '.tsx']);\nconst SHELL_EXTENSIONS = new Set(['.sh', '.bash']);\nconst PYTHON_EXTENSIONS = new Set(['.py']);\n\nfunction printHelp() {\n console.log(\n [\n 'Usage:',\n ' node tools/scripts/add-framework-headers.js --data (--dry-run | --write | --verify) [options]',\n '',\n 'Required:',\n ' --data Path to classification JSON data file.',\n '',\n 'Modes (choose exactly one):',\n ' --dry-run Show planned changes without writing files.',\n ' --write Apply header updates to files.',\n ' --verify Read-only validation of headers against classification data.',\n '',\n 'Options:',\n ' --filter Process only files under this repo-relative prefix.',\n ' --exclude-subdirs With --filter, include only direct child files.',\n ' --force Overwrite rows that already contain @category or @purpose.',\n ' --help Show this help output.',\n '',\n 'Examples:',\n ' node tools/scripts/add-framework-headers.js --data script-classifications.json --dry-run',\n ' node tools/scripts/add-framework-headers.js --data /tmp/classifications.json --filter tools/scripts --write',\n ' node tools/scripts/add-framework-headers.js --data script-classifications.json --filter .githooks --exclude-subdirs --verify'\n ].join('\\n')\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n dataPath: '',\n filter: '',\n excludeSubdirs: false,\n dryRun: false,\n write: false,\n verify: false,\n force: false,\n help: false\n };\n\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i];\n\n if (token === '--help') {\n args.help = true;\n continue;\n }\n if (token === '--dry-run') {\n args.dryRun = true;\n continue;\n }\n if (token === '--write') {\n args.write = true;\n continue;\n }\n if (token === '--verify') {\n args.verify = true;\n continue;\n }\n if (token === '--exclude-subdirs') {\n args.excludeSubdirs = true;\n continue;\n }\n if (token === '--force') {\n args.force = true;\n continue;\n }\n\n if (token === '--data') {\n args.dataPath = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--data=')) {\n args.dataPath = token.slice('--data='.length).trim();\n continue;\n }\n\n if (token === '--filter') {\n args.filter = String(argv[i + 1] || '').trim();\n i += 1;\n continue;\n }\n if (token.startsWith('--filter=')) {\n args.filter = token.slice('--filter='.length).trim();\n continue;\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (args.help) return args;\n\n if (!args.dataPath) {\n throw new Error('Missing required --data argument.');\n }\n\n const modeCount = [args.dryRun, args.write, args.verify].filter(Boolean).length;\n if (modeCount !== 1) {\n throw new Error('Exactly one mode is required: --dry-run, --write, or --verify.');\n }\n\n if (args.excludeSubdirs && !args.filter) {\n throw new Error('--exclude-subdirs requires --filter.');\n }\n\n return args;\n}\n\nfunction normalizeRepoPath(value, label) {\n const raw = String(value || '').trim();\n if (!raw) {\n throw new Error(`Missing ${label || 'path'} value.`);\n }\n\n let candidate = raw;\n if (path.isAbsolute(raw)) {\n candidate = path.relative(REPO_ROOT, raw);\n }\n\n const posix = path.posix.normalize(String(candidate).replace(/\\\\/g, '/'));\n const withoutDotPrefix = posix.replace(/^\\.\\//, '');\n\n if (!withoutDotPrefix || withoutDotPrefix === '.') {\n throw new Error(`Invalid ${label || 'path'} value: \"${raw}\"`);\n }\n\n if (\n withoutDotPrefix === '..' ||\n withoutDotPrefix.startsWith('../') ||\n path.isAbsolute(withoutDotPrefix)\n ) {\n throw new Error(`Path escapes repository root: \"${raw}\"`);\n }\n\n return withoutDotPrefix;\n}\n\nfunction normalizePrefix(prefix) {\n const normalized = normalizeRepoPath(prefix, '--filter');\n return normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;\n}\n\nfunction stringField(row, fieldName) {\n const value = row[fieldName];\n if (value === undefined || value === null) return '';\n return String(value).trim();\n}\n\nfunction loadClassificationData(dataPath) {\n const absPath = path.isAbsolute(dataPath) ? dataPath : path.join(REPO_ROOT, dataPath);\n\n let raw = '';\n try {\n raw = fs.readFileSync(absPath, 'utf8');\n } catch (error) {\n throw new Error(`Unable to read data file: ${absPath} (${error.message})`);\n }\n\n let parsed;\n try {\n parsed = JSON.parse(raw);\n } catch (error) {\n throw new Error(`Invalid JSON in ${absPath}: ${error.message}`);\n }\n\n if (!Array.isArray(parsed)) {\n throw new Error(`Classification data must be an array: ${absPath}`);\n }\n\n const rows = [];\n const seenPaths = new Set();\n\n parsed.forEach((row, index) => {\n if (!row || typeof row !== 'object' || Array.isArray(row)) {\n throw new Error(`data[${index}] must be an object.`);\n }\n\n const repoPath = normalizeRepoPath(row.path, `data[${index}].path`);\n if (seenPaths.has(repoPath)) {\n throw new Error(`Duplicate path in classification data: ${repoPath}`);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "",
+ "type": "stdout",
+ "call": "writeFileSync"
+ }
+ ],
+ "outputs_display": "",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/enforcers/pr/check-pr-template.js",
+ "script": "check-pr-template",
+ "category": "enforcer",
+ "purpose": "governance:repo-health",
+ "scope": "tools/scripts/enforcers/pr, .github/pull_request_template.md, .github/pull-request-template-v2.md",
+ "owner": "docs",
+ "needs": "R-R14, R-C6",
+ "purpose_statement": "Enforces that PR descriptions include required change and rationale sections before merge",
+ "pipeline_declared": "ci",
+ "usage": "PR_BODY=\"...\" node tools/scripts/enforcers/pr/check-pr-template.js",
+ "header": "#!/usr/bin/env node\n/**\n * @script check-pr-template\n * @category enforcer\n * @purpose governance:repo-health\n * @scope tools/scripts/enforcers/pr, .github/pull_request_template.md, .github/pull-request-template-v2.md\n * @owner docs\n * @needs R-R14, R-C6\n * @purpose-statement Enforces that PR descriptions include required change and rationale sections before merge\n * @pipeline ci\n * @usage PR_BODY=\"...\" node tools/scripts/enforcers/pr/check-pr-template.js\n */\n\nconst fs = require('fs');\n\nconst CHANGE_HEADINGS = new Set(['what changed', 'changes', 'changes made']);\nconst RATIONALE_HEADINGS = new Set(['why', 'motivation', 'reason', 'description']);\n\nfunction normalizeHeading(value) {\n return String(value || '')\n .toLowerCase()\n .replace(/[`*_~]/g, ' ')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\nfunction readPrBody() {\n const fromEnv = String(process.env.PR_BODY || '');\n if (fromEnv.trim()) return fromEnv;\n if (!process.stdin.isTTY) {\n return fs.readFileSync(0, 'utf8');\n }\n return '';\n}\n\nfunction collectHeadings(body) {\n const headings = [];\n const re = /^\\s{0,3}#{2,6}\\s+(.+?)\\s*#*\\s*$/gm;\n let match = re.exec(body);\n\n while (match) {\n headings.push(normalizeHeading(match[1]));\n match = re.exec(body);\n }\n\n return headings;\n}\n\nfunction hasRequiredHeading(headings, allowed) {\n return headings.some((heading) => allowed.has(heading));\n}\n\nfunction main() {\n const prBody = readPrBody();\n const headings = collectHeadings(prBody);\n const hasChangeSection = hasRequiredHeading(headings, CHANGE_HEADINGS);\n const hasRationaleSection = hasRequiredHeading(headings, RATIONALE_HEADINGS);\n const missing = [];\n\n if (!hasChangeSection) {\n missing.push('change section (accepted: ## What changed, ## Changes, ## Changes Made)');\n }\n\n if (!hasRationaleSection) {\n missing.push('rationale section (accepted: ## Why, ## Motivation, ## Reason, ## Description)');\n }\n\n if (missing.length === 0) {\n console.log('✅ PR template sections present.');\n process.exit(0);\n }\n\n const branch = String(process.env.GITHUB_HEAD_REF || '').trim();\n const message = `Missing required PR sections: ${missing.join('; ')}`;\n\n if (branch.startsWith('codex/')) {\n console.warn(`⚠️ ${message}`);\n process.exit(0);\n }\n\n console.error(`❌ ${message}`);\n process.exit(1);\n}\n\nmain();\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": false,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "C",
+ "flags": [
+ "invalid-scope"
+ ],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/validators/governance/audit-script-inventory.js",
+ "script": "audit-script-inventory",
+ "category": "validator",
+ "purpose": "governance:repo-health",
+ "scope": "full-repo",
+ "owner": "docs",
+ "needs": "R-R14, R-R18, R-C6",
+ "purpose_statement": "Deep inventory audit of every script in the repo. Traces triggers, outputs, downstream chains, and governance compliance. Produces reports grouped by trigger category.",
+ "pipeline_declared": "manual",
+ "usage": "node tools/scripts/validators/governance/audit-script-inventory.js [--json] [--md] [--output ] [--verbose]",
+ "header": "#!/usr/bin/env node\n/**\n * @script audit-script-inventory\n * @category validator\n * @purpose governance:repo-health\n * @scope full-repo\n * @owner docs\n * @needs R-R14, R-R18, R-C6\n * @purpose-statement Deep inventory audit of every script in the repo. Traces triggers, outputs, downstream chains, and governance compliance. Produces reports grouped by trigger category.\n * @pipeline manual\n * @usage node tools/scripts/validators/governance/audit-script-inventory.js [--json] [--md] [--output ] [--verbose]\n */\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execFileSync } = require('child_process');\nconst yaml = require('js-yaml');\nconst {\n CATEGORY_ENUM,\n CLASSIFICATION_DATA_PATH,\n DISCOVERY_ROOTS,\n FRAMEWORK_FIELDS,\n GROUP_LABELS,\n GROUP_ORDER,\n PIPELINE_ORDER,\n PURPOSE_ENUM,\n REQUIRED_FRAMEWORK_KEYS,\n SCOPE_ENUM,\n SCRIPT_EXTENSIONS,\n isDiscoveredScriptPath,\n normalizeRepoPath,\n parseDeclaredPipelines\n} = require('../../../lib/script-governance-config');\n\nconst REPO_ROOT = path.resolve(__dirname, '../../../..');\nconst DEFAULT_OUTPUT_DIR = 'tasks/reports/repo-ops';\nconst DEFAULT_MD_PATH = 'SCRIPT_INVENTORY_FULL.md';\nconst DEFAULT_JSON_PATH = 'SCRIPT_INVENTORY_FULL.json';\nconst REPO_ROOT_POSIX = normalizeRepoPath(REPO_ROOT);\nconst REPO_ROOT_LOOSE = REPO_ROOT_POSIX.replace(/^\\/+/, '');\nconst HEADER_SCAN_LINES = 220;\nconst SPECIAL_CALLERS = new Set(['.githooks/pre-commit', '.githooks/pre-push', 'tests/run-all.js', 'tests/run-pr-checks.js']);\nconst PACKAGE_JSON_PATHS = ['tools/package.json', 'tests/package.json'];\nconst WRITE_CALL_RE = /\\b(?:fs\\.)?(writeFileSync|writeFile|appendFileSync|appendFile|mkdirSync|mkdir|createWriteStream|writeJson)\\s*\\(([\\s\\S]{0,220}?)\\)/g;\nconst STRING_RE = /(['\"`])((?:\\\\.|(?!\\1).)*)\\1/g;\nconst CONST_RE = /^\\s*const\\s+([A-Za-z0-9_]+)\\s*=\\s*(.+?);\\s*$/gm;\nconst HEADER_TABLE_COLUMNS = [\n 'Path',\n 'Category',\n 'Purpose',\n 'Pipeline claimed',\n 'Pipeline actual',\n 'Pipeline verdict',\n 'Outputs',\n 'Triggers downstream?',\n 'Scope',\n 'Needs',\n 'Header completeness',\n 'Grade',\n 'Flags'\n];\nconst AUTOMATED_PIPELINES = new Set(['P1', 'P2', 'P3', 'P5', 'P6']);\n\nfunction usage() {\n console.log(\n 'Usage: node tools/scripts/validators/governance/audit-script-inventory.js [--json] [--md] [--output ] [--verbose]'\n );\n}\n\nfunction parseArgs(argv) {\n const args = {\n json: false,\n md: false,\n verbose: false,\n outputDir: DEFAULT_OUTPUT_DIR\n };\n\n for (let index = 0; index < argv.length; index += 1) {\n const token = argv[index];\n if (token === '--json') {\n args.json = true;\n continue;\n }\n if (token === '--md') {\n args.md = true;\n continue;\n }\n if (token === '--verbose') {\n args.verbose = true;\n continue;\n }\n if (token === '--output') {\n args.outputDir = String(argv[index + 1] || '').trim() || DEFAULT_OUTPUT_DIR;\n index += 1;\n continue;\n }\n if (token.startsWith('--output=')) {\n args.outputDir = token.slice('--output='.length).trim() || DEFAULT_OUTPUT_DIR;\n continue;\n }\n if (token === '--help' || token === '-h') {\n args.help = true;\n continue;\n }\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!args.json && !args.md) {\n args.json = true;\n args.md = true;\n args.printSummary = true;\n }\n\n return args;\n}\n\nfunction ensureDirectory(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction readRepoFile(repoPath, warnings) {\n try {\n return fs.readFileSync(path.join(REPO_ROOT, repoPath), 'utf8');\n } catch (error) {\n warnings.push(`Could not read ${repoPath}: ${error.message}`);\n return '';\n }\n}\n\nfunction listTrackedFiles() {\n const output = execFileSync('git', ['ls-files'], {\n cwd: REPO_ROOT,\n encoding: 'utf8'\n });\n return output\n .split('\\n')\n .map((line) => normalizeRepoPath(line.trim()))\n .filter(Boolean);\n}\n\nfunction getWorkflowFiles(trackedFiles) {\n return trackedFiles.filter((repoPath) => repoPath.startsWith('.github/workflows/') && /\\.(ya?ml)$/i.test(repoPath));\n}\n\nfunction getDiscoveredScripts(trackedFiles) {\n return trackedFiles.filter(isDiscoveredScriptPath).sort();\n}\n\nfunction getHeaderChunk(content) {\n return String(content || '')\n .split('\\n')\n .slice(0, HEADER_SCAN_LINES)\n .join('\\n');\n}\n\nfunction getTagValue(header, tagName) {\n const pattern = new RegExp(`\\\\${tagName}\\\\s+(.+)`);\n const match = header.match(pattern);\n return match ? match[1].trim() : '';\n}\n\nfunction getSectionLines(header, tagName) {\n const lines = String(header || '').split('\\n');\n const tagToken = tagName.replace('@', '');\n const start = lines.findIndex((line) => line.includes(`@${tagToken}`));\n if (start === -1) return [];\n\n const values = [];\n for (let index = start + 1; index < lines.length; index += 1) {\n const line = lines[index].trim();\n if (!line) continue;\n const stripped = line.replace(/^\\*\\s?/, '').replace(/^#\\s?/, '').trim();\n if (!stripped) continue;\n if (stripped.startsWith('@')) break;\n if (stripped === '/**' || stripped === '*/') continue;\n values.push(stripped);\n }\n return values;\n}\n\nfunction readUsageValue(header) {\n const inline = getTagValue(header, '@usage');\n if (inline) return inline;\n return getSectionLines(header, '@usage').find(Boolean) || '';\n}\n\nfunction extractHeaderMetadata(scriptPath, content) {\n const header = getHeaderChunk(content);\n const values = {\n path: scriptPath,\n script: getTagValue(header, '@script'),\n category: getTagValue(header, '@category'),\n purpose: getTagValue(header, '@purpose'),\n scope: getTagValue(header, '@scope'),\n owner: getTagValue(header, '@owner'),\n needs: getTagValue(header, '@needs'),\n purpose_statement: getTagValue(header, '@purpose-statement'),\n pipeline_declared: getTagValue(header, '@pipeline'),\n usage: readUsageValue(header)\n };\n\n const headerFieldCount = FRAMEWORK_FIELDS.filter((field) => String(values[field.key] || '').trim()).length;\n const hasAnyHeader = header.includes('@script') || header.includes('@summary');\n const hasFrameworkHeader = header.includes('@category') || header.includes('@purpose') || header.includes('@purpose-statement');\n\n return {\n ...values,\n header,\n header_field_count: headerFieldCount,\n has_any_header: hasAnyHeader,\n has_framework_header: hasFrameworkHeader,\n category_valid: values.category ? CATEGORY_ENUM.includes(values.category) : false,\n purpose_valid: values.purpose ? PURPOSE_ENUM.includes(values.purpose) : false,\n scope_valid: values.scope ? SCOPE_ENUM.includes(values.scope) : false\n };\n}\n\nfunction loadClassificationRows(trackedFiles, warnings) {\n if (!trackedFiles.includes(CLASSIFICATION_DATA_PATH)) {\n warnings.push(`Missing classification data file: ${CLASSIFICATION_DATA_PATH}`);",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "audit:scripts"
+ },
+ {
+ "type": "npm-script",
+ "caller": "tools/package.json",
+ "pipeline": "manual",
+ "script_name": "audit:scripts:verbose"
+ }
+ ],
+ "outputs": [
+ {
+ "output_path": "stdout",
+ "type": "stdout",
+ "call": "console"
+ }
+ ],
+ "outputs_display": "stdout only",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (npm script: audit:scripts); manual (npm script: audit:scripts:verbose)",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "snippets/automations/youtube/filterVideos.js",
+ "script": "filterVideos",
+ "category": "automation",
+ "purpose": "infrastructure:data-feeds",
+ "scope": "external",
+ "owner": "docs",
+ "needs": "F-R1",
+ "purpose_statement": "YouTube video filter — post-processes fetched YouTube data to filter/sort videos for display",
+ "pipeline_declared": "manual — not yet in pipeline",
+ "usage": "node snippets/automations/youtube/filterVideos.js [flags]",
+ "header": "/**\n * @script filterVideos\n * @category automation\n * @purpose infrastructure:data-feeds\n * @scope external\n * @owner docs\n * @needs F-R1\n * @purpose-statement YouTube video filter — post-processes fetched YouTube data to filter/sort videos for display\n * @pipeline manual — not yet in pipeline\n * @usage node snippets/automations/youtube/filterVideos.js [flags]\n */\nexport const filterVideos = (\n videos,\n excludeKeywords = [\"fireside\", \"watercooler\"]\n) => {\n return videos.filter((video) => {\n const title = video.title.toLowerCase();\n return !excludeKeywords.some((keyword) =>\n title.includes(keyword.toLowerCase())\n );\n });\n};\n",
+ "header_field_count": 8,
+ "has_any_header": true,
+ "has_framework_header": true,
+ "category_valid": true,
+ "purpose_valid": true,
+ "scope_valid": true,
+ "triggers": [
+ {
+ "type": "manual",
+ "caller": "none",
+ "pipeline": "manual"
+ }
+ ],
+ "outputs": [],
+ "outputs_display": "none detected",
+ "downstream_consumers": [],
+ "downstream_display": "No",
+ "in_json": true,
+ "category_match": true,
+ "purpose_match": true,
+ "pipeline_verified": "MATCH",
+ "declared_pipeline_set": {},
+ "actual_pipeline_set": {},
+ "pipeline_actual": "manual (none)",
+ "grade": "B",
+ "flags": [],
+ "trigger_group": "Manual"
+ },
+ {
+ "path": "tools/scripts/convert-rss-to-mdx.js",
+ "script": "convert-rss-to-mdx",
+ "category": "automation",
+ "purpose": "infrastructure:data-feeds",
+ "scope": "tools/scripts, v2/internal/assets/transcripts",
+ "owner": "docs",
+ "needs": "F-R1",
+ "purpose_statement": "RSS-to-MDX converter — imports RSS feed items and converts to MDX page format",
+ "pipeline_declared": "manual — interactive developer tool, not suited for automated pipelines",
+ "usage": "node tools/scripts/convert-rss-to-mdx.js [flags]",
+ "header": "#!/usr/bin/env node\n/**\n * @script convert-rss-to-mdx\n * @category automation\n * @purpose infrastructure:data-feeds\n * @scope tools/scripts, v2/internal/assets/transcripts\n * @owner docs\n * @needs F-R1\n * @purpose-statement RSS-to-MDX converter — imports RSS feed items and converts to MDX page format\n * @pipeline manual — interactive developer tool, not suited for automated pipelines\n * @usage node tools/scripts/convert-rss-to-mdx.js [flags]\n */\n\nconst fs = require('fs')\nconst path = require('path')\n\nfunction parseArgs(argv) {\n const args = {}\n for (let i = 0; i < argv.length; i += 1) {\n const token = argv[i]\n if (!token.startsWith('--')) continue\n const key = token.slice(2)\n const next = argv[i + 1]\n if (!next || next.startsWith('--')) {\n args[key] = true\n } else {\n args[key] = next\n i += 1\n }\n }\n return args\n}\n\nfunction toAbsolutePath(p) {\n if (!p) return ''\n return path.isAbsolute(p) ? p : path.join(process.cwd(), p)\n}\n\nfunction decodeEntities(input = '') {\n return input\n .replace(//g, '$1')\n .replace(/&/g, '&')\n .replace(/</g, '<')\n .replace(/>/g, '>')\n .replace(/"/g, '\"')\n .replace(/'/g, \"'\")\n .replace(/'/g, \"'\")\n .replace(/ /g, ' ')\n}\n\nfunction stripHtml(input = '') {\n return decodeEntities(input)\n .replace(//gi, '\\n')\n .replace(/<\\/p>/gi, '\\n')\n .replace(/]*>/gi, '')\n .replace(/<[^>]+>/g, '')\n .replace(/\\n{3,}/g, '\\n\\n')\n .trim()\n}\n\nfunction firstMatch(regex, text, fallback = '') {\n const match = text.match(regex)\n return match ? match[1].trim() : fallback\n}\n\nfunction escapeYamlSingleQuoted(value = '') {\n return String(value).replace(/'/g, \"''\")\n}\n\nfunction parseRss(xml) {\n const channelBlock = firstMatch(/([\\s\\S]*?)