@mrclrchtr/supi-code-intelligence 1.7.0 → 1.8.0

package/src/target-resolution.ts

@@ -1,17 +1,20 @@
-// Target resolution — resolve symbol references to concrete file positions
-// for semantic actions (callers, callees, implementations, affected).
-// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: anchored, symbol, and file-surface target resolution intentionally live together to share resolution helpers
+/**
+ * Target resolution — facade that delegates to the structured targeting pipeline
+ * while preserving backward-compatible types and exports for existing consumers.
+ *
+ * New code should import from `./targeting/` directly.
+ */
 
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
-import { type Position, type SessionLspService, toLspPosition } from "@mrclrchtr/supi-lsp/api";
-import { getSemanticService, getSemanticServiceState } from "./providers/semantic-provider.ts";
-import { withStructuralSession } from "./providers/structural-provider.ts";
+import { type Position, toLspPosition } from "@mrclrchtr/supi-lsp/api";
 import { normalizePath } from "./search-helpers.ts";
-import { highestConfidence } from "./semantic-action-helpers.ts";
+import type { SemanticSubstrate, StructuralSubstrate } from "./substrates/types.ts";
+import { resolveAnchoredTarget as resolveAnchored } from "./targeting/resolve-anchored.ts";
+import { resolveFileTargetGroup as resolveFile } from "./targeting/resolve-file.ts";
+import { resolveSymbolTarget as resolveSymbol } from "./targeting/resolve-symbol.ts";
 import type { ConfidenceMode, DisambiguationCandidate } from "./types.ts";
 
+// ── Re-exported legacy types ──────────────────────────────────────────
+
 export interface ResolvedTarget {
   file: string;
   /** 0-based position for LSP API */
@@ -46,8 +49,11 @@ export function toZeroBased(line: number, character: number): Position {
   return toLspPosition(line, character);
 }
 
+// ── Anchored resolver ─────────────────────────────────────────────────
+
 /**
  * Resolve a target from anchored coordinates (file + line + character).
+ * Delegates to the new targeting pipeline after normalizing the file path.
  */
 export function resolveAnchoredTarget(
   file: string,
@@ -56,80 +62,39 @@ export function resolveAnchoredTarget(
   cwd: string,
 ): TargetResolutionResult {
   const resolvedFile = normalizePath(file, cwd);
+  const outcome = resolveAnchored(resolvedFile, line, character);
 
-  if (!fs.existsSync(resolvedFile)) {
-    return { kind: "error", message: `File not found: \`${file}\`` };
-  }
-
-  if (isBinaryFile(resolvedFile)) {
+  if (outcome.kind === "resolved") {
     return {
-      kind: "error",
-      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_pattern\` for explicit text search.`,
+      kind: "resolved",
+      target: outcome.target as ResolvedTarget,
     };
   }
 
-  const position = toZeroBased(line, character);
-
-  return {
-    kind: "resolved",
-    target: {
-      file: resolvedFile,
-      position,
-      displayLine: line,
-      displayCharacter: character,
-      name: null,
-      kind: null,
-      confidence: "semantic",
-    },
-  };
+  return outcome as TargetResolutionResult;
 }
 
+// ── File-level target group ───────────────────────────────────────────
+
 /**
  * Resolve a file-only request into a group of actionable targets.
- * Prefers LSP document symbols when available and falls back to Tree-sitter export discovery.
+ * Delegates to the new targeting pipeline with optional structural substrate.
  */
 export async function resolveFileTargetGroup(
   file: string,
   cwd: string,
+  structural?: StructuralSubstrate,
 ): Promise<{ kind: "resolved"; group: ResolvedTargetGroup } | { kind: "error"; 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_pattern\` for explicit text search.`,
-    };
-  }
-
-  const relPath = path.relative(cwd, resolvedFile);
-  const structuralTargets = await resolveFileTargetsViaTreeSitter(relPath, resolvedFile, cwd);
-  const lspTargets = await resolveFileTargetsViaLsp(resolvedFile, cwd, structuralTargets);
-  const targets = lspTargets ?? structuralTargets;
-
-  if (!targets || targets.length === 0) {
-    return {
-      kind: "error",
-      message:
-        `**Error:** File-level semantic exploration is not available for \`${file}\`. ` +
-        "Provide `line` and `character`, or a `symbol` for discovery.",
-    };
-  }
-
+  const outcome = await resolveFile(file, cwd, { structural });
+  if (outcome.kind === "error") return outcome;
   return {
     kind: "resolved",
-    group: {
-      file: resolvedFile,
-      displayName: relPath,
-      targets,
-      confidence: highestConfidence(targets.map((target) => target.confidence)),
-    },
+    group: outcome.group as ResolvedTargetGroup,
   };
 }
 
+// ── Symbol resolver ───────────────────────────────────────────────────
+
 /**
  * Resolve a target from symbol discovery — finds matching declarations.
  * Symbol discovery is semantic-only; it does not fall back to text search.
@@ -137,367 +102,21 @@ export async function resolveFileTargetGroup(
 export async function resolveSymbolTarget(
   symbol: string,
   cwd: string,
+  semantic: SemanticSubstrate,
   options?: {
     path?: string;
     kind?: string;
     exportedOnly?: boolean;
   },
 ): Promise<TargetResolutionResult> {
-  const lspState = await getSemanticServiceState(cwd, { waitForReady: true });
-
-  if (lspState.kind !== "ready") {
-    return {
-      kind: "error",
-      message:
-        `Symbol discovery for \`${symbol}\` requires active LSP. ` +
-        "Use `file` + coordinates, or enable LSP and retry.",
-    };
-  }
-
-  return resolveSymbolViaLsp(symbol, cwd, lspState.service, options);
-}
-
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: pre-existing — not introduced by this change
-async function resolveSymbolViaLsp(
-  symbol: string,
-  cwd: string,
-  lsp: SessionLspService,
-  options?: { path?: string; kind?: string; exportedOnly?: boolean },
-): Promise<TargetResolutionResult> {
-  const results = await lsp.workspaceSymbol(symbol);
-  if (!results || results.length === 0) {
-    return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
-  }
-
-  // Filter by path scope
-  const scopePath = options?.path ? normalizePath(options.path, cwd) : null;
-  let candidates = results.filter((s) => {
-    if (!("location" in s) || !s.location) return false;
-    const uri = s.location.uri;
-    const filePath = uri.startsWith("file://") ? decodeURIComponent(uri.slice(7)) : uri;
-    if (scopePath && !isWithinOrEqual(scopePath, filePath)) return false;
-    return true;
-  });
-
-  // Filter by kind
-  if (options?.kind) {
-    const kindLower = options.kind.toLowerCase();
-    candidates = candidates.filter((s) => {
-      const symbolKind = symbolKindName(s.kind);
-      return symbolKind.toLowerCase().includes(kindLower);
-    });
-  }
-
-  // Filter to exported symbols only (heuristic: non-local SymbolKinds)
-  if (options?.exportedOnly) {
-    candidates = candidates.filter((s) => {
-      // LSP workspace symbols don't expose export visibility directly.
-      // Filter out SymbolKinds that are typically local/private (Variable, Field, Property).
-      const NON_EXPORTED_KINDS = new Set([7, 8, 13]); // Property, Field, Variable
-      return !NON_EXPORTED_KINDS.has(s.kind);
-    });
-  }
-
-  if (candidates.length === 0) {
-    return {
-      kind: "error",
-      message: `Symbol not found: \`${symbol}\`${scopePath ? ` in path \`${options?.path}\`` : ""}`,
-    };
-  }
-
-  if (candidates.length === 1) {
-    const c = candidates[0];
-    const rawLoc = "location" in c ? c.location : null;
-    // WorkspaceSymbol.location may be Location | { uri: string }; we need range.
-    const loc =
-      rawLoc && "range" in rawLoc
-        ? (rawLoc as { uri: string; range: { start: { line: number; character: number } } })
-        : null;
-    if (!loc) {
-      return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
-    }
-    const filePath = loc.uri.startsWith("file://") ? decodeURIComponent(loc.uri.slice(7)) : loc.uri;
+  const outcome = await resolveSymbol(symbol, cwd, semantic, options);
 
+  if (outcome.kind === "resolved") {
     return {
       kind: "resolved",
-      target: {
-        file: filePath,
-        position: loc.range.start,
-        displayLine: loc.range.start.line + 1,
-        displayCharacter: loc.range.start.character + 1,
-        name: c.name,
-        kind: symbolKindName(c.kind),
-        confidence: "semantic",
-      },
+      target: outcome.target as ResolvedTarget,
     };
   }
 
-  // Multiple candidates — return disambiguation
-  const MAX_CANDIDATES = 8;
-  const disambiguated = candidates
-    .slice(0, MAX_CANDIDATES)
-    .map((c, idx) => mapCandidateToDisambiguation(c, idx, cwd));
-
-  return {
-    kind: "disambiguation",
-    candidates: disambiguated,
-    omittedCount: Math.max(0, candidates.length - MAX_CANDIDATES),
-  };
-}
-
-async function resolveFileTargetsViaLsp(
-  resolvedFile: string,
-  cwd: string,
-  structuralTargets: ResolvedTarget[] | null,
-): Promise<ResolvedTarget[] | null> {
-  const lsp = await getSemanticService(cwd, { waitForReady: true });
-  if (!lsp) return null;
-
-  const symbols = await lsp.documentSymbols(resolvedFile);
-  if (!symbols || symbols.length === 0) {
-    return structuralTargets;
-  }
-
-  const topLevel = flattenDocumentSymbols(symbols)
-    .filter((symbol) => !symbol.container)
-    .map((symbol) =>
-      createResolvedTarget({
-        file: resolvedFile,
-        line: symbol.line,
-        character: symbol.character,
-        name: symbol.name,
-        kind: symbol.kind,
-        confidence: "semantic",
-      }),
-    );
-
-  if (topLevel.length === 0) {
-    return structuralTargets;
-  }
-
-  if (!structuralTargets || structuralTargets.length === 0) {
-    return dedupeTargets(topLevel);
-  }
-
-  const matched = structuralTargets.map((target) => {
-    const byName = topLevel.find((candidate) => candidate.name === target.name);
-    return byName ?? target;
-  });
-
-  return dedupeTargets(matched);
-}
-
-async function resolveFileTargetsViaTreeSitter(
-  relPath: string,
-  resolvedFile: string,
-  cwd: string,
-): Promise<ResolvedTarget[] | null> {
-  try {
-    return await withStructuralSession(cwd, async (tsSession) => {
-      const exportsResult = await tsSession.exports(relPath);
-      if (exportsResult.kind !== "success" || exportsResult.data.length === 0) {
-        return null;
-      }
-
-      return dedupeTargets(
-        exportsResult.data.map((record) =>
-          createResolvedTarget({
-            file: resolvedFile,
-            line: record.range.startLine,
-            character: record.range.startCharacter,
-            name: record.name,
-            kind: record.kind,
-            confidence: "structural",
-          }),
-        ),
-      );
-    });
-  } catch {
-    return null;
-  }
-}
-
-function flattenDocumentSymbols(
-  symbols: Array<{
-    name: string;
-    kind: number;
-    selectionRange?: { start: { line: number; character: number } };
-    location?: { range: { start: { line: number; character: number } } };
-    children?: Array<unknown>;
-  }>,
-  container: string | null = null,
-): Array<{
-  name: string;
-  kind: string;
-  line: number;
-  character: number;
-  container: string | null;
-}> {
-  const flattened: Array<{
-    name: string;
-    kind: string;
-    line: number;
-    character: number;
-    container: string | null;
-  }> = [];
-
-  for (const symbol of symbols) {
-    const start = symbol.selectionRange?.start ?? symbol.location?.range.start;
-    if (!start) continue;
-
-    flattened.push({
-      name: symbol.name,
-      kind: symbolKindName(symbol.kind),
-      line: start.line + 1,
-      character: start.character + 1,
-      container,
-    });
-
-    if (Array.isArray(symbol.children) && symbol.children.length > 0) {
-      flattened.push(
-        ...flattenDocumentSymbols(
-          symbol.children as Array<{
-            name: string;
-            kind: number;
-            selectionRange?: { start: { line: number; character: number } };
-            location?: { range: { start: { line: number; character: number } } };
-            children?: Array<unknown>;
-          }>,
-          symbol.name,
-        ),
-      );
-    }
-  }
-
-  return flattened;
-}
-
-function createResolvedTarget(input: {
-  file: string;
-  line: number;
-  character: number;
-  name: string;
-  kind: string | null;
-  confidence: ConfidenceMode;
-}): ResolvedTarget {
-  return {
-    file: input.file,
-    position: toZeroBased(input.line, input.character),
-    displayLine: input.line,
-    displayCharacter: input.character,
-    name: input.name,
-    kind: input.kind,
-    confidence: input.confidence,
-  };
-}
-
-function dedupeTargets(targets: ResolvedTarget[]): ResolvedTarget[] {
-  const deduped = new Map<string, ResolvedTarget>();
-  for (const target of targets) {
-    const key = `${target.name ?? ""}:${target.displayLine}:${target.displayCharacter}`;
-    if (!deduped.has(key)) {
-      deduped.set(key, target);
-    }
-  }
-  return [...deduped.values()];
-}
-
-// ── Helpers ───────────────────────────────────────────────────────────
-
-function mapCandidateToDisambiguation(
-  c: {
-    name: string;
-    kind: number;
-    containerName?: string | null;
-    location?: { uri: string } | null;
-  },
-  idx: number,
-  cwd: string,
-): DisambiguationCandidate {
-  const loc = c.location;
-  const filePath = loc
-    ? loc.uri.startsWith("file://")
-      ? decodeURIComponent(loc.uri.slice(7))
-      : loc.uri
-    : "";
-  const relPath = filePath ? path.relative(cwd, filePath) : "";
-  const rangeObj =
-    loc && "range" in loc
-      ? (loc as unknown as { range: { start: { line: number; character: number } } }).range
-      : null;
-
-  return {
-    name: c.name,
-    kind: symbolKindName(c.kind),
-    container: "containerName" in c ? (c.containerName ?? null) : null,
-    file: relPath,
-    line: rangeObj ? rangeObj.start.line + 1 : 0,
-    character: rangeObj ? rangeObj.start.character + 1 : 0,
-    reason: relPath,
-    rank: idx + 1,
-  };
-}
-
-const BINARY_EXTENSIONS = new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".bmp",
-  ".ico",
-  ".woff",
-  ".woff2",
-  ".ttf",
-  ".eot",
-  ".zip",
-  ".tar",
-  ".gz",
-  ".bz2",
-  ".pdf",
-  ".doc",
-  ".docx",
-  ".exe",
-  ".dll",
-  ".so",
-  ".dylib",
-  ".wasm",
-  ".node",
-]);
-
-function isBinaryFile(filePath: string): boolean {
-  return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
-}
-
-/** Map LSP SymbolKind to a human-readable name. */
-function symbolKindName(kind: number): string {
-  const kinds: Record<number, string> = {
-    1: "File",
-    2: "Module",
-    3: "Namespace",
-    4: "Package",
-    5: "Class",
-    6: "Method",
-    7: "Property",
-    8: "Field",
-    9: "Constructor",
-    10: "Enum",
-    11: "Interface",
-    12: "Function",
-    13: "Variable",
-    14: "Constant",
-    15: "String",
-    16: "Number",
-    17: "Boolean",
-    18: "Array",
-    19: "Object",
-    20: "Key",
-    21: "Null",
-    22: "EnumMember",
-    23: "Struct",
-    24: "Event",
-    25: "Operator",
-    26: "TypeParameter",
-  };
-  return kinds[kind] ?? "Unknown";
+  return outcome as TargetResolutionResult;
 }

package/src/targeting/query.ts

@@ -0,0 +1,60 @@
+/**
+ * Query normalization — converts raw tool/action parameters into a
+ * pre-classified {@link NormalizedQuery}.
+ *
+ * This is the first step in the targeting pipeline. Callers receive
+ * a disambiguated query kind so downstream resolvers can dispatch
+ * without re-checking input shapes.
+ */
+
+import type { NormalizedQuery } from "./types.ts";
+
+export interface QueryInput {
+  path?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  kind?: string;
+  exportedOnly?: boolean;
+}
+
+/**
+ * Normalize a raw params bag into a typed {@link NormalizedQuery}.
+ *
+ * Priority order:
+ * 1. anchored: file + line + character
+ * 2. file: file without coordinates
+ * 3. symbol: symbol without file
+ * 4. invalid: neither file nor symbol
+ */
+export function normalizeQuery(input: QueryInput): NormalizedQuery {
+  if (input.file && input.line != null && input.character != null) {
+    return {
+      kind: "anchored",
+      file: input.file,
+      line: input.line,
+      character: input.character,
+    };
+  }
+
+  if (input.file) {
+    return { kind: "file", file: input.file };
+  }
+
+  if (input.symbol) {
+    return {
+      kind: "symbol",
+      symbol: input.symbol,
+      path: input.path,
+      symbolKind: input.kind,
+      exportedOnly: input.exportedOnly,
+    };
+  }
+
+  return {
+    kind: "invalid",
+    reason:
+      "Semantic actions require either anchored coordinates (`file`, `line`, `character`) or a `symbol` for discovery.",
+  };
+}

package/src/targeting/resolve-anchored.ts

@@ -0,0 +1,80 @@
+/**
+ * Anchored target resolution — resolves a file + position pair into a
+ * typed target outcome using purely filesystem-level validation.
+ *
+ * This resolver does not require LSP or Tree-sitter. It validates
+ * file existence, binary-file guards, and produces the necessary
+ * position conversions for downstream semantic operations.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const BINARY_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".ico",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".bz2",
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".wasm",
+  ".node",
+]);
+
+function isBinaryFile(filePath: string): boolean {
+  return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+/**
+ * Resolve an anchored target from file + position.
+ *
+ * @param file - absolute path to the file
+ * @param line - 1-based line
+ * @param character - 1-based character
+ * @returns Typed outcome: resolved or error
+ */
+export function resolveAnchoredTarget(
+  file: string,
+  line: number,
+  character: number,
+): import("./types.ts").TargetOutcome {
+  if (!fs.existsSync(file)) {
+    return { kind: "error", message: `File not found: \`${file}\`` };
+  }
+
+  if (isBinaryFile(file)) {
+    return {
+      kind: "error",
+      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_pattern\` for explicit text search.`,
+    };
+  }
+
+  return {
+    kind: "resolved",
+    target: {
+      file,
+      position: { line: line - 1, character: character - 1 },
+      displayLine: line,
+      displayCharacter: character,
+      name: null,
+      kind: null,
+      confidence: "semantic",
+    },
+  };
+}