optipack 0.0.0-stage → 1.0.0

package/test/harness/setup.js

@@ -0,0 +1,198 @@
+/**
+ * Differential harness.
+ *
+ * Equivalence notion: transforms may legitimately eliminate READS — that is
+ * the point — so we compare EFFECTS, not API-call traces. Every mutating call
+ * (sendMessage, setDynamicProperty, runCommand, spawnEntity, applyDamage,
+ * component writes, runInterval/runTimeout/runJob registrations) must match
+ * exactly, in order, between original and optimized code.
+ *
+ * Reads return scripted sequences from the recorder, so data flows through
+ * the script deterministically.
+ */
+import { register } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import fs from 'node:fs';
+import os from 'node:os';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+if (!globalThis.__opkHooksRegistered) {
+  register(
+    pathToFileURL(path.join(here, '..', 'loader-hooks.mjs')).href,
+    pathToFileURL(path.join(here, 'setup.js')).href
+  );
+  globalThis.__opkHooksRegistered = true;
+}
+
+export function makeRecorder({ reads = {}, state = {} } = {}) {
+  const r = {
+    effects: [],
+    handlers: new Map(),
+    intervals: [],
+    timeouts: [],
+    jobs: [],
+    readQueues: structuredClone(reads),
+    readIdx: {},
+    state,
+    tickCounter: 0,
+  };
+  r.effect = (call, args) => {
+    r.effects.push({ call, args });
+  };
+  // Scripted reads index by TICK, not by call: the engine is synchronous, so
+  // repeated reads within one tick return the same value, and values may only
+  // change between ticks. This models the real host boundary correctly.
+  r.scriptedRead = (key, fallback) => {
+    const q = r.readQueues[key];
+    if (!q || q.length === 0) return fallback;
+    return q[r.tickCounter % q.length];
+  };
+  r.addHandler = (name, cb) => {
+    if (!r.handlers.has(name)) r.handlers.set(name, []);
+    r.handlers.get(name).push(cb);
+  };
+  r.removeHandler = (name, cb) => {
+    const arr = r.handlers.get(name);
+    if (arr) {
+      const idx = arr.indexOf(cb);
+      if (idx >= 0) arr.splice(idx, 1);
+    }
+  };
+  r.addInterval = (cb, interval) => {
+    const id = r.intervals.length;
+    r.intervals.push({ fn: cb, interval });
+    return id;
+  };
+  r.addTimeout = (cb, delay) => {
+    const id = r.timeouts.length;
+    r.timeouts.push({ fn: cb, delay, due: r.tickCounter + delay });
+    return id;
+  };
+  r.addJob = (gen) => {
+    r.jobs.push({ gen });
+  };
+  // One game tick: run due interval callbacks, timeouts, and one job step each.
+  r.tick = (n = 1) => {
+    for (let t = 0; t < n; t++) {
+      r.tickCounter++;
+      const intervals = [...r.intervals];
+      for (const it of intervals) {
+        if (r.tickCounter % it.interval === 0) it.fn();
+      }
+      const due = r.timeouts.filter((to) => to.due <= r.tickCounter);
+      for (const to of due) {
+        to.fn();
+      }
+      r.timeouts = r.timeouts.filter((to) => to.due > r.tickCounter);
+      for (const j of r.jobs) {
+        try {
+          j.gen.next();
+        } catch (e) {
+          // Generator exceptions propagate like engine errors; record them.
+          r.effects.push({ call: 'job.error', args: String(e && e.message) });
+        }
+      }
+    }
+  };
+  r.fire = (eventName, payload) => {
+    const handlers = [...(r.handlers.get(eventName) || [])];
+    const hydrated = hydrate(payload, r);
+    for (const cb of handlers) cb(hydrated);
+  };
+  r.tickCount = () => r.tickCounter;
+  return r;
+}
+
+/** Recursively replace {__entity: id} markers in a payload with live entities. */
+function hydrate(value, rec) {
+  if (globalThis.__opkEnsurePlayers) globalThis.__opkEnsurePlayers(rec);
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => hydrate(v, rec));
+  if (typeof value.__entity === 'string') {
+    const players = rec._players || [];
+    const found = players.find((p) => p.id === value.__entity);
+    return found || value;
+  }
+  const out = {};
+  for (const k of Object.keys(value)) out[k] = hydrate(value[k], rec);
+  return out;
+}
+
+/**
+ * Load a script entry with a fresh recorder and run the step list.
+ * Steps: {op:'tick', n}, {op:'fire', event, payload}, {op:'call', fn(rec)}
+ */
+export async function runVariant(entryUrl, variant, { reads, state, steps = [] }) {
+  const rec = makeRecorder({ reads, state });
+  globalThis.__opkRecorder = rec;
+  try {
+    const mod = await import(`${entryUrl}?opkv=${variant}&t=${Date.now()}-${Math.floor(Math.random() * 1e9)}`);
+    for (const step of steps) {
+      if (step.op === 'tick') rec.tick(step.n);
+      else if (step.op === 'fire') rec.fire(step.event, step.payload);
+      else if (step.op === 'call') step.fn(rec);
+    }
+  } finally {
+    globalThis.__opkRecorder = null;
+  }
+  return rec;
+}
+
+export function assertSameEffects(a, b, label = '') {
+  const ja = JSON.stringify(a.effects);
+  const jb = JSON.stringify(b.effects);
+  if (ja !== jb) {
+    // Find the first divergence for a helpful message.
+    const la = a.effects;
+    const lb = b.effects;
+    let i = 0;
+    while (i < la.length && i < lb.length && JSON.stringify(la[i]) === JSON.stringify(lb[i])) i++;
+    const fmt = (e) => JSON.stringify(e);
+    throw new Error(
+      `effects diverge${label ? ' (' + label + ')' : ''} at index ${i}:\n` +
+      `  original:   ${la[i] ? fmt(la[i]) : '<none>'}\n` +
+      `  optimized:  ${lb[i] ? fmt(lb[i]) : '<none>'}\n` +
+      `  (original had ${la.length} effects, optimized had ${lb.length})`
+    );
+  }
+}
+
+/**
+ * Build a temp pack from sources, run the pipeline over it, and return both
+ * the original and optimized file paths.
+ */
+export async function buildVariantPack(files, config, testSuffix) {
+  const { normalizeConfig } = await import('../../src/config.js');
+  const { runPack } = await import('../../src/pipeline.js');
+  const inputDir = fs.mkdtempSync(path.join(os.tmpdir(), `optipack-${testSuffix}-in-`));
+  const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), `optipack-${testSuffix}-out-`));
+  for (const [relPath, content] of Object.entries(files)) {
+    const abs = path.join(inputDir, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  const cfg = normalizeConfig(config || { level: 'balanced' });
+  const report = runPack(inputDir, outputDir, cfg);
+  return { inputDir, outputDir, report };
+}
+
+export function pathToUrl(p) {
+  return 'file:///' + p.replace(/\\/g, '/').replace(/^\//, '');
+}
+
+/**
+ * Full differential check: run original + optimized with the same scenario
+ * and compare effect traces.
+ */
+export async function differentialCheck(files, config, scenario, label) {
+  const { inputDir, outputDir } = await buildVariantPack(files, config, label.replace(/\W+/g, '-'));
+  const entryRel = scenario.entry; // e.g. 'scripts/main.js'
+  const origUrl = pathToUrl(path.join(inputDir, entryRel));
+  const optUrl = pathToUrl(path.join(outputDir, entryRel));
+  const a = await runVariant(origUrl, 'orig', scenario);
+  const b = await runVariant(optUrl, 'opt', scenario);
+  assertSameEffects(a, b, label);
+  return { a, b, outputDir };
+}

package/test/hoist-invariant-members/expected.js

@@ -0,0 +1,37 @@
+// S7: loop-invariant member hoisting inside hot functions.
+import { world, system } from '@minecraft/server';
+
+// Before-loop hoist: player.location read once instead of 10 times.
+function onTick(player) {
+  let total = 0;
+  const _opH = player.location.y;
+  for (let i = 0; i < 10; i++) {
+    total += _opH;
+  }
+  world.setDynamicProperty('total', total);
+}
+
+// Two chains, each used twice per iteration: both hoisted.
+function onTick2(chest) {
+  let dx = 0;
+  const _opC = chest.location;
+  const _opH2 = _opC.x;
+  const _opH3 = _opC.y;
+  for (let i = 0; i < 5; i++) {
+    dx += _opH2 + _opH3;
+  }
+  world.setDynamicProperty('dx', dx);
+}
+
+// Loop body with a call: barrier, bails.
+function onTick3(player) {
+  let total = 0;
+  for (let i = 0; i < 4; i++) {
+    total += player.location.y;
+    world.sendMessage('tick');
+  }
+  world.setDynamicProperty('total3', total);
+}
+system.runInterval(onTick, 20);
+system.runInterval(onTick2, 20);
+system.runInterval(onTick3, 20);

package/test/hoist-invariant-members/expects.json

@@ -0,0 +1,11 @@
+{
+    "transforms":  {
+                       "hoist-invariant-members":  2
+                   },
+    "bails":  [
+                  {
+                      "transform":  "S7",
+                      "reasonContains":  "mutation barrier"
+                  }
+              ]
+}

package/test/hoist-invariant-members/input.js

@@ -0,0 +1,34 @@
+// S7: loop-invariant member hoisting inside hot functions.
+import { world, system } from '@minecraft/server';
+
+// Before-loop hoist: player.location read once instead of 10 times.
+function onTick(player) {
+  let total = 0;
+  for (let i = 0; i < 10; i++) {
+    total += player.location.y;
+  }
+  world.setDynamicProperty('total', total);
+}
+
+// Two chains, each used twice per iteration: both hoisted.
+function onTick2(chest) {
+  let dx = 0;
+  for (let i = 0; i < 5; i++) {
+    dx += chest.location.x + chest.location.y;
+  }
+  world.setDynamicProperty('dx', dx);
+}
+
+// Loop body with a call: barrier, bails.
+function onTick3(player) {
+  let total = 0;
+  for (let i = 0; i < 4; i++) {
+    total += player.location.y;
+    world.sendMessage('tick');
+  }
+  world.setDynamicProperty('total3', total);
+}
+
+system.runInterval(onTick, 20);
+system.runInterval(onTick2, 20);
+system.runInterval(onTick3, 20);

package/test/hoist-invariant-members/scenario.json

@@ -0,0 +1,35 @@
+{
+    "reads":  {
+                  "location:p1":  [
+                                      {
+                                          "y":  64,
+                                          "z":  2,
+                                          "x":  1
+                                      }
+                                  ],
+                  "location:p2":  [
+                                      {
+                                          "y":  70,
+                                          "z":  4,
+                                          "x":  3
+                                      }
+                                  ]
+              },
+    "entry":  "scripts/input.js",
+    "steps":  [
+                  {
+                      "n":  5,
+                      "op":  "tick"
+                  }
+              ],
+    "state":  {
+                  "players":  [
+                                  {
+                                      "id":  "p1"
+                                  },
+                                  {
+                                      "id":  "p2"
+                                  }
+                              ]
+              }
+}

package/test/hoist-invariant-members-bail/expected.js

@@ -0,0 +1,19 @@
+// S7 bails: loop-variable roots, computed members, reassignment.
+import { world, system } from '@minecraft/server';
+function loopVar(chests) {
+  let total = 0;
+  for (let i = 0; i < chests.length; i++) {
+    total += chests[i].location.y;
+  }
+  world.setDynamicProperty('t', total);
+}
+function reassigned(player) {
+  let total = 0;
+  for (let i = 0; i < 4; i++) {
+    total += player.location.y;
+  }
+  player = null;
+  world.setDynamicProperty('t', total);
+}
+system.runInterval(() => loopVar([1, 2]), 20);
+system.runInterval(() => reassigned(world.getAllPlayers()[0]), 20);

package/test/hoist-invariant-members-bail/expects.json

@@ -0,0 +1,5 @@
+{
+    "transforms":  {
+                       "hoist-invariant-members":  0
+                   }
+}

package/test/hoist-invariant-members-bail/input.js

@@ -0,0 +1,22 @@
+// S7 bails: loop-variable roots, computed members, reassignment.
+import { world, system } from '@minecraft/server';
+
+function loopVar(chests) {
+  let total = 0;
+  for (let i = 0; i < chests.length; i++) {
+    total += chests[i].location.y;
+  }
+  world.setDynamicProperty('t', total);
+}
+
+function reassigned(player) {
+  let total = 0;
+  for (let i = 0; i < 4; i++) {
+    total += player.location.y;
+  }
+  player = null;
+  world.setDynamicProperty('t', total);
+}
+
+system.runInterval(() => loopVar([1, 2]), 20);
+system.runInterval(() => reassigned(world.getAllPlayers()[0]), 20);

package/test/infra.test.mjs

@@ -0,0 +1,260 @@
+/**
+ * Infrastructure tests: pragmas, config handling, CLI behaviors, determinism.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(here, '..');
+const CLI = path.join(root, 'bin', 'optipack.js');
+
+const { normalizeConfig, loadConfigFile, ConfigError } = await import('../src/config.js');
+const { transformSource, runPack } = await import('../src/pipeline.js');
+
+function mkPack(files) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-infra-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  return dir;
+}
+
+const cfg = (over = {}) => normalizeConfig({ level: 'balanced', ...over });
+
+test('config: normalize + validation', () => {
+  assert.equal(cfg().level, 'balanced');
+  assert.equal(cfg({ level: 'risky' }).level, 'risky');
+  assert.equal(cfg({ hotPath: { transitiveDepth: 3 } }).hotPath.transitiveDepth, 3);
+  assert.throws(() => normalizeConfig({ level: 'nope' }), ConfigError);
+  assert.throws(() => normalizeConfig({ transforms: { 'x': 1 } }), ConfigError);
+  assert.throws(() => normalizeConfig({ hotPath: { transitiveDepth: -1 } }), ConfigError);
+  assert.throws(() => normalizeConfig({ unknownKey: true }), ConfigError);
+});
+
+test('config: file loading with BOM + explicit path', () => {
+  const dir = mkPack({ 'optipack.config.json': '\uFEFF{"level":"safe","transforms":{"json-fold":false}}' });
+  const { config } = loadConfigFile(path.join(dir, 'optipack.config.json'));
+  assert.equal(config.level, 'safe');
+  assert.equal(config.transforms['json-fold'], false);
+  assert.throws(() => loadConfigFile(path.join(dir, 'nope.json')), ConfigError);
+});
+test('pragma: file-level optipack: off disables everything', () => {
+  const src = [
+    '// optipack: off',
+    "export const a = 1 + 2;",
+    "export function f() {",
+    "  let s = '';",
+    "  for (const x of ['a']) { s += x; }",
+    "  return s;",
+    '}',
+  ].join('\n');
+  const { code, fileReport } = transformSource('t.js', src, cfg());
+  assert.equal(code, src);
+  assert.deepEqual(fileReport.transforms, {});
+});
+
+test('pragma: optipack-disable on the line before a statement', () => {
+  const src = [
+    '// const-fold disabled for this declaration only',
+    '// optipack-disable const-fold',
+    'export const a = 1 + 2;',
+    'export const b = 3 + 4;',
+  ].join('\n');
+  const { code, fileReport } = transformSource('t.js', src, cfg());
+  assert.ok(code.includes('export const a = 1 + 2;'), 'disabled line unchanged');
+  assert.ok(code.includes('export const b = 7;'), 'enabled line folded');
+  assert.equal(fileReport.transforms['const-fold'], 1);
+});
+
+test('pragma: optipack-disable all', () => {
+  const src = [
+    'export function f() {',
+    '  // optipack-disable all',
+    '  return 1 + 2;',
+    '}',
+    'export const g = 2 + 3;',
+  ].join('\n');
+  const { code, fileReport } = transformSource('t.js', src, cfg());
+  assert.ok(code.includes('return 1 + 2;'), 'disabled return unchanged');
+  assert.ok(code.includes('export const g = 5;'), 'other code folded');
+  assert.equal(fileReport.transforms['const-fold'], 1);
+});
+
+test('pragma: optipack-hot force-marks a function', () => {
+  const src = [
+    "import { world } from '@minecraft/server';",
+    '// optipack-hot',
+    'function notRegistered(player) {',
+    '  const a = player.location.x;',
+    '  const b = player.location.x;',
+    '  world.sendMessage(String(a + b));',
+    '}',
+  ].join('\n');
+  const { fileReport } = transformSource('t.js', src, cfg());
+  // Hot-marked -> B1 applies even without registration.
+  assert.ok(fileReport.transforms['cache-getter-chains'] >= 1, 'B1 applied to pragma-hot function');
+});
+
+test('pipeline: determinism — same input produces byte-identical output', () => {
+  const src = [
+    "import { world, system } from '@minecraft/server';",
+    'function onTick() {',
+    "  const tags = ['a', 'b'].filter((t) => t.length > 0);",
+    '  let s = 0;',
+    '  for (const t of tags) { s += t.length; }',
+    "  world.sendMessage('' + s);",
+    '}',
+    'system.runInterval(onTick, 20);',
+  ].join('\n');
+  const r1 = transformSource('t.js', src, cfg());
+  const r2 = transformSource('t.js', src, cfg());
+  assert.equal(r1.code, r2.code);
+});
+
+test('pipeline: output round-trips as ESM', () => {
+  const src = [
+    "import { world } from '@minecraft/server';",
+    'export class Thing { #n = 1; get n() { return this.#n; } }',
+    'export const arrow = async (x) => x ?? 0;',
+  ].join('\n');
+  const { code } = transformSource('t.js', src, cfg());
+  assert.ok(code.includes('class Thing'), 'modern syntax preserved');
+});
+
+test('pipeline: parse failure reports file and line', () => {
+  assert.throws(() => transformSource('scripts/bad.js', 'function {{{', cfg()), (e) => {
+    assert.equal(e.code, 2);
+    assert.ok(e.message.includes('scripts/bad.js'), 'file name in message');
+    assert.match(e.message, /:\d+:\d+/, 'line:column in message');
+    return true;
+  });
+});
+
+test('pack walker: non-script files copied verbatim, manifest untouched', () => {
+  const input = mkPack({
+    'manifest.json': '{"format_version": 2, "header": {"name": "keep"}}',
+    'scripts/main.js': 'export const a = 1 + 2;\n',
+    'functions/tick.mcfunction': 'say hi\n',
+    'texts/en_US.lang': 'item.name=Thing\n',
+    'textures/foo.png': 'not-really-a-png',
+    'scripts/nested/sub.js': 'const b = 2 + 2;\n',
+  });
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'pack');
+  const report = runPack(input, out, cfg());
+  assert.equal(fs.readFileSync(path.join(out, 'manifest.json'), 'utf8'), '{"format_version": 2, "header": {"name": "keep"}}');
+  assert.equal(fs.readFileSync(path.join(out, 'functions/tick.mcfunction'), 'utf8'), 'say hi\n');
+  assert.equal(fs.readFileSync(path.join(out, 'textures/foo.png'), 'utf8'), 'not-really-a-png');
+  assert.equal(fs.readFileSync(path.join(out, 'texts/en_US.lang'), 'utf8'), 'item.name=Thing\n');
+  const mainOut = fs.readFileSync(path.join(out, 'scripts/main.js'), 'utf8');
+  assert.ok(mainOut.includes('3'), 'script transformed');
+  assert.ok(fs.existsSync(path.join(out, 'scripts/nested/sub.js')));
+  assert.equal(report.files.length, 2);
+});
+
+test('CLI: exit 0 on the example pack, report written, manifest identical', () => {
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-cli-')), 'out');
+  const res = spawnSync(process.execPath, [CLI, path.join(root, 'example'), out, '--report', path.join(out, 'report.json')], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+  assert.ok(fs.existsSync(path.join(out, 'manifest.json')));
+  assert.ok(fs.existsSync(path.join(out, 'report.json')));
+  assert.ok(fs.existsSync(path.join(out, 'scripts/main.js')));
+});
+
+test('CLI: exit 1 on usage errors', () => {
+  const res1 = spawnSync(process.execPath, [CLI], { encoding: 'utf8' });
+  assert.equal(res1.status, 1);
+  const res2 = spawnSync(process.execPath, [CLI, 'Z:/definitely/missing/dir', 'out'], { encoding: 'utf8' });
+  assert.equal(res2.status, 1);
+  const res3 = spawnSync(process.execPath, [CLI, path.join(root, 'example'), 'out', '--level', 'bogus'], { encoding: 'utf8' });
+  assert.equal(res3.status, 1);
+  const res4 = spawnSync(process.execPath, [CLI, path.join(root, 'example'), 'out', '--only', 'no-such-transform'], { encoding: 'utf8' });
+  assert.equal(res4.status, 1);
+});
+
+test('CLI: exit 2 on parse failure with file+line in stderr', () => {
+  const input = mkPack({
+    'manifest.json': '{}',
+    'scripts/broken.js': 'function broken( {\n  return 1;\n}\n',
+  });
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'out');
+  const res = spawnSync(process.execPath, [CLI, input, out], { encoding: 'utf8' });
+  assert.equal(res.status, 2);
+  assert.ok(res.stderr.includes('scripts/broken.js'), res.stderr);
+  assert.match(res.stderr, /:\d+:/, 'line number present');
+});
+
+test('CLI: --dry-run writes nothing', () => {
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'out');
+  const res = spawnSync(process.execPath, [CLI, path.join(root, 'example'), out, '--dry-run'], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+  assert.ok(res.stdout.includes('"level"'), 'report printed to stdout');
+  assert.equal(fs.existsSync(out), false, 'no output directory created');
+});
+
+test('CLI: --only restricts to the named transforms', () => {
+  const input = mkPack({ 'scripts/main.js': "export const a = 1 + 2;\nexport const b = 'x' + 'y';\n" });
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'out');
+  const res = spawnSync(process.execPath, [CLI, input, out, '--only', 'for-of-to-indexed', '--report', path.join(out, 'r.json')], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+  const outCode = fs.readFileSync(path.join(out, 'scripts/main.js'), 'utf8');
+  assert.ok(outCode.includes('1 + 2'), 'const-fold excluded');
+});
+
+test('CLI: --except disables a transform', () => {
+  const input = mkPack({ 'scripts/main.js': "export const a = 1 + 2;\n" });
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'out');
+  const res = spawnSync(process.execPath, [CLI, input, out, '--except', 'const-fold', '--report', path.join(out, 'r.json')], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+  assert.ok(fs.readFileSync(path.join(out, 'scripts/main.js'), 'utf8').includes('1 + 2'));
+});
+
+test('CLI: --diff prints unified diffs', () => {
+  const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'out');
+  const res = spawnSync(process.execPath, [CLI, path.join(root, 'example'), out, '--diff', '--report', path.join(out, 'r.json')], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+  assert.ok(res.stdout.includes('--- a/scripts/main.js'), 'diff header present');
+  assert.ok(res.stdout.includes('@@'), 'hunk headers present');
+});
+
+test('CLI: --level safe skips balanced passes', () => {
+  const input = mkPack({
+    'scripts/main.js': [
+      "import { world, system } from '@minecraft/server';",
+      'function onTick(player) {',
+      '  const a = player.location.x;',
+      '  const b = player.location.x;',
+      "  world.sendMessage('' + (a + b));",
+      '}',
+      'system.runInterval(onTick, 20);',
+    ].join('\n'),
+  });
+  const outSafe = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-out-')), 'safe');
+  spawnSync(process.execPath, [CLI, input, outSafe, '--level', 'safe', '--report', path.join(outSafe, 'r.json')], { encoding: 'utf8' });
+  const safeCode = fs.readFileSync(path.join(outSafe, 'scripts/main.js'), 'utf8');
+  assert.ok(safeCode.includes('player.location.x'), 'B1 did not run at safe level');
+});
+
+test('CLI: risky passes only run at risky level or explicit config', () => {
+  const src = [
+    "import { world, system } from '@minecraft/server';",
+    "const CFG = JSON.parse('{\"n\":1}');",
+    'function onTick(player) {',
+    "  world.sendMessage('' + CFG.n + player.id);",
+    '}',
+    'system.runInterval(onTick, 20);',
+  ].join('\n');
+  const balanced = transformSource('t.js', src, cfg({ level: 'balanced' }));
+  assert.ok(balanced.code.includes('JSON.parse'), 'R2 did not run at balanced');
+  const risky = transformSource('t.js', src, cfg({ level: 'risky' }));
+  assert.ok(risky.code.includes('_opJson'), 'R2 ran at risky level');
+  assert.ok(risky.fileReport.warnings >= 1, 'R2 emitted a warning');
+  const explicit = transformSource('t.js', src, cfg({ level: 'safe', transforms: { 'json-fold': true } }));
+  assert.ok(explicit.code.includes('_opJson'), 'R2 ran via explicit config');
+});

package/test/json-fold/config.json

@@ -0,0 +1 @@
+{"level": "risky"}

package/test/json-fold/expected.js

@@ -0,0 +1,14 @@
+// R2: JSON.parse on a constant string folded to a module const (risky).
+import { world } from '@minecraft/server';
+const _opJson = JSON.parse('{"region":"eu","retries":3,"features":["a","b"]}');
+export function describeConfig() {
+  return _opJson.region + ':' + _opJson.retries + ':' + _opJson.features.length;
+}
+
+// Reassignment of the parsed object: bails.
+const MUT = JSON.parse('{"n":1}');
+export function bump() {
+  MUT.n = 2;
+  return MUT.n;
+}
+world.sendMessage(describeConfig());

package/test/json-fold/expects.json

@@ -0,0 +1,12 @@
+{
+    "bails":  [
+                  {
+                      "transform":  "R2",
+                      "reasonContains":  "property of the parsed object is written"
+                  }
+              ],
+    "warnings":  1,
+    "transforms":  {
+                       "json-fold":  1
+                   }
+}

package/test/json-fold/input.js

@@ -0,0 +1,17 @@
+// R2: JSON.parse on a constant string folded to a module const (risky).
+import { world } from '@minecraft/server';
+
+const CONFIG = JSON.parse('{"region":"eu","retries":3,"features":["a","b"]}');
+
+export function describeConfig() {
+  return CONFIG.region + ':' + CONFIG.retries + ':' + CONFIG.features.length;
+}
+
+// Reassignment of the parsed object: bails.
+const MUT = JSON.parse('{"n":1}');
+export function bump() {
+  MUT.n = 2;
+  return MUT.n;
+}
+
+world.sendMessage(describeConfig());