@mrclrchtr/supi-code-intelligence 1.16.0 → 2.0.0

package/src/analysis/target/symbol.ts

@@ -0,0 +1,196 @@
+/**
+ * Symbol target resolution — discovers symbols via the semantic substrate
+ * and returns typed outcomes (resolved, disambiguation, or error).
+ *
+ * This resolver is semantic-only: it does not fall back to text search
+ * or heuristic guessing. Ambiguous matches produce explicit disambiguation.
+ */
+
+import * as path from "node:path";
+import type {
+  CodeSymbol,
+  SemanticProvider as SemanticSubstrate,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+import type { AnchorKind } from "../../session/target-store.ts";
+import { normalizePath } from "../search/ripgrep.ts";
+import type { DisambiguationCandidateData, TargetOutcome } from "./types.ts";
+
+const MAX_CANDIDATES = 8; // default fallback when maxResults is not provided
+const NON_EXPORTED_KINDS = new Set(["Variable", "Field", "Property"]);
+
+function normalizeContainer(container: string | null | undefined): string | null {
+  return container ?? null;
+}
+
+function isExactDocumentSymbolMatch(candidate: CodeSymbol, workspaceSymbol: CodeSymbol): boolean {
+  return (
+    candidate.name === workspaceSymbol.name &&
+    candidate.kind === workspaceSymbol.kind &&
+    normalizeContainer(candidate.container) === normalizeContainer(workspaceSymbol.container)
+  );
+}
+
+/**
+ * The preferred anchor for resolution/downstream: the name (identifier) anchor
+ * when the provider derived it, else the declaration anchor. Strict consumers
+ * (tree-sitter `calleesAt`, LSP `rename`) prefer the name anchor; tolerant
+ * consumers (`references`, `implementation`, `definition`) accept either.
+ * Per ADR 0003. When `nameAnchor` is absent, strict consumers that consume
+ * this anchor should hard-fail observably (slice D) rather than silently use
+ * the declaration — handled at the consumer boundary, not here.
+ */
+function anchorOf(s: CodeSymbol): CodeSymbol["declarationAnchor"] {
+  return s.nameAnchor ?? s.declarationAnchor;
+}
+
+/**
+ * Prefer a document-symbol anchor when it provides one unambiguous exact match
+ * for the already-selected workspace symbol.
+ */
+async function refineResolvedSymbolAnchor(
+  workspaceSymbol: CodeSymbol,
+  semantic: SemanticSubstrate,
+): Promise<CodeSymbol> {
+  try {
+    const documentSymbols = await semantic.documentSymbols(workspaceSymbol.file);
+    if (!documentSymbols || documentSymbols.length === 0) {
+      return workspaceSymbol;
+    }
+
+    const exactMatches = documentSymbols.filter((candidate) =>
+      isExactDocumentSymbolMatch(candidate, workspaceSymbol),
+    );
+    if (exactMatches.length !== 1) {
+      return workspaceSymbol;
+    }
+
+    const refined = exactMatches[0];
+    const a = anchorOf(refined);
+    if (a.line <= 0 && a.character <= 0) {
+      return workspaceSymbol;
+    }
+
+    return refined;
+  } catch {
+    return workspaceSymbol;
+  }
+}
+
+/**
+ * Resolve a symbol via the semantic substrate.
+ *
+ * @param symbol - the symbol name to search for
+ * @param cwd - session working directory
+ * @param semantic - the semantic substrate (LSP-backed)
+ * @param options - optional filters: path scope, kind filter, exported-only
+ * @returns Typed outcome: resolved, disambiguation, or error
+ */
+export async function resolveSymbolTarget(
+  symbol: string,
+  cwd: string,
+  semantic: SemanticSubstrate,
+  options?: {
+    path?: string;
+    kind?: string;
+    exportedOnly?: boolean;
+    maxResults?: number;
+  },
+): Promise<TargetOutcome> {
+  const results = await semantic.workspaceSymbols(symbol);
+  if (results === null) {
+    return {
+      kind: "error",
+      message: `Symbol discovery for \`${symbol}\` requires active LSP. Use \`file\` + coordinates, or enable LSP and retry.`,
+    };
+  }
+  if (results.length === 0) {
+    return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
+  }
+
+  // Filter by path scope. Tool paths may include pi's leading `@` prefix;
+  // normalize through the shared path helper so every caller gets the same
+  // scope semantics.
+  const scopePath = options?.path ? normalizePath(options.path, cwd) : null;
+  let candidates = results.filter((s) => {
+    if (scopePath && !isWithinOrEqual(scopePath, s.file)) return false;
+    return true;
+  });
+
+  // Filter by kind
+  if (options?.kind) {
+    const kindLower = options.kind.toLowerCase();
+    candidates = candidates.filter((s) => s.kind.toLowerCase().includes(kindLower));
+  }
+
+  // Filter to exported symbols only
+  if (options?.exportedOnly) {
+    candidates = candidates.filter((s) => !NON_EXPORTED_KINDS.has(s.kind));
+  }
+
+  // Range-less candidates (line=0,char=0) come from URI-only workspace symbols.
+  // Keep them for disambiguation but don't promote to single-match resolution.
+  const ranged = candidates.filter(
+    (s) => s.declarationAnchor.line > 0 || s.declarationAnchor.character > 0,
+  );
+
+  if (ranged.length === 1) {
+    const c = await refineResolvedSymbolAnchor(ranged[0], semantic);
+    const a = anchorOf(c);
+    return {
+      kind: "resolved",
+      target: {
+        file: c.file,
+        position: { line: a.line - 1, character: a.character - 1 },
+        displayLine: a.line,
+        displayCharacter: a.character,
+        name: c.name,
+        kind: c.kind,
+        confidence: "semantic",
+        anchorKind: (c.nameAnchor ? "name" : "declaration") as AnchorKind,
+        container: c.container ?? null,
+      },
+    };
+  }
+
+  // All candidates lost or only rangeless
+  if (candidates.length === 0) {
+    return {
+      kind: "error",
+      message: `Symbol not found: \`${symbol}\`${scopePath ? ` in path \`${options?.path}\`` : ""}`,
+    };
+  }
+
+  // Multiple candidates — refine each to a name (identifier) anchor before
+  // returning disambiguation, so position-strict downstream substrates
+  // (tree-sitter calleesAt, LSP rename) receive the identifier anchor rather
+  // than the declaration anchor (the `export` keyword) that workspace-symbol
+  // hits carry. Mirrors the single-match refine path above.
+  // Per ADR 0003, `anchorOf` prefers the refined doc symbol's `nameAnchor`.
+  // TODO: batch the per-file documentSymbols dedupe across candidates.
+  const cap = options?.maxResults ?? MAX_CANDIDATES;
+  const refined = await Promise.all(
+    candidates.slice(0, cap).map((c) => refineResolvedSymbolAnchor(c, semantic)),
+  );
+  const candidatesOut = refined.map((c, idx) => {
+    const relFile = path.relative(cwd, c.file);
+    const a = anchorOf(c);
+    return {
+      name: c.name,
+      kind: c.kind,
+      container: c.container ?? null,
+      file: relFile,
+      line: a.line,
+      character: a.character,
+      reason: relFile,
+      rank: idx + 1,
+      anchorKind: (c.nameAnchor ? "name" : "declaration") as AnchorKind,
+    };
+  }) satisfies DisambiguationCandidateData[];
+
+  return {
+    kind: "disambiguation",
+    candidates: candidatesOut,
+    omittedCount: Math.max(0, candidates.length - cap),
+  };
+}

package/src/{targeting → analysis/target}/types.ts

@@ -6,7 +6,11 @@
  * and keep action-facing code focused on routing, not string building.
  */
 
-import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
+import type {
+  SemanticProvider as SemanticSubstrate,
+  StructuralProvider as StructuralSubstrate,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { AnchorKind } from "../../session/target-store.ts";
 
 // ── Normalized query ──────────────────────────────────────────────────
 
@@ -68,6 +72,16 @@ export interface ResolvedTargetData {
   name: string | null;
   kind: string | null;
   confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+  /** Which anchor this target carries — drives strict-consumer enforcement (ADR 0003). */
+  anchorKind: AnchorKind;
+  /** Symbolic container (class/namespace/module name), or null for top-level. */
+  container: string | null;
+  /**
+   * Resolution provenance — present when the target was resolved from
+   * anchored coordinates. Carries requested/resolved coordinates, whether the
+   * anchor was snapped, and the provider-backed evidence source.
+   */
+  resolution?: import("../../types/index.ts").AnchoredResolutionMetadata;
 }
 
 /**
@@ -92,6 +106,8 @@ export interface DisambiguationCandidateData {
   character: number;
   reason: string;
   rank: number;
+  /** Which anchor this candidate carries (ADR 0003). */
+  anchorKind: AnchorKind;
 }
 
 /**

package/src/analysis/tests/likely-tests.ts

@@ -0,0 +1,174 @@
+/**
+ * Likely test file discovery for impact analysis.
+ *
+ * Extracted from orchestrate.ts to keep impact orchestration focused.
+ * Combines direct test-file detection, semantic reference-based discovery,
+ * and path conventions to find companion test files for affected source files.
+ */
+
+import * as path from "node:path";
+import type { CodePosition } from "@mrclrchtr/supi-code-runtime/api";
+import type { CodeProvider } from "../provider.ts";
+import {
+  type DiscoveredTestFile,
+  describeTestFile,
+  discoverTestFilesForSource,
+  isTestFilePath,
+} from "./test-discovery.ts";
+
+export interface ChangeSetFileEntry {
+  absPath: string;
+  relPath: string;
+}
+
+export type TestAnchorMap = Map<string, CodePosition[]>;
+
+export interface LikelyTestsResult {
+  paths: string[];
+  files: Array<Pick<DiscoveredTestFile, "absPath" | "testNames" | "labelStatus">>;
+  provenance?: "semantic+conventions" | "conventions-only";
+}
+
+export function buildTestAnchorMap(
+  entries: Array<{ file: string; position: CodePosition }>,
+): TestAnchorMap {
+  const map: TestAnchorMap = new Map();
+  for (const entry of entries) {
+    const key = path.resolve(entry.file);
+    const positions = map.get(key) ?? [];
+    positions.push(entry.position);
+    map.set(key, positions);
+  }
+  return map;
+}
+
+export function normalizeChangeSet(files: string[], cwd: string): ChangeSetFileEntry[] {
+  const seen = new Set<string>();
+  const result: ChangeSetFileEntry[] = [];
+
+  for (const file of files) {
+    const absPath = path.resolve(cwd, file);
+    const relPath = path.relative(cwd, absPath) || file;
+    if (seen.has(absPath)) continue;
+    seen.add(absPath);
+    result.push({ absPath, relPath });
+  }
+
+  return result;
+}
+
+function dedupeDiscoveredTestFiles(
+  files: Array<Pick<DiscoveredTestFile, "absPath" | "testNames" | "labelStatus">>,
+): Array<Pick<DiscoveredTestFile, "absPath" | "testNames" | "labelStatus">> {
+  const byPath = new Map<
+    string,
+    Pick<DiscoveredTestFile, "absPath" | "testNames" | "labelStatus">
+  >();
+
+  for (const file of files) {
+    const existing = byPath.get(file.absPath);
+    if (!existing) {
+      byPath.set(file.absPath, file);
+      continue;
+    }
+
+    if (existing.labelStatus !== "recognized" && file.labelStatus === "recognized") {
+      byPath.set(file.absPath, file);
+    }
+  }
+
+  return [...byPath.values()].sort((left, right) => left.absPath.localeCompare(right.absPath));
+}
+
+// biome-ignore lint/complexity/useMaxParams: shared likely-test collection keeps evidence inputs explicit
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: discovery aggregation across direct tests, semantic references, and conventions is clearest in one helper
+export async function collectLikelyTests(
+  affectedFiles: Set<string>,
+  cwd: string,
+  references: CodeProvider["references"] | undefined,
+  testAnchors?: TestAnchorMap,
+  fallbackProvenance?: "semantic+conventions" | "conventions-only",
+  outline?: CodeProvider["outline"],
+): Promise<LikelyTestsResult> {
+  const seen = new Set<string>();
+  const likelyTests: string[] = [];
+  const discoveredFiles: Array<Pick<DiscoveredTestFile, "absPath" | "testNames" | "labelStatus">> =
+    [];
+  let provenance = fallbackProvenance;
+
+  for (const affFile of affectedFiles) {
+    if (isTestFilePath(affFile)) {
+      addLikelyTestPath(cwd, affFile, seen, likelyTests);
+      const described = await describeTestFile(affFile, { outline, cwd });
+      discoveredFiles.push(described);
+      continue;
+    }
+
+    const positions = testAnchors?.get(path.resolve(affFile)) ?? [];
+    const discoveries =
+      positions.length > 0
+        ? await Promise.all(
+            positions.map((position) =>
+              discoverTestFilesForSource(affFile, {
+                cwd,
+                cap: 3,
+                references,
+                outline,
+                position,
+              }),
+            ),
+          )
+        : [
+            await discoverTestFilesForSource(affFile, {
+              cwd,
+              cap: 3,
+              references,
+              outline,
+            }),
+          ];
+
+    for (const discovery of discoveries) {
+      if (discovery.kind !== "found") continue;
+      if (discovery.provenance === "semantic+conventions") {
+        provenance = "semantic+conventions";
+      } else if (!provenance) {
+        provenance = discovery.provenance;
+      }
+    }
+
+    const discovered = dedupeDiscoveredTestFiles(discoveries.flatMap((entry) => entry.files));
+    for (const testFile of discovered) {
+      addLikelyTestPath(cwd, testFile.absPath, seen, likelyTests);
+      discoveredFiles.push(testFile);
+    }
+  }
+
+  const files = dedupeDiscoveredTestFiles(discoveredFiles).slice(0, 3);
+  likelyTests.sort((a, b) => a.localeCompare(b));
+  return { paths: likelyTests.slice(0, 3), files, provenance };
+}
+
+function addLikelyTestPath(
+  cwd: string,
+  absPath: string,
+  seen: Set<string>,
+  likelyTests: string[],
+): void {
+  const relPath = path.relative(cwd, absPath) || absPath;
+  if (seen.has(relPath)) return;
+  seen.add(relPath);
+  likelyTests.push(relPath);
+}
+
+import { detectVitestWorkspace, VITEST_RUNNABLE_EXTENSIONS } from "./vitest.ts";
+
+export function buildLikelyTestCommands(cwd: string, likelyTests: string[]): string[] {
+  if (likelyTests.length === 0 || !detectVitestWorkspace(cwd)) {
+    return [];
+  }
+
+  return likelyTests
+    .filter((testPath) => VITEST_RUNNABLE_EXTENSIONS.has(path.extname(testPath)))
+    .slice(0, 3)
+    .map((relTest) => `pnpm vitest run ${relTest} --reporter=verbose`);
+}