@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/{tool/refactor-apply → analysis/refactor}/apply.ts

@@ -1,43 +1,64 @@
 /**
  * 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.
+ * Stages transformed content beside each source file before atomically
+ * replacing that file. A failed stage cannot truncate a source file, and a
+ * failed later replacement attempts to roll back files already replaced.
  *
- * Edits are sorted by descending absolute offset (line + character)
- * so same-line edits are applied right-to-left regardless of order.
+ * Edits are sorted by descending source position
+ * so edits are applied from bottom-right to top-left regardless of order.
  *
  * Only called after safety validation has passed.
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
-import { validateEditAgainstFiles } from "../../analysis/refactor/safety.ts";
+import { compareCodePositions } from "./position.ts";
+import { validateEditAgainstFiles } from "./safety.ts";
 
 export type ApplyResult =
   | { kind: "applied"; filesChanged: number; totalEdits: number }
   | { kind: "error"; reason: string };
 
+export interface ApplyOptions {
+  /** Expected SHA-256 fingerprints per file, validated after queue acquisition. */
+  expectedFingerprints?: ReadonlyMap<string, 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.
+ * all writes. If a commit fails after some files were already replaced,
+ * the function attempts to roll those files back to their original contents.
+ *
+ * When `expectedFingerprints` is supplied, fingerprints are compared
+ * **after** all mutation queues are acquired, so a sibling write cannot
+ * change the file between fingerprint check and queue entry.
  *
  * The whole precompute-then-commit (including range/safety re-checks) runs
  * inside pi's per-file mutation queue, acquired for every involved file in
  * sorted path order before reading. This serializes against sibling
  * `edit`/`write` tools on the same file and prevents lock-ordering deadlock
- * across concurrent applies, while preserving all-or-nothing across files
- * (ADR 0006).
+ * across concurrent applies, while attempting to roll back ordinary commit
+ * failures across files (ADR 0006). It does not provide durable crash recovery
+ * across sequential replacements.
  */
-export async function applyWorkspaceEdit(edit: WorkspaceEdit): Promise<ApplyResult> {
+export async function applyWorkspaceEdit(
+  edit: WorkspaceEdit,
+  options: ApplyOptions = {},
+): Promise<ApplyResult> {
   const grouped = groupEditsByFile(edit.edits);
   const files = [...grouped.keys()].sort();
   return withAllMutationQueues(files, async () => {
+    if (options.expectedFingerprints) {
+      const freshness = validateFingerprints(files, options.expectedFingerprints);
+      if (!freshness.ok) return { kind: "error", reason: freshness.reason };
+    }
+
     const validation = validateEditAgainstFiles(edit);
     if (!validation.safe) {
       return { kind: "error", reason: validation.reason };
@@ -55,6 +76,35 @@ export async function applyWorkspaceEdit(edit: WorkspaceEdit): Promise<ApplyResu
   });
 }
 
+function validateFingerprints(
+  files: string[],
+  expected: ReadonlyMap<string, string>,
+): { ok: true } | { ok: false; reason: string } {
+  for (const file of files) {
+    const expectedFingerprint = expected.get(file);
+    if (expectedFingerprint === undefined) continue;
+    let actual: string;
+    try {
+      actual = sha256File(file);
+    } catch {
+      return stalePlanError(file);
+    }
+    if (actual !== expectedFingerprint) return stalePlanError(file);
+  }
+  return { ok: true };
+}
+
+function sha256File(file: string): string {
+  return createHash("sha256").update(readFileSync(file, "utf-8")).digest("hex");
+}
+
+function stalePlanError(file: string): { ok: false; reason: string } {
+  return {
+    ok: false,
+    reason: `File ${file} has changed since the plan was generated. Regenerate with code_refactor_plan.`,
+  };
+}
+
 /**
  * Acquire pi's per-file mutation queue for every involved file in sorted path
  * order before running `fn`, holding all locks for the duration. Sorted order
@@ -111,8 +161,9 @@ 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),
+      // Descending by start position so later edits don't shift earlier ones.
+      compareCodePositions(right.range.start, left.range.start) ||
+      compareCodePositions(right.range.end, left.range.end),
   );
 
   let updated = content;
@@ -125,26 +176,40 @@ function applyEditsToContent(content: string, edits: FileEdit[]): string {
   return updated;
 }
 
+interface StagedContents {
+  kind: "staged";
+  files: Map<string, string>;
+}
+
+type StageResult = StagedContents | { kind: "error"; reason: string };
+
 function commitTransformedContents(
   transformedContents: Map<string, string>,
   originalContents: Map<string, string>,
   totalEdits: number,
 ): ApplyResult {
-  const writtenFiles: string[] = [];
+  const staged = stageTransformedContents(transformedContents);
+  if (staged.kind === "error") return staged;
 
+  const committedFiles: string[] = [];
   try {
-    for (const file of [...transformedContents.keys()].sort()) {
-      writeFileSync(file, transformedContents.get(file) ?? "", "utf-8");
-      writtenFiles.push(file);
+    // ponytail: no durable journal; add one only if cross-file crash recovery is required.
+    for (const [file, stagedFile] of [...staged.files].sort(([left], [right]) =>
+      left.localeCompare(right),
+    )) {
+      renameSync(stagedFile, file);
+      committedFiles.push(file);
     }
   } catch (error) {
-    const rollbackError = rollbackWrittenFiles(writtenFiles, originalContents);
+    const rollbackError = rollbackCommittedFiles(committedFiles, originalContents);
     return {
       kind: "error",
       reason: rollbackError
         ? `${toErrorMessage(error)} (rollback failed: ${rollbackError})`
         : toErrorMessage(error),
     };
+  } finally {
+    cleanupStagedFiles(staged.files);
   }
 
   return {
@@ -154,12 +219,45 @@ function commitTransformedContents(
   };
 }
 
-function rollbackWrittenFiles(
-  writtenFiles: string[],
+function stageTransformedContents(transformedContents: Map<string, string>): StageResult {
+  const stagedFiles = new Map<string, string>();
+  try {
+    for (const [file, content] of transformedContents) {
+      const stagedFile = stagedFilePath(file);
+      stagedFiles.set(file, stagedFile);
+      writeFileSync(stagedFile, content, {
+        encoding: "utf-8",
+        flag: "wx",
+        mode: statSync(file).mode & 0o777,
+      });
+    }
+    return { kind: "staged", files: stagedFiles };
+  } catch (error) {
+    cleanupStagedFiles(stagedFiles);
+    return { kind: "error", reason: toErrorMessage(error) };
+  }
+}
+
+function stagedFilePath(file: string): string {
+  return join(dirname(file), `.${basename(file)}.supi-refactor-${randomUUID()}.tmp`);
+}
+
+function cleanupStagedFiles(stagedFiles: ReadonlyMap<string, string>): void {
+  for (const stagedFile of stagedFiles.values()) {
+    try {
+      rmSync(stagedFile, { force: true });
+    } catch {
+      // Staging cleanup is best-effort; source files have already been preserved or restored.
+    }
+  }
+}
+
+function rollbackCommittedFiles(
+  committedFiles: string[],
   originalContents: Map<string, string>,
 ): string | null {
   try {
-    for (const file of writtenFiles.reverse()) {
+    for (const file of committedFiles.reverse()) {
       writeFileSync(file, originalContents.get(file) ?? "", "utf-8");
     }
     return null;
@@ -168,10 +266,6 @@ function rollbackWrittenFiles(
   }
 }
 
-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++) {

package/src/analysis/refactor/position.ts

@@ -0,0 +1,6 @@
+import type { CodePosition } from "@mrclrchtr/supi-code-runtime/api";
+
+/** Compare zero-based source positions lexicographically by line, then character. */
+export function compareCodePositions(left: CodePosition, right: CodePosition): number {
+  return left.line - right.line || left.character - right.character;
+}

package/src/analysis/refactor/safety.ts

@@ -7,6 +7,7 @@
 
 import { readFileSync } from "node:fs";
 import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
+import { compareCodePositions } from "./position.ts";
 
 export type ValidationResult = { safe: true } | { safe: false; reason: string };
 
@@ -122,27 +123,19 @@ function validateCharacterBounds(file: string, edit: FileEdit, lines: string[]):
 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),
+    const sorted = [...fileEdits].sort((left, right) =>
+      compareCodePositions(left.range.start, right.range.start),
     );
 
     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;
+      if (compareCodePositions(current.range.start, previous.range.end) < 0) 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) {

package/src/analysis/references/locations.ts

@@ -0,0 +1,20 @@
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+
+/** Minimal semantic location shape used to remove a declaration from references. */
+export interface HasLspPosition {
+  uri: string;
+  range: { start: { line: number; character: number } };
+}
+
+/** Exclude the target declaration from provider references. */
+export function filterOutDeclaration<T extends HasLspPosition>(
+  references: T[],
+  targetFile: string,
+  targetPosition: { line: number; character: number },
+): T[] {
+  return references.filter((reference) => {
+    if (uriToFile(reference.uri) !== targetFile) return true;
+    const start = reference.range.start;
+    return start.line !== targetPosition.line || start.character !== targetPosition.character;
+  });
+}

package/src/analysis/references/semantic-refs.ts

@@ -6,14 +6,17 @@ import type {
   ConfidenceMode,
   SemanticProvider as SemanticSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
 import {
   createEvidenceList,
+  type EvidenceList,
   type EvidenceListMetadata,
   renderEvidenceListDisclosure,
 } from "../evidence.ts";
 import { dedupeFileLineRefs, highestConfidence } from "../helpers.ts";
-import { filterOutDeclaration, isInProjectPath, uriToFile } from "../search/ripgrep.ts";
+import { isInProjectPath } from "../search/paths.ts";
 import type { ResolvedTargetData } from "../target/types.ts";
+import { filterOutDeclaration } from "./locations.ts";
 
 export interface FileLineRef {
   file: string;
@@ -35,20 +38,21 @@ export async function collectReferences(
   cwd: string,
   semantic: SemanticSubstrate,
 ): Promise<ReferenceCollection> {
-  const locs = await semantic.references(target.file, target.position);
-  if (!locs) {
+  const result = await semantic.references(target.file, target.position);
+  if (result.kind === "unavailable") {
     return { refs: [], confidence: "unavailable", externalCount: 0 };
   }
+  const locations = result.data;
 
   let externalCount = 0;
-  for (const ref of locs) {
+  for (const ref of locations) {
     const filePath = uriToFile(ref.uri);
     if (!isInProjectPath(filePath, cwd)) {
       externalCount++;
     }
   }
 
-  const filtered = filterOutDeclaration(locs, target.file, target.position);
+  const filtered = filterOutDeclaration(locations, target.file, target.position);
   const projectRefs: FileLineRef[] = [];
   for (const ref of filtered) {
     const filePath = uriToFile(ref.uri);
@@ -123,6 +127,16 @@ export function formatReferenceList(
     maxResults,
   });
 
+  return formatAssembledReferenceList(lines, evidence);
+}
+
+/** Render a reference list whose items and completeness were already assembled. */
+export function formatAssembledReferenceList(
+  lines: string[],
+  evidence: EvidenceList<FileLineRef>,
+): EvidenceListMetadata | null {
+  if (evidence.metadata.totalCount === 0 && evidence.items.length === 0) return null;
+
   const byFile = new Map<string, number[]>();
   for (const ref of evidence.items) {
     const group = byFile.get(ref.file) ?? [];
@@ -132,15 +146,11 @@ export function formatReferenceList(
 
   for (const [file, locations] of byFile) {
     lines.push(`### ${file}`);
-    const label = compactLineRanges(locations);
-    lines.push(`- ${label}`);
+    lines.push(`- ${compactLineRanges(locations)}`);
     lines.push("");
   }
 
   const disclosure = renderEvidenceListDisclosure(evidence);
-  if (disclosure) {
-    lines.push(disclosure);
-  }
-
+  if (disclosure) lines.push(disclosure);
   return evidence.metadata;
 }

package/src/{tool/graph → analysis/relations}/implementations.ts

@@ -2,6 +2,12 @@
  * Semantic implementation lookup — finds implementations of a target.
  */
 
+import {
+  isTargetLocation,
+  normalizeProviderLocations,
+  normalizeTargetFile,
+  type RelationLocationPartialReason,
+} from "./provider-locations.ts";
 import type { ImplementationEntry, RelationsServiceDeps } from "./types.ts";
 
 export interface ImplementationsResult {
@@ -9,6 +15,9 @@ export interface ImplementationsResult {
   targetName: string;
   implementations: ImplementationEntry[];
   externalCount: number;
+  /** Provider locations omitted because their URI or position was unusable. */
+  invalidLocationCount: number;
+  partialReason: RelationLocationPartialReason | null;
   confidence: "semantic" | "unavailable";
 }
 
@@ -29,40 +38,32 @@ export async function collectImplementations(
       targetName: targetName ?? "symbol",
       implementations: [],
       externalCount: 0,
+      invalidLocationCount: 0,
+      partialReason: null,
       confidence: "unavailable",
     };
   }
 
-  const impls = await deps.provider.implementation(targetFile, targetPosition);
-  if (!impls) {
+  const result = await deps.provider.implementation(targetFile, targetPosition);
+  if (result.kind === "unavailable") {
     return {
       kind: "implementations",
       targetName: targetName ?? "symbol",
       implementations: [],
       externalCount: 0,
-      confidence: "semantic",
+      invalidLocationCount: 0,
+      partialReason: null,
+      confidence: "unavailable",
     };
   }
 
-  const project: ImplementationEntry[] = [];
-  let externalCount = 0;
-
-  for (const loc of impls) {
-    const uri = loc.uri ?? loc.targetUri ?? "";
-    const filePath = uri.startsWith("file://") ? uri.slice(7) : uri;
-    const line = (loc.range?.start?.line ?? loc.targetRange?.start?.line ?? 0) + 1;
-
-    if (filePath?.startsWith(deps.cwd)) {
-      project.push({
-        file: filePath,
-        line,
-        character: 0,
-        name: targetName,
-      });
-    } else {
-      externalCount++;
-    }
-  }
+  const normalized = normalizeProviderLocations(result.data, deps.cwd);
+  const normalizedTargetFile = normalizeTargetFile(targetFile, deps.cwd);
+  const project: ImplementationEntry[] = normalized.project
+    .filter(
+      (implementation) => !isTargetLocation(implementation, normalizedTargetFile, targetPosition),
+    )
+    .map((implementation) => ({ ...implementation, name: targetName }));
 
   void maxResults;
 
@@ -70,7 +71,10 @@ export async function collectImplementations(
     kind: "implementations",
     targetName: targetName ?? "symbol",
     implementations: project,
-    externalCount,
+    externalCount: normalized.external.length,
+    invalidLocationCount: normalized.invalidLocationCount,
+    partialReason:
+      normalized.partialReason ?? (result.kind === "partial" ? "provider-limited" : null),
     confidence: "semantic",
   };
 }

package/src/analysis/relations/provider-locations.ts

@@ -0,0 +1,179 @@
+import * as path from "node:path";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+
+/** Why a provider-backed relation location could not be included as evidence. */
+export type RelationLocationPartialReason = "invalid-provider-location" | "provider-limited";
+
+interface ProviderPositionLike {
+  readonly line?: number;
+  readonly character?: number;
+}
+
+interface ProviderRangeLike {
+  readonly start?: ProviderPositionLike;
+}
+
+/** Location shapes accepted from semantic providers, including LSP LocationLink fields. */
+export interface ProviderLocationLike {
+  readonly uri?: string;
+  readonly targetUri?: string;
+  readonly range?: ProviderRangeLike;
+  readonly targetSelectionRange?: ProviderRangeLike;
+  readonly targetRange?: ProviderRangeLike;
+}
+
+/** One canonical absolute provider location with a 1-based display position. */
+export interface NormalizedProviderLocation {
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+}
+
+/** Canonical provider locations partitioned without treating invalid data as external evidence. */
+export interface NormalizedProviderLocations {
+  readonly project: readonly NormalizedProviderLocation[];
+  readonly external: readonly NormalizedProviderLocation[];
+  readonly invalidLocationCount: number;
+  readonly partialReason: RelationLocationPartialReason | null;
+}
+
+/**
+ * Normalize, validate, deduplicate, order, and classify semantic-provider locations.
+ * Invalid locations are counted separately because they establish neither project nor external facts.
+ */
+export function normalizeProviderLocations(
+  locations: readonly ProviderLocationLike[],
+  cwd: string,
+): NormalizedProviderLocations {
+  const flavor = pathFlavor(cwd);
+  const projectRoot = normalizeAbsolutePath(cwd, flavor);
+  const unique = new Map<string, NormalizedProviderLocation>();
+  let invalidLocationCount = 0;
+
+  for (const location of locations) {
+    const normalized = normalizeProviderLocation(location, flavor);
+    if (!normalized) {
+      invalidLocationCount++;
+      continue;
+    }
+    const key = locationKey(normalized);
+    const existing = unique.get(key);
+    if (!existing || compareLocations(normalized, existing) < 0) {
+      unique.set(key, normalized);
+    }
+  }
+
+  const project: NormalizedProviderLocation[] = [];
+  const external: NormalizedProviderLocation[] = [];
+  for (const location of [...unique.values()].sort(compareLocations)) {
+    (isProjectLocation(projectRoot, location.file, flavor) ? project : external).push(location);
+  }
+
+  return {
+    project,
+    external,
+    invalidLocationCount,
+    partialReason: invalidLocationCount > 0 ? "invalid-provider-location" : null,
+  };
+}
+
+/** Normalize a target path for exact declaration-location comparisons. */
+export function normalizeTargetFile(file: string, cwd: string): string {
+  const flavor = pathFlavor(cwd);
+  const pathApi = flavor === "windows" ? path.win32 : path.posix;
+  return pathApi.normalize(pathApi.isAbsolute(file) ? file : pathApi.resolve(cwd, file));
+}
+
+/** Compare a normalized provider location with a zero-based target anchor. */
+export function isTargetLocation(
+  location: NormalizedProviderLocation,
+  targetFile: string,
+  targetPosition: { readonly line: number; readonly character: number },
+): boolean {
+  return (
+    pathsEqual(location.file, targetFile) &&
+    location.line === targetPosition.line + 1 &&
+    location.character === targetPosition.character + 1
+  );
+}
+
+type PathFlavor = "posix" | "windows";
+
+function normalizeProviderLocation(
+  location: ProviderLocationLike,
+  flavor: PathFlavor,
+): NormalizedProviderLocation | null {
+  const uri = location.uri ?? location.targetUri;
+  const start =
+    location.targetSelectionRange?.start ?? location.targetRange?.start ?? location.range?.start;
+  if (!uri || !isProviderPosition(start)) return null;
+
+  let file: string;
+  try {
+    file = uriToFile(uri);
+  } catch {
+    return null;
+  }
+  if (flavor === "windows" && /^\/[A-Za-z]:[\\/]/.test(file)) {
+    file = file.slice(1);
+  }
+  const pathApi = flavor === "windows" ? path.win32 : path.posix;
+  if (!file || !pathApi.isAbsolute(file)) return null;
+
+  return {
+    file: pathApi.normalize(file),
+    line: start.line + 1,
+    character: start.character + 1,
+  };
+}
+
+function isProviderPosition(value: ProviderPositionLike | undefined): value is {
+  line: number;
+  character: number;
+} {
+  return (
+    value !== undefined &&
+    typeof value.line === "number" &&
+    Number.isInteger(value.line) &&
+    value.line >= 0 &&
+    typeof value.character === "number" &&
+    Number.isInteger(value.character) &&
+    value.character >= 0
+  );
+}
+
+function pathFlavor(file: string): PathFlavor {
+  return /^[A-Za-z]:[\\/]/.test(file) || file.startsWith("\\\\") ? "windows" : "posix";
+}
+
+function normalizeAbsolutePath(file: string, flavor: PathFlavor): string {
+  const pathApi = flavor === "windows" ? path.win32 : path.posix;
+  return pathApi.normalize(pathApi.resolve(file));
+}
+
+function isProjectLocation(root: string, file: string, flavor: PathFlavor): boolean {
+  const pathApi = flavor === "windows" ? path.win32 : path.posix;
+  const relative = pathApi.relative(root, file);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${pathApi.sep}`) && !pathApi.isAbsolute(relative))
+  );
+}
+
+function pathsEqual(left: string, right: string): boolean {
+  if (pathFlavor(left) === "windows" || pathFlavor(right) === "windows") {
+    return path.win32.relative(left, right) === "";
+  }
+  return left === right;
+}
+
+function locationKey(location: NormalizedProviderLocation): string {
+  const fileKey =
+    pathFlavor(location.file) === "windows" ? location.file.toLowerCase() : location.file;
+  return `${fileKey}\0${location.line}\0${location.character}`;
+}
+
+function compareLocations(a: NormalizedProviderLocation, b: NormalizedProviderLocation): number {
+  if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+  return a.line - b.line || a.character - b.character;
+}