gov4a

README

go-v4a

Context-anchored V4A diff engine for LLM-powered file editing — Go library.

V4A hunks use @@ text anchors instead of line numbers, so patches stay resilient when the file changes between turns. This package parses V4A diffs, applies them to source text, and returns the patched result plus structured line metadata.

Pure text-to-text API with no filesystem I/O. Reading, writing, and deleting files is left to the consumer.

Install

go get github.com/b805rohit/go-v4a@latest

Usage

package main

import (
	"fmt"

	gov4a "github.com/b805rohit/go-v4a"
)

func main() {
	result, err := gov4a.Apply(
		"function add(a, b) {\n  return a - b\n}",
		"@@\n function add(a, b) {\n-  return a - b\n+  return a + b\n }",
		gov4a.ModeUpdate,
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Text)
	// function add(a, b) {
	//   return a + b
	// }

	refined := gov4a.Refine(result.Diff)
	_ = refined
}

Modes

Mode	Purpose
ModeUpdate (default)	Apply hunks to existing content
ModeCreate	Build a new file from + lines
ModeDelete	Empty text; structured delete diff from source
ModeMove	Same as update (rename is handled by the caller)

Envelope

result, err := gov4a.Apply(
	"const x = 1",
	"*** Begin Patch\n*** Update File: /src/config.ts\n@@\n-const x = 1\n+const x = 2\n*** End Patch",
	gov4a.ModeUpdate,
)

API

func Apply(sourceText, diffText string, mode Mode) (Result, error)
func Refine(diff []DiffLine) []DiffLine

Result contains Text (patched), Diff (line ops with optional OldLine/NewLine), and Source (original for rollback).

Refine attaches grapheme-level Segments on paired delete/add lines.

V4A format

*** Begin Patch
*** Update File: {path}
@@ {anchor_text}
 context line (space prefix)
-removed line
+added line
*** End Patch

• Bare @@ means start of file.
• Headers also include *** Add File:, *** Delete File:, *** Move to:.

LLM tool schemas: schema/.

Testing

go test ./...

Acknowledgements

Clean-room Go port of the V4A context-anchored diff format.

Based on the V4A format and reference implementations by OpenAI:

• Apply Patch Tool Documentation
• Rust Reference (codex apply-patch)

License

MIT — see LICENSE.

Documentation

Index

• type CharSegment
• type DiffLine
  • func Refine(diffLines []DiffLine) []DiffLine
• type LineType
• type Mode
• type Result
  • func Apply(sourceText, diffText string, mode Mode) (Result, error)

Types

type CharSegment

type CharSegment struct {
	Type  LineType `json:"type"`
	Value string   `json:"value"`
}

CharSegment is an intra-line grapheme run from Refine.

type DiffLine

type DiffLine struct {
	Type     LineType      `json:"type"`
	Value    string        `json:"value"`
	OldLine  *int          `json:"oldLine"`
	NewLine  *int          `json:"newLine"`
	Segments []CharSegment `json:"segments,omitempty"`
}

DiffLine is one line in a structured diff.

func Refine

func Refine(diffLines []DiffLine) []DiffLine

Refine adds grapheme-level segments to paired delete/add lines. Non-changed lines pass through untouched. Nil input returns nil.

type LineType

type LineType string

LineType is the operation type for a structured diff line or segment.

const (
	LineEqual  LineType = "equal"
	LineAdd    LineType = "add"
	LineDelete LineType = "delete"
)

type Mode

type Mode string

Mode selects how Apply interprets the diff text.

const (
	ModeUpdate Mode = "update"
	ModeCreate Mode = "create"
	ModeDelete Mode = "delete"
	ModeMove   Mode = "move"
)

type Result

type Result struct {
	// Text is the patched output.
	Text string
	// Diff is the structured line-by-line diff.
	Diff []DiffLine
	// Source is the original input for rollback.
	Source string
}

Result is returned by Apply.

func Apply

func Apply(sourceText, diffText string, mode Mode) (Result, error)

Apply applies a V4A context-anchored diff to sourceText. Pure text-to-text: no filesystem I/O.