@mrclrchtr/supi-code-intelligence 2.0.5 → 2.1.0

package/src/tool/orientation/orchestrate.ts

@@ -19,6 +19,7 @@ import type {
   OrientationTarget,
   OrientationUseCaseResult,
 } from "../../ui/markdown/types.ts";
+import { assembleOrientationDetails } from "../result/orientation.ts";
 import { type RenderedOrientationSection, renderOrientationResult } from "./markdown.ts";
 
 const DEFAULT_TARGET_SECTIONS: OrientationSection[] = ["defs", "docs", "diagnostics"];
@@ -59,15 +60,13 @@ async function executeOrientationContext(
     lspService: deps.lspService,
   });
 
-  const details: ContextDetails = {
+  const details: ContextDetails = assembleOrientationDetails({
     confidence: result.details.confidence,
-    task: null,
     focusTarget: input.focus ?? null,
-    requestedSections: [],
     renderedSections: ["orientation"],
     omittedCount: result.details.omittedCount,
     nextQueries: result.details.nextQueries,
-  };
+  });
 
   return {
     content: result.content,
@@ -107,15 +106,13 @@ async function executeTargetOrientation(
       ? "structural"
       : "unavailable";
 
-  const details: ContextDetails = {
+  const details: ContextDetails = assembleOrientationDetails({
     confidence,
-    task: null,
     focusTarget,
     requestedSections,
     renderedSections: sections.map((section) => section.key),
-    omittedCount: 0,
     nextQueries: buildNextQueries(input.target, deps.cwd),
-  };
+  });
 
   return {
     content: renderOrientationResult({

package/src/tool/orientation/precise-target.ts

@@ -4,14 +4,18 @@
  * Handles targetId expansion, coordinate-based symbol resolution, and
  * running the use-case layer for a resolved symbol target. Shared by
  * the main code_orientation executor.
+ *
+ * Uses the session target workflow (deep seam) instead of ad-hoc
+ * expandTargetId / executeResolveService calls.
  */
 
 import { relative } from "node:path";
-import { executeResolveService } from "../../analysis/target/service.ts";
+import type { TargetWorkflowOutcome } from "../../session/session.ts";
 import type { TargetStoreEntry } from "../../session/target-store.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx, ContextDetails } from "../../types/index.ts";
 import { orientationCoordinateRules } from "../infra/cross-field.ts";
 import { unavailableContextDetails } from "../infra/error-results.ts";
+import { assembleOrientationDetails } from "../result/orientation.ts";
 import { prepareOrientationDeps } from "./deps.ts";
 import type { CodeOrientationToolParams } from "./execute.ts";
 import { executeOrientation } from "./orchestrate.ts";
@@ -27,29 +31,57 @@ export interface PreciseTarget {
 
 /**
  * Outcome of precise-target resolution in code_orientation.
- *
- * {@link resolvePreciseTarget} returns this discriminated union instead
- * of {@link CodeIntelResult} | null so callers can't silently fall through
- * on a bug that produces null unintentionally.
  */
 export type PreciseTargetOutcome =
   | { kind: "resolved"; result: CodeIntelResult }
   | { kind: "fallthrough" };
 
+/** Orientation target-workflow policy: file-level not for precise, name anchor not required. */
+const ORIENTATION_TARGET_POLICY = {
+  fileLevelAllowed: false,
+  nameAnchorRequired: false,
+  waitForSemantic: true,
+} as const;
+
 /**
  * Resolve a precise target ({@link CodeOrientationToolParams.targetId}
  * wins over focus/coordinates), then run symbol-centered orientation
  * sections. Falls through to orientation-mode when both targetId
  * expansion and coordinate resolution produce no target.
  */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: layered resolution + disambiguation + section building stays together for clarity
 export async function resolvePreciseTarget(
   params: CodeOrientationToolParams,
   ctx: CodeIntelToolExecCtx,
   hasCoords: boolean,
 ): Promise<PreciseTargetOutcome> {
+  // ── Deep seam: resolve through session target workflow ──
   if (params.targetId !== undefined && params.targetId !== null) {
-    const targetIdOutcome = await resolveTargetIdTarget(params, ctx, hasCoords);
-    if (targetIdOutcome.kind === "resolved") return targetIdOutcome;
+    const outcome = await ctx.session.resolveTarget(
+      {
+        targetId: params.targetId,
+        file: hasCoords ? params.focus : undefined,
+        line: hasCoords ? params.line : undefined,
+        character: hasCoords ? params.character : undefined,
+      },
+      ORIENTATION_TARGET_POLICY,
+    );
+    if (outcome.kind === "resolved") {
+      const precise: PreciseTarget = {
+        entry: outcome.entry,
+        notes: outcome.notes,
+      };
+      return wrapOutcome(await runWithOrientationTarget(params, ctx, precise));
+    }
+    if (outcome.kind === "invalid-input" || outcome.kind === "unavailable") {
+      return wrapOutcome({
+        content: `**Error:** ${outcome.kind === "invalid-input" ? outcome.message : outcome.reason}`,
+        details: unavailableContextDetails([
+          "Verify the `targetId` is valid and from this session",
+          "Re-resolve with `code_resolve` to get a fresh targetId",
+        ]),
+      });
+    }
   }
 
   if (hasCoords) {
@@ -60,36 +92,6 @@ export async function resolvePreciseTarget(
   return { kind: "fallthrough" };
 }
 
-/** Resolve a targetId-supplied precise target, or fallthrough. */
-async function resolveTargetIdTarget(
-  params: CodeOrientationToolParams,
-  ctx: CodeIntelToolExecCtx,
-  hasCoords: boolean,
-): Promise<PreciseTargetOutcome> {
-  const expansion = ctx.session.expandTargetId(params);
-  if (expansion.kind === "error") {
-    return wrapOutcome({
-      content: expansion.message,
-      details: unavailableContextDetails([
-        "Verify the `targetId` is valid and from this session",
-        "Re-resolve with `code_resolve` to get a fresh targetId",
-      ]),
-    });
-  }
-  if (expansion.kind !== "ok") return { kind: "fallthrough" };
-
-  const notes: string[] = [];
-  if (params.focus || hasCoords) {
-    notes.push(
-      "_Note: `targetId` takes precedence over the supplied focus/coordinates; focus and coordinates were ignored._",
-    );
-  }
-
-  return wrapOutcome(
-    await runWithOrientationTarget(params, ctx, { entry: expansion.entry, notes }),
-  );
-}
-
 /** Resolve a focus+coordinate-supplied precise target, or fallthrough. */
 async function resolveCoordinateTarget(
   params: CodeOrientationToolParams,
@@ -105,39 +107,42 @@ async function resolveCoordinateTarget(
     });
   }
 
-  const resolveResult = await executeResolveService(
+  const outcome = await ctx.session.resolveTarget(
     { file: params.focus, line: params.line, character: params.character },
-    ctx.session,
+    ORIENTATION_TARGET_POLICY,
   );
 
-  if (resolveResult.kind === "error") {
+  if (outcome.kind === "resolved") {
+    return wrapOutcome(
+      await runWithOrientationTarget(params, ctx, { entry: outcome.entry, notes: outcome.notes }),
+    );
+  }
+
+  if (outcome.kind === "disambiguation") {
+    return wrapOutcome(disambiguationResult(outcome));
+  }
+
+  if (outcome.kind === "invalid-input") {
     return wrapOutcome({
-      content: resolveResult.message,
+      content: outcome.message,
       details: unavailableContextDetails([
         "Use `code_inspect` for point-level facts at this coordinate",
         "Or pass the identifier coordinate of a declaration",
       ]),
     });
   }
-  if (resolveResult.kind === "disambiguation") {
-    return wrapOutcome(disambiguationResult(resolveResult));
-  }
 
-  const entry = resolveResult.targets[0];
-  if (!entry) {
-    return wrapOutcome({
-      content: "**Error:** Coordinate resolution returned no target.",
-      details: unavailableContextDetails(["Use `code_inspect` for point-level facts"]),
-    });
-  }
-
-  return wrapOutcome(await runWithOrientationTarget(params, ctx, { entry, notes: [] }));
+  return wrapOutcome({
+    content: "**Error:** Coordinate resolution returned no target.",
+    details: unavailableContextDetails(["Use `code_inspect` for point-level facts"]),
+  });
 }
 
 /** Wrap a CodeIntelResult into a resolved PreciseTargetOutcome. */
 function wrapOutcome(result: CodeIntelResult): PreciseTargetOutcome {
   return { kind: "resolved", result };
 }
+
 async function runWithOrientationTarget(
   params: CodeOrientationToolParams,
   ctx: CodeIntelToolExecCtx,
@@ -170,12 +175,7 @@ async function runWithOrientationTarget(
 
 // ── Helpers ───────────────────────────────────────────────────────────
 
-/**
- * Cross-field rule for code_orientation coordinate mode.
- *
- * TypeBox already enforces line/character types and min >= 1.
- * This covers only pairing, existence, and directory checks.
- */
+/** Cross-field rule for code_orientation coordinate mode. */
 const validateCoordinateParams = orientationCoordinateRules<CodeOrientationToolParams>();
 
 function buildOrientationTarget(params: CodeOrientationToolParams) {
@@ -215,14 +215,14 @@ function prependNotes(
 
 /** Build the ambiguous-coordinate result: candidate targetIds, no sections. */
 function disambiguationResult(
-  result: Extract<Awaited<ReturnType<typeof executeResolveService>>, { kind: "disambiguation" }>,
+  outcome: Extract<TargetWorkflowOutcome, { kind: "disambiguation" }>,
 ): CodeIntelResult {
   const lines: string[] = ["# Multiple matches found", ""];
   lines.push(
     "Coordinate resolution was ambiguous. Use `focus` + `line` + `character` for one of the candidates (pass the identifier coordinate):",
   );
   lines.push("");
-  for (const c of result.candidates) {
+  for (const c of outcome.candidates) {
     const kind = c.kind ? ` (\`${c.kind}\`)` : "";
     const container = c.container ? ` in \`${c.container}\`` : "";
     lines.push(
@@ -231,14 +231,10 @@ function disambiguationResult(
     lines.push(`   Target ID: \`${c.targetId}\``);
   }
 
-  const details: ContextDetails = {
+  const details: ContextDetails = assembleOrientationDetails({
     confidence: "semantic",
-    task: null,
-    focusTarget: null,
-    requestedSections: [],
-    renderedSections: [],
-    omittedCount: 0,
-    candidates: result.candidates.map((c) => ({
+    omittedCount: outcome.omittedCount,
+    candidates: outcome.candidates.map((c) => ({
       targetId: c.targetId,
       name: c.name,
       kind: c.kind,
@@ -251,7 +247,7 @@ function disambiguationResult(
     nextQueries: [
       "Use `focus` + `line` + `character` for one of the candidates above (pass the identifier coordinate)",
     ],
-  };
+  });
 
   return { content: lines.join("\n"), details: { type: "context", data: details } };
 }

package/src/tool/refactor-apply/orchestrate.ts

@@ -15,6 +15,7 @@ import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts"
 import type { CodeIntelResult } from "../../types/index.ts";
 import { unavailableSearchDetails } from "../infra/error-results.ts";
 import { renderRefactorApplyResult } from "../refactor-plan/markdown.ts";
+import { assembleRefactorApplyDetails } from "../result/refactor.ts";
 import { applyWorkspaceEdit } from "./apply.ts";
 
 export interface RefactorApplyInput {
@@ -77,13 +78,7 @@ export async function executeRefactorApply(
     content,
     details: {
       type: "search" as const,
-      data: {
-        confidence: "semantic" as const,
-        scope: null,
-        candidateCount: applyResult.kind === "applied" ? applyResult.totalEdits : 0,
-        omittedCount: 0,
-        nextQueries: ["`code_health` to check for new issues after the refactor"],
-      },
+      data: assembleRefactorApplyDetails(applyResult),
     },
   };
 }

package/src/tool/refactor-plan/orchestrate.ts

@@ -17,7 +17,6 @@ import {
   type SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { toLspPosition } from "@mrclrchtr/supi-lsp/api";
-import { createEvidenceList } from "../../analysis/evidence.ts";
 import { validateEdit } from "../../analysis/refactor/safety.ts";
 import { normalizePath } from "../../analysis/search/ripgrep.ts";
 import {
@@ -28,6 +27,7 @@ import {
 import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
 import type { CodeIntelResult } from "../../types/index.ts";
 import { unavailableSearchDetails } from "../infra/error-results.ts";
+import { assembleRefactorPlanDetails } from "../result/refactor.ts";
 import { renderRefactorPlanResult } from "./markdown.ts";
 
 type CanonicalRefactorOperation = Exclude<RefactorOperation, "rename">;
@@ -73,7 +73,7 @@ export async function executeRefactorPlan(
   }
   const operation = normalizedOperation.operation;
 
-  const target = resolveRefactorTarget(input, operation, deps.session);
+  const target = await resolveRefactorTarget(input, operation, deps.session);
   if ("content" in target) return target;
 
   const resolvedFile = normalizePath(target.file, deps.cwd);
@@ -125,25 +125,13 @@ export async function executeRefactorPlan(
   };
   deps.session.storePlan(plan);
 
-  const editEvidence = createEvidenceList({
-    key: "refactor.edits",
-    items: refactorResult.edits.edits,
-    maxResults: 5,
-  }).metadata;
   const content = renderRefactorPlanResult(plan, deps.cwd);
 
   return {
     content,
     details: {
       type: "search" as const,
-      data: {
-        confidence: "semantic" as const,
-        scope: null,
-        candidateCount: refactorResult.edits.edits.length,
-        omittedCount: editEvidence.omittedCount ?? 0,
-        evidenceLists: [editEvidence],
-        nextQueries: [`Use code_refactor_apply with planId: "${planId}" to apply this refactor`],
-      },
+      data: assembleRefactorPlanDetails(refactorResult.edits, planId),
     },
   };
 }
@@ -174,39 +162,43 @@ function normalizeRequestedOperation(
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: target expansion and operation-specific validation are kept together for clear user-facing errors.
-function resolveRefactorTarget(
+async function resolveRefactorTarget(
   input: RefactorPlanInput,
   operation: CanonicalRefactorOperation,
   session: WorkspaceCodeIntelligenceSession,
-): CodeIntelResult | { file: string; line: number; character: number } {
-  const expansion = session.expandTargetId(input);
-  if (expansion.kind === "error") {
-    return {
-      content: expansion.message,
-      details: unavailableSearchDetails(null, [
-        "Verify the `targetId` is valid and from this session",
-      ]),
-    };
-  }
-  if (expansion.kind === "ok") {
-    input.file = expansion.file;
-    input.line = expansion.line;
-    input.character = expansion.character;
-
-    // Per ADR 0003: rename_symbol is position-strict — LSP rename requires
-    // the identifier (name anchor), and a declaration anchor silently yields
-    // empty or wrong edits. Refuse before planning.
-    if (operation === "rename_symbol" && expansion.entry.anchorKind === "declaration") {
+): Promise<CodeIntelResult | { file: string; line: number; character: number }> {
+  // ── Deep seam: resolve target through the session target workflow ──
+  if (input.targetId) {
+    const policy = {
+      fileLevelAllowed: false,
+      nameAnchorRequired: operation === "rename_symbol",
+      waitForSemantic: false,
+    } as const;
+
+    const outcome = await session.resolveTarget({ targetId: input.targetId }, policy);
+    if (outcome.kind === "resolved") {
+      input.file = outcome.entry.file;
+      input.line = outcome.entry.displayLine;
+      input.character = outcome.entry.displayCharacter;
+    } else if (outcome.kind === "invalid-input") {
+      // Declaration-anchor refusal for rename_symbol comes back as invalid-input
       return {
-        content:
-          `**Cannot plan rename:** The resolved target fell back to a declaration anchor (the \`export\` keyword or similar), not an identifier (name anchor). LSP \`rename\` requires the identifier. ` +
-          `Re-resolve via \`code_resolve\` after the language server has indexed the file, ` +
-          `or pass \`file\` + \`line\` + \`character\` anchored directly on the identifier.`,
+        content: `**Cannot plan rename:** ${outcome.message}`,
         details: unavailableSearchDetails(null, [
           "Re-resolve via `code_resolve` when the LSP has indexed the file",
           "Or use `file` + `line` + `character` anchored on the identifier directly",
         ]),
       };
+    } else {
+      return {
+        content:
+          outcome.kind === "unavailable"
+            ? `**Error:** ${outcome.reason}`
+            : `**Error:** Target resolution failed. Verify the targetId is valid and from this session.`,
+        details: unavailableSearchDetails(null, [
+          "Verify the `targetId` is valid and from this session",
+        ]),
+      };
     }
   }
 

package/src/tool/resolve/markdown.ts

@@ -7,11 +7,9 @@
 
 import { relative } from "node:path";
 import { renderEvidenceListMetadataDisclosure } from "../../analysis/evidence.ts";
-import type {
-  DisambiguationCandidate,
-  ResolveServiceResult,
-} from "../../analysis/target/service.ts";
+import type { DisambiguationCandidate } from "../../analysis/target/service.ts";
 import type { TargetStoreEntry } from "../../session/target-store.ts";
+import type { ResolveResultAssembly } from "../result/resolve.ts";
 
 /**
  * Render a provenance note for an anchored resolution, but only when the
@@ -57,8 +55,9 @@ function renderSingleTarget(t: TargetStoreEntry, confidence: string, cwd: string
   return lines;
 }
 
-/** Render a full resolve service result into markdown. */
-export function renderResolveResult(result: ResolveServiceResult, cwd: string): string {
+/** Render an assembled resolve result into markdown. */
+export function renderResolveResult(assembly: ResolveResultAssembly): string {
+  const { result, cwd } = assembly;
   switch (result.kind) {
     case "resolved":
       return renderResolved(result.targets, result.omittedCount, result.confidence, cwd);

package/src/tool/resolve/orchestrate.ts

@@ -1,15 +1,11 @@
 /**
- * code_resolve orchestration — result assembly and details construction.
- *
- * Receives raw resolution outcomes from the resolution service and
- * assembles the markdown content and structured details.
+ * code_resolve orchestration — resolve facts, assemble tool evidence, render adapters.
  */
 
-import { relative } from "node:path";
 import { executeResolveService, type ResolveServiceParams } from "../../analysis/target/service.ts";
 import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
-import type { CodeIntelResult, ResolveDetails } from "../../types/index.ts";
-import { unavailableResolveDetails } from "../infra/error-results.ts";
+import type { CodeIntelResult } from "../../types/index.ts";
+import { assembleResolveResult, suggestedResolveRelations } from "../result/resolve.ts";
 import { renderResolveResult } from "./markdown.ts";
 
 export interface ResolveOrchestrateInput {
@@ -21,114 +17,22 @@ export interface ResolveOrchestrateInput {
 export async function orchestrateResolve(input: ResolveOrchestrateInput): Promise<CodeIntelResult> {
   const { params, session, cwd } = input;
   const result = await executeResolveService(params, session);
+  const assembly = assembleResolveResult(result, cwd);
 
-  let content = renderResolveResult(result, cwd);
+  let content = renderResolveResult(assembly);
 
   // For single-target resolutions, append actionable "Chain next" guidance.
   if (result.kind === "resolved" && result.targets.length === 1) {
     const target = result.targets[0];
-    const rels = suggestedRelations(target.kind);
+    const rels = suggestedResolveRelations(target.kind);
     if (rels) {
       const chainLine = `Chain next: \`code_graph(targetId: "${target.targetId}", relations: ${JSON.stringify(rels)})\``;
       content = `${content}\n${chainLine}\n`;
     }
   }
 
-  // Build structured details
-  if (result.kind === "resolved") {
-    const details: ResolveDetails = {
-      confidence: result.confidence,
-      targetCount: result.targets.length + result.omittedCount,
-      omittedCount: result.omittedCount,
-      evidenceLists: [
-        {
-          key: "resolve.targets",
-          totalCount: result.targets.length + result.omittedCount,
-          shownCount: result.targets.length,
-          omittedCount: result.omittedCount,
-          partialReason: null,
-        },
-      ],
-      targets: result.targets.map((t) => ({
-        targetId: t.targetId,
-        spanId: t.spanId,
-        file: relative(cwd, t.file) || t.file,
-        displayLine: t.displayLine,
-        displayCharacter: t.displayCharacter,
-        name: t.name,
-        kind: t.kind,
-        anchorKind: t.anchorKind,
-        confidence: t.confidence,
-        provenance: t.provenance,
-        resolution: t.resolution,
-      })),
-      nextQueries: result.nextQueries,
-    };
-    return { content, details: { type: "resolve", data: details } };
-  }
-
-  if (result.kind === "disambiguation") {
-    const details: ResolveDetails = {
-      confidence: "semantic",
-      targetCount: result.candidates.length + result.omittedCount,
-      omittedCount: result.omittedCount,
-      evidenceLists: [
-        {
-          key: "resolve.candidates",
-          totalCount: result.candidates.length + result.omittedCount,
-          shownCount: result.candidates.length,
-          omittedCount: result.omittedCount,
-          partialReason: null,
-        },
-      ],
-      targets: [],
-      candidates: result.candidates.map((cand) => ({
-        targetId: cand.targetId,
-        name: cand.name,
-        kind: cand.kind,
-        container: cand.container,
-        file: cand.file,
-        line: cand.line,
-        character: cand.character,
-        reason: cand.reason,
-        rank: cand.rank,
-        anchorKind: cand.anchorKind,
-      })),
-      nextQueries: result.nextQueries,
-    };
-    return { content, details: { type: "resolve", data: details } };
-  }
-
-  // Error — still return structured details
   return {
     content,
-    details: unavailableResolveDetails([
-      "Refine the `query` or `scope`",
-      "Use anchored `file` + `line` + `character` for a precise target",
-    ]),
+    details: { type: "resolve", data: assembly.details },
   };
 }
-
-/**
- * Suggested `code_graph` relations for a resolved symbol kind.
- */
-function suggestedRelations(kind: string | undefined | null): string[] | undefined {
-  switch (kind?.toLowerCase()) {
-    case "function":
-    case "method":
-    case "constructor":
-      return ["references", "callees", "tests"];
-    case "class":
-    case "interface":
-    case "type":
-    case "enum":
-      return ["references", "implements"];
-    case "file":
-    case "module":
-      return ["imports", "exports"];
-    case "test":
-      return ["tests"];
-    default:
-      return undefined;
-  }
-}