@mrclrchtr/supi-code-intelligence 1.16.0 → 2.0.0

package/src/analysis/brief/enrich.ts

@@ -0,0 +1,157 @@
+// Enrichment helpers for the brief pipeline.
+//
+// Provides three functions:
+// - enrichFileContext(provider, file, maxResults) — outline, imports, exports
+// - enrichDiagnosticContext(cwd, file, maxResults) — LSP diagnostics
+// - gatherBriefEnrichment(provider, cwd, file, maxResults) — orchestrates both
+
+import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import { diagnosticMessageString } from "../../substrate/lsp/utils.ts";
+import type { CodeProvider } from "../provider.ts";
+import type { BriefDiagnostic, BriefEnrichment } from "./models.ts";
+
+// ── Default caps ─────────────────────────────────────────────────────
+
+const DEFAULT_OUTLINE_CAP = 15;
+const DEFAULT_IMPORTS_CAP = 10;
+const DEFAULT_EXPORTS_CAP = 10;
+const DEFAULT_DIAGNOSTICS_CAP = 5;
+
+function cap(count: number | undefined, def: number): number {
+  return count != null && count > 0 ? count : def;
+}
+
+// ── Structural enrichment ───────────────────────────────────────────
+
+/**
+ * Enrich file context with outline, imports, and exports from a provider.
+ * Each section is capped at maxResults with per-section defaults.
+ */
+export async function enrichFileContext(
+  provider: CodeProvider,
+  file: string,
+  maxResults?: number,
+): Promise<Pick<BriefEnrichment, "outline" | "imports" | "exports">> {
+  const outlineCap = cap(maxResults, DEFAULT_OUTLINE_CAP);
+  const importsCap = cap(maxResults, DEFAULT_IMPORTS_CAP);
+  const exportsCap = cap(maxResults, DEFAULT_EXPORTS_CAP);
+
+  const outline = await tryOutline(provider, file, outlineCap);
+  const imports = await tryImports(provider, file, importsCap);
+  const exports = await tryExports(provider, file, exportsCap);
+
+  return { outline, imports, exports };
+}
+
+async function tryOutline(
+  provider: CodeProvider,
+  file: string,
+  capN: number,
+): Promise<BriefEnrichment["outline"]> {
+  try {
+    const result = await provider.outline(file);
+    if (result.kind !== "success") return [];
+    return result.data.slice(0, capN).map((item) => ({
+      name: item.name,
+      kind: item.kind,
+      startLine: item.startLine,
+      endLine: item.endLine,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+async function tryImports(
+  provider: CodeProvider,
+  file: string,
+  capN: number,
+): Promise<BriefEnrichment["imports"]> {
+  try {
+    const result = await provider.imports(file);
+    if (result.kind !== "success") return [];
+    return result.data.slice(0, capN).map((item) => ({
+      moduleSpecifier: item.moduleSpecifier,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+async function tryExports(
+  provider: CodeProvider,
+  file: string,
+  capN: number,
+): Promise<BriefEnrichment["exports"]> {
+  try {
+    const result = await provider.exports(file);
+    if (result.kind !== "success") return [];
+    return result.data.slice(0, capN).map((item) => ({
+      name: item.name,
+      kind: item.kind,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// ── Diagnostic enrichment ───────────────────────────────────────────
+
+/**
+ * Get LSP diagnostics for a file (errors + warnings).
+ * Returns capped diagnostic entries.
+ */
+export async function enrichDiagnosticContext(
+  file: string | undefined,
+  maxResults: number | undefined,
+  lspService: SessionLspServiceState,
+): Promise<Pick<BriefEnrichment, "diagnostics">> {
+  if (!file) return { diagnostics: [] };
+
+  const capN = cap(maxResults, DEFAULT_DIAGNOSTICS_CAP);
+
+  try {
+    if (lspService.kind !== "ready") return { diagnostics: [] };
+
+    const diags = await lspService.service.fileDiagnostics(file, 2);
+    if (!diags || diags.length === 0) return { diagnostics: [] };
+
+    // Map to our DTO shape (1-based line for display)
+    const mapped: BriefDiagnostic[] = diags.map((d) => ({
+      line: d.range.start.line + 1,
+      severity: d.severity ?? 1,
+      message: diagnosticMessageString(d),
+    }));
+
+    return { diagnostics: mapped.slice(0, capN) };
+  } catch {
+    return { diagnostics: [] };
+  }
+}
+
+// ── Combined enrichment ─────────────────────────────────────────────
+
+/**
+ * Orchestrate both structural and diagnostic enrichment for a file.
+ */
+export async function gatherBriefEnrichment(
+  provider: CodeProvider | null,
+  file: string,
+  maxResults: number | undefined,
+  lspService: SessionLspServiceState,
+): Promise<BriefEnrichment> {
+  // Structural context (outline, imports, exports) needs a provider
+  const structural = provider
+    ? await enrichFileContext(provider, file, maxResults)
+    : { outline: [], imports: [], exports: [] };
+
+  // Diagnostics can work independently of provider (reaches LSP directly)
+  const diagnostic = await enrichDiagnosticContext(file, maxResults, lspService);
+
+  return {
+    outline: structural.outline,
+    imports: structural.imports,
+    exports: structural.exports,
+    diagnostics: diagnostic.diagnostics,
+  };
+}

package/src/analysis/brief/file.ts

@@ -0,0 +1,84 @@
+/**
+ * File-level brief generation with provider enrichment.
+ *
+ * Generates a brief for a single source file, enriching with outline, imports,
+ * exports, diagnostics, and entrypoint-detection metadata.
+ *
+ * Extracted from brief-focused.ts.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { renderFileBrief } from "../../ui/markdown/brief.ts";
+import type { ArchitectureModel } from "../architecture/model.ts";
+import { findModuleForPath } from "../architecture/model.ts";
+import { gatherBriefEnrichment } from "./enrich.ts";
+import type { BriefOpts } from "./models.ts";
+
+/** Generate a file-level brief with structural enrichment and diagnostics. */
+export async function generateFileBrief(
+  model: ArchitectureModel,
+  resolvedPath: string,
+  opts?: BriefOpts,
+): Promise<{
+  content: string;
+  publicSurfaces: string[];
+  nextQueries: string[];
+}> {
+  const mod = findModuleForPath(model, resolvedPath);
+  const publicSurfaces: string[] = [];
+  const nextQueries: string[] = [];
+
+  const fileName = path.basename(resolvedPath);
+  const relPath = path.relative(model.root, resolvedPath);
+
+  let lineCount = 0;
+  try {
+    const fileContent = fs.readFileSync(resolvedPath, "utf-8");
+    lineCount = fileContent.split("\n").length;
+  } catch {
+    // Leave 0
+  }
+
+  const isEntrypoint =
+    mod?.entrypoints.some((ep) => path.resolve(mod.root, ep) === resolvedPath) ?? false;
+
+  const lspService =
+    opts?.lspService ??
+    ({
+      kind: "unavailable" as const,
+      reason: "No LSP service",
+    } as import("@mrclrchtr/supi-lsp/api").SessionLspServiceState);
+  const enrichment = await gatherBriefEnrichment(
+    opts?.provider ?? null,
+    relPath,
+    opts?.maxResults,
+    lspService,
+  );
+
+  const renderedContent = renderFileBrief({
+    relPath: relPath || fileName,
+    lineCount,
+    isEntrypoint,
+    moduleName: mod ? mod.name.replace(/^@[^/]+\//, "") : null,
+    moduleRelativePath: mod ? mod.relativePath : null,
+    enrichment,
+    maxResults: opts?.maxResults,
+  });
+
+  if (isEntrypoint) {
+    const shortName = mod?.name.replace(/^@[^/]+\//, "") ?? "";
+    publicSurfaces.push(`${shortName} entrypoint`);
+  }
+
+  nextQueries.push(
+    `\`code_graph\`, \`file: "${relPath}"\`, and a line/character for reference sites`,
+  );
+  if (mod) {
+    nextQueries.push(
+      `\`code_orientation\` with \`focus: "${mod.relativePath}"\` for the containing module overview`,
+    );
+  }
+
+  return { content: renderedContent, publicSurfaces, nextQueries };
+}

package/src/analysis/brief/inventory.ts

@@ -0,0 +1,177 @@
+/**
+ * Directory inventory collection — flat file counts by extension and landmark detection.
+ *
+ * Extracted from brief-focused.ts to keep the focus-generation modules
+ * cohesive and avoid a single 800+ line file.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+/** Flat inventory of a directory tree. */
+export interface DirectoryInventory {
+  totalFiles: number;
+  byExtension: Map<string, number>;
+  landmarkFiles: string[];
+}
+
+// ── Public API ────────────────────────────────────────────────────────
+
+/** Walk a directory tree collecting extension breakdown and landmark files. */
+export function collectDirectoryInventory(dir: string): DirectoryInventory {
+  const byExtension = new Map<string, number>();
+  const landmarkFiles: string[] = [];
+  const state = { totalFiles: 0, byExtension, landmarkFiles };
+
+  function walk(currentPath: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(currentPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      processInventoryEntry(entry, currentPath, walk, state);
+    }
+  }
+
+  walk(dir);
+  landmarkFiles.sort((a, b) => a.localeCompare(b));
+  return { totalFiles: state.totalFiles, byExtension, landmarkFiles };
+}
+
+/** Append inventory (extension breakdown + landmarks) to a lines array. */
+export function addInventoryToLines(lines: string[], inventory: DirectoryInventory): void {
+  if (inventory.totalFiles === 0) return;
+
+  lines.push(`**Files:** ${inventory.totalFiles} total`);
+
+  const sortedExts = [...inventory.byExtension.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10);
+  for (const [ext, count] of sortedExts) {
+    const label = EXTENSION_LABELS.get(ext) ?? (ext || "(no extension)");
+    lines.push(`- ${label}: ${count}`);
+  }
+  if (inventory.byExtension.size > 10) {
+    lines.push(`- _+${inventory.byExtension.size - 10} more extensions_`);
+  }
+
+  if (inventory.landmarkFiles.length > 0) {
+    const unique = [...new Set(inventory.landmarkFiles)].sort((a, b) => a.localeCompare(b));
+    lines.push("");
+    lines.push("**Landmark files:**");
+    for (const f of unique) {
+      lines.push(`- \`${f}\``);
+    }
+  }
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────
+
+/** Process a single directory entry during inventory collection. */
+function processInventoryEntry(
+  entry: fs.Dirent,
+  currentPath: string,
+  walkFn: (p: string) => void,
+  state: {
+    totalFiles: number;
+    byExtension: Map<string, number>;
+    landmarkFiles: string[];
+  },
+): void {
+  if (entry.name.startsWith(".") && entry.isDirectory()) return;
+  if (SKIP_DIRS.has(entry.name)) return;
+  if (entry.isDirectory()) {
+    walkFn(path.join(currentPath, entry.name));
+    return;
+  }
+  state.totalFiles++;
+  const ext = path.extname(entry.name).toLowerCase();
+  state.byExtension.set(ext, (state.byExtension.get(ext) ?? 0) + 1);
+  if (LANDMARK_FILES.has(entry.name)) {
+    state.landmarkFiles.push(entry.name);
+  }
+}
+
+// ── Constants ─────────────────────────────────────────────────────────
+
+/** Human-readable labels for common file extensions. */
+const EXTENSION_LABELS: Map<string, string> = new Map([
+  [".ts", "TypeScript"],
+  [".tsx", "TSX"],
+  [".js", "JavaScript"],
+  [".jsx", "JSX"],
+  [".mts", "TypeScript"],
+  [".cts", "TypeScript"],
+  [".mjs", "JavaScript"],
+  [".cjs", "JavaScript"],
+  [".py", "Python"],
+  [".pyi", "Python"],
+  [".rs", "Rust"],
+  [".go", "Go"],
+  [".mod", "Go"],
+  [".java", "Java"],
+  [".kt", "Kotlin"],
+  [".kts", "Kotlin"],
+  [".rb", "Ruby"],
+  [".php", "PHP"],
+  [".swift", "Swift"],
+  [".cpp", "C++"],
+  [".hpp", "C++"],
+  [".cc", "C++"],
+  [".cxx", "C++"],
+  [".hxx", "C++ Header"],
+  [".c++", "C++"],
+  [".h++", "C++ Header"],
+  [".c", "C"],
+  [".h", "C Header"],
+  [".css", "CSS"],
+  [".scss", "SCSS"],
+  [".less", "Less"],
+  [".html", "HTML"],
+  [".htm", "HTML"],
+  [".xhtml", "HTML"],
+  [".json", "JSON"],
+  [".yaml", "YAML"],
+  [".yml", "YAML"],
+  [".toml", "TOML"],
+  [".md", "Markdown"],
+  [".sh", "Shell"],
+  [".bash", "Shell"],
+  [".zsh", "Shell"],
+  [".r", "R"],
+  [".sql", "SQL"],
+  [".cs", "C#"],
+]);
+
+/** Landmark files — well-known project configuration files. */
+const LANDMARK_FILES = new Set([
+  "package.json",
+  "tsconfig.json",
+  "jsconfig.json",
+  "vite.config.ts",
+  "vitest.config.ts",
+  "jest.config.ts",
+  "playwright.config.ts",
+  "biome.json",
+  "eslint.config.js",
+  ".eslintrc.js",
+  "deno.json",
+  "deno.jsonc",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "setup.py",
+  "requirements.txt",
+  "Makefile",
+  "justfile",
+  "Taskfile.yml",
+  "Dockerfile",
+  "docker-compose.yml",
+  ".env.example",
+  ".env.local.example",
+]);
+
+/** Skip these directories during flat inventory walks. */
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);

package/src/analysis/brief/main.ts

@@ -0,0 +1,176 @@
+/**
+ * Focused brief generation — dispatches to file or directory brief.
+ *
+ * This is the main entry point, extracted from the original 800+ line
+ * brief-focused.ts. File and directory brief logic now live in sibling
+ * modules under use-case/brief/.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { BriefDetails } from "../../types/index.ts";
+import type { ArchitectureModel } from "../architecture/model.ts";
+import { findModuleForPath } from "../architecture/model.ts";
+import { formatGitContext, gatherGitContext } from "../signals/git.ts";
+import {
+  appendPrioritySignalsSection,
+  summarizePrioritySignalsForFiles,
+} from "../signals/project.ts";
+import { generateDirectoryBrief } from "./directory.ts";
+import { generateFileBrief } from "./file.ts";
+import type { BriefOpts } from "./models.ts";
+import { summarizeDirectoryRecursively } from "./summarize.ts";
+
+/**
+ * Generate a focused brief for a specific path (directory or file).
+ *
+ * When opts.provider is available, file briefs include structural
+ * context (outline, imports, exports) and inline diagnostics.
+ * Module briefs include aggregated diagnostics across source files.
+ */
+export async function generateFocusedBrief(
+  model: ArchitectureModel,
+  focusPath: string,
+  opts?: BriefOpts,
+): Promise<{ content: string; details: BriefDetails }> {
+  const resolvedPath = path.resolve(focusPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    return {
+      content: `**Error:** Path not found: \`${focusPath}\``,
+      details: {
+        confidence: "unavailable",
+        focusTarget: focusPath,
+        startHere: [],
+        publicSurfaces: [],
+        dependencySummary: null,
+        omittedCount: 0,
+        nextQueries: [],
+      },
+    };
+  }
+
+  const stat = fs.statSync(resolvedPath);
+
+  if (stat.isDirectory()) {
+    return await generateDirectoryFocused(model, resolvedPath, focusPath, opts);
+  }
+
+  return await generateFileFocused(model, resolvedPath, focusPath, opts);
+}
+
+// ── Directory dispatch ────────────────────────────────────────────────
+
+async function generateDirectoryFocused(
+  model: ArchitectureModel,
+  resolvedPath: string,
+  originalPath: string,
+  opts?: BriefOpts,
+): Promise<{ content: string; details: BriefDetails }> {
+  const confidence: ConfidenceMode = "structural";
+
+  const { lines, publicSurfaces, nextQueries, startHere } = await generateDirectoryBrief(
+    model,
+    resolvedPath,
+    originalPath,
+    opts,
+  );
+
+  // Determine module info for dependency summary
+  const mod = findModuleForPath(model, resolvedPath);
+  const isModuleRoot = mod && mod.root === resolvedPath;
+
+  // Priority signals
+  const lspService =
+    opts?.lspService ??
+    ({
+      kind: "unavailable" as const,
+      reason: "No LSP service",
+    } as import("@mrclrchtr/supi-lsp/api").SessionLspServiceState);
+  const prioritySignals = summarizePrioritySignalsForFiles(
+    model.root,
+    summarizeDirectoryRecursively(resolvedPath).allFiles,
+    lspService,
+  );
+  appendPrioritySignalsSection(lines, prioritySignals);
+
+  // Git context
+  if (opts?.showGitContext !== false) {
+    const gitCtx = gatherGitContext(model.root);
+    if (gitCtx) {
+      lines.push(formatGitContext(gitCtx));
+    }
+  }
+
+  lines.push("");
+
+  return {
+    content: lines.join("\n"),
+    details: {
+      confidence,
+      focusTarget: originalPath,
+      startHere: startHere.slice(0, 3),
+      publicSurfaces: publicSurfaces.slice(0, 5),
+      dependencySummary: isModuleRoot
+        ? { moduleCount: 1, edgeCount: mod.internalDeps.length }
+        : null,
+      omittedCount: 0,
+      nextQueries,
+      prioritySignals,
+    },
+  };
+}
+
+// ── File dispatch ─────────────────────────────────────────────────────
+
+async function generateFileFocused(
+  model: ArchitectureModel,
+  resolvedPath: string,
+  originalPath: string,
+  opts?: BriefOpts,
+): Promise<{ content: string; details: BriefDetails }> {
+  const {
+    content: briefContent,
+    publicSurfaces,
+    nextQueries,
+  } = await generateFileBrief(model, resolvedPath, opts);
+
+  // Priority signals
+  const lspService =
+    opts?.lspService ??
+    ({
+      kind: "unavailable" as const,
+      reason: "No LSP service",
+    } as import("@mrclrchtr/supi-lsp/api").SessionLspServiceState);
+  const prioritySignals = summarizePrioritySignalsForFiles(model.root, [resolvedPath], lspService);
+  const extraLines: string[] = [];
+  if (prioritySignals) {
+    appendPrioritySignalsSection(extraLines, prioritySignals);
+  }
+
+  // Git context
+  if (opts?.showGitContext !== false) {
+    const gitCtx = gatherGitContext(model.root);
+    if (gitCtx) {
+      extraLines.push(formatGitContext(gitCtx));
+    }
+  }
+
+  const extraStr = extraLines.filter((l) => l.trim()).join("\n");
+  const combinedContent = extraStr ? `${briefContent.trim()}\n\n${extraStr}\n` : briefContent;
+
+  return {
+    content: combinedContent,
+    details: {
+      confidence: "structural",
+      focusTarget: originalPath,
+      startHere: [],
+      publicSurfaces,
+      dependencySummary: null,
+      omittedCount: 0,
+      nextQueries,
+      prioritySignals,
+    },
+  };
+}

package/src/analysis/brief/models.ts

@@ -0,0 +1,75 @@
+// Typed DTOs for brief pipeline stages.
+//
+// Each brief mode produces a typed model (sync, manifest + fs), then
+// enrichment adds provider context (async), then renderers consume
+// the enriched model to produce markdown.
+
+// ── Brief models (build stage output) ────────────────────────────────
+
+/** Model for a single-file brief. */
+export interface FileBriefModel {
+  kind: "file";
+  file: string;
+  relPath: string;
+  lineCount: number;
+  isEntrypoint: boolean;
+  moduleName: string | null;
+  moduleRelativePath: string | null;
+}
+
+/** Model for a module (package) brief. */
+export interface ModuleBriefModel {
+  kind: "module";
+  name: string;
+  shortName: string;
+  description: string | null;
+  relativePath: string;
+  entrypoints: string[];
+  sourceFiles: string[];
+  allFiles: string[];
+}
+
+/** Model for a non-module directory brief. */
+export interface DirectoryBriefModel {
+  kind: "directory";
+  path: string;
+  relPath: string;
+  directFiles: string[];
+  subdirs: Array<{ name: string; fileCount: number }>;
+  totalSourceFiles: number;
+}
+
+// ── Enrichment (async provider context) ──────────────────────────────
+
+/** A single file's diagnostic entry. */
+export interface BriefDiagnostic {
+  line: number;
+  severity: number;
+  message: string;
+}
+
+/** Provider-enriched context for a file or module. */
+export interface BriefEnrichment {
+  outline: Array<{ name: string; kind: string; startLine: number; endLine: number }>;
+  imports: Array<{ moduleSpecifier: string }>;
+  exports: Array<{ name: string; kind: string }>;
+  diagnostics: BriefDiagnostic[];
+  /** Per-file aggregated diagnostics for module briefs. */
+  fileDiagnostics?: Array<{ file: string; errors: number; warnings: number }>;
+  /** Entrypoint outlines for module briefs. */
+  entrypointOutlines?: Array<{
+    entrypoint: string;
+    items: Array<{ name: string; kind: string; startLine: number }>;
+  }>;
+}
+
+/** Options for generateFocusedBrief. */
+export interface BriefOpts {
+  provider?: import("../provider.ts").CodeProvider | null;
+  maxResults?: number;
+  cwd: string;
+  /** Show git context in orientation output. Defaults to true. */
+  showGitContext?: boolean;
+  /** LSP service state for diagnostic access. */
+  lspService?: import("@mrclrchtr/supi-lsp/api").SessionLspServiceState;
+}