@neabyte/v4a-diff 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeaByteLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+<div align='center'>
+
+# V4A Diff
+
+Context-anchored diff engine for LLM-powered file editing
+
+[![Deno](https://img.shields.io/badge/deno-compatible-ffcb00?logo=deno&logoColor=000000)](https://deno.com) [![Node](https://img.shields.io/badge/node-%3E%3D24-6DA55F?logo=node.js&logoColor=white)](https://nodejs.org) [![Bun](https://img.shields.io/badge/bun-compatible-f9f1e1?logo=bun&logoColor=000000)](https://bun.sh) [![Browser](https://img.shields.io/badge/browser-compatible-4285F4?logo=googlechrome&logoColor=white)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+
+[![Module type: Deno/ESM](https://img.shields.io/badge/module%20type-deno%2Fesm-brightgreen)](https://github.com/NeaByteLab/V4A-Diff) [![npm version](https://img.shields.io/npm/v/@neabyte/v4a-diff.svg)](https://www.npmjs.org/package/@neabyte/v4a-diff) [![JSR](https://jsr.io/badges/@neabyte/v4a-diff)](https://jsr.io/@neabyte/v4a-diff) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+<img src="./assets/preview.webp" alt="V4A Diff Preview" width="100%">
+
+</div>
+
+## What is V4A?
+
+V4A is a context-anchored diff format designed for LLM tool calling. Instead of line numbers, hunks use `@@` text anchors to locate edits - making diffs resilient to file changes between turns. This package parses V4A diffs, applies them to source text, and returns both the patched result and structured diff metadata with line numbers.
+
+## Features
+
+- **Token efficient** - Returns only changed lines, not the entire file.
+- **Instant rollback** - Original source included in result, no manual tracking.
+- **Structured diff** - Line-by-line add/delete/equal metadata with line numbers.
+- **Smart matching** - Fuzzy context resolution with whitespace and Unicode tolerance.
+
+## Installation
+
+**Deno (JSR):**
+
+```bash
+deno add jsr:@neabyte/v4a-diff
+```
+
+**npm:**
+
+```bash
+npm install @neabyte/v4a-diff
+```
+
+**CDN (jsDelivr/esm.sh):**
+
+```html
+<script type="module">
+  import V4A from 'https://cdn.jsdelivr.net/npm/@neabyte/v4a-diff/dist/index.mjs'
+</script>
+```
+
+Or via [esm.sh](https://esm.sh):
+
+```html
+<script type="module">
+  import V4A from 'https://esm.sh/@neabyte/v4a-diff'
+</script>
+```
+
+## Usage
+
+```ts
+import V4A from '@neabyte/v4a-diff'
+
+// Update an existing file
+const result = V4A.apply(
+  'function add(a, b) {\n  return a - b\n}',
+  '@@\n function add(a, b) {\n-  return a - b\n+  return a + b\n }'
+)
+
+console.log(result.source)
+// function add(a, b) {
+//   return a - b
+// }
+
+console.log(result.text)
+// function add(a, b) {
+//   return a + b
+// }
+
+console.log(result.diff)
+// [
+//   { type: 'equal',  value: 'function add(a, b) {', oldLine: 1, newLine: 1 },
+//   { type: 'delete', value: '  return a - b',       oldLine: 2, newLine: null },
+//   { type: 'add',    value: '  return a + b',       oldLine: null, newLine: 2 },
+//   { type: 'equal',  value: '}',                    oldLine: 3, newLine: 3 }
+// ]
+```
+
+### With `*** Begin Patch` envelope
+
+```ts
+const result = V4A.apply(
+  'const x = 1',
+  '*** Begin Patch\n*** Update File: /src/config.ts\n@@\n-const x = 1\n+const x = 2\n*** End Patch'
+)
+// result.text === 'const x = 2'
+```
+
+### Create a new file
+
+```ts
+const result = V4A.apply(
+  '',
+  '+export const PORT = 8080\n+export const HOST = "localhost"',
+  'create'
+)
+// result.text === 'export const PORT = 8080\nexport const HOST = "localhost"'
+```
+
+### Multi-hunk edits
+
+```ts
+const result = V4A.apply(
+  'function add(a, b) {\n  return a - b\n}\nfunction sub(a, b) {\n  return a + b\n}',
+  '@@ function add(\n function add(a, b) {\n-  return a - b\n+  return a + b\n }\n@@ function sub(\n function sub(a, b) {\n-  return a + b\n+  return a - b\n }'
+)
+```
+
+## API
+
+### `V4A.apply(sourceText, diffText, mode?)`
+
+| Parameter    | Type                    | Description                                                          |
+| ------------ | ----------------------- | -------------------------------------------------------------------- |
+| `sourceText` | `string`                | Original file content                                                |
+| `diffText`   | `string`                | V4A format diff string                                               |
+| `mode`       | `'default' \| 'create'` | `default` updates existing text, `create` builds from `+` lines only |
+
+**Returns:** `ApplyDiffResult`
+
+```ts
+type ApplyDiffResult = {
+  text: string // Patched output text
+  diff: DiffLine[] // Structured line-by-line diff
+  source: string // Original source text for rollback
+}
+
+type DiffLine = {
+  type: 'add' | 'delete' | 'equal'
+  value: string // Line content
+  oldLine: number | null // Source line number (null for adds)
+  newLine: number | null // Result line number (null for deletes)
+}
+```
+
+## V4A Diff Format
+
+```
+*** Begin Patch
+*** Update File: {path}
+@@ {anchor_text}
+ context line (space prefix, exact copy from file)
+-removed line (must match file exactly)
++added line
+*** End Patch
+```
+
+- `@@` followed by text anchors to a matching line in the source file.
+- A bare `@@` alone means "start of file."
+- Every line in a hunk must start with ``(space),`-`, or `+`.
+- `*** Add File:` with `+` prefixed lines creates new files.
+
+## LLM Tool Schemas
+
+Pre-built schemas for tool calling live in [`schema/`](schema/README.md):
+
+- [`schema/openai.json`](schema/openai.json) - OpenAI function calling format
+- [`schema/anthropic.json`](schema/anthropic.json) - Anthropic tool use format
+
+## Build
+
+```bash
+npm run build
+```
+
+## Testing
+
+```bash
+deno task check
+```
+
+```bash
+deno task test
+```
+
+## Acknowledgements
+
+This is a clean-room TypeScript reimplementation of the V4A context-anchored diff format, with additional features including fuzz matching, envelope stripping, and structured diff output.
+
+Based on the V4A format specification and reference implementations by OpenAI:
+
+- [Apply Patch Tool Documentation](https://developers.openai.com/api/docs/guides/tools-apply-patch)
+- [Rust Reference (codex apply-patch)](https://github.com/openai/codex/tree/main/codex-rs/apply-patch)
+- [TypeScript Reference (openai-agents-js)](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/utils/applyDiff.ts)
+
+## License
+
+This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for details.

package/dist/index.cjs

@@ -0,0 +1,7 @@
+"use strict";class f{static anchorStrategies=[{mapFn:e=>e,fuzzScore:0},{mapFn:e=>e.trim(),fuzzScore:1},{mapFn:this.normalizeUnicode.bind(this),fuzzScore:10}];static contextStrategies=[{mapFn:e=>e,fuzzScore:0},{mapFn:e=>e.trimEnd(),fuzzScore:1},{mapFn:e=>e.trim(),fuzzScore:100},{mapFn:this.normalizeUnicode.bind(this),fuzzScore:1e3}];static unicodeMap=new Map([[8208,"-"],[8209,"-"],[8210,"-"],[8211,"-"],[8212,"-"],[8213,"-"],[8722,"-"],[8216,"'"],[8217,"'"],[8218,"'"],[8219,"'"],[8220,'"'],[8221,'"'],[8222,'"'],[8223,'"'],[160," "],[8194," "],[8195," "],[8196," "],[8197," "],[8198," "],[8199," "],[8200," "],[8201," "],[8202," "],[8239," "],[8287," "],[12288," "]]);static findContext(e,t,n,r){if(r){const i=this.findContextCore(e,t,Math.max(0,e.length-t.length));if(i.matchedIndex!==-1)return i;const c=this.findContextCore(e,t,n);return{matchedIndex:c.matchedIndex,fuzzScore:c.fuzzScore+1e4}}return this.findContextCore(e,t,n)}static resolveAnchor(e,t,n,r){for(const i of this.anchorStrategies){const c=i.mapFn(e);let u=!1;for(let a=0;a<n;a+=1)if(i.mapFn(t[a])===c){u=!0;break}if(u)return n;const s=this.searchLines(t,e,n,i.mapFn);if(s!==-1)return r.fuzzScore+=i.fuzzScore,s}return n}static findContextCore(e,t,n){if(!t.length)return{matchedIndex:n,fuzzScore:0};for(const r of this.contextStrategies)for(let i=n;i<e.length;i+=1)if(this.sliceEquals(e,t,i,r.mapFn))return{matchedIndex:i,fuzzScore:r.fuzzScore};return{matchedIndex:-1,fuzzScore:0}}static normalizeUnicode(e){const t=e.trim(),n=[];for(let r=0;r<t.length;r+=1)n.push(this.unicodeMap.get(t.charCodeAt(r))??t[r]);return n.join("")}static searchLines(e,t,n,r){const i=r(t);for(let c=n;c<e.length;c+=1)if(r(e[c])===i)return c;return-1}static sliceEquals(e,t,n,r){if(n+t.length>e.length)return!1;for(let i=0;i<t.length;i+=1)if(r(e[n+i])!==r(t[i]))return!1;return!0}}class p{static endFile="*** End of File";static prefixToMode={"+":"add","-":"delete"," ":"keep"};static terminators=["*** End Patch","*** Update File:","*** Delete File:","*** Add File:"];static normalizeDiffLines(e){const t=e.split(/\r?\n/);return t.at(-1)===""&&t.pop(),t}static parseCreateDiff(e){const t=this.createState(e),n=[];for(;!this.isDone(t,!1);){const r=t.lines[t.currentIndex];if(t.currentIndex+=1,!r.startsWith("+"))throw new SyntaxError(`expected '+' prefix but got "${r}"`);n.push(r.slice(1))}return n.join(`
+`)}static parseUpdateDiff(e,t){const n=this.createState(e),r=t.split(`
+`),i=[];let c=0;for(;!this.isDone(n,!0);){const u=this.consumePrefix(n,"@@ "),s=!u&&n.lines[n.currentIndex]==="@@";if(s&&(n.currentIndex+=1),!u&&!s&&c!==0)throw new SyntaxError(`unexpected line "${n.lines[n.currentIndex]}"`);u?.trim()&&(c=f.resolveAnchor(u,r,c,n));const a=this.readSection(n.lines,n.currentIndex),l=f.findContext(r,a.contextLines,c,a.isEndOfFile);if(l.matchedIndex===-1){const d=a.isEndOfFile?"EOF context":"context";throw new SyntaxError(`unmatched ${d} at cursor ${c} "${a.contextLines.join(`
+`)}"`)}n.fuzzScore+=l.fuzzScore;for(const d of a.diffChunks)i.push({...d,sourceIndex:d.sourceIndex+l.matchedIndex});c=l.matchedIndex+a.contextLines.length,n.currentIndex=a.endIndex}return{diffChunks:i,fuzzScore:n.fuzzScore}}static consumePrefix(e,t){return e.lines[e.currentIndex]?.startsWith(t)?(e.currentIndex+=1,e.lines[e.currentIndex-1].slice(t.length)):""}static createState(e){return{lines:[...e,this.terminators[0]],currentIndex:0,fuzzScore:0}}static isDone(e,t){return e.currentIndex>=e.lines.length||this.isTerminator(e.lines[e.currentIndex],t)}static isSectionBoundary(e){return e.startsWith("@@")||this.isTerminator(e,!0)}static isTerminator(e,t){return this.terminators.some(n=>e.startsWith(n))?!0:t&&e.startsWith(this.endFile)}static readSection(e,t){const n=[];let r=[],i=[];const c=[];let u="keep",s=t;for(;s<e.length;){const a=e[s];if(this.isSectionBoundary(a)||a==="***")break;if(a.startsWith("***"))throw new SyntaxError(`unexpected marker "${a}"`);s+=1;const l=u,d=a||" ",m=this.prefixToMode[d[0]];if(!m)throw new SyntaxError(`unexpected line prefix "${d}"`);u=m;const h=d.slice(1);u==="keep"&&l!==u&&(r.length||i.length)&&(c.push({sourceIndex:n.length-r.length,deletedLines:r,insertedLines:i}),r=[],i=[]),u==="delete"?(r.push(h),n.push(h)):u==="add"?i.push(h):n.push(h)}if((r.length||i.length)&&c.push({sourceIndex:n.length-r.length,deletedLines:r,insertedLines:i}),s<e.length&&e[s]===this.endFile)return{contextLines:n,diffChunks:c,endIndex:s+1,isEndOfFile:!0};if(s===t)throw new SyntaxError(`empty section at index ${s} "${e[s]}"`);return{contextLines:n,diffChunks:c,endIndex:s,isEndOfFile:!1}}}class o{static apply(e,t,n="default"){const r=this.stripLeadingEmpty(this.stripEnvelope(p.normalizeDiffLines(t)));if(n==="create"){const i=p.parseCreateDiff(r),c=i.split(`
+`),u=[];for(let s=0;s<c.length;s+=1)u.push({type:"add",value:c[s],oldLine:null,newLine:s+1});return{text:i,diff:u,source:e}}return this.applyChunks(e,p.parseUpdateDiff(r,e).diffChunks)}static applyChunks(e,t){const n=e.split(`
+`),r=[],i=[];let c=0,u=1;for(const s of t){if(s.sourceIndex>n.length)throw new RangeError(`chunk sourceIndex ${s.sourceIndex} exceeds input length ${n.length}`);if(c>s.sourceIndex)throw new RangeError(`overlapping chunk at ${s.sourceIndex} cursor already at ${c}`);for(let a=c;a<s.sourceIndex;a+=1)r.push(n[a]),i.push({type:"equal",value:n[a],oldLine:a+1,newLine:u}),u+=1;c=s.sourceIndex;for(const a of s.deletedLines)i.push({type:"delete",value:a,oldLine:c+1,newLine:null}),c+=1;for(const a of s.insertedLines)r.push(a),i.push({type:"add",value:a,oldLine:null,newLine:u}),u+=1}for(let s=c;s<n.length;s+=1)r.push(n[s]),i.push({type:"equal",value:n[s],oldLine:s+1,newLine:u}),u+=1;return{text:r.join(`
+`),diff:i,source:e}}static stripEnvelope(e){return e.filter(t=>!(t==="*** Begin Patch"||t==="*** End Patch"||t.startsWith("*** Update File:")||t.startsWith("*** Add File:")||t.startsWith("--- a/")||t.startsWith("+++ b/")||t.startsWith("--- a\\")||t.startsWith("+++ b\\")||t==="\"))}static stripLeadingEmpty(e){let t=0;for(;t<e.length&&e[t]==="";)t+=1;return t>0?e.slice(t):e}}module.exports=o;

package/dist/index.d.cts

@@ -0,0 +1,140 @@
+/** Diff application mode selector */
+type ApplyDiffMode = 'default' | 'create';
+/**
+ * Result from applying a diff.
+ * @description Contains patched text, structured diff, and source.
+ */
+type ApplyDiffResult = {
+    /** Patched output text */
+    text: string;
+    /** Structured line-by-line diff entries */
+    diff: DiffLine[];
+    /** Original source text before patching */
+    source: string;
+};
+/**
+ * Fuzzy context match result.
+ * @description Holds matched line index and fuzz penalty.
+ */
+type ContextMatch = {
+    /** Matched source line index */
+    matchedIndex: number;
+    /** Accumulated fuzz penalty score */
+    fuzzScore: number;
+};
+/**
+ * Single chunk of diff operations.
+ * @description Groups deleted and inserted lines at source position.
+ */
+type DiffChunk = {
+    /** Starting index in source lines */
+    sourceIndex: number;
+    /** Lines removed from source */
+    deletedLines: string[];
+    /** Lines added to output */
+    insertedLines: string[];
+};
+/**
+ * Single line in structured diff.
+ * @description Represents one add, delete, or equal line entry.
+ */
+type DiffLine = {
+    /** Operation type for this line */
+    type: 'add' | 'delete' | 'equal';
+    /** Line content without prefix */
+    value: string;
+    /** Source line number or null */
+    oldLine: number | null;
+    /** Result line number or null */
+    newLine: number | null;
+};
+/**
+ * Fuzzy matching strategy with penalty.
+ * @description Pairs a line transform with fuzz score.
+ */
+type FuzzStrategy = {
+    /** Line transformation function */
+    mapFn: (line: string) => string;
+    /** Penalty score for this strategy */
+    fuzzScore: number;
+};
+/** Hunk line operation mode */
+type HunkLineMode = 'keep' | 'add' | 'delete';
+/**
+ * Parsed update diff result.
+ * @description Contains diff chunks and total fuzz score.
+ */
+type ParsedUpdate = {
+    /** Ordered list of diff chunks */
+    diffChunks: DiffChunk[];
+    /** Total accumulated fuzz score */
+    fuzzScore: number;
+};
+/**
+ * Mutable parser state during processing.
+ * @description Tracks lines, cursor position, and fuzz score.
+ */
+type ParserState = {
+    /** All diff lines being parsed */
+    lines: string[];
+    /** Current cursor position */
+    currentIndex: number;
+    /** Running fuzz penalty total */
+    fuzzScore: number;
+};
+/**
+ * Parsed section with context and chunks.
+ * @description Groups context lines, chunks, and boundary info.
+ */
+type SectionResult = {
+    /** Context lines from source */
+    contextLines: string[];
+    /** Diff chunks in this section */
+    diffChunks: DiffChunk[];
+    /** Line index after section end */
+    endIndex: number;
+    /** True when section ends at EOF */
+    isEndOfFile: boolean;
+};
+
+/**
+ * V4A context-anchored diff applicator.
+ * @description Applies V4A patches and produces structured diff output.
+ */
+declare class V4A {
+    /**
+     * Apply a V4A diff patch.
+     * @description Parses and applies diff to source text.
+     * @param sourceText - Original source file text
+     * @param diffText - V4A format diff string
+     * @param mode - Apply mode: default or create
+     * @returns Result with patched text and diff lines
+     */
+    static apply(sourceText: string, diffText: string, mode?: ApplyDiffMode): ApplyDiffResult;
+    /**
+     * Apply diff chunks to source text.
+     * @description Builds output text and structured diff from chunks.
+     * @param sourceText - Original source file text
+     * @param diffChunks - Parsed diff chunks to apply
+     * @returns Result with patched text and diff lines
+     * @throws RangeError on out-of-bounds or overlapping chunks
+     */
+    private static applyChunks;
+    /**
+     * Strip patch envelope markers from lines.
+     * @description Removes Begin/End Patch, file headers, and git markers.
+     * @param diffLines - Raw diff lines to filter
+     * @returns Lines without envelope markers
+     */
+    private static stripEnvelope;
+    /**
+     * Strip leading empty lines from diff.
+     * @description Skips empty lines at start of array.
+     * @param diffLines - Lines to trim
+     * @returns Lines without leading empties
+     */
+    private static stripLeadingEmpty;
+}
+
+export = V4A;
+export type { ApplyDiffMode, ApplyDiffResult, ContextMatch, DiffChunk, DiffLine, FuzzStrategy, HunkLineMode, ParsedUpdate, ParserState, SectionResult };

package/dist/index.d.mts

@@ -0,0 +1,140 @@
+/** Diff application mode selector */
+type ApplyDiffMode = 'default' | 'create';
+/**
+ * Result from applying a diff.
+ * @description Contains patched text, structured diff, and source.
+ */
+type ApplyDiffResult = {
+    /** Patched output text */
+    text: string;
+    /** Structured line-by-line diff entries */
+    diff: DiffLine[];
+    /** Original source text before patching */
+    source: string;
+};
+/**
+ * Fuzzy context match result.
+ * @description Holds matched line index and fuzz penalty.
+ */
+type ContextMatch = {
+    /** Matched source line index */
+    matchedIndex: number;
+    /** Accumulated fuzz penalty score */
+    fuzzScore: number;
+};
+/**
+ * Single chunk of diff operations.
+ * @description Groups deleted and inserted lines at source position.
+ */
+type DiffChunk = {
+    /** Starting index in source lines */
+    sourceIndex: number;
+    /** Lines removed from source */
+    deletedLines: string[];
+    /** Lines added to output */
+    insertedLines: string[];
+};
+/**
+ * Single line in structured diff.
+ * @description Represents one add, delete, or equal line entry.
+ */
+type DiffLine = {
+    /** Operation type for this line */
+    type: 'add' | 'delete' | 'equal';
+    /** Line content without prefix */
+    value: string;
+    /** Source line number or null */
+    oldLine: number | null;
+    /** Result line number or null */
+    newLine: number | null;
+};
+/**
+ * Fuzzy matching strategy with penalty.
+ * @description Pairs a line transform with fuzz score.
+ */
+type FuzzStrategy = {
+    /** Line transformation function */
+    mapFn: (line: string) => string;
+    /** Penalty score for this strategy */
+    fuzzScore: number;
+};
+/** Hunk line operation mode */
+type HunkLineMode = 'keep' | 'add' | 'delete';
+/**
+ * Parsed update diff result.
+ * @description Contains diff chunks and total fuzz score.
+ */
+type ParsedUpdate = {
+    /** Ordered list of diff chunks */
+    diffChunks: DiffChunk[];
+    /** Total accumulated fuzz score */
+    fuzzScore: number;
+};
+/**
+ * Mutable parser state during processing.
+ * @description Tracks lines, cursor position, and fuzz score.
+ */
+type ParserState = {
+    /** All diff lines being parsed */
+    lines: string[];
+    /** Current cursor position */
+    currentIndex: number;
+    /** Running fuzz penalty total */
+    fuzzScore: number;
+};
+/**
+ * Parsed section with context and chunks.
+ * @description Groups context lines, chunks, and boundary info.
+ */
+type SectionResult = {
+    /** Context lines from source */
+    contextLines: string[];
+    /** Diff chunks in this section */
+    diffChunks: DiffChunk[];
+    /** Line index after section end */
+    endIndex: number;
+    /** True when section ends at EOF */
+    isEndOfFile: boolean;
+};
+
+/**
+ * V4A context-anchored diff applicator.
+ * @description Applies V4A patches and produces structured diff output.
+ */
+declare class V4A {
+    /**
+     * Apply a V4A diff patch.
+     * @description Parses and applies diff to source text.
+     * @param sourceText - Original source file text
+     * @param diffText - V4A format diff string
+     * @param mode - Apply mode: default or create
+     * @returns Result with patched text and diff lines
+     */
+    static apply(sourceText: string, diffText: string, mode?: ApplyDiffMode): ApplyDiffResult;
+    /**
+     * Apply diff chunks to source text.
+     * @description Builds output text and structured diff from chunks.
+     * @param sourceText - Original source file text
+     * @param diffChunks - Parsed diff chunks to apply
+     * @returns Result with patched text and diff lines
+     * @throws RangeError on out-of-bounds or overlapping chunks
+     */
+    private static applyChunks;
+    /**
+     * Strip patch envelope markers from lines.
+     * @description Removes Begin/End Patch, file headers, and git markers.
+     * @param diffLines - Raw diff lines to filter
+     * @returns Lines without envelope markers
+     */
+    private static stripEnvelope;
+    /**
+     * Strip leading empty lines from diff.
+     * @description Skips empty lines at start of array.
+     * @param diffLines - Lines to trim
+     * @returns Lines without leading empties
+     */
+    private static stripLeadingEmpty;
+}
+
+export { V4A as default };
+export type { ApplyDiffMode, ApplyDiffResult, ContextMatch, DiffChunk, DiffLine, FuzzStrategy, HunkLineMode, ParsedUpdate, ParserState, SectionResult };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+/** Diff application mode selector */
+type ApplyDiffMode = 'default' | 'create';
+/**
+ * Result from applying a diff.
+ * @description Contains patched text, structured diff, and source.
+ */
+type ApplyDiffResult = {
+    /** Patched output text */
+    text: string;
+    /** Structured line-by-line diff entries */
+    diff: DiffLine[];
+    /** Original source text before patching */
+    source: string;
+};
+/**
+ * Fuzzy context match result.
+ * @description Holds matched line index and fuzz penalty.
+ */
+type ContextMatch = {
+    /** Matched source line index */
+    matchedIndex: number;
+    /** Accumulated fuzz penalty score */
+    fuzzScore: number;
+};
+/**
+ * Single chunk of diff operations.
+ * @description Groups deleted and inserted lines at source position.
+ */
+type DiffChunk = {
+    /** Starting index in source lines */
+    sourceIndex: number;
+    /** Lines removed from source */
+    deletedLines: string[];
+    /** Lines added to output */
+    insertedLines: string[];
+};
+/**
+ * Single line in structured diff.
+ * @description Represents one add, delete, or equal line entry.
+ */
+type DiffLine = {
+    /** Operation type for this line */
+    type: 'add' | 'delete' | 'equal';
+    /** Line content without prefix */
+    value: string;
+    /** Source line number or null */
+    oldLine: number | null;
+    /** Result line number or null */
+    newLine: number | null;
+};
+/**
+ * Fuzzy matching strategy with penalty.
+ * @description Pairs a line transform with fuzz score.
+ */
+type FuzzStrategy = {
+    /** Line transformation function */
+    mapFn: (line: string) => string;
+    /** Penalty score for this strategy */
+    fuzzScore: number;
+};
+/** Hunk line operation mode */
+type HunkLineMode = 'keep' | 'add' | 'delete';
+/**
+ * Parsed update diff result.
+ * @description Contains diff chunks and total fuzz score.
+ */
+type ParsedUpdate = {
+    /** Ordered list of diff chunks */
+    diffChunks: DiffChunk[];
+    /** Total accumulated fuzz score */
+    fuzzScore: number;
+};
+/**
+ * Mutable parser state during processing.
+ * @description Tracks lines, cursor position, and fuzz score.
+ */
+type ParserState = {
+    /** All diff lines being parsed */
+    lines: string[];
+    /** Current cursor position */
+    currentIndex: number;
+    /** Running fuzz penalty total */
+    fuzzScore: number;
+};
+/**
+ * Parsed section with context and chunks.
+ * @description Groups context lines, chunks, and boundary info.
+ */
+type SectionResult = {
+    /** Context lines from source */
+    contextLines: string[];
+    /** Diff chunks in this section */
+    diffChunks: DiffChunk[];
+    /** Line index after section end */
+    endIndex: number;
+    /** True when section ends at EOF */
+    isEndOfFile: boolean;
+};
+
+/**
+ * V4A context-anchored diff applicator.
+ * @description Applies V4A patches and produces structured diff output.
+ */
+declare class V4A {
+    /**
+     * Apply a V4A diff patch.
+     * @description Parses and applies diff to source text.
+     * @param sourceText - Original source file text
+     * @param diffText - V4A format diff string
+     * @param mode - Apply mode: default or create
+     * @returns Result with patched text and diff lines
+     */
+    static apply(sourceText: string, diffText: string, mode?: ApplyDiffMode): ApplyDiffResult;
+    /**
+     * Apply diff chunks to source text.
+     * @description Builds output text and structured diff from chunks.
+     * @param sourceText - Original source file text
+     * @param diffChunks - Parsed diff chunks to apply
+     * @returns Result with patched text and diff lines
+     * @throws RangeError on out-of-bounds or overlapping chunks
+     */
+    private static applyChunks;
+    /**
+     * Strip patch envelope markers from lines.
+     * @description Removes Begin/End Patch, file headers, and git markers.
+     * @param diffLines - Raw diff lines to filter
+     * @returns Lines without envelope markers
+     */
+    private static stripEnvelope;
+    /**
+     * Strip leading empty lines from diff.
+     * @description Skips empty lines at start of array.
+     * @param diffLines - Lines to trim
+     * @returns Lines without leading empties
+     */
+    private static stripLeadingEmpty;
+}
+
+export = V4A;
+export type { ApplyDiffMode, ApplyDiffResult, ContextMatch, DiffChunk, DiffLine, FuzzStrategy, HunkLineMode, ParsedUpdate, ParserState, SectionResult };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+class x{static anchorStrategies=[{mapFn:e=>e,fuzzScore:0},{mapFn:e=>e.trim(),fuzzScore:1},{mapFn:this.normalizeUnicode.bind(this),fuzzScore:10}];static contextStrategies=[{mapFn:e=>e,fuzzScore:0},{mapFn:e=>e.trimEnd(),fuzzScore:1},{mapFn:e=>e.trim(),fuzzScore:100},{mapFn:this.normalizeUnicode.bind(this),fuzzScore:1e3}];static unicodeMap=new Map([[8208,"-"],[8209,"-"],[8210,"-"],[8211,"-"],[8212,"-"],[8213,"-"],[8722,"-"],[8216,"'"],[8217,"'"],[8218,"'"],[8219,"'"],[8220,'"'],[8221,'"'],[8222,'"'],[8223,'"'],[160," "],[8194," "],[8195," "],[8196," "],[8197," "],[8198," "],[8199," "],[8200," "],[8201," "],[8202," "],[8239," "],[8287," "],[12288," "]]);static findContext(e,t,n,r){if(r){const i=this.findContextCore(e,t,Math.max(0,e.length-t.length));if(i.matchedIndex!==-1)return i;const o=this.findContextCore(e,t,n);return{matchedIndex:o.matchedIndex,fuzzScore:o.fuzzScore+1e4}}return this.findContextCore(e,t,n)}static resolveAnchor(e,t,n,r){for(const i of this.anchorStrategies){const o=i.mapFn(e);let a=!1;for(let c=0;c<n;c+=1)if(i.mapFn(t[c])===o){a=!0;break}if(a)return n;const s=this.searchLines(t,e,n,i.mapFn);if(s!==-1)return r.fuzzScore+=i.fuzzScore,s}return n}static findContextCore(e,t,n){if(!t.length)return{matchedIndex:n,fuzzScore:0};for(const r of this.contextStrategies)for(let i=n;i<e.length;i+=1)if(this.sliceEquals(e,t,i,r.mapFn))return{matchedIndex:i,fuzzScore:r.fuzzScore};return{matchedIndex:-1,fuzzScore:0}}static normalizeUnicode(e){const t=e.trim(),n=[];for(let r=0;r<t.length;r+=1)n.push(this.unicodeMap.get(t.charCodeAt(r))??t[r]);return n.join("")}static searchLines(e,t,n,r){const i=r(t);for(let o=n;o<e.length;o+=1)if(r(e[o])===i)return o;return-1}static sliceEquals(e,t,n,r){if(n+t.length>e.length)return!1;for(let i=0;i<t.length;i+=1)if(r(e[n+i])!==r(t[i]))return!1;return!0}}class h{static endFile="*** End of File";static prefixToMode={"+":"add","-":"delete"," ":"keep"};static terminators=["*** End Patch","*** Update File:","*** Delete File:","*** Add File:"];static normalizeDiffLines(e){const t=e.split(/\r?\n/);return t.at(-1)===""&&t.pop(),t}static parseCreateDiff(e){const t=this.createState(e),n=[];for(;!this.isDone(t,!1);){const r=t.lines[t.currentIndex];if(t.currentIndex+=1,!r.startsWith("+"))throw new SyntaxError(`expected '+' prefix but got "${r}"`);n.push(r.slice(1))}return n.join(`
+`)}static parseUpdateDiff(e,t){const n=this.createState(e),r=t.split(`
+`),i=[];let o=0;for(;!this.isDone(n,!0);){const a=this.consumePrefix(n,"@@ "),s=!a&&n.lines[n.currentIndex]==="@@";if(s&&(n.currentIndex+=1),!a&&!s&&o!==0)throw new SyntaxError(`unexpected line "${n.lines[n.currentIndex]}"`);a?.trim()&&(o=x.resolveAnchor(a,r,o,n));const c=this.readSection(n.lines,n.currentIndex),d=x.findContext(r,c.contextLines,o,c.isEndOfFile);if(d.matchedIndex===-1){const u=c.isEndOfFile?"EOF context":"context";throw new SyntaxError(`unmatched ${u} at cursor ${o} "${c.contextLines.join(`
+`)}"`)}n.fuzzScore+=d.fuzzScore;for(const u of c.diffChunks)i.push({...u,sourceIndex:u.sourceIndex+d.matchedIndex});o=d.matchedIndex+c.contextLines.length,n.currentIndex=c.endIndex}return{diffChunks:i,fuzzScore:n.fuzzScore}}static consumePrefix(e,t){return e.lines[e.currentIndex]?.startsWith(t)?(e.currentIndex+=1,e.lines[e.currentIndex-1].slice(t.length)):""}static createState(e){return{lines:[...e,this.terminators[0]],currentIndex:0,fuzzScore:0}}static isDone(e,t){return e.currentIndex>=e.lines.length||this.isTerminator(e.lines[e.currentIndex],t)}static isSectionBoundary(e){return e.startsWith("@@")||this.isTerminator(e,!0)}static isTerminator(e,t){return this.terminators.some(n=>e.startsWith(n))?!0:t&&e.startsWith(this.endFile)}static readSection(e,t){const n=[];let r=[],i=[];const o=[];let a="keep",s=t;for(;s<e.length;){const c=e[s];if(this.isSectionBoundary(c)||c==="***")break;if(c.startsWith("***"))throw new SyntaxError(`unexpected marker "${c}"`);s+=1;const d=a,u=c||" ",p=this.prefixToMode[u[0]];if(!p)throw new SyntaxError(`unexpected line prefix "${u}"`);a=p;const l=u.slice(1);a==="keep"&&d!==a&&(r.length||i.length)&&(o.push({sourceIndex:n.length-r.length,deletedLines:r,insertedLines:i}),r=[],i=[]),a==="delete"?(r.push(l),n.push(l)):a==="add"?i.push(l):n.push(l)}if((r.length||i.length)&&o.push({sourceIndex:n.length-r.length,deletedLines:r,insertedLines:i}),s<e.length&&e[s]===this.endFile)return{contextLines:n,diffChunks:o,endIndex:s+1,isEndOfFile:!0};if(s===t)throw new SyntaxError(`empty section at index ${s} "${e[s]}"`);return{contextLines:n,diffChunks:o,endIndex:s,isEndOfFile:!1}}}class m{static apply(e,t,n="default"){const r=this.stripLeadingEmpty(this.stripEnvelope(h.normalizeDiffLines(t)));if(n==="create"){const i=h.parseCreateDiff(r),o=i.split(`
+`),a=[];for(let s=0;s<o.length;s+=1)a.push({type:"add",value:o[s],oldLine:null,newLine:s+1});return{text:i,diff:a,source:e}}return this.applyChunks(e,h.parseUpdateDiff(r,e).diffChunks)}static applyChunks(e,t){const n=e.split(`
+`),r=[],i=[];let o=0,a=1;for(const s of t){if(s.sourceIndex>n.length)throw new RangeError(`chunk sourceIndex ${s.sourceIndex} exceeds input length ${n.length}`);if(o>s.sourceIndex)throw new RangeError(`overlapping chunk at ${s.sourceIndex} cursor already at ${o}`);for(let c=o;c<s.sourceIndex;c+=1)r.push(n[c]),i.push({type:"equal",value:n[c],oldLine:c+1,newLine:a}),a+=1;o=s.sourceIndex;for(const c of s.deletedLines)i.push({type:"delete",value:c,oldLine:o+1,newLine:null}),o+=1;for(const c of s.insertedLines)r.push(c),i.push({type:"add",value:c,oldLine:null,newLine:a}),a+=1}for(let s=o;s<n.length;s+=1)r.push(n[s]),i.push({type:"equal",value:n[s],oldLine:s+1,newLine:a}),a+=1;return{text:r.join(`
+`),diff:i,source:e}}static stripEnvelope(e){return e.filter(t=>!(t==="*** Begin Patch"||t==="*** End Patch"||t.startsWith("*** Update File:")||t.startsWith("*** Add File:")||t.startsWith("--- a/")||t.startsWith("+++ b/")||t.startsWith("--- a\\")||t.startsWith("+++ b\\")||t==="\"))}static stripLeadingEmpty(e){let t=0;for(;t<e.length&&e[t]==="";)t+=1;return t>0?e.slice(t):e}}export{m as default};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@neabyte/v4a-diff",
+  "version": "0.1.0",
+  "description": "Apply context-anchored file patches from LLM tool calls",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "unbuild --minify",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "rm -rf dist && npm run build"
+  },
+  "keywords": [
+    "anthropic",
+    "code-editing",
+    "context-anchored-diff",
+    "deno",
+    "diff-engine",
+    "diff-parser",
+    "esm",
+    "fuzz-matching",
+    "jsr",
+    "llm-tools",
+    "npm-package",
+    "openai",
+    "patch-applier",
+    "structured-diff",
+    "text-patching",
+    "tool-calling",
+    "typescript",
+    "unicode-normalization",
+    "v4a-diff",
+    "zero-dependencies"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "unbuild": "^3.6.1"
+  },
+  "author": {
+    "name": "NeaByteLab",
+    "email": "me@neabyte.com",
+    "url": "https://github.com/NeaByteLab"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NeaByteLab/V4A-Diff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NeaByteLab/V4A-Diff/issues"
+  },
+  "homepage": "https://github.com/NeaByteLab/V4A-Diff#readme",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}