blockpatch 1.0.0 → 1.1.0

package/conformance/README.md

@@ -0,0 +1,29 @@
+# blockpatch conformance
+
+These cases exercise the public `.blockpatch` apply/check contract for independent implementations.
+
+Run against an installed implementation:
+
+```sh
+npx -p blockpatch blockpatch-conformance ./my-implementation
+```
+
+The shorter `npx blockpatch-conformance ./my-implementation` spelling would require publishing a separate npm package named `blockpatch-conformance`; this repository currently ships the runner as a `blockpatch` package binary.
+
+Run against this repository after building:
+
+```sh
+npm run build
+node conformance/runner.mjs node dist/cli.js
+```
+
+The runner invokes the implementation as:
+
+```sh
+<implementation> check <patch.blockpatch> --cwd <work> --json-output
+<implementation> apply <patch.blockpatch> --cwd <work> --json-output
+```
+
+Successful cases also verify retry idempotence and `apply --reverse`. Failure cases verify the expected JSON error code and that the work tree remains byte-identical.
+
+Set `BLOCKPATCH_CONFORMANCE_KEEP=1` to keep the temporary work directory after a failure.

package/conformance/cases/ambiguous-source/case.json

@@ -0,0 +1,8 @@
+{
+  "expect": "fail",
+  "error_code": "source_ambiguous",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\n+move me\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget\nalpha\nmove me\nomega\n"
+  }
+}

package/conformance/cases/ambiguous-target/case.json

@@ -0,0 +1,8 @@
+{
+  "expect": "fail",
+  "error_code": "target_ambiguous",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\n+move me\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget\ntarget\n"
+  }
+}

package/conformance/cases/create-file/case.json

@@ -0,0 +1,8 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch /dev/null b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=072a398e62ad50e40613b98e57f3e3236a471dcbd7c2b9f190440c22adc16a0f\n--- /dev/null\n+++ b/file.txt\n\n@@ -0,0 +1,1 @@ blockpatch-target id=move-1\n+created file\n",
+  "files": {},
+  "expected_files": {
+    "file.txt": "created file\n"
+  }
+}

package/conformance/cases/crlf/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=10d316fe0179a4ccaa97a509f75294785f941d7f9b0656684844edcdf1b5a01a\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\r\n-move me\r\n omega\r\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\r\n+move me\r\n",
+  "files": {
+    "file.txt": "alpha\r\nmove me\r\nomega\r\ntarget\r\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\r\nomega\r\ntarget\r\nmove me\r\n"
+  }
+}

package/conformance/cases/cross-file-relocation/case.json

@@ -0,0 +1,12 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/source.txt b/source.txt\nblockpatch version 1\nblockpatch move id=move-1 role=source payload-sha256=a990c0da5571138b0e2363af883a399fe214a137ad809c67f6530c618967a4e6\n--- a/source.txt\n+++ b/source.txt\n\n@@ -1,5 +1,2 @@ blockpatch-source id=move-1\n alpha()\n-function movedThing() {\n-  return 42;\n-}\n omega()\n\ndiff --blockpatch a/target.txt b/target.txt\nblockpatch version 1\nblockpatch move id=move-1 role=target payload-sha256=a990c0da5571138b0e2363af883a399fe214a137ad809c67f6530c618967a4e6\n--- a/target.txt\n+++ b/target.txt\n\n@@ -1,3 +1,6 @@ blockpatch-target id=move-1\n class Target {\n   method() {}\n+function movedThing() {\n+  return 42;\n+}\n }\n",
+  "files": {
+    "source.txt": "alpha()\nfunction movedThing() {\n  return 42;\n}\nomega()\n",
+    "target.txt": "class Target {\n  method() {}\n}\n"
+  },
+  "expected_files": {
+    "source.txt": "alpha()\nomega()\n",
+    "target.txt": "class Target {\n  method() {}\nfunction movedThing() {\n  return 42;\n}\n}\n"
+  }
+}

package/conformance/cases/delete-existing-file/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=5dbe6af8d3a2a31f6696ebdae9e590977a19b827ec8e0a22ea1e3decf1a79b77\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-remove me\n omega\n",
+  "files": {
+    "file.txt": "alpha\nremove me\nomega\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\nomega\n"
+  }
+}

package/conformance/cases/insert-existing-file/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=cbfeef0cd60ab2c01e036d23082a1f19ea3f5153d9cffde8790ad0152a3830f5\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,2 +1,3 @@ blockpatch-target id=move-1\n alpha\n+inserted line\n omega\n",
+  "files": {
+    "file.txt": "alpha\nomega\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\ninserted line\nomega\n"
+  }
+}

package/conformance/cases/no-trailing-newline/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n+move me\n target\n\\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget"
+  },
+  "expected_files": {
+    "file.txt": "alpha\nomega\nmove me\ntarget"
+  }
+}

package/conformance/cases/remove-file/case.json

@@ -0,0 +1,9 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt /dev/null\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=4da5a83256114db88b111676cf3b2f4a04f202d3d7fc99417cac1ba5145713e2\n--- a/file.txt\n+++ /dev/null\n\n@@ -1,1 +0,0 @@ blockpatch-source id=move-1\n-obsolete file\n",
+  "files": {
+    "file.txt": "obsolete file\n"
+  },
+  "expected_files": {},
+  "expected_absent": ["file.txt"]
+}

package/conformance/cases/same-file-relocation/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\n+move me\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\nomega\ntarget\nmove me\n"
+  }
+}

package/conformance/runner.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { constants } from "node:fs";
+import { access, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const conformanceRoot = dirname(fileURLToPath(import.meta.url));
+const casesRoot = join(conformanceRoot, "cases");
+const invocationCwd = process.cwd();
+const keepTemp = process.env.BLOCKPATCH_CONFORMANCE_KEEP === "1";
+const implementationArgv = process.argv.slice(2);
+
+if (implementationArgv.length === 0 || implementationArgv[0] === "--help" || implementationArgv[0] === "-h") {
+  printUsage();
+  process.exit(implementationArgv.length === 0 ? 2 : 0);
+}
+
+const implementation = normalizeImplementation(implementationArgv);
+const tempRoot = await mkdtemp(join(tmpdir(), "blockpatch-conformance-"));
+
+try {
+  const caseNames = await readCaseNames();
+  for (const caseName of caseNames) {
+    await runCase(caseName);
+    console.log(`ok ${caseName}`);
+  }
+  console.log(`ok ${caseNames.length} conformance cases`);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  if (keepTemp) {
+    console.error(`kept temp directory: ${tempRoot}`);
+  }
+  process.exitCode = 1;
+} finally {
+  if (!keepTemp) {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function printUsage() {
+  console.error("Usage: blockpatch-conformance <blockpatch-command> [args...]");
+  console.error("");
+  console.error("Examples:");
+  console.error("  blockpatch-conformance blockpatch");
+  console.error("  blockpatch-conformance node dist/cli.js");
+}
+
+function normalizeImplementation(argv) {
+  const [command, ...args] = argv;
+  const resolvedCommand = looksPathLike(command) ? resolve(invocationCwd, command) : command;
+  return { command: resolvedCommand, args };
+}
+
+function looksPathLike(command) {
+  return command.startsWith(".") || command.includes("/") || command.includes("\\") || isAbsolute(command);
+}
+
+async function readCaseNames() {
+  const entries = await readdir(casesRoot, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+async function runCase(caseName) {
+  const caseDefinition = JSON.parse(await readFile(join(casesRoot, caseName, "case.json"), "utf8"));
+  const caseRoot = join(tempRoot, caseName);
+  const workRoot = join(caseRoot, "work");
+  const patchPath = join(caseRoot, "patch.blockpatch");
+  await mkdir(workRoot, { recursive: true });
+  await writeCaseFiles(workRoot, caseDefinition.files ?? {});
+  await writeFile(patchPath, Buffer.from(requiredString(caseDefinition.patch, caseName, "patch"), "utf8"));
+
+  const initialFiles = caseDefinition.files ?? {};
+  const expectedFiles = caseDefinition.expected_files ?? initialFiles;
+  const expectedAbsent = caseDefinition.expected_absent ?? [];
+  const expect = caseDefinition.expect ?? "pass";
+
+  if (expect === "pass") {
+    await expectSuccess(caseName, "check", [patchPath, "--cwd", workRoot]);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    await expectSuccess(caseName, "apply", [patchPath, "--cwd", workRoot]);
+    await expectTree(caseName, workRoot, expectedFiles, expectedAbsent);
+    await expectSuccess(caseName, "retry", [patchPath, "--cwd", workRoot]);
+    await expectTree(caseName, workRoot, expectedFiles, expectedAbsent);
+    await expectSuccess(caseName, "reverse", [patchPath, "--cwd", workRoot, "--reverse"]);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    return;
+  }
+
+  if (expect === "fail") {
+    await expectFailure(caseName, "check", [patchPath, "--cwd", workRoot], caseDefinition.error_code);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    await expectFailure(caseName, "apply", [patchPath, "--cwd", workRoot], caseDefinition.error_code);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    return;
+  }
+
+  throw new Error(`${caseName}: unknown expect value ${JSON.stringify(expect)}`);
+}
+
+async function expectSuccess(caseName, label, args) {
+  const result = runBlockpatch(commandArgs(label, args));
+  if (result.status !== 0) {
+    throw commandError(caseName, label, result);
+  }
+  const json = parseJson(caseName, label, result.stdout);
+  if (json.ok !== true) {
+    throw new Error(`${caseName}: ${label} returned non-ok JSON ${JSON.stringify(json)}`);
+  }
+}
+
+async function expectFailure(caseName, label, args, errorCode) {
+  const result = runBlockpatch(commandArgs(label, args));
+  if (result.status === 0) {
+    throw new Error(`${caseName}: ${label} succeeded but expected failure`);
+  }
+  const json = parseJson(caseName, label, result.stderr || result.stdout);
+  if (json.ok !== false) {
+    throw new Error(`${caseName}: ${label} failure returned non-error JSON ${JSON.stringify(json)}`);
+  }
+  if (errorCode !== undefined && json.error?.code !== errorCode) {
+    throw new Error(`${caseName}: ${label} expected error ${errorCode}, got ${String(json.error?.code)}`);
+  }
+}
+
+function commandArgs(label, args) {
+  return [label === "check" ? "check" : "apply", ...args];
+}
+
+function runBlockpatch(args) {
+  return spawnSync(implementation.command, [...implementation.args, ...args, "--json-output"], {
+    cwd: invocationCwd,
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024,
+    shell: process.platform === "win32"
+  });
+}
+
+function commandError(caseName, label, result) {
+  if (result.error !== undefined) {
+    return result.error;
+  }
+  return new Error(
+    `${caseName}: ${label} failed\n` +
+      `exit: ${String(result.status)}\n` +
+      `stdout:\n${result.stdout}\n` +
+      `stderr:\n${result.stderr}`
+  );
+}
+
+function parseJson(caseName, label, text) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${caseName}: ${label} did not return JSON: ${text.trim()}\n${String(error)}`);
+  }
+}
+
+async function writeCaseFiles(root, files) {
+  for (const [path, text] of Object.entries(files)) {
+    const absolute = join(root, path);
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, Buffer.from(requiredString(text, path, "file text"), "utf8"));
+  }
+}
+
+async function expectTree(caseName, root, expectedFiles, expectedAbsent) {
+  const actualPaths = await listFiles(root);
+  const expectedPaths = Object.keys(expectedFiles).sort();
+  assertEqual(caseName, "file list", actualPaths, expectedPaths);
+
+  for (const [path, text] of Object.entries(expectedFiles)) {
+    const expected = Buffer.from(requiredString(text, path, "expected file text"), "utf8");
+    const actual = await readFile(join(root, path));
+    if (!actual.equals(expected)) {
+      throw new Error(`${caseName}: ${path} bytes differ`);
+    }
+  }
+
+  for (const path of expectedAbsent) {
+    try {
+      await access(join(root, path), constants.F_OK);
+    } catch {
+      continue;
+    }
+    throw new Error(`${caseName}: expected ${path} to be absent`);
+  }
+}
+
+async function listFiles(root, prefix = "") {
+  const entries = await readdir(join(root, prefix), { withFileTypes: true });
+  const paths = [];
+  for (const entry of entries) {
+    const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      paths.push(...await listFiles(root, path));
+    } else if (entry.isFile()) {
+      paths.push(path);
+    }
+  }
+  return paths.sort();
+}
+
+function requiredString(value, label, field) {
+  if (typeof value !== "string") {
+    throw new Error(`${label}: ${field} must be a string`);
+  }
+  return value;
+}
+
+function assertEqual(caseName, label, actual, expected) {
+  const actualJson = JSON.stringify(actual);
+  const expectedJson = JSON.stringify(expected);
+  if (actualJson !== expectedJson) {
+    throw new Error(`${caseName}: ${label} expected ${expectedJson}, got ${actualJson}`);
+  }
+}