editcodewithai 2.4.0 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # editcodewithai
 
-A lightweight, flexible library for AI-powered code editing.
+A lightweight, model-agnostic library for AI-powered code editing.
 
 See also [vizhub-benchmarks](https://github.com/vizhub-core/vizhub-benchmarks).
 
@@ -8,7 +8,7 @@ See also [vizhub-benchmarks](https://github.com/vizhub-core/vizhub-benchmarks).
 
 `editcodewithai` is a JavaScript/TypeScript library that enables AI-powered code editing in your applications. It provides a simple interface to send code files and instructions to an LLM (Large Language Model) and receive edited code in return.
 
-The library is designed to be model-agnostic, allowing you to use any LLM provider while handling the prompt engineering, file parsing, and response processing for you.
+The library is designed to be **model-agnostic** — you provide a function that calls any LLM provider (OpenAI, Anthropic, OpenRouter, local models, etc.), and `editcodewithai` handles the prompt engineering, file parsing, and response processing.
 
 Edit formats inspired by [Aider](https://aider.chat/). See [Aider: Edit Formats](https://aider.chat/docs/more/edit-formats.html) for details.
 
@@ -66,16 +66,24 @@ main();
 
 ## Edit Formats
 
-This library supports several "edit formats" that instruct the LLM on how to specify file changes. Different models may perform better with different formats. You can specify the format using the `editFormat` parameter in `performAiEdit`.
+This library supports five edit formats that instruct the LLM on how to specify file changes. Different models may perform better with different formats. You specify the format via the `editFormat` parameter in `performAiEdit`.
+
+| Format        | Description                                                                                 | File path location       |
+| ------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
+| `whole`       | Complete file replacement (default). Simple but wasteful for small changes in large files.  | After `**file.js**` bold |
+| `diff`        | Search/replace blocks. Efficient — only the changed portions are transmitted. (Aider-style) | Outside the code fence   |
+| `diff-fenced` | Same search/replace blocks, but with file path _inside_ the code fence.                     | Inside the code fence    |
+| `udiff`       | Unified diff format. Each hunk shows exact lines to add/remove with surrounding context.    | After `---` / `+++`      |
+| `hybrid`      | Mix-and-match: the LLM chooses per file whether to use `whole` or `diff` format.            | Both styles supported    |
 
 ### `whole` (default)
 
-The LLM returns the complete, updated content for each file that needs changes. This is simple but can be inefficient for large files with small changes.
+The LLM returns the complete, updated content for each file that needs changes. The file name is written in bold (`**name**`) followed by a fenced code block.
 
-**Example:**
+**Example LLM response:**
 
 ````
-index.js
+**index.js**
 ```js
 console.log("Hello, Universe!");
 ```
@@ -83,9 +91,9 @@ console.log("Hello, Universe!");
 
 ### `diff`
 
-The LLM returns a series of search-and-replace blocks. This is efficient as it only includes the changed portions of the files.
+The LLM returns search/replace blocks. Each block specifies the file path on its own line, then a fenced block containing a `<<<<<<< SEARCH` / `=======` / `>>>>>>> REPLACE` section. The library finds the `SEARCH` text in the original file and replaces it with the `REPLACE` text.
 
-**Example:**
+**Example LLM response:**
 
 ````
 index.js
@@ -98,23 +106,182 @@ console.log("Hello, Universe!");
 ```
 ````
 
-### File Operations
+### `diff-fenced`
+
+Same search/replace concept as `diff`, but the file path is placed on the first line _inside_ the code fence instead of outside it.
+
+**Example LLM response:**
+
+````
+```
+index.js
+<<<<<<< SEARCH
+console.log("Hello, World!");
+=======
+console.log("Hello, Universe!");
+>>>>>>> REPLACE
+```
+````
+
+### `udiff`
+
+The LLM returns standard unified diff hunks inside a ` ```diff ` code fence. Each hunk begins with `@@ ... @@` and uses `-` / `+` prefixes for removed / added lines. Lines prefixed with a space are context used for matching.
+
+**Example LLM response:**
+
+````diff
+```diff
+--- index.js
++++ index.js
+@@ -1 +1 @@
+-console.log("Hello, World!");
++console.log("Hello, Universe!");
+```
+````
+
+### `hybrid`
+
+The LLM can mix both whole-file and search/replace formats in the same response, choosing per file which is more appropriate. Use the **whole-file format** for major rewrites, new files, or when many parts of a file change. Use the **search/replace diff format** for small, targeted changes. If the same file appears in both formats, the whole-file content takes precedence (applied after the diff).
+
+**Example LLM response:**
+
+````
+alpha.js
+```
+<<<<<<< SEARCH
+const greeting = "Hello";
+=======
+const greeting = "Hi";
+>>>>>>> REPLACE
+```
+
+**beta.js**
+
+```js
+// Entirely rewritten file
+const beta = "new version";
+```
+````
+
+## File Operations
 
 The library handles several file operations automatically:
 
-- **Updating existing files**: When the AI modifies a file's content
-- **Creating new files**: When the AI suggests new files to add
-- **Deleting files**: When the AI returns empty content for a file
+- **Updating existing files**: When the AI modifies a file's content (using any edit format).
+- **Creating new files**: When the AI includes a file name that doesn't exist in the original set.
+- **Deleting files**: When the AI returns empty/whitespace-only content for a file (works with `whole` format; for `diff`/`udiff`, deletions happen naturally when all content is replaced).
 
-## Format Instructions
+### Best-effort application and warnings
 
-The library exports `FORMAT_INSTRUCTIONS` which contains the exact prompt instructions used for each edit format. This can be useful if you want to:
+`performAiEdit` applies edits independently and **never throws because the model
+returned an edit that could not be matched**. If one edit references a missing
+file, an anchor that cannot be found, or an ambiguous location, that edit is
+skipped and reported — every other valid edit is still applied.
 
-- Use the formatting instructions in your own custom prompts
-- Understand exactly what instructions are sent to the LLM for each format
-- Build your own AI editing tools using the same proven prompt patterns
+Skipped edits are returned in `result.warnings`:
 
-### Usage
+```typescript
+const result = await performAiEdit({
+  prompt,
+  files,
+  llmFunction,
+  editFormat: "diff",
+});
+
+for (const warning of result.warnings ?? []) {
+  console.warn(warning.code, warning.fileName, warning.message);
+}
+```
+
+| Warning code       | Meaning                                                             |
+| ------------------ | ------------------------------------------------------------------- |
+| `FILE_NOT_FOUND`   | The edit targets a filename that isn't in the file set.             |
+| `SEARCH_NOT_FOUND` | The `SEARCH` text could not be located in the file.                 |
+| `HUNK_NOT_FOUND`   | A udiff hunk's original lines could not be located.                 |
+| `AMBIGUOUS_SEARCH` | The anchor matched more than one location, so the edit was skipped. |
+| `AMBIGUOUS_FILE`   | More than one file shares the target name, so the edit was skipped. |
+| `EMPTY_SEARCH`     | The search block was empty, so the edit could not be applied.       |
+| `NO_EDITS_PARSED`  | The model response contained no recognizable edits.                 |
+
+Matching is deterministic: only harmless formatting drift is absorbed (CRLF vs
+LF, a missing/extra trailing newline, trailing whitespace). Anything ambiguous or
+unmatched is skipped rather than guessed. Successful normalized matches produce
+no warnings.
+
+`warnings` is optional, so existing consumers continue to work unchanged.
+
+## API Reference
+
+### `performAiEdit(params)`
+
+The main entry point. Accepts a `PerformAiEditParams` object and returns a `PerformAiEditResult`.
+
+#### Input: `PerformAiEditParams`
+
+| Property      | Type                                            | Default    | Description                                                                      |
+| ------------- | ----------------------------------------------- | ---------- | -------------------------------------------------------------------------------- |
+| `prompt`      | `string`                                        | _required_ | Natural-language instructions describing the desired changes.                    |
+| `files`       | `VizFiles`                                      | _required_ | A record of file objects (`{ [id]: { name, text } }`).                           |
+| `llmFunction` | `LlmFunction`                                   | _required_ | Async function that sends the assembled prompt to an LLM and returns its output. |
+| `editFormat`  | `"whole" \| "diff" \| "diff-fenced" \| "udiff"` | `"whole"`  | How the LLM should specify file changes.                                         |
+| `apiKey`      | `string`                                        | optional   | OpenRouter API key — if provided, cost metadata is fetched automatically.        |
+
+#### `LlmFunction`
+
+```typescript
+type LlmFunction = (prompt: string) => Promise<{
+  content: string; // The raw string response from the LLM
+  generationId?: string; // OpenRouter generation ID (for cost tracking)
+}>;
+```
+
+#### Output: `PerformAiEditResult`
+
+| Property                 | Type             | Description                                                       |
+| ------------------------ | ---------------- | ----------------------------------------------------------------- |
+| `changedFiles`           | `VizFiles`       | The updated file collection with all edits applied.               |
+| `openRouterGenerationId` | `string`         | The generation ID from the LLM function response.                 |
+| `upstreamCostCents`      | `number`         | Cost in cents (only populated if `apiKey` was provided).          |
+| `provider`               | `string`         | The OpenRouter provider name used.                                |
+| `inputTokens`            | `number`         | Number of input (prompt) tokens billed.                           |
+| `outputTokens`           | `number`         | Number of output (completion) tokens billed.                      |
+| `promptTemplateVersion`  | `number`         | Version of the prompt template used (for tracking migrations).    |
+| `rawResponse`            | `string`         | The raw string response from the LLM, unmodified.                 |
+| `warnings`               | `ApplyWarning[]` | Edits that were skipped because they could not be applied safely. |
+
+### Exported Utilities
+
+```typescript
+import {
+  // --- Prompt assembly ---
+  assembleFullPrompt, // Build a complete prompt string from task, files, format
+  FORMAT_INSTRUCTIONS, // { whole, diff, 'diff-fenced', udiff, hybrid } — full formatting instructions
+  PROMPT_TEMPLATE_VERSION,
+
+  // --- File processing ---
+  mergeFileChanges, // Merge LLM output back into original files
+  prepareFilesForPrompt, // Prepare files for prompt (truncation, image exclusion)
+  isImageFile, // Check if a filename refers to an image
+
+  // --- Diff parsing (manual use) ---
+  parseDiffs, // Parse search/replace blocks (diff format)
+  applyDiffs, // Apply parsed diffs to a file set (throws on unmatched edits)
+  applyDiffsSafe, // Best-effort apply: returns { files, warnings } instead of throwing
+  parseDiffFenced, // Parse search/replace blocks (diff-fenced format)
+  parseUdiffs, // Parse unified diff hunks
+  applyUdiffs, // Apply parsed unified diff hunks (throws on unmatched edits)
+  applyUdiffsSafe, // Best-effort apply: returns { files, warnings } instead of throwing
+  applyHybridEdits, // Apply mixed whole-file + diff edits from a single response
+  applyHybridEditsSafe, // Best-effort hybrid apply: returns { files, warnings }
+
+  // --- Cost metadata ---
+  getGenerationMetadata, // Fetch OpenRouter cost data for a generation ID
+} from "editcodewithai";
+```
+
+## Format Instructions
+
+The `FORMAT_INSTRUCTIONS` export contains the exact prompt text sent to the LLM for each edit format. You can use them in custom prompts:
 
 ```typescript
 import { FORMAT_INSTRUCTIONS } from "editcodewithai";
@@ -134,58 +301,67 @@ ${yourCodeHere}
 `;
 ```
 
-### Available Formats
+## Image File Handling
 
-The `FORMAT_INSTRUCTIONS` object contains instructions for these edit formats:
+Files with image extensions (`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.svg`, `.webp`) are handled specially:
 
-- **`whole`**: Instructions for returning complete file contents
-- **`diff`**: Instructions for search-and-replace blocks
-- **`diff-fenced`**: Instructions for search-and-replace blocks with file paths inside code fences
-- **`udiff`**: Instructions for unified diff format
+- They are **excluded** from the file listing sent to the LLM (binary content is not useful in the prompt).
+- Their filenames are listed separately at the end of the prompt so the LLM is aware of them (e.g., to reference them in HTML `<img>` tags).
+- The `isImageFile()` utility can be used to check if a filename is an image.
 
-Each instruction set is a string containing detailed formatting guidelines that help ensure the LLM produces properly structured output that can be parsed by the library.
+## File Truncation
 
-## Similar Projects
+When preparing files for the prompt via `prepareFilesForPrompt`, large files are truncated to keep prompts manageable:
+
+- Regular files: truncated to **500 lines**, each line capped at **200 characters**.
+- CSV and JSON files: truncated to **50 lines** (these files tend to be very large).
+- Image files: excluded entirely (see above).
 
-- **Aider**: An AI pair programming tool that integrates with your terminal to assist in code editing within your local git repository. [https://aider.chat/](https://aider.chat/)
+## Benchmarking
 
-- **Bolt.new / Bolt.diy**: A platform that allows users to prompt, run, edit, and deploy full-stack web and mobile applications. [https://bolt.new/](https://bolt.new/)
+The project includes a benchmarking system for evaluating LLM edit quality across different models and edit formats.
 
-- **Cline**: An AI-powered code assistant designed to help developers write and debug code more efficiently. [https://cline.ai/](https://cline.ai/)
+```bash
+# Run benchmarks
+npm run benchmark
 
-- **Cerebras Coder**: A code generation tool developed by Cerebras Systems, leveraging advanced AI models to assist in coding tasks. [https://www.cerebras.net/](https://www.cerebras.net/)
+# Grade results
+npm run grade
+```
 
-- **Pear AI**: An open-source AI code editor that accelerates the development process by integrating features like AI chat, code generation, and debugging assistance. [https://trypear.ai/](https://trypear.ai/)
+Benchmarks live in the `benchmarks/` directory. Results, caches, and challenges are gitignored to keep the repository size small.
 
-- **Void**: An open-source alternative to proprietary AI code editors, offering AI-assisted coding features while prioritizing user privacy and control. [https://void.dev/](https://void.dev/)
+## OpenRouter Cost Tracking
 
-- **Cody**: An advanced AI coding assistant developed by Sourcegraph, integrating seamlessly with popular IDEs to provide features like AI-driven chat, code autocompletion, and inline editing. [https://github.com/sourcegraph/cody](https://github.com/sourcegraph/cody)
+If you provide an `apiKey` (OpenRouter API key) and your `LlmFunction` returns a `generationId` from OpenRouter, the library automatically fetches cost metadata after each edit. The result includes `upstreamCostCents`, `provider`, `inputTokens`, and `outputTokens`.
 
-## Contributing
+The `getGenerationMetadata` utility implements retry logic with up to 10 attempts (1 second delay) to handle the brief delay before OpenRouter makes generation metadata available.
+
+## Similar Projects
 
-To contribute to this project:
+- **[Aider](https://aider.chat/)** — AI pair programming in the terminal with local git repos. The edit formats used in this library were inspired by Aider's search/replace approach.
+- **[Bolt.new / Bolt.diy](https://bolt.new/)** — Prompt, run, edit, and deploy full-stack apps in the browser.
+- **[Cline](https://cline.ai/)** — AI coding assistant for VS Code.
+- **[Cerebras Coder](https://www.cerebras.net/)** — Code generation using Cerebras hardware.
+- **[Pear AI](https://trypear.ai/)** — Open-source AI code editor.
+- **[Void](https://void.dev/)** — Open-source AI coding environment with privacy focus.
+- **[Cody](https://github.com/sourcegraph/cody)** — AI coding assistant by Sourcegraph, available as IDE extensions.
+
+## Contributing
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/editcodewithai.git
-
-# Navigate to project directory
-cd editcodewithai
+git clone https://github.com/vizhub-core/editcodewithai.git
 
 # Install dependencies
+cd editcodewithai
 npm install
 ```
 
-Run tests to ensure everything is working correctly:
+Before submitting a PR, ensure all checks pass:
 
 ```bash
 npm test
-```
-
-Please submit pull requests with clear descriptions of changes and ensure all tests pass. Protocol for wrapping up a PR:
-
-```
-npm test
 npm run typecheck
 npm run prettier
 # Verify the README is up to date
@@ -195,4 +371,4 @@ Please create an issue first before creating a PR to discuss the changes you wan
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+MIT. See the [LICENSE](LICENSE) file for details.

package/dist/applyEngine.d.ts

@@ -0,0 +1,13 @@
+import { VizFiles } from "@vizhub/viz-types";
+import type { ApplyResult, ParsedEdit } from "./types";
+/**
+ * Applies parsed edits on a best-effort basis.
+ *
+ * Each edit is applied independently: an edit that cannot be applied safely is
+ * skipped and reported in `warnings`, and never prevents other edits from being
+ * applied. The input `files` is never mutated.
+ *
+ * This function only throws for programmer error; anticipated model-output
+ * failures are reported as warnings.
+ */
+export declare function applyEditsSafe(files: VizFiles, edits: ParsedEdit[]): ApplyResult;

package/dist/applyEngine.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyEditsSafe = applyEditsSafe;
+const matching_1 = require("./matching");
+/**
+ * Normalizes a filename for comparison: trims, converts Windows separators to
+ * "/", collapses duplicate separators, and strips leading "./" and "/".
+ *
+ * Case is intentionally preserved — case-insensitive matching is not part of
+ * the deterministic behavior and is deferred.
+ */
+function normalizeFileName(name) {
+    return name
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/\/+/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/^\/+/, "");
+}
+function resolveFileId(files, rawName) {
+    const target = normalizeFileName(rawName);
+    const matches = Object.keys(files).filter((id) => normalizeFileName(files[id].name) === target);
+    if (matches.length === 1)
+        return { kind: "found", id: matches[0] };
+    if (matches.length > 1)
+        return { kind: "ambiguous" };
+    return { kind: "none" };
+}
+function anchorOf(edit) {
+    return edit.kind === "diff" ? edit.search : edit.original;
+}
+function replacementOf(edit) {
+    return edit.kind === "diff" ? edit.replace : edit.updated;
+}
+/**
+ * Applies parsed edits on a best-effort basis.
+ *
+ * Each edit is applied independently: an edit that cannot be applied safely is
+ * skipped and reported in `warnings`, and never prevents other edits from being
+ * applied. The input `files` is never mutated.
+ *
+ * This function only throws for programmer error; anticipated model-output
+ * failures are reported as warnings.
+ */
+function applyEditsSafe(files, edits) {
+    const work = JSON.parse(JSON.stringify(files));
+    const warnings = [];
+    for (const edit of edits) {
+        const resolution = resolveFileId(work, edit.fileName);
+        if (resolution.kind === "ambiguous") {
+            warnings.push({
+                code: "AMBIGUOUS_FILE",
+                fileName: edit.fileName,
+                message: `Skipped ${edit.fileName}: multiple files share that name.`,
+            });
+            continue;
+        }
+        if (resolution.kind === "none") {
+            warnings.push({
+                code: "FILE_NOT_FOUND",
+                fileName: edit.fileName,
+                message: `Skipped changes to ${edit.fileName}: file not found.`,
+            });
+            continue;
+        }
+        const anchor = anchorOf(edit);
+        if (anchor.trim() === "") {
+            warnings.push({
+                code: "EMPTY_SEARCH",
+                fileName: edit.fileName,
+                message: `Skipped a change to ${edit.fileName}: the search block was empty.`,
+            });
+            continue;
+        }
+        const file = work[resolution.id];
+        const match = (0, matching_1.findAnchor)(file.text, anchor);
+        if (match === null) {
+            warnings.push({
+                code: edit.kind === "udiff" ? "HUNK_NOT_FOUND" : "SEARCH_NOT_FOUND",
+                fileName: edit.fileName,
+                message: edit.kind === "udiff"
+                    ? `Skipped part of a change to ${edit.fileName}: referenced lines were not found.`
+                    : `Skipped a change to ${edit.fileName}: the referenced code was not found.`,
+            });
+            continue;
+        }
+        // Ambiguous anchors are never guessed: skip rather than replace the first.
+        if (match.matchCount > 1) {
+            warnings.push({
+                code: "AMBIGUOUS_SEARCH",
+                fileName: edit.fileName,
+                message: `Skipped a change to ${edit.fileName}: the referenced code matched ${match.matchCount} locations.`,
+            });
+            continue;
+        }
+        file.text =
+            file.text.slice(0, match.start) +
+                replacementOf(edit) +
+                file.text.slice(match.end);
+    }
+    return { files: work, warnings };
+}

package/dist/fileUtils.d.ts

@@ -1,4 +1,5 @@
 import { VizFiles, VizFile, FileCollection } from "@vizhub/viz-types";
+import type { ApplyResult } from "./types";
 /**
  * If the LLM outputs empty text for a file, we interpret this
  * as a request to delete the file.
@@ -33,4 +34,31 @@ export interface UdiffHunk {
     updated: string;
 }
 export declare function parseUdiffs(responseText: string): UdiffHunk[];
+/**
+ * Hybrid edit mode: parses both whole-file blocks (bold-markdown)
+ * and search/replace diff blocks from the same response.
+ *
+ * Strategy:
+ * 1. Apply all search/replace diffs first.
+ * 2. Then apply whole-file replacements on top.
+ *    (If the same file appears in both forms, the whole-file content wins.)
+ */
+export declare function applyHybridEdits(responseText: string, originalFiles: VizFiles, parseWholeFiles: (text: string) => FileCollection): VizFiles;
+/**
+ * Best-effort variant of `applyDiffs`. Never throws for unmatched files or
+ * anchors; skipped edits are reported in `warnings`.
+ */
+export declare function applyDiffsSafe(originalFiles: VizFiles, diffs: Diff[]): ApplyResult;
+/**
+ * Best-effort variant of `applyUdiffs`. Never throws for unmatched files or
+ * hunks; skipped edits are reported in `warnings`.
+ */
+export declare function applyUdiffsSafe(originalFiles: VizFiles, hunks: UdiffHunk[]): ApplyResult;
+/**
+ * Best-effort variant of `applyHybridEdits`. Applies search/replace diffs first,
+ * then whole-file replacements. Warnings for diffs that target a file which is
+ * also replaced wholesale are suppressed, since the whole-file content
+ * supersedes the failed diff.
+ */
+export declare function applyHybridEditsSafe(responseText: string, originalFiles: VizFiles, parseWholeFiles: (text: string) => FileCollection): ApplyResult;
 export declare function applyUdiffs(originalFiles: VizFiles, hunks: UdiffHunk[]): VizFiles;

package/dist/fileUtils.js

@@ -8,8 +8,13 @@ exports.parseDiffs = parseDiffs;
 exports.applyDiffs = applyDiffs;
 exports.parseDiffFenced = parseDiffFenced;
 exports.parseUdiffs = parseUdiffs;
+exports.applyHybridEdits = applyHybridEdits;
+exports.applyDiffsSafe = applyDiffsSafe;
+exports.applyUdiffsSafe = applyUdiffsSafe;
+exports.applyHybridEditsSafe = applyHybridEditsSafe;
 exports.applyUdiffs = applyUdiffs;
 const viz_utils_1 = require("@vizhub/viz-utils");
+const applyEngine_1 = require("./applyEngine");
 /**
  * If the LLM outputs empty text for a file, we interpret this
  * as a request to delete the file.
@@ -165,6 +170,63 @@ function parseUdiffs(responseText) {
     }
     return hunks;
 }
+/**
+ * Hybrid edit mode: parses both whole-file blocks (bold-markdown)
+ * and search/replace diff blocks from the same response.
+ *
+ * Strategy:
+ * 1. Apply all search/replace diffs first.
+ * 2. Then apply whole-file replacements on top.
+ *    (If the same file appears in both forms, the whole-file content wins.)
+ */
+function applyHybridEdits(responseText, originalFiles, parseWholeFiles) {
+    // Step 1: apply search/replace diffs
+    const diffs = parseDiffs(responseText);
+    let changedFiles = applyDiffs(originalFiles, diffs);
+    // Step 2: parse and apply whole-file replacements on top
+    const parsed = parseWholeFiles(responseText);
+    changedFiles = mergeFileChanges(changedFiles, parsed);
+    return changedFiles;
+}
+/**
+ * Best-effort variant of `applyDiffs`. Never throws for unmatched files or
+ * anchors; skipped edits are reported in `warnings`.
+ */
+function applyDiffsSafe(originalFiles, diffs) {
+    return (0, applyEngine_1.applyEditsSafe)(originalFiles, diffs.map((diff) => ({
+        kind: "diff",
+        fileName: diff.fileName,
+        search: diff.search,
+        replace: diff.replace,
+    })));
+}
+/**
+ * Best-effort variant of `applyUdiffs`. Never throws for unmatched files or
+ * hunks; skipped edits are reported in `warnings`.
+ */
+function applyUdiffsSafe(originalFiles, hunks) {
+    return (0, applyEngine_1.applyEditsSafe)(originalFiles, hunks.map((hunk) => ({
+        kind: "udiff",
+        fileName: hunk.fileName,
+        original: hunk.original,
+        updated: hunk.updated,
+    })));
+}
+/**
+ * Best-effort variant of `applyHybridEdits`. Applies search/replace diffs first,
+ * then whole-file replacements. Warnings for diffs that target a file which is
+ * also replaced wholesale are suppressed, since the whole-file content
+ * supersedes the failed diff.
+ */
+function applyHybridEditsSafe(responseText, originalFiles, parseWholeFiles) {
+    const diffResult = applyDiffsSafe(originalFiles, parseDiffs(responseText));
+    const parsedWholeFiles = parseWholeFiles(responseText);
+    const changedFiles = mergeFileChanges(diffResult.files, parsedWholeFiles);
+    const wholeFileNames = new Set(Object.keys(parsedWholeFiles).map((name) => name.trim()));
+    const warnings = diffResult.warnings.filter((warning) => warning.fileName === undefined ||
+        !wholeFileNames.has(warning.fileName.trim()));
+    return { files: changedFiles, warnings };
+}
 function applyUdiffs(originalFiles, hunks) {
     const changedFiles = JSON.parse(JSON.stringify(originalFiles));
     for (const hunk of hunks) {

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import type { PerformAiEditParams, PerformAiEditResult } from "./types";
 import { PROMPT_TEMPLATE_VERSION, assembleFullPrompt, FORMAT_INSTRUCTIONS } from "./prompt";
 import { getGenerationMetadata } from "./metadata";
-import { prepareFilesForPrompt, mergeFileChanges, parseDiffs, applyDiffs, parseDiffFenced, parseUdiffs, applyUdiffs, isImageFile } from "./fileUtils";
-export type { LlmFunction, PerformAiEditParams, PerformAiEditResult, EditFormat, } from "./types";
-export { FORMAT_INSTRUCTIONS, mergeFileChanges, prepareFilesForPrompt, isImageFile, parseDiffs, applyDiffs, parseDiffFenced, parseUdiffs, applyUdiffs, assembleFullPrompt, getGenerationMetadata, PROMPT_TEMPLATE_VERSION, };
+import { prepareFilesForPrompt, mergeFileChanges, parseDiffs, applyDiffs, applyDiffsSafe, parseDiffFenced, parseUdiffs, applyUdiffs, applyUdiffsSafe, applyHybridEdits, applyHybridEditsSafe, isImageFile } from "./fileUtils";
+export type { LlmFunction, PerformAiEditParams, PerformAiEditResult, EditFormat, ApplyWarning, ApplyWarningCode, ApplyResult, ParsedEdit, } from "./types";
+export { FORMAT_INSTRUCTIONS, mergeFileChanges, prepareFilesForPrompt, isImageFile, parseDiffs, applyDiffs, applyDiffsSafe, parseDiffFenced, parseUdiffs, applyUdiffs, applyUdiffsSafe, applyHybridEdits, applyHybridEditsSafe, assembleFullPrompt, getGenerationMetadata, PROMPT_TEMPLATE_VERSION, };
 /**
  * Core AI logic for:
  * - Building the prompt (including context)

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROMPT_TEMPLATE_VERSION = exports.getGenerationMetadata = exports.assembleFullPrompt = exports.applyUdiffs = exports.parseUdiffs = exports.parseDiffFenced = exports.applyDiffs = exports.parseDiffs = exports.isImageFile = exports.prepareFilesForPrompt = exports.mergeFileChanges = exports.FORMAT_INSTRUCTIONS = void 0;
+exports.PROMPT_TEMPLATE_VERSION = exports.getGenerationMetadata = exports.assembleFullPrompt = exports.applyHybridEditsSafe = exports.applyHybridEdits = exports.applyUdiffsSafe = exports.applyUdiffs = exports.parseUdiffs = exports.parseDiffFenced = exports.applyDiffsSafe = exports.applyDiffs = exports.parseDiffs = exports.isImageFile = exports.prepareFilesForPrompt = exports.mergeFileChanges = exports.FORMAT_INSTRUCTIONS = void 0;
 exports.performAiEdit = performAiEdit;
 const llm_code_format_1 = require("llm-code-format");
 const prompt_1 = require("./prompt");
@@ -14,9 +14,13 @@ Object.defineProperty(exports, "prepareFilesForPrompt", { enumerable: true, get:
 Object.defineProperty(exports, "mergeFileChanges", { enumerable: true, get: function () { return fileUtils_1.mergeFileChanges; } });
 Object.defineProperty(exports, "parseDiffs", { enumerable: true, get: function () { return fileUtils_1.parseDiffs; } });
 Object.defineProperty(exports, "applyDiffs", { enumerable: true, get: function () { return fileUtils_1.applyDiffs; } });
+Object.defineProperty(exports, "applyDiffsSafe", { enumerable: true, get: function () { return fileUtils_1.applyDiffsSafe; } });
 Object.defineProperty(exports, "parseDiffFenced", { enumerable: true, get: function () { return fileUtils_1.parseDiffFenced; } });
 Object.defineProperty(exports, "parseUdiffs", { enumerable: true, get: function () { return fileUtils_1.parseUdiffs; } });
 Object.defineProperty(exports, "applyUdiffs", { enumerable: true, get: function () { return fileUtils_1.applyUdiffs; } });
+Object.defineProperty(exports, "applyUdiffsSafe", { enumerable: true, get: function () { return fileUtils_1.applyUdiffsSafe; } });
+Object.defineProperty(exports, "applyHybridEdits", { enumerable: true, get: function () { return fileUtils_1.applyHybridEdits; } });
+Object.defineProperty(exports, "applyHybridEditsSafe", { enumerable: true, get: function () { return fileUtils_1.applyHybridEditsSafe; } });
 Object.defineProperty(exports, "isImageFile", { enumerable: true, get: function () { return fileUtils_1.isImageFile; } });
 const debug = false;
 /**
@@ -43,31 +47,60 @@ async function performAiEdit({ prompt, files, llmFunction, apiKey, editFormat =
     // 4. We parse the output to figure out which files changed
     const resultString = result.content;
     let changedFiles;
+    const warnings = [];
+    let editsParsed = 0;
     switch (editFormat) {
         case "whole": {
             const parsed = (0, llm_code_format_1.parseMarkdownFiles)(resultString, "bold");
+            editsParsed = Object.keys(parsed.files).length;
             changedFiles = (0, fileUtils_1.mergeFileChanges)(files, parsed.files);
             break;
         }
         case "diff": {
             const diffs = (0, fileUtils_1.parseDiffs)(resultString);
-            changedFiles = (0, fileUtils_1.applyDiffs)(files, diffs);
+            editsParsed = diffs.length;
+            const applied = (0, fileUtils_1.applyDiffsSafe)(files, diffs);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         case "diff-fenced": {
             const diffs = (0, fileUtils_1.parseDiffFenced)(resultString);
-            changedFiles = (0, fileUtils_1.applyDiffs)(files, diffs);
+            editsParsed = diffs.length;
+            const applied = (0, fileUtils_1.applyDiffsSafe)(files, diffs);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         case "udiff": {
             const hunks = (0, fileUtils_1.parseUdiffs)(resultString);
-            changedFiles = (0, fileUtils_1.applyUdiffs)(files, hunks);
+            editsParsed = hunks.length;
+            const applied = (0, fileUtils_1.applyUdiffsSafe)(files, hunks);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
+            break;
+        }
+        case "hybrid": {
+            const diffs = (0, fileUtils_1.parseDiffs)(resultString);
+            const wholeFiles = (0, llm_code_format_1.parseMarkdownFiles)(resultString, "bold").files;
+            editsParsed = diffs.length + Object.keys(wholeFiles).length;
+            const applied = (0, fileUtils_1.applyHybridEditsSafe)(resultString, files, (text) => (0, llm_code_format_1.parseMarkdownFiles)(text, "bold").files);
+            changedFiles = applied.files;
+            warnings.push(...applied.warnings);
             break;
         }
         default:
             // This will catch any unhandled or unknown edit formats.
             throw new Error(`Unknown edit format: ${editFormat}`);
     }
+    // Zero parsed edits is worth surfacing, but only when nothing else was
+    // reported — otherwise it just adds noise on top of real failures.
+    if (editsParsed === 0 && warnings.length === 0) {
+        warnings.push({
+            code: "NO_EDITS_PARSED",
+            message: "The model returned no applicable edits.",
+        });
+    }
     // 6. Retrieve cost metadata for charging the user
     const openRouterGenerationId = result.generationId || "";
     let upstreamCostCents = 0;
@@ -93,5 +126,6 @@ async function performAiEdit({ prompt, files, llmFunction, apiKey, editFormat =
         outputTokens,
         promptTemplateVersion: prompt_1.PROMPT_TEMPLATE_VERSION,
         rawResponse: resultString, // Include the raw response
+        warnings,
     };
 }

package/dist/matching.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Deterministic anchor matching for edit application.
+ *
+ * This module intentionally implements only deterministic strategies. It never
+ * guesses a location via similarity scoring; if a deterministic match cannot be
+ * found, callers skip the edit and report a warning.
+ *
+ * Strategies, in order:
+ *   1. `exact`           — the anchor is a literal substring.
+ *   2. `line-normalized` — both sides split into lines and compared with
+ *                          trailing whitespace removed. This absorbs CRLF vs LF
+ *                          drift, a missing/extra trailing newline, and
+ *                          trailing-whitespace drift.
+ *
+ * Leading indentation drift is deliberately NOT handled (deferred).
+ */
+export type MatchStrategy = "exact" | "line-normalized";
+export interface AnchorMatch {
+    start: number;
+    end: number;
+    strategy: MatchStrategy;
+    /** Number of equally-valid locations found. `> 1` means ambiguous. */
+    matchCount: number;
+}
+/**
+ * Finds `anchor` within `source` using deterministic strategies only.
+ *
+ * Returns `null` when no deterministic match exists. When a match exists,
+ * `matchCount` reports how many equivalent locations were found so callers can
+ * skip ambiguous edits.
+ */
+export declare function findAnchor(source: string, anchor: string): AnchorMatch | null;

package/dist/matching.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Deterministic anchor matching for edit application.
+ *
+ * This module intentionally implements only deterministic strategies. It never
+ * guesses a location via similarity scoring; if a deterministic match cannot be
+ * found, callers skip the edit and report a warning.
+ *
+ * Strategies, in order:
+ *   1. `exact`           — the anchor is a literal substring.
+ *   2. `line-normalized` — both sides split into lines and compared with
+ *                          trailing whitespace removed. This absorbs CRLF vs LF
+ *                          drift, a missing/extra trailing newline, and
+ *                          trailing-whitespace drift.
+ *
+ * Leading indentation drift is deliberately NOT handled (deferred).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAnchor = findAnchor;
+/**
+ * Splits text into lines while retaining each line's character offsets.
+ * A trailing newline produces a final empty line, matching `String.split("\n")`.
+ */
+function splitLinesWithOffsets(text) {
+    const lines = [];
+    if (text.length === 0)
+        return lines;
+    let start = 0;
+    // Loop is bounded: `start` always advances past the newline.
+    for (;;) {
+        const newlineIndex = text.indexOf("\n", start);
+        if (newlineIndex === -1) {
+            lines.push({ text: text.slice(start), start, end: text.length });
+            break;
+        }
+        lines.push({
+            text: text.slice(start, newlineIndex),
+            start,
+            end: newlineIndex,
+        });
+        start = newlineIndex + 1;
+        if (start === text.length) {
+            lines.push({ text: "", start, end: start });
+            break;
+        }
+    }
+    return lines;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count++;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function findLineNormalized(source, anchor) {
+    const sourceLines = splitLinesWithOffsets(source);
+    const anchorLines = splitLinesWithOffsets(anchor);
+    // Trailing/leading blank lines carry no anchoring information.
+    while (anchorLines.length > 0 &&
+        anchorLines[anchorLines.length - 1].text.trim() === "") {
+        anchorLines.pop();
+    }
+    while (anchorLines.length > 0 && anchorLines[0].text.trim() === "") {
+        anchorLines.shift();
+    }
+    if (anchorLines.length === 0)
+        return null;
+    if (anchorLines.length > sourceLines.length)
+        return null;
+    const normalizedAnchor = anchorLines.map((line) => line.text.trimEnd());
+    const normalizedSource = sourceLines.map((line) => line.text.trimEnd());
+    let matchCount = 0;
+    let first = null;
+    for (let i = 0; i + normalizedAnchor.length <= sourceLines.length; i++) {
+        let isMatch = true;
+        for (let j = 0; j < normalizedAnchor.length; j++) {
+            if (normalizedSource[i + j] !== normalizedAnchor[j]) {
+                isMatch = false;
+                break;
+            }
+        }
+        if (isMatch) {
+            matchCount++;
+            if (first === null) {
+                first = {
+                    start: sourceLines[i].start,
+                    end: sourceLines[i + normalizedAnchor.length - 1].end,
+                };
+            }
+        }
+    }
+    if (first === null)
+        return null;
+    return {
+        start: first.start,
+        end: first.end,
+        strategy: "line-normalized",
+        matchCount,
+    };
+}
+/**
+ * Finds `anchor` within `source` using deterministic strategies only.
+ *
+ * Returns `null` when no deterministic match exists. When a match exists,
+ * `matchCount` reports how many equivalent locations were found so callers can
+ * skip ambiguous edits.
+ */
+function findAnchor(source, anchor) {
+    if (anchor.length === 0 || source.length === 0)
+        return null;
+    const exactIndex = source.indexOf(anchor);
+    if (exactIndex !== -1) {
+        return {
+            start: exactIndex,
+            end: exactIndex + anchor.length,
+            strategy: "exact",
+            matchCount: countOccurrences(source, anchor),
+        };
+    }
+    return findLineNormalized(source, anchor);
+}

package/dist/prompt.d.ts

@@ -1,5 +1,5 @@
 import type { EditFormat } from "./types";
-export declare const PROMPT_TEMPLATE_VERSION = 1;
+export declare const PROMPT_TEMPLATE_VERSION = 2;
 export declare const FORMAT_INSTRUCTIONS: Record<EditFormat, string>;
 /**
  * Assembles the full prompt by combining task, files context, and formatting instructions

package/dist/prompt.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FORMAT_INSTRUCTIONS = exports.PROMPT_TEMPLATE_VERSION = void 0;
 exports.assembleFullPrompt = assembleFullPrompt;
 // Versions of the prompt template.
-exports.PROMPT_TEMPLATE_VERSION = 1;
+exports.PROMPT_TEMPLATE_VERSION = 2;
 // Template pieces
 const TASK = (prompt) => `## Your Task\n\n${prompt}`;
 const FILES = (filesContext) => `## Original Files\n\n${filesContext}`;
@@ -32,6 +32,7 @@ exports.FORMAT_INSTRUCTIONS = {
         "// new code\n",
         ">>>>>>> REPLACE\n",
         "```\n",
+        "Use the exact filename listed in the Original Files section. Copy the SEARCH text verbatim, including whitespace and indentation. Do not invent filenames.",
     ].join(""),
     "diff-fenced": [
         "## Formatting Instructions\n\n",
@@ -44,6 +45,7 @@ exports.FORMAT_INSTRUCTIONS = {
         "// new code\n",
         ">>>>>>> REPLACE\n",
         "```\n",
+        "Use the exact filename listed in the Original Files section. Copy the SEARCH text verbatim, including whitespace and indentation. Do not invent filenames.",
     ].join(""),
     udiff: [
         "## Formatting Instructions\n\n",
@@ -55,6 +57,44 @@ exports.FORMAT_INSTRUCTIONS = {
         "-// line to be removed\n",
         "+// line to be added\n",
         "```\n",
+        "Use the exact filename listed in the Original Files section. Copy all context lines verbatim, including whitespace. Do not invent filenames; use the whole-file format when creating a new file.",
+    ].join(""),
+    hybrid: [
+        "## Formatting Instructions\n\n",
+        "Suggest changes to the original files. You may use either of these two",
+        " formats for each file, choosing whichever is more appropriate:\n\n",
+        "**Whole file format** (use for major rewrites, new files, or when many",
+        " parts of a file change):\n\n",
+        "```\n",
+        "**path/to/fileA.js**\n",
+        "```js\n",
+        "// Entire updated code for fileA\n",
+        "```\n",
+        "```\n\n",
+        "**Search/replace diff format** (use for small, targeted changes):\n\n",
+        "```\n",
+        "path/to/fileB.js\n",
+        "```\n",
+        "<<<<<<< SEARCH\n",
+        "// code to be replaced\n",
+        "=======\n",
+        "// new code\n",
+        ">>>>>>> REPLACE\n",
+        "```\n",
+        "```\n\n",
+        "You can mix both formats in the same response, choosing per file.",
+        " For the whole file format, you MUST include the ENTIRE content of",
+        " the updated file. For search/replace, only include the changed",
+        " portions.\n\n",
+        'NEVER leave out sections as in "... rest of the code remain the same',
+        ' ...".\n\n',
+        "Delete all unused files, but we need to keep `README.md`. ",
+        "Files can be deleted by setting their content to empty, for example:\n\n",
+        "```\n",
+        "**fileToDelete.js**\n",
+        "```\n",
+        "```\n",
+        "```\n",
     ].join(""),
 };
 /**

package/dist/types.d.ts

@@ -1,5 +1,42 @@
 import { VizFiles } from "@vizhub/viz-types";
-export type EditFormat = "whole" | "diff" | "diff-fenced" | "udiff";
+export type EditFormat = "whole" | "diff" | "diff-fenced" | "udiff" | "hybrid";
+/**
+ * A parsed edit that can be applied independently to a file.
+ * `diff`/`diff-fenced` edits are search/replace pairs; `udiff` edits are
+ * original/updated blocks.
+ */
+export interface DiffEdit {
+    kind: "diff";
+    fileName: string;
+    search: string;
+    replace: string;
+}
+export interface UdiffEdit {
+    kind: "udiff";
+    fileName: string;
+    original: string;
+    updated: string;
+}
+export type ParsedEdit = DiffEdit | UdiffEdit;
+/**
+ * Reason an edit was skipped. Warnings strictly mean "something went wrong"
+ * or "this edit could not be applied" — successful normalized matches are not
+ * reported here.
+ */
+export type ApplyWarningCode = "FILE_NOT_FOUND" | "SEARCH_NOT_FOUND" | "HUNK_NOT_FOUND" | "AMBIGUOUS_SEARCH" | "AMBIGUOUS_FILE" | "EMPTY_SEARCH" | "NO_EDITS_PARSED";
+export interface ApplyWarning {
+    code: ApplyWarningCode;
+    fileName?: string;
+    message: string;
+}
+/**
+ * Result of best-effort edit application. `files` always contains the changes
+ * that could be applied safely; `warnings` describes everything skipped.
+ */
+export interface ApplyResult {
+    files: VizFiles;
+    warnings: ApplyWarning[];
+}
 export type LlmFunction = (prompt: string) => Promise<{
     content: string;
     generationId?: string;
@@ -20,4 +57,6 @@ export interface PerformAiEditResult {
     outputTokens?: number;
     promptTemplateVersion?: number;
     rawResponse?: string;
+    /** Edits that were skipped because they could not be applied safely. */
+    warnings?: ApplyWarning[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editcodewithai",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Edit Code With AI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",