@mrclrchtr/supi-code-intelligence 0.1.0

package/src/code-intelligence.ts

@@ -0,0 +1,122 @@
+// Code Intelligence extension entry point — registers the `code_intel` tool with pi.
+// Provides architecture briefs, caller/callee analysis, impact assessment, and pattern search.
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { BeforeAgentStartEventResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { buildArchitectureModel } from "./architecture.ts";
+import { generateOverview } from "./brief.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
+import { type CodeIntelAction, executeAction } from "./tool-actions.ts";
+
+const OVERVIEW_CUSTOM_TYPE = "code-intelligence-overview";
+
+const CodeIntelActionEnum = StringEnum([
+  "brief",
+  "callers",
+  "callees",
+  "implementations",
+  "affected",
+  "pattern",
+  "index",
+] as const);
+
+/**
+ * Register the `code_intel` tool and inject a lightweight architecture overview
+ * once per session.
+ */
+export default function codeIntelligenceExtension(pi: ExtensionAPI) {
+  let hasInjectedOverview = false;
+
+  pi.on("session_start", (_event, ctx) => {
+    hasInjectedOverview = false;
+
+    // Scan active branch for existing overview to avoid duplicates on reload/resume
+    const branch = ctx.sessionManager.getBranch();
+    for (const entry of branch) {
+      if (entry.type === "custom_message" && entry.customType === OVERVIEW_CUSTOM_TYPE) {
+        hasInjectedOverview = true;
+        break;
+      }
+    }
+  });
+
+  pi.on(
+    "before_agent_start",
+    async (_event, ctx): Promise<BeforeAgentStartEventResult | undefined> => {
+      if (hasInjectedOverview) return;
+      hasInjectedOverview = true;
+
+      const model = await buildArchitectureModel(ctx.cwd);
+      if (!model || model.modules.length === 0) return;
+
+      const overview = generateOverview(model);
+      if (!overview) return;
+
+      return {
+        message: {
+          customType: OVERVIEW_CUSTOM_TYPE,
+          display: false,
+          content: overview,
+        },
+      };
+    },
+  );
+
+  pi.registerTool({
+    name: "code_intel",
+    label: "Code Intelligence",
+    description: toolDescription,
+    parameters: Type.Object({
+      action: CodeIntelActionEnum,
+      path: Type.Optional(
+        Type.String({ description: "Scope or focus path (package, directory, or file)" }),
+      ),
+      file: Type.Optional(
+        Type.String({ description: "Anchored target file (use with line/character)" }),
+      ),
+      line: Type.Optional(Type.Number({ description: "1-based line number for anchored target" })),
+      character: Type.Optional(
+        Type.Number({ description: "1-based character column (UTF-16) for anchored target" }),
+      ),
+      symbol: Type.Optional(
+        Type.String({ description: "Symbol name for discovery-based resolution" }),
+      ),
+      pattern: Type.Optional(
+        Type.String({
+          description: "Text search pattern (pattern action only; literal by default)",
+        }),
+      ),
+      regex: Type.Optional(
+        Type.Boolean({
+          description: "Use regex semantics for pattern action (default: false, literal search)",
+        }),
+      ),
+      kind: Type.Optional(Type.String({ description: "Symbol kind filter for discovery" })),
+      exportedOnly: Type.Optional(
+        Type.Boolean({ description: "Limit discovery to exported symbols" }),
+      ),
+      maxResults: Type.Optional(Type.Number({ description: "Maximum results to return" })),
+      contextLines: Type.Optional(Type.Number({ description: "Context lines around matches" })),
+      summary: Type.Optional(
+        Type.Boolean({
+          description:
+            "Aggregate counts by directory instead of line-level matches (pattern action only)",
+        }),
+      ),
+    }),
+    promptSnippet,
+    promptGuidelines,
+    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const { content, details } = await executeAction(
+        params as unknown as { action: CodeIntelAction } & Record<string, unknown>,
+        { cwd: ctx.cwd },
+      );
+      return {
+        content: [{ type: "text", text: content }],
+        details,
+      };
+    },
+  });
+}

package/src/git-context.ts

@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+
+function execGit(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5000,
+  });
+}
+
+export interface GitContext {
+  branch: string;
+  dirtyFiles: string[];
+  lastCommitMessage: string | null;
+}
+
+export function gatherGitContext(cwd: string): GitContext | null {
+  try {
+    const branch = execGit(cwd, ["branch", "--show-current"]).trim();
+
+    const status = execGit(cwd, ["status", "--porcelain"]).trim();
+
+    const dirtyFiles = status
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim());
+
+    let lastCommitMessage: string | null = null;
+    try {
+      lastCommitMessage = execGit(cwd, ["log", "-1", "--format=%s"]).trim();
+    } catch {
+      // No commits yet
+    }
+
+    return { branch, dirtyFiles, lastCommitMessage };
+  } catch {
+    return null;
+  }
+}
+
+export function formatGitContext(ctx: GitContext): string {
+  const lines: string[] = [];
+  lines.push("## Git Context");
+  lines.push("");
+  lines.push(`Branch: \`${ctx.branch}\``);
+  if (ctx.dirtyFiles.length > 0) {
+    lines.push(
+      `Uncommitted: ${ctx.dirtyFiles.length} file${ctx.dirtyFiles.length !== 1 ? "s" : ""}`,
+    );
+    for (const f of ctx.dirtyFiles.slice(0, 5)) {
+      lines.push(`- \`${f}\``);
+    }
+    if (ctx.dirtyFiles.length > 5) {
+      lines.push(`- _+${ctx.dirtyFiles.length - 5} more_`);
+    }
+  } else {
+    lines.push("Working tree clean.");
+  }
+  if (ctx.lastCommitMessage) {
+    lines.push(`Last commit: \`${ctx.lastCommitMessage}\``);
+  }
+  lines.push("");
+  return lines.join("\n");
+}

package/src/guidance.ts

@@ -0,0 +1,39 @@
+// Prompt guidance and tool description for the code_intel tool.
+
+export const toolDescription = `Code intelligence tool — architecture briefs, semantic relationships, impact analysis, structured text search, and project indexing.
+
+Actions:
+- brief: Architecture overview or focused brief for a project, package, directory, file, or anchored symbol
+- callers: Find call sites for a symbol (LSP-first, heuristic text-search fallback)
+- callees: Best-effort outgoing calls from a symbol (structural tree-sitter analysis across supported grammars)
+- implementations: Find concrete implementations of an interface or abstract type
+- affected: Blast-radius analysis — direct references, downstream dependents, risk level, likely tests
+- pattern: Bounded text search with grouped matches, context lines, scope enforcement, and regex opt-in via \`regex: true\`
+- index: Factual project map — file counts by language, top-level directory tree, landmark config files
+
+Coordinates are 1-based (line, character) with UTF-16 character columns, matching lsp and tree_sitter conventions.
+Relative paths resolve from the session working directory. A leading @ on path/file is stripped automatically.
+
+Examples:
+  { "action": "brief" }
+  { "action": "brief", "path": "packages/supi-lsp/" }
+  { "action": "brief", "file": "packages/supi-lsp/lsp.ts", "line": 42, "character": 7 }
+  { "action": "callers", "symbol": "registerSettings", "path": "packages/supi-core/" }
+  { "action": "callees", "file": "src/handler.ts", "line": 88, "character": 12 }
+  { "action": "implementations", "symbol": "SessionLspService", "path": "packages/" }
+  { "action": "affected", "file": "packages/supi-core/index.ts", "line": 12, "character": 8 }
+  { "action": "pattern", "pattern": "registerSettings", "path": "packages/", "maxResults": 10 }
+  { "action": "pattern", "pattern": "register(Settings|Config)", "path": "packages/", "regex": true, "maxResults": 10 }`;
+
+export const promptSnippet =
+  "Use the code_intel tool for architecture orientation, semantic relationships, impact analysis, and structured search before broad file reads.";
+
+export const promptGuidelines = [
+  "Use `code_intel brief` before editing an unfamiliar package, directory, or file to get architecture context and reduce blind reads.",
+  "Use `code_intel affected` before changing exported APIs, shared helpers, config surfaces, or cross-package contracts to check blast radius and risk.",
+  "Use `code_intel callers` before modifying a function to verify all call sites; use `callees` and `implementations` for dependency and interface analysis.",
+  "Use `code_intel pattern` for bounded, scope-aware text search when the question is textual rather than semantic; it treats patterns as literal strings by default and supports `regex: true` when needed.",
+  "Use `code_intel index` for a factual project map (file counts, directory structure, landmark files) when you need to orient yourself in a new codebase.",
+  "After `code_intel` narrows the target, use raw `lsp` and `tree_sitter` tools for precise drill-down on exact symbols, types, or AST nodes.",
+  "Do not prefer `code_intel` over direct file reads or lower-level tools for trivial, already-localized edits or exact symbol/AST drill-down tasks.",
+];

package/src/index.ts

@@ -0,0 +1,28 @@
+// Package root exports for @mrclrchtr/supi-code-intelligence.
+// Peer extensions can import these APIs for programmatic access.
+
+export type { ArchitectureModel, DependencyEdge, ModuleInfo } from "./architecture.ts";
+export {
+  buildArchitectureModel,
+  findModuleForPath,
+  getDependencies,
+  getDependents,
+} from "./architecture.ts";
+
+export { generateFocusedBrief, generateOverview, generateProjectBrief } from "./brief.ts";
+export type { ResolvedTarget, TargetResolutionResult } from "./target-resolution.ts";
+export {
+  normalizePath,
+  resolveAnchoredTarget,
+  resolveSymbolTarget,
+  toZeroBased,
+} from "./target-resolution.ts";
+
+export type {
+  AffectedDetails,
+  BriefDetails,
+  CodeIntelResult,
+  ConfidenceMode,
+  DisambiguationCandidate,
+  SearchDetails,
+} from "./types.ts";

package/src/resolve-target.ts

@@ -0,0 +1,104 @@
+import {
+  type ResolvedTarget,
+  resolveAnchoredTarget,
+  resolveSymbolTarget,
+} from "./target-resolution.ts";
+import type { ActionParams } from "./tool-actions.ts";
+
+/**
+ * Resolve a target from action params. Returns either a ResolvedTarget
+ * or a string error/disambiguation message to return directly.
+ */
+export async function resolveTarget(
+  params: ActionParams,
+  cwd: string,
+): Promise<ResolvedTarget | string> {
+  if (!params.file && !params.symbol) {
+    return "**Error:** Semantic actions require either anchored coordinates (`file`, `line`, `character`) or a `symbol` for discovery.";
+  }
+
+  if (params.file && params.line != null && params.character != null) {
+    return resolveAnchored(params.file, params.line, params.character, cwd);
+  }
+
+  if (params.file && !params.symbol) {
+    return "**Error:** Semantic actions with `file` require `line` and `character`, or provide `symbol` for discovery.";
+  }
+
+  if (params.symbol) {
+    return resolveBySymbol(params, cwd);
+  }
+
+  return "**Error:** Could not resolve target.";
+}
+
+function resolveAnchored(
+  file: string,
+  line: number,
+  character: number,
+  cwd: string,
+): ResolvedTarget | string {
+  const result = resolveAnchoredTarget(file, line, character, cwd);
+  if (result.kind === "error") return result.message;
+  if (result.kind === "resolved") return result.target;
+  return "**Error:** Unexpected disambiguation for anchored target.";
+}
+
+async function resolveBySymbol(
+  params: ActionParams,
+  cwd: string,
+): Promise<ResolvedTarget | string> {
+  const result = await resolveSymbolTarget(params.symbol ?? "", cwd, {
+    path: params.path,
+    kind: params.kind,
+    exportedOnly: params.exportedOnly,
+  });
+
+  if (result.kind === "error") return result.message;
+  if (result.kind === "resolved") return result.target;
+
+  return formatDisambiguation(params, result);
+}
+
+function formatDisambiguation(
+  params: ActionParams,
+  result: {
+    candidates: Array<{
+      name: string;
+      kind: string | null;
+      container: string | null;
+      file: string;
+      line: number;
+      character: number;
+      rank: number;
+    }>;
+    omittedCount: number;
+  },
+): string {
+  const lines: string[] = [];
+  lines.push(`# Disambiguation needed for \`${params.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: \`{ "action": "${params.action}", "file": "${first.file}", "line": ${first.line}, "character": ${first.character} }\``,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/search-helpers.ts

@@ -0,0 +1,283 @@
+// Shared search helpers for code_intel actions.
+
+import { execFileSync } from "node:child_process";
+import * as path from "node:path";
+
+const LOW_SIGNAL_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".pnpm",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  "coverage",
+  ".turbo",
+  ".cache",
+  "__pycache__",
+  ".tsbuildinfo",
+]);
+
+/** Check if a file path contains an obviously low-signal directory segment. */
+export function isLowSignalPath(filePath: string): boolean {
+  const segments = filePath.split(path.sep);
+  return segments.some((s) => LOW_SIGNAL_DIRS.has(s));
+}
+
+/** Convert a file:// URI to a file path, matching the normalization in supi-lsp. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}
+
+/** Check whether a resolved file path is inside the current project (within cwd, not under node_modules or .pnpm). */
+export function isInProjectPath(filePath: string, cwd: string): boolean {
+  const relativePath = path.relative(cwd, path.resolve(cwd, filePath));
+  if (relativePath.startsWith(`..${path.sep}`) || relativePath === "..") return false;
+  const normalized = relativePath.replaceAll("\\", "/");
+  return !(
+    normalized.includes("/node_modules/") ||
+    normalized.startsWith("node_modules/") ||
+    normalized.includes("/.pnpm/") ||
+    normalized.startsWith(".pnpm/")
+  );
+}
+
+/** Escape regex special characters. */
+export function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Normalize a file/path value: strip leading @, resolve relative to cwd. */
+export function normalizePath(input: string, cwd: string): string {
+  const stripped = input.startsWith("@") ? input.slice(1) : input;
+  return path.resolve(cwd, stripped);
+}
+
+export interface RgMatch {
+  file: string;
+  line: number;
+  text: string;
+  /** Context lines surrounding this match (from -C flag). */
+  context?: Array<{ line: number; text: string }>;
+}
+
+/** Result of a ripgrep invocation for callers that need both matches and execution errors. */
+export interface RipgrepRunResult {
+  /** Parsed ripgrep matches, if any. */
+  matches: RgMatch[];
+  /** Non-no-match ripgrep execution error text, such as invalid regex syntax. */
+  error?: string;
+}
+
+/**
+ * Run ripgrep with JSON output and parse matches, filtering low-signal paths.
+ *
+ * This helper preserves the historical behavior used by most `code_intel`
+ * actions: any ripgrep execution failure is treated like an empty match set.
+ * Call `runRipgrepDetailed()` when a caller needs to surface regex parse errors
+ * or other non-no-match failures to the agent.
+ */
+export function runRipgrep(
+  pattern: string,
+  scopePath: string,
+  cwd: string,
+  opts?: { maxMatches?: number; contextLines?: number; filterLowSignal?: boolean },
+): RgMatch[] {
+  return runRipgrepDetailed(pattern, scopePath, cwd, opts).matches;
+}
+
+/**
+ * Run ripgrep and preserve non-no-match execution errors for callers that need
+ * to distinguish invalid regex syntax from a genuine empty search result.
+ */
+export function runRipgrepDetailed(
+  pattern: string,
+  scopePath: string,
+  cwd: string,
+  opts?: { maxMatches?: number; contextLines?: number; filterLowSignal?: boolean },
+): RipgrepRunResult {
+  const filter = opts?.filterLowSignal ?? true;
+
+  try {
+    const result = execFileSync("rg", buildRipgrepArgs(pattern, scopePath, opts), {
+      encoding: "utf-8",
+      cwd,
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    return { matches: parseRgJson(result, filter) };
+  } catch (err: unknown) {
+    return handleRipgrepError(err, filter);
+  }
+}
+
+function buildRipgrepArgs(
+  pattern: string,
+  scopePath: string,
+  opts?: { maxMatches?: number; contextLines?: number },
+): string[] {
+  const args = ["--json", "-m", String(opts?.maxMatches ?? 30)];
+  if ((opts?.contextLines ?? 0) > 0) {
+    args.push("-C", String(opts?.contextLines ?? 0));
+  }
+  args.push("-e", pattern, scopePath);
+  return args;
+}
+
+function handleRipgrepError(err: unknown, filterLowSignal: boolean): RipgrepRunResult {
+  if (!isExecError(err)) {
+    return { matches: [] };
+  }
+
+  const stdout = typeof err.stdout === "string" ? err.stdout : "";
+  const stderr = typeof err.stderr === "string" ? err.stderr.trim() : "";
+  const matches = stdout ? parseRgJson(stdout, filterLowSignal) : [];
+
+  if (err.status === 1) {
+    return { matches };
+  }
+
+  return {
+    matches,
+    ...(stderr ? { error: stderr } : {}),
+  };
+}
+
+function isExecError(err: unknown): err is { status: number; stdout?: unknown; stderr?: unknown } {
+  return typeof err === "object" && err !== null && "status" in err;
+}
+
+interface RawRgEvent {
+  type: string;
+  data?: {
+    path?: { text: string };
+    line_number?: number;
+    lines?: { text: string };
+  };
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: JSON ripgrep output parsing with context line collection
+function parseRgJson(output: string, filterLowSignal: boolean): RgMatch[] {
+  const matches: RgMatch[] = [];
+  // Pending context lines that precede the next match
+  let pendingContext: Array<{ line: number; text: string }> = [];
+
+  for (const line of output.split("\n")) {
+    if (!line.trim()) continue;
+    let parsed: RawRgEvent;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (parsed.type === "context" && parsed.data) {
+      const lineNum = parsed.data.line_number;
+      const text = (parsed.data.lines?.text ?? "").trim();
+      if (lineNum) pendingContext.push({ line: lineNum, text });
+      continue;
+    }
+
+    if (parsed.type === "match" && parsed.data) {
+      const filePath = parsed.data.path?.text;
+      const lineNum = parsed.data.line_number;
+      const text = (parsed.data.lines?.text ?? "").trim();
+      if (filePath && lineNum) {
+        // Split pendingContext: lines before this match are "before" context,
+        // lines from before this match line that trail the previous match stay with it.
+        const beforeCtx = pendingContext.filter((c) => c.line < lineNum);
+        const trailingCtx = pendingContext.filter((c) => c.line >= lineNum);
+
+        // Attach trailing context from previous match to the last accepted match
+        if (beforeCtx.length > 0 && matches.length > 0) {
+          const prev = matches[matches.length - 1];
+          const prevTrailing = beforeCtx.filter((c) => c.line > prev.line);
+          if (prevTrailing.length > 0) {
+            prev.context = [...(prev.context ?? []), ...prevTrailing];
+          }
+        }
+
+        if (filterLowSignal && isLowSignalPath(filePath)) {
+          pendingContext = [];
+          continue;
+        }
+
+        const match: RgMatch = { file: filePath, line: lineNum, text };
+        // Leading context: lines just before this match
+        const leadingCtx =
+          matches.length > 0
+            ? beforeCtx.filter(
+                (c) => c.line <= lineNum && c.line > (matches[matches.length - 1]?.line ?? 0),
+              )
+            : beforeCtx;
+        if (leadingCtx.length > 0) {
+          match.context = leadingCtx;
+        }
+        // Also include any pending context at/after this match's line (trailing from rg ordering)
+        pendingContext = trailingCtx;
+        matches.push(match);
+      } else {
+        pendingContext = [];
+      }
+    }
+  }
+
+  // Attach any trailing context lines to the last match
+  if (pendingContext.length > 0 && matches.length > 0) {
+    const last = matches[matches.length - 1];
+    last.context = [...(last.context ?? []), ...pendingContext];
+  }
+
+  return matches;
+}
+
+/**
+ * Minimal interface for a reference-like object with a URI and range start.
+ * Used by {@link filterOutDeclaration} to avoid coupling to a specific LspRef type.
+ */
+export interface HasLspPosition {
+  uri: string;
+  range: { start: { line: number; character: number } };
+}
+
+/**
+ * Filter out the declaration/definition location from LSP references.
+ * LSP's `textDocument/references` includes the declaration by default;
+ * for callers/affected analysis, the declaration is not a call site or affected reference.
+ *
+ * Uses {@link uriToFile} for robust URI-to-path conversion.
+ */
+export function filterOutDeclaration<T extends HasLspPosition>(
+  refs: T[],
+  targetFile: string,
+  targetPos: { line: number; character: number },
+): T[] {
+  return refs.filter((ref) => {
+    const filePath = uriToFile(ref.uri);
+    if (filePath !== targetFile) return true;
+    const start = ref.range.start;
+    return start.line !== targetPos.line || start.character !== targetPos.character;
+  });
+}
+
+/** Group matches by file. */
+export function groupByFile(matches: RgMatch[]): Map<string, RgMatch[]> {
+  const byFile = new Map<string, RgMatch[]>();
+  for (const m of matches) {
+    const group = byFile.get(m.file) ?? [];
+    group.push(m);
+    byFile.set(m.file, group);
+  }
+  return byFile;
+}