feat: enhance file versioning and snippet handling in edit and write tools

qorzj · qorzj · commit 9588313e1634 · 2026-05-15T15:17:47.000+08:00
diff --git a/src/common/state.ts b/src/common/state.ts
@@ -7,6 +7,7 @@ export type FileState = {
   filePath: string;
   content: string;
   timestamp: number;
+  version?: number;
   offset?: number;
   limit?: number;
   isPartialView?: boolean;
@@ -20,11 +21,13 @@ export type FileSnippet = {
   startLine: number;
   endLine: number;
   preview: string;
+  fileVersion: number;
 };
 
 const fileStatesBySession = new Map<string, Map<string, FileState>>();
 const snippetsBySession = new Map<string, Map<string, FileSnippet>>();
 const snippetCountersBySession = new Map<string, number>();
+const fileVersionsBySession = new Map<string, Map<string, number>>();
 
 export function normalizeFilePath(filePath: string, platform: NodeJS.Platform = process.platform): string {
   const nativePath = normalizeNativeFilePath(filePath, platform);
@@ -57,7 +60,11 @@ function isGitBashAbsolutePath(filePath: string): boolean {
   return /^\/[A-Za-z](?:\/|$)/.test(filePath) || /^\/cygdrive\/[A-Za-z](?:\/|$)/.test(filePath);
 }
 
-export function recordFileState(sessionId: string, state: FileState): void {
+export function recordFileState(
+  sessionId: string,
+  state: FileState,
+  options: { incrementVersion?: boolean } = {}
+): void {
   if (!sessionId || !state.filePath) {
     return;
   }
@@ -69,9 +76,13 @@ export function recordFileState(sessionId: string, state: FileState): void {
   }
 
   const normalizedPath = normalizeFilePath(state.filePath);
+  const currentVersion = getFileVersion(sessionId, normalizedPath);
+  const nextVersion = options.incrementVersion ? currentVersion + 1 : currentVersion;
+  setFileVersion(sessionId, normalizedPath, nextVersion);
   sessionState.set(normalizedPath, {
     ...state,
     filePath: normalizedPath,
+    version: nextVersion,
   });
 }
 
@@ -108,6 +119,22 @@ export function wasFileRead(sessionId: string, filePath: string): boolean {
   return getFileState(sessionId, filePath) !== null;
 }
 
+export function getFileVersion(sessionId: string, filePath: string): number {
+  if (!sessionId || !filePath) {
+    return 0;
+  }
+  return fileVersionsBySession.get(sessionId)?.get(normalizeFilePath(filePath)) ?? 0;
+}
+
+function setFileVersion(sessionId: string, filePath: string, version: number): void {
+  let sessionVersions = fileVersionsBySession.get(sessionId);
+  if (!sessionVersions) {
+    sessionVersions = new Map<string, number>();
+    fileVersionsBySession.set(sessionId, sessionVersions);
+  }
+  sessionVersions.set(normalizeFilePath(filePath), version);
+}
+
 export function isFullFileView(state: FileState | null): boolean {
   return Boolean(
     state && !state.isPartialView && typeof state.offset === "undefined" && typeof state.limit === "undefined"
@@ -134,6 +161,7 @@ export function createSnippet(
     startLine,
     endLine,
     preview,
+    fileVersion: getFileVersion(sessionId, filePath),
   };
 
   let snippets = snippetsBySession.get(sessionId);
@@ -151,3 +179,7 @@ export function getSnippet(sessionId: string, snippetId: string): FileSnippet |
   }
   return snippetsBySession.get(sessionId)?.get(snippetId) ?? null;
 }
+
+export function hasSnippetOutdatedFileVersion(sessionId: string, snippet: FileSnippet): boolean {
+  return getFileVersion(sessionId, snippet.filePath) > snippet.fileVersion;
+}
diff --git a/src/tests/tool-handlers.test.ts b/src/tests/tool-handlers.test.ts
@@ -88,6 +88,184 @@ test("Edit returns candidate match snippets when old_string is not unique", asyn
   assert.match(candidates[0]?.preview ?? "", /city/);
 });
 
+test("Edit returns closest matches only above threshold with surrounding context", async () => {
+  const workspace = createTempWorkspace();
+  const filePath = path.join(workspace, "closest.ts");
+  fs.writeFileSync(
+    filePath,
+    [
+      "const before = true;",
+      "function computeSubtotal(value: number) {",
+      "  return value;",
+      "}",
+      "const after = true;",
+    ].join("\n"),
+    "utf8"
+  );
+
+  const sessionId = "closest-match-context";
+  await handleReadTool({ file_path: filePath }, createContext(sessionId, workspace));
+
+  const closeResult = await handleEditTool(
+    {
+      file_path: filePath,
+      old_string: "function computeTotal(value: number) {",
+      new_string: "function computeTotal(input: number) {",
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(closeResult.ok, false);
+  assert.equal(closeResult.error, "old_string not found in file.");
+  const closestMatch = closeResult.metadata?.closest_match as
+    | { snippet_id?: string; start_line?: number; end_line?: number; similarity?: number; preview?: string }
+    | undefined;
+  assert.ok(closestMatch?.snippet_id);
+  assert.equal(closestMatch.start_line, 1);
+  assert.equal(closestMatch.end_line, 4);
+  assert.ok((closestMatch.similarity ?? 0) >= 0.8);
+  assert.match(closestMatch.preview ?? "", /const before = true/);
+  assert.match(closestMatch.preview ?? "", /return value/);
+
+  const lowResult = await handleEditTool(
+    {
+      file_path: filePath,
+      old_string: 'query: string = Field(description="search query")',
+      new_string: "query: string",
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(lowResult.ok, false);
+  assert.equal(lowResult.error, "old_string not found in file.");
+  assert.equal(lowResult.metadata?.closest_match, undefined);
+
+  const partialRead = await handleReadTool(
+    { file_path: filePath, offset: 2, limit: 2 },
+    createContext(sessionId, workspace)
+  );
+  const snippet = (partialRead.metadata?.snippet ?? null) as { id: string } | null;
+  assert.ok(snippet);
+
+  const scopedCloseResult = await handleEditTool(
+    {
+      snippet_id: snippet.id,
+      old_string: "function computeTotal(value: number) {",
+      new_string: "function computeTotal(input: number) {",
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(scopedCloseResult.ok, false);
+  const scopedClosestMatch = scopedCloseResult.metadata?.closest_match as
+    | { start_line?: number; end_line?: number; preview?: string }
+    | undefined;
+  assert.equal(scopedClosestMatch?.start_line, 2);
+  assert.equal(scopedClosestMatch?.end_line, 3);
+  assert.doesNotMatch(scopedClosestMatch?.preview ?? "", /const before = true/);
+});
+
+test("Edit allows outdated snippet matches but reports outdated snippet when no match is found", async () => {
+  const workspace = createTempWorkspace();
+  const filePath = path.join(workspace, "snippet-outdated.txt");
+  fs.writeFileSync(filePath, ["alpha = 1", "beta = 1", "gamma = 1"].join("\n"), "utf8");
+
+  const sessionId = "outdated-snippet-miss";
+  const readResult = await handleReadTool({ file_path: filePath }, createContext(sessionId, workspace));
+  const snippet = (readResult.metadata?.snippet ?? null) as { id: string } | null;
+  assert.ok(snippet);
+
+  const firstEdit = await handleEditTool(
+    {
+      snippet_id: snippet.id,
+      old_string: "alpha = 1",
+      new_string: "alpha = 2",
+    },
+    createContext(sessionId, workspace)
+  );
+  assert.equal(firstEdit.ok, true);
+
+  const secondEdit = await handleEditTool(
+    {
+      snippet_id: snippet.id,
+      old_string: "beta = 1",
+      new_string: "beta = 2",
+    },
+    createContext(sessionId, workspace)
+  );
+  assert.equal(secondEdit.ok, true);
+  assert.equal(fs.readFileSync(filePath, "utf8"), ["alpha = 2", "beta = 2", "gamma = 1"].join("\n"));
+
+  const missingEdit = await handleEditTool(
+    {
+      snippet_id: snippet.id,
+      old_string: "delta = 1",
+      new_string: "delta = 2",
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(missingEdit.ok, false);
+  assert.equal(
+    missingEdit.error,
+    "old_string was not found in this snippet scope. The file has changed since this snippet was created. Read the file again before editing."
+  );
+  const outdatedScope = (missingEdit.metadata?.scope ?? {}) as { snippet_id?: string };
+  assert.equal(outdatedScope.snippet_id, snippet.id);
+
+  const freshRead = await handleReadTool({ file_path: filePath }, createContext(sessionId, workspace));
+  const freshSnippet = (freshRead.metadata?.snippet ?? null) as { id: string } | null;
+  assert.ok(freshSnippet);
+
+  const freshMissingEdit = await handleEditTool(
+    {
+      snippet_id: freshSnippet.id,
+      old_string: "delta = 1",
+      new_string: "delta = 2",
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(freshMissingEdit.ok, false);
+  assert.equal(freshMissingEdit.error, "old_string not found in file.");
+});
+
+test("Edit reports outdated snippet when a later Write changes the file and snippet matching fails", async () => {
+  const workspace = createTempWorkspace();
+  const filePath = path.join(workspace, "write-outdated.txt");
+  fs.writeFileSync(filePath, ["alpha = 1", "beta = 1"].join("\n"), "utf8");
+
+  const sessionId = "write-outdated-snippet";
+  const readResult = await handleReadTool({ file_path: filePath }, createContext(sessionId, workspace));
+  const snippet = (readResult.metadata?.snippet ?? null) as { id: string } | null;
+  assert.ok(snippet);
+
+  const writeResult = await handleWriteTool(
+    {
+      file_path: filePath,
+      content: ["alpha = 2", "gamma = 2"].join("\n"),
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(writeResult.ok, true);
+
+  const editResult = await handleEditTool(
+    {
+      snippet_id: snippet.id,
+      old_string: "beta = 1",
+      new_string: "beta = 2",
+    },
+    createContext(sessionId, workspace)
+  );
+
+  assert.equal(editResult.ok, false);
+  assert.equal(
+    editResult.error,
+    "old_string was not found in this snippet scope. The file has changed since this snippet was created. Read the file again before editing."
+  );
+});
+
 test("replace_all requires expected_occurrences for broad short-fragment replacements", async () => {
   const workspace = createTempWorkspace();
   const filePath = path.join(workspace, "openapi.yaml");
diff --git a/src/tools/edit-handler.ts b/src/tools/edit-handler.ts
@@ -13,6 +13,7 @@ import {
   createSnippet,
   getFileState,
   getSnippet,
+  hasSnippetOutdatedFileVersion,
   isAbsoluteFilePath,
   isFullFileView,
   normalizeFilePath,
@@ -22,7 +23,10 @@ import {
 const MAX_CANDIDATE_COUNT = 5;
 const REPLACE_ALL_MATCH_THRESHOLD = 5;
 const SHORT_REPLACE_ALL_LENGTH = 40;
-const MIN_FUZZY_SCORE = 0.45;
+const MIN_FUZZY_SCORE = 0.8;
+const CLOSEST_MATCH_CONTEXT_LINES = 2;
+const OUTDATED_SNIPPET_NOT_FOUND_ERROR =
+  "old_string was not found in this snippet scope. The file has changed since this snippet was created. Read the file again before editing.";
 
 type LineIndex = {
   lines: string[];
@@ -242,6 +246,17 @@ export async function handleEditTool(
         }
 
         if (matches.length === 0) {
+          if (snippet && hasSnippetOutdatedFileVersion(context.sessionId, snippet)) {
+            return {
+              ok: false,
+              name: "edit",
+              error: OUTDATED_SNIPPET_NOT_FOUND_ERROR,
+              metadata: {
+                scope: formatScopeMetadata(scope),
+              },
+            };
+          }
+
           const closestMatch = findClosestMatch(raw, oldString, scope, lineIndex);
           return {
             ok: false,
@@ -295,13 +310,17 @@ export async function handleEditTool(
         const diffPreview = buildDiffPreview(filePath, raw, updated);
         writeTextFile(filePath, updated, metadata.encoding, metadata.lineEndings);
         const freshMetadata = readTextFileWithMetadata(filePath);
-        recordFileState(context.sessionId, {
-          filePath,
-          content: freshMetadata.content,
-          timestamp: freshMetadata.timestamp,
-          encoding: freshMetadata.encoding,
-          lineEndings: freshMetadata.lineEndings,
-        });
+        recordFileState(
+          context.sessionId,
+          {
+            filePath,
+            content: freshMetadata.content,
+            timestamp: freshMetadata.timestamp,
+            encoding: freshMetadata.encoding,
+            lineEndings: freshMetadata.lineEndings,
+          },
+          { incrementVersion: true }
+        );
         const replacedCount = replaceAll ? matches.length : 1;
         return {
           ok: true,
@@ -603,8 +622,8 @@ function findClosestMatch(
       }
     }
 
-    if (bestLooseMatch) {
-      return bestLooseMatch;
+    if (bestLooseMatch && bestLooseMatch.score >= MIN_FUZZY_SCORE) {
+      return expandClosestMatch(raw, lineIndex, scope, bestLooseMatch);
     }
   }
 
@@ -640,7 +659,23 @@ function findClosestMatch(
     }
   }
 
-  return bestMatch;
+  return bestMatch ? expandClosestMatch(raw, lineIndex, scope, bestMatch) : null;
+}
+
+function expandClosestMatch(
+  raw: string,
+  lineIndex: LineIndex,
+  scope: SearchScope,
+  closestMatch: ClosestMatch
+): ClosestMatch {
+  const startLine = clamp(closestMatch.startLine - CLOSEST_MATCH_CONTEXT_LINES, scope.startLine, scope.endLine);
+  const endLine = clamp(closestMatch.endLine + CLOSEST_MATCH_CONTEXT_LINES, startLine, scope.endLine);
+  return {
+    ...closestMatch,
+    text: sliceLines(raw, lineIndex, startLine, endLine),
+    startLine,
+    endLine,
+  };
 }
 
 function buildLooseEscapeRegex(source: string): RegExp | null {
diff --git a/src/tools/write-handler.ts b/src/tools/write-handler.ts
@@ -100,13 +100,17 @@ export async function handleWriteTool(
         const bytes = writeTextFile(filePath, normalizedContent, encoding, lineEndings);
         const freshMetadata = readTextFileWithMetadata(filePath);
 
-        recordFileState(context.sessionId, {
-          filePath,
-          content: freshMetadata.content,
-          timestamp: freshMetadata.timestamp,
-          encoding: freshMetadata.encoding,
-          lineEndings: freshMetadata.lineEndings,
-        });
+        recordFileState(
+          context.sessionId,
+          {
+            filePath,
+            content: freshMetadata.content,
+            timestamp: freshMetadata.timestamp,
+            encoding: freshMetadata.encoding,
+            lineEndings: freshMetadata.lineEndings,
+          },
+          { incrementVersion: true }
+        );
 
         return {
           ok: true,
