@mrclrchtr/supi-code-intelligence 0.1.0 → 1.1.2

package/src/prioritization-signals.ts

@@ -0,0 +1,188 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getSessionLspService } from "@mrclrchtr/supi-lsp";
+
+export interface PrioritySignalsSummary {
+  diagnosticsCount: number;
+  lowCoverageCount: number;
+  unusedCount: number;
+  warnings: string[];
+}
+
+interface LoadedSignals {
+  diagnostics: Array<{ file: string; total: number; errors: number; warnings: number }>;
+  coverageByFile: Map<string, number>;
+  unusedFiles: Set<string>;
+  unusedExports: Array<{ file: string; name: string }>;
+}
+
+export function summarizePrioritySignalsForFiles(
+  cwd: string,
+  files: Iterable<string>,
+): PrioritySignalsSummary | null {
+  const loaded = loadPrioritizationSignals(cwd);
+  const relevantFiles = new Set([...files].map((file) => path.resolve(cwd, file)));
+  if (relevantFiles.size === 0) return null;
+
+  const warnings: string[] = [];
+
+  const matchingDiagnostics = loaded.diagnostics.filter((entry) =>
+    relevantFiles.has(path.resolve(entry.file)),
+  );
+  const diagnosticsCount = matchingDiagnostics.reduce((sum, entry) => sum + entry.total, 0);
+  for (const entry of matchingDiagnostics.slice(0, 3)) {
+    warnings.push(
+      `Diagnostics: \`${path.relative(cwd, entry.file)}\` (${entry.total} total${entry.errors > 0 ? `, ${entry.errors} errors` : ""}${entry.warnings > 0 ? `, ${entry.warnings} warnings` : ""})`,
+    );
+  }
+
+  const lowCoverage = [...loaded.coverageByFile.entries()]
+    .filter(([file, pct]) => relevantFiles.has(path.resolve(file)) && pct < 50)
+    .sort((a, b) => a[1] - b[1]);
+  for (const [file, pct] of lowCoverage.slice(0, 3)) {
+    warnings.push(`Low coverage: \`${path.relative(cwd, file)}\` (${pct.toFixed(0)}%)`);
+  }
+
+  const unusedFileMatches = [...loaded.unusedFiles]
+    .filter((file) => relevantFiles.has(path.resolve(file)))
+    .sort((a, b) => a.localeCompare(b));
+  for (const file of unusedFileMatches.slice(0, 3)) {
+    warnings.push(`Unused file: \`${path.relative(cwd, file)}\``);
+  }
+
+  const unusedExportMatches = loaded.unusedExports
+    .filter((entry) => relevantFiles.has(path.resolve(entry.file)))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of unusedExportMatches.slice(0, 3)) {
+    warnings.push(`Unused export: \`${entry.name}\` in \`${path.relative(cwd, entry.file)}\``);
+  }
+
+  const summary: PrioritySignalsSummary = {
+    diagnosticsCount,
+    lowCoverageCount: lowCoverage.length,
+    unusedCount: unusedFileMatches.length + unusedExportMatches.length,
+    warnings,
+  };
+
+  return summary.diagnosticsCount > 0 || summary.lowCoverageCount > 0 || summary.unusedCount > 0
+    ? summary
+    : null;
+}
+
+export function loadPrioritizationSignals(cwd: string): LoadedSignals {
+  return {
+    diagnostics: loadDiagnostics(cwd),
+    coverageByFile: loadCoverageSummary(cwd),
+    unusedFiles: loadUnusedFiles(cwd),
+    unusedExports: loadUnusedExports(cwd),
+  };
+}
+
+export function appendPrioritySignalsSection(
+  lines: string[],
+  summary: PrioritySignalsSummary | null,
+): void {
+  if (!summary || summary.warnings.length === 0) return;
+  lines.push("## Priority Signals");
+  for (const warning of summary.warnings.slice(0, 6)) {
+    lines.push(`- ${warning}`);
+  }
+  lines.push("");
+}
+
+function loadDiagnostics(
+  cwd: string,
+): Array<{ file: string; total: number; errors: number; warnings: number }> {
+  const lspState = getSessionLspService(cwd);
+  if (lspState.kind !== "ready") return [];
+
+  return lspState.service.getOutstandingDiagnosticSummary(2).map((entry) => ({
+    file: path.resolve(cwd, entry.file),
+    total: entry.total,
+    errors: entry.errors,
+    warnings: entry.warnings,
+  }));
+}
+
+function loadCoverageSummary(cwd: string): Map<string, number> {
+  const coveragePath = path.join(cwd, "coverage", "coverage-summary.json");
+  if (!fs.existsSync(coveragePath)) return new Map();
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(coveragePath, "utf-8")) as Record<string, unknown>;
+    const map = new Map<string, number>();
+    for (const [file, value] of Object.entries(parsed)) {
+      if (file === "total" || typeof value !== "object" || value === null) continue;
+      const linesPct = getPct(value, "lines");
+      const statementsPct = getPct(value, "statements");
+      const pct = Math.min(linesPct ?? 100, statementsPct ?? 100);
+      map.set(path.resolve(cwd, file), pct);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+function loadUnusedFiles(cwd: string): Set<string> {
+  const parsed = loadKnipJson(cwd);
+  const values = Array.isArray(parsed?.files) ? parsed.files : [];
+  const files = values
+    .map((value) => toPathString(value))
+    .filter((value): value is string => Boolean(value))
+    .map((file) => path.resolve(cwd, file));
+  return new Set(files);
+}
+
+function loadUnusedExports(cwd: string): Array<{ file: string; name: string }> {
+  const parsed = loadKnipJson(cwd);
+  const values = Array.isArray(parsed?.exports) ? parsed.exports : [];
+  const exports: Array<{ file: string; name: string }> = [];
+
+  for (const value of values) {
+    if (typeof value === "string") {
+      exports.push({ file: path.resolve(cwd, value), name: path.basename(value) });
+      continue;
+    }
+    if (typeof value !== "object" || value === null) continue;
+    const record = value as Record<string, unknown>;
+    const file = toPathString(record.file) ?? toPathString(record.path);
+    const name = typeof record.name === "string" ? record.name : null;
+    if (file && name) {
+      exports.push({ file: path.resolve(cwd, file), name });
+    }
+  }
+
+  return exports;
+}
+
+function loadKnipJson(cwd: string): Record<string, unknown> | null {
+  const knipPath = path.join(cwd, "knip.json");
+  if (!fs.existsSync(knipPath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(knipPath, "utf-8"));
+    return typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function getPct(value: object, key: string): number | null {
+  const candidate = (value as Record<string, unknown>)[key];
+  if (typeof candidate !== "object" || candidate === null) return null;
+  const pct = (candidate as Record<string, unknown>).pct;
+  return typeof pct === "number" ? pct : null;
+}
+
+function toPathString(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (typeof value !== "object" || value === null) return null;
+  const record = value as Record<string, unknown>;
+  return typeof record.file === "string"
+    ? record.file
+    : typeof record.path === "string"
+      ? record.path
+      : null;
+}

package/src/resolve-target.ts

@@ -1,18 +1,20 @@
 import {
   type ResolvedTarget,
+  type ResolvedTargetGroup,
   resolveAnchoredTarget,
+  resolveFileTargetGroup,
   resolveSymbolTarget,
 } from "./target-resolution.ts";
 import type { ActionParams } from "./tool-actions.ts";
 
 /**
- * Resolve a target from action params. Returns either a ResolvedTarget
+ * Resolve a target from action params. Returns either a target, a file-level target group,
  * or a string error/disambiguation message to return directly.
  */
 export async function resolveTarget(
   params: ActionParams,
   cwd: string,
-): Promise<ResolvedTarget | string> {
+): Promise<ResolvedTarget | ResolvedTargetGroup | string> {
   if (!params.file && !params.symbol) {
     return "**Error:** Semantic actions require either anchored coordinates (`file`, `line`, `character`) or a `symbol` for discovery.";
   }
@@ -22,7 +24,7 @@ export async function resolveTarget(
   }
 
   if (params.file && !params.symbol) {
-    return "**Error:** Semantic actions with `file` require `line` and `character`, or provide `symbol` for discovery.";
+    return resolveByFile(params.file, cwd);
   }
 
   if (params.symbol) {
@@ -44,6 +46,12 @@ function resolveAnchored(
   return "**Error:** Unexpected disambiguation for anchored target.";
 }
 
+async function resolveByFile(file: string, cwd: string): Promise<ResolvedTargetGroup | string> {
+  const result = await resolveFileTargetGroup(file, cwd);
+  if (result.kind === "error") return result.message;
+  return result.group;
+}
+
 async function resolveBySymbol(
   params: ActionParams,
   cwd: string,

package/src/search-helpers.ts

@@ -136,6 +136,15 @@ function buildRipgrepArgs(
 }
 
 function handleRipgrepError(err: unknown, filterLowSignal: boolean): RipgrepRunResult {
+  // ENOENT means rg is not installed — surface a clear error instead of silent empty results
+  if (isCodeError(err, "ENOENT")) {
+    return {
+      matches: [],
+      error:
+        "ripgrep (rg) is not available. Install it (e.g., `apt install ripgrep` or `brew install ripgrep`).",
+    };
+  }
+
   if (!isExecError(err)) {
     return { matches: [] };
   }
@@ -158,6 +167,15 @@ function isExecError(err: unknown): err is { status: number; stdout?: unknown; s
   return typeof err === "object" && err !== null && "status" in err;
 }
 
+function isCodeError(err: unknown, code: string): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    "code" in err &&
+    (err as { code: unknown }).code === code
+  );
+}
+
 interface RawRgEvent {
   type: string;
   data?: {

package/src/semantic-action-helpers.ts

@@ -0,0 +1,28 @@
+import type { ResolvedTarget, ResolvedTargetGroup } from "./target-resolution.ts";
+import type { ConfidenceMode } from "./types.ts";
+
+interface FileLineRef {
+  file: string;
+  line: number;
+}
+
+export function isResolvedTargetGroup(
+  target: ResolvedTarget | ResolvedTargetGroup,
+): target is ResolvedTargetGroup {
+  return "targets" in target;
+}
+
+export function highestConfidence(confidences: ConfidenceMode[]): ConfidenceMode {
+  if (confidences.includes("semantic")) return "semantic";
+  if (confidences.includes("structural")) return "structural";
+  if (confidences.includes("heuristic")) return "heuristic";
+  return "unavailable";
+}
+
+export function dedupeFileLineRefs<T extends FileLineRef>(refs: T[]): T[] {
+  const deduped = new Map<string, T>();
+  for (const ref of refs) {
+    deduped.set(`${ref.file}:${ref.line}`, ref);
+  }
+  return [...deduped.values()];
+}

package/src/target-resolution.ts

@@ -1,11 +1,14 @@
 // 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
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core";
 import { getSessionLspService, type Position, type SessionLspService } from "@mrclrchtr/supi-lsp";
+import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
 import { escapeRegex, normalizePath } from "./search-helpers.ts";
+import { highestConfidence } from "./semantic-action-helpers.ts";
 import type { ConfidenceMode, DisambiguationCandidate } from "./types.ts";
 
 export interface ResolvedTarget {
@@ -20,6 +23,13 @@ export interface ResolvedTarget {
   confidence: ConfidenceMode;
 }
 
+export interface ResolvedTargetGroup {
+  file: string;
+  displayName: string;
+  targets: ResolvedTarget[];
+  confidence: ConfidenceMode;
+}
+
 export type TargetResolutionResult =
   | { kind: "resolved"; target: ResolvedTarget }
   | { kind: "disambiguation"; candidates: DisambiguationCandidate[]; omittedCount: number }
@@ -73,6 +83,52 @@ export function resolveAnchoredTarget(
   };
 }
 
+/**
+ * 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.
+ */
+export async function resolveFileTargetGroup(
+  file: string,
+  cwd: string,
+): 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}\`. Try \`code_intel pattern\` for 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.",
+    };
+  }
+
+  return {
+    kind: "resolved",
+    group: {
+      file: resolvedFile,
+      displayName: relPath,
+      targets,
+      confidence: highestConfidence(targets.map((target) => target.confidence)),
+    },
+  };
+}
+
 /**
  * Resolve a target from symbol discovery — finds matching declarations.
  * Uses LSP workspace symbols when available, falls back to Tree-sitter/text search.
@@ -271,6 +327,165 @@ async function resolveSymbolViaSearch(
   }
 }
 
+async function resolveFileTargetsViaLsp(
+  resolvedFile: string,
+  cwd: string,
+  structuralTargets: ResolvedTarget[] | null,
+): Promise<ResolvedTarget[] | null> {
+  const lspState = getSessionLspService(cwd);
+  if (lspState.kind !== "ready") return null;
+
+  const symbols = await lspState.service.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> {
+  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
+  try {
+    tsSession = createTreeSitterSession(cwd);
+    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;
+  } finally {
+    tsSession?.dispose();
+  }
+}
+
+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(

package/src/tool-actions.ts

@@ -105,5 +105,13 @@ function validateParams(params: ActionParams, cwd: string): string | null {
     return "**Error:** `line` and `character` require `file`.";
   }
 
+  if (
+    params.action === "pattern" &&
+    params.kind &&
+    !new Set(["definition", "export", "import"]).has(params.kind)
+  ) {
+    return "**Error:** `pattern` action `kind` must be one of `definition`, `export`, or `import`.";
+  }
+
   return null;
 }

package/src/types.ts

@@ -1,5 +1,7 @@
 // Shared types for code intelligence tool results and metadata.
 
+import type { PrioritySignalsSummary } from "./prioritization-signals.ts";
+
 /** Confidence vocabulary for result labeling. */
 export type ConfidenceMode = "semantic" | "structural" | "heuristic" | "unavailable";
 
@@ -12,6 +14,7 @@ export interface BriefDetails {
   dependencySummary: { moduleCount: number; edgeCount: number } | null;
   omittedCount: number;
   nextQueries: string[];
+  prioritySignals?: PrioritySignalsSummary | null;
 }
 
 /** Structured details metadata for relationship and pattern results. */
@@ -33,6 +36,7 @@ export interface AffectedDetails {
   likelyTests: string[];
   omittedCount: number;
   nextQueries: string[];
+  prioritySignals?: PrioritySignalsSummary | null;
 }
 
 /** Disambiguation candidate for ambiguous symbol resolution. */