optipack 0.0.0-stage → 1.0.1

package/BENCHMARKING.md

@@ -0,0 +1,127 @@
+# Benchmarking optipack
+
+Two complementary ways to measure what optipack actually buys you.
+
+## 1. Automated A/B (`optipack bench`) — engine-independent crossing counts
+
+```bash
+optipack bench <packDir> [--ticks N] [--scenario file.json] [--level safe|balanced|risky] [--json out.json]
+```
+
+Builds the optimized pack, then runs the **original** and **optimized** scripts
+side by side under the harness mock for N simulated ticks with identical
+scenario input, and reports:
+
+- **Host-boundary crossings by kind** — the number of `player.location` reads,
+  `getComponent()` calls, `getDynamicProperty()` calls, `getEntities()` sweeps,
+  etc. This is the metric optipack exists to reduce, and it is
+  **engine-independent**: a crossing is a crossing in V8 (the test harness) or
+  QuickJS (the game).
+- **Wall time per tick** — *indicative only*. The harness runs in Node (V8, with
+  a JIT); Minecraft runs QuickJS (interpreter, no JIT). Use the in-game
+  workflow below for authoritative numbers.
+- **Effect-trace equality** — if the two builds diverge behaviorally, the bench
+  is flagged invalid (`exit code 1`).
+
+Example (real output over 147 community scripts from JaylyDev/ScriptAPI):
+
+```
+optipack bench — test/corpus/jayly-pack (entry scripts/main.js, 100 ticks, level risky)
+  boundary crossing      original  optimized  delta
+  boundary.getBlock            29         29  0%
+  boundary.getComponent       400        202  -49%
+  boundary.getPlayers         206        206  0%
+  boundary.location            20         10  -50%
+  TOTAL                       655        447  -32%
+  transforms applied: 97
+  wall (indicative, Node/V8): original 6.5ms (65µs/tick), optimized 6.4ms (64µs/tick)
+```
+
+Read it as: at `--level risky`, R1's cross-tick component cache halves
+`getComponent` crossings and S7/B1 halve location reads, with identical
+behavior verified. At `balanced`, crossings stay flat on this corpus because
+its hot paths are call-dominated (caching those is exactly what R1 opts into).
+
+Scenario files drive events between ticks (`test/corpus/jayly-scenario.json`
+is an example): `{"reads": {...}, "state": {players: [{id: "p1"}]}, "steps":
+[{"op": "fire", "event": "world.afterEvents.worldLoad", "payload": {}},
+{"op": "fireMany", "event": "world.afterEvents.playerBreakBlock", "count": 30,
+"payload": {...}}, {"op": "tick", "n": 0}]}`. Payloads may reference mock
+objects with `{"__entity": "p1"}`, `{"__dimension": "minecraft:overworld"}`,
+or `{"__block": {"location": {...}, "dimension": "..."}}`.
+
+A real-world corpus of MIT-licensed community scripts is fetched with:
+
+```bash
+npm run fetch-corpus
+node bin/optipack.js bench test/corpus/jayly-pack --scenario test/corpus/jayly-scenario.json
+```
+
+## 2. In-game A/B with the script profiler — authoritative numbers
+
+The numbers that matter run on the real engine: **QuickJS inside Minecraft**,
+where the script watchdog and the server tick budget live. Bedrock ships a
+built-in script profiler.
+
+1. **Build both packs.** The original is just a copy (optipack always
+   optimizes):
+
+   ```powershell
+   # Windows
+   robocopy MyPack MyPack-original /E
+   optipack MyPack MyPack-optimized --level balanced
+   ```
+
+   ```bash
+   # Linux/macOS
+   cp -r MyPack MyPack-original
+   optipack MyPack MyPack-optimized --level balanced
+   ```
+
+2. **Install one pack** into your `development_behavior_packs` folder and apply
+   it to a test world (enable the required experiments if the pack needs them).
+
+3. **Profile a consistent play pattern.** In the world, run:
+
+   ```
+   /script profiler start
+   ```
+
+   exercise the same actions for a fixed period (e.g. 60 seconds of the same
+   movement/interactions, or a repeatable redstone/tick-driven scenario), then:
+
+   ```
+   /script profiler stop
+   ```
+
+   The profiler writes the execution profile to the content log (visible in
+   the in-game content log screen and in the world's log files under
+   `content_log/`).
+
+4. **Repeat with the other pack**, same actions, same duration.
+
+5. **Compare.** What to look for in the two profiles:
+   - total script time per tick / per frame;
+   - time in your hottest handlers (the profiler reports per-function costs);
+   - the count of host API calls attributed to your entry points.
+
+   optipack's transforms reduce *calls into the host* (location reads,
+   component queries, dynamic properties) and *allocations per tick*
+   (closures, form objects, intermediate strings) — those show up as smaller
+   per-function times and fewer API-call entries, without any behavioral
+   difference (which the harness already proved).
+
+6. **Send the logs back.** If you're reporting results, include both content
+   log profile sections (original + optimized), the optipack report JSON from
+   the optimized build, and the level you used. The structured
+   `optipack bench --json` output pairs well with this.
+
+### Notes and caveats
+
+- Enable the script watchdog thresholds or keep profiling sessions short —
+  a pathological pack can trip the watchdog during profiling; that itself is
+  useful signal.
+- Profile at least two sessions per variant and compare like with like (same
+  world, same player count, same actions). Entity counts dominate host costs.
+- `optipack bench` crossing counts are the cheapest regression signal for
+  CI; the in-game profiler is the ground truth for player-visible wins.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 optipack contributors
+
+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.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# optipack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A build-time optimizer for Minecraft Bedrock behavior-pack scripts.**
+
+Bedrock runs your scripts on QuickJS: an interpreter with no JIT, no escape analysis, and an expensive crossing every time script code touches the host (`player.location` allocates a fresh Vector3 *every read*). All of it shares one tick budget. optipack rewrites your `scripts/` folder with 16 semantics-preserving transforms that cut those crossings and per-tick allocations — and proves behavior is unchanged while doing it.
+
+```
+npm install -g optipack
+optipack MyPack MyPack-optimized
+```
+
+## Measured impact
+
+Host-boundary crossings before → after (engine-independent: identical in Node and in-game), with behavior verified identical by the test harness:
+
+| Benchmark | Level | Crossings | Top reduction |
+|---|---|---|---|
+| [example pack](example/) (300 ticks) | balanced | 237 → **177** (−25%) | `location` reads −50% |
+| [JaylyDev/ScriptAPI](https://github.com/JaylyDev/ScriptAPI) corpus, 147 real scripts | balanced | 655 → 655 (0%)¹ | — |
+| same corpus | risky | 655 → **447** (−32%) | `getComponent` −49%, `location` −50% |
+
+¹ *Honest number: this corpus's hot paths are call-dominated (`getComponent` every tick) — caching those is exactly the opt-in risky tier. Safe transforms only ever remove reads.*
+
+Reproduce with `optipack bench` (see [BENCHMARKING.md](BENCHMARKING.md)), which also covers the in-game `/script profiler` A/B workflow for authoritative QuickJS numbers.
+
+## How it works
+
+```
+optipack <inputPack> <outputPack> [--level safe|balanced|risky] [--diff] [--dry-run] [--only ids] [--except ids] [--report path]
+```
+
+- Only `scripts/**/*.js` is transformed; the manifest, JSON, functions, and textures are copied byte-for-byte. `import` declarations are never touched.
+- Every output file is re-parsed (valid ESM, ES2022-grade syntax — nothing is down-leveled, no bundling, no minification).
+- Same input + config → byte-identical output. Exit codes: `0` ok · `1` usage · `2` parse failure (file+line) · `3` internal error.
+
+```bash
+optipack bench <packDir> --level risky   # A/B benchmark: original vs optimized (see BENCHMARKING.md)
+```
+
+## The 16 transforms
+
+Passes run in order; each is an independent pass with an ID, a level, and strict bail conditions — when a site can't be proven safe, the pass **bails and records the reason** (line + reason in the report) instead of guessing.
+
+<details>
+<summary><strong>SAFE — provably behavior-identical (enabled at every level)</strong></summary>
+
+| ID | Name | What it does |
+|---|---|---|
+| S1 | `const-fold` | Folds literal arithmetic, string concat, `typeof`/`!` on literals, fully-literal templates, logical expressions with literal left side. Never across identifiers or calls. |
+| S2 | `dead-code` | Removes statements after `return`/`throw`/`break`/`continue`, constant branches, unused locals with pure initializers. |
+| S3 | `bool-simplify` | `x ? true : false` → `!!x`; `if (x) return true; else return false;` → `return !!x;`; `x === true` → `x` when statically boolean. |
+| S4 | `for-of-to-indexed` | `for (const v of it)` → indexed loop when `it` is *provably* an array (literal, `.map/.filter/.split`, `Object.entries`, …). Never on host returns, Map/Set, strings, generators. |
+| S5 | `array-methods-to-loops` | **Hot paths only.** Inline-arrow `.forEach/.map/.filter/.some/.every/.find` → indexed loops with exact per-method return semantics. |
+| S6 | `destructure-to-direct` | **Hot paths only.** `const { x, y } = obj` → `obj.x` reads at use sites (≤ 3 uses); defaults hoisted to an `if`. |
+| S7 | `hoist-invariant-members` | **Hot paths only.** Hoists loop-invariant host chains out of barrier-free loops — `total += chest.location.y` reads `chest.location` once instead of N times. |
+
+</details>
+
+<details>
+<summary><strong>BALANCED — per-site-checked assumptions (default level)</strong></summary>
+
+| ID | Name | What it does |
+|---|---|---|
+| B1 | `cache-getter-chains` | Repeated identical host chains in barrier-free regions → one hoisted `const` (`p.location.x` twice = 2 crossings + 2 allocations → 0). |
+| B2 | `closure-lift` | Arrows created inside hot functions (re-allocated every tick) lifted to module scope when they capture nothing / module bindings / const primitives (inlined) / never-reassigned locals via a module-level cell. |
+| B3 | `string-build` | `s += x` in a hot loop → `parts.push()` + one `join("")` (QuickJS strings are immutable flat buffers: `+=` is O(n²), parts+join is O(n)). |
+| B4 | `dynprop-hoist` | `entity.getDynamicProperty("k")` with a constant key, read in a hot loop, hoisted above the loop. |
+| B5 | `null-chain-flatten` | After a proven guard (`if (!a) return;`), `a?.b` → `a.b` within the barrier-free region. |
+
+</details>
+
+<details>
+<summary><strong>RISKY — opt-in (<code>--level risky</code> or config); every application warns, each has a documented failure mode</strong></summary>
+
+| ID | Name | What it does | Failure mode |
+|---|---|---|---|
+| R1 | `cross-tick-cache` | Module-level WeakMap caches `getComponent("…")` and `entity.id`/`typeId` across ticks. | **Stale component views after death/dimension change.** |
+| R2 | `json-fold` | `const x = JSON.parse('…')` hoisted to a module const when provably never mutated or passed to unknown code. | Shared mutable state if mutated anyway. |
+| R3 | `try-catch-strip` | Removes `try { } catch { }` with no calls in the try body, in hot functions. | A pathological engine-level throw now crashes the script instead of being swallowed. |
+| R4 | `getter-cache-cross-barrier` | B1, allowed to cross call barriers within one synchronous callback. | Cached values stale if an intervening call teleports/damages the entity. |
+
+</details>
+
+## Pragmas
+
+```js
+// optipack: off                      ← first comment in the file: skip the whole file
+// optipack-disable const-fold        ← line before a statement/function: skip that node (or `all`, or comma lists)
+// optipack-hot                       ← line before a function: force-mark it hot
+```
+
+## Config
+
+`optipack.config.json` (CLI flags win):
+
+```json
+{
+  "level": "balanced",
+  "transforms": { "json-fold": true },
+  "hotPath": { "transitiveDepth": 1 },
+  "lint": true
+}
+```
+
+`transforms` can force any pass on/off regardless of level — that's how you run RISKY passes without `--level risky`.
+
+## What the report tells you
+
+Each build writes `optipack-report.json`: transforms applied per file, every bail (line + reason — the tool never silently skips), lint findings (e.g. `getAllPlayers()` in tick handlers, residual allocations), and byte sizes.
+
+## Correctness: effects, not vibes
+
+The test suite (68 tests) proves **effects-equivalence**: scripts run against a mock `@minecraft/server` with an effect recorder that logs every *mutating* call and registration in order — reads return scripted sequences and are free to be eliminated. Original and optimized must produce **identical effect traces** across simulated ticks and events, for every fixture and for the example pack. Mocks exist for all ten `@minecraft/*` runtime modules (functional for `server`/`server-ui`, generated from real type definitions for the rest).
+
+```bash
+npm test                # 68 tests
+npm run fetch-corpus    # pull the real-world benchmark corpus (JaylyDev/ScriptAPI, MIT)
+npm run update-snapshot # regenerate the example report snapshot
+```
+
+## Limitations
+
+- Same-file analysis only; cross-file helpers aren't auto-hot (annotate with `// optipack-hot`).
+- No bundling/minification — pair with esbuild etc. if you use npm libraries like `@minecraft/math`.
+- S5 assumes dense arrays (sparse-array provenance bails); S7's before-loop hoist evaluates once per loop entry (safe for live host objects, documented edge for null roots + zero-iteration loops).
+
+## Development
+
+```
+npm install
+npm test
+npm run update-snapshot     # example report snapshot
+npm run update-mock-stubs   # regenerate @minecraft/* stubs from real type defs
+npm run fetch-corpus        # real-world benchmark corpus
+```
+
+MIT — see [LICENSE](LICENSE). Benchmark corpus scripts belong to their original authors (see `test/corpus/SOURCES.json`).

package/bin/optipack.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    console.error(err && err.stack ? err.stack : String(err));
+    process.exitCode = 3;
+  }
+);

package/example/manifest.json

@@ -0,0 +1,27 @@
+{
+  "format_version": 2,
+  "header": {
+    "name": "optipack example pack",
+    "description": "Tiny behavior pack exercising tick loops, event handlers, a runJob generator and dynamic properties. Used by the optipack test suite.",
+    "uuid": "6f2a1c8e-3d44-4b0a-9d21-77aa01bb2f01",
+    "version": [1, 0, 0],
+    "min_engine_version": [1, 21, 0]
+  },
+  "modules": [
+    {
+      "type": "data",
+      "uuid": "9c1b3f60-8e2d-4c6a-b1e4-52dd03cc2f02",
+      "version": [1, 0, 0]
+    },
+    {
+      "type": "script",
+      "language": "javascript",
+      "uuid": "b7d4e2a0-5f31-4a88-8c70-63ee04dd2f03",
+      "entry": "scripts/main.js",
+      "version": [1, 0, 0]
+    }
+  ],
+  "dependencies": [
+    { "module_name": "@minecraft/server", "version": "2.0.0" }
+  ]
+}

package/example/scripts/drops.js

@@ -0,0 +1,24 @@
+// optipack example — drop tables and dynamic property loops.
+// Constant JSON folded at build time when R2 (json-fold) is enabled.
+
+const DROP_TABLE = JSON.parse('{"common":["apple","bread"],"rare":["diamond"]}');
+
+export function buildDropSummary(count) {
+  const items = DROP_TABLE.common;
+  let out = '';
+  for (let i = 0; i < items.length && i < count; i++) {
+    out += items[i] + ';';
+  }
+  return out;
+}
+
+// Hot loop re-reading dynamic properties: the B4 pattern when called per-tick.
+export function pollDropState(entity) {
+  let picked = 0;
+  for (let i = 0; i < 3; i++) {
+    if (entity.getDynamicProperty('optipack:drops') !== undefined) {
+      picked = picked + 1;
+    }
+  }
+  return picked;
+}

package/example/scripts/main.js

@@ -0,0 +1,67 @@
+// optipack example — main entry.
+// Registers a tick loop, an event handler, and a runJob generator.
+import { world, system } from '@minecraft/server';
+import { toZoneLabel, trackBaseline } from './util.js';
+import { buildDropSummary, pollDropState } from './drops.js';
+
+world.afterEvents.worldLoad.subscribe(() => {
+  world.sendMessage('optipack example loaded');
+  system.runInterval(onTick, 20);
+  world.afterEvents.playerSpawn.subscribe(onPlayerSpawn);
+});
+
+// Per-tick handler: re-reads host getters every run, builds a string with +=,
+// and iterates provable arrays with for...of + array methods.
+function onTick() {
+  const players = world.getAllPlayers();
+  let summary = '';
+  for (const player of players) {
+    const label = toZoneLabel(player);
+    const dist = player.location.x + player.location.y;
+    summary += label + ' dist=' + dist;
+    player.setDynamicProperty('optipack:lastDist', dist);
+    // Per-player baseline: re-reads the same host chain every iteration (S7).
+    let baseline = 0;
+    for (let i = 0; i < 4; i++) {
+      baseline += player.location.y;
+    }
+    player.setDynamicProperty('optipack:baseline', baseline);
+  }
+  if (summary.length > 0) {
+    world.sendMessage(summary);
+  }
+
+  const zones = ['overworld', 'nether', 'the_end'].filter((z) => z.length > 4);
+  for (const z of zones) {
+    world.setDynamicProperty('optipack:zone:' + z, true);
+  }
+
+  system.runJob(chunkScan());
+
+  if (players.length > 0) {
+    pollDropState(players[0]);
+  }
+}
+
+// runJob iterator: every yield is a barrier for host-object caching.
+function* chunkScan() {
+  for (let cx = 0; cx < 4; cx++) {
+    const before = world.getDynamicProperty('optipack:scan:' + cx);
+    yield;
+    world.setDynamicProperty('optipack:scan:' + cx, (before ?? 0) + 1);
+  }
+}
+
+function onPlayerSpawn(ev) {
+  const p = ev.player;
+  if (!p) return;
+  world.sendMessage('welcome ' + p.name);
+  const health = p.getComponent('minecraft:health');
+  if (health) {
+    p.setDynamicProperty('optipack:spawnHp', health.currentValue);
+  }
+  const drops = buildDropSummary(2);
+  p.setDynamicProperty('optipack:drops', drops);
+  // Hot helper defined in util.js — exercises transitive hot-path analysis.
+  trackBaseline(p);
+}

package/example/scripts/util.js

@@ -0,0 +1,30 @@
+// optipack example — utilities. Hot helpers called from the tick loop.
+import { world } from '@minecraft/server';
+
+export function toZoneLabel(player) {
+  const x = player.location.x;
+  const z = player.location.z;
+  return 'pos:' + Math.floor(x) + ',' + Math.floor(z);
+}
+
+export function clamp(v, lo, hi) {
+  if (v < lo) return lo;
+  if (v > hi) return hi;
+  return v;
+}
+
+// Called from onPlayerSpawn which is called from a subscribed handler, and
+// re-reads the same host chain in a loop: the S7 pattern.
+export function trackBaseline(player) {
+  let sum = 0;
+  for (let i = 0; i < 8; i++) {
+    sum += player.location.y;
+  }
+  world.setDynamicProperty('optipack:baseline', sum);
+  return sum;
+}
+
+// Bool-shape helpers (S3).
+export function isAboveWater(player) {
+  return player.location.y > 62 ? true : false;
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "optipack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "QuickJS-targeted micro-optimizing pre-processor for Minecraft Bedrock behavior-pack scripts",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "optipack": "bin/optipack.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "src/pipeline.js",
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "update-snapshot": "node test/update-example-snapshot.mjs",
+    "fetch-corpus": "node test/fetch-corpus.mjs",
+    "update-mock-stubs": "node test/update-mock-stubs.mjs"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.26.0",
+    "@babel/parser": "^7.26.0",
+    "@babel/traverse": "^7.26.0",
+    "@babel/types": "^7.26.0",
+    "commander": "^12.1.0"
+  },
+  "author": "lettucebecaesar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lettucebecaesar/optipack.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lettucebecaesar/optipack/issues"
+  },
+  "homepage": "https://github.com/lettucebecaesar/optipack#readme"
+}