docguard-cli 0.9.11 → 0.11.0

package/cli/docguard.mjs

@@ -35,6 +35,7 @@ import { runCI } from './commands/ci.mjs';
 import { runFix } from './commands/fix.mjs';
 import { runWatch } from './commands/watch.mjs';
 import { runDiagnose } from './commands/diagnose.mjs';
+import { runSync } from './commands/sync.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
 import { runLlms } from './commands/llms.mjs';
@@ -236,6 +237,10 @@ ${c.bold}Enforcement:${c.reset}
   ${c.green}guard${c.reset}      Validate project against canonical docs (51+ checks)
   ${c.green}diagnose${c.reset}   AI orchestrator — guard → fix in one command
 
+${c.bold}Memory (build & maintain docs):${c.reset}
+  ${c.green}generate --plan${c.reset}  AI-powered: scan any project, emit agent task manifest + skeleton
+  ${c.green}sync${c.reset}       Refresh code-truth doc sections to match current code (always up to date)
+
 ${c.bold}Analysis:${c.reset}
   ${c.green}score${c.reset}      CDD maturity score (0-100)
   ${c.green}trace${c.reset}      Requirements traceability matrix
@@ -267,6 +272,13 @@ ${c.bold}Options:${c.reset}
   --threshold <n> Minimum score for CI pass (used with ci command)
   --fail-on-warning  Fail CI on warnings (used with ci command)
   --auto          Auto-fix what's possible (used with fix command)
+  --write         Apply deterministic fixes in place (fix command): removes
+                  documented endpoints the OpenAPI spec confirms are gone.
+                  Only edits docguard:generated docs unless --force.
+  --plan          AI-powered Generate (generate command): scan any project
+                  (JS/Python/Rust/Go/Java/…), emit the agent task manifest +
+                  code-truth skeleton. Add --write to scaffold, --format json
+                  for the machine-readable manifest.
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
   --profile <p>   Compliance profile: starter, standard, enterprise (init command)
   --tax           Show estimated documentation maintenance cost (with score)
@@ -346,6 +358,13 @@ async function main() {
       flags.failOnWarning = true;
     } else if (args[i] === '--auto') {
       flags.auto = true;
+    } else if (args[i] === '--write') {
+      flags.write = true;
+    } else if (args[i] === '--plan') {
+      flags.plan = true;
+    } else if (args[i] === '--since' && args[i + 1]) {
+      flags.since = args[i + 1];
+      i++;
     } else if (args[i] === '--doc' && args[i + 1]) {
       flags.doc = args[i + 1];
       i++;
@@ -443,6 +462,9 @@ async function main() {
     case 'watch':
       runWatch(projectDir, config, flags);
       break;
+    case 'sync':
+      runSync(projectDir, config, flags);
+      break;
     case 'publish':
     case 'pub':
       runPublish(projectDir, config, flags);

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/frontend.mjs

@@ -0,0 +1,438 @@
+/**
+ * Frontend Scanner — captures the UI surface of a project so the generated
+ * "memory" covers screens/pages/components, not just the backend API.
+ *
+ * Detects:
+ *   - Screens/routes:
+ *       • React Router  — <Route path="/x" element={<XPage/>} /> and route-object configs
+ *       • Next.js App   — app/**​/page.{tsx,jsx}
+ *       • Next.js Pages — pages/**​/*.{tsx,jsx} (excluding api/ and _files)
+ *   - Component inventory (files under components/ dirs)
+ *   - State + data libraries (from dependencies)
+ *
+ * Monorepo-aware via resolveSourceRoots(). Pure read-only scanning.
+ * Zero NPM dependencies — Node.js built-ins only.
+ */
+
+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',
+]);
+const UI_EXT = new Set(['.tsx', '.jsx']);
+
+function walk(dir, onFile, depth = 0) {
+  if (depth > 12 || !existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) walk(full, onFile, depth + 1);
+    else if (e.isFile()) onFile(full);
+  }
+}
+
+function readSafe(p) { try { return readFileSync(p, 'utf-8'); } catch { return ''; } }
+
+/** Normalize a route path param syntax to {param} and strip trailing slash. */
+function normRoute(p) {
+  let s = String(p).trim();
+  if (!s.startsWith('/')) s = '/' + s;
+  s = s.replace(/:([A-Za-z0-9_]+)/g, '{$1}').replace(/\[(?:\.\.\.)?(\w+)\]/g, '{$1}');
+  if (s.length > 1) s = s.replace(/\/+$/, '');
+  return s;
+}
+
+/** Detect the frontend stack from merged dependencies. */
+function detectFrontendStack(projectDir, config) {
+  const deps = {};
+  for (const { pkg } of collectPackageJsons(projectDir, config)) {
+    Object.assign(deps, pkg.dependencies || {}, pkg.devDependencies || {});
+  }
+  let framework = '';
+  if (deps.next) framework = 'Next.js';
+  else if (deps['react-router-dom'] || deps['react-router']) framework = 'React Router';
+  else if (deps['@tanstack/react-router']) framework = 'TanStack Router';
+  else if (deps.react) framework = 'React';
+  else if (deps.vue) framework = 'Vue';
+  else if (deps.svelte || deps['@sveltejs/kit']) framework = 'Svelte';
+
+  const stateLib = deps.zustand ? 'Zustand'
+    : deps['@reduxjs/toolkit'] || deps.redux ? 'Redux'
+    : deps.jotai ? 'Jotai' : deps.mobx ? 'MobX' : null;
+  const dataLib = deps['@tanstack/react-query'] ? 'TanStack Query'
+    : deps.swr ? 'SWR' : deps['@apollo/client'] ? 'Apollo' : null;
+  const buildTool = deps.vite ? 'Vite' : deps.next ? 'Next.js' : deps.webpack ? 'Webpack' : null;
+
+  return { framework, stateLib, dataLib, buildTool };
+}
+
+// Components that WRAP a route's real screen — skip them when identifying the page.
+const ROUTE_WRAPPERS = new Set([
+  'RequireAuth', 'ProtectedRoute', 'PrivateRoute', 'PublicRoute', 'AuthGuard',
+  'Guard', 'Suspense', 'Layout', 'AppLayout', 'MainLayout', 'RootLayout',
+  'Fragment', 'Outlet', 'Navigate', 'ErrorBoundary', 'Route', 'Routes',
+  'Provider', 'Wrapper',
+]);
+
+/** Pick the most meaningful screen component from candidates in a route element. */
+function pickScreenComponent(candidates) {
+  const real = candidates.filter(c => !ROUTE_WRAPPERS.has(c));
+  if (real.length === 0) return candidates[candidates.length - 1] || null;
+  // Prefer a *Page / *Screen / *View name, else the innermost (last) real one.
+  const named = real.find(c => /(Page|Screen|View)$/.test(c));
+  return named || real[real.length - 1];
+}
+
+/** Extract React Router screens: <Route path=".." element={<Wrapper><Comp/></Wrapper>} /> + route objects. */
+function scanReactRouterScreens(roots, projectDir) {
+  const screens = [];
+  const seen = new Set();
+  const add = (path, component, file) => {
+    const p = normRoute(path);
+    if (seen.has(p)) return; // one screen per path
+    seen.add(p);
+    screens.push({ path: p, component: component || null, file: relative(projectDir, file) });
+  };
+
+  // Find each `path="..."`, then look in a window AFTER it for the element's
+  // component(s) — the element JSX can nest wrappers, so collect all and pick.
+  const pathRe = /\bpath\s*[=:]\s*["'`]([^"'`]+)["'`]/g;
+  const compRe = /<\s*([A-Z][A-Za-z0-9_]*)/g;
+
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!UI_EXT.has(extname(file)) && !/\.(ts|js|mjs)$/.test(file)) return;
+      const content = readSafe(file);
+      if (!content.includes('<Route') && !content.includes('createBrowserRouter') &&
+          !content.includes('useRoutes') && !content.includes('createRoutesFrom')) return;
+
+      let m;
+      const re = new RegExp(pathRe.source, 'g');
+      while ((m = re.exec(content)) !== null) {
+        // Window = from this path up to the START of the next route entry
+        // (next `path=`/`path:`), capped — so nested `<Spinner/>` fallbacks don't
+        // truncate the window before the real screen component.
+        const start = m.index + m[0].length;
+        const nextPath = new RegExp(pathRe.source, 'g');
+        nextPath.lastIndex = start;
+        const nm = nextPath.exec(content);
+        const end = Math.min(nm ? nm.index : content.length, start + 400);
+        const windowStr = content.slice(start, end);
+        const comps = [];
+        let cm;
+        const cre = new RegExp(compRe.source, 'g');
+        while ((cm = cre.exec(windowStr)) !== null) comps.push(cm[1]);
+        add(m[1], pickScreenComponent(comps), file);
+      }
+    });
+  }
+  return screens;
+}
+
+/** Extract Next.js screens from app/ and pages/ file conventions. */
+function scanNextScreens(projectDir, config) {
+  const screens = [];
+  const seen = new Set();
+  const add = (path, file) => {
+    const p = normRoute(path || '/');
+    if (seen.has(p)) return;
+    seen.add(p);
+    screens.push({ path: p, component: basename(relative(projectDir, file)), file: relative(projectDir, file) });
+  };
+
+  // Next conventions live at a PACKAGE root (app/, pages/, src/app, src/pages),
+  // so search package/project bases — not the granular source roots (which
+  // already include `app/` and would double-append).
+  const bases = new Set([resolve(projectDir)]);
+  for (const { dir } of collectPackageJsons(projectDir, config)) bases.add(dir);
+
+  for (const root of bases) {
+    // App Router: app/**/page.{tsx,jsx}
+    for (const appBase of ['app', 'src/app']) {
+      const appDir = resolve(root, appBase);
+      if (!existsSync(appDir)) continue;
+      walk(appDir, (file) => {
+        if (!/^page\.(tsx|jsx|ts|js)$/.test(basename(file))) return;
+        const rel = relative(appDir, file).replace(/\/page\.\w+$/, '').replace(/^page\.\w+$/, '');
+        // strip route groups (group) segments
+        const routePath = '/' + rel.split('/').filter(seg => seg && !/^\(.*\)$/.test(seg)).join('/');
+        add(routePath, file);
+      });
+    }
+    // Pages Router: pages/**/*.{tsx,jsx} excluding api and _files
+    for (const pagesBase of ['pages', 'src/pages']) {
+      const pagesDir = resolve(root, pagesBase);
+      if (!existsSync(pagesDir)) continue;
+      walk(pagesDir, (file) => {
+        if (!UI_EXT.has(extname(file))) return;
+        const rel = relative(pagesDir, file);
+        if (rel.startsWith('api/') || basename(file).startsWith('_')) return;
+        const routePath = '/' + rel.replace(extname(rel), '').replace(/\/index$/, '').replace(/^index$/, '');
+        add(routePath, file);
+      });
+    }
+  }
+  return screens;
+}
+
+/** Inventory component files under components/ directories. */
+function scanComponents(roots, projectDir) {
+  const components = [];
+  const seen = new Set();
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!UI_EXT.has(extname(file))) return;
+      const rel = relative(projectDir, file);
+      // Heuristic: under a components/ dir, PascalCase filename, not a test/story.
+      if (!/(^|\/)components\//.test(rel)) return;
+      if (/\.(test|spec|stories)\./.test(rel)) return;
+      const name = basename(file, extname(file));
+      if (!/^[A-Z]/.test(name)) return;
+      if (seen.has(rel)) return;
+      seen.add(rel);
+      components.push({ name, file: rel });
+    });
+  }
+  return components;
+}
+
+/** Scan frontend state stores (Zustand, Redux Toolkit slices, Jotai atoms, MobX). */
+function scanStores(roots, projectDir) {
+  const out = [];
+  const seen = new Set();
+  const add = (name, library, file) => {
+    const key = `${name}::${file}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ name, library, file: relative(projectDir, file) });
+  };
+  // Zustand: const useThing = create(...) / create<T>(...)
+  const zustand = /\b(?:export\s+)?const\s+(use[A-Z]\w*)\s*=\s*create\b/g;
+  // Redux Toolkit slice
+  const rtkSlice = /\bcreateSlice\s*\(\s*\{[^}]*?\bname\s*:\s*["']([^"']+)["']/g;
+  // Jotai atoms: const xAtom = atom(...) / atomWithStorage(...)
+  const jotai = /\b(?:export\s+)?const\s+(\w+Atom)\s*=\s*atom(?:WithStorage)?\b/g;
+  // MobX: class XStore { makeObservable / makeAutoObservable }
+  const mobx = /\bclass\s+(\w+Store)\b[\s\S]{0,400}?(?:makeObservable|makeAutoObservable)\b/g;
+
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!/\.(ts|tsx|js|jsx|mjs)$/.test(file)) return;
+      const content = readSafe(file);
+      if (!content) return;
+      let m;
+      if (content.includes('create(') || content.includes('create<')) {
+        const re = new RegExp(zustand.source, 'g');
+        while ((m = re.exec(content)) !== null) add(m[1], 'Zustand', file);
+      }
+      if (content.includes('createSlice')) {
+        const re = new RegExp(rtkSlice.source, 'g');
+        while ((m = re.exec(content)) !== null) add(m[1], 'Redux Toolkit', file);
+      }
+      if (content.includes('atom(') || content.includes('atomWithStorage')) {
+        const re = new RegExp(jotai.source, 'g');
+        while ((m = re.exec(content)) !== null) add(m[1], 'Jotai', file);
+      }
+      if (content.includes('makeObservable') || content.includes('makeAutoObservable')) {
+        const re = new RegExp(mobx.source, 'g');
+        while ((m = re.exec(content)) !== null) add(m[1], 'MobX', file);
+      }
+    });
+  }
+  return out;
+}
+
+/** Inventory custom React hooks: exported `useXxx` declarations. */
+function scanHooks(roots, projectDir) {
+  const out = [];
+  const seen = new Set();
+  // export function useThing / export const useThing = / export { useThing }
+  const decl = /\bexport\s+(?:function|const|let)\s+(use[A-Z]\w*)\b/g;
+  const reexport = /\bexport\s*\{\s*([^}]+)\}/g;
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!/\.(ts|tsx|js|jsx|mjs)$/.test(file)) return;
+      if (/\.(test|spec|stories)\./.test(file)) return;
+      const content = readSafe(file);
+      if (!content || !content.includes('use')) return;
+      const rel = relative(projectDir, file);
+      let m;
+      const re1 = new RegExp(decl.source, 'g');
+      while ((m = re1.exec(content)) !== null) {
+        if (seen.has(m[1])) continue;
+        seen.add(m[1]);
+        out.push({ name: m[1], file: rel });
+      }
+      const re2 = new RegExp(reexport.source, 'g');
+      while ((m = re2.exec(content)) !== null) {
+        // For `X as Y`, the EXPORTED name is the alias (Y) — that's what consumers see.
+        for (const id of m[1].split(',').map(s => s.trim().split(/\s+as\s+/).pop()).filter(Boolean)) {
+          if (/^use[A-Z]/.test(id) && !seen.has(id)) {
+            seen.add(id);
+            out.push({ name: id, file: rel });
+          }
+        }
+      }
+    });
+  }
+  return out;
+}
+
+/** React Context inventory: `const XContext = createContext(...)`. */
+function scanContexts(roots, projectDir) {
+  const out = [];
+  const seen = new Set();
+  const re = /\b(?:export\s+)?const\s+(\w+Context)\s*=\s*(?:React\.)?createContext\b/g;
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!/\.(ts|tsx|js|jsx|mjs)$/.test(file)) return;
+      const content = readSafe(file);
+      if (!content || !content.includes('createContext')) return;
+      let m;
+      const r = new RegExp(re.source, 'g');
+      while ((m = r.exec(content)) !== null) {
+        if (seen.has(m[1])) continue;
+        seen.add(m[1]);
+        out.push({ name: m[1], file: relative(projectDir, file) });
+      }
+    });
+  }
+  return out;
+}
+
+/**
+ * i18n: detect translation keys used in code (`t('a.b')`, `i18n.t('a.b')`, `i18nKey="a.b"`)
+ * and the locale files that define them. Reports keys used in code but missing
+ * from locales as a small drift signal the agent can call out.
+ * @returns {{ usedKeys, locales, missing }}
+ */
+function scanI18n(projectDir, roots) {
+  const usedKeys = new Set();
+  const codeRe = /\b(?:i18n\.)?t\(\s*[`'"]([a-zA-Z][\w.-]*\.[\w.-]+)[`'"]/g;
+  const propRe = /\bi18nKey\s*=\s*[`'"]([a-zA-Z][\w.-]*\.[\w.-]+)[`'"]/g;
+
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!/\.(ts|tsx|js|jsx|mjs)$/.test(file)) return;
+      const content = readSafe(file);
+      if (!content || (!content.includes('t(') && !content.includes('i18nKey'))) return;
+      let m;
+      const r1 = new RegExp(codeRe.source, 'g');
+      while ((m = r1.exec(content)) !== null) usedKeys.add(m[1]);
+      const r2 = new RegExp(propRe.source, 'g');
+      while ((m = r2.exec(content)) !== null) usedKeys.add(m[1]);
+    });
+  }
+
+  // Locale files: src/i18n/locales/<lang>.json, src/locales/<lang>.json, public/locales/<lang>/*.json
+  const locales = [];
+  const localeKeys = new Set();
+  const seenLocaleDirs = new Set();
+  const seenLocaleFiles = new Set();
+  const candidates = ['i18n', 'locales', 'src/i18n', 'src/locales', 'public/locales'];
+  for (const base of [resolve(projectDir), ...roots]) {
+    for (const sub of candidates) {
+      const localesDir = resolve(base, sub);
+      if (seenLocaleDirs.has(localesDir) || !existsSync(localesDir)) continue;
+      seenLocaleDirs.add(localesDir);
+      walk(localesDir, (file) => {
+        if (seenLocaleFiles.has(file)) return;
+        seenLocaleFiles.add(file);
+        if (!file.endsWith('.json')) return;
+        let json;
+        try { json = JSON.parse(readSafe(file) || '{}'); } catch { return; }
+        const rel = relative(projectDir, file);
+        const collected = [];
+        const walkObj = (obj, prefix) => {
+          for (const [k, v] of Object.entries(obj || {})) {
+            const path = prefix ? `${prefix}.${k}` : k;
+            if (v && typeof v === 'object' && !Array.isArray(v)) walkObj(v, path);
+            else { localeKeys.add(path); collected.push(path); }
+          }
+        };
+        walkObj(json, '');
+        if (collected.length) locales.push({ file: rel, keys: collected.length });
+      });
+    }
+  }
+
+  const missing = [...usedKeys].filter(k => !localeKeys.has(k)).sort();
+  return { usedKeys: [...usedKeys].sort(), locales, missing };
+}
+
+/**
+ * Frontend → backend wiring: extract API calls (`axios.get('/api/...')`,
+ * `fetch('/api/...')`, generic client methods) so the agent can map screens
+ * to the endpoints they hit.
+ */
+function scanApiCalls(roots, projectDir) {
+  const out = [];
+  const seen = new Set();
+  const add = (method, path, file) => {
+    const key = `${method} ${path}::${file}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ method, path, file: relative(projectDir, file) });
+  };
+  // method-call style: <obj>.get('/api/...'), axios.post('/api/...'), apiClient.users.get('/api/...')
+  const methodCall = /\b(?:axios|api|client|apiClient|http|fetcher)\b[\w.]*\.(get|post|put|delete|patch)\s*\(\s*[`'"](\/[^`'")\s]+)/gi;
+  // bare fetch
+  const fetchCall = /\bfetch\s*\(\s*[`'"](\/[^`'")\s]+)[`'"]\s*(?:,\s*\{[^}]*?method\s*:\s*[`'"](GET|POST|PUT|DELETE|PATCH))?/gi;
+
+  for (const root of roots) {
+    walk(root, (file) => {
+      if (!/\.(ts|tsx|js|jsx|mjs)$/.test(file)) return;
+      const content = readSafe(file);
+      if (!content) return;
+      let m;
+      const a = new RegExp(methodCall.source, 'gi');
+      while ((m = a.exec(content)) !== null) add(m[1].toUpperCase(), m[2], file);
+      const f = new RegExp(fetchCall.source, 'gi');
+      while ((m = f.exec(content)) !== null) add((m[2] || 'GET').toUpperCase(), m[1], file);
+    });
+  }
+  return out;
+}
+
+/**
+ * Scan the frontend surface of a project.
+ * @returns {{ framework, buildTool, stateLib, dataLib, routerType,
+ *             screens: object[], components: object[],
+ *             stores: object[], hooks: object[], contexts: object[], apiCalls: object[] }}
+ */
+export function scanFrontend(projectDir, config = {}) {
+  const stack = detectFrontendStack(projectDir, config);
+  const roots = resolveSourceRoots(projectDir, config);
+
+  let screens = [];
+  let routerType = null;
+  if (stack.framework === 'Next.js') {
+    screens = scanNextScreens(projectDir, config);
+    routerType = 'next';
+  } else {
+    // React Router (and TanStack/React fallbacks use the same JSX/route-object forms)
+    screens = scanReactRouterScreens(roots, projectDir);
+    if (screens.length) routerType = 'react-router';
+    // If nothing matched but a Next layout exists, try Next as a fallback.
+    if (!screens.length) {
+      const nx = scanNextScreens(projectDir, config);
+      if (nx.length) { screens = nx; routerType = 'next'; }
+    }
+  }
+
+  screens.sort((a, b) => a.path.localeCompare(b.path));
+  const components = scanComponents(roots, projectDir).sort((a, b) => a.name.localeCompare(b.name));
+  const stores = scanStores(roots, projectDir).sort((a, b) => a.name.localeCompare(b.name));
+  const hooks = scanHooks(roots, projectDir).sort((a, b) => a.name.localeCompare(b.name));
+  const contexts = scanContexts(roots, projectDir).sort((a, b) => a.name.localeCompare(b.name));
+  const apiCalls = scanApiCalls(roots, projectDir).sort((a, b) =>
+    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 };
+}