docguard-cli 0.7.0 → 0.7.1

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)\// },
     ],

package/cli/validators/traceability.mjs

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ * @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 };
+  }
+
+  // Scan project files once
+  const projectFiles = [];
+  scanDir(projectDir, projectDir, projectFiles);
+
+  for (const [docName, traceInfo] of Object.entries(TRACE_MAP)) {
+    total++;
+    const docPath = resolve(docsDir, docName);
+    const docExists = existsSync(docPath);
+
+    if (!docExists) {
+      // Only warn for API-REFERENCE.md (not all projects have APIs)
+      if (docName === 'API-REFERENCE.md') {
+        // Don't count API-REFERENCE as missing — it's optional
+        total--;
+      } else {
+        warnings.push(`${docName} — document 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)`);
+    }
+  }
+
+  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.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {