optipack 0.0.0-stage → 1.0.1

package/src/diff.js

@@ -0,0 +1,108 @@
+/**
+ * Minimal dependency-free unified diff (line based, LCS). Deterministic.
+ * Used by `optipack --diff`.
+ */
+
+export function splitLines(text) {
+  const lines = text.split('\n');
+  // A trailing newline produces a final empty element; drop it for diffing.
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+function lcsTable(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = new Array((n + 1) * (m + 1)).fill(0);
+  const at = (i, j) => dp[i * (m + 1) + j];
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i * (m + 1) + j] = a[i] === b[j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
+    }
+  }
+  return at;
+}
+
+/**
+ * Compute ops: [{type: 'eq'|'del'|'add', aLine, bLine, text}]
+ */
+export function diffLines(a, b) {
+  const A = splitLines(a);
+  const B = splitLines(b);
+  const at = lcsTable(A, B);
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < A.length && j < B.length) {
+    if (A[i] === B[j]) {
+      ops.push({ type: 'eq', aLine: i + 1, bLine: j + 1, text: A[i] });
+      i++; j++;
+    } else if (at(i + 1, j) >= at(i, j + 1)) {
+      ops.push({ type: 'del', aLine: i + 1, bLine: j + 1, text: A[i] });
+      i++;
+    } else {
+      ops.push({ type: 'add', aLine: i + 1, bLine: j + 1, text: B[j] });
+      j++;
+    }
+  }
+  while (i < A.length) ops.push({ type: 'del', aLine: i + 1, bLine: j + 1, text: A[i++] });
+  while (j < B.length) ops.push({ type: 'add', aLine: i + 1, bLine: j + 1, text: B[j++] });
+  return ops;
+}
+
+/**
+ * Render a unified diff for one file. Returns '' when there are no changes.
+ */
+export function unifiedDiff(fileA, fileB, aText, bText, contextLines = 3) {
+  const ops = diffLines(aText, bText);
+  if (ops.every((o) => o.type === 'eq')) return '';
+  const out = [];
+  out.push(`--- a/${fileA}`);
+  out.push(`+++ b/${fileB}`);
+  // Group into hunks.
+  let idx = 0;
+  while (idx < ops.length) {
+    if (ops[idx].type === 'eq') { idx++; continue; }
+    // Find hunk start: back up `contextLines` eq ops.
+    let start = idx;
+    let ctxBefore = 0;
+    while (start > 0 && ops[start - 1].type === 'eq' && ctxBefore < contextLines) { start--; ctxBefore++; }
+    // Extend hunk end while changes or within context of next change.
+    let end = idx;
+    let pendingEq = 0;
+    let k = idx;
+    while (k < ops.length) {
+      if (ops[k].type !== 'eq') { end = k; pendingEq = 0; k++; }
+      else {
+        pendingEq++;
+        if (pendingEq > contextLines * 2) break;
+        end = k;
+        k++;
+      }
+    }
+    // Trim trailing eq to contextLines.
+    let endTrim = end;
+    let ctxAfter = 0;
+    while (endTrim > start && ops[endTrim].type === 'eq' && ctxAfter < contextLines) { endTrim--; ctxAfter++; }
+    endTrim = Math.min(end, endTrim + (ops[endTrim] && ops[endTrim].type === 'eq' ? 0 : 0));
+    // hunk = ops[start..endTrim]
+    const hunk = ops.slice(start, endTrim + 1);
+    const aStart = hunk[0].aLine;
+    const bStart = hunk[0].bLine;
+    let aCount = 0;
+    let bCount = 0;
+    for (const o of hunk) {
+      if (o.type !== 'add') aCount++;
+      if (o.type !== 'del') bCount++;
+    }
+    out.push(`@@ -${aStart},${aCount} +${bStart},${bCount} @@`);
+    for (const o of hunk) {
+      if (o.type === 'eq') out.push(' ' + o.text);
+      else if (o.type === 'del') out.push('-' + o.text);
+      else out.push('+' + o.text);
+    }
+    idx = endTrim + 1;
+    while (idx < ops.length && ops[idx].type === 'eq') idx++;
+  }
+  return out.join('\n') + '\n';
+}

package/src/harness/driver.js

@@ -0,0 +1,216 @@
+/**
+ * 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));
+
+/** Register the ESM loader hooks (idempotent). Only needed for variant loading. */
+export function ensureHooks() {
+  if (!globalThis.__opkHooksRegistered) {
+    register(
+      pathToFileURL(path.join(here, 'loader-hooks.mjs')).href,
+      pathToFileURL(path.join(here, 'driver.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,
+    counters: {},
+  };
+  r.count = (kind, n = 1) => {
+    r.counters[kind] = (r.counters[kind] || 0) + n;
+  };
+  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}/{__dimension}/{__block} markers in a payload with live mock objects. */
+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;
+  }
+  if (typeof value.__dimension === 'string') {
+    if (!globalThis.__opkMakeDimension) throw new Error('hydrate __dimension: server mock not loaded');
+    return globalThis.__opkMakeDimension(value.__dimension);
+  }
+  if (value.__block) {
+    if (!globalThis.__opkMakeBlock) throw new Error('hydrate __block: server mock not loaded');
+    return globalThis.__opkMakeBlock(hydrate(value.__block.location, rec), value.__block.dimension);
+  }
+  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 = [] }) {
+  ensureHooks();
+  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 === 'fireMany') {
+        for (let i = 0; i < (step.count || 1); i++) 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('../config.js');
+  const { runPack } = await import('../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/src/harness/loader-hooks.mjs

@@ -0,0 +1,63 @@
+/**
+ * Node module loader hooks for differential testing.
+ *
+ * - `@minecraft/*` runtime modules resolve to harness mocks under
+ *   test/mock/@minecraft/ (single instances; the recorder is passed via
+ *   globalThis.__opkRecorder). @minecraft/server and @minecraft/server-ui
+ *   have functional mocks; the remaining runtime modules have permissive
+ *   stubs generated from their real type definitions.
+ * - Pack files are loaded with a `?opkv=<variant>` query so the original and
+ *   optimized variants get separate ESM cache entries; the query is stripped
+ *   when reading from disk and propagated to relative imports.
+ */
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const mockDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'mock', '@minecraft');
+
+// Functional mocks.
+const FUNCTIONAL = new Set(['@minecraft/server', '@minecraft/server-ui']);
+
+// Permissive stubs generated from each module's real index.d.ts.
+const STUBBED = new Set([
+  '@minecraft/common',
+  '@minecraft/debug-utilities',
+  '@minecraft/diagnostics',
+  '@minecraft/server-admin',
+  '@minecraft/server-editor',
+  '@minecraft/server-gametest',
+  '@minecraft/server-graphics',
+  '@minecraft/server-net',
+]);
+
+const MOCK_URLS = new Map([
+  ['@minecraft/server', pathToFileURL(path.join(mockDir, 'server.mjs')).href],
+  ['@minecraft/server-ui', pathToFileURL(path.join(mockDir, 'server-ui.mjs')).href],
+  ...[...STUBBED].map((name) => [
+    name,
+    pathToFileURL(path.join(mockDir, name.replace('@minecraft/', '').replace(/\//g, '-') + '.mjs')).href,
+  ]),
+]);
+
+export async function resolve(specifier, context, nextResolve) {
+  if (MOCK_URLS.has(specifier)) {
+    return { url: MOCK_URLS.get(specifier), shortCircuit: true };
+  }
+  const res = await nextResolve(specifier, context);
+  const parentURL = context.parentURL || '';
+  if (parentURL.includes('opkv=') && res.url.startsWith('file:') && !res.url.includes('opkv=')) {
+    const q = new URL(parentURL).search;
+    return { ...res, url: res.url + q, shortCircuit: true };
+  }
+  return res;
+}
+
+export async function load(url, context, nextLoad) {
+  const u = new URL(url);
+  if (u.protocol === 'file:' && u.search) {
+    const clean = pathToFileURL(fileURLToPath(u)).href;
+    const r = await nextLoad(clean, context);
+    return { format: r.format || 'module', source: r.source, shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/src/harness/mock/@minecraft/common.mjs

@@ -0,0 +1,17 @@
+/**
+ * Permissive stub of @minecraft/common@1.3.0 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const ArgumentOutOfBoundsError = permissive('common.ArgumentOutOfBoundsError');
+export const ContainerSizeOutOfBoundsError = permissive('common.ContainerSizeOutOfBoundsError');
+export const EngineError = permissive('common.EngineError');
+export const InvalidArgumentError = permissive('common.InvalidArgumentError');
+export const InvalidArgumentErrorType = permissive('common.InvalidArgumentErrorType');
+export const PropertyOutOfBoundsError = permissive('common.PropertyOutOfBoundsError');
+export const RuntimeConditionError = permissive('common.RuntimeConditionError');
+export const UnsupportedFunctionalityError = permissive('common.UnsupportedFunctionalityError');

package/src/harness/mock/@minecraft/debug-utilities.mjs

@@ -0,0 +1,10 @@
+/**
+ * Permissive stub of @minecraft/debug-utilities@1.0.0-beta.1.20.70-preview.20 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const disableWatchdog = permissive('debug-utilities.disableWatchdog');

package/src/harness/mock/@minecraft/diagnostics.mjs

@@ -0,0 +1,14 @@
+/**
+ * Permissive stub of @minecraft/diagnostics@1.0.0-beta.1.21.70-preview.22 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const Sentry = permissive('diagnostics.Sentry');
+export const SentryAlreadyInitializedError = permissive('diagnostics.SentryAlreadyInitializedError');
+export const SentryBreadcrumbLevel = permissive('diagnostics.SentryBreadcrumbLevel');
+export const SentryUninitializedError = permissive('diagnostics.SentryUninitializedError');
+export const sentry = permissive('diagnostics.sentry');

package/src/harness/mock/@minecraft/server-admin.mjs

@@ -0,0 +1,14 @@
+/**
+ * Permissive stub of @minecraft/server-admin@1.0.0-beta.11940b24 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const SecretString = permissive('server-admin.SecretString');
+export const ServerSecrets = permissive('server-admin.ServerSecrets');
+export const ServerVariables = permissive('server-admin.ServerVariables');
+export const secrets = permissive('server-admin.secrets');
+export const variables = permissive('server-admin.variables');

package/src/harness/mock/@minecraft/server-editor.mjs

@@ -0,0 +1,39 @@
+/**
+ * Permissive stub of @minecraft/server-editor@0.1.0-beta.1.20.20-preview.20 for the differential harness.
+ * Generated from the module's real index.d.ts (see test/update-mock-stubs.mjs).
+ * Every runtime export is a permissive value: callable, constructable, and
+ * chainable; calls and constructions record harness effects so differential
+ * equivalence holds. NOT a behavioral model of the engine module.
+ */
+import { permissive } from '../permissive.mjs';
+
+export const ActionTypes = permissive('server-editor.ActionTypes');
+export const BedrockEventSubscriptionCache = permissive('server-editor.BedrockEventSubscriptionCache');
+export const ClipboardItem = permissive('server-editor.ClipboardItem');
+export const ClipboardManager = permissive('server-editor.ClipboardManager');
+export const ClipboardMirrorAxis = permissive('server-editor.ClipboardMirrorAxis');
+export const ClipboardRotation = permissive('server-editor.ClipboardRotation');
+export const Cursor = permissive('server-editor.Cursor');
+export const CursorControlMode = permissive('server-editor.CursorControlMode');
+export const CursorTargetMode = permissive('server-editor.CursorTargetMode');
+export const EDITOR_PANE_PROPERTY_ITEM_TYPE = permissive('server-editor.EDITOR_PANE_PROPERTY_ITEM_TYPE');
+export const EditorInputContext = permissive('server-editor.EditorInputContext');
+export const EditorStatusBarAlignment = permissive('server-editor.EditorStatusBarAlignment');
+export const Extension = permissive('server-editor.Extension');
+export const ExtensionContext = permissive('server-editor.ExtensionContext');
+export const InputModifier = permissive('server-editor.InputModifier');
+export const KeyInputType = permissive('server-editor.KeyInputType');
+export const KeyboardKey = permissive('server-editor.KeyboardKey');
+export const Logger = permissive('server-editor.Logger');
+export const MinecraftEditor = permissive('server-editor.MinecraftEditor');
+export const MouseActionCategory = permissive('server-editor.MouseActionCategory');
+export const MouseActionType = permissive('server-editor.MouseActionType');
+export const MouseInputType = permissive('server-editor.MouseInputType');
+export const Selection = permissive('server-editor.Selection');
+export const SelectionManager = permissive('server-editor.SelectionManager');
+export const TransactionManager = permissive('server-editor.TransactionManager');
+export const bindDataSource = permissive('server-editor.bindDataSource');
+export const editor = permissive('server-editor.editor');
+export const executeLargeOperation = permissive('server-editor.executeLargeOperation');
+export const getLocalizationId = permissive('server-editor.getLocalizationId');
+export const registerEditorExtension = permissive('server-editor.registerEditorExtension');