@mrclrchtr/supi-code-intelligence 1.6.0 → 1.8.0

package/src/tool/guidance.ts

@@ -1,18 +1,58 @@
-// Prompt guidance and tool description for the code_intel tool.
+// Prompt guidance and tool descriptions for the focused code-intelligence tool surface.
+//
+// Each code_* tool owns its base prompt guidelines (describing its own surface).
+// Additional cross-family orchestration guidelines are appended to help the
+// model choose between code_*, lsp_*, and tree_sitter_* tools.
 
-import { CODE_INTEL_ACTION_SPECS, formatCodeIntelActionList } from "./action-specs.ts";
+import { CODE_INTELLIGENCE_TOOL_SPECS, type CodeIntelligenceToolName } from "./tool-specs.ts";
 
-export const toolDescription = `Code intelligence tool — codebase orientation, semantic relationships, impact analysis, and scoped search.
+export interface CodeIntelligenceToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
 
-Actions: ${formatCodeIntelActionList()}.
+export type CodeIntelligenceToolPromptSurfaceMap = Record<
+  CodeIntelligenceToolName,
+  CodeIntelligenceToolPromptSurface
+>;
 
-Use code_intel to localize relevant files before precise drill-down: summarize a project/package/file, find callers/callees/implementations, estimate blast radius, or search within a scope. Prefer lsp_lookup, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_refactor, and lsp_recover for semantic drill-down once the target is known; use tree_sitter for exact syntax and read/rg once you know the file. line and character are 1-based and require file. pattern is literal unless regex is true; kind supports definition, export, or import. Relative paths resolve from cwd, and leading @ on path/file is stripped.`;
+// ── Cross-family orchestration guidelines ──────────────────────────────
+//
+// These are appended to the appropriate code_* tools so the model sees a
+// coherent strategy for choosing between code_*, lsp_*, and tree_sitter_*
+// tools.  They do not re-own substrate metadata — each of the other packages
+// describes and documents its own tools independently.
 
-export const promptGuidelines = [
-  ...CODE_INTEL_ACTION_SPECS.map((spec) => spec.promptGuideline),
-  "Use code_intel with `file`, `line`, and `character` for anchored positions; do not pair `line` or `character` with `path`.",
-  "Use code_intel first when the area is not yet localized; switch to lsp_lookup, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_refactor, or lsp_recover for semantic drill-down once code_intel narrows the target.",
-];
+const ORCHESTRATION_GUIDELINES: Record<CodeIntelligenceToolName, string[]> = {
+  code_brief: [
+    "After code_brief, use lsp_hover/lsp_definition/lsp_references for semantic detail or tree_sitter_* for quick structure.",
+  ],
+  code_map: ["Use code_brief instead when you need prioritized guidance."],
+  code_relations: [
+    "Follow caller results with lsp_references/lsp_definition; use tree_sitter_callees for structural outgoing calls.",
+  ],
+  code_affected: [
+    "Use lsp_references instead when you need a plain reference list, not impact analysis.",
+  ],
+  code_pattern: [
+    "Use tree_sitter_query or lsp_hover/lsp_definition when you need structure or semantic precision.",
+  ],
+};
 
-export const promptSnippet =
-  "code_intel — codebase orientation, callers/callees, blast radius, and scoped search before file drill-down";
+// ── Surface builder ────────────────────────────────────────────────────
+
+export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolPromptSurfaceMap {
+  return Object.fromEntries(
+    CODE_INTELLIGENCE_TOOL_SPECS.map((spec) => [
+      spec.name,
+      {
+        description: spec.description,
+        promptSnippet: spec.promptSnippet,
+        promptGuidelines: [...spec.basePromptGuidelines, ...ORCHESTRATION_GUIDELINES[spec.name]],
+      } satisfies CodeIntelligenceToolPromptSurface,
+    ]),
+  ) as CodeIntelligenceToolPromptSurfaceMap;
+}
+
+export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES = buildCodeIntelligenceToolPromptSurfaces();

package/src/tool/register-tools.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
+  type CodeIntelligenceToolPromptSurfaceMap,
+} from "./guidance.ts";
+import { CODE_INTELLIGENCE_TOOL_SPECS } from "./tool-specs.ts";
+
+/** Register the focused code-intelligence tool surface from shared specs. */
+export function registerCodeIntelligenceTools(
+  pi: ExtensionAPI,
+  promptSurfaces: CodeIntelligenceToolPromptSurfaceMap = CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
+): void {
+  for (const spec of CODE_INTELLIGENCE_TOOL_SPECS) {
+    const surface = promptSurfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface.description,
+      promptSnippet: surface.promptSnippet,
+      promptGuidelines: surface.promptGuidelines,
+      parameters: spec.parameters,
+      // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+      execute: async (_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) => {
+        const { content, details } = await spec.run(params, { cwd: ctx.cwd });
+        return {
+          content: [{ type: "text" as const, text: content }],
+          details,
+        };
+      },
+    });
+  }
+}

package/src/tool/tool-specs.ts

@@ -0,0 +1,165 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+import type { CodeIntelResult } from "../types.ts";
+import { executeAffectedTool } from "./execute-affected.ts";
+import { executeBriefTool } from "./execute-brief.ts";
+import { executeMapTool } from "./execute-map.ts";
+import { executePatternTool } from "./execute-pattern.ts";
+import { executeRelationsTool } from "./execute-relations.ts";
+
+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 kind: definition | export | import",
+});
+
+export const CODE_INTELLIGENCE_TOOL_NAMES = [
+  "code_brief",
+  "code_map",
+  "code_relations",
+  "code_affected",
+  "code_pattern",
+] as const;
+export type CodeIntelligenceToolName = (typeof CODE_INTELLIGENCE_TOOL_NAMES)[number];
+
+export const CODE_RELATION_KIND_NAMES = ["callers", "callees", "implementations"] as const;
+export type CodeRelationsKind = (typeof CODE_RELATION_KIND_NAMES)[number];
+
+const CodeRelationsKindEnum = StringEnum(CODE_RELATION_KIND_NAMES);
+
+const CodeBriefParameters = Type.Object(
+  {
+    path: Type.Optional(PathParam),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+const CodeMapParameters = Type.Object(
+  {
+    path: Type.Optional(Type.String({ description: "Project/package/dir path" })),
+  },
+  { additionalProperties: false },
+);
+
+const CodeRelationsParameters = Type.Object(
+  {
+    kind: CodeRelationsKindEnum,
+    path: Type.Optional(PathParam),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    exportedOnly: Type.Optional(ExportedOnlyParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+const CodeAffectedParameters = Type.Object(
+  {
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    exportedOnly: Type.Optional(ExportedOnlyParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+const CodePatternParameters = Type.Object(
+  {
+    path: Type.Optional(PathParam),
+    pattern: PatternParam,
+    regex: Type.Optional(RegexParam),
+    kind: Type.Optional(StructuredPatternKindParam),
+    maxResults: Type.Optional(MaxResultsParam),
+    contextLines: Type.Optional(ContextLinesParam),
+    summary: Type.Optional(SummaryParam),
+  },
+  { additionalProperties: false },
+);
+
+export interface CodeIntelligenceToolDefinitionSpec {
+  name: CodeIntelligenceToolName;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  basePromptGuidelines: string[];
+  parameters: TSchema;
+  run: (params: unknown, ctx: { cwd: string }) => Promise<CodeIntelResult> | CodeIntelResult;
+}
+
+export const CODE_INTELLIGENCE_TOOL_SPECS = [
+  {
+    name: "code_brief",
+    label: "Code Brief",
+    description: "Prioritized brief for a project, package, directory, file, or symbol.",
+    promptSnippet: "code_brief — prioritized code orientation",
+    basePromptGuidelines: [
+      "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),
+  },
+  {
+    name: "code_map",
+    label: "Code Map",
+    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: "Trace callers, callees, or implementations for a resolved target.",
+    promptSnippet: "code_relations — callers, callees, or implementations",
+    basePromptGuidelines: [
+      "Use code_relations(kind) for `callers`, `callees`, or `implementations`.",
+    ],
+    parameters: CodeRelationsParameters,
+    run: (params, ctx) =>
+      executeRelationsTool(params as Parameters<typeof executeRelationsTool>[0], ctx),
+  },
+  {
+    name: "code_affected",
+    label: "Code Affected",
+    description: "Estimate blast radius and downstream impact for a target.",
+    promptSnippet: "code_affected — blast radius and impact",
+    basePromptGuidelines: [
+      "Use code_affected before edits to estimate blast radius and follow-up checks.",
+    ],
+    parameters: CodeAffectedParameters,
+    run: (params, ctx) =>
+      executeAffectedTool(params as Parameters<typeof executeAffectedTool>[0], ctx),
+  },
+  {
+    name: "code_pattern",
+    label: "Code Pattern",
+    description: "Run explicit search with literal, regex, or structured matching.",
+    promptSnippet: "code_pattern — explicit code search",
+    basePromptGuidelines: [
+      "Use code_pattern for literal, regex, or structured search in a bounded path.",
+    ],
+    parameters: CodePatternParameters,
+    run: (params, ctx) =>
+      executePatternTool(params as Parameters<typeof executePatternTool>[0], ctx),
+  },
+] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];

package/src/tool/validation.ts

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import type { CodeQueryParams } from "../query-params.ts";
+import { normalizePath } from "../search-helpers.ts";
+
+const STRUCTURED_PATTERN_KINDS = new Set(["definition", "export", "import"]);
+
+/** Shared validation for focused tool inputs that can anchor into files. */
+export function validateFocusedToolParams(
+  params: Pick<CodeQueryParams, "path" | "file" | "line" | "character">,
+  cwd: string,
+): string | null {
+  if (params.path && (params.line != null || params.character != null)) {
+    return "**Error:** `line` and `character` require `file`, not `path`. Use `path` to scope/focus; use `file` to anchor a position.";
+  }
+
+  if (params.file) {
+    const resolvedFile = normalizePath(params.file, cwd);
+    if (fs.existsSync(resolvedFile) && fs.statSync(resolvedFile).isDirectory()) {
+      return "**Error:** `file` points to a directory. Use `path` to scope a directory; use `file` to anchor a position in a file.";
+    }
+  }
+
+  if ((params.line != null || params.character != null) && !params.file) {
+    return "**Error:** `line` and `character` require `file`.";
+  }
+
+  return null;
+}
+
+/** Shared validation for explicit pattern-tool input. */
+export function validatePatternToolParams(
+  params: Pick<CodeQueryParams, "path" | "file" | "line" | "character" | "kind">,
+  cwd: string,
+): string | null {
+  const commonError = validateFocusedToolParams(params, cwd);
+  if (commonError) return commonError;
+
+  if (params.kind && !STRUCTURED_PATTERN_KINDS.has(params.kind)) {
+    return "**Error:** `code_pattern` `kind` must be one of `definition`, `export`, or `import`.";
+  }
+
+  return null;
+}

package/src/types.ts

@@ -17,6 +17,15 @@ export interface BriefDetails {
   prioritySignals?: PrioritySignalsSummary | null;
 }
 
+/** Structured details metadata for factual map results. */
+export interface MapDetails {
+  scope: string | null;
+  totalFiles: number;
+  childDirectoryCount: number;
+  landmarkCount: number;
+  nextQueries: string[];
+}
+
 /** Structured details metadata for relationship and pattern results. */
 export interface SearchDetails {
   confidence: ConfidenceMode;
@@ -56,6 +65,7 @@ export interface CodeIntelResult {
   content: string;
   details?:
     | { type: "brief"; data: BriefDetails }
+    | { type: "map"; data: MapDetails }
     | { type: "search"; data: SearchDetails }
     | { type: "affected"; data: AffectedDetails };
 }

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

@@ -0,0 +1,36 @@
+// Typed overview data builder from ArchitectureModel.
+
+import type { ArchitectureModel } from "../architecture.ts";
+import { formatGitContext, gatherGitContext } from "../git-context.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,279 @@
+// 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 "../architecture.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 { SemanticSubstrate } from "../substrates/types.ts";
+import type { ResolvedTarget, ResolvedTargetGroup } from "../target-resolution.ts";
+import type { AffectedDetails, CodeIntelResult, ConfidenceMode } from "../types.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;
+}
+
+/** Execute the affected use-case — target resolution, reference collection, analysis, and rendering. */
+export async function executeAffected(
+  input: AffectedInput,
+  deps: AffectedDeps,
+): Promise<CodeIntelResult> {
+  const semantic: SemanticSubstrate = await import("../substrates/lsp-adapter.ts").then((m) =>
+    m.createSemanticSubstrate(deps.cwd),
+  );
+  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: SemanticSubstrate,
+): 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: SemanticSubstrate,
+): 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`,
+  ];
+}