@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/analyzers/cbm-analyzer.js

@@ -0,0 +1,1205 @@
+import { spawnSync } from "child_process";
+import * as path from "path";
+import { readFile } 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 { 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;
+function isLikelyHttpRoute(qualifiedName) {
+  const httpPath = qualifiedName.replace(/^__route__[A-Z]+__/, "");
+  return !SOURCE_CODE_EXT_RE.test(httpPath) && !httpPath.startsWith("/.dr/") && !httpPath.startsWith("/schemas/");
+}
+function inferHttpMethodFromFunctionName(name) {
+  const lower = name.toLowerCase();
+  return /^(create|add|post|submit|send)/.test(lower) ? "POST" : /^(update|put|save|replace|set)/.test(lower) ? "PUT" : /^(patch|merge)/.test(lower) ? "PATCH" : /^(delete|remove|destroy)/.test(lower) ? "DELETE" : "GET";
+}
+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}` : "/";
+}
+class CbmAnalyzer {
+  mapper;
+  testCodePatternWarned = !1;
+  warnedHeuristics = /* @__PURE__ */ new Set();
+  /**
+   * Default regex patterns for test code detection
+   */
+  static DEFAULT_TEST_PATTERNS = [
+    /\.test\./,
+    /\.spec\./,
+    /\/tests?\//,
+    /\/__tests__\//,
+    /\/test-/,
+    /\/fixtures?\//,
+    /\/__fixtures__\//
+  ];
+  constructor(mapper) {
+    this.mapper = mapper;
+  }
+  /**
+   * Get the analyzer name
+   */
+  get name() {
+    return this.mapper.getAnalyzerName();
+  }
+  /**
+   * Get the analyzer display name
+   */
+  get displayName() {
+    return this.mapper.getAnalyzerMetadata()?.display_name || this.mapper.getAnalyzerName();
+  }
+  /**
+   * Check if the MCP server is registered in .mcp.json
+   *
+   * Reads .mcp.json from the project root and checks if the analyzer's MCP server
+   * is registered there. This is extracted into a separate method for easier testing.
+   *
+   * @param projectRoot Absolute path to the project root
+   * @returns True if the MCP server is registered, false otherwise
+   * @throws CLIError if .mcp.json exists but is unreadable or malformed
+   */
+  async checkMcpRegistration(projectRoot) {
+    try {
+      const mcpJsonPath = path.join(projectRoot, ".mcp.json"), mcpContent = await readFile(mcpJsonPath, "utf-8"), mcpConfig = JSON.parse(mcpContent), mcpServerName = this.mapper.getAnalyzerMetadata()?.mcp_server_name ?? "codebase-memory-mcp";
+      return mcpConfig.mcpServers && mcpServerName in mcpConfig.mcpServers || !1;
+    } catch (error) {
+      const err = error;
+      if (err.code === "ENOENT")
+        return !1;
+      throw err.code === "EACCES" ? new CLIError("Permission denied reading .mcp.json", ErrorCategory.SYSTEM, [
+        `Cannot read ${path.join(projectRoot, ".mcp.json")}`,
+        "Check file permissions"
+      ]) : new CLIError("Invalid .mcp.json format", ErrorCategory.VALIDATION, [
+        `Check that ${path.join(projectRoot, ".mcp.json")} contains valid JSON`,
+        `Error: ${error instanceof Error ? error.message : String(error)}`
+      ]);
+    }
+  }
+  /**
+   * Detect if the analyzer is installed and functional
+   *
+   * Checks for the presence of the analyzer binary, reads .mcp.json for registration info,
+   * and validates the required tool contract by calling initialize and verifying required_tools.
+   *
+   * @param projectRoot Optional absolute path to project root (defaults to cwd)
+   * @returns Detection result with binary path, version, and MCP registration status
+   */
+  async detect(projectRoot) {
+    const metadata = this.mapper.getAnalyzerMetadata(), binaryNames = metadata?.binary_names ?? [
+      "codebase-memory-mcp"
+    ];
+    let mcpRegistered = !1;
+    try {
+      mcpRegistered = await this.checkMcpRegistration(projectRoot || process.cwd());
+    } catch (error) {
+      if (error instanceof CLIError)
+        handleWarning(error.message, error.suggestions);
+      else {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        handleWarning("Unexpected error checking MCP registration", [errorMsg]);
+      }
+      mcpRegistered = !1;
+    }
+    for (const binaryName of binaryNames) {
+      const whichResult = spawnSync("which", [binaryName], {
+        stdio: "pipe",
+        encoding: "utf-8"
+      });
+      if (whichResult.status !== 0)
+        continue;
+      const binaryPath = whichResult.stdout.trim();
+      if (!binaryPath)
+        continue;
+      const client = new StdioClient();
+      try {
+        client.spawn(binaryPath);
+        const version = await getCliVersion();
+        await client.initialize({
+          name: "dr-cli",
+          version
+        });
+        let contractOk = !0;
+        const requiredTools = metadata?.supported_tool_contract?.required_tools ?? [];
+        if (requiredTools.length > 0)
+          try {
+            const response = await client.callTool("tools/list", {}), availableTools = new Set((response.tools ?? []).map((tool) => tool.name));
+            for (const tool of requiredTools)
+              availableTools.has(tool) || (contractOk = !1, handleWarning(`Required tool '${tool}' not available in ${binaryName}`, ["Ensure the analyzer server exports all required tools"]));
+          } catch (error) {
+            contractOk = !1;
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            handleWarning(`Failed to verify required tools for ${binaryName}: ${errorMsg}`, ["Ensure all required tools are available in the analyzer server"]);
+          }
+        return {
+          installed: !0,
+          binary_path: binaryPath,
+          version: void 0,
+          // Version could be extracted from --version if needed
+          mcp_registered: mcpRegistered,
+          contract_ok: contractOk
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        handleWarning(`Binary ${binaryName} failed initialization: ${errorMessage}`, ["Check that the binary is properly installed and functional"]);
+        continue;
+      } finally {
+        try {
+          client.close();
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          handleWarning(`Failed to close MCP client for ${binaryName}: ${errorMessage}`, [
+            "The MCP server process may still be running",
+            "Try restarting your terminal or manually killing the process"
+          ]);
+        }
+      }
+    }
+    return {
+      installed: !1
+    };
+  }
+  /**
+   * Get the current status of the analyzer for a project
+   *
+   * Checks if the project is indexed and whether the index is fresh relative to git HEAD.
+   *
+   * @param projectRoot Absolute path to the project root
+   * @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);
+    if (!(indexMeta !== null))
+      return {
+        detected,
+        indexed: !1,
+        fresh: !1
+      };
+    let fresh = !1;
+    try {
+      const currentHeadResult = spawnSync("git", ["rev-parse", "HEAD"], {
+        cwd: projectRoot,
+        stdio: "pipe",
+        encoding: "utf-8"
+      });
+      if (currentHeadResult.status === 0)
+        fresh = currentHeadResult.stdout.trim() === indexMeta.git_head;
+      else {
+        const gitError = currentHeadResult.stderr?.trim() || "git returned non-zero status";
+        handleWarning("Failed to check git freshness", [
+          `Git error: ${gitError}`,
+          "Index freshness cannot be determined - treating as stale"
+        ]), fresh = !1;
+      }
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      handleWarning("Failed to spawn git process", [
+        `Error: ${errorMsg}`,
+        "Index freshness cannot be determined - treating as stale"
+      ]), fresh = !1;
+    }
+    return {
+      detected,
+      indexed: !0,
+      index_meta: indexMeta,
+      fresh,
+      last_indexed: indexMeta.timestamp
+    };
+  }
+  /**
+   * Index a project or update the index
+   *
+   * Creates a project entry in the CBM backend if it doesn't already exist,
+   * indexes the repository, and writes freshness metadata.
+   *
+   * 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
+   * @returns Index result with counts and metadata
+   */
+  async index(projectRoot, options) {
+    const status = await this.status(projectRoot);
+    if (status.indexed && status.fresh && !options?.force) {
+      handleWarning("Index is fresh. Use --force to reindex.", [
+        `Last indexed: ${status.last_indexed}`
+      ]);
+      const meta = status.index_meta;
+      return {
+        node_count: meta.node_count,
+        edge_count: meta.edge_count,
+        git_head: meta.git_head,
+        timestamp: meta.timestamp
+      };
+    }
+    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",
+        "Ensure the binary is in your PATH"
+      ]);
+    const client = new StdioClient();
+    try {
+      client.spawn(detection.binary_path);
+      const version = await getCliVersion();
+      await client.initialize({
+        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) {
+        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",
+            "Or manually delete the project from CBM backend and re-index"
+          ]);
+        const meta2 = status.index_meta;
+        return {
+          node_count: meta2.node_count,
+          edge_count: meta2.edge_count,
+          git_head: meta2.git_head,
+          timestamp: meta2.timestamp
+        };
+      }
+      const headResult = spawnSync("git", ["rev-parse", "HEAD"], {
+        cwd: projectRoot,
+        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",
+          "Verify git is installed and functional",
+          `Error: ${headResult.stderr?.trim() || "unknown error"}`
+        ]);
+      const gitHead = headResult.stdout.trim();
+      try {
+        const activeChangesetId = await new StagingAreaManager(projectRoot).getActiveId();
+        activeChangesetId && console.log(`Indexing with active changeset: ${activeChangesetId}`);
+      } catch (error) {
+        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;
+      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"
+      ]), typeof indexResponse.edges != "number" && handleWarning("Invalid edge count from index_repository", [
+        `Expected number, got ${typeof indexResponse.edges}: ${String(indexResponse.edges)}`,
+        "Defaulting to 0 - index may be incomplete or corrupted"
+      ]);
+      const meta = {
+        git_head: gitHead,
+        timestamp,
+        node_count: nodeCount,
+        edge_count: edgeCount
+      }, analyzerName = this.mapper.getAnalyzerName();
+      return await writeIndexMeta(meta, projectRoot, analyzerName), {
+        node_count: nodeCount,
+        edge_count: edgeCount,
+        git_head: gitHead,
+        timestamp
+      };
+    } finally {
+      client.close();
+    }
+  }
+  /**
+   * Validate search_graph response structure
+   *
+   * Ensures response is an object and nodes is an array.
+   * Throws CLIError if validation fails.
+   *
+   * @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;
+  }
+  /**
+   * Resolve the internal project name used by codebase-memory-mcp for a given root path.
+   *
+   * list_projects returns { name, root_path } per entry. search_graph and other
+   * 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);
+    return match ? match.name : (handleWarning("Project not found in CBM backend; using absolute path as project identifier", [
+      `Project root: ${projectRoot}`,
+      "Run `dr analyzer index` to ensure the project is indexed"
+    ]), projectRoot);
+  }
+  /**
+   * Query for API endpoints/routes in the indexed project
+   *
+   * Searches the indexed graph for Route nodes, applies field mappings from
+   * the analyzer's mapping, and filters based on test code exclusion rules.
+   *
+   * @param projectRoot Absolute path to the project root
+   * @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);
+    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 routeMapping = this.mapper.getNodeMapping("Route");
+    if (!routeMapping)
+      throw new CLIError("Route mapping not found in analyzer", ErrorCategory.VALIDATION, ["Run `npm run build:spec` to recompile the analyzer artifacts"]);
+    const client = new StdioClient();
+    try {
+      client.spawn(detection.binary_path);
+      const version = await getCliVersion();
+      await client.initialize({
+        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 = [];
+      for (const node of nodes) {
+        const candidate = await this.transformNodeToEndpoint(node, routeMapping, projectRoot);
+        candidate.source_file && (this.isTestCode(candidate) || candidates.push(candidate));
+      }
+      if (candidates.length === 0)
+        try {
+          const qResp = await client.invokeTool("query_graph", {
+            query: `
+            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'
+                   OR n.file_path CONTAINS 'service' OR n.file_path CONTAINS 'http'
+                   OR n.file_path CONTAINS 'Http')
+              AND (n.name STARTS WITH 'fetch' OR n.name STARTS WITH 'get'
+                   OR n.name STARTS WITH 'post' OR n.name STARTS WITH 'put'
+                   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);
+            }
+          }
+        } catch {
+        }
+      return this.warnOnDuplicateIdFragments(candidates, (c) => c.suggested_id_fragment, (c) => c.source_symbol || c.source_file || "(unknown)"), candidates;
+    } finally {
+      client.close();
+    }
+  }
+  /**
+   * Execute a raw Cypher query against the analyzer's graph
+   *
+   * Passes the raw Cypher string directly to the query_graph MCP tool.
+   * The query_graph tool is optional (not in required_tools contract).
+   * If the tool call fails, surfaces a clear error message.
+   *
+   * @param projectRoot Absolute path to the project root
+   * @param rawQuery Raw Cypher query string
+   * @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);
+    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);
+      const version = await getCliVersion();
+      await client.initialize({
+        name: "dr-cli",
+        version
+      });
+      const projectName = await this.resolveProjectName(client, projectRoot);
+      try {
+        return await client.invokeTool("query_graph", {
+          query: rawQuery,
+          project: projectName
+        });
+      } catch (error) {
+        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",
+          "Ensure your codebase-memory-mcp version supports raw graph queries",
+          "Contact the analyzer maintainers if you need this feature"
+        ]) : error;
+      }
+    } finally {
+      client.close();
+    }
+  }
+  warnOnDuplicateIdFragments(items, getKey, getLabel) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const key = getKey(item);
+      if (!key)
+        continue;
+      const label = getLabel(item);
+      seen.has(key) ? handleWarning(`Duplicate suggested ID "${key}" \u2014 multiple symbols map to the same element ID`, [
+        `First: ${seen.get(key)}`,
+        `Conflict: ${label}`,
+        'Rename one or use "dr add" with a custom name'
+      ]) : seen.set(key, label);
+    }
+  }
+  /**
+   * Transform a CBM graph node to an endpoint candidate
+   *
+   * Maps CBM Route node properties to DR EndpointCandidate contract:
+   * - suggested_layer: always "api" for endpoints
+   * - suggested_element_type: always "operation" for routes
+   * - suggested_name: from node properties or id (kebab-case)
+   * - http_method: from properties.method or defaults to "GET"
+   * - http_path: from properties.path or defaults to "/"
+   * - handler_qualified_name: from properties.handler_name or empty string
+   * - source_symbol: from properties.symbol or empty string
+   * - source_start_line: from properties.start_line or 0
+   * - source_end_line: from properties.end_line or 0
+   *
+   * Downgrades confidence if required fields are missing.
+   *
+   * @private
+   */
+  async transformNodeToEndpoint(node, mapping, projectRoot) {
+    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;
+    let rawMethod;
+    typeof properties.method == "string" ? rawMethod = properties.method.toUpperCase() : (rawMethod = String(node.qualified_name ?? "").match(/^__route__([A-Z]+)__/)?.[1] ?? "GET", rawMethod === "ANY" && (rawMethod = "GET"));
+    const validMethods = new Set(VALID_HTTP_METHODS), isValidMethod = validMethods.has(rawMethod), httpMethod = isValidMethod ? rawMethod : "GET";
+    isValidMethod || handleWarning(`Node ${nodeId}: Invalid HTTP method`, [
+      `Method '${rawMethod}' is not a valid HTTP method`,
+      `Valid methods: ${Array.from(validMethods).join(", ")}`,
+      "Defaulting to GET - endpoint documentation may be inaccurate"
+    ]);
+    let httpPath;
+    typeof properties.path == "string" ? httpPath = properties.path : typeof node.name == "string" && node.name.startsWith("/") ? httpPath = node.name : (handleWarning(`Node ${nodeId}: Missing or invalid HTTP path`, [
+      `Expected string, got ${typeof properties.path}`,
+      "Defaulting to / - endpoint may be incomplete"
+    ]), httpPath = "/");
+    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)
+      try {
+        sourceFile = path.relative(projectRoot, sourceFile);
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        handleWarning(`Failed to compute relative path for ${nodeId}`, [
+          `Error: ${errorMsg}`,
+          "Using absolute file path instead of relative"
+        ]);
+      }
+    return {
+      source_file: sourceFile,
+      confidence,
+      suggested_layer: "api",
+      suggested_element_type: "operation",
+      suggested_name: suggestedName,
+      suggested_id_fragment: suggestedIdFragment,
+      http_method: httpMethod,
+      http_path: httpPath,
+      handler_qualified_name: handlerQualifiedName,
+      source_symbol: sourceSymbol,
+      source_start_line: sourceStartLine,
+      source_end_line: sourceEndLine,
+      source_reference: {
+        provenance: "extracted",
+        locations: sourceFile ? [
+          {
+            file: sourceFile,
+            symbol: sourceSymbol || void 0
+          }
+        ] : void 0
+      }
+    };
+  }
+  /**
+   * Check if a candidate (endpoint, service, or datastore) is in test code
+   *
+   * Applies the test_code_exclusion filtering rule from the analyzer mapping.
+   * If the configured regex pattern is invalid, warns the user once and falls back to defaults.
+   * Uses a one-shot flag to ensure the warning is only emitted once even if called in a loop.
+   *
+   * Accepts any object with a source_file property (structural typing), allowing it to work
+   * with EndpointCandidate, ServiceCandidate, DatastoreCandidate, and temporary objects.
+   *
+   * @private
+   */
+  /**
+   * 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) {
+    const name = String(node.name ?? node.id ?? "");
+    if (!name)
+      return null;
+    let sourceFile = String(node.file_path ?? "");
+    if (sourceFile && projectRoot)
+      try {
+        sourceFile = path.relative(projectRoot, sourceFile);
+      } catch {
+      }
+    if (!sourceFile)
+      return null;
+    const httpMethod = inferHttpMethodFromFunctionName(name), httpPath = inferHttpPathFromFunctionName(name), suggestedName = toKebabCase(name);
+    return {
+      source_file: sourceFile,
+      confidence: "low",
+      suggested_layer: "api",
+      suggested_element_type: "operation",
+      suggested_name: suggestedName,
+      suggested_id_fragment: suggestedName,
+      http_method: httpMethod,
+      http_path: httpPath,
+      handler_qualified_name: name,
+      source_symbol: name,
+      source_start_line: Number(node.properties?.start_line ?? 0),
+      source_end_line: Number(node.properties?.end_line ?? 0),
+      source_reference: {
+        provenance: "inferred",
+        locations: [{ file: sourceFile, symbol: name }]
+      }
+    };
+  }
+  isTestCode(candidate) {
+    const testCodeRule = this.mapper.getFilteringRules().find((rule) => rule.name === "test_code_exclusion" && rule.enabled);
+    if (!testCodeRule || !testCodeRule.pattern)
+      return CbmAnalyzer.DEFAULT_TEST_PATTERNS.some((pattern) => pattern.test(candidate.source_file));
+    try {
+      return new RegExp(testCodeRule.pattern).test(candidate.source_file);
+    } catch (error) {
+      if (!this.testCodePatternWarned) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        handleWarning("Invalid test_code_exclusion regex pattern in analyzer mapping", [
+          `Pattern: ${testCodeRule.pattern}`,
+          `Error: ${errorMsg}`,
+          "Falling back to default test code patterns"
+        ]), this.testCodePatternWarned = !0;
+      }
+      return CbmAnalyzer.DEFAULT_TEST_PATTERNS.some((pattern) => pattern.test(candidate.source_file));
+    }
+  }
+  /**
+   * Query for services/components in the indexed project
+   *
+   * Searches for application-layer nodes using the mapping-loader-driven pattern.
+   * For each node, evaluates all promotion_heuristics and records which fire in
+   * qualifying_heuristics. Drops candidates with zero qualifying heuristics (unless
+   * is_entry_point heuristic fires, adding it to qualifying_heuristics). Caps confidence
+   * at "medium" and excludes test files.
+   *
+   * @param projectRoot Absolute path to the project root
+   * @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);
+    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);
+      const version = await getCliVersion();
+      await client.initialize({
+        name: "dr-cli",
+        version
+      });
+      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);
+      }
+      if (applicationLabels.length === 0)
+        return handleWarning("No application-layer labels found in analyzer mapping", [
+          "Check that the analyzer is properly configured with application-layer node mappings",
+          "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 };
+      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);
+        if (!nodeMapping)
+          continue;
+        const promotionHeuristicNames = nodeMapping.promotion_heuristics || [];
+        for (const node of nodes) {
+          const candidate = await this.transformNodeToService(node, nodeMapping, projectRoot, promotionHeuristicNames);
+          candidate.qualifying_heuristics.length > 0 && !this.isTestCode(candidate) && candidates.push(candidate);
+        }
+      }
+      const seenFiles = /* @__PURE__ */ new Set(), deduped = candidates.filter((c) => c.source_file ? seenFiles.has(c.source_file) ? !1 : (seenFiles.add(c.source_file), !0) : !0);
+      return this.warnOnDuplicateIdFragments(deduped, (c) => c.suggested_id_fragment, (c) => c.source_symbol || c.source_file || "(unknown)"), deduped;
+    } finally {
+      client.close();
+    }
+  }
+  /**
+   * Transform a CBM graph node to a service candidate
+   *
+   * Evaluates all promotion heuristics against the node's properties and records
+   * which heuristics fire. Drops candidates where no heuristics fire (unless the
+   * is_entry_point heuristic fires, which adds it to qualifying_heuristics).
+   * Caps confidence at "medium".
+   *
+   * @private
+   */
+  async transformNodeToService(node, mapping, projectRoot, promotionHeuristicNames) {
+    const properties = node.properties ?? {}, suggestedName = toKebabCase(String(properties.name ?? node.name ?? node.id ?? "")), suggestedIdFragment = suggestedName;
+    let sourceFile = node.file_path ?? "";
+    if (sourceFile && projectRoot)
+      try {
+        sourceFile = path.relative(projectRoot, 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)")}`, [
+          `Error: ${errorMsg}`,
+          "Using absolute file path instead of relative"
+        ]);
+      }
+    const qualifiedName = String(properties.qualified_name ?? node.qualified_name ?? node.name ?? node.id ?? ""), fanIn = typeof properties.fan_in == "number" ? properties.fan_in : 0, fanOut = typeof properties.fan_out == "number" ? properties.fan_out : 0, qualifyingHeuristics = [];
+    let isEntryPoint = !1;
+    for (const heuristicName of promotionHeuristicNames) {
+      const heuristic = this.mapper.getHeuristic(heuristicName);
+      if (!heuristic) {
+        this.warnedHeuristics.has(heuristicName) || (this.warnedHeuristics.add(heuristicName), handleWarning(`Promotion heuristic "${heuristicName}" not found in analyzer mapping`, [
+          "Check the mapping configuration for typos",
+          `Available heuristics: ${getKnownHeuristicNames().join(", ")}`,
+          "This heuristic will be skipped for service promotion"
+        ]));
+        continue;
+      }
+      this.evaluateHeuristic(heuristic, node, sourceFile) && (qualifyingHeuristics.push(heuristicName), heuristicName === "is_entry_point" && (isEntryPoint = !0));
+    }
+    if (!(qualifyingHeuristics.length > 0 || isEntryPoint))
+      return {
+        suggested_layer: "application",
+        suggested_element_type: mapping.dr_element_type_promoted === "applicationcomponent" ? "applicationcomponent" : "applicationservice",
+        suggested_id_fragment: suggestedIdFragment,
+        suggested_name: suggestedName,
+        source_file: sourceFile,
+        source_symbol: String(properties.name ?? node.name ?? node.id ?? ""),
+        qualified_name: qualifiedName,
+        qualifying_heuristics: [],
+        confidence: "low",
+        fan_in: fanIn,
+        fan_out: fanOut
+      };
+    const confidence = capConfidence(mapping.confidence);
+    return {
+      suggested_layer: "application",
+      suggested_element_type: mapping.dr_element_type_promoted === "applicationcomponent" ? "applicationcomponent" : "applicationservice",
+      suggested_id_fragment: suggestedIdFragment,
+      suggested_name: suggestedName,
+      source_file: sourceFile,
+      source_symbol: String(properties.name ?? node.name ?? node.id ?? ""),
+      qualified_name: qualifiedName,
+      qualifying_heuristics: qualifyingHeuristics,
+      confidence,
+      fan_in: fanIn,
+      fan_out: fanOut
+    };
+  }
+  /**
+   * Evaluate a single heuristic against a node
+   *
+   * Checks if the heuristic's conditions are met based on the node's properties
+   * and file path. Unknown heuristics are logged with a warning rather than
+   * silently ignored, to support dynamic heuristics from cbm.json.
+   *
+   * Warnings for unknown heuristics are deduplicated - each heuristic name is warned
+   * about only once, even if evaluated against many nodes.
+   *
+   * @private
+   */
+  evaluateHeuristic(heuristic, node, sourceFile) {
+    const properties = node.properties ?? {}, result = evaluateHeuristic(heuristic, properties, sourceFile);
+    return heuristic.name && !getKnownHeuristicNames().includes(heuristic.name) && (this.warnedHeuristics.has(heuristic.name) || (handleWarning(`Unknown heuristic type: ${heuristic.name}`, [
+      "The heuristic is defined in cbm.json but not implemented in heuristic-utils.ts",
+      "This heuristic will be treated as not met (returning false)",
+      "Add support for this heuristic to evaluateHeuristic() if it should fire"
+    ]), this.warnedHeuristics.add(heuristic.name))), result;
+  }
+  /**
+   * Match a file path against a glob-like pattern
+   *
+   * @param filePath The file path to match
+   * @param pattern The glob pattern
+   * @returns True if the pattern matches, false otherwise
+   * @private
+   */
+  matchPattern(filePath, pattern) {
+    return matchPattern(filePath, pattern);
+  }
+  /**
+   * Query for datastores/databases inferred from code analysis
+   *
+   * Applies datastore_detection heuristic rules to aggregate signals by file/module.
+   * Matches import target names against import_patterns and function/symbol names against
+   * naming_indicators from the heuristic parameters. All candidates have confidence "low".
+   *
+   * @param projectRoot Absolute path to the project root
+   * @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);
+    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);
+      const version = await getCliVersion();
+      await client.initialize({
+        name: "dr-cli",
+        version
+      });
+      const datastoreHeuristic = this.mapper.getHeuristic("datastore_detection");
+      if (!datastoreHeuristic)
+        throw new CLIError("datastore_detection heuristic not found in analyzer", ErrorCategory.VALIDATION, [
+          "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);
+      let allNodes = [];
+      try {
+        const queryResponse = await client.invokeTool("query_graph", {
+          query: `
+          MATCH (n1)-[r:IMPORTS]->(n2)
+          RETURN DISTINCT n1 as node
+          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"));
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        handleWarning("query_graph tool failed; falling back to search_graph for datastore detection", [
+          `Error: ${errorMsg}`,
+          "Using search_graph will return ALL nodes instead of only IMPORTS-connected nodes",
+          "Datastore detection results may include false positives or be less accurate",
+          "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 node of allNodes) {
+        const filePath = node.file_path ?? "", importTargetName = String(node.label ?? node.properties?.name ?? node.id ?? "").toLowerCase();
+        let matchedImportPattern;
+        for (const pattern of importPatterns)
+          if (this.matchPattern(importTargetName, pattern)) {
+            matchedImportPattern = pattern;
+            break;
+          }
+        const nodeName = String(node.properties?.name ?? "").toLowerCase(), matchedIndicators = namingIndicators.filter((indicator) => nodeName.includes(indicator.toLowerCase()));
+        if (!matchedImportPattern && matchedIndicators.length === 0)
+          continue;
+        let datastoreName = this.inferDatastoreName(filePath, node, matchedImportPattern, importTargetName);
+        if (!datastoreName)
+          continue;
+        datastoreName = toKebabCase(datastoreName), datastoreSignals.has(datastoreName) ? datastoreFirstSource.get(datastoreName) !== importTargetName && handleWarning(`Multiple imports normalize to datastore name "${datastoreName}"`, [
+          `First: ${datastoreFirstSource.get(datastoreName)}`,
+          `Conflict: ${importTargetName}`,
+          'Use "dr add" with a custom name to distinguish them'
+        ]) : (datastoreSignals.set(datastoreName, []), datastoreFirstSource.set(datastoreName, importTargetName));
+        const signals = datastoreSignals.get(datastoreName);
+        let relativeFile = filePath;
+        if (filePath && projectRoot)
+          try {
+            relativeFile = path.relative(projectRoot, filePath);
+          } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            handleWarning("Failed to compute relative path in datastore detection", [
+              `File: ${filePath}`,
+              `Error: ${errorMsg}`,
+              "Using absolute file path instead of relative"
+            ]);
+          }
+        signals.push({
+          sourceFile: relativeFile,
+          importPattern: matchedImportPattern,
+          functionPatterns: matchedIndicators
+        });
+      }
+      const candidates = [], entriesArray = Array.from(datastoreSignals.entries());
+      for (const [datastoreName, signals] of entriesArray) {
+        const inferredFromMap = /* @__PURE__ */ new Map();
+        for (const signal of signals) {
+          inferredFromMap.has(signal.sourceFile) || inferredFromMap.set(signal.sourceFile, {
+            importPatterns: /* @__PURE__ */ new Set(),
+            functionPatterns: /* @__PURE__ */ new Set()
+          });
+          const entry = inferredFromMap.get(signal.sourceFile);
+          signal.importPattern && entry.importPatterns.add(signal.importPattern), signal.functionPatterns.forEach((fp) => entry.functionPatterns.add(fp));
+        }
+        let inferredFromMapEntries = Array.from(inferredFromMap.entries());
+        if (inferredFromMapEntries = inferredFromMapEntries.filter(([sourceFile]) => {
+          const tempCandidate = {
+            source_file: sourceFile
+          };
+          return !this.isTestCode(tempCandidate);
+        }), inferredFromMapEntries.length === 0)
+          continue;
+        const inferredFrom = inferredFromMapEntries.map(([sourceFile, evidence]) => ({
+          source_file: sourceFile,
+          import_pattern: Array.from(evidence.importPatterns).join(", ") || datastoreName,
+          function_patterns: Array.from(evidence.functionPatterns)
+        }));
+        candidates.push({
+          suggested_layer: "data-store",
+          suggested_name: datastoreName,
+          inferred_from: inferredFrom,
+          confidence: "low",
+          notes: `Inferred from ${inferredFrom.length} source file(s) based on datastore detection heuristics`
+        });
+      }
+      const browserStorageTypes = ["local-storage", "session-storage"], browserStorageSignals = /* @__PURE__ */ new Map();
+      try {
+        const storageResp = await client.invokeTool("query_graph", {
+          query: `
+          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'
+             OR n.file_path CONTAINS 'auth' OR n.file_path CONTAINS 'Auth'
+             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);
+          }
+        }
+      } catch {
+      }
+      for (const storageType of browserStorageTypes) {
+        const sourceFiles = browserStorageSignals.get(storageType);
+        if (!sourceFiles || sourceFiles.size === 0)
+          continue;
+        const accessPattern = storageType === "local-storage" ? "localStorage" : "sessionStorage", inferredFrom = Array.from(sourceFiles).filter((f) => !this.isTestCode({ source_file: f })).map((f) => ({
+          source_file: f,
+          import_pattern: accessPattern,
+          function_patterns: []
+        }));
+        inferredFrom.length > 0 && candidates.push({
+          suggested_layer: "data-store",
+          suggested_name: storageType,
+          inferred_from: inferredFrom,
+          confidence: "low",
+          notes: `Inferred from ${inferredFrom.length} source file(s) using browser ${accessPattern} (global API, no import required)`
+        });
+      }
+      return candidates;
+    } finally {
+      client.close();
+    }
+  }
+  /**
+   * Infer a datastore name from import target name, file path, node properties, or import pattern
+   *
+   * @private
+   */
+  inferDatastoreName(filePath, node, matchedPattern, importTargetName) {
+    if (importTargetName && matchedPattern && this.matchPattern(importTargetName, matchedPattern))
+      return importTargetName;
+    if (matchedPattern) {
+      const match = matchedPattern.match(/[a-z]+/i);
+      if (match)
+        return match[0];
+    }
+    const fileName = path.basename(filePath);
+    if (fileName.includes("migration") || fileName.includes("schema")) {
+      const match = fileName.match(/^([a-z0-9_-]+)/i);
+      if (match && match[1])
+        return match[1];
+    }
+    const nodeName = String(node.label ?? node.id ?? "");
+    if (nodeName) {
+      const nodeMapping = this.mapper.getNodeMapping(nodeName);
+      if (nodeMapping && nodeMapping.dr_layer !== "api" && nodeMapping.dr_layer !== "application" || nodeName.toLowerCase().includes("database") || nodeName.toLowerCase().includes("repository") || nodeName.toLowerCase().includes("datastore"))
+        return nodeName;
+    }
+  }
+  /**
+   * Query for callers of a specific function or symbol
+   *
+   * Delegates to trace_path MCP tool with direction="inbound" to find
+   * all functions that call the specified qualified name. Applies depth clamping
+   * (default 3, max 10) and transforms CBM response nodes into CallGraphNode objects
+   * using edge-type mappings from the analyzer.
+   *
+   * @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)
+   * @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");
+  }
+  /**
+   * Query for callees of a specific function or symbol
+   *
+   * Delegates to trace_path MCP tool with direction="outbound" to find
+   * all functions called by the specified qualified name. Applies depth clamping
+   * (default 3, max 10) and transforms CBM response nodes into CallGraphNode objects
+   * using edge-type mappings from the analyzer.
+   *
+   * @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)
+   * @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");
+  }
+  /**
+   * Cypher fallback for call graph traversal when trace_path is unavailable.
+   *
+   * Uses query_graph directly with CALLS-edge Cypher when trace_path returns a
+   * non-array nodes field (i.e. is not implemented in the binary).
+   *
+   * @private
+   */
+  async callGraphViaCypher(binaryPath, projectName, qualifiedName, direction, depth, projectRoot) {
+    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();
+    try {
+      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 obj = {};
+        return cols.forEach((col, i) => {
+          const key = col.includes(".") ? col.slice(col.lastIndexOf(".") + 1) : col;
+          obj[key] = row[i];
+        }), shapeCallGraphNode(obj, projectRoot);
+      });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return handleWarning("Cypher CALLS fallback failed \u2014 returning empty call graph", [
+        `Error: ${errorMsg}`,
+        "Neither trace_path nor query_graph is available for call graph traversal"
+      ]), [];
+    } finally {
+      client.close();
+    }
+  }
+  /**
+   * Internal helper to trace call paths in either direction
+   *
+   * Handles common logic for callers() and callees(): pre-flight checks,
+   * depth clamping, tool invocation, and response transformation.
+   *
+   * @private
+   */
+  async traceCallPath(projectRoot, qualifiedName, depth, direction) {
+    const status = await this.status(projectRoot);
+    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 clampedDepth = clampDepth(depth), client = new StdioClient();
+    try {
+      client.spawn(detection.binary_path);
+      const version = await getCliVersion();
+      await client.initialize({
+        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 = [];
+      for (const node of nodes) {
+        const nodeQualifiedName = node.qualified_name || node.id;
+        let callGraphNode = shapeCallGraphNode(node, projectRoot);
+        const nodeDepth = typeof node.depth == "number" ? node.depth : 0, edgeType = determineEdgeType(nodeDepth, edges, nodeQualifiedName, validEdgeTypes);
+        callGraphNode.edge_type = edgeType, callGraphNodes.push(callGraphNode);
+      }
+      return callGraphNodes;
+    } finally {
+      client.close();
+    }
+  }
+  /**
+   * Shape a single CBM graph node into a route object with defaults applied
+   *
+   * This is extracted to be testable - applies the defaulting logic used in verify()
+   * to ensure empty/missing properties are handled consistently.
+   *
+   * @param node Raw node from CBM graph search
+   * @returns Shaped route object with defaults applied
+   * @internal
+   */
+  shapeRoute(node) {
+    const properties = node.properties ?? {}, nodeName = String(node.name ?? node.id ?? "");
+    let httpMethod = "GET";
+    if (typeof properties.method == "string")
+      httpMethod = properties.method.toUpperCase();
+    else {
+      const extracted = String(node.qualified_name ?? "").match(/^__route__([A-Z]+)__/)?.[1] ?? "";
+      extracted && VALID_HTTP_METHODS.includes(extracted) && (httpMethod = extracted);
+    }
+    const httpPath = typeof properties.path == "string" ? properties.path : typeof node.name == "string" && node.name.startsWith("/") ? node.name : "/", handler = String(properties.handler_name ?? ""), sourceFile = node.file_path ?? "", sourceSymbol = String(properties.symbol ?? properties.source_symbol ?? properties.handler_name ?? "");
+    return {
+      id: sourceFile && sourceSymbol ? `${sourceFile}:${sourceSymbol}` : nodeName || node.id || "(unknown)",
+      http_method: httpMethod,
+      http_path: httpPath,
+      handler,
+      source_file: sourceFile,
+      source_symbol: sourceSymbol
+    };
+  }
+  /**
+   * Verify that graph-discovered routes align with model endpoints
+   *
+   * Queries the CBM graph for Route nodes, shapes them via the Route mapping,
+   * and delegates comparison to VerifyEngine. Entirely read-only.
+   *
+   * @param projectRoot Absolute path to the project root
+   * @param options Verification options
+   * @returns Comprehensive verification report
+   * @throws CLIError if project not indexed or analyzer not installed
+   */
+  async verify(projectRoot, options) {
+    const status = await this.status(projectRoot);
+    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 routeMapping = this.mapper.getNodeMapping("Route");
+    if (!routeMapping)
+      throw new CLIError("Route mapping not found in analyzer", ErrorCategory.VALIDATION, ["Run `npm run build:spec` to recompile the analyzer artifacts"]);
+    const client = new StdioClient();
+    try {
+      client.spawn(detection.binary_path);
+      const version = await getCliVersion();
+      await client.initialize({
+        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;
+      return await engine.computeReport(projectRoot, routes, options, analyzerName, indexMeta);
+    } finally {
+      client.close();
+    }
+  }
+}
+export {
+  CbmAnalyzer,
+  SOURCE_CODE_EXT_RE
+};
+//# sourceMappingURL=cbm-analyzer.js.map