#!/usr/bin/env node /** * Generate docs/reference/findings.md from the finding-code registry, so the * published reference cannot drift from what `docguard explain` prints. * * npm run docs:reference # write * npm run docs:reference -- --check # exit 1 when stale (CI, tests) * * @implements docguard.user-documentation#FR-004 */ import { readFileSync, writeFileSync } from 'node:fs'; import { resolve, dirname } from 'node:path'; import { fileURLToPath } from 'node:url'; import { CODES, BLOCKER_CODES } from '../cli/findings.mjs'; import { DISPLAY_NAMES } from '../cli/commands/explain.mjs'; import { skillSectionBlock } from '../cli/authoring-contract.mjs'; const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..'); export const FINDINGS_REFERENCE = 'docs/reference/findings.md'; /** Files that carry the authoring-contract block (docguard.authoring-contract#FR-003). */ export const AUTHORING_BLOCK_FILES = ['extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md', '.agent/skills/docguard-fix/SKILL.md']; const BLOCK_RE = /[\s\S]*?/; /** `text` with its authoring-contract block replaced by the registry's, or null without a block. */ export function withAuthoringBlock(text) { return BLOCK_RE.test(text) ? text.replace(BLOCK_RE, skillSectionBlock()) : null; } const normalize = s => String(s).toLowerCase().replace(/[^a-z0-9]/g, ''); const NAME_BY_KEY = new Map(Object.entries(DISPLAY_NAMES).map(([key, name]) => [normalize(key), { key, name }])); const anchor = s => s.toLowerCase().replace(/[^a-z0-9 -]/g, '').trim().replace(/\s+/g, '-'); export function renderFindingsReference() { const groups = new Map(); for (const [code, entry] of Object.entries(CODES)) { const known = NAME_BY_KEY.get(normalize(entry.validator)); const key = known?.key ?? entry.validator; if (!groups.has(key)) groups.set(key, { name: known?.name ?? entry.validator, codes: [] }); groups.get(key).codes.push([code, entry]); } const ordered = [...groups.entries()].sort((a, b) => a[1].name.localeCompare(b[1].name)); const total = Object.keys(CODES).length; const blockers = Object.entries(BLOCKER_CODES); const out = [ '---', 'title: Finding Codes', 'parent: Reference', 'nav_order: 5', '---', '', '# Finding Codes', '', '', '', `Every finding DocGuard reports carries a stable code. This page lists all ${total} finding codes, grouped by the validator that reports them, and the ${blockers.length} codes that block a \`specs\` command. Codes are never renumbered.`, '', 'The same text is available offline:', '', '```bash', 'docguard explain DSY001', '```', '', 'A code that accepts an in-place marker shows it below. Inline `docguard:ignore ` works only where it is shown (the security codes, REF001, REF002 and SPK010); other markers are specific to their code. A code with no marker has no in-place suppression: fix the cause, freeze it in the [adoption baseline](../configuration.md#adoption-baseline--baseline), or [mute the validator](../configuration.md#muting-a-validator) with a reason. A finding\'s severity, disposition, confidence and parser tier are explained in [Troubleshooting](../guides/troubleshooting.md).', '', '## Validators', '', '| Validator | Codes |', '|---|---|', ...ordered.map(([key, g]) => `| [${g.name}](#${anchor(`${g.name} ${key}`)}) | ${g.codes.map(([c]) => c).join(', ')} |`), `| [Command blockers](#command-blockers) | ${blockers.map(([c]) => c).join(', ')} |`, '', ]; for (const [key, g] of ordered) { out.push(`## ${g.name} (${key})`, ''); for (const [code, entry] of g.codes) { out.push(`### ${code}: ${entry.title}`, '', entry.help.trim(), ''); if (entry.defaultLevel === 'info') out.push('Informational by default: it does not change the exit code unless `findingSeverity` raises it.', ''); if (entry.suppress) out.push('Marker:', '', '```text', entry.suppress, '```', ''); } } out.push('## Command blockers', '', 'These codes stop a `docguard specs` subcommand before it writes anything. They are not guard findings.', ''); for (const [code, entry] of blockers) { out.push(`### ${code}: ${entry.title}`, '', `Reported by \`${entry.command}\`.`, '', entry.help.trim(), ''); } return `${out.join('\n').trimEnd()}\n`; } function main(argv) { const targets = [[FINDINGS_REFERENCE, () => renderFindingsReference()]]; for (const rel of AUTHORING_BLOCK_FILES) targets.push([rel, current => withAuthoringBlock(current ?? '')]); let stale = 0; for (const [rel, render] of targets) { const path = resolve(ROOT, rel); let current = null; try { current = readFileSync(path, 'utf-8'); } catch { /* missing counts as stale */ } const rendered = render(current); if (rendered === null) { console.error(`${rel} has no docguard:authoring-contract block.`); stale++; continue; } if (current === rendered) { console.log(`${rel} ${argv.includes('--check') ? 'is current.' : 'already current — nothing written.'}`); continue; } if (argv.includes('--check')) { console.error(`Out of date: ${rel} — run \`npm run docs:reference\`.`); stale++; continue; } writeFileSync(path, rendered, 'utf-8'); console.log(`Regenerated: ${rel}`); } return stale ? 1 : 0; } if (import.meta.url === `file://${process.argv[1]}`) { process.exit(main(process.argv.slice(2))); }