optipack 0.0.0-stage → 1.0.1

package/src/hotpath.js

@@ -0,0 +1,158 @@
+/**
+ * Hot-path classification and the shared pass context.
+ */
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+
+const _traverse = traverse.default || traverse;
+
+const HOT_CALLEE_NAMES = new Set(['runInterval', 'runTimeout', 'run', 'runJob', 'subscribe']);
+const TICK_CALLEE_NAMES = new Set(['runInterval', 'run']);
+
+function functionLike(node) {
+  return t.isFunctionDeclaration(node) || t.isFunctionExpression(node) || t.isArrowFunctionExpression(node);
+}
+
+/**
+ * Analyze the AST and classify functions as hot.
+ * Returns a HotInfo with:
+ *   isHot(node), isTick(node), hotCount, tickCount,
+ *   markHot(node), copyHotness(fromNode, toNode)
+ */
+export function analyzeHotPaths(ast, pragmas, { transitiveDepth = 1 } = {}) {
+  const hot = new WeakSet();
+  const tick = new WeakSet();
+  let hotCount = 0;
+  let tickCount = 0;
+
+  const addHot = (node, isTick) => {
+    if (!functionLike(node)) return;
+    if (!hot.has(node)) hotCount++;
+    hot.add(node);
+    if (isTick && !tick.has(node)) tickCount++;
+    if (isTick) tick.add(node);
+  };
+
+  // Resolve an argument that refers to a same-file function (by binding).
+  const resolveArg = (path, arg) => {
+    if (functionLike(arg)) return { node: arg, viaBinding: null };
+    if (t.isIdentifier(arg)) {
+      const binding = path.scope.getBinding(arg.name);
+      if (!binding) return null;
+      if (binding.path.isFunctionDeclaration()) return { node: binding.path.node, viaBinding: binding };
+      if (binding.path.isVariableDeclarator()) {
+        const init = binding.path.node.init;
+        if (functionLike(init)) return { node: init, viaBinding: binding };
+      }
+    }
+    return null;
+  };
+
+  // Pass 1: direct registration sites.
+  _traverse(ast, {
+    CallExpression(path) {
+      const callee = path.node.callee;
+      if (!t.isMemberExpression(callee) || callee.computed) return;
+      const prop = callee.property;
+      if (!t.isIdentifier(prop)) return;
+      if (prop.name === 'subscribe' || HOT_CALLEE_NAMES.has(prop.name)) {
+        const firstFn = path.node.arguments.find((a) => functionLike(a));
+        if (firstFn) {
+          addHot(firstFn, TICK_CALLEE_NAMES.has(prop.name));
+          return;
+        }
+        const arg = path.node.arguments[0];
+        if (!arg) return;
+        const r = resolveArg(path, arg);
+        if (r) addHot(r.node, TICK_CALLEE_NAMES.has(prop.name));
+      }
+    },
+  });
+
+  // Pass 1b: pragma hot marks.
+  _traverse(ast, {
+    'FunctionDeclaration|FunctionExpression|ArrowFunctionExpression'(path) {
+      const node = path.node;
+      if (node.loc && pragmas.isHotLine(node.loc.start.line)) addHot(node, false);
+    },
+  });
+
+  // Pass 2: transitive propagation through the same-file call graph.
+  // callGraph: targetNode -> Set of caller nodes (null = module top level)
+  // Also tracks reference sites for functions passed around as values.
+  const callersOf = new Map();
+  const recordCaller = (targetNode, callerNode) => {
+    if (!targetNode) return;
+    if (!callersOf.has(targetNode)) callersOf.set(targetNode, new Set());
+    callersOf.get(targetNode).add(callerNode);
+  };
+
+  const resolveCalleeNode = (path, callee) => {
+    if (!t.isIdentifier(callee)) return null;
+    if (callee.name === 'arguments' || callee.name === 'eval') return null;
+    const binding = path.scope.getBinding(callee.name);
+    if (!binding) return null;
+    if (binding.path.isFunctionDeclaration()) return binding.path.node;
+    if (binding.path.isVariableDeclarator()) {
+      const init = binding.path.node.init;
+      if (functionLike(init)) return init;
+    }
+    return null;
+  };
+
+  _traverse(ast, {
+    CallExpression(path) {
+      const target = resolveCalleeNode(path, path.node.callee);
+      if (target) recordCaller(target, path.getFunctionParent() ? path.getFunctionParent().node : null);
+    },
+    ReferencedIdentifier(path) {
+      // A function referenced as a value (e.g. passed to runInterval) counts as
+      // a use site within the enclosing function.
+      const binding = path.scope.getBinding(path.node.name);
+      if (!binding) return;
+      let target = null;
+      if (binding.path.isFunctionDeclaration()) target = binding.path.node;
+      else if (binding.path.isVariableDeclarator() && binding.path.node.init && functionLike(binding.path.node.init)) {
+        target = binding.path.node.init;
+      }
+      if (!target) return;
+      // Skip the declaration's own identifier.
+      if (binding.path.node.id === path.node || (binding.path.node.init && binding.path.node.init === path.node)) return;
+      recordCaller(target, path.getFunctionParent() ? path.getFunctionParent().node : null);
+    },
+  });
+
+  // BFS from the directly-hot set. A candidate becomes hot when every
+  // reference site is inside an already-hot function (i.e. it is only ever
+  // reached from hot code) and it has at least one reference site.
+  for (let depth = 0; depth < transitiveDepth; depth++) {
+    let changed = false;
+    for (const [target, callers] of callersOf) {
+      if (hot.has(target) || callers.size === 0) continue;
+      if (callers.has(null)) continue; // referenced at module top level
+      let allHot = true;
+      for (const c of callers) {
+        if (!hot.has(c)) { allHot = false; break; }
+      }
+      if (allHot) {
+        // Inherit tick-ness: if all callers are tick handlers, so is this.
+        let allTick = callers.size > 0;
+        for (const c of callers) if (!tick.has(c)) { allTick = false; break; }
+        addHot(target, allTick);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+
+  return {
+    isHot: (node) => hot.has(node),
+    isTick: (node) => tick.has(node),
+    markHot: (node) => addHot(node, false),
+    copyHotness(fromNode, toNode) {
+      if (hot.has(fromNode)) addHot(toNode, tick.has(fromNode));
+    },
+    get hotCount() { return hotCount; },
+    get tickCount() { return tickCount; },
+  };
+}

package/src/lint.js

@@ -0,0 +1,150 @@
+/**
+ * Lint pass — reports anti-patterns with line numbers; never rewrites.
+ *
+ * Rules:
+ *  - per-tick-getAllPlayers   getAllPlayers()/getEntities()/dimension.players
+ *                             unconditionally inside per-tick callbacks
+ *  - dynprop-in-loop          getDynamicProperty inside tick loops beyond what
+ *                             B4 hoisted
+ *  - residual-allocs          closures/arrays/object literals remaining inside
+ *                             hot callbacks (GC pressure metric)
+ *  - subscribe-in-interval    subscribe() called inside runInterval handlers
+ *  - json-in-hot              JSON.parse/JSON.stringify/structuredClone in hot
+ *                             functions
+ *  - try-catch-wraps-tick     try/catch wrapping an entire tick-handler body
+ */
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+import { walkSameFunction } from './pass-utils.js';
+
+const _traverse = traverse.default || traverse;
+
+export function runLint(programPath, ctx, hot) {
+  const fr = ctx.fileReport;
+
+  // ---- residual allocations inside hot functions (innermost attribution)
+  const counted = new WeakSet();
+  programPath.traverse({
+    'FunctionDeclaration|FunctionExpression|ArrowFunctionExpression'(path) {
+      const fn = path.node;
+      if (!ctx.isHot(fn)) return;
+      if (counted.has(fn)) return;
+      walkSameFunction(fn.body, (n) => {
+        if (n !== fn && (t.isFunctionExpression(n) || t.isArrowFunctionExpression(n))) {
+          if (counted.has(n)) return false; // attributed to the inner hot fn
+          if (ctx.isHot(n)) return true; // visited separately
+          if (n.loc) fr.residualAllocs.closures++;
+          counted.add(n);
+          return false;
+        }
+        if (t.isFunctionDeclaration(n) && n !== fn) {
+          counted.add(n);
+          return false;
+        }
+        if (n.loc && t.isArrayExpression(n)) fr.residualAllocs.arrays++;
+        else if (n.loc && t.isObjectExpression(n)) fr.residualAllocs.objects++;
+        return true;
+      });
+      counted.add(fn);
+    },
+  });
+
+  // ---- per-tick scan
+  programPath.traverse({
+    'FunctionDeclaration|FunctionExpression|ArrowFunctionExpression'(path) {
+      const fn = path.node;
+      if (!hot || !hot.isTick(fn)) return;
+      const line = fn.loc ? fn.loc.start.line : 0;
+
+      walkSameFunction(fn.body, (n) => {
+        // Rule 1: population sweeps in tick handlers.
+        if (t.isCallExpression(n) && t.isMemberExpression(n.callee) && !n.callee.computed &&
+            t.isIdentifier(n.callee.property)) {
+          const m = n.callee.property.name;
+          if (m === 'getAllPlayers' || m === 'getEntities') {
+            fr.lint.push({
+              line: n.loc ? n.loc.start.line : 0,
+              rule: 'per-tick-getAllPlayers',
+              message: `${m}() runs unconditionally inside a per-tick callback — prefer event-driven updates or caching between ticks`,
+            });
+          }
+          if (m === 'subscribe') {
+            fr.lint.push({
+              line: n.loc ? n.loc.start.line : 0,
+              rule: 'subscribe-in-interval',
+              message: 'subscribe() inside a per-tick handler re-registers on every tick — move registration to setup',
+            });
+          }
+          if (m === 'parse' && t.isMemberExpression(n.callee.object) &&
+              t.isIdentifier(n.callee.object.object, { name: 'JSON' })) {
+            fr.lint.push({
+              line: n.loc ? n.loc.start.line : 0,
+              rule: 'json-in-hot',
+              message: 'JSON.parse in a hot function — parse once at startup instead',
+            });
+          }
+        }
+        if (t.isMemberExpression(n) && !n.computed && t.isIdentifier(n.property) &&
+            n.property.name === 'players' && !isCallCallee(n)) {
+          // dimension.players — only flag when the object looks like a dimension
+          if (t.isIdentifier(n.object) && /dimension/i.test(n.object.name)) {
+            fr.lint.push({
+              line: n.loc ? n.loc.start.line : 0,
+              rule: 'per-tick-getAllPlayers',
+              message: 'dimension.players allocates a fresh array every read — cache or go event-driven',
+            });
+          }
+        }
+        if (t.isCallExpression(n) && t.isMemberExpression(n.callee) && !n.callee.computed &&
+            t.isIdentifier(n.callee.property) && n.callee.property.name === 'stringify' &&
+            t.isMemberExpression(n.callee.object) && t.isIdentifier(n.callee.object.object, { name: 'JSON' })) {
+          fr.lint.push({
+            line: n.loc ? n.loc.start.line : 0,
+            rule: 'json-in-hot',
+            message: 'JSON.stringify in a hot function — serialize only when data changes',
+          });
+        }
+        if (t.isCallExpression(n) && t.isIdentifier(n.callee) && n.callee.name === 'structuredClone') {
+          fr.lint.push({
+            line: n.loc ? n.loc.start.line : 0,
+            rule: 'json-in-hot',
+            message: 'structuredClone in a hot function — clones allocate every tick',
+          });
+        }
+        // Rule 2: remaining getDynamicProperty inside loops.
+        if ((t.isForStatement(n) || t.isWhileStatement(n) || t.isDoWhileStatement(n) ||
+             t.isForOfStatement(n) || t.isForInStatement(n))) {
+          walkSameFunction(n.body, (m) => {
+            if (t.isCallExpression(m) && t.isMemberExpression(m.callee) && !m.callee.computed &&
+                t.isIdentifier(m.callee.property) && m.callee.property.name === 'getDynamicProperty') {
+              fr.lint.push({
+                line: m.loc ? m.loc.start.line : 0,
+                rule: 'dynprop-in-loop',
+                message: 'getDynamicProperty inside a tick loop — reads cross the host boundary every iteration',
+              });
+            }
+            return true;
+          });
+        }
+        return true;
+      });
+
+      // Rule 6: try/catch wrapping the whole handler body.
+      if (t.isBlockStatement(fn.body) && fn.body.body.length === 1 &&
+          t.isTryStatement(fn.body.body[0])) {
+        fr.lint.push({
+          line: fn.body.body[0].loc ? fn.body.body[0].loc.start.line : line,
+          rule: 'try-catch-wraps-tick',
+          message: 'try/catch wraps the entire tick handler body — errors are swallowed every tick',
+        });
+      }
+    },
+  });
+}
+
+function isCallCallee(memberPathNode) {
+  // We walk nodes without paths here; a member expression that is a callee is
+  // handled by the CallExpression branch above, so treat all as non-callee.
+  void memberPathNode;
+  return false;
+}

package/src/pack-walker.js

@@ -0,0 +1,50 @@
+/**
+ * Pack walker — walks the input behavior pack, copies non-script files
+ * verbatim, and returns the list of script files to transform.
+ *
+ * Only files under `scripts/` with .js/.mjs extensions are transformed.
+ * node_modules/ and .git/ are skipped entirely. Everything else (manifest.json,
+ * JSON, functions, texts, textures) is copied byte-for-byte.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SCRIPT_EXT = new Set(['.js', '.mjs']);
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+export function walkPack(inputDir) {
+  const scripts = [];
+  const copies = [];
+  const visit = (dir, rel) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const ent of entries) {
+      const abs = path.join(dir, ent.name);
+      const relPath = rel ? `${rel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        visit(abs, relPath);
+      } else if (ent.isFile()) {
+        const ext = path.extname(ent.name).toLowerCase();
+        const inScripts = relPath === 'scripts' || relPath.startsWith('scripts/');
+        if (inScripts && SCRIPT_EXT.has(ext)) {
+          scripts.push({ abs, relPath });
+        } else {
+          copies.push({ abs, relPath });
+        }
+      }
+    }
+  };
+  visit(inputDir, '');
+  return { scripts, copies };
+}
+
+export function copyFile(srcAbs, destAbs) {
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+  fs.copyFileSync(srcAbs, destAbs);
+}
+
+export function writeFile(destAbs, content) {
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+  fs.writeFileSync(destAbs, content);
+}