@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/tool/find/execute.ts

@@ -1,131 +1,40 @@
-/**
- * Tool executor for code_find.
- *
- * Unified ranked code search with strict mode dispatch:
- * - text (default): literal ripgrep
- * - regex: ripgrep regex
- * - ast: tree-sitter structured search
- * - semantic: LSP workspace symbols
- *
- * Thin executor: validates params via pipeline, then delegates all
- * modes to the pattern use-case.
- */
+/** Thin Pi adapter for the session-owned code_find workflow. */
 
+import type { FindMode, FindWorkflowInput } from "../../session/find-types.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
-import { findModeKindRules } from "../infra/cross-field.ts";
 import { unavailableSearchDetails } from "../infra/error-results.ts";
-import {
-  gateSemanticReadiness,
-  resolveScopeSetParam,
-  runPipe,
-  validateParams,
-} from "../infra/pipeline.ts";
-import { emitToolProgress } from "../infra/progress.ts";
-import { renderSemanticReadinessTimeout } from "../infra/readiness-message.ts";
-import { executePattern } from "./orchestrate.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { assembleFindWorkflowResult } from "../result/find.ts";
+import type { CodeFindAstKind } from "./ast-kinds.ts";
+import { renderFindResult } from "./render.ts";
 
 export interface CodeFindToolParams {
   query: string;
-  scope?: string | string[];
-  mode?: "text" | "regex" | "ast" | "semantic";
-  kind?:
-    | "definition"
-    | "import"
-    | "export"
-    | "call"
-    | "type"
-    | "interface"
-    | "class"
-    | "method"
-    | "enum"
-    | "test";
-  contextLines?: number;
+  scope?: string[];
+  mode: FindMode;
+  kind?: CodeFindAstKind;
   maxResults?: number;
 }
 
-interface CodeFindPipelineParams extends CodeFindToolParams {
-  _resolvedScopePaths?: string[];
-  _resolvedScopeDisplay?: string | null;
-}
-
-function scopeForDetails(scope: CodeFindToolParams["scope"]): string | null {
-  if (Array.isArray(scope)) return scope.join(", ");
-  return scope ?? null;
-}
-
 export async function executeFindTool(
   params: CodeFindToolParams,
   ctx: CodeIntelToolExecCtx,
 ): Promise<CodeIntelResult> {
-  if (!params.query || params.query.trim().length === 0) {
+  const outcome = await ctx.session.find(params as FindWorkflowInput, toWorkflowControl(ctx));
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
     return {
-      content: "**Error:** `code_find` requires a non-empty `query` parameter.",
-      details: unavailableSearchDetails(scopeForDetails(params.scope), [
-        "Provide a non-empty `query` parameter",
-      ]),
+      content: `**Error:** ${outcome.message}`,
+      details: unavailableSearchDetails(
+        Array.isArray(params?.scope) ? params.scope.join(", ") : null,
+        ["Fix the search input and retry"],
+      ),
     };
   }
 
-  emitToolProgress(ctx.onUpdate, `code_find: searching for "${params.query}"...`);
-
-  const mode = params.mode ?? "text";
-  const needsSemanticReadiness = mode === "semantic";
-
-  const pipelineParams = params as CodeFindPipelineParams;
-
-  return runPipe(
-    pipelineParams,
-    ctx,
-    [
-      validateParams(findModeKindRules(), (msg) => ({
-        content: msg,
-        details: unavailableSearchDetails(scopeForDetails(params.scope), [
-          'Use `mode: "ast"` with `kind`, or remove `kind` for text/regex/semantic search',
-        ]),
-      })),
-      resolveScopeSetParam((reason) => ({
-        content: `**Error:** ${reason}`,
-        details: unavailableSearchDetails(scopeForDetails(params.scope), [
-          "Verify each `scope` path exists and is within the workspace",
-        ]),
-      })),
-      ...(needsSemanticReadiness
-        ? [
-            gateSemanticReadiness("code_find", {
-              onTimeout: () => ({
-                content: renderSemanticReadinessTimeout("code_find", 15_000),
-                details: unavailableSearchDetails(scopeForDetails(params.scope), [
-                  "Retry shortly or check `code_health`",
-                ]),
-              }),
-              throwOnUnavailable: true,
-            }),
-          ]
-        : []),
-    ],
-    async (p, c) => {
-      emitToolProgress(c.onUpdate, `code_find: ${mode} mode...`);
-
-      // AST mode requires structural provider
-      if (mode === "ast" && !c.session.getStructuralProvider()) {
-        throw new Error(
-          "code_find AST search is unavailable because no structural/tree-sitter provider is active for this workspace.",
-        );
-      }
-
-      return executePattern(
-        {
-          pattern: p.query,
-          paths: p._resolvedScopePaths ?? [c.cwd],
-          scopeLabel: p._resolvedScopeDisplay ?? null,
-          regex: mode === "regex",
-          kind: p.kind,
-          mode,
-          maxResults: p.maxResults ?? 8,
-          contextLines: p.contextLines ?? 1,
-        },
-        { cwd: c.cwd, provider: c.session.getProvider(), signal: c.signal },
-      );
-    },
-  );
+  const assembly = assembleFindWorkflowResult(outcome);
+  return {
+    content: renderFindResult(assembly),
+    details: { type: "search", data: assembly.details },
+  };
 }

package/src/tool/find/markdown.ts

@@ -1,132 +1,107 @@
-// Pattern search markdown renderer — all formatting for literal, regex, and structured search results.
+// AST search Markdown rendering.
 
-import type { StructuralProvider as StructuralSubstrate } from "@mrclrchtr/supi-code-runtime/api";
 import {
-  createEvidenceList,
   type EvidenceListMetadata,
-  renderEvidenceListDisclosure,
+  renderEvidenceListMetadataDisclosure,
 } from "../../analysis/evidence.ts";
 import type {
   StructuredMatch,
-  StructuredPatternKind,
   StructuredPatternResult,
+  StructuredScanLimitation,
 } from "../../analysis/search/pattern.ts";
-import type { RgMatch } from "../../analysis/search/ripgrep.ts";
-import { groupByFile } from "../../analysis/search/ripgrep.ts";
-
-// ── Structured search formatting ─────────────────────────────────────
-
-// biome-ignore lint/complexity/useMaxParams: structured empty-state with optional result parameter keeps partial-warning logic together
-export function renderStructuredEmptyState(
-  pattern: string,
-  kind: StructuredPatternKind,
-  relScope: string,
-  _structural?: StructuralSubstrate,
-  result?: StructuredPatternResult,
-): string {
-  const lines = [`No ${kind} matches found for \`${pattern}\` in \`${relScope}\`.`];
-  const partial = renderPartialWarning(result);
-  if (partial) {
-    lines.push("");
-    lines.push(partial);
-  }
-  const failureLines = renderFailureSummary(result?.failures);
-  if (failureLines.length > 0) {
-    lines.push("");
-    lines.push(...failureLines);
-  }
+import { CODE_FIND_AST_KIND_LABELS, type CodeFindAstKind } from "./ast-kinds.ts";
+
+export function renderStructuredEmptyState(options: {
+  pattern: string;
+  kind: CodeFindAstKind;
+  relScope: string;
+  result: StructuredPatternResult;
+  evidenceMetadata: EvidenceListMetadata;
+}): string {
+  const lines = [
+    options.result.scan.complete
+      ? `No ${options.kind} matches found for \`${options.pattern}\` in \`${options.relScope}\`.`
+      : `No ${options.kind} matches were collected for \`${options.pattern}\` in \`${options.relScope}\`.`,
+  ];
+  appendScanAndFailures(lines, options.result);
+  const disclosure = renderEvidenceListMetadataDisclosure(options.evidenceMetadata);
+  if (disclosure) lines.push("", disclosure);
   return lines.join("\n");
 }
 
-function renderFailureSummary(failures?: Array<{ file: string; reason: string }>): string[] {
-  if (!failures || failures.length === 0) return [];
+function renderFailureSummary(failures: readonly { file: string; reason: string }[]): string[] {
+  if (failures.length === 0) return [];
   const lines: string[] = [
-    `**${failures.length} file${failures.length !== 1 ? "s" : ""} could not be analyzed:**`,
+    `**${failures.length} file${failures.length === 1 ? "" : "s"} could not be analyzed:**`,
   ];
-  for (const f of failures.slice(0, 5)) {
-    lines.push(`- \`${f.file}\` — ${f.reason}`);
-  }
-  if (failures.length > 5) {
-    lines.push(`- _+${failures.length - 5} more_`);
+  for (const failure of failures.slice(0, 5)) {
+    lines.push(`- \`${failure.file}\` — ${failure.reason}`);
   }
+  if (failures.length > 5) lines.push(`- _+${failures.length - 5} more_`);
   return lines;
 }
 
-function renderPartialWarning(result?: StructuredPatternResult): string | null {
-  if (!result || result.omittedCount <= 0 || !result.partialReason) return null;
-  if (result.partialReason === "timeout") {
-    return `_Partial structured results — scan timed out with +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted. Narrow \`path\` or \`pattern\` for complete coverage._`;
+function renderScanLimitations(limitations: readonly StructuredScanLimitation[]): string | null {
+  if (limitations.length === 0) return null;
+  const descriptions = limitations.map((limitation) => {
+    const count =
+      limitation.pathCount === null
+        ? "unknown paths"
+        : `${limitation.pathCount} path${limitation.pathCount === 1 ? "" : "s"}`;
+    return `${limitation.reason}: ${count}`;
+  });
+  return `_AST Scan incomplete — ${descriptions.join("; ")}. Match total is unknown._`;
+}
+
+function appendScanAndFailures(lines: string[], result: StructuredPatternResult): void {
+  const operationExclusion = result.scan.exclusions.find(
+    (exclusion) => exclusion.reason === "unsupported-operation",
+  );
+  if (operationExclusion) {
+    const count = operationExclusion.pathCount;
+    lines.push(
+      "",
+      `_AST Scan policy excluded ${count} file${count === 1 ? "" : "s"} because ${result.scan.policy.operation} analysis is not supported for their language._`,
+    );
   }
-  return `_Partial structured results — +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted after reaching the structured scan cap. Narrow \`path\` or \`pattern\` for complete coverage._`;
+  const scanWarning = renderScanLimitations(result.scan.limitations);
+  if (scanWarning) lines.push("", scanWarning);
+  const failureLines = renderFailureSummary(result.failures);
+  if (failureLines.length > 0) lines.push("", ...failureLines);
 }
 
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: pattern search rendering groups matches by file and adds summaries — each branch stays linear
-// biome-ignore lint/complexity/useMaxParams: structured renderer mirrors the existing public helper shape plus display cap
+// biome-ignore lint/complexity/useMaxParams: renderer mirrors the public evidence inputs
 export function renderStructuredMatches(
   pattern: string,
-  kind: StructuredPatternKind,
+  kind: CodeFindAstKind,
   relScope: string,
   result: StructuredPatternResult,
-  maxResults: number,
+  evidenceMetadata: EvidenceListMetadata,
 ): { content: string; evidenceList: EvidenceListMetadata } {
-  const evidence = createEvidenceList({
-    key: "find.astMatches",
-    items: result.matches,
-    maxResults,
-  });
-  const grouped = new Map<string, StructuredMatch[]>();
-  for (const match of evidence.items) {
-    const group = grouped.get(match.file) ?? [];
-    group.push(match);
-    grouped.set(match.file, group);
-  }
+  const shownMatches = result.matches.slice(0, evidenceMetadata.shownCount);
+  const grouped = groupMatches(shownMatches);
+  const matchedFiles = groupMatches(result.matches);
+  const kindLabel = CODE_FIND_AST_KIND_LABELS[kind];
+  const matchCount =
+    evidenceMetadata.totalCount === null
+      ? `At least ${result.matches.length} collected match${result.matches.length === 1 ? "" : "es"}`
+      : `${result.matches.length} match${result.matches.length === 1 ? "" : "es"}`;
+  const lines = [
+    `# Pattern ${kindLabel}: \`${pattern}\``,
+    "",
+    `**${matchCount}** across **${matchedFiles.size} file${matchedFiles.size === 1 ? "" : "s"}** in \`${relScope}\``,
+  ];
 
-  const kindLabel =
-    kind === "definition"
-      ? "Definitions"
-      : kind === "export"
-        ? "Exports"
-        : kind === "import"
-          ? "Imports"
-          : kind === "call"
-            ? "Calls"
-            : kind === "type"
-              ? "Types"
-              : kind === "interface"
-                ? "Interfaces"
-                : kind === "class"
-                  ? "Classes"
-                  : kind === "method"
-                    ? "Methods"
-                    : kind === "enum"
-                      ? "Enums"
-                      : "Tests";
-  const lines: string[] = [];
-  lines.push(`# Pattern ${kindLabel}: \`${pattern}\``);
-  lines.push("");
-  lines.push(
-    `**${result.matches.length} match${result.matches.length !== 1 ? "es" : ""}** across **${grouped.size} file${grouped.size !== 1 ? "s" : ""}** in \`${relScope}\``,
-  );
   if (kind === "call") {
-    lines.push("");
     lines.push(
+      "",
       '_Note: AST call results are name-based, not symbol-identity-aware. Use `code_graph` with `relations: ["references"]` on a resolved target for identity-aware callers._',
     );
   }
-  const partialWarning = renderPartialWarning(result);
-  if (partialWarning) {
-    lines.push(partialWarning);
-  }
-  if (result.failures.length > 0) {
-    lines.push("");
-    lines.push(...renderFailureSummary(result.failures));
-  }
+  appendScanAndFailures(lines, result);
   lines.push("");
 
-  if (kind === "definition" || kind === "export") {
-    addDuplicateSummary(lines, result.matches);
-  }
-
+  if (kind === "definition" || kind === "export") addDuplicateSummary(lines, shownMatches);
   for (const [file, fileMatches] of grouped) {
     lines.push(`### ${file}`);
     for (const match of fileMatches) {
@@ -135,15 +110,22 @@ export function renderStructuredMatches(
     lines.push("");
   }
 
-  const disclosure = renderEvidenceListDisclosure(evidence);
-  if (disclosure) {
-    lines.push(disclosure);
-  }
+  const disclosure = renderEvidenceListMetadataDisclosure(evidenceMetadata);
+  if (disclosure) lines.push(disclosure);
+  return { content: lines.join("\n"), evidenceList: evidenceMetadata };
+}
 
-  return { content: lines.join("\n"), evidenceList: evidence.metadata };
+function groupMatches(matches: readonly StructuredMatch[]): Map<string, StructuredMatch[]> {
+  const grouped = new Map<string, StructuredMatch[]>();
+  for (const match of matches) {
+    const group = grouped.get(match.file) ?? [];
+    group.push(match);
+    grouped.set(match.file, group);
+  }
+  return grouped;
 }
 
-function addDuplicateSummary(lines: string[], matches: StructuredMatch[]): void {
+function addDuplicateSummary(lines: string[], matches: readonly StructuredMatch[]): void {
   const byName = new Map<string, Set<string>>();
   for (const match of matches) {
     const files = byName.get(match.name) ?? new Set<string>();
@@ -155,7 +137,6 @@ function addDuplicateSummary(lines: string[], matches: StructuredMatch[]): void
     .map(([name, files]) => ({ name, files: [...files].sort((a, b) => a.localeCompare(b)) }))
     .filter((entry) => entry.files.length > 1)
     .sort((a, b) => b.files.length - a.files.length || a.name.localeCompare(b.name));
-
   if (duplicates.length === 0) return;
 
   lines.push("## Duplicate Definitions");
@@ -166,123 +147,6 @@ function addDuplicateSummary(lines: string[], matches: StructuredMatch[]): void
         .join(", ")}`,
     );
   }
-  if (duplicates.length > 8) {
-    lines.push(`- _+${duplicates.length - 8} more duplicates_`);
-  }
+  if (duplicates.length > 8) lines.push(`- _+${duplicates.length - 8} more duplicates_`);
   lines.push("");
 }
-
-// ── Text search formatting ──────────────────────────────────────────
-
-export function renderRegexError(pattern: string, error: string): string {
-  const errLines = error
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean);
-  const detail =
-    [...errLines]
-      .reverse()
-      .find((line) => line.startsWith("error:"))
-      ?.replace(/^error:\s*/, "") ??
-    errLines.at(-1) ??
-    "ripgrep rejected the regex.";
-  return `**Error:** Invalid regex pattern \`${pattern}\`: ${detail}`;
-}
-
-export function renderPatternResults(
-  pattern: string,
-  relScope: string,
-  matches: RgMatch[],
-  maxResults: number,
-): { content: string; evidenceList: EvidenceListMetadata } {
-  const lines: string[] = [];
-  lines.push(`# Pattern: \`${pattern}\``);
-  lines.push("");
-  lines.push(`**${matches.length} match${matches.length > 1 ? "es" : ""}** in \`${relScope}\``);
-  lines.push("");
-
-  const evidence = createEvidenceList({
-    key: "find.textMatches",
-    items: matches,
-    maxResults,
-  });
-  const byFile = groupByFile(evidence.items);
-  for (const [file, fileMatches] of byFile) {
-    lines.push(`### ${file}`);
-    const renderedLines = new Set<number>();
-    const matchLines = new Set(fileMatches.map((match) => match.line));
-    for (const m of fileMatches) {
-      renderMatchWithContext(lines, m, renderedLines, matchLines, pattern);
-    }
-    lines.push("");
-  }
-
-  const disclosure = renderEvidenceListDisclosure(evidence);
-  if (disclosure) {
-    lines.push(disclosure);
-  }
-  lines.push("");
-  return { content: lines.join("\n"), evidenceList: evidence.metadata };
-}
-
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: context-line rendering with before/after/skip logic is clearer as one function
-// biome-ignore lint/complexity/useMaxParams: options-object refactor would reduce readability for this rendering helper
-function renderMatchWithContext(
-  lines: string[],
-  m: RgMatch,
-  renderedLines: Set<number>,
-  matchLines: Set<number>,
-  _pattern: string,
-): void {
-  if (m.context) {
-    for (const c of m.context.filter((cx) => cx.line < m.line)) {
-      if (renderedLines.has(c.line) || matchLines.has(c.line)) continue;
-      lines.push(`  L${c.line}: ${c.text.slice(0, 120)}`);
-      renderedLines.add(c.line);
-    }
-  }
-  if (!renderedLines.has(m.line)) {
-    lines.push(`- L${m.line}: \`${(m.text || "").slice(0, 120)}\``);
-    renderedLines.add(m.line);
-  }
-  if (m.context) {
-    for (const c of m.context.filter((cx) => cx.line > m.line)) {
-      if (renderedLines.has(c.line) || matchLines.has(c.line)) continue;
-      lines.push(`  L${c.line}: ${c.text.slice(0, 120)}`);
-      renderedLines.add(c.line);
-    }
-  }
-}
-
-export function renderPatternSummary(
-  pattern: string,
-  relScope: string,
-  matches: RgMatch[],
-  maxResults: number,
-): string {
-  const byFile = groupByFile(matches);
-  const sorted = [...byFile.entries()].sort((a, b) => b[1].length - a[1].length);
-
-  const lines: string[] = [];
-  lines.push(`# Pattern Summary: \`${pattern}\``);
-  lines.push("");
-  lines.push(
-    `**${matches.length} match${matches.length > 1 ? "es" : ""}** across **${byFile.size} file${byFile.size > 1 ? "s" : ""}** in \`${relScope}\``,
-  );
-  lines.push("");
-
-  for (const [file, fileMatches] of sorted.slice(0, maxResults)) {
-    const lineNums = [...new Set(fileMatches.map((m) => m.line))].sort((a, b) => a - b).slice(0, 3);
-    const extra = fileMatches.length > 3 ? ` (+${fileMatches.length - 3} more)` : "";
-    const linesStr = lineNums.join(", ");
-    lines.push(
-      `- \`${file}\` — ${fileMatches.length} match${fileMatches.length > 1 ? "es" : ""}${linesStr ? ` at L${linesStr}` : ""}${extra}`,
-    );
-  }
-
-  if (sorted.length > maxResults) {
-    lines.push(`- _+${sorted.length - maxResults} more files omitted_`);
-  }
-  lines.push("");
-  return lines.join("\n");
-}

package/src/tool/find/modes.ts

@@ -0,0 +1,5 @@
+/** Canonical public code_find mode vocabulary. */
+export const CODE_FIND_MODES = ["ast", "semantic"] as const;
+
+/** One supported code-aware search mode. */
+export type CodeFindMode = (typeof CODE_FIND_MODES)[number];

package/src/tool/find/render.ts

@@ -0,0 +1,57 @@
+/** Markdown adapter for assembled code_find outcomes. */
+
+import {
+  type EvidenceListMetadata,
+  renderEvidenceListMetadataDisclosure,
+} from "../../analysis/evidence.ts";
+import type { FindResultAssembly } from "../result/find.ts";
+import { renderStructuredEmptyState, renderStructuredMatches } from "./markdown.ts";
+
+export function renderFindResult(assembly: FindResultAssembly): string {
+  const { outcome } = assembly;
+  const evidence = assembly.assembled.evidenceLists[0];
+  if (!evidence) return "**Unavailable:** Search evidence metadata was not assembled.";
+
+  const content =
+    outcome.data.kind === "semantic"
+      ? renderSemantic(assembly, evidence)
+      : outcome.data.result.matches.length === 0
+        ? renderStructuredEmptyState({
+            pattern: outcome.query,
+            kind: outcome.data.astKind,
+            relScope: outcome.scopeLabel,
+            result: outcome.data.result,
+            evidenceMetadata: evidence,
+          })
+        : renderStructuredMatches(
+            outcome.query,
+            outcome.data.astKind,
+            outcome.scopeLabel,
+            outcome.data.result,
+            evidence,
+          ).content;
+
+  return `**Confidence:** \`${assembly.assembled.confidence}\`\n\n${content}`;
+}
+
+function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMetadata): string {
+  const { outcome } = assembly;
+  if (outcome.data.kind !== "semantic") return "";
+  const symbols = outcome.data.symbols;
+  if (symbols.length === 0) {
+    return `**Semantic search** — \`${outcome.query}\`\n\nNo semantic results found in \`${outcome.scopeLabel}\`.`;
+  }
+
+  const lines = [
+    `**Semantic search** — \`${outcome.query}\` (${symbols.length} symbol${symbols.length === 1 ? "" : "s"} found)`,
+  ];
+  for (const symbol of symbols.slice(0, evidence.shownCount)) {
+    const kind = symbol.kind ? ` [${symbol.kind}]` : "";
+    const container = symbol.container ? ` (in ${symbol.container})` : "";
+    const anchor = symbol.nameAnchor ?? symbol.declarationAnchor;
+    lines.push(`- \`${symbol.name}\`${kind}${container} — \`${symbol.file}:${anchor.line}\``);
+  }
+  const disclosure = renderEvidenceListMetadataDisclosure(evidence);
+  if (disclosure) lines.push(disclosure);
+  return lines.join("\n");
+}

package/src/tool/find/tui.ts

@@ -10,7 +10,7 @@ import type { CodeFindToolParams } from "./execute.ts";
 
 export function renderFindCall(args: unknown, theme: Theme, _context: unknown): Text {
   const params = (args ?? {}) as CodeFindToolParams;
-  const mode = params.mode ?? "text";
+  const mode = params.mode ?? "mode?";
 
   let content = theme.fg("toolTitle", "code_find");
 

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

@@ -1,51 +1,38 @@
-/**
- * Calls markdown renderer — renders direct structural calls.
- */
+/** Calls markdown renderer — renders assembled structural-call evidence. */
 
 import {
-  createEvidenceList,
+  type EvidenceList,
   type EvidenceListMetadata,
-  renderEvidenceListDisclosure,
+  renderEvidenceListMetadataDisclosure,
 } from "../../analysis/evidence.ts";
-import type { CallEntry, CalleeScope } from "./types.ts";
+import type { CallEntry, CalleeScope } from "../../analysis/relations/types.ts";
 
-export // biome-ignore lint/complexity/useMaxParams: renderer needs target data + depth
-function renderCallsResult(
+export function renderCallsResult(
   enclosingScope: CalleeScope,
-  calls: CallEntry[],
+  calls: EvidenceList<CallEntry>,
   relPath: string,
-  maxResults: number,
   depth: "direct" | "deep" = "direct",
-): { content: string; evidenceList: EvidenceListMetadata | null } {
+): { content: string; evidenceList: EvidenceListMetadata } {
   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._";
+  const total = calls.metadata.totalCount ?? calls.metadata.shownCount;
 
-  lines.push(`# ${depthLabel} from \`${enclosingScope.name}\``);
-  lines.push("");
+  lines.push(`# ${depthLabel} from \`${enclosingScope.name}\``, "");
   lines.push(
-    `**${calls.length} ${depth === "deep" ? "" : "direct "}structural call${calls.length !== 1 ? "s" : ""}** from enclosing scope \`${enclosingScope.name}\` (${formatScopeRange(enclosingScope)}) in \`${relPath}\``,
+    `**${total} ${depth === "deep" ? "" : "direct "}structural call${total === 1 ? "" : "s"}** from enclosing scope \`${enclosingScope.name}\` (${formatScopeRange(enclosingScope)}) in \`${relPath}\``,
+    "",
+    depthNote,
+    "",
   );
-  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 };
+  for (const call of calls.items) lines.push(`- \`${call.name}\` (L${call.line})`);
+  const disclosure = renderEvidenceListMetadataDisclosure(calls.metadata);
+  if (disclosure) lines.push(disclosure);
+  return { content: lines.join("\n"), evidenceList: calls.metadata };
 }
 
 function formatScopeRange(scope: CalleeScope): string {