@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/analysis/target/anchored.ts

@@ -18,6 +18,10 @@ import type {
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { AnchorKind } from "../../session/target-store.ts";
 import type { AnchoredResolutionMetadata, AnchoredResolutionSource } from "../../types/index.ts";
+import {
+  createCodeSymbolIdentityResolver,
+  type DeclarationOccurrenceIdentity,
+} from "./identity.ts";
 import type { DisambiguationCandidateData, ResolvedTargetData, TargetOutcome } from "./types.ts";
 
 /** 1-based symbol anchor position (mirrors the runtime `SymbolAnchor`). */
@@ -149,7 +153,12 @@ function buildResolution(
 function resolvedFromSymbol(
   file: string,
   s: CodeSymbol,
-  opts: { snapped: boolean; requested: Anchor; source: AnchoredResolutionSource },
+  opts: {
+    snapped: boolean;
+    requested: Anchor;
+    source: AnchoredResolutionSource;
+    identity: DeclarationOccurrenceIdentity;
+  },
 ): { kind: "resolved"; target: ResolvedTargetData } {
   const a = (s.nameAnchor ?? s.declarationAnchor) as Anchor;
   return {
@@ -159,9 +168,13 @@ function resolvedFromSymbol(
       position: { line: a.line - 1, character: a.character - 1 },
       displayLine: a.line,
       displayCharacter: a.character,
+      declarationAnchor: { ...s.declarationAnchor },
+      declarationOccurrence: opts.identity.declarationOccurrence,
       name: s.name,
       kind: s.kind,
+      identityKind: opts.identity.identityKind,
       confidence: "semantic",
+      provenance: opts.identity.structuralEvidence ? ["semantic", "structural"] : ["semantic"],
       anchorKind: (s.nameAnchor ? "name" : "declaration") as AnchorKind,
       container: s.container ?? null,
       resolution: buildResolution(opts.requested, a, opts.snapped, opts.source),
@@ -169,24 +182,37 @@ function resolvedFromSymbol(
   };
 }
 
-function candidatesFromSymbols(
+async function candidatesFromSymbols(
   file: string,
   matched: CodeSymbol[],
-): { kind: "disambiguation"; candidates: DisambiguationCandidateData[]; omittedCount: number } {
-  const candidates = matched.map((s, idx) => {
-    const a = (s.nameAnchor ?? s.declarationAnchor) as Anchor;
-    return {
-      name: s.name,
-      kind: s.kind,
-      container: s.container ?? null,
-      file,
-      line: a.line,
-      character: a.character,
-      reason: `${a.line}:${a.character}`,
-      rank: idx + 1,
-      anchorKind: (s.nameAnchor ? "name" : "declaration") as AnchorKind,
-    } satisfies DisambiguationCandidateData;
-  });
+  resolveIdentity: (symbol: CodeSymbol) => Promise<DeclarationOccurrenceIdentity>,
+): Promise<{
+  kind: "disambiguation";
+  candidates: DisambiguationCandidateData[];
+  omittedCount: number;
+}> {
+  const candidates = await Promise.all(
+    matched.map(async (s, idx) => {
+      const a = (s.nameAnchor ?? s.declarationAnchor) as Anchor;
+      const identity = await resolveIdentity(s);
+      return {
+        name: s.name,
+        kind: s.kind,
+        identityKind: identity.identityKind,
+        provenance: identity.structuralEvidence
+          ? (["semantic", "structural"] as const)
+          : (["semantic"] as const),
+        container: s.container ?? null,
+        file,
+        line: a.line,
+        character: a.character,
+        declarationAnchor: { ...s.declarationAnchor },
+        declarationOccurrence: identity.declarationOccurrence,
+        rank: idx + 1,
+        anchorKind: (s.nameAnchor ? "name" : "declaration") as AnchorKind,
+      } satisfies DisambiguationCandidateData;
+    }),
+  );
   return { kind: "disambiguation", candidates, omittedCount: 0 };
 }
 
@@ -197,13 +223,14 @@ async function resolveFromSemantic(
   provider: AnchoredResolverProvider,
 ): Promise<TargetOutcome | null> {
   if (!provider.documentSymbols) return null;
-  let symbols: CodeSymbol[] | null = null;
+  let symbols: CodeSymbol[] = [];
   try {
-    symbols = await provider.documentSymbols(file);
+    const result = await provider.documentSymbols(file);
+    if (result.kind !== "unavailable") symbols = result.data;
   } catch {
-    symbols = null;
+    symbols = [];
   }
-  if (!symbols || symbols.length === 0) return null;
+  if (symbols.length === 0) return null;
 
   const exact: CodeSymbol[] = [];
   const snap: CodeSymbol[] = [];
@@ -213,14 +240,26 @@ async function resolveFromSemantic(
     else if (m === "snap") snap.push(s);
   }
 
+  const structural = provider.nodeAt ? { nodeAt: provider.nodeAt } : undefined;
+  const resolveIdentity = createCodeSymbolIdentityResolver(file, symbols, structural);
   if (exact.length === 1) {
-    return resolvedFromSymbol(file, exact[0], { snapped: false, requested, source: "semantic" });
+    return resolvedFromSymbol(file, exact[0], {
+      snapped: false,
+      requested,
+      source: "semantic",
+      identity: await resolveIdentity(exact[0]),
+    });
   }
-  if (exact.length > 1) return candidatesFromSymbols(file, exact);
+  if (exact.length > 1) return candidatesFromSymbols(file, exact, resolveIdentity);
   if (snap.length === 1) {
-    return resolvedFromSymbol(file, snap[0], { snapped: true, requested, source: "semantic" });
+    return resolvedFromSymbol(file, snap[0], {
+      snapped: true,
+      requested,
+      source: "semantic",
+      identity: await resolveIdentity(snap[0]),
+    });
   }
-  if (snap.length > 1) return candidatesFromSymbols(file, snap);
+  if (snap.length > 1) return candidatesFromSymbols(file, snap, resolveIdentity);
   return null;
 }
 
@@ -277,9 +316,15 @@ async function resolveFromStructural(
       position: { line: nameAnchor.line - 1, character: nameAnchor.character - 1 },
       displayLine: nameAnchor.line,
       displayCharacter: nameAnchor.character,
+      declarationAnchor: {
+        line: declAncestor.startLine,
+        character: declAncestor.startCharacter,
+      },
+      declarationOccurrence: 0,
       name: node.text,
       kind: kindFromDeclarationType(declAncestor.type),
       confidence: "structural",
+      provenance: ["structural"],
       anchorKind: "name",
       container: null,
       resolution: buildResolution(requested, nameAnchor, snapped, "structural-identifier"),
@@ -318,7 +363,7 @@ export async function resolveAnchoredSymbolTarget(
   if (isBinaryFile(file)) {
     return {
       kind: "error",
-      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_find\` with \`mode: "text"\` for explicit text search.`,
+      message: `File type not supported for semantic analysis: \`${file}\`. Use PI read or grep for explicit filesystem inspection when appropriate.`,
     };
   }
 
@@ -342,7 +387,7 @@ function coordinateNotOnSymbolMessage(
   const at = `${path.basename(file)}:${line}:${character}`;
   const reason = detail ? ` (on \`${detail}\`)` : "";
   return (
-    `**Error:** No symbol target resolved at \`${at}\`${reason}. ` +
+    `No symbol target resolved at \`${at}\`${reason}. ` +
     "`code_resolve` resolves real symbol targets from provider-backed evidence; " +
     "use `code_inspect` for point-level facts at this coordinate, or pass the identifier coordinate of a declaration."
   );

package/src/analysis/target/file.ts

@@ -1,22 +1,24 @@
 /**
- * File-surface target resolution — discovers actionable targets within a file
- * using injected semantic (LSP document symbols) and structural (Tree-sitter exports)
- * substrates with explicit fallback policy.
+ * File target discovery — collects every evidence-backed declaration in one
+ * file after the Target workflow has established semantic readiness.
  *
- * Policy: LSP document symbols preferred (semantic). Falls back to Tree-sitter
- * exports (structural) when LSP is unavailable or returns no results.
+ * Semantic and structural facts are merged. Semantic facts win duplicate
+ * members; structural outline facts may supplement declarations omitted by
+ * the language server.
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type {
+  DeclarationNesting,
+  DocumentCodeSymbol,
+  OutlineData,
   SemanticProvider as SemanticSubstrate,
   StructuralProvider as StructuralSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { AnchorKind } from "../../session/target-store.ts";
-import { highestConfidence } from "../helpers.ts";
-import { getCodeProvider } from "../provider.ts";
-import { normalizePath } from "../search/ripgrep.ts";
+import { normalizePath } from "../search/paths.ts";
+import { canonicalDeclarationKind, refineTypeAliasIdentity } from "./identity.ts";
 import type { ResolvedTargetData, ResolvedTargetGroupData } from "./types.ts";
 
 const BINARY_EXTENSIONS = new Set([
@@ -46,18 +48,31 @@ const BINARY_EXTENSIONS = new Set([
   ".node",
 ]);
 
-function isBinaryFile(filePath: string): boolean {
-  return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+interface DiscoveredTargetData extends ResolvedTargetData {
+  /** Provider-backed hierarchy used only for file-result presentation ranking. */
+  readonly nesting: DeclarationNesting;
 }
 
-/**
- * Resolve a file into a group of discoverable targets.
- *
- * @param file - the file path (absolute or cwd-relative)
- * @param cwd - session working directory
- * @param deps - injected substrates (both optional)
- * @returns typed group outcome or error
- */
+interface DiscoveryResult {
+  readonly available: boolean;
+  readonly targets: DiscoveredTargetData[];
+}
+
+/** Validated file-discovery input with its normalized absolute path. */
+export type FileDiscoveryValidation =
+  | { kind: "valid"; file: string }
+  | { kind: "invalid-input"; message: string };
+
+/** Validate a file selector before any semantic startup or provider call. */
+export function validateFileTargetDiscovery(file: string, cwd: string): FileDiscoveryValidation {
+  const resolvedFile = normalizePath(file, cwd);
+  const validationError = validateDiscoveryFile(resolvedFile, file);
+  return validationError
+    ? { kind: "invalid-input", message: validationError }
+    : { kind: "valid", file: resolvedFile };
+}
+
+/** Discover a Target group for one file without rendering or registering handles. */
 export async function resolveFileTargetGroup(
   file: string,
   cwd: string,
@@ -66,149 +81,294 @@ export async function resolveFileTargetGroup(
     structural?: StructuralSubstrate;
   } = {},
 ): Promise<
-  { kind: "resolved"; group: ResolvedTargetGroupData } | { kind: "error"; message: string }
+  | { kind: "resolved"; group: ResolvedTargetGroupData }
+  | { kind: "invalid-input"; message: string }
+  | { kind: "unavailable"; message: string }
 > {
-  const resolvedFile = normalizePath(file, cwd);
-
-  if (!fs.existsSync(resolvedFile)) {
-    return { kind: "error", message: `File not found: \`${file}\`` };
-  }
-
-  if (isBinaryFile(resolvedFile)) {
-    return {
-      kind: "error",
-      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_find\` with \`mode: "text"\` for explicit text search.`,
-    };
-  }
+  const validation = validateFileTargetDiscovery(file, cwd);
+  if (validation.kind === "invalid-input") return validation;
+  const resolvedFile = validation.file;
 
-  const relPath = path.relative(cwd, resolvedFile);
-
-  // Try structure-based discovery first (faster, no LSP needed)
-  const structuralTargets = await resolveViaStructral(relPath, resolvedFile, cwd, deps.structural);
-
-  // Try semantic discovery (richer), preferring it over structural
-  const semanticTargets = await resolveViaSemantic(resolvedFile, deps.semantic, structuralTargets);
-
-  const targets = semanticTargets ?? structuralTargets;
-
-  if (!targets || targets.length === 0) {
+  const [semantic, structural] = await Promise.all([
+    discoverSemantic(resolvedFile, deps.semantic, deps.structural),
+    discoverStructural(resolvedFile, deps.structural),
+  ]);
+  if (!semantic.available && !structural.available) {
+    const displayFile = path.relative(cwd, resolvedFile) || file;
     return {
-      kind: "error",
-      message:
-        `**Error:** File-level semantic exploration is not available for \`${file}\`. ` +
-        "Provide `line` and `character`, or a `symbol` for discovery.",
+      kind: "unavailable",
+      message: `Declaration discovery is unavailable for \`${displayFile}\`.`,
     };
   }
 
+  const targets = mergeDiscoveries(structural.targets, semantic.targets);
+  const unknownNestingCount = targets.filter((target) => target.nesting === "unknown").length;
+  const discoveryProvenance = [
+    ...(semantic.available ? (["semantic"] as const) : []),
+    ...(structural.available ? (["structural"] as const) : []),
+  ];
   return {
     kind: "resolved",
     group: {
       file: resolvedFile,
-      displayName: relPath,
+      displayName: path.relative(cwd, resolvedFile) || resolvedFile,
       targets,
-      confidence: highestConfidence(targets.map((t) => t.confidence)),
+      discoveryProvenance,
+      confidence: targetGroupConfidence(targets, discoveryProvenance),
+      unknownNestingCount,
     },
   };
 }
 
-// ── Resolution helpers ───────────────────────────────────────────────
+function targetGroupConfidence(
+  targets: readonly ResolvedTargetData[],
+  discoveryProvenance: ResolvedTargetGroupData["discoveryProvenance"],
+): ResolvedTargetGroupData["confidence"] {
+  if (targets.length === 0) {
+    return discoveryProvenance.includes("semantic") ? "semantic" : "structural";
+  }
+  if (targets.some((target) => target.confidence === "unavailable")) return "unavailable";
+  if (targets.some((target) => target.confidence === "heuristic")) return "heuristic";
+  if (targets.some((target) => target.confidence === "structural")) return "structural";
+  return "semantic";
+}
 
-async function resolveViaSemantic(
-  resolvedFile: string,
-  semantic?: SemanticSubstrate,
-  structuralTargets: ResolvedTargetData[] | null = null,
-): Promise<ResolvedTargetData[] | null> {
-  if (!semantic) return structuralTargets;
+function validateDiscoveryFile(resolvedFile: string, requestedFile: string): string | null {
+  if (!fs.existsSync(resolvedFile)) return `File not found: \`${requestedFile}\``;
+  try {
+    if (!fs.statSync(resolvedFile).isFile()) return `Not a file: \`${requestedFile}\``;
+  } catch {
+    return `Cannot access file: \`${requestedFile}\``;
+  }
+  if (!BINARY_EXTENSIONS.has(path.extname(resolvedFile).toLowerCase())) return null;
+  return `File type not supported for code analysis: \`${requestedFile}\`. Use PI read or grep for explicit filesystem inspection when appropriate.`;
+}
 
+async function discoverSemantic(
+  file: string,
+  semantic: SemanticSubstrate | undefined,
+  structural: StructuralSubstrate | undefined,
+): Promise<DiscoveryResult> {
+  if (!semantic) return { available: false, targets: [] };
   try {
-    const symbols = await semantic.documentSymbols(resolvedFile);
-    if (!symbols || symbols.length === 0) return structuralTargets;
-
-    const topLevel = symbols
-      .filter((s) => !s.container)
-      .map((s) => {
-        const a = s.nameAnchor ?? s.declarationAnchor;
-        return {
-          file: resolvedFile,
-          position: { line: a.line - 1, character: a.character - 1 },
-          displayLine: a.line,
-          displayCharacter: a.character,
-          name: s.name,
-          kind: s.kind,
-          confidence: "semantic" as const,
-          anchorKind: (s.nameAnchor ? "name" : "declaration") as AnchorKind,
-          container: s.container ?? null,
-        };
-      });
-
-    if (topLevel.length === 0) return structuralTargets;
-
-    // Semantic symbols are available — prefer them over structural exports.
-    // Only fall back to structural targets that have no semantic counterpart
-    // (different position).
-    if (!structuralTargets || structuralTargets.length === 0) return dedupeTargets(topLevel);
-
-    // Build a position-based dedup: for each position, prefer the semantic entry.
-    const byPos = new Map<string, ResolvedTargetData>();
-    for (const t of structuralTargets) {
-      byPos.set(`${t.position.line}:${t.position.character}`, t);
-    }
-    for (const t of topLevel) {
-      byPos.set(`${t.position.line}:${t.position.character}`, t);
-    }
-    return [...byPos.values()];
+    const result = await semantic.documentSymbols(file);
+    if (result.kind === "unavailable") return { available: false, targets: [] };
+    return {
+      available: true,
+      targets: await Promise.all(
+        result.data.map(async (symbol) => {
+          const target = targetFromSymbol(file, symbol);
+          const refined = await refineTypeAliasIdentity(target, structural);
+          return { ...refined, nesting: target.nesting };
+        }),
+      ),
+    };
   } catch {
-    return structuralTargets;
+    return { available: false, targets: [] };
   }
 }
 
-async function resolveViaStructral(
-  relPath: string,
-  resolvedFile: string,
-  cwd: string,
-  structural?: StructuralSubstrate,
-): Promise<ResolvedTargetData[] | null> {
-  // Resolve a substrate to use — prefer injected, fall back to auto-created
-  const substrate = structural ?? createFallbackSubstrate(cwd);
-  if (!substrate) return null;
+function targetFromSymbol(file: string, symbol: DocumentCodeSymbol): DiscoveredTargetData {
+  const anchor = symbol.nameAnchor ?? symbol.declarationAnchor;
+  return {
+    file,
+    position: { line: anchor.line - 1, character: anchor.character - 1 },
+    displayLine: anchor.line,
+    displayCharacter: anchor.character,
+    declarationAnchor: { ...symbol.declarationAnchor },
+    declarationOccurrence: 0,
+    name: symbol.name,
+    kind: symbol.kind,
+    confidence: "semantic",
+    provenance: ["semantic"],
+    anchorKind: (symbol.nameAnchor ? "name" : "declaration") as AnchorKind,
+    container: symbol.container ?? null,
+    nesting: normalizeNesting(symbol.nesting),
+  };
+}
+
+/** Normalize process-global or legacy provider observations at the discovery seam. */
+function normalizeNesting(value: unknown): DeclarationNesting {
+  if (value === "top-level" || value === "nested" || value === "unknown") return value;
+  return "unknown";
+}
 
+async function discoverStructural(
+  file: string,
+  structural: StructuralSubstrate | undefined,
+): Promise<DiscoveryResult> {
+  if (!structural) return { available: false, targets: [] };
   try {
-    const exportsResult = await substrate.exports(relPath);
-    if (exportsResult.kind !== "success" || exportsResult.data.length === 0) return null;
-
-    return dedupeTargets(
-      exportsResult.data.map((record) => ({
-        file: resolvedFile,
-        position: { line: record.startLine - 1, character: record.startCharacter - 1 },
-        displayLine: record.startLine,
-        displayCharacter: record.startCharacter,
-        name: record.name,
-        kind: record.kind,
-        confidence: "structural" as const,
-        // Structural exports use the node start (startLine/startCharacter) =
-        // declaration anchor; no name anchor is derivable from exports alone.
-        anchorKind: "declaration",
-        container: null,
-      })),
-    );
+    const result = await structural.outline(file);
+    if (result.kind !== "success") return { available: false, targets: [] };
+    return { available: true, targets: flattenOutline(file, result.data) };
   } catch {
-    return null;
+    return { available: false, targets: [] };
   }
 }
 
-/** Create a fallback substrate from a working directory using the unified registry. */
-function createFallbackSubstrate(dir: string): StructuralSubstrate | null {
-  const state = getCodeProvider(dir);
-  return state.kind === "ready" ? state.provider : null;
+function flattenOutline(
+  file: string,
+  items: readonly OutlineData[],
+  container: string | null = null,
+  nesting: DeclarationNesting = "top-level",
+): DiscoveredTargetData[] {
+  return items.flatMap((item) => {
+    const target: DiscoveredTargetData = {
+      file,
+      position: { line: item.startLine - 1, character: item.startCharacter - 1 },
+      displayLine: item.startLine,
+      displayCharacter: item.startCharacter,
+      declarationAnchor: { line: item.startLine, character: item.startCharacter },
+      declarationOccurrence: 0,
+      name: item.name,
+      kind: item.kind,
+      identityKind: canonicalDeclarationKind(item.kind),
+      confidence: "structural",
+      provenance: ["structural"],
+      anchorKind: "declaration",
+      container,
+      nesting,
+    };
+    return [target, ...flattenOutline(file, item.children ?? [], item.name, "nested")];
+  });
+}
+
+/**
+ * Merge duplicate provider observations without collapsing repeated declarations.
+ * Semantic facts win a matched pair while retaining both provider sources.
+ */
+function mergeDiscoveries(
+  structural: readonly DiscoveredTargetData[],
+  semantic: readonly DiscoveredTargetData[],
+): DiscoveredTargetData[] {
+  const unmatchedSemantic = new Set(semantic.map((_target, index) => index));
+  const mergedStructural = structural.flatMap((structuralTarget) => {
+    const semanticIndex = findSemanticMatch(structuralTarget, semantic, unmatchedSemantic);
+    if (semanticIndex === null) return [structuralTarget];
+    unmatchedSemantic.delete(semanticIndex);
+    const semanticTarget = semantic[semanticIndex];
+    return [
+      {
+        ...semanticTarget,
+        provenance: ["semantic", "structural"] as const,
+        container: reconcileContainer(semanticTarget, structuralTarget),
+        nesting: reconcileNesting(semanticTarget.nesting, structuralTarget.nesting),
+      },
+    ];
+  });
+  const semanticOnly = semantic.filter((_target, index) => unmatchedSemantic.has(index));
+  const sourceOrdered = [...mergedStructural, ...semanticOnly].sort(compareDeclarations);
+  const identified = assignDeclarationOccurrences(sourceOrdered);
+  return identified.sort(compareFileOrientationDeclarations);
+}
+
+/** Let provider-backed known hierarchy refine unknown without guessing through a conflict. */
+function reconcileNesting(
+  semantic: DeclarationNesting,
+  structural: DeclarationNesting,
+): DeclarationNesting {
+  if (semantic === structural) return semantic;
+  if (semantic === "unknown") return structural;
+  if (structural === "unknown") return semantic;
+  return "unknown";
 }
 
-function dedupeTargets(targets: ResolvedTargetData[]): ResolvedTargetData[] {
-  const deduped = new Map<string, ResolvedTargetData>();
-  for (const target of targets) {
-    const key = `${target.name ?? ""}:${target.displayLine}:${target.displayCharacter}`;
-    if (!deduped.has(key)) {
-      deduped.set(key, target);
-    }
+/** Preserve known container evidence while clearing explicit provider conflicts. */
+function reconcileContainer(
+  semantic: DiscoveredTargetData,
+  structural: DiscoveredTargetData,
+): string | null {
+  if (semantic.container === structural.container) return semantic.container;
+  if (semantic.nesting === "unknown" && semantic.container === null) {
+    return structural.container;
+  }
+  if (structural.nesting === "unknown" && structural.container === null) {
+    return semantic.container;
   }
-  return [...deduped.values()];
+  return null;
+}
+
+function findSemanticMatch(
+  structural: DiscoveredTargetData,
+  semantic: readonly DiscoveredTargetData[],
+  unmatched: ReadonlySet<number>,
+): number | null {
+  const matches = semantic
+    .map((target, index) => ({ target, index }))
+    .filter(({ target, index }) => unmatched.has(index) && sameDeclaration(target, structural))
+    .sort(
+      (left, right) =>
+        Math.abs(left.target.declarationAnchor.character - structural.declarationAnchor.character) -
+          Math.abs(
+            right.target.declarationAnchor.character - structural.declarationAnchor.character,
+          ) ||
+        left.target.declarationAnchor.character - right.target.declarationAnchor.character ||
+        compareDeclarations(left.target, right.target) ||
+        (left.target.container ?? "").localeCompare(right.target.container ?? "") ||
+        left.target.nesting.localeCompare(right.target.nesting) ||
+        left.index - right.index,
+    );
+  return matches[0]?.index ?? null;
+}
+
+function sameDeclaration(left: DiscoveredTargetData, right: DiscoveredTargetData): boolean {
+  return (
+    left.name === right.name &&
+    compatibleContainerEvidence(left, right) &&
+    left.declarationAnchor.line === right.declarationAnchor.line &&
+    declarationIdentityKind(left) === declarationIdentityKind(right)
+  );
+}
+
+/** Container conflicts match only when both providers report the exact declaration anchor. */
+function compatibleContainerEvidence(
+  left: DiscoveredTargetData,
+  right: DiscoveredTargetData,
+): boolean {
+  return (
+    left.container === right.container ||
+    left.declarationAnchor.character === right.declarationAnchor.character
+  );
+}
+
+function assignDeclarationOccurrences(
+  targets: readonly DiscoveredTargetData[],
+): DiscoveredTargetData[] {
+  const occurrences = new Map<string, number>();
+  return targets.map((target) => {
+    const key = [
+      target.declarationAnchor.line,
+      target.name ?? "",
+      declarationIdentityKind(target),
+      target.container ?? "",
+    ].join("\0");
+    const occurrence = occurrences.get(key) ?? 0;
+    occurrences.set(key, occurrence + 1);
+    return { ...target, declarationOccurrence: occurrence };
+  });
+}
+
+function declarationIdentityKind(target: ResolvedTargetData): string {
+  return target.identityKind ?? canonicalDeclarationKind(target.kind);
+}
+
+function compareFileOrientationDeclarations(
+  left: DiscoveredTargetData,
+  right: DiscoveredTargetData,
+): number {
+  return topLevelRank(left) - topLevelRank(right) || compareDeclarations(left, right);
+}
+
+function topLevelRank(target: DiscoveredTargetData): number {
+  return target.nesting === "top-level" ? 0 : 1;
+}
+
+function compareDeclarations(left: ResolvedTargetData, right: ResolvedTargetData): number {
+  return (
+    left.displayLine - right.displayLine ||
+    left.displayCharacter - right.displayCharacter ||
+    (left.name ?? "").localeCompare(right.name ?? "") ||
+    (left.kind ?? "").localeCompare(right.kind ?? "")
+  );
 }