@mrclrchtr/supi-code-intelligence 2.0.5 → 2.1.0

package/src/tool/result/resolve.ts

@@ -0,0 +1,114 @@
+import { relative } from "node:path";
+import type { ResolveServiceResult } from "../../analysis/target/service.ts";
+import type { ResolveDetails } from "./types.ts";
+
+export interface ResolveResultAssembly {
+  result: ResolveServiceResult;
+  cwd: string;
+  details: ResolveDetails;
+}
+
+/** Assemble code_resolve evidence/details before markdown and TUI adapters render it. */
+export function assembleResolveResult(
+  result: ResolveServiceResult,
+  cwd: string,
+): ResolveResultAssembly {
+  return { result, cwd, details: buildResolveDetails(result, cwd) };
+}
+
+function buildResolveDetails(result: ResolveServiceResult, cwd: string): ResolveDetails {
+  if (result.kind === "resolved") {
+    return {
+      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,
+    };
+  }
+
+  if (result.kind === "disambiguation") {
+    return {
+      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 {
+    confidence: "unavailable",
+    targetCount: 0,
+    omittedCount: 0,
+    targets: [],
+    nextQueries: [
+      "Refine the `query` or `scope`",
+      "Use anchored `file` + `line` + `character` for a precise target",
+    ],
+  };
+}
+
+/** Suggested `code_graph` relations for a resolved symbol kind. */
+export function suggestedResolveRelations(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;
+  }
+}

package/src/tool/result/types.ts

@@ -0,0 +1,188 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { PrioritySignalsSummary } from "../../analysis/signals/project.ts";
+import type { TestSurfaceDetails } from "../../analysis/tests/test-discovery.ts";
+import type { AnchorKind, TargetStoreEntry } from "../../session/target-store.ts";
+
+export type { TestSurfaceDetails } from "../../analysis/tests/test-discovery.ts";
+
+// ── Anchored coordinate resolution metadata ───────────────────────────
+
+/**
+ * Provider-backed evidence source that identified an anchored coordinate
+ * target. Drives the markdown provenance note and structured resolution
+ * metadata per ADR 0003/0004.
+ *
+ * - `semantic` — LSP document symbols identified the symbol and its anchors.
+ * - `structural` — tree-sitter structural evidence (outline/exports/nodeAt)
+ *   identified the declaration and/or identifier.
+ * - `structural-identifier` — tree-sitter `nodeAt` classified the coordinate
+ *   as an identifier token and snapped it to a declaration via ancestry.
+ */
+export type AnchoredResolutionSource = "semantic" | "structural" | "structural-identifier";
+
+/**
+ * Resolution metadata for a target resolved from anchored coordinates.
+ *
+ * Records the requested coordinate, the resolved anchor coordinate, whether
+ * the resolved anchor differs from the request (a snap), and the
+ * provider-backed evidence source. Structured details always carry this when
+ * a target was resolved from coordinates; markdown surfaces a note only when
+ * the resolution was non-obvious (snapped or degraded).
+ */
+export interface AnchoredResolutionMetadata {
+  /** The 1-based coordinate the caller requested. */
+  requested: { line: number; character: number };
+  /** The 1-based anchor coordinate the target was resolved to. */
+  resolved: { line: number; character: number };
+  /** Whether the resolved anchor differs from the requested coordinate. */
+  snapped: boolean;
+  /** Provider-backed evidence source that identified the target. */
+  source: AnchoredResolutionSource;
+}
+
+/** Structured details metadata returned alongside markdown brief content. */
+export interface BriefDetails {
+  confidence: ConfidenceMode;
+  focusTarget: string | null;
+  startHere: Array<{ target: string; reason: string }>;
+  publicSurfaces: string[];
+  dependencySummary: { moduleCount: number; edgeCount: number } | null;
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  prioritySignals?: PrioritySignalsSummary | null;
+}
+
+/** Structured details metadata for relationship and pattern results. */
+export interface SearchDetails {
+  confidence: ConfidenceMode;
+  scope: string | null;
+  candidateCount: number;
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  tests?: TestSurfaceDetails;
+}
+
+/** Structured details metadata for affected analysis results. */
+export interface AffectedDetails {
+  confidence: ConfidenceMode;
+  directCount: number;
+  downstreamCount: number;
+  riskLevel: "low" | "medium" | "high";
+  checkNext: string[];
+  likelyTests: string[];
+  /** Concrete test commands to run relevant verification. */
+  likelyTestCommands: string[];
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  prioritySignals?: PrioritySignalsSummary | null;
+  tests?: TestSurfaceDetails;
+}
+
+/**
+ * Structured details metadata for workflow-oriented impact analysis results.
+ *
+ * Currently structurally identical to `AffectedDetails`. When adding own fields,
+ * audit callers in `orchestrate.ts` that construct `{ type: "impact", data }`
+ * so they return `ImpactDetails`, not just `AffectedDetails`.
+ */
+export interface ImpactDetails extends AffectedDetails {}
+
+// Canonical disambiguation candidate — re-exported from resolution/types.ts
+export type { DisambiguationCandidateData as DisambiguationCandidate } from "../../analysis/target/types.ts";
+
+/** Structured details metadata for code_resolve results. */
+export interface ResolveDetails {
+  confidence: ConfidenceMode;
+  targetCount: number;
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  /** Resolved targets with relative paths (computed from {@link TargetStoreEntry} at detail-build time). */
+  targets: Array<{
+    targetId: string;
+    spanId: string;
+    /** Workspace-relative path. */
+    file: string;
+    displayLine: number;
+    displayCharacter: number;
+    name: string | null;
+    kind: string | null;
+    anchorKind: AnchorKind;
+    confidence: ConfidenceMode;
+    provenance: string;
+    /** Resolution provenance — present when the target was resolved from anchored coordinates. */
+    resolution?: AnchoredResolutionMetadata;
+  }>;
+  /** Disambiguation candidates from the resolve service. */
+  candidates?: Array<{
+    targetId: string;
+    name: string;
+    kind: string | null;
+    container: string | null;
+    file: string;
+    line: number;
+    character: number;
+    reason: string;
+    rank: number;
+    anchorKind: AnchorKind;
+  }>;
+  nextQueries: string[];
+}
+
+/** Structured details metadata for code_orientation results. */
+export interface ContextDetails {
+  confidence: ConfidenceMode;
+  task: string | null;
+  focusTarget: string | null;
+  requestedSections: string[];
+  renderedSections: string[];
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  tests?: TestSurfaceDetails;
+  /**
+   * Resolved target store entry — populated for both coordinate and targetId
+   * precise-target inputs. Absent for orientation/scope-only calls and for
+   * ambiguous coordinate resolution (see `candidates`).
+   * File paths are absolute; compute relative paths at render time.
+   */
+  target?: TargetStoreEntry;
+  /**
+   * Disambiguation candidates with targetIds — populated only when coordinate
+   * resolution was ambiguous. No task sections are rendered in that case.
+   */
+  candidates?: Array<{
+    targetId: string;
+    name: string;
+    kind: string | null;
+    container: string | null;
+    file: string;
+    line: number;
+    character: number;
+    rank: number;
+  }>;
+}
+
+/** Structured details metadata for code_inspect results. */
+export interface InspectDetails {
+  confidence: ConfidenceMode;
+  focusTarget: string;
+  unavailableSections: string[];
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+}
+
+/** Structured details metadata for code_health results. */
+export interface HealthDetails {
+  lspAvailable: boolean;
+  lspStatus: string;
+  recovered: boolean;
+  /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */
+  structuralStatus?: string;
+  diagnosticFileCount: number;
+  serverCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+}

package/src/tool/schemas.ts

@@ -5,6 +5,27 @@ import type { CodeIntelligenceToolName } from "../types/index.ts";
 const ScopeParam = Type.String({
   description: "Workspace-relative path, package, or directory scope for the workflow query.",
 });
+const FindScopeParam = Type.Union(
+  [
+    Type.String({
+      description: "Workspace-relative path, package, or directory scope for the search query.",
+    }),
+    Type.Array(
+      Type.String({
+        description: "Workspace-relative path, package, or directory search scope.",
+      }),
+      {
+        description: "One or more workspace-relative paths, packages, or directories to search.",
+        minItems: 1,
+        uniqueItems: true,
+      },
+    ),
+  ],
+  {
+    description:
+      "Workspace-relative path, package, directory, or array of scopes for the search query.",
+  },
+);
 const FileParam = Type.String({ description: "Target file path." });
 const QueryParam = Type.String({
   description: "Human or code reference to resolve or search for.",
@@ -129,7 +150,7 @@ export const CodeOrientationParameters = Type.Object(
 export const CodeFindParameters = Type.Object(
   {
     query: QueryParam,
-    scope: Type.Optional(ScopeParam),
+    scope: Type.Optional(FindScopeParam),
     mode: Type.Optional(
       StringEnum(["text", "regex", "ast", "semantic"], {
         description:

package/src/types/details.ts

@@ -1,188 +1,20 @@
-import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
-import type { EvidenceListMetadata } from "../analysis/evidence.ts";
-import type { PrioritySignalsSummary } from "../analysis/signals/project.ts";
-import type { TestSurfaceDetails } from "../analysis/tests/test-discovery.ts";
-import type { AnchorKind, TargetStoreEntry } from "../session/target-store.ts";
-
-export type { TestSurfaceDetails } from "../analysis/tests/test-discovery.ts";
-
-// ── Anchored coordinate resolution metadata ───────────────────────────
-
 /**
- * Provider-backed evidence source that identified an anchored coordinate
- * target. Drives the markdown provenance note and structured resolution
- * metadata per ADR 0003/0004.
+ * Compatibility export for tool-result detail shapes.
  *
- * - `semantic` — LSP document symbols identified the symbol and its anchors.
- * - `structural` — tree-sitter structural evidence (outline/exports/nodeAt)
- *   identified the declaration and/or identifier.
- * - `structural-identifier` — tree-sitter `nodeAt` classified the coordinate
- *   as an identifier token and snapped it to a declaration via ancestry.
+ * Public code-intelligence details are assembled in `src/tool/result/`.
+ * Import new result assembly code from `../tool/result/types.ts` directly.
  */
-export type AnchoredResolutionSource = "semantic" | "structural" | "structural-identifier";
-
-/**
- * Resolution metadata for a target resolved from anchored coordinates.
- *
- * Records the requested coordinate, the resolved anchor coordinate, whether
- * the resolved anchor differs from the request (a snap), and the
- * provider-backed evidence source. Structured details always carry this when
- * a target was resolved from coordinates; markdown surfaces a note only when
- * the resolution was non-obvious (snapped or degraded).
- */
-export interface AnchoredResolutionMetadata {
-  /** The 1-based coordinate the caller requested. */
-  requested: { line: number; character: number };
-  /** The 1-based anchor coordinate the target was resolved to. */
-  resolved: { line: number; character: number };
-  /** Whether the resolved anchor differs from the requested coordinate. */
-  snapped: boolean;
-  /** Provider-backed evidence source that identified the target. */
-  source: AnchoredResolutionSource;
-}
-
-/** Structured details metadata returned alongside markdown brief content. */
-export interface BriefDetails {
-  confidence: ConfidenceMode;
-  focusTarget: string | null;
-  startHere: Array<{ target: string; reason: string }>;
-  publicSurfaces: string[];
-  dependencySummary: { moduleCount: number; edgeCount: number } | null;
-  omittedCount: number;
-  evidenceLists?: EvidenceListMetadata[];
-  nextQueries: string[];
-  prioritySignals?: PrioritySignalsSummary | null;
-}
-
-/** Structured details metadata for relationship and pattern results. */
-export interface SearchDetails {
-  confidence: ConfidenceMode;
-  scope: string | null;
-  candidateCount: number;
-  omittedCount: number;
-  evidenceLists?: EvidenceListMetadata[];
-  nextQueries: string[];
-  tests?: TestSurfaceDetails;
-}
-
-/** Structured details metadata for affected analysis results. */
-export interface AffectedDetails {
-  confidence: ConfidenceMode;
-  directCount: number;
-  downstreamCount: number;
-  riskLevel: "low" | "medium" | "high";
-  checkNext: string[];
-  likelyTests: string[];
-  /** Concrete test commands to run relevant verification. */
-  likelyTestCommands: string[];
-  omittedCount: number;
-  evidenceLists?: EvidenceListMetadata[];
-  nextQueries: string[];
-  prioritySignals?: PrioritySignalsSummary | null;
-  tests?: TestSurfaceDetails;
-}
-
-/**
- * Structured details metadata for workflow-oriented impact analysis results.
- *
- * Currently structurally identical to `AffectedDetails`. When adding own fields,
- * audit callers in `orchestrate.ts` that construct `{ type: "impact", data }`
- * so they return `ImpactDetails`, not just `AffectedDetails`.
- */
-export interface ImpactDetails extends AffectedDetails {}
-
-// Canonical disambiguation candidate — re-exported from resolution/types.ts
-export type { DisambiguationCandidateData as DisambiguationCandidate } from "../analysis/target/types.ts";
-
-/** Structured details metadata for code_resolve results. */
-export interface ResolveDetails {
-  confidence: ConfidenceMode;
-  targetCount: number;
-  omittedCount: number;
-  evidenceLists?: EvidenceListMetadata[];
-  /** Resolved targets with relative paths (computed from {@link TargetStoreEntry} at detail-build time). */
-  targets: Array<{
-    targetId: string;
-    spanId: string;
-    /** Workspace-relative path. */
-    file: string;
-    displayLine: number;
-    displayCharacter: number;
-    name: string | null;
-    kind: string | null;
-    anchorKind: AnchorKind;
-    confidence: ConfidenceMode;
-    provenance: string;
-    /** Resolution provenance — present when the target was resolved from anchored coordinates. */
-    resolution?: AnchoredResolutionMetadata;
-  }>;
-  /** Disambiguation candidates from the resolve service. */
-  candidates?: Array<{
-    targetId: string;
-    name: string;
-    kind: string | null;
-    container: string | null;
-    file: string;
-    line: number;
-    character: number;
-    reason: string;
-    rank: number;
-    anchorKind: AnchorKind;
-  }>;
-  nextQueries: string[];
-}
-
-/** Structured details metadata for code_orientation results. */
-export interface ContextDetails {
-  confidence: ConfidenceMode;
-  task: string | null;
-  focusTarget: string | null;
-  requestedSections: string[];
-  renderedSections: string[];
-  omittedCount: number;
-  evidenceLists?: EvidenceListMetadata[];
-  nextQueries: string[];
-  tests?: TestSurfaceDetails;
-  /**
-   * Resolved target store entry — populated for both coordinate and targetId
-   * precise-target inputs. Absent for orientation/scope-only calls and for
-   * ambiguous coordinate resolution (see `candidates`).
-   * File paths are absolute; compute relative paths at render time.
-   */
-  target?: TargetStoreEntry;
-  /**
-   * Disambiguation candidates with targetIds — populated only when coordinate
-   * resolution was ambiguous. No task sections are rendered in that case.
-   */
-  candidates?: Array<{
-    targetId: string;
-    name: string;
-    kind: string | null;
-    container: string | null;
-    file: string;
-    line: number;
-    character: number;
-    rank: number;
-  }>;
-}
-
-/** Structured details metadata for code_inspect results. */
-export interface InspectDetails {
-  confidence: ConfidenceMode;
-  focusTarget: string;
-  unavailableSections: string[];
-  evidenceLists?: EvidenceListMetadata[];
-  nextQueries: string[];
-}
-
-/** Structured details metadata for code_health results. */
-export interface HealthDetails {
-  lspAvailable: boolean;
-  lspStatus: string;
-  recovered: boolean;
-  /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */
-  structuralStatus?: string;
-  diagnosticFileCount: number;
-  serverCount: number;
-  evidenceLists?: EvidenceListMetadata[];
-}
+export type {
+  AffectedDetails,
+  AnchoredResolutionMetadata,
+  AnchoredResolutionSource,
+  BriefDetails,
+  ContextDetails,
+  DisambiguationCandidate,
+  HealthDetails,
+  ImpactDetails,
+  InspectDetails,
+  ResolveDetails,
+  SearchDetails,
+  TestSurfaceDetails,
+} from "../tool/result/types.ts";

package/src/ui/tui/common.ts

@@ -147,9 +147,9 @@ function buildExpandedView(
   if (lists && lists.length > 0) {
     container.addChild(new Spacer(1));
     renderEvidenceLines(container, lists, theme);
-    container.addChild(new Spacer(1));
   }
 
+  renderStructuredDetailBody(container, data, theme);
   renderMarkdownDetail(container, result, theme);
 
   return container;
@@ -189,6 +189,50 @@ export function buildSimpleCompact(
   return new Text(segments.join(` ${dot} `), 0, 0);
 }
 
+export function renderStructuredDetailBody(
+  container: Container,
+  data: Record<string, unknown> | undefined,
+  theme: Theme,
+): void {
+  if (!data) return;
+  const lines = structuredDetailLines(data);
+  if (lines.length === 0) return;
+  container.addChild(new Spacer(1));
+  for (const line of lines) {
+    container.addChild(new Text(theme.fg("muted", line), 0, 0));
+  }
+}
+
+function structuredDetailLines(data: Record<string, unknown>): string[] {
+  const lines: string[] = [];
+  const focusTarget = data.focusTarget;
+  if (typeof focusTarget === "string" && focusTarget.length > 0) {
+    lines.push(`target: ${focusTarget}`);
+  }
+
+  const unavailable = data.unavailableSections;
+  if (Array.isArray(unavailable) && unavailable.length > 0) {
+    lines.push(`unavailable: ${unavailable.join(", ")}`);
+  }
+
+  const checkNext = data.checkNext;
+  if (Array.isArray(checkNext) && checkNext.length > 0) {
+    lines.push(`check next: ${checkNext.slice(0, 3).join(" · ")}`);
+  }
+
+  const likelyTests = data.likelyTests;
+  if (Array.isArray(likelyTests) && likelyTests.length > 0) {
+    lines.push(`likely tests: ${likelyTests.slice(0, 3).join(" · ")}`);
+  }
+
+  const nextQueries = data.nextQueries;
+  if (Array.isArray(nextQueries) && nextQueries.length > 0) {
+    lines.push(`next: ${nextQueries.slice(0, 2).join(" · ")}`);
+  }
+
+  return lines;
+}
+
 export function buildSimpleHeader(
   data: Record<string, unknown> | undefined,
   theme: Theme,