@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/tool/graph/execute.ts

@@ -1,123 +1,62 @@
-/**
- * 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: resolves target via session target workflow (deep seam),
- * validates params via pipeline, then delegates to the graph use-case.
- */
+/** Thin Pi adapter for the session-owned code_graph workflow. */
 
-import type { AnchorKind } from "../../session/target-store.ts";
+import type { GraphWorkflowInput, RequestedGraphRelation } from "../../session/graph-types.ts";
+import type { GraphTargetInput } from "../../session/target-input.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 { gateCapability, resolveScopeParam, runPipe, validateParams } from "../infra/pipeline.ts";
-import { emitToolProgress } from "../infra/progress.ts";
-import { executeGraph } from "./orchestrate.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { assembleGraphResult } from "../result/graph.ts";
+import { renderGraphResult } from "./markdown-base.ts";
 
-/** Relation kinds accepted by code_graph. */
-export type GraphRelation =
-  | "references"
-  | "callees"
-  | "imports"
-  | "exports"
-  | "implements"
-  | "tests"
-  | "all";
+export type GraphRelation = RequestedGraphRelation;
 
 export interface CodeGraphToolParams {
-  targetId?: string;
-  file?: string;
-  line?: number;
-  character?: number;
-  symbol?: string;
-  scope?: string;
+  target: GraphTargetInput;
   relations?: GraphRelation[];
   calleeDepth?: "direct" | "deep";
   maxResults?: number;
-  /** Set by target-workflow resolution. */
-  _expandedName?: string | null;
-  /** Set by target-workflow resolution. */
-  _expandedAnchorKind?: string | null;
 }
 
-/** Graph target-workflow policy: no file-level targets, name anchor optional. */
-const GRAPH_TARGET_POLICY = {
-  fileLevelAllowed: false,
-  nameAnchorRequired: false,
-  waitForSemantic: false,
-} as const;
-
 export async function executeGraphTool(
   params: CodeGraphToolParams,
   ctx: CodeIntelToolExecCtx,
 ): Promise<CodeIntelResult> {
-  emitToolProgress(ctx.onUpdate, "code_graph: resolving target...");
-
-  // ── Deep seam: resolve targetId through the session target workflow ──
-  // Replaces expandTargetId pipeline stage. Anchored coordinates and
-  // symbol queries still use the orchestrate's own resolution.
-  if (params.targetId) {
-    const outcome = await ctx.session.resolveTarget(
-      { targetId: params.targetId },
-      GRAPH_TARGET_POLICY,
-    );
+  const outcome = await ctx.session.graph(params as GraphWorkflowInput, toWorkflowControl(ctx));
 
-    if (outcome.kind === "resolved") {
-      params.file = outcome.entry.file;
-      params.line = outcome.entry.displayLine;
-      params.character = outcome.entry.displayCharacter;
-      params._expandedName = outcome.entry.name;
-      params._expandedAnchorKind = outcome.entry.anchorKind;
-      // targetId wins — drop conflicting scope to avoid validation error
-      params.scope = undefined;
-    } else if (outcome.kind !== "no-target") {
-      const msg =
-        outcome.kind === "invalid-input"
-          ? outcome.message
-          : outcome.kind === "unavailable"
-            ? outcome.reason
-            : "Target resolution failed. Verify the targetId is valid.";
-      return searchErrorResult(`**Error:** ${msg}`);
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return searchErrorResult(`**Error:** ${outcome.message}`);
+  }
+  if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
+    const lines = [
+      outcome.kind === "kind-mismatch"
+        ? `**No target matched provider kind \`${outcome.requestedKind}\`. Near matches:**`
+        : "**Target is ambiguous. Choose one candidate handle:**",
+      "",
+    ];
+    for (const candidate of outcome.candidates) {
+      lines.push(
+        `- \`${candidate.targetId}\` — ${candidate.name} (\`${candidate.kind ?? "unknown"}\`) at ${candidate.file}:${candidate.line}:${candidate.character}`,
+      );
     }
+    if (outcome.kind === "kind-mismatch") {
+      lines.push(
+        "",
+        "Retry without `symbolKind`, use an observed provider kind, or choose a handle.",
+      );
+    }
+    return searchErrorResult(lines.join("\n"));
   }
 
-  return runPipe(
-    params,
-    ctx,
-    [
-      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,
-        },
-      );
-    },
-  );
+  const assembly = assembleGraphResult({
+    displayName: outcome.displayName,
+    sections: outcome.sections,
+    resolvedDisplayFile: outcome.resolvedDisplayFile,
+    maxResults: outcome.maxResults,
+    cwd: ctx.cwd,
+  });
+  return {
+    content: renderGraphResult(assembly),
+    details: { type: "search", data: assembly.details },
+  };
 }

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

@@ -1,20 +1,16 @@
-/**
- * Implementations markdown renderer — renders semantic implementation locations.
- */
+/** Implementations markdown renderer over assembled semantic evidence. */
 
 import {
-  createEvidenceList,
+  type EvidenceList,
   type EvidenceListMetadata,
-  renderEvidenceListDisclosure,
+  renderEvidenceListMetadataDisclosure,
 } 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";
+import type { ImplementationEntry } from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
+import { renderInvalidProviderLocations } from "./provider-location-md.ts";
 
-/**
- * Group implementation entries by display file path, collecting line numbers.
- */
-function groupByFile(impls: ImplementationEntry[], cwd: string): Map<string, number[]> {
+function groupByFile(impls: readonly ImplementationEntry[], cwd: string): Map<string, number[]> {
   const byFile = new Map<string, number[]>();
   for (const impl of impls) {
     const displayPath = toDisplayPath(cwd, impl.file);
@@ -25,55 +21,37 @@ function groupByFile(impls: ImplementationEntry[], cwd: string): Map<string, num
   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)`
+export function renderImplementationsResult(options: {
+  implementations: EvidenceList<ImplementationEntry>;
+  externalCount: number;
+  cwd: string;
+  targetName?: string;
+}): { content: string; evidenceList: EvidenceListMetadata } {
+  const lines: string[] = [
+    options.targetName
+      ? `# Implementations of \`${options.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);
+    "",
+  ];
+  const total =
+    options.implementations.metadata.totalCount ?? options.implementations.metadata.shownCount;
+  if (total > 0) {
+    lines.push(`**${total} implementation${total === 1 ? "" : "s"}** in the project`, "");
+    for (const [file, locations] of groupByFile(options.implementations.items, options.cwd)) {
+      lines.push(`### ${file}`, `- ${compactLineRanges(locations)}`, "");
     }
+    const disclosure = renderEvidenceListMetadataDisclosure(options.implementations.metadata);
+    if (disclosure) lines.push(disclosure);
   }
 
-  if (externalCount > 0) {
+  if (options.externalCount > 0) {
     lines.push(
-      `_+${externalCount} external location${externalCount !== 1 ? "s" : ""} (outside this project)_`,
+      `_+${options.externalCount} external location${options.externalCount === 1 ? "" : "s"} (outside this project)_`,
+      "",
     );
-    lines.push("");
   }
+  const invalidDisclosure = renderInvalidProviderLocations(options.implementations.metadata);
+  if (invalidDisclosure) lines.push(invalidDisclosure, "");
 
-  return {
-    content: lines.join("\n"),
-    evidenceList:
-      impls.length > 0
-        ? createEvidenceList({ key: "implements.locations", items: impls, maxResults }).metadata
-        : null,
-  };
+  return { content: lines.join("\n"), evidenceList: options.implementations.metadata };
 }

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

@@ -1,211 +1,88 @@
-// Relations markdown renderer — consumes use-case data and produces markdown content.
+/** Markdown adapter for assembled code_graph evidence. */
 
-import {
-  createEvidenceList,
-  type EvidenceListMetadata,
-  renderEvidenceListDisclosure,
-} from "../../analysis/evidence.ts";
 import { 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 { GraphResultAssembly, GraphSection } from "../result/graph.ts";
+import type { GraphResultAssembly } from "../result/graph.ts";
+import { renderCallsResult } from "./calls-md.ts";
+import { renderImplementationsResult } from "./implementations-md.ts";
+import { renderReferencesResult } from "./references-md.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) {
+/** Render an assembled graph result. */
+export function renderGraphResult(assembly: GraphResultAssembly): string {
+  const lines = [
+    `# Graph of \`${assembly.displayName}\``,
+    "",
+    `_File: \`${assembly.resolvedDisplayFile}\`_`,
+    "",
+  ];
+
+  const available = assembly.sections.filter((section) => section.kind === "ok");
+  if (available.length > 0) {
     lines.push(
-      `_+${result.externalCount} external reference${result.externalCount !== 1 ? "s" : ""}_`,
+      available
+        .map(
+          (section) =>
+            `**${section.rel}**: ${sectionCount(section)} result${sectionCount(section) === 1 ? "" : "s"}`,
+        )
+        .join(" | "),
+      "",
     );
   }
-  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 ───────────────────────────────────────────────────
-
-/**
- * Render an assembled graph result.
- *
- * Produces a unified markdown output with a summary header, per-section
- * pre-rendered content, and a footer with follow-up hints.
- */
-export function renderGraphResult(assembly: GraphResultAssembly): string {
-  const { displayName, sections, resolvedDisplayFile: resolvedFile } = assembly;
-  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("");
-  }
+  const unavailable = assembly.sections.filter((section) => section.kind === "unavailable");
   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("");
+    lines.push(
+      `_Unavailable: ${unavailable.map((section) => `\`${section.rel}\``).join(", ")}_`,
+      "",
+    );
   }
 
-  // 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("");
+  for (const section of assembly.sections) {
+    if (section.kind === "unavailable") {
+      lines.push(`**${section.rel}**: ${section.message}`, "");
+      continue;
     }
-  }
 
-  lines.push(...renderReadNextSection(okSections.flatMap((section) => section.readNext ?? [])));
+    switch (section.rel) {
+      case "references": {
+        const rendered = renderReferencesResult({
+          symbolName: assembly.displayName,
+          references: section.evidence,
+          externalCount: section.data.externalCount,
+          confidence: section.data.confidence,
+          cwd: assembly.cwd,
+        });
+        lines.push(rendered.content, "");
+        break;
+      }
+      case "callees": {
+        const rendered = renderCallsResult(
+          section.data.enclosingScope,
+          section.evidence,
+          assembly.resolvedDisplayFile,
+          section.data.depth,
+        );
+        lines.push(rendered.content, "");
+        break;
+      }
+      case "implements": {
+        const rendered = renderImplementationsResult({
+          implementations: section.evidence,
+          externalCount: section.data.externalCount,
+          cwd: assembly.cwd,
+          targetName: assembly.displayName,
+        });
+        lines.push(rendered.content, "");
+        break;
+      }
+    }
+  }
 
+  lines.push(...renderReadNextSection(available.flatMap((section) => section.readNext)));
   return lines.join("\n");
 }
+
+function sectionCount(
+  section: Extract<GraphResultAssembly["sections"][number], { kind: "ok" }>,
+): number {
+  return section.evidence.metadata.totalCount ?? section.evidence.metadata.shownCount;
+}

package/src/tool/graph/provider-location-md.ts

@@ -0,0 +1,9 @@
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+
+/** Render an explicit disclosure for unusable semantic-provider locations. */
+export function renderInvalidProviderLocations(metadata: EvidenceListMetadata): string | null {
+  const count = metadata.invalidLocationCount ?? 0;
+  if (count <= 0 || metadata.partialReason === null) return null;
+  const noun = count === 1 ? "location" : "locations";
+  return `_${count} invalid provider ${noun} omitted (${metadata.partialReason})_`;
+}

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

@@ -1,34 +1,41 @@
-/**
- * References markdown renderer — labels results as references/usages, not callers.
- */
+/** References markdown renderer over assembled semantic evidence. */
 
-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";
+import type { EvidenceList, EvidenceListMetadata } from "../../analysis/evidence.ts";
+import { formatAssembledReferenceList } from "../../analysis/references/semantic-refs.ts";
+import type { ReferenceEntry } from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
+import { renderInvalidProviderLocations } from "./provider-location-md.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" : ""}_`);
+export function renderReferencesResult(options: {
+  symbolName: string;
+  references: EvidenceList<ReferenceEntry>;
+  externalCount: number;
+  confidence: string;
+  cwd: string;
+}): { content: string; evidenceList: EvidenceListMetadata | null } {
+  const total = options.references.metadata.totalCount ?? options.references.metadata.shownCount;
+  const lines = [
+    `# References of \`${options.symbolName}\``,
+    "",
+    `**${total} reference${total === 1 ? "" : "s"}** (${options.confidence})`,
+  ];
+  if (options.externalCount > 0) {
+    lines.push(
+      `_+${options.externalCount} external reference${options.externalCount === 1 ? "" : "s"}_`,
+    );
   }
+  const invalidDisclosure = renderInvalidProviderLocations(options.references.metadata);
+  if (invalidDisclosure) lines.push(invalidDisclosure);
   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);
+  const displayEvidence = {
+    key: options.references.key,
+    items: options.references.items.map((reference) => ({
+      file: toDisplayPath(options.cwd, reference.file),
+      line: reference.line,
+    })),
+    metadata: options.references.metadata,
+  };
+  const evidenceList = formatAssembledReferenceList(lines, displayEvidence);
   return { content: lines.join("\n"), evidenceList };
 }