@mrclrchtr/supi-code-intelligence 1.7.0 → 1.8.0

package/src/use-case/generate-brief.ts

@@ -0,0 +1,324 @@
+// Brief orchestration use-case — dispatches by mode, coordinates substrate access,
+// and returns fully rendered markdown content + details metadata.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ArchitectureModel } from "../architecture.ts";
+import { findModuleForPath } from "../architecture.ts";
+import { generateFocusedBrief, generateProjectBrief } from "../brief.ts";
+import { renderAnchoredBrief, renderSymbolBrief } from "../presentation/markdown/brief.ts";
+import { normalizePath } from "../search-helpers.ts";
+import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
+import type { TargetResolutionResult } from "../target-resolution.ts";
+import { resolveSymbolTarget } from "../target-resolution.ts";
+import type { BriefDeps, BriefInput, BriefUseCaseResult } from "./types.ts";
+
+// ── TreeSitterContext is an intermediate data shape from the use-case ──
+
+export interface TreeSitterContext {
+  nodeInfo: { type: string; text: string; startLine: number; startCharacter: number } | null;
+  outline: Array<{ name: string; kind: string; startLine: number; endLine: number }>;
+  imports: Array<{ moduleSpecifier: string }>;
+  exports: Array<{ name: string; kind: string }>;
+}
+
+// ── Public entrypoint ─────────────────────────────────────────────────
+
+export async function executeBrief(
+  input: BriefInput,
+  deps: BriefDeps,
+): Promise<BriefUseCaseResult> {
+  switch (input.kind) {
+    case "project":
+      if (deps.model) {
+        return executeProjectBrief(deps.model);
+      }
+      return noModelResult();
+    case "path":
+      return executePathBrief(input.path, deps);
+    case "file":
+      return executeFileBrief(input.file, deps);
+    case "anchored":
+      return executeAnchoredBrief(input, deps);
+    case "symbol":
+      return executeSymbolBrief(input.symbol, input.path, deps);
+  }
+}
+
+// ── Project brief ─────────────────────────────────────────────────────
+
+function executeProjectBrief(model: ArchitectureModel): BriefUseCaseResult {
+  if (!model) {
+    return noModelResult();
+  }
+  const result = generateProjectBrief(model);
+  return { content: result.content, details: result.details };
+}
+
+// ── Path / file briefs ────────────────────────────────────────────────
+
+function executePathBrief(requestPath: string, deps: BriefDeps): BriefUseCaseResult {
+  if (!deps.model) {
+    return noModelResult();
+  }
+  const resolved = normalizePath(requestPath, deps.cwd);
+  const result = generateFocusedBrief(deps.model, resolved);
+  return { content: result.content, details: result.details };
+}
+
+function executeFileBrief(file: string, deps: BriefDeps): BriefUseCaseResult {
+  if (!deps.model) {
+    return noModelResult();
+  }
+  const resolved = normalizePath(file, deps.cwd);
+  const result = generateFocusedBrief(deps.model, resolved);
+  return { content: result.content, details: result.details };
+}
+
+// ── Anchored brief ────────────────────────────────────────────────────
+
+async function executeAnchoredBrief(
+  input: { file: string; line: number; character: number },
+  deps: BriefDeps,
+): Promise<BriefUseCaseResult> {
+  const { file, line, character } = input;
+  const resolvedFile = normalizePath(file, deps.cwd);
+
+  if (!fs.existsSync(resolvedFile)) {
+    return {
+      content: `**Error:** File not found: \`${file}\``,
+      details: {
+        confidence: "unavailable",
+        focusTarget: `${file}:${line}:${character}`,
+        startHere: [],
+        publicSurfaces: [],
+        dependencySummary: null,
+        omittedCount: 0,
+        nextQueries: [],
+      },
+    };
+  }
+
+  const relPath = path.relative(deps.cwd, resolvedFile);
+  const context = await gatherTreeSitterContext(deps.structural, relPath, line, character);
+
+  const details = {
+    confidence: "structural" as const,
+    focusTarget: `${relPath}:${line}:${character}`,
+    startHere: [] as Array<{ target: string; reason: string }>,
+    publicSurfaces: [] as string[],
+    dependencySummary: null as { moduleCount: number; edgeCount: number } | null,
+    omittedCount: 0,
+    nextQueries: [
+      `\`code_relations\` with \`kind: "callers"\`, \`file: "${relPath}"\`, \`line: ${line}\`, and \`character: ${character}\` for call sites`,
+      `\`code_affected\` with \`file: "${relPath}"\`, \`line: ${line}\`, and \`character: ${character}\` for impact analysis`,
+    ],
+  };
+
+  const rendered = renderAnchoredBrief({
+    relPath,
+    line,
+    character,
+    context,
+    model: deps.model ?? null,
+    details,
+    cwd: deps.cwd,
+  });
+
+  return rendered;
+}
+
+// ── Symbol brief ──────────────────────────────────────────────────────
+
+async function executeSymbolBrief(
+  symbol: string,
+  scopePath: string | undefined,
+  deps: BriefDeps,
+): Promise<BriefUseCaseResult> {
+  if (!deps.model || deps.model.modules.length === 0) {
+    return {
+      content: `**Error:** Symbol brief requires a project model, which is not available.`,
+      details: {
+        confidence: "unavailable",
+        focusTarget: symbol,
+        startHere: [],
+        publicSurfaces: [],
+        dependencySummary: null,
+        omittedCount: 0,
+        nextQueries: ["Add a package.json or workspace manifest to enable architecture analysis"],
+      },
+    };
+  }
+
+  const semanticModule = await import("../substrates/lsp-adapter.ts");
+  const semantic: SemanticSubstrate = semanticModule.createSemanticSubstrate(deps.cwd);
+  const resolved = await resolveSymbolTarget(symbol, deps.cwd, semantic, {
+    path: scopePath,
+  });
+
+  if (resolved.kind === "error") {
+    return {
+      content: resolved.message,
+      details: {
+        confidence: "unavailable",
+        focusTarget: symbol,
+        startHere: [],
+        publicSurfaces: [],
+        dependencySummary: null,
+        omittedCount: 0,
+        nextQueries: [
+          "Use `file` + coordinates for a precise symbol brief, or enable LSP and retry",
+        ],
+      },
+    };
+  }
+
+  if (resolved.kind === "disambiguation") {
+    const disambiguationContent = formatDisambiguation(symbol, resolved);
+    return {
+      content: disambiguationContent,
+      details: {
+        confidence: "unavailable",
+        focusTarget: symbol,
+        startHere: [],
+        publicSurfaces: [],
+        dependencySummary: null,
+        omittedCount: resolved.omittedCount,
+        nextQueries: [
+          "Use `file` + coordinates for a precise symbol brief, or enable LSP and retry",
+        ],
+      },
+    };
+  }
+
+  const target = resolved.target;
+  const relPath = path.relative(deps.cwd, target.file);
+
+  const mod = findModuleForPath(deps.model, target.file);
+  const context = await gatherTreeSitterContext(
+    deps.structural,
+    relPath,
+    target.displayLine,
+    target.displayCharacter,
+  );
+
+  const details = {
+    confidence: target.confidence,
+    focusTarget: `${target.name ?? relPath}:${target.displayLine}:${target.displayCharacter}`,
+    startHere: [] as Array<{ target: string; reason: string }>,
+    publicSurfaces: [] as string[],
+    dependencySummary: mod ? { moduleCount: 1, edgeCount: mod.internalDeps.length } : null,
+    omittedCount: 0,
+    nextQueries: [
+      `\`code_relations\` with \`kind: "callers"\`, \`file: "${relPath}"\`, \`line: ${target.displayLine}\`, and \`character: ${target.displayCharacter}\` for call sites`,
+      `\`code_affected\` with \`file: "${relPath}"\`, \`line: ${target.displayLine}\`, and \`character: ${target.displayCharacter}\` for impact analysis`,
+    ],
+  };
+
+  const rendered = renderSymbolBrief({
+    relPath,
+    symbolName: target.name ?? "",
+    targetLine: target.displayLine,
+    targetCharacter: target.displayCharacter,
+    targetKind: target.kind,
+    context,
+    model: deps.model ?? null,
+    details,
+    cwd: deps.cwd,
+  });
+
+  return rendered;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+async function gatherTreeSitterContext(
+  structural: StructuralSubstrate,
+  relPath: string,
+  line: number,
+  character: number,
+): Promise<TreeSitterContext> {
+  let nodeInfo: TreeSitterContext["nodeInfo"] = null;
+  let outline: TreeSitterContext["outline"] = [];
+  let imports: TreeSitterContext["imports"] = [];
+  let exports: TreeSitterContext["exports"] = [];
+
+  try {
+    const nodeResult = await structural.nodeAt(relPath, line, character);
+    if (nodeResult.kind === "success") {
+      nodeInfo = {
+        type: nodeResult.data.type,
+        text: nodeResult.data.text,
+        startLine: nodeResult.data.startLine,
+        startCharacter: nodeResult.data.startCharacter,
+      };
+    }
+
+    const outlineResult = await structural.outline(relPath);
+    if (outlineResult.kind === "success") {
+      outline = outlineResult.data.map((item) => ({
+        name: item.name,
+        kind: item.kind,
+        startLine: item.startLine,
+        endLine: item.endLine,
+      }));
+    }
+
+    const importsResult = await structural.imports(relPath);
+    if (importsResult.kind === "success") {
+      imports = importsResult.data;
+    }
+
+    const exportsResult = await structural.exports(relPath);
+    if (exportsResult.kind === "success") {
+      exports = exportsResult.data.map((item) => ({
+        name: item.name,
+        kind: item.kind,
+      }));
+    }
+  } catch {
+    // Tree-sitter not available
+  }
+
+  return { nodeInfo, outline, imports, exports };
+}
+
+function noModelResult(): BriefUseCaseResult {
+  return {
+    content:
+      "No project structure detected. This directory has no recognizable project metadata or source files.",
+    details: {
+      confidence: "unavailable",
+      focusTarget: null,
+      startHere: [],
+      publicSurfaces: [],
+      dependencySummary: null,
+      omittedCount: 0,
+      nextQueries: ["Add a package.json or pnpm-workspace.yaml to enable architecture analysis"],
+    },
+  };
+}
+
+function formatDisambiguation(
+  symbol: string,
+  result: Extract<TargetResolutionResult, { kind: "disambiguation" }>,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Disambiguation needed for \`${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 candidate of result.candidates) {
+    const kind = candidate.kind ? ` (${candidate.kind})` : "";
+    const container = candidate.container ? ` in ${candidate.container}` : "";
+    lines.push(
+      `${candidate.rank}. **${candidate.name}**${kind}${container} — \`${candidate.file}\`:${candidate.line}:${candidate.character}`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/{actions/map-action.ts → use-case/generate-map.ts}

@@ -1,6 +1,22 @@
+// Map use-case — typed filesystem scanning for factual project/directory inventory.
+// Produces structured data for the markdown renderer.
+
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { CodeIntelResult, MapDetails } from "../types.ts";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface MapStats {
+  byExtension: Map<string, number>;
+  byChildDir: Map<string, number>;
+  landmarkFiles: string[];
+  total: number;
+}
+
+export interface MapData {
+  scope: string;
+  stats: MapStats;
+}
 
 const SOURCE_EXTENSIONS = new Map([
   [".ts", "TypeScript"],
@@ -79,30 +95,16 @@ const LANDMARK_FILES = new Set([
 
 const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
 
-interface FileStats {
-  byExtension: Map<string, number>;
-  byChildDir: Map<string, number>;
-  landmarkFiles: string[];
-  total: number;
-}
+// ── Public entrypoint ────────────────────────────────────────────────
 
-export function executeMapAction(scopePath: string, cwd: string): CodeIntelResult {
+export function buildMapData(scopePath: string, cwd: string): MapData {
   const stats = gatherStats(scopePath);
   const scope = formatScope(scopePath, cwd);
-  const content = formatMap(scope, stats);
-  const details: MapDetails = {
-    scope,
-    totalFiles: stats.total,
-    childDirectoryCount: stats.byChildDir.size,
-    landmarkCount: stats.landmarkFiles.length,
-    nextQueries: ["`code_brief` for prioritized context on this scope"],
-  };
-
-  return { content, details: { type: "map", data: details } };
+  return { scope, stats };
 }
 
-function gatherStats(scopePath: string): FileStats {
-  const stats: FileStats = {
+function gatherStats(scopePath: string): MapStats {
+  const stats: MapStats = {
     byExtension: new Map<string, number>(),
     byChildDir: new Map<string, number>(),
     landmarkFiles: [],
@@ -113,7 +115,7 @@ function gatherStats(scopePath: string): FileStats {
   return stats;
 }
 
-function walkDirectory(dir: string, rel: string, stats: FileStats): void {
+function walkDirectory(dir: string, rel: string, stats: MapStats): void {
   const entries = readEntries(dir);
   if (!entries) return;
 
@@ -132,10 +134,12 @@ function readEntries(dir: string): fs.Dirent[] | null {
 }
 
 function shouldSkipEntry(entry: fs.Dirent): boolean {
-  return entry.name.startsWith(".") || SKIP_DIRS.has(entry.name);
+  // Skip hidden directories and node_modules, but keep dot-prefixed landmark files
+  if (entry.name.startsWith(".") && entry.isDirectory()) return true;
+  return SKIP_DIRS.has(entry.name);
 }
 
-function visitEntry(dir: string, rel: string, entry: fs.Dirent, stats: FileStats): void {
+function visitEntry(dir: string, rel: string, entry: fs.Dirent, stats: MapStats): void {
   const entryRel = rel ? `${rel}/${entry.name}` : entry.name;
   const fullPath = path.join(dir, entry.name);
 
@@ -147,7 +151,7 @@ function visitEntry(dir: string, rel: string, entry: fs.Dirent, stats: FileStats
   recordFileStats(entry.name, entryRel, stats);
 }
 
-function recordFileStats(entryName: string, entryRel: string, stats: FileStats): void {
+function recordFileStats(entryName: string, entryRel: string, stats: MapStats): void {
   stats.total++;
   const ext = path.extname(entryName).toLowerCase();
   stats.byExtension.set(ext, (stats.byExtension.get(ext) ?? 0) + 1);
@@ -162,45 +166,11 @@ function recordFileStats(entryName: string, entryRel: string, stats: FileStats):
   }
 }
 
-function formatMap(scope: string, stats: FileStats): string {
-  const lines: string[] = [];
-
-  lines.push(`# Code Map: ${scope}`);
-  lines.push("");
-  lines.push(`**Files:** ${stats.total} total`);
-  for (const [ext, count] of [...stats.byExtension.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 10)) {
-    const label = SOURCE_EXTENSIONS.get(ext) ?? (ext || "(no extension)");
-    lines.push(`- ${label}: ${count}`);
-  }
-  if (stats.byExtension.size > 10) {
-    lines.push(`- _+${stats.byExtension.size - 10} more extensions_`);
-  }
-  lines.push("");
-
-  if (stats.byChildDir.size > 0) {
-    lines.push("**Child directories:**");
-    for (const [dir, count] of [...stats.byChildDir.entries()].sort((a, b) => b[1] - a[1])) {
-      lines.push(`- ${dir}/ (${count} file${count !== 1 ? "s" : ""})`);
-    }
-    lines.push("");
-  }
-
-  if (stats.landmarkFiles.length > 0) {
-    lines.push("**Landmark files:**");
-    for (const file of stats.landmarkFiles) {
-      lines.push(`- \`${file}\``);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
 function formatScope(scopePath: string, cwd: string): string {
   const relative = path.relative(cwd, scopePath);
   if (relative === "") return ".";
   if (relative.startsWith(`..${path.sep}`) || relative === "..") return scopePath;
   return relative.replaceAll(path.sep, "/");
 }
+
+export { SOURCE_EXTENSIONS };