docguard-cli 0.7.0 → 0.7.2

package/cli/commands/generate.mjs

@@ -406,8 +406,8 @@ function generateArchitecture(dir, config, stack, scan, flags, docTools) {
     componentRows.push(`| Storybook | UI component docs | .storybook/ (${docTools.storybook.storyCount || '?'} stories) | |`);
   }
 
-  // Doc tools section
-  const docToolRows = [];
+  // Doc tools section — always include DocGuard since it generated these docs
+  const docToolRows = ['| DocGuard | `.docguard.json` | Active |'];
   if (docTools?._detected?.length > 0) {
     for (const tool of docTools._detected) {
       const info = docTools[tool];

package/cli/commands/guard.mjs

@@ -17,6 +17,7 @@ import { validateSecurity } from '../validators/security.mjs';
 import { validateDocsSync } from '../validators/docs-sync.mjs';
 import { validateArchitecture } from '../validators/architecture.mjs';
 import { validateFreshness } from '../validators/freshness.mjs';
+import { validateTraceability } from '../validators/traceability.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -48,6 +49,7 @@ export function runGuardInternal(projectDir, config) {
       }
       return { errors, warnings, passed, total: passed + warnings.length + errors.length };
     }},
+    { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
   ];
 
   for (const { key, name, fn } of validatorMap) {

package/cli/commands/trace.mjs

@@ -53,7 +53,7 @@ const TRACE_MAP = {
   'TEST-SPEC.md': {
     standard: 'ISO/IEC/IEEE 29119-3',
     sourcePatterns: [
-      { label: 'Test files', glob: /\.(test|spec)\.[jt]sx?$/ },
+      { label: 'Test files', glob: /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/ },
       { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
       { label: 'E2E tests', glob: /(e2e|integration)\// },
     ],
@@ -89,7 +89,12 @@ export function runTrace(projectDir, config, flags) {
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);
 
-  // ── 1. Inventory canonical docs ──
+  // ── 1. Build set of required doc basenames from config ──
+  const requiredDocs = new Set(
+    (config.requiredFiles?.canonical || []).map(f => basename(f))
+  );
+
+  // ── 2. Inventory canonical docs ──
   const docsDir = resolve(projectDir, 'docs-canonical');
   const canonicalDocs = [];
   if (existsSync(docsDir)) {
@@ -98,16 +103,26 @@ export function runTrace(projectDir, config, flags) {
     }
   }
 
-  // ── 2. Scan project files ──
+  // ── 3. Scan project files ──
   const projectFiles = [];
   scanDir(projectDir, projectDir, projectFiles);
 
-  // ── 3. Build traceability matrix ──
+  // ── 4. Build traceability matrix (only required docs) ──
   const matrix = [];
+  const orphanedDocs = [];
 
   for (const [docName, traceInfo] of Object.entries(TRACE_MAP)) {
     const docPath = resolve(docsDir, docName);
     const docExists = existsSync(docPath);
+
+    // Check if this doc is excluded from config
+    if (!requiredDocs.has(docName)) {
+      if (docExists) {
+        orphanedDocs.push(docName);
+      }
+      continue; // Skip excluded docs from the matrix
+    }
+
     let lastModified = null;
     let docSize = 0;
 
@@ -152,15 +167,15 @@ export function runTrace(projectDir, config, flags) {
     });
   }
 
-  // ── 4. Output ──
+  // ── 5. Output ──
   if (flags.format === 'json') {
-    outputJSON(config.projectName, matrix);
+    outputJSON(config.projectName, matrix, orphanedDocs);
   } else {
-    outputText(config.projectName, matrix, canonicalDocs);
+    outputText(config.projectName, matrix, canonicalDocs, orphanedDocs);
   }
 }
 
-function outputJSON(projectName, matrix) {
+function outputJSON(projectName, matrix, orphanedDocs) {
   const result = {
     project: projectName,
     traceability: matrix.map(m => ({
@@ -173,19 +188,21 @@ function outputJSON(projectName, matrix) {
       tests: m.relatedTests.length,
       traces: m.traces,
     })),
+    orphanedDocs,
     summary: {
       total: matrix.length,
       traced: matrix.filter(m => m.coverageSignal === 'TRACED').length,
       partial: matrix.filter(m => m.coverageSignal === 'PARTIAL').length,
       unlinked: matrix.filter(m => m.coverageSignal === 'UNLINKED').length,
       missing: matrix.filter(m => m.coverageSignal === 'MISSING').length,
+      orphaned: orphanedDocs.length,
     },
     timestamp: new Date().toISOString(),
   };
   console.log(JSON.stringify(result, null, 2));
 }
 
-function outputText(projectName, matrix, canonicalDocs) {
+function outputText(projectName, matrix, canonicalDocs, orphanedDocs) {
   // Header table
   console.log(`  ${c.bold}Traceability Matrix${c.reset}\n`);
   console.log(`  ${c.dim}${'Document'.padEnd(22)} ${'Standard'.padEnd(28)} ${'Status'.padEnd(10)} ${'Sources'.padEnd(9)} ${'Tests'.padEnd(7)} ${'Last Modified'}${c.reset}`);
@@ -257,6 +274,16 @@ function outputText(projectName, matrix, canonicalDocs) {
     console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to fix coverage gaps.${c.reset}`);
   }
 
+  // ── Orphaned docs warning ──
+  if (orphanedDocs.length > 0) {
+    console.log(`\n  ${c.yellow}⚠️  Orphaned Files (${orphanedDocs.length})${c.reset}`);
+    console.log(`  ${c.dim}These files exist in docs-canonical/ but are excluded from your config:${c.reset}`);
+    for (const doc of orphanedDocs) {
+      console.log(`     ${c.yellow}→${c.reset} ${doc}`);
+    }
+    console.log(`  ${c.dim}Delete them or add to .docguard.json requiredFiles.canonical${c.reset}`);
+  }
+
   console.log(`\n  ${c.dim}Traceability methodology: ISO/IEC/IEEE 29119 (Lopez et al., AITPG, IEEE TSE 2026)${c.reset}\n`);
 }
 

package/cli/validators/traceability.mjs

@@ -0,0 +1,157 @@
+/**
+ * Traceability Validator — Checks that canonical docs are linked to source code
+ * 
+ * Returns warnings for PARTIAL/UNLINKED canonical docs, and errors for MISSING ones.
+ * This runs as part of `docguard guard` on every invocation.
+ *
+ * Inspired by ISO/IEC/IEEE 29119 traceability requirements
+ * and Lopez et al., AITPG (IEEE TSE 2026).
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, basename } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  '.amplify-hosting', '.serverless',
+]);
+
+/**
+ * Mapping of canonical docs to source code patterns they should trace to.
+ */
+const TRACE_MAP = {
+  'ARCHITECTURE.md': {
+    sourcePatterns: [
+      { label: 'Entry points', glob: /^(index|main|app|server)\.[jt]sx?$/ },
+      { label: 'Config files', glob: /^(package\.json|tsconfig.*|next\.config|vite\.config)/ },
+      { label: 'Route handlers', glob: /(routes?|api|pages|app)\// },
+    ],
+  },
+  'DATA-MODEL.md': {
+    sourcePatterns: [
+      { label: 'Schema definitions', glob: /(schema|model|entity|migration|prisma)/i },
+      { label: 'Type definitions', glob: /types?\.[jt]sx?$/ },
+      { label: 'Database configs', glob: /(drizzle|knex|sequelize|typeorm)/i },
+    ],
+  },
+  'TEST-SPEC.md': {
+    sourcePatterns: [
+      { label: 'Test files', glob: /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/ },
+      { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
+      { label: 'E2E tests', glob: /(e2e|integration)\// },
+    ],
+  },
+  'SECURITY.md': {
+    sourcePatterns: [
+      { label: 'Auth modules', glob: /(auth|login|session|jwt|oauth|middleware)/i },
+      { label: 'Secret configs', glob: /\.(env|env\.example|env\.local)$/ },
+      { label: 'Gitignore', glob: /^\.gitignore$/ },
+    ],
+  },
+  'ENVIRONMENT.md': {
+    sourcePatterns: [
+      { label: 'Env files', glob: /\.env/ },
+      { label: 'Docker configs', glob: /(Dockerfile|docker-compose|\.dockerignore)/ },
+      { label: 'CI/CD configs', glob: /\.(github|gitlab-ci|circleci)/ },
+    ],
+  },
+  'API-REFERENCE.md': {
+    sourcePatterns: [
+      { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
+      { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
+      { label: 'API middleware', glob: /middleware\// },
+    ],
+  },
+};
+
+/**
+ * Validate traceability — ensures canonical docs have corresponding source artifacts.
+ * Respects config.requiredFiles.canonical — only checks docs the user requires.
+ * Also warns about orphaned files (exist but excluded from config).
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateTraceability(projectDir, config) {
+  const errors = [];
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (!existsSync(docsDir)) {
+    // No docs-canonical dir at all — structure validator handles this
+    return { errors, warnings, passed: 0, total: 0 };
+  }
+
+  // Build set of required doc basenames from config
+  const requiredDocs = new Set(
+    (config.requiredFiles?.canonical || []).map(f => basename(f))
+  );
+
+  // Scan project files once
+  const projectFiles = [];
+  scanDir(projectDir, projectDir, projectFiles);
+
+  // ── Check required docs for traceability ──
+  for (const [docName, traceInfo] of Object.entries(TRACE_MAP)) {
+    // Skip docs not in the user's required list
+    if (!requiredDocs.has(docName)) continue;
+
+    total++;
+    const docPath = resolve(docsDir, docName);
+    const docExists = existsSync(docPath);
+
+    if (!docExists) {
+      warnings.push(`${docName} — required but missing, no traceability possible`);
+      continue;
+    }
+
+    // Count matching source files
+    let totalSources = 0;
+    for (const pattern of traceInfo.sourcePatterns) {
+      const matches = projectFiles.filter(f => pattern.glob.test(f));
+      totalSources += matches.length;
+    }
+
+    if (totalSources > 0) {
+      passed++;
+    } else {
+      warnings.push(`${docName} — exists but no matching source code found (unlinked doc)`);
+    }
+  }
+
+  // ── Detect orphaned files (exist but not required) ──
+  try {
+    const existingDocs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
+    for (const docFile of existingDocs) {
+      if (!requiredDocs.has(docFile) && TRACE_MAP[docFile]) {
+        warnings.push(`${docFile} — file exists in docs-canonical/ but is not in your requiredFiles config. Consider deleting it or adding it to .docguard.json requiredFiles.canonical`);
+      }
+    }
+  } catch { /* ignore */ }
+
+  return { errors, warnings, passed, total };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function scanDir(rootDir, dir, files) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.') && entry !== '.env' && entry !== '.env.example'
+        && entry !== '.gitignore' && !entry.startsWith('.github')) continue;
+
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      scanDir(rootDir, full, files);
+    } else {
+      files.push(relative(rootDir, full));
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {