@mrclrchtr/supi-code-intelligence 6.4.0 → 7.0.0

package/src/session/orientation-types.ts

@@ -5,6 +5,7 @@ import type { EvidenceListMetadata } from "../analysis/evidence.ts";
 import type { InstructionFilesMetadata } from "../analysis/instruction-files.ts";
 import type { CodeProvider } from "../analysis/provider.ts";
 import type { ReadNextItem } from "../analysis/read-next.ts";
+import type { TargetCandidateCompleteness } from "../analysis/target/types.ts";
 import type { OrientationTargetInput, TargetSymbolKind } from "./target-input.ts";
 import type { AnchorKind, TargetStoreEntry } from "./target-store.ts";
 
@@ -118,16 +119,14 @@ export interface OrientationResultData {
 
 export type OrientationWorkflowOutcome =
   | { readonly kind: "completed"; readonly data: OrientationResultData }
-  | {
+  | ({
       readonly kind: "disambiguation";
       readonly candidates: readonly OrientationCandidate[];
-      readonly omittedCount: number;
-    }
-  | {
+    } & TargetCandidateCompleteness)
+  | ({
       readonly kind: "kind-mismatch";
       readonly requestedKind: TargetSymbolKind;
       readonly candidates: readonly OrientationCandidate[];
-      readonly omittedCount: number;
-    }
+    } & TargetCandidateCompleteness)
   | { readonly kind: "invalid-input"; readonly message: string }
   | { readonly kind: "unavailable"; readonly reason: string };

package/src/session/orientation-workflow.ts

@@ -131,10 +131,18 @@ async function orientTarget(options: {
       ? {
           kind: "kind-mismatch",
           requestedKind: target.requestedKind,
-          omittedCount: target.omittedCount,
           candidates,
+          totalCount: target.totalCount,
+          omittedCount: target.omittedCount,
+          partialReason: target.partialReason,
         }
-      : { kind: "disambiguation", omittedCount: target.omittedCount, candidates };
+      : {
+          kind: "disambiguation",
+          candidates,
+          totalCount: target.totalCount,
+          omittedCount: target.omittedCount,
+          partialReason: target.partialReason,
+        };
   }
   if (target.kind !== "resolved") return target;
   throwIfAborted(control);

package/src/session/target-workflow.ts

@@ -19,6 +19,7 @@ import { resolveSymbolTarget } from "../analysis/target/symbol.ts";
 import type {
   ResolvedTargetData,
   ResolvedTargetGroupData,
+  TargetCandidateCompleteness,
   TargetOutcome,
 } from "../analysis/target/types.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
@@ -59,17 +60,15 @@ export type TargetWorkflowOutcome =
       omittedCount: number;
       unknownNestingCount: number;
     }
-  | {
+  | ({
       kind: "disambiguation";
       candidates: ReadonlyArray<TargetWorkflowCandidate>;
-      omittedCount: number;
-    }
-  | {
+    } & TargetCandidateCompleteness)
+  | ({
       kind: "kind-mismatch";
       requestedKind: TargetSymbolKind;
       candidates: ReadonlyArray<TargetWorkflowCandidate>;
-      omittedCount: number;
-    }
+    } & TargetCandidateCompleteness)
   | { kind: "invalid-input"; message: string }
   | { kind: "unavailable"; reason: string };
 
@@ -318,12 +317,16 @@ function toWorkflowOutcome(
         kind: "kind-mismatch",
         requestedKind: outcome.requestedKind,
         candidates,
+        totalCount: outcome.totalCount,
         omittedCount: outcome.omittedCount,
+        partialReason: outcome.partialReason,
       }
     : {
         kind: "disambiguation",
         candidates,
+        totalCount: outcome.totalCount,
         omittedCount: outcome.omittedCount,
+        partialReason: outcome.partialReason,
       };
 }
 

package/src/substrate/lsp/source-tracking.ts

@@ -26,7 +26,12 @@ export interface SourceTrackingReport {
   readonly observedFileCount: number;
   readonly discovered: readonly string[];
   readonly tracked: readonly string[];
-  readonly unsupported: readonly string[];
+  /**
+   * Candidates skipped by automatic policy or tracking preconditions. This can
+   * include policy exclusions, unsupported automatic routes, and paths that
+   * are no longer regular; it is not a server capability result.
+   */
+  readonly skipped: readonly string[];
   readonly unavailable: readonly string[];
   readonly deferred: number;
 }
@@ -68,7 +73,7 @@ export async function trackCreatedSources(options: {
         inventory,
         discovered: [],
         tracked: [],
-        unsupported: [],
+        skipped: [],
         unavailable: [],
         deferred: options.state.createdSourceQueue,
         control: options.control,
@@ -103,7 +108,7 @@ export async function trackCreatedSources(options: {
   };
 
   const tracked = pathsForOutcome(batch.outcomes, "tracked");
-  const unsupported = pathsForOutcome(batch.outcomes, "unsupported");
+  const skipped = pathsForOutcome(batch.outcomes, "skipped");
   const unavailable = pathsForOutcome(batch.outcomes, "unavailable");
   return {
     state: nextState,
@@ -112,7 +117,7 @@ export async function trackCreatedSources(options: {
       inventory,
       discovered,
       tracked,
-      unsupported,
+      skipped,
       unavailable,
       deferred: nextQueue,
       control: options.control,
@@ -188,7 +193,7 @@ function createReport(options: {
   inventory: WorkspaceSourceInventory;
   discovered: readonly string[];
   tracked: readonly string[];
-  unsupported: readonly string[];
+  skipped: readonly string[];
   unavailable: readonly string[];
   deferred: readonly string[];
   control?: CodeRequestControl;
@@ -199,7 +204,7 @@ function createReport(options: {
     observedFileCount: options.inventory.observedFileCount,
     discovered: displayPaths(options.cwd, options.discovered, options.control),
     tracked: displayPaths(options.cwd, options.tracked, options.control),
-    unsupported: displayPaths(options.cwd, options.unsupported, options.control),
+    skipped: displayPaths(options.cwd, options.skipped, options.control),
     unavailable: displayPaths(options.cwd, options.unavailable, options.control),
     deferred: options.deferred.length,
   };

package/src/tool/code_find/guidance.ts

@@ -1,8 +1,8 @@
 export const toolDescription =
-  "Search code structure or workspace symbols for structural or semantic matches. It never silently falls back to another mode or to text search.";
+  "Search workspace symbols in semantic mode, or declaration, import, export, and call names in AST mode. Use PI grep for literal or regular-expression file-content search. The selected mode does not switch to another search method.";
 
 export const promptSnippet = "search code structure or workspace symbols";
 
 export const promptGuidelines = [
-  "Use code_find for structural or semantic search, grep for text search, and code_graph for symbol relationships.",
+  "Use code_find for broad code-aware discovery, code_resolve for target identity, and code_graph for relationships.",
 ];

package/src/tool/code_find/spec.ts

@@ -1,7 +1,7 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import type { CodeIntelToolExecCtx } from "../../types/index.ts";
-import { FindScopeParam, MaxResultsParam, QueryParam } from "../schemas.ts";
+import { FindQueryParam, FindScopeParam, MaxResultsParam } from "../schemas.ts";
 import { CODE_FIND_AST_KINDS } from "./ast-kinds.ts";
 import { executeFindTool } from "./execute.ts";
 import { CODE_FIND_MODES } from "./modes.ts";
@@ -16,14 +16,15 @@ export const codeFindSpec = {
   label: CODE_FIND_TOOL_LABEL,
   parameters: Type.Object(
     {
-      query: QueryParam,
+      query: FindQueryParam,
       scope: Type.Optional(FindScopeParam),
       mode: StringEnum(CODE_FIND_MODES, {
-        description: 'Required code-aware search mode. mode:"ast" requires `kind`.',
+        description:
+          "Required code-aware search mode. AST mode requires `kind`; semantic mode rejects `kind`.",
       }),
       kind: Type.Optional(
         StringEnum(CODE_FIND_AST_KINDS, {
-          description: 'AST kind for mode:"ast".',
+          description: 'AST structure kind; required only for mode:"ast".',
         }),
       ),
       maxResults: Type.Optional(MaxResultsParam),

package/src/tool/code_find/tui.ts

@@ -37,5 +37,11 @@ export function renderFindResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Searching…", context);
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Searching…", failure: "code_find failed" },
+    context,
+  );
 }

package/src/tool/code_graph/details.ts

@@ -0,0 +1,32 @@
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { ReadNextItem } from "../../analysis/read-next.ts";
+import type { CalleeScope } from "../../analysis/relations/types.ts";
+import type { GraphRelationKind } from "../../session/graph-types.ts";
+
+/** File heading for the next count rows in the relation's bounded display section. */
+export interface GraphFileGroup {
+  file: string;
+  count: number;
+}
+
+/** Relation status and context kept for the human transcript. Counts live in evidenceLists. */
+export interface GraphSectionDetails {
+  rel: GraphRelationKind;
+  source: "semantic" | "structural";
+  status: "complete" | "partial" | "unavailable";
+  message: string | null;
+  externalCount: number;
+  enclosingScope: CalleeScope | null;
+  depth: "direct" | "deep" | null;
+  /** Absent in older results whose display rows already contain full paths. */
+  fileGroups?: GraphFileGroup[];
+}
+
+/** Persisted graph facts. The TUI does not read or parse agent Markdown. */
+export interface GraphDetails {
+  targetName: string;
+  targetFile: string;
+  sections: GraphSectionDetails[];
+  evidenceLists: EvidenceListMetadata[];
+  readNext: ReadNextItem[];
+}

package/src/tool/code_graph/display.ts

@@ -0,0 +1,54 @@
+import type { CallEntry, ReferenceEntry } from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
+import { createToolDisplaySection } from "../result/display.ts";
+import type { ToolDisplaySection } from "../result/types.ts";
+import type { GraphFileGroup } from "./details.ts";
+import { compactGraphLabel } from "./format.ts";
+import type { AssembledGraphSection } from "./result.ts";
+
+/** Bound sites before grouping them. Each file group partitions the display rows. */
+export function graphDisplaySection(
+  section: AssembledGraphSection,
+  cwd: string,
+): {
+  display: ToolDisplaySection;
+  fileGroups: GraphFileGroup[];
+} {
+  if (section.kind === "unavailable") {
+    return {
+      display: createToolDisplaySection({
+        key: `graph.${section.rel}`,
+        title: section.rel,
+        items: [],
+        format: () => "",
+      }),
+      fileGroups: [],
+    };
+  }
+  const items = section.evidence.items as readonly (CallEntry | ReferenceEntry)[];
+  const display = createToolDisplaySection({
+    key: `graph.${section.rel}`,
+    title: section.rel,
+    items,
+    totalCount: section.evidence.metadata.totalCount,
+    omittedCount: section.evidence.metadata.omittedCount,
+    partialReason: section.evidence.metadata.partialReason,
+    format: (item) => {
+      const site = `L${item.line}:${item.character}`;
+      if (section.rel !== "callees") return site;
+      const call = item as CallEntry;
+      return `${site} — ${compactGraphLabel(call.displayName ?? call.name)}`;
+    },
+  });
+  const groups = new Map<string, string[]>();
+  for (let index = 0; index < display.shownCount; index++) {
+    const file = toDisplayPath(cwd, items[index].file);
+    const rows = groups.get(file) ?? [];
+    rows.push(display.lines[index]);
+    groups.set(file, rows);
+  }
+  return {
+    display: { ...display, lines: [...groups.values()].flat() },
+    fileGroups: [...groups].map(([file, rows]) => ({ file, count: rows.length })),
+  };
+}

package/src/tool/code_graph/format.ts

@@ -0,0 +1,60 @@
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+
+/** Format graph counts and all known limits in one place. */
+export function formatGraphEvidence(
+  metadata: Omit<EvidenceListMetadata, "partialReason"> & { partialReason: string | null },
+  noun: "locations" | "call sites" | "candidates",
+  externalCount = 0,
+): string {
+  const { shownCount, totalCount, omittedCount, partialReason, invalidLocationCount } = metadata;
+  const count = totalCount ?? shownCount;
+  const label = count === 1 ? singularGraphNoun(noun) : noun;
+  let text =
+    totalCount === null
+      ? `${shownCount} ${label} shown${omittedCount ? `; ${omittedCount} collected omitted` : ""}; more may exist — ${partialReason}`
+      : omittedCount
+        ? `${shownCount} of ${totalCount} ${label} shown; ${omittedCount} omitted`
+        : `${totalCount} ${label}`;
+  if (externalCount > 0)
+    text += `; ${externalCount} external location${externalCount === 1 ? "" : "s"}`;
+  if (invalidLocationCount) {
+    const invalidNoun = invalidLocationCount === 1 ? "location" : "locations";
+    text += `; ${invalidLocationCount} invalid provider ${invalidNoun} omitted (invalid-provider-location)`;
+  }
+  return text;
+}
+
+function singularGraphNoun(noun: "locations" | "call sites" | "candidates"): string {
+  switch (noun) {
+    case "locations":
+      return "location";
+    case "call sites":
+      return "call site";
+    case "candidates":
+      return "candidate";
+  }
+}
+
+/** Format a 1-based source-line range for either graph presentation. */
+export function formatGraphRange(scope: { startLine: number; endLine: number }): string {
+  return scope.startLine === scope.endLine
+    ? `L${scope.startLine}`
+    : `L${scope.startLine}–L${scope.endLine}`;
+}
+
+/** Bound a source label while keeping both ends of a chained expression. */
+export function compactGraphLabel(value: string, limit = 100): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  if (text.length <= limit) return text;
+  const tail = Math.floor(limit / 3);
+  return `${text.slice(0, limit - tail - 1)}…${text.slice(-tail)}`;
+}
+
+/** Quote source text that can contain Markdown backticks. */
+export function graphCodeSpan(text: string): string {
+  const runs = text.match(/`+/g) ?? [];
+  const delimiter = "`".repeat(Math.max(0, ...runs.map((run) => run.length)) + 1);
+  return text.startsWith("`") || text.endsWith("`")
+    ? `${delimiter} ${text} ${delimiter}`
+    : `${delimiter}${text}${delimiter}`;
+}

package/src/tool/code_graph/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Find symbol references and implementations, and list calls from a target's enclosing scope. Callee results match source shape, not symbol identity.";
+  "Find semantic references and implementations, or non-symbol-aware structural calls written inside a target's enclosing scope.";
 
 export const promptSnippet = "trace code relationships";
 

package/src/tool/code_graph/markdown.ts

@@ -1,222 +1,100 @@
 /** Markdown adapter for assembled code_graph evidence. */
 
-import {
-  type EvidenceList,
-  type EvidenceListMetadata,
-  renderEvidenceListMetadataDisclosure,
-} from "../../analysis/evidence.ts";
 import { renderReadNextSection } from "../../analysis/read-next.ts";
-import {
-  compactLineRanges,
-  formatAssembledReferenceList,
-} from "../../analysis/references/semantic-refs.ts";
-import type {
-  CallEntry,
-  CalleeScope,
-  ImplementationEntry,
-  ReferenceEntry,
-} from "../../analysis/relations/types.ts";
+import type { CallEntry, CalleeScope } from "../../analysis/relations/types.ts";
 import { toDisplayPath } from "../../analysis/search/paths.ts";
-import type { GraphResultAssembly } from "./result.ts";
-
-/** Render an assembled graph result. */
+import { assembledReadNext } from "../result/assembly.ts";
+import {
+  compactGraphLabel,
+  formatGraphEvidence,
+  formatGraphRange,
+  graphCodeSpan,
+} from "./format.ts";
+import type { AssembledGraphSection, GraphResultAssembly } from "./result.ts";
+
+/** Render one target and one summary per requested relation. */
 export function renderGraphResult(assembly: GraphResultAssembly): string {
   const lines = [
-    `# Graph of \`${assembly.displayName}\``,
-    "",
-    `_File: \`${assembly.resolvedDisplayFile}\`_`,
+    `Target: ${graphCodeSpan(assembly.displayName)} — ${graphCodeSpan(assembly.resolvedDisplayFile)}`,
     "",
   ];
-
-  const available = assembly.sections.filter((section) => section.kind === "ok");
-  if (available.length > 0) {
-    lines.push(
-      available
-        .map(
-          (section) =>
-            `**${section.rel}**: ${sectionCount(section)} result${sectionCount(section) === 1 ? "" : "s"}`,
-        )
-        .join(" | "),
-      "",
-    );
-  }
-
-  const unavailable = assembly.sections.filter((section) => section.kind === "unavailable");
-  if (unavailable.length > 0) {
-    lines.push(
-      `_Unavailable: ${unavailable.map((section) => `\`${section.rel}\``).join(", ")}_`,
-      "",
-    );
-  }
-
-  for (const section of assembly.sections) {
-    if (section.kind === "unavailable") {
-      lines.push(`**${section.rel}**: ${section.message}`, "");
-      continue;
-    }
-
-    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)));
+  for (const section of assembly.sections) lines.push(...renderSection(section, assembly), "");
+  lines.push(...renderReadNextSection(assembledReadNext(assembly.assembled)));
   return lines.join("\n");
 }
 
-function sectionCount(
-  section: Extract<GraphResultAssembly["sections"][number], { kind: "ok" }>,
-): number {
-  return section.evidence.metadata.totalCount ?? section.evidence.metadata.shownCount;
-}
-
-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 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 };
-}
-
-function renderCallsResult(
-  enclosingScope: CalleeScope,
-  calls: EvidenceList<CallEntry>,
-  relPath: string,
-  depth: "direct" | "deep" = "direct",
-): { 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}\``, "");
+function renderSection(section: AssembledGraphSection, assembly: GraphResultAssembly): string[] {
+  const source = section.rel === "callees" ? "structural" : "semantic";
+  const depth = section.kind === "ok" && section.rel === "callees" ? `, ${section.data.depth}` : "";
+  const lines = [`## ${section.rel} (${source}${depth})`];
+  if (section.kind === "unavailable") return [...lines, `Unavailable — ${section.message}`];
   lines.push(
-    `**${total} ${depth === "deep" ? "" : "direct "}structural call${total === 1 ? "" : "s"}** from enclosing scope \`${enclosingScope.name}\` (${formatScopeRange(enclosingScope)}) in \`${relPath}\``,
-    "",
-    depthNote,
+    formatGraphEvidence(
+      section.evidence.metadata,
+      section.rel === "callees" ? "call sites" : "locations",
+      section.rel === "callees" ? 0 : section.data.externalCount,
+    ),
     "",
   );
-
-  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 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)",
+  if (section.rel !== "callees") return [...lines, ...formatLocations(section, assembly.cwd)];
+  return [
+    ...lines,
+    formatScope(section.data.enclosingScope, assembly.displayName),
+    section.data.depth === "direct"
+      ? "Nested scopes excluded; calls are source expressions, not resolved symbols."
+      : "Nested scopes included; calls are source expressions, not resolved symbols.",
     "",
+    ...formatCalls(section.evidence.items, assembly),
   ];
-  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 (options.externalCount > 0) {
-    lines.push(
-      `_+${options.externalCount} external location${options.externalCount === 1 ? "" : "s"} (outside this project)_`,
-      "",
-    );
-  }
-  const invalidDisclosure = renderInvalidProviderLocations(options.implementations.metadata);
-  if (invalidDisclosure) lines.push(invalidDisclosure, "");
-
-  return { content: lines.join("\n"), evidenceList: options.implementations.metadata };
 }
 
-function formatScopeRange(scope: CalleeScope): string {
-  if (scope.startLine === scope.endLine) return `L${scope.startLine}`;
-  return `L${scope.startLine}–L${scope.endLine}`;
+function formatScope(scope: CalleeScope, targetName: string): string {
+  const name = scope.name === targetName ? "" : `${graphCodeSpan(scope.name)} — `;
+  return `Scope: ${name}${formatGraphRange(scope)}`;
 }
 
-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);
-    const group = byFile.get(displayPath) ?? [];
-    group.push(impl.line);
-    byFile.set(displayPath, group);
+function formatLocations(
+  section: Extract<AssembledGraphSection, { kind: "ok"; rel: "references" | "implements" }>,
+  cwd: string,
+): string[] {
+  const groups = new Map<string, string[]>();
+  for (const location of section.evidence.items) {
+    const file = toDisplayPath(cwd, location.file);
+    const sites = groups.get(file) ?? [];
+    sites.push(`L${location.line}:${location.character}`);
+    groups.set(file, sites);
   }
-  return byFile;
+  return [...groups].map(([file, sites]) => `- ${graphCodeSpan(file)}: ${sites.join(", ")}`);
 }
 
-/** Render an explicit disclosure for unusable semantic-provider locations. */
-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})_`;
+/** Group by the full expression, never by a shortened display label. */
+function formatCalls(calls: readonly CallEntry[], assembly: GraphResultAssembly): string[] {
+  const groups = new Map<string, { name: string; file: string; sites: string[] }>();
+  for (const call of calls) {
+    const file = toDisplayPath(assembly.cwd, call.file);
+    const key = JSON.stringify([file, call.name]);
+    const group = groups.get(key) ?? { name: call.displayName ?? call.name, file, sites: [] };
+    group.sites.push(`L${call.line}:${call.character}`);
+    groups.set(key, group);
+  }
+  const previews = [...groups.values()].map((group) => ({
+    ...group,
+    label: compactGraphLabel(group.name),
+  }));
+  const collisions = new Map<string, { count: number; seen: number }>();
+  for (const { file, label } of previews) {
+    const key = JSON.stringify([file, label]);
+    const count = (collisions.get(key)?.count ?? 0) + 1;
+    collisions.set(key, { count, seen: 0 });
+  }
+  return previews.map(({ label, file, sites }) => {
+    const collision = collisions.get(JSON.stringify([file, label]));
+    let qualifier = "";
+    if (collision && collision.count > 1) {
+      collision.seen++;
+      qualifier = ` (expression ${collision.seen}/${collision.count})`;
+    }
+    const prefix = file === assembly.resolvedDisplayFile ? "" : `${graphCodeSpan(file)}: `;
+    return `- ${graphCodeSpan(label)}${qualifier} — ${prefix}${sites.join(", ")}`;
+  });
 }