@mrclrchtr/supi-code-intelligence 1.16.0 → 2.0.0

package/src/tool/infra/pipeline.ts

@@ -0,0 +1,311 @@
+/**
+ * Lightweight tool-execution pipeline.
+ *
+ * Executors compose stages that gate before the tool-specific logic:
+ * targetId expansion, scope resolution, param validation, semantic
+ * readiness, and capability checks. Each stage returns a
+ * {@link PipeOutcome}: `{ kind: "continue" }` to proceed to the next
+ * stage, or `{ kind: "error", result }` to short-circuit the pipeline.
+ *
+ * Usage in an executor:
+ *
+ * ```ts
+ * return runPipe(params, ctx, [
+ *   expandTargetId((msg) => ({ content: msg, details: ... })),
+ *   resolveScopeParam((reason) => ({ content: reason, details: ... })),
+ *   validateParams(myValidator, (msg) => ({ content: msg, details: ... })),
+ *   gateSemanticReadiness("code_graph"),
+ * ], async (p, c) => {
+ *   // tool-specific execution
+ * });
+ * ```
+ */
+
+import { match } from "ts-pattern";
+import { ensureSemanticReadiness } from "../../analysis/readiness.ts";
+import { resolveScope } from "../../analysis/search/ripgrep.ts";
+import { routeFor } from "../../analysis/target/planner.ts";
+import type {
+  CodeIntelligenceToolName,
+  CodeIntelResult,
+  CodeIntelToolExecCtx,
+} from "../../types/index.ts";
+import { searchErrorResult } from "./error-results.ts";
+import { renderSemanticReadinessTimeout } from "./readiness-message.ts";
+
+// Re-export for stage consumers
+export type { CodeIntelligenceToolName };
+
+// ── Param accessors ──────────────────────────────────────────────────
+
+/**
+ * Read a param value for runtime inspection in generic pipeline stages
+ * and cross-field validation rules.
+ *
+ * Centralizes the {@link Record}<string, unknown> cast needed when
+ * generic code accesses params by dynamic/computed keys. Callers get
+ * `unknown` back and must narrow to the expected type.
+ */
+export function inspectParam<P>(params: P, key: keyof P & string): unknown {
+  return (params as Record<string, unknown>)[key];
+}
+
+/**
+ * Set a param value in generic pipeline code.
+ *
+ * Companion to {@link inspectParam} for mutation stages like
+ * {@link expandTargetId} and {@link resolveScopeParam}.
+ */
+export function setParam<P>(params: P, key: keyof P & string, value: unknown): void {
+  (params as Record<string, unknown>)[key] = value;
+}
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+/**
+ * Outcome of a single pipeline stage.
+ *
+ * `continue` — proceed to the next stage (or the execute function).
+ * `error`    — short-circuit the pipeline with the given result.
+ */
+export type PipeOutcome = { kind: "continue" } | { kind: "error"; result: CodeIntelResult };
+
+/**
+ * A pipeline stage: receives (possibly mutated) params and the execution
+ * context. Returns {@link PipeOutcome} — `{ kind: "continue" }` to
+ * advance to the next stage, or `{ kind: "error", result }` to
+ * short-circuit immediately.
+ */
+export type PipeStage<P> = (
+  params: P,
+  ctx: CodeIntelToolExecCtx,
+) => Promise<PipeOutcome> | PipeOutcome;
+
+// ── Orchestrator ──────────────────────────────────────────────────────
+
+/**
+ * Run a sequence of gating stages then the tool-specific execute function.
+ *
+ * Stages are executed in order. The first stage that returns
+ * `{ kind: "error" }` short-circuits the pipeline and its result is
+ * returned to the caller. If every stage returns `{ kind: "continue" }`,
+ * `execute(params, ctx)` runs.
+ */
+export async function runPipe<P>(
+  params: P,
+  ctx: CodeIntelToolExecCtx,
+  stages: PipeStage<P>[],
+  execute: (params: P, ctx: CodeIntelToolExecCtx) => Promise<CodeIntelResult>,
+): Promise<CodeIntelResult> {
+  for (const stage of stages) {
+    const outcome = await stage(params, ctx);
+    if (outcome.kind === "error") return outcome.result;
+  }
+  return execute(params, ctx);
+}
+
+// ── Stage factories ───────────────────────────────────────────────────
+
+/** Minimum parameter shape needed by `expandTargetId`. */
+export interface HasTargetParams {
+  targetId?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  /** Set by expandTargetId stage — resolved name from the stored target entry. */
+  _expandedName?: string | null;
+  /** Set by expandTargetId stage — anchor kind from the stored target entry. */
+  _expandedAnchorKind?: string | null;
+}
+
+/**
+ * Expand an optional `targetId` into file/line/character params.
+ *
+ * On success the stage mutates `params.file`, `params.line`, and
+ * `params.character` from the stored entry. On error it calls
+ * `onError(message)` to build a tool-appropriate error result.
+ *
+ * A missing/null targetId is not an error — the stage passes through
+ * (no expansion, params unchanged).
+ */
+export function expandTargetId<P extends HasTargetParams>(
+  onError: (message: string) => CodeIntelResult,
+): PipeStage<P> {
+  return (params, ctx) => {
+    const expansion = ctx.session.expandTargetId(params);
+    if (expansion.kind === "error") return { kind: "error", result: onError(expansion.message) };
+    if (expansion.kind === "ok") {
+      params.file = expansion.file;
+      params.line = expansion.line;
+      params.character = expansion.character;
+      params._expandedName = expansion.targetName;
+      params._expandedAnchorKind = expansion.entry.anchorKind;
+    }
+    return { kind: "continue" };
+  };
+}
+
+/** Minimum parameter shape needed by `resolveScope`. */
+export interface HasScopeParam {
+  scope?: string;
+}
+
+/**
+ * Resolve the `scope` parameter to an absolute path.
+ *
+ * Mutates `params.scope` to the resolved absolute path. An undefined
+ * scope passes through unchanged. On resolution error calls
+ * `onError(reason)`.
+ *
+ * @param paramName — defaults to `"scope"`.
+ */
+export function resolveScopeParam<P extends HasScopeParam>(
+  onError: (reason: string) => CodeIntelResult,
+  paramName: keyof P & string = "scope" as keyof P & string,
+): PipeStage<P> {
+  return (params, ctx) => {
+    const raw = inspectParam(params, paramName) as string | undefined;
+    if (raw === undefined) return { kind: "continue" };
+
+    const result = resolveScope(raw, ctx.cwd);
+    if (result.kind === "error") return { kind: "error", result: onError(result.reason) };
+
+    setParam(params, paramName, result.path);
+    return { kind: "continue" };
+  };
+}
+
+/**
+ * Apply cross-field validation rules after TypeBox schema validation.
+ *
+ * pi already validates structural types, required fields, and enum
+ * values against the TypeBox schema in {@link ./schemas.ts} before
+ * calling executors. This stage handles only cross-field constraints
+ * that TypeBox cannot express (pairing, mutual exclusion, filesystem
+ * checks, semantic consistency).
+ *
+ * The validator receives `(params, cwd)` and returns `null` when
+ * valid, or an error message string. The stage calls `onError(message)`
+ * to build a tool-appropriate error result.
+ */
+export function validateParams<P>(
+  validator: (params: P, cwd: string) => string | null,
+  onError: (message: string) => CodeIntelResult,
+): PipeStage<P> {
+  return (params, ctx) => {
+    const message = validator(params, ctx.cwd);
+    if (message) return { kind: "error", result: onError(message) };
+    return { kind: "continue" };
+  };
+}
+
+/** Options for {@link gateSemanticReadiness}. */
+export interface SemanticGateOptions {
+  /**
+   * Optional param key for the file path used for file-scoped readiness.
+   * When provided, readiness waits for the specific file. Defaults to
+   * workspace-scoped readiness.
+   */
+  fileParam?: string;
+
+  /** Build a result when readiness times out. */
+  onTimeout?: (toolName: string, timeoutMs: number) => CodeIntelResult;
+
+  /** When true, throw (whole-tool unavailable) instead of returning an error result. */
+  throwOnUnavailable?: boolean;
+
+  /**
+   * When true, let "unavailable" pass through to the execute function
+   * instead of returning an error. Use when the use-case layer handles
+   * missing providers with explicit unavailable-section notes.
+   * `throwOnUnavailable` takes precedence when both are true.
+   */
+  passThroughOnUnavailable?: boolean;
+
+  /** Build a result when readiness is permanently unavailable. */
+  onUnavailable?: (reason: string) => CodeIntelResult;
+}
+
+/**
+ * Gate execution behind semantic (LSP) readiness.
+ *
+ * Waits up to the default timeout for the LSP to be ready for the
+ * workspace (or a specific file). On timeout, calls `onTimeout` if
+ * provided, otherwise builds a default timeout result. When
+ * `throwOnUnavailable` is true and the provider is permanently
+ * unavailable, the stage throws so pi marks the call as an error.
+ */
+export function gateSemanticReadiness<P>(
+  toolName: CodeIntelligenceToolName,
+  opts: SemanticGateOptions = {},
+): PipeStage<P> {
+  return async (params, ctx) => {
+    // opts.fileParam is a runtime string from an options bag, not a
+    // compile-time keyof P — keep the cast local instead of routing
+    // through inspectParam which requires keyof P & string.
+    const file = opts.fileParam
+      ? ((params as Record<string, unknown>)[opts.fileParam] as string | undefined)
+      : undefined;
+
+    const scope = file ? { kind: "file" as const, file } : { kind: "workspace" as const };
+    const readiness = await ensureSemanticReadiness(ctx.cwd, scope);
+
+    if (readiness.kind === "ready") return { kind: "continue" };
+
+    return handleNonReadyReadiness(readiness, toolName, opts);
+  };
+}
+
+/** Handle timeout or unavailable readiness, applying tool-specific callbacks. */
+function handleNonReadyReadiness(
+  readiness: { kind: "timeout" } | { kind: "unavailable"; reason: string },
+  toolName: CodeIntelligenceToolName,
+  opts: SemanticGateOptions,
+): PipeOutcome {
+  return match(readiness)
+    .with({ kind: "timeout" }, () => {
+      if (opts.onTimeout)
+        return { kind: "error" as const, result: opts.onTimeout(toolName, 15_000) };
+      return defaultTimeoutOutcome(toolName);
+    })
+    .with({ kind: "unavailable" }, ({ reason }) => {
+      if (opts.throwOnUnavailable) throw new Error(reason);
+      if (opts.passThroughOnUnavailable) return { kind: "continue" as const };
+      if (opts.onUnavailable) return { kind: "error" as const, result: opts.onUnavailable(reason) };
+      return defaultUnavailableOutcome(reason);
+    })
+    .exhaustive() as PipeOutcome;
+}
+
+function defaultTimeoutOutcome(toolName: string): PipeOutcome {
+  return {
+    kind: "error",
+    result: searchErrorResult(renderSemanticReadinessTimeout(toolName, 15_000)),
+  };
+}
+
+function defaultUnavailableOutcome(reason: string): PipeOutcome {
+  return { kind: "error", result: searchErrorResult(`**Error:** ${reason}`) };
+}
+
+/**
+ * Gate execution behind capability availability.
+ *
+ * Calls `routeFor(cwd, toolName)`. When `preferred === "unavailable"`
+ * the stage throws (whole-tool capability-unavailable) so pi marks the
+ * call as an error. Partial per-relation unavailability is NOT gated
+ * here — executors surface that through best-effort notes.
+ *
+ * This is a sync stage — no async work.
+ */
+export function gateCapability<P>(toolName: CodeIntelligenceToolName): PipeStage<P> {
+  return (_params, ctx) => {
+    const route = routeFor(ctx.cwd, toolName);
+    if (route.preferred === "unavailable") {
+      throw new Error(
+        `No analysis provider is available for this workspace. Check \`code_health\` for LSP and tree-sitter status.`,
+      );
+    }
+    return { kind: "continue" };
+  };
+}

package/src/tool/infra/progress.ts

@@ -0,0 +1,21 @@
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Emit a coarse progress beat to the agent runtime via `onUpdate`.
+ *
+ * Long-running code-intelligence executors (code_find ripgrep, code_impact
+ * sweeps, code_graph `relations:["all"]`, code_health `refresh`, and
+ * code_refactor_plan LSP requests) call this at a few natural checkpoints —
+ * a start beat plus a couple of progress beats — so the UI can show the tool
+ * is working. Beats must stay coarse: not chatty.
+ *
+ * Safe no-op when `onUpdate` is absent (the common case for direct executor
+ * calls and tests). The `details.progress` marker mirrors the beat text for
+ * UI rendering; the final tool result carries the real structured `details`.
+ */
+export function emitToolProgress(
+  onUpdate: AgentToolUpdateCallback | undefined,
+  text: string,
+): void {
+  onUpdate?.({ content: [{ type: "text", text }], details: { progress: text } });
+}

package/src/tool/infra/readiness-message.ts

@@ -0,0 +1,5 @@
+/** Render user-facing semantic readiness messages for tool executors. */
+export function renderSemanticReadinessTimeout(toolName: string, timeoutMs: number): string {
+  const seconds = Math.max(1, Math.round(timeoutMs / 1000));
+  return `**Error:** Semantic analysis for \`${toolName}\` is still warming for this workspace (LSP indexing/startup not finished after ${seconds}s). Try again shortly or check \`code_health\`.`;
+}

package/src/tool/infra/truncate.ts

@@ -0,0 +1,49 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+
+/** Options for {@link truncateToolContent}. */
+export interface TruncateToolContentOptions {
+  /** Max lines (defaults to pi's {@link DEFAULT_MAX_LINES}). */
+  maxLines?: number;
+  /** Max bytes (defaults to pi's {@link DEFAULT_MAX_BYTES}). */
+  maxBytes?: number;
+}
+
+/** Result of truncating a tool's model-facing content. */
+export interface TruncatedToolContent {
+  /** Content, with a `[truncated: ...]` notice appended when truncation occurred. */
+  text: string;
+  /** Whether truncation occurred. */
+  truncated: boolean;
+}
+
+/**
+ * Head-truncate model-facing tool content to pi defaults and append a
+ * `[truncated: kept N of M lines (X of Y)]` notice when truncation occurs.
+ *
+ * Used by the code-intelligence tool adapter so every tool emits uniformly
+ * bounded output regardless of which executor produced it. Short content is
+ * returned unchanged (`truncated: false`, no notice). `details` are never
+ * truncated — only the markdown `content` string passes through here.
+ *
+ * Head truncation (not tail) is correct for code-intelligence output: results
+ * are ranked/structured and the most relevant entries come first.
+ */
+export function truncateToolContent(
+  content: string,
+  options: TruncateToolContentOptions = {},
+): TruncatedToolContent {
+  const result = truncateHead(content, {
+    maxLines: options.maxLines ?? DEFAULT_MAX_LINES,
+    maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+  });
+  if (!result.truncated) {
+    return { text: content, truncated: false };
+  }
+  const notice = `\n[truncated: kept ${result.outputLines} of ${result.totalLines} lines (${formatSize(result.outputBytes)} of ${formatSize(result.totalBytes)})]\n`;
+  return { text: `${result.content}${notice}`, truncated: true };
+}

package/src/tool/inspect/execute.ts

@@ -0,0 +1,76 @@
+/**
+ * Tool executor for code_inspect — factual point inspection.
+ */
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { focusedToolRules } from "../infra/cross-field.ts";
+import { unavailableInspectDetails } from "../infra/error-results.ts";
+import { gateSemanticReadiness, runPipe, validateParams } from "../infra/pipeline.ts";
+import { renderSemanticReadinessTimeout } from "../infra/readiness-message.ts";
+import { executeInspect } from "./orchestrate.ts";
+
+export interface CodeInspectToolParams {
+  file: string;
+  line: number;
+  character: number;
+  maxResults?: number;
+}
+
+export async function executeInspectTool(
+  params: Partial<CodeInspectToolParams>,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  return runPipe(
+    params,
+    ctx,
+    [
+      validateParams(focusedToolRules(), (msg) => ({
+        content: msg,
+        details: unavailableInspectDetails("validation error", [
+          "Provide `file`, `line`, and `character` for point inspection",
+        ]),
+      })),
+      gateSemanticReadiness("code_inspect", {
+        fileParam: "file",
+        onTimeout: () => ({
+          content: renderSemanticReadinessTimeout("code_inspect", 15_000),
+          details: unavailableInspectDetails("timeout", ["Retry shortly or check `code_health`"]),
+        }),
+        // Unavailable LSP passes through — the use-case layer renders
+        // explicit unavailable-section notes.
+        passThroughOnUnavailable: true,
+      }),
+    ],
+    async (p, c) => {
+      if (!p.file || p.line == null || p.character == null) {
+        return {
+          content: "**Error:** `code_inspect` requires `file`, `line`, and `character`.",
+          details: unavailableInspectDetails("missing coordinates", [
+            "Provide `file`, `line`, and `character` for point inspection",
+          ]),
+        };
+      }
+
+      const providerState = c.session.getProviders();
+      const provider = providerState.kind === "ready" ? providerState.provider : null;
+      const lspService =
+        providerState.kind === "ready"
+          ? providerState.lspService
+          : { kind: "unavailable" as const, reason: "No provider" };
+
+      // Let unavailable pass through — the use-case layer handles missing
+      // providers with explicit unavailable-section notes.
+      const result = await executeInspect(
+        {
+          file: p.file,
+          line: p.line,
+          character: p.character,
+          maxResults: p.maxResults,
+        },
+        { provider, cwd: c.cwd, lspService },
+      );
+
+      return { content: result.content, details: { type: "inspect", data: result.details } };
+    },
+  );
+}

package/src/tool/inspect/markdown.ts

@@ -0,0 +1,169 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type EvidenceListMetadata,
+  renderEvidenceListMetadataDisclosure,
+} from "../../analysis/evidence.ts";
+
+export interface InspectRenderInput {
+  relPath: string;
+  line: number;
+  character: number;
+  confidence: ConfidenceMode;
+  node: {
+    type: string;
+    text: string;
+    startLine: number;
+    startCharacter: number;
+    ancestry?: Array<
+      | string
+      | {
+          type: string;
+          startLine: number;
+          startCharacter: number;
+          endLine?: number;
+          endCharacter?: number;
+        }
+    >;
+  } | null;
+  enclosingSymbol: {
+    name: string;
+    kind: string;
+    startLine: number;
+    endLine: number;
+  } | null;
+  hover: string | null;
+  definitions: Array<{ file: string; line: number; character: number }>;
+  diagnostics: Array<{ line: number; severity: number | string; message: string }>;
+  codeActions: Array<{ title: string; kind?: string }>;
+  codeActionEvidence?: EvidenceListMetadata;
+  unavailableSections: string[];
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: inspect rendering keeps section ordering and unavailable-state handling explicit
+export function renderInspectResult(input: InspectRenderInput): string {
+  const lines: string[] = [];
+  lines.push(`# Inspect: ${input.relPath}:${input.line}:${input.character}`);
+  lines.push("");
+  lines.push(`**Confidence:** \`${input.confidence}\``);
+  lines.push("");
+
+  if (input.node) {
+    lines.push("## Node");
+    lines.push(
+      `- Type: \`${input.node.type}\` at ${input.relPath}:${input.node.startLine}:${input.node.startCharacter}`,
+    );
+    if (input.node.text) {
+      lines.push("```ts");
+      lines.push(input.node.text);
+      lines.push("```");
+    }
+    const ancestry = normalizeAncestry(input.node.ancestry ?? []);
+    if (ancestry.length > 0) {
+      lines.push("");
+      lines.push("### Ancestry");
+      for (const ancestor of ancestry) {
+        lines.push(`- \`${ancestor}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  if (input.enclosingSymbol) {
+    lines.push("## Enclosing symbol");
+    lines.push(
+      `- \`${input.enclosingSymbol.name}\` (${input.enclosingSymbol.kind}) L${input.enclosingSymbol.startLine}–${input.enclosingSymbol.endLine}`,
+    );
+    lines.push("");
+  }
+
+  if (input.hover) {
+    lines.push("## Hover");
+    lines.push(input.hover);
+    lines.push("");
+  }
+
+  if (input.definitions.length > 0) {
+    lines.push("## Definition");
+    for (const def of input.definitions) {
+      lines.push(`- \`${def.file}:${def.line}:${def.character}\``);
+    }
+    lines.push("");
+  }
+
+  if (input.diagnostics.length > 0) {
+    lines.push("## Diagnostics");
+    for (const diagnostic of input.diagnostics) {
+      lines.push(
+        `- L${diagnostic.line}: ${formatSeverity(diagnostic.severity)}: ${diagnostic.message}`,
+      );
+    }
+    lines.push("");
+  }
+
+  if (input.codeActions.length > 0) {
+    lines.push("## Code Actions");
+    for (const action of input.codeActions) {
+      const kind = action.kind ? ` (${action.kind})` : "";
+      lines.push(`- "${action.title}"${kind}`);
+    }
+    if (input.codeActionEvidence) {
+      const disclosure = renderEvidenceListMetadataDisclosure(input.codeActionEvidence);
+      if (disclosure) {
+        lines.push(disclosure);
+      }
+    }
+    lines.push("");
+  }
+
+  if (input.unavailableSections.length > 0) {
+    lines.push("## Unavailable");
+    for (const section of input.unavailableSections) {
+      lines.push(`- ${section}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function normalizeAncestry(
+  ancestry: Array<
+    | string
+    | {
+        type: string;
+        startLine: number;
+        startCharacter: number;
+        endLine?: number;
+        endCharacter?: number;
+      }
+  >,
+): string[] {
+  return ancestry.map((entry) => {
+    if (typeof entry === "string") return entry;
+    const start = `L${entry.startLine}:${entry.startCharacter}`;
+    const end =
+      entry.endLine != null && entry.endCharacter != null
+        ? `–L${entry.endLine}:${entry.endCharacter}`
+        : "";
+    return `${entry.type} ${start}${end}`;
+  });
+}
+
+function formatSeverity(severity: number | string): string {
+  if (typeof severity === "string") {
+    return severity.charAt(0).toUpperCase() + severity.slice(1);
+  }
+
+  switch (severity) {
+    case 1:
+      return "Error";
+    case 2:
+      return "Warning";
+    case 3:
+      return "Info";
+    case 4:
+      return "Hint";
+    default:
+      return "Diagnostic";
+  }
+}