@mrclrchtr/supi-code-intelligence 1.9.1 → 1.10.0

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,

package/src/tool/guidance.ts

@@ -17,26 +17,33 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
   CodeIntelligenceToolPromptSurface
 >;
 
-// ── Cross-family orchestration guidelines ──────────────────────────────
+// ── Intent-first 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.
+// These steer the model toward choosing tools by user intent rather than
+// by implementation family.  Substrate tools (lsp_*, tree_sitter_*) are
+// described as expert follow-up surfaces, not the primary choice.
 
-const ORCHESTRATION_GUIDELINES: Record<CodeIntelligenceToolName, string[]> = {
+const INTENT_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.",
+    "Use code_brief for prioritized orientation on a project, package, file, or symbol.",
+    "The planner selects the best provider (semantic or structural) automatically.",
+    "After code_brief, use lsp_hover/lsp_definition/lsp_references for deeper semantic detail or tree_sitter_* for quick structural context.",
   ],
   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.",
+    "The planner routes callers/implementations to semantic (LSP) analysis and callees to structural (tree-sitter) analysis.",
+    "Follow caller results with lsp_references/lsp_definition for additional context; use tree_sitter_callees for structural outgoing calls as a debug surface.",
   ],
   code_affected: [
-    "Use lsp_references instead when you need a plain reference list, not impact analysis.",
+    "Uses semantic evidence for blast-radius assessment. Does not fall back to heuristic text search.",
+    "Use lsp_references when you only need a plain reference list without impact analysis.",
   ],
   code_pattern: [
-    "Use tree_sitter_query or lsp_hover/lsp_definition when you need structure or semantic precision.",
+    "The only code_* tool that uses heuristic/text search behavior. For structured or semantic precision, use tree_sitter_query or lsp_hover/lsp_definition instead.",
+  ],
+  code_refactor: [
+    "Uses semantic provider for precise rename/code-action operations with safety checks.",
+    "Does not fall back to heuristic text replacement — if the provider cannot produce precise edits, the tool reports unavailable.",
   ],
 };
 
@@ -49,7 +56,7 @@ export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolP
       {
         description: spec.description,
         promptSnippet: spec.promptSnippet,
-        promptGuidelines: [...spec.basePromptGuidelines, ...ORCHESTRATION_GUIDELINES[spec.name]],
+        promptGuidelines: [...spec.basePromptGuidelines, ...INTENT_GUIDELINES[spec.name]],
       } satisfies CodeIntelligenceToolPromptSurface,
     ]),
   ) as CodeIntelligenceToolPromptSurfaceMap;

package/src/tool/tool-specs.ts

@@ -5,6 +5,7 @@ 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 { executeRefactorTool } from "./execute-refactor.ts";
 import { executeRelationsTool } from "./execute-relations.ts";
 
 const PathParam = Type.String({ description: "Scope path" });
@@ -28,6 +29,7 @@ export const CODE_INTELLIGENCE_TOOL_NAMES = [
   "code_relations",
   "code_affected",
   "code_pattern",
+  "code_refactor",
 ] as const;
 export type CodeIntelligenceToolName = (typeof CODE_INTELLIGENCE_TOOL_NAMES)[number];
 
@@ -94,6 +96,17 @@ const CodePatternParameters = Type.Object(
   { additionalProperties: false },
 );
 
+const CodeRefactorParameters = Type.Object(
+  {
+    operation: Type.String({ description: "Refactor operation: rename" }),
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+    newName: Type.String({ description: "New name for rename operation" }),
+  },
+  { additionalProperties: false },
+);
+
 export interface CodeIntelligenceToolDefinitionSpec {
   name: CodeIntelligenceToolName;
   label: string;
@@ -162,4 +175,16 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
     run: (params, ctx) =>
       executePatternTool(params as Parameters<typeof executePatternTool>[0], ctx),
   },
+  {
+    name: "code_refactor",
+    label: "Code Refactor",
+    description: "Apply a precise semantic refactor (rename) with direct-apply safety checks.",
+    promptSnippet: "code_refactor — semantic refactor with direct apply",
+    basePromptGuidelines: [
+      "Use code_refactor for safe semantic rename operations with precise workspace edits.",
+    ],
+    parameters: CodeRefactorParameters,
+    run: (params, ctx) =>
+      executeRefactorTool(params as Parameters<typeof executeRefactorTool>[0], ctx),
+  },
 ] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];