optipack 0.0.0-stage → 1.0.0

package/test/example.test.mjs

@@ -0,0 +1,115 @@
+/**
+ * Example pack end-to-end: run the CLI over example/, verify parse validity,
+ * manifest fidelity, effects-equivalence across the whole script graph, report
+ * snapshot, and 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 { 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 EXAMPLE = path.join(root, 'example');
+
+function mkOut(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+test('example: CLI produces a valid optimized pack + report', async () => {
+  const out = mkOut('optipack-example-');
+  const res = spawnSync(process.execPath, [CLI, EXAMPLE, out], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+
+  // Manifest and non-scripts copied verbatim.
+  assert.equal(
+    fs.readFileSync(path.join(out, 'manifest.json'), 'utf8'),
+    fs.readFileSync(path.join(EXAMPLE, 'manifest.json'), 'utf8')
+  );
+
+  // Report exists with the expected schema shape.
+  const report = JSON.parse(fs.readFileSync(path.join(out, 'optipack-report.json'), 'utf8'));
+  assert.equal(report.level, 'balanced');
+  assert.ok(Array.isArray(report.files) && report.files.length === 3);
+  assert.ok(report.files.every((f) => f.path.startsWith('scripts/')));
+  assert.ok(report.totals.transforms > 0, 'transforms applied');
+  for (const f of report.files) {
+    for (const key of ['path', 'hotFunctions', 'transforms', 'bails', 'lint', 'residualAllocs', 'bytes']) {
+      assert.ok(key in f, `report file has ${key}`);
+    }
+    assert.ok(f.bytes.after > 0);
+  }
+
+  // Every output script re-parses as ESM.
+  const { parseSource } = await import('../src/pipeline.js');
+  for (const f of ['scripts/main.js', 'scripts/util.js', 'scripts/drops.js']) {
+    const src = fs.readFileSync(path.join(out, f), 'utf8');
+    assert.doesNotThrow(() => parseSource(f, src), `${f} round-trips`);
+  }
+});
+
+test('example: effects-equivalence across the whole script graph', async () => {
+  const out = mkOut('optipack-example-');
+  const res = spawnSync(process.execPath, [CLI, EXAMPLE, out], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+
+  const { runVariant, assertSameEffects, pathToUrl } = await import('./harness/setup.js');
+  const scenario = {
+    reads: {
+      'location:p1': [{ x: 10, y: 64, z: 20 }, { x: 12, y: 65, z: 22 }],
+      'name:p1': ['Alex'],
+      'dp:p1:optipack:lastDist': [undefined],
+      'dp:p1:optipack:baseline': [undefined],
+      'dp:p1:optipack:drops': [undefined],
+      'world.dp:scan:0': [0],
+      'world.dp:scan:1': [0],
+      'world.dp:scan:2': [0],
+      'world.dp:scan:3': [0],
+    },
+    state: { players: [{ id: 'p1' }] },
+    steps: [
+      { op: 'fire', event: 'world.afterEvents.worldLoad', payload: {} },
+      { op: 'tick', n: 60 },
+      { op: 'fire', event: 'world.afterEvents.playerSpawn', payload: { player: { __entity: 'p1' } } },
+      { op: 'tick', n: 40 },
+    ],
+  };
+
+  const a = await runVariant(pathToUrl(path.join(EXAMPLE, 'scripts', 'main.js')), 'orig', scenario);
+  const b = await runVariant(pathToUrl(path.join(out, 'scripts', 'main.js')), 'opt', scenario);
+  assertSameEffects(a, b, 'example pack');
+  assert.ok(a.effects.length > 10, 'scenario exercised real effects');
+});
+
+test('example: report snapshot is stable', () => {
+  const out = mkOut('optipack-example-');
+  const res = spawnSync(process.execPath, [CLI, EXAMPLE, out, '--report', path.join(out, 'r.json')], { encoding: 'utf8' });
+  assert.equal(res.status, 0, res.stderr);
+  const actual = fs.readFileSync(path.join(out, 'r.json'), 'utf8');
+  const snapshotPath = path.join(here, 'example-report-snapshot.json');
+  if (process.env.UPDATE_SNAPSHOT) {
+    fs.writeFileSync(snapshotPath, actual);
+  }
+  assert.ok(fs.existsSync(snapshotPath), 'snapshot exists (run npm run update-snapshot)');
+  const expected = JSON.parse(fs.readFileSync(snapshotPath, 'utf8'));
+  const got = JSON.parse(actual);
+  assert.deepEqual(got, expected, 'report matches snapshot');
+});
+
+test('example: deterministic output — two runs are byte-identical', () => {
+  const out1 = mkOut('optipack-det1-');
+  const out2 = mkOut('optipack-det2-');
+  spawnSync(process.execPath, [CLI, EXAMPLE, out1], { encoding: 'utf8' });
+  spawnSync(process.execPath, [CLI, EXAMPLE, out2], { encoding: 'utf8' });
+  for (const f of ['scripts/main.js', 'scripts/util.js', 'scripts/drops.js', 'optipack-report.json']) {
+    assert.equal(
+      fs.readFileSync(path.join(out1, f), 'utf8'),
+      fs.readFileSync(path.join(out2, f), 'utf8'),
+      `${f} identical across runs`
+    );
+  }
+});

package/test/for-of-to-indexed/expected.js

@@ -0,0 +1,59 @@
+// S4: for-of conversion over provably-array iterables.
+const names = ['a', 'b', 'c'];
+export function sumLengths() {
+  let n = 0;
+  for (let _opI = 0; _opI < names.length; _opI++) {
+    const v = names[_opI];
+    {
+      n += v.length;
+    }
+  }
+  return n;
+}
+export function letters() {
+  let s = 0;
+  {
+    const _opArr = 'hello'.split('');
+    for (let _opI2 = 0; _opI2 < _opArr.length; _opI2++) {
+      const ch = _opArr[_opI2];
+      {
+        if (ch === 'l') s += 1;
+      }
+    }
+  }
+  return s;
+}
+export function mapped() {
+  const vals = ['a', 'bb'].map(v => v + '!');
+  let out = 0;
+  for (let _opI3 = 0; _opI3 < vals.length; _opI3++) {
+    const v = vals[_opI3];
+    {
+      out += v.length;
+    }
+  }
+  return out;
+}
+export function withDestructure(pairs) {
+  const entries = Object.entries({
+    a: 1,
+    b: 2
+  });
+  let total = 0;
+  for (let _opI4 = 0; _opI4 < entries.length; _opI4++) {
+    const _opEl = entries[_opI4];
+    const k = _opEl[0];
+    const v = _opEl[1];
+    {
+      total += v;
+    }
+  }
+  return total;
+}
+
+// Host returns are never converted (bail).
+export function hostIter(players) {
+  for (const p of players) {
+    p.x = 1;
+  }
+}

package/test/for-of-to-indexed/expects.json

@@ -0,0 +1,11 @@
+{
+    "transforms":  {
+                       "for-of-to-indexed":  4
+                   },
+    "bails":  [
+                  {
+                      "transform":  "S4",
+                      "reasonContains":  "not provably an array"
+                  }
+              ]
+}

package/test/for-of-to-indexed/input.js

@@ -0,0 +1,43 @@
+// S4: for-of conversion over provably-array iterables.
+const names = ['a', 'b', 'c'];
+
+export function sumLengths() {
+  let n = 0;
+  for (const v of names) {
+    n += v.length;
+  }
+  return n;
+}
+
+export function letters() {
+  let s = 0;
+  for (const ch of 'hello'.split('')) {
+    if (ch === 'l') s += 1;
+  }
+  return s;
+}
+
+export function mapped() {
+  const vals = ['a', 'bb'].map((v) => v + '!');
+  let out = 0;
+  for (const v of vals) {
+    out += v.length;
+  }
+  return out;
+}
+
+export function withDestructure(pairs) {
+  const entries = Object.entries({ a: 1, b: 2 });
+  let total = 0;
+  for (const [k, v] of entries) {
+    total += v;
+  }
+  return total;
+}
+
+// Host returns are never converted (bail).
+export function hostIter(players) {
+  for (const p of players) {
+    p.x = 1;
+  }
+}

package/test/for-of-to-indexed-bail/expected.js

@@ -0,0 +1,25 @@
+// S4 bails: Map/Set/strings/host returns are never converted.
+const m = new Map();
+export function mapIter(m2) {
+  for (const [k, v] of m2) {
+    m.set(k, v);
+  }
+}
+export function stringIter(s) {
+  let n = 0;
+  for (const ch of s) {
+    n += 1;
+  }
+  return n;
+}
+export function hostReturns(players) {
+  for (const p of worldPlayers()) {
+    p.ping = 1;
+  }
+  for (const p of players) {
+    p.pong = 2;
+  }
+}
+function worldPlayers() {
+  return [];
+}

package/test/for-of-to-indexed-bail/expects.json

@@ -0,0 +1,11 @@
+{
+    "transforms":  {
+                       "for-of-to-indexed":  0
+                   },
+    "bails":  [
+                  {
+                      "transform":  "S4",
+                      "reasonContains":  "not provably an array"
+                  }
+              ]
+}

package/test/for-of-to-indexed-bail/input.js

@@ -0,0 +1,29 @@
+// S4 bails: Map/Set/strings/host returns are never converted.
+const m = new Map();
+
+export function mapIter(m2) {
+  for (const [k, v] of m2) {
+    m.set(k, v);
+  }
+}
+
+export function stringIter(s) {
+  let n = 0;
+  for (const ch of s) {
+    n += 1;
+  }
+  return n;
+}
+
+export function hostReturns(players) {
+  for (const p of worldPlayers()) {
+    p.ping = 1;
+  }
+  for (const p of players) {
+    p.pong = 2;
+  }
+}
+
+function worldPlayers() {
+  return [];
+}

package/test/gen-expected.mjs

@@ -0,0 +1,33 @@
+// One-off helper: generate expected.js for every fixture that lacks one.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = here; // fixtures live directly under test/
+
+const { normalizeConfig } = await import('../src/config.js');
+const { transformSource } = await import('../src/pipeline.js');
+
+const dirs = fs.readdirSync(root, { withFileTypes: true })
+  .filter((e) => e.isDirectory() && fs.existsSync(path.join(root, e.name, 'input.js')))
+  .map((e) => e.name)
+  .sort();
+
+const only = process.argv[2] || null;
+for (const dir of dirs) {
+  if (only && dir !== only) continue;
+  const fdir = path.join(root, dir);
+  if (fs.existsSync(path.join(fdir, 'expected.js'))) continue;
+  const input = fs.readFileSync(path.join(fdir, 'input.js'), 'utf8');
+  const configPath = path.join(fdir, 'config.json');
+  const raw = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, 'utf8')) : { level: 'balanced' };
+  const cfg = normalizeConfig(raw);
+  try {
+    const { code, fileReport } = transformSource('input.js', input, cfg);
+    fs.writeFileSync(path.join(fdir, 'expected.js'), code);
+    console.log(`${dir}: generated (${Object.keys(fileReport.transforms).join(', ') || 'no transforms'})`);
+  } catch (e) {
+    console.error(`${dir}: FAILED: ${e.message}`);
+  }
+}

package/test/getter-cache-cross-barrier/config.json

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

package/test/getter-cache-cross-barrier/expected.js

@@ -0,0 +1,10 @@
+// R4: getter caching across call barriers (risky).
+import { world, system } from '@minecraft/server';
+function onTick(player) {
+  const _opC = player.location.x;
+  const before = _opC;
+  world.sendMessage('moving'); // call barrier — B1 would bail, R4 crosses it
+  const after = _opC;
+  world.sendMessage('moved=' + (after - before));
+}
+system.runInterval(() => onTick(world.getAllPlayers()[0]), 20);

package/test/getter-cache-cross-barrier/expects.json

@@ -0,0 +1,6 @@
+{
+    "warnings":  1,
+    "transforms":  {
+                       "getter-cache-cross-barrier":  1
+                   }
+}

package/test/getter-cache-cross-barrier/input.js

@@ -0,0 +1,11 @@
+// R4: getter caching across call barriers (risky).
+import { world, system } from '@minecraft/server';
+
+function onTick(player) {
+  const before = player.location.x;
+  world.sendMessage('moving'); // call barrier — B1 would bail, R4 crosses it
+  const after = player.location.x;
+  world.sendMessage('moved=' + (after - before));
+}
+
+system.runInterval(() => onTick(world.getAllPlayers()[0]), 20);

package/test/getter-cache-cross-barrier/scenario.json

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

package/test/harness/fixture.js

@@ -0,0 +1,117 @@
+/**
+ * Fixture runner for per-transform unit tests.
+ *
+ * A fixture directory contains:
+ *   input.js     — source fed through the full pipeline
+ *   expected.js  — (optional) exact expected output; when absent the input
+ *                  must come out unchanged (bail fixtures)
+ *   config.json  — (optional) { level, transforms, hotPath, lint } user config
+ *   expects.json — (optional) assertions on the report:
+ *                  { transforms: {id: count}, bails: [{transform, reasonContains}],
+ *                    lint: [{rule}], warnings: n }
+ *   scenario.json— (optional) differential scenario { entry, reads, state, steps }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export async function runFixtureDir(dir) {
+  const inputPath = path.join(dir, 'input.js');
+  const input = fs.readFileSync(inputPath, 'utf8');
+  const expectedPath = path.join(dir, 'expected.js');
+  const hasExpected = fs.existsSync(expectedPath);
+  const expected = hasExpected ? fs.readFileSync(expectedPath, 'utf8') : null;
+
+  const configPath = path.join(dir, 'config.json');
+  const config = fs.existsSync(configPath)
+    ? JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, ''))
+    : { level: 'balanced' };
+
+  const expectsPath = path.join(dir, 'expects.json');
+  const expects = fs.existsSync(expectsPath) ? JSON.parse(fs.readFileSync(expectsPath, 'utf8')) : null;
+
+  const scenarioPath = path.join(dir, 'scenario.json');
+  const scenario = fs.existsSync(scenarioPath) ? JSON.parse(fs.readFileSync(scenarioPath, 'utf8')) : null;
+
+  const { normalizeConfig } = await import('../../src/config.js');
+  const { runPack } = await import('../../src/pipeline.js');
+
+  const inputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-fx-in-'));
+  const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'optipack-fx-out-'));
+  fs.mkdirSync(path.join(inputDir, 'scripts'), { recursive: true });
+  fs.writeFileSync(path.join(inputDir, 'scripts', 'input.js'), input);
+  const cfg = normalizeConfig(config);
+  const report = runPack(inputDir, outputDir, cfg);
+  const output = fs.readFileSync(path.join(outputDir, 'scripts', 'input.js'), 'utf8');
+
+  const result = { input, output, expected, report, expects, scenario, outputDir, config: cfg };
+
+  // Exact output comparison.
+  const want = hasExpected ? expected : input;
+  const got = output.replace(/\r\n/g, '\n');
+  const wantNorm = want.replace(/\r\n/g, '\n');
+  if (got !== wantNorm) {
+    throw new Error(
+      `fixture output mismatch for ${path.basename(dir)}:\n` +
+      `--- expected ---\n${wantNorm}\n--- actual ---\n${got}`
+    );
+  }
+
+  // Report expectations.
+  if (expects) {
+    const file = report.files[0];
+    if (expects.transforms) {
+      for (const [id, count] of Object.entries(expects.transforms)) {
+        const gotCount = (file.transforms[id] || 0);
+        if (gotCount !== count) {
+          throw new Error(`fixture ${path.basename(dir)}: expected ${count} of ${id}, got ${gotCount}`);
+        }
+      }
+    }
+    if (expects.noTransforms) {
+      const total = Object.values(file.transforms).reduce((a, b) => a + b, 0);
+      if (total !== 0) {
+        throw new Error(`fixture ${path.basename(dir)}: expected no transforms, got ${JSON.stringify(file.transforms)}`);
+      }
+    }
+    if (expects.bails) {
+      for (const wantBail of expects.bails) {
+        const found = file.bails.find((b) =>
+          b.transform === wantBail.transform &&
+          (wantBail.reasonContains === undefined || b.reason.includes(wantBail.reasonContains)) &&
+          (wantBail.line === undefined || b.line === wantBail.line));
+        if (!found) {
+          throw new Error(`fixture ${path.basename(dir)}: expected bail ${JSON.stringify(wantBail)}, have ${JSON.stringify(file.bails)}`);
+        }
+      }
+    }
+    if (expects.lint) {
+      for (const wantLint of expects.lint) {
+        const found = file.lint.find((l) => l.rule === wantLint.rule &&
+          (wantLint.line === undefined || l.line === wantLint.line));
+        if (!found) {
+          throw new Error(`fixture ${path.basename(dir)}: expected lint ${JSON.stringify(wantLint)}, have ${JSON.stringify(file.lint)}`);
+        }
+      }
+    }
+    if (expects.warnings !== undefined) {
+      if (report.warnings.length !== expects.warnings) {
+        throw new Error(`fixture ${path.basename(dir)}: expected ${expects.warnings} warnings, got ${report.warnings.length}`);
+      }
+    }
+    if (expects.hotFunctions !== undefined) {
+      if (file.hotFunctions !== expects.hotFunctions) {
+        throw new Error(`fixture ${path.basename(dir)}: expected ${expects.hotFunctions} hot functions, got ${file.hotFunctions}`);
+      }
+    }
+  }
+
+  return result;
+}
+
+export function fixtureDirs(baseDir) {
+  return fs.readdirSync(baseDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(baseDir, e.name, 'input.js')))
+    .map((e) => path.join(baseDir, e.name))
+    .sort();
+}