@mrclrchtr/supi-code-intelligence 1.9.1 → 1.11.0

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -8,9 +8,11 @@ import type {
   AgentToolResult,
   AgentToolUpdateCallback,
   ExtensionAPI,
+  ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { type TSchema, Type } from "typebox";
+import { ProgressWidget, type WidgetProgress } from "./progress-widget.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -114,3 +116,67 @@ export const SymbolParam = Type.String({
 
 /** Maximum results to return. */
 export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });
+
+// ---------------------------------------------------------------------------
+// Progress widget runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an async operation with a live TUI progress widget.
+ *
+ * Automatically manages:
+ * - The {@link ProgressWidget} lifecycle
+ * - `supi:working:start` / `supi:working:end` events for tab-spinner integration
+ * - Abort signal handling
+ * - Error catching (returns `null` on failure)
+ *
+ * Falls back to running without a widget when `ctx.hasUI` is false.
+ *
+ * @param pi - The extension API (for event emission).
+ * @param ctx - The command context (for UI access and hasUI check).
+ * @param title - The progress widget title.
+ * @param runner - Async function that receives (signal, onProgress).
+ * @returns The runner result, or `null` on cancel/error.
+ */
+export async function runWithProgressWidget<T>(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  title: string,
+  runner: (signal: AbortSignal, onProgress: (p: WidgetProgress) => void) => Promise<T>,
+): Promise<T | null> {
+  if (!ctx.hasUI) {
+    // No UI — run without progress widget but still emit working events
+    pi.events.emit("supi:working:start", { source: "supi-core" });
+    try {
+      return await runner(new AbortController().signal, () => {});
+    } catch {
+      return null;
+    } finally {
+      pi.events.emit("supi:working:end", { source: "supi-core" });
+    }
+  }
+
+  return ctx.ui.custom<T | null>((tui, theme, _kb, done) => {
+    const widget = new ProgressWidget(tui, theme, title);
+    let finished = false;
+
+    const finish = (result: T | null) => {
+      if (finished) return;
+      finished = true;
+      pi.events.emit("supi:working:end", { source: "supi-core" });
+      widget.dispose();
+      done(result);
+    };
+
+    widget.onAbort = () => {
+      // Widget handles abort signal; runner resolves with cancel/error.
+    };
+
+    pi.events.emit("supi:working:start", { source: "supi-core" });
+    runner(widget.signal, (progress) => widget.updateProgress(progress))
+      .then((result) => finish(result))
+      .catch(() => finish(null));
+
+    return widget;
+  });
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -24,8 +24,8 @@
   ],
   "dependencies": {
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-code-runtime": "1.9.1",
-    "@mrclrchtr/supi-core": "1.9.1"
+    "@mrclrchtr/supi-code-runtime": "1.11.0",
+    "@mrclrchtr/supi-core": "1.11.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "SuPi Code Intelligence extension — architecture briefs, caller/callee analysis, impact assessment, and pattern search for pi",
   "license": "MIT",
   "repository": {
@@ -19,10 +19,10 @@
     "src/**/*.ts"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-lsp": "1.9.1",
-    "@mrclrchtr/supi-core": "1.9.1",
-    "@mrclrchtr/supi-code-runtime": "1.9.1",
-    "@mrclrchtr/supi-tree-sitter": "1.9.1"
+    "@mrclrchtr/supi-code-runtime": "1.11.0",
+    "@mrclrchtr/supi-core": "1.11.0",
+    "@mrclrchtr/supi-lsp": "1.11.0",
+    "@mrclrchtr/supi-tree-sitter": "1.11.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/intent/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Normalized intent and routing types for the code-intelligence planner.
+ */
+import type { CodeIntelligenceToolName, CodeRelationsKind } from "../tool/tool-specs.ts";
+
+/**
+ * A route describes how the planner recommends handling a tool intent.
+ */
+export interface PlannerRoute {
+  /** Whether a semantic (LSP-backed) provider is available */
+  semanticAvailable: boolean;
+  /** Whether a structural (tree-sitter-backed) provider is available */
+  structuralAvailable: boolean;
+  /** Whether precise refactoring is available */
+  refactorAvailable: boolean;
+  /**
+   * The preferred execution strategy for this intent.
+   * - `semantic`: use LSP first
+   * - `structural`: use tree-sitter first
+   * - `search`: use explicit text/heuristic search
+   * - `unavailable`: no capability can satisfy this intent
+   */
+  preferred: "semantic" | "structural" | "search" | "unavailable";
+}
+
+/**
+ * A resolved intents for a tool execution request.
+ * Provides the normalized target and routing info together.
+ */
+export interface ResolvedIntent {
+  tool: CodeIntelligenceToolName;
+  relationsKind?: CodeRelationsKind;
+  route: PlannerRoute;
+}

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);