Log inGet started
Package

text_diff.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

text_diff

Pure-Luau line-diff helper used by world.diff / world.show and the zm diff / zm show shell commands. LCS-based; produces structured hunks (op-tagged lines, not unified-diff text) so AI consumers can pattern-match on op instead of parsing +/-/ prefixes.

Exports

  • M.diff(oldText: string?, newText: string?, opts: DiffOpts?) -> FileDiff — diff two strings, return the structured per-file shape.
  • M.added(newText: string?, opts: DiffOpts?) -> FileDiff — pure-add convenience (equivalent to M.diff("", newText, opts)).
  • M.removed(oldText: string?, opts: DiffOpts?) -> FileDiff — pure-remove convenience.
  • M.toUnifiedText(fileDiff: FileDiff) -> string — render structured diff back into unified-diff text.
  • M.toStatLine(fileDiff: FileDiff) -> string — git diff --stat-style one-line summary.
  • M.SIZE_CAP_BYTES: number — per-file size cap (256 KB). Files larger than this return a size-only summary with is_text=false.

Types:

  • DiffLine = { op: string, text: string } — one tagged line. op is "+", "-", or " " (context).
  • DiffHunk = { old_start, old_count, new_start, new_count, lines: { DiffLine } } — git-style hunk.
  • DiffOpts = { context: number?, path: string?, action: string? }.
  • FileDiff = { path?, action?, is_text, added?, removed?, hunks?, size_old?, size_new? }.

Usage

local TextDiff = require("@builtin::modules.text_diff")

local d = TextDiff.diff(oldBytes, newBytes, { path = "foo.luau" })
if d.is_text then
    print(TextDiff.toStatLine(d))         -- "modified  foo.luau  +3 -1"
    print(TextDiff.toUnifiedText(d))
else
    print(string.format("oversize: %d -> %d bytes", d.size_old, d.size_new))
end

Notes

  • The per-file size cap (M.SIZE_CAP_BYTES = 256 * 1024) mirrors the spacetime text_blobs inline threshold. Anything above that lives in the bucket as binary anyway, so the diff library never sees it as text in practice; the cap is belt-and-suspenders for callers that bypass the routing.
  • The alignment is a longest common subsequence computed on the diagonal band of the table its edit distance reaches, one bit per cell, after the common prefix and suffix are aligned line by line. Memory and time follow the lengths of the two texts times their edit distance, so a few changed lines in a long file cost a few bands of that file's length. A long diff runs in slices that hand the frame back (FrameBudget.yield) when the caller runs on a coroutine that can yield.
  • Where repeated lines leave several equally long alignments, the diff takes the one a walk back from the last lines takes: a common pair of lines is kept, and otherwise the new side's line is let go first, so each run of changed lines lists its removed lines before its added ones.
  • Default context window is 3 lines (matches git diff -U3). Override via opts.context.
  • Hunk header line numbers follow git's @@ -0,0 +1,N @@ shape for pure additions (and the mirror for pure deletions).
  • Trailing newline handling: a final \n doesn't produce an empty trailing element. Matches POSIX wc -l semantics and most diff tools.