@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.0

package/src/tool/graph/callees.ts

@@ -0,0 +1,87 @@
+/**
+ * Structural callee lookup — finds direct calls in the enclosing scope at a target position.
+ */
+
+import type { CalleeEntry, CalleeScope, RelationsServiceDeps } from "./types.ts";
+
+export interface CalleesResult {
+  kind: "callees";
+  targetName: string;
+  enclosingScope: CalleeScope | null;
+  callees: CalleeEntry[];
+  confidence: "structural" | "unavailable";
+  depth: "direct" | "deep";
+}
+
+/**
+ * Collect direct structural callees at a target file/position using the
+ * enclosing executable scope reported by the structural provider.
+ */
+// biome-ignore lint/complexity/useMaxParams: service function with clear positional parameters matching provider contract
+export async function collectCallees(
+  targetFile: string,
+  targetLine: number,
+  targetCharacter: number,
+  targetName: string | null,
+  deps: RelationsServiceDeps,
+  maxResults?: number,
+  depth: "direct" | "deep" = "direct",
+): Promise<CalleesResult> {
+  if (!deps.provider?.calleesAt) {
+    return unavailableCallees(targetName);
+  }
+
+  const result = await deps.provider.calleesAt(targetFile, targetLine, targetCharacter, depth);
+  if (result.kind !== "success" || !result.data) {
+    return unavailableCallees(targetName);
+  }
+
+  void maxResults;
+  const enclosingScope = buildEnclosingScope(
+    result.data.enclosingScope,
+    targetFile,
+    targetLine,
+    targetName,
+  );
+  const callees: CalleeEntry[] = result.data.callees.map((c) => ({
+    name: c.name,
+    file: c.file ?? c.location ?? targetFile,
+    line: c.startLine ?? targetLine,
+    character: c.startCharacter ?? targetCharacter,
+  }));
+
+  return {
+    kind: "callees",
+    targetName: targetName ?? "symbol",
+    enclosingScope,
+    callees,
+    confidence: "structural",
+    depth: result.data.depth ?? depth,
+  };
+}
+
+function unavailableCallees(targetName: string | null): CalleesResult {
+  return {
+    kind: "callees",
+    targetName: targetName ?? "symbol",
+    enclosingScope: null,
+    callees: [],
+    confidence: "unavailable",
+    depth: "direct",
+  };
+}
+
+function buildEnclosingScope(
+  scope: { name?: string; startLine?: number; endLine?: number } | undefined,
+  targetFile: string,
+  targetLine: number,
+  targetName: string | null,
+): CalleeScope {
+  const startLine = scope?.startLine ?? targetLine;
+  return {
+    name: scope?.name ?? targetName ?? "symbol",
+    file: targetFile,
+    startLine,
+    endLine: scope?.endLine ?? startLine,
+  };
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Calls markdown renderer — renders direct structural calls.
+ */
+
+import {
+  createEvidenceList,
+  type EvidenceListMetadata,
+  renderEvidenceListDisclosure,
+} from "../../analysis/evidence.ts";
+import type { CallEntry, CalleeScope } from "./types.ts";
+
+export // biome-ignore lint/complexity/useMaxParams: renderer needs target data + depth
+function renderCallsResult(
+  enclosingScope: CalleeScope,
+  calls: CallEntry[],
+  relPath: string,
+  maxResults: number,
+  depth: "direct" | "deep" = "direct",
+): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const lines: string[] = [];
+  const depthLabel = depth === "deep" ? "Deep structural calls" : "Direct structural calls";
+  const depthNote =
+    depth === "deep"
+      ? "_Deep: includes calls from nested function/method/callback scopes within the enclosing scope._"
+      : "_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(`# ${depthLabel} from \`${enclosingScope.name}\``);
+  lines.push("");
+  lines.push(
+    `**${calls.length} ${depth === "deep" ? "" : "direct "}structural call${calls.length !== 1 ? "s" : ""}** from enclosing scope \`${enclosingScope.name}\` (${formatScopeRange(enclosingScope)}) in \`${relPath}\``,
+  );
+  lines.push("");
+  lines.push(depthNote);
+  lines.push("");
+
+  const evidence = createEvidenceList({
+    key: "callees.calls",
+    items: calls,
+    maxResults,
+  });
+  for (const c of evidence.items) {
+    lines.push(`- \`${c.name}\` (L${c.line})`);
+  }
+  const disclosure = renderEvidenceListDisclosure(evidence);
+  if (disclosure) {
+    lines.push(disclosure);
+  }
+  return { content: lines.join("\n"), evidenceList: evidence.metadata };
+}
+
+function formatScopeRange(scope: CalleeScope): string {
+  if (scope.startLine === scope.endLine) return `L${scope.startLine}`;
+  return `L${scope.startLine}–L${scope.endLine}`;
+}

package/src/tool/graph/collect-relation.ts

@@ -0,0 +1,371 @@
+/**
+ * Per-relation data collection for code_graph.
+ *
+ * Extracted from execute-graph.ts to keep the graph executor focused on
+ * orchestration. Each relation dispatches to a dedicated handler that
+ * calls the appropriate relations module directly.
+ */
+
+import type { CodeProvider } from "../../analysis/provider.ts";
+import {
+  readNextEnclosingScope,
+  readNextTarget,
+  readNextTopSites,
+} from "../../analysis/read-next.ts";
+import { toDisplayPath } from "../../analysis/search/ripgrep.ts";
+import {
+  buildTestSurfaceDetails,
+  discoverTestFilesForSource,
+  renderRankedTestLabelsForMarkdown,
+} from "../../analysis/tests/test-discovery.ts";
+import type { AnchorKind } from "../../session/target-store.ts";
+import { collectCallees } from "./callees.ts";
+import { renderCallsResult } from "./calls-md.ts";
+import type { GraphRelation } from "./execute.ts";
+import { collectImplementations } from "./implementations.ts";
+import { renderImplementationsResult } from "./implementations-md.ts";
+import { type GraphSection, renderExportsResult, renderImportsResult } from "./markdown-base.ts";
+import { collectCallers } from "./references.ts";
+import { renderReferencesResult } from "./references-md.ts";
+import type { CallEntry } from "./types.ts";
+
+// ── Shared context passed to each relation handler ────────────────────
+
+interface CollectionContext {
+  file: string;
+  position: { line: number; character: number };
+  displayName: string;
+  cwd: string;
+  provider: CodeProvider | null;
+  maxResults: number;
+  anchorKind: AnchorKind;
+  calleeDepth: "direct" | "deep";
+}
+
+// ── Dispatcher ────────────────────────────────────────────────────────
+
+/** Options for {@link collectRelation}. */
+export interface CollectRelationOptions {
+  file: string;
+  position: { line: number; character: number };
+  displayName: string;
+  cwd: string;
+  provider: CodeProvider | null;
+  maxResults: number;
+  semanticReadinessError: string | null;
+  anchorKind: AnchorKind;
+  calleeDepth?: "direct" | "deep";
+}
+
+/**
+ * Collect data for one graph relation. Dispatches to the handler for the
+ * requested relation kind, gating semantic relations behind readiness.
+ */
+export async function collectRelation(
+  rel: GraphRelation,
+  opts: CollectRelationOptions,
+): Promise<GraphSection> {
+  if (opts.semanticReadinessError && (rel === "references" || rel === "implements")) {
+    return { kind: "unavailable", rel, message: opts.semanticReadinessError };
+  }
+
+  const ctx: CollectionContext = {
+    file: opts.file,
+    position: opts.position,
+    displayName: opts.displayName,
+    cwd: opts.cwd,
+    provider: opts.provider,
+    maxResults: opts.maxResults,
+    anchorKind: opts.anchorKind,
+    calleeDepth: opts.calleeDepth ?? "direct",
+  };
+
+  try {
+    const handler = RELATION_HANDLERS[rel];
+    if (!handler) {
+      return { kind: "not-implemented", rel, message: `Unknown relation: ${rel}` };
+    }
+    return handler(ctx);
+  } catch (err) {
+    return {
+      kind: "unavailable",
+      rel,
+      message: err instanceof Error ? err.message : "Unknown error",
+    };
+  }
+}
+
+// ── Relation handlers ─────────────────────────────────────────────────
+
+async function collectReferencesRelation(ctx: CollectionContext): Promise<GraphSection> {
+  const rel: GraphRelation = "references";
+  if (!ctx.provider?.references) {
+    return { kind: "unavailable", rel, message: "No semantic provider for references" };
+  }
+  const result = await collectCallers(ctx.file, ctx.position, ctx.displayName, {
+    cwd: ctx.cwd,
+    provider: { references: ctx.provider.references },
+  });
+  if (result.confidence === "unavailable") {
+    return { kind: "unavailable", rel, message: "No references available" };
+  }
+
+  // Filter out the declaration position (target file + position)
+  const targetLine = ctx.position.line + 1;
+  const targetChar = ctx.position.character + 1;
+  const refs = result.references.filter((r) => {
+    if (r.file !== ctx.file) return true;
+    if (r.line === targetLine && r.character === targetChar) return false;
+    return true;
+  });
+
+  const rendered = renderReferencesResult(
+    ctx.displayName,
+    refs,
+    result.externalCount,
+    result.confidence,
+    ctx.cwd,
+    ctx.maxResults,
+  );
+  return {
+    kind: "ok",
+    rel,
+    count: refs.length,
+    content: rendered.content,
+    evidenceLists: rendered.evidenceList ? [rendered.evidenceList] : [],
+    readNext: [
+      readNextTarget(
+        toDisplayPath(ctx.cwd, ctx.file),
+        ctx.position.line + 1,
+        "inspect the resolved target before editing",
+      ),
+      ...readNextTopSites(
+        refs.slice(0, ctx.maxResults).map((ref) => ({
+          file: toDisplayPath(ctx.cwd, ref.file),
+          line: ref.line,
+        })),
+        2,
+        "reference",
+      ),
+    ],
+  };
+}
+
+async function collectCalleesRelation(ctx: CollectionContext): Promise<GraphSection> {
+  const rel: GraphRelation = "callees";
+  if (ctx.anchorKind === "declaration") {
+    return {
+      kind: "unavailable",
+      rel,
+      message:
+        "Cannot collect callees from a declaration anchor. Re-resolve the target to a name anchor, or pass file + line + character anchored on the identifier.",
+    };
+  }
+  if (!ctx.provider?.calleesAt) {
+    return { kind: "unavailable", rel, message: "No structural provider for callees" };
+  }
+  const result = await collectCallees(
+    ctx.file,
+    ctx.position.line + 1,
+    ctx.position.character + 1,
+    ctx.displayName,
+    { cwd: ctx.cwd, provider: { calleesAt: ctx.provider.calleesAt } },
+    undefined,
+    ctx.calleeDepth,
+  );
+  if (result.confidence === "unavailable") {
+    return { kind: "unavailable", rel, message: "No callees available" };
+  }
+  const enclosingScope = result.enclosingScope ?? {
+    name: ctx.displayName ?? "symbol",
+    file: ctx.file,
+    startLine: ctx.position.line + 1,
+    endLine: ctx.position.line + 1,
+  };
+  const calls: CallEntry[] = result.callees.map((c) => ({
+    name: c.name,
+    file: c.file,
+    line: c.line,
+  }));
+  const rendered = renderCallsResult(
+    enclosingScope,
+    calls,
+    toDisplayPath(ctx.cwd, ctx.file),
+    ctx.maxResults,
+    result.depth,
+  );
+  return {
+    kind: "ok",
+    rel,
+    count: calls.length,
+    content: rendered.content,
+    evidenceLists: rendered.evidenceList ? [rendered.evidenceList] : [],
+    readNext: [
+      readNextEnclosingScope(
+        toDisplayPath(ctx.cwd, ctx.file),
+        enclosingScope,
+        ctx.position.line + 1,
+      ),
+    ],
+  };
+}
+
+async function collectImplementationsRelation(ctx: CollectionContext): Promise<GraphSection> {
+  const rel: GraphRelation = "implements";
+  if (!ctx.provider?.implementation) {
+    return { kind: "unavailable", rel, message: "No semantic provider for implementations" };
+  }
+  const result = await collectImplementations(
+    ctx.file,
+    ctx.position,
+    ctx.displayName,
+    { cwd: ctx.cwd, provider: { implementation: ctx.provider.implementation } },
+    ctx.maxResults,
+  );
+  if (result.confidence === "unavailable") {
+    return { kind: "unavailable", rel, message: "No implementations available" };
+  }
+  // Filter self-references: LSP returns the declaration itself as an
+  // "implementation" for non-interface symbols. Drop the target location.
+  const targetLine = ctx.position.line + 1;
+  const filtered = result.implementations.filter(
+    (impl) => !(impl.file === ctx.file && impl.line === targetLine),
+  );
+  const rendered = renderImplementationsResult(
+    filtered,
+    result.externalCount,
+    ctx.cwd,
+    ctx.maxResults,
+    ctx.displayName,
+  );
+  return {
+    kind: "ok",
+    rel,
+    count: filtered.length,
+    content: rendered.content,
+    evidenceLists: rendered.evidenceList ? [rendered.evidenceList] : [],
+  };
+}
+
+async function collectImportsRelation(ctx: CollectionContext): Promise<GraphSection> {
+  const rel: GraphRelation = "imports";
+  if (!ctx.provider?.imports) {
+    return { kind: "unavailable", rel, message: "No structural provider for imports" };
+  }
+  const importResult = await ctx.provider.imports(ctx.file);
+  if (importResult.kind !== "success") {
+    return { kind: "unavailable", rel, message: `Imports unavailable: ${importResult.kind}` };
+  }
+  const flatImports = importResult.data.map((entry) => ({
+    moduleSpecifier: entry.moduleSpecifier,
+    startLine: entry.startLine,
+  }));
+  const rendered = renderImportsResult(
+    ctx.displayName,
+    flatImports,
+    toDisplayPath(ctx.cwd, ctx.file),
+    ctx.maxResults,
+  );
+  return {
+    kind: "ok",
+    rel,
+    count: flatImports.length,
+    content: rendered.content,
+    evidenceLists: rendered.evidenceList ? [rendered.evidenceList] : [],
+  };
+}
+
+async function collectExportsRelation(ctx: CollectionContext): Promise<GraphSection> {
+  const rel: GraphRelation = "exports";
+  if (!ctx.provider?.exports) {
+    return { kind: "unavailable", rel, message: "No structural provider for exports" };
+  }
+  const exportResult = await ctx.provider.exports(ctx.file);
+  if (exportResult.kind !== "success") {
+    return { kind: "unavailable", rel, message: `Exports unavailable: ${exportResult.kind}` };
+  }
+  const flatExports = exportResult.data.map((entry) => ({
+    name: entry.name,
+    kind: entry.kind,
+    startLine: entry.startLine,
+  }));
+  const rendered = renderExportsResult(
+    ctx.displayName,
+    flatExports,
+    toDisplayPath(ctx.cwd, ctx.file),
+    ctx.maxResults,
+  );
+  return {
+    kind: "ok",
+    rel,
+    count: flatExports.length,
+    content: rendered.content,
+    evidenceLists: rendered.evidenceList ? [rendered.evidenceList] : [],
+  };
+}
+
+async function collectTestsRelation(ctx: CollectionContext): Promise<GraphSection> {
+  const rel: GraphRelation = "tests";
+  const discovery = await discoverTestFilesForSource(ctx.file, {
+    references: ctx.provider?.references,
+    outline: ctx.provider?.outline,
+    cwd: ctx.cwd,
+    cap: ctx.maxResults,
+    position: ctx.position,
+  });
+  const tests = buildTestSurfaceDetails(
+    { status: discovery.kind, provenance: discovery.provenance, files: discovery.files },
+    ctx.cwd,
+    ctx.maxResults,
+  );
+
+  if (discovery.kind === "unavailable") {
+    return {
+      kind: "unavailable",
+      rel,
+      message: "No test provider available — semantic and structural providers are absent",
+      tests,
+    };
+  }
+
+  if (discovery.kind === "empty") {
+    return {
+      kind: "ok",
+      rel,
+      count: 0,
+      content: `**Tests** — no companion test files found.\n`,
+      tests,
+    };
+  }
+
+  const testLines: string[] = [];
+  for (const testFile of tests.files.slice(0, 3)) {
+    testLines.push(`- \`${testFile.file}\``);
+    testLines.push(...renderRankedTestLabelsForMarkdown(testFile.labels, ctx.maxResults));
+  }
+
+  const provenanceNote = `, ${discovery.provenance}`;
+  const content = `**Tests** (${discovery.files.length} companion file${discovery.files.length !== 1 ? "s" : ""}${provenanceNote})\n\n${testLines.join("\n")}\n`;
+  return { kind: "ok", rel, count: discovery.files.length, content, tests };
+}
+
+// ── Handler dispatch table ────────────────────────────────────────────
+
+/**
+ * Handler dispatch table for concrete relation kinds.
+ *
+ * The `"all"` pseudo-relation is expanded into the individual kinds by
+ * {@link expandAllRelations} in execute-graph.ts before iteration, so
+ * `collectRelation` is never called with `"all"` at runtime. The table
+ * is typed as a partial record to reflect this invariant.
+ */
+const RELATION_HANDLERS: Partial<
+  Record<GraphRelation, (ctx: CollectionContext) => Promise<GraphSection>>
+> = {
+  references: collectReferencesRelation,
+  callees: collectCalleesRelation,
+  implements: collectImplementationsRelation,
+  imports: collectImportsRelation,
+  exports: collectExportsRelation,
+  tests: collectTestsRelation,
+};

package/src/tool/graph/execute.ts

@@ -0,0 +1,95 @@
+/**
+ * Tool executor for code_graph.
+ *
+ * Unified relation-graph tool — replaces code_references, code_calls,
+ * and code_implementations. Resolves one target, then dispatches to the
+ * appropriate analysis service per requested relation.
+ *
+ * Thin executor: validates params via pipeline, then delegates to the
+ * graph use-case for target resolution, data collection, and rendering.
+ */
+
+import type { AnchorKind } from "../../session/target-store.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { composeRules, focusedToolRules, requireAtLeastOne } from "../infra/cross-field.ts";
+import { searchErrorResult } from "../infra/error-results.ts";
+import {
+  expandTargetId,
+  gateCapability,
+  resolveScopeParam,
+  runPipe,
+  validateParams,
+} from "../infra/pipeline.ts";
+import { emitToolProgress } from "../infra/progress.ts";
+import { executeGraph } from "./orchestrate.ts";
+
+/** Relation kinds accepted by code_graph. */
+export type GraphRelation =
+  | "references"
+  | "callees"
+  | "imports"
+  | "exports"
+  | "implements"
+  | "tests"
+  | "all";
+
+export interface CodeGraphToolParams {
+  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?: string | null;
+}
+
+export async function executeGraphTool(
+  params: CodeGraphToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  emitToolProgress(ctx.onUpdate, "code_graph: resolving target...");
+
+  return runPipe(
+    params,
+    ctx,
+    [
+      expandTargetId((msg) => searchErrorResult(msg)),
+      resolveScopeParam((reason) => searchErrorResult(`**Error:** ${reason}`)),
+      validateParams(
+        composeRules(focusedToolRules(), requireAtLeastOne("file", "symbol", "scope")),
+        (msg) => searchErrorResult(msg),
+      ),
+      gateCapability("code_graph"),
+    ],
+    async (p, c) => {
+      emitToolProgress(c.onUpdate, "code_graph: collecting relations...");
+      return executeGraph(
+        {
+          targetId: p.targetId,
+          file: p.file,
+          line: p.line,
+          character: p.character,
+          symbol: p.symbol,
+          scope: p.scope,
+          relations: p.relations,
+          calleeDepth: p.calleeDepth,
+          maxResults: p.maxResults,
+          _expandedName: p._expandedName,
+          _expandedAnchorKind: p._expandedAnchorKind as AnchorKind | undefined,
+        },
+        {
+          cwd: c.cwd,
+          session: c.session,
+          provider: c.session.getProvider(),
+          onUpdate: c.onUpdate,
+        },
+      );
+    },
+  );
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Implementations markdown renderer — renders semantic implementation locations.
+ */
+
+import {
+  createEvidenceList,
+  type EvidenceListMetadata,
+  renderEvidenceListDisclosure,
+} from "../../analysis/evidence.ts";
+import { compactLineRanges } from "../../analysis/references/semantic-refs.ts";
+import { toDisplayPath } from "../../analysis/search/ripgrep.ts";
+import type { ImplementationEntry } from "./types.ts";
+
+/**
+ * Group implementation entries by display file path, collecting line numbers.
+ */
+function groupByFile(impls: ImplementationEntry[], cwd: string): Map<string, number[]> {
+  const byFile = new Map<string, number[]>();
+  for (const impl of impls) {
+    const displayPath = toDisplayPath(cwd, impl.file);
+    const group = byFile.get(displayPath) ?? [];
+    group.push(impl.line);
+    byFile.set(displayPath, group);
+  }
+  return byFile;
+}
+
+// biome-ignore lint/complexity/useMaxParams: render function with independent display parameters
+export function renderImplementationsResult(
+  impls: ImplementationEntry[],
+  externalCount: number,
+  cwd: string,
+  maxResults: number,
+  targetName?: string,
+): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const lines: string[] = [];
+  lines.push(
+    targetName
+      ? `# Implementations of \`${targetName}\` (semantic)`
+      : "# Implementations (semantic)",
+  );
+  lines.push("");
+  if (impls.length > 0) {
+    lines.push(`**${impls.length} implementation${impls.length !== 1 ? "s" : ""}** in the project`);
+    lines.push("");
+
+    const evidence = createEvidenceList({
+      key: "implements.locations",
+      items: impls,
+      maxResults,
+    });
+    const byFile = groupByFile(evidence.items, cwd);
+    for (const [file, locations] of byFile) {
+      lines.push(`### ${file}`);
+      lines.push(`- ${compactLineRanges(locations)}`);
+      lines.push("");
+    }
+
+    const disclosure = renderEvidenceListDisclosure(evidence);
+    if (disclosure) {
+      lines.push(disclosure);
+    }
+  }
+
+  if (externalCount > 0) {
+    lines.push(
+      `_+${externalCount} external location${externalCount !== 1 ? "s" : ""} (outside this project)_`,
+    );
+    lines.push("");
+  }
+
+  return {
+    content: lines.join("\n"),
+    evidenceList:
+      impls.length > 0
+        ? createEvidenceList({ key: "implements.locations", items: impls, maxResults }).metadata
+        : null,
+  };
+}