@mrclrchtr/supi-code-intelligence 1.7.0 → 1.8.0

package/src/targeting/resolve-file.ts

@@ -0,0 +1,197 @@
+/**
+ * File-surface target resolution — discovers actionable targets within a file
+ * using injected semantic (LSP document symbols) and structural (Tree-sitter exports)
+ * substrates with explicit fallback policy.
+ *
+ * Policy: LSP document symbols preferred (semantic). Falls back to Tree-sitter
+ * exports (structural) when LSP is unavailable or returns no results.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { normalizePath } from "../search-helpers.ts";
+import { highestConfidence } from "../semantic-action-helpers.ts";
+import { createStructuralSubstrate } from "../substrates/tree-sitter-adapter.ts";
+import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
+import type { ResolvedTargetData, ResolvedTargetGroupData } from "./types.ts";
+
+const BINARY_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".ico",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".bz2",
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".wasm",
+  ".node",
+]);
+
+function isBinaryFile(filePath: string): boolean {
+  return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+/**
+ * Resolve a file into a group of discoverable targets.
+ *
+ * @param file - the file path (absolute or cwd-relative)
+ * @param cwd - session working directory
+ * @param deps - injected substrates (both optional)
+ * @returns typed group outcome or error
+ */
+export async function resolveFileTargetGroup(
+  file: string,
+  cwd: string,
+  deps: {
+    semantic?: SemanticSubstrate;
+    structural?: StructuralSubstrate;
+  } = {},
+): Promise<
+  { kind: "resolved"; group: ResolvedTargetGroupData } | { kind: "error"; message: string }
+> {
+  const resolvedFile = normalizePath(file, cwd);
+
+  if (!fs.existsSync(resolvedFile)) {
+    return { kind: "error", message: `File not found: \`${file}\`` };
+  }
+
+  if (isBinaryFile(resolvedFile)) {
+    return {
+      kind: "error",
+      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_pattern\` for explicit text search.`,
+    };
+  }
+
+  const relPath = path.relative(cwd, resolvedFile);
+
+  // Try structure-based discovery first (faster, no LSP needed)
+  const structuralTargets = await resolveViaStructral(relPath, resolvedFile, cwd, deps.structural);
+
+  // Try semantic discovery (richer), preferring it over structural
+  const semanticTargets = await resolveViaSemantic(resolvedFile, deps.semantic, structuralTargets);
+
+  const targets = semanticTargets ?? structuralTargets;
+
+  if (!targets || targets.length === 0) {
+    return {
+      kind: "error",
+      message:
+        `**Error:** File-level semantic exploration is not available for \`${file}\`. ` +
+        "Provide `line` and `character`, or a `symbol` for discovery.",
+    };
+  }
+
+  return {
+    kind: "resolved",
+    group: {
+      file: resolvedFile,
+      displayName: relPath,
+      targets,
+      confidence: highestConfidence(targets.map((t) => t.confidence)),
+    },
+  };
+}
+
+// ── Resolution helpers ───────────────────────────────────────────────
+
+async function resolveViaSemantic(
+  resolvedFile: string,
+  semantic?: SemanticSubstrate,
+  structuralTargets: ResolvedTargetData[] | null = null,
+): Promise<ResolvedTargetData[] | null> {
+  if (!semantic) return structuralTargets;
+
+  try {
+    const symbols = await semantic.documentSymbols(resolvedFile);
+    if (!symbols || symbols.length === 0) return structuralTargets;
+
+    const topLevel = symbols
+      .filter((s) => !s.container)
+      .map((s) => ({
+        file: resolvedFile,
+        position: { line: s.line - 1, character: s.character - 1 },
+        displayLine: s.line,
+        displayCharacter: s.character,
+        name: s.name,
+        kind: s.kind,
+        confidence: "semantic" as const,
+      }));
+
+    if (topLevel.length === 0) return structuralTargets;
+    if (!structuralTargets || structuralTargets.length === 0) return dedupeTargets(topLevel);
+
+    const matched = structuralTargets.map((target) => {
+      const byName = topLevel.find((candidate) => candidate.name === target.name);
+      return byName ?? target;
+    });
+
+    return dedupeTargets(matched);
+  } catch {
+    return structuralTargets;
+  }
+}
+
+async function resolveViaStructral(
+  relPath: string,
+  resolvedFile: string,
+  cwd: string,
+  structural?: StructuralSubstrate,
+): Promise<ResolvedTargetData[] | null> {
+  // Resolve a substrate to use — prefer injected, fall back to auto-created
+  const substrate = structural ?? createFallbackSubstrate(cwd);
+  if (!substrate) return null;
+
+  try {
+    const exportsResult = await substrate.exports(relPath);
+    if (exportsResult.kind !== "success" || exportsResult.data.length === 0) return null;
+
+    return dedupeTargets(
+      exportsResult.data.map((record) => ({
+        file: resolvedFile,
+        position: { line: record.startLine - 1, character: record.startCharacter - 1 },
+        displayLine: record.startLine,
+        displayCharacter: record.startCharacter,
+        name: record.name,
+        kind: record.kind,
+        confidence: "structural" as const,
+      })),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Create a fallback structural substrate from a working directory. */
+function createFallbackSubstrate(dir: string): StructuralSubstrate | null {
+  try {
+    return createStructuralSubstrate(dir);
+  } catch {
+    return null;
+  }
+}
+
+function dedupeTargets(targets: ResolvedTargetData[]): ResolvedTargetData[] {
+  const deduped = new Map<string, ResolvedTargetData>();
+  for (const target of targets) {
+    const key = `${target.name ?? ""}:${target.displayLine}:${target.displayCharacter}`;
+    if (!deduped.has(key)) {
+      deduped.set(key, target);
+    }
+  }
+  return [...deduped.values()];
+}

package/src/targeting/resolve-symbol.ts

@@ -0,0 +1,110 @@
+/**
+ * Symbol target resolution — discovers symbols via the semantic substrate
+ * and returns typed outcomes (resolved, disambiguation, or error).
+ *
+ * This resolver is semantic-only: it does not fall back to text search
+ * or heuristic guessing. Ambiguous matches produce explicit disambiguation.
+ */
+
+import * as path from "node:path";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+import type { SemanticSubstrate } from "../substrates/types.ts";
+import type { DisambiguationCandidateData, TargetOutcome } from "./types.ts";
+
+const MAX_CANDIDATES = 8;
+const NON_EXPORTED_KINDS = new Set(["Variable", "Field", "Property"]);
+
+/**
+ * Resolve a symbol via the semantic substrate.
+ *
+ * @param symbol - the symbol name to search for
+ * @param cwd - session working directory
+ * @param semantic - the semantic substrate (LSP-backed)
+ * @param options - optional filters: path scope, kind filter, exported-only
+ * @returns Typed outcome: resolved, disambiguation, or error
+ */
+export async function resolveSymbolTarget(
+  symbol: string,
+  cwd: string,
+  semantic: SemanticSubstrate,
+  options?: {
+    path?: string;
+    kind?: string;
+    exportedOnly?: boolean;
+  },
+): Promise<TargetOutcome> {
+  const results = await semantic.workspaceSymbols(symbol);
+  if (results === null) {
+    return {
+      kind: "error",
+      message: `Symbol discovery for \`${symbol}\` requires active LSP. Use \`file\` + coordinates, or enable LSP and retry.`,
+    };
+  }
+  if (results.length === 0) {
+    return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
+  }
+
+  // Filter by path scope
+  const scopePath = options?.path ? path.resolve(cwd, options.path) : null;
+  let candidates = results.filter((s) => {
+    if (scopePath && !isWithinOrEqual(scopePath, s.file)) return false;
+    return true;
+  });
+
+  // Filter by kind
+  if (options?.kind) {
+    const kindLower = options.kind.toLowerCase();
+    candidates = candidates.filter((s) => s.kind.toLowerCase().includes(kindLower));
+  }
+
+  // Filter to exported symbols only
+  if (options?.exportedOnly) {
+    candidates = candidates.filter((s) => !NON_EXPORTED_KINDS.has(s.kind));
+  }
+
+  // Range-less candidates (line=0,char=0) come from URI-only workspace symbols.
+  // Keep them for disambiguation but don't promote to single-match resolution.
+  const ranged = candidates.filter((s) => s.line > 0 || s.character > 0);
+
+  if (ranged.length === 1) {
+    const c = ranged[0];
+    return {
+      kind: "resolved",
+      target: {
+        file: c.file,
+        position: { line: c.line - 1, character: c.character - 1 },
+        displayLine: c.line,
+        displayCharacter: c.character,
+        name: c.name,
+        kind: c.kind,
+        confidence: "semantic",
+      },
+    };
+  }
+
+  // All candidates lost or only rangeless
+  if (candidates.length === 0) {
+    return {
+      kind: "error",
+      message: `Symbol not found: \`${symbol}\`${scopePath ? ` in path \`${options?.path}\`` : ""}`,
+    };
+  }
+
+  // Multiple candidates — return disambiguation
+  const candidatesOut = candidates.slice(0, MAX_CANDIDATES).map((c, idx) => ({
+    name: c.name,
+    kind: c.kind,
+    container: c.container ?? null,
+    file: path.relative(cwd, c.file),
+    line: c.line,
+    character: c.character,
+    reason: path.relative(cwd, c.file),
+    rank: idx + 1,
+  })) satisfies DisambiguationCandidateData[];
+
+  return {
+    kind: "disambiguation",
+    candidates: candidatesOut,
+    omittedCount: Math.max(0, candidates.length - MAX_CANDIDATES),
+  };
+}

package/src/targeting/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Targeting types — normalized query and typed outcomes for the
+ * target-resolution pipeline.
+ *
+ * These types decouple request normalization from resolution implementation
+ * and keep action-facing code focused on routing, not string building.
+ */
+
+import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
+
+// ── Normalized query ──────────────────────────────────────────────────
+
+/**
+ * A pre-classified target request extracted from tool/action parameters.
+ *
+ * The pipeline normalizes incoming params into one of these shapes
+ * so each resolver phase can operate on an already-disambiguated query.
+ */
+export type NormalizedQuery =
+  | {
+      kind: "anchored";
+      file: string;
+      line: number;
+      character: number;
+    }
+  | {
+      kind: "file";
+      file: string;
+    }
+  | {
+      kind: "symbol";
+      symbol: string;
+      path?: string;
+      symbolKind?: string;
+      exportedOnly?: boolean;
+    }
+  | {
+      kind: "invalid";
+      reason: string;
+    };
+
+// ── Resolver dependency injection ─────────────────────────────────────
+
+/**
+ * Substrates and context injected into the resolution pipeline.
+ *
+ * Passed from the action/tool entrypoint rather than constructed
+ * inside resolver internals, so fallback policy is explicit.
+ */
+export interface ResolverDeps {
+  cwd: string;
+  semantic?: SemanticSubstrate;
+  structural?: StructuralSubstrate;
+}
+
+// ── Typed resolution outcomes ─────────────────────────────────────────
+
+/**
+ * A successfully resolved anchored target with 0-/1-based positions.
+ */
+export interface ResolvedTargetData {
+  file: string;
+  /** 0-based position for LSP calls */
+  position: { line: number; character: number };
+  /** 1-based position for user display */
+  displayLine: number;
+  displayCharacter: number;
+  name: string | null;
+  kind: string | null;
+  confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+}
+
+/**
+ * A file-level target group with one or more discoverable targets.
+ */
+export interface ResolvedTargetGroupData {
+  file: string;
+  displayName: string;
+  targets: ResolvedTargetData[];
+  confidence: "semantic" | "structural" | "heuristic" | "unavailable";
+}
+
+/**
+ * A disambiguation candidate for symbol searches with multiple matches.
+ */
+export interface DisambiguationCandidateData {
+  name: string;
+  kind: string | null;
+  container: string | null;
+  file: string;
+  line: number;
+  character: number;
+  reason: string;
+  rank: number;
+}
+
+/**
+ * Typed outcome of a resolution attempt.
+ *
+ * Actions consume these to produce user-facing strings/details;
+ * the resolution pipeline itself stays presentation-agnostic.
+ */
+export type TargetOutcome =
+  | { kind: "resolved"; target: ResolvedTargetData }
+  | { kind: "group"; group: ResolvedTargetGroupData }
+  | {
+      kind: "disambiguation";
+      candidates: DisambiguationCandidateData[];
+      omittedCount: number;
+    }
+  | { kind: "error"; message: string };

package/src/tool/execute-affected.ts

@@ -1,5 +1,5 @@
-import { executeAffectedAction } from "../actions/affected-action.ts";
 import type { CodeIntelResult } from "../types.ts";
+import { executeAffected } from "../use-case/generate-affected.ts";
 import { validateFocusedToolParams } from "./validation.ts";
 
 export interface CodeAffectedToolParams {
@@ -11,7 +11,7 @@ export interface CodeAffectedToolParams {
   maxResults?: number;
 }
 
-/** Execute the public code_affected tool through the substrate-only affected action. */
+/** Execute the public code_affected tool through the affected use-case. */
 export async function executeAffectedTool(
   params: CodeAffectedToolParams,
   ctx: { cwd: string },
@@ -21,5 +21,5 @@ export async function executeAffectedTool(
     return { content: error, details: undefined };
   }
 
-  return executeAffectedAction(params, ctx.cwd);
+  return executeAffected(params, { cwd: ctx.cwd });
 }

package/src/tool/execute-brief.ts

@@ -1,5 +1,8 @@
-import { executeBriefAction } from "../actions/brief-action.ts";
+import { buildArchitectureModel } from "../architecture.ts";
+import { createStructuralSubstrate } from "../substrates/tree-sitter-adapter.ts";
 import type { CodeIntelResult } from "../types.ts";
+import { executeBrief } from "../use-case/generate-brief.ts";
+import type { BriefInput } from "../use-case/types.ts";
 import { validateFocusedToolParams } from "./validation.ts";
 
 export interface CodeBriefToolParams {
@@ -11,7 +14,7 @@ export interface CodeBriefToolParams {
   maxResults?: number;
 }
 
-/** Execute the public code_brief tool through the existing brief action. */
+/** Execute the public code_brief tool through the use-case/presentation layers. */
 export async function executeBriefTool(
   params: CodeBriefToolParams,
   ctx: { cwd: string },
@@ -21,5 +24,28 @@ export async function executeBriefTool(
     return { content: error, details: undefined };
   }
 
-  return executeBriefAction(params, ctx.cwd);
+  const structural = createStructuralSubstrate(ctx.cwd);
+  const model = await buildArchitectureModel(ctx.cwd);
+
+  const input: BriefInput = determineInput(params);
+  const deps = { model, structural, cwd: ctx.cwd };
+
+  const result = await executeBrief(input, deps);
+  return { content: result.content, details: { type: "brief", data: result.details } };
+}
+
+function determineInput(params: CodeBriefToolParams): BriefInput {
+  if (params.file && params.line != null && params.character != null) {
+    return { kind: "anchored", file: params.file, line: params.line, character: params.character };
+  }
+  if (params.symbol) {
+    return { kind: "symbol", symbol: params.symbol, path: params.path };
+  }
+  if (params.path) {
+    return { kind: "path", path: params.path };
+  }
+  if (params.file) {
+    return { kind: "file", file: params.file };
+  }
+  return { kind: "project" };
 }

package/src/tool/execute-map.ts

@@ -1,7 +1,8 @@
 import * as fs from "node:fs";
-import { executeMapAction } from "../actions/map-action.ts";
+import { renderMap } from "../presentation/markdown/map.ts";
 import { normalizePath } from "../search-helpers.ts";
 import type { CodeIntelResult } from "../types.ts";
+import { buildMapData } from "../use-case/generate-map.ts";
 
 export interface CodeMapToolParams {
   path?: string;
@@ -28,5 +29,7 @@ export async function executeMapTool(
     };
   }
 
-  return executeMapAction(scopePath, ctx.cwd);
+  const data = buildMapData(scopePath, ctx.cwd);
+  const rendered = renderMap(data);
+  return { content: rendered.content, details: { type: "map", data: rendered.details } };
 }

package/src/tool/execute-pattern.ts

@@ -1,5 +1,6 @@
-import { executePatternAction } from "../actions/pattern-action.ts";
+import { createStructuralSubstrate } from "../substrates/tree-sitter-adapter.ts";
 import type { CodeIntelResult } from "../types.ts";
+import { executePattern } from "../use-case/generate-pattern.ts";
 import { validatePatternToolParams } from "./validation.ts";
 
 export interface CodePatternToolParams {
@@ -12,7 +13,7 @@ export interface CodePatternToolParams {
   summary?: boolean;
 }
 
-/** Execute the public code_pattern tool as the sole heuristic/structured search surface. */
+/** Execute the public code_pattern tool through the pattern use-case. */
 export async function executePatternTool(
   params: CodePatternToolParams,
   ctx: { cwd: string },
@@ -22,5 +23,6 @@ export async function executePatternTool(
     return { content: error, details: undefined };
   }
 
-  return executePatternAction(params, ctx.cwd);
+  const structural = createStructuralSubstrate(ctx.cwd);
+  return executePattern(params, { cwd: ctx.cwd, structural });
 }

package/src/tool/execute-relations.ts

@@ -1,7 +1,6 @@
-import { executeCalleesAction } from "../actions/callees-action.ts";
-import { executeCallersAction } from "../actions/callers-action.ts";
-import { executeImplementationsAction } from "../actions/implementations-action.ts";
 import type { CodeIntelResult } from "../types.ts";
+import type { RelationsInput } from "../use-case/generate-relations.ts";
+import { executeRelations } from "../use-case/generate-relations.ts";
 import type { CodeRelationsKind } from "./tool-specs.ts";
 import { validateFocusedToolParams } from "./validation.ts";
 
@@ -16,13 +15,7 @@ export interface CodeRelationsToolParams {
   maxResults?: number;
 }
 
-const RELATION_HANDLERS = {
-  callers: executeCallersAction,
-  callees: executeCalleesAction,
-  implementations: executeImplementationsAction,
-} as const;
-
-/** Execute the public code_relations tool by dispatching to the selected substrate-backed relation action. */
+/** Execute the public code_relations tool through the relations use-case. */
 export async function executeRelationsTool(
   params: CodeRelationsToolParams,
   ctx: { cwd: string },
@@ -32,17 +25,16 @@ export async function executeRelationsTool(
     return { content: error, details: undefined };
   }
 
-  const handler = RELATION_HANDLERS[params.kind];
-  return handler(
-    {
-      path: params.path,
-      file: params.file,
-      line: params.line,
-      character: params.character,
-      symbol: params.symbol,
-      exportedOnly: params.exportedOnly,
-      maxResults: params.maxResults,
-    },
-    ctx.cwd,
-  );
+  const input: RelationsInput = {
+    kind: params.kind,
+    path: params.path,
+    file: params.file,
+    line: params.line,
+    character: params.character,
+    symbol: params.symbol,
+    exportedOnly: params.exportedOnly,
+    maxResults: params.maxResults,
+  };
+
+  return executeRelations(input, { cwd: ctx.cwd });
 }

package/src/tool/guidance.ts

@@ -1,4 +1,8 @@
 // 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_INTELLIGENCE_TOOL_SPECS, type CodeIntelligenceToolName } from "./tool-specs.ts";
 
@@ -13,6 +17,31 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
   CodeIntelligenceToolPromptSurface
 >;
 
+// ── 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.
+
+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.",
+  ],
+};
+
+// ── Surface builder ────────────────────────────────────────────────────
+
 export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolPromptSurfaceMap {
   return Object.fromEntries(
     CODE_INTELLIGENCE_TOOL_SPECS.map((spec) => [
@@ -20,7 +49,7 @@ export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolP
       {
         description: spec.description,
         promptSnippet: spec.promptSnippet,
-        promptGuidelines: [...spec.basePromptGuidelines],
+        promptGuidelines: [...spec.basePromptGuidelines, ...ORCHESTRATION_GUIDELINES[spec.name]],
       } satisfies CodeIntelligenceToolPromptSurface,
     ]),
   ) as CodeIntelligenceToolPromptSurfaceMap;