redscript-mc 2.4.0 → 2.5.0

package/dist/src2/mir/macro.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Macro function detection — pre-scans HIR to find parameters used in
+ * builtin call positions (coordinates, entity types, etc.)
+ *
+ * A function becomes a "macro function" when one of its params appears
+ * in a position that requires literal substitution in the MC command
+ * (e.g. summon coords, particle coords, setblock coords, local/relative
+ * coords like ^px or ~height).
+ */
+import type { HIRModule } from '../hir/types';
+/** Builtins whose arguments appear literally in MC commands */
+export declare const BUILTIN_SET: Set<string>;
+export interface MacroFunctionInfo {
+    macroParams: Set<string>;
+    /** param name → param type name (for NBT scale inference) */
+    paramTypes: Map<string, string>;
+}
+/**
+ * Pre-scan HIR functions to detect which params need macro treatment.
+ * Returns a map: function name → MacroFunctionInfo.
+ */
+export declare function detectMacroFunctions(hir: HIRModule): Map<string, MacroFunctionInfo>;

package/dist/src2/mir/macro.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Macro function detection — pre-scans HIR to find parameters used in
+ * builtin call positions (coordinates, entity types, etc.)
+ *
+ * A function becomes a "macro function" when one of its params appears
+ * in a position that requires literal substitution in the MC command
+ * (e.g. summon coords, particle coords, setblock coords, local/relative
+ * coords like ^px or ~height).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_SET = void 0;
+exports.detectMacroFunctions = detectMacroFunctions;
+// ---------------------------------------------------------------------------
+// Known builtins that emit MC commands with inline arguments
+// ---------------------------------------------------------------------------
+/** Builtins whose arguments appear literally in MC commands */
+exports.BUILTIN_SET = new Set([
+    'say', 'tell', 'tellraw', 'title', 'actionbar', 'subtitle', 'title_times',
+    'announce', 'give', 'kill', 'effect', 'effect_clear',
+    'summon', 'particle', 'playsound', 'clear', 'weather',
+    'time_set', 'time_add', 'gamerule', 'tag_add', 'tag_remove',
+    'kick', 'setblock', 'fill', 'clone', 'difficulty', 'xp_add', 'xp_set',
+]);
+/**
+ * Pre-scan HIR functions to detect which params need macro treatment.
+ * Returns a map: function name → MacroFunctionInfo.
+ */
+function detectMacroFunctions(hir) {
+    const result = new Map();
+    for (const fn of hir.functions) {
+        const paramNames = new Set(fn.params.map(p => p.name));
+        const macroParams = new Set();
+        scanBlock(fn.body, paramNames, macroParams);
+        if (macroParams.size > 0) {
+            const paramTypes = new Map();
+            for (const p of fn.params) {
+                const typeName = p.type?.kind === 'named' ? p.type.name : 'int';
+                paramTypes.set(p.name, typeName);
+            }
+            result.set(fn.name, { macroParams, paramTypes });
+        }
+    }
+    for (const ib of hir.implBlocks) {
+        for (const m of ib.methods) {
+            const paramNames = new Set(m.params.map(p => p.name));
+            const macroParams = new Set();
+            scanBlock(m.body, paramNames, macroParams);
+            if (macroParams.size > 0) {
+                const paramTypes = new Map();
+                for (const p of m.params) {
+                    const typeName = p.type?.kind === 'named' ? p.type.name : 'int';
+                    paramTypes.set(p.name, typeName);
+                }
+                result.set(`${ib.typeName}::${m.name}`, { macroParams, paramTypes });
+            }
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// HIR scanning
+// ---------------------------------------------------------------------------
+function scanBlock(stmts, paramNames, macroParams) {
+    for (const stmt of stmts)
+        scanStmt(stmt, paramNames, macroParams);
+}
+function scanStmt(stmt, paramNames, macroParams) {
+    switch (stmt.kind) {
+        case 'expr':
+            scanExpr(stmt.expr, paramNames, macroParams);
+            break;
+        case 'let':
+            scanExpr(stmt.init, paramNames, macroParams);
+            break;
+        case 'return':
+            if (stmt.value)
+                scanExpr(stmt.value, paramNames, macroParams);
+            break;
+        case 'if':
+            scanExpr(stmt.cond, paramNames, macroParams);
+            scanBlock(stmt.then, paramNames, macroParams);
+            if (stmt.else_)
+                scanBlock(stmt.else_, paramNames, macroParams);
+            break;
+        case 'while':
+            scanExpr(stmt.cond, paramNames, macroParams);
+            scanBlock(stmt.body, paramNames, macroParams);
+            if (stmt.step)
+                scanBlock(stmt.step, paramNames, macroParams);
+            break;
+        case 'foreach':
+            scanBlock(stmt.body, paramNames, macroParams);
+            break;
+        case 'match':
+            scanExpr(stmt.expr, paramNames, macroParams);
+            for (const arm of stmt.arms)
+                scanBlock(arm.body, paramNames, macroParams);
+            break;
+        case 'execute':
+            scanBlock(stmt.body, paramNames, macroParams);
+            break;
+        case 'raw': break;
+    }
+}
+function scanExpr(expr, paramNames, macroParams) {
+    if (expr.kind === 'call' && exports.BUILTIN_SET.has(expr.fn)) {
+        // Check if any argument is a param identifier or a coord with a param variable
+        for (const arg of expr.args) {
+            checkMacroArg(arg, paramNames, macroParams);
+        }
+        // Recurse into args for nested expressions
+        for (const arg of expr.args)
+            scanExpr(arg, paramNames, macroParams);
+        return;
+    }
+    // Recurse into sub-expressions
+    switch (expr.kind) {
+        case 'call':
+            for (const arg of expr.args)
+                scanExpr(arg, paramNames, macroParams);
+            break;
+        case 'invoke':
+            scanExpr(expr.callee, paramNames, macroParams);
+            for (const arg of expr.args)
+                scanExpr(arg, paramNames, macroParams);
+            break;
+        case 'binary':
+            scanExpr(expr.left, paramNames, macroParams);
+            scanExpr(expr.right, paramNames, macroParams);
+            break;
+        case 'unary':
+            scanExpr(expr.operand, paramNames, macroParams);
+            break;
+        case 'assign':
+            scanExpr(expr.value, paramNames, macroParams);
+            break;
+        case 'member_assign':
+            scanExpr(expr.obj, paramNames, macroParams);
+            scanExpr(expr.value, paramNames, macroParams);
+            break;
+        case 'member':
+            scanExpr(expr.obj, paramNames, macroParams);
+            break;
+        case 'index':
+            scanExpr(expr.obj, paramNames, macroParams);
+            scanExpr(expr.index, paramNames, macroParams);
+            break;
+        case 'static_call':
+            for (const arg of expr.args)
+                scanExpr(arg, paramNames, macroParams);
+            break;
+    }
+}
+/** Check if a single argument expression references a function parameter in a macro position */
+function checkMacroArg(expr, paramNames, macroParams) {
+    if (expr.kind === 'ident' && paramNames.has(expr.name)) {
+        macroParams.add(expr.name);
+    }
+    else if (expr.kind === 'local_coord' || expr.kind === 'rel_coord') {
+        // ^varname or ~varname — extract the variable part
+        const rest = expr.value.slice(1);
+        if (rest && /^[a-zA-Z_]\w*$/.test(rest) && paramNames.has(rest)) {
+            macroParams.add(rest);
+        }
+    }
+}
+//# sourceMappingURL=macro.js.map

package/dist/src2/mir/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * MIR (Mid-level IR) Types — Stage 3 of the RedScript compiler pipeline.
+ *
+ * MIR is a 3-address, explicit-CFG representation with versioned temporaries.
+ * Every instruction produces at most one result into a fresh temporary.
+ *
+ * Spec: docs/compiler-pipeline-redesign.md § "MIR Instruction Set"
+ */
+export type Temp = string;
+export type Operand = {
+    kind: 'temp';
+    name: Temp;
+} | {
+    kind: 'const';
+    value: number;
+};
+export type BlockId = string;
+export type CmpOp = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge';
+export type NBTType = 'int' | 'double' | 'float' | 'long' | 'short' | 'byte';
+export type ExecuteSubcmd = {
+    kind: 'as';
+    selector: string;
+} | {
+    kind: 'at';
+    selector: string;
+} | {
+    kind: 'at_self';
+} | {
+    kind: 'positioned';
+    x: string;
+    y: string;
+    z: string;
+} | {
+    kind: 'rotated';
+    yaw: string;
+    pitch: string;
+} | {
+    kind: 'in';
+    dimension: string;
+} | {
+    kind: 'anchored';
+    anchor: 'eyes' | 'feet';
+} | {
+    kind: 'if_score';
+    a: string;
+    op: CmpOp;
+    b: string;
+} | {
+    kind: 'unless_score';
+    a: string;
+    op: CmpOp;
+    b: string;
+} | {
+    kind: 'if_matches';
+    score: string;
+    range: string;
+} | {
+    kind: 'unless_matches';
+    score: string;
+    range: string;
+};
+export type MIRInstr = {
+    kind: 'const';
+    dst: Temp;
+    value: number;
+} | {
+    kind: 'copy';
+    dst: Temp;
+    src: Operand;
+} | {
+    kind: 'add';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'sub';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'mul';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'div';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'mod';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'neg';
+    dst: Temp;
+    src: Operand;
+} | {
+    kind: 'cmp';
+    dst: Temp;
+    op: CmpOp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'and';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'or';
+    dst: Temp;
+    a: Operand;
+    b: Operand;
+} | {
+    kind: 'not';
+    dst: Temp;
+    src: Operand;
+} | {
+    kind: 'nbt_read';
+    dst: Temp;
+    ns: string;
+    path: string;
+    scale: number;
+} | {
+    kind: 'nbt_write';
+    ns: string;
+    path: string;
+    type: NBTType;
+    scale: number;
+    src: Operand;
+} | {
+    kind: 'call';
+    dst: Temp | null;
+    fn: string;
+    args: Operand[];
+} | {
+    kind: 'call_macro';
+    dst: Temp | null;
+    fn: string;
+    args: {
+        name: string;
+        value: Operand;
+        type: NBTType;
+        scale: number;
+    }[];
+} | {
+    kind: 'call_context';
+    fn: string;
+    subcommands: ExecuteSubcmd[];
+} | {
+    kind: 'jump';
+    target: BlockId;
+} | {
+    kind: 'branch';
+    cond: Operand;
+    then: BlockId;
+    else: BlockId;
+} | {
+    kind: 'return';
+    value: Operand | null;
+};
+export interface MIRBlock {
+    id: BlockId;
+    instrs: MIRInstr[];
+    term: MIRInstr;
+    preds: BlockId[];
+}
+export interface MIRFunction {
+    name: string;
+    params: {
+        name: Temp;
+        isMacroParam: boolean;
+    }[];
+    blocks: MIRBlock[];
+    entry: BlockId;
+    isMacro: boolean;
+}
+export interface MIRModule {
+    functions: MIRFunction[];
+    namespace: string;
+    objective: string;
+}

package/dist/src2/mir/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * MIR (Mid-level IR) Types — Stage 3 of the RedScript compiler pipeline.
+ *
+ * MIR is a 3-address, explicit-CFG representation with versioned temporaries.
+ * Every instruction produces at most one result into a fresh temporary.
+ *
+ * Spec: docs/compiler-pipeline-redesign.md § "MIR Instruction Set"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/src2/mir/verify.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MIR Verifier — validates structural invariants of MIR modules.
+ *
+ * Checks:
+ * 1. Every block ends with exactly one terminator (jump | branch | return)
+ * 2. Every temp used is defined before use (in the block or as a param)
+ * 3. No unreachable blocks (all blocks reachable from entry)
+ * 4. Branch/jump targets must exist in the function
+ */
+import type { MIRModule } from './types';
+export interface VerifyError {
+    fn: string;
+    block?: string;
+    message: string;
+}
+export declare function verifyMIR(module: MIRModule): VerifyError[];

package/dist/src2/mir/verify.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * MIR Verifier — validates structural invariants of MIR modules.
+ *
+ * Checks:
+ * 1. Every block ends with exactly one terminator (jump | branch | return)
+ * 2. Every temp used is defined before use (in the block or as a param)
+ * 3. No unreachable blocks (all blocks reachable from entry)
+ * 4. Branch/jump targets must exist in the function
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMIR = verifyMIR;
+function verifyMIR(module) {
+    const errors = [];
+    for (const fn of module.functions) {
+        errors.push(...verifyFunction(fn));
+    }
+    return errors;
+}
+function verifyFunction(fn) {
+    const errors = [];
+    const blockIds = new Set(fn.blocks.map(b => b.id));
+    // 1. Check terminators
+    for (const block of fn.blocks) {
+        if (!isTerminator(block.term)) {
+            errors.push({
+                fn: fn.name,
+                block: block.id,
+                message: `block '${block.id}' does not end with a terminator (found '${block.term.kind}')`,
+            });
+        }
+        // Check that no non-terminator instruction is a terminator
+        for (const instr of block.instrs) {
+            if (isTerminator(instr)) {
+                errors.push({
+                    fn: fn.name,
+                    block: block.id,
+                    message: `block '${block.id}' has terminator '${instr.kind}' in non-terminal position`,
+                });
+            }
+        }
+    }
+    // 2. Check that branch/jump targets exist
+    for (const block of fn.blocks) {
+        const targets = getTermTargets(block.term);
+        for (const target of targets) {
+            if (!blockIds.has(target)) {
+                errors.push({
+                    fn: fn.name,
+                    block: block.id,
+                    message: `block '${block.id}' references non-existent target '${target}'`,
+                });
+            }
+        }
+    }
+    // 3. Check reachability from entry
+    const reachable = new Set();
+    const entryBlock = fn.blocks.find(b => b.id === fn.entry);
+    if (!entryBlock) {
+        errors.push({
+            fn: fn.name,
+            message: `entry block '${fn.entry}' not found`,
+        });
+    }
+    else {
+        // BFS from entry
+        const queue = [fn.entry];
+        while (queue.length > 0) {
+            const id = queue.shift();
+            if (reachable.has(id))
+                continue;
+            reachable.add(id);
+            const block = fn.blocks.find(b => b.id === id);
+            if (block) {
+                for (const target of getTermTargets(block.term)) {
+                    if (!reachable.has(target)) {
+                        queue.push(target);
+                    }
+                }
+            }
+        }
+        for (const block of fn.blocks) {
+            if (!reachable.has(block.id)) {
+                errors.push({
+                    fn: fn.name,
+                    block: block.id,
+                    message: `block '${block.id}' is unreachable from entry`,
+                });
+            }
+        }
+    }
+    // 4. Check use-before-def for temporaries
+    // Collect all defined temps: params + all dst fields in instructions
+    const allDefs = new Set();
+    for (const p of fn.params)
+        allDefs.add(p.name);
+    for (const block of fn.blocks) {
+        for (const instr of block.instrs) {
+            const dst = getDst(instr);
+            if (dst)
+                allDefs.add(dst);
+        }
+        const termDst = getDst(block.term);
+        if (termDst)
+            allDefs.add(termDst);
+    }
+    // Check that every temp used in an operand is in allDefs
+    for (const block of fn.blocks) {
+        for (const instr of block.instrs) {
+            for (const used of getUsedTemps(instr)) {
+                if (!allDefs.has(used)) {
+                    errors.push({
+                        fn: fn.name,
+                        block: block.id,
+                        message: `temp '${used}' used but never defined`,
+                    });
+                }
+            }
+        }
+        for (const used of getUsedTemps(block.term)) {
+            if (!allDefs.has(used)) {
+                errors.push({
+                    fn: fn.name,
+                    block: block.id,
+                    message: `temp '${used}' used in terminator but never defined`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+function isTerminator(instr) {
+    return instr.kind === 'jump' || instr.kind === 'branch' || instr.kind === 'return';
+}
+function getTermTargets(term) {
+    switch (term.kind) {
+        case 'jump': return [term.target];
+        case 'branch': return [term.then, term.else];
+        case 'return': return [];
+        default: return [];
+    }
+}
+function getDst(instr) {
+    switch (instr.kind) {
+        case 'const':
+        case 'copy':
+        case 'add':
+        case 'sub':
+        case 'mul':
+        case 'div':
+        case 'mod':
+        case 'neg':
+        case 'cmp':
+        case 'and':
+        case 'or':
+        case 'not':
+        case 'nbt_read':
+            return instr.dst;
+        case 'call':
+        case 'call_macro':
+            return instr.dst;
+        default:
+            return null;
+    }
+}
+function getOperandTemps(op) {
+    return op.kind === 'temp' ? [op.name] : [];
+}
+function getUsedTemps(instr) {
+    const temps = [];
+    switch (instr.kind) {
+        case 'const':
+            break;
+        case 'copy':
+        case 'neg':
+        case 'not':
+            temps.push(...getOperandTemps(instr.src));
+            break;
+        case 'add':
+        case 'sub':
+        case 'mul':
+        case 'div':
+        case 'mod':
+        case 'cmp':
+        case 'and':
+        case 'or':
+            temps.push(...getOperandTemps(instr.a), ...getOperandTemps(instr.b));
+            break;
+        case 'nbt_read':
+            break;
+        case 'nbt_write':
+            temps.push(...getOperandTemps(instr.src));
+            break;
+        case 'call':
+            for (const arg of instr.args)
+                temps.push(...getOperandTemps(arg));
+            break;
+        case 'call_macro':
+            for (const arg of instr.args)
+                temps.push(...getOperandTemps(arg.value));
+            break;
+        case 'call_context':
+            break;
+        case 'jump':
+            break;
+        case 'branch':
+            temps.push(...getOperandTemps(instr.cond));
+            break;
+        case 'return':
+            if (instr.value)
+                temps.push(...getOperandTemps(instr.value));
+            break;
+    }
+    return temps;
+}
+//# sourceMappingURL=verify.js.map

package/dist/src2/optimizer/block_merge.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Block Merging — MIR optimization pass.
+ *
+ * Merges a block B into its sole predecessor A when:
+ * - A ends with an unconditional jump to B
+ * - B has exactly one predecessor (A)
+ * - B is not the entry block
+ *
+ * The merged block keeps A's id and combines A's instrs + B's instrs + B's terminator.
+ */
+import type { MIRFunction } from '../mir/types';
+export declare function blockMerge(fn: MIRFunction): MIRFunction;