@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.1

package/src/tool/register.ts

@@ -0,0 +1,123 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import type { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
+import { renderFindCall, renderFindResult } from "./find/tui.ts";
+import { renderGraphCall, renderGraphResult } from "./graph/tui.ts";
+import {
+  CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
+  type CodeIntelligenceToolPromptSurfaceMap,
+} from "./guidance.ts";
+import { renderHealthCall, renderHealthResult } from "./health/tui.ts";
+import { renderImpactCall, renderImpactResult } from "./impact/tui.ts";
+import { truncateToolContent } from "./infra/truncate.ts";
+import { renderInspectCall, renderInspectResult } from "./inspect/tui.ts";
+import { renderOrientationCall, renderOrientationResult } from "./orientation/tui.ts";
+import { renderRefactorApplyCall, renderRefactorApplyResult } from "./refactor-apply/tui.ts";
+import { renderRefactorPlanCall, renderRefactorPlanResult } from "./refactor-plan/tui.ts";
+import { renderResolveCall, renderResolveResult } from "./resolve/tui.ts";
+import { CODE_INTELLIGENCE_TOOL_SPECS, type CodeIntelligenceToolDefinitionSpec } from "./specs.ts";
+
+interface ToolRenderer {
+  // biome-ignore lint/suspicious/noExplicitAny: pi render call/result signatures vary per tool; spread into pi.registerTool where concrete typing handles variance
+  renderCall?: (...args: any[]) => Component;
+  // biome-ignore lint/suspicious/noExplicitAny: same variance reason as renderCall
+  renderResult?: (...args: any[]) => Component;
+  renderShell?: "self";
+}
+
+function getToolRenderer(name: string): ToolRenderer {
+  switch (name) {
+    case "code_graph":
+      return {
+        renderCall: renderGraphCall,
+        renderResult: renderGraphResult,
+      };
+    case "code_health":
+      return {
+        renderCall: renderHealthCall,
+        renderResult: renderHealthResult,
+      };
+    case "code_orientation":
+      return {
+        renderCall: renderOrientationCall,
+        renderResult: renderOrientationResult,
+      };
+    case "code_resolve":
+      return { renderCall: renderResolveCall, renderResult: renderResolveResult };
+    case "code_inspect":
+      return { renderCall: renderInspectCall, renderResult: renderInspectResult };
+    case "code_find":
+      return { renderCall: renderFindCall, renderResult: renderFindResult };
+    case "code_impact":
+      return { renderCall: renderImpactCall, renderResult: renderImpactResult };
+    case "code_refactor_plan":
+      return {
+        renderCall: renderRefactorPlanCall,
+        renderResult: renderRefactorPlanResult,
+      };
+    case "code_refactor_apply":
+      return {
+        renderCall: renderRefactorApplyCall,
+        renderResult: renderRefactorApplyResult,
+      };
+    default:
+      return {};
+  }
+}
+
+/**
+ * Register the focused code-intelligence tool surface from shared specs.
+ *
+ * @param getOrCreateSession — session factory; production passes the app-managed
+ *   sessions, tests pass a `createSessionCache`-backed factory.
+ */
+export function registerCodeIntelligenceTools(
+  pi: ExtensionAPI,
+  getOrCreateSession: (cwd: string) => WorkspaceCodeIntelligenceSession,
+  promptSurfaces: CodeIntelligenceToolPromptSurfaceMap = CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
+  specs: readonly CodeIntelligenceToolDefinitionSpec[] = CODE_INTELLIGENCE_TOOL_SPECS,
+): void {
+  for (const spec of specs) {
+    const surface = promptSurfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface.description,
+      promptSnippet: surface.promptSnippet,
+      promptGuidelines: surface.promptGuidelines,
+      parameters: spec.parameters,
+      // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+      execute: async (_toolCallId, params, signal, onUpdate, ctx: ExtensionContext) => {
+        const session = getOrCreateSession(ctx.cwd);
+        const { content, details } = await spec.run(params, {
+          cwd: ctx.cwd,
+          signal,
+          onUpdate,
+          session,
+        });
+        const { text, truncated } = truncateToolContent(content, {
+          maxLines: spec.maxLines,
+          maxBytes: spec.maxBytes,
+        });
+        if (truncated && spec.spillToTempFile && content.length > 0) {
+          const dir = mkdtempSync(join(tmpdir(), "supi-ci-"));
+          const spillPath = join(dir, `${spec.name}-output.md`);
+          writeFileSync(spillPath, content, "utf-8");
+          const notice = `\n_Full output saved to: \`${spillPath}\`_`;
+          return {
+            content: [{ type: "text" as const, text: text + notice }],
+            details,
+          };
+        }
+        return {
+          content: [{ type: "text" as const, text }],
+          details,
+        };
+      },
+      ...getToolRenderer(spec.name),
+    });
+  }
+}

package/src/tool/resolve/execute.ts

@@ -0,0 +1,82 @@
+/**
+ * Tool executor for code_resolve.
+ *
+ * Thin adapter: validates params, gates readiness, delegates to orchestrate.
+ */
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { resolveCrossFieldRules } from "../infra/cross-field.ts";
+import { unavailableResolveDetails } from "../infra/error-results.ts";
+import {
+  expandTargetId,
+  gateSemanticReadiness,
+  resolveScopeParam,
+  runPipe,
+  validateParams,
+} from "../infra/pipeline.ts";
+import { renderSemanticReadinessTimeout } from "../infra/readiness-message.ts";
+import { orchestrateResolve } from "./orchestrate.ts";
+
+export interface CodeResolveToolParams {
+  query?: string;
+  scope?: string;
+  kind?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  maxResults?: number;
+  targetId?: string;
+}
+
+export async function executeResolveTool(
+  params: CodeResolveToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const needsSemantic = Boolean(params.query) && params.kind !== "file" && params.kind !== "File";
+
+  return runPipe(
+    params,
+    ctx,
+    [
+      expandTargetId((msg) => ({
+        content: msg,
+        details: unavailableResolveDetails([
+          "Fix the input parameters and retry",
+          "Use anchored `file` + `line` + `character` or a `query` for resolution",
+        ]),
+      })),
+      resolveScopeParam((reason) => ({
+        content: `**Error:** ${reason}`,
+        details: unavailableResolveDetails([
+          "Verify the `scope` path exists and is within the workspace",
+          "Use an existing workspace-relative file or directory path",
+        ]),
+      })),
+      validateParams(resolveCrossFieldRules, (msg) => ({
+        content: msg,
+        details: unavailableResolveDetails([
+          "Fix the input parameters and retry",
+          "Use anchored `file` + `line` + `character` or a `query` for resolution",
+        ]),
+      })),
+      ...(needsSemantic
+        ? [
+            gateSemanticReadiness("code_resolve", {
+              onTimeout: () => ({
+                content: renderSemanticReadinessTimeout("code_resolve", 15_000),
+                details: unavailableResolveDetails(["Retry shortly or check `code_health`"]),
+              }),
+              throwOnUnavailable: true,
+            }),
+          ]
+        : []),
+    ],
+    async (p, c) => {
+      return orchestrateResolve({
+        params: { ...p, scope: p.scope },
+        session: c.session,
+        cwd: c.cwd,
+      });
+    },
+  );
+}

package/src/tool/resolve/markdown.ts

@@ -0,0 +1,150 @@
+/**
+ * Markdown renderer for code_resolve results.
+ *
+ * Produces compact, agent-friendly markdown showing resolved targets
+ * with stable handles, disambiguation candidates, or actionable errors.
+ */
+
+import { relative } from "node:path";
+import { renderEvidenceListMetadataDisclosure } from "../../analysis/evidence.ts";
+import type {
+  DisambiguationCandidate,
+  ResolveServiceResult,
+} from "../../analysis/target/service.ts";
+import type { TargetStoreEntry } from "../../session/target-store.ts";
+
+/**
+ * Render a provenance note for an anchored resolution, but only when the
+ * resolution was non-obvious — i.e. the coordinate was snapped to a different
+ * anchor, or the evidence was structural rather than semantic. Exact
+ * name-anchor hits resolved from semantic evidence stay quiet.
+ */
+function renderAnchoredResolutionNote(t: TargetStoreEntry): string | null {
+  const r = t.resolution;
+  if (!r) return null;
+  const degraded = r.source !== "semantic";
+  if (!r.snapped && !degraded) return null;
+
+  const req = `${r.requested.line}:${r.requested.character}`;
+  const res = `${r.resolved.line}:${r.resolved.character}`;
+  if (r.snapped) {
+    return `_Note: snapped from requested coordinate ${req} to name anchor ${res} (evidence: ${r.source})._`;
+  }
+  return `_Note: resolved from ${r.source} evidence; confirm with \`code_inspect\` if you need point-level facts._`;
+}
+
+/** Render the single-target resolved block (with optional provenance note). */
+function renderSingleTarget(t: TargetStoreEntry, confidence: string, cwd: string): string[] {
+  const relFile = relative(cwd, t.file) || t.file;
+  const kind = t.kind ? ` \`${t.kind}\`` : "";
+  const name = t.name ? ` **${t.name}**${kind}` : "";
+  const lines: string[] = [
+    `Resolved${name}:`,
+    "",
+    `- File: \`${relFile}\``,
+    `- Line: ${t.displayLine}, Column: ${t.displayCharacter}`,
+    `- Target ID: \`${t.targetId}\``,
+    `- Span ID: \`${t.spanId}\``,
+    `- Confidence: \`${confidence}\``,
+    `- Provenance: \`${t.provenance}\``,
+  ];
+  const note = renderAnchoredResolutionNote(t);
+  if (note) {
+    lines.push("");
+    lines.push(note);
+  }
+  lines.push("");
+  return lines;
+}
+
+/** Render a full resolve service result into markdown. */
+export function renderResolveResult(result: ResolveServiceResult, cwd: string): string {
+  switch (result.kind) {
+    case "resolved":
+      return renderResolved(result.targets, result.omittedCount, result.confidence, cwd);
+    case "disambiguation":
+      return renderDisambiguation(result.candidates, result.omittedCount, cwd);
+    case "error":
+      return result.message;
+  }
+}
+
+function renderResolved(
+  targets: TargetStoreEntry[],
+  omittedCount: number,
+  confidence: string,
+  cwd: string,
+): string {
+  if (targets.length === 0) {
+    return "No targets resolved.";
+  }
+
+  const lines: string[] = [];
+
+  if (targets.length === 1) {
+    lines.push(...renderSingleTarget(targets[0], confidence, cwd));
+  } else {
+    lines.push(`Resolved ${targets.length} target(s):`);
+    lines.push("");
+
+    for (const t of targets) {
+      const relFile = relative(cwd, t.file) || t.file;
+      const kind = t.kind ? ` (\`${t.kind}\`)` : "";
+      const name = t.name ?? "(unnamed)";
+      lines.push(
+        `- \`${relFile}\`:${t.displayLine}:${t.displayCharacter} — **${name}**${kind} — \`${t.targetId}\``,
+      );
+    }
+
+    const disclosure = renderEvidenceListMetadataDisclosure({
+      key: "resolve.targets",
+      totalCount: targets.length + omittedCount,
+      shownCount: targets.length,
+      omittedCount,
+      partialReason: null,
+    });
+    if (disclosure) {
+      lines.push(disclosure);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function renderDisambiguation(
+  candidates: DisambiguationCandidate[],
+  omittedCount: number,
+  cwd: string,
+): string {
+  const lines: string[] = [];
+
+  lines.push("# Multiple matches found");
+  lines.push("");
+  lines.push("Resolve by file + line + character, or refine with scope/kind:");
+  lines.push("");
+
+  for (const c of candidates) {
+    const relFile = relative(cwd, c.entry.file) || c.file;
+    const kind = c.kind ? ` (\`${c.kind}\`)` : "";
+    const container = c.container ? ` in \`${c.container}\`` : "";
+    lines.push(
+      `${c.rank}. **${c.name}**${kind}${container} — \`${relFile}\`:${c.line}:${c.character}`,
+    );
+    lines.push(`   Target ID: \`${c.targetId}\``);
+  }
+
+  const disclosure = renderEvidenceListMetadataDisclosure({
+    key: "resolve.candidates",
+    totalCount: candidates.length + omittedCount,
+    shownCount: candidates.length,
+    omittedCount,
+    partialReason: null,
+  });
+  if (disclosure) {
+    lines.push("");
+    lines.push(disclosure);
+  }
+
+  return lines.join("\n");
+}

package/src/tool/resolve/orchestrate.ts

@@ -0,0 +1,134 @@
+/**
+ * code_resolve orchestration — result assembly and details construction.
+ *
+ * Receives raw resolution outcomes from the resolution service and
+ * assembles the markdown content and structured details.
+ */
+
+import { relative } from "node:path";
+import { executeResolveService, type ResolveServiceParams } from "../../analysis/target/service.ts";
+import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
+import type { CodeIntelResult, ResolveDetails } from "../../types/index.ts";
+import { unavailableResolveDetails } from "../infra/error-results.ts";
+import { renderResolveResult } from "./markdown.ts";
+
+export interface ResolveOrchestrateInput {
+  params: ResolveServiceParams;
+  session: WorkspaceCodeIntelligenceSession;
+  cwd: string;
+}
+
+export async function orchestrateResolve(input: ResolveOrchestrateInput): Promise<CodeIntelResult> {
+  const { params, session, cwd } = input;
+  const result = await executeResolveService(params, session);
+
+  let content = renderResolveResult(result, cwd);
+
+  // For single-target resolutions, append actionable "Chain next" guidance.
+  if (result.kind === "resolved" && result.targets.length === 1) {
+    const target = result.targets[0];
+    const rels = suggestedRelations(target.kind);
+    if (rels) {
+      const chainLine = `Chain next: \`code_graph(targetId: "${target.targetId}", relations: ${JSON.stringify(rels)})\``;
+      content = `${content}\n${chainLine}\n`;
+    }
+  }
+
+  // Build structured details
+  if (result.kind === "resolved") {
+    const details: ResolveDetails = {
+      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,
+    };
+    return { content, details: { type: "resolve", data: details } };
+  }
+
+  if (result.kind === "disambiguation") {
+    const details: ResolveDetails = {
+      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 { content, details: { type: "resolve", data: details } };
+  }
+
+  // Error — still return structured details
+  return {
+    content,
+    details: unavailableResolveDetails([
+      "Refine the `query` or `scope`",
+      "Use anchored `file` + `line` + `character` for a precise target",
+    ]),
+  };
+}
+
+/**
+ * Suggested `code_graph` relations for a resolved symbol kind.
+ */
+function suggestedRelations(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/resolve/tui.ts

@@ -0,0 +1,40 @@
+/**
+ * TUI renderer for code_resolve — renderCall + renderResult.
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type ResultOptios, renderSimpleResult, type ToolResult } from "../../ui/tui/common.ts";
+import type { CodeResolveToolParams } from "./execute.ts";
+
+/** ── renderCall ────────────────────────────────────────────────── */
+
+export function renderResolveCall(args: unknown, theme: Theme, _context: unknown): Text {
+  const params = (args ?? {}) as CodeResolveToolParams;
+
+  let content = theme.fg("toolTitle", "code_resolve");
+
+  if (params.query) {
+    content += ` ${theme.fg("accent", params.query)}`;
+  } else if (params.file) {
+    const file = params.file.split("/").pop() ?? params.file;
+    content += ` ${theme.fg("accent", file)}`;
+    if (params.line) content += theme.fg("warning", `:${params.line}`);
+  }
+
+  if (params.kind) {
+    content += theme.fg("dim", ` [${params.kind}]`);
+  }
+
+  return new Text(content, 0, 0);
+}
+
+/** ── renderResult ──────────────────────────────────────────────── */
+
+export function renderResolveResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  _context: unknown,
+): ReturnType<typeof renderSimpleResult> {
+  return renderSimpleResult(result, options, theme, "Resolving…");
+}