docguard-cli 0.9.11 → 0.10.0

package/cli/commands/generate.mjs

@@ -311,6 +311,8 @@ function detectStack(dir) {
 
 // ── Project Scanner ────────────────────────────────────────────────────────
 
+
+
 function scanProject(dir) {
   const scan = {
     routes: [],
@@ -324,6 +326,30 @@ function scanProject(dir) {
     totalLines: 0,
   };
 
+  scanRoutes(dir, scan);
+  scanModels(dir, scan);
+  scanServices(dir, scan);
+  scanTests(dir, scan);
+  scanComponents(dir, scan);
+  scanMiddlewares(dir, scan);
+  scanEnvVars(dir, scan);
+
+  // Count files and lines
+  countFilesAndLines(dir, scan);
+
+  // ── Filter test files out of source lists ──
+  // Test files (*.test.*, *.spec.*, __tests__/) should NOT appear as source files
+  const isTestFile = (f) => f.includes('__tests__') || f.includes('__test__') || /\.(test|spec)\.[^.]+$/.test(f);
+  scan.routes = scan.routes.filter(f => !isTestFile(f));
+  scan.models = scan.models.filter(f => !isTestFile(f));
+  scan.services = scan.services.filter(f => !isTestFile(f));
+  scan.components = scan.components.filter(f => !isTestFile(f));
+  scan.middlewares = scan.middlewares.filter(f => !isTestFile(f));
+
+  return scan;
+}
+
+function scanRoutes(dir, scan) {
   // Find routes
   ['src/app/api', 'src/routes', 'routes', 'api', 'src/api'].forEach(routeDir => {
     const fullDir = resolve(dir, routeDir);
@@ -334,7 +360,10 @@ function scanProject(dir) {
       }
     }
   });
+}
+
 
+function scanModels(dir, scan) {
   // Find models/entities
   ['src/models', 'models', 'src/entities', 'entities', 'src/schema', 'schema', 'prisma'].forEach(modelDir => {
     const fullDir = resolve(dir, modelDir);
@@ -345,7 +374,10 @@ function scanProject(dir) {
       }
     }
   });
+}
+
 
+function scanServices(dir, scan) {
   // Find services
   ['src/services', 'services', 'src/lib', 'lib'].forEach(svcDir => {
     const fullDir = resolve(dir, svcDir);
@@ -356,7 +388,10 @@ function scanProject(dir) {
       }
     }
   });
+}
+
 
+function scanTests(dir, scan) {
   // Find tests — top-level test dirs
   ['tests', 'test', '__tests__', 'spec', 'e2e'].forEach(testDir => {
     const fullDir = resolve(dir, testDir);
@@ -416,7 +451,10 @@ function scanProject(dir) {
       break; // Use first found config
     }
   }
+}
 
+
+function scanComponents(dir, scan) {
   // Find components
   ['src/components', 'components', 'src/ui'].forEach(compDir => {
     const fullDir = resolve(dir, compDir);
@@ -427,7 +465,10 @@ function scanProject(dir) {
       }
     }
   });
+}
+
 
+function scanMiddlewares(dir, scan) {
   // Find middleware
   ['src/middleware', 'middleware', 'src/middlewares'].forEach(mwDir => {
     const fullDir = resolve(dir, mwDir);
@@ -438,7 +479,10 @@ function scanProject(dir) {
       }
     }
   });
+}
+
 
+function scanEnvVars(dir, scan) {
   // Parse .env.example for env vars
   const envExample = resolve(dir, '.env.example');
   if (existsSync(envExample)) {
@@ -451,20 +495,6 @@ function scanProject(dir) {
       }
     }
   }
-
-  // Count files and lines
-  countFilesAndLines(dir, scan);
-
-  // ── Filter test files out of source lists ──
-  // Test files (*.test.*, *.spec.*, __tests__/) should NOT appear as source files
-  const isTestFile = (f) => f.includes('__tests__') || f.includes('__test__') || /\.(test|spec)\.[^.]+$/.test(f);
-  scan.routes = scan.routes.filter(f => !isTestFile(f));
-  scan.models = scan.models.filter(f => !isTestFile(f));
-  scan.services = scan.services.filter(f => !isTestFile(f));
-  scan.components = scan.components.filter(f => !isTestFile(f));
-  scan.middlewares = scan.middlewares.filter(f => !isTestFile(f));
-
-  return scan;
 }
 
 function countFilesAndLines(dir, scan) {
@@ -535,7 +565,7 @@ function generateArchitecture(dir, config, stack, scan, flags, docTools) {
 ## 1. Introduction & Goals
 <!-- arc42: §1 — Introduction and Goals -->
 
-<!-- TODO: Describe what this system does, who it's for, and key quality goals -->
+<!-- TBD: Describe what this system does, who it's for, and key quality goals -->
 ${config.projectName} is a ${stack.framework || stack.language || 'software'} application.
 
 ### Quality Goals
@@ -611,8 +641,8 @@ See \\\`docs-canonical/DEPLOYMENT.md\\\` for details.
 | Environment | Infrastructure | URL |
 |-------------|---------------|-----|
 | Development | localhost | http://localhost:3000 |
-| Staging | ${stack.hosting || 'TBD'} | <!-- TODO --> |
-| Production | ${stack.hosting || 'TBD'} | <!-- TODO --> |
+| Staging | ${stack.hosting || 'TBD'} | <!-- TBD --> |
+| Production | ${stack.hosting || 'TBD'} | <!-- TBD --> |
 
 ## 8. Crosscutting Concepts
 <!-- arc42: §8 — Crosscutting Concepts -->
@@ -715,7 +745,7 @@ ${r.description ? `- **Description:** ${r.description}` : ''}
 
 | Parameter | In | Type | Required | Description |
 |-----------|-----|------|:--------:|-------------|
-| <!-- TODO --> | | | | |
+| <!-- TBD --> | | | | |
 
 | Status | Response |
 |--------|----------|
@@ -742,7 +772,7 @@ ${routeDetails}`;
 |----------|-------|
 | **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
 | **Base URL** | \`http://localhost:3000\` |
-| **Auth** | <!-- TODO: Describe auth mechanism --> |
+| **Auth** | <!-- TBD: Describe auth mechanism --> |
 | **Total Endpoints** | ${deepRoutes.length} |
 | **Source** | ${deepRoutes[0]?.source || 'code scan'} |
 
@@ -826,7 +856,7 @@ function generateDataModel(dir, config, stack, scan, flags, deepSchemas) {
 
 | Field | Type | Required | Default | Constraints | Description |
 |-------|------|----------|---------|-------------|-------------|
-| <!-- TODO: Fill in fields --> | | | | | |
+| <!-- TBD: Fill in fields --> | | | | | |
 `;
       }
       const fieldRows = e.fields.map(f =>
@@ -913,7 +943,7 @@ ${erDiagram}
 
 | Table | Index Name | Fields | Type | Purpose |
 |-------|-----------|--------|------|---------|
-| <!-- TODO: Document indexes --> | | | | |
+| <!-- TBD: Document indexes --> | | | | |
 
 ---
 
@@ -1046,9 +1076,9 @@ function generateTestSpec(dir, config, stack, scan, flags) {
 
 | Metric | Target | Current |
 |--------|:------:|:-------:|
-| Line Coverage | 80% | <!-- TODO --> |
-| Branch Coverage | 70% | <!-- TODO --> |
-| Function Coverage | 80% | <!-- TODO --> |
+| Line Coverage | 80% | <!-- TBD --> |
+| Branch Coverage | 70% | <!-- TBD --> |
+| Function Coverage | 80% | <!-- TBD --> |
 
 ## Service-to-Test Map
 
@@ -1103,7 +1133,7 @@ function generateSecurity(dir, config, stack, scan, flags) {
 
 | Method | Provider | Token Type | Expiry |
 |--------|---------|-----------|--------|
-| ${stack.auth || '<!-- TODO -->'} | | | |
+| ${stack.auth || '<!-- TBD -->'} | | | |
 
 ## Authorization
 
@@ -1117,8 +1147,8 @@ function generateSecurity(dir, config, stack, scan, flags) {
 | Secret | Storage | Rotation | Access |
 |--------|---------|----------|--------|
 ${scan.envVars.filter(v => isSecretVar(v.name)).map(v =>
-  `| \`${v.name}\` | Environment Variable | <!-- TODO --> | Application |`
-).join('\n') || '| <!-- TODO --> | | | |'}
+  `| \`${v.name}\` | Environment Variable | <!-- TBD --> | Application |`
+).join('\n') || '| <!-- TBD --> | | | |'}
 
 ## Security Rules
 

package/cli/commands/guard.mjs

@@ -20,6 +20,7 @@ import { validateArchitecture } from '../validators/architecture.mjs';
 import { validateFreshness } from '../validators/freshness.mjs';
 import { validateTraceability } from '../validators/traceability.mjs';
 import { validateDocsDiff } from '../validators/docs-diff.mjs';
+import { validateApiSurface } from '../validators/api-surface.mjs';
 import { validateMetadataSync } from '../validators/metadata-sync.mjs';
 import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
 import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
@@ -32,6 +33,38 @@ import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
  * Internal guard — returns structured data, no console output, no process.exit.
  * Used by diagnose, ci, and guard --format json.
  */
+/**
+ * Classify a validator result into a status + quality badge.
+ *
+ * Critically, a check that found NOTHING to validate (no errors, no warnings,
+ * total === 0) — or that explicitly reports `applicable === false` — is status
+ * 'na' (not applicable), NOT 'pass'. This prevents a validator from rendering a
+ * confident green ✅ when it actually checked nothing (the root cause of the
+ * "clean bill of health on out-of-sync docs" incident).
+ */
+export function classifyResult(result) {
+  const hasErrors = result.errors.length > 0;
+  const hasWarnings = result.warnings.length > 0;
+
+  if (!hasErrors && !hasWarnings && (result.applicable === false || result.total === 0)) {
+    return { status: 'na', quality: null };
+  }
+
+  const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
+
+  // Quality label: HIGH/MEDIUM/LOW (inspired by CJE quality stratification, Lopez et al. TRACE 2026)
+  let quality;
+  if (hasErrors) {
+    quality = 'LOW';
+  } else if (hasWarnings) {
+    quality = 'MEDIUM';
+  } else {
+    const ratio = result.total > 0 ? result.passed / result.total : 1;
+    quality = ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
+  }
+  return { status, quality };
+}
+
 export function runGuardInternal(projectDir, config) {
   const validators = config.validators || {};
   const results = [];
@@ -40,7 +73,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'structure', name: 'Structure', fn: () => validateStructure(projectDir, config) },
     { key: 'structure', name: 'Doc Sections', fn: () => validateDocSections(projectDir, config) },
     { key: 'docsSync', name: 'Docs-Sync', fn: () => validateDocsSync(projectDir, config) },
-    { key: 'drift', name: 'Drift', fn: () => validateDrift(projectDir, config) },
+    { key: 'drift', name: 'Drift-Comments', fn: () => validateDrift(projectDir, config) },
     { key: 'changelog', name: 'Changelog', fn: () => validateChangelog(projectDir, config) },
     { key: 'testSpec', name: 'Test-Spec', fn: () => validateTestSpec(projectDir, config) },
     { key: 'environment', name: 'Environment', fn: () => validateEnvironment(projectDir, config) },
@@ -60,6 +93,7 @@ export function runGuardInternal(projectDir, config) {
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
     { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
+    { key: 'apiSurface', name: 'API-Surface', fn: () => validateApiSurface(projectDir, config) },
     { key: 'metadataSync', name: 'Metadata-Sync', fn: () => validateMetadataSync(projectDir, config) },
     { key: 'docsCoverage', name: 'Docs-Coverage', fn: () => validateDocsCoverage(projectDir, config) },
     { key: 'docQuality', name: 'Doc-Quality', fn: () => validateDocQuality(projectDir, config) },
@@ -77,23 +111,7 @@ export function runGuardInternal(projectDir, config) {
 
     try {
       const result = fn();
-      const hasErrors = result.errors.length > 0;
-      const hasWarnings = result.warnings.length > 0;
-      const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
-
-      // Quality label: HIGH/MEDIUM/LOW (inspired by CJE quality stratification, Lopez et al. TRACE 2026)
-      let quality;
-      if (hasErrors) {
-        quality = 'LOW';
-      } else if (hasWarnings) {
-        quality = 'MEDIUM';
-      } else {
-        // Pass — check coverage ratio for HIGH vs MEDIUM
-        const ratio = result.total > 0 ? result.passed / result.total : 1;
-        quality = ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
-      }
-
-      results.push({ ...result, name, key, status, quality });
+      results.push({ ...result, name, key, ...classifyResult(result) });
     } catch (err) {
       results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
     }
@@ -103,12 +121,7 @@ export function runGuardInternal(projectDir, config) {
   if (validators.metricsConsistency !== false) {
     try {
       const result = validateMetricsConsistency(projectDir, config, results);
-      const hasErrors = result.errors.length > 0;
-      const hasWarnings = result.warnings.length > 0;
-      const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
-      const ratio = result.total > 0 ? result.passed / result.total : 1;
-      const quality = hasErrors ? 'LOW' : hasWarnings ? 'MEDIUM' : ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
-      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', status, quality });
+      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', ...classifyResult(result) });
     } catch (err) {
       results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
     }
@@ -161,6 +174,14 @@ export function runGuard(projectDir, config, flags) {
       continue;
     }
 
+    // Not applicable — nothing to validate. Render neutrally (NOT a green pass)
+    // so the reader can tell "checked and clean" apart from "nothing checked".
+    if (v.status === 'na') {
+      const reason = v.note ? ` ${c.dim}(${v.note})${c.reset}` : ` ${c.dim}(nothing to validate)${c.reset}`;
+      console.log(`  ${c.dim}➖ ${v.name}${c.reset} ${c.dim}[N/A]${c.reset}${reason}`);
+      continue;
+    }
+
     // Quality label badge
     const qColor = v.quality === 'HIGH' ? c.green : v.quality === 'MEDIUM' ? c.yellow : c.red;
     const qBadge = `${qColor}[${v.quality}]${c.reset}`;

package/cli/scanners/api-doc.mjs

@@ -0,0 +1,122 @@
+/**
+ * API Documentation Parser
+ *
+ * Extracts API endpoints from a canonical API doc (API-REFERENCE.md) robustly,
+ * and provides normalized comparison primitives shared by `docguard diff` and
+ * the API-Surface guard validator.
+ *
+ * Handles two documentation styles:
+ *   1. Headings:    `#### GET /api/admin/users`  (method + path, backticks optional)
+ *   2. Table rows:  | `GET` | `/api/admin/users` | ... |
+ *
+ * Normalization makes comparison reliable:
+ *   - method split into its own field, upper-cased
+ *   - path params unified: `:id` ≡ `{id}` → `{}` placeholder
+ *   - trailing slashes, backticks, and table pipes stripped
+ *   - query strings / fragments removed
+ *
+ * Zero NPM dependencies — pure Node.js built-ins only.
+ */
+
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+
+/**
+ * Normalize an API path for comparison.
+ * Strips decoration and collapses param syntax so `:id` and `{id}` match.
+ * @param {string} raw
+ * @returns {string} normalized path (e.g. "/api/users/{}") or '' if not a path
+ */
+export function normalizePath(raw) {
+  if (!raw) return '';
+  let p = String(raw).trim();
+  // strip surrounding backticks / pipes / quotes / whitespace
+  p = p.replace(/^[|`'"\s]+/, '').replace(/[|`'"\s]+$/, '');
+  // cut query string / fragment
+  p = p.split(/[?#]/)[0];
+  if (!p.startsWith('/')) return '';
+  // collapse param syntax: :param and {param} → {}
+  p = p.replace(/\{[^}/]+\}/g, '{}').replace(/:[^/]+/g, '{}');
+  // strip trailing slash (but keep root "/")
+  if (p.length > 1) p = p.replace(/\/+$/, '');
+  return p;
+}
+
+/** Build a canonical comparison key for an endpoint. */
+export function endpointKey(method, path) {
+  return `${String(method).toUpperCase()} ${normalizePath(path)}`;
+}
+
+/**
+ * Parse endpoints documented in an API reference markdown string.
+ * @param {string} content
+ * @returns {Array<{ method: string, path: string, key: string }>}
+ */
+export function parseApiReferenceDoc(content) {
+  if (!content) return [];
+  const found = new Map(); // key → { method, path, key }
+
+  const addEndpoint = (method, rawPath) => {
+    const m = String(method).toUpperCase();
+    if (!HTTP_METHODS.has(m)) return;
+    const path = normalizePath(rawPath);
+    if (!path || path.length < 2) return;
+    const key = `${m} ${path}`;
+    if (!found.has(key)) found.set(key, { method: m, path, key });
+  };
+
+  const lines = content.split('\n');
+
+  // Style 1: headings — "#### GET `/api/...`" (method + path, backticks optional)
+  const headingRe = /^#{2,6}\s+`?(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)`?\s+`?(\/[^\s`|]+)`?/i;
+
+  // Style 2: table rows — "| `GET` | `/api/...` | ... |"
+  for (const line of lines) {
+    const h = line.match(headingRe);
+    if (h) {
+      addEndpoint(h[1], h[2]);
+      continue;
+    }
+
+    if (line.includes('|')) {
+      const cells = line.split('|').map(s => s.trim()).filter(s => s.length > 0);
+      if (cells.length >= 2) {
+        const c0 = cells[0].replace(/`/g, '').trim().toUpperCase();
+        if (HTTP_METHODS.has(c0)) {
+          // path is the next cell that looks like a route
+          for (let i = 1; i < cells.length; i++) {
+            const cand = cells[i].replace(/`/g, '').trim();
+            if (cand.startsWith('/')) { addEndpoint(c0, cand); break; }
+          }
+        }
+      }
+    }
+  }
+
+  return [...found.values()];
+}
+
+/**
+ * Compare a documented endpoint set against an actual endpoint set.
+ * @param {Array<{method,path}>} documented
+ * @param {Array<{method,path}>} actual
+ * @returns {{ documentedButAbsent: object[], presentButUndocumented: object[], matched: object[] }}
+ */
+export function compareEndpoints(documented, actual) {
+  const docMap = new Map();
+  for (const e of documented) docMap.set(endpointKey(e.method, e.path), e);
+  const actMap = new Map();
+  for (const e of actual) actMap.set(endpointKey(e.method, e.path), e);
+
+  const documentedButAbsent = [];
+  const matched = [];
+  for (const [key, e] of docMap) {
+    if (actMap.has(key)) matched.push(e);
+    else documentedButAbsent.push(e);
+  }
+  const presentButUndocumented = [];
+  for (const [key, e] of actMap) {
+    if (!docMap.has(key)) presentButUndocumented.push(e);
+  }
+
+  return { documentedButAbsent, presentButUndocumented, matched };
+}

package/cli/scanners/doc-tools.mjs

@@ -36,7 +36,7 @@ export function detectDocTools(dir) {
 
 // ── OpenAPI / Swagger Spec ─────────────────────────────────────────────────
 
-function detectOpenAPI(dir) {
+export function detectOpenAPI(dir) {
   const candidates = [
     'openapi.yaml', 'openapi.yml', 'openapi.json',
     'swagger.yaml', 'swagger.yml', 'swagger.json',

package/cli/scanners/routes.mjs

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname, dirname } from 'node:path';
+import { resolveSourceRoots } from '../shared-source.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -19,9 +20,10 @@ const IGNORE_DIRS = new Set([
  * @param {string} dir - Project root
  * @param {object} stack - Detected tech stack
  * @param {object} docTools - Detected doc tools (may include OpenAPI)
+ * @param {object} [opts] - { config } — config enables monorepo-aware source roots
  * @returns {Array} Array of route objects { method, path, handler, file, auth, description }
  */
-export function scanRoutesDeep(dir, stack, docTools) {
+export function scanRoutesDeep(dir, stack, docTools, opts = {}) {
   // Priority 1: Use OpenAPI spec if available (most accurate)
   if (docTools?.openapi?.found && docTools.openapi.endpoints?.length > 0) {
     return docTools.openapi.endpoints.map(ep => ({
@@ -31,24 +33,27 @@ export function scanRoutesDeep(dir, stack, docTools) {
     }));
   }
 
-  // Priority 2: Framework-specific code scanning
+  // Priority 2: Framework-specific code scanning.
+  // Monorepo-aware: when a config is supplied, scan the resolved source roots
+  // (honors config.sourceRoot + workspaces) instead of only root-relative dirs.
   const framework = stack?.framework || '';
   const routes = [];
+  const roots = opts.config ? resolveSourceRoots(dir, opts.config) : null;
 
   if (framework.includes('Next.js') || framework.includes('Next')) {
     routes.push(...scanNextJsRoutes(dir));
   }
 
   if (framework.includes('Express') || !framework) {
-    routes.push(...scanExpressRoutes(dir));
+    routes.push(...scanExpressRoutes(dir, roots));
   }
 
   if (framework.includes('Fastify')) {
-    routes.push(...scanFastifyRoutes(dir));
+    routes.push(...scanFastifyRoutes(dir, roots));
   }
 
   if (framework.includes('Hono')) {
-    routes.push(...scanHonoRoutes(dir));
+    routes.push(...scanHonoRoutes(dir, roots));
   }
 
   if (framework.includes('Django')) {
@@ -167,13 +172,16 @@ function scanNextJsRoutes(dir) {
 
 // ── Express / Generic Node.js ───────────────────────────────────────────────
 
-function scanExpressRoutes(dir) {
+function scanExpressRoutes(dir, roots = null) {
   const routes = [];
   const routePattern = /(?:app|router|server)\s*\.\s*(get|post|put|delete|patch|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
 
-  const searchDirs = ['src', 'routes', 'api', 'server', 'lib'];
-  for (const searchDir of searchDirs) {
-    const fullDir = resolve(dir, searchDir);
+  // Monorepo-aware: walk resolved absolute source roots when provided,
+  // otherwise fall back to conventional root-relative directories.
+  const searchTargets = roots && roots.length
+    ? roots
+    : ['src', 'routes', 'api', 'server', 'lib'].map(d => resolve(dir, d));
+  for (const fullDir of searchTargets) {
     if (!existsSync(fullDir)) continue;
 
     walkRouteDirs(fullDir, (filePath) => {
@@ -224,42 +232,47 @@ function scanExpressRoutes(dir) {
 
 // ── Fastify ─────────────────────────────────────────────────────────────────
 
-function scanFastifyRoutes(dir) {
+function scanFastifyRoutes(dir, roots = null) {
   const routes = [];
   const pattern = /(?:fastify|server|app)\s*\.\s*(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
 
-  walkRouteDirs(resolve(dir, 'src'), (filePath) => {
-    if (!isJSFile(filePath)) return;
-    const content = readFileSafe(filePath);
-    if (!content) return;
+  const searchTargets = roots && roots.length ? roots : [resolve(dir, 'src')];
+  for (const fullDir of searchTargets) {
+    if (!existsSync(fullDir)) continue;
+    walkRouteDirs(fullDir, (filePath) => {
+      if (!isJSFile(filePath)) return;
+      const content = readFileSafe(filePath);
+      if (!content) return;
 
-    let match;
-    const regex = new RegExp(pattern.source, 'gi');
-    while ((match = regex.exec(content)) !== null) {
-      routes.push({
-        method: match[1].toUpperCase(),
-        path: match[2],
-        handler: extractHandlerName(content, match.index),
-        file: relative(dir, filePath),
-        source: 'fastify',
-        auth: hasAuthCheck(content),
-        description: extractNearbyComment(content, match.index),
-      });
-    }
-  });
+      let match;
+      const regex = new RegExp(pattern.source, 'gi');
+      while ((match = regex.exec(content)) !== null) {
+        routes.push({
+          method: match[1].toUpperCase(),
+          path: match[2],
+          handler: extractHandlerName(content, match.index),
+          file: relative(dir, filePath),
+          source: 'fastify',
+          auth: hasAuthCheck(content),
+          description: extractNearbyComment(content, match.index),
+        });
+      }
+    });
+  }
 
   return routes;
 }
 
 // ── Hono ────────────────────────────────────────────────────────────────────
 
-function scanHonoRoutes(dir) {
+function scanHonoRoutes(dir, roots = null) {
   const routes = [];
   const pattern = /(?:app|router)\s*\.\s*(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
 
-  const searchDirs = ['src', '.'];
-  for (const searchDir of searchDirs) {
-    const fullDir = resolve(dir, searchDir);
+  const searchTargets = roots && roots.length
+    ? roots
+    : ['src', '.'].map(d => resolve(dir, d));
+  for (const fullDir of searchTargets) {
     if (!existsSync(fullDir)) continue;
 
     walkRouteDirs(fullDir, (filePath) => {