@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.0

package/src/analysis/target/anchored.ts

@@ -0,0 +1,349 @@
+/**
+ * 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";
+import type {
+  CodeResult,
+  CodeSymbol,
+  NodeAtData,
+  SemanticProvider,
+  StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { AnchorKind } from "../../session/target-store.ts";
+import type { AnchoredResolutionMetadata, AnchoredResolutionSource } from "../../types/index.ts";
+import type { DisambiguationCandidateData, ResolvedTargetData, TargetOutcome } from "./types.ts";
+
+/** 1-based symbol anchor position (mirrors the runtime `SymbolAnchor`). */
+type Anchor = { line: number; character: number };
+
+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());
+}
+
+// ── Provider-backed anchored symbol resolution ────────────────────────
+
+/**
+ * Minimal provider surface used by anchored symbol resolution — only the
+ * methods the resolver actually consults. The composite `CodeProvider` from
+ * `request-context.ts` satisfies this shape, as do focused test doubles.
+ */
+export interface AnchoredResolverProvider {
+  documentSymbols?: SemanticProvider["documentSymbols"];
+  nodeAt?: StructuralProvider["nodeAt"];
+}
+
+/** Tree-sitter node types that introduce a named declaration. */
+const DECLARATION_NODE_TYPES = new Set([
+  "function_declaration",
+  "generator_function_declaration",
+  "function_signature",
+  "method_definition",
+  "method_declaration",
+  "method_signature",
+  "class_declaration",
+  "interface_declaration",
+  "enum_declaration",
+  "type_alias_declaration",
+  "lexical_declaration",
+  "variable_declaration",
+  "export_statement",
+]);
+
+/** Tree-sitter node types that represent non-symbol tokens. */
+const NON_SYMBOL_NODE_TYPES = new Set([
+  "comment",
+  "line_comment",
+  "block_comment",
+  "string",
+  "string_fragment",
+  "template_string",
+  "template_literal_type",
+  "regex",
+  "regex_pattern",
+  "number",
+  "escape_sequence",
+]);
+
+function kindFromDeclarationType(nodeType: string): string | null {
+  if (nodeType.includes("function")) return "Function";
+  if (nodeType.includes("method")) return "Method";
+  if (nodeType.includes("class")) return "Class";
+  if (nodeType.includes("interface")) return "Interface";
+  if (nodeType.includes("enum")) return "Enum";
+  if (nodeType.includes("type_alias")) return "Type";
+  if (nodeType.includes("lexical") || nodeType.includes("variable")) return "Variable";
+  return null;
+}
+
+/**
+ * Classify how (or whether) a document symbol relates to a 1-based coordinate.
+ *
+ * - `"exact"` — the coordinate lands on the identifier token (name anchor).
+ * - `"snap"` — the coordinate lands on the declaration header/modifier area
+ *   on the declaration line, before the identifier, and a name anchor exists
+ *   to snap to.
+ * - `null` — no relationship.
+ */
+function matchSymbolAt(s: CodeSymbol, line: number, character: number): "exact" | "snap" | null {
+  const nameAnchor = s.nameAnchor;
+  if (nameAnchor && nameAnchor.line === line) {
+    const start = nameAnchor.character;
+    const end = start + s.name.length;
+    if (character >= start && character < end) return "exact";
+  }
+  const decl = s.declarationAnchor;
+  if (decl.line === line && nameAnchor && nameAnchor.line === line) {
+    if (character >= decl.character && character < nameAnchor.character) return "snap";
+  }
+  return null;
+}
+
+function buildResolution(
+  requested: Anchor,
+  resolvedAnchor: Anchor,
+  snapped: boolean,
+  source: AnchoredResolutionSource,
+): AnchoredResolutionMetadata {
+  return {
+    requested: { line: requested.line, character: requested.character },
+    resolved: { line: resolvedAnchor.line, character: resolvedAnchor.character },
+    snapped,
+    source,
+  };
+}
+
+function resolvedFromSymbol(
+  file: string,
+  s: CodeSymbol,
+  opts: { snapped: boolean; requested: Anchor; source: AnchoredResolutionSource },
+): { kind: "resolved"; target: ResolvedTargetData } {
+  const a = (s.nameAnchor ?? s.declarationAnchor) as Anchor;
+  return {
+    kind: "resolved",
+    target: {
+      file,
+      position: { line: a.line - 1, character: a.character - 1 },
+      displayLine: a.line,
+      displayCharacter: a.character,
+      name: s.name,
+      kind: s.kind,
+      confidence: "semantic",
+      anchorKind: (s.nameAnchor ? "name" : "declaration") as AnchorKind,
+      container: s.container ?? null,
+      resolution: buildResolution(opts.requested, a, opts.snapped, opts.source),
+    },
+  };
+}
+
+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;
+  });
+  return { kind: "disambiguation", candidates, omittedCount: 0 };
+}
+
+/** Layer 1: match the coordinate against LSP document symbols. Returns null to fall through. */
+async function resolveFromSemantic(
+  file: string,
+  requested: Anchor,
+  provider: AnchoredResolverProvider,
+): Promise<TargetOutcome | null> {
+  if (!provider.documentSymbols) return null;
+  let symbols: CodeSymbol[] | null = null;
+  try {
+    symbols = await provider.documentSymbols(file);
+  } catch {
+    symbols = null;
+  }
+  if (!symbols || symbols.length === 0) return null;
+
+  const exact: CodeSymbol[] = [];
+  const snap: CodeSymbol[] = [];
+  for (const s of symbols) {
+    const m = matchSymbolAt(s, requested.line, requested.character);
+    if (m === "exact") exact.push(s);
+    else if (m === "snap") snap.push(s);
+  }
+
+  if (exact.length === 1) {
+    return resolvedFromSymbol(file, exact[0], { snapped: false, requested, source: "semantic" });
+  }
+  if (exact.length > 1) return candidatesFromSymbols(file, exact);
+  if (snap.length === 1) {
+    return resolvedFromSymbol(file, snap[0], { snapped: true, requested, source: "semantic" });
+  }
+  if (snap.length > 1) return candidatesFromSymbols(file, snap);
+  return null;
+}
+
+/** Layer 2: classify the coordinate via tree-sitter `nodeAt`. Returns null to fall through. */
+async function resolveFromStructural(
+  file: string,
+  requested: Anchor,
+  provider: AnchoredResolverProvider,
+): Promise<TargetOutcome | null> {
+  if (!provider.nodeAt) return null;
+  let nodeResult: CodeResult<NodeAtData> | null = null;
+  try {
+    nodeResult = await provider.nodeAt(file, requested.line, requested.character);
+  } catch {
+    nodeResult = null;
+  }
+  if (nodeResult?.kind !== "success") return null;
+
+  const node = nodeResult.data;
+  if (NON_SYMBOL_NODE_TYPES.has(node.type)) {
+    return {
+      kind: "error",
+      message: coordinateNotOnSymbolMessage(file, requested.line, requested.character, node.type),
+    };
+  }
+  if (node.type !== "identifier") {
+    // Keyword/modifier/operator etc. — no LSP header snap available.
+    return {
+      kind: "error",
+      message: coordinateNotOnSymbolMessage(file, requested.line, requested.character, node.type),
+    };
+  }
+
+  const declAncestor = node.ancestry.find((a) => DECLARATION_NODE_TYPES.has(a.type));
+  if (!declAncestor) {
+    // Identifier is a usage, not a declaration name.
+    return {
+      kind: "error",
+      message: coordinateNotOnSymbolMessage(
+        file,
+        requested.line,
+        requested.character,
+        "identifier usage",
+      ),
+    };
+  }
+  const nameAnchor: Anchor = { line: node.startLine, character: node.startCharacter };
+  const snapped =
+    nameAnchor.line !== requested.line || nameAnchor.character !== requested.character;
+  return {
+    kind: "resolved",
+    target: {
+      file,
+      position: { line: nameAnchor.line - 1, character: nameAnchor.character - 1 },
+      displayLine: nameAnchor.line,
+      displayCharacter: nameAnchor.character,
+      name: node.text,
+      kind: kindFromDeclarationType(declAncestor.type),
+      confidence: "structural",
+      anchorKind: "name",
+      container: null,
+      resolution: buildResolution(requested, nameAnchor, snapped, "structural-identifier"),
+    },
+  };
+}
+
+/**
+ * Resolve a real symbol target from anchored coordinates using provider
+ * evidence. Replaces the anonymous point-target behavior for `code_resolve`
+ * and `code_orientation`.
+ *
+ * Layered resolution (per the coordinated-targets plan):
+ * 1. Prefer LSP document-symbol evidence: exact identifier hit, declaration
+ *    header snap (only when exactly one enclosing symbol is unambiguous), or
+ *    explicit disambiguation candidates.
+ * 2. Structural fallback via tree-sitter `nodeAt` — only when unambiguous and
+ *    provider-backed: an identifier token that is a declaration name resolves
+ *    to a structural name-anchor target; comment/string/non-symbol nodes fail
+ *    honestly.
+ * 3. If no provider-backed symbol target can be resolved, return an explicit
+ *    error recommending `code_inspect` for point-level facts.
+ *
+ * This does not perform heuristic global text search and does not silently
+ * treat declaration anchors as name anchors (ADR 0003).
+ */
+export async function resolveAnchoredSymbolTarget(
+  file: string,
+  line: number,
+  character: number,
+  provider: AnchoredResolverProvider | null,
+): Promise<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_find\` with \`mode: "text"\` for explicit text search.`,
+    };
+  }
+
+  const requested: Anchor = { line, character };
+  if (provider) {
+    const semantic = await resolveFromSemantic(file, requested, provider);
+    if (semantic) return semantic;
+    const structural = await resolveFromStructural(file, requested, provider);
+    if (structural) return structural;
+  }
+
+  return { kind: "error", message: coordinateNotOnSymbolMessage(file, line, character, null) };
+}
+
+function coordinateNotOnSymbolMessage(
+  file: string,
+  line: number,
+  character: number,
+  detail: string | null,
+): string {
+  const at = `${path.basename(file)}:${line}:${character}`;
+  const reason = detail ? ` (on \`${detail}\`)` : "";
+  return (
+    `**Error:** 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/bridge.ts

@@ -0,0 +1,152 @@
+/**
+ * Unified target resolution facade through src/analysis/target/*.
+ *
+ * This is the canonical resolution path. It handles anchored coordinates,
+ * file-only, symbol discovery, and disambiguation cases through one path.
+ */
+
+import type { SemanticProvider } from "@mrclrchtr/supi-code-runtime/api";
+import { normalizePath } from "../search/ripgrep.ts";
+import { resolveAnchoredSymbolTarget } from "./anchored.ts";
+import { resolveFileTargetGroup as resolveFile } from "./file.ts";
+import { normalizeQuery, type QueryInput } from "./query.ts";
+import { resolveSymbolTarget as resolveSymbol } from "./symbol.ts";
+import type {
+  NormalizedQuery,
+  ResolvedTargetData,
+  ResolvedTargetGroupData,
+  TargetOutcome,
+} from "./types.ts";
+
+export type { QueryInput } from "./query.ts";
+
+/**
+ * Resolve a target from action params through one canonical path.
+ *
+ * Returns either a resolved target, a target group, or an error string.
+ */
+export async function resolveTarget(
+  params: QueryInput,
+  cwd: string,
+  semantic?: SemanticProvider,
+): Promise<ResolvedTargetData | ResolvedTargetGroupData | string> {
+  const query = normalizeQuery(params);
+
+  switch (query.kind) {
+    case "anchored":
+      return resolveAnchoredCase(query, cwd, semantic);
+
+    case "file": {
+      const result = await resolveFile(query.file, cwd);
+      if (result.kind === "error") return result.message;
+      return result.group;
+    }
+
+    case "symbol": {
+      if (!semantic) {
+        return "**Error:** Symbol discovery requires active LSP. Use `file` + coordinates, or enable LSP and retry.";
+      }
+      const outcome = await resolveSymbol(query.symbol, cwd, semantic, {
+        path: query.path,
+        kind: query.symbolKind,
+        exportedOnly: query.exportedOnly,
+      });
+      if (outcome.kind === "resolved") return outcome.target;
+      if (outcome.kind === "error") return outcome.message;
+      if (outcome.kind !== "disambiguation") {
+        return "**Error:** Unexpected resolution outcome.";
+      }
+      // Disambiguation — format candidates
+      return formatDisambiguation(query.symbol, outcome);
+    }
+
+    case "invalid":
+      return `**Error:** ${query.reason}`;
+  }
+}
+
+/**
+ * Anchored case: route file + line + character through the same provider-backed
+ * symbol resolver as `code_resolve`/`code_orientation` (resolveAnchoredSymbolTarget),
+ * so `code_graph`/`code_impact` resolve real symbol targets (exact identifier
+ * hit or declaration-header snap) instead of anonymous point targets.
+ * Per ADR 0003 — no silent `name:null` point targets.
+ */
+async function resolveAnchoredCase(
+  query: Extract<NormalizedQuery, { kind: "anchored" }>,
+  cwd: string,
+  semantic: SemanticProvider | undefined,
+): Promise<ResolvedTargetData | string> {
+  const resolvedFile = normalizePath(query.file, cwd);
+  const result = await resolveAnchoredSymbolTarget(
+    resolvedFile,
+    query.line,
+    query.character,
+    semantic ?? null,
+  );
+  if (result.kind === "error") return result.message;
+  if (result.kind === "resolved") return result.target;
+  if (result.kind === "disambiguation") {
+    return formatAnchoredDisambiguation(query.file, query.line, query.character, result);
+  }
+  return "**Error:** Unexpected resolution outcome.";
+}
+
+function formatDisambiguation(
+  symbol: string,
+  result: Extract<TargetOutcome, { kind: "disambiguation" }>,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Disambiguation needed for \`${symbol}\``);
+  lines.push("");
+  const omitNote = result.omittedCount > 0 ? ` (+${result.omittedCount} more)` : "";
+  lines.push(
+    `Found ${result.candidates.length} candidates${omitNote}. Rerun with anchored coordinates:`,
+  );
+  lines.push("");
+
+  for (const c of result.candidates) {
+    const kind = c.kind ? ` (${c.kind})` : "";
+    const container = c.container ? ` in ${c.container}` : "";
+    lines.push(
+      `${c.rank}. **${c.name}**${kind}${container} — \`${c.file}\`:${c.line}:${c.character}`,
+    );
+  }
+
+  lines.push("");
+  if (result.candidates.length > 0) {
+    const first = result.candidates[0];
+    lines.push(
+      `Example: rerun with \`file: "${first.file}"\`, \`line: ${first.line}\`, and \`character: ${first.character}\`.`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** Format anchored-coordinate disambiguation (multiple symbols match one coordinate). */
+function formatAnchoredDisambiguation(
+  file: string,
+  line: number,
+  character: number,
+  result: Extract<TargetOutcome, { kind: "disambiguation" }>,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Disambiguation needed at \`${file}:${line}:${character}\``);
+  lines.push("");
+  const omitNote = result.omittedCount > 0 ? ` (+${result.omittedCount} more)` : "";
+  lines.push(
+    `Found ${result.candidates.length} symbol candidates at this coordinate${omitNote}. Use \`code_resolve\` to pick one:`,
+  );
+  lines.push("");
+
+  for (const c of result.candidates) {
+    const kind = c.kind ? ` (${c.kind})` : "";
+    const container = c.container ? ` in ${c.container}` : "";
+    lines.push(
+      `${c.rank}. **${c.name}**${kind}${container} — \`${c.file}\`:${c.line}:${c.character}`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/analysis/target/file-resolution.ts

@@ -0,0 +1,125 @@
+/**
+ * File-level resolution logic for code_resolve.
+ *
+ * Extracted from resolve/service.ts. Handles file-only resolution and
+ * path-like query resolution for the code_resolve tool.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
+import type { CodeProvider } from "../provider.ts";
+import { normalizePath } from "../search/ripgrep.ts";
+import { resolveFileTargetGroup as resolveFile } from "./file.ts";
+import {
+  type ResolveServiceParams,
+  type ResolveServiceResult,
+  registerFromTarget,
+} from "./resolve-common.ts";
+
+/** Resolve file-only (no coordinates) input. */
+export async function resolveFileOnlyInput(
+  params: ResolveServiceParams,
+  session: WorkspaceCodeIntelligenceSession,
+  maxResults: number,
+  provider: CodeProvider | null,
+): Promise<ResolveServiceResult> {
+  const cwd = session.cwd;
+  const file = params.file;
+  if (!file) {
+    return { kind: "error", message: "**Error:** File required for file-level resolution." };
+  }
+  const resolvedFile = normalizePath(file, cwd);
+  if (!existsSync(resolvedFile)) {
+    return { kind: "error", message: `**Error:** File not found: \`${file}\`` };
+  }
+  const outcome = await resolveFile(file, cwd, {
+    semantic: provider ?? undefined,
+    structural: provider ?? undefined,
+  });
+  if (outcome.kind === "error") {
+    return { kind: "error", message: outcome.message };
+  }
+  const targets = outcome.group.targets
+    .slice(0, maxResults)
+    .map((t) =>
+      registerFromTarget({ ...t, position: t.position, confidence: t.confidence }, session, "file"),
+    );
+  return {
+    kind: "resolved",
+    targets,
+    confidence: outcome.group.confidence,
+    omittedCount: Math.max(0, outcome.group.targets.length - maxResults),
+    nextQueries: [
+      "Use `targetId` with `code_graph` for reference tracking",
+      "Use `targetId` with `code_impact` for blast radius",
+    ],
+  };
+}
+
+/** Handle a path-like query with kind: "file". */
+export async function resolvePathQuery(
+  query: string,
+  session: WorkspaceCodeIntelligenceSession,
+  maxResults: number,
+  provider: CodeProvider | null,
+): Promise<ResolveServiceResult | null> {
+  const cwd = session.cwd;
+  const candidatePath = resolvePathLikeQuery(query, cwd);
+  if (!candidatePath) return null;
+  const outcome = await resolveFile(candidatePath, cwd, {
+    semantic: provider ?? undefined,
+    structural: provider ?? undefined,
+  });
+  if (outcome.kind === "error") return null;
+  const targets = outcome.group.targets
+    .slice(0, maxResults)
+    .map((t) =>
+      registerFromTarget({ ...t, position: t.position, confidence: t.confidence }, session, "file"),
+    );
+  return {
+    kind: "resolved",
+    targets,
+    confidence: outcome.group.confidence,
+    omittedCount: Math.max(0, outcome.group.targets.length - maxResults),
+    nextQueries: [
+      "Use `targetId` with `code_graph` for reference tracking",
+      "Use `targetId` with `code_impact` for blast radius",
+    ],
+  };
+}
+
+/** Attempt file-level resolution when query looks like a file path. */
+export async function tryPathLikeQuery(
+  params: ResolveServiceParams,
+  session: WorkspaceCodeIntelligenceSession,
+  maxResults: number,
+  provider: CodeProvider | null,
+): Promise<ResolveServiceResult | null> {
+  if (params.kind !== "file" && params.kind !== "File") return null;
+  const query = params.query;
+  if (!query || !isPathLike(query)) return null;
+  return resolvePathQuery(query, session, maxResults, provider);
+}
+
+export function isPathLike(query: string): boolean {
+  return (
+    query.includes("/") || query.includes("\\") || query.endsWith(".ts") || query.endsWith(".js")
+  );
+}
+
+/**
+ * Attempt to resolve a path-like query string to an absolute file path.
+ * Returns null if the path cannot be resolved to an existing file.
+ */
+export function resolvePathLikeQuery(query: string, cwd: string): string | null {
+  const candidate = resolve(cwd, query);
+  if (existsSync(candidate)) {
+    return candidate;
+  }
+  for (const ext of [".ts", ".tsx", ".js", ".jsx", ".json", ".md"]) {
+    const withExt = candidate + ext;
+    if (existsSync(withExt)) return withExt;
+  }
+  return null;
+}