docguard-cli 0.23.0 → 0.25.0

package/cli/scanners/schemas.mjs

@@ -8,11 +8,10 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
-
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo',
-]);
+import { extractJsSchemaBodies } from './js-ast.mjs';
+import { extractPythonFiles } from './py-ast.mjs';
+import { readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix } from '../shared-ignore.mjs';
 
 /**
  * Deep scan schemas from ORM definitions, validation libraries, and OpenAPI specs.
@@ -21,7 +20,7 @@ const IGNORE_DIRS = new Set([
  * @param {object} docTools - Detected doc tools (may include OpenAPI)
  * @returns {object} { entities: [...], relationships: [...], source: string }
  */
-export function scanSchemasDeep(dir, stack, docTools) {
+export function scanSchemasDeep(dir, stack, docTools, config = {}) {
   // Priority 1: OpenAPI schemas
   if (docTools?.openapi?.found && docTools.openapi.schemas?.length > 0) {
     return {
@@ -78,10 +77,22 @@ export function scanSchemasDeep(dir, stack, docTools) {
     }
   }
 
+  // Honor .docguardignore / config.ignore: drop entities whose source file the
+  // user excluded (e.g. test/fixtures/**), then drop relationships that point at
+  // a dropped entity. Filtering the RESULTS (not the walk) keeps the cache and
+  // the per-ORM walkers untouched. entity.file is project-relative already.
+  const keptEntities = entities.filter(
+    e => !e.file || !shouldIgnore(relPosix(dir, resolve(dir, e.file)), config)
+  );
+  const keptNames = new Set(keptEntities.map(e => e.name));
+  const keptRelationships = keptEntities.length === entities.length
+    ? relationships
+    : relationships.filter(r => keptNames.has(r.from) && keptNames.has(r.to));
+
   return {
-    entities,
-    relationships,
-    source: entities.length > 0 ? entities[0].source : 'none',
+    entities: keptEntities,
+    relationships: keptRelationships,
+    source: keptEntities.length > 0 ? keptEntities[0].source : 'none',
   };
 }
 
@@ -220,26 +231,15 @@ function scanDrizzleSchemas(dir) {
       const content = readFileSafe(filePath);
       if (!content || !content.includes('Table(')) return;
 
-      let match;
-      const regex = new RegExp(tablePattern.source, 'g');
-      while ((match = regex.exec(content)) !== null) {
-        const varName = match[1];
-        const tableName = match[2];
-        const body = match[3];
+      // Emit one entity from a (tableName, body) pair. `body` is the balanced
+      // inner text of the table's column object.
+      const emit = (tableName, body) => {
         const fields = parseDrizzleColumns(body);
-
-        // Look for references (foreign keys)
         for (const field of fields) {
           if (field._ref) {
-            relationships.push({
-              from: tableName,
-              to: field._ref,
-              type: 'many-to-one',
-              field: field.name,
-            });
+            relationships.push({ from: tableName, to: field._ref, type: 'many-to-one', field: field.name });
           }
         }
-
         entities.push({
           name: tableName,
           fields: fields.map(f => ({ ...f, _ref: undefined })),
@@ -247,6 +247,17 @@ function scanDrizzleSchemas(dir) {
           source: 'drizzle',
           description: '',
         });
+      };
+
+      // Full-support tier: AST extraction (nested braces handled). Falls back
+      // to the legacy regex only when @babel/parser can't parse the file.
+      const ast = extractJsSchemaBodies(content, filePath);
+      if (ast) {
+        for (const s of ast) if (s.kind === 'drizzle') emit(s.table, s.body);
+      } else {
+        let match;
+        const regex = new RegExp(tablePattern.source, 'g');
+        while ((match = regex.exec(content)) !== null) emit(match[2], match[3]);
       }
     });
   }
@@ -327,20 +338,28 @@ function scanZodSchemas(dir) {
       const content = readFileSafe(filePath);
       if (!content || !content.includes('z.object')) return;
 
-      let match;
-      const regex = new RegExp(zodPattern.source, 'g');
-      while ((match = regex.exec(content)) !== null) {
-        const schemaName = match[1].replace(/Schema$|Validator$/, '');
-        const body = match[2];
-        const fields = parseZodFields(body);
-
+      const emit = (rawName, body) => {
+        const schemaName = rawName.replace(/Schema$|Validator$/, '');
         entities.push({
           name: schemaName,
-          fields,
+          fields: parseZodFields(body),
           file: relative(dir, filePath),
           source: 'zod',
           description: '',
         });
+      };
+
+      const ast = extractJsSchemaBodies(content, filePath);
+      if (ast) {
+        // Keep the legacy naming gate (only *Schema/Validator/Input/Output) so
+        // inline z.object() validations aren't treated as data-model entities.
+        for (const s of ast) {
+          if (s.kind === 'zod' && /(?:Schema|Validator|Input|Output)$/.test(s.name)) emit(s.name, s.body);
+        }
+      } else {
+        let match;
+        const regex = new RegExp(zodPattern.source, 'g');
+        while ((match = regex.exec(content)) !== null) emit(match[1], match[2]);
       }
     });
   }
@@ -407,25 +426,14 @@ function scanMongooseSchemas(dir) {
       const content = readFileSafe(filePath);
       if (!content || !content.includes('Schema(')) return;
 
-      let match;
-      const regex = new RegExp(schemaPattern.source, 'g');
-      while ((match = regex.exec(content)) !== null) {
-        const schemaName = match[1].replace(/Schema$/i, '');
-        const body = match[2];
+      const emit = (rawName, body) => {
+        const schemaName = rawName.replace(/Schema$/i, '');
         const fields = parseMongooseFields(body);
-
-        // Check for refs (relationships)
         for (const field of fields) {
           if (field._ref) {
-            relationships.push({
-              from: schemaName,
-              to: field._ref,
-              type: 'many-to-one',
-              field: field.name,
-            });
+            relationships.push({ from: schemaName, to: field._ref, type: 'many-to-one', field: field.name });
           }
         }
-
         entities.push({
           name: schemaName.charAt(0).toUpperCase() + schemaName.slice(1),
           fields: fields.map(f => ({ ...f, _ref: undefined })),
@@ -433,6 +441,15 @@ function scanMongooseSchemas(dir) {
           source: 'mongoose',
           description: '',
         });
+      };
+
+      const ast = extractJsSchemaBodies(content, filePath);
+      if (ast) {
+        for (const s of ast) if (s.kind === 'mongoose') emit(s.name, s.body);
+      } else {
+        let match;
+        const regex = new RegExp(schemaPattern.source, 'g');
+        while ((match = regex.exec(content)) !== null) emit(match[1], match[2]);
       }
     });
   }
@@ -504,8 +521,38 @@ function mapMongooseType(type) {
 function scanPythonModels(dir) {
   const entities = [];
   const relationships = [];
-  walkDir(dir, (filePath) => {
-    if (!filePath.endsWith('.py')) return;
+
+  // Collect .py files first so the AST tier parses them in ONE python3
+  // subprocess. `null` → Python unavailable / subprocess failed → regex
+  // fallback for all; a per-file `ok:false` falls back for that file only.
+  // The AST tier gets every field exactly (no body-capture truncation, no
+  // miss on multi-base classes) — undercounting fields is what makes the
+  // data-model validators falsely pass on a stale DATA-MODEL.md.
+  const pyFiles = [];
+  walkDir(dir, (filePath) => { if (filePath.endsWith('.py')) pyFiles.push(filePath); });
+  const astByFile = extractPythonFiles(pyFiles);
+
+  for (const filePath of pyFiles) {
+    const parsed = astByFile && astByFile[filePath];
+    if (parsed && parsed.ok) {
+      for (const s of parsed.schemas || []) {
+        const fields = (s.fields || []).map(f => ({
+          name: f.name, type: f.type || '', required: f.required !== false, description: '',
+        }));
+        if (fields.length > 0) entities.push({ name: s.name, fields, file: filePath, source: s.kind });
+        for (const to of s.rels || []) relationships.push({ from: s.name, to, type: 'related' });
+      }
+      continue;
+    }
+    scanPythonModelsRegex(filePath, entities, relationships);
+  }
+  return { entities, relationships };
+}
+
+// Regex (beta) fallback — used per-file when the Python AST tier is unavailable
+// or couldn't parse that file. Identical behavior to the pre-AST scanner.
+function scanPythonModelsRegex(filePath, entities, relationships) {
+  {
     const content = readFileSafe(filePath);
     if (!content) return;
     if (!/class\s+\w+\s*\([^)]*(Base|BaseModel|db\.Model|Model|SQLModel)/.test(content)) return;
@@ -549,8 +596,7 @@ function scanPythonModels(dir) {
       }
       if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'pydantic' });
     }
-  });
-  return { entities, relationships };
+  }
 }
 
 // ── Rust: Diesel `table! { ... }` ─────────────────────────────────────────────
@@ -687,7 +733,7 @@ function extractOpenAPIRelationships(schemas) {
 }
 
 function readFileSafe(path) {
-  try { return readFileSync(path, 'utf-8'); } catch { return null; }
+  return readScannable(path); // size-capped; skips minified/generated bundles
 }
 
 // v0.15-P2: walkDir is called 8 times across schemas.mjs (Pydantic, Mongoose,

package/cli/shared-ignore.mjs

@@ -50,7 +50,22 @@ const ALWAYS_REJECT_PATH_RE =
  * Returns [] if the file is missing or unreadable — never throws.
  */
 import { readFileSync, existsSync } from 'node:fs';
-import { resolve as resolvePath } from 'node:path';
+import { resolve as resolvePath, relative as relativePath, sep } from 'node:path';
+
+/**
+ * Project-relative path with POSIX (`/`) separators — the canonical form that
+ * every validator should compare against docs, ignore globs, and changed-file
+ * sets.
+ *
+ * Replaces the old `absPath.replace(projectDir + '/', '')` idiom, which failed
+ * two ways: on Windows the `/` literal never matched the OS `\` separators, and
+ * for a sibling dir sharing a prefix (`/repo` vs `/repo-staging`) the replace
+ * was a no-op — both cases left an ABSOLUTE path, silently breaking
+ * `content.includes(relPath)`, glob matching, and `--changed-only` scoping.
+ */
+export function relPosix(projectDir, absPath) {
+  return relativePath(projectDir, absPath).split(sep).join('/');
+}
 
 export function loadDocguardIgnore(projectDir) {
   const p = resolvePath(projectDir, '.docguardignore');
@@ -98,7 +113,13 @@ export function mergeIgnoreFile(projectDir, config) {
  * @returns {RegExp}
  */
 function globToRegex(pattern) {
-  const escaped = pattern
+  // gitignore-style trailing slash ("dir/") means "this directory and everything
+  // under it". Strip it so "dir/" matches identically to "dir" — otherwise the
+  // escaped pattern keeps the slash and the alternation below can only match a
+  // literal "dir//" (double slash), so the pattern silently matches nothing.
+  // `|| pattern` guards the degenerate all-slashes case (e.g. "/") from emptying.
+  const normalized = pattern.replace(/\/+$/, '') || pattern;
+  const escaped = normalized
     .replace(/\./g, '\\.')
     .replace(/\*\*/g, '§§')     // temp placeholder for **
     .replace(/\*/g, '[^/]*')

package/cli/shared-source.mjs

@@ -39,6 +39,39 @@ function safeReadJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return null; }
 }
 
+/**
+ * Files DocGuard reads WHOLE and regex/AST-scans. A bundle, minified vendor
+ * file, or generated client checked into source is slow to read, hostile to
+ * regex, expensive to AST-parse, and is never the project's authored truth.
+ * 1.5 MB sits far above any hand-written module yet below typical bundles.
+ */
+export const MAX_SCAN_BYTES = 1_500_000;
+
+/** True for build artifacts / minified / generated / declaration files. */
+export function isGeneratedPath(p) {
+  const b = String(p);
+  return /\.min\.[cm]?js$/i.test(b)
+      || /\.(bundle|chunk)\.[cm]?jsx?$/i.test(b)
+      || /[.-]generated\.[a-z0-9]+$/i.test(b)
+      || /\.d\.ts$/i.test(b);
+}
+
+/**
+ * Read a source file for scanning, or return null when it should be skipped:
+ * unreadable, a generated/minified artifact, or larger than `maxBytes`. This is
+ * the single guard that keeps every scanner from choking on a checked-in
+ * bundle. Skipping is logged by callers that care (most just see "no match").
+ */
+export function readScannable(absPath, { maxBytes = MAX_SCAN_BYTES } = {}) {
+  try {
+    if (isGeneratedPath(absPath)) return null;
+    if (statSync(absPath).size > maxBytes) return null;
+    return readFileSync(absPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Expand a workspace glob (e.g. "packages/*") into concrete directories
  * that contain a package.json. Only the trailing single-level "/*" glob is
@@ -236,8 +269,8 @@ export function grepEnvUsage(projectDir, config = {}) {
     if (!CODE_EXTENSIONS.has(extname(filePath))) return;
     const rel = relative(projectDir, filePath);
     if (shouldIgnore(rel, config)) return;
-    let content;
-    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+    const content = readScannable(filePath);
+    if (content === null) return; // unreadable, generated, or too large to scan
     if (!content.includes('env')) return;
     // patterns[2] is the import.meta.env one — its matches are Vite-injected
     // when the name is an intrinsic, and must not be reported as user env vars.
@@ -250,6 +283,30 @@ export function grepEnvUsage(projectDir, config = {}) {
         names.add(m[1]);
       }
     }
+
+    // v0.24: env vars are increasingly declared in a validation schema
+    // (Zod / envalid / convict) and read via a typed `config` object instead of
+    // `process.env.X` — so the direct-access patterns above miss them and every
+    // documented var looked "missing from code" (field report). Only harvest
+    // when the file actually validates process.env through such a schema.
+    const validatesEnv =
+      /(?:safeParse|parse)\s*\(\s*process\.env\b/.test(content) || // zod: schema.parse(process.env)
+      /\bcleanEnv\s*\(\s*process\.env\b/.test(content) ||          // envalid
+      /\bconvict\s*\(/.test(content);                              // convict
+    if (validatesEnv) {
+      let km;
+      // Zod / envalid: the schema KEYS are the env var names. Data schemas use
+      // camelCase keys, so requiring UPPER_SNAKE keeps this env-specific.
+      const keyRe = /^\s*['"]?([A-Z][A-Z0-9_]*[A-Z0-9])['"]?\s*:/gm;
+      while ((km = keyRe.exec(content)) !== null) {
+        if (km[1].length >= 3 && !VITE_INTRINSICS.has(km[1])) names.add(km[1]);
+      }
+      // convict: the env var name is the `env:` property value, not the key.
+      const convictRe = /\benv\s*:\s*['"]([A-Z][A-Z0-9_]*[A-Z0-9])['"]/g;
+      while ((km = convictRe.exec(content)) !== null) {
+        if (km[1].length >= 3) names.add(km[1]);
+      }
+    }
   };
 
   const walk = (dir) => {

package/cli/shared-trace-patterns.mjs

@@ -12,6 +12,19 @@
  * pattern (app/api, pages/api) preserved from the v0.22.0 #195 fix.
  */
 
+/**
+ * A markdown file is documentation, never the source that *implements* a
+ * canonical doc — so it must not count as a doc→code match. Without this,
+ * SECURITY.md's "Auth modules" glob (which includes `guard`) matched
+ * `commands/docguard.guard.md` and listed DocGuard's own command docs as the
+ * project's auth modules (field report). Real config-file matches (.env,
+ * Dockerfile, pyproject.toml, .gitignore) are unaffected — none are `.md`.
+ * Used by both `docguard trace` and the guard-time Traceability validator.
+ */
+export function isTraceableSource(relPath) {
+  return !relPath.endsWith('.md');
+}
+
 export const TEST_PATTERNS = [
   // JS/TS
   /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.test\.(mjs|cjs)$/,

package/cli/shared.mjs

@@ -39,6 +39,65 @@ export function resolveSeverity(config, validatorKey) {
   return 'medium';
 }
 
+// ── Canonical section heading matching ─────────────────────────────────────
+/**
+ * Required canonical sections used to be matched by literal substring, so an
+ * arc42/C4 doc with "## 5.4 Layer boundaries" or "## Building Block View"
+ * scored as if the section were absent — the validator made well-structured
+ * docs look WORSE than the skeleton (field report). These synonyms + section-
+ * number tolerance let equivalent headings count. Synonyms only ever ADD
+ * matches; the literal canonical heading always still passes.
+ *
+ * Keyed by the normalized canonical heading (lowercase, alphanumerics + spaces).
+ */
+export const SECTION_SYNONYMS = {
+  'system overview':       ['system context', 'system summary', 'introduction and goals', 'context and scope', 'overview and goals'],
+  'component map':         ['components', 'component overview', 'building block view', 'building blocks', 'containers', 'module overview'],
+  'tech stack':            ['technology stack', 'technologies', 'technical stack'],
+  'entities':              ['entity definitions', 'data model', 'domain model', 'data entities'],
+  'authentication':        ['auth', 'authn', 'authentication and authorization', 'identity'],
+  'secrets management':    ['secrets', 'secret management', 'secrets handling', 'credentials', 'credential management'],
+  'test categories':       ['test types', 'categories of tests', 'test strategy', 'testing strategy', 'test approach'],
+  'coverage rules':        ['coverage', 'coverage targets', 'coverage goals', 'coverage requirements', 'coverage policy'],
+  'environment variables': ['env vars', 'environment', 'configuration', 'config variables'],
+  'setup steps':           ['setup', 'getting started', 'installation', 'setup instructions', 'local setup', 'quick start'],
+  'layer boundaries':      ['layers', 'layering', 'module boundaries', 'layer boundary', 'boundaries'],
+  'external dependencies': ['dependencies', 'external systems', 'third party dependencies', 'integrations', 'external interfaces'],
+  'revision history':      ['changelog', 'change history', 'history', 'revisions', 'document history', 'change log'],
+};
+
+/** Normalize a markdown heading: drop #, leading arc42-style numbers, punctuation. */
+function normalizeHeadingText(line) {
+  return line
+    .replace(/^#{1,6}\s*/, '')             // strip leading #s
+    .replace(/^\d+(?:\.\d+)*\.?\s+/, '')   // strip leading "5.4 " / "3. " section numbers
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')           // non-alphanumeric → single space
+    .trim();
+}
+
+/**
+ * True if `content` has an H2–H6 heading equivalent to `canonicalHeading` —
+ * the exact text, a known synonym, or the same text behind an arc42-style
+ * section number (e.g. "## 5.4 Layer boundaries" satisfies "## Layer Boundaries").
+ *
+ * @param {string} content - markdown file contents
+ * @param {string} canonicalHeading - e.g. '## Component Map' or 'Component Map'
+ */
+export function docHasSection(content, canonicalHeading) {
+  const key = normalizeHeadingText(canonicalHeading);
+  if (!key) return false;
+  const accepted = [key, ...(SECTION_SYNONYMS[key] || [])];
+  const headings = content.match(/^#{2,6}\s+.+$/gm) || [];
+  for (const line of headings) {
+    const norm = normalizeHeadingText(line);
+    for (const phrase of accepted) {
+      if (norm.includes(phrase)) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Parse a dotted-decimal version string into a tuple of integers for
  * comparison. Tolerates extra suffixes (e.g. `0.4-beta` → [0, 4]).
@@ -85,7 +144,7 @@ export const c = {
 // ── Compliance Profiles ───────────────────────────────────────────────────
 export const PROFILES = {
   starter: {
-    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
+    description: 'Minimal CDD — architecture + changelog, no Spec Kit framework scaffold (pass --spec-kit to add it). For side projects and prototypes.',
     requiredFiles: {
       canonical: [
         'docs-canonical/ARCHITECTURE.md',
@@ -124,6 +183,38 @@ export const PROFILES = {
       freshness: true,
     },
   },
+  // F3 (field report): non-web-centric profiles. The default doc set assumes an
+  // HTTP API + database; for a CLI or library that structure fights the project.
+  // These drop the HTTP/DB-shaped requirements. (A bespoke CLI-REFERENCE doc type
+  // is a separate, larger follow-up; until then API-REFERENCE doubles as the
+  // library's module-API reference.)
+  cli: {
+    description: 'CLI / command-line tool — no HTTP API or database assumed.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+        'docs-canonical/TEST-SPEC.md',
+        'docs-canonical/SECURITY.md',
+        'docs-canonical/ENVIRONMENT.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+  },
+  library: {
+    description: 'Library / package — public API matters; no HTTP server or DB assumed.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+        'docs-canonical/API-REFERENCE.md',
+        'docs-canonical/TEST-SPEC.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+  },
   'enterprise-ai': {
     description: 'EU AI Act compliance — Annex IV documentation requirements, ALCOA+ alignment, strict freshness. For AI/ML projects under regulatory scrutiny.',
     requiredFiles: {

package/cli/validator-markers.mjs

@@ -0,0 +1,91 @@
+/**
+ * Inline whole-validator N/A markers — "declare intentional non-applicability,
+ * visibly."
+ *
+ * A project can mute an entire validator from inside its docs, with the
+ * rationale right next to the declaration and tracked in git:
+ *
+ *   <!-- docguard:validator testSpec n/a — POC, no automated tests yet -->
+ *   <!-- docguard:validator traceability n/a — no formal requirements doc -->
+ *
+ * This is the validator-level sibling of the section-level
+ * `<!-- docguard:section <id> n/a — reason -->`. Unlike the config switch
+ * (`validators: { testSpec: false }`), which renders as a silent "disabled",
+ * a marked validator renders as a visible `➖ [N/A] (declared N/A: reason)` —
+ * honest non-applicability, not an invisible skip or a fake green check.
+ *
+ * Markers are read from the project's primary docs (canonical docs + the root
+ * agent/readme files) so the rationale lives where humans and agents read.
+ *
+ * Zero NPM dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// `<!-- docguard:validator <key> n/a [— reason] -->`
+// Separator before the reason may be —, :, or one-or-more hyphens. Reason
+// is optional. Case-insensitive on the keyword and "n/a".
+const MARKER_RE = /<!--\s*docguard:validator\s+([A-Za-z0-9_-]+)\s+n\/a\b\s*(?:[—:\-]+\s*([^>]*?))?\s*-->/gi;
+
+/** Files where a validator marker is honored — the docs humans actually read. */
+function markerSourceFiles(projectDir) {
+  const files = [];
+  const canonicalDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonicalDir)) {
+    try {
+      for (const f of readdirSync(canonicalDir)) {
+        if (f.toLowerCase().endsWith('.md')) files.push(join(canonicalDir, f));
+      }
+    } catch { /* ignore */ }
+  }
+  for (const root of ['AGENTS.md', 'README.md', 'CLAUDE.md']) {
+    const p = resolve(projectDir, root);
+    if (existsSync(p)) files.push(p);
+  }
+  return files;
+}
+
+/** Normalize a key for tolerant matching: `Test-Spec`/`test_spec` → `testspec`. */
+function norm(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/**
+ * Scan the project's primary docs for `docguard:validator <key> n/a` markers.
+ *
+ * @param {string} projectDir
+ * @param {Iterable<string>} validKeys - the canonical validator keys (camelCase)
+ * @returns {{ suppressed: Map<string,string>, unknown: Array<{raw:string, file:string}> }}
+ *   `suppressed` maps a canonical validator key → reason ('' if none given).
+ *   `unknown` lists markers whose key didn't resolve (typo protection).
+ */
+export function loadValidatorSuppressions(projectDir, validKeys) {
+  const canonicalByNorm = new Map();
+  for (const k of validKeys) canonicalByNorm.set(norm(k), k);
+
+  const suppressed = new Map();
+  const unknown = [];
+
+  for (const file of markerSourceFiles(projectDir)) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    if (!content.includes('docguard:validator')) continue;
+
+    MARKER_RE.lastIndex = 0;
+    let m;
+    while ((m = MARKER_RE.exec(content)) !== null) {
+      const rawKey = m[1];
+      const reason = (m[2] || '').trim();
+      const canonical = canonicalByNorm.get(norm(rawKey));
+      if (!canonical) {
+        unknown.push({ raw: rawKey, file });
+        continue;
+      }
+      // First marker wins; keep its reason. Re-declaring is harmless.
+      if (!suppressed.has(canonical)) suppressed.set(canonical, reason);
+    }
+  }
+
+  return { suppressed, unknown };
+}

package/cli/validators/api-surface.mjs

@@ -29,6 +29,7 @@ import { detectOpenAPI } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { parseApiReferenceDoc, compareEndpoints, endpointKey } from '../scanners/api-doc.mjs';
 import { collectPackageJsons, getWorkspaceDirs } from '../shared-source.mjs';
+import { relPosix } from '../shared-ignore.mjs';
 
 const MAX_REPORTED = 15;
 const API_DOC = 'docs-canonical/API-REFERENCE.md';
@@ -86,15 +87,35 @@ export function findAllOpenApiSpecs(projectDir, config) {
     seenAbs.add(absPath);
     specs.push({
       absPath,
-      relPath: absPath.startsWith(resolve(projectDir))
-        ? absPath.slice(resolve(projectDir).length + 1)
-        : absPath,
+      relPath: relPosix(projectDir, absPath),
       endpoints: oa.endpoints.filter(e => e && e.method && e.path),
     });
   }
   return specs;
 }
 
+/**
+ * OpenAPI specs that exist and declare a `paths:` section but parsed to ZERO
+ * endpoints — i.e. DocGuard's minimal YAML/JSON parser couldn't extract them
+ * (an unsupported feature: `$ref`, anchors, folded scalars). These are silently
+ * skipped by findAllOpenApiSpecs (good — code scanning takes over), but the
+ * parse failure must be SURFACED so a broken spec doesn't masquerade as a
+ * clean "no API surface" pass. Returns relative spec paths.
+ */
+export function findUnparseableSpecs(projectDir, config) {
+  const out = [];
+  const seen = new Set();
+  for (const dir of orderedSpecDirs(projectDir, config)) {
+    const oa = detectOpenAPI(dir);
+    if (!oa.found || !oa.parseIncomplete) continue;
+    const abs = resolve(dir, oa.path);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(relPosix(projectDir, abs));
+  }
+  return out;
+}
+
 /**
  * Detect divergence between multiple canonical OpenAPI specs.
  * @returns {null | { specs, divergent: string[], authoritative: string }}
@@ -208,6 +229,19 @@ export function validateApiSurface(projectDir, config) {
     }
   }
 
+  // ── Honest-failure: an OpenAPI spec we couldn't parse ──
+  // A spec that declares paths but yielded zero endpoints means our parser
+  // choked on it. We fall back to code scanning (below), but the parse failure
+  // is surfaced here rather than silently producing a clean "no surface" pass.
+  for (const specPath of findUnparseableSpecs(projectDir, config)) {
+    warnings.push(
+      `OpenAPI spec ${specPath} declares paths but DocGuard parsed 0 endpoints from it ` +
+      `(likely an unsupported YAML feature — $ref, anchors, or folded scalars). ` +
+      `Falling back to code scanning; the spec's own endpoint list is unavailable. ` +
+      `Validate it with a full OpenAPI linter.`
+    );
+  }
+
   const drift = computeApiSurfaceDrift(projectDir, config);
 
   // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──