editcodewithai 1.0.0 → 2.0.0

package/README.md

@@ -2,12 +2,16 @@
 
 A lightweight, flexible library for AI-powered code editing.
 
+See also [vizhub-benchmarks](https://github.com/vizhub-core/vizhub-benchmarks).
+
 ## Overview
 
 `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.
 
+Edit formats inspired by [Aider](https://aider.chat/). See [Aider: Edit Formats](https://aider.chat/docs/more/edit-formats.html) for details.
+
 ## Installation
 
 ```bash
@@ -16,93 +20,79 @@ npm install editcodewithai
 
 ## Usage
 
+Here's a basic example of how to use `performAiEdit` to update a file:
+
 ```typescript
-import { performAiEdit } from "editcodewithai";
+import { performAiEdit, LlmFunction } from "editcodewithai";
 import { VizFiles } from "@vizhub/viz-types";
 
-// Define your LLM function that will process the prompt
-const myLlmFunction = async (prompt: string) => {
-  // Call your preferred LLM API here
-  // This example assumes using OpenRouter
-  const response = await fetch(
-    "https://openrouter.ai/api/v1/chat/completions",
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        model: "openai/gpt-4",
-        messages: [{ role: "user", content: prompt }],
-      }),
-    },
-  );
-
-  const data = await response.json();
+// Your function to call the LLM
+const myLlmFunction: LlmFunction = async (prompt: string) => {
+  // ... call your LLM API with the prompt
+  const llmResponse = "...";
   return {
-    content: data.choices[0].message.content,
-    generationId: data.id,
+    content: llmResponse, // The raw string response from the LLM
+    generationId: "some-generation-id", // Optional, for cost tracking with OpenRouter
   };
 };
 
-// Your files
 const files: VizFiles = {
   file1: {
     name: "index.js",
-    text: "console.log('Hello world');",
+    text: 'console.log("Hello, World!");',
   },
 };
 
-// Perform the AI edit
-const result = await performAiEdit({
-  prompt: "Update the code to use async/await",
-  files: files,
-  llmFunction: myLlmFunction,
-  apiKey: "your-openrouter-api-key",
-});
+const prompt = 'Change the greeting to "Hello, Universe!"';
 
-console.log(result.changedFiles);
-```
+async function main() {
+  const result = await performAiEdit({
+    prompt,
+    files,
+    llmFunction: myLlmFunction,
+    editFormat: "diff", // Specify the desired edit format
+  });
 
-## API Reference
+  console.log(result.changedFiles["file1"].text);
+  // Expected output: console.log("Hello, Universe!");
+}
 
-### performAiEdit(params)
+main();
+```
 
-The main function that processes files with an AI model and returns edited code.
+## Edit Formats
 
-#### Parameters
+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`.
 
-| Parameter     | Type          | Description                                                       |
-| ------------- | ------------- | ----------------------------------------------------------------- |
-| `prompt`      | `string`      | Instructions for the AI on how to modify the code                 |
-| `files`       | `VizFiles`    | Object containing file information (see below)                    |
-| `llmFunction` | `LlmFunction` | Function that sends the prompt to an LLM and returns the response |
-| `apiKey`      | `string`      | OpenRouter API key for retrieving cost metadata                   |
+### `whole` (default)
 
-The `VizFiles` type is a map of file IDs to file objects, where each file object has:
+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.
 
-- `name`: The filename (e.g., "index.js")
-- `text`: The file contents as a string
+**Example:**
 
-The `LlmFunction` type is a function that takes a prompt string and returns a Promise with:
+````
+index.js
+```js
+console.log("Hello, Universe!");
+```
+````
 
-- `content`: The LLM's response text
-- `generationId`: A unique ID for the generation (used for cost tracking)
+### `diff`
 
-#### Return Value
+The LLM returns a series of search-and-replace blocks. This is efficient as it only includes the changed portions of the files.
 
-The function returns an object with:
+**Example:**
 
-| Property                 | Type       | Description                                |
-| ------------------------ | ---------- | ------------------------------------------ |
-| `changedFiles`           | `VizFiles` | Updated files with AI modifications        |
-| `openRouterGenerationId` | `string`   | ID of the generation from the LLM provider |
-| `upstreamCostCents`      | `number`   | Cost of the API call in cents              |
-| `provider`               | `string`   | The AI provider used (e.g., "openai")      |
-| `inputTokens`            | `number`   | Number of input tokens used                |
-| `outputTokens`           | `number`   | Number of output tokens generated          |
-| `promptTemplateVersion`  | `number`   | Version of the prompt template used        |
+````
+index.js
+```
+<<<<<<< SEARCH
+console.log("Hello, World!");
+=======
+console.log("Hello, Universe!");
+>>>>>>> REPLACE
+```
+````
 
 ### File Operations
 

package/dist/fileUtils.d.ts

@@ -12,3 +12,18 @@ export declare function prepareFilesForPrompt(files: VizFiles): FileCollection;
  * Merges original files with changes from the LLM
  */
 export declare function mergeFileChanges(originalFiles: VizFiles, parsedFiles: FileCollection): VizFiles;
+export interface Diff {
+    fileName: string;
+    search: string;
+    replace: string;
+}
+export declare function parseDiffs(responseText: string): Diff[];
+export declare function applyDiffs(originalFiles: VizFiles, diffs: Diff[]): VizFiles;
+export declare function parseDiffFenced(responseText: string): Diff[];
+export interface UdiffHunk {
+    fileName: string;
+    original: string;
+    updated: string;
+}
+export declare function parseUdiffs(responseText: string): UdiffHunk[];
+export declare function applyUdiffs(originalFiles: VizFiles, hunks: UdiffHunk[]): VizFiles;

package/dist/fileUtils.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.shouldDeleteFile = shouldDeleteFile;
 exports.prepareFilesForPrompt = prepareFilesForPrompt;
 exports.mergeFileChanges = mergeFileChanges;
+exports.parseDiffs = parseDiffs;
+exports.applyDiffs = applyDiffs;
+exports.parseDiffFenced = parseDiffFenced;
+exports.parseUdiffs = parseUdiffs;
+exports.applyUdiffs = applyUdiffs;
 const viz_utils_1 = require("@vizhub/viz-utils");
 /**
  * If the LLM outputs empty text for a file, we interpret this
@@ -64,3 +69,100 @@ function mergeFileChanges(originalFiles, parsedFiles) {
     });
     return changedFiles;
 }
+function parseDiffs(responseText) {
+    const diffs = [];
+    // This regex captures the file path, and the content of the SEARCH and REPLACE blocks.
+    const diffRegex = /^(.+)\n```\n<<<<<<< SEARCH\n([\s\S]*?)\n=======\n([\s\S]*?)\n>>>>>>> REPLACE\n```/gm;
+    const matches = responseText.matchAll(diffRegex);
+    for (const match of matches) {
+        const [_, fileName, search, replace] = match;
+        diffs.push({
+            fileName: fileName.trim(),
+            search,
+            replace,
+        });
+    }
+    return diffs;
+}
+function applyDiffs(originalFiles, diffs) {
+    // Create a mutable copy of the files to avoid side effects.
+    const changedFiles = JSON.parse(JSON.stringify(originalFiles));
+    for (const diff of diffs) {
+        const fileId = Object.keys(changedFiles).find((id) => changedFiles[id].name === diff.fileName);
+        if (!fileId) {
+            throw new Error(`File not found: ${diff.fileName}`);
+        }
+        const file = changedFiles[fileId];
+        if (!file.text.includes(diff.search)) {
+            throw new Error(`Search block not found in file: ${diff.fileName}`);
+        }
+        // Replace only the first occurrence, which is the standard behavior of string.replace.
+        file.text = file.text.replace(diff.search, diff.replace);
+    }
+    return changedFiles;
+}
+function parseDiffFenced(responseText) {
+    const diffs = [];
+    const diffRegex = /^```\n(.+)\n<<<<<<< SEARCH\n([\s\S]*?)\n=======\n([\s\S]*?)\n>>>>>>> REPLACE\n```/gm;
+    const matches = responseText.matchAll(diffRegex);
+    for (const match of matches) {
+        const [_, fileName, search, replace] = match;
+        diffs.push({
+            fileName: fileName.trim(),
+            search,
+            replace,
+        });
+    }
+    return diffs;
+}
+function parseUdiffs(responseText) {
+    const hunks = [];
+    const udiffFileRegex = /```diff\n--- (.+?)\n\+\+\+ \1\n([\s\S]+?)```/g;
+    let fileMatch;
+    while ((fileMatch = udiffFileRegex.exec(responseText)) !== null) {
+        const fileName = fileMatch[1].trim();
+        const allHunksContent = fileMatch[2];
+        const hunkParts = allHunksContent.split(/^@@ .* @@$/m).slice(1);
+        for (const part of hunkParts) {
+            if (part.trim() === "")
+                continue;
+            const lines = part.trim().split("\n");
+            const original = [];
+            const updated = [];
+            for (const line of lines) {
+                if (line.startsWith("+")) {
+                    updated.push(line.substring(1));
+                }
+                else if (line.startsWith("-")) {
+                    original.push(line.substring(1));
+                }
+                else {
+                    const content = line.startsWith(" ") ? line.substring(1) : line;
+                    original.push(content);
+                    updated.push(content);
+                }
+            }
+            hunks.push({
+                fileName: fileName,
+                original: original.join("\n"),
+                updated: updated.join("\n"),
+            });
+        }
+    }
+    return hunks;
+}
+function applyUdiffs(originalFiles, hunks) {
+    const changedFiles = JSON.parse(JSON.stringify(originalFiles));
+    for (const hunk of hunks) {
+        const fileId = Object.keys(changedFiles).find((id) => changedFiles[id].name === hunk.fileName);
+        if (!fileId) {
+            throw new Error(`File not found: ${hunk.fileName}`);
+        }
+        const file = changedFiles[fileId];
+        if (!file.text.includes(hunk.original)) {
+            throw new Error(`Original content for hunk not found in file: ${hunk.fileName}`);
+        }
+        file.text = file.text.replace(hunk.original, hunk.updated);
+    }
+    return changedFiles;
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { PerformAiEditParams, PerformAiEditResult } from "./types";
+import type { PerformAiEditParams, PerformAiEditResult } from "./types";
+export type { LlmFunction, PerformAiEditParams, PerformAiEditResult, EditFormat, } from "./types";
 /**
  * Core AI logic for:
  * - Building the prompt (including context)
@@ -6,4 +7,4 @@ import { PerformAiEditParams, PerformAiEditResult } from "./types";
  * - Parsing and merging file changes
  * - Retrieving cost metadata
  */
-export declare function performAiEdit({ prompt, files, llmFunction, apiKey, }: PerformAiEditParams): Promise<PerformAiEditResult>;
+export declare function performAiEdit({ prompt, files, llmFunction, apiKey, editFormat, }: PerformAiEditParams): Promise<PerformAiEditResult>;

package/dist/index.js

@@ -13,20 +13,43 @@ const debug = false;
  * - Parsing and merging file changes
  * - Retrieving cost metadata
  */
-async function performAiEdit({ prompt, files, llmFunction, apiKey, }) {
+async function performAiEdit({ prompt, files, llmFunction, apiKey, editFormat = "whole", }) {
     // 1. Format the existing files into the "markdown code block" format
     const preparedFiles = (0, fileUtils_1.prepareFilesForPrompt)(files);
     const filesContext = (0, llm_code_format_1.formatMarkdownFiles)(preparedFiles);
     // 2. Assemble the final prompt
-    const fullPrompt = (0, prompt_1.assembleFullPrompt)({ filesContext, prompt });
+    const fullPrompt = (0, prompt_1.assembleFullPrompt)({ filesContext, prompt, editFormat });
     debug && console.log("[performAiEdit] fullPrompt:", fullPrompt);
     // 3. Invoke the model via the provided LLM function
     const result = await llmFunction(fullPrompt);
     // 4. We parse the output to figure out which files changed
     const resultString = result.content;
-    const parsed = (0, llm_code_format_1.parseMarkdownFiles)(resultString, "bold");
-    // 5. Merge the changes into a new `Files` object
-    const changedFiles = (0, fileUtils_1.mergeFileChanges)(files, parsed.files);
+    let changedFiles;
+    switch (editFormat) {
+        case "whole": {
+            const parsed = (0, llm_code_format_1.parseMarkdownFiles)(resultString, "bold");
+            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);
+            break;
+        }
+        case "diff-fenced": {
+            const diffs = (0, fileUtils_1.parseDiffFenced)(resultString);
+            changedFiles = (0, fileUtils_1.applyDiffs)(files, diffs);
+            break;
+        }
+        case "udiff": {
+            const hunks = (0, fileUtils_1.parseUdiffs)(resultString);
+            changedFiles = (0, fileUtils_1.applyUdiffs)(files, hunks);
+            break;
+        }
+        default:
+            // This will catch any unhandled or unknown edit formats.
+            throw new Error(`Unknown edit format: ${editFormat}`);
+    }
     // 6. Retrieve cost metadata for charging the user
     const openRouterGenerationId = result.generationId || "";
     let upstreamCostCents = 0;

package/dist/prompt.d.ts

@@ -1,8 +1,10 @@
+import type { EditFormat } from "./types";
 export declare const PROMPT_TEMPLATE_VERSION = 1;
 /**
  * Assembles the full prompt by combining task, files context, and formatting instructions
  */
-export declare function assembleFullPrompt({ filesContext, prompt, }: {
+export declare function assembleFullPrompt({ filesContext, prompt, editFormat, }: {
     filesContext: string;
     prompt: string;
+    editFormat?: EditFormat;
 }): string;

package/dist/prompt.js

@@ -7,25 +7,63 @@ exports.PROMPT_TEMPLATE_VERSION = 1;
 // Template pieces
 const TASK = (prompt) => `## Your Task\n\n${prompt}`;
 const FILES = (filesContext) => `## Original Files\n\n${filesContext}`;
-const FORMAT = [
-    "## Formatting Instructions\n\n",
-    "Suggest changes to the original files using this exact format:\n\n",
-    "**fileA.js**\n\n```js\n// Entire updated code for fileA\n```\n\n",
-    "**fileB.js**\n\n```js\n// Entire updated code for fileB\n```\n\n",
-    "Only include the files that need to be updated or created.\n\n",
-    "To suggest changes you MUST include the ENTIRE content of the updated file.\n\n",
-    'NEVER leave out sections as in "... rest of the code remain the same ...".\n\n',
-    "Refactor large files into smaller files in the same directory.\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",
-    "**fileToDelete.js**\n\n```\n```\n\n",
-    "For D3 logic, make sure it remains idempotent (use data joins), ",
-    "and prefer function signatures like `someFunction(selection, options)` ",
-    "where `selection` is a D3 selection and `options` is an object.\n\n",
-].join("");
+const FORMAT_INSTRUCTIONS = {
+    whole: [
+        "## Formatting Instructions\n\n",
+        "Suggest changes to the original files using this exact format:\n\n",
+        "**fileA.js**\n\n```js\n// Entire updated code for fileA\n```\n\n",
+        "**fileB.js**\n\n```js\n// Entire updated code for fileB\n```\n\n",
+        "Only include the files that need to be updated or created.\n\n",
+        "To suggest changes you MUST include the ENTIRE content of the updated file.\n\n",
+        'NEVER leave out sections as in "... rest of the code remain the same ...".\n\n',
+        "Refactor large files into smaller files in the same directory.\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",
+        "**fileToDelete.js**\n\n```\n```\n\n",
+        "For D3 logic, make sure it remains idempotent (use data joins), ",
+        "and prefer function signatures like `someFunction(selection, options)` ",
+        "where `selection` is a D3 selection and `options` is an object.\n\n",
+    ].join(""),
+    diff: [
+        "## Formatting Instructions\n\n",
+        "Suggest changes to the original files using this search/replace block format:\n\n",
+        "path/to/filename.ext\n",
+        "```\n",
+        "<<<<<<< SEARCH\n",
+        "// code to be replaced\n",
+        "=======\n",
+        "// new code\n",
+        ">>>>>>> REPLACE\n",
+        "```\n",
+    ].join(""),
+    "diff-fenced": [
+        "## Formatting Instructions\n\n",
+        "Suggest changes to the original files using this search/replace block format with the file path inside the fence:\n\n",
+        "```\n",
+        "path/to/filename.ext\n",
+        "<<<<<<< SEARCH\n",
+        "// code to be replaced\n",
+        "=======\n",
+        "// new code\n",
+        ">>>>>>> REPLACE\n",
+        "```\n",
+    ].join(""),
+    udiff: [
+        "## Formatting Instructions\n\n",
+        "Suggest changes to the original files using the unified diff format:\n\n",
+        "```diff\n",
+        "--- path/to/filename.ext\n",
+        "+++ path/to/filename.ext\n",
+        "@@ ... @@\n",
+        "-// line to be removed\n",
+        "+// line to be added\n",
+        "```\n",
+    ].join(""),
+};
 /**
  * Assembles the full prompt by combining task, files context, and formatting instructions
  */
-function assembleFullPrompt({ filesContext, prompt, }) {
+function assembleFullPrompt({ filesContext, prompt, editFormat = "whole", }) {
+    const FORMAT = FORMAT_INSTRUCTIONS[editFormat];
     return [TASK(prompt), FILES(filesContext), FORMAT].join("\n\n");
 }

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { VizFiles } from "@vizhub/viz-types";
+export type EditFormat = "whole" | "diff" | "diff-fenced" | "udiff";
 export type LlmFunction = (prompt: string) => Promise<{
     content: string;
     generationId?: string;
@@ -8,7 +9,7 @@ export interface PerformAiEditParams {
     files: VizFiles;
     llmFunction: LlmFunction;
     apiKey?: string;
-    baseURL?: string;
+    editFormat?: EditFormat;
 }
 export interface PerformAiEditResult {
     changedFiles: VizFiles;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editcodewithai",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Edit Code With AI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,7 @@
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
-    "benchmark": "ts-node src/benchmarks/cli.ts run; cp -r ./benchmarks grader-app/public",
+    "benchmark": "vite-node src/benchmarks/cli.ts run; cp -r ./benchmarks grader-app/public",
     "grade": "ts-node src/benchmarks/cli.ts grade",
     "benchmark:help": "ts-node src/benchmarks/cli.ts help",
     "upgrade": "ncu -u",
@@ -40,24 +40,22 @@
   },
   "homepage": "https://github.com/vizhub-core/editcodewithai#readme",
   "dependencies": {
-    "@langchain/core": "^0.3.43",
-    "@langchain/openai": "^0.5.4",
-    "@types/d3": "^7.4.3",
     "@vizhub/viz-types": "^0.1.0",
-    "@vizhub/viz-utils": "^0.1.0",
-    "d3": "^7.9.0",
-    "dotenv": "^16.4.7",
-    "langchain": "^0.3.20",
+    "@vizhub/viz-utils": "^1.1.0",
+    "dotenv": "^17.0.1",
     "llm-code-format": "^2.0.1"
   },
   "devDependencies": {
+    "@langchain/core": "^0.3.61",
+    "@langchain/openai": "^0.5.16",
+    "langchain": "^0.3.29",
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "npm-check-updates": "^17.1.16",
-    "prettier": "^3.5.3",
-    "puppeteer": "^24.6.0",
+    "npm-check-updates": "^18.0.1",
+    "prettier": "^3.6.2",
+    "puppeteer": "^24.11.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.1"
+    "vitest": "^3.2.4"
   }
 }