@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/tool/result/resolve.ts

@@ -1,114 +1,277 @@
 import { relative } from "node:path";
-import type { ResolveServiceResult } from "../../analysis/target/service.ts";
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import { createEvidenceList } from "../../analysis/evidence.ts";
+import type { TargetStoreEntry } from "../../session/target-store.ts";
+import type { TargetWorkflowOutcome } from "../../session/target-workflow.ts";
+import {
+  assembledNextQueries,
+  assembleToolResult,
+  type ResultProvenance,
+  type ToolResultAssembly,
+} from "./assembly.ts";
 import type { ResolveDetails } from "./types.ts";
 
+/** Presentation-neutral assembled code_resolve result. */
 export interface ResolveResultAssembly {
-  result: ResolveServiceResult;
-  cwd: string;
-  details: ResolveDetails;
+  readonly outcome: TargetWorkflowOutcome;
+  readonly cwd: string;
+  readonly assembled: ToolResultAssembly<TargetWorkflowOutcome>;
+  readonly details: ResolveDetails;
 }
 
-/** Assemble code_resolve evidence/details before markdown and TUI adapters render it. */
+interface ResolveProjection {
+  readonly key: string;
+  readonly title: string;
+  readonly status: "complete" | "unavailable";
+  readonly items: readonly unknown[];
+  readonly confidence: ConfidenceMode;
+  readonly evidence: EvidenceListMetadata | null;
+  readonly details: ResolveDetails;
+}
+
+/** Assemble resolved-target facts before markdown and TUI adapters render them. */
 export function assembleResolveResult(
-  result: ResolveServiceResult,
+  outcome: TargetWorkflowOutcome,
   cwd: string,
 ): ResolveResultAssembly {
-  return { result, cwd, details: buildResolveDetails(result, cwd) };
+  const projection = projectResolveOutcome(outcome, cwd);
+  const provenance = resolveProvenance(outcome);
+  const assembled = assembleToolResult({
+    data: outcome,
+    sections: [
+      {
+        key: projection.key,
+        title: projection.title,
+        status: projection.status,
+        items: projection.items,
+        confidence: projection.confidence,
+        provenance,
+      },
+    ],
+    evidenceLists: projection.evidence ? [projection.evidence] : [],
+    nextQueries: projection.details.nextQueries,
+    candidateCount: projection.details.targetCount,
+    confidence: projection.confidence,
+    provenance,
+  });
+
+  return Object.freeze({
+    outcome,
+    cwd,
+    assembled,
+    details: {
+      ...projection.details,
+      omittedCount: assembled.totals.omittedCount,
+      evidenceLists: [...assembled.evidenceLists],
+      nextQueries: assembledNextQueries(assembled),
+    },
+  });
 }
 
-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,
-    };
+function projectResolveOutcome(outcome: TargetWorkflowOutcome, cwd: string): ResolveProjection {
+  switch (outcome.kind) {
+    case "resolved":
+      return projectResolved(outcome.entry, cwd);
+    case "target-group":
+      return projectTargetGroup(outcome, cwd);
+    case "disambiguation":
+    case "kind-mismatch":
+      return projectCandidateOutcome(outcome);
+    case "invalid-input":
+    case "unavailable":
+      return projectFailure(outcome);
   }
+}
+
+function projectResolved(target: Readonly<TargetStoreEntry>, cwd: string): ResolveProjection {
+  const evidence = createEvidenceList({ key: "resolve.targets", items: [target] }).metadata;
+  return {
+    key: "resolve.targets",
+    title: "Resolved target",
+    status: "complete",
+    items: [target],
+    confidence: target.confidence,
+    evidence,
+    details: {
+      resultKind: "resolved",
+      confidence: target.confidence,
+      targetCount: 1,
+      omittedCount: 0,
+      evidenceLists: [evidence],
+      targets: [toTargetDetails(target, cwd)],
+      nextQueries: buildResolveNextQueries(target.targetId, target.kind),
+    },
+  };
+}
 
-  if (result.kind === "disambiguation") {
-    return {
+function projectTargetGroup(
+  outcome: Extract<TargetWorkflowOutcome, { kind: "target-group" }>,
+  cwd: string,
+): ResolveProjection {
+  const evidence = {
+    key: "resolve.targets",
+    items: [...outcome.targets],
+    metadata: {
+      key: "resolve.targets",
+      totalCount: outcome.totalCount,
+      shownCount: outcome.targets.length,
+      omittedCount: outcome.omittedCount,
+      partialReason: null,
+    },
+  };
+  return {
+    key: "resolve.target-group",
+    title: "Target group",
+    status: "complete",
+    items: evidence.items,
+    confidence: outcome.confidence,
+    evidence: evidence.metadata,
+    details: {
+      resultKind: "target-group",
+      groupFile: relative(cwd, outcome.file) || outcome.file,
+      groupDiscoveryProvenance: [...outcome.discoveryProvenance],
+      groupUnknownNestingCount: outcome.unknownNestingCount,
+      confidence: outcome.confidence,
+      targetCount: outcome.totalCount,
+      omittedCount: evidence.metadata.omittedCount,
+      evidenceLists: [evidence.metadata],
+      targets: evidence.items.map((target) => toTargetDetails(target, cwd)),
+      nextQueries:
+        outcome.totalCount > 0
+          ? ["Choose one Target group member handle for precise graph or refactor work"]
+          : ["Use code_inspect for point facts or code_find for explicit source evidence"],
+    },
+  };
+}
+
+function projectCandidateOutcome(
+  outcome: Extract<TargetWorkflowOutcome, { kind: "disambiguation" | "kind-mismatch" }>,
+): ResolveProjection {
+  const totalCount = outcome.candidates.length + outcome.omittedCount;
+  const evidence: EvidenceListMetadata = {
+    key: "resolve.candidates",
+    totalCount,
+    shownCount: outcome.candidates.length,
+    omittedCount: outcome.omittedCount,
+    partialReason: null,
+  };
+  const mismatch = outcome.kind === "kind-mismatch";
+  return {
+    key: "resolve.candidates",
+    title: mismatch ? "Near matches" : "Candidates",
+    status: "complete",
+    items: outcome.candidates,
+    confidence: "semantic",
+    evidence,
+    details: {
+      resultKind: outcome.kind,
+      ...(mismatch ? { requestedKind: outcome.requestedKind } : {}),
       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,
-        },
-      ],
+      targetCount: totalCount,
+      omittedCount: outcome.omittedCount,
+      evidenceLists: [evidence],
       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,
+      candidates: outcome.candidates.map((candidate) => ({
+        targetId: candidate.targetId,
+        name: candidate.name,
+        kind: candidate.kind,
+        container: candidate.container,
+        file: candidate.file,
+        line: candidate.line,
+        character: candidate.character,
+        rank: candidate.rank,
+        anchorKind: candidate.anchorKind,
       })),
-      nextQueries: result.nextQueries,
-    };
-  }
+      nextQueries: mismatch
+        ? ["Retry without symbolKind, use an observed provider kind, or choose a near-match handle"]
+        : ["Choose one candidate handle, or narrow the symbol selector with scope or symbolKind"],
+    },
+  };
+}
 
+function projectFailure(
+  outcome: Extract<TargetWorkflowOutcome, { kind: "invalid-input" | "unavailable" }>,
+): ResolveProjection {
+  const message = outcome.kind === "invalid-input" ? outcome.message : outcome.reason;
   return {
+    key: "resolve.targets",
+    title: "Resolved target",
+    status: "unavailable",
+    items: [],
     confidence: "unavailable",
-    targetCount: 0,
-    omittedCount: 0,
-    targets: [],
-    nextQueries: [
-      "Refine the `query` or `scope`",
-      "Use anchored `file` + `line` + `character` for a precise target",
-    ],
+    evidence: null,
+    details: {
+      resultKind: outcome.kind,
+      message,
+      confidence: "unavailable",
+      targetCount: 0,
+      omittedCount: 0,
+      targets: [],
+      nextQueries: [
+        "Refine the target selector",
+        "Use an anchor target when you already know an identifier coordinate",
+      ],
+    },
   };
 }
 
-/** Suggested `code_graph` relations for a resolved symbol kind. */
-export function suggestedResolveRelations(kind: string | undefined | null): string[] | undefined {
+function toTargetDetails(target: Readonly<TargetStoreEntry>, cwd: string) {
+  return {
+    targetId: target.targetId,
+    spanId: target.spanId,
+    file: relative(cwd, target.file) || target.file,
+    displayLine: target.displayLine,
+    displayCharacter: target.displayCharacter,
+    name: target.name,
+    kind: target.kind,
+    container: target.container,
+    anchorKind: target.anchorKind,
+    confidence: target.confidence,
+    provenance: [...target.provenance],
+    resolution: target.resolution,
+  };
+}
+
+function resolveProvenance(outcome: TargetWorkflowOutcome): ResultProvenance[] {
+  const sources = new Set<"semantic" | "structural">();
+  if (outcome.kind === "resolved") {
+    for (const source of outcome.entry.provenance) sources.add(source);
+  } else if (outcome.kind === "target-group") {
+    for (const source of outcome.discoveryProvenance) sources.add(source);
+  } else if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
+    sources.add("semantic");
+  }
+  return [
+    ...(sources.has("semantic")
+      ? [{ source: "semantic" as const, detail: "target-workflow" }]
+      : []),
+    ...(sources.has("structural")
+      ? [{ source: "structural" as const, detail: "target-workflow" }]
+      : []),
+  ];
+}
+
+/** Suggested surviving graph relations for a resolved symbol kind. */
+export function suggestedResolveRelations(kind: string | undefined | null): string[] {
   switch (kind?.toLowerCase()) {
     case "function":
     case "method":
     case "constructor":
-      return ["references", "callees", "tests"];
+      return ["references", "callees"];
     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;
+      return ["references"];
   }
 }
+
+function buildResolveNextQueries(targetId: string, kind: string | null): string[] {
+  const relations = suggestedResolveRelations(kind);
+  return [
+    `Use code_graph with target.handle "${targetId}" and relations ${JSON.stringify(relations)}`,
+  ];
+}

package/src/tool/result/types.ts

@@ -1,11 +1,23 @@
 import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { CapabilityWarningReport } from "../../analysis/capability/capability-warnings.ts";
 import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
 import type { InstructionFilesMetadata } from "../../analysis/instruction-files.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";
+import type { ReadNextItem } from "../../analysis/read-next.ts";
+import type { StructuredScanSummary } from "../../analysis/search/pattern.ts";
+import type {
+  HealthDiagnosticObservation,
+  HealthRefreshState,
+  HealthSection,
+  SemanticHealthState,
+} from "../../session/health-types.ts";
+import type { InspectResultData } from "../../session/inspect-types.ts";
+import type { TargetSymbolKind } from "../../session/target-input.ts";
+import type {
+  AnchorKind,
+  TargetProviderProvenance,
+  TargetStoreEntry,
+} from "../../session/target-store.ts";
+import type { ResultProvenance } from "./assembly.ts";
 
 // ── Anchored coordinate resolution metadata ───────────────────────────
 
@@ -42,19 +54,6 @@ export interface AnchoredResolutionMetadata {
   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;
@@ -63,41 +62,35 @@ export interface SearchDetails {
   omittedCount: number;
   evidenceLists?: EvidenceListMetadata[];
   nextQueries: string[];
-  tests?: TestSurfaceDetails;
+  /** Paths successfully changed by `code_refactor_apply`. */
+  changedFiles?: readonly string[];
+  /** Present for AST mode; declares the operation-specific source-file universe and completeness. */
+  scan?: StructuredScanSummary;
 }
 
-/** 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 {
+  resultKind:
+    | "resolved"
+    | "target-group"
+    | "disambiguation"
+    | "kind-mismatch"
+    | "invalid-input"
+    | "unavailable";
+  /** Workspace-relative source file for a file-derived Target group. */
+  groupFile?: string;
+  /** Providers that successfully enumerated a file-derived Target group. */
+  groupDiscoveryProvenance?: readonly TargetProviderProvenance[];
+  /** Complete-group declarations whose providers could not establish nesting. */
+  groupUnknownNestingCount?: number;
+  /** Strict provider kind that produced a near-match result. */
+  requestedKind?: TargetSymbolKind;
   confidence: ConfidenceMode;
+  /** Plain workflow failure message, present for invalid-input and unavailable results. */
+  message?: string;
   targetCount: number;
   omittedCount: number;
   evidenceLists?: EvidenceListMetadata[];
@@ -111,9 +104,10 @@ export interface ResolveDetails {
     displayCharacter: number;
     name: string | null;
     kind: string | null;
+    container: string | null;
     anchorKind: AnchorKind;
     confidence: ConfidenceMode;
-    provenance: string;
+    provenance: readonly TargetProviderProvenance[];
     /** Resolution provenance — present when the target was resolved from anchored coordinates. */
     resolution?: AnchoredResolutionMetadata;
   }>;
@@ -126,13 +120,23 @@ export interface ResolveDetails {
     file: string;
     line: number;
     character: number;
-    reason: string;
     rank: number;
     anchorKind: AnchorKind;
   }>;
   nextQueries: string[];
 }
 
+/** One independently collected code_orientation section. */
+export interface OrientationSectionDetails {
+  key: string;
+  title: string;
+  status: "complete" | "partial" | "unavailable";
+  reason: string | null;
+  confidence: ConfidenceMode;
+  provenance: ResultProvenance[];
+  evidenceLists: EvidenceListMetadata[];
+}
+
 /** Structured details metadata for code_orientation results. */
 export interface ContextDetails {
   confidence: ConfidenceMode;
@@ -142,20 +146,23 @@ export interface ContextDetails {
   renderedSections: string[];
   omittedCount: number;
   evidenceLists?: EvidenceListMetadata[];
+  /** Per-section status, provenance, and bounded-list metadata. */
+  sections?: OrientationSectionDetails[];
   nextQueries: string[];
-  tests?: TestSurfaceDetails;
+  /** Source ranges projected from the assembled read-next actions. */
+  readNext?: ReadNextItem[];
   /** Directory-local instruction files surfaced during directory orientation. */
   instructions?: InstructionFilesMetadata;
   /**
    * 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`).
+   * precise-target inputs. Absent for orientation/scope-only calls and when
+   * target selection remains ambiguous or has a Symbol-kind mismatch.
    * 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.
+   * Bounded candidates with targetIds when target selection is ambiguous or
+   * has a Symbol-kind mismatch. No task sections are rendered in that case.
    */
   candidates?: Array<{
     targetId: string;
@@ -169,22 +176,59 @@ export interface ContextDetails {
   }>;
 }
 
+/** One canonical point-inspection section projected into structured details. */
+export interface InspectSectionDetails {
+  key: keyof InspectResultData["sections"];
+  title: string;
+  status: "complete" | "partial" | "unavailable";
+  reason: string | null;
+  itemCount: number;
+  confidence: ConfidenceMode;
+  provenance: ResultProvenance[];
+}
+
 /** Structured details metadata for code_inspect results. */
 export interface InspectDetails {
   confidence: ConfidenceMode;
   focusTarget: string;
-  unavailableSections: string[];
+  diagnosticWindow: { startLine: number; endLine: number } | null;
+  sections: InspectSectionDetails[];
   evidenceLists?: EvidenceListMetadata[];
   nextQueries: string[];
 }
 
+/** One requested health signal projected into structured result details. */
+export interface HealthSectionDetails {
+  key: HealthSection;
+  title: string;
+  status: "complete" | "partial" | "unavailable";
+  confidence: ConfidenceMode;
+  provenance: ResultProvenance[];
+  itemCount: number;
+  available: boolean;
+}
+
 /** Structured details metadata for code_health results. */
 export interface HealthDetails {
-  lspAvailable: boolean;
-  lspStatus: string;
-  recovered: boolean;
+  includedSections: HealthSection[];
+  sections: HealthSectionDetails[];
+  confidence: ConfidenceMode;
+  provenance: ResultProvenance[];
+  candidateCount: number;
+  omittedCount: number;
+  semanticState: SemanticHealthState | null;
+  serverInventoryAvailable: boolean;
+  /** Server inventory remains workspace-wide even for a scoped diagnostic request. */
+  serverInventoryScope: "workspace";
+  /** Exact status and evidence boundary of the diagnostic observation. */
+  diagnosticObservation: HealthDiagnosticObservation;
+  /** Current or most recent explicit diagnostic refresh attempt. */
+  refresh: HealthRefreshState;
+  structuralAvailable: boolean;
   /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */
   structuralStatus?: string;
+  /** Supplemental status for diagnostic/server requests; not a selectable section. */
+  capabilityWarnings: CapabilityWarningReport | null;
   diagnosticFileCount: number;
   serverCount: number;
   evidenceLists?: EvidenceListMetadata[];