docguard-cli 0.23.0 → 0.25.0

package/cli/commands/upgrade.mjs

@@ -71,14 +71,48 @@ function readProjectSchemaVersion(projectDir) {
   }
 }
 
+/**
+ * Normalize the `requiredFiles` block to the canonical object shape
+ * (`{ canonical: [...], agentFile, changelog, driftLog }`). Validators read
+ * `config.requiredFiles?.canonical || []`, so a config whose `requiredFiles` is
+ * a bare array (a legacy/hand-edited shape) or an object that lost its
+ * `canonical` key makes Traceability/Structure/Freshness silently see an empty
+ * list and PASS — the exact false-green this tool exists to prevent.
+ *
+ * Returns `{ cfg, changed, notes }`. We only TRANSFORM the unambiguous case (a
+ * bare array can only ever have been the canonical doc list); any other broken
+ * shape is SURFACED as a note rather than guessed at.
+ */
+function normalizeRequiredFiles(cfg) {
+  const rf = cfg.requiredFiles;
+  const notes = [];
+  if (rf === undefined || rf === null) {
+    // No requiredFiles at all — validators default to empty and check nothing.
+    // Don't fabricate a list (we can't know the project's docs); surface it.
+    notes.push('⚠ requiredFiles is missing — Traceability/Structure/Freshness have nothing to verify (silent-pass risk). Run `docguard init` to generate it.');
+    return { cfg, changed: false, notes };
+  }
+  if (Array.isArray(rf)) {
+    notes.push('Normalized legacy requiredFiles array → { canonical: [...] } so canonical-doc checks see your docs again.');
+    return { cfg: { ...cfg, requiredFiles: { canonical: rf } }, changed: true, notes };
+  }
+  if (typeof rf === 'object' && !Array.isArray(rf.canonical)) {
+    notes.push('⚠ requiredFiles.canonical is missing or not an array — canonical-doc checks will silently pass. Restore it or run `docguard init`.');
+  }
+  return { cfg, changed: false, notes };
+}
+
 /**
  * Idempotent migration: walk the project config and add any fields introduced
- * since the stored schema version. Returns { changed, newConfig }.
+ * since the stored schema version, then normalize the requiredFiles shape.
+ * Returns { changed, newConfig, notes }.
  *
- * Each migration is keyed by the version it migrates TO. Adding a new schema
- * version means adding one entry here.
+ * Each version migration is keyed by the version it migrates TO. Adding a new
+ * schema version means adding one entry here. The requiredFiles normalization
+ * runs regardless of the version delta — a config can sit at the current
+ * version yet still carry a hand-edited shape that breaks validators silently.
  */
-function migrateSchema(cfg, fromVersion) {
+export function migrateSchema(cfg, fromVersion) {
   const migrations = {
     // v0.4 — pre-0.4 schemas (no `version` field, often `project` instead
     // of `projectName`) normalize here. Rename `project` → `projectName`
@@ -99,16 +133,24 @@ function migrateSchema(cfg, fromVersion) {
   let current = { ...cfg };
   let changed = false;
   const target = CURRENT_SCHEMA_VERSION;
-  // No migrations yet — current schema matches the constant.
-  if (compareVersions(fromVersion, target) >= 0) return { changed: false, newConfig: current };
-  for (const [ver, fn] of Object.entries(migrations)) {
-    if (compareVersions(fromVersion, ver) < 0 && compareVersions(ver, target) <= 0) {
-      current = fn(current);
-      changed = true;
+
+  // Version-keyed field migrations (additive). Skipped when already current.
+  if (compareVersions(fromVersion, target) < 0) {
+    for (const [ver, fn] of Object.entries(migrations)) {
+      if (compareVersions(fromVersion, ver) < 0 && compareVersions(ver, target) <= 0) {
+        current = fn(current);
+        changed = true;
+      }
     }
+    if (changed) current.version = target;
   }
-  if (changed) current.version = target;
-  return { changed, newConfig: current };
+
+  // requiredFiles shape normalization — independent of the version delta.
+  const norm = normalizeRequiredFiles(current);
+  current = norm.cfg;
+  if (norm.changed) changed = true;
+
+  return { changed, newConfig: current, notes: norm.notes };
 }
 
 /**
@@ -291,7 +333,13 @@ export async function runUpgrade(projectDir, _config, flags) {
     if (schemaBehind && projectSchema) {
       const cfgPath = resolve(projectDir, '.docguard.json');
       const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
-      const { changed, newConfig } = migrateSchema(cfg, projectSchema);
+      const { changed, newConfig, notes } = migrateSchema(cfg, projectSchema);
+      // Surface requiredFiles findings (a normalization that happened, or a
+      // broken shape we refuse to guess at) before reporting the version bump.
+      for (const n of notes || []) {
+        const warn = n.startsWith('⚠');
+        console.log(`  ${warn ? c.yellow : c.dim}${warn ? '' : '• '}${n}${c.reset}`);
+      }
       if (changed) {
         // v0.14-P4: --pr opens a PR for review instead of in-place editing.
         // Useful when the team wants a reviewable diff or has branch-protected

package/cli/config.mjs

@@ -10,13 +10,17 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
-import { c, PROFILES } from './shared.mjs';
+import { c, PROFILES, SEVERITY_LEVELS } from './shared.mjs';
 import { mergeIgnoreFile } from './shared-ignore.mjs';
 
 export function loadConfig(projectDir) {
   const configPath = resolve(projectDir, '.docguard.json');
   const defaults = {
     projectName: basename(projectDir),
+    // Legacy/unversioned fallback ONLY — the value a config is ASSUMED to be
+    // when its file has no `version` field. NOT the current schema version
+    // (that's CURRENT_SCHEMA_VERSION in shared.mjs, written by `init`). Kept low
+    // on purpose so a versionless (pre-0.4) config still trips the upgrade nudge.
     version: '0.2',
     profile: 'standard',
     requiredFiles: {
@@ -89,6 +93,19 @@ export function loadConfig(projectDir) {
       const merged = deepMerge(withProfile, normalizeConfig(userConfig));
       merged.profile = profileName;
 
+      // v0.24: severity accepts only high|medium|low and changes EXIT-CODE
+      // weight — it never mutes a warning from display. A value like "off"
+      // silently fell back to "medium", so users who wrote severity:{k:"off"}
+      // expecting silence still saw the warning and got no feedback (field
+      // report). Surface the misconfig and point at the real disable switch.
+      if (merged.severity && typeof merged.severity === 'object') {
+        for (const [key, val] of Object.entries(merged.severity)) {
+          if (typeof val === 'string' && !SEVERITY_LEVELS.has(val.toLowerCase())) {
+            console.error(`${c.yellow}⚠ .docguard.json: severity.${key} = "${val}" is not a valid level${c.reset} ${c.dim}(use high | medium | low). To silence a validator entirely, set ${c.reset}${c.cyan}validators.${key}: false${c.dim}.${c.reset}`);
+          }
+        }
+      }
+
       // Auto-detect project type if not set
       if (!merged.projectType) {
         merged.projectType = autoDetectProjectType(projectDir);

package/cli/docguard.mjs

@@ -125,7 +125,7 @@ ${c.bold}Options:${c.reset}
                   code-truth skeleton. Add --write to scaffold, --format json
                   for the machine-readable manifest.
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
-  --profile <p>   Compliance profile: starter, standard, enterprise (init command)
+  --profile <p>   Profile: starter, standard, cli, library, enterprise (init command)
   --tax           Show estimated documentation maintenance cost (with score)
   --help          Show this help message
   --version       Show version
@@ -133,6 +133,8 @@ ${c.bold}Options:${c.reset}
 ${c.bold}Profiles:${c.reset}
   ${c.green}starter${c.reset}      Minimal CDD — just ARCHITECTURE.md + CHANGELOG (side projects)
   ${c.green}standard${c.reset}     Full CDD — all 5 canonical docs (default, team projects)
+  ${c.green}cli${c.reset}          CLI tool — no HTTP API / DB (ARCHITECTURE, TEST-SPEC, SECURITY, ENVIRONMENT)
+  ${c.green}library${c.reset}      Library — public API, no HTTP/DB (ARCHITECTURE, API-REFERENCE, TEST-SPEC)
   ${c.green}enterprise${c.reset}   Strict CDD — all docs + all validators + freshness enforced
 
 ${c.bold}Examples:${c.reset}
@@ -158,6 +160,135 @@ ${c.bold}Learn more:${c.reset}
 `);
 }
 
+// ── Per-command help (v0.24, field report B6) ───────────────────────────────
+// `docguard <command> --help` now prints the flags + examples for THAT command,
+// so a flag like `generate --plan --write` or `init --skeleton` is discoverable.
+// Only flags that genuinely apply to each command are listed (derived from the
+// vetted global help above). Commands without a focused entry fall back to the
+// global help, which still lists them.
+const COMMAND_HELP = {
+  init: {
+    summary: 'Bootstrap CDD docs — smart-scans existing code, or writes blank templates.',
+    usage: 'docguard init [--skeleton|--wizard] [--profile <p>] [--with <name>] [--fix]',
+    flags: [
+      ['--skeleton', 'Blank templates instead of the smart scan-and-propose'],
+      ['--wizard', 'Guided interactive onboarding'],
+      ['--with <name>', 'Add a scaffolder: agents, hooks, ci, badge, llms, publish'],
+      ['--profile <p>', 'starter | standard | cli | library | enterprise (default: standard)'],
+      ['--skip-prompts', 'Non-interactive; create the profile defaults (CI)'],
+      ['--fix', 'Headless: create any missing required docs from templates'],
+      ['--force', 'Overwrite existing files (.bak backup kept)'],
+    ],
+    examples: ['docguard init', 'docguard init --skeleton', 'docguard init --profile starter --skip-prompts', 'docguard init --with ci'],
+  },
+  generate: {
+    summary: 'Reverse-engineer canonical docs from existing code.',
+    usage: 'docguard generate [--plan [--write] [--format json]] [--force]',
+    flags: [
+      ['--plan', 'AI scan: emit the agent task manifest + code-truth skeleton'],
+      ['--write', 'With --plan: scaffold the skeleton docs to disk'],
+      ['--format json', 'With --plan: machine-readable manifest'],
+      ['--force', 'Overwrite existing docs (.bak backup kept)'],
+    ],
+    examples: ['docguard generate', 'docguard generate --plan', 'docguard generate --plan --write', 'docguard generate --plan --format json'],
+  },
+  guard: {
+    summary: 'Validate code against canonical docs (all validators).',
+    usage: 'docguard guard [--format json] [--changed-only] [--fail-on-warning]',
+    flags: [
+      ['--format json', 'Machine-readable results for CI'],
+      ['--changed-only', 'Only validate docs/code touched in the working tree'],
+      ['--fail-on-warning', 'Exit non-zero on warnings (strict CI)'],
+    ],
+    examples: ['docguard guard', 'docguard guard --format json'],
+  },
+  score: {
+    summary: 'CDD maturity score (0–100).',
+    usage: 'docguard score [--diff] [--tax] [--format json]',
+    flags: [
+      ['--diff', 'Delta between two refs'],
+      ['--tax', 'Estimated documentation maintenance cost'],
+      ['--format json', 'Machine-readable score'],
+    ],
+    examples: ['docguard score', 'docguard score --tax'],
+  },
+  diff: {
+    summary: 'Show gaps between docs and code.',
+    usage: 'docguard diff [--since <ref>]',
+    flags: [['--since <ref>', 'Restrict to files changed since <ref> (impact mode)']],
+    examples: ['docguard diff', 'docguard diff --since HEAD~5'],
+  },
+  sync: {
+    summary: 'Refresh code-truth doc sections (preview by default).',
+    usage: 'docguard sync [--write] [--since <ref>]',
+    flags: [
+      ['--write', 'Apply the refresh (default is a dry-run preview)'],
+      ['--since <ref>', 'Only sync sections whose source files changed since <ref>'],
+    ],
+    examples: ['docguard sync', 'docguard sync --write'],
+  },
+  fix: {
+    summary: 'Generate AI fix instructions for docs (or apply deterministic fixes).',
+    usage: 'docguard fix [--doc <name>] [--auto] [--write] [--force]',
+    flags: [
+      ['--doc <name>', 'Target a specific doc (architecture, security, …)'],
+      ['--auto', 'Auto-fix what is mechanically possible'],
+      ['--write', 'Apply deterministic fixes in place (docguard:generated docs)'],
+      ['--force', 'Allow edits outside docguard:generated docs'],
+    ],
+    examples: ['docguard fix --doc architecture', 'docguard diagnose'],
+  },
+  trace: {
+    summary: 'Requirements traceability matrix.',
+    usage: 'docguard trace [--reverse]',
+    flags: [['--reverse', 'Code→doc map instead of doc→code']],
+    examples: ['docguard trace', 'docguard trace --reverse'],
+  },
+  upgrade: {
+    summary: 'Migrate .docguard.json schema + CLI.',
+    usage: 'docguard upgrade [--apply] [--pr]',
+    flags: [
+      ['--apply', 'Write the migration (default is a preview)'],
+      ['--pr', 'Open a team-wide PR with the migration'],
+    ],
+    examples: ['docguard upgrade', 'docguard upgrade --apply'],
+  },
+  ci: {
+    summary: 'Generate CI / pipeline config.',
+    usage: 'docguard ci [--threshold <n>] [--fail-on-warning]',
+    flags: [
+      ['--threshold <n>', 'Minimum score for CI pass'],
+      ['--fail-on-warning', 'Fail CI on warnings'],
+    ],
+    examples: ['docguard ci'],
+  },
+  memory: {
+    summary: 'Show what DocGuard remembers about the project.',
+    usage: 'docguard memory [--diff]',
+    flags: [['--diff', 'Drill into drift between memory and code']],
+    examples: ['docguard memory', 'docguard memory --diff'],
+  },
+};
+
+function printCommandHelp(command) {
+  const h = COMMAND_HELP[command];
+  if (!h) { printHelp(); return; } // no focused entry — global help still lists it
+  printBanner();
+  console.log(`${c.bold}docguard ${command}${c.reset} — ${h.summary}\n`);
+  console.log(`${c.bold}Usage:${c.reset}\n  ${h.usage}\n`);
+  if (h.flags?.length) {
+    console.log(`${c.bold}Options:${c.reset}`);
+    for (const [flag, desc] of h.flags) console.log(`  ${c.cyan}${flag.padEnd(18)}${c.reset} ${desc}`);
+    console.log('');
+  }
+  if (h.examples?.length) {
+    console.log(`${c.bold}Examples:${c.reset}`);
+    for (const ex of h.examples) console.log(`  ${c.dim}${ex}${c.reset}`);
+    console.log('');
+  }
+  console.log(`${c.dim}All commands: ${c.cyan}docguard --help${c.reset}`);
+}
+
 // ── Main ───────────────────────────────────────────────────────────────────
 async function main() {
   const args = process.argv.slice(2);
@@ -241,6 +372,12 @@ async function main() {
       // Default stays on (discoverability), but lets minimalist library
       // projects skip the .specify/.agent/commands scaffolding.
       flags.noSpecKit = true;
+    } else if (args[i] === '--spec-kit') {
+      // v0.24: explicit opt-IN to the Spec Kit framework scaffold. The
+      // `starter` profile skips that scaffold by default (minimal, for side
+      // projects — it would otherwise drop ~30 files); pass --spec-kit to
+      // include it anyway. No effect on other profiles (already on by default).
+      flags.specKit = true;
     } else if (args[i] === '--pin') {
       // v0.17-P1: `docguard guard --pin` records the running CLI version
       // into .docguard.json (`docguardVersion` field) after a successful run.
@@ -298,6 +435,11 @@ async function main() {
       flags.debate = true;
     } else if (args[i] === '--stdout') {
       flags.stdout = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      // v0.24: capture --help anywhere on the line, not just as the bare
+      // command. Previously `docguard generate --help` fell through the parser
+      // and executed generate, scaffolding files into the cwd (field report).
+      flags.help = true;
     }
   }
 
@@ -313,14 +455,26 @@ async function main() {
     process.exit(0);
   }
 
+  // v0.24: `docguard <command> --help` shows that command's own flags +
+  // examples (field report B6); commands without a focused entry fall back to
+  // the global help. Non-destructive (generate no longer scaffolds on --help).
+  if (flags.help) {
+    printCommandHelp(command);
+    process.exit(0);
+  }
+
   // In JSON mode the entire stdout MUST be parseable JSON. The banner and
   // ensureSkills' install message would corrupt the output for any
   // programmatic consumer (CI, dashboards, the Score-on-PR Action recipe).
   // Headless flags (`--write`, `--check-only`, `--auto`) also suppress chrome.
   // v0.16-P5: --quiet (-q) joins the headless club for users who want
   // banner-free output without committing to a specific machine format.
+  // v0.24 (field report): `--plan` is a read-only preview — "show me, don't
+  // touch" — so it joins the club to suppress the banner AND ensureSkills'
+  // .agent/.specify writes, which were a surprising side effect of a bare
+  // `generate --plan` (and were already suppressed for `--plan --write`).
   const jsonMode = flags.format === 'json';
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet;
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan;
 
   if (!headless) printBanner();
 

package/cli/ensure-skills.mjs

@@ -46,9 +46,12 @@ const __dirname = dirname(__filename);
 const SKILLS_SOURCE = resolve(__dirname, '..', 'extensions', 'spec-kit-docguard', 'skills');
 const COMMANDS_SOURCE = resolve(__dirname, '..', 'commands');
 
-// Destination in the user's project
+// Destination in the user's project. Commands live UNDER `.agent/` alongside
+// skills (was root `commands/`, which polluted the project namespace and got
+// mis-scanned as source). `.agent/commands/` is the generic spec-kit convention
+// agents already discover, and keeps DocGuard's footprint in one place.
 const SKILLS_DEST = '.agent/skills';
-const COMMANDS_DEST = 'commands';
+const COMMANDS_DEST = '.agent/commands';
 
 // ── Agent Mode Detection ────────────────────────────────────────────────
 
@@ -195,14 +198,6 @@ export function isSpecKitInitialized(projectDir) {
 
 // ── Spec-Kit Integration Gate ───────────────────────────────────────────
 
-// Read DocGuard package version (for skill auto-update)
-const PKG_VERSION = (() => {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
-    return pkg.version || '0.0.0';
-  } catch { return '0.0.0'; }
-})();
-
 const SPEC_KIT_INSTALL_CMD = 'uv tool install specify-cli --from git+https://github.com/github/spec-kit.git';
 
 /**
@@ -225,6 +220,13 @@ export function ensureSpecKit(projectDir, flags = {}) {
     return { specKitReady: true };
   }
 
+  // Caller opted out of the Spec Kit framework scaffold (--no-spec-kit, or the
+  // minimal `starter` profile which passes noSpecKit through). Don't auto-init
+  // and don't nag — DocGuard's own skills/commands still install below.
+  if (flags.noSpecKit) {
+    return { specKitReady: false, skipped: true };
+  }
+
   // Spec-kit CLI available — auto-initialize
   if (isSpecKitAvailable()) {
     if (!silent) {
@@ -298,26 +300,22 @@ export function ensureSkills(projectDir, flags = {}) {
 
       for (const skillDir of skillDirs) {
         const destDir = resolve(projectDir, SKILLS_DEST, skillDir);
-        if (!existsSync(destDir)) {
-          mkdirSync(destDir, { recursive: true });
-        }
         const srcSkill = resolve(SKILLS_SOURCE, skillDir, 'SKILL.md');
         const destSkill = resolve(destDir, 'SKILL.md');
 
-        if (!existsSync(destSkill)) {
-          // New install
-          writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+        const srcContent = readFileSync(srcSkill, 'utf-8');
+        const installedContent = existsSync(destSkill) ? readFileSync(destSkill, 'utf-8') : null;
+
+        // Content-equality gate: write only when the bundled skill differs from
+        // what's on disk. Covers a fresh install AND a genuine update, but stops
+        // the per-command rewrite churn the old version-marker gate caused — a
+        // skill whose SKILL.md lacked a `docguard:version:` marker compared as
+        // '0.0.0', so it was rewritten (and announced) on EVERY command, even
+        // read-only ones like `explain`/`score` (field report, Issue D).
+        if (installedContent !== srcContent) {
+          if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+          writeFileSync(destSkill, srcContent, 'utf-8');
           result.skillsInstalled = true;
-        } else {
-          // Auto-update: check if package version is newer than installed
-          const installedContent = readFileSync(destSkill, 'utf-8');
-          const versionMatch = installedContent.match(/docguard:version:\s*(\S+)/);
-          const installedVersion = versionMatch ? versionMatch[1] : '0.0.0';
-
-          if (installedVersion !== PKG_VERSION) {
-            writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
-            result.skillsInstalled = true;
-          }
         }
       }
 

package/cli/scanners/api-doc.mjs

@@ -22,7 +22,17 @@ const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', '
 
 /**
  * Normalize an API path for comparison.
- * Strips decoration and collapses param syntax so `:id` and `{id}` match.
+ * Strips decoration and collapses ALL dynamic-segment syntaxes to a single `{}`
+ * placeholder so an endpoint documented one way matches the same endpoint
+ * emitted another way:
+ *   Express/colon   `/users/:id`            → `/users/{}`
+ *   OpenAPI/brace   `/users/{id}`           → `/users/{}`
+ *   Next.js bracket `/users/[id]`           → `/users/{}`
+ *   catch-all       `/auth/[...nextauth]`, `/auth/:nextauth*` → `/auth/{}`
+ *   optional c-all  `/shop/[[...filters]]`  → `/shop/{}`
+ * Without the bracket rule, a doc written in Next.js `[id]` syntax never matched
+ * the code-scan's `:id`, so every dynamic route double-fired as both
+ * "documented-but-absent" and "undocumented" (field test: hugocross_revamp).
  * @param {string} raw
  * @returns {string} normalized path (e.g. "/api/users/{}") or '' if not a path
  */
@@ -34,8 +44,12 @@ export function normalizePath(raw) {
   // cut query string / fragment
   p = p.split(/[?#]/)[0];
   if (!p.startsWith('/')) return '';
-  // collapse param syntax: :param and {param} → {}
-  p = p.replace(/\{[^}/]+\}/g, '{}').replace(/:[^/]+/g, '{}');
+  // collapse every param syntax to {}: Next.js [id]/[...slug]/[[...slug]],
+  // OpenAPI {param}, and colon :param (incl. catch-all :param*).
+  p = p
+    .replace(/\[{1,2}[^\]]*\]{1,2}/g, '{}')
+    .replace(/\{[^}/]+\}/g, '{}')
+    .replace(/:[^/]+/g, '{}');
   // strip trailing slash (but keep root "/")
   if (p.length > 1) p = p.replace(/\/+$/, '');
   return p;

package/cli/scanners/doc-tools.mjs

@@ -9,6 +9,21 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 
+/**
+ * Read + parse a JSON file, returning null on any error (missing, unreadable,
+ * malformed). A bare `JSON.parse(readFileSync(...))` on a malformed
+ * `package.json` used to THROW out of a detector and abort the entire
+ * `detectDocTools` scan — which then made the memory plan (and every validator
+ * that compares against it) see empty "truth" and falsely pass. Fail soft.
+ */
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Detect all documentation tools present in the project.
  * @param {string} dir - Project root directory
@@ -57,6 +72,7 @@ export function detectOpenAPI(dir) {
         endpoints: spec.endpoints,
         schemas: spec.schemas,
         info: spec.info,
+        parseIncomplete: spec.parseIncomplete === true,
       };
     }
   }
@@ -122,6 +138,14 @@ function parseOpenAPISpec(content, filename) {
     }
   } catch { /* spec parsing failed, return empty */ }
 
+  // Honest-failure signal: a spec that clearly declares a `paths:` section but
+  // yielded ZERO endpoints means our parser couldn't extract them (anchors,
+  // unresolved $ref, folded scalars, or a YAML feature the minimal parser
+  // doesn't cover). Flag it so the caller can WARN and fall back to code
+  // scanning, instead of silently reporting "no API surface" — a false green.
+  const hasPathsKey = /(^|\n)[ \t]*["']?paths["']?[ \t]*:/.test(content);
+  result.parseIncomplete = hasPathsKey && result.endpoints.length === 0;
+
   return result;
 }
 
@@ -215,12 +239,9 @@ function detectTypeDoc(dir) {
   }
 
   // Check package.json devDeps
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    if (pkg.devDependencies?.typedoc) {
-      return { found: true, config: 'package.json (devDependency)' };
-    }
+  const pkg = readJsonSafe(resolve(dir, 'package.json'));
+  if (pkg?.devDependencies?.typedoc) {
+    return { found: true, config: 'package.json (devDependency)' };
   }
 
   return { found: false };
@@ -236,12 +257,9 @@ function detectJSDoc(dir) {
     }
   }
 
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    if (pkg.devDependencies?.jsdoc) {
-      return { found: true, config: 'package.json (devDependency)' };
-    }
+  const pkg = readJsonSafe(resolve(dir, 'package.json'));
+  if (pkg?.devDependencies?.jsdoc) {
+    return { found: true, config: 'package.json (devDependency)' };
   }
 
   return { found: false };
@@ -316,9 +334,8 @@ function detectRedocly(dir) {
 // ── Swagger UI ─────────────────────────────────────────────────────────────
 
 function detectSwagger(dir) {
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const pkg = readJsonSafe(resolve(dir, 'package.json'));
+  if (pkg) {
     const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
     if (allDeps['swagger-ui-express'] || allDeps['@fastify/swagger'] || allDeps['swagger-jsdoc']) {
       return {

package/cli/scanners/frontend.mjs

@@ -16,12 +16,9 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
-import { resolveSourceRoots, collectPackageJsons } from '../shared-source.mjs';
-
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
-]);
+import { resolveSourceRoots, collectPackageJsons, readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { extractJsxRouteScreens } from './js-ast.mjs';
 const UI_EXT = new Set(['.tsx', '.jsx']);
 
 function walk(dir, onFile, depth = 0) {
@@ -36,7 +33,7 @@ function walk(dir, onFile, depth = 0) {
   }
 }
 
-function readSafe(p) { try { return readFileSync(p, 'utf-8'); } catch { return ''; } }
+function readSafe(p) { return readScannable(p) ?? ''; } // size-capped; skips bundles
 
 /** Normalize a route path param syntax to {param} and strip trailing slash. */
 function normRoute(p) {
@@ -111,6 +108,15 @@ function scanReactRouterScreens(roots, projectDir) {
       if (!content.includes('<Route') && !content.includes('createBrowserRouter') &&
           !content.includes('useRoutes') && !content.includes('createRoutesFrom')) return;
 
+      // AST-first: scopes each route's element JSX exactly (nested auth wrappers,
+      // layouts, and multi-line elements no longer truncate or mis-pick the
+      // screen). `null` → parse failure → the window-based regex fallback below.
+      const astScreens = extractJsxRouteScreens(content, file);
+      if (astScreens) {
+        for (const s of astScreens) add(s.path, pickScreenComponent(s.components), file);
+        return;
+      }
+
       let m;
       const re = new RegExp(pathRe.source, 'g');
       while ((m = re.exec(content)) !== null) {
@@ -434,5 +440,15 @@ export function scanFrontend(projectDir, config = {}) {
     a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
   const i18n = scanI18n(projectDir, roots);
 
-  return { ...stack, routerType, screens, components, stores, hooks, contexts, apiCalls, i18n };
+  // Honor .docguardignore / config.ignore — drop entries whose source file the
+  // user excluded (e.g. a fixtures/storybook dir). Entries without a `file`
+  // (or in i18n) are unaffected.
+  const keep = (arr) => Array.isArray(arr)
+    ? arr.filter(x => !x || !x.file || !shouldIgnore(relPosix(projectDir, resolve(projectDir, x.file)), config))
+    : arr;
+  return {
+    ...stack, routerType,
+    screens: keep(screens), components: keep(components), stores: keep(stores),
+    hooks: keep(hooks), contexts: keep(contexts), apiCalls: keep(apiCalls), i18n,
+  };
 }