docguard-cli 0.10.0 → 0.11.1

package/cli/scanners/routes.mjs

@@ -60,6 +60,22 @@ export function scanRoutesDeep(dir, stack, docTools, opts = {}) {
     routes.push(...scanDjangoRoutes(dir));
   }
 
+  if (framework.includes('Spring') || framework.includes('Java')) {
+    routes.push(...scanSpringBootRoutes(dir));
+  }
+
+  if (framework.includes('Rails') || framework.includes('Ruby')) {
+    routes.push(...scanRailsRoutes(dir));
+  }
+
+  if (framework.includes('Gin') || framework.includes('Echo') || framework.includes('Chi') || framework.includes('Fiber') || framework.includes('Go')) {
+    routes.push(...scanGoWebRoutes(dir));
+  }
+
+  if (framework.includes('Axum') || framework.includes('Actix') || framework.includes('Rocket') || framework.includes('Warp') || framework.includes('Rust')) {
+    routes.push(...scanRustWebRoutes(dir));
+  }
+
   if (framework.includes('FastAPI') || framework.includes('Flask')) {
     routes.push(...scanFastAPIRoutes(dir));
   }
@@ -357,6 +373,139 @@ function scanFastAPIRoutes(dir) {
   return routes;
 }
 
+// ── Spring Boot (Java/Kotlin) ────────────────────────────────────────────────
+
+function scanSpringBootRoutes(dir) {
+  const routes = [];
+  // Method-level verb annotations (NOT @RequestMapping — that's class-level base).
+  // Optional path; bare `@PostMapping` means "base path only".
+  const verbMap = /@(Get|Post|Put|Delete|Patch)Mapping(?:\s*\(\s*(?:value\s*=\s*)?["']([^"']*)["'])?/g;
+  const classBase = /@RequestMapping\s*\(\s*(?:value\s*=\s*)?["']([^"']+)["'][^)]*\)\s*[\r\n][\s\S]*?(?:public\s+)?class\s+\w+/;
+
+  const javaFiles = findFiles(dir, /\.(java|kt)$/);
+  for (const filePath of javaFiles) {
+    const content = readFileSafe(filePath);
+    if (!content || !content.includes('Mapping')) continue;
+
+    // Class-level base path, if any.
+    const cb = classBase.exec(content);
+    const basePath = cb ? cb[1] : '';
+    const authPresent = /@PreAuthorize|@Secured|SecurityContext/.test(content);
+
+    let match;
+    const re = new RegExp(verbMap.source, 'g');
+    while ((match = re.exec(content)) !== null) {
+      const method = match[1].toUpperCase();
+      const sub = match[2] || '';
+      const path = (basePath + sub).replace(/\/+/g, '/') || '/';
+      routes.push({
+        method, path,
+        handler: '', file: relative(dir, filePath), source: 'spring-boot',
+        auth: authPresent, description: '',
+      });
+    }
+  }
+  return routes;
+}
+
+// ── Rails (Ruby) — config/routes.rb ──────────────────────────────────────────
+
+function scanRailsRoutes(dir) {
+  const routes = [];
+  const routesFile = resolve(dir, 'config/routes.rb');
+  if (!existsSync(routesFile)) return routes;
+  const content = readFileSafe(routesFile);
+  if (!content) return routes;
+
+  // Verb DSL: get '/x', post '/x', etc.  AND  resources :things (RESTful 7 actions)
+  const verbDsl = /^\s*(get|post|put|patch|delete)\s+['"]([^'"]+)['"]/gm;
+  let m;
+  while ((m = verbDsl.exec(content)) !== null) {
+    routes.push({
+      method: m[1].toUpperCase(),
+      path: m[2].startsWith('/') ? m[2] : '/' + m[2],
+      handler: '', file: 'config/routes.rb', source: 'rails', auth: false, description: '',
+    });
+  }
+  // resources :users → 7 standard RESTful routes.
+  const resourcesRe = /^\s*resources\s+:([a-z_]+)/gm;
+  while ((m = resourcesRe.exec(content)) !== null) {
+    const r = m[1];
+    const base = `/${r}`;
+    const seven = [
+      ['GET', base], ['GET', `${base}/new`], ['POST', base],
+      ['GET', `${base}/:id`], ['GET', `${base}/:id/edit`],
+      ['PATCH', `${base}/:id`], ['DELETE', `${base}/:id`],
+    ];
+    for (const [method, path] of seven) {
+      routes.push({ method, path, handler: '', file: 'config/routes.rb', source: 'rails', auth: false, description: '' });
+    }
+  }
+  return routes;
+}
+
+// ── Go web frameworks (Gin / Echo / Chi / Fiber / std mux) ───────────────────
+
+function scanGoWebRoutes(dir) {
+  const routes = [];
+  // Generic: <recv>.<METHOD>("/path", handler)  for Gin/Echo/Chi/Fiber/mux.Router
+  const pattern = /\.(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS|HandleFunc|Handle)\s*\(\s*["']([^"']+)["']/g;
+  const goFiles = findFiles(dir, /\.go$/);
+  for (const filePath of goFiles) {
+    const content = readFileSafe(filePath);
+    if (!content) continue;
+    let m;
+    const re = new RegExp(pattern.source, 'g');
+    while ((m = re.exec(content)) !== null) {
+      const verb = m[1];
+      // HandleFunc / Handle are method-agnostic.
+      const method = ['HandleFunc', 'Handle'].includes(verb) ? 'ANY' : verb;
+      const path = m[2];
+      if (!path.startsWith('/')) continue;
+      routes.push({
+        method, path,
+        handler: '', file: relative(dir, filePath), source: 'go-web',
+        auth: /Authorization|jwt\.|middleware\.Auth/.test(content),
+        description: '',
+      });
+    }
+  }
+  return routes;
+}
+
+// ── Rust web frameworks (Axum / Actix / Rocket / Warp) ───────────────────────
+
+function scanRustWebRoutes(dir) {
+  const routes = [];
+  const rsFiles = findFiles(dir, /\.rs$/);
+  for (const filePath of rsFiles) {
+    const content = readFileSafe(filePath);
+    if (!content) continue;
+
+    // Axum: .route("/x", get(handler)) / .route("/x", post(handler).get(handler))
+    const axum = /\.route\s*\(\s*"([^"]+)"\s*,\s*([a-z]+)\s*\(/g;
+    let m;
+    while ((m = axum.exec(content)) !== null) {
+      const method = m[2].toUpperCase();
+      if (!['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'].includes(method)) continue;
+      routes.push({ method, path: m[1], handler: '', file: relative(dir, filePath), source: 'axum', auth: false, description: '' });
+    }
+
+    // Actix-web: .route("/x", web::get().to(handler))
+    const actix = /\.route\s*\(\s*"([^"]+)"\s*,\s*web::(get|post|put|delete|patch)\(\)/g;
+    while ((m = actix.exec(content)) !== null) {
+      routes.push({ method: m[2].toUpperCase(), path: m[1], handler: '', file: relative(dir, filePath), source: 'actix', auth: false, description: '' });
+    }
+
+    // Rocket: #[get("/x")] etc.
+    const rocket = /#\[(get|post|put|delete|patch)\(\s*"([^"]+)"/g;
+    while ((m = rocket.exec(content)) !== null) {
+      routes.push({ method: m[1].toUpperCase(), path: m[2], handler: '', file: relative(dir, filePath), source: 'rocket', auth: false, description: '' });
+    }
+  }
+  return routes;
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function readFileSafe(path) {

package/cli/scanners/schemas.mjs

@@ -69,6 +69,15 @@ export function scanSchemasDeep(dir, stack, docTools) {
     relationships.push(...mongooseResult.relationships);
   }
 
+  // ── Multi-language model scanners (additive; supports polyglot repos) ──
+  for (const scanner of [scanPythonModels, scanRustModels, scanGoModels, scanJpaModels, scanRailsModels]) {
+    const result = scanner(dir);
+    if (result.entities.length > 0) {
+      entities.push(...result.entities);
+      relationships.push(...(result.relationships || []));
+    }
+  }
+
   return {
     entities,
     relationships,
@@ -490,6 +499,170 @@ function mapMongooseType(type) {
   return map[type] || type;
 }
 
+// ── Python: SQLAlchemy + Pydantic ────────────────────────────────────────────
+
+function scanPythonModels(dir) {
+  const entities = [];
+  const relationships = [];
+  walkDir(dir, (filePath) => {
+    if (!filePath.endsWith('.py')) return;
+    const content = readFileSafe(filePath);
+    if (!content) return;
+    if (!/class\s+\w+\s*\([^)]*(Base|BaseModel|db\.Model|Model|SQLModel)/.test(content)) return;
+
+    // SQLAlchemy ORM: class X(Base): __tablename__ = "x"; id = Column(...)
+    const ormRe = /class\s+(\w+)\s*\([^)]*(?:Base|db\.Model|SQLModel)[^)]*\):([\s\S]*?)(?=\nclass\s+\w+|\n*$)/g;
+    let m;
+    while ((m = ormRe.exec(content)) !== null) {
+      const name = m[1];
+      const body = m[2];
+      const fields = [];
+      const colRe = /^\s*(\w+)\s*=\s*(?:mapped_column|Column)\s*\(\s*([A-Za-z_]+)(?:\([^)]*\))?([^)]*)\)/gm;
+      let cm;
+      while ((cm = colRe.exec(body)) !== null) {
+        const required = !/nullable\s*=\s*True/.test(cm[3]);
+        fields.push({ name: cm[1], type: cm[2], required, description: '' });
+      }
+      const relRe = /(\w+)\s*[:=]\s*(?:Mapped\[[^\]]*?["'](\w+)["']|relationship\s*\(\s*["'](\w+)["'])/g;
+      let rm;
+      while ((rm = relRe.exec(body)) !== null) {
+        relationships.push({ from: name, to: rm[2] || rm[3], type: 'related' });
+      }
+      if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'sqlalchemy' });
+    }
+
+    // Pydantic / SQLModel: class X(BaseModel): name: str
+    const pydRe = /class\s+(\w+)\s*\([^)]*(?:BaseModel|SQLModel)[^)]*\):([\s\S]*?)(?=\nclass\s+\w+|\n*$)/g;
+    while ((m = pydRe.exec(content)) !== null) {
+      const name = m[1];
+      if (entities.some(e => e.name === name)) continue;
+      const body = m[2];
+      const fields = [];
+      const fieldRe = /^\s{2,}(\w+)\s*:\s*([\w\[\],\s|]+?)(?:\s*=\s*([^\n]+))?$/gm;
+      let fm;
+      while ((fm = fieldRe.exec(body)) !== null) {
+        const fname = fm[1];
+        if (/^[A-Z_]+$/.test(fname)) continue;
+        const type = fm[2].trim();
+        const required = !/Optional|None|None\s*$/.test(type + (fm[3] || ''));
+        fields.push({ name: fname, type, required, description: '' });
+      }
+      if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'pydantic' });
+    }
+  });
+  return { entities, relationships };
+}
+
+// ── Rust: Diesel `table! { ... }` ─────────────────────────────────────────────
+
+function scanRustModels(dir) {
+  const entities = [];
+  walkDir(dir, (filePath) => {
+    if (!filePath.endsWith('.rs')) return;
+    const content = readFileSafe(filePath);
+    if (!content || !content.includes('table!')) return;
+    const tableRe = /table!\s*\{\s*(\w+)\s*\([^)]*\)\s*\{([\s\S]*?)\}\s*\}/g;
+    let m;
+    while ((m = tableRe.exec(content)) !== null) {
+      const name = m[1];
+      const body = m[2];
+      const fields = [];
+      const colRe = /(\w+)\s*->\s*(\w+)/g;
+      let cm;
+      while ((cm = colRe.exec(body)) !== null) {
+        fields.push({ name: cm[1], type: cm[2], required: !/Nullable/.test(cm[2]), description: '' });
+      }
+      if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'diesel' });
+    }
+  });
+  return { entities, relationships: [] };
+}
+
+// ── Go: structs with json/gorm/db tags ───────────────────────────────────────
+
+function scanGoModels(dir) {
+  const entities = [];
+  walkDir(dir, (filePath) => {
+    if (!filePath.endsWith('.go')) return;
+    const content = readFileSafe(filePath);
+    if (!content || !/`[^`]*\b(json|gorm|db|bson):/.test(content)) return;
+    const structRe = /type\s+(\w+)\s+struct\s*\{([\s\S]*?)\}/g;
+    let m;
+    while ((m = structRe.exec(content)) !== null) {
+      const name = m[1];
+      const body = m[2];
+      const fields = [];
+      const fieldRe = /^\s*(\w+)\s+([\w*.\[\]]+)\s+`([^`]+)`/gm;
+      let fm;
+      while ((fm = fieldRe.exec(body)) !== null) {
+        const fname = fm[1];
+        const ftype = fm[2];
+        const tag = fm[3];
+        if (!/\b(json|gorm|db|bson):/.test(tag)) continue;
+        const required = !tag.includes('omitempty');
+        fields.push({ name: fname, type: ftype, required, description: '' });
+      }
+      if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'go-struct' });
+    }
+  });
+  return { entities, relationships: [] };
+}
+
+// ── Java/Kotlin: JPA @Entity ─────────────────────────────────────────────────
+
+function scanJpaModels(dir) {
+  const entities = [];
+  walkDir(dir, (filePath) => {
+    if (!/\.(java|kt)$/.test(filePath)) return;
+    const content = readFileSafe(filePath);
+    if (!content || !content.includes('@Entity')) return;
+    const classRe = /@Entity[\s\S]*?class\s+(\w+)\s*(?:\([^)]*\))?\s*\{([\s\S]*?)^\}/gm;
+    let m;
+    while ((m = classRe.exec(content)) !== null) {
+      const name = m[1];
+      const body = m[2];
+      const fields = [];
+      const fieldRe = /(?:private|public|protected|val|var)\s+([\w<>]+)\s+(\w+)\s*[;=]/g;
+      let fm;
+      while ((fm = fieldRe.exec(body)) !== null) {
+        const ftype = fm[1];
+        const fname = fm[2];
+        if (/^(boolean|int|long|short|byte|float|double|char)$/.test(ftype) || /^[A-Z]/.test(ftype)) {
+          fields.push({ name: fname, type: ftype, required: true, description: '' });
+        }
+      }
+      if (fields.length > 0) entities.push({ name, fields, file: filePath, source: 'jpa' });
+    }
+  });
+  return { entities, relationships: [] };
+}
+
+// ── Rails: ActiveRecord migrations + schema.rb ───────────────────────────────
+
+function scanRailsModels(dir) {
+  const entities = [];
+  walkDir(dir, (filePath) => {
+    if (!/db\/(migrate|schema\.rb)/.test(filePath) || !filePath.endsWith('.rb')) return;
+    const content = readFileSafe(filePath);
+    if (!content || !content.includes('create_table')) return;
+    const tableRe = /create_table\s+:(\w+)\s+do\s+\|t\|([\s\S]*?)end/g;
+    let m;
+    while ((m = tableRe.exec(content)) !== null) {
+      const name = m[1];
+      const body = m[2];
+      const fields = [{ name: 'id', type: 'integer', required: true, description: '' }];
+      const colRe = /t\.(string|text|integer|float|decimal|datetime|date|time|boolean|json|binary|references)\s+:(\w+)(?:\s*,\s*([^,\n]+))?/g;
+      let cm;
+      while ((cm = colRe.exec(body)) !== null) {
+        const required = !!cm[3] && /null:\s*false/.test(cm[3]);
+        fields.push({ name: cm[2], type: cm[1], required, description: '' });
+      }
+      entities.push({ name, fields, file: filePath, source: 'rails-migration' });
+    }
+  });
+  return { entities, relationships: [] };
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function extractOpenAPIRelationships(schemas) {
@@ -526,7 +699,7 @@ function walkDir(dir, callback) {
       const fullPath = join(dir, entry.name);
       if (entry.isDirectory()) {
         walkDir(fullPath, callback);
-      } else if (entry.isFile() && /\.(js|mjs|cjs|ts|tsx|jsx|py)$/.test(entry.name)) {
+      } else if (entry.isFile() && /\.(js|mjs|cjs|ts|tsx|jsx|py|rs|go|java|kt|rb)$/.test(entry.name)) {
         callback(fullPath);
       }
     }

package/cli/shared-ignore.mjs

@@ -15,6 +15,31 @@
  * Zero NPM dependencies — pure Node.js built-ins only.
  */
 
+/**
+ * Canonical set of directory names that should never be scanned, regardless
+ * of validator. Build outputs, VCS internals, package caches, framework synth
+ * outputs. Validators MAY extend this with their own additions but SHOULD
+ * start from this base so behavior is consistent across the tool.
+ */
+export const DEFAULT_IGNORE_DIRS = new Set([
+  // Package managers
+  'node_modules', 'vendor', '.venv', '__pycache__',
+  // VCS
+  '.git', '.jj', '.hg', '.svn',
+  // Build outputs — JS/TS, Rust/Java, generic
+  'dist', 'build', 'out', 'coverage', 'target', '.gradle',
+  // Framework synth/cache
+  '.next', '.nuxt', '.turbo', '.vercel', '.cache', '.svelte-kit', 'cdk.out',
+  // OS
+  '.DS_Store',
+]);
+
+// Regex for paths that must always be rejected at any depth, regardless of
+// the glob pattern matching them. These are duplicate file trees (worktrees)
+// or runtime caches that should NEVER be treated as primary source.
+const ALWAYS_REJECT_PATH_RE =
+  /(?:^|[/\\])(?:node_modules|\.claude[/\\]worktrees|\.git[/\\]worktrees|\.jj)(?:[/\\]|$)/;
+
 /**
  * Convert a glob pattern to a RegExp.
  * Supports: * (any chars except /), ** (any path segments), . (literal dot).
@@ -111,8 +136,10 @@ function globToMatchRegex(pattern) {
 export function globMatch(relPath, patterns) {
   if (!relPath || !patterns || patterns.length === 0) return false;
 
-  // Always reject paths containing node_modules at any depth
-  if (/(?:^|[/\\])node_modules(?:[/\\]|$)/.test(relPath)) return false;
+  // Always reject paths inside node_modules / worktree copies / .jj at any
+  // depth. A user's testPatterns like "**/*.test.ts" would otherwise match
+  // duplicate trees under .claude/worktrees and inflate test counts.
+  if (ALWAYS_REJECT_PATH_RE.test(relPath)) return false;
 
   const regexes = patterns.map(p => globToMatchRegex(p));
   return regexes.some(r => r.test(relPath));

package/cli/shared-source.mjs

@@ -18,8 +18,9 @@ import { resolve, join, dirname, relative, extname } from 'node:path';
 import { shouldIgnore } from './shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build',
+  'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
   'coverage', '.cache', '__pycache__', '.venv', 'vendor', '.turbo',
+  'cdk.out',
 ]);
 
 const CODE_EXTENSIONS = new Set([

package/cli/validators/api-surface.mjs

@@ -15,17 +15,23 @@
  *                              downgraded to WARNING on heuristic code-scan only.
  *   - present-but-undocumented → WARNING (a real route missing from the docs).
  *
- * Returns { errors, warnings, passed, total } like the other validators.
+ * Also flags MULTIPLE OpenAPI specs in the repo that disagree on their endpoint
+ * set (e.g. a served spec and a generated spec that have diverged).
+ *
+ * Returns { errors, warnings, passed, total, fixes, authoritativeSpec } — the
+ * `fixes` array lists deterministic remove-endpoint actions that
+ * `docguard fix --write` can apply without an LLM.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 import { detectOpenAPI } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
-import { parseApiReferenceDoc, compareEndpoints } from '../scanners/api-doc.mjs';
+import { parseApiReferenceDoc, compareEndpoints, endpointKey } from '../scanners/api-doc.mjs';
 import { collectPackageJsons, getWorkspaceDirs } from '../shared-source.mjs';
 
 const MAX_REPORTED = 15;
+const API_DOC = 'docs-canonical/API-REFERENCE.md';
 
 /** Walk up from a dir to the nearest enclosing package.json directory. */
 function nearestPackageDir(projectDir, startDir) {
@@ -44,7 +50,8 @@ function nearestPackageDir(projectDir, startDir) {
  * Build an ordered list of directories to search for an OpenAPI spec.
  * The spec under the configured sourceRoot's package takes precedence over a
  * (possibly stale) copy at the repo root — monorepos frequently keep a
- * divergent root copy.
+ * divergent root copy. Only CANONICAL bases are searched (sourceRoot package,
+ * workspaces, repo root) — never worktrees / vendor / scan-tool dirs.
  */
 function orderedSpecDirs(projectDir, config) {
   const ordered = [];
@@ -65,18 +72,45 @@ function orderedSpecDirs(projectDir, config) {
 }
 
 /**
- * Locate the authoritative OpenAPI spec across the monorepo.
- * Returns the FIRST spec found in priority order (sourceRoot first).
+ * Enumerate every OpenAPI spec found in a canonical location, in priority order.
+ * @returns {Array<{ absPath: string, relPath: string, endpoints: object[] }>}
  */
-function findOpenApiEndpoints(projectDir, config) {
+export function findAllOpenApiSpecs(projectDir, config) {
+  const specs = [];
+  const seenAbs = new Set();
   for (const dir of orderedSpecDirs(projectDir, config)) {
     const oa = detectOpenAPI(dir);
-    if (oa.found && oa.endpoints?.length) {
-      const endpoints = oa.endpoints.filter(e => e && e.method && e.path);
-      if (endpoints.length) return { endpoints, path: oa.path };
-    }
+    if (!oa.found || !oa.endpoints?.length) continue;
+    const absPath = resolve(dir, oa.path);
+    if (seenAbs.has(absPath)) continue;
+    seenAbs.add(absPath);
+    specs.push({
+      absPath,
+      relPath: absPath.startsWith(resolve(projectDir))
+        ? absPath.slice(resolve(projectDir).length + 1)
+        : absPath,
+      endpoints: oa.endpoints.filter(e => e && e.method && e.path),
+    });
   }
-  return null;
+  return specs;
+}
+
+/**
+ * Detect divergence between multiple canonical OpenAPI specs.
+ * @returns {null | { specs, divergent: string[], authoritative: string }}
+ */
+export function detectSpecDivergence(projectDir, config) {
+  const specs = findAllOpenApiSpecs(projectDir, config);
+  if (specs.length < 2) return null;
+
+  const keySets = specs.map(s => new Set(s.endpoints.map(e => endpointKey(e.method, e.path))));
+  // Union and symmetric difference across all specs.
+  const union = new Set();
+  for (const ks of keySets) for (const k of ks) union.add(k);
+  const divergent = [...union].filter(k => !keySets.every(ks => ks.has(k)));
+
+  if (divergent.length === 0) return null;
+  return { specs, divergent, authoritative: specs[0].relPath };
 }
 
 function detectFramework(projectDir, config) {
@@ -96,12 +130,13 @@ function detectFramework(projectDir, config) {
  * @returns {{ endpoints: Array<{method,path}>, confidence: 'spec'|'code'|'none', source: string }}
  */
 export function resolveApiSurface(projectDir, config) {
-  const spec = findOpenApiEndpoints(projectDir, config);
-  if (spec) {
+  const specs = findAllOpenApiSpecs(projectDir, config);
+  if (specs.length > 0) {
+    const spec = specs[0]; // highest priority (sourceRoot first, root last)
     return {
       endpoints: spec.endpoints.map(e => ({ method: e.method, path: e.path })),
       confidence: 'spec',
-      source: spec.path,
+      source: spec.relPath,
     };
   }
 
@@ -119,61 +154,101 @@ export function resolveApiSurface(projectDir, config) {
   return { endpoints: [], confidence: 'none', source: null };
 }
 
-export function validateApiSurface(projectDir, config) {
-  const errors = [];
-  const warnings = [];
-
-  const apiDocPath = resolve(projectDir, 'docs-canonical/API-REFERENCE.md');
+/**
+ * Compute API-surface drift in a structured, reusable form.
+ * Used by the validator AND by `docguard fix --write`.
+ * @returns {{ applicable, confidence, source, documented, documentedButAbsent,
+ *             presentButUndocumented, matched }}
+ */
+export function computeApiSurfaceDrift(projectDir, config) {
+  const apiDocPath = resolve(projectDir, API_DOC);
   if (!existsSync(apiDocPath)) {
-    // No API reference doc → nothing to validate (not applicable).
-    return { errors, warnings, passed: 0, total: 0 };
+    return { applicable: false, confidence: 'none', source: null,
+      documented: [], documentedButAbsent: [], presentButUndocumented: [], matched: [] };
   }
 
   const documented = parseApiReferenceDoc(readFileSync(apiDocPath, 'utf-8'));
   const surface = resolveApiSurface(projectDir, config);
 
-  // If we cannot determine the actual surface, do not fabricate drift.
   if (surface.confidence === 'none' || documented.length === 0) {
-    return { errors, warnings, passed: documented.length, total: documented.length };
+    return { applicable: false, confidence: surface.confidence, source: surface.source,
+      documented, documentedButAbsent: [], presentButUndocumented: [], matched: [] };
   }
 
-  const { documentedButAbsent, presentButUndocumented, matched } =
-    compareEndpoints(documented, surface.endpoints);
+  const cmp = compareEndpoints(documented, surface.endpoints);
+  return {
+    applicable: true,
+    confidence: surface.confidence,
+    source: surface.source,
+    documented,
+    documentedButAbsent: cmp.documentedButAbsent,
+    presentButUndocumented: cmp.presentButUndocumented,
+    matched: cmp.matched,
+  };
+}
+
+export function validateApiSurface(projectDir, config) {
+  const errors = [];
+  const warnings = [];
+  const fixes = [];
+
+  const drift = computeApiSurfaceDrift(projectDir, config);
+
+  // ── Multi-spec divergence (independent of the API-REFERENCE doc) ──
+  const divergence = detectSpecDivergence(projectDir, config);
+  if (divergence) {
+    const others = divergence.specs.slice(1).map(s => s.relPath).join(', ');
+    const sample = divergence.divergent.slice(0, 8).join(', ');
+    const more = divergence.divergent.length > 8 ? ` (+${divergence.divergent.length - 8} more)` : '';
+    warnings.push(
+      `Multiple OpenAPI specs disagree on ${divergence.divergent.length} endpoint(s): ` +
+      `${divergence.authoritative} (treated as authoritative) vs ${others}. Divergent: ${sample}${more}`
+    );
+  }
+
+  if (!drift.applicable) {
+    // Nothing to validate against the API-REFERENCE doc.
+    return { errors, warnings, passed: 0, total: 0, fixes, authoritativeSpec: drift.source };
+  }
 
+  const { documentedButAbsent, presentButUndocumented, matched, confidence, source } = drift;
   const total = matched.length + documentedButAbsent.length + presentButUndocumented.length;
   const passed = matched.length;
 
   const trim = (arr) => {
     const shown = arr.slice(0, MAX_REPORTED);
-    const extra = arr.length - shown.length;
-    return { shown, extra };
+    return { shown, extra: arr.length - shown.length };
   };
 
-  // documented-but-absent
+  // documented-but-absent → deterministic remove-endpoint fixes
   if (documentedButAbsent.length) {
     const { shown, extra } = trim(documentedButAbsent);
     for (const e of shown) {
-      const msg = `Documented endpoint not found in code: ${e.method} ${e.path} (docs-canonical/API-REFERENCE.md)`;
-      if (surface.confidence === 'spec') errors.push(msg);
+      const msg = `Documented endpoint not found in code: ${e.method} ${e.path} (${API_DOC})`;
+      if (confidence === 'spec') errors.push(msg);
       else warnings.push(`${msg} [code-scan — verify]`);
     }
     if (extra > 0) {
       const tail = `…and ${extra} more documented endpoint(s) not found in code`;
-      if (surface.confidence === 'spec') errors.push(tail);
+      if (confidence === 'spec') errors.push(tail);
       else warnings.push(tail);
     }
+    // Only spec-confirmed absences are safe to auto-remove.
+    if (confidence === 'spec') {
+      for (const e of documentedButAbsent) {
+        fixes.push({ type: 'remove-endpoint', method: e.method, path: e.path, doc: API_DOC });
+      }
+    }
   }
 
-  // present-but-undocumented
+  // present-but-undocumented → warning (NOT auto-applied; needs a real block)
   if (presentButUndocumented.length) {
     const { shown, extra } = trim(presentButUndocumented);
     for (const e of shown) {
-      warnings.push(`Undocumented endpoint in code: ${e.method} ${e.path} — add it to docs-canonical/API-REFERENCE.md`);
-    }
-    if (extra > 0) {
-      warnings.push(`…and ${extra} more undocumented endpoint(s) in code`);
+      warnings.push(`Undocumented endpoint in code: ${e.method} ${e.path} — add it to ${API_DOC}`);
     }
+    if (extra > 0) warnings.push(`…and ${extra} more undocumented endpoint(s) in code`);
   }
 
-  return { errors, warnings, passed, total };
+  return { errors, warnings, passed, total, fixes, authoritativeSpec: source };
 }

package/cli/validators/changelog.mjs

@@ -25,7 +25,7 @@ function getStagedFiles(projectDir) {
 }
 
 export function validateChangelog(projectDir, config) {
-  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0 };
+  const results = { name: 'changelog', errors: [], warnings: [], passed: 0, total: 0, fixes: [] };
 
   const changelogPath = resolve(projectDir, config.requiredFiles.changelog);
   if (!existsSync(changelogPath)) {
@@ -40,7 +40,8 @@ export function validateChangelog(projectDir, config) {
   if (content.includes('[Unreleased]') || content.includes('[unreleased]')) {
     results.passed++;
   } else {
-    results.warnings.push('CHANGELOG.md: missing [Unreleased] section');
+    results.warnings.push('CHANGELOG.md: missing [Unreleased] section — fix with `docguard fix --write`');
+    results.fixes.push({ type: 'insert-changelog-unreleased', file: config.requiredFiles.changelog });
   }
 
   // Check it follows Keep a Changelog format (at least has ## headers)