redscript-mc 2.0.0 → 2.1.1

package/src/lir/budget.ts

@@ -0,0 +1,321 @@
+/**
+ * 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.
+ */
+
+import type { LIRModule, LIRFunction, LIRInstr } from './types'
+
+/** Default estimated iteration count when the upper bound is unknown */
+const DEFAULT_LOOP_ITERATIONS = 100
+
+/** Warning threshold: suggest @coroutine */
+export const BUDGET_WARN_THRESHOLD = 32768
+
+/** Error threshold: likely exceeds maxCommandChainLength */
+export const BUDGET_ERROR_THRESHOLD = 65536
+
+export interface BudgetDiagnostic {
+  level: 'warning' | 'error'
+  fnName: string
+  estimatedCommands: number
+  message: string
+}
+
+// ---------------------------------------------------------------------------
+// Call graph utilities
+// ---------------------------------------------------------------------------
+
+/** Extract all function names called by an instruction */
+function getCalledFunctions(instr: LIRInstr): string[] {
+  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: LIRModule): Map<string, Set<string>> {
+  const fnNames = new Set(mod.functions.map(f => f.name))
+  const graph = new Map<string, Set<string>>()
+
+  for (const fn of mod.functions) {
+    const callees = new Set<string>()
+    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: string, namespace: string): string {
+  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: Map<string, Set<string>>): string[][] {
+  let index = 0
+  const stack: string[] = []
+  const onStack = new Set<string>()
+  const indices = new Map<string, number>()
+  const lowlinks = new Map<string, number>()
+  const sccs: string[][] = []
+
+  function strongconnect(v: string): void {
+    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: string[] = []
+      let w: string
+      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: LIRInstr): number {
+  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: LIRFunction): number {
+  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: LIRFunction[]): number {
+  // 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
+ */
+export function estimateCommandCount(fnName: string, mod: LIRModule): number {
+  const fnMap = new Map<string, LIRFunction>()
+  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<string, string[]>()
+  for (const scc of sccs) {
+    for (const name of scc) {
+      fnToSCC.set(name, scc)
+    }
+  }
+
+  // Memoize estimated counts
+  const memo = new Map<string, number>()
+
+  function estimate(name: string, visiting: Set<string>): number {
+    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)
+ */
+export function analyzeBudget(
+  mod: LIRModule,
+  coroutineFunctions: Set<string> = new Set(),
+): BudgetDiagnostic[] {
+  const diagnostics: BudgetDiagnostic[] = []
+
+  // 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 > 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 > BUDGET_WARN_THRESHOLD) {
+      diagnostics.push({
+        level: 'warning',
+        fnName: fn.name,
+        estimatedCommands: estimated,
+        message: `loop may exceed tick budget (~${estimated} commands), consider @coroutine`,
+      })
+    }
+  }
+
+  return diagnostics
+}

package/{src2 → src}/lir/lower.ts

@@ -15,7 +15,7 @@ import type {
   MIRModule, MIRFunction, MIRBlock, MIRInstr, Operand, Temp, BlockId,
 } from '../mir/types'
 import type {
-  LIRModule, LIRFunction, LIRInstr, Slot,
+  LIRModule, LIRFunction, LIRInstr, Slot, SourceLoc,
 } from './types'
 
 // ---------------------------------------------------------------------------
@@ -77,6 +77,14 @@ class LoweringContext {
     this.functions.push(fn)
   }
 
+  /** Attach sourceLoc to newly added instructions (from the given start index onward) */
+  tagSourceLoc(instrs: LIRInstr[], fromIndex: number, sourceLoc: SourceLoc | undefined): void {
+    if (!sourceLoc) return
+    for (let i = fromIndex; i < instrs.length; i++) {
+      if (!instrs[i].sourceLoc) instrs[i].sourceLoc = sourceLoc
+    }
+  }
+
   analyzeBlocks(fn: MIRFunction): void {
     this.currentMIRFn = fn
     this.multiPredBlocks.clear()
@@ -197,6 +205,17 @@ function lowerInstr(
   fn: MIRFunction,
   ctx: LoweringContext,
   instrs: LIRInstr[],
+): void {
+  const beforeLen = instrs.length
+  lowerInstrInner(instr, fn, ctx, instrs)
+  ctx.tagSourceLoc(instrs, beforeLen, instr.sourceLoc)
+}
+
+function lowerInstrInner(
+  instr: MIRInstr,
+  fn: MIRFunction,
+  ctx: LoweringContext,
+  instrs: LIRInstr[],
 ): void {
   switch (instr.kind) {
     case 'const': {
@@ -391,6 +410,18 @@ function lowerTerminator(
   ctx: LoweringContext,
   instrs: LIRInstr[],
   visited: Set<BlockId>,
+): void {
+  const beforeLen = instrs.length
+  lowerTerminatorInner(term, fn, ctx, instrs, visited)
+  ctx.tagSourceLoc(instrs, beforeLen, term.sourceLoc)
+}
+
+function lowerTerminatorInner(
+  term: MIRInstr,
+  fn: MIRFunction,
+  ctx: LoweringContext,
+  instrs: LIRInstr[],
+  visited: Set<BlockId>,
 ): void {
   switch (term.kind) {
     case 'return': {

package/{src2 → src}/lir/types.ts

@@ -7,7 +7,7 @@
  * Spec: docs/compiler-pipeline-redesign.md § "LIR Instruction Set"
  */
 
-import type { CmpOp, NBTType, ExecuteSubcmd } from '../mir/types'
+import type { CmpOp, NBTType, ExecuteSubcmd, SourceLoc } from '../mir/types'
 
 // A scoreboard slot: fake-player name + objective
 export interface Slot {
@@ -16,13 +16,16 @@ export interface Slot {
 }
 
 // Re-export types used in LIR from MIR
-export type { CmpOp, NBTType, ExecuteSubcmd }
+export type { CmpOp, NBTType, ExecuteSubcmd, SourceLoc }
 
 // ---------------------------------------------------------------------------
 // LIR Instructions
 // ---------------------------------------------------------------------------
 
-export type LIRInstr =
+// Base type for all LIR instructions — carries optional source location
+export type LIRInstrBase = { sourceLoc?: SourceLoc }
+
+export type LIRInstr = LIRInstrBase & (
   // ── Scoreboard ───────────────────────────────────────────────────────────
   | { kind: 'score_set'; dst: Slot; value: number }
   // scoreboard players set <dst.player> <dst.obj> value
@@ -90,6 +93,7 @@ export type LIRInstr =
   // ── Arbitrary MC command ─────────────────────────────────────────────────
   | { kind: 'raw'; cmd: string }
   // Emitted verbatim. Use sparingly — prefer typed instructions.
+)
 
 // ---------------------------------------------------------------------------
 // LIR function and module structure

package/src/lsp/main.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * RedScript LSP server entry point.
+ * Communicates over stdio (standard LSP protocol).
+ *
+ * Usage: redscript-lsp  (started by your editor's LSP client)
+ */
+
+import './server'