@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/commands/analyzer.js

@@ -1,3 +1,4 @@
+import { Option } from "commander";
 import { intro, outro, select, isCancel } from "@clack/prompts";
 import ansis from "ansis";
 import { promises as fs } from "fs";
@@ -8,7 +9,10 @@ import { readSession, writeSession, writeStatus, readIndexMeta } from "../analyz
 import { CLIError, ModelNotFoundError, ErrorCategory, categorizeError } from "../utils/errors.js";
 import { findProjectRoot } from "../utils/project-paths.js";
 import { performDiscover } from "./discover-logic.js";
+import { analyzerHomepage, getAnalyzerBackend, resolveAnalyzerName, splitVerifyLayers } from "../analyzers/active-analyzer.js";
+import { finishIndexJob, INDEX_JOB_TIMEOUT_MS, markIndexJobPhase } from "../analyzers/index-job.js";
 import { formatVerifyReport } from "../export/verify-formatters.js";
+import { Model } from "../core/model.js";
 function analyzerCommands(program) {
   const analyzer = program.command("analyzer").description("Manage analyzer discovery and indexing");
   analyzer.command("discover").description("Discover and select an analyzer").option("--json", "Output as JSON").option("--reselect", "Force re-selection even if analyzer already selected").addHelpText("after", `
@@ -131,11 +135,16 @@ Examples:
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND, ["Check the analyzer name with `dr analyzer discover`"]);
       const actualProjectRoot = await findProjectRoot();
       let status;
-      if (actualProjectRoot ? status = await backend.status(actualProjectRoot) : status = {
-        detected: await backend.detect(),
-        indexed: !1,
-        fresh: !1
-      }, jsonMode) {
+      if (actualProjectRoot) {
+        const model = await Model.load(actualProjectRoot);
+        status = await backend.status(actualProjectRoot, { codebaseRoot: model.codebaseRoot });
+      } else
+        status = {
+          detected: await backend.detect(),
+          indexed: !1,
+          fresh: !1
+        };
+      if (jsonMode) {
         console.log(JSON.stringify(status, null, 2)), actualProjectRoot && await writeStatus(status, actualProjectRoot, analyzerName);
         return;
       }
@@ -146,39 +155,43 @@ Examples:
       const category = categorizeError(error), cliError = new CLIError(error instanceof Error ? error.message : String(error), category);
       throw error instanceof Error && (cliError.cause = error), cliError;
     }
-  }), analyzer.command("index").description("Index the current project with the analyzer").option("--name <n>", "Analyzer name (defaults to active from session.json)").option("--force", "Force re-indexing even if index is fresh").addHelpText("after", `
+  }), analyzer.command("index").description("Index the current project with the analyzer").option("--name <n>", "Analyzer name (defaults to active from session.json)").option("--force", "Force re-indexing even if index is fresh").addOption(new Option("--job <id>", "Record the run in .dr/analyzers/index-job.json (set by codebase_index)").hideHelp()).addHelpText("after", `
 Examples:
   $ dr analyzer index              # Index with active analyzer
   $ dr analyzer index --force      # Force re-index
-  $ dr analyzer index --name cbm   # Index with specific analyzer`).action(async (options) => {
+  $ dr analyzer index --name cbm   # Index with specific analyzer
+
+With codebase-memory-mcp (cbm), each run first adds /documentation-robotics/ and /.dr/ to a
+.cbmignore at the codebase root (creating it if needed, keeping your lines, and leaving alone a
+folder you negate with !), so DR's model, changesets and analyzer state stay out of the index.
+Commit .cbmignore with the code.`).action(async (options) => {
+    const jobId = options.job;
+    let projectRoot = null;
     try {
-      const projectRoot = await findProjectRoot();
-      if (!projectRoot)
+      if (projectRoot = await findProjectRoot(), !projectRoot)
         throw new ModelNotFoundError();
-      let analyzerName = options.name;
-      if (!analyzerName) {
-        const session = await readSession(projectRoot);
-        if (!session)
-          throw new CLIError("No analyzer selected. Run `dr analyzer discover` first.", ErrorCategory.USER);
-        analyzerName = session.active_analyzer;
-      }
-      const registry = AnalyzerRegistry.getInstance();
-      await registry.initialize();
-      const backend = await registry.getAnalyzer(analyzerName);
-      if (!backend)
-        throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND, ["Check the analyzer name with `dr analyzer discover`"]);
+      const analyzerName = await resolveAnalyzerName(projectRoot, options.name), backend = await getAnalyzerBackend(analyzerName, [
+        "Check the analyzer name with `dr analyzer discover`"
+      ]);
       if (!(await backend.detect()).installed) {
-        const homepageUrl = (await MappingLoader.load(analyzerName)).getAnalyzerMetadata()?.homepage || "https://github.com/search?q=codebase-memory";
+        const homepageUrl = await analyzerHomepage(analyzerName);
         throw new CLIError(`Analyzer not installed: ${analyzerName}`, ErrorCategory.USER, [
           "Run `dr analyzer discover` to find available analyzers and installation instructions",
           `Visit: ${homepageUrl}`
         ]);
       }
-      console.log(`Indexing project with ${analyzerName}...`);
-      const result = await backend.index(projectRoot, { force: options.force });
-      console.log(ansis.green("\u2713 Indexing complete")), console.log(`  Nodes: ${result.node_count}`), console.log(`  Edges: ${result.edge_count}`), console.log(`  Git HEAD: ${result.git_head}`);
+      const model = await Model.load(projectRoot);
+      jobId && await markIndexJobPhase(projectRoot, jobId, "indexing"), console.log(`Indexing project with ${analyzerName}...`);
+      const result = await backend.index(projectRoot, {
+        force: options.force,
+        codebaseRoot: model.codebaseRoot,
+        // A background run has no caller waiting on it: give a large codebase the time it needs.
+        ...jobId ? { timeoutMs: INDEX_JOB_TIMEOUT_MS } : {}
+      });
+      jobId && await finishIndexJob(projectRoot, jobId, { result }), console.log(ansis.green("\u2713 Indexing complete")), console.log(`  Nodes: ${result.node_count}`), console.log(`  Edges: ${result.edge_count}`), console.log(`  Git HEAD: ${result.git_head}`);
     } catch (error) {
-      if (error instanceof CLIError || error instanceof ModelNotFoundError)
+      if (jobId && await finishIndexJob(projectRoot ?? process.cwd(), jobId, { error: describeJobError(error) }).catch(() => {
+      }), error instanceof CLIError || error instanceof ModelNotFoundError)
         throw error;
       const cliError = new CLIError(error instanceof Error ? error.message : String(error), ErrorCategory.SYSTEM);
       throw error instanceof Error && (cliError.cause = error), cliError;
@@ -205,9 +218,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
-      if (!(await backend.status(projectRoot)).indexed)
+      const model = await Model.load(projectRoot);
+      if (!(await backend.status(projectRoot, { codebaseRoot: model.codebaseRoot })).indexed)
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` to index the project first"]);
-      const endpoints = await backend.endpoints(projectRoot);
+      const endpoints = await backend.endpoints(projectRoot, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(endpoints, null, 2));
         return;
@@ -252,9 +266,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      let services = await backend.services(projectRoot);
+      let services = await backend.services(projectRoot, { codebaseRoot: model.codebaseRoot });
       if (options.layer && (services = services.filter((s) => s.suggested_layer === options.layer)), jsonMode) {
         console.log(JSON.stringify(services, null, 2));
         return;
@@ -298,9 +313,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const datastores = await backend.datastores(projectRoot);
+      const datastores = await backend.datastores(projectRoot, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(datastores, null, 2));
         return;
@@ -348,9 +364,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const callers = await backend.callers(projectRoot, qualifiedName, depth);
+      const callers = await backend.callers(projectRoot, qualifiedName, depth, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(callers, null, 2));
         return;
@@ -394,9 +411,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const callees = await backend.callees(projectRoot, qualifiedName, depth);
+      const callees = await backend.callees(projectRoot, qualifiedName, depth, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(callees, null, 2));
         return;
@@ -441,9 +459,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const result = await backend.query(projectRoot, cypher);
+      const result = await backend.query(projectRoot, cypher, { codebaseRoot: model.codebaseRoot });
       options.json, console.log(JSON.stringify(result, null, 2));
     } catch (error) {
       if (error instanceof CLIError || error instanceof ModelNotFoundError)
@@ -476,11 +495,61 @@ Examples:
       const projectRoot = await findProjectRoot();
       if (!projectRoot)
         throw new ModelNotFoundError();
-      const requestedLayers = options.layer || ["api"], apiLayers = requestedLayers.filter((layer) => layer === "api"), nonApiLayers = requestedLayers.filter((layer) => layer !== "api");
+      const { verifiable: apiLayers, unsupported: nonApiLayers } = splitVerifyLayers(options.layer);
       for (const layer of nonApiLayers)
         console.log(ansis.dim(`No verification available for layer '${layer}'`));
       if (apiLayers.length === 0)
         return;
+      const analyzerName = await resolveAnalyzerName(projectRoot, options.name), backend = await getAnalyzerBackend(analyzerName), model = await Model.load(projectRoot);
+      if (!await readIndexMeta(projectRoot, analyzerName))
+        throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
+      const report = await backend.verify(projectRoot, {
+        layers: apiLayers,
+        changesetAware: !0,
+        codebaseRoot: model.codebaseRoot
+      }), formatted = formatVerifyReport(report, { format });
+      if (options.output) {
+        const outputPath = path.resolve(options.output);
+        await fs.writeFile(outputPath, formatted, "utf-8"), console.log(ansis.green(`\u2713 Report written to ${outputPath}`));
+        return;
+      }
+      console.log(formatted);
+    } catch (error) {
+      if (error instanceof CLIError || error instanceof ModelNotFoundError)
+        throw error;
+      const cliError = new CLIError(error instanceof Error ? error.message : String(error), categorizeError(error));
+      throw error instanceof Error && (cliError.cause = error), cliError;
+    }
+  }), analyzer.command("classify").description("Classify the indexed project's symbols into model layers and types (Tier 0: rules only)").option("--name <n>", "Analyzer name (defaults to active from session.json)").option("--tier0-only", "Apply only the analyzer's Tier-0 rules: no model calls, no network (required for now)").option("--label <labels>", "Comma-separated analyzer labels to classify (default: Class, Interface, Function, Method, Module, Route and every label a rule names)").option("--file <glob>", "Only symbols in files matching this glob").option("--exclude <regex>", "Also leave out files matching this regular expression (build and vendored paths always are)").option("--limit <n>", "Stop after this many symbols").option("--cards", "Include each symbol's full card (source and graph neighbourhood) in JSON output").option("--output <file>", "Write the JSON report to a file").option("--json", "Output as JSON").addHelpText("after", `
+Tier 0 is the first step of the classification cascade (docs/analyzers/CASCADE_DESIGN.md):
+the analyzer's rules decide a symbol's layer and type, reject it as not a model element,
+or narrow its choices for a later tier. Symbols no rule covers are reported as undecided.
+Nothing is written to the model.
+
+Examples:
+  $ dr analyzer classify --tier0-only
+  $ dr analyzer classify --tier0-only --json > tier0.json
+  $ dr analyzer classify --tier0-only --label Class,Method --file "src/main/**"
+  $ dr analyzer classify --tier0-only --cards --output tier0-cards.json`).action(async (options) => {
+    const jsonMode = options.json ?? program.opts().json;
+    try {
+      if (!options.tier0Only)
+        throw new CLIError("Only Tier-0 classification is available so far: pass --tier0-only", ErrorCategory.USER, ["Model-backed classification (Tier 1) needs the per-project opt-in and is not built yet"]);
+      let exclude;
+      if (options.exclude !== void 0)
+        try {
+          exclude = new RegExp(String(options.exclude));
+        } catch (e) {
+          throw new CLIError(`Invalid --exclude regular expression: ${e instanceof Error ? e.message : String(e)}`, ErrorCategory.USER);
+        }
+      let limit;
+      if (options.limit !== void 0 && (limit = Number(options.limit), !Number.isInteger(limit) || limit < 1))
+        throw new CLIError(`--limit must be a positive integer, got '${options.limit}'`, ErrorCategory.USER);
+      const labels = options.label ? String(options.label).split(",").map((l) => l.trim()).filter(Boolean) : void 0;
+      options.cards && !jsonMode && !options.output && console.error(ansis.yellow("--cards only affects JSON output: add --json or --output <file>"));
+      const projectRoot = await findProjectRoot();
+      if (!projectRoot)
+        throw new ModelNotFoundError();
       let analyzerName = options.name;
       if (!analyzerName) {
         const session = await readSession(projectRoot);
@@ -493,18 +562,46 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      if (!backend.classify)
+        throw new CLIError(`The ${analyzerName} analyzer does not support classification`, ErrorCategory.USER);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const report = await backend.verify(projectRoot, {
-        layers: apiLayers,
-        changesetAware: !0
-      }), formatted = formatVerifyReport(report, { format });
+      const model = await Model.load(projectRoot), showProgress = !jsonMode && !options.output && process.stderr.isTTY, report = await backend.classify(projectRoot, {
+        codebaseRoot: model.codebaseRoot,
+        labels,
+        filePattern: options.file,
+        exclude,
+        limit,
+        includeCards: !!options.cards,
+        onProgress: showProgress ? (done, total) => {
+          (done % 50 === 0 || done === total) && process.stderr.write(`\r  ${done}/${total} symbols`), done === total && process.stderr.write(`
+`);
+        } : void 0
+      });
       if (options.output) {
         const outputPath = path.resolve(options.output);
-        await fs.writeFile(outputPath, formatted, "utf-8"), console.log(ansis.green(`\u2713 Report written to ${outputPath}`));
+        await fs.writeFile(outputPath, JSON.stringify(report, null, 2) + `
+`, "utf-8"), jsonMode || console.log(ansis.green(`\u2713 Report written to ${outputPath}`));
+      }
+      if (jsonMode) {
+        console.log(JSON.stringify(report, null, 2));
         return;
       }
-      console.log(formatted);
+      const { summary } = report, pct = (n) => summary.cards ? `${(100 * n / summary.cards).toFixed(0)}%` : "0%";
+      console.log(""), console.log(ansis.bold(`Tier-0 classification: ${summary.cards} symbols, ${report.rules} rules`)), console.log(ansis.dim("\u2500".repeat(60))), console.log(`  ${ansis.green("decided")}    ${String(summary.decided).padStart(6)}  ${pct(summary.decided)}`), console.log(`  ${ansis.yellow("rejected")}   ${String(summary.rejected).padStart(6)}  ${pct(summary.rejected)}  (not model elements)`), console.log(`  ${ansis.cyan("narrowed")}   ${String(summary.narrowed).padStart(6)}  ${pct(summary.narrowed)}  (choices restricted for Tier 1)`), console.log(`  ${ansis.dim("undecided")}  ${String(summary.undecided).padStart(6)}  ${pct(summary.undecided)}`), summary.no_source && console.log(ansis.yellow(`  ${summary.no_source} symbol(s) had no source, so rules that read the declaration could not apply`));
+      const targets = Object.entries(summary.by_target).sort((a, b) => b[1] - a[1]);
+      if (targets.length) {
+        console.log(""), console.log(ansis.bold("Decided, by type:"));
+        for (const [target, n] of targets)
+          console.log(`  ${target.padEnd(40)} ${String(n).padStart(6)}`);
+      }
+      const rules = Object.entries(summary.by_rule).sort((a, b) => b[1] - a[1]);
+      if (rules.length) {
+        console.log(""), console.log(ansis.bold("Matches, by rule:"));
+        for (const [rule, n] of rules)
+          console.log(`  ${rule.padEnd(40)} ${String(n).padStart(6)}`);
+      }
+      console.log(ansis.dim("\u2500".repeat(60))), console.log(ansis.dim("Per-symbol outcomes: --json or --output <file>")), console.log("");
     } catch (error) {
       if (error instanceof CLIError || error instanceof ModelNotFoundError)
         throw error;
@@ -513,6 +610,12 @@ Examples:
     }
   });
 }
+function describeJobError(error) {
+  const message = error instanceof Error ? error.message : String(error), suggestions = error instanceof CLIError ? error.suggestions ?? [] : [];
+  return suggestions.length > 0 ? `${message}
+${suggestions.map((s) => `- ${s}`).join(`
+`)}` : message;
+}
 export {
   analyzerCommands
 };