redscript-mc 1.2.30 → 2.1.0

package/dist/src/lir/budget.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Static Tick Budget Analysis — Phase 1a
+ *
+ * Estimates the number of MC commands a function will execute at runtime.
+ * Used to warn when loops may exceed Minecraft's maxCommandChainLength (65536).
+ *
+ * In LIR, loops are represented as mutually-recursive function calls
+ * (e.g., fn__header ↔ fn__body). This module detects call-graph cycles
+ * and multiplies the loop body cost by an estimated iteration count.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUDGET_ERROR_THRESHOLD = exports.BUDGET_WARN_THRESHOLD = void 0;
+exports.estimateCommandCount = estimateCommandCount;
+exports.analyzeBudget = analyzeBudget;
+/** Default estimated iteration count when the upper bound is unknown */
+const DEFAULT_LOOP_ITERATIONS = 100;
+/** Warning threshold: suggest @coroutine */
+exports.BUDGET_WARN_THRESHOLD = 32768;
+/** Error threshold: likely exceeds maxCommandChainLength */
+exports.BUDGET_ERROR_THRESHOLD = 65536;
+// ---------------------------------------------------------------------------
+// Call graph utilities
+// ---------------------------------------------------------------------------
+/** Extract all function names called by an instruction */
+function getCalledFunctions(instr) {
+    switch (instr.kind) {
+        case 'call':
+        case 'call_macro':
+            return [instr.fn];
+        case 'call_if_matches':
+        case 'call_unless_matches':
+        case 'call_if_score':
+        case 'call_unless_score':
+        case 'call_context':
+            return [instr.fn];
+        case 'store_cmd_to_score':
+            // The nested cmd may also be a call
+            return getCalledFunctions(instr.cmd);
+        default:
+            return [];
+    }
+}
+/** Build adjacency list: fnName → set of called function names (module-local only) */
+function buildCallGraph(mod) {
+    const fnNames = new Set(mod.functions.map(f => f.name));
+    const graph = new Map();
+    for (const fn of mod.functions) {
+        const callees = new Set();
+        for (const instr of fn.instructions) {
+            for (const callee of getCalledFunctions(instr)) {
+                // Strip namespace prefix to match local function names
+                const local = stripNamespace(callee, mod.namespace);
+                if (fnNames.has(local)) {
+                    callees.add(local);
+                }
+            }
+        }
+        graph.set(fn.name, callees);
+    }
+    return graph;
+}
+/** Strip "namespace:" prefix from a qualified function name */
+function stripNamespace(qualifiedName, namespace) {
+    const prefix = `${namespace}:`;
+    if (qualifiedName.startsWith(prefix)) {
+        return qualifiedName.slice(prefix.length);
+    }
+    return qualifiedName;
+}
+/** Find all strongly connected components (Tarjan's algorithm) */
+function findSCCs(graph) {
+    let index = 0;
+    const stack = [];
+    const onStack = new Set();
+    const indices = new Map();
+    const lowlinks = new Map();
+    const sccs = [];
+    function strongconnect(v) {
+        indices.set(v, index);
+        lowlinks.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of graph.get(v) ?? []) {
+            if (!indices.has(w)) {
+                strongconnect(w);
+                lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+            }
+            else if (onStack.has(w)) {
+                lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
+            }
+        }
+        if (lowlinks.get(v) === indices.get(v)) {
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+            } while (w !== v);
+            sccs.push(scc);
+        }
+    }
+    for (const v of graph.keys()) {
+        if (!indices.has(v)) {
+            strongconnect(v);
+        }
+    }
+    return sccs;
+}
+// ---------------------------------------------------------------------------
+// Command count estimation
+// ---------------------------------------------------------------------------
+/** Count the number of MC commands an instruction generates (non-recursive) */
+function instrCommandCount(instr) {
+    switch (instr.kind) {
+        case 'store_cmd_to_score':
+            // The execute store wrapper + the inner command
+            return 1;
+        default:
+            // Each LIR instruction maps to ~1 MC command
+            return 1;
+    }
+}
+/** Count raw (non-call) commands in a function */
+function localCommandCount(fn) {
+    let count = 0;
+    for (const instr of fn.instructions) {
+        count += instrCommandCount(instr);
+    }
+    return count;
+}
+/**
+ * Try to extract a constant loop bound from a loop's LIR functions.
+ *
+ * Looks for patterns like:
+ *   score_set <limit_slot> <N>
+ * in the cycle's functions, where N is used as a comparison bound.
+ *
+ * Returns the bound if found, otherwise DEFAULT_LOOP_ITERATIONS.
+ */
+function estimateLoopIterations(cycleFns) {
+    // Look for score_set instructions that might be loop bounds
+    // Heuristic: find the largest constant set in the cycle's callers
+    // that looks like a loop limit (typically set before the loop)
+    for (const fn of cycleFns) {
+        for (const instr of fn.instructions) {
+            if (instr.kind === 'call_if_matches' || instr.kind === 'call_unless_matches') {
+                // Parse range like "..999" or "0..999" to extract upper bound
+                const range = instr.range;
+                const match = range.match(/\.\.(\d+)/);
+                if (match) {
+                    return parseInt(match[1], 10) + 1;
+                }
+            }
+        }
+    }
+    return DEFAULT_LOOP_ITERATIONS;
+}
+/**
+ * Estimate the total command count for a function, including callees.
+ *
+ * @param fnName - Name of the function to estimate
+ * @param mod - The LIR module
+ * @returns Estimated number of MC commands
+ */
+function estimateCommandCount(fnName, mod) {
+    const fnMap = new Map();
+    for (const fn of mod.functions) {
+        fnMap.set(fn.name, fn);
+    }
+    const callGraph = buildCallGraph(mod);
+    const sccs = findSCCs(callGraph);
+    // Map each function to its SCC
+    const fnToSCC = new Map();
+    for (const scc of sccs) {
+        for (const name of scc) {
+            fnToSCC.set(name, scc);
+        }
+    }
+    // Memoize estimated counts
+    const memo = new Map();
+    function estimate(name, visiting) {
+        if (memo.has(name))
+            return memo.get(name);
+        const fn = fnMap.get(name);
+        if (!fn)
+            return 0;
+        // Detect cycle: if we're already visiting this function, return 0
+        // (cycle cost is handled at the SCC level)
+        if (visiting.has(name))
+            return 0;
+        visiting.add(name);
+        const scc = fnToSCC.get(name);
+        const isCyclic = scc.length > 1 || (scc.length === 1 && callGraph.get(name)?.has(name));
+        if (isCyclic) {
+            // Sum local commands across all functions in the cycle
+            let cycleLocalCost = 0;
+            for (const member of scc) {
+                const memberFn = fnMap.get(member);
+                if (memberFn)
+                    cycleLocalCost += localCommandCount(memberFn);
+            }
+            // Estimate iterations
+            const cycleFns = scc.map(n => fnMap.get(n)).filter(Boolean);
+            const iterations = estimateLoopIterations(cycleFns);
+            // Also add cost of non-cycle callees
+            let externalCalleeCost = 0;
+            for (const member of scc) {
+                for (const callee of callGraph.get(member) ?? []) {
+                    if (!scc.includes(callee)) {
+                        externalCalleeCost += estimate(callee, new Set(visiting));
+                    }
+                }
+            }
+            const total = (cycleLocalCost + externalCalleeCost) * iterations;
+            // Memoize for all members of this SCC
+            for (const member of scc) {
+                memo.set(member, total);
+            }
+            visiting.delete(name);
+            return total;
+        }
+        // Non-cyclic: local cost + callee costs
+        let total = localCommandCount(fn);
+        for (const callee of callGraph.get(name) ?? []) {
+            total += estimate(callee, visiting);
+        }
+        memo.set(name, total);
+        visiting.delete(name);
+        return total;
+    }
+    return estimate(fnName, new Set());
+}
+// ---------------------------------------------------------------------------
+// Budget analysis for a full module
+// ---------------------------------------------------------------------------
+/**
+ * Analyze all "top-level" functions in the module for tick budget violations.
+ *
+ * @param mod - The LIR module to analyze
+ * @param coroutineFunctions - Set of function names marked @coroutine (skip these)
+ * @returns Array of budget diagnostics (warnings and errors)
+ */
+function analyzeBudget(mod, coroutineFunctions = new Set()) {
+    const diagnostics = [];
+    // Only analyze user-defined "root" functions, not compiler-generated helper blocks
+    // Helper blocks have names like "fnname__blockid"
+    for (const fn of mod.functions) {
+        // Skip coroutine-annotated functions
+        if (coroutineFunctions.has(fn.name))
+            continue;
+        // Skip compiler-generated helper functions (contain __)
+        if (fn.name.includes('__'))
+            continue;
+        // Skip coroutine-generated functions
+        if (fn.name.startsWith('_coro_'))
+            continue;
+        const estimated = estimateCommandCount(fn.name, mod);
+        if (estimated > exports.BUDGET_ERROR_THRESHOLD) {
+            diagnostics.push({
+                level: 'error',
+                fnName: fn.name,
+                estimatedCommands: estimated,
+                message: `function '${fn.name}' may exceed tick budget (~${estimated} commands), this will likely crash. Consider @coroutine or reducing loop iterations`,
+            });
+        }
+        else if (estimated > exports.BUDGET_WARN_THRESHOLD) {
+            diagnostics.push({
+                level: 'warning',
+                fnName: fn.name,
+                estimatedCommands: estimated,
+                message: `loop may exceed tick budget (~${estimated} commands), consider @coroutine`,
+            });
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=budget.js.map

package/dist/src/lir/lower.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MIR → LIR Lowering — Stage 5 of the RedScript compiler pipeline.
+ *
+ * Converts 3-address MIR (CFG with basic blocks) to 2-address LIR
+ * (flat instruction lists with MC scoreboard semantics).
+ *
+ * Key transformations:
+ * - Each MIR Temp → a Slot (player = $tempname, obj = module.objective)
+ * - 3-address arithmetic → score_copy dst←a, then score_op dst←b
+ * - CFG control flow → call_if_matches / call_unless_matches to extracted functions
+ * - MIR calls → parameter slot setup + call instruction
+ */
+import type { MIRModule } from '../mir/types';
+import type { LIRModule } from './types';
+export declare function lowerToLIR(mir: MIRModule): LIRModule;