@mrclrchtr/supi-code-intelligence 1.9.1 → 1.11.0

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[];