@mrclrchtr/supi-code-intelligence 1.9.0 → 1.10.0

package/src/planner/planner.ts

@@ -0,0 +1,82 @@
+/**
+ * Central planner for code-intelligence tool routing.
+ *
+ * Reads capability state from the shared workspace broker and returns
+ * routing decisions for each tool intent. Keeps the execution strategy
+ * explicit and centralized instead of scattering capability checks
+ * across per-tool execute files.
+ */
+
+import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import type { PlannerRoute } from "../intent/types.ts";
+import type { CodeIntelligenceToolName, CodeRelationsKind } from "../tool/tool-specs.ts";
+
+interface RouteAvailability {
+  semanticAvailable: boolean;
+  structuralAvailable: boolean;
+  refactorAvailable: boolean;
+}
+
+function readAvailability(cwd: string): RouteAvailability {
+  const runtime = getDefaultWorkspaceRuntime();
+  const workspace = runtime.getWorkspace(cwd);
+  return {
+    semanticAvailable:
+      workspace.semantic.state.kind === "ready" && workspace.semantic.provider !== null,
+    structuralAvailable:
+      workspace.structural.state.kind === "ready" && workspace.structural.provider !== null,
+    refactorAvailable: workspace.semantic.refactorAvailable,
+  };
+}
+
+function withPreferred(
+  availability: RouteAvailability,
+  preferred: PlannerRoute["preferred"],
+): PlannerRoute {
+  return { ...availability, preferred };
+}
+
+function semanticOnly(availability: RouteAvailability): PlannerRoute["preferred"] {
+  return availability.semanticAvailable ? "semantic" : "unavailable";
+}
+
+function structuralOnly(availability: RouteAvailability): PlannerRoute["preferred"] {
+  return availability.structuralAvailable ? "structural" : "unavailable";
+}
+
+function briefPreferred(availability: RouteAvailability): PlannerRoute["preferred"] {
+  if (availability.semanticAvailable) return "semantic";
+  if (availability.structuralAvailable) return "structural";
+  return "unavailable";
+}
+
+/**
+ * Get the routing decision for a tool intent in a workspace.
+ */
+export function routeFor(
+  cwd: string,
+  tool: CodeIntelligenceToolName,
+  relationsKind?: CodeRelationsKind,
+): PlannerRoute {
+  const availability = readAvailability(cwd);
+
+  if (tool === "code_pattern") {
+    return withPreferred(availability, "search");
+  }
+
+  if (tool === "code_relations") {
+    const preferred =
+      relationsKind === "callees" ? structuralOnly(availability) : semanticOnly(availability);
+    return withPreferred(availability, preferred);
+  }
+
+  if (tool === "code_affected") {
+    return withPreferred(availability, semanticOnly(availability));
+  }
+
+  if (tool === "code_refactor") {
+    return withPreferred(availability, availability.refactorAvailable ? "semantic" : "unavailable");
+  }
+
+  return withPreferred(availability, briefPreferred(availability));
+}

package/src/presentation/markdown/refactor.ts

@@ -0,0 +1,27 @@
+/**
+ * Markdown renderer for refactor results.
+ */
+import type { ApplyResult } from "../../refactor/apply-workspace-edit.ts";
+
+export interface RefactorRenderInput {
+  result: ApplyResult;
+  operation: string;
+  targetDescription: string;
+}
+
+/**
+ * Render a refactor result as human-readable markdown.
+ */
+export function renderRefactorResult(input: RefactorRenderInput): string {
+  const { result, operation, targetDescription } = input;
+
+  if (result.kind === "error") {
+    return `**Refactor failed:** ${result.reason}`;
+  }
+
+  return [
+    `**Refactor applied:** ${operation} on ${targetDescription}`,
+    `- Files changed: ${result.filesChanged}`,
+    `- Total edits: ${result.totalEdits}`,
+  ].join("\n");
+}

package/src/refactor/apply-workspace-edit.ts

@@ -0,0 +1,162 @@
+/**
+ * Direct-apply file mutation path for precise workspace edits.
+ *
+ * Writes edits atomically per-file: all transformed content is precomputed
+ * in memory before any file is written, so a mid-apply failure never
+ * leaves the workspace half-renamed.
+ *
+ * Edits are sorted by descending absolute offset (line + character)
+ * so same-line edits are applied right-to-left regardless of order.
+ *
+ * Only called after safety validation has passed.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
+import { validateEditAgainstFiles } from "./safety.ts";
+
+export type ApplyResult =
+  | { kind: "applied"; filesChanged: number; totalEdits: number }
+  | { kind: "error"; reason: string };
+
+/**
+ * Apply a validated WorkspaceEdit to the filesystem.
+ *
+ * Precomputes every file's new content in memory first, then commits
+ * all writes. If a commit fails after some files were already written,
+ * the function rolls those files back to their original contents.
+ */
+export function applyWorkspaceEdit(edit: WorkspaceEdit): ApplyResult {
+  const validation = validateEditAgainstFiles(edit);
+  if (!validation.safe) {
+    return { kind: "error", reason: validation.reason };
+  }
+
+  const grouped = groupEditsByFile(edit.edits);
+  const originalContents = readOriginalContents(grouped);
+  if (originalContents.kind === "error") return originalContents;
+
+  const transformedContents = buildTransformedContents(grouped, originalContents.contents);
+  return commitTransformedContents(
+    transformedContents,
+    originalContents.contents,
+    edit.edits.length,
+  );
+}
+
+function groupEditsByFile(edits: FileEdit[]): Map<string, FileEdit[]> {
+  const grouped = new Map<string, FileEdit[]>();
+  for (const fileEdit of edits) {
+    const group = grouped.get(fileEdit.file) ?? [];
+    group.push(fileEdit);
+    grouped.set(fileEdit.file, group);
+  }
+  return grouped;
+}
+
+function readOriginalContents(
+  grouped: Map<string, FileEdit[]>,
+): { kind: "ok"; contents: Map<string, string> } | { kind: "error"; reason: string } {
+  const contents = new Map<string, string>();
+
+  try {
+    for (const file of [...grouped.keys()].sort()) {
+      contents.set(file, readFileSync(file, "utf-8"));
+    }
+  } catch (error) {
+    return { kind: "error", reason: toErrorMessage(error) };
+  }
+
+  return { kind: "ok", contents };
+}
+
+function buildTransformedContents(
+  grouped: Map<string, FileEdit[]>,
+  originalContents: Map<string, string>,
+): Map<string, string> {
+  const transformed = new Map<string, string>();
+
+  for (const [file, edits] of grouped) {
+    const originalContent = originalContents.get(file) ?? "";
+    transformed.set(file, applyEditsToContent(originalContent, edits));
+  }
+
+  return transformed;
+}
+
+function applyEditsToContent(content: string, edits: FileEdit[]): string {
+  const lines = content.split("\n");
+  const sortedEdits = [...edits].sort(
+    (left, right) =>
+      absoluteOffset(right.range.start.line, right.range.start.character) -
+      absoluteOffset(left.range.start.line, left.range.start.character),
+  );
+
+  let updated = content;
+  for (const fileEdit of sortedEdits) {
+    const startOffset = toOffset(lines, fileEdit.range.start.line, fileEdit.range.start.character);
+    const endOffset = toOffset(lines, fileEdit.range.end.line, fileEdit.range.end.character);
+    updated = updated.slice(0, startOffset) + fileEdit.newText + updated.slice(endOffset);
+  }
+
+  return updated;
+}
+
+function commitTransformedContents(
+  transformedContents: Map<string, string>,
+  originalContents: Map<string, string>,
+  totalEdits: number,
+): ApplyResult {
+  const writtenFiles: string[] = [];
+
+  try {
+    for (const file of [...transformedContents.keys()].sort()) {
+      writeFileSync(file, transformedContents.get(file) ?? "", "utf-8");
+      writtenFiles.push(file);
+    }
+  } catch (error) {
+    const rollbackError = rollbackWrittenFiles(writtenFiles, originalContents);
+    return {
+      kind: "error",
+      reason: rollbackError
+        ? `${toErrorMessage(error)} (rollback failed: ${rollbackError})`
+        : toErrorMessage(error),
+    };
+  }
+
+  return {
+    kind: "applied",
+    filesChanged: transformedContents.size,
+    totalEdits,
+  };
+}
+
+function rollbackWrittenFiles(
+  writtenFiles: string[],
+  originalContents: Map<string, string>,
+): string | null {
+  try {
+    for (const file of writtenFiles.reverse()) {
+      writeFileSync(file, originalContents.get(file) ?? "", "utf-8");
+    }
+    return null;
+  } catch (error) {
+    return toErrorMessage(error);
+  }
+}
+
+function absoluteOffset(line: number, character: number): number {
+  return line * 1_000_000 + character;
+}
+
+function toOffset(lines: string[], line: number, character: number): number {
+  let offset = 0;
+  for (let index = 0; index < line && index < lines.length; index++) {
+    offset += lines[index].length + 1;
+  }
+  return offset + character;
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/refactor/safety.ts

@@ -0,0 +1,154 @@
+/**
+ * Edit validation safety checks for the code_refactor apply path.
+ *
+ * Rejects empty edits, invalid ranges, and out-of-bounds changes
+ * before they reach the filesystem.
+ */
+
+import { readFileSync } from "node:fs";
+import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
+
+export type ValidationResult = { safe: true } | { safe: false; reason: string };
+
+/**
+ * Validate a WorkspaceEdit before applying it.
+ *
+ * Rejects:
+ * - empty edit sets
+ * - edits with negative line/character ranges
+ * - edits with end position before start position
+ * - overlapping edits on the same file
+ */
+export function validateEdit(edit: WorkspaceEdit): ValidationResult {
+  if (!edit.edits || edit.edits.length === 0) {
+    return { safe: false, reason: "Edit set is empty" };
+  }
+
+  for (const fe of edit.edits) {
+    if (fe.range.start.line < 0 || fe.range.end.line < 0) {
+      return { safe: false, reason: `Invalid range in edit for file "${fe.file}": negative line` };
+    }
+    if (fe.range.start.character < 0 || fe.range.end.character < 0) {
+      return {
+        safe: false,
+        reason: `Invalid range in edit for file "${fe.file}": negative character`,
+      };
+    }
+
+    if (
+      fe.range.end.line < fe.range.start.line ||
+      (fe.range.end.line === fe.range.start.line &&
+        fe.range.end.character < fe.range.start.character)
+    ) {
+      return { safe: false, reason: `Edit for file "${fe.file}" has end before start` };
+    }
+  }
+
+  if (hasOverlappingEdits(edit.edits)) {
+    return { safe: false, reason: "Overlapping edits in one or more files" };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Validate edit ranges against the current file contents.
+ *
+ * Rejects:
+ * - unreadable files
+ * - line indices beyond file length
+ * - character indices beyond the referenced line length
+ */
+export function validateEditAgainstFiles(edit: WorkspaceEdit): ValidationResult {
+  const baseValidation = validateEdit(edit);
+  if (!baseValidation.safe) return baseValidation;
+
+  const grouped = groupByFile(edit.edits);
+  for (const [file, fileEdits] of grouped) {
+    let content: string;
+    try {
+      content = readFileSync(file, "utf-8");
+    } catch (error) {
+      return {
+        safe: false,
+        reason: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    const lines = content.split("\n");
+    for (const fileEdit of fileEdits) {
+      const lineValidation = validateLineBounds(file, fileEdit, lines);
+      if (!lineValidation.safe) return lineValidation;
+
+      const characterValidation = validateCharacterBounds(file, fileEdit, lines);
+      if (!characterValidation.safe) return characterValidation;
+    }
+  }
+
+  return { safe: true };
+}
+
+function validateLineBounds(file: string, edit: FileEdit, lines: string[]): ValidationResult {
+  const maxLine = lines.length - 1;
+  if (edit.range.start.line > maxLine || edit.range.end.line > maxLine) {
+    return {
+      safe: false,
+      reason: `Edit in file "${file}" references line ${Math.max(edit.range.start.line, edit.range.end.line)}, but the file has only ${lines.length} line${lines.length === 1 ? "" : "s"}`,
+    };
+  }
+  return { safe: true };
+}
+
+function validateCharacterBounds(file: string, edit: FileEdit, lines: string[]): ValidationResult {
+  const startLineLength = lines[edit.range.start.line]?.length ?? 0;
+  if (edit.range.start.character > startLineLength) {
+    return {
+      safe: false,
+      reason: `Edit in file "${file}" references character ${edit.range.start.character} on line ${edit.range.start.line}, but that line is only ${startLineLength} character${startLineLength === 1 ? "" : "s"} long`,
+    };
+  }
+
+  const endLineLength = lines[edit.range.end.line]?.length ?? 0;
+  if (edit.range.end.character > endLineLength) {
+    return {
+      safe: false,
+      reason: `Edit in file "${file}" references character ${edit.range.end.character} on line ${edit.range.end.line}, but that line is only ${endLineLength} character${endLineLength === 1 ? "" : "s"} long`,
+    };
+  }
+
+  return { safe: true };
+}
+
+function hasOverlappingEdits(edits: FileEdit[]): boolean {
+  const fileGroups = groupByFile(edits);
+  for (const [, fileEdits] of fileGroups) {
+    const sorted = [...fileEdits].sort(
+      (a, b) =>
+        absoluteOffset(a.range.start.line, a.range.start.character) -
+        absoluteOffset(b.range.start.line, b.range.start.character),
+    );
+
+    for (let index = 1; index < sorted.length; index++) {
+      const previous = sorted[index - 1];
+      const current = sorted[index];
+      const previousEnd = absoluteOffset(previous.range.end.line, previous.range.end.character);
+      const currentStart = absoluteOffset(current.range.start.line, current.range.start.character);
+      if (currentStart < previousEnd) return true;
+    }
+  }
+  return false;
+}
+
+function absoluteOffset(line: number, character: number): number {
+  return line * 1_000_000 + character;
+}
+
+function groupByFile(edits: FileEdit[]): Map<string, FileEdit[]> {
+  const groups = new Map<string, FileEdit[]>();
+  for (const fileEdit of edits) {
+    const group = groups.get(fileEdit.file) ?? [];
+    group.push(fileEdit);
+    groups.set(fileEdit.file, group);
+  }
+  return groups;
+}

package/src/tool/execute-affected.ts

@@ -1,3 +1,4 @@
+import { routeFor } from "../planner/planner.ts";
 import type { CodeIntelResult } from "../types.ts";
 import { executeAffected } from "../use-case/generate-affected.ts";
 import { getCodeProvider } from "../workspace/request-context.ts";
@@ -43,6 +44,27 @@ export async function executeAffectedTool(
     };
   }
 
+  const route = routeFor(ctx.cwd, "code_affected");
+  if (route.preferred === "unavailable") {
+    return {
+      content:
+        "**Error:** No semantic analysis provider is available for this workspace. Use lsp_* tools directly if needed.",
+      details: {
+        type: "affected" as const,
+        data: {
+          confidence: "unavailable" as const,
+          directCount: 0,
+          downstreamCount: 0,
+          riskLevel: "low" as const,
+          checkNext: [],
+          likelyTests: [],
+          omittedCount: 0,
+          nextQueries: ["Check LSP configuration for this workspace"],
+        },
+      },
+    };
+  }
+
   const providerState = getCodeProvider(ctx.cwd);
   const provider = providerState.kind === "ready" ? providerState.provider : null;
   return executeAffected(params, { cwd: ctx.cwd, provider });

package/src/tool/execute-brief.ts

@@ -1,4 +1,5 @@
 import { buildArchitectureModel } from "../model.ts";
+import { routeFor } from "../planner/planner.ts";
 import type { CodeIntelResult } from "../types.ts";
 import { executeBrief } from "../use-case/generate-brief.ts";
 import type { BriefInput } from "../use-case/types.ts";
@@ -14,7 +15,7 @@ export interface CodeBriefToolParams {
   maxResults?: number;
 }
 
-/** Execute the public code_brief tool through the use-case/presentation layers. */
+/** Execute the public code_brief tool through the planner-backed use-case layers. */
 export async function executeBriefTool(
   params: CodeBriefToolParams,
   ctx: { cwd: string },
@@ -24,8 +25,14 @@ export async function executeBriefTool(
     return { content: error, details: undefined };
   }
 
+  const route = routeFor(ctx.cwd, "code_brief");
   const providerState = getCodeProvider(ctx.cwd);
-  const provider = providerState.kind === "ready" ? providerState.provider : null;
+  let provider = providerState.kind === "ready" ? providerState.provider : null;
+
+  if (route.preferred === "unavailable") {
+    // code_brief can still work with model-only data even without providers
+    provider = null;
+  }
   const model = await buildArchitectureModel(ctx.cwd);
 
   const input: BriefInput = determineInput(params);

package/src/tool/execute-refactor.ts

@@ -0,0 +1,101 @@
+/**
+ * code_refactor tool execution.
+ *
+ * Routes through the planner to get the refactor-capable semantic provider,
+ * calls rename/codeActions, validates the returned edit, applies it,
+ * and returns the result.
+ */
+
+import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import { toLspPosition } from "@mrclrchtr/supi-lsp/api";
+import { routeFor } from "../planner/planner.ts";
+import { renderRefactorResult } from "../presentation/markdown/refactor.ts";
+import { applyWorkspaceEdit } from "../refactor/apply-workspace-edit.ts";
+import { validateEdit } from "../refactor/safety.ts";
+import { normalizePath } from "../search-helpers.ts";
+import type { CodeIntelResult } from "../types.ts";
+
+export interface CodeRefactorToolParams {
+  operation: "rename";
+  file: string;
+  line: number;
+  character: number;
+  newName: string;
+  // Future: "code-action" operation could be added here
+}
+
+/**
+ * Execute the code_refactor tool.
+ */
+export async function executeRefactorTool(
+  params: CodeRefactorToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const route = routeFor(ctx.cwd, "code_refactor");
+  if (route.preferred === "unavailable") {
+    return {
+      content:
+        "**Error:** No refactor-capable provider is available for this workspace. Ensure an LSP server is configured and running.",
+      details: undefined,
+    };
+  }
+
+  const runtime = getDefaultWorkspaceRuntime();
+  const ws = runtime.getWorkspace(ctx.cwd);
+  const provider = ws.semantic.provider;
+
+  if (!provider?.rename) {
+    return {
+      content: "**Error:** The active semantic provider does not support rename operations.",
+      details: undefined,
+    };
+  }
+
+  const resolvedFile = normalizePath(params.file, ctx.cwd);
+
+  // Execute the rename operation with 0-based LSP coordinates
+  const refactorResult = await provider.rename(
+    resolvedFile,
+    toLspPosition(params.line, params.character),
+    params.newName,
+  );
+
+  if (refactorResult.kind === "unavailable") {
+    return {
+      content: `**Refactor unavailable:** ${refactorResult.reason}`,
+      details: undefined,
+    };
+  }
+
+  if (refactorResult.kind === "ambiguous") {
+    const candidates = refactorResult.candidates
+      .map((c, i) => {
+        const location = c.file ? `${c.file}${c.line != null ? `:${c.line}` : ""}` : "";
+        return `${i + 1}. ${c.description}${location ? ` (${location})` : ""}`;
+      })
+      .join("\n");
+    return {
+      content: `**Refactor ambiguous:** Multiple matching targets found. Please disambiguate:\n${candidates}`,
+      details: undefined,
+    };
+  }
+
+  // Validate the edit
+  const validation = validateEdit(refactorResult.edits);
+  if (!validation.safe) {
+    return {
+      content: `**Refactor safety check failed:** ${validation.reason}`,
+      details: undefined,
+    };
+  }
+
+  // Apply the edit
+  const applyResult = applyWorkspaceEdit(refactorResult.edits);
+  const content = renderRefactorResult({
+    result: applyResult,
+    operation: `rename "${params.newName}"`,
+    targetDescription: `${resolvedFile}:${params.line}:${params.character}`,
+  });
+
+  return { content, details: undefined };
+}

package/src/tool/execute-relations.ts

@@ -1,3 +1,4 @@
+import { routeFor } from "../planner/planner.ts";
 import type { CodeIntelResult } from "../types.ts";
 import type { RelationsInput } from "../use-case/generate-relations.ts";
 import { executeRelations } from "../use-case/generate-relations.ts";
@@ -16,7 +17,7 @@ export interface CodeRelationsToolParams {
   maxResults?: number;
 }
 
-/** Execute the public code_relations tool through the relations use-case. */
+/** Execute the public code_relations tool through the planner-backed routing. */
 export async function executeRelationsTool(
   params: CodeRelationsToolParams,
   ctx: { cwd: string },
@@ -26,11 +27,11 @@ export async function executeRelationsTool(
     return { content: error, details: undefined };
   }
 
-  // Semantic actions (callers, callees, implementations) require file or symbol
+  // Semantic actions (callers, implementations) or structural (callees) require file or symbol
   if (!params.file && !params.symbol) {
     return {
       content:
-        "**Error:** Semantic actions require either anchored coordinates (`file`, `line`, `character`) or a `symbol` for discovery.",
+        "**Error:** Relations require either anchored coordinates (`file`, `line`, `character`) or a `symbol` for discovery.",
       details: {
         type: "search" as const,
         data: {
@@ -44,6 +45,23 @@ export async function executeRelationsTool(
     };
   }
 
+  const route = routeFor(ctx.cwd, "code_relations", params.kind);
+  if (route.preferred === "unavailable") {
+    return {
+      content: `**Error:** No ${params.kind === "callees" ? "structural" : "semantic"} analysis provider is available for this workspace. Use tree_sitter_callees or lsp_* tools directly if needed.`,
+      details: {
+        type: "search" as const,
+        data: {
+          confidence: "unavailable" as const,
+          scope: null,
+          candidateCount: 0,
+          omittedCount: 0,
+          nextQueries: ["Check LSP and tree-sitter configuration"],
+        },
+      },
+    };
+  }
+
   const input: RelationsInput = {
     kind: params.kind,
     path: params.path,