@mrclrchtr/supi-code-intelligence 1.16.0 → 2.0.0

package/src/tool/inspect/orchestrate.ts

@@ -0,0 +1,156 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createEvidenceList } from "../../analysis/evidence.ts";
+import { normalizePath } from "../../analysis/search/ripgrep.ts";
+import { gatherNearbyDiagnostics, gatherTreeSitterContext } from "../../ui/markdown/gather.ts";
+import type { InspectDeps, InspectInput, InspectUseCaseResult } from "../../ui/markdown/types.ts";
+import { renderInspectResult } from "./markdown.ts";
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: inspect orchestration keeps data gathering and unavailable-section derivation in one place
+export async function executeInspect(
+  input: InspectInput,
+  deps: InspectDeps,
+): Promise<InspectUseCaseResult> {
+  const resolvedFile = normalizePath(input.file, deps.cwd);
+  if (!fs.existsSync(resolvedFile)) {
+    const relTarget = `${input.file}:${input.line}:${input.character}`;
+    return {
+      content: `**Error:** File not found: \`${input.file}\``,
+      details: {
+        confidence: "unavailable",
+        focusTarget: relTarget,
+        unavailableSections: ["syntax", "hover", "definition", "diagnostics", "codeActions"],
+        nextQueries: ["Use `code_health` to inspect provider state"],
+      },
+    };
+  }
+
+  const relPath = path.relative(deps.cwd, resolvedFile);
+  const context = await gatherTreeSitterContext(
+    deps.provider,
+    relPath,
+    input.line,
+    input.character,
+  );
+  const diagnostics = await gatherNearbyDiagnostics(
+    deps.cwd,
+    relPath,
+    input.line,
+    input.maxResults ?? 5,
+    deps.lspService,
+  );
+  const enclosing = context.outline.find(
+    (item) => item.startLine <= input.line && item.endLine >= input.line,
+  );
+  const definitions = (context.definition ?? []).map((def) => {
+    const absFile = def.uri.startsWith("file://") ? decodeURIComponent(def.uri.slice(7)) : def.uri;
+    return {
+      file: path.relative(deps.cwd, absFile),
+      line: def.range.start.line + 1,
+      character: def.range.start.character + 1,
+    };
+  });
+
+  const unavailableSections: string[] = [];
+  if (!context.nodeInfo && context.outline.length === 0) unavailableSections.push("syntax");
+  if (!context.hover && deps.provider?.hover == null) unavailableSections.push("hover");
+  if (definitions.length === 0 && deps.provider?.definition == null)
+    unavailableSections.push("definition");
+  if (diagnostics.length === 0 && deps.lspService.kind !== "ready")
+    unavailableSections.push("diagnostics");
+  if ((context.codeActions?.length ?? 0) === 0 && deps.provider?.codeActionTitles == null) {
+    unavailableSections.push("codeActions");
+  }
+
+  if (
+    !context.nodeInfo &&
+    !enclosing &&
+    !context.hover &&
+    definitions.length === 0 &&
+    diagnostics.length === 0 &&
+    (context.codeActions?.length ?? 0) === 0
+  ) {
+    unavailableSections.push("providers");
+  }
+
+  const confidence = deriveConfidence({
+    hasSemantic: Boolean(
+      context.hover || definitions.length > 0 || (context.codeActions?.length ?? 0) > 0,
+    ),
+    hasStructural: Boolean(context.nodeInfo || enclosing),
+    hasDiagnostics: diagnostics.length > 0,
+  });
+
+  const maxResults = input.maxResults ?? 5;
+  const codeActions = createEvidenceList({
+    key: "inspect.codeActions",
+    items: context.codeActions ?? [],
+    maxResults,
+  });
+
+  const nextQueries = buildNextQueries(relPath, input.line, input.character, confidence);
+  const content = renderInspectResult({
+    relPath,
+    line: input.line,
+    character: input.character,
+    confidence,
+    node: context.nodeInfo,
+    enclosingSymbol: enclosing
+      ? {
+          name: enclosing.name,
+          kind: enclosing.kind,
+          startLine: enclosing.startLine,
+          endLine: enclosing.endLine,
+        }
+      : null,
+    hover: context.hover?.contents ?? null,
+    definitions,
+    diagnostics,
+    codeActions: codeActions.items,
+    codeActionEvidence: codeActions.metadata,
+    unavailableSections: dedupe(unavailableSections),
+  });
+
+  return {
+    content,
+    details: {
+      confidence,
+      focusTarget: `${relPath}:${input.line}:${input.character}`,
+      unavailableSections: dedupe(unavailableSections),
+      evidenceLists: [codeActions.metadata],
+      nextQueries,
+    },
+  };
+}
+
+function deriveConfidence(input: {
+  hasSemantic: boolean;
+  hasStructural: boolean;
+  hasDiagnostics: boolean;
+}): "semantic" | "structural" | "unavailable" {
+  if (input.hasSemantic || input.hasDiagnostics) return "semantic";
+  if (input.hasStructural) return "structural";
+  return "unavailable";
+}
+
+function buildNextQueries(
+  relPath: string,
+  line: number,
+  character: number,
+  confidence: "semantic" | "structural" | "unavailable",
+): string[] {
+  const next = [
+    `\`code_graph\`, \`file: "${relPath}"\`, \`line: ${line}\`, and \`character: ${character}\` for relationships`,
+    `\`code_orientation\` with \`focus: "${relPath}"\` for broader orientation`,
+  ];
+  if (confidence === "unavailable") {
+    next.push("Use `code_health` to inspect provider state");
+  } else {
+    next.push("Use `code_health` when you need provider or diagnostic status");
+  }
+  return next;
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)];
+}

package/src/tool/inspect/tui.ts

@@ -0,0 +1,36 @@
+/**
+ * TUI renderer for code_inspect — 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";
+
+/** ── renderCall ────────────────────────────────────────────────── */
+
+export function renderInspectCall(args: unknown, theme: Theme, _context: unknown): Text {
+  const params = (args ?? {}) as { file?: string; line?: number; character?: number };
+
+  let content = theme.fg("toolTitle", "code_inspect");
+
+  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.character) content += theme.fg("dim", `:${params.character}`);
+    }
+  }
+
+  return new Text(content, 0, 0);
+}
+
+/** ── renderResult ──────────────────────────────────────────────── */
+
+export function renderInspectResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  _context: unknown,
+): ReturnType<typeof renderSimpleResult> {
+  return renderSimpleResult(result, options, theme, "Inspecting…");
+}

package/src/tool/orientation/deps.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared context dependency assembly for code_orientation.
+ *
+ * Used by both the precise-target and orientation-mode execution paths
+ * to build the provider/model/LSP deps needed by the use-case layer.
+ */
+
+import { buildArchitectureModel } from "../../analysis/architecture/discovery.ts";
+import type { CodeProvider } from "../../analysis/provider.ts";
+import { ensureSemanticReadiness } from "../../analysis/readiness.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import type { OrientationDeps as UseCaseOrientationDeps } from "../../ui/markdown/types.ts";
+import { unavailableContextDetails } from "../infra/error-results.ts";
+import { renderSemanticReadinessTimeout } from "../infra/readiness-message.ts";
+import type { CodeOrientationToolParams } from "./execute.ts";
+
+/** Shared context dependencies (provider/model/lsp) or a readiness error result. */
+export type OrientationDeps = Omit<UseCaseOrientationDeps, "cwd"> | CodeIntelResult;
+
+/**
+ * Assemble provider deps and architecture model for the use-case layer.
+ *
+ * If the semantic provider is not ready and a precise target is requested,
+ * gates behind readiness (which may timeout). Returns a CodeIntelResult
+ * on timeout or the assembled deps on success.
+ */
+export async function prepareOrientationDeps(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<OrientationDeps> {
+  const readinessResult = await gateSemanticReadiness(params, ctx.cwd);
+  if (readinessResult) return readinessResult;
+
+  const providerState = ctx.session.getProviders();
+  const provider: CodeProvider | null =
+    providerState.kind === "ready" ? providerState.provider : null;
+  const lspService =
+    providerState.kind === "ready"
+      ? providerState.lspService
+      : { kind: "unavailable" as const, reason: "No provider" };
+  const model = await buildArchitectureModel(ctx.cwd);
+  return { model, provider, lspService };
+}
+
+async function gateSemanticReadiness(
+  params: CodeOrientationToolParams,
+  cwd: string,
+): Promise<CodeIntelResult | null> {
+  const hasSemanticTarget = params.file != null && params.line != null && params.character != null;
+  if (!hasSemanticTarget) return null;
+
+  const readiness = await ensureSemanticReadiness(
+    cwd,
+    params.file ? { kind: "file", file: params.file } : { kind: "workspace" },
+  );
+  if (readiness.kind === "timeout") {
+    return {
+      content: renderSemanticReadinessTimeout("code_orientation", 15_000),
+      details: unavailableContextDetails(["Retry shortly or check `code_health`"]),
+    };
+  }
+  return null;
+}

package/src/tool/orientation/execute.ts

@@ -0,0 +1,50 @@
+/**
+ * code_orientation tool executor.
+ *
+ * Thin orchestrator: dispatches to precise-target resolution or
+ * orientation-mode depending on whether targetId/coordinates or
+ * a plain focus is provided.
+ */
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { runOrientationMode } from "./mode.ts";
+import { resolvePreciseTarget } from "./precise-target.ts";
+
+export interface CodeOrientationToolParams {
+  /** Workspace-relative path or discovered module name for orientation. */
+  focus?: string;
+  /** Resolved target handle from code_resolve. Wins over focus/coordinates. */
+  targetId?: string;
+  /** 1-based line for symbol orientation. Requires focus. */
+  line?: number;
+  /** 1-based UTF-16 column for symbol orientation. Requires focus and line. */
+  character?: number;
+  /** Maximum results per rendered list. Defaults to 10. */
+  maxResults?: number;
+  // Internal-only expansion fields populated from targetId or coordinate resolution.
+  file?: string;
+  targetName?: string | null;
+  targetKind?: string | null;
+  targetAnchorKind?: "name" | "declaration";
+}
+
+/**
+ * Execute the public code_orientation tool.
+ *
+ * When `targetId` or `line`/`character` coordinates are provided,
+ * resolves a precise symbol target and runs symbol-centered sections.
+ * Otherwise runs project/module/directory/file orientation mode.
+ */
+export async function executeOrientationTool(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const hasCoords = params.line !== undefined || params.character !== undefined;
+  const hasTargetId = params.targetId !== undefined && params.targetId !== null;
+
+  if (hasTargetId || hasCoords) {
+    const outcome = await resolvePreciseTarget(params, ctx, hasCoords);
+    if (outcome.kind === "resolved") return outcome.result;
+  }
+  return runOrientationMode(params, ctx);
+}

package/src/tool/orientation/markdown.ts

@@ -0,0 +1,35 @@
+import { type ReadNextItem, renderReadNextSection } from "../../analysis/read-next.ts";
+import type { OrientationSection } from "../../ui/markdown/types.ts";
+
+export interface RenderedOrientationSection {
+  key: OrientationSection;
+  title: string;
+  lines: string[];
+}
+
+export interface RenderOrientationParams {
+  focusTarget: string | null;
+  sections: RenderedOrientationSection[];
+  readNext?: ReadNextItem[];
+}
+
+/** Render a symbol-centered code_orientation result into markdown. */
+export function renderOrientationResult(params: RenderOrientationParams): string {
+  const lines: string[] = ["# Code Orientation", ""];
+
+  if (params.focusTarget) {
+    lines.push("## Focus", `- \`${params.focusTarget}\``, "");
+  }
+
+  for (const section of params.sections) {
+    lines.push(`## ${section.title}`);
+    if (section.lines.length > 0) {
+      lines.push(...section.lines);
+    }
+    lines.push("");
+  }
+
+  lines.push(...renderReadNextSection(params.readNext ?? []));
+
+  return lines.join("\n");
+}

package/src/tool/orientation/mode.ts

@@ -0,0 +1,88 @@
+/**
+ * Orientation-mode execution for code_orientation.
+ *
+ * Runs the non-target path: validates/resolves the focus parameter
+ * and delegates to the use-case layer for project/module/directory/file
+ * orientation.
+ */
+
+import { existsSync } from "node:fs";
+import type { ArchitectureModel } from "../../analysis/architecture/model.ts";
+import { normalizePath } from "../../analysis/search/ripgrep.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { unavailableContextDetails } from "../infra/error-results.ts";
+import { prepareOrientationDeps } from "./deps.ts";
+import type { CodeOrientationToolParams } from "./execute.ts";
+import { executeOrientation } from "./orchestrate.ts";
+
+/** Track which cwds have already shown git context in this session. */
+const shownGitContextCwds = new Set<string>();
+
+/**
+ * Run orientation mode: validate/resolve focus and produce a
+ * project/module/directory/file brief through the use-case layer.
+ */
+export async function runOrientationMode(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const deps = await prepareOrientationDeps(params, ctx);
+  if ("content" in deps) return deps;
+
+  const focusResolution = resolveOrientationFocus(params.focus, ctx.cwd, deps.model);
+  if (focusResolution.kind === "error") {
+    return {
+      content: `**Error:** ${focusResolution.reason}`,
+      details: unavailableContextDetails([
+        "Provide a workspace-relative path or a discovered module name as `focus`",
+      ]),
+    };
+  }
+
+  const showGitContext = !shownGitContextCwds.has(ctx.cwd);
+  shownGitContextCwds.add(ctx.cwd);
+
+  const result = await executeOrientation(
+    {
+      focus: focusResolution.path,
+      maxResults: params.maxResults ?? 10,
+      showGitContext,
+    },
+    { ...deps, cwd: ctx.cwd },
+  );
+
+  return { content: result.content, details: { type: "context", data: result.details } };
+}
+
+/**
+ * Resolve a focus string to a concrete filesystem path or discovered
+ * module root. Returns an error reason when the focus is ambiguous or
+ * not found.
+ */
+function resolveOrientationFocus(
+  focus: string | undefined,
+  cwd: string,
+  model: ArchitectureModel | null,
+): { kind: "ok"; path: string | undefined } | { kind: "error"; reason: string } {
+  if (!focus) return { kind: "ok", path: undefined };
+
+  const pathCandidate = normalizePath(focus, cwd);
+  if (existsSync(pathCandidate)) return { kind: "ok", path: pathCandidate };
+
+  const matches =
+    model?.modules.filter(
+      (mod) => mod.name === focus || mod.name.replace(/^@[^/]+\//, "") === focus,
+    ) ?? [];
+  if (matches.length === 1) return { kind: "ok", path: matches[0].root };
+  if (matches.length > 1) {
+    const candidates = matches
+      .map((mod) => `\`${mod.name}\` at \`${mod.relativePath}\``)
+      .join(", ");
+    return { kind: "error", reason: `Focus is ambiguous: ${candidates}` };
+  }
+
+  return {
+    kind: "error",
+    reason: `Focus not found: \`${focus}\`. Provide a workspace-relative path or discovered module name.`,
+  };
+}