@mrclrchtr/supi-code-intelligence 0.2.0 → 1.1.3

package/src/actions/callers-action.ts

@@ -6,14 +6,19 @@ import { resolveTarget } from "../resolve-target.ts";
 import {
   escapeRegex,
   filterOutDeclaration,
-  groupByFile,
   isInProjectPath,
   normalizePath,
   runRipgrep,
   uriToFile,
 } from "../search-helpers.ts";
+import {
+  dedupeFileLineRefs,
+  highestConfidence,
+  isResolvedTargetGroup,
+} from "../semantic-action-helpers.ts";
+import type { ResolvedTarget, ResolvedTargetGroup } from "../target-resolution.ts";
 import type { ActionParams } from "../tool-actions.ts";
-import type { CodeIntelResult, SearchDetails } from "../types.ts";
+import type { CodeIntelResult, ConfidenceMode, SearchDetails } from "../types.ts";
 
 export async function executeCallersAction(
   params: ActionParams,
@@ -36,42 +41,45 @@ export async function executeCallersAction(
     };
   }
 
-  const maxResults = params.maxResults ?? 5;
-  const lspState = getSessionLspService(cwd);
-
-  if (lspState.kind === "ready") {
-    const refs = await lspState.service.references(target.file, target.position);
-    if (refs && refs.length > 0) {
-      // Filter out the declaration itself — LSP includes it with includeDeclaration
-      const callerRefs = filterOutDeclaration(refs, target.file, target.position);
-      if (callerRefs.length > 0) {
-        const content = formatSemanticCallers(callerRefs, target.name, cwd, maxResults);
-        const { project: projectRefs, external: externalRefs } = partitionRefs(refs, cwd);
-        const details: SearchDetails = {
-          confidence: "semantic",
-          scope: params.path ?? null,
-          candidateCount: projectRefs.length,
-          omittedCount: externalRefs.length,
-          nextQueries: [
-            "`code_intel affected` for impact analysis",
-            "`code_intel pattern` with broader scope for additional matches",
-          ],
-        };
-        return { content, details: { type: "search" as const, data: details } };
-      }
-    }
+  if (isResolvedTargetGroup(target)) {
+    return executeFileLevelCallers(target, params, cwd);
   }
 
-  if (target.name) {
-    const result = formatHeuristicCallers(target.name, params, cwd);
+  const result = await collectCallerRefs(target, params, cwd);
+  if (result.refs.length > 0) {
+    const content = formatTargetCallers(
+      `Callers of \`${target.name ?? "symbol"}\``,
+      result,
+      cwd,
+      params,
+    );
     const details: SearchDetails = {
-      confidence: "heuristic",
+      confidence: result.confidence,
       scope: params.path ?? null,
-      candidateCount: result.matchCount,
-      omittedCount: 0,
-      nextQueries: ["Enable LSP for `semantic` caller accuracy"],
+      candidateCount: result.candidateCount,
+      omittedCount: result.externalCount,
+      nextQueries: [
+        "`code_intel affected` for impact analysis",
+        "`code_intel pattern` with broader scope for additional matches",
+      ],
+    };
+    return { content, details: { type: "search" as const, data: details } };
+  }
+
+  if (target.name) {
+    return {
+      content: `No references found for \`${target.name}\` (${result.confidence}).`,
+      details: {
+        type: "search" as const,
+        data: {
+          confidence: result.confidence,
+          scope: params.path ?? null,
+          candidateCount: 0,
+          omittedCount: 0,
+          nextQueries: ["Enable LSP for `semantic` caller accuracy"],
+        },
+      },
     };
-    return { content: result.content, details: { type: "search" as const, data: details } };
   }
 
   const relPath = path.relative(cwd, target.file);
@@ -90,126 +98,185 @@ export async function executeCallersAction(
   };
 }
 
-function partitionRefs(
-  refs: Array<{ uri: string; range: { start: { line: number; character: number } } }>,
-  cwd: string,
-): { project: typeof refs; external: typeof refs } {
-  const project: typeof refs = [];
-  const external: typeof refs = [];
-  for (const ref of refs) {
-    if (isInProjectPath(uriToFile(ref.uri), cwd)) {
-      project.push(ref);
-    } else {
-      external.push(ref);
-    }
-  }
-  return { project, external };
+interface CallerRef {
+  file: string;
+  line: number;
 }
 
-function groupRefsByFile(
-  refs: Array<{ uri: string; range: { start: { line: number; character: number } } }>,
-  cwd: string,
-): Map<string, number[]> {
-  const byFile = new Map<string, number[]>();
-  for (const ref of refs) {
-    const filePath = uriToFile(ref.uri);
-    const relPath = path.relative(cwd, filePath);
-    const group = byFile.get(relPath) ?? [];
-    group.push(ref.range.start.line + 1);
-    byFile.set(relPath, group);
-  }
-  return byFile;
+interface CallerCollection {
+  refs: CallerRef[];
+  confidence: ConfidenceMode;
+  externalCount: number;
+  candidateCount: number;
 }
 
-function formatSemanticCallers(
-  refs: Array<{ uri: string; range: { start: { line: number; character: number } } }>,
-  name: string | null,
+async function executeFileLevelCallers(
+  targetGroup: ResolvedTargetGroup,
+  params: ActionParams,
   cwd: string,
-  maxResults: number,
-): string {
-  const { project: projectRefs, external: externalRefs } = partitionRefs(refs, cwd);
+): Promise<CodeIntelResult> {
+  const perTarget = await Promise.all(
+    targetGroup.targets.map(async (target) => ({
+      target,
+      result: await collectCallerRefs(target, params, cwd),
+    })),
+  );
+
+  const withRefs = perTarget.filter((entry) => entry.result.refs.length > 0);
+  const uniqueRefs = dedupeFileLineRefs(withRefs.flatMap((entry) => entry.result.refs));
+  const confidence = highestConfidence(withRefs.map((entry) => entry.result.confidence));
+  const externalCount = withRefs.reduce((sum, entry) => sum + entry.result.externalCount, 0);
 
   const lines: string[] = [];
-  lines.push(`# Callers of \`${name ?? "symbol"}\``);
+  lines.push(`# Callers in \`${targetGroup.displayName}\``);
   lines.push("");
   lines.push(
-    `**${projectRefs.length} reference${projectRefs.length !== 1 ? "s" : ""}** (semantic)`,
+    `**${targetGroup.targets.length} exported target${targetGroup.targets.length !== 1 ? "s" : ""}** | **${uniqueRefs.length} reference${uniqueRefs.length !== 1 ? "s" : ""}** (${confidence})`,
   );
-  if (externalRefs.length > 0) {
-    const suffix =
-      externalRefs.length === 1
-        ? "+1 external reference"
-        : `+${externalRefs.length} external references`;
-    lines.push(`_${suffix} (node_modules, .pnpm, or out-of-tree)_`);
+  if (externalCount > 0) {
+    lines.push(`_+${externalCount} external reference${externalCount !== 1 ? "s" : ""}_`);
   }
   lines.push("");
 
-  const byFile = groupRefsByFile(projectRefs, cwd);
-
-  let shown = 0;
-  for (const [file, locations] of byFile) {
-    if (shown >= maxResults) break;
-    lines.push(`### ${file}`);
-    for (const loc of locations.slice(0, 5)) {
-      lines.push(`- L${loc}`);
-    }
-    if (locations.length > 5) {
-      lines.push(`- _+${locations.length - 5} more in this file_`);
-    }
+  for (const entry of withRefs) {
+    lines.push(`## \`${entry.target.name ?? "symbol"}\``);
+    addRefList(lines, entry.result.refs, cwd, params.maxResults ?? 5);
     lines.push("");
-    shown++;
   }
 
-  if (byFile.size > maxResults) {
-    lines.push(
-      `_+${byFile.size - maxResults} more files omitted. Narrow with \`path\` or increase \`maxResults\`._`,
-    );
+  if (withRefs.length === 0) {
+    lines.push("No caller references found for the discovered file-level targets.");
     lines.push("");
   }
 
-  return lines.join("\n");
+  const details: SearchDetails = {
+    confidence,
+    scope: params.path ?? null,
+    candidateCount: uniqueRefs.length,
+    omittedCount: externalCount,
+    nextQueries: [
+      "`code_intel affected` for impact analysis",
+      "Use `file` + coordinates to drill into one symbol precisely",
+    ],
+  };
+
+  return { content: lines.join("\n"), details: { type: "search" as const, data: details } };
 }
 
-function formatHeuristicCallers(
-  symbol: string,
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: LSP-first caller collection with fallback and declaration filtering is clearest in one helper
+async function collectCallerRefs(
+  target: ResolvedTarget,
   params: ActionParams,
   cwd: string,
-): { content: string; matchCount: number } {
-  const maxResults = params.maxResults ?? 8;
-  const scopePath = params.path ? normalizePath(params.path, cwd) : cwd;
-  const pattern = `\\b${escapeRegex(symbol)}\\b`;
-  const matches = runRipgrep(pattern, scopePath, cwd, { maxMatches: maxResults * 3 });
+): Promise<CallerCollection> {
+  const lspState = getSessionLspService(cwd);
+
+  if (lspState.kind === "ready") {
+    const refs = await lspState.service.references(target.file, target.position);
+    if (refs && refs.length > 0) {
+      const filtered = filterOutDeclaration(refs, target.file, target.position);
+      const projectRefs: CallerRef[] = [];
+      let externalCount = 0;
+      for (const ref of refs) {
+        const filePath = uriToFile(ref.uri);
+        if (!isInProjectPath(filePath, cwd)) {
+          externalCount++;
+        }
+      }
+      for (const ref of filtered) {
+        const filePath = uriToFile(ref.uri);
+        if (isInProjectPath(filePath, cwd)) {
+          projectRefs.push({ file: path.relative(cwd, filePath), line: ref.range.start.line + 1 });
+        }
+      }
+      if (projectRefs.length > 0) {
+        return {
+          refs: projectRefs,
+          confidence: "semantic",
+          externalCount,
+          candidateCount: projectRefs.length,
+        };
+      }
+    }
+  }
 
-  if (matches.length === 0) {
-    return { content: `No references found for \`${symbol}\` (heuristic).`, matchCount: 0 };
+  if (!target.name) {
+    return { refs: [], confidence: "unavailable", externalCount: 0, candidateCount: 0 };
   }
 
+  const scopePath = params.path ? normalizePath(params.path, cwd) : cwd;
+  const pattern = `\\b${escapeRegex(target.name)}\\b`;
+  const matches = runRipgrep(pattern, scopePath, cwd, { maxMatches: (params.maxResults ?? 8) * 3 });
+  const refs = matches
+    .filter((match) => !isDeclarationMatch(match.file, match.line, target, cwd))
+    .map((match) => ({
+      file: path.relative(cwd, path.resolve(cwd, match.file)),
+      line: match.line,
+    }));
+
+  return { refs, confidence: "heuristic", externalCount: 0, candidateCount: refs.length };
+}
+
+function formatTargetCallers(
+  title: string,
+  result: CallerCollection,
+  cwd: string,
+  params: ActionParams,
+): string {
   const lines: string[] = [];
-  lines.push(`# Callers of \`${symbol}\` (heuristic)`);
+  lines.push(`# ${title}`);
   lines.push("");
   lines.push(
-    `**${matches.length} match${matches.length > 1 ? "es" : ""}** — text-search hints, not semantic references`,
+    `**${result.candidateCount} reference${result.candidateCount !== 1 ? "s" : ""}** (${result.confidence})`,
   );
+  if (result.externalCount > 0) {
+    lines.push(
+      `_+${result.externalCount} external reference${result.externalCount !== 1 ? "s" : ""}_`,
+    );
+  }
   lines.push("");
+  addRefList(lines, result.refs, cwd, params.maxResults ?? 5);
+  return lines.join("\n");
+}
 
-  const byFile = groupByFile(matches);
+function addRefList(lines: string[], refs: CallerRef[], cwd: string, maxResults: number): void {
+  const byFile = groupRefsByFile(refs, cwd);
   let shown = 0;
-  for (const [file, fileMatches] of byFile) {
+  for (const [file, locations] of byFile) {
     if (shown >= maxResults) break;
     lines.push(`### ${file}`);
-    for (const m of fileMatches.slice(0, 3)) {
-      lines.push(`- L${m.line}: \`${m.text.slice(0, 100)}\``);
+    for (const loc of locations.slice(0, 5)) {
+      lines.push(`- L${loc}`);
     }
-    if (fileMatches.length > 3) {
-      lines.push(`- _+${fileMatches.length - 3} more_`);
+    if (locations.length > 5) {
+      lines.push(`- _+${locations.length - 5} more in this file_`);
     }
     lines.push("");
     shown++;
   }
 
   if (byFile.size > maxResults) {
-    lines.push(`_+${byFile.size - maxResults} more files omitted._`);
+    lines.push(
+      `_+${byFile.size - maxResults} more files omitted. Narrow with \`path\` or increase \`maxResults\`._`,
+    );
+  }
+}
+
+function groupRefsByFile(refs: CallerRef[], _cwd: string): Map<string, number[]> {
+  const byFile = new Map<string, number[]>();
+  for (const ref of refs) {
+    const group = byFile.get(ref.file) ?? [];
+    group.push(ref.line);
+    byFile.set(ref.file, group);
   }
+  return byFile;
+}
 
-  return { content: lines.join("\n"), matchCount: matches.length };
+function isDeclarationMatch(
+  file: string,
+  line: number,
+  target: ResolvedTarget,
+  cwd: string,
+): boolean {
+  return path.resolve(cwd, file) === target.file && line === target.displayLine;
 }

package/src/actions/implementations-action.ts

@@ -10,9 +10,11 @@ import {
   runRipgrep,
   uriToFile,
 } from "../search-helpers.ts";
+import { isResolvedTargetGroup } from "../semantic-action-helpers.ts";
 import type { ActionParams } from "../tool-actions.ts";
 import type { CodeIntelResult, SearchDetails } from "../types.ts";
 
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: implementation lookup has distinct semantic, unsupported-file, and heuristic branches
 export async function executeImplementationsAction(
   params: ActionParams,
   cwd: string,
@@ -34,6 +36,22 @@ export async function executeImplementationsAction(
     };
   }
 
+  if (isResolvedTargetGroup(target)) {
+    return {
+      content: `**Error:** File-level implementation discovery is not available for \`${path.relative(cwd, target.file)}\`.\n\nProvide \`line\` and \`character\`, or a \`symbol\` for discovery.`,
+      details: {
+        type: "search" as const,
+        data: {
+          confidence: "unavailable",
+          scope: params.path ?? null,
+          candidateCount: 0,
+          omittedCount: 0,
+          nextQueries: ["Use `file` + coordinates or `symbol` for implementation lookup"],
+        },
+      },
+    };
+  }
+
   const lspState = getSessionLspService(cwd);
   const relPath = path.relative(cwd, target.file);
 

package/src/actions/pattern-action.ts

@@ -1,5 +1,12 @@
 // Pattern action — bounded, scope-aware text search.
+// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: text and structured pattern flows share one formatter and matcher pipeline
 
+import {
+  getStructuredPatternMatches,
+  isStructuredPatternKind,
+  type StructuredMatch,
+  type StructuredPatternResult,
+} from "../pattern-structured.ts";
 import type { RgMatch } from "../search-helpers.ts";
 import {
   escapeRegex,
@@ -19,7 +26,7 @@ import type { CodeIntelResult, SearchDetails } from "../types.ts";
  * patterns are surfaced as explicit user-facing errors instead of being
  * collapsed into a misleading no-match response.
  */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: function has multiple distinct paths (validation, regex vs literal, summary vs detailed, zero vs results) that are clearer when explicit than when split; 18 is acceptable for the use case
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: function has multiple distinct paths (validation, regex vs literal, summary vs detailed, structured vs text, zero vs results) that are clearer when explicit than when split
 export async function executePatternAction(
   params: ActionParams,
   cwd: string,
@@ -36,6 +43,63 @@ export async function executePatternAction(
   const scopePath = params.path ? normalizePath(params.path, cwd) : cwd;
   const relScope = params.path ?? ".";
 
+  if (isStructuredPatternKind(params.kind)) {
+    const structured = await getStructuredPatternMatches(
+      { ...params, pattern: params.pattern, kind: params.kind },
+      scopePath,
+      cwd,
+      relScope,
+    );
+    if (typeof structured === "string") {
+      const errorDetails: SearchDetails = {
+        confidence: "unavailable",
+        scope: params.path ?? null,
+        candidateCount: 0,
+        omittedCount: 0,
+        nextQueries: ["Fix the regex pattern and retry"],
+      };
+      return { content: structured, details: { type: "search", data: errorDetails } };
+    }
+
+    if (structured) {
+      if (structured.matches.length === 0) {
+        return {
+          content: formatStructuredEmptyState(params.pattern, params.kind, relScope, structured),
+          details: {
+            type: "search",
+            data: {
+              confidence: "structural",
+              scope: params.path ?? null,
+              candidateCount: 0,
+              omittedCount: structured.omittedCount,
+              nextQueries: [
+                "Try a broader `pattern`, or omit `kind` for plain text search",
+                "Narrow `path` if the structured scan was partial",
+              ],
+            },
+          },
+        };
+      }
+
+      return {
+        content: formatStructuredMatches(params.pattern, params.kind, relScope, structured),
+        details: {
+          type: "search",
+          data: {
+            confidence: "structural",
+            scope: params.path ?? null,
+            candidateCount: structured.matches.length,
+            omittedCount: structured.omittedCount,
+            nextQueries: [
+              "Omit `kind` for plain text matches",
+              "Use `summary: true` for broader textual distribution",
+            ],
+          },
+        },
+      };
+    }
+  }
+
   const matches = params.regex
     ? getRegexMatches({
         pattern: params.pattern,
@@ -78,12 +142,9 @@ export async function executePatternAction(
     };
   }
 
-  let content: string;
-  if (params.summary) {
-    content = formatPatternSummary(params.pattern, relScope, matches, maxResults);
-  } else {
-    content = formatPatternResults(params.pattern, relScope, matches, maxResults);
-  }
+  const content = params.summary
+    ? formatPatternSummary(params.pattern, relScope, matches, maxResults)
+    : formatPatternResults(params.pattern, relScope, matches, maxResults);
 
   const details: SearchDetails = {
     confidence: "heuristic",
@@ -97,6 +158,105 @@ export async function executePatternAction(
   return { content, details: { type: "search" as const, data: details } };
 }
 
+function formatStructuredEmptyState(
+  pattern: string,
+  kind: "definition" | "export" | "import",
+  relScope: string,
+  result: StructuredPatternResult,
+): string {
+  const lines = [`No ${kind} matches found for \`${pattern}\` in \`${relScope}\`.`];
+  const partialWarning = formatPartialStructuredWarning(result);
+  if (partialWarning) {
+    lines.push("");
+    lines.push(partialWarning);
+  }
+  return lines.join("\n");
+}
+
+function formatStructuredMatches(
+  pattern: string,
+  kind: "definition" | "export" | "import",
+  relScope: string,
+  result: StructuredPatternResult,
+): string {
+  const grouped = new Map<string, StructuredMatch[]>();
+  for (const match of result.matches) {
+    const group = grouped.get(match.file) ?? [];
+    group.push(match);
+    grouped.set(match.file, group);
+  }
+
+  const kindLabel =
+    kind === "definition" ? "Definitions" : kind === "export" ? "Exports" : "Imports";
+  const lines: string[] = [];
+  lines.push(`# Pattern ${kindLabel}: \`${pattern}\``);
+  lines.push("");
+  lines.push(
+    `**${result.matches.length} match${result.matches.length !== 1 ? "es" : ""}** across **${grouped.size} file${grouped.size !== 1 ? "s" : ""}** in \`${relScope}\``,
+  );
+  const partialWarning = formatPartialStructuredWarning(result);
+  if (partialWarning) {
+    lines.push(partialWarning);
+  }
+  lines.push("");
+
+  if (kind === "definition" || kind === "export") {
+    addDuplicateSummary(lines, result.matches);
+  }
+
+  for (const [file, fileMatches] of grouped) {
+    lines.push(`### ${file}`);
+    for (const match of fileMatches.slice(0, 8)) {
+      lines.push(`- \`${match.name}\` (${match.kind}) L${match.line}`);
+    }
+    if (fileMatches.length > 8) {
+      lines.push(`- _+${fileMatches.length - 8} more in this file_`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function formatPartialStructuredWarning(result: StructuredPatternResult): string | null {
+  if (!result.partialReason || result.omittedCount <= 0) return null;
+
+  if (result.partialReason === "timeout") {
+    return `_Partial structured results — scan timed out with +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted. Narrow \`path\` or \`pattern\` for complete coverage._`;
+  }
+
+  return `_Partial structured results — +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted after reaching the structured scan cap. Narrow \`path\` or \`pattern\` for complete coverage._`;
+}
+
+function addDuplicateSummary(lines: string[], matches: StructuredMatch[]): void {
+  const byName = new Map<string, Set<string>>();
+  for (const match of matches) {
+    const files = byName.get(match.name) ?? new Set<string>();
+    files.add(match.file);
+    byName.set(match.name, files);
+  }
+
+  const duplicates = [...byName.entries()]
+    .map(([name, files]) => ({ name, files: [...files].sort((a, b) => a.localeCompare(b)) }))
+    .filter((entry) => entry.files.length > 1)
+    .sort((a, b) => b.files.length - a.files.length || a.name.localeCompare(b.name));
+
+  if (duplicates.length === 0) return;
+
+  lines.push("## Duplicate Definitions");
+  for (const duplicate of duplicates.slice(0, 8)) {
+    lines.push(
+      `- \`${duplicate.name}\` — defined in ${duplicate.files.length} files: ${duplicate.files
+        .map((file) => `\`${file}\``)
+        .join(", ")}`,
+    );
+  }
+  if (duplicates.length > 8) {
+    lines.push(`- _+${duplicates.length - 8} more duplicates_`);
+  }
+  lines.push("");
+}
+
 function getRegexMatches(options: {
   pattern: string;
   scopePath: string;