@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/analyzers/cbm-analyzer.js

@@ -1,17 +1,24 @@
 import { spawnSync } from "child_process";
 import * as path from "path";
-import { readFile } from "fs/promises";
+import { readFile, writeFile } from "fs/promises";
 import { CLIError, ErrorCategory, handleWarning } from "../utils/errors.js";
 import { VALID_HTTP_METHODS } from "./types.js";
 import { StdioClient } from "./stdio-client.js";
 import { readIndexMeta, writeIndexMeta } from "./session-state.js";
 import { getCliVersion } from "./version.js";
 import { StagingAreaManager } from "../core/staging-area.js";
+import { DR_OWN_DIRS } from "./code-changes.js";
 import { VerifyEngine } from "./verify-engine.js";
 import { clampDepth, shapeCallGraphNode, determineEdgeType } from "./call-graph-utils.js";
 import { evaluateHeuristic, capConfidence, matchPattern, getKnownHeuristicNames } from "./heuristic-utils.js";
 import { toKebabCase } from "../utils/id-generator.js";
-const SOURCE_CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte|py|go|rb|java|rs|php|cs|cpp|c|h|kt|swift|sh|bash)$/i;
+import { CbmTools, CbmToolError, ROUTE_HANDLERS_QUERY, attachRouteHandlers, nodeColumns, nodesFromQuery, relativeToRoot, routeHandlersFromQuery } from "./cbm-responses.js";
+import { cbmCardGraph } from "./cards/graph.js";
+import { classifyTier0, defaultLabels } from "./cards/classify.js";
+import { CARD_FIELDS } from "./cards/build.js";
+import { tier0RulesFrom } from "./tier0-rules.js";
+import { collectExtraction, extractionConfigFrom } from "./cards/extract.js";
+const EXTRACT_CALL_TIMEOUT_MS = 12e4, SOURCE_CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte|py|go|rb|java|rs|php|cs|cpp|c|h|kt|swift|sh|bash)$/i;
 function isLikelyHttpRoute(qualifiedName) {
   const httpPath = qualifiedName.replace(/^__route__[A-Z]+__/, "");
   return !SOURCE_CODE_EXT_RE.test(httpPath) && !httpPath.startsWith("/.dr/") && !httpPath.startsWith("/schemas/");
@@ -24,21 +31,17 @@ function inferHttpPathFromFunctionName(name) {
   const stripped = name.replace(/^(fetch|get|list|create|add|update|put|delete|remove|patch|merge|load|save|replace|post|submit|send|destroy)/i, ""), segment = toKebabCase(stripped || name);
   return segment ? `/${segment}` : "/";
 }
+const SERVICE_SOURCE_TYPES = /* @__PURE__ */ new Set(["applicationfunction", "applicationcomponent", "applicationservice"]);
 class CbmAnalyzer {
   mapper;
   testCodePatternWarned = !1;
   warnedHeuristics = /* @__PURE__ */ new Set();
   /**
-   * Default regex patterns for test code detection
+   * Test code detection when the mapping has no test_code_exclusion rule: the same test-file
+   * pattern as the mapping's rule and its tier0_test_file rule.
    */
   static DEFAULT_TEST_PATTERNS = [
-    /\.test\./,
-    /\.spec\./,
-    /\/tests?\//,
-    /\/__tests__\//,
-    /\/test-/,
-    /\/fixtures?\//,
-    /\/__fixtures__\//
+    /((^|\/)(tests?|__tests__|__fixtures__|fixtures?)\/|(^|\/)test_[^/]*\.py$|(^|\/)conftest\.py$|_test\.(go|py)$|\.(test|spec)\.[cm]?[jt]sx?$|Tests?\.(java|kt)$)/
   ];
   constructor(mapper) {
     this.mapper = mapper;
@@ -171,10 +174,11 @@ class CbmAnalyzer {
    * Checks if the project is indexed and whether the index is fresh relative to git HEAD.
    *
    * @param projectRoot Absolute path to the project root
+   * @param options Optional codebase configuration
    * @returns Current status including detection, index state, and freshness
    */
-  async status(projectRoot) {
-    const detected = await this.detect(projectRoot), analyzerName = this.mapper.getAnalyzerName(), indexMeta = await readIndexMeta(projectRoot, analyzerName);
+  async status(projectRoot, options) {
+    const detected = await this.detect(projectRoot), effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, analyzerName = this.mapper.getAnalyzerName(), indexMeta = await readIndexMeta(projectRoot, analyzerName);
     if (!(indexMeta !== null))
       return {
         detected,
@@ -184,7 +188,7 @@ class CbmAnalyzer {
     let fresh = !1;
     try {
       const currentHeadResult = spawnSync("git", ["rev-parse", "HEAD"], {
-        cwd: projectRoot,
+        cwd: effectiveCodebaseRoot,
         stdio: "pipe",
         encoding: "utf-8"
       });
@@ -192,7 +196,11 @@ class CbmAnalyzer {
         fresh = currentHeadResult.stdout.trim() === indexMeta.git_head;
       else {
         const gitError = currentHeadResult.stderr?.trim() || "git returned non-zero status";
-        handleWarning("Failed to check git freshness", [
+        options?.codebaseRoot ? handleWarning("Failed to check git freshness in codebase root", [
+          `Codebase root: ${effectiveCodebaseRoot}`,
+          `Git error: ${gitError}`,
+          "Index freshness cannot be determined - treating as stale"
+        ]) : handleWarning("Failed to check git freshness", [
           `Git error: ${gitError}`,
           "Index freshness cannot be determined - treating as stale"
         ]), fresh = !1;
@@ -221,11 +229,11 @@ class CbmAnalyzer {
    * Skips indexing if the index is fresh (git HEAD matches) unless --force is set.
    *
    * @param projectRoot Absolute path to the project root
-   * @param options Optional configuration
+   * @param options Optional configuration including force flag and codebase root
    * @returns Index result with counts and metadata
    */
   async index(projectRoot, options) {
-    const status = await this.status(projectRoot);
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (status.indexed && status.fresh && !options?.force) {
       handleWarning("Index is fresh. Use --force to reindex.", [
         `Last indexed: ${status.last_indexed}`
@@ -252,10 +260,8 @@ class CbmAnalyzer {
         name: "dr-cli",
         version
       });
-      const listProjectsResponse = await client.invokeTool("list_projects");
-      if (!listProjectsResponse || typeof listProjectsResponse != "object")
-        throw new CLIError("Invalid response from list_projects", ErrorCategory.SYSTEM, ["Ensure codebase-memory-mcp is properly installed and functional"]);
-      if ((Array.isArray(listProjectsResponse.projects) ? listProjectsResponse.projects : []).some((p) => p.root_path === projectRoot) && status.fresh && !options?.force) {
+      const tools = new CbmTools(client);
+      if ((await tools.listProjects()).some((p) => p.root_path === effectiveCodebaseRoot) && status.fresh && !options?.force) {
         if (handleWarning("Project already indexed in CBM backend with fresh index.", ["Use --force to re-index the project"]), !status.index_meta)
           throw new CLIError("Project exists in CBM backend but local metadata is missing", ErrorCategory.VALIDATION, [
             "Use --force to re-index and regenerate metadata",
@@ -270,13 +276,14 @@ class CbmAnalyzer {
         };
       }
       const headResult = spawnSync("git", ["rev-parse", "HEAD"], {
-        cwd: projectRoot,
+        cwd: effectiveCodebaseRoot,
         stdio: "pipe",
         encoding: "utf-8"
       });
       if (headResult.status !== 0)
         throw new CLIError("Failed to get git HEAD", ErrorCategory.SYSTEM, [
-          "Ensure the project is a git repository",
+          "Ensure the codebase root is a git repository",
+          `Codebase root: ${effectiveCodebaseRoot}`,
           "Verify git is installed and functional",
           `Error: ${headResult.stderr?.trim() || "unknown error"}`
         ]);
@@ -288,12 +295,14 @@ class CbmAnalyzer {
         const errorMsg = error instanceof Error ? error.message : String(error);
         handleWarning("Failed to read active changeset", [`Error: ${errorMsg}`, "Continuing with indexing"]);
       }
-      const indexResponse = await client.invokeTool("index_repository", {
-        repo_path: projectRoot
-      });
-      if (!indexResponse || typeof indexResponse != "object")
-        throw new CLIError("Invalid response from index_repository", ErrorCategory.SYSTEM, ["Ensure codebase-memory-mcp is properly installed and functional"]);
-      const timestamp = (/* @__PURE__ */ new Date()).toISOString(), nodeCount = typeof indexResponse.nodes == "number" ? indexResponse.nodes : 0, edgeCount = typeof indexResponse.edges == "number" ? indexResponse.edges : 0;
+      try {
+        const ignore = await ensureCbmIgnore(effectiveCodebaseRoot, projectRoot);
+        ignore.added.length > 0 && console.log(`Added ${ignore.added.join(", ")} to ${ignore.path} so the index leaves DR's own files out`);
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        handleWarning("Could not update .cbmignore; DR's own files may be indexed", [`Error: ${errorMsg}`]);
+      }
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString(), indexResponse = await tools.indexRepository(effectiveCodebaseRoot, options?.timeoutMs ? { timeout: options.timeoutMs } : void 0), nodeCount = typeof indexResponse.nodes == "number" ? indexResponse.nodes : 0, edgeCount = typeof indexResponse.edges == "number" ? indexResponse.edges : 0;
       typeof indexResponse.nodes != "number" && handleWarning("Invalid node count from index_repository", [
         `Expected number, got ${typeof indexResponse.nodes}: ${String(indexResponse.nodes)}`,
         "Defaulting to 0 - index may be incomplete or corrupted"
@@ -318,26 +327,25 @@ class CbmAnalyzer {
     }
   }
   /**
-   * Validate search_graph response structure
+   * Fetch Route nodes with their HANDLES-edge handlers attached.
    *
-   * Ensures response is an object and nodes is an array.
-   * Throws CLIError if validation fails.
+   * CBM Route nodes carry only `{ method, source }` and often no file (every fastapi route,
+   * for example); the handler function, its symbol, lines and file come from HANDLES edges.
+   * If the handler query fails the routes are returned as they are.
    *
    * @private
-   * @param response Raw response from search_graph MCP tool
-   * @returns Typed nodes array (may be empty if no results found)
-   * @throws CLIError if response structure is invalid
    */
-  validateSearchResponse(response) {
-    if (!response || typeof response != "object")
-      throw new CLIError("Invalid response from search_graph", ErrorCategory.SYSTEM, ["Ensure codebase-memory-mcp is properly installed and functional"]);
-    const responseObj = response, nodeArray = responseObj.results ?? responseObj.nodes;
-    if (!Array.isArray(nodeArray))
-      throw new CLIError("Invalid response from search_graph: results must be an array", ErrorCategory.SYSTEM, [
-        `Expected array in 'results' or 'nodes', got ${typeof nodeArray}`,
-        "Ensure codebase-memory-mcp is properly installed and returning valid results"
-      ]);
-    return nodeArray;
+  async fetchRoutes(tools, projectName, label) {
+    const routes = await tools.searchGraph({ label, project: projectName });
+    try {
+      const handlers = routeHandlersFromQuery(await tools.queryGraph(ROUTE_HANDLERS_QUERY, projectName));
+      return attachRouteHandlers(routes, handlers);
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return handleWarning("Could not read route handlers (HANDLES edges); routes lack handler details", [
+        `Error: ${errorMsg}`
+      ]), routes;
+    }
   }
   /**
    * Resolve the internal project name used by codebase-memory-mcp for a given root path.
@@ -346,12 +354,12 @@ class CbmAnalyzer {
    * query tools require the internal `name`, not the absolute `root_path`.
    * Falls back to the absolute path with a warning if the project is not found.
    */
-  async resolveProjectName(client, projectRoot) {
-    const listResponse = await client.invokeTool("list_projects"), match = (Array.isArray(listResponse?.projects) ? listResponse.projects : []).find((p) => p.root_path === projectRoot);
+  async resolveProjectName(client, codebaseRoot) {
+    const match = (await (client instanceof CbmTools ? client : new CbmTools(client)).listProjects()).find((p) => p.root_path === codebaseRoot);
     return match ? match.name : (handleWarning("Project not found in CBM backend; using absolute path as project identifier", [
-      `Project root: ${projectRoot}`,
+      `Codebase root: ${codebaseRoot}`,
       "Run `dr analyzer index` to ensure the project is indexed"
-    ]), projectRoot);
+    ]), codebaseRoot);
   }
   /**
    * Query for API endpoints/routes in the indexed project
@@ -360,11 +368,12 @@ class CbmAnalyzer {
    * the analyzer's mapping, and filters based on test code exclusion rules.
    *
    * @param projectRoot Absolute path to the project root
+   * @param options Optional codebase configuration
    * @returns Array of endpoint candidates with confidence and source info
    * @throws CLIError if the project is not indexed
    */
-  async endpoints(projectRoot) {
-    const status = await this.status(projectRoot);
+  async endpoints(projectRoot, options) {
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (!status.indexed)
       throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
         "Run `dr analyzer index` to index the project",
@@ -384,18 +393,14 @@ class CbmAnalyzer {
         name: "dr-cli",
         version
       });
-      const projectName = await this.resolveProjectName(client, projectRoot), searchResponse = await client.invokeTool("search_graph", {
-        label: routeMapping.cbm_label,
-        project: projectName
-      }), nodes = this.validateSearchResponse(searchResponse).filter((n) => /^__route__[A-Z]+__\//.test(String(n.qualified_name ?? ""))).filter((n) => isLikelyHttpRoute(String(n.qualified_name ?? ""))), candidates = [];
+      const tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot), nodes = (await this.fetchRoutes(tools, projectName, routeMapping.cbm_label)).filter((n) => /^__route__[A-Z]+__\//.test(String(n.qualified_name ?? ""))).filter((n) => isLikelyHttpRoute(String(n.qualified_name ?? ""))), candidates = [];
       for (const node of nodes) {
-        const candidate = await this.transformNodeToEndpoint(node, routeMapping, projectRoot);
+        const candidate = await this.transformNodeToEndpoint(node, routeMapping, effectiveCodebaseRoot);
         candidate.source_file && (this.isTestCode(candidate) || candidates.push(candidate));
       }
       if (candidates.length === 0)
         try {
-          const qResp = await client.invokeTool("query_graph", {
-            query: `
+          const clientQuery = `
             MATCH (n:Function)
             WHERE (n.file_path CONTAINS 'client' OR n.file_path CONTAINS 'Client'
                    OR n.file_path CONTAINS 'Api' OR n.file_path CONTAINS 'Service'
@@ -406,21 +411,17 @@ class CbmAnalyzer {
                    OR n.name STARTS WITH 'delete' OR n.name STARTS WITH 'patch'
                    OR n.name STARTS WITH 'create' OR n.name STARTS WITH 'update'
                    OR n.name STARTS WITH 'list')
-            RETURN n
-          `,
-            project: projectName
-          });
-          if (qResp && typeof qResp == "object") {
-            const records = qResp.records ?? [];
-            for (const record of records) {
-              const node = record.n;
-              if (!node || !node.file_path)
-                continue;
-              const candidate = this.shapeClientSideEndpoint(node, projectRoot);
-              candidate && !this.isTestCode(candidate) && candidates.push(candidate);
-            }
+            RETURN ${nodeColumns("n")}
+          `, clientNodes = nodesFromQuery(await tools.queryGraph(clientQuery, projectName));
+          for (const node of clientNodes) {
+            if (!node.file_path)
+              continue;
+            const candidate = this.shapeClientSideEndpoint(node, effectiveCodebaseRoot);
+            candidate && !this.isTestCode(candidate) && candidates.push(candidate);
           }
-        } catch {
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          handleWarning("Client-side endpoint fallback skipped: query_graph failed", [`Error: ${errorMsg}`]);
         }
       return this.warnOnDuplicateIdFragments(candidates, (c) => c.suggested_id_fragment, (c) => c.source_symbol || c.source_file || "(unknown)"), candidates;
     } finally {
@@ -436,11 +437,12 @@ class CbmAnalyzer {
    *
    * @param projectRoot Absolute path to the project root
    * @param rawQuery Raw Cypher query string
+   * @param options Optional codebase configuration
    * @returns Raw result from query_graph tool
    * @throws CLIError if project not indexed or query_graph tool unavailable
    */
-  async query(projectRoot, rawQuery) {
-    const status = await this.status(projectRoot);
+  async query(projectRoot, rawQuery, options) {
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (!status.indexed)
       throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
         "Run `dr analyzer index` to index the project",
@@ -457,13 +459,13 @@ class CbmAnalyzer {
         name: "dr-cli",
         version
       });
-      const projectName = await this.resolveProjectName(client, projectRoot);
+      const tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot);
       try {
-        return await client.invokeTool("query_graph", {
-          query: rawQuery,
-          project: projectName
-        });
+        const result = await tools.queryGraph(rawQuery, projectName);
+        return { ...result, total: result.rows.length };
       } catch (error) {
+        if (error instanceof CbmToolError)
+          throw new CLIError(`Query failed: ${error.detail}`, ErrorCategory.USER, error.suggestions);
         const errorMessage = error instanceof Error ? error.message : String(error);
         throw errorMessage.includes("query_graph") || errorMessage.includes("Unknown method") ? new CLIError("query_graph not supported by this analyzer", ErrorCategory.USER, [
           "The query_graph tool is optional in the CBM analyzer contract",
@@ -507,7 +509,7 @@ class CbmAnalyzer {
    *
    * @private
    */
-  async transformNodeToEndpoint(node, mapping, projectRoot) {
+  async transformNodeToEndpoint(node, mapping, codebaseRoot) {
     const properties = node.properties ?? {}, nodeId = String(node.name ?? node.id ?? "(unknown)");
     let confidence = mapping.confidence;
     const suggestedName = toKebabCase(String(properties.name ?? node.name ?? node.id ?? "")), suggestedIdFragment = suggestedName;
@@ -527,9 +529,9 @@ class CbmAnalyzer {
     const handlerQualifiedName = String(properties.handler_name ?? properties.handler_qualified_name ?? ""), sourceSymbol = String(properties.symbol ?? properties.source_symbol ?? ""), sourceStartLine = Number(properties.start_line ?? 0), sourceEndLine = Number(properties.end_line ?? 0);
     (!handlerQualifiedName || !sourceSymbol) && (confidence = capConfidence(confidence));
     let sourceFile = String(node.file_path ?? properties.file_path ?? properties.source_file ?? "");
-    if (sourceFile && projectRoot)
+    if (sourceFile && codebaseRoot)
       try {
-        sourceFile = path.relative(projectRoot, sourceFile);
+        sourceFile = relativeToRoot(codebaseRoot, sourceFile);
       } catch (error) {
         const errorMsg = error instanceof Error ? error.message : String(error);
         handleWarning(`Failed to compute relative path for ${nodeId}`, [
@@ -577,14 +579,14 @@ class CbmAnalyzer {
    * Build a low-confidence EndpointCandidate from a client-side API function node.
    * Used as a fallback when no server-side Route nodes are found (ISSUE-003).
    */
-  shapeClientSideEndpoint(node, projectRoot) {
+  shapeClientSideEndpoint(node, codebaseRoot) {
     const name = String(node.name ?? node.id ?? "");
     if (!name)
       return null;
     let sourceFile = String(node.file_path ?? "");
-    if (sourceFile && projectRoot)
+    if (sourceFile && codebaseRoot)
       try {
-        sourceFile = path.relative(projectRoot, sourceFile);
+        sourceFile = relativeToRoot(codebaseRoot, sourceFile);
       } catch {
       }
     if (!sourceFile)
@@ -637,11 +639,12 @@ class CbmAnalyzer {
    * at "medium" and excludes test files.
    *
    * @param projectRoot Absolute path to the project root
+   * @param options Optional codebase configuration
    * @returns Array of service candidates with qualifying heuristics populated
    * @throws CLIError if the project is not indexed
    */
-  async services(projectRoot) {
-    const status = await this.status(projectRoot);
+  async services(projectRoot, options) {
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (!status.indexed)
       throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
         "Run `dr analyzer index` to index the project",
@@ -661,7 +664,7 @@ class CbmAnalyzer {
       const nodeLabels = this.mapper.getNodeLabels(), applicationLabels = [];
       for (const label of nodeLabels) {
         const mapping = this.mapper.getNodeMapping(label);
-        mapping && mapping.dr_layer === "application" && applicationLabels.push(label);
+        mapping && mapping.dr_layer === "application" && SERVICE_SOURCE_TYPES.has(mapping.dr_element_type) && applicationLabels.push(label);
       }
       if (applicationLabels.length === 0)
         return handleWarning("No application-layer labels found in analyzer mapping", [
@@ -669,18 +672,15 @@ class CbmAnalyzer {
           "Services detection requires at least one mapped application-layer node type",
           "Returning empty services list"
         ]), [];
-      const candidates = [], projectName = await this.resolveProjectName(client, projectRoot), labelPriority = { Class: 0, Module: 1 };
+      const candidates = [], tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot), labelPriority = { Class: 0, Module: 1 };
       applicationLabels.sort((a, b) => (labelPriority[a] ?? 99) - (labelPriority[b] ?? 99));
       for (const label of applicationLabels) {
-        const searchResponse = await client.invokeTool("search_graph", {
-          label,
-          project: projectName
-        }), nodes = this.validateSearchResponse(searchResponse), nodeMapping = this.mapper.getNodeMapping(label);
+        const nodes = await tools.searchGraph({ label, project: projectName }), nodeMapping = this.mapper.getNodeMapping(label);
         if (!nodeMapping)
           continue;
         const promotionHeuristicNames = nodeMapping.promotion_heuristics || [];
         for (const node of nodes) {
-          const candidate = await this.transformNodeToService(node, nodeMapping, projectRoot, promotionHeuristicNames);
+          const candidate = await this.transformNodeToService(node, nodeMapping, effectiveCodebaseRoot, promotionHeuristicNames);
           candidate.qualifying_heuristics.length > 0 && !this.isTestCode(candidate) && candidates.push(candidate);
         }
       }
@@ -700,12 +700,12 @@ class CbmAnalyzer {
    *
    * @private
    */
-  async transformNodeToService(node, mapping, projectRoot, promotionHeuristicNames) {
+  async transformNodeToService(node, mapping, codebaseRoot, promotionHeuristicNames) {
     const properties = node.properties ?? {}, suggestedName = toKebabCase(String(properties.name ?? node.name ?? node.id ?? "")), suggestedIdFragment = suggestedName;
     let sourceFile = node.file_path ?? "";
-    if (sourceFile && projectRoot)
+    if (sourceFile && codebaseRoot)
       try {
-        sourceFile = path.relative(projectRoot, sourceFile);
+        sourceFile = relativeToRoot(codebaseRoot, sourceFile);
       } catch (error) {
         const errorMsg = error instanceof Error ? error.message : String(error);
         handleWarning(`Failed to compute relative path for ${String(node.name ?? node.id ?? "(unknown)")}`, [
@@ -795,11 +795,12 @@ class CbmAnalyzer {
    * naming_indicators from the heuristic parameters. All candidates have confidence "low".
    *
    * @param projectRoot Absolute path to the project root
+   * @param options Optional codebase configuration
    * @returns Array of datastore candidates aggregated by inferred datastore
    * @throws CLIError if the project is not indexed
    */
-  async datastores(projectRoot) {
-    const status = await this.status(projectRoot);
+  async datastores(projectRoot, options) {
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (!status.indexed)
       throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
         "Run `dr analyzer index` to index the project",
@@ -822,20 +823,17 @@ class CbmAnalyzer {
           "The analyzer configuration is missing the datastore_detection heuristic",
           "Run `npm run build:spec` to recompile the analyzer artifacts"
         ]);
-      const importPatterns = datastoreHeuristic.parameters?.patterns ?? [], namingIndicators = datastoreHeuristic.parameters?.naming_indicators ?? [], datastoreSignals = /* @__PURE__ */ new Map(), datastoreFirstSource = /* @__PURE__ */ new Map(), projectName = await this.resolveProjectName(client, projectRoot);
+      const importPatterns = datastoreHeuristic.parameters?.patterns ?? [], namingIndicators = datastoreHeuristic.parameters?.naming_indicators ?? [], datastoreSignals = /* @__PURE__ */ new Map(), datastoreFirstSource = /* @__PURE__ */ new Map(), tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot);
       let allNodes = [];
       try {
-        const queryResponse = await client.invokeTool("query_graph", {
-          query: `
+        const importsQuery = `
           MATCH (n1)-[r:IMPORTS]->(n2)
-          RETURN DISTINCT n1 as node
+          RETURN DISTINCT ${nodeColumns("n1")}
           UNION
           MATCH (n1)-[r:IMPORTS]->(n2)
-          RETURN DISTINCT n2 as node
-        `,
-          project: projectName
-        });
-        queryResponse && typeof queryResponse == "object" && Array.isArray(queryResponse.records) && (allNodes = (queryResponse.records || []).map((r) => r.node).filter((n) => n && typeof n == "object"));
+          RETURN DISTINCT ${nodeColumns("n2")}
+        `;
+        allNodes = nodesFromQuery(await tools.queryGraph(importsQuery, projectName));
       } catch (error) {
         const errorMsg = error instanceof Error ? error.message : String(error);
         handleWarning("query_graph tool failed; falling back to search_graph for datastore detection", [
@@ -845,13 +843,8 @@ class CbmAnalyzer {
           "Ensure query_graph is supported by your analyzer version for best results"
         ]);
         const nodeLabels = this.mapper.getNodeLabels();
-        for (const label of nodeLabels) {
-          const searchResponse = await client.invokeTool("search_graph", {
-            label,
-            project: projectName
-          }), nodes = this.validateSearchResponse(searchResponse);
-          allNodes.push(...nodes);
-        }
+        for (const label of nodeLabels)
+          allNodes.push(...await tools.searchGraph({ label, project: projectName }));
       }
       for (const node of allNodes) {
         const filePath = node.file_path ?? "", importTargetName = String(node.label ?? node.properties?.name ?? node.id ?? "").toLowerCase();
@@ -874,9 +867,9 @@ class CbmAnalyzer {
         ]) : (datastoreSignals.set(datastoreName, []), datastoreFirstSource.set(datastoreName, importTargetName));
         const signals = datastoreSignals.get(datastoreName);
         let relativeFile = filePath;
-        if (filePath && projectRoot)
+        if (filePath && effectiveCodebaseRoot)
           try {
-            relativeFile = path.relative(projectRoot, filePath);
+            relativeFile = relativeToRoot(effectiveCodebaseRoot, filePath);
           } catch (error) {
             const errorMsg = error instanceof Error ? error.message : String(error);
             handleWarning("Failed to compute relative path in datastore detection", [
@@ -925,8 +918,7 @@ class CbmAnalyzer {
       }
       const browserStorageTypes = ["local-storage", "session-storage"], browserStorageSignals = /* @__PURE__ */ new Map();
       try {
-        const storageResp = await client.invokeTool("query_graph", {
-          query: `
+        const storageQuery = `
           MATCH (n:Function)
           WHERE n.file_path CONTAINS 'Store' OR n.file_path CONTAINS 'store'
              OR n.file_path CONTAINS 'storage' OR n.file_path CONTAINS 'Storage'
@@ -934,24 +926,13 @@ class CbmAnalyzer {
              OR n.file_path CONTAINS 'preference' OR n.file_path CONTAINS 'Preference'
              OR n.file_path CONTAINS 'layout' OR n.file_path CONTAINS 'Layout'
              OR n.file_path CONTAINS 'settings' OR n.file_path CONTAINS 'Settings'
-          RETURN n
-        `,
-          project: projectName
-        });
-        if (storageResp && typeof storageResp == "object") {
-          const records = storageResp.records ?? [];
-          for (const record of records) {
-            const node = record.n;
-            if (!node?.file_path)
-              continue;
-            let relFile = node.file_path;
-            try {
-              relFile = path.relative(projectRoot, node.file_path);
-            } catch {
-            }
-            const storageKey = /session/i.test(relFile) ? "session-storage" : "local-storage";
-            browserStorageSignals.has(storageKey) || browserStorageSignals.set(storageKey, /* @__PURE__ */ new Set()), browserStorageSignals.get(storageKey).add(relFile);
-          }
+          RETURN ${nodeColumns("n")}
+        `, storageNodes = nodesFromQuery(await tools.queryGraph(storageQuery, projectName));
+        for (const node of storageNodes) {
+          if (!node.file_path)
+            continue;
+          const relFile = relativeToRoot(effectiveCodebaseRoot, node.file_path), storageKey = /session/i.test(relFile) ? "session-storage" : "local-storage";
+          browserStorageSignals.has(storageKey) || browserStorageSignals.set(storageKey, /* @__PURE__ */ new Set()), browserStorageSignals.get(storageKey).add(relFile);
         }
       } catch {
       }
@@ -1014,11 +995,12 @@ class CbmAnalyzer {
    * @param projectRoot Absolute path to the project root
    * @param qualifiedName Fully qualified symbol name (e.g., "com.example.UserService.getUser")
    * @param depth Maximum traversal depth (default 3, clamped to max 10)
+   * @param options Optional codebase configuration
    * @returns Array of callers in the call graph
    * @throws CLIError if project not indexed or analyzer not installed
    */
-  async callers(projectRoot, qualifiedName, depth) {
-    return this.traceCallPath(projectRoot, qualifiedName, depth, "inbound");
+  async callers(projectRoot, qualifiedName, depth, options) {
+    return this.traceCallPath(projectRoot, qualifiedName, depth, "inbound", options);
   }
   /**
    * Query for callees of a specific function or symbol
@@ -1031,11 +1013,12 @@ class CbmAnalyzer {
    * @param projectRoot Absolute path to the project root
    * @param qualifiedName Fully qualified symbol name (e.g., "com.example.UserService.getUser")
    * @param depth Maximum traversal depth (default 3, clamped to max 10)
+   * @param options Optional codebase configuration
    * @returns Array of callees in the call graph
    * @throws CLIError if project not indexed or analyzer not installed
    */
-  async callees(projectRoot, qualifiedName, depth) {
-    return this.traceCallPath(projectRoot, qualifiedName, depth, "outbound");
+  async callees(projectRoot, qualifiedName, depth, options) {
+    return this.traceCallPath(projectRoot, qualifiedName, depth, "outbound", options);
   }
   /**
    * Cypher fallback for call graph traversal when trace_path is unavailable.
@@ -1045,7 +1028,7 @@ class CbmAnalyzer {
    *
    * @private
    */
-  async callGraphViaCypher(binaryPath, projectName, qualifiedName, direction, depth, projectRoot) {
+  async callGraphViaCypher(binaryPath, projectName, qualifiedName, direction, depth, codebaseRoot) {
     const safeQN = qualifiedName.replace(/'/g, "''"), limit = Math.min(depth * 20, 100), cypher = direction === "inbound" ? `MATCH (caller)-[:CALLS]->(target) WHERE target.qualified_name = '${safeQN}' OR target.name = '${safeQN}' RETURN caller.id AS id, caller.qualified_name AS qualified_name, caller.file_path AS file_path LIMIT ${limit}` : `MATCH (source)-[:CALLS]->(callee) WHERE source.qualified_name = '${safeQN}' OR source.name = '${safeQN}' RETURN callee.id AS id, callee.qualified_name AS qualified_name, callee.file_path AS file_path LIMIT ${limit}`;
     depth > 1 && handleWarning(`Cypher CALLS fallback: depth ${depth} requested but fallback only traverses 1 hop`, ["Multi-hop traversal requires trace_path support in the analyzer binary"]);
     const client = new StdioClient();
@@ -1053,16 +1036,13 @@ class CbmAnalyzer {
       client.spawn(binaryPath);
       const version = await getCliVersion();
       await client.initialize({ name: "dr-cli", version });
-      const queryResponse = await client.invokeTool("query_graph", {
-        query: cypher,
-        project: projectName
-      }), cols = queryResponse?.columns ?? [];
-      return (queryResponse?.rows ?? []).map((row) => {
+      const queryResponse = await new CbmTools(client).queryGraph(cypher, projectName), cols = queryResponse.columns;
+      return queryResponse.rows.map((row) => {
         const obj = {};
         return cols.forEach((col, i) => {
           const key = col.includes(".") ? col.slice(col.lastIndexOf(".") + 1) : col;
           obj[key] = row[i];
-        }), shapeCallGraphNode(obj, projectRoot);
+        }), shapeCallGraphNode(obj, codebaseRoot);
       });
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
@@ -1082,8 +1062,8 @@ class CbmAnalyzer {
    *
    * @private
    */
-  async traceCallPath(projectRoot, qualifiedName, depth, direction) {
-    const status = await this.status(projectRoot);
+  async traceCallPath(projectRoot, qualifiedName, depth, direction, options) {
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (!status.indexed)
       throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
         "Run `dr analyzer index` to index the project",
@@ -1100,25 +1080,37 @@ class CbmAnalyzer {
         name: "dr-cli",
         version
       });
-      const projectName = await this.resolveProjectName(client, projectRoot), traceResponse = await client.invokeTool("trace_path", {
-        function_name: qualifiedName,
-        direction,
-        depth: clampedDepth,
-        project: projectName
-      });
-      if (!traceResponse || typeof traceResponse != "object")
-        throw new CLIError("Invalid response from trace_path", ErrorCategory.SYSTEM, ["Ensure codebase-memory-mcp is properly installed and functional"]);
-      if (!Array.isArray(traceResponse.nodes))
-        return this.callGraphViaCypher(detection.binary_path, projectName, qualifiedName, direction, clampedDepth, projectRoot);
-      if (!Array.isArray(traceResponse.edges))
-        return handleWarning("trace_path returned no edges array \u2014 returning empty call graph", [
-          `Expected array, got ${typeof traceResponse.edges}`,
-          "Ensure codebase-memory-mcp supports trace_path and the project is indexed"
-        ]), [];
-      const nodes = traceResponse.nodes, edges = traceResponse.edges, validEdgeTypes = this.mapper.getEdgeTypes(), callGraphNodes = [];
+      const tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot);
+      let trace;
+      try {
+        trace = await tools.tracePath({
+          function_name: qualifiedName,
+          direction,
+          depth: clampedDepth,
+          project: projectName
+        });
+      } catch (error) {
+        throw error instanceof CbmToolError && /not found/i.test(error.detail) ? new CLIError(`Symbol not found in the code graph: ${qualifiedName}`, ErrorCategory.NOT_FOUND, [
+          ...error.suggestions ?? [],
+          "Pass the fully qualified name as CBM records it (see `dr analyzer services --json`)"
+        ]) : error;
+      }
+      if (!trace)
+        return this.callGraphViaCypher(detection.binary_path, projectName, qualifiedName, direction, clampedDepth, effectiveCodebaseRoot);
+      const nodes = trace.nodes, edges = trace.edges;
+      if (trace.shape === "grouped" && nodes.length > 0)
+        try {
+          const files = await tools.filePathsOf(nodes.map((n) => String(n.qualified_name ?? "")), projectName);
+          for (const node of nodes)
+            node.file_path ??= files.get(String(node.qualified_name ?? ""));
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          handleWarning("Could not look up source files for the call graph", [`Error: ${errorMsg}`]);
+        }
+      const validEdgeTypes = ["CALLS", ...this.mapper.getEdgeTypes().filter((t) => t !== "CALLS")], callGraphNodes = [];
       for (const node of nodes) {
-        const nodeQualifiedName = node.qualified_name || node.id;
-        let callGraphNode = shapeCallGraphNode(node, projectRoot);
+        const nodeQualifiedName = String(node.qualified_name || node.id || "");
+        let callGraphNode = shapeCallGraphNode(node, effectiveCodebaseRoot);
         const nodeDepth = typeof node.depth == "number" ? node.depth : 0, edgeType = determineEdgeType(nodeDepth, edges, nodeQualifiedName, validEdgeTypes);
         callGraphNode.edge_type = edgeType, callGraphNodes.push(callGraphNode);
       }
@@ -1156,6 +1148,85 @@ class CbmAnalyzer {
       source_symbol: sourceSymbol
     };
   }
+  /**
+   * Tier-0 classification of the indexed project (`dr analyzer classify --tier0-only`).
+   *
+   * Builds a card for every candidate symbol (src/analyzers/cards) and applies the Tier-0 rules
+   * from this analyzer's extraction heuristics. Reads the graph only: no model calls, no writes.
+   *
+   * @throws CLIError if the project is not indexed or the mapping has no Tier-0 rules
+   */
+  async classify(projectRoot, options = {}) {
+    const effectiveCodebaseRoot = options.codebaseRoot ?? projectRoot, rules = tier0RulesFrom(this.mapper.getHeuristics());
+    if (rules.length === 0)
+      throw new CLIError(`The ${this.name} analyzer mapping has no Tier-0 rules`, ErrorCategory.USER, [
+        "Tier-0 rules are heuristics with a parameters.tier0 block in the analyzer's extraction-heuristics.json"
+      ]);
+    if (options.labels?.length) {
+      const known = /* @__PURE__ */ new Set([...this.mapper.getNodeLabels(), ...defaultLabels(rules), ...Object.keys(CARD_FIELDS)]), unknown = options.labels.filter((l) => !known.has(l));
+      if (unknown.length)
+        throw new CLIError(`Unknown label${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}`, ErrorCategory.USER, [
+          `Labels are case-sensitive; known labels: ${[...known].sort().join(", ")}`
+        ]);
+    }
+    const status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
+    if (!status.indexed)
+      throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
+        "Run `dr analyzer index` to index the project",
+        "Ensure codebase-memory-mcp is installed and working"
+      ]);
+    const detection = status.detected;
+    if (!detection.installed)
+      throw new CLIError("CBM analyzer not installed", ErrorCategory.NOT_FOUND, [
+        "Install codebase-memory-mcp: npm install -g codebase-memory-mcp"
+      ]);
+    const client = new StdioClient();
+    try {
+      client.spawn(detection.binary_path), await client.initialize({ name: "dr-cli", version: await getCliVersion() });
+      const tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot);
+      return await classifyTier0(cbmCardGraph(tools, projectName), rules, this.name, {
+        sourceRoot: effectiveCodebaseRoot,
+        ...options
+      });
+    } finally {
+      client.close();
+    }
+  }
+  /** The Tier-0 rules, edge mappings and node-mapping decisions extraction runs with. */
+  extractionConfig() {
+    const nodeMappings = this.mapper.getNodeLabels().map((label) => this.mapper.getNodeMapping(label)).filter((m) => !!m), edgeMappings = this.mapper.getEdgeTypes().map((type) => this.mapper.getEdgeMapping(type)).filter((m) => !!m);
+    return extractionConfigFrom(tier0RulesFrom(this.mapper.getHeuristics()), edgeMappings, nodeMappings);
+  }
+  /**
+   * What `codebase_extract` reads from the index (src/analyzers/cards/extract.ts): cards with
+   * their Tier-0 outcomes, the mapped edges and the symbols of the files asked about. Read-only.
+   * Graph reads get two minutes each, past the client's 30s default, for large graphs.
+   *
+   * @throws CLIError if the project is not indexed or the mapping has no Tier-0 rules
+   */
+  async extract(projectRoot, options = {}) {
+    const effectiveCodebaseRoot = options.codebaseRoot ?? projectRoot, config = this.extractionConfig();
+    if (config.rules.length === 0)
+      throw new CLIError(`The ${this.name} analyzer mapping has no Tier-0 rules`, ErrorCategory.USER);
+    const status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
+    if (!status.indexed)
+      throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, ["Run `dr analyzer index` to index the project"]);
+    if (!status.detected.installed)
+      throw new CLIError("CBM analyzer not installed", ErrorCategory.NOT_FOUND, [
+        "Install codebase-memory-mcp: npm install -g codebase-memory-mcp"
+      ]);
+    const client = new StdioClient();
+    try {
+      client.spawn(status.detected.binary_path), await client.initialize({ name: "dr-cli", version: await getCliVersion() });
+      const tools = new CbmTools(client, { timeout: EXTRACT_CALL_TIMEOUT_MS }), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot);
+      return await collectExtraction(cbmCardGraph(tools, projectName), config, this.name, {
+        sourceRoot: effectiveCodebaseRoot,
+        ...options
+      });
+    } finally {
+      client.close();
+    }
+  }
   /**
    * Verify that graph-discovered routes align with model endpoints
    *
@@ -1163,12 +1234,12 @@ class CbmAnalyzer {
    * and delegates comparison to VerifyEngine. Entirely read-only.
    *
    * @param projectRoot Absolute path to the project root
-   * @param options Verification options
+   * @param options Verification options including codebase root
    * @returns Comprehensive verification report
    * @throws CLIError if project not indexed or analyzer not installed
    */
   async verify(projectRoot, options) {
-    const status = await this.status(projectRoot);
+    const effectiveCodebaseRoot = options?.codebaseRoot ?? projectRoot, status = await this.status(projectRoot, { codebaseRoot: effectiveCodebaseRoot });
     if (!status.indexed)
       throw new CLIError(`Project not indexed: ${projectRoot}`, ErrorCategory.NOT_FOUND, [
         "Run `dr analyzer index` to index the project",
@@ -1188,18 +1259,43 @@ class CbmAnalyzer {
         name: "dr-cli",
         version
       });
-      const projectName = await this.resolveProjectName(client, projectRoot), searchResponse = await client.invokeTool("search_graph", {
-        label: routeMapping.cbm_label,
-        project: projectName
-      }), routes = this.validateSearchResponse(searchResponse).filter((n) => /^__route__[A-Z]+__\//.test(String(n.qualified_name ?? ""))).filter((n) => isLikelyHttpRoute(String(n.qualified_name ?? ""))).map((node) => this.shapeRoute(node)).filter((r) => r.source_file), engine = new VerifyEngine(), indexMeta = status.index_meta, analyzerName = this.name;
+      const tools = new CbmTools(client), projectName = await this.resolveProjectName(tools, effectiveCodebaseRoot), routes = (await this.fetchRoutes(tools, projectName, routeMapping.cbm_label)).filter((n) => /^__route__[A-Z]+__\//.test(String(n.qualified_name ?? ""))).filter((n) => isLikelyHttpRoute(String(n.qualified_name ?? ""))).map((node) => this.shapeRoute(node)).filter((r) => r.source_file), engine = new VerifyEngine(), indexMeta = status.index_meta, analyzerName = this.name;
       return await engine.computeReport(projectRoot, routes, options, analyzerName, indexMeta);
     } finally {
       client.close();
     }
   }
 }
+const CBM_IGNORE_HEADING = "# Added by Documentation Robotics: its model, changesets and analyzer state are not code.";
+async function ensureCbmIgnore(codebaseRoot, projectRoot) {
+  const file = path.join(codebaseRoot, ".cbmignore");
+  let text = "", created = !0;
+  try {
+    text = await readFile(file, "utf-8"), created = !1;
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#")), folder = (line) => line.replace(/^\/+/, "").replace(/\/+$/, ""), listed = new Set(lines.filter((line) => !line.startsWith("!")).map(folder)), negated = new Set(lines.filter((line) => line.startsWith("!")).map((line) => folder(line.slice(1)))), added = [];
+  for (const dir of DR_OWN_DIRS) {
+    const relative = path.relative(codebaseRoot, path.join(projectRoot, dir)).split(path.sep).join("/");
+    !relative || relative.startsWith("..") || path.isAbsolute(relative) || !listed.has(relative) && !negated.has(relative) && added.push(`/${relative}/`);
+  }
+  if (added.length === 0)
+    return { path: file, added, created: !1 };
+  const separator = text.length === 0 ? "" : text.endsWith(`
+`) ? `
+` : `
+
+`, heading = text.includes(CBM_IGNORE_HEADING) ? "" : `${CBM_IGNORE_HEADING}
+`;
+  return await writeFile(file, `${text}${separator}${heading}${added.join(`
+`)}
+`), { path: file, added, created };
+}
 export {
   CbmAnalyzer,
-  SOURCE_CODE_EXT_RE
+  SOURCE_CODE_EXT_RE,
+  ensureCbmIgnore
 };
 //# sourceMappingURL=cbm-analyzer.js.map