bage

func (*Editor) Apply ¶

func (e *Editor) Apply(ctx context.Context, edits []Edit, anchors []FileAnchor) ([]EditResult, error)

Apply is the standalone convenience for a one-shot edit: it Prepares the edits and, on success, immediately Commits the resulting Plan, returning the EditResults. Integrated callers that interleave the FILE leg with a graph leg use Prepare/Commit directly so the coordinator controls the commit point.

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/hylla-io/bage/internal/hashing"
	"github.com/hylla-io/bage/internal/region"
	"github.com/hylla-io/bage/pkg/bage"
)

func main() {
	dir, err := os.MkdirTemp("", "bage-example-*")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(dir)

	src := "package main\n\nvar Greeting = \"hi\"\n"
	file := filepath.Join(dir, "greeting.go")
	if err := os.WriteFile(file, []byte(src), 0o644); err != nil {
		panic(err)
	}

	ed, err := bage.Open(bage.Config{
		Lang:   bage.LangGo,
		WALDir: dir,
	})
	if err != nil {
		panic(err)
	}
	defer ed.Close()

	// Anchor the edit to the byte range covering "hi" with its region_hash, so
	// the resolver verifies the targeted content before applying "hello".
	start := len("package main\n\nvar Greeting = \"")
	end := start + len("hi")
	live := []byte(src)
	hasher := hashing.XXHasher{}

	edit := bage.Edit{
		Region: bage.Region{
			Path:       file,
			StartByte:  start,
			EndByte:    end,
			RegionHash: region.HashRegion(live, start, end),
		},
		NewText: "hello",
	}
	anchor := bage.FileAnchor{
		Path:     file,
		RawHash:  hashing.RawHash(hasher, live),
		NormHash: hashing.NormHash(hasher, live),
	}

	results, err := ed.Apply(context.Background(), []bage.Edit{edit}, []bage.FileAnchor{anchor})
	if err != nil {
		panic(err)
	}

	out, err := os.ReadFile(file)
	if err != nil {
		panic(err)
	}
	fmt.Printf("changed [%d:%d] new lines %d-%d\n", results[0].ChangedStart, results[0].ChangedEnd, results[0].NewStartLine, results[0].NewEndLine)
	fmt.Print(string(out))
}

Output:
changed [30:35] new lines 3-3
package main

var Greeting = "hello"

func (*Editor) ApplyBatch ¶ added in v0.2.0

func (e *Editor) ApplyBatch(ctx context.Context, ops []Op) ([]BatchResult, error)

ApplyBatch applies a heterogeneous []Op (Edit + Create + Delete + Move) as ONE all-or-nothing change a host maps to ONE graph mutation, returning one BatchResult per op in input order. If ANY op fails its anchor (region_hash/ raw_hash drift, clobber, parse/lint floor) or fails to apply, the ENTIRE batch is rejected and the filesystem is left EXACTLY as before — no op half-applied; a crash mid-commit converges via Recover to fully-before or fully-after. An empty batch is a hard reject. It delegates to the session batch leg.

func (*Editor) Close ¶

func (e *Editor) Close() error

Close releases the Editor's resources. The parser and session hold no long-lived handles between edits (the LSP client is per-Rename), so Close is currently a no-op kept for forward-compatible lifecycle management.

func (*Editor) Commit ¶

func (e *Editor) Commit(plan *Plan) ([]EditResult, error)

Commit is the atomic, lossless point: per file, under that file's lock, it re-reads the live bytes and re-resolves every edit (resolve-under-lock, so a benign concurrent shift lands at the current offset and a same-region conflict is rejected), atomic-writes, and returns one EditResult per edit. A *ConflictError aborts the commit, leaving the source untouched and the WAL intact for Recover; full success clears the WAL.

func (*Editor) Create ¶ added in v0.2.0

func (e *Editor) Create(ctx context.Context, op Op) (EditResult, error)

Create brings a new file into being from op (op.Kind must be OpCreate), returning a whole-file EditResult a host can ingest. The path's anchor is NON-EXISTENCE: an existing path HARD-REJECTS with ErrExists (matchable via errors.Is) and is never clobbered. The staged op.Content clears the same format/lint/parse floor edits clear, and the create is WAL-logged so a crash unlinks the half-created file. It delegates to the session create leg.

func (*Editor) Delete ¶ added in v0.2.0

func (e *Editor) Delete(ctx context.Context, op Op) (DeleteResult, error)

Delete unlinks the file named by op (op.Kind must be OpDelete), returning a DeleteResult a host can ingest to close that file's node versions. Its anchor is the expected raw_hash drift gate: the live bytes must still hash to op.ExpectedRawHash or the delete HARD-REJECTS with a *ConflictError (matchable via errors.Is(err, ErrConflict)) and never discards bytes the caller did not see; a missing path rejects with ErrNotFound. The full prior bytes are WAL-captured before the unlink so a crash can restore them. It delegates to the session delete leg.

func (*Editor) Move ¶ added in v0.2.0

func (e *Editor) Move(ctx context.Context, op Op) (MoveResult, error)

Move relocates op.Path to op.To (op.Kind must be OpMove), preserving the source bytes unchanged, and returns a MoveResult a host can ingest. It composes the delete and create anchors: the SOURCE is gated by op.ExpectedRawHash (drift HARD-REJECTS with a *ConflictError; a missing source rejects with ErrNotFound) and the DESTINATION by non-existence (an existing op.To HARD-REJECTS with ErrExists, no clobber). It is RELOCATE-ONLY (no LSP import-fixup) and delegates to the session move leg.

func (*Editor) Parser ¶

func (e *Editor) Parser() ParserPort

Parser returns the Editor's shared ParserPort so Hylla can reuse the exact parser Båge edits with, keeping graph ingest and file edits structurally consistent.

func (*Editor) Prepare ¶

func (e *Editor) Prepare(ctx context.Context, edits []Edit, anchors []FileAnchor) (*Plan, error)

Prepare optimistically stages every region-anchored edit against the live files, drift-checks via the per-region region_hash (rejecting a Conflict or Ambiguous as a *ConflictError, matchable via errors.Is(err, ErrConflict)), runs the optional Formatter/Linter, reparses to prove the result is valid, and durably records a WAL intent. It returns a Plan whose staged bytes are not yet on disk — Prepare's sole on-disk effect is the WAL record. anchors carries the per-file drift gate (SPEC §8.1) for each file the edits touch.

func (*Editor) Read ¶ added in v0.3.0

func (e *Editor) Read(ctx context.Context, path string, opts ReadOptions) (ReadResult, error)

Read opens path with the shared parser, lists its Blocks, and returns a ReadResult carrying the path, detected language, and the whole-file raw and normalized hashes computed with the Editor's hasher.

Addressing mode is chosen from opts, and the three modes are mutually exclusive: line mode (opts.Line >= 1, optionally bounded by EndLine > Line), byte mode (opts.EndByte > opts.StartByte), and whole-file/symbol mode when neither line nor byte addressing is active. Because lines are 1-based, Line 0 means "unset"; a byte range is active only when EndByte > StartByte, so the zero-value ReadOptions{} stays whole-file. Setting opts.Symbol together with a line or byte range is rejected with an error.

In line or byte mode Read returns exactly one Block: a synthetic Kind:"range" Symbol over the range ResolveRange resolves, anchored by region.HashRegion over that range; its Content is the range's raw bytes when opts.IncludeContent is set (bounds-guarded). Otherwise, when opts.IncludeContent is set each Block's Content is populated; when opts.Symbol is non-empty the Blocks are filtered to those whose Name matches exactly. It reuses OpenFile, ReadBlocks, ResolveRange, and the Editor's hasher; the opened file is closed before Read returns.

func (*Editor) Recover ¶

func (e *Editor) Recover(ctx context.Context) error

Recover is the crash path: it replays any WAL intent left in the Editor's WALDir, restoring affected files to their pre-Prepare state, then clears the WAL. A clean Commit leaves nothing to replay, so Recover is then a no-op.

func (*Editor) Rename ¶

func (e *Editor) Rename(ctx context.Context, file string, line, col uint32, newName string) (*Plan, error)

Rename performs an LSP-driven rename of the symbol at the zero-based (line, col) UTF-16 position in file, then stages the resulting cross-file edits as region-anchored edits. It requires Config.LSPCommand: it spawns the language server, requests the rename, converts the server's WorkspaceEdit into byte-range edits, grounds each as a Region with a content region_hash, builds one FileAnchor per file, and Prepares them. It returns the Plan; the caller Commits (or Rollbacks) it. The server is shut down before Rename returns.

func (*Editor) Rollback ¶

func (e *Editor) Rollback(plan *Plan) error

Rollback abandons a prepared Plan, discarding the staged edits and clearing the WAL; the source files are left untouched.

func (*OpenedFile) Close ¶

func (o *OpenedFile) Close()

Close releases the native resources held by the opened tree. It is nil-safe and idempotent (parser.Tree.Close is idempotent), so calling it twice or on a zero OpenedFile is a no-op.

func (ReadResult) RenderText ¶ added in v0.3.0

func (r ReadResult) RenderText(w io.Writer) error

RenderText writes the human-readable read view of r to w: a header line "<path> lang=<lang> raw=<raw> norm=<norm> blocks=<N>" followed by one line per Block — " <kind> <name> lines [<sl>:<el>] bytes [<sb>:<eb>] region=<H>" — where an empty Block.Name renders as "-". This is byte-identical to the text output cmd/bage show emits, so the CLI and any RenderText-aware host share one format. Implementing RenderText makes ReadResult text-renderable without importing pkg/render.