@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/tool/specs.ts

@@ -1,4 +1,8 @@
 import type { TSchema } from "typebox";
+import {
+  DEFAULT_AST_SCAN_MAX_FILES,
+  DEFAULT_AST_SCAN_TIMEOUT_MS,
+} from "../analysis/search/ast-scan.ts";
 import type {
   CodeIntelligenceToolName,
   CodeIntelResult,
@@ -7,8 +11,6 @@ import type {
 import { executeFindTool } from "./find/execute.ts";
 import { executeGraphTool } from "./graph/execute.ts";
 import { executeHealthTool } from "./health/execute.ts";
-import { executeImpactTool } from "./impact/execute.ts";
-import { emitToolProgress } from "./infra/progress.ts";
 import { executeInspectTool } from "./inspect/execute.ts";
 import { executeOrientationTool } from "./orientation/execute.ts";
 import { executeRefactorApplyTool } from "./refactor-apply/execute.ts";
@@ -19,7 +21,6 @@ import {
   CodeFindParameters,
   CodeGraphParameters,
   CodeHealthParameters,
-  CodeImpactParameters,
   CodeInspectParameters,
   CodeOrientationParameters,
   CodeRefactorParameters,
@@ -27,49 +28,23 @@ import {
 } from "./schemas.ts";
 
 /** Substrate families that power a tool's implementation. */
-export type ToolSubstrate = "semantic" | "structural" | "search" | "git" | "diagnostics";
-
-/** Deployment phase for a tool. */
-export type ToolPhase = "phase-1" | "phase-2" | "phase-3" | "phase-4" | "phase-5" | "phase-6";
+export type ToolSubstrate = "semantic" | "structural" | "search" | "diagnostics";
 
-/** Canonical spec for one code-intelligence tool — runtime registration config. */
+/** Canonical registration spec for one public code-intelligence tool. */
 export interface CodeIntelligenceToolDefinitionSpec {
   name: CodeIntelligenceToolName;
   label: string;
   parameters: TSchema;
-  /** Per-spec line-limit override for the adapter's head truncation. */
   maxLines?: number;
-  /** Per-spec byte-limit override for the adapter's head truncation. */
   maxBytes?: number;
-  /** When true, oversized truncated output spills to a temp file. */
-  spillToTempFile?: boolean;
   run: (params: unknown, ctx: CodeIntelToolExecCtx) => Promise<CodeIntelResult> | CodeIntelResult;
-
-  // ── Design metadata ────────────────────────────────────────────────
-
-  /** One-line purpose summary for docs and tests. */
-  purpose?: string;
-  /** Key into CODE_INTELLIGENCE_TOOL_SCHEMAS. */
-  schemaKey?: CodeIntelligenceToolName;
-  /** Concise schema summary for future maintainers. */
-  schemaDocs?: string;
-  /** Legacy tools this tool absorbed (empty for new tools). */
-  absorbsTools?: string[];
-  /** Legacy behaviors this tool absorbed. */
-  absorbsBehaviors?: string[];
-  /** Substrate families that power the implementation. */
-  substrates?: ToolSubstrate[];
-  /** Deployment phase. */
-  phase?: ToolPhase;
-  /** Explicit non-goals — what the tool intentionally does NOT do. */
-  nonGoals?: string[];
+  purpose: string;
+  schemaDocs: string;
+  substrates: ToolSubstrate[];
+  nonGoals: string[];
 }
 
-/**
- * Canonical code-intelligence tool specs — runtime registration data.
- *
- * Prompt descriptions and guidelines live in {@link ./guidance.ts}.
- */
+/** Single source of truth for the surviving eight-tool family. */
 export const CODE_INTELLIGENCE_TOOL_SPECS = [
   {
     name: "code_resolve",
@@ -78,15 +53,13 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
     run: (params, ctx) =>
       executeResolveTool(params as Parameters<typeof executeResolveTool>[0], ctx),
     purpose:
-      "Resolve human or code references into precise file/range/symbol targets and stable target handles.",
-    schemaKey: "code_resolve",
-    schemaDocs:
-      "Accepts a query or file-based anchor plus optional scope/kind/maxResults. Later phases validate that line/character require file.",
-    absorbsTools: [],
-    absorbsBehaviors: [],
-    substrates: ["semantic", "search"],
-    phase: "phase-1",
-    nonGoals: ["Target handles do not persist across sessions."],
+      "Resolve an anchor/symbol into handles or enumerate a file's declarations as a Target group.",
+    schemaDocs: "Requires one exact target selector: anchor, symbol, or file.",
+    substrates: ["semantic", "structural"],
+    nonGoals: [
+      "Handles do not persist across sessions.",
+      "No text-search or structural-only target creation fallback.",
+    ],
   },
   {
     name: "code_inspect",
@@ -94,19 +67,10 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
     parameters: CodeInspectParameters,
     run: (params, ctx) =>
       executeInspectTool(params as Parameters<typeof executeInspectTool>[0], ctx),
-    purpose:
-      "Inspect one precise point in code with best-effort syntax, symbol, hover, definition, diagnostics, and code-action facts.",
-    schemaKey: "code_inspect",
-    schemaDocs:
-      "Requires file, line, and character plus optional maxResults. It is the explicit point-inspection surface; code_orientation handles broader orientation.",
-    absorbsTools: [],
-    absorbsBehaviors: ["anchored orientation inspection"],
+    purpose: "Inspect one exact source point with semantic, structural, and diagnostic facts.",
+    schemaDocs: "Requires point.file, point.line, and point.character.",
     substrates: ["semantic", "structural", "diagnostics"],
-    phase: "phase-2",
-    nonGoals: [
-      "Does not accept targetId in this first pass; inspection stays point-based.",
-      "Does not apply code actions.",
-    ],
+    nonGoals: ["Does not apply code actions."],
   },
   {
     name: "code_orientation",
@@ -114,107 +78,59 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
     parameters: CodeOrientationParameters,
     run: (params, ctx) =>
       executeOrientationTool(params as Parameters<typeof executeOrientationTool>[0], ctx),
-    purpose:
-      "Orient around a project, discovered module, directory, file, or precise symbol before choosing surgical follow-up tools.",
-    schemaKey: "code_orientation",
-    schemaDocs:
-      "Accepts optional focus, targetId, line, character, and maxResults. Omitted focus returns workspace orientation; focus is path-first with discovered-module lookup; focus+line+character resolves a symbol; targetId wins over focus/coordinates.",
-    absorbsTools: ["code_brief", "code_context"],
-    absorbsBehaviors: [],
+    purpose: "Orient around the workspace or one exact path, module, or target focus.",
+    schemaDocs: "Omitted focus means workspace; otherwise focus is an exact-one selector.",
     substrates: ["semantic", "structural", "diagnostics"],
-    phase: "phase-2",
-    nonGoals: [
-      "Does not provide relation, tests, or impact sections; use code_graph and code_impact.",
-      "Does not resolve bare symbol names; use code_resolve first.",
-    ],
+    nonGoals: ["Relation evidence belongs to code_graph.", "Health belongs to code_health."],
   },
   {
     name: "code_graph",
     label: "Code Graph",
     parameters: CodeGraphParameters,
-    spillToTempFile: true,
     run: (params, ctx) => executeGraphTool(params as Parameters<typeof executeGraphTool>[0], ctx),
-    purpose:
-      "Show the graph of relationships touching a target, including references, callees, imports, exports, implementations, and tests.",
-    schemaKey: "code_graph",
+    purpose: "Collect references, structural callees, and implementations for one exact target.",
     schemaDocs:
-      "Accepts targetId plus relations and maxResults (per-relation result cap). Uses references rather than misleading callers labels.",
-    absorbsTools: ["code_references", "code_calls", "code_implementations"],
-    absorbsBehaviors: [],
-    substrates: ["semantic", "structural", "search"],
-    phase: "phase-3",
-    nonGoals: [
-      "Does not claim true incoming caller support until a real call hierarchy exists.",
-      "Does not collapse unrelated impact or search concerns into the graph surface.",
-    ],
-  },
-  {
-    name: "code_impact",
-    label: "Code Impact",
-    parameters: CodeImpactParameters,
-    spillToTempFile: true,
-    run: (params, ctx) => executeImpactTool(params as Parameters<typeof executeImpactTool>[0], ctx),
-    purpose:
-      "Estimate blast radius for a target, user-supplied change set, or proposed change description, including likely tests and docs.",
-    schemaKey: "code_impact",
-    schemaDocs:
-      "Accepts targetId, change, or changeSetFiles plus includeTests/maxResults. Runtime validation later requires at least one primary subject.",
-    absorbsTools: [],
-    absorbsBehaviors: [],
-    substrates: ["semantic", "structural", "search", "diagnostics"],
-    phase: "phase-4",
-    nonGoals: [
-      "Does not guarantee perfect downstream impact inference without substrate evidence.",
-    ],
+      "Target is handle, anchor, or symbol; all expands to the three surviving relations.",
+    substrates: ["semantic", "structural"],
+    nonGoals: ["No inferred tests.", "No file-level import/export inventories."],
   },
   {
     name: "code_find",
     label: "Code Find",
     parameters: CodeFindParameters,
-    spillToTempFile: true,
     run: (params, ctx) => executeFindTool(params as Parameters<typeof executeFindTool>[0], ctx),
-    purpose:
-      "Run unified ranked search across literal text, regex, AST, and semantic modes with one intent-level surface.",
-    schemaKey: "code_find",
-    schemaDocs:
-      "Requires query and supports scope, mode, kind, contextLines, and maxResults. Excludes speculative natural-language mode.",
-    absorbsTools: ["code_pattern"],
-    absorbsBehaviors: [],
-    substrates: ["semantic", "structural", "search"],
-    phase: "phase-2",
+    purpose: "Search structural source shape or semantic workspace symbols explicitly.",
+    schemaDocs: `Requires query and ast/semantic mode; scope is optional and AST mode requires kind. AST enumeration uses a shared ${DEFAULT_AST_SCAN_TIMEOUT_MS / 1_000}-second deadline, a ${DEFAULT_AST_SCAN_MAX_FILES}-file cap, and canonical scope deduplication.`,
+    substrates: ["semantic", "structural"],
     nonGoals: [
-      "Does not activate natural-language retrieval without a real implementation.",
-      "Removed code_pattern in Phase 2b (TNDM-057XHJ).",
+      "No literal or regex text search; use PI grep when active.",
+      "No natural-language retrieval.",
+      "No silent mode fallback.",
+    ],
+  },
+  {
+    name: "code_health",
+    label: "Code Health",
+    parameters: CodeHealthParameters,
+    run: (params, ctx) => executeHealthTool(params as Parameters<typeof executeHealthTool>[0], ctx),
+    purpose: "Report live diagnostic, runtime, and structural health observations.",
+    schemaDocs: "Optional scope, refresh, include, and level; diagnostics and servers are default.",
+    substrates: ["semantic", "structural", "diagnostics"],
+    nonGoals: [
+      "Does not run tests or verification commands.",
+      "Does not load precomputed coverage or unused-code reports.",
     ],
   },
   {
     name: "code_refactor_plan",
     label: "Code Refactor Plan",
     parameters: CodeRefactorParameters,
-    run: async (params, ctx) => {
-      emitToolProgress(
-        ctx.onUpdate,
-        `code_refactor_plan: requesting ${(params as Record<string, unknown>).operation} plan from LSP...`,
-      );
-      return executeRefactorPlanTool(
-        params as Parameters<typeof executeRefactorPlanTool>[0],
-        ctx,
-        "code_refactor_plan",
-      );
-    },
-    purpose:
-      "Create precise refactor plans for named operations such as rename and extract refactors.",
-    schemaKey: "code_refactor_plan",
-    schemaDocs:
-      "Uses a scoped operation enum with target/file coordinates, optional selected range, and operation-specific options. This is the only intentional operation-style schema.",
-    absorbsTools: [],
-    absorbsBehaviors: [],
-    substrates: ["semantic", "structural", "search"],
-    phase: "phase-5",
-    nonGoals: [
-      "Does not introduce a broad action mega-tool.",
-      "code_refactor_plan is a pure planner; use code_refactor_apply to execute stored plans.",
-    ],
+    run: (params, ctx) =>
+      executeRefactorPlanTool(params as Parameters<typeof executeRefactorPlanTool>[0], ctx),
+    purpose: "Create a precise, non-mutating semantic refactor plan.",
+    schemaDocs: "Requires one handle/anchor target and one exact operation payload.",
+    substrates: ["semantic"],
+    nonGoals: ["Never mutates files.", "No heuristic text edits."],
   },
   {
     name: "code_refactor_apply",
@@ -222,36 +138,9 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
     parameters: CodeApplyParameters,
     run: (params, ctx) =>
       executeRefactorApplyTool(params as Parameters<typeof executeRefactorApplyTool>[0], ctx),
-    purpose: "Apply a previously stored plan through explicit, fingerprint-checked mutation.",
-    schemaKey: "code_refactor_apply",
-    schemaDocs:
-      "Requires a planId. Enforces stale-plan rejection, validation, and fingerprint checks before mutation.",
-    absorbsTools: [],
-    absorbsBehaviors: [],
-    substrates: ["semantic", "search", "git"],
-    phase: "phase-5",
-    nonGoals: [
-      "Does not bypass plan validation or fingerprint checks.",
-      "Format/verify modes are not implemented; they return explicit unavailable outcomes when added later.",
-    ],
-  },
-  {
-    name: "code_health",
-    label: "Code Health",
-    parameters: CodeHealthParameters,
-    run: (params, ctx) => executeHealthTool(params as Parameters<typeof executeHealthTool>[0], ctx),
-    purpose:
-      "Summarize diagnostics, provider state, dirty workspace signals, and maintenance cues from one workflow-oriented health surface.",
-    schemaKey: "code_health",
-    schemaDocs:
-      "Accepts scope, refresh, include sections, and detail level. It is the planned replacement for direct public diagnostic and recovery substrate access.",
-    absorbsTools: ["lsp_diagnostics", "lsp_recover"],
-    absorbsBehaviors: ["ci-status summary"],
-    substrates: ["semantic", "search", "git", "diagnostics"],
-    phase: "phase-6",
-    nonGoals: [
-      "Public lsp_* and tree_sitter_* tools were removed; only code_* tools remain on the public surface.",
-      "Does not act as a generic verification/test runner.",
-    ],
+    purpose: "Apply one stored, fingerprint-checked refactor plan.",
+    schemaDocs: "Requires the planId returned by code_refactor_plan.",
+    substrates: ["structural"],
+    nonGoals: ["Does not compose plans.", "Does not bypass freshness checks."],
   },
 ] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];

package/src/types/details.ts

@@ -5,16 +5,14 @@
  * Import new result assembly code from `../tool/result/types.ts` directly.
  */
 export type {
-  AffectedDetails,
   AnchoredResolutionMetadata,
   AnchoredResolutionSource,
-  BriefDetails,
   ContextDetails,
   DisambiguationCandidate,
   HealthDetails,
-  ImpactDetails,
+  HealthSectionDetails,
   InspectDetails,
+  OrientationSectionDetails,
   ResolveDetails,
   SearchDetails,
-  TestSurfaceDetails,
 } from "../tool/result/types.ts";

package/src/types/execution.ts

@@ -1,10 +1,8 @@
 import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
 import type { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
 import type {
-  BriefDetails,
   ContextDetails,
   HealthDetails,
-  ImpactDetails,
   InspectDetails,
   ResolveDetails,
   SearchDetails,
@@ -22,9 +20,9 @@ import type {
  * to subprocesses / emit coarse `onUpdate` beats.
  *
  * The `session` property carries the per-workspace
- * `WorkspaceCodeIntelligenceSession` facade (ADR 0008) for centralized
- * provider access, target resolution, and plan management. Executors
- * must prefer `ctx.session` over ad-hoc session factories.
+ * `WorkspaceCodeIntelligenceSession` seam (ADR 0015) for workflow policy,
+ * target resolution, and plan management. Executors must prefer
+ * `ctx.session` over ad-hoc session factories.
  */
 export interface CodeIntelToolExecCtx {
   cwd: string;
@@ -33,15 +31,10 @@ export interface CodeIntelToolExecCtx {
   /** Progress callback; long-running executors emit coarse beats, not chatty ones. */
   onUpdate?: AgentToolUpdateCallback;
   /**
-   * Per-workspace code-intelligence session facade.
+   * Per-workspace code-intelligence session.
    *
-   * Provides centralized access to:
-   * - Provider state: {@link WorkspaceCodeIntelligenceSession.getProviders}
-   * - Target resolution: {@link WorkspaceCodeIntelligenceSession.expandTargetId}
-   * - Plan management: {@link WorkspaceCodeIntelligenceSession.storePlan}
-   *
-   * Present on every execution. Executors that need it should destructure
-   * `{ cwd, session }` from their ctx parameter.
+   * Exposes typed intent workflows while keeping providers, mutable targets,
+   * plans, and runtime policy internal. Present on every execution.
    */
   session: WorkspaceCodeIntelligenceSession;
 }
@@ -50,11 +43,9 @@ export interface CodeIntelToolExecCtx {
 export interface CodeIntelResult {
   content: string;
   details?:
-    | { type: "brief"; data: BriefDetails }
     | { type: "context"; data: ContextDetails }
     | { type: "inspect"; data: InspectDetails }
     | { type: "search"; data: SearchDetails }
-    | { type: "impact"; data: ImpactDetails }
     | { type: "resolve"; data: ResolveDetails }
     | { type: "health"; data: HealthDetails };
 }

package/src/types/index.ts

@@ -13,16 +13,14 @@ export type { CodeIntelResult, CodeIntelToolExecCtx } from "./execution.ts";
 // ── Detail types ────────────────────────────────────────────────────────
 
 export type {
-  AffectedDetails,
   AnchoredResolutionMetadata,
   AnchoredResolutionSource,
-  BriefDetails,
   ContextDetails,
   DisambiguationCandidate,
   HealthDetails,
-  ImpactDetails,
+  HealthSectionDetails,
   InspectDetails,
+  OrientationSectionDetails,
   ResolveDetails,
   SearchDetails,
-  TestSurfaceDetails,
 } from "./details.ts";

package/src/types/tool-names.ts

@@ -5,7 +5,6 @@ export const CODE_INTELLIGENCE_TOOL_NAMES = [
   "code_orientation",
   "code_find",
   "code_graph",
-  "code_impact",
   "code_refactor_plan",
   "code_refactor_apply",
   "code_health",
@@ -28,7 +27,7 @@ export interface PlannerRoute {
    * The preferred execution strategy for this intent.
    * - `semantic`: use LSP first
    * - `structural`: use tree-sitter first
-   * - `search`: use explicit text/heuristic search
+   * - `search`: use an explicit code-aware search workflow
    * - `unavailable`: no capability can satisfy this intent
    */
   preferred: "semantic" | "structural" | "search" | "unavailable";

package/src/ui/footer.ts

@@ -12,10 +12,10 @@ import type { LspAdapterState } from "../substrate/lsp/state.ts";
 /** Build the LSP status text: "λ lsp • 2 servers • 5 open files" */
 export function buildLspStatusText(lspState: LspAdapterState): string | undefined {
   const controller = lspState.controller;
-  const service = controller?.service;
-  if (!service) return undefined;
+  const runtime = controller?.workspaceRuntime;
+  if (!runtime) return undefined;
 
-  const servers = service.getProjectServers();
+  const servers = runtime.getProjectServers();
   const runningServers = servers.filter((s) => s.status === "running").length;
   const openFiles = servers.reduce((sum, s) => sum + s.openFiles.length, 0);
 

package/src/ui/markdown/gather.ts

@@ -5,11 +5,17 @@
  * noExcessiveLinesPerFile threshold.
  */
 
-import { resolve } from "node:path";
-import type { SourceRange } from "@mrclrchtr/supi-code-runtime/api";
-import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
-import type { CodeProvider } from "../../analysis/provider.ts";
-import { diagnosticMessageString } from "../../substrate/lsp/utils.ts";
+import type {
+  SemanticProvider,
+  SourceRange,
+  StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
+
+export type ContextGatherProvider = Pick<
+  StructuralProvider,
+  "nodeAt" | "outline" | "imports" | "exports"
+> &
+  Partial<Pick<SemanticProvider, "hover" | "definition">>;
 
 export interface TreeSitterContext {
   nodeInfo: {
@@ -32,13 +38,11 @@ export interface TreeSitterContext {
   hover: { contents: string; range?: SourceRange } | null;
   /** Best-effort LSP definition targets at the anchored position. `null` when unavailable. */
   definition: Array<{ uri: string; range: SourceRange }> | null;
-  /** Best-effort code action titles at the anchored position. `null` when unavailable. */
-  codeActions: Array<{ title: string; kind?: string }> | null;
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: best-effort substrate gathering with independent try/catch blocks kept together for readability
 export async function gatherTreeSitterContext(
-  provider: CodeProvider | null,
+  provider: ContextGatherProvider | null,
   relPath: string,
   line: number,
   character: number,
@@ -49,10 +53,8 @@ export async function gatherTreeSitterContext(
   let exports: TreeSitterContext["exports"] = [];
   let hover: TreeSitterContext["hover"] = null;
   let definition: TreeSitterContext["definition"] = null;
-  let codeActions: TreeSitterContext["codeActions"] = null;
 
-  if (!provider)
-    return { nodeInfo, outline, imports, exports, hover, definition: null, codeActions: null };
+  if (!provider) return { nodeInfo, outline, imports, exports, hover, definition: null };
 
   try {
     const nodeResult = await provider.nodeAt(relPath, line, character);
@@ -96,7 +98,7 @@ export async function gatherTreeSitterContext(
           line: line - 1,
           character: character - 1,
         });
-        if (hoverResult) hover = hoverResult;
+        if (hoverResult.kind !== "unavailable" && hoverResult.data) hover = hoverResult.data;
       } catch {
         // hover failed — continue without it
       }
@@ -109,8 +111,8 @@ export async function gatherTreeSitterContext(
           line: line - 1,
           character: character - 1,
         });
-        if (defResult && defResult.length > 0) {
-          definition = defResult.map((loc) => ({
+        if (defResult.kind !== "unavailable" && defResult.data.length > 0) {
+          definition = defResult.data.map((loc) => ({
             uri: loc.uri,
             range: loc.range,
           }));
@@ -119,59 +121,9 @@ export async function gatherTreeSitterContext(
         // definition failed — continue without it
       }
     }
-
-    // Best-effort code actions — LSP expects 0-based coordinates
-    if (provider.codeActionTitles) {
-      try {
-        const titles = await provider.codeActionTitles(relPath, {
-          line: line - 1,
-          character: character - 1,
-        });
-        if (titles && titles.length > 0) {
-          codeActions = titles.map((a) => ({
-            title: a.title,
-            kind: a.kind,
-          }));
-        }
-      } catch {
-        // code actions failed — continue without it
-      }
-    }
   } catch {
     // Provider not available
   }
 
-  return { nodeInfo, outline, imports, exports, hover, definition, codeActions };
-}
-
-export interface NearbyDiagnostic {
-  line: number;
-  severity: number;
-  message: string;
-}
-
-// biome-ignore lint/complexity/useMaxParams: lspService is a DI seam, not a logic parameter
-export async function gatherNearbyDiagnostics(
-  cwd: string,
-  file: string,
-  line: number,
-  maxResults: number,
-  lspService: SessionLspServiceState,
-): Promise<NearbyDiagnostic[]> {
-  if (lspService.kind !== "ready") return [];
-
-  try {
-    const diagnostics = await lspService.service.fileDiagnostics(resolve(cwd, file), 4);
-    if (!diagnostics || diagnostics.length === 0) return [];
-
-    const nearby = diagnostics.filter((d) => Math.abs(d.range.start.line + 1 - line) <= 2);
-    const chosen = nearby.length > 0 ? nearby : diagnostics;
-    return chosen.slice(0, maxResults).map((d) => ({
-      line: d.range.start.line + 1,
-      severity: d.severity ?? 1,
-      message: diagnosticMessageString(d),
-    }));
-  } catch {
-    return [];
-  }
+  return { nodeInfo, outline, imports, exports, hover, definition };
 }