@mrclrchtr/supi-code-intelligence 1.6.0 → 1.8.0

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",
+    },
+  };
+}

package/src/targeting/resolve-file.ts

@@ -0,0 +1,197 @@
+/**
+ * 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.
+ *
+ * Policy: LSP document symbols preferred (semantic). Falls back to Tree-sitter
+ * exports (structural) when LSP is unavailable or returns no results.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { normalizePath } from "../search-helpers.ts";
+import { highestConfidence } from "../semantic-action-helpers.ts";
+import { createStructuralSubstrate } from "../substrates/tree-sitter-adapter.ts";
+import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
+import type { ResolvedTargetData, ResolvedTargetGroupData } from "./types.ts";
+
+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 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
+ */
+export async function resolveFileTargetGroup(
+  file: string,
+  cwd: string,
+  deps: {
+    semantic?: SemanticSubstrate;
+    structural?: StructuralSubstrate;
+  } = {},
+): Promise<
+  { kind: "resolved"; group: ResolvedTargetGroupData } | { 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);
+
+  // 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) {
+    return {
+      kind: "error",
+      message:
+        `**Error:** File-level semantic exploration is not available for \`${file}\`. ` +
+        "Provide `line` and `character`, or a `symbol` for discovery.",
+    };
+  }
+
+  return {
+    kind: "resolved",
+    group: {
+      file: resolvedFile,
+      displayName: relPath,
+      targets,
+      confidence: highestConfidence(targets.map((t) => t.confidence)),
+    },
+  };
+}
+
+// ── Resolution helpers ───────────────────────────────────────────────
+
+async function resolveViaSemantic(
+  resolvedFile: string,
+  semantic?: SemanticSubstrate,
+  structuralTargets: ResolvedTargetData[] | null = null,
+): Promise<ResolvedTargetData[] | null> {
+  if (!semantic) return structuralTargets;
+
+  try {
+    const symbols = await semantic.documentSymbols(resolvedFile);
+    if (!symbols || symbols.length === 0) return structuralTargets;
+
+    const topLevel = symbols
+      .filter((s) => !s.container)
+      .map((s) => ({
+        file: resolvedFile,
+        position: { line: s.line - 1, character: s.character - 1 },
+        displayLine: s.line,
+        displayCharacter: s.character,
+        name: s.name,
+        kind: s.kind,
+        confidence: "semantic" as const,
+      }));
+
+    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);
+  } catch {
+    return structuralTargets;
+  }
+}
+
+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;
+
+  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,
+      })),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Create a fallback structural substrate from a working directory. */
+function createFallbackSubstrate(dir: string): StructuralSubstrate | null {
+  try {
+    return createStructuralSubstrate(dir);
+  } catch {
+    return null;
+  }
+}
+
+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);
+    }
+  }
+  return [...deduped.values()];
+}

package/src/targeting/resolve-symbol.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+import type { SemanticSubstrate } from "../substrates/types.ts";
+import type { DisambiguationCandidateData, TargetOutcome } from "./types.ts";
+
+const MAX_CANDIDATES = 8;
+const NON_EXPORTED_KINDS = new Set(["Variable", "Field", "Property"]);
+
+/**
+ * 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;
+  },
+): 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
+  const scopePath = options?.path ? path.resolve(cwd, options.path) : 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.line > 0 || s.character > 0);
+
+  if (ranged.length === 1) {
+    const c = ranged[0];
+    return {
+      kind: "resolved",
+      target: {
+        file: c.file,
+        position: { line: c.line - 1, character: c.character - 1 },
+        displayLine: c.line,
+        displayCharacter: c.character,
+        name: c.name,
+        kind: c.kind,
+        confidence: "semantic",
+      },
+    };
+  }
+
+  // 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 — return disambiguation
+  const candidatesOut = candidates.slice(0, MAX_CANDIDATES).map((c, idx) => ({
+    name: c.name,
+    kind: c.kind,
+    container: c.container ?? null,
+    file: path.relative(cwd, c.file),
+    line: c.line,
+    character: c.character,
+    reason: path.relative(cwd, c.file),
+    rank: idx + 1,
+  })) satisfies DisambiguationCandidateData[];
+
+  return {
+    kind: "disambiguation",
+    candidates: candidatesOut,
+    omittedCount: Math.max(0, candidates.length - MAX_CANDIDATES),
+  };
+}

package/src/targeting/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Targeting types — normalized query and typed outcomes for the
+ * target-resolution pipeline.
+ *
+ * These types decouple request normalization from resolution implementation
+ * and keep action-facing code focused on routing, not string building.
+ */
+
+import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
+
+// ── Normalized query ──────────────────────────────────────────────────
+
+/**
+ * A pre-classified target request extracted from tool/action parameters.
+ *
+ * The pipeline normalizes incoming params into one of these shapes
+ * so each resolver phase can operate on an already-disambiguated query.
+ */
+export type NormalizedQuery =
+  | {
+      kind: "anchored";
+      file: string;
+      line: number;
+      character: number;
+    }
+  | {
+      kind: "file";
+      file: string;
+    }
+  | {
+      kind: "symbol";
+      symbol: string;
+      path?: string;
+      symbolKind?: string;
+      exportedOnly?: boolean;
+    }
+  | {
+      kind: "invalid";
+      reason: string;
+    };
+
+// ── Resolver dependency injection ─────────────────────────────────────
+
+/**
+ * Substrates and context injected into the resolution pipeline.
+ *
+ * Passed from the action/tool entrypoint rather than constructed
+ * inside resolver internals, so fallback policy is explicit.
+ */
+export interface ResolverDeps {
+  cwd: string;
+  semantic?: SemanticSubstrate;
+  structural?: StructuralSubstrate;
+}
+
+// ── Typed resolution outcomes ─────────────────────────────────────────
+
+/**
+ * A successfully resolved anchored target with 0-/1-based positions.
+ */
+export interface ResolvedTargetData {
+  file: string;
+  /** 0-based position for LSP calls */
+  position: { line: number; character: number };
+  /** 1-based position for user display */
+  displayLine: number;
+  displayCharacter: number;
+  name: string | null;
+  kind: string | null;
+  confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+}
+
+/**
+ * A file-level target group with one or more discoverable targets.
+ */
+export interface ResolvedTargetGroupData {
+  file: string;
+  displayName: string;
+  targets: ResolvedTargetData[];
+  confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+}
+
+/**
+ * A disambiguation candidate for symbol searches with multiple matches.
+ */
+export interface DisambiguationCandidateData {
+  name: string;
+  kind: string | null;
+  container: string | null;
+  file: string;
+  line: number;
+  character: number;
+  reason: string;
+  rank: number;
+}
+
+/**
+ * Typed outcome of a resolution attempt.
+ *
+ * Actions consume these to produce user-facing strings/details;
+ * the resolution pipeline itself stays presentation-agnostic.
+ */
+export type TargetOutcome =
+  | { kind: "resolved"; target: ResolvedTargetData }
+  | { kind: "group"; group: ResolvedTargetGroupData }
+  | {
+      kind: "disambiguation";
+      candidates: DisambiguationCandidateData[];
+      omittedCount: number;
+    }
+  | { kind: "error"; message: string };

package/src/tool/execute-affected.ts

@@ -0,0 +1,25 @@
+import type { CodeIntelResult } from "../types.ts";
+import { executeAffected } from "../use-case/generate-affected.ts";
+import { validateFocusedToolParams } from "./validation.ts";
+
+export interface CodeAffectedToolParams {
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  exportedOnly?: boolean;
+  maxResults?: number;
+}
+
+/** Execute the public code_affected tool through the affected use-case. */
+export async function executeAffectedTool(
+  params: CodeAffectedToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validateFocusedToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  return executeAffected(params, { cwd: ctx.cwd });
+}

package/src/tool/execute-brief.ts

@@ -0,0 +1,51 @@
+import { buildArchitectureModel } from "../architecture.ts";
+import { createStructuralSubstrate } from "../substrates/tree-sitter-adapter.ts";
+import type { CodeIntelResult } from "../types.ts";
+import { executeBrief } from "../use-case/generate-brief.ts";
+import type { BriefInput } from "../use-case/types.ts";
+import { validateFocusedToolParams } from "./validation.ts";
+
+export interface CodeBriefToolParams {
+  path?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  maxResults?: number;
+}
+
+/** Execute the public code_brief tool through the use-case/presentation layers. */
+export async function executeBriefTool(
+  params: CodeBriefToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validateFocusedToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  const structural = createStructuralSubstrate(ctx.cwd);
+  const model = await buildArchitectureModel(ctx.cwd);
+
+  const input: BriefInput = determineInput(params);
+  const deps = { model, structural, cwd: ctx.cwd };
+
+  const result = await executeBrief(input, deps);
+  return { content: result.content, details: { type: "brief", data: result.details } };
+}
+
+function determineInput(params: CodeBriefToolParams): BriefInput {
+  if (params.file && params.line != null && params.character != null) {
+    return { kind: "anchored", file: params.file, line: params.line, character: params.character };
+  }
+  if (params.symbol) {
+    return { kind: "symbol", symbol: params.symbol, path: params.path };
+  }
+  if (params.path) {
+    return { kind: "path", path: params.path };
+  }
+  if (params.file) {
+    return { kind: "file", file: params.file };
+  }
+  return { kind: "project" };
+}

package/src/tool/execute-map.ts

@@ -0,0 +1,35 @@
+import * as fs from "node:fs";
+import { renderMap } from "../presentation/markdown/map.ts";
+import { normalizePath } from "../search-helpers.ts";
+import type { CodeIntelResult } from "../types.ts";
+import { buildMapData } from "../use-case/generate-map.ts";
+
+export interface CodeMapToolParams {
+  path?: string;
+}
+
+/** Execute the public code_map tool with focused directory validation. */
+export async function executeMapTool(
+  params: CodeMapToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const scopePath = params.path ? normalizePath(params.path, ctx.cwd) : ctx.cwd;
+
+  if (!fs.existsSync(scopePath)) {
+    return {
+      content: `**Error:** code_map path not found: \`${params.path ?? scopePath}\``,
+      details: undefined,
+    };
+  }
+
+  if (!fs.statSync(scopePath).isDirectory()) {
+    return {
+      content: "**Error:** code_map requires a directory path, not a file.",
+      details: undefined,
+    };
+  }
+
+  const data = buildMapData(scopePath, ctx.cwd);
+  const rendered = renderMap(data);
+  return { content: rendered.content, details: { type: "map", data: rendered.details } };
+}

package/src/tool/execute-pattern.ts

@@ -0,0 +1,28 @@
+import { createStructuralSubstrate } from "../substrates/tree-sitter-adapter.ts";
+import type { CodeIntelResult } from "../types.ts";
+import { executePattern } from "../use-case/generate-pattern.ts";
+import { validatePatternToolParams } from "./validation.ts";
+
+export interface CodePatternToolParams {
+  path?: string;
+  pattern: string;
+  regex?: boolean;
+  kind?: string;
+  maxResults?: number;
+  contextLines?: number;
+  summary?: boolean;
+}
+
+/** Execute the public code_pattern tool through the pattern use-case. */
+export async function executePatternTool(
+  params: CodePatternToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validatePatternToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  const structural = createStructuralSubstrate(ctx.cwd);
+  return executePattern(params, { cwd: ctx.cwd, structural });
+}

package/src/tool/execute-relations.ts

@@ -0,0 +1,40 @@
+import type { CodeIntelResult } from "../types.ts";
+import type { RelationsInput } from "../use-case/generate-relations.ts";
+import { executeRelations } from "../use-case/generate-relations.ts";
+import type { CodeRelationsKind } from "./tool-specs.ts";
+import { validateFocusedToolParams } from "./validation.ts";
+
+export interface CodeRelationsToolParams {
+  kind: CodeRelationsKind;
+  path?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  exportedOnly?: boolean;
+  maxResults?: number;
+}
+
+/** Execute the public code_relations tool through the relations use-case. */
+export async function executeRelationsTool(
+  params: CodeRelationsToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validateFocusedToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  const input: RelationsInput = {
+    kind: params.kind,
+    path: params.path,
+    file: params.file,
+    line: params.line,
+    character: params.character,
+    symbol: params.symbol,
+    exportedOnly: params.exportedOnly,
+    maxResults: params.maxResults,
+  };
+
+  return executeRelations(input, { cwd: ctx.cwd });
+}