septum 0.1.4 → 0.1.6

package/src/core/resolver/vertical-slice-tracer.ts

@@ -1,285 +1,323 @@
-import type {
-  ExecutionChainNode,
-  VerticalSliceRecord,
-  VerticalSliceTraceResponse,
-} from "../../types/index.ts";
-import type { SeptumRepository } from "../database/repository.ts";
-import { CallGraphTracer } from "./call-graph-tracer.ts";
-import { SemanticSliceExtractorRegistry } from "../parser/extractors/registry.ts";
-import { TopologyDetector } from "../discovery/topology-detector.ts";
-
-export class VerticalSliceTracer {
-  constructor(private repo: SeptumRepository, private projectRoot: string = process.cwd()) {}
-
-  /**
-   * Trace an end-to-end vertical slice from route/action/intent query.
-   * Examples of queries:
-   *  - "POST /orders/{id}/status"
-   *  - "/orders/{id}/status"
-   *  - "OrderController@updateStatus"
-   *  - "OrderController::updateStatus"
-   *  - "orders.update_status"
-   *  - "createOrder"
-   *  - "Ubah status order di dashboard"
-   */
-  public trace(rawQuery: string): VerticalSliceTraceResponse {
-    const trimmed = rawQuery.trim();
-    const lowerTrimmed = trimmed.toLowerCase();
-    let allSlices = this.repo.getAllVerticalSlices();
-
-    // Lazy on-demand fallback: If no slices cataloged, extract framework routes or trace call-graph
-    const hasCatalogData = typeof (this.repo as any).getAllDomains === "function" && this.repo.getAllDomains().length > 0;
-    if (allSlices.length === 0 && hasCatalogData) {
-      try {
-        const topology = TopologyDetector.detect(this.projectRoot);
-        const semanticSlices = SemanticSliceExtractorRegistry.extractAllSlicesSync(
-          this.projectRoot,
-          topology.framework
-        );
-        if (semanticSlices.length > 0) {
-          for (const s of semanticSlices) {
-            this.repo.upsertVerticalSlice(s);
-          }
-          allSlices = this.repo.getAllVerticalSlices();
-        } else {
-          const tracer = new CallGraphTracer(this.repo, this.projectRoot);
-          const traced = tracer.traceAllSlices();
-          if (traced.length > 0) {
-            for (const s of traced) {
-              this.repo.upsertVerticalSlice(s);
-            }
-            allSlices = this.repo.getAllVerticalSlices();
-          }
-        }
-      } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[Septum Slice Warning] Failed on-demand trace of vertical slices: ${msg}`);
-      }
-    }
-
-    if (allSlices.length === 0) {
-      return {
-        query: trimmed,
-        found: false,
-        message: "No vertical slices cataloged. Run 'septum ingest' to extract framework routes and MVC slices.",
-      };
-    }
-
-    // 1. Exact HTTP Method + URI match: "POST /orders/{id}/status" or "POST /api/orders"
-    const methodUriMatch = trimmed.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s]+)$/i);
-    if (methodUriMatch) {
-      const httpMethod = methodUriMatch[1].toUpperCase();
-      const uri = methodUriMatch[2].toLowerCase();
-      const exact = allSlices.find(
-        (s) =>
-          s.http_method.toUpperCase() === httpMethod &&
-          (s.route_uri.toLowerCase() === uri || this.urisMatch(s.route_uri, uri))
-      );
-      if (exact) {
-        return this.formatSuccessResponse(trimmed, exact, "exact");
-      }
-    }
-
-    // 2. URI-only match: "/orders" or "orders/{id}"
-    const uriMatches = allSlices.filter((s) => s.route_uri.toLowerCase() === lowerTrimmed);
-    if (uriMatches.length > 0) {
-      if (uriMatches.length === 1) {
-        return this.formatSuccessResponse(trimmed, uriMatches[0], "exact");
-      }
-      // Multiple matches (e.g. GET /orders and POST /orders) -> return primary with alternatives
-      return this.formatSuccessResponse(trimmed, uriMatches[0], "exact", uriMatches.slice(1));
-    }
-
-    // 3. Named Route match: "orders.status.update" or "admin.users.index"
-    const nameMatch = allSlices.find(
-      (s) => s.route_name && s.route_name.toLowerCase() === lowerTrimmed
-    );
-    if (nameMatch) {
-      return this.formatSuccessResponse(trimmed, nameMatch, "exact");
-    }
-
-    // 3b. Omni-Trigger Match: "JOB ProcessOrderJob", "job:ProcessOrderJob", "CLI order:cleanup", "EVENT OrderPlacedListener"
-    const omniTriggerMatch = trimmed.match(/^(JOB|CLI|EVENT)\s+([A-Za-z0-9_:\-]+)$/i);
-    if (omniTriggerMatch) {
-      const triggerKind = omniTriggerMatch[1].toUpperCase();
-      const targetName = omniTriggerMatch[2].toLowerCase();
-      const exact = allSlices.find(
-        (s) =>
-          s.http_method.toUpperCase() === triggerKind &&
-          (s.controller_class.toLowerCase() === targetName ||
-            s.route_uri.toLowerCase() === targetName ||
-            s.route_uri.toLowerCase() === `${triggerKind.toLowerCase()}:${targetName}`)
-      );
-      if (exact) {
-        return this.formatSuccessResponse(trimmed, exact, "exact");
-      }
-    }
-
-    // 4. Controller@Action match: "OrderController@updateStatus" or "OrderController"
-    const controllerActionMatch = trimmed.match(/^([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?$/);
-    if (controllerActionMatch) {
-      const [, ctrl, act] = controllerActionMatch;
-      const lowerCtrl = ctrl.toLowerCase();
-      const lowerAct = act ? act.toLowerCase() : undefined;
-
-      const exact = allSlices.find((s) => {
-        const ctrlMatch = s.controller_class.toLowerCase() === lowerCtrl || s.controller_class.toLowerCase().endsWith(lowerCtrl);
-        if (!ctrlMatch) return false;
-        if (lowerAct) return s.action_name.toLowerCase() === lowerAct;
-        return true;
-      });
-      if (exact) {
-        return this.formatSuccessResponse(trimmed, exact, "exact");
-      }
-    }
-
-    // 5. Symbol Match in Execution Chain or Action Name (e.g. "createOrder", "CreateOrderUseCase", "OrderController")
-    const symbolMatch = allSlices.find((s) => {
-      if (s.action_name.toLowerCase() === lowerTrimmed) return true;
-      if (s.controller_class.toLowerCase() === lowerTrimmed) return true;
-      if (s.execution_chain_json) {
-        try {
-          const chain: ExecutionChainNode[] = JSON.parse(s.execution_chain_json);
-          return chain.some(
-            (node) =>
-              node.symbol.toLowerCase() === lowerTrimmed ||
-              node.symbol.toLowerCase().includes(lowerTrimmed) ||
-              (node.file && node.file.toLowerCase().includes(lowerTrimmed))
-          );
-        } catch {
-          return false;
-        }
-      }
-      return false;
-    });
-    if (symbolMatch) {
-      return this.formatSuccessResponse(trimmed, symbolMatch, "inferred");
-    }
-
-    // 6. Semantic / Token Scoring for Natural Language (e.g. "Ubah status order di dashboard")
-    const tokens = this.tokenize(trimmed);
-    const scoredSlices = allSlices
-      .map((slice) => {
-        let score = 0;
-        const textCorpus = [
-          slice.route_uri,
-          slice.route_name || "",
-          slice.controller_class,
-          slice.action_name,
-          slice.execution_chain_json || "",
-        ].join(" ").toLowerCase();
-
-        for (const token of tokens) {
-          if (textCorpus.includes(token)) {
-            score += 1;
-            if (slice.route_uri.toLowerCase().includes(token)) score += 2;
-            if (slice.action_name.toLowerCase().includes(token)) score += 2;
-          }
-        }
-        return { slice, score };
-      })
-      .filter((item) => item.score > 0)
-      .sort((a, b) => b.score - a.score);
-
-    if (scoredSlices.length > 0) {
-      const primary = scoredSlices[0].slice;
-      const alternatives = scoredSlices.slice(1, 4).map((item) => item.slice);
-      return this.formatSuccessResponse(trimmed, primary, "inferred", alternatives);
-    }
-
-    return {
-      query: trimmed,
-      found: false,
-      alternatives: allSlices.slice(0, 5).map((s) => ({
-        method: s.http_method,
-        uri: s.route_uri,
-        controller: s.controller_class,
-        action: s.action_name,
-      })),
-      message: `No vertical slice found matching query '${trimmed}'.`,
-    };
-  }
-
-  private urisMatch(uriA: string, uriB: string): boolean {
-    const normA = uriA.toLowerCase().replace(/\{[^}]+\}/g, ":param");
-    const normB = uriB.toLowerCase().replace(/\{[^}]+\}/g, ":param").replace(/:[a-zA-Z0-9_]+/g, ":param");
-    return normA === normB;
-  }
-
-  private tokenize(str: string): string[] {
-    return str
-      .replace(/([a-z])([A-Z])/g, "$1 $2")
-      .toLowerCase()
-      .replace(/[^a-z0-9_]+/g, " ")
-      .split(/\s+/)
-      .filter((t) => t.length > 2 && !["ubah", "di", "dan", "yang", "the", "for", "and"].includes(t));
-  }
-
-  private formatSuccessResponse(
-    query: string,
-    record: VerticalSliceRecord,
-    confidence: "exact" | "inferred" = "exact",
-    alternatives?: VerticalSliceRecord[]
-  ): VerticalSliceTraceResponse {
-    let chain: ExecutionChainNode[] = [];
-    if (record.execution_chain_json) {
-      try {
-        chain = JSON.parse(record.execution_chain_json);
-      } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[Septum Slice Error] Corrupted execution chain JSON for slice ${record.id}: ${msg}`);
-      }
-    }
-
-    let message = `Vertical slice resolved (${confidence}): ${record.http_method} ${record.route_uri} -> ${record.controller_class}@${record.action_name}`;
-    if (chain.length > 0) {
-      const stageLines = chain.map((node) => {
-        const stageLabel = `[${node.stage.toUpperCase()}]`.padEnd(14, " ");
-        const loc = node.file ? ` (${node.file}${node.line ? `:${node.line}` : ""})` : "";
-        let extra = "";
-        if (node.table) {
-          extra += ` [table: ${node.table}]`;
-        }
-        if (node.columns_summary) {
-          extra += ` {${node.columns_summary}}`;
-        }
-        if (node.guards && node.guards.length > 0 && node.stage !== "guard") {
-          extra += ` [guards: ${node.guards.join(", ")}]`;
-        }
-        if (node.mutations && node.mutations.length > 0 && node.stage !== "side_effect") {
-          extra += ` [mutates: ${node.mutations.join(", ")}]`;
-        }
-        if (node.transactions && node.stage !== "transaction") {
-          extra += ` [tx: active]`;
-        }
-        return `${stageLabel} ${node.symbol}${loc}${extra}`;
-      });
-      message = `=== VERTICAL SLICE TRACE (${confidence.toUpperCase()}) ===\n` + stageLines.join("\n");
-    }
-
-    return {
-      query,
-      found: true,
-      confidence,
-      is_exact_match: confidence === "exact",
-      architecture_style: record.architecture_style,
-      entrypoint: {
-        method: record.http_method,
-        uri: record.route_uri,
-        name: record.route_name,
-        controller: record.controller_class,
-        action: record.action_name,
-        file: record.controller_file,
-        line: record.controller_line,
-      },
-      chain,
-      alternatives: alternatives?.map((a) => ({
-        method: a.http_method,
-        uri: a.route_uri,
-        controller: a.controller_class,
-        action: a.action_name,
-      })),
-      message,
-    };
-  }
-}
+import type {
+  ExecutionChainNode,
+  VerticalSliceRecord,
+  VerticalSliceTraceResponse,
+} from "../../types/index.ts";
+import type { SeptumRepository } from "../database/repository.ts";
+import { CallGraphTracer } from "./call-graph-tracer.ts";
+import { SemanticSliceExtractorRegistry } from "../parser/extractors/registry.ts";
+import { TopologyDetector } from "../discovery/topology-detector.ts";
+
+export class VerticalSliceTracer {
+  constructor(private repo: SeptumRepository, private projectRoot: string = process.cwd()) {}
+
+  /**
+   * Trace an end-to-end vertical slice from route/action/intent query.
+   * Examples of queries:
+   *  - "POST /orders/{id}/status"
+   *  - "/orders/{id}/status"
+   *  - "OrderController@updateStatus"
+   *  - "OrderController::updateStatus"
+   *  - "orders.update_status"
+   *  - "createOrder"
+   *  - "Ubah status order di dashboard"
+   */
+  public trace(rawQuery: string, maxDepth: number = 5): VerticalSliceTraceResponse {
+    const effectiveMaxDepth = Math.min(Math.max(Math.trunc(maxDepth || 5), 1), 8);
+    const trimmed = rawQuery.trim();
+    const lowerTrimmed = trimmed.toLowerCase();
+    let allSlices = this.repo.getAllVerticalSlices();
+
+    // Lazy on-demand fallback: If no slices cataloged, extract framework routes or trace call-graph
+    const topology = TopologyDetector.detect(this.projectRoot);
+    const isSupportedFramework = ["laravel", "express", "nestjs", "fastify"].includes(topology.framework);
+    const hasCatalogData = typeof (this.repo as any).getAllDomains === "function" && this.repo.getAllDomains().length > 0;
+    if (allSlices.length === 0 && (hasCatalogData || isSupportedFramework)) {
+      try {
+        const semanticSlices = SemanticSliceExtractorRegistry.extractAllSlicesSync(
+          this.projectRoot,
+          topology.framework
+        );
+        if (semanticSlices.length > 0) {
+          for (const s of semanticSlices) {
+            this.repo.upsertVerticalSlice(s);
+          }
+          allSlices = this.repo.getAllVerticalSlices();
+        } else {
+          const tracer = new CallGraphTracer(this.repo, this.projectRoot);
+          const traced = tracer.traceAllSlices(effectiveMaxDepth);
+          if (traced.length > 0) {
+            for (const s of traced) {
+              this.repo.upsertVerticalSlice(s);
+            }
+            allSlices = this.repo.getAllVerticalSlices();
+          }
+        }
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[Septum Slice Warning] Failed on-demand trace of vertical slices: ${msg}`);
+      }
+    }
+
+    if (allSlices.length === 0) {
+      return {
+        query: trimmed,
+        found: false,
+        max_depth_applied: effectiveMaxDepth,
+        message: "No vertical slices cataloged. Run 'septum ingest' to extract framework routes and MVC slices.",
+      };
+    }
+
+    // 1. Exact HTTP Method + URI match: "POST /orders/{id}/status" or "POST /api/orders"
+    const methodUriMatch = trimmed.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s]+)$/i);
+    if (methodUriMatch) {
+      const httpMethod = methodUriMatch[1].toUpperCase();
+      const uri = methodUriMatch[2].toLowerCase();
+      const exact = allSlices.find(
+        (s) =>
+          s.http_method.toUpperCase() === httpMethod &&
+          (s.route_uri.toLowerCase() === uri || this.urisMatch(s.route_uri, uri))
+      );
+      if (exact) {
+        return this.formatSuccessResponse(trimmed, exact, "exact", undefined, effectiveMaxDepth);
+      }
+    }
+
+    // 2. URI-only match: "/orders" or "orders/{id}"
+    const uriMatches = allSlices.filter((s) => s.route_uri.toLowerCase() === lowerTrimmed);
+    if (uriMatches.length > 0) {
+      if (uriMatches.length === 1) {
+        return this.formatSuccessResponse(trimmed, uriMatches[0], "exact", undefined, effectiveMaxDepth);
+      }
+      // Multiple matches (e.g. GET /orders and POST /orders) -> return primary with alternatives
+      return this.formatSuccessResponse(trimmed, uriMatches[0], "exact", uriMatches.slice(1), effectiveMaxDepth);
+    }
+
+    // 3. Named Route match: "orders.status.update" or "admin.users.index"
+    const nameMatch = allSlices.find(
+      (s) => s.route_name && s.route_name.toLowerCase() === lowerTrimmed
+    );
+    if (nameMatch) {
+      return this.formatSuccessResponse(trimmed, nameMatch, "exact", undefined, effectiveMaxDepth);
+    }
+
+    // 3b. Omni-Trigger Match: "JOB ProcessOrderJob", "job:ProcessOrderJob", "CLI order:cleanup", "EVENT OrderPlacedListener"
+    const omniTriggerMatch = trimmed.match(/^(JOB|CLI|EVENT)\s+([A-Za-z0-9_:\-]+)$/i);
+    if (omniTriggerMatch) {
+      const triggerKind = omniTriggerMatch[1].toUpperCase();
+      const targetName = omniTriggerMatch[2].toLowerCase();
+      const exact = allSlices.find(
+        (s) =>
+          s.http_method.toUpperCase() === triggerKind &&
+          (s.controller_class.toLowerCase() === targetName ||
+            s.route_uri.toLowerCase() === targetName ||
+            s.route_uri.toLowerCase() === `${triggerKind.toLowerCase()}:${targetName}`)
+      );
+      if (exact) {
+        return this.formatSuccessResponse(trimmed, exact, "exact", undefined, effectiveMaxDepth);
+      }
+    }
+
+    // 4. Controller@Action match: "OrderController@updateStatus" or "OrderController"
+    const controllerActionMatch = trimmed.match(/^([A-Za-z0-9_\\/.]+?)(?:(?:@|::)([A-Za-z0-9_]+))?$/);
+    if (controllerActionMatch) {
+      const [, rawCtrl, act] = controllerActionMatch;
+      const ctrl = rawCtrl.split(/[\\/]/).pop()?.replace(/\.(php|ts|js)$/i, "") || rawCtrl;
+      const lowerCtrl = ctrl.toLowerCase();
+      const lowerAct = act ? act.toLowerCase() : undefined;
+
+      const exact = allSlices.find((s) => {
+        const sCtrlLower = s.controller_class.toLowerCase();
+        const ctrlMatch =
+          sCtrlLower === lowerCtrl ||
+          sCtrlLower.endsWith(`\\${lowerCtrl}`) ||
+          sCtrlLower.endsWith(`/${lowerCtrl}`);
+        if (!ctrlMatch) return false;
+        if (lowerAct) return s.action_name.toLowerCase() === lowerAct;
+        if (!act && !lowerCtrl.endsWith("controller") && sCtrlLower !== lowerCtrl) {
+          return false;
+        }
+        return true;
+      });
+      if (exact) {
+        return this.formatSuccessResponse(trimmed, exact, "exact", undefined, effectiveMaxDepth);
+      }
+    }
+
+    // 5. Symbol Match in Execution Chain or Action Name (e.g. "createOrder", "CreateOrderUseCase", "OrderController")
+    const symbolMatch = allSlices.find((s) => {
+      if (s.action_name.toLowerCase() === lowerTrimmed) return true;
+      if (s.controller_class.toLowerCase() === lowerTrimmed) return true;
+      if (s.execution_chain_json) {
+        try {
+          const chain: ExecutionChainNode[] = JSON.parse(s.execution_chain_json);
+          return chain.some(
+            (node) =>
+              node.symbol.toLowerCase() === lowerTrimmed ||
+              node.symbol.toLowerCase().includes(lowerTrimmed) ||
+              (node.file && node.file.toLowerCase().includes(lowerTrimmed))
+          );
+        } catch {
+          return false;
+        }
+      }
+      return false;
+    });
+    if (symbolMatch) {
+      return this.formatSuccessResponse(trimmed, symbolMatch, "inferred", undefined, effectiveMaxDepth);
+    }
+
+    // 6. Semantic / Token Scoring for Natural Language (e.g. "Ubah status order di dashboard")
+    const tokens = this.tokenize(trimmed);
+    const scoredSlices = allSlices
+      .map((slice) => {
+        let score = 0;
+        const textCorpus = [
+          slice.route_uri,
+          slice.route_name || "",
+          slice.controller_class,
+          slice.action_name,
+          slice.execution_chain_json || "",
+        ].join(" ").toLowerCase();
+
+        for (const token of tokens) {
+          if (textCorpus.includes(token)) {
+            score += 1;
+            if (slice.route_uri.toLowerCase().includes(token)) score += 2;
+            if (slice.action_name.toLowerCase().includes(token)) score += 2;
+          }
+        }
+        return { slice, score };
+      })
+      .filter((item) => item.score > 0)
+      .sort((a, b) => b.score - a.score);
+
+    if (scoredSlices.length > 0) {
+      const primary = scoredSlices[0].slice;
+      const alternatives = scoredSlices.slice(1, 4).map((item) => item.slice);
+      return this.formatSuccessResponse(trimmed, primary, "inferred", alternatives, effectiveMaxDepth);
+    }
+
+    return {
+      query: trimmed,
+      found: false,
+      max_depth_applied: effectiveMaxDepth,
+      alternatives: allSlices.slice(0, 5).map((s) => ({
+        method: s.http_method,
+        uri: s.route_uri,
+        controller: s.controller_class,
+        action: s.action_name,
+      })),
+      message: `No vertical slice found matching query '${trimmed}'.`,
+    };
+  }
+
+  private urisMatch(uriA: string, uriB: string): boolean {
+    const normA = uriA
+      .toLowerCase()
+      .replace(/\{[^}]+\}/g, ":param")
+      .replace(/:[a-zA-Z0-9_]+/g, ":param");
+    const normB = uriB
+      .toLowerCase()
+      .replace(/\{[^}]+\}/g, ":param")
+      .replace(/:[a-zA-Z0-9_]+/g, ":param");
+    return normA === normB;
+  }
+
+  private tokenize(str: string): string[] {
+    return str
+      .replace(/([a-z])([A-Z])/g, "$1 $2")
+      .toLowerCase()
+      .replace(/[^a-z0-9_]+/g, " ")
+      .split(/\s+/)
+      .filter((t) => t.length > 2 && !["ubah", "di", "dan", "yang", "the", "for", "and"].includes(t));
+  }
+
+  private formatSuccessResponse(
+    query: string,
+    record: VerticalSliceRecord,
+    confidence: "exact" | "inferred" = "exact",
+    alternatives?: VerticalSliceRecord[],
+    effectiveMaxDepth: number = 5
+  ): VerticalSliceTraceResponse {
+    let chain: ExecutionChainNode[] = [];
+    if (record.execution_chain_json) {
+      try {
+        chain = JSON.parse(record.execution_chain_json);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[Septum Slice Error] Corrupted execution chain JSON for slice ${record.id}: ${msg}`);
+      }
+    }
+
+    if (
+      chain.length < effectiveMaxDepth &&
+      record.controller_file &&
+      typeof (this.repo as any).getAllFiles === "function"
+    ) {
+      try {
+        const callGraphTracer = new CallGraphTracer(this.repo, this.projectRoot);
+        chain = callGraphTracer.expandChainFromFile(
+          record.controller_file,
+          chain,
+          effectiveMaxDepth
+        );
+      } catch {
+        // Ignore expansion errors on mock/partial repositories
+      }
+    }
+
+    let message = `Vertical slice resolved (${confidence}): ${record.http_method} ${record.route_uri} -> ${record.controller_class}@${record.action_name}`;
+    if (chain.length > 0) {
+      const stageLines = chain.map((node) => {
+        const stageLabel = `[${node.stage.toUpperCase()}]`.padEnd(14, " ");
+        const loc = node.file ? ` (${node.file}${node.line ? `:${node.line}` : ""})` : "";
+        let extra = "";
+        if (node.table) {
+          extra += ` [table: ${node.table}]`;
+        }
+        if (node.columns_summary) {
+          extra += ` {${node.columns_summary}}`;
+        }
+        if (node.guards && node.guards.length > 0 && node.stage !== "guard") {
+          extra += ` [guards: ${node.guards.join(", ")}]`;
+        }
+        if (node.mutations && node.mutations.length > 0 && node.stage !== "side_effect") {
+          extra += ` [mutates: ${node.mutations.join(", ")}]`;
+        }
+        if (node.transactions && node.stage !== "transaction") {
+          extra += ` [tx: active]`;
+        }
+        return `${stageLabel} ${node.symbol}${loc}${extra}`;
+      });
+      message = `=== VERTICAL SLICE TRACE (${confidence.toUpperCase()}) ===\n` + stageLines.join("\n");
+    }
+
+    return {
+      query,
+      found: true,
+      confidence,
+      is_exact_match: confidence === "exact",
+      architecture_style: record.architecture_style,
+      max_depth_applied: effectiveMaxDepth,
+      entrypoint: {
+        method: record.http_method,
+        uri: record.route_uri,
+        name: record.route_name,
+        controller: record.controller_class,
+        action: record.action_name,
+        file: record.controller_file,
+        line: record.controller_line,
+      },
+      chain,
+      slice: chain,
+      alternatives: alternatives?.map((a) => ({
+        method: a.http_method,
+        uri: a.route_uri,
+        controller: a.controller_class,
+        action: a.action_name,
+      })),
+      message,
+    };
+  }
+}