@mrclrchtr/supi-code-intelligence 0.1.0 → 1.1.2

package/src/brief-focused.ts

@@ -1,10 +1,15 @@
 // Focused brief generation — directory and file briefs.
+// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: focused brief formatting and recursive directory summarization are kept together to share local helpers
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ArchitectureModel } from "./architecture.ts";
 import { findModuleForPath, getDependencies, getDependents } from "./architecture.ts";
 import { formatGitContext, gatherGitContext } from "./git-context.ts";
+import {
+  appendPrioritySignalsSection,
+  summarizePrioritySignalsForFiles,
+} from "./prioritization-signals.ts";
 import type { BriefDetails, ConfidenceMode } from "./types.ts";
 
 /**
@@ -55,7 +60,15 @@ function generateDirectoryBrief(
   if (mod && mod.root === resolvedPath) {
     formatModuleBrief({ mod, model, lines, startHere, publicSurfaces, nextQueries, resolvedPath });
   } else {
-    formatNonModuleDir({ model, mod, resolvedPath, originalPath, lines });
+    formatNonModuleDir({
+      model,
+      mod,
+      resolvedPath,
+      originalPath,
+      lines,
+      publicSurfaces,
+      nextQueries,
+    });
   }
 
   if (nextQueries.length > 0) {
@@ -66,6 +79,12 @@ function generateDirectoryBrief(
     }
   }
 
+  const prioritySignals = summarizePrioritySignalsForFiles(
+    model.root,
+    summarizeDirectoryRecursively(resolvedPath).allFiles,
+  );
+  appendPrioritySignalsSection(lines, prioritySignals);
+
   const gitCtx = gatherGitContext(model.root);
   if (gitCtx) {
     lines.push(formatGitContext(gitCtx));
@@ -83,6 +102,7 @@ function generateDirectoryBrief(
       dependencySummary: mod ? { moduleCount: 1, edgeCount: mod.internalDeps.length } : null,
       omittedCount: 0,
       nextQueries,
+      prioritySignals,
     },
   };
 }
@@ -195,10 +215,13 @@ interface NonModuleDirContext {
   resolvedPath: string;
   originalPath: string;
   lines: string[];
+  publicSurfaces: string[];
+  nextQueries: string[];
 }
 
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: nested-directory brief formatting is clearer as one staged formatter than as many tiny helpers
 function formatNonModuleDir(ctx: NonModuleDirContext): void {
-  const { model, mod, resolvedPath, originalPath, lines } = ctx;
+  const { model, mod, resolvedPath, originalPath, lines, publicSurfaces, nextQueries } = ctx;
   const relPath = path.relative(model.root, resolvedPath);
   lines.push(`# Directory: ${relPath || originalPath}`);
   lines.push("");
@@ -209,17 +232,55 @@ function formatNonModuleDir(ctx: NonModuleDirContext): void {
     lines.push("");
   }
 
-  const files = listSourceFiles(resolvedPath);
-  if (files.length > 0) {
-    const shown = files.slice(0, 10);
+  const summary = summarizeDirectoryRecursively(resolvedPath);
+  if (summary.directFiles.length > 0) {
     lines.push("## Source Files");
-    for (const f of shown) {
+    for (const f of summary.directFiles.slice(0, 10)) {
       lines.push(`- \`${f}\``);
     }
-    if (files.length > 10) {
-      lines.push(`- _+${files.length - 10} more files_`);
+    if (summary.directFiles.length > 10) {
+      lines.push(`- _+${summary.directFiles.length - 10} more files_`);
     }
-  } else {
+    lines.push("");
+  }
+
+  if (summary.totalSourceFiles > 0) {
+    lines.push("## Descendant Source Files");
+    lines.push(`- Total: ${summary.totalSourceFiles}`);
+    for (const subdir of summary.subdirs.slice(0, 8)) {
+      lines.push(
+        `- \`${subdir.name}/\` — ${subdir.fileCount} file${subdir.fileCount !== 1 ? "s" : ""}`,
+      );
+    }
+    if (summary.subdirs.length > 8) {
+      lines.push(`- _+${summary.subdirs.length - 8} more subdirectories_`);
+    }
+    lines.push("");
+  }
+
+  if (summary.publicSurfaces.length > 0) {
+    lines.push("## Public Surfaces");
+    for (const surface of summary.publicSurfaces.slice(0, 8)) {
+      lines.push(`- ${surface}`);
+      publicSurfaces.push(surface);
+    }
+    if (summary.publicSurfaces.length > 8) {
+      lines.push(`- _+${summary.publicSurfaces.length - 8} more exports_`);
+    }
+    lines.push("");
+  }
+
+  if (summary.totalSourceFiles > 0) {
+    lines.push("## Import / Export Summary");
+    lines.push(`- Imports: ${summary.importCount}`);
+    lines.push(`- Exports: ${summary.exportCount}`);
+    lines.push("");
+    nextQueries.push(
+      `\`code_intel pattern\` with \`path: "${relPath || originalPath}"\` to inspect a specific nested symbol`,
+    );
+  }
+
+  if (summary.totalSourceFiles === 0) {
     lines.push("No recognized source files in this directory.");
   }
 }
@@ -266,6 +327,12 @@ function generateFileBrief(
     lines.push("_Could not read file contents._");
   }
 
+  const prioritySignals = summarizePrioritySignalsForFiles(model.root, [resolvedPath]);
+  if (prioritySignals) {
+    lines.push("");
+    appendPrioritySignalsSection(lines, prioritySignals);
+  }
+
   nextQueries.push(
     `\`code_intel callers\` with \`file: "${relPath}"\` and a line/character for call-site analysis`,
   );
@@ -300,6 +367,7 @@ function generateFileBrief(
       dependencySummary: null,
       omittedCount: 0,
       nextQueries,
+      prioritySignals,
     },
   };
 }
@@ -365,6 +433,16 @@ const SOURCE_EXTENSIONS = new Set([
   ".sql",
 ]);
 
+interface RecursiveDirectorySummary {
+  directFiles: string[];
+  allFiles: string[];
+  totalSourceFiles: number;
+  subdirs: Array<{ name: string; fileCount: number }>;
+  publicSurfaces: string[];
+  importCount: number;
+  exportCount: number;
+}
+
 function listSourceFiles(dir: string): string[] {
   const files: string[] = [];
   try {
@@ -381,3 +459,105 @@ function listSourceFiles(dir: string): string[] {
   }
   return files.sort((a, b) => a.localeCompare(b));
 }
+
+function summarizeDirectoryRecursively(dir: string): RecursiveDirectorySummary {
+  const directFiles = listSourceFiles(dir);
+  const summary: RecursiveDirectorySummary = {
+    directFiles,
+    allFiles: directFiles.map((file) => path.join(dir, file)),
+    totalSourceFiles: directFiles.length,
+    subdirs: [],
+    publicSurfaces: [],
+    importCount: 0,
+    exportCount: 0,
+  };
+
+  accumulateJsTsSignals(summary, dir, directFiles, "");
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const childDir = path.join(dir, entry.name);
+      const childSummary = summarizeDirectoryRecursively(childDir);
+      if (childSummary.totalSourceFiles === 0) continue;
+      summary.totalSourceFiles += childSummary.totalSourceFiles;
+      summary.allFiles.push(...childSummary.allFiles);
+      summary.subdirs.push({ name: entry.name, fileCount: childSummary.totalSourceFiles });
+      summary.publicSurfaces.push(
+        ...childSummary.publicSurfaces.map((surface) => `${entry.name}/${surface}`),
+      );
+      summary.importCount += childSummary.importCount;
+      summary.exportCount += childSummary.exportCount;
+    }
+  } catch {
+    // Directory not readable
+  }
+
+  summary.subdirs.sort((a, b) => a.name.localeCompare(b.name));
+  return summary;
+}
+
+function accumulateJsTsSignals(
+  summary: RecursiveDirectorySummary,
+  dir: string,
+  files: string[],
+  prefix: string,
+): void {
+  for (const file of files) {
+    if (!isJsTsFile(file)) continue;
+    try {
+      const relFile = prefix ? `${prefix}/${file}` : file;
+      const content = fs.readFileSync(path.join(dir, file), "utf-8");
+      summary.importCount += countMatches(content, /^import\s/gm);
+      const exports = extractNamedExports(content);
+      summary.exportCount += exports.length;
+      for (const exportedName of exports) {
+        summary.publicSurfaces.push(`\`${exportedName}\` — \`${relFile}\``);
+      }
+    } catch {
+      // File not readable
+    }
+  }
+}
+
+function isJsTsFile(file: string): boolean {
+  return [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"].includes(
+    path.extname(file),
+  );
+}
+
+/**
+ * Lightweight exported-name extraction for recursive directory briefs.
+ *
+ * Best-effort only: handles exported declarations and simple named export lists,
+ * but intentionally does not try to cover default exports, export-all forms,
+ * re-exported defaults, or every multiline formatting variant.
+ */
+function extractNamedExports(content: string): string[] {
+  const names = new Set<string>();
+  const declarationRegex =
+    /export\s+(?:async\s+)?(?:function|class|interface|type|const|let|var|enum)\s+([A-Za-z_$][\w$]*)/g;
+  const namedExportRegex = /export\s*\{\s*([^}]+)\s*\}/g;
+
+  for (const match of content.matchAll(declarationRegex)) {
+    if (match[1]) names.add(match[1]);
+  }
+
+  for (const match of content.matchAll(namedExportRegex)) {
+    const parts = match[1]?.split(",") ?? [];
+    for (const part of parts) {
+      const candidate = part
+        .trim()
+        .split(/\s+as\s+/i)[0]
+        ?.trim();
+      if (candidate) names.add(candidate);
+    }
+  }
+
+  return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+function countMatches(content: string, regex: RegExp): number {
+  return [...content.matchAll(regex)].length;
+}

package/src/code-intelligence.ts

@@ -73,7 +73,10 @@ export default function codeIntelligenceExtension(pi: ExtensionAPI) {
         Type.String({ description: "Scope or focus path (package, directory, or file)" }),
       ),
       file: Type.Optional(
-        Type.String({ description: "Anchored target file (use with line/character)" }),
+        Type.String({
+          description:
+            "Anchored target file (use with line/character) or a file-level semantic target for brief/callers/affected",
+        }),
       ),
       line: Type.Optional(Type.Number({ description: "1-based line number for anchored target" })),
       character: Type.Optional(
@@ -92,7 +95,12 @@ export default function codeIntelligenceExtension(pi: ExtensionAPI) {
           description: "Use regex semantics for pattern action (default: false, literal search)",
         }),
       ),
-      kind: Type.Optional(Type.String({ description: "Symbol kind filter for discovery" })),
+      kind: Type.Optional(
+        Type.String({
+          description:
+            "Symbol kind filter for discovery, or pattern kind (`definition` | `export` | `import`) for structured searches",
+        }),
+      ),
       exportedOnly: Type.Optional(
         Type.Boolean({ description: "Limit discovery to exported symbols" }),
       ),

package/src/git-context.ts

@@ -1,9 +1,20 @@
 import { execFileSync } from "node:child_process";
 
+function scrubGitEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const next = { ...env };
+  for (const key of Object.keys(next)) {
+    if (key.startsWith("GIT_")) {
+      delete next[key];
+    }
+  }
+  return next;
+}
+
 function execGit(cwd: string, args: string[]): string {
   return execFileSync("git", args, {
     cwd,
     encoding: "utf-8",
+    env: scrubGitEnv(process.env),
     stdio: ["ignore", "pipe", "ignore"],
     timeout: 5000,
   });

package/src/guidance.ts

@@ -4,11 +4,11 @@ export const toolDescription = `Code intelligence tool — architecture briefs,
 
 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)
+- callers: Find call sites for a symbol, or analyze a file-level export surface when only \`file\` is provided
 - 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\`
+- affected: Blast-radius analysis for a symbol or exported file surface — direct references, downstream dependents, risk level, likely tests
+- pattern: Bounded text search with grouped matches, context lines, structured \`kind\` filters (\`definition\` | \`export\` | \`import\`), partial-result warnings on oversized structured scans, 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.
@@ -18,21 +18,24 @@ Examples:
   { "action": "brief" }
   { "action": "brief", "path": "packages/supi-lsp/" }
   { "action": "brief", "file": "packages/supi-lsp/lsp.ts", "line": 42, "character": 7 }
+  { "action": "callers", "file": "packages/supi-core/index.ts" }
   { "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": "affected", "file": "packages/supi-core/index.ts" }
   { "action": "pattern", "pattern": "registerSettings", "path": "packages/", "maxResults": 10 }
-  { "action": "pattern", "pattern": "register(Settings|Config)", "path": "packages/", "regex": true, "maxResults": 10 }`;
+  { "action": "pattern", "pattern": "register(Settings|Config)", "path": "packages/", "regex": true, "maxResults": 10 }
+  { "action": "pattern", "pattern": "payment", "kind": "definition", "path": "src/" }`;
 
 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 affected` before changing exported APIs, shared helpers, config surfaces, or cross-package contracts to check blast radius and risk; file-only requests now expand across exported targets when possible.",
+  "Use `code_intel callers` before modifying a function to verify all call sites; use `callees` and `implementations` for dependency and interface analysis, and use file-only `callers` when you need the export surface of a module.",
+  '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, supports `regex: true`, supports `kind: "definition" | "export" | "import"` for structured searches, and may return a partial-result warning when a structured scan is too broad.',
+  "Use `code_intel brief` and `code_intel affected` priority signals to notice diagnostics, low coverage, or unused-code hints before editing risky files.",
   "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/pattern-structured.ts

@@ -0,0 +1,196 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
+import type { ActionParams } from "./tool-actions.ts";
+
+export const STRUCTURED_PATTERN_FILE_CAP = 200;
+const STRUCTURED_PATTERN_TIMEOUT_MS = 10_000;
+
+export type StructuredPatternKind = "definition" | "export" | "import";
+
+export interface StructuredMatch {
+  file: string;
+  name: string;
+  kind: string;
+  line: number;
+}
+
+export interface StructuredPatternResult {
+  matches: StructuredMatch[];
+  omittedCount: number;
+  partialReason: "file-cap" | "timeout" | null;
+}
+
+export function isStructuredPatternKind(kind: string | undefined): kind is StructuredPatternKind {
+  return kind === "definition" || kind === "export" || kind === "import";
+}
+
+export async function getStructuredPatternMatches(
+  params: ActionParams & { pattern: string; kind: StructuredPatternKind },
+  scopePath: string,
+  cwd: string,
+  relScope: string,
+): Promise<StructuredPatternResult | string | null> {
+  const deadline = Date.now() + STRUCTURED_PATTERN_TIMEOUT_MS;
+  const collected = collectStructuredFiles(scopePath, deadline);
+  if (collected.files.length === 0) {
+    return null;
+  }
+
+  const matcher = createStructuredMatcher(params.pattern, params.regex ?? false);
+  if (typeof matcher === "string") {
+    return matcher;
+  }
+
+  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
+  try {
+    tsSession = createTreeSitterSession(cwd);
+    const matches: StructuredMatch[] = [];
+    let timedOut = collected.timedOut;
+
+    for (const [index, file] of collected.files.entries()) {
+      if (Date.now() > deadline) {
+        collected.omittedCount += collected.files.length - index;
+        timedOut = true;
+        break;
+      }
+      const relFile = path.relative(cwd, file);
+      await collectMatchesForFile(matches, tsSession, relFile, params.kind, matcher);
+    }
+
+    return {
+      matches,
+      omittedCount: timedOut ? Math.max(1, collected.omittedCount) : collected.omittedCount,
+      partialReason: timedOut ? "timeout" : collected.omittedCount > 0 ? "file-cap" : null,
+    };
+  } catch {
+    return `No structured ${params.kind} search data available in \`${relScope}\`. Try omitting \`kind\` for plain text search.`;
+  } finally {
+    tsSession?.dispose();
+  }
+}
+
+// biome-ignore lint/complexity/useMaxParams: helper takes explicit collection inputs to avoid intermediate objects in the hot path
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: kind-specific tree-sitter matching is clearest as one helper
+async function collectMatchesForFile(
+  matches: StructuredMatch[],
+  tsSession: ReturnType<typeof createTreeSitterSession>,
+  relFile: string,
+  kind: StructuredPatternKind,
+  matcher: (value: string) => boolean,
+): Promise<void> {
+  if (kind === "definition") {
+    const outline = await tsSession.outline(relFile);
+    if (outline.kind !== "success") return;
+    for (const item of outline.data) {
+      if (!matcher(item.name)) continue;
+      matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.range.startLine });
+    }
+    return;
+  }
+
+  if (kind === "export") {
+    const exportsResult = await tsSession.exports(relFile);
+    if (exportsResult.kind !== "success") return;
+    for (const item of exportsResult.data) {
+      if (!matcher(item.name)) continue;
+      matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.range.startLine });
+    }
+    return;
+  }
+
+  const importsResult = await tsSession.imports(relFile);
+  if (importsResult.kind !== "success") return;
+  for (const item of importsResult.data) {
+    if (!matcher(item.moduleSpecifier)) continue;
+    matches.push({
+      file: relFile,
+      name: item.moduleSpecifier,
+      kind: "import",
+      line: item.range.startLine,
+    });
+  }
+}
+
+function collectStructuredFiles(
+  scopePath: string,
+  deadline: number,
+): { files: string[]; omittedCount: number; timedOut: boolean } {
+  const files: string[] = [];
+  let omittedCount = 0;
+  let timedOut = false;
+  const skipDirs = new Set(["node_modules", ".git", "dist", "build", "coverage"]);
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: timeout, file, and directory branches stay adjacent for predictable short-circuiting
+  function walk(currentPath: string) {
+    if (timedOut) return;
+    if (Date.now() > deadline) {
+      timedOut = true;
+      return;
+    }
+
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(currentPath);
+    } catch {
+      return;
+    }
+
+    if (stat.isFile()) {
+      if (isStructuredFile(currentPath)) {
+        if (files.length < STRUCTURED_PATTERN_FILE_CAP) {
+          files.push(currentPath);
+        } else {
+          omittedCount++;
+        }
+      }
+      return;
+    }
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(currentPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      if (entry.isDirectory() && skipDirs.has(entry.name)) continue;
+      walk(path.join(currentPath, entry.name));
+      if (timedOut) return;
+    }
+  }
+
+  walk(scopePath);
+  return { files: files.sort((a, b) => a.localeCompare(b)), omittedCount, timedOut };
+}
+
+function isStructuredFile(file: string): boolean {
+  return [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"].includes(
+    path.extname(file),
+  );
+}
+
+function createStructuredMatcher(
+  pattern: string,
+  regex: boolean,
+): ((value: string) => boolean) | string {
+  const ignoreCase = !/[A-Z]/.test(pattern);
+
+  if (regex) {
+    try {
+      const compiled = new RegExp(pattern, ignoreCase ? "i" : undefined);
+      return (value: string) => compiled.test(value);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Invalid regex";
+      return `**Error:** Invalid regex pattern \`${pattern}\`: ${message}`;
+    }
+  }
+
+  const needle = ignoreCase ? pattern.toLowerCase() : pattern;
+  return (value: string) => {
+    const haystack = ignoreCase ? value.toLowerCase() : value;
+    return haystack.includes(needle);
+  };
+}