docguard-cli 0.23.0 → 0.24.0

package/cli/ensure-skills.mjs

@@ -46,9 +46,12 @@ const __dirname = dirname(__filename);
 const SKILLS_SOURCE = resolve(__dirname, '..', 'extensions', 'spec-kit-docguard', 'skills');
 const COMMANDS_SOURCE = resolve(__dirname, '..', 'commands');
 
-// Destination in the user's project
+// Destination in the user's project. Commands live UNDER `.agent/` alongside
+// skills (was root `commands/`, which polluted the project namespace and got
+// mis-scanned as source). `.agent/commands/` is the generic spec-kit convention
+// agents already discover, and keeps DocGuard's footprint in one place.
 const SKILLS_DEST = '.agent/skills';
-const COMMANDS_DEST = 'commands';
+const COMMANDS_DEST = '.agent/commands';
 
 // ── Agent Mode Detection ────────────────────────────────────────────────
 
@@ -195,14 +198,6 @@ export function isSpecKitInitialized(projectDir) {
 
 // ── Spec-Kit Integration Gate ───────────────────────────────────────────
 
-// Read DocGuard package version (for skill auto-update)
-const PKG_VERSION = (() => {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
-    return pkg.version || '0.0.0';
-  } catch { return '0.0.0'; }
-})();
-
 const SPEC_KIT_INSTALL_CMD = 'uv tool install specify-cli --from git+https://github.com/github/spec-kit.git';
 
 /**
@@ -225,6 +220,13 @@ export function ensureSpecKit(projectDir, flags = {}) {
     return { specKitReady: true };
   }
 
+  // Caller opted out of the Spec Kit framework scaffold (--no-spec-kit, or the
+  // minimal `starter` profile which passes noSpecKit through). Don't auto-init
+  // and don't nag — DocGuard's own skills/commands still install below.
+  if (flags.noSpecKit) {
+    return { specKitReady: false, skipped: true };
+  }
+
   // Spec-kit CLI available — auto-initialize
   if (isSpecKitAvailable()) {
     if (!silent) {
@@ -298,26 +300,22 @@ export function ensureSkills(projectDir, flags = {}) {
 
       for (const skillDir of skillDirs) {
         const destDir = resolve(projectDir, SKILLS_DEST, skillDir);
-        if (!existsSync(destDir)) {
-          mkdirSync(destDir, { recursive: true });
-        }
         const srcSkill = resolve(SKILLS_SOURCE, skillDir, 'SKILL.md');
         const destSkill = resolve(destDir, 'SKILL.md');
 
-        if (!existsSync(destSkill)) {
-          // New install
-          writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+        const srcContent = readFileSync(srcSkill, 'utf-8');
+        const installedContent = existsSync(destSkill) ? readFileSync(destSkill, 'utf-8') : null;
+
+        // Content-equality gate: write only when the bundled skill differs from
+        // what's on disk. Covers a fresh install AND a genuine update, but stops
+        // the per-command rewrite churn the old version-marker gate caused — a
+        // skill whose SKILL.md lacked a `docguard:version:` marker compared as
+        // '0.0.0', so it was rewritten (and announced) on EVERY command, even
+        // read-only ones like `explain`/`score` (field report, Issue D).
+        if (installedContent !== srcContent) {
+          if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+          writeFileSync(destSkill, srcContent, 'utf-8');
           result.skillsInstalled = true;
-        } else {
-          // Auto-update: check if package version is newer than installed
-          const installedContent = readFileSync(destSkill, 'utf-8');
-          const versionMatch = installedContent.match(/docguard:version:\s*(\S+)/);
-          const installedVersion = versionMatch ? versionMatch[1] : '0.0.0';
-
-          if (installedVersion !== PKG_VERSION) {
-            writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
-            result.skillsInstalled = true;
-          }
         }
       }
 

package/cli/scanners/api-doc.mjs

@@ -22,7 +22,17 @@ const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', '
 
 /**
  * Normalize an API path for comparison.
- * Strips decoration and collapses param syntax so `:id` and `{id}` match.
+ * Strips decoration and collapses ALL dynamic-segment syntaxes to a single `{}`
+ * placeholder so an endpoint documented one way matches the same endpoint
+ * emitted another way:
+ *   Express/colon   `/users/:id`            → `/users/{}`
+ *   OpenAPI/brace   `/users/{id}`           → `/users/{}`
+ *   Next.js bracket `/users/[id]`           → `/users/{}`
+ *   catch-all       `/auth/[...nextauth]`, `/auth/:nextauth*` → `/auth/{}`
+ *   optional c-all  `/shop/[[...filters]]`  → `/shop/{}`
+ * Without the bracket rule, a doc written in Next.js `[id]` syntax never matched
+ * the code-scan's `:id`, so every dynamic route double-fired as both
+ * "documented-but-absent" and "undocumented" (field test: hugocross_revamp).
  * @param {string} raw
  * @returns {string} normalized path (e.g. "/api/users/{}") or '' if not a path
  */
@@ -34,8 +44,12 @@ export function normalizePath(raw) {
   // cut query string / fragment
   p = p.split(/[?#]/)[0];
   if (!p.startsWith('/')) return '';
-  // collapse param syntax: :param and {param} → {}
-  p = p.replace(/\{[^}/]+\}/g, '{}').replace(/:[^/]+/g, '{}');
+  // collapse every param syntax to {}: Next.js [id]/[...slug]/[[...slug]],
+  // OpenAPI {param}, and colon :param (incl. catch-all :param*).
+  p = p
+    .replace(/\[{1,2}[^\]]*\]{1,2}/g, '{}')
+    .replace(/\{[^}/]+\}/g, '{}')
+    .replace(/:[^/]+/g, '{}');
   // strip trailing slash (but keep root "/")
   if (p.length > 1) p = p.replace(/\/+$/, '');
   return p;

package/cli/scanners/doc-tools.mjs

@@ -9,6 +9,21 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 
+/**
+ * Read + parse a JSON file, returning null on any error (missing, unreadable,
+ * malformed). A bare `JSON.parse(readFileSync(...))` on a malformed
+ * `package.json` used to THROW out of a detector and abort the entire
+ * `detectDocTools` scan — which then made the memory plan (and every validator
+ * that compares against it) see empty "truth" and falsely pass. Fail soft.
+ */
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Detect all documentation tools present in the project.
  * @param {string} dir - Project root directory
@@ -57,6 +72,7 @@ export function detectOpenAPI(dir) {
         endpoints: spec.endpoints,
         schemas: spec.schemas,
         info: spec.info,
+        parseIncomplete: spec.parseIncomplete === true,
       };
     }
   }
@@ -122,6 +138,14 @@ function parseOpenAPISpec(content, filename) {
     }
   } catch { /* spec parsing failed, return empty */ }
 
+  // Honest-failure signal: a spec that clearly declares a `paths:` section but
+  // yielded ZERO endpoints means our parser couldn't extract them (anchors,
+  // unresolved $ref, folded scalars, or a YAML feature the minimal parser
+  // doesn't cover). Flag it so the caller can WARN and fall back to code
+  // scanning, instead of silently reporting "no API surface" — a false green.
+  const hasPathsKey = /(^|\n)[ \t]*["']?paths["']?[ \t]*:/.test(content);
+  result.parseIncomplete = hasPathsKey && result.endpoints.length === 0;
+
   return result;
 }
 
@@ -215,12 +239,9 @@ function detectTypeDoc(dir) {
   }
 
   // Check package.json devDeps
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    if (pkg.devDependencies?.typedoc) {
-      return { found: true, config: 'package.json (devDependency)' };
-    }
+  const pkg = readJsonSafe(resolve(dir, 'package.json'));
+  if (pkg?.devDependencies?.typedoc) {
+    return { found: true, config: 'package.json (devDependency)' };
   }
 
   return { found: false };
@@ -236,12 +257,9 @@ function detectJSDoc(dir) {
     }
   }
 
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    if (pkg.devDependencies?.jsdoc) {
-      return { found: true, config: 'package.json (devDependency)' };
-    }
+  const pkg = readJsonSafe(resolve(dir, 'package.json'));
+  if (pkg?.devDependencies?.jsdoc) {
+    return { found: true, config: 'package.json (devDependency)' };
   }
 
   return { found: false };
@@ -316,9 +334,8 @@ function detectRedocly(dir) {
 // ── Swagger UI ─────────────────────────────────────────────────────────────
 
 function detectSwagger(dir) {
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const pkg = readJsonSafe(resolve(dir, 'package.json'));
+  if (pkg) {
     const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
     if (allDeps['swagger-ui-express'] || allDeps['@fastify/swagger'] || allDeps['swagger-jsdoc']) {
       return {

package/cli/scanners/frontend.mjs

@@ -16,12 +16,9 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
-import { resolveSourceRoots, collectPackageJsons } from '../shared-source.mjs';
-
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
-]);
+import { resolveSourceRoots, collectPackageJsons, readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { extractJsxRouteScreens } from './js-ast.mjs';
 const UI_EXT = new Set(['.tsx', '.jsx']);
 
 function walk(dir, onFile, depth = 0) {
@@ -36,7 +33,7 @@ function walk(dir, onFile, depth = 0) {
   }
 }
 
-function readSafe(p) { try { return readFileSync(p, 'utf-8'); } catch { return ''; } }
+function readSafe(p) { return readScannable(p) ?? ''; } // size-capped; skips bundles
 
 /** Normalize a route path param syntax to {param} and strip trailing slash. */
 function normRoute(p) {
@@ -111,6 +108,15 @@ function scanReactRouterScreens(roots, projectDir) {
       if (!content.includes('<Route') && !content.includes('createBrowserRouter') &&
           !content.includes('useRoutes') && !content.includes('createRoutesFrom')) return;
 
+      // AST-first: scopes each route's element JSX exactly (nested auth wrappers,
+      // layouts, and multi-line elements no longer truncate or mis-pick the
+      // screen). `null` → parse failure → the window-based regex fallback below.
+      const astScreens = extractJsxRouteScreens(content, file);
+      if (astScreens) {
+        for (const s of astScreens) add(s.path, pickScreenComponent(s.components), file);
+        return;
+      }
+
       let m;
       const re = new RegExp(pathRe.source, 'g');
       while ((m = re.exec(content)) !== null) {
@@ -434,5 +440,15 @@ export function scanFrontend(projectDir, config = {}) {
     a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
   const i18n = scanI18n(projectDir, roots);
 
-  return { ...stack, routerType, screens, components, stores, hooks, contexts, apiCalls, i18n };
+  // Honor .docguardignore / config.ignore — drop entries whose source file the
+  // user excluded (e.g. a fixtures/storybook dir). Entries without a `file`
+  // (or in i18n) are unaffected.
+  const keep = (arr) => Array.isArray(arr)
+    ? arr.filter(x => !x || !x.file || !shouldIgnore(relPosix(projectDir, resolve(projectDir, x.file)), config))
+    : arr;
+  return {
+    ...stack, routerType,
+    screens: keep(screens), components: keep(components), stores: keep(stores),
+    hooks: keep(hooks), contexts: keep(contexts), apiCalls: keep(apiCalls), i18n,
+  };
 }