@mrclrchtr/supi-code-intelligence 1.7.0 → 1.9.0

package/src/tool/tool-specs.ts

@@ -7,26 +7,19 @@ import { executeMapTool } from "./execute-map.ts";
 import { executePatternTool } from "./execute-pattern.ts";
 import { executeRelationsTool } from "./execute-relations.ts";
 
-const PathParam = Type.String({ description: "Scope or focus path (package, directory, or file)" });
-const FileParam = Type.String({
-  description:
-    "Anchored target file (use with line/character) or a file-level semantic target where supported",
-});
-const LineParam = Type.Number({ description: "1-based line number for anchored target" });
-const CharacterParam = Type.Number({
-  description: "1-based character column (UTF-16) for anchored target",
-});
-const SymbolParam = Type.String({ description: "Symbol name for discovery-based resolution" });
-const PatternParam = Type.String({ description: "Text search pattern" });
-const RegexParam = Type.Boolean({ description: "Use regex semantics instead of literal matching" });
-const ExportedOnlyParam = Type.Boolean({ description: "Limit discovery to exported symbols" });
-const MaxResultsParam = Type.Number({ description: "Maximum results to return" });
-const ContextLinesParam = Type.Number({ description: "Context lines around matches" });
-const SummaryParam = Type.Boolean({
-  description: "Aggregate counts by directory instead of line-level matches",
-});
+const PathParam = Type.String({ description: "Scope path" });
+const FileParam = Type.String({ description: "Target file" });
+const LineParam = Type.Number({ description: "1-based line" });
+const CharacterParam = Type.Number({ description: "1-based UTF-16 column" });
+const SymbolParam = Type.String({ description: "Symbol name" });
+const PatternParam = Type.String({ description: "Search pattern" });
+const RegexParam = Type.Boolean({ description: "Regex search" });
+const ExportedOnlyParam = Type.Boolean({ description: "Exported symbols only" });
+const MaxResultsParam = Type.Number({ description: "Max results" });
+const ContextLinesParam = Type.Number({ description: "Context lines" });
+const SummaryParam = Type.Boolean({ description: "Summarize by directory" });
 const StructuredPatternKindParam = Type.String({
-  description: "Structured pattern kind (`definition` | `export` | `import`)",
+  description: "Structured kind: definition | export | import",
 });
 
 export const CODE_INTELLIGENCE_TOOL_NAMES = [
@@ -57,7 +50,7 @@ const CodeBriefParameters = Type.Object(
 
 const CodeMapParameters = Type.Object(
   {
-    path: Type.Optional(Type.String({ description: "Project, package, or directory path to map" })),
+    path: Type.Optional(Type.String({ description: "Project/package/dir path" })),
   },
   { additionalProperties: false },
 );
@@ -115,12 +108,11 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
   {
     name: "code_brief",
     label: "Code Brief",
-    description:
-      "Code brief tool — interpretive orientation for a project, package, directory, file, or symbol. Use code_brief when you need prioritized context and start-here guidance rather than raw search output.",
-    promptSnippet: "code_brief — interpretive orientation and start-here guidance",
+    description: "Prioritized brief for a project, package, directory, file, or symbol.",
+    promptSnippet: "code_brief — prioritized code orientation",
     basePromptGuidelines: [
-      "Use code_brief for a project, package, directory, file, or symbol overview when you need prioritized context.",
-      "Use code_brief before deeper drill-down when you want a start-here recommendation instead of raw inventory output.",
+      "Use code_brief for prioritized orientation on a project, package, file, or symbol.",
+      "Use code_brief before deeper drill-down when you need a start-here recommendation.",
     ],
     parameters: CodeBriefParameters,
     run: (params, ctx) => executeBriefTool(params as Parameters<typeof executeBriefTool>[0], ctx),
@@ -128,26 +120,19 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
   {
     name: "code_map",
     label: "Code Map",
-    description:
-      "Code map tool — factual inventory for a repo, package, or directory. Use code_map when you want counts, child directories, language mix, and landmark files without interpretive guidance.",
-    promptSnippet: "code_map — factual project, package, or directory inventory",
-    basePromptGuidelines: [
-      "Use code_map for a factual repo, package, or directory map when you need counts, landmark files, and local structure without interpretation.",
-      "Use code_map with `path` for any directory path you want to inventory; code_map should stay factual rather than prioritized.",
-    ],
+    description: "Factual map of a repo, package, or directory.",
+    promptSnippet: "code_map — factual repo or directory map",
+    basePromptGuidelines: ["Use code_map for counts, directories, language mix, and landmarks."],
     parameters: CodeMapParameters,
     run: (params, ctx) => executeMapTool(params as Parameters<typeof executeMapTool>[0], ctx),
   },
   {
     name: "code_relations",
     label: "Code Relations",
-    description:
-      'Code relations tool — trace callers, callees, or implementations for a resolved target. Use code_relations with `kind: "callers" | "callees" | "implementations"` when you need semantic or structural relationships rather than broad search.',
-    promptSnippet: "code_relations — callers, callees, or implementations for a resolved target",
+    description: "Trace callers, callees, or implementations for a resolved target.",
+    promptSnippet: "code_relations — callers, callees, or implementations",
     basePromptGuidelines: [
-      'Use code_relations with `kind: "callers"` to find who invokes a symbol or file-level surface.',
-      'Use code_relations with `kind: "callees"` to inspect outgoing calls from a function or method at a known position.',
-      'Use code_relations with `kind: "implementations"` to find which concrete types implement a declaration.',
+      "Use code_relations(kind) for `callers`, `callees`, or `implementations`.",
     ],
     parameters: CodeRelationsParameters,
     run: (params, ctx) =>
@@ -156,12 +141,10 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
   {
     name: "code_affected",
     label: "Code Affected",
-    description:
-      "Code affected tool — estimate blast radius, downstream impact, and risk for a target. Use code_affected before edits when you need an impact-oriented view rather than a plain relationship list.",
-    promptSnippet: "code_affected — blast radius, downstream impact, and risk",
+    description: "Estimate blast radius and downstream impact for a target.",
+    promptSnippet: "code_affected — blast radius and impact",
     basePromptGuidelines: [
-      "Use code_affected before edits when you need blast radius, downstream impact, and likely follow-up checks.",
-      "Use code_affected after you have a concrete file/position or symbol target to estimate change risk.",
+      "Use code_affected before edits to estimate blast radius and follow-up checks.",
     ],
     parameters: CodeAffectedParameters,
     run: (params, ctx) =>
@@ -170,12 +153,10 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
   {
     name: "code_pattern",
     label: "Code Pattern",
-    description:
-      "Code pattern tool — explicit literal, regex, or structured search within a bounded scope. Use code_pattern when you intentionally want search behavior rather than semantic or structural relationships.",
-    promptSnippet: "code_pattern — explicit literal, regex, or structured search",
+    description: "Run explicit search with literal, regex, or structured matching.",
+    promptSnippet: "code_pattern — explicit code search",
     basePromptGuidelines: [
-      "Use code_pattern for explicit literal or regex search within a bounded path.",
-      'Use code_pattern with `kind: "definition" | "export" | "import"` for structured search instead of plain text matching.',
+      "Use code_pattern for literal, regex, or structured search in a bounded path.",
     ],
     parameters: CodePatternParameters,
     run: (params, ctx) =>

package/src/types.ts

@@ -1,10 +1,108 @@
-// Shared types for code intelligence tool results and metadata.
+// ── Canonical shared types for the code-understanding stack ─────────────
 
-import type { PrioritySignalsSummary } from "./prioritization-signals.ts";
+/** 0-based LSP position. */
+export interface CodePosition {
+  line: number;
+  character: number;
+}
+
+/** A source range spanning two CodePositions. */
+export interface SourceRange {
+  start: CodePosition;
+  end: CodePosition;
+}
+
+/** A code location (file URI + range). */
+export interface CodeLocation {
+  uri: string;
+  range: SourceRange;
+}
 
-/** Confidence vocabulary for result labeling. */
+/** A discovered symbol / declaration. */
+export interface CodeSymbol {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  character: number;
+  container?: string | null;
+}
+
+/** Discriminated result union for provider operations. */
+export type CodeResult<T> =
+  | { kind: "success"; data: T }
+  | { kind: "unsupported-language"; file: string; message: string }
+  | { kind: "file-access-error"; file: string; message: string }
+  | { kind: "validation-error"; message: string }
+  | { kind: "runtime-error"; message: string }
+  | { kind: "unavailable"; message: string };
+
+/** Result confidence classification. */
 export type ConfidenceMode = "semantic" | "structural" | "heuristic" | "unavailable";
 
+/** Provider availability states. */
+export type ProviderAvailability =
+  | { kind: "pending" }
+  | { kind: "ready" }
+  | { kind: "disabled" }
+  | { kind: "inactive" }
+  | { kind: "unavailable"; reason: string };
+
+// ── Structural data shapes (value types, range-flattened) ──────────────
+
+export interface OutlineData {
+  name: string;
+  kind: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  children?: OutlineData[];
+}
+
+export interface ExportData {
+  name: string;
+  kind: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  moduleSpecifier?: string;
+}
+
+export interface ImportData {
+  moduleSpecifier: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+}
+
+export interface NodeAtData {
+  type: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  text: string;
+  ancestry: Array<{
+    type: string;
+    startLine: number;
+    startCharacter: number;
+    endLine: number;
+    endCharacter: number;
+  }>;
+}
+
+export interface CalleesData {
+  enclosingScope: { name: string; startLine: number; endLine: number };
+  callees: Array<{ name: string; startLine: number }>;
+}
+
+// ── Existing code-intelligence types ──────────────────────────────────
+
+import type { PrioritySignalsSummary } from "./prioritization-signals.ts";
+
 /** Structured details metadata returned alongside markdown brief content. */
 export interface BriefDetails {
   confidence: ConfidenceMode;

package/src/use-case/build-overview.ts

@@ -0,0 +1,36 @@
+// Typed overview data builder from ArchitectureModel.
+
+import { formatGitContext, gatherGitContext } from "../git-context.ts";
+import type { ArchitectureModel } from "../model.ts";
+import type { OverviewData, OverviewModule } from "./types.ts";
+
+/**
+ * Build structured overview data from an architecture model.
+ * No markdown rendering — callers pass the result to a presentation renderer.
+ */
+export function buildOverviewData(model: ArchitectureModel): OverviewData | null {
+  if (model.modules.length === 0) return null;
+
+  const dependedOn = new Set(model.edges.map((e) => e.to));
+
+  const modules: OverviewModule[] = model.modules.slice(0, 8).map((mod) => ({
+    name: mod.name,
+    shortName: mod.name.replace(/^@[^/]+\//, ""),
+    description: mod.description,
+    isLeaf: !dependedOn.has(mod.name),
+    internalDeps: mod.internalDeps,
+  }));
+
+  const omittedModuleCount = Math.max(0, model.modules.length - 8);
+
+  const gitCtx = gatherGitContext(model.root);
+  const gitContextOverview = gitCtx ? formatGitContext(gitCtx) : null;
+
+  return {
+    projectName: model.name,
+    projectDescription: model.description,
+    modules,
+    omittedModuleCount,
+    gitContextOverview,
+  };
+}

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

@@ -0,0 +1,297 @@
+// Affected orchestration use-case — blast-radius analysis for a symbol change.
+// Coordinates target resolution, reference collection, architecture analysis, and
+// returns fully rendered content + details metadata.
+
+import * as path from "node:path";
+import { buildArchitectureModel, findModuleForPath, getDependents } from "../model.ts";
+import {
+  renderAffectedFileLevel,
+  renderAffectedSingle,
+} from "../presentation/markdown/affected.ts";
+import { summarizePrioritySignalsForFiles } from "../prioritization-signals.ts";
+import { resolveTarget } from "../resolve-target.ts";
+import { isResolvedTargetGroup } from "../semantic-action-helpers.ts";
+import type { ResolvedTarget, ResolvedTargetGroup } from "../target-resolution.ts";
+import type { AffectedDetails, CodeIntelResult, ConfidenceMode } from "../types.ts";
+import type { CodeProvider } from "../workspace/request-context.ts";
+import {
+  aggregatePerTarget,
+  collectReferences,
+  type ReferenceCollection,
+} from "./support/semantic-references.ts";
+
+export interface AffectedInput {
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  exportedOnly?: boolean;
+  maxResults?: number;
+}
+
+export interface AffectedDeps {
+  cwd: string;
+  provider: CodeProvider | null;
+}
+
+/** Execute the affected use-case — target resolution, reference collection, analysis, and rendering. */
+export async function executeAffected(
+  input: AffectedInput,
+  deps: AffectedDeps,
+): Promise<CodeIntelResult> {
+  const semantic = deps.provider;
+  if (!semantic) {
+    return {
+      content:
+        "**Error:** Affected analysis requires an active code provider (LSP). Enable LSP and retry.",
+      details: {
+        type: "affected" as const,
+        data: {
+          confidence: "unavailable",
+          directCount: 0,
+          downstreamCount: 0,
+          riskLevel: "low",
+          checkNext: [],
+          likelyTests: [],
+          omittedCount: 0,
+          nextQueries: ["Provide `file`, `line`, `character` or a `symbol` to resolve the target"],
+        },
+      },
+    };
+  }
+  const target = await resolveTarget(input, deps.cwd, semantic);
+
+  if (typeof target === "string") {
+    return {
+      content: target,
+      details: {
+        type: "affected" as const,
+        data: {
+          confidence: "unavailable",
+          directCount: 0,
+          downstreamCount: 0,
+          riskLevel: "low",
+          checkNext: [],
+          likelyTests: [],
+          omittedCount: 0,
+          nextQueries: ["Provide `file`, `line`, `character` or a `symbol` to resolve the target"],
+        },
+      },
+    };
+  }
+
+  if (isResolvedTargetGroup(target)) {
+    return executeFileLevelAffected(target, input, deps.cwd, semantic);
+  }
+
+  const symbolName =
+    target.name ?? `symbol at ${path.relative(deps.cwd, target.file)}:${target.displayLine}`;
+  return executeSingleAffected(target, symbolName, input, deps.cwd, semantic);
+}
+
+// ── Single target ────────────────────────────────────────────────────
+
+interface ImpactAnalysis {
+  confidence: ConfidenceMode;
+  affectedFiles: Set<string>;
+  affectedModules: Set<string>;
+  downstreamCount: number;
+  checkNext: string[];
+  likelyTests: string[];
+  riskLevel: "low" | "medium" | "high";
+  externalRefs: number;
+}
+
+// biome-ignore lint/complexity/useMaxParams: substrate injection and analysis inputs keep related parameters explicit
+async function executeSingleAffected(
+  target: ResolvedTarget,
+  symbolName: string,
+  input: AffectedInput,
+  cwd: string,
+  semantic: CodeProvider,
+): Promise<CodeIntelResult> {
+  const refs = await collectReferences(target, cwd, semantic);
+  const model = await buildArchitectureModel(cwd);
+  const analysis = analyzeImpact(refs, model, target.name, cwd);
+
+  const prioritySignals = summarizePrioritySignalsForFiles(
+    cwd,
+    analysis.affectedFiles.size > 0 ? [...analysis.affectedFiles] : [target.file],
+  );
+
+  const content = renderAffectedSingle({
+    symbolName,
+    refs,
+    analysis,
+    maxResults: input.maxResults ?? 8,
+    prioritySignals,
+    target,
+    cwd,
+  });
+
+  const details: AffectedDetails = {
+    confidence: analysis.confidence,
+    directCount: refs.refs.length,
+    downstreamCount: analysis.downstreamCount,
+    riskLevel: analysis.riskLevel,
+    checkNext: analysis.checkNext,
+    likelyTests: analysis.likelyTests,
+    omittedCount: computeOmittedCount(analysis.externalRefs, analysis.affectedFiles.size, input),
+    nextQueries: buildAffectedNextQueries(target, symbolName, cwd),
+    prioritySignals,
+  };
+
+  return { content, details: { type: "affected" as const, data: details } };
+}
+
+// ── File-level target group ──────────────────────────────────────────
+
+async function executeFileLevelAffected(
+  targetGroup: ResolvedTargetGroup,
+  input: AffectedInput,
+  cwd: string,
+  semantic: CodeProvider,
+): Promise<CodeIntelResult> {
+  const perTarget = await Promise.all(
+    targetGroup.targets.map(async (t) => ({
+      target: t,
+      refs: await collectReferences(t, cwd, semantic),
+    })),
+  );
+
+  const aggregated = await aggregatePerTarget(targetGroup.targets, (t) =>
+    collectReferences(t, cwd, semantic),
+  );
+
+  const model = await buildArchitectureModel(cwd);
+  const analysis = analyzeImpact(aggregated, model, null, cwd);
+
+  const prioritySignals = summarizePrioritySignalsForFiles(
+    cwd,
+    analysis.affectedFiles.size > 0 ? [...analysis.affectedFiles] : [targetGroup.file],
+  );
+
+  const content = renderAffectedFileLevel({
+    targetGroup,
+    perTarget,
+    aggregated,
+    analysis,
+    maxResults: input.maxResults ?? 8,
+    prioritySignals,
+  });
+
+  const details: AffectedDetails = {
+    confidence: analysis.confidence,
+    directCount: aggregated.refs.length,
+    downstreamCount: analysis.downstreamCount,
+    riskLevel: analysis.riskLevel,
+    checkNext: analysis.checkNext,
+    likelyTests: analysis.likelyTests,
+    omittedCount: computeOmittedCount(analysis.externalRefs, analysis.affectedFiles.size, input),
+    nextQueries: [
+      "`code_brief` on the most-affected module for deeper context",
+      "Use `file` + coordinates to inspect one exported target precisely",
+    ],
+    prioritySignals,
+  };
+
+  return { content, details: { type: "affected" as const, data: details } };
+}
+
+// ── Impact analysis ──────────────────────────────────────────────────
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: impact analysis with downstream module traversal and multiple risk dimensions is clearer as one function
+function analyzeImpact(
+  result: ReferenceCollection,
+  model: Awaited<ReturnType<typeof buildArchitectureModel>>,
+  _symbolName: string | null,
+  cwd: string,
+): ImpactAnalysis {
+  const affectedFiles = new Set(result.refs.map((r) => r.file));
+  const affectedModules = new Set<string>();
+  const checkNext: string[] = [];
+  let downstreamCount = 0;
+
+  if (model) {
+    for (const file of affectedFiles) {
+      const mod = findModuleForPath(model, path.resolve(cwd, file));
+      if (mod) affectedModules.add(mod.name);
+    }
+
+    const downstreamModules = new Set<string>();
+    const queue = [...affectedModules];
+    while (queue.length > 0) {
+      const modName = queue.shift() as string;
+      for (const dep of getDependents(model, modName)) {
+        if (!affectedModules.has(dep.name) && !downstreamModules.has(dep.name)) {
+          downstreamModules.add(dep.name);
+          queue.push(dep.name);
+        }
+      }
+    }
+    downstreamCount = downstreamModules.size;
+
+    for (const modName of [...affectedModules, ...downstreamModules].slice(0, 3)) {
+      const mod = model.modules.find((m) => m.name === modName);
+      if (mod) checkNext.push(`${mod.name.replace(/^@[^/]+\//, "")} (\`${mod.relativePath}\`)`);
+    }
+  }
+
+  const likelyTests = findLikelyTests(affectedFiles);
+  const riskLevel = assessRisk(
+    result.refs.length + result.externalCount,
+    affectedModules.size,
+    downstreamCount,
+  );
+
+  return {
+    confidence: result.confidence,
+    affectedFiles,
+    affectedModules,
+    downstreamCount,
+    checkNext,
+    likelyTests,
+    riskLevel,
+    externalRefs: result.externalCount,
+  };
+}
+
+function findLikelyTests(affectedFiles: Set<string>): string[] {
+  const tests: string[] = [];
+  for (const file of affectedFiles) {
+    if (file.includes("test") || file.includes("spec") || file.includes("__tests__")) {
+      tests.push(file);
+    }
+  }
+  return tests.slice(0, 3);
+}
+
+function assessRisk(
+  totalRefs: number,
+  moduleCount: number,
+  downstreamCount: number,
+): "low" | "medium" | "high" {
+  if (totalRefs > 10 || moduleCount > 3 || downstreamCount > 1) return "high";
+  if (totalRefs > 3 || moduleCount > 1 || downstreamCount >= 1) return "medium";
+  return "low";
+}
+
+function computeOmittedCount(
+  externalRefs: number,
+  affectedFileCount: number,
+  input: AffectedInput,
+): number {
+  return externalRefs + Math.max(0, affectedFileCount - (input.maxResults ?? 8));
+}
+
+function buildAffectedNextQueries(
+  target: ResolvedTarget,
+  symbolName: string,
+  cwd: string,
+): string[] {
+  const relPath = path.relative(cwd, target.file);
+  return [
+    `\`code_brief\` with \`file: "${relPath}"\`, \`line: ${target.displayLine}\`, and \`character: ${target.displayCharacter}\` for deeper context around ${symbolName}`,
+    `\`code_relations\` with \`kind: "callers"\`, \`file: "${relPath}"\`, \`line: ${target.displayLine}\`, and \`character: ${target.displayCharacter}\` for call sites`,
+  ];
+}