@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/analysis/brief/directory.ts

@@ -1,324 +0,0 @@
-/**
- * Directory and module brief generation.
- *
- * Formats briefs for module directories (with dependency info, entrypoints,
- * and aggregated diagnostics) and non-module directories (with recursive summaries
- * and import/export counts).
- *
- * Extracted from brief-focused.ts.
- */
-
-import * as path from "node:path";
-import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
-import { renderModuleDiagnostics } from "../../ui/markdown/brief.ts";
-import type { ArchitectureModel } from "../architecture/model.ts";
-import { findModuleForPath, getDependencies, getDependents } from "../architecture/model.ts";
-import { addInventoryToLines, collectDirectoryInventory } from "./inventory.ts";
-import type { BriefOpts } from "./models.ts";
-import { listSourceFiles, summarizeDirectoryRecursively } from "./summarize.ts";
-
-/** Generate a directory-level brief (handles both module and non-module directories). */
-export async function generateDirectoryBrief(
-  model: ArchitectureModel,
-  resolvedPath: string,
-  originalPath: string,
-  opts?: BriefOpts,
-): Promise<{
-  lines: string[];
-  publicSurfaces: string[];
-  nextQueries: string[];
-  startHere: Array<{ target: string; reason: string }>;
-}> {
-  const mod = findModuleForPath(model, resolvedPath);
-  const lines: string[] = [];
-  const publicSurfaces: string[] = [];
-  const nextQueries: string[] = [];
-
-  if (mod && mod.root === resolvedPath) {
-    const startHere: Array<{ target: string; reason: string }> = [];
-    formatModuleBrief({
-      mod,
-      model,
-      lines,
-      startHere,
-      publicSurfaces,
-      nextQueries,
-      resolvedPath,
-      maxResults: opts?.maxResults ?? 10,
-    });
-
-    // Add aggregated diagnostics for module source files
-    await enrichModuleWithDiagnostics(lines, resolvedPath, opts);
-
-    return { lines, publicSurfaces, nextQueries, startHere };
-  } else {
-    formatNonModuleDir({
-      model,
-      mod,
-      resolvedPath,
-      originalPath,
-      lines,
-      publicSurfaces,
-      nextQueries,
-      maxResults: opts?.maxResults ?? 10,
-    });
-
-    return { lines, publicSurfaces, nextQueries, startHere: [] };
-  }
-}
-
-// ── Module brief ──────────────────────────────────────────────────────
-
-interface ModuleBriefContext {
-  mod: NonNullable<ReturnType<typeof findModuleForPath>>;
-  model: ArchitectureModel;
-  lines: string[];
-  startHere: Array<{ target: string; reason: string }>;
-  publicSurfaces: string[];
-  nextQueries: string[];
-  resolvedPath: string;
-  maxResults: number;
-}
-
-function formatModuleBrief(ctx: ModuleBriefContext): void {
-  const { mod, model, lines, startHere, publicSurfaces, nextQueries, resolvedPath } = ctx;
-  const shortName = mod.name.replace(/^@[^/]+\//, "");
-  lines.push(`# Module: ${shortName}`);
-  if (mod.description) {
-    lines.push("");
-    lines.push(mod.description);
-  }
-  lines.push("");
-  lines.push(`- Path: \`${mod.relativePath}\``);
-
-  if (mod.entrypoints.length > 0) {
-    lines.push(`- Entrypoints: ${mod.entrypoints.map((e) => `\`${e}\``).join(", ")}`);
-    for (const ep of mod.entrypoints) {
-      publicSurfaces.push(`${shortName}: ${ep}`);
-      startHere.push({ target: ep, reason: "module entrypoint" });
-    }
-  }
-
-  addDependenciesSection(model, mod, lines);
-  addDependentsSection(model, mod, lines, nextQueries);
-  addSourceFilesSection(resolvedPath, lines, ctx.maxResults);
-}
-
-function addDependenciesSection(
-  model: ArchitectureModel,
-  mod: NonNullable<ReturnType<typeof findModuleForPath>>,
-  lines: string[],
-): void {
-  const deps = getDependencies(model, mod.name);
-  if (deps.length > 0) {
-    lines.push("");
-    lines.push("## Dependencies (internal)");
-    for (const dep of deps) {
-      const depShort = dep.name.replace(/^@[^/]+\//, "");
-      lines.push(`- ${depShort} (\`${dep.relativePath}\`)`);
-    }
-  }
-
-  if (mod.externalDeps.length > 0) {
-    const shown = mod.externalDeps.slice(0, 8);
-    lines.push("");
-    lines.push("## Dependencies (external)");
-    for (const dep of shown) {
-      lines.push(`- ${dep}`);
-    }
-    if (mod.externalDeps.length > 8) {
-      lines.push(`- _+${mod.externalDeps.length - 8} more_`);
-    }
-  }
-}
-
-function addDependentsSection(
-  model: ArchitectureModel,
-  mod: NonNullable<ReturnType<typeof findModuleForPath>>,
-  lines: string[],
-  nextQueries: string[],
-): void {
-  const dependents = getDependents(model, mod.name);
-  if (dependents.length > 0) {
-    lines.push("");
-    lines.push("## Dependents");
-    for (const dep of dependents) {
-      const depShort = dep.name.replace(/^@[^/]+\//, "");
-      lines.push(`- ${depShort} (\`${dep.relativePath}\`)`);
-    }
-    nextQueries.push("`code_impact` before modifying exports from this module");
-  }
-
-  if (mod.entrypoints.length > 0) {
-    const ep = mod.entrypoints[0];
-    nextQueries.push(
-      `\`code_orientation\` with \`focus: "${mod.relativePath}/${ep.replace(/^\.\//, "")}"\` for entrypoint details`,
-    );
-  }
-}
-
-function addSourceFilesSection(resolvedPath: string, lines: string[], maxResults = 10): void {
-  const files = listSourceFiles(resolvedPath);
-  if (files.length > 0) {
-    const shown = files.slice(0, maxResults);
-    lines.push("");
-    lines.push("## Source Files");
-    for (const f of shown) {
-      lines.push(`- \`${f}\``);
-    }
-    if (files.length > maxResults) {
-      lines.push(`- _+${files.length - maxResults} more files_`);
-    }
-  }
-
-  const inventory = collectDirectoryInventory(resolvedPath);
-  if (inventory.totalFiles > 0) {
-    addInventoryToLines(lines, inventory);
-  }
-}
-
-// ── Non-module directory brief ────────────────────────────────────────
-
-interface NonModuleDirContext {
-  model: ArchitectureModel;
-  mod: ReturnType<typeof findModuleForPath>;
-  resolvedPath: string;
-  originalPath: string;
-  lines: string[];
-  publicSurfaces: string[];
-  nextQueries: string[];
-  maxResults: number;
-}
-
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: nested-directory brief formatting is clearer as one staged formatter
-function formatNonModuleDir(ctx: NonModuleDirContext): void {
-  const { model, mod, resolvedPath, originalPath, lines, publicSurfaces, nextQueries, maxResults } =
-    ctx;
-  const relPath = path.relative(model.root, resolvedPath);
-  lines.push(`# Directory: ${relPath || originalPath}`);
-  lines.push("");
-
-  if (mod) {
-    const shortName = mod.name.replace(/^@[^/]+\//, "");
-    lines.push(`_Inside module: ${shortName} (\`${mod.relativePath}\`)_`);
-    lines.push("");
-  }
-
-  const summary = summarizeDirectoryRecursively(resolvedPath);
-  if (summary.directFiles.length > 0) {
-    lines.push("## Source Files");
-    for (const f of summary.directFiles.slice(0, maxResults)) {
-      lines.push(`- \`${f}\``);
-    }
-    if (summary.directFiles.length > maxResults) {
-      lines.push(`- _+${summary.directFiles.length - maxResults} more files_`);
-    }
-    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_find\` with \`query: "..."\` and \`scope: "${relPath || originalPath}"\` to inspect a specific nested symbol`,
-    );
-  }
-
-  const inventory = collectDirectoryInventory(resolvedPath);
-  if (inventory.totalFiles > 0) {
-    addInventoryToLines(lines, inventory);
-  }
-
-  if (summary.totalSourceFiles === 0) {
-    lines.push("No recognized source files in this directory.");
-  }
-}
-
-// ── Module diagnostics ────────────────────────────────────────────────
-
-/**
- * Enrich a module brief with aggregated diagnostics for all source files.
- */
-async function enrichModuleWithDiagnostics(
-  lines: string[],
-  dirPath: string,
-  opts?: BriefOpts,
-): Promise<void> {
-  const sourceFiles = listSourceFiles(dirPath);
-  if (sourceFiles.length === 0 || !opts?.cwd) return;
-
-  const enrichmentDiags = await gatherModuleDiagnostics(
-    sourceFiles,
-    dirPath,
-    opts.cwd,
-    opts.lspService ??
-      ({ kind: "unavailable" as const, reason: "No LSP service" } as SessionLspServiceState),
-    opts.maxResults,
-  );
-  if (enrichmentDiags) {
-    lines.push(enrichmentDiags);
-  }
-}
-
-// biome-ignore lint/complexity/useMaxParams: lspService is a DI seam, not a logic parameter
-async function gatherModuleDiagnostics(
-  sourceFiles: string[],
-  dirPath: string,
-  cwd: string,
-  lspService: SessionLspServiceState,
-  maxResults?: number,
-): Promise<string | null> {
-  try {
-    if (lspService.kind !== "ready") return null;
-
-    const fileDiags: Array<{ file: string; errors: number; warnings: number }> = [];
-    for (const basename of sourceFiles) {
-      const fullPath = path.join(dirPath, basename);
-      const relPath = path.relative(cwd, fullPath);
-      try {
-        const diags = await lspService.service.fileDiagnostics(relPath, 2);
-        if (!diags || diags.length === 0) continue;
-        const errors = diags.filter((d) => (d.severity ?? 1) === 1).length;
-        const warnings = diags.filter((d) => (d.severity ?? 1) === 2).length;
-        if (errors > 0 || warnings > 0) {
-          fileDiags.push({ file: basename, errors, warnings });
-        }
-      } catch {
-        // Skip file
-      }
-    }
-
-    if (fileDiags.length === 0) return null;
-    return renderModuleDiagnostics(fileDiags, maxResults) ?? null;
-  } catch {
-    return null;
-  }
-}

package/src/analysis/brief/enrich.ts

@@ -1,157 +0,0 @@
-// 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

@@ -1,84 +0,0 @@
-/**
- * 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 };
-}