docguard-cli 0.36.1 → 0.37.0

package/cli/shared-requirements.mjs

@@ -0,0 +1,91 @@
+/**
+ * Requirement identity parsing shared by traceability and lifecycle recovery.
+ * Only declaration-shaped Markdown counts; prose, comments, code fences, and
+ * example sections cannot mint identities.
+ */
+
+export const DEFAULT_REQ_PATTERNS = [
+  /\b(REQ)-(\d{2,4})\b/g,
+  /\b(FR)-(\d{2,4})\b/g,
+  /\b(NFR)-(\d{2,4})\b/g,
+  /\b(US)-(\d{2,4})\b/g,
+  /\b(STORY)-(\d{2,4})\b/g,
+  /\b(AC)-(\d{2,4})\b/g,
+  /\b(UC)-(\d{2,4})\b/g,
+  /\b(SYS)-(\d{2,4})\b/g,
+  /\b(ARCH)-(\d{2,4})\b/g,
+  /\b(MOD)-(\d{2,4})\b/g,
+  /\b(SC)-(\d{2,4})\b/g,
+  /(?<=\[[ xX]\]\s|@(?:req|task|covers)\s)(T)(\d{3,4})\b/g,
+];
+
+export function requirementPatterns(config = {}) {
+  const customPattern = config.traceability?.requirementPattern;
+  return customPattern
+    ? [new RegExp(customPattern, 'g')]
+    : DEFAULT_REQ_PATTERNS;
+}
+
+/**
+ * Return path-qualified identities from one Markdown artifact.
+ * @returns {Map<string, {id:string, file:string, line:number, text:string}>}
+ */
+export function collectRequirementIdsFromContent(content, docName, patterns = DEFAULT_REQ_PATTERNS) {
+  const reqIds = new Map();
+  const hasMatch = patterns.some(pattern => {
+    pattern.lastIndex = 0;
+    return pattern.test(content);
+  });
+  if (!hasMatch) return reqIds;
+
+  const lines = content.split('\n');
+  let fence = null;
+  let exampleLevel = null;
+  let inComment = false;
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    if (/^(?: {4}|\t)/.test(line) && !fence && !inComment) continue;
+    const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length
+        && line.slice(marker[0].length).trim() === '') fence = null;
+      continue;
+    }
+    if (marker) { fence = marker[1]; continue; }
+    line = line.replace(/<!--[\s\S]*?-->/g, '');
+    if (inComment) {
+      const close = line.indexOf('-->');
+      if (close < 0) continue;
+      line = line.slice(close + 3);
+      inComment = false;
+    }
+    const open = line.indexOf('<!--');
+    if (open >= 0) { line = line.slice(0, open); inComment = true; }
+    const heading = line.match(/^\s{0,3}(#{1,6})\s+(.*)/);
+    if (heading) {
+      if (exampleLevel !== null && heading[1].length <= exampleLevel) exampleLevel = null;
+      if (exampleLevel === null && /^(?:(?:requirement|task)[ -]+)?(?:examples?|ID[ -]+(?:formats?|syntax|examples?)|(?:formats?|syntax)[ -]+(?:of[ -]+)?IDs?)\b/i.test(heading[2])) {
+        exampleLevel = heading[1].length;
+      }
+    }
+    if (exampleLevel !== null) continue;
+    for (const pattern of patterns) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(line)) !== null) {
+        const prefix = line.slice(0, match.index);
+        if (!/^\s{0,3}(?:#{1,6}\s+|[-*+]\s+(?:\[[ xX]\]\s+)?|\d+[.)]\s+|\|\s*)?[\s*`_]*$/.test(prefix)) {
+          if (!match[0].length) pattern.lastIndex++;
+          continue;
+        }
+        const reqId = match[0];
+        if (!reqId.length) { pattern.lastIndex++; continue; }
+        const key = `${docName}#${reqId}`;
+        if (!reqIds.has(key)) {
+          reqIds.set(key, { id: reqId, file: docName, line: i + 1, text: line.trim() });
+        }
+      }
+    }
+  }
+  return reqIds;
+}

package/cli/validators/docs-coverage.mjs

@@ -19,10 +19,12 @@ import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
  * existing tests are unaffected; guard just renders richer output.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, relative, basename, extname } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync, lstatSync } from 'node:fs';
+import { resolve, join, relative, basename, extname, isAbsolute } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { shouldIgnore, walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
+import { shouldIgnore, walkFiles as sharedWalkFiles, buildIgnoreFilter, mergeIgnoreFile, DEFAULT_IGNORE_DIRS } from '../shared-ignore.mjs';
+import { resolveDocDirs } from '../shared.mjs';
+import { parseJsTs, walk } from '../scanners/js-ast.mjs';
 import { detectIaC, hasInfrastructureHeading, buildIaCWarning } from '../scanners/iac.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
@@ -73,7 +75,7 @@ export function validateDocsCoverage(projectDir, config) {
   let total = 0;
 
   // Collect all doc content for searching
-  const allDocContent = collectDocContent(projectDir);
+  const allDocContent = collectDocContent(projectDir, config);
   if (!allDocContent) {
     // Literal legacy shape (no findings key) — tests deepEqual this exact object.
     return { errors: [], warnings: [], passed: 0, total: 0 };
@@ -172,7 +174,7 @@ function checkConfigFiles(projectDir, allDocContent, config = {}) {
         code: 'DCV001',
         validator: 'docsCoverage',
         severity: 'warn',
-        message: `Config file "${entry}" exists but is not mentioned in any documentation. Document its purpose in ARCHITECTURE.md or README.md`,
+        message: `Config file "${entry}" exists but is not mentioned in scanned supported Markdown or extension YAML documentation. Document its purpose in ARCHITECTURE.md or README.md`,
         location: entry,
         suggestion: { kind: 'fix', text: 'Explain what this config file does in ARCHITECTURE.md or README.md' },
       }));
@@ -372,42 +374,60 @@ function checkIaCDocumentation(projectDir, iac, config = {}) {
 }
 
 /**
- * Check 4: Config files that code actually READS are documented.
- *
- * Scans source code for resolve(dir, '.configname') and existsSync('.configname')
- * patterns — these are configs the project USES. Avoids matching config names
- * sitting in arrays (scan patterns for detecting other projects' configs).
+ * Check 4: Distinguish direct file IO from config-like path expressions.
+ * Parsed calls exclude comments and example strings. Unparsed text supplies
+ * review candidates only; it cannot establish file IO or documentation need.
  */
 function checkCodeReferencedConfigs(projectDir, allDocContent, config = {}) {
   const findings = [];
   let passed = 0;
   let total = 0;
-
   const lowerDocContent = allDocContent.toLowerCase();
-  const foundConfigs = new Set();
-
-  // Only match config filenames inside function calls that actually USE the file:
-  // resolve(dir, '.docguardignore'), existsSync('.env.example'), readFileSync('vitest.config.ts')
-  const usageRegex = /(?:resolve|join|existsSync|readFileSync|accessSync|writeFileSync)\s*\([^)]*['"`]([^'"`\n]{2,})['"`]/g;
+  const foundConfigs = new Map();
+  const methods = new Set(['resolve', 'join', 'existsSync', 'accessSync', 'readFileSync', 'writeFileSync']);
+  const directIO = new Set(['readFileSync', 'writeFileSync']);
 
   const scanFile = (filePath) => {
-    const ext = extname(filePath);
-    if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) return;
+    if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(extname(filePath))) return;
     let content;
     try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
-
-    usageRegex.lastIndex = 0;
-    let match;
-    while ((match = usageRegex.exec(content)) !== null) {
-      const name = match[1];
-      // Must be a dotfile (.something) or *.config.* — not a path
-      if (name.includes('/') || name.startsWith('..')) continue;
-      const isDotConfig = name.startsWith('.') && name.length > 2;
-      const isNamedConfig = /^[\w-]+\.config\.\w+$/.test(name);
-      if (!isDotConfig && !isNamedConfig) continue;
-      // Skip bare extensions
-      if (/^\.[a-z]{1,4}$/i.test(name)) continue;
-      foundConfigs.add(name);
+    if (!/(?:resolve|join|existsSync|accessSync|readFileSync|writeFileSync)\s*\(/.test(content)) return;
+    // Parsing cannot yield a config candidate without a matching literal prefix.
+    // Keep every escaped source conservatively: escapes may encode that prefix.
+    if (!/['"\x60](?:\.(?![./])|[\w-]+\.config\.)|\\/.test(content)) return;
+    const source = relative(projectDir, filePath).split('\\').join('/');
+    const record = (name, method, line, parsed) => {
+      if (typeof name !== 'string' || name.includes('/') || name.includes('\\') || name.startsWith('..')) return;
+      if (!(name.startsWith('.') && name.length > 2) && !/^[\w-]+\.config\.\w+$/.test(name)) return;
+      if (/^\.[a-z]{1,4}$/i.test(name) || COMMON_DOTFILES.has(name)) return;
+      const direct = parsed && directIO.has(method);
+      // Prefer concrete IO when the same name also occurs in a path expression.
+      if (!foundConfigs.has(name) || (direct && !foundConfigs.get(name).direct)) {
+        foundConfigs.set(name, { direct, parsed, method, source: source + ':' + line });
+      }
+    };
+    const { ast, ok } = parseJsTs(content, filePath);
+    if (ok && !ast.errors?.length) {
+      walk(ast, node => {
+        if (node.type !== 'CallExpression') return;
+        const callee = node.callee;
+        const method = callee.type === 'Identifier' ? callee.name
+          : callee.type === 'MemberExpression' && !callee.computed ? callee.property.name : null;
+        if (!methods.has(method)) return;
+        // IO and existence checks use argument one as the path; join/resolve
+        // may supply a filename in any segment. No dynamic-path evaluation.
+        const args = ['join', 'resolve'].includes(method) ? node.arguments : node.arguments.slice(0, 1);
+        for (const arg of args) {
+          const value = arg.type === 'StringLiteral' ? arg.value
+            : arg.type === 'TemplateLiteral' && arg.expressions.length === 0 ? arg.quasis[0].value.cooked : null;
+          record(value, method, node.loc.start.line, true);
+        }
+      });
+    } else {
+      const pattern = /\b(resolve|join|existsSync|accessSync|readFileSync|writeFileSync)\s*\([^)]*?['"\x60]([^'"\x60\n]{2,})['"\x60]/g;
+      for (const match of content.matchAll(pattern)) {
+        record(match[2], match[1], content.slice(0, match.index).split('\n').length, false);
+      }
     }
   };
 
@@ -415,19 +435,26 @@ function checkCodeReferencedConfigs(projectDir, allDocContent, config = {}) {
     walkFiles(rootDir, scanFile);
   }
 
-  for (const configName of foundConfigs) {
-    if (COMMON_DOTFILES.has(configName)) continue;
+  for (const [configName, evidence] of foundConfigs) {
     total++;
     if (lowerDocContent.includes(configName.toLowerCase())) {
       passed++;
     } else {
+      const scope = 'scanned supported Markdown or extension YAML documentation';
+      const context = evidence.parsed ? evidence.method + ' call' : 'unparsed source text (parser unavailable or failed)';
       findings.push(mkFinding({
         code: 'DCV004',
         validator: 'docsCoverage',
         severity: 'warn',
-        message: `Code references config file "${configName}" but no documentation mentions it. Add it to README.md or ARCHITECTURE.md`,
+        confidence: evidence.direct ? 'high' : 'low',
+        message: evidence.direct
+          ? 'Direct ' + context + ' references config file "' + configName + '" at ' + evidence.source + ', but it is not mentioned in ' + scope + '.'
+          : 'Config-like path "' + configName + '" appears in ' + context + ' at ' + evidence.source + '; file use and documentation need are unverified. No mention was found in ' + scope + '.',
+        // Preserve the published filename location; source context is in the message.
         location: configName,
-        suggestion: { kind: 'fix', text: 'Describe this config file (purpose and format) in README.md or ARCHITECTURE.md' },
+        suggestion: evidence.direct
+          ? { kind: 'fix', text: 'Describe this config file (purpose and format) in a supported documentation file' }
+          : { kind: 'review', text: 'Inspect this source reference: it may be a directory, generated output, or example. Document it only if appropriate.' },
       }));
     }
   }
@@ -500,36 +527,59 @@ function checkReadmeSections(projectDir) {
 /**
  * Collect all documentation content into a single searchable string.
  */
-function collectDocContent(projectDir) {
-  const docPaths = [];
-
-  const rootDocs = ['README.md', 'AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'STANDARD.md'];
-  for (const doc of rootDocs) {
-    const p = resolve(projectDir, doc);
-    if (existsSync(p)) docPaths.push(p);
-  }
-
-  for (const doc of listCanonicalDocs(projectDir)) docPaths.push(doc.abs); // recursive
-
-  const extDir = resolve(projectDir, 'extensions');
-  if (existsSync(extDir)) {
-    walkFiles(extDir, (f) => {
-      if (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml')) {
-        docPaths.push(f);
+function collectDocContent(projectDir, config = {}) {
+  const docPaths = new Set();
+  const visited = new Set();
+  const isIgnored = buildIgnoreFilter(mergeIgnoreFile(projectDir, { ...config }).ignore);
+
+  // Check every ancestor before traversal: the shared walker follows symlinks.
+  // Explicit homes must remain scoped inside the project, including private aliases.
+  const safePath = (path) => {
+    const normalized = path.replace(/\\/g, '/');
+    if (isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized) || normalized.includes('\0')) return null;
+    const parts = normalized.split('/').filter(p => p && p !== '.');
+    if (!parts.length || parts.some(p => p === '..' || ['.local', '.git'].includes(p.toLowerCase())
+        || /^\.env(?:\.|$)/i.test(p) || DEFAULT_IGNORE_DIRS.has(p) || IGNORE_DIRS.has(p))) return null;
+    let current = resolve(projectDir);
+    let rel = '';
+    try {
+      for (const part of parts) {
+        rel = rel ? rel + '/' + part : part;
+        if (isIgnored(rel) || isIgnored(rel + '/')) return null;
+        current = join(current, part);
+        if (lstatSync(current).isSymbolicLink()) return null;
       }
-    });
-  }
-
-  for (const docsDir of ['docs', 'docs-implementation']) {
-    const d = resolve(projectDir, docsDir);
-    if (existsSync(d)) {
-      walkFiles(d, (f) => {
-        if (f.endsWith('.md')) docPaths.push(f);
-      });
+      return current;
+    } catch { return null; }
+  };
+  const addDoc = (rel) => {
+    const abs = safePath(rel);
+    if (abs && lstatSync(abs).isFile()) docPaths.add(abs);
+  };
+  const walkDocs = (rel) => {
+    const dir = safePath(rel);
+    if (!dir || visited.has(dir)) return;
+    visited.add(dir);
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const path = relative(projectDir, join(dir, entry.name)).split('\\').join('/');
+      if (entry.isDirectory() && !entry.name.startsWith('.')) walkDocs(path);
+      else if (entry.isFile() && (/\.md$/i.test(entry.name)
+          || (path.startsWith('extensions/') && /\.ya?ml$/i.test(entry.name)))) addDoc(path);
     }
+  };
+
+  for (const doc of ['README.md', 'AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'STANDARD.md']) addDoc(doc);
+  for (const dir of resolveDocDirs(projectDir, config)) walkDocs(dir);
+  // Resolve roles directly so raw callers get the same boundaries as loadConfig.
+  for (const role of Object.keys(config.docs?.roles || {})) {
+    const abs = resolveDocRole(projectDir, config, role);
+    addDoc(relative(projectDir, abs));
   }
 
-  if (docPaths.length === 0) return null;
+  if (docPaths.size === 0) return null;
   const parts = [];
   for (const p of docPaths) {
     try { parts.push(readFileSync(p, 'utf-8')); } catch { /* skip */ }

package/cli/validators/document-lifecycle.mjs

@@ -0,0 +1,51 @@
+import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { scanDocumentLifecycle } from '../scanners/document-lifecycle.mjs';
+
+/**
+ * Finds terminal lifecycle declarations and specs whose task list is complete.
+ * Both remain review signals; `retire --write` still requires explicit paths.
+ */
+export function validateDocumentLifecycle(projectDir, config = {}) {
+  const { scanned, candidates, coverage } = scanDocumentLifecycle(projectDir, config);
+  if (coverage.status === 'unavailable' && coverage.reason === 'not-git') {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+  const findings = candidates.map(candidate => mkFinding({
+    code: candidate.code,
+    validator: 'documentLifecycle',
+    severity: 'warn',
+    confidence: candidate.confidence === 'high' ? 'high' : 'low',
+    message: candidate.code === 'DLC001'
+      ? `${candidate.path} declares terminal lifecycle status "${candidate.status}" but remains in active AI context.`
+      : candidate.code === 'DLC004'
+        ? `${candidate.path} is recorded as retired but remains in the working tree.`
+        : `${candidate.path} has ${candidate.reason}`,
+    location: candidate.path,
+    suggestion: {
+      kind: 'review',
+      text: 'Confirm shipped outcomes are represented in current docs, then archive the explicit path.',
+      command: `docguard retire --write --path ${candidate.path} --reason "<why this is no longer current>"`,
+    },
+  }));
+  if (coverage.status !== 'complete') {
+    findings.push(mkFinding({
+      code: 'DLC003',
+      validator: 'documentLifecycle',
+      severity: 'warn',
+      confidence: 'high',
+      message: coverage.status === 'unavailable'
+        ? `Document lifecycle coverage is unavailable: ${coverage.error}`
+        : `Document lifecycle coverage is partial; ${coverage.unreadable.length} tracked Markdown file(s) could not be read.`,
+      location: coverage.unreadable[0] || null,
+      suggestion: {
+        kind: 'review',
+        text: 'Restore readable Git/document access and rerun guard; an incomplete scan cannot prove lifecycle hygiene.',
+      },
+    }));
+  }
+  return resultFromFindings(findings, {
+    passed: Math.max(0, scanned - candidates.length),
+    total: scanned + (coverage.status === 'unavailable' ? 1 : 0),
+    applicable: scanned > 0 || coverage.status !== 'complete',
+  });
+}

package/cli/validators/schema-sync.mjs

@@ -10,15 +10,14 @@ import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
  * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, relative, extname, basename } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
-import { walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
+import { DEFAULT_IGNORE_DIRS, relPosix, shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
 const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  ...DEFAULT_IGNORE_DIRS,
   '.amplify-hosting', '.serverless',
 ]);
 
@@ -192,7 +191,8 @@ function detectAllModels(projectDir, config = {}) {
  * Find schema files for a given detector configuration.
  */
 function findSchemaFiles(projectDir, detector, config = {}) {
-  const files = [];
+  // Deduplicate files, not model names: separate schemas may share a name.
+  const files = new Set();
 
   // Monorepo-aware: resolve each searchDir against the project root AND every
   // configured source root (config.sourceRoot + workspaces), so schemas under
@@ -203,19 +203,24 @@ function findSchemaFiles(projectDir, detector, config = {}) {
   for (const base of bases) {
     for (const searchDir of detector.searchDirs) {
       const dir = resolve(base, searchDir);
-      if (seenDirs.has(dir) || !existsSync(dir)) continue;
+      const rel = relPosix(projectDir, dir);
+      if (seenDirs.has(dir) || !existsSync(dir) ||
+          rel.split('/').some(part => IGNORE_DIRS.has(part)) ||
+          shouldIgnore(rel + '/', config)) continue;
       seenDirs.add(dir);
-      scanSchemaDir(dir, detector.filePattern, files);
+      scanSchemaDir(dir, detector.filePattern, files, projectDir, config);
     }
   }
 
-  return files;
+  return [...files];
 }
 
 // v0.29 consolidation: traversal delegates to the shared canonical walker.
-function scanSchemaDir(dir, filePattern, files) {
+function scanSchemaDir(dir, filePattern, files, projectDir, config) {
   sharedWalkFiles(dir, (full) => {
-    if (filePattern.test(basename(full))) files.push(full);
+    if (filePattern.test(basename(full)) && !shouldIgnore(relPosix(projectDir, full), config)) {
+      files.add(full);
+    }
   }, { ignoreDirs: IGNORE_DIRS });
 }
 

package/cli/validators/spec-registry.mjs

@@ -0,0 +1,47 @@
+import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { projectSpecRegistry, SPEC_REGISTRY_PATH } from '../scanners/spec-registry.mjs';
+
+export function validateSpecRegistry(projectDir, config = {}) {
+  const projection = projectSpecRegistry(projectDir, config);
+  if (projection.detected === 0 && !projection.exists) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+  const findings = projection.issues.map(issue => mkFinding({
+    code: issue.code,
+    validator: 'specRegistry',
+    severity: 'warn',
+    confidence: 'high',
+    message: issue.message,
+    location: issue.path,
+    suggestion: {
+      kind: 'review',
+      text: issue.code === 'SPR002'
+        ? 'Assign a unique immutable Spec ID in the authoritative spec metadata.'
+        : 'Resolve the lifecycle or registry integrity conflict, then refresh the registry.',
+      command: 'docguard specs --write',
+    },
+  }));
+  if (!projection.current && projection.issues.length === 0) {
+    findings.push(mkFinding({
+      code: 'SPR001',
+      validator: 'specRegistry',
+      severity: 'warn',
+      confidence: 'high',
+      message: projection.exists
+        ? `${SPEC_REGISTRY_PATH} does not match the current deterministic spec evidence projection.`
+        : `${SPEC_REGISTRY_PATH} is missing while active specifications exist.`,
+      location: SPEC_REGISTRY_PATH,
+      suggestion: {
+        kind: 'fix',
+        text: 'Refresh derived evidence without changing reviewed lifecycle fields.',
+        command: 'docguard specs --write',
+      },
+    }));
+  }
+  const checks = Math.max(1, projection.registry.specs.length + projection.registry.tombstones.length);
+  return resultFromFindings(findings, {
+    passed: Math.max(0, checks - findings.length),
+    total: checks,
+    applicable: true,
+  });
+}