docguard-cli 0.25.1 → 0.27.0

package/cli/commands/score.mjs

@@ -10,6 +10,70 @@ import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
 
+/**
+ * Detect whether the project configures a test runner (the "Check 3" of the
+ * testing score). Extracted as an exported seam so it's unit-testable without
+ * the full score pipeline.
+ *
+ * Recognises, in order: standalone config files; pytest config inside
+ * pyproject.toml / tox.ini; node:test via projectTypeConfig or scripts.test;
+ * a `scripts.test` that invokes a known runner; Vitest configured INSIDE
+ * vite.config.* (field report #3 — `vitest/config` import or a `test:` block);
+ * and runner configs in common workspace subdirs.
+ *
+ * @param {string} dir
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function detectTestRunner(dir, config = {}) {
+  const testConfigFiles = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
+  if (testConfigFiles.some((f) => existsSync(resolve(dir, f)))) return true;
+
+  // Python: pytest config usually lives inside pyproject.toml ([tool.pytest.ini_options])
+  // or tox.ini ([pytest]) — not a standalone file.
+  for (const [file, marker] of [['pyproject.toml', /\[tool\.pytest/], ['tox.ini', /\[pytest\]/]]) {
+    const p = resolve(dir, file);
+    if (!existsSync(p)) continue;
+    try { if (marker.test(readFileSync(p, 'utf-8'))) return true; } catch { /* skip */ }
+  }
+
+  // node:test has no config file — recognize it via projectTypeConfig or package.json.
+  const ptc = config.projectTypeConfig || {};
+  if (ptc.testFramework === 'node:test') return true;
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const testScript = pkg.scripts?.test || '';
+      if (testScript.includes('node --test') || testScript.includes('node:test')) return true;
+      // v0.27 (field report #3): a `scripts.test` that runs a known runner IS a
+      // configured test runner, even without a standalone config file.
+      if (/\b(vitest|jest|mocha|ava|playwright|cypress|pytest)\b/.test(testScript)) return true;
+    } catch { /* skip */ }
+  }
+
+  // v0.27 (field report #3): Vitest configured INSIDE vite.config.* rather than a
+  // standalone vitest.config (`vitest/config` import + a `test:` block).
+  for (const f of ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']) {
+    const p = resolve(dir, f);
+    if (!existsSync(p)) continue;
+    try {
+      const src = readFileSync(p, 'utf-8');
+      if (/vitest\/config/.test(src) || /^\s*test\s*:/m.test(src)) return true;
+    } catch { /* skip */ }
+  }
+
+  // Workspace subdirs: a runner config one level down still configures the project.
+  const subConfigs = ['vitest.config.ts', 'vitest.config.js', 'jest.config.ts', 'jest.config.js', 'vite.config.ts'];
+  for (const sub of ['backend', 'frontend', 'server', 'client', 'app', 'web', 'api']) {
+    for (const f of subConfigs) {
+      if (existsSync(resolve(dir, sub, f))) return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * v0.18-P3: map score categories to the validator keys that contribute.
  * One category can roll up multiple validators (e.g. "environment" pulls
@@ -585,38 +649,7 @@ function calcTestingScore(dir, config) {
   else failures.push({ issue: 'TEST-SPEC.md missing', fixCmd: 'docguard fix --doc test-spec' });
 
   // ── Check 3: Test config or built-in runner (15 pts) ──
-  const testConfigFiles = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
-  let hasTestRunner = testConfigFiles.some(f => existsSync(resolve(dir, f)));
-
-  // Python: pytest config usually lives inside pyproject.toml ([tool.pytest.ini_options])
-  // or tox.ini ([pytest]) — not a standalone file. Detect those too, so a uv/pytest
-  // project isn't told to "add a test runner" it already configured (field report, Issue B).
-  if (!hasTestRunner) {
-    for (const [file, marker] of [['pyproject.toml', /\[tool\.pytest/], ['tox.ini', /\[pytest\]/]]) {
-      const p = resolve(dir, file);
-      if (!existsSync(p)) continue;
-      try { if (marker.test(readFileSync(p, 'utf-8'))) { hasTestRunner = true; break; } } catch { /* skip */ }
-    }
-  }
-
-  // node:test has no config file — recognize it via projectTypeConfig or package.json.
-  if (!hasTestRunner) {
-    const ptc = config.projectTypeConfig || {};
-    if (ptc.testFramework === 'node:test') {
-      hasTestRunner = true;
-    } else {
-      const pkgPath = resolve(dir, 'package.json');
-      if (existsSync(pkgPath)) {
-        try {
-          const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-          const testScript = pkg.scripts?.test || '';
-          if (testScript.includes('node --test') || testScript.includes('node:test')) hasTestRunner = true;
-        } catch { /* skip */ }
-      }
-    }
-  }
-
-  if (hasTestRunner) score += 15;
+  if (detectTestRunner(dir, config)) score += 15;
   else failures.push({ issue: 'no test runner config detected (jest/vitest/pytest/node:test)' });
 
   // ── Check 4: CI test step (15 pts) ──

package/cli/config.mjs

@@ -12,11 +12,16 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { c, PROFILES, SEVERITY_LEVELS } from './shared.mjs';
 import { mergeIgnoreFile } from './shared-ignore.mjs';
+import { detectProjectName } from './scanners/project-type.mjs';
 
 export function loadConfig(projectDir) {
   const configPath = resolve(projectDir, '.docguard.json');
   const defaults = {
-    projectName: basename(projectDir),
+    // v0.26 (Bug #4): read the declared name from the root manifest
+    // (pyproject/package.json/Cargo/composer/go.mod) before falling back to the
+    // dir basename — otherwise a git-worktree slug becomes the project name.
+    // An explicit `projectName` in .docguard.json still wins via deepMerge.
+    projectName: detectProjectName(projectDir),
     // Legacy/unversioned fallback ONLY — the value a config is ASSUMED to be
     // when its file has no `version` field. NOT the current schema version
     // (that's CURRENT_SCHEMA_VERSION in shared.mjs, written by `init`). Kept low

package/cli/docguard.mjs

@@ -43,8 +43,10 @@ import { runSetup } from './commands/setup.mjs';
 import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
+import { runFeedback } from './commands/feedback.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
+import { runAgent } from './commands/agent.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -83,7 +85,9 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}diagnose${c.reset}   AI orchestrator — guard → emit fix prompts in one command
   ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
-  ${c.green}explain${c.reset}    Explain a validator key or warning text
+  ${c.green}agent${c.reset}      One-shot agent task graph — ordered tasks, pre-filled code-truth, per-task verify (${c.cyan}--format json${c.reset})
+  ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
+  ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
@@ -192,6 +196,15 @@ const COMMAND_HELP = {
     ],
     examples: ['docguard generate', 'docguard generate --plan', 'docguard generate --plan --write', 'docguard generate --plan --format json'],
   },
+  agent: {
+    summary: 'One-shot agent task graph: ordered, dependency-aware, with pre-filled code-truth + per-task verify.',
+    usage: 'docguard agent [--profile <name>] [--format json]',
+    flags: [
+      ['--format json', 'Machine-readable task graph (the agent-executable artifact)'],
+      ['--profile <name>', 'Preview a profile (cli/library/standard/…) without running init first'],
+    ],
+    examples: ['docguard agent', 'docguard agent --format json', 'docguard agent --profile cli --format json'],
+  },
   guard: {
     summary: 'Validate code against canonical docs (all validators).',
     usage: 'docguard guard [--format json] [--changed-only] [--fail-on-warning]',
@@ -268,6 +281,12 @@ const COMMAND_HELP = {
     flags: [['--diff', 'Drill into drift between memory and code']],
     examples: ['docguard memory', 'docguard memory --diff'],
   },
+  feedback: {
+    summary: 'Report likely false positives back to DocGuard. Collects the low-confidence findings of a guard run, saves a full local record under .docguard/feedback/, and prints a one-click, prefilled, redacted GitHub issue URL (zero typing, no source code or secret values).',
+    usage: 'docguard feedback [--format json]',
+    flags: [['--format json', 'Machine-readable list of reportable findings + URLs']],
+    examples: ['docguard feedback'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -474,16 +493,42 @@ async function main() {
   // .agent/.specify writes, which were a surprising side effect of a bare
   // `generate --plan` (and were already suppressed for `--plan --write`).
   const jsonMode = flags.format === 'json';
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan;
+  // `agent` emits a machine task graph (JSON by default) — it must be banner-
+  // free and side-effect-free like the other read-only commands.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent';
 
   if (!headless) printBanner();
 
   const config = loadConfig(projectDir);
 
+  // Commands that only READ and REPORT — they must never mutate the working
+  // tree. Scaffolding (ensureSkills → .agent/.specify, spawning `specify`)
+  // belongs to setup/init/generate and the `init --with` family, where the
+  // user is establishing or expanding their setup, not auditing it.
+  //
+  // v0.26 (field report Bug #3): a bare `docguard guard` used to run
+  // ensureSkills → auto-init Spec Kit → spawn `specify` and write ~9 files into
+  // the tree BEFORE printing results. Surprising for a *validate* command, and
+  // fatal for a read-only CI audit or a clean-tree precondition check. These
+  // commands are now exempt regardless of flags. (`audit` is the guard alias;
+  // `diff`/`impact` only read; `demo` runs against a throwaway fixture.)
+  const READ_ONLY_COMMANDS = new Set([
+    'guard', 'audit', 'score', 'diff', 'impact',
+    'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent',
+    // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
+    // skills or touch source, so it's gated out of ensureSkills like the rest.
+    'feedback',
+  ]);
+
   // Silent auto-check: install skills/commands if missing. Skip entirely in
-  // headless modes where the user wants deterministic, parseable output and
-  // doesn't expect side effects on their AI-agent skill directories.
-  if (command !== 'setup' && command !== 'init' && !headless) {
+  // headless modes (deterministic, parseable output; no side effects expected)
+  // and for read-only commands (see above).
+  if (
+    command !== 'setup' &&
+    command !== 'init' &&
+    !READ_ONLY_COMMANDS.has(command) &&
+    !headless
+  ) {
     ensureSkills(projectDir, flags);
   }
 
@@ -566,6 +611,11 @@ async function main() {
     case 'generate':
       runGenerate(projectDir, config, flags);
       break;
+    case 'agent':
+      // v0.26 (field report §2): one-shot, dependency-ordered task graph with
+      // pre-filled code-truth + per-task verify. Read-only; JSON by default.
+      runAgent(projectDir, config, flags);
+      break;
     case 'hooks':
       await runInit(projectDir, config, { ...flags, with: ['hooks'], skipPrompts: true });
       break;
@@ -607,6 +657,12 @@ async function main() {
     case 'explain':
       runExplain(projectDir, config, flags);
       break;
+    case 'feedback':
+      // v0.27 (field report #3 / LLM feedback loop): collect low-confidence
+      // findings (likely false positives) → local record + 1-click prefilled,
+      // redacted, capped GitHub issue URL. Opt-in; nothing filed automatically.
+      runFeedback(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;

package/cli/findings.mjs

@@ -0,0 +1,194 @@
+/**
+ * Findings — the structured, LLM-addressable result unit (v0.27).
+ *
+ * Background (LLM field report #3): DocGuard's whole job is to tell an agent
+ * what to do NEXT. A free-text `errors`/`warnings` string can't carry a stable
+ * code (for `explain <CODE>` + inline suppression), a confidence (the signal
+ * the false-positive feedback loop runs on), or a machine-readable suggested
+ * action. A Finding carries all three.
+ *
+ * The migration is INCREMENTAL and BACKWARD-COMPATIBLE. A validator that opts in
+ * builds `Finding[]` and returns `resultFromFindings(...)`, which still emits the
+ * exact `{ errors, warnings, passed, total }` shape every existing consumer
+ * (guard counts + exit code, diagnose, score, ci, `--format json`) already reads
+ * — PLUS a `findings` array that guard renders richly (each issue gets its
+ * `→ suggestion`). Validators that haven't migrated keep returning their
+ * hand-built results and render exactly as before. Nothing regresses.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ *
+ * @typedef {Object} Suggestion
+ * @property {'fix'|'suppress'|'review'|'report'} kind
+ * @property {string}  text             One concise line: what to do next.
+ * @property {string} [command]         Optional CLI/skill command to run.
+ * @property {string} [pragma]          Optional inline suppression snippet.
+ *
+ * @typedef {Object} Finding
+ * @property {string}      code          Stable code, e.g. 'SEC001' (see CODES).
+ * @property {string}      validator     Owning validator key.
+ * @property {'error'|'warn'} severity
+ * @property {'high'|'low'} confidence   'low' = candidate false positive.
+ * @property {string}      message       Concise, NO ansi colour.
+ * @property {string|null} location      'path:line' or 'path'.
+ * @property {Suggestion|null} suggestion
+ * @property {boolean}     reportable    Surface in `docguard feedback`.
+ * @property {string|null} redactedContext  Safe-to-share context for a report.
+ */
+
+/**
+ * Stable finding-code registry. `docguard explain <CODE>` reads this, and
+ * inline `// docguard:ignore <CODE>` keys off it. Keep codes append-only — a
+ * published code is a public surface we don't renumber.
+ */
+export const CODES = {
+  SEC001: {
+    validator: 'security',
+    title: 'Hardcoded password',
+    help: 'A `password`/`passwd`/`pwd` assignment with a quoted literal value (8+ chars). If the value is natural-language UI copy or a validation message — not a credential — this is a false positive: DocGuard now flags those low-confidence, but you can suppress inline.',
+    suppress: '// docguard:ignore SEC001 — UI copy, not a credential',
+  },
+  SEC002: {
+    validator: 'security',
+    title: 'Hardcoded API key',
+    help: 'An `api_key`/`apikey` assignment with a quoted literal value (16+ chars). Move it to an environment variable and read it via `process.env`.',
+    suppress: '// docguard:ignore SEC002 — sample value in fixture',
+  },
+  SEC003: {
+    validator: 'security',
+    title: 'Hardcoded secret key',
+    help: 'A `secret_key`/`secretkey` assignment with a quoted literal value (16+ chars). Move it to an environment variable.',
+    suppress: '// docguard:ignore SEC003 — reason',
+  },
+  SEC004: {
+    validator: 'security',
+    title: 'Hardcoded access token',
+    help: 'An `access_token`/`accesstoken` assignment with a quoted literal value (16+ chars). Move it to an environment variable.',
+    suppress: '// docguard:ignore SEC004 — reason',
+  },
+  SEC005: {
+    validator: 'security',
+    title: 'AWS Access Key ID',
+    help: 'A string matching the AWS Access Key ID format (AKIA…). Rotate it immediately if real, and move credentials to the AWS credential chain / environment.',
+    suppress: '// docguard:ignore SEC005 — documented example key',
+  },
+  SEC006: {
+    validator: 'security',
+    title: 'API secret key (Stripe/OpenAI pattern)',
+    help: 'A string matching a live/test secret-key format (sk-…, sk_live_…). Rotate it if real and move it to an environment variable.',
+    suppress: '// docguard:ignore SEC006 — reason',
+  },
+  SEC010: {
+    validator: 'security',
+    title: '.env not in .gitignore',
+    help: 'No `.env` entry was found in .gitignore, so a local `.env` could be committed. Add `.env` (and `.env.local`) to .gitignore.',
+    suppress: null,
+  },
+  SEC011: {
+    validator: 'security',
+    title: 'No source files scanned for secrets',
+    help: 'The secret scan matched zero source files — usually a too-broad ignore config or a wrong sourceRoot. A scan that checks nothing is a dangerous false ✅.',
+    suppress: null,
+  },
+};
+
+/**
+ * Build a Finding with sane defaults. `reportable` defaults to true for
+ * low-confidence findings — low confidence IS the feedback signal.
+ *
+ * @param {Partial<Finding>} f
+ * @returns {Finding}
+ */
+export function mkFinding(f) {
+  const severity = f.severity === 'error' ? 'error' : 'warn';
+  const confidence = f.confidence === 'low' ? 'low' : 'high';
+  return {
+    code: f.code || null,
+    validator: f.validator || null,
+    severity,
+    confidence,
+    message: f.message || '',
+    location: f.location || null,
+    suggestion: f.suggestion || null,
+    reportable: f.reportable === true || confidence === 'low',
+    redactedContext: f.redactedContext || null,
+  };
+}
+
+/**
+ * Derive the legacy `{ errors, warnings, passed, total }` result from a list of
+ * findings, keeping `findings` attached for the rich renderer. ONE source of
+ * truth — the strings guard counts and the findings guard renders can never
+ * disagree because they're computed from the same array.
+ *
+ * @param {Finding[]} findings
+ * @param {{passed?:number, total?:number, applicable?:boolean}} [opts]
+ */
+export function resultFromFindings(findings, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  for (const f of findings) {
+    if (f.severity === 'error') errors.push(f.message);
+    else warnings.push(f.message);
+  }
+  const res = {
+    errors,
+    warnings,
+    passed: opts.passed || 0,
+    total: opts.total != null ? opts.total : 0,
+    findings,
+  };
+  if (opts.applicable !== undefined) res.applicable = opts.applicable;
+  return res;
+}
+
+/**
+ * Does an inline `docguard:ignore` pragma in `text` suppress finding `code`?
+ *
+ * Accepted forms (mirrors the ergonomics of eslint-disable / ruff `# noqa`):
+ *   docguard:ignore                 → suppresses ANY code on the line
+ *   docguard:ignore SEC001          → suppresses exactly SEC001
+ *   docguard:ignore SEC001,DQ002    → comma list
+ *   docguard:ignore SEC*            → prefix wildcard
+ *   docguard:ignore all             → suppresses any code
+ *   docguard:ignore-secret          → convenience alias for any SEC* code
+ *
+ * @param {string} text
+ * @param {string} code
+ * @returns {boolean}
+ */
+export function suppressesCode(text, code) {
+  if (!text || !code) return false;
+  const m = text.match(/docguard:ignore(-secret)?\b[ \t]*([A-Za-z0-9_,*-]+)?/i);
+  if (!m) return false;
+  if (m[1]) return /^SEC/i.test(code);            // ignore-secret alias
+  const arg = (m[2] || '').trim();
+  if (!arg) return true;                           // bare ignore → any code
+  return arg.split(',').map((s) => s.trim()).some((tok) => {
+    if (!tok) return false;
+    if (tok.toLowerCase() === 'all') return true;
+    if (tok.endsWith('*')) return code.toUpperCase().startsWith(tok.slice(0, -1).toUpperCase());
+    return tok.toUpperCase() === code.toUpperCase();
+  });
+}
+
+/**
+ * Source-line suppression: an ignore pragma counts if it's on the flagged line
+ * OR the line directly above it (so a comment can sit above the offending
+ * statement, the common style for non-trailing-comment languages).
+ */
+export function lineSuppresses(code, line, prevLine = '') {
+  return suppressesCode(line, code) || suppressesCode(prevLine, code);
+}
+
+/**
+ * Flatten a one-line, colour-free rendering of a suggestion — used by JSON
+ * consumers, diagnose, and the feedback body. Guard does its own coloured
+ * rendering and does not use this.
+ */
+export function suggestionLine(s) {
+  if (!s) return '';
+  let out = s.text || '';
+  if (s.command) out += `  →  ${s.command}`;
+  else if (s.pragma) out += `  →  ${s.pragma}`;
+  return out;
+}

package/cli/scanners/inventory.mjs

@@ -0,0 +1,140 @@
+/**
+ * Inventory scanners — code-truth the generator PRE-FILLS instead of leaving
+ * empty placeholders.
+ *
+ * Field report §2/§5: `generate` markets "reverse-engineer docs from code" but
+ * shipped empty templates, so the agent hand-greps the structure that was right
+ * there in the code. These two extractors populate the `source:"code"` sections
+ * so the agent is left with only the genuine prose (the *why*):
+ *   - scanComponents:    top-level source modules → ARCHITECTURE Component Map
+ *   - scanTestInventory: test files + per-file case counts → TEST-SPEC inventory
+ *
+ * Language-agnostic, best-effort, zero NPM deps.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve, join, relative, extname } from 'node:path';
+import { resolveSourceRoots, readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, isNonProductDir } from '../shared-ignore.mjs';
+
+const CODE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.rb', '.php', '.java', '.kt']);
+const toPosix = (p) => p.split(/[\\/]/).join('/');
+
+// ── Component map ─────────────────────────────────────────────────────────────
+
+// Descend through single-package wrappers (src/ → src/<pkg>/) so we list the
+// REAL modules, not just the wrapper folder. A wrapper is a dir whose only
+// non-ignored child is another dir (e.g. a Python `src/<pkg>/` layout).
+function componentRoot(root, config) {
+  let cur = root;
+  for (let depth = 0; depth < 3; depth++) {
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { break; }
+    const dirs = entries.filter(e => e.isDirectory() && !e.name.startsWith('.')
+      && !IGNORE_DIRS.has(e.name) && !isNonProductDir(e.name, config));
+    const codeFiles = entries.filter(e => e.isFile() && CODE_EXT.has(extname(e.name))
+      && !/^(index|main|mod|lib|__init__|__main__)\./.test(e.name));
+    if (dirs.length === 1 && codeFiles.length === 0) { cur = join(cur, dirs[0].name); continue; }
+    break;
+  }
+  return cur;
+}
+
+/**
+ * Top-level source modules under the project's (de-wrapped) source root(s).
+ * Each is a directory (a module) or a significant source file directly under
+ * the root. Non-product dirs (tests/fixtures/examples) and barrel/entry files
+ * are excluded. Capped to keep the table readable.
+ * @returns {Array<{ name: string, kind: 'module'|'file', path: string }>}
+ */
+export function scanComponents(projectDir, config = {}, limit = 30) {
+  const out = [];
+  const seen = new Set();
+  for (const root of resolveSourceRoots(projectDir, config)) {
+    const croot = componentRoot(root, config);
+    let entries;
+    try { entries = readdirSync(croot, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      let kind;
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name) || isNonProductDir(e.name, config)) continue;
+        kind = 'module';
+      } else if (e.isFile() && CODE_EXT.has(extname(e.name))) {
+        if (/^(index|__init__)\./.test(e.name)) continue; // barrels/entry-init aren't components
+        kind = 'file';
+      } else continue;
+      const rel = toPosix(relative(projectDir, join(croot, e.name)));
+      if (seen.has(rel)) continue;
+      seen.add(rel);
+      out.push({ name: e.name, kind, path: rel });
+    }
+  }
+  out.sort((a, b) => (a.kind === b.kind ? a.path.localeCompare(b.path) : (a.kind === 'module' ? -1 : 1)));
+  return out.slice(0, limit);
+}
+
+// ── Test inventory ────────────────────────────────────────────────────────────
+
+// Test FILE conventions across ecosystems: JS *.test/*.spec, Python test_*.py /
+// *_test.py, Go *_test.go, Ruby *_spec.rb / *_test.rb.
+const TEST_FILE_RE = /(?:\.(?:test|spec)\.[cm]?[jt]sx?|(?:^|\/)test_[^/]*\.py|_test\.(?:py|go)|_spec\.rb|(?:^|\/)[^/]*_test\.rb)$/i;
+// Fixture/mock subdirs that sit INSIDE a test dir but aren't themselves tests.
+const FIXTURE_DIRS = new Set(['fixtures', '__fixtures__', 'testdata', 'test-fixtures', 'testfixtures', 'mocks', '__mocks__', 'snapshots', '__snapshots__']);
+const TEST_DIRS = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+
+function countCases(content, ext) {
+  let re;
+  if (['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) re = /\b(?:it|test)\s*\(/g;
+  else if (ext === '.py') re = /^[ \t]*(?:async[ \t]+)?def[ \t]+test_/gm;
+  else if (ext === '.go') re = /^[ \t]*func[ \t]+Test[A-Z]/gm;
+  else if (ext === '.rs') re = /#\[(?:test|tokio::test)\]/g;
+  else if (ext === '.rb') re = /^[ \t]*(?:it|test|specify)\b/gm;
+  else return 0;
+  let n = 0;
+  while (re.exec(content) !== null) n++;
+  return n;
+}
+
+function walkTestFiles(dir, projectDir, acc) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || IGNORE_DIRS.has(e.name)) continue;
+    if (e.isDirectory()) {
+      if (FIXTURE_DIRS.has(e.name)) continue; // fixtures/mocks inside a test dir aren't tests
+      walkTestFiles(join(dir, e.name), projectDir, acc);
+    } else if (e.isFile() && CODE_EXT.has(extname(e.name))) {
+      const rel = toPosix(relative(projectDir, join(dir, e.name)));
+      if (TEST_FILE_RE.test(rel)) acc.add(rel);
+    }
+  }
+}
+
+/**
+ * Test files + per-file case counts. Walks the conventional test dirs (tests/,
+ * test/, __tests__, spec/, e2e/) plus each source root (co-located tests),
+ * skipping fixture/mock subdirs. Case counts are per-language (it()/test(),
+ * `def test_`, `func Test`, `#[test]`, …).
+ * @returns {{ files: Array<{file:string,cases:number}>, totalCases:number, totalFiles:number }}
+ */
+export function scanTestInventory(projectDir, config = {}) {
+  const root = resolve(projectDir);
+  const acc = new Set();
+  for (const td of TEST_DIRS) {
+    const d = join(root, td);
+    if (existsSync(d)) walkTestFiles(d, root, acc);
+  }
+  for (const sr of resolveSourceRoots(projectDir, config)) walkTestFiles(sr, root, acc);
+
+  const files = [];
+  let totalCases = 0;
+  for (const rel of acc) {
+    const content = readScannable(join(root, rel));
+    const cases = content === null ? 0 : countCases(content, extname(rel));
+    files.push({ file: rel, cases });
+    totalCases += cases;
+  }
+  files.sort((a, b) => b.cases - a.cases || a.file.localeCompare(b.file));
+  return { files, totalCases, totalFiles: files.length };
+}