Add the diffr TypeScript contract and pinned binary fetcher

.github/workflows/test.yml

@@ -117,3 +117,23 @@ jobs:
         run: curl -LsSf https://github.com/crate-ci/typos/releases/download/$TYPOS_VERSION/typos-$TYPOS_VERSION-x86_64-unknown-linux-musl.tar.gz | tar zxf - -C ${CARGO_HOME:-~/.cargo}/bin
       - name: Check for typos
         run: typos
+
+  test_typescript:
+    name: Test @dev.fast/diffr
+    permissions:
+      contents: read
+    runs-on: ubuntu-22.04
+    steps:
+      # v4.2.2
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.10
+      - uses: dtolnay/rust-toolchain@1.85.0
+      - run: cargo build --locked
+      - working-directory: diffr-ts
+        run: |
+          bun install --frozen-lockfile
+          bun run typecheck
+          bun run build
+          bun test

diffr-ts/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

diffr-ts/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021-2025 Wilfred Hughes
+Copyright (c) 2026 dev.fast
+
+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.

diffr-ts/README.md

@@ -0,0 +1,40 @@
+# @dev.fast/diffr
+
+TypeScript types, zod validators, and a binary fetcher for diffr's NDJSON protocol.
+The package version matches the diffr release.
+
+```ts
+import { decodeStructuralDiffEvent } from "@dev.fast/diffr";
+const event = decodeStructuralDiffEvent(line);
+```
+
+```sh
+npx --package @dev.fast/diffr@0.1.1 diffr-fetch --into ./bin --required
+```
+
+Supports macOS arm64 and Linux x64. `--check` verifies an existing install without
+network access. Downloads warn on network failure unless `--required`; invalid
+hashes or archives always fail.
+
+## Wire changes
+
+Keep these files in sync:
+
+| Files (from repo root) | Check |
+|---|---|
+| `src/protocol/mod.rs`, `src/pairing.rs`, `diffr-ts/src/contract.ts` | Contract tests against the binary; Rust version check |
+| `docs/streaming.md` | Review against the wire format |
+| `tui/packages/hunk/src/diffr/wire.ts` (v3 only) | TUI fixture tests |
+| Review's `packages/review-protocol/package.json` and `packages/review/package.json` | Exact package version pins |
+
+## Release
+
+After tagging the matching Rust release and building with `cargo build --locked`,
+run from `diffr-ts`:
+
+```sh
+bun install --frozen-lockfile
+npm run pin
+bun run typecheck && bun test
+npm publish --access public
+```

diffr-ts/bin/fetch.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const targets = { "darwin-arm64": "aarch64-apple-darwin", "linux-x64": "x86_64-unknown-linux-gnu" };
+
+try {
+  await main();
+} catch (error) {
+  console.error(`diffr-fetch: ${error.message}`);
+  process.exitCode = 1;
+}
+
+async function main() {
+  const { values } = parseArgs({ options: {
+    into: { type: "string" },
+    check: { type: "boolean" },
+    required: { type: "boolean" },
+    pins: { type: "string", default: join(root, "pins.json") },
+  } });
+  if (!values.into) throw new Error("--into <dir> is required");
+  const into = resolve(values.into);
+  const { version } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const pins = JSON.parse(readFileSync(values.pins, "utf8"));
+  if (pins.version !== version) throw new Error(`pins.json is for ${pins.version}, package is ${version}; run \`npm run pin\``);
+  const target = targets[`${process.platform}-${process.arch}`];
+  if (!target) throw new Error(`no diffr release for ${process.platform}-${process.arch}`);
+  const expected = pins.sha256?.[target];
+  if (typeof expected !== "string" || !/^[a-f0-9]{64}$/.test(expected)) {
+    throw new Error(`pins.json has no valid sha256 for ${target}`);
+  }
+
+  const binary = join(into, "diffr");
+  const stampPath = join(into, "diffr.stamp.json");
+  let installed = false;
+  try {
+    const stamp = JSON.parse(readFileSync(stampPath, "utf8"));
+    const stat = lstatSync(binary);
+    installed = stat.isFile() && (stat.mode & 0o111) !== 0 && stamp.version === version && stamp.target === target;
+  } catch { /* Missing or damaged installations are fetched again. */ }
+  if (installed) {
+    console.log(`diffr ${version} (${target}) already at ${binary}`);
+    return;
+  }
+  if (values.check) throw new Error(`${binary} is missing or not diffr ${version} (${target})`);
+
+  const asset = `diffr-${version}-${target}.tar.gz`;
+  const url = `https://github.com/devdotfast/diffr/releases/download/${version}/${asset}`;
+  let bytes;
+  try {
+    const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+    if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+    bytes = Buffer.from(await response.arrayBuffer());
+  } catch (error) {
+    if (values.required) throw new Error(`could not download ${url}: ${error.message}`);
+    console.warn(`diffr-fetch: could not download ${url}: ${error.message}; continuing without a bundled diffr`);
+    return;
+  }
+  const actual = createHash("sha256").update(bytes).digest("hex");
+  if (actual !== expected) throw new Error(`${asset} sha256 ${actual} does not match pinned ${expected}`);
+
+  mkdirSync(into, { recursive: true });
+  const staging = mkdtempSync(join(into, ".diffr-"));
+  try {
+    const archive = join(staging, "archive.tar.gz");
+    writeFileSync(archive, bytes);
+    const tar = spawnSync("tar", ["-xzf", archive, "-C", staging, "diffr"], { encoding: "utf8" });
+    const extracted = join(staging, "diffr");
+    if (tar.status !== 0 || !lstatSync(extracted).isFile()) {
+      throw new Error(`${asset} does not contain a regular diffr file at its root`);
+    }
+    chmodSync(extracted, 0o755);
+    const stamp = join(staging, "stamp.json");
+    writeFileSync(stamp, `${JSON.stringify({ version, target }, null, 2)}\n`);
+    renameSync(extracted, binary);
+    renameSync(stamp, stampPath);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  console.log(`diffr ${version} (${target}) installed at ${binary}`);
+}

diffr-ts/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dev.fast/diffr",
+  "version": "0.1.1",
+  "description": "diffr's NDJSON wire contract, validators, and release binary fetcher",
+  "repository": "https://github.com/devdotfast/diffr",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./src/*": "./src/*"
+  },
+  "bin": {
+    "diffr-fetch": "bin/fetch.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/*.test.ts",
+    "!src/test-binary.ts",
+    "bin",
+    "pins.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "pin": "node scripts/pin.mjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3",
+    "zod": "4.1.12"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

diffr-ts/pins.json

@@ -0,0 +1,7 @@
+{
+  "version": "0.1.1",
+  "sha256": {
+    "aarch64-apple-darwin": "7312213893286b804190da46d4c181cc9646320b6c651ada68a42fd97a84bb7f",
+    "x86_64-unknown-linux-gnu": "1cce58b34031b274b1ab511bf929f501d9e99a8710d4ca33b0ed4cdc94d9ab60"
+  }
+}

diffr-ts/scripts/pin.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, "..");
+const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+const targets = ["aarch64-apple-darwin", "x86_64-unknown-linux-gnu"];
+const sha256 = {};
+for (const target of targets) {
+  const url = `https://github.com/devdotfast/diffr/releases/download/${version}/diffr-${version}-${target}.tar.gz`;
+  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+  if (!response.ok) {
+    console.error(`pin: GET ${url} failed with ${response.status} ${response.statusText}`);
+    process.exit(1);
+  }
+  sha256[target] = createHash("sha256").update(Buffer.from(await response.arrayBuffer())).digest("hex");
+  console.log(`${target} ${sha256[target]}`);
+}
+writeFileSync(join(root, "pins.json"), `${JSON.stringify({ version, sha256 }, null, 2)}\n`);
+console.log(`wrote pins.json for ${version}`);

diffr-ts/src/contract.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  STRUCTURAL_DIFF_BASE_WIRE_VERSION,
+  STRUCTURAL_DIFF_WIRE_VERSION,
+  type StructuralDiffEvent,
+  decodeStructuralDiffEvent,
+} from "./index.js";
+import { diffrBinary, repositoryRoot } from "./test-binary.js";
+
+const dirs: string[] = [];
+function tempDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  dirs.push(dir);
+  return dir;
+}
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function run(args: string[], cwd = repositoryRoot): StructuralDiffEvent[] {
+  const result = Bun.spawnSync([diffrBinary(), ...args], {
+    cwd,
+    env: { ...process.env, XDG_CONFIG_HOME: tempDir("diffr-config-") },
+  });
+  expect(result.exitCode, result.stderr.toString()).toBe(0);
+  const stdout = new TextDecoder().decode(result.stdout);
+  const lines = stdout.split("\n").filter((line) => line.length > 0);
+  expect(lines.length).toBeGreaterThan(0);
+  return lines.map(decodeStructuralDiffEvent);
+}
+
+function git(cwd: string, ...args: string[]): void {
+  const result = Bun.spawnSync(["git", "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", ...args], { cwd });
+  expect(result.exitCode).toBe(0);
+}
+
+const pairs: [string, string][] = [
+  ["sample_files/simple_1.js", "sample_files/simple_2.js"],
+  ["sample_files/if_1.py", "sample_files/if_2.py"],
+  ["sample_files/context_1.rs", "sample_files/context_2.rs"],
+  ["sample_files/comments_1.rs", "sample_files/comments_2.rs"],
+];
+
+describe("every record the binary writes validates", () => {
+  for (const [before, after] of pairs) {
+    test(`--no-index ${before} ${after}`, () => {
+      const events = run(["--no-index", "--format", "ndjson", "--", before, after]);
+      expect(events[0]).toMatchObject({ type: "start", version: STRUCTURAL_DIFF_BASE_WIRE_VERSION });
+      expect(events.at(-1)).toMatchObject({ type: "complete", failed: 0 });
+      expect(events.some((event) => event.type === "file")).toBe(true);
+    });
+  }
+
+  test("--syntax adds syntax spans that validate", () => {
+    const events = run(["--no-index", "--syntax", "--format", "ndjson", "--", ...pairs[2]]);
+    const file = events.find((event) => event.type === "file");
+    expect(file?.diff && file.diff.type === "text" && (file.diff.rhs?.syntax?.length ?? 0) > 0).toBe(true);
+  });
+
+  test("--stream-annotations emits version 4 and annotation records", () => {
+    const root = tempDir("diffr-contract-repo-");
+    git(root, "init", "-q", "-b", "main");
+    git(root, "config", "user.email", "test@example.com");
+    git(root, "config", "user.name", "test");
+    writeFileSync(join(root, "lib.rs"), "fn a() -> u32 {\n    1\n}\n");
+    git(root, "add", ".");
+    git(root, "commit", "-q", "-m", "one");
+    writeFileSync(join(root, "lib.rs"), "fn a() -> u32 {\n    2\n}\n\nfn b() -> u32 {\n    a() + 1\n}\n");
+    git(root, "commit", "-q", "-am", "two");
+
+    const events = run(["--repo", root, "--format", "ndjson", "--stream-annotations", "HEAD~1", "HEAD"], root);
+    expect(events[0]).toMatchObject({ type: "start", version: STRUCTURAL_DIFF_WIRE_VERSION });
+    expect(events.some((event) => event.type === "file")).toBe(true);
+    expect(events.some((event) => event.type === "annotations")).toBe(true);
+    expect(events.at(-1)).toMatchObject({ type: "complete", failed: 0 });
+  });
+});
+
+test("the terminal UI's committed v3 fixture still validates", async () => {
+  const text = await Bun.file(join(repositoryRoot, "tui/test/fixtures/comparison.ndjson")).text();
+  const events = text.split("\n").filter((line) => line.length > 0).map(decodeStructuralDiffEvent);
+  expect(events[0]).toMatchObject({ type: "start", version: STRUCTURAL_DIFF_BASE_WIRE_VERSION });
+  expect(events.at(-1)).toMatchObject({ type: "complete", failed: 0 });
+});
+
+test("a record missing required fields is rejected", () => {
+  expect(() => decodeStructuralDiffEvent('{"type":"complete","succeeded":1}')).toThrow(
+    "Malformed diffr protocol record.",
+  );
+});
+
+test("invalid JSON preserves the parse failure as its cause", () => {
+  try {
+    decodeStructuralDiffEvent("{");
+    throw new Error("expected decoding to fail");
+  } catch (error) {
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe("Malformed diffr protocol record.");
+    expect((error as Error).cause).toBeInstanceOf(SyntaxError);
+  }
+});