redscript-mc 1.2.30 → 2.1.0

package/dist/src/lir/lower.js

@@ -0,0 +1,472 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lowerToLIR = lowerToLIR;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+function lowerToLIR(mir) {
+    const ctx = new LoweringContext(mir.namespace, mir.objective);
+    for (const fn of mir.functions) {
+        lowerFunction(fn, ctx);
+    }
+    return {
+        functions: ctx.functions,
+        namespace: mir.namespace,
+        objective: mir.objective,
+    };
+}
+// ---------------------------------------------------------------------------
+// Lowering context
+// ---------------------------------------------------------------------------
+class LoweringContext {
+    constructor(namespace, objective) {
+        this.functions = [];
+        /** Track which blocks have multiple predecessors (need their own function) */
+        this.multiPredBlocks = new Set();
+        /** Map block id → generated LIR function name for multi-pred blocks */
+        this.blockFnNames = new Map();
+        /** Current MIR function being lowered */
+        this.currentMIRFn = null;
+        /** Block map for quick lookup */
+        this.blockMap = new Map();
+        this.namespace = namespace;
+        this.objective = objective;
+    }
+    slot(temp) {
+        // Return field temps are global (shared between caller/callee)
+        if (temp.startsWith('__rf_')) {
+            return { player: `$ret_${temp.slice(5)}`, obj: this.objective };
+        }
+        // Prefix temp names with function name to avoid caller/callee collision
+        const fn = this.currentMIRFn;
+        const prefix = fn ? fn.name : '';
+        return { player: `$${prefix}_${temp}`, obj: this.objective };
+    }
+    qualifiedName(fnName) {
+        // Convert :: to / and lowercase for MC function paths
+        const mcName = fnName.replace(/::/g, '/').toLowerCase();
+        return `${this.namespace}:${mcName}`;
+    }
+    addFunction(fn) {
+        this.functions.push(fn);
+    }
+    /** Attach sourceLoc to newly added instructions (from the given start index onward) */
+    tagSourceLoc(instrs, fromIndex, sourceLoc) {
+        if (!sourceLoc)
+            return;
+        for (let i = fromIndex; i < instrs.length; i++) {
+            if (!instrs[i].sourceLoc)
+                instrs[i].sourceLoc = sourceLoc;
+        }
+    }
+    analyzeBlocks(fn) {
+        this.currentMIRFn = fn;
+        this.multiPredBlocks.clear();
+        this.blockFnNames.clear();
+        this.blockMap.clear();
+        for (const block of fn.blocks) {
+            this.blockMap.set(block.id, block);
+        }
+        // Count predecessors for each block
+        const predCount = new Map();
+        for (const block of fn.blocks) {
+            const targets = getTermTargets(block.term);
+            for (const target of targets) {
+                predCount.set(target, (predCount.get(target) || 0) + 1);
+            }
+        }
+        // Blocks with >1 predecessors or that are branch targets need their own function
+        for (const [blockId, count] of predCount) {
+            if (count > 1 && blockId !== fn.entry) {
+                this.multiPredBlocks.add(blockId);
+                this.blockFnNames.set(blockId, `${fn.name}__${blockId}`);
+            }
+        }
+    }
+    isMultiPred(blockId) {
+        return this.multiPredBlocks.has(blockId);
+    }
+    getBlockFnName(blockId) {
+        const name = this.blockFnNames.get(blockId);
+        if (name)
+            return name;
+        // Generate one on demand
+        const generated = `${this.currentMIRFn.name}__${blockId}`;
+        this.blockFnNames.set(blockId, generated);
+        return generated;
+    }
+    getBlock(id) {
+        return this.blockMap.get(id);
+    }
+}
+// ---------------------------------------------------------------------------
+// Function lowering
+// ---------------------------------------------------------------------------
+function lowerFunction(fn, ctx) {
+    ctx.analyzeBlocks(fn);
+    // Lower the entry block as the main function body
+    const instrs = [];
+    const visited = new Set();
+    // Copy parameter slots ($p0, $p1, ...) into the callee's temp slots
+    for (let i = 0; i < fn.params.length; i++) {
+        const paramSlot = { player: `$p${i}`, obj: ctx.objective };
+        const tempSlot = ctx.slot(fn.params[i].name);
+        instrs.push({ kind: 'score_copy', dst: tempSlot, src: paramSlot });
+    }
+    lowerBlock(fn.entry, fn, ctx, instrs, visited);
+    ctx.addFunction({
+        name: fn.name,
+        instructions: instrs,
+        isMacro: fn.isMacro,
+        macroParams: fn.params.filter(p => p.isMacroParam).map(p => p.name),
+    });
+    // Emit separate functions for multi-pred blocks
+    for (const blockId of ctx['multiPredBlocks']) {
+        if (!visited.has(blockId)) {
+            const blockInstrs = [];
+            const blockVisited = new Set();
+            lowerBlock(blockId, fn, ctx, blockInstrs, blockVisited);
+            ctx.addFunction({
+                name: ctx.getBlockFnName(blockId),
+                instructions: blockInstrs,
+                isMacro: false,
+                macroParams: [],
+            });
+        }
+    }
+}
+function lowerBlock(blockId, fn, ctx, instrs, visited) {
+    if (visited.has(blockId))
+        return;
+    visited.add(blockId);
+    const block = ctx.getBlock(blockId);
+    if (!block)
+        return;
+    // Lower all non-terminator instructions
+    for (const instr of block.instrs) {
+        lowerInstr(instr, fn, ctx, instrs);
+    }
+    // Lower the terminator
+    lowerTerminator(block.term, fn, ctx, instrs, visited);
+}
+// ---------------------------------------------------------------------------
+// Instruction lowering
+// ---------------------------------------------------------------------------
+function lowerInstr(instr, fn, ctx, instrs) {
+    const beforeLen = instrs.length;
+    lowerInstrInner(instr, fn, ctx, instrs);
+    ctx.tagSourceLoc(instrs, beforeLen, instr.sourceLoc);
+}
+function lowerInstrInner(instr, fn, ctx, instrs) {
+    switch (instr.kind) {
+        case 'const': {
+            instrs.push({ kind: 'score_set', dst: ctx.slot(instr.dst), value: instr.value });
+            break;
+        }
+        case 'copy': {
+            lowerOperandToSlot(instr.dst, instr.src, ctx, instrs);
+            break;
+        }
+        case 'add':
+        case 'sub':
+        case 'mul':
+        case 'div':
+        case 'mod': {
+            // 3-address → 2-address: copy a to dst, then op dst with b
+            lowerOperandToSlot(instr.dst, instr.a, ctx, instrs);
+            const scoreOp = {
+                add: 'score_add',
+                sub: 'score_sub',
+                mul: 'score_mul',
+                div: 'score_div',
+                mod: 'score_mod',
+            };
+            lowerBinOp(instr.dst, instr.b, scoreOp[instr.kind], ctx, instrs);
+            break;
+        }
+        case 'neg': {
+            // 0 - src: set tmp to 0, then subtract src
+            const dst = ctx.slot(instr.dst);
+            instrs.push({ kind: 'score_set', dst, value: 0 });
+            const srcSlot = operandToSlot(instr.src, ctx, instrs);
+            instrs.push({ kind: 'score_sub', dst, src: srcSlot });
+            break;
+        }
+        case 'cmp': {
+            // Strategy: set dst=0, then conditionally set to 1
+            // MC pattern: execute if score $a <op> $b run scoreboard players set $dst 1
+            const dst = ctx.slot(instr.dst);
+            const aSlot = operandToSlot(instr.a, ctx, instrs);
+            const bSlot = operandToSlot(instr.b, ctx, instrs);
+            instrs.push({ kind: 'score_set', dst, value: 0 });
+            const cmpOps = {
+                eq: '=', ne: '=', lt: '<', le: '<=', gt: '>', ge: '>=',
+            };
+            const op = cmpOps[instr.op];
+            const guard = instr.op === 'ne' ? 'unless' : 'if';
+            const dstStr = `${dst.player} ${dst.obj}`;
+            const aStr = `${aSlot.player} ${aSlot.obj}`;
+            const bStr = `${bSlot.player} ${bSlot.obj}`;
+            instrs.push({
+                kind: 'raw',
+                cmd: `execute ${guard} score ${aStr} ${op} ${bStr} run scoreboard players set ${dstStr} 1`,
+            });
+            break;
+        }
+        case 'and': {
+            // Bitwise/logical AND: both are 0/1, so multiply works
+            // But more accurately: dst = (a != 0) && (b != 0)
+            // Simple approach: copy a, then score_mul with b (since both are 0/1)
+            lowerOperandToSlot(instr.dst, instr.a, ctx, instrs);
+            lowerBinOp(instr.dst, instr.b, 'score_mul', ctx, instrs);
+            break;
+        }
+        case 'or': {
+            // OR for 0/1 values: add then clamp to 1
+            // dst = a + b; if dst > 1, dst = 1
+            const dst = ctx.slot(instr.dst);
+            lowerOperandToSlot(instr.dst, instr.a, ctx, instrs);
+            lowerBinOp(instr.dst, instr.b, 'score_add', ctx, instrs);
+            // Clamp: use score_min with a const slot set to 1
+            const oneSlot = constSlot(1, ctx, instrs);
+            instrs.push({ kind: 'score_min', dst, src: oneSlot });
+            break;
+        }
+        case 'not': {
+            // NOT for 0/1: dst = 1 - src
+            const dst = ctx.slot(instr.dst);
+            instrs.push({ kind: 'score_set', dst, value: 1 });
+            const srcSlot = operandToSlot(instr.src, ctx, instrs);
+            instrs.push({ kind: 'score_sub', dst, src: srcSlot });
+            break;
+        }
+        case 'nbt_read': {
+            const dst = ctx.slot(instr.dst);
+            instrs.push({
+                kind: 'store_nbt_to_score',
+                dst,
+                ns: instr.ns,
+                path: instr.path,
+                scale: instr.scale,
+            });
+            break;
+        }
+        case 'nbt_write': {
+            const srcSlot = operandToSlot(instr.src, ctx, instrs);
+            instrs.push({
+                kind: 'store_score_to_nbt',
+                ns: instr.ns,
+                path: instr.path,
+                type: instr.type,
+                scale: instr.scale,
+                src: srcSlot,
+            });
+            break;
+        }
+        case 'call': {
+            // Set parameter slots $p0, $p1, ...
+            for (let i = 0; i < instr.args.length; i++) {
+                const paramSlot = { player: `$p${i}`, obj: ctx.objective };
+                lowerOperandToSlotDirect(paramSlot, instr.args[i], ctx, instrs);
+            }
+            // Handle raw commands embedded in call
+            if (instr.fn.startsWith('__raw:')) {
+                const cmd = instr.fn.slice(6);
+                if (cmd.startsWith('\x01')) {
+                    // Macro sentinel → emit as macro_line ($ prefix added by emit)
+                    instrs.push({ kind: 'macro_line', template: cmd.slice(1) });
+                }
+                else {
+                    instrs.push({ kind: 'raw', cmd });
+                }
+            }
+            else {
+                instrs.push({ kind: 'call', fn: ctx.qualifiedName(instr.fn) });
+            }
+            // Copy return value to dst if needed
+            if (instr.dst) {
+                const retSlot = { player: '$ret', obj: ctx.objective };
+                instrs.push({ kind: 'score_copy', dst: ctx.slot(instr.dst), src: retSlot });
+            }
+            break;
+        }
+        case 'call_macro': {
+            const macroStorage = `rs:macro_args`;
+            // Store each arg to NBT
+            for (const arg of instr.args) {
+                const srcSlot = operandToSlot(arg.value, ctx, instrs);
+                instrs.push({
+                    kind: 'store_score_to_nbt',
+                    ns: 'rs:macro_args',
+                    path: arg.name,
+                    type: arg.type,
+                    scale: arg.scale,
+                    src: srcSlot,
+                });
+            }
+            instrs.push({ kind: 'call_macro', fn: ctx.qualifiedName(instr.fn), storage: macroStorage });
+            // Copy return value to dst if needed
+            if (instr.dst) {
+                const retSlot = { player: '$ret', obj: ctx.objective };
+                instrs.push({ kind: 'score_copy', dst: ctx.slot(instr.dst), src: retSlot });
+            }
+            break;
+        }
+        case 'call_context': {
+            instrs.push({
+                kind: 'call_context',
+                fn: ctx.qualifiedName(instr.fn),
+                subcommands: instr.subcommands,
+            });
+            break;
+        }
+        default:
+            break;
+    }
+}
+// ---------------------------------------------------------------------------
+// Terminator lowering
+// ---------------------------------------------------------------------------
+function lowerTerminator(term, fn, ctx, instrs, visited) {
+    const beforeLen = instrs.length;
+    lowerTerminatorInner(term, fn, ctx, instrs, visited);
+    ctx.tagSourceLoc(instrs, beforeLen, term.sourceLoc);
+}
+function lowerTerminatorInner(term, fn, ctx, instrs, visited) {
+    switch (term.kind) {
+        case 'return': {
+            if (term.value) {
+                const retSlot = { player: '$ret', obj: ctx.objective };
+                const srcSlot = operandToSlot(term.value, ctx, instrs);
+                instrs.push({ kind: 'return_value', slot: srcSlot });
+            }
+            break;
+        }
+        case 'jump': {
+            if (ctx.isMultiPred(term.target)) {
+                // Target has multiple predecessors — call the extracted function
+                instrs.push({ kind: 'call', fn: ctx.qualifiedName(ctx.getBlockFnName(term.target)) });
+            }
+            else {
+                // Inline the target block's instructions
+                lowerBlock(term.target, fn, ctx, instrs, visited);
+            }
+            break;
+        }
+        case 'branch': {
+            const condSlot = operandToSlot(term.cond, ctx, instrs);
+            // Then branch: use `return run function` to atomically call and exit.
+            // This prevents fallthrough to the else-branch even when recursive calls
+            // (e.g. continue → loop header → loop body) clobber the condition slot.
+            const thenFnName = emitBranchTarget(term.then, fn, ctx, visited);
+            instrs.push({
+                kind: 'raw',
+                cmd: `execute if score ${condSlot.player} ${condSlot.obj} matches 1 run return run function ${ctx.qualifiedName(thenFnName)}`,
+            });
+            // Else branch: if we reach here, cond was not 1 (the then-path returned).
+            const elseFnName = emitBranchTarget(term.else, fn, ctx, visited);
+            instrs.push({ kind: 'call', fn: ctx.qualifiedName(elseFnName) });
+            break;
+        }
+    }
+}
+/**
+ * Emit a branch target as a separate LIR function and return its name.
+ * If the target is already a multi-pred block with a function, reuse it.
+ */
+function emitBranchTarget(blockId, fn, ctx, parentVisited) {
+    // If already has a function (multi-pred), return its name
+    if (ctx.isMultiPred(blockId)) {
+        // Make sure the block gets emitted
+        if (!parentVisited.has(blockId)) {
+            const blockInstrs = [];
+            const blockVisited = new Set();
+            lowerBlock(blockId, fn, ctx, blockInstrs, blockVisited);
+            ctx.addFunction({
+                name: ctx.getBlockFnName(blockId),
+                instructions: blockInstrs,
+                isMacro: false,
+                macroParams: [],
+            });
+            parentVisited.add(blockId);
+        }
+        return ctx.getBlockFnName(blockId);
+    }
+    // Create a new function for this branch target
+    const branchFnName = ctx.getBlockFnName(blockId);
+    const blockInstrs = [];
+    const blockVisited = new Set();
+    lowerBlock(blockId, fn, ctx, blockInstrs, blockVisited);
+    ctx.addFunction({
+        name: branchFnName,
+        instructions: blockInstrs,
+        isMacro: false,
+        macroParams: [],
+    });
+    // Mark visited so parent doesn't re-inline
+    parentVisited.add(blockId);
+    return branchFnName;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Lower an operand into a named temp slot (copy const or score_copy) */
+function lowerOperandToSlot(dstTemp, src, ctx, instrs) {
+    const dst = ctx.slot(dstTemp);
+    if (src.kind === 'const') {
+        instrs.push({ kind: 'score_set', dst, value: src.value });
+    }
+    else {
+        instrs.push({ kind: 'score_copy', dst, src: ctx.slot(src.name) });
+    }
+}
+/** Lower an operand into a specific slot (not by temp name) */
+function lowerOperandToSlotDirect(dst, src, ctx, instrs) {
+    if (src.kind === 'const') {
+        instrs.push({ kind: 'score_set', dst, value: src.value });
+    }
+    else {
+        instrs.push({ kind: 'score_copy', dst, src: ctx.slot(src.name) });
+    }
+}
+/** Get a slot for an operand, emitting a score_set for constants into a temp */
+function operandToSlot(op, ctx, instrs) {
+    if (op.kind === 'temp') {
+        return ctx.slot(op.name);
+    }
+    // Constant → need a temporary slot
+    return constSlot(op.value, ctx, instrs);
+}
+/** Create a constant slot with a given value */
+function constSlot(value, ctx, instrs) {
+    const slot = { player: `$__const_${value}`, obj: ctx.objective };
+    instrs.push({ kind: 'score_set', dst: slot, value });
+    return slot;
+}
+/** Apply a binary score operation: dst op= src */
+function lowerBinOp(dstTemp, b, scoreKind, ctx, instrs) {
+    const dst = ctx.slot(dstTemp);
+    const srcSlot = operandToSlot(b, ctx, instrs);
+    instrs.push({ kind: scoreKind, dst, src: srcSlot });
+}
+function getTermTargets(term) {
+    switch (term.kind) {
+        case 'jump': return [term.target];
+        case 'branch': return [term.then, term.else];
+        case 'return': return [];
+        default: return [];
+    }
+}
+//# sourceMappingURL=lower.js.map

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

@@ -0,0 +1,139 @@
+/**
+ * LIR (Low-level IR) Types — Stage 5 of the RedScript compiler pipeline.
+ *
+ * LIR is 2-address, MC-specific, typed nodes — no raw strings.
+ * Each LIR instruction maps 1:1 (or near) to one MC command.
+ *
+ * Spec: docs/compiler-pipeline-redesign.md § "LIR Instruction Set"
+ */
+import type { CmpOp, NBTType, ExecuteSubcmd, SourceLoc } from '../mir/types';
+export interface Slot {
+    player: string;
+    obj: string;
+}
+export type { CmpOp, NBTType, ExecuteSubcmd, SourceLoc };
+export type LIRInstrBase = {
+    sourceLoc?: SourceLoc;
+};
+export type LIRInstr = LIRInstrBase & ({
+    kind: 'score_set';
+    dst: Slot;
+    value: number;
+} | {
+    kind: 'score_copy';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_add';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_sub';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_mul';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_div';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_mod';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_min';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_max';
+    dst: Slot;
+    src: Slot;
+} | {
+    kind: 'score_swap';
+    a: Slot;
+    b: Slot;
+} | {
+    kind: 'store_cmd_to_score';
+    dst: Slot;
+    cmd: LIRInstr;
+} | {
+    kind: 'store_score_to_nbt';
+    ns: string;
+    path: string;
+    type: NBTType;
+    scale: number;
+    src: Slot;
+} | {
+    kind: 'store_nbt_to_score';
+    dst: Slot;
+    ns: string;
+    path: string;
+    scale: number;
+} | {
+    kind: 'nbt_set_literal';
+    ns: string;
+    path: string;
+    value: string;
+} | {
+    kind: 'nbt_copy';
+    srcNs: string;
+    srcPath: string;
+    dstNs: string;
+    dstPath: string;
+} | {
+    kind: 'call';
+    fn: string;
+} | {
+    kind: 'call_macro';
+    fn: string;
+    storage: string;
+} | {
+    kind: 'call_if_matches';
+    fn: string;
+    slot: Slot;
+    range: string;
+} | {
+    kind: 'call_unless_matches';
+    fn: string;
+    slot: Slot;
+    range: string;
+} | {
+    kind: 'call_if_score';
+    fn: string;
+    a: Slot;
+    op: CmpOp;
+    b: Slot;
+} | {
+    kind: 'call_unless_score';
+    fn: string;
+    a: Slot;
+    op: CmpOp;
+    b: Slot;
+} | {
+    kind: 'call_context';
+    fn: string;
+    subcommands: ExecuteSubcmd[];
+} | {
+    kind: 'return_value';
+    slot: Slot;
+} | {
+    kind: 'macro_line';
+    template: string;
+} | {
+    kind: 'raw';
+    cmd: string;
+});
+export interface LIRFunction {
+    name: string;
+    instructions: LIRInstr[];
+    isMacro: boolean;
+    macroParams: string[];
+}
+export interface LIRModule {
+    functions: LIRFunction[];
+    namespace: string;
+    objective: string;
+}

package/dist/src/lir/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * LIR (Low-level IR) Types — Stage 5 of the RedScript compiler pipeline.
+ *
+ * LIR is 2-address, MC-specific, typed nodes — no raw strings.
+ * Each LIR instruction maps 1:1 (or near) to one MC command.
+ *
+ * Spec: docs/compiler-pipeline-redesign.md § "LIR Instruction Set"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * LIR Verifier — validates structural invariants of LIR modules.
+ *
+ * Checks:
+ * 1. All Slots use the module's objective
+ * 2. No undefined function references (call/call_if_* targets exist)
+ * 3. macro_line only appears in isMacro functions
+ */
+import type { LIRModule } from './types';
+export interface LIRVerifyError {
+    fn: string;
+    message: string;
+}
+export declare function verifyLIR(module: LIRModule): LIRVerifyError[];