SugarCraft — SugarDiff

SugarDiff

Unified-diff engine — hunks, writer, and patch scanner

component-package diff patch

A unified-diff engine the whole ecosystem can share: LCS line diffing, numbered context hunks, a GNU diff -u writer, and a scanner that numbers the rows of any patch. Extracted from sugar-crush's BuildsUnifiedDiff trait and the DiffGutter region model, so every surface that produces or displays patches reads the same line numbers out of the same engine. First-party — there is no 1:1 upstream Go library.

Install

composer require sugarcraft/sugar-diff:@dev

Quickstart

use SugarCraft\Diff\Diff;
use SugarCraft\Diff\DiffOptions;
use SugarCraft\Diff\Reader\UnifiedScan;

$diff = Diff::compute("Hello World\n", "Hello PHP\n");

echo $diff->unified('file.txt');
// --- a/file.txt
// +++ b/file.txt
// @@ -1,1 +1,1 @@
// -Hello World
// +Hello PHP

// Immutable, fluent options — defaults reproduce sugar-crush byte-for-byte.
$wide = Diff::compute($before, $after, DiffOptions::new()
    ->withContextLines(10)
    ->withIgnoreWhitespace()
    ->withNoNewlineMarker()
    ->withDevNullOnEmptySide());

// Number the rows of an existing patch (gutter/viewer support):
foreach (UnifiedScan::lines($patchText) as $row) {
    // $row->old, $row->new, $row->fileHeader
}

The model

Diffcompute() entry point; lines, hunks, per-side counts and final-newline facts; isEmpty/addedLines/removedLines/unified/hunkText.

Hunk / Line / LineKindOne @@ block; one numbered row; eq/del/ins. All immutable value objects.

Writer\UnifiedFormatRenders the GNU diff -u shape: headers, @@ ranges, opt-in "\ No newline" markers and /dev/null labels.

Reader\UnifiedScanWalks any rendered unified diff and returns which old/new line each row points at — the gutter model without the gutter.

Use it for

Patch display in TUIs — numbered hunks feed gutters, diff panes, and review overlays without re-deriving line numbers.
Editing tools — the same engine sugar-crush's Edit/Write tools use to report changes to the model and the user.
Patch consumers — UnifiedScan answers "which file line is this row?" for arbitrary incoming diffs, including multi-file git output.

Source

Try the quickstart →

API

Class	Method	Description
Diff	compute(string\|list<string> $before, string\|list<string> $after, ?DiffOptions $options = null): self	Line-mode LCS diff (byte-for-byte faithful to sugar-crush defaults)
Diff	unified(string $path, ?string $newPath = null): string	Full diff -u text with --- / +++ headers
Diff	hunkText(): string	Hunks only, no file headers
Diff	isEmpty() / addedLines() / removedLines(): int\|bool	Summary counts
DiffOptions	withContextLines(int) / withMaxLcsCells(int)	Context window (default 3) and LCS cell budget (default 250 000)
DiffOptions	withIgnoreWhitespace() / withIgnoreCase()	Fold comparisons; emitted rows keep original bytes
DiffOptions	withNoNewlineMarker() / withDevNullOnEmptySide()	GNU annotations, opt-in
UnifiedFormat	write(Diff, string, ?string) / hunksOnly(Diff): string	The writer behind Diff::unified()/hunkText()
UnifiedScan	lines(string\|list<string>): list<ScannedLine>	Per-row old/new line numbers + fileHeader flag
UnifiedScan	fileHeaders(string\|list<string>): list<bool>	Which rows start a new file