@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/tool/graph/tui.ts

@@ -62,15 +62,13 @@ export function renderGraphResult(
     return container;
   }
 
-  const omittedCount = (details?.omittedCount as number) ?? 0;
-
   if (!options.expanded) {
-    container.addChild(buildSimpleCompact(details ?? undefined, theme, { omittedCount }));
+    container.addChild(buildSimpleCompact(details ?? undefined, theme));
     return container;
   }
 
   // Expanded view
-  const header = buildSimpleHeader(details ?? undefined, theme, { omittedCount });
+  const header = buildSimpleHeader(details ?? undefined, theme);
   if (header) container.addChild(header);
 
   const evidenceLists = details?.evidenceLists as EvidenceEntry[] | undefined;
@@ -79,11 +77,6 @@ export function renderGraphResult(
     renderEvidenceLines(container, evidenceLists, theme);
   }
 
-  if (details?.tests) {
-    container.addChild(new Spacer(1));
-    container.addChild(buildTestsSection(details.tests as Record<string, unknown>, theme));
-  }
-
   renderStructuredDetailBody(container, details ?? undefined, theme);
   renderMarkdownDetail(container, result, theme);
 
@@ -100,23 +93,12 @@ function formatRelations(relations: GraphRelation[]): string {
 }
 
 function formatTarget(params: CodeGraphToolParams): string {
-  if (params.symbol) return `of ${params.symbol}`;
-  if (params.file) {
-    const file = params.file.split("/").pop() ?? params.file;
-    if (params.line) return `at ${file}:${params.line}`;
-    return `of ${file}`;
+  if ("symbol" in params.target) return `of ${params.target.symbol.query}`;
+  if ("anchor" in params.target) {
+    const point = params.target.anchor;
+    const file = point.file.split("/").pop() ?? point.file;
+    return `at ${file}:${point.line}`;
   }
+  if ("handle" in params.target) return `of ${params.target.handle}`;
   return "";
 }
-
-function buildTestsSection(tests: Record<string, unknown>, theme: Theme): Text {
-  const fileCount = (tests.files as Array<unknown> | undefined)?.length ?? 0;
-  if (fileCount === 0) {
-    return new Text(theme.fg("dim", "No companion test files found"), 0, 0);
-  }
-  return new Text(
-    theme.fg("dim", `${fileCount} companion test file${fileCount !== 1 ? "s" : ""}`),
-    0,
-    0,
-  );
-}

package/src/tool/guidance.ts

@@ -1,15 +1,13 @@
-// Prompt guidance and tool descriptions for the focused code-intelligence tool surface.
-//
-// Each code_* tool owns its complete promptGuidelines here.
-// Runtime registration data (name, parameters, run) lives in specs.ts.
-//
-// Cross-tool steering is centralized (authored once on its natural-home tool) and
-// some tools have empty promptGuidelines by design: all code_* tools are always
-// active together, so a steering bullet on one tool is always co-visible. See
-// docs/adr/0013-centralized-code-intelligence-prompt-steering-assumes-all-tools-active.md.
+// Model-facing descriptions and concise sibling-selection guidance.
 
+import {
+  DEFAULT_AST_SCAN_MAX_FILES,
+  DEFAULT_AST_SCAN_TIMEOUT_MS,
+} from "../analysis/search/ast-scan.ts";
 import type { CodeIntelligenceToolName } from "../types/index.ts";
 
+const AST_SCAN_TIMEOUT_SECONDS = DEFAULT_AST_SCAN_TIMEOUT_MS / 1_000;
+
 export interface CodeIntelligenceToolPromptSurface {
   description: string;
   promptSnippet: string;
@@ -24,78 +22,63 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
 export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptSurfaceMap = {
   code_resolve: {
     description:
-      "Resolve references to evidence-backed code targets and stable targetId/spanId handles for follow-up code_* tools. Accepts query/symbol/file or anchored file+line+character; anchored resolution snaps only to real provider-backed symbols, and whitespace/comment/non-symbol points fail with code_inspect guidance. No text-search fallback; ambiguous results return ranked candidates. Truncates at 2000 lines/50KB.",
-    promptSnippet: "code_resolve — resolve references into precise targets and target handles",
+      "Resolve one provider-backed anchor or semantic symbol query to session handles, or enumerate a file's declarations as a bounded Target group. Requires a concrete ready LSP client; anchors must identify real symbols, and symbol lookup never falls back to text search. symbolKind is an exact provider-reported LSP kind filter. File groups keep overloads distinct and disclose omissions and provenance.",
+    promptSnippet: "code_resolve — resolve a precise target or enumerate a file’s target group",
     promptGuidelines: [
-      "Use code_resolve first for ambiguous or symbol-only targets, before graph/impact/refactor/orientation; if resolve returns ranked candidates, narrow with a candidate file + line + character.",
+      "Use code_resolve when a symbol query may be ambiguous, when later calls should share a stable target handle, or when a known file’s declarations should be enumerated.",
     ],
   },
   code_inspect: {
     description:
-      "Inspect one exact file position for syntax, symbol, hover/definition, nearby diagnostics, and code-action titles. Requires file, line, and character; use for point facts, not broad orientation. Unavailable providers are disclosed; code actions are advisory only. Truncates at 2000 lines/50KB.",
+      "Inspect one exact point for syntax, the narrowest enclosing declaration, hover, definition, and diagnostics intersecting the nearby line window. Use for point facts, not broad Orientation. Completed-empty, partial, and unavailable sections are disclosed independently; no action is applied.",
     promptSnippet: "code_inspect — factual point inspection",
-    // No guidelines: selection is steered by code_orientation's bullet plus this
-    // self-sufficient description. See ADR 0013 (all code_* tools always active).
     promptGuidelines: [],
   },
   code_orientation: {
     description:
-      "Orient around the workspace, module, directory, file, or resolved symbol before surgical work. Omit focus for workspace orientation; use focus for a path/module, or targetId/focus+line+character for symbol orientation. Directory focus may surface local instruction files (CLAUDE.md, AGENTS.md). targetId wins and stale IDs error. Returns landmarks, docs, local diagnostics, and read-next guidance; relations/impact/health belong in code_graph/code_impact/code_health. maxResults caps lists; output is truncated to 2000 lines / 50KB.",
-    promptSnippet: "code_orientation — project/module/file/symbol orientation",
+      "Orient around the workspace or one path, module, or target focus before surgical work. Omit focus for workspace Orientation. Directory focus may surface local instruction files. Use code_graph for relations and code_health for health.",
+    promptSnippet: "code_orientation — workspace/path/module/symbol Orientation",
     promptGuidelines: [
-      "Use `code_orientation({ focus })` for first-pass project/package/directory/file orientation before `bash`/`read`.",
-      "Use directory focus (for example `packages/foo`) to surface local instruction files before package work.",
-      "Use code_resolve first for bare symbol names, then pass the resulting targetId to code_orientation.",
-      "Use code_graph/code_impact/code_health for relations, impact, or full health instead of asking code_orientation for those sections.",
+      "Use code_orientation before broad file reading when you need direct workspace, package, directory, file, or symbol facts.",
+      "Use focus.path for a known workspace path, focus.module for a discovered module name, and focus.target for a precise symbol.",
+      "Use code_graph for relationships and code_health for provider or diagnostic state.",
     ],
   },
   code_graph: {
     description:
-      'Analyze relation evidence for a resolved target or coordinates: references, structural callees, imports/exports, implementations, and tests. Defaults to references; relations:["all"] expands all families. Per-relation substrate failures are disclosed. Callees are syntax/direct-scope source-shape calls, not symbol identity; calleeDepth:"deep" includes nested scopes. Scope narrows by workspace path; targetId from code_resolve is preferred. Truncates at 2000 lines/50KB.',
-    promptSnippet: "code_graph — semantic and structural relation graph",
-    // No guidelines: selection is steered by this self-sufficient description plus
-    // code_impact's "use code_graph instead of code_impact" bullet. See ADR 0013.
+      'Collect references, structural callees, and implementations for one target. Defaults to references; "all" selects all three. Callees match source shape, not symbol identity; calleeDepth:"deep" includes nested scopes. Per-relation failures are disclosed; no edges are invented.',
+    promptSnippet: "code_graph — provider-backed and structural relation evidence",
     promptGuidelines: [],
   },
-  code_impact: {
-    description:
-      "Estimate blast radius for a resolved target or user-supplied changeSetFiles before editing. changeSetFiles are explicit files, not inferred from git and no line-level diff; change-only requests report insufficient evidence. Uses semantic references plus deterministic test discovery when available; no heuristic search fallback. Output includes read-next guidance; truncates at 2000 lines/50KB.",
-    promptSnippet: "code_impact — blast radius and impact",
+  code_find: {
+    description: `Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic"; AST requires kind. Use PI grep for literal/regex source search. Modes never silently fall back. Definition/type/interface/class/method/enum use outline support; import/export use their matching extractors; call uses registered call-site queries. Unscoped AST scans visible regular files supported by the selected kind's structural operation, excluding hidden entries and common generated/dependency directories without reading ignore files or following descendant symlinks. Explicit roots are honored; operation-ineligible files are disclosed, and exact ineligible scopes fail rather than widening. A ${AST_SCAN_TIMEOUT_SECONDS}-second deadline and ${DEFAULT_AST_SCAN_MAX_FILES}-file cap cover enumeration and analysis. Incomplete scans disclose limitations and unknown match totals.`,
+    promptSnippet: "code_find — explicit structural or semantic code search",
     promptGuidelines: [
-      "Use code_graph instead of code_impact when you only need a plain reference list.",
+      "Use code_find for structural or semantic search evidence; use PI grep for literal/regex source search and code_graph references for symbol-identity relationships.",
     ],
   },
-  code_find: {
+  code_health: {
     description:
-      'Search code with explicit modes: text literal (default), regex, semantic workspace-symbol, or ast structured. mode:"ast" requires `kind` (definition/import/export/call/type/interface/class/method/enum/test); text/regex/semantic reject kind. Semantic mode uses LSP only and does not silently fall back. AST call matches written call-site names, not by symbol identity; use code_graph references on a resolved target for symbol-identity-aware callers. Truncates at 2000 lines/50KB.',
-    promptSnippet: "code_find — unified ranked code search",
+      "Report live diagnostics as observations, language-server status, and final semantic health state. Use refresh:true to report a diagnostic-recovery attempt before finalizing semantic state. Tracked-file snapshots do not prove workspace completeness; server inventory is workspace-wide. Capability Warnings supplement diagnostic/server results.",
+    promptSnippet: "code_health — live workspace health observations",
     promptGuidelines: [
-      "Use code_find for explicit text, regex, semantic symbol, or AST search; use code_graph references for symbol-identity callers.",
+      "Use code_health with refresh:true before relying on potentially stale diagnostics.",
     ],
   },
   code_refactor_plan: {
     description:
-      "Preview a semantic refactor plan and return planId; never mutates files. Supports rename_symbol (rename alias) and extract_function/extract_variable when LSP returns precise edits. Requires targetId or anchored file+line+character, plus operation-specific newName/range. Apply separately with code_refactor_apply. Truncates at 2000 lines/50KB.",
-    promptSnippet: "code_refactor_plan — preview a precise workflow refactor plan",
+      "Preview a precise semantic rename or extraction and return a planId without mutating files. Requires one handle/anchor target and one operation; unavailable precise edits never fall back to text edits. Apply separately with code_refactor_apply.",
+    promptSnippet: "code_refactor_plan — preview a precise semantic refactor",
     promptGuidelines: [
-      "Use code_refactor_plan to preview rename/extract edits only; mutate later with code_refactor_apply and the returned planId.",
+      "Use code_refactor_plan for preview only, then explicitly call code_refactor_apply with its planId.",
     ],
   },
   code_refactor_apply: {
     description:
-      "Apply a stored refactor plan by planId. Revalidates plan freshness and file fingerprints before mutating; does not compose new plans. Truncates at 2000 lines/50KB.",
-    promptSnippet: "code_refactor_apply — apply a stored refactor plan",
+      "Apply one stored refactor plan by planId. Revalidates freshness, file fingerprints, ranges, and edit overlap before mutation; never composes or regenerates plans.",
+    promptSnippet: "code_refactor_apply — apply a fresh stored refactor plan",
     promptGuidelines: [
       "Use code_refactor_apply only with a planId returned by code_refactor_plan.",
     ],
   },
-  code_health: {
-    description:
-      "Report workspace health: diagnostics, language-server status, dirty files, coverage, and unused code. Use scope/include/level to narrow; refresh:true recovers stale diagnostics. Missing coverage/unused reports are disclosed. Truncates at 2000 lines/50KB.",
-    promptSnippet:
-      "code_health — diagnostics, server status, coverage, unused-code, and workspace health",
-    promptGuidelines: [
-      "Use code_health for diagnostics/server/dirty/coverage/unused health; pass refresh:true to code_health before relying on stale diagnostics.",
-    ],
-  },
 };

package/src/tool/health/execute.ts

@@ -1,76 +1,35 @@
-/**
- * Tool executor for code_health.
- *
- * Thin executor: validates scope, extracts provider state from the
- * session, and delegates to the health use-case which handles data
- * collection, rendering, and details construction.
- */
+/** Thin Pi adapter for the session-owned code_health workflow. */
 
-import { resolveScope } from "../../analysis/search/ripgrep.ts";
+import type { HealthSection, HealthWorkflowInput } from "../../session/health-types.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
 import { unavailableHealthDetails } from "../infra/error-results.ts";
-import { emitToolProgress } from "../infra/progress.ts";
-import {
-  executeHealth,
-  getLastHealthRefresh,
-  type HealthInput,
-  trackHealthRefresh,
-} from "./orchestrate.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { assembleHealthResult } from "../result/health.ts";
+import { renderHealthResult } from "./markdown.ts";
 
 export interface CodeHealthToolParams {
   scope?: string;
   refresh?: boolean;
-  include?: string[];
+  include?: HealthSection[];
   level?: "summary" | "detailed";
-  coveragePath?: string;
-  unusedPath?: string;
 }
 
 export async function executeHealthTool(
   params: CodeHealthToolParams,
   ctx: CodeIntelToolExecCtx,
 ): Promise<CodeIntelResult> {
-  const cwd = ctx.cwd;
-  emitToolProgress(ctx.onUpdate, "code_health: gathering workspace health...");
-
-  const scopeResolution = resolveScope(params.scope, cwd);
-  if (scopeResolution.kind === "error") {
+  const outcome = await ctx.session.health(params as HealthWorkflowInput, toWorkflowControl(ctx));
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
     return {
-      content: `**Error:** ${scopeResolution.reason}`,
-      details: unavailableHealthDetails("scope not found"),
+      content: `**Error:** ${outcome.message}`,
+      details: unavailableHealthDetails("invalid input"),
     };
   }
-  const scopeFilter = scopeResolution.path === cwd ? null : scopeResolution.path;
-
-  if (params.refresh) {
-    trackHealthRefresh(cwd);
-  }
 
-  const providerState = ctx.session.getProviders();
-  const workspaceState = ctx.session.getWorkspaceState();
-  const lspState =
-    providerState.kind === "ready"
-      ? providerState.lspService
-      : { kind: "unavailable" as const, reason: "No provider" };
-
-  const input: HealthInput = {
-    scope: params.scope,
-    refresh: params.refresh,
-    include: params.include,
-    level: params.level,
-    coveragePath: params.coveragePath,
-    unusedPath: params.unusedPath,
+  const assembly = assembleHealthResult(outcome.data);
+  return {
+    content: renderHealthResult(assembly, ctx.cwd),
+    details: { type: "health", data: assembly.details },
   };
-
-  return executeHealth(input, {
-    cwd,
-    lspState,
-    providerAvailable: providerState.kind === "ready",
-    semanticStateKind: workspaceState.semantic.state.kind,
-    structuralState: workspaceState.structural.state,
-    lspController: ctx.session.lspController,
-    onUpdate: ctx.onUpdate,
-    scopeFilter,
-    lastRefresh: getLastHealthRefresh(cwd),
-  });
 }