@mrclrchtr/supi-code-intelligence 1.16.0 → 2.0.0

package/src/tool/graph/implementations.ts

@@ -0,0 +1,76 @@
+/**
+ * Semantic implementation lookup — finds implementations of a target.
+ */
+
+import type { ImplementationEntry, RelationsServiceDeps } from "./types.ts";
+
+export interface ImplementationsResult {
+  kind: "implementations";
+  targetName: string;
+  implementations: ImplementationEntry[];
+  externalCount: number;
+  confidence: "semantic" | "unavailable";
+}
+
+/**
+ * Collect implementations 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 collectImplementations(
+  targetFile: string,
+  targetPosition: { line: number; character: number },
+  targetName: string | null,
+  deps: RelationsServiceDeps,
+  maxResults?: number,
+): Promise<ImplementationsResult> {
+  if (!deps.provider?.implementation) {
+    return {
+      kind: "implementations",
+      targetName: targetName ?? "symbol",
+      implementations: [],
+      externalCount: 0,
+      confidence: "unavailable",
+    };
+  }
+
+  const impls = await deps.provider.implementation(targetFile, targetPosition);
+  if (!impls) {
+    return {
+      kind: "implementations",
+      targetName: targetName ?? "symbol",
+      implementations: [],
+      externalCount: 0,
+      confidence: "semantic",
+    };
+  }
+
+  const project: ImplementationEntry[] = [];
+  let externalCount = 0;
+
+  for (const loc of impls) {
+    const uri = loc.uri ?? loc.targetUri ?? "";
+    const filePath = uri.startsWith("file://") ? uri.slice(7) : uri;
+    const line = (loc.range?.start?.line ?? loc.targetRange?.start?.line ?? 0) + 1;
+
+    if (filePath?.startsWith(deps.cwd)) {
+      project.push({
+        file: filePath,
+        line,
+        character: 0,
+        name: targetName,
+      });
+    } else {
+      externalCount++;
+    }
+  }
+
+  void maxResults;
+
+  return {
+    kind: "implementations",
+    targetName: targetName ?? "symbol",
+    implementations: project,
+    externalCount,
+    confidence: "semantic",
+  };
+}

package/src/tool/graph/markdown-base.ts

@@ -0,0 +1,243 @@
+// Relations markdown renderer — consumes use-case data and produces markdown content.
+
+import {
+  createEvidenceList,
+  type EvidenceListMetadata,
+  renderEvidenceListDisclosure,
+} from "../../analysis/evidence.ts";
+import { type ReadNextItem, renderReadNextSection } from "../../analysis/read-next.ts";
+import type { ReferenceCollection } from "../../analysis/references/semantic-refs.ts";
+import { formatReferenceList } from "../../analysis/references/semantic-refs.ts";
+import type { TestSurfaceDetails } from "../../analysis/tests/test-discovery.ts";
+
+// ── Callers ──────────────────────────────────────────────────────────
+
+export function renderCallersResult(
+  symbolName: string,
+  result: ReferenceCollection,
+  _cwd: string,
+  maxResults: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Callers of \`${symbolName}\``);
+  lines.push("");
+  lines.push(
+    `**${result.refs.length} reference${result.refs.length !== 1 ? "s" : ""}** (${result.confidence})`,
+  );
+  if (result.externalCount > 0) {
+    lines.push(
+      `_+${result.externalCount} external reference${result.externalCount !== 1 ? "s" : ""}_`,
+    );
+  }
+  lines.push("");
+
+  formatReferenceList(lines, result.refs, maxResults);
+  return lines.join("\n");
+}
+
+// ── Callees ──────────────────────────────────────────────────────────
+
+export function renderCalleesResult(
+  data: {
+    enclosingScope: { name: string; startLine?: number; endLine?: number };
+    callees: Array<{ name: string; startLine: number }>;
+  },
+  relPath: string,
+  maxResults: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Direct structural calls from \`${data.enclosingScope.name}\``);
+  lines.push("");
+  lines.push(
+    `**${data.callees.length} direct structural call${data.callees.length !== 1 ? "s" : ""}** from enclosing scope \`${data.enclosingScope.name}\`${formatOptionalScopeRange(data.enclosingScope)} in \`${relPath}\``,
+  );
+  lines.push("");
+  lines.push(
+    "_Structural only: call expressions are reported by source shape, not symbol identity; calls inside nested function/method/callback scopes are excluded from this enclosing scope._",
+  );
+  lines.push("");
+
+  const evidence = createEvidenceList({
+    key: "callees.calls",
+    items: data.callees,
+    maxResults,
+  });
+  for (const c of evidence.items) {
+    lines.push(`- \`${c.name}\` (L${c.startLine})`);
+  }
+  const disclosure = renderEvidenceListDisclosure(evidence);
+  if (disclosure) {
+    lines.push(disclosure);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function formatOptionalScopeRange(scope: { startLine?: number; endLine?: number }): string {
+  if (!scope.startLine) return "";
+  if (!scope.endLine || scope.startLine === scope.endLine) return ` (L${scope.startLine})`;
+  return ` (L${scope.startLine}–L${scope.endLine})`;
+}
+
+// ── Imports ─────────────────────────────────────────────────────────
+
+/**
+ * Render imports for a file as a graph section.
+ *
+ * Imports are file-level structural results from tree-sitter — they show
+ * every module specifier that the target file imports.
+ */
+export function renderImportsResult(
+  displayName: string,
+  imports: Array<{ moduleSpecifier: string; startLine: number }>,
+  relPath: string,
+  maxResults: number,
+): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const lines: string[] = [];
+  lines.push(`# Imports of \`${displayName}\` (structural)`);
+  lines.push("");
+  lines.push(`**${imports.length} import${imports.length !== 1 ? "s" : ""}** in \`${relPath}\``);
+  lines.push("");
+
+  const evidence = createEvidenceList({
+    key: "imports.modules",
+    items: imports,
+    maxResults,
+  });
+  for (const entry of evidence.items) {
+    lines.push(`- \`${entry.moduleSpecifier}\` (L${entry.startLine})`);
+  }
+  const disclosure = renderEvidenceListDisclosure(evidence);
+  if (disclosure) {
+    lines.push(disclosure);
+  }
+  return { content: lines.join("\n"), evidenceList: evidence.metadata };
+}
+
+// ── Exports ─────────────────────────────────────────────────────────
+
+/**
+ * Render exports for a file as a graph section.
+ *
+ * Exports are file-level structural results from tree-sitter — they show
+ * every named export from the target file.
+ */
+export function renderExportsResult(
+  displayName: string,
+  exports: Array<{ name: string; kind: string; startLine: number }>,
+  relPath: string,
+  maxResults: number,
+): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const lines: string[] = [];
+  lines.push(`# Exports of \`${displayName}\` (structural)`);
+  lines.push("");
+  lines.push(`**${exports.length} export${exports.length !== 1 ? "s" : ""}** in \`${relPath}\``);
+  lines.push("");
+
+  const evidence = createEvidenceList({
+    key: "exports.symbols",
+    items: exports,
+    maxResults,
+  });
+  for (const entry of evidence.items) {
+    const kindLabel = entry.kind ? ` (${entry.kind})` : "";
+    lines.push(`- \`${entry.name}\`${kindLabel} (L${entry.startLine})`);
+  }
+  const disclosure = renderEvidenceListDisclosure(evidence);
+  if (disclosure) {
+    lines.push(disclosure);
+  }
+  return { content: lines.join("\n"), evidenceList: evidence.metadata };
+}
+
+// ── Combined graph ───────────────────────────────────────────────────
+
+/** Relation families accepted by code_graph. */
+export type GraphRelationKind =
+  | "all"
+  | "references"
+  | "callees"
+  | "imports"
+  | "exports"
+  | "implements"
+  | "tests";
+
+/** A section in the combined graph output. */
+export type GraphSection =
+  | {
+      kind: "ok";
+      rel: GraphRelationKind;
+      count: number;
+      content: string;
+      evidenceLists?: EvidenceListMetadata[];
+      tests?: TestSurfaceDetails;
+      readNext?: ReadNextItem[];
+    }
+  | { kind: "unavailable"; rel: GraphRelationKind; message: string; tests?: TestSurfaceDetails }
+  | {
+      kind: "not-implemented";
+      rel: GraphRelationKind;
+      message: string;
+      tests?: TestSurfaceDetails;
+    };
+
+/**
+ * Render a combined graph result from multiple relation sections.
+ *
+ * Produces a unified markdown output with a summary header, per-section
+ * pre-rendered content, and a footer with follow-up hints.
+ */
+export function renderGraphResult(
+  displayName: string,
+  sections: GraphSection[],
+  resolvedFile: string,
+): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`# Graph of \`${displayName}\``);
+  lines.push("");
+  lines.push(`_File: \`${resolvedFile}\`_`);
+  lines.push("");
+
+  // Summary
+  const okSections = sections.filter((s) => s.kind === "ok") as Extract<
+    GraphSection,
+    { kind: "ok" }
+  >[];
+  const unavailable = sections.filter((s) => s.kind === "unavailable");
+  const notImpl = sections.filter((s) => s.kind === "not-implemented");
+
+  if (okSections.length > 0) {
+    const parts = okSections.map(
+      (s) => `**${s.rel}**: ${s.count} result${s.count !== 1 ? "s" : ""}`,
+    );
+    lines.push(parts.join(" | "));
+    lines.push("");
+  }
+  if (unavailable.length > 0) {
+    const names = unavailable.map((s) => `\`${s.rel}\``).join(", ");
+    lines.push(`_Unavailable: ${names}_`);
+    lines.push("");
+  }
+  if (notImpl.length > 0) {
+    const names = notImpl.map((s) => `\`${s.rel}\``).join(", ");
+    lines.push(`_Not yet implemented: ${names}_`);
+    lines.push("");
+  }
+
+  // Per-section content
+  for (const section of sections) {
+    if (section.kind === "ok") {
+      lines.push(section.content);
+      lines.push("");
+    } else if (section.kind === "unavailable") {
+      lines.push(`**${section.rel}**: ${section.message}`);
+      lines.push("");
+    }
+  }
+
+  lines.push(...renderReadNextSection(okSections.flatMap((section) => section.readNext ?? [])));
+
+  return lines.join("\n");
+}

package/src/tool/graph/orchestrate.ts

@@ -0,0 +1,285 @@
+/**
+ * Graph orchestration use-case — unified relation-graph data collection.
+ *
+ * Resolves a target and collects per-relation data (references, callees,
+ * imports, exports, implementations, tests) through the code provider.
+ * Returns a rendered CodeIntelResult with structured details.
+ *
+ * Extracted from execute-graph.ts as part of the thin-executor normalization.
+ */
+
+import type { CodeProvider } from "../../analysis/provider.ts";
+import { ensureSemanticReadiness } from "../../analysis/readiness.ts";
+import { toDisplayPath } from "../../analysis/search/ripgrep.ts";
+import { resolveTarget } from "../../analysis/target/bridge.ts";
+import type { AnchorKind } from "../../session/target-store.ts";
+import type { CodeIntelResult } from "../../types/index.ts";
+import { searchErrorResult } from "../infra/error-results.ts";
+import { emitToolProgress } from "../infra/progress.ts";
+import { renderSemanticReadinessTimeout } from "../infra/readiness-message.ts";
+import { type CollectRelationOptions, collectRelation } from "./collect-relation.ts";
+import type { GraphRelation } from "./execute.ts";
+import { renderGraphResult } from "./markdown-base.ts";
+
+/** Relation kinds accepted by code_graph. */
+export type { GraphRelation };
+
+/** Default relation set when none specified. */
+const DEFAULT_RELATIONS: GraphRelation[] = ["references"];
+
+/** Relations that need semantic (LSP) readiness. */
+const SEMANTIC_RELATIONS: GraphRelation[] = ["references", "implements"];
+
+/** Relations that only need a file path, not a position. */
+const FILE_LEVEL_RELATIONS: GraphRelation[] = ["imports", "exports"];
+
+export interface GraphInput {
+  targetId?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  scope?: string;
+  relations?: GraphRelation[];
+  calleeDepth?: "direct" | "deep";
+  maxResults?: number;
+  /** Set by pipeline expandTargetId stage. */
+  _expandedName?: string | null;
+  /** Set by pipeline expandTargetId stage. */
+  _expandedAnchorKind?: AnchorKind;
+}
+
+export interface GraphDeps {
+  cwd: string;
+  session: import("../../session/session.ts").WorkspaceCodeIntelligenceSession;
+  /** Ready code provider, or null. */
+  provider: CodeProvider | null;
+  /** Progress callback for long-running relation collection. */
+  onUpdate?: import("@earendil-works/pi-coding-agent").AgentToolUpdateCallback;
+}
+
+/**
+ * Execute the graph use-case.
+ *
+ * Resolves the target and collects all requested relations. The caller
+ * (tool executor) has already validated params, expanded targetId, and
+ * gated on capability availability.
+ */
+export async function executeGraph(input: GraphInput, deps: GraphDeps): Promise<CodeIntelResult> {
+  const requestedRelations = input.relations ?? DEFAULT_RELATIONS;
+  const relations = expandAllRelations(requestedRelations);
+
+  // Semantic readiness — degrades per-relation rather than blocking.
+  const requestedSemantic = relations.some((r) => SEMANTIC_RELATIONS.includes(r));
+  let semanticReadinessError: string | null = null;
+  if (requestedSemantic) {
+    const readiness = await ensureSemanticReadiness(
+      deps.cwd,
+      input.file ? { kind: "file", file: input.file } : { kind: "workspace" },
+    );
+    if (readiness.kind === "timeout") {
+      semanticReadinessError = renderSemanticReadinessTimeout("code_graph", 15_000);
+    } else if (readiness.kind === "unavailable") {
+      semanticReadinessError =
+        "No analysis provider is available for this workspace. Check `code_health` for LSP and tree-sitter status.";
+    }
+  }
+
+  const allFileLevel =
+    relations.length > 0 && relations.every((r) => FILE_LEVEL_RELATIONS.includes(r));
+
+  // Resolve target
+  const target = await resolveGraphTarget(input, deps, allFileLevel);
+  if ("content" in target) return target;
+
+  const { resolvedFile, resolvedPosition, displayName, resolvedAnchorKind } = target;
+  const resolvedDisplayFile = toDisplayPath(deps.cwd, resolvedFile);
+
+  // Collect results per relation
+  const sections = [];
+  const maxResults = input.maxResults ?? 8;
+
+  emitToolProgress(deps.onUpdate, `code_graph: collecting ${relations.length} relation(s)...`);
+
+  for (const rel of relations) {
+    if (relations.length > 1) {
+      emitToolProgress(deps.onUpdate, `code_graph: ${rel}...`);
+    }
+    const opts: CollectRelationOptions = {
+      file: resolvedFile,
+      position: resolvedPosition,
+      displayName,
+      cwd: deps.cwd,
+      provider: deps.provider,
+      maxResults,
+      semanticReadinessError,
+      anchorKind: resolvedAnchorKind,
+      calleeDepth: input.calleeDepth,
+    };
+    const section = await collectRelation(rel, opts);
+    sections.push(section);
+  }
+
+  // Render combined output
+  return buildGraphResult(displayName, sections, resolvedDisplayFile, input.scope);
+}
+
+// ── Target resolution ─────────────────────────────────────────────────
+
+interface ResolvedGraphTarget {
+  resolvedFile: string;
+  resolvedPosition: { line: number; character: number };
+  displayName: string;
+  resolvedAnchorKind: AnchorKind;
+}
+
+async function resolveGraphTarget(
+  input: GraphInput,
+  deps: GraphDeps,
+  allFileLevel: boolean,
+): Promise<ResolvedGraphTarget | CodeIntelResult> {
+  if (allFileLevel) {
+    return resolveFileLevelTarget(input, deps);
+  }
+  return resolvePositionAnchoredTarget(input, deps);
+}
+
+async function resolveFileLevelTarget(
+  input: GraphInput,
+  deps: GraphDeps,
+): Promise<ResolvedGraphTarget | CodeIntelResult> {
+  if (input.file) {
+    return {
+      resolvedFile: input.file,
+      resolvedPosition: { line: 1, character: 1 },
+      displayName: toDisplayPath(deps.cwd, input.file),
+      resolvedAnchorKind: "name",
+    };
+  }
+
+  if (input.symbol) {
+    const target = await resolveTarget(
+      { symbol: input.symbol, path: input.scope },
+      deps.cwd,
+      deps.provider ?? undefined,
+    );
+    if (typeof target === "string") return searchErrorResult(target);
+    if ("targets" in target) {
+      return searchErrorResult(
+        "**Error:** `code_graph` requires a precise target for file-level relations. Use `file` or `targetId` from `code_resolve`.",
+      );
+    }
+    return {
+      resolvedFile: target.file,
+      resolvedPosition: { line: 1, character: 1 },
+      displayName: toDisplayPath(deps.cwd, target.file),
+      resolvedAnchorKind: "name",
+    };
+  }
+
+  if (input.scope) {
+    return searchErrorResult(
+      "**Error:** `code_graph` file-level relations require a `file` or `symbol`, not just `scope`.",
+    );
+  }
+
+  return searchErrorResult("**Error:** `code_graph` requires a target for file-level relations.");
+}
+
+async function resolvePositionAnchoredTarget(
+  input: GraphInput,
+  deps: GraphDeps,
+): Promise<ResolvedGraphTarget | CodeIntelResult> {
+  const target = await resolveTarget(
+    {
+      file: input.file,
+      line: input.line,
+      character: input.character,
+      symbol: input.symbol,
+      path: input.scope,
+    },
+    deps.cwd,
+    deps.provider ?? undefined,
+  );
+  if (typeof target === "string") return searchErrorResult(target);
+
+  if ("targets" in target) {
+    return searchErrorResult(
+      "**Error:** `code_graph` requires a precise target. Use anchored coordinates (`file`, `line`, `character`), `symbol`, or pass a `targetId` from `code_resolve`.",
+    );
+  }
+
+  const resolvedAnchorKind = input._expandedAnchorKind ?? target.anchorKind;
+  const displayName =
+    input._expandedName ??
+    target.name ??
+    `symbol at ${toDisplayPath(deps.cwd, target.file)}:${target.displayLine}`;
+
+  return {
+    resolvedFile: target.file,
+    resolvedPosition: target.position,
+    displayName,
+    resolvedAnchorKind,
+  };
+}
+
+// ── Result assembly ───────────────────────────────────────────────────
+
+function buildGraphResult(
+  displayName: string,
+  sections: Awaited<ReturnType<typeof collectRelation>>[],
+  resolvedDisplayFile: string,
+  scope: string | undefined,
+): CodeIntelResult {
+  const content = renderGraphResult(displayName, sections, resolvedDisplayFile);
+
+  const hasStructural = sections.some(
+    (s) =>
+      s.kind === "ok" &&
+      (s.rel === "callees" ||
+        s.rel === "imports" ||
+        s.rel === "exports" ||
+        (s.rel === "tests" && s.count > 0)),
+  );
+  const hasSemantic = sections.some(
+    (s) => s.kind === "ok" && (s.rel === "references" || s.rel === "implements"),
+  );
+  const confidence = hasSemantic ? "semantic" : hasStructural ? "structural" : "unavailable";
+
+  const tests = sections.find((section) => section.rel === "tests")?.tests;
+  const evidenceLists = sections.flatMap((section) =>
+    section.kind === "ok" ? (section.evidenceLists ?? []) : [],
+  );
+  const omittedCount = evidenceLists.reduce(
+    (sum, evidenceList) => sum + (evidenceList.omittedCount ?? 0),
+    0,
+  );
+
+  return {
+    content,
+    details: {
+      type: "search",
+      data: {
+        confidence,
+        scope: scope ?? null,
+        candidateCount: sections.reduce((sum, s) => (s.kind === "ok" ? sum + s.count : sum), 0),
+        omittedCount,
+        evidenceLists,
+        nextQueries: [
+          "`code_orientation` on individual results for deeper orientation",
+          "`code_impact` for impact analysis",
+        ],
+        tests,
+      },
+    },
+  };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function expandAllRelations(relations: GraphRelation[]): GraphRelation[] {
+  if (!relations.includes("all")) {
+    return relations;
+  }
+  return ["references", "callees", "imports", "exports", "implements", "tests"];
+}

package/src/tool/graph/references-md.ts

@@ -0,0 +1,34 @@
+/**
+ * References markdown renderer — labels results as references/usages, not callers.
+ */
+
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import { formatReferenceList } from "../../analysis/references/semantic-refs.ts";
+import { toDisplayPath } from "../../analysis/search/ripgrep.ts";
+import type { ReferenceEntry } from "./types.ts";
+
+// biome-ignore lint/complexity/useMaxParams: render function with independent display parameters
+export function renderReferencesResult(
+  symbolName: string,
+  refs: ReferenceEntry[],
+  externalCount: number,
+  confidence: string,
+  cwd: string,
+  maxResults: number,
+): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const lines: string[] = [];
+  lines.push(`# References of \`${symbolName}\``);
+  lines.push("");
+  lines.push(`**${refs.length} reference${refs.length !== 1 ? "s" : ""}** (${confidence})`);
+  if (externalCount > 0) {
+    lines.push(`_+${externalCount} external reference${externalCount !== 1 ? "s" : ""}_`);
+  }
+  lines.push("");
+
+  const refLines: Array<{ file: string; line: number }> = refs.map((r) => ({
+    file: toDisplayPath(cwd, r.file),
+    line: r.line,
+  }));
+  const evidenceList = formatReferenceList(lines, refLines, maxResults);
+  return { content: lines.join("\n"), evidenceList };
+}