@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.1

package/src/tool/graph/references.ts

@@ -0,0 +1,81 @@
+/**
+ * Semantic caller collection — finds references for a target.
+ *
+ * Returns typed caller data with explicit evidence metadata
+ * ("semantic-references" since we use LSP references as caller evidence).
+ */
+
+import type { CallerEvidence, CallerReference, RelationsServiceDeps } from "./types.ts";
+
+export interface CallersResult {
+  kind: "callers";
+  targetName: string;
+  references: CallerReference[];
+  externalCount: number;
+  evidence: CallerEvidence;
+  confidence: "semantic" | "unavailable";
+}
+
+/**
+ * Collect callers (references) for a target file/position using semantic provider.
+ */
+// biome-ignore lint/complexity/useMaxParams: service function with clear positional parameters matching provider contract
+export async function collectCallers(
+  targetFile: string,
+  targetPosition: { line: number; character: number },
+  targetName: string | null,
+  deps: RelationsServiceDeps,
+  maxResults?: number,
+): Promise<CallersResult> {
+  if (!deps.provider?.references) {
+    return {
+      kind: "callers",
+      targetName: targetName ?? "symbol",
+      references: [],
+      externalCount: 0,
+      evidence: "semantic-references",
+      confidence: "unavailable",
+    };
+  }
+
+  const refs = await deps.provider.references(targetFile, targetPosition);
+  if (!refs) {
+    return {
+      kind: "callers",
+      targetName: targetName ?? "symbol",
+      references: [],
+      externalCount: 0,
+      evidence: "semantic-references",
+      confidence: "semantic",
+    };
+  }
+
+  const inProject: CallerReference[] = [];
+  let externalCount = 0;
+
+  for (const ref of refs) {
+    const uri = ref.uri ?? "";
+    const filePath = uri.startsWith("file://") ? uri.slice(7) : uri;
+    if (filePath.startsWith(deps.cwd)) {
+      inProject.push({
+        file: filePath,
+        line: ref.range.start.line + 1,
+        character: ref.range.start.character + 1,
+        name: targetName,
+      });
+    } else {
+      externalCount++;
+    }
+  }
+
+  void maxResults;
+
+  return {
+    kind: "callers",
+    targetName: targetName ?? "symbol",
+    references: inProject,
+    externalCount,
+    evidence: "semantic-references",
+    confidence: "semantic",
+  };
+}

package/src/tool/graph/tui.ts

@@ -0,0 +1,120 @@
+/**
+ * TUI renderer for code_graph — renderCall + renderResult.
+ *
+ * Dual-surface rendering: chrome built from details, markdown body
+ * available as a collapsible detail view.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import {
+  buildSimpleCompact,
+  buildSimpleHeader,
+  type EvidenceEntry,
+  type ResultOptios,
+  renderEvidenceLines,
+  renderMarkdownDetail,
+  renderPartial,
+  type ToolResult,
+} from "../../ui/tui/common.ts";
+import type { CodeGraphToolParams, GraphRelation } from "./execute.ts";
+
+/** ── renderCall ────────────────────────────────────────────────── */
+
+export function renderGraphCall(args: unknown, theme: Theme, _context: unknown): Text {
+  const params = (args ?? {}) as CodeGraphToolParams;
+  const relations = params.relations ?? ["references"];
+  const relationLabel = formatRelations(relations);
+
+  let content = theme.fg("toolTitle", "code_graph");
+
+  if (relationLabel) {
+    content += ` ${theme.fg("accent", relationLabel)}`;
+  }
+
+  const target = formatTarget(params);
+  if (target) {
+    content += ` ${theme.fg("muted", target)}`;
+  }
+
+  return new Text(content, 0, 0);
+}
+
+/** ── renderResult ──────────────────────────────────────────────── */
+
+export function renderGraphResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  _context: unknown,
+): Container | Text {
+  if (options.isPartial) {
+    return renderPartial("Collecting relations…", theme);
+  }
+
+  const container = new Container();
+  const details =
+    result.details?.type === "search" ? (result.details.data as Record<string, unknown>) : null;
+
+  if (result.isError) {
+    container.addChild(new Text(theme.fg("error", "code_graph failed"), 0, 0));
+    return container;
+  }
+
+  const omittedCount = (details?.omittedCount as number) ?? 0;
+
+  if (!options.expanded) {
+    container.addChild(buildSimpleCompact(details ?? undefined, theme, { omittedCount }));
+    return container;
+  }
+
+  // Expanded view
+  const header = buildSimpleHeader(details ?? undefined, theme, { omittedCount });
+  if (header) container.addChild(header);
+
+  const evidenceLists = details?.evidenceLists as EvidenceEntry[] | undefined;
+  if (evidenceLists && evidenceLists.length > 0) {
+    container.addChild(new Spacer(1));
+    renderEvidenceLines(container, evidenceLists, theme);
+  }
+
+  if (details?.tests) {
+    container.addChild(new Spacer(1));
+    container.addChild(buildTestsSection(details.tests as Record<string, unknown>, theme));
+  }
+
+  renderMarkdownDetail(container, result, theme);
+
+  return container;
+}
+
+/** ── Helpers ───────────────────────────────────────────────────── */
+
+function formatRelations(relations: GraphRelation[]): string {
+  if (relations.length === 0) return "";
+  if (relations.length === 1) return `→ ${relations[0]}`;
+  if (relations.length <= 3) return `→ ${relations.join(", ")}`;
+  return `→ ${relations.slice(0, 2).join(", ")} +${relations.length - 2}`;
+}
+
+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}`;
+  }
+  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/graph/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared types for the relations analysis modules.
+ *
+ * These are the canonical entry-point types — consumers import them directly
+ * instead of going through thin service wrappers.
+ */
+
+/** Describes how caller evidence was collected. */
+export type CallerEvidence = "semantic-references" | "verified-call-sites";
+
+/** One caller reference / usages result. */
+export interface CallerReference {
+  file: string;
+  line: number;
+  character: number;
+  name: string | null;
+}
+
+/** Consumer-facing alias for reference/usages entries. */
+export type ReferenceEntry = CallerReference;
+
+/** Enclosing scope used for direct structural callee lookup. */
+export interface CalleeScope {
+  name: string;
+  file: string;
+  startLine: number;
+  endLine: number;
+}
+
+/** One direct structural callee entry from an enclosing-scope lookup. */
+export interface CalleeEntry {
+  name: string;
+  file: string;
+  line: number;
+  character: number;
+}
+
+/** Consumer-facing display entry for structural calls (no character). */
+export type CallEntry = Omit<CalleeEntry, "character">;
+
+/** One implementation entry from a semantic implementation lookup. */
+export interface ImplementationEntry {
+  file: string;
+  line: number;
+  character: number;
+  name: string | null;
+}
+
+/** Shared provider deps for all relation kinds. */
+export interface RelationsServiceDeps {
+  cwd: string;
+  provider: {
+    references?: (
+      file: string,
+      pos: { line: number; character: number },
+    ) => Promise<Array<{
+      uri: string;
+      range: {
+        start: { line: number; character: number };
+        end: { line: number; character: number };
+      };
+    }> | null>;
+    implementation?: (
+      file: string,
+      pos: { line: number; character: number },
+    ) => Promise<Array<{
+      uri?: string;
+      targetUri?: string;
+      range?: { start: { line: number }; end?: { line: number } };
+      targetRange?: { start: { line: number }; end?: { line: number } };
+    }> | null>;
+    calleesAt?: (
+      file: string,
+      line: number,
+      character: number,
+      depth?: "direct" | "deep",
+    ) => Promise<{
+      kind: string;
+      data?: {
+        enclosingScope?: {
+          name?: string;
+          startLine?: number;
+          endLine?: number;
+        };
+        callees: Array<{
+          name: string;
+          file?: string;
+          location?: string;
+          startLine?: number;
+          startCharacter?: number;
+        }>;
+        depth?: "direct" | "deep";
+      };
+      message?: string;
+    }>;
+  } | null;
+}

package/src/tool/guidance.ts

@@ -1,10 +1,9 @@
 // Prompt guidance and tool descriptions for the focused code-intelligence tool surface.
 //
-// Each code_* tool owns its base prompt guidelines (describing its own surface).
-// Additional cross-family orchestration guidelines are appended to help the
-// model choose between code_*, lsp_*, and tree_sitter_* tools.
+// Each code_* tool owns its complete promptGuidelines here.
+// Runtime registration data (name, parameters, run) lives in specs.ts.
 
-import { CODE_INTELLIGENCE_TOOL_SPECS, type CodeIntelligenceToolName } from "./tool-specs.ts";
+import type { CodeIntelligenceToolName } from "../types/index.ts";
 
 export interface CodeIntelligenceToolPromptSurface {
   description: string;
@@ -17,49 +16,97 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
   CodeIntelligenceToolPromptSurface
 >;
 
-// ── Intent-first orchestration guidelines ─────────────────────────────
-//
-// These steer the model toward choosing tools by user intent rather than
-// by implementation family.  Substrate tools (lsp_*, tree_sitter_*) are
-// described as expert follow-up surfaces, not the primary choice.
-
-const INTENT_GUIDELINES: Record<CodeIntelligenceToolName, string[]> = {
-  code_brief: [
-    "Use code_brief for prioritized orientation on a project, package, file, or symbol.",
-    "The planner selects the best provider (semantic or structural) automatically.",
-    "After code_brief, use lsp_hover/lsp_definition/lsp_references for deeper semantic detail or tree_sitter_* for quick structural context.",
-  ],
-  code_map: ["Use code_brief instead when you need prioritized guidance."],
-  code_relations: [
-    "The planner routes callers/implementations to semantic (LSP) analysis and callees to structural (tree-sitter) analysis.",
-    "Follow caller results with lsp_references/lsp_definition for additional context; use tree_sitter_callees for structural outgoing calls as a debug surface.",
-  ],
-  code_affected: [
-    "Uses semantic evidence for blast-radius assessment. Does not fall back to heuristic text search.",
-    "Use lsp_references when you only need a plain reference list without impact analysis.",
-  ],
-  code_pattern: [
-    "The only code_* tool that uses heuristic/text search behavior. For structured or semantic precision, use tree_sitter_query or lsp_hover/lsp_definition instead.",
-  ],
-  code_refactor: [
-    "Uses semantic provider for precise rename/code-action operations with safety checks.",
-    "Does not fall back to heuristic text replacement — if the provider cannot produce precise edits, the tool reports unavailable.",
-  ],
+export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptSurfaceMap = {
+  code_resolve: {
+    description:
+      "Resolve human or code references into precise file/range/symbol targets and stable target handles. Use when a symbol, file, or code reference is ambiguous and needs precise resolution. Returns targetId and spanId handles that can be passed to code_graph, code_impact, and code_refactor_plan. Supports anchored (file + line + character), file-only, and query/symbol inputs. Anchored coordinates resolve a real symbol target from provider-backed evidence: an exact identifier coordinate resolves to a named target; a declaration-header coordinate (e.g. an `export` keyword) snaps to the symbol name anchor only when unambiguous. Whitespace/comment/non-symbol coordinates fail honestly and recommend code_inspect. Does not fall back to text search for symbol resolution; ambiguous results return ranked candidates with target IDs for every shown item. Output is truncated to 2000 lines / 50KB.",
+    promptSnippet: "code_resolve — resolve references into precise targets and target handles",
+    promptGuidelines: [
+      "Use code_resolve when a symbol, file, or code reference is ambiguous and needs precise resolution.",
+      "Prefer code_resolve as the entry point before code_orientation, code_graph, code_impact, or code_refactor_plan — its targetId replaces fragile file/line/character coordinates.",
+      "When code_resolve returns ambiguous results with ranked candidates, pick one and use file + line + character for follow-up resolution.",
+    ],
+  },
+  code_inspect: {
+    description:
+      "Inspect one precise point in a file and return factual syntax, symbol, hover, definition, diagnostics, and code-action information. Use when you need to understand exactly what is at a position without choosing between provider-specific substrate tools. When some providers are unavailable, returns best-effort sections with explicit unavailable notes instead of heuristic guesses. Code action titles are advisory only — there is no tool to execute them yet. Output is truncated to 2000 lines / 50KB.",
+    promptSnippet: "code_inspect — factual point inspection",
+    promptGuidelines: [
+      "Use code_inspect for factual point inspection at one precise file position.",
+      "Provide `file`, `line`, and `character` — code_inspect is intentionally point-based.",
+      "Prefer code_inspect over code_orientation for point-level facts when no symbol target can be resolved.",
+    ],
+  },
+  code_orientation: {
+    description:
+      "Primary code-orientation tool for understanding a project, discovered module, directory, file, or symbol before choosing surgical follow-up tools. Use `focus` for a workspace-relative path or discovered module name; omit `focus` for project orientation. Use `focus` + `line` + `character` for symbol orientation, or pass `targetId` from `code_resolve`; `targetId` takes precedence over focus/coordinates and stale target IDs do not fall back. Symbol orientation returns definitions, JSDoc/TSDoc docs, local diagnostics near the target, and Read Next guidance; relation evidence belongs in code_graph, impact evidence in code_impact, and health/status in code_health. Not a point-inspection tool — use code_inspect for exact position facts. `maxResults` caps each rendered list and defaults to 10. Output is truncated to 2000 lines / 50KB.",
+    promptSnippet: "code_orientation — project/module/file/symbol orientation",
+    promptGuidelines: [
+      "Use `code_orientation({ focus })` for first-pass project/package/directory/file orientation before `bash`/`read`.",
+      "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.",
+    ],
+  },
+  code_graph: {
+    description:
+      'Unified relation-graph tool — replaces code_references, code_calls, and code_implementations. Resolves a target once and dispatches to the appropriate analysis service per requested relation. Defaults to ["references"] when `relations` is omitted. Each relation is best-effort: unavailable substrates skip with a note rather than failing the whole call. Each relation annotates its evidence source. The tests relation displays discovery provenance (semantic+conventions or conventions-only) separately from any extracted test labels. `callees` is structural/direct-scope evidence: it reports call expressions by source shape, not symbol identity, and excludes calls inside nested function/method/callback scopes — use `references` on a resolved target for identity-aware incoming callers. Pass `calleeDepth: "deep"` to include callees from nested scopes. `imports` and `exports` use file-level tree-sitter analysis; `tests` discovers companion test files and labels. Targeted graph results include Read Next guidance for source ranges worth inspecting via `read`. `scope` (not `path`) narrows by workspace-relative directory/package. Use code_resolve first to get a targetId, then pass it to code_graph. Output is truncated to 2000 lines / 50KB.',
+    promptSnippet: "code_graph — semantic and structural relation graph",
+    promptGuidelines: [
+      "Use code_graph to find references, direct structural calls, and implementations for a target.",
+      'Default `relations` is ["references"]; use `relations: ["callees"]` or `["implements"]` for those, or `relations: ["all"]` to expand to every relation family in one call.',
+      "After code_graph, follow up with code_orientation on individual results for type or definition context.",
+      'Pass `calleeDepth: "deep"` to include callees from nested function/method/callback scopes (default `"direct"` excludes them).',
+      'Suggested relations by target kind: For functions/methods: `["references", "callees", "tests"]` — For interfaces/types/classes/enums: `["references", "implements"]` — For files/modules: `["imports", "exports"]` — For tests: `["tests"]`.',
+    ],
+  },
+  code_impact: {
+    description:
+      "Estimate blast radius and downstream impact for a target or user-supplied change set before making edits. `changeSetFiles` are explicit workspace-relative files to analyze as in scope for a proposed/current change; they are not inferred from git and carry no line-level diff evidence. Uses semantic evidence for target-based impact and merges semantic references for symbols defined in change-set files when available. Includes Read Next guidance for source ranges worth inspecting via `read` before editing. Does not fall back to heuristic text search. Use a resolved target for precise semantic reference-based impact. Output is truncated to 2000 lines / 50KB.",
+    promptSnippet: "code_impact — blast radius and impact",
+    promptGuidelines: [
+      "Use code_impact before edits to estimate blast radius and follow-up checks.",
+      "Use code_graph instead of code_impact when you only need a plain reference list without impact analysis.",
+    ],
+  },
+  code_find: {
+    description:
+      'Unified ranked code search with strict mode dispatch: default/`mode: "text"` is literal ripgrep, `mode: "regex"` is ripgrep regex, `mode: "semantic"` is LSP workspace-symbol search, and `mode: "ast"` is tree-sitter structured search. `mode: "ast"` requires `kind` and currently supports `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, `enum`, and `test`. `mode: "text"`, `mode: "regex"`, and `mode: "semantic"` do not accept `kind`. `code_find` with `mode: "semantic"` does not silently fall back to text search, and unsupported mode/kind combinations fail. AST `call` mode matches call-site identifiers by name, not by symbol identity; use `code_graph` references for identity-aware callers of a resolved target. Output is truncated to 2000 lines / 50KB.',
+    promptSnippet: "code_find — unified ranked code search",
+    promptGuidelines: [
+      "Use code_find as the sole code search tool for literal text, regex, semantic workspace-symbol, or AST structured search.",
+      'code_find with `mode: "ast"` requires `kind` and supports `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, `enum`, and `test`.',
+      'code_find with `mode: "text"`, `mode: "regex"`, or `mode: "semantic"` does not accept `kind`.',
+      'code_find with `mode: "semantic"` does not fall back to text search and fails when semantic capability is unavailable.',
+      'AST `call` mode matches call-site identifiers by name only; use `code_graph` with `relations: ["references"]` on a resolved target for symbol-identity-aware callers.',
+    ],
+  },
+  code_refactor_plan: {
+    description:
+      'Pure planner: previews a precise semantic refactor plan without mutating files and returns a planId for later use with code_refactor_apply. Supports rename_symbol plus extract_function/extract_variable when the active LSP can return precise edits. Legacy `operation: "rename"` is accepted as a compatibility alias. This tool never mutates files. Output is truncated to 2000 lines / 50KB.',
+    promptSnippet: "code_refactor_plan — preview a precise workflow refactor plan",
+    promptGuidelines: [
+      'Use `operation: "rename_symbol"` with code_refactor_plan for symbol renames. Legacy `operation: "rename"` is accepted as a compatibility alias.',
+      'Use `operation: "extract_function"` or `"extract_variable"` with a 1-based `range` and `newName` when the LSP advertises precise extract code actions.',
+      "code_refactor_plan is a pure planner — it returns a planId. Use code_refactor_apply with that planId to execute.",
+    ],
+  },
+  code_refactor_apply: {
+    description:
+      "Sole mutator in the refactor workflow: applies a previously stored plan by planId. Revalidates the plan and checks file fingerprints, mutating files only when the plan is still fresh. Output is truncated to 2000 lines / 50KB.",
+    promptSnippet: "code_refactor_apply — apply a stored refactor plan",
+    promptGuidelines: [
+      "Use code_refactor_apply to execute a plan generated by code_refactor_plan.",
+      "Use code_refactor_plan first to obtain a planId, then code_refactor_apply to execute it.",
+    ],
+  },
+  code_health: {
+    description:
+      "Summarize diagnostics, language server status, dirty workspace signals, coverage, and unused-code findings. Pass refresh: true to recover stale diagnostics before checking. Use scope to narrow to a specific file or package. Use include to request specific sections: diagnostics, servers, dirty, coverage, unused. Defaults to summary level (counts); use level: detailed for per-file listings. Output is truncated to 2000 lines / 50KB.",
+    promptSnippet:
+      "code_health — diagnostics, server status, coverage, unused-code, and workspace health",
+    promptGuidelines: [
+      "Use code_health to check for diagnostics, language server status, dirty workspace state, coverage, or unused-code signals.",
+      "Pass `refresh: true` to code_health to recover stale diagnostics before checking.",
+    ],
+  },
 };
-
-// ── Surface builder ────────────────────────────────────────────────────
-
-export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolPromptSurfaceMap {
-  return Object.fromEntries(
-    CODE_INTELLIGENCE_TOOL_SPECS.map((spec) => [
-      spec.name,
-      {
-        description: spec.description,
-        promptSnippet: spec.promptSnippet,
-        promptGuidelines: [...spec.basePromptGuidelines, ...INTENT_GUIDELINES[spec.name]],
-      } satisfies CodeIntelligenceToolPromptSurface,
-    ]),
-  ) as CodeIntelligenceToolPromptSurfaceMap;
-}
-
-export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES = buildCodeIntelligenceToolPromptSurfaces();

package/src/tool/health/execute.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+
+import { resolveScope } from "../../analysis/search/ripgrep.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";
+
+export interface CodeHealthToolParams {
+  scope?: string;
+  refresh?: boolean;
+  include?: string[];
+  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") {
+    return {
+      content: `**Error:** ${scopeResolution.reason}`,
+      details: unavailableHealthDetails("scope not found"),
+    };
+  }
+  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,
+  };
+
+  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),
+  });
+}