redscript-mc 1.2.30 → 2.1.0

package/src/mir/macro.ts

@@ -0,0 +1,167 @@
+/**
+ * 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, HIRExpr, HIRStmt, HIRBlock } from '../hir/types'
+
+// ---------------------------------------------------------------------------
+// Known builtins that emit MC commands with inline arguments
+// ---------------------------------------------------------------------------
+
+/** Builtins whose arguments appear literally in MC commands */
+export const 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',
+])
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+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 function detectMacroFunctions(hir: HIRModule): Map<string, MacroFunctionInfo> {
+  const result = new Map<string, MacroFunctionInfo>()
+
+  for (const fn of hir.functions) {
+    const paramNames = new Set(fn.params.map(p => p.name))
+    const macroParams = new Set<string>()
+    scanBlock(fn.body, paramNames, macroParams)
+    if (macroParams.size > 0) {
+      const paramTypes = new Map<string, string>()
+      for (const p of fn.params) {
+        const typeName = p.type?.kind === 'named' ? (p.type as any).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<string>()
+      scanBlock(m.body, paramNames, macroParams)
+      if (macroParams.size > 0) {
+        const paramTypes = new Map<string, string>()
+        for (const p of m.params) {
+          const typeName = p.type?.kind === 'named' ? (p.type as any).name : 'int'
+          paramTypes.set(p.name, typeName)
+        }
+        result.set(`${ib.typeName}::${m.name}`, { macroParams, paramTypes })
+      }
+    }
+  }
+
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// HIR scanning
+// ---------------------------------------------------------------------------
+
+function scanBlock(stmts: HIRBlock, paramNames: Set<string>, macroParams: Set<string>): void {
+  for (const stmt of stmts) scanStmt(stmt, paramNames, macroParams)
+}
+
+function scanStmt(stmt: HIRStmt, paramNames: Set<string>, macroParams: Set<string>): void {
+  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: HIRExpr, paramNames: Set<string>, macroParams: Set<string>): void {
+  if (expr.kind === 'call' && 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: HIRExpr, paramNames: Set<string>, macroParams: Set<string>): void {
+  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)
+    }
+  }
+}

package/src/mir/types.ts

@@ -0,0 +1,117 @@
+/**
+ * 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"
+ */
+
+// A temporary variable — unique within a function, named t0, t1, t2...
+export type Temp = string
+
+// Source location from the original .mcrs file
+export interface SourceLoc {
+  file: string
+  line: number
+  col: number
+}
+
+// An operand: either a temp or an inline constant
+export type Operand =
+  | { kind: 'temp'; name: Temp }
+  | { kind: 'const'; value: number }
+
+// A basic block identifier
+export type BlockId = string
+
+// Comparison operators (for cmp instruction)
+export type CmpOp = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge'
+
+// NBT value types (for nbt_write)
+export type NBTType = 'int' | 'double' | 'float' | 'long' | 'short' | 'byte'
+
+// ---------------------------------------------------------------------------
+// Execute subcommands (used in call_context)
+// ---------------------------------------------------------------------------
+
+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 }
+
+// ---------------------------------------------------------------------------
+// MIR Instructions
+// ---------------------------------------------------------------------------
+
+// Base type for all MIR instructions — carries optional source location
+export type MIRInstrBase = { sourceLoc?: SourceLoc }
+
+export type MIRInstr = MIRInstrBase & (
+  // ── Constants & copies ──────────────────────────────────────────────────
+  | { kind: 'const'; dst: Temp; value: number }
+  | { kind: 'copy'; dst: Temp; src: Operand }
+
+  // ── Integer arithmetic ──────────────────────────────────────────────────
+  | { 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 }
+
+  // ── Comparison (result is 0 or 1) ────────────────────────────────────────
+  | { kind: 'cmp'; dst: Temp; op: CmpOp; a: Operand; b: Operand }
+
+  // ── Boolean logic ────────────────────────────────────────────────────────
+  | { kind: 'and'; dst: Temp; a: Operand; b: Operand }
+  | { kind: 'or'; dst: Temp; a: Operand; b: Operand }
+  | { kind: 'not'; dst: Temp; src: Operand }
+
+  // ── NBT storage ──────────────────────────────────────────────────────────
+  | { kind: 'nbt_read'; dst: Temp; ns: string; path: string; scale: number }
+  | { kind: 'nbt_write'; ns: string; path: string; type: NBTType; scale: number; src: Operand }
+
+  // ── Function calls ────────────────────────────────────────────────────────
+  | { 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[] }
+
+  // ── Terminators (exactly one per basic block, must be last) ──────────────
+  | { kind: 'jump'; target: BlockId }
+  | { kind: 'branch'; cond: Operand; then: BlockId; else: BlockId }
+  | { kind: 'return'; value: Operand | null }
+)
+
+// ---------------------------------------------------------------------------
+// Basic block and function structure
+// ---------------------------------------------------------------------------
+
+export interface MIRBlock {
+  id: BlockId
+  instrs: MIRInstr[]   // non-terminator instructions
+  term: MIRInstr        // must be jump | branch | return
+  preds: BlockId[]      // predecessor block ids (for dataflow)
+}
+
+export interface MIRFunction {
+  name: string
+  params: { name: Temp; isMacroParam: boolean }[]
+  blocks: MIRBlock[]
+  entry: BlockId         // entry block id (always 'entry')
+  isMacro: boolean       // true if any param is a macro param
+}
+
+export interface MIRModule {
+  functions: MIRFunction[]
+  namespace: string
+  objective: string      // scoreboard objective (default: __<namespace>)
+}

package/src/mir/verify.ts

@@ -0,0 +1,218 @@
+/**
+ * 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, MIRFunction, MIRBlock, MIRInstr, Operand, Temp } from './types'
+
+export interface VerifyError {
+  fn: string
+  block?: string
+  message: string
+}
+
+export function verifyMIR(module: MIRModule): VerifyError[] {
+  const errors: VerifyError[] = []
+  for (const fn of module.functions) {
+    errors.push(...verifyFunction(fn))
+  }
+  return errors
+}
+
+function verifyFunction(fn: MIRFunction): VerifyError[] {
+  const errors: VerifyError[] = []
+
+  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<string>()
+  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: string[] = [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<Temp>()
+  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: MIRInstr): boolean {
+  return instr.kind === 'jump' || instr.kind === 'branch' || instr.kind === 'return'
+}
+
+function getTermTargets(term: MIRInstr): string[] {
+  switch (term.kind) {
+    case 'jump': return [term.target]
+    case 'branch': return [term.then, term.else]
+    case 'return': return []
+    default: return []
+  }
+}
+
+function getDst(instr: MIRInstr): Temp | null {
+  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: Operand): Temp[] {
+  return op.kind === 'temp' ? [op.name] : []
+}
+
+function getUsedTemps(instr: MIRInstr): Temp[] {
+  const temps: Temp[] = []
+  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
+}

package/src/optimizer/block_merge.ts

@@ -0,0 +1,93 @@
+/**
+ * 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, MIRBlock, BlockId } from '../mir/types'
+
+export function blockMerge(fn: MIRFunction): MIRFunction {
+  let blocks = fn.blocks
+
+  // Iterate until no more merges possible
+  let changed = true
+  while (changed) {
+    changed = false
+    const blockMap = new Map(blocks.map(b => [b.id, b]))
+    const predCounts = computePredCounts(blocks)
+
+    const newBlocks: MIRBlock[] = []
+    const removed = new Set<BlockId>()
+
+    for (const block of blocks) {
+      if (removed.has(block.id)) continue
+
+      // Check: does this block jump unconditionally to a single-pred successor?
+      if (block.term.kind === 'jump') {
+        const targetId = block.term.target
+        const target = blockMap.get(targetId)
+        if (target && targetId !== fn.entry && predCounts.get(targetId) === 1) {
+          // Merge target into this block
+          const merged: MIRBlock = {
+            id: block.id,
+            instrs: [...block.instrs, ...target.instrs],
+            term: target.term,
+            preds: block.preds,
+          }
+          newBlocks.push(merged)
+          removed.add(targetId)
+          changed = true
+          continue
+        }
+      }
+
+      newBlocks.push(block)
+    }
+
+    blocks = newBlocks
+  }
+
+  // Recompute preds after merging
+  blocks = recomputePreds(blocks)
+
+  return { ...fn, blocks }
+}
+
+function computePredCounts(blocks: MIRBlock[]): Map<BlockId, number> {
+  const counts = new Map<BlockId, number>()
+  for (const b of blocks) counts.set(b.id, 0)
+
+  for (const block of blocks) {
+    for (const target of getTermTargets(block.term)) {
+      counts.set(target, (counts.get(target) ?? 0) + 1)
+    }
+  }
+  return counts
+}
+
+function recomputePreds(blocks: MIRBlock[]): MIRBlock[] {
+  const predMap = new Map<BlockId, BlockId[]>()
+  for (const b of blocks) predMap.set(b.id, [])
+
+  for (const block of blocks) {
+    for (const target of getTermTargets(block.term)) {
+      const preds = predMap.get(target)
+      if (preds) preds.push(block.id)
+    }
+  }
+
+  return blocks.map(b => ({ ...b, preds: predMap.get(b.id) ?? [] }))
+}
+
+function getTermTargets(term: MIRBlock['term']): BlockId[] {
+  switch (term.kind) {
+    case 'jump': return [term.target]
+    case 'branch': return [term.then, term.else]
+    default: return []
+  }
+}

package/src/optimizer/branch_simplify.ts

@@ -0,0 +1,27 @@
+/**
+ * Branch Simplification — MIR optimization pass.
+ *
+ * Replaces `branch(const, then, else)` with an unconditional `jump`:
+ * - branch(nonzero, then, else) → jump(then)
+ * - branch(0, then, else) → jump(else)
+ */
+
+import type { MIRFunction, MIRBlock } from '../mir/types'
+
+export function branchSimplify(fn: MIRFunction): MIRFunction {
+  return {
+    ...fn,
+    blocks: fn.blocks.map(simplifyBlock),
+  }
+}
+
+function simplifyBlock(block: MIRBlock): MIRBlock {
+  if (block.term.kind !== 'branch') return block
+  if (block.term.cond.kind !== 'const') return block
+
+  const target = block.term.cond.value !== 0 ? block.term.then : block.term.else
+  return {
+    ...block,
+    term: { kind: 'jump', target },
+  }
+}