redscript-mc 3.0.1 → 3.0.2

package/src/mc-test/client.ts

@@ -266,6 +266,46 @@ export class MCTestClient {
     }
   }
 
+  /**
+   * Dump all scoreboard entries for a namespace's objective (__<ns>).
+   * Returns { "$p0": 0, "$val": 11, "#result": 42, ... }
+   */
+  async dumpScores(ns: string): Promise<Record<string, number>> {
+    return this.get('/scoreboard/dump', { ns })
+      .then((r: any) => r.entries ?? {})
+  }
+
+  /**
+   * Dump all scoreboard entries for a specific objective.
+   */
+  async dumpScoresByObj(obj: string): Promise<Record<string, number>> {
+    return this.get('/scoreboard/dump', { obj })
+      .then((r: any) => r.entries ?? {})
+  }
+
+  /**
+   * Dump the raw NBT of an entire storage namespace.
+   */
+  async dumpStorage(storage: string): Promise<{ raw: string; ok: boolean }> {
+    return this.get('/storage/dump', { storage })
+  }
+
+  /**
+   * Assert multiple scoreboard values at once.
+   * Usage: await mc.assertScoreMap('ns', { '$p0': 11, '$ret': 2 })
+   */
+  async assertScoreMap(ns: string, expected: Record<string, number>): Promise<void> {
+    const actual = await this.dumpScores(ns)
+    for (const [key, val] of Object.entries(expected)) {
+      if (actual[key] !== val) {
+        throw new Error(
+          `assertScoreMap[${ns}] ${key}: expected ${val}, got ${actual[key] ?? '(unset)'}\n` +
+          `Full dump: ${JSON.stringify(actual)}`
+        )
+      }
+    }
+  }
+
   /**
    * Wait until a scoreboard value equals expected, up to timeout ms.
    */

package/src/mir/lower.ts

@@ -136,9 +136,12 @@ export function lowerToMIR(hir: HIRModule, sourceFile?: string): MIRModule {
     else if (c.value.kind === 'float_lit') constValues.set(c.name, Math.round(c.value.value * 10000))
   }
 
+  // Collect module-level global variable names (mutable lets at top level)
+  const globalVarNames = new Set<string>(hir.globals.map(g => g.name))
+
   const allFunctions: MIRFunction[] = []
   for (const f of hir.functions) {
-    const { fn, helpers } = lowerFunction(f, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, undefined, hirFnMap, specializedFnsRegistry, undefined, enumPayloads, constValues, singletonStructs, displayImpls)
+    const { fn, helpers } = lowerFunction(f, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, undefined, hirFnMap, specializedFnsRegistry, undefined, enumPayloads, constValues, singletonStructs, displayImpls, globalVarNames)
     allFunctions.push(fn, ...helpers)
   }
 
@@ -146,7 +149,7 @@ export function lowerToMIR(hir: HIRModule, sourceFile?: string): MIRModule {
   for (const ib of hir.implBlocks) {
     if (ib.traitName === 'Display') continue  // Display impls are inlined, not emitted as functions
     for (const m of ib.methods) {
-      const { fn, helpers } = lowerImplMethod(m, ib.typeName, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, enumPayloads, constValues)
+      const { fn, helpers } = lowerImplMethod(m, ib.typeName, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, enumPayloads, constValues, globalVarNames)
       allFunctions.push(fn, ...helpers)
     }
   }
@@ -226,6 +229,8 @@ class FnContext {
   singletonStructs: Set<string> = new Set()
   /** Display trait impls: typeName → f-string parts from to_string body (inlined at call sites) */
   displayImpls: Map<string, HIRFStringPart[]> = new Map()
+  /** Module-level global variable names — reads/writes must go through scoreboard */
+  globalVarNames: Set<string> = new Set()
 
   constructor(
     namespace: string,
@@ -366,6 +371,7 @@ function lowerFunction(
   constValues: Map<string, number> = new Map(),
   singletonStructs: Set<string> = new Set(),
   displayImpls: Map<string, HIRFStringPart[]> = new Map(),
+  globalVarNames: Set<string> = new Set(),
 ): { fn: MIRFunction; helpers: MIRFunction[] } {
   const mirFnName = overrideName ?? fn.name
   const ctx = new FnContext(namespace, mirFnName, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, timerCounter, enumPayloads)
@@ -373,6 +379,7 @@ function lowerFunction(
   ctx.constValues = constValues
   ctx.singletonStructs = singletonStructs
   ctx.displayImpls = displayImpls
+  ctx.globalVarNames = globalVarNames
   if (hirFnMap) ctx.hirFunctions = hirFnMap
   if (specializedFnsRegistry) ctx.specializedFnsRegistry = specializedFnsRegistry
   const fnMacroInfo = macroInfo.get(fn.name)
@@ -452,11 +459,13 @@ function lowerImplMethod(
   timerCounter: { count: number; timerId: number } = { count: 0, timerId: 0 },
   enumPayloads: Map<string, Map<string, { name: string; type: TypeNode }[]>> = new Map(),
   constValues: Map<string, number> = new Map(),
+  globalVarNames: Set<string> = new Set(),
 ): { fn: MIRFunction; helpers: MIRFunction[] } {
   const fnName = `${typeName}::${method.name}`
   const ctx = new FnContext(namespace, fnName, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, timerCounter, enumPayloads)
   ctx.sourceFile = method.sourceFile ?? sourceFile
   ctx.constValues = constValues
+  ctx.globalVarNames = globalVarNames
   const fields = structDefs.get(typeName) ?? []
   const hasSelf = method.params.length > 0 && method.params[0].name === 'self'
 
@@ -1318,6 +1327,7 @@ function lowerStmt(
       const rawCmd = stmt.cmd
         .replace(/__NS__/g, ns)
         .replace(/__OBJ__/g, `__${ns}`)
+        .replace(/__RS__/g, 'rs')
       ctx.emit({ kind: 'call', dst: null, fn: `__raw:${rawCmd}`, args: [] })
       break
     }
@@ -1520,6 +1530,13 @@ function lowerExpr(
       if (ctx.constValues.has(expr.name)) {
         return { kind: 'const', value: ctx.constValues.get(expr.name)! }
       }
+      // Module-level global variable: read from scoreboard slot
+      if (ctx.globalVarNames.has(expr.name)) {
+        const t = ctx.freshTemp()
+        ctx.emit({ kind: 'score_read', dst: t, player: expr.name, obj: `__${ctx.getNamespace()}` })
+        scope.set(expr.name, t)
+        return { kind: 'temp', name: t }
+      }
       // Unresolved ident — could be a global or external reference
       const t = ctx.freshTemp()
       ctx.emit({ kind: 'copy', dst: t, src: { kind: 'const', value: 0 } })
@@ -1620,6 +1637,31 @@ function lowerExpr(
 
     case 'assign': {
       const val = lowerExpr(expr.value, ctx, scope)
+      // Check if the target is a struct variable — if so, update its field temps
+      // from the __rf_<field> return slots that the callee populated.
+      const sv = ctx.structVars.get(expr.target)
+      if (sv) {
+        const fields = ctx.structDefs.get(sv.typeName) ?? []
+        for (const fieldName of fields) {
+          const existingFieldTemp = sv.fields.get(fieldName)
+          // Reuse the existing field temp if it exists (so scoreboard slot stays stable),
+          // otherwise allocate a fresh one.
+          const fieldTemp = existingFieldTemp ?? ctx.freshTemp()
+          ctx.emit({ kind: 'copy', dst: fieldTemp, src: { kind: 'temp', name: `__rf_${fieldName}` } })
+          sv.fields.set(fieldName, fieldTemp)
+        }
+        return val
+      }
+      // Global variable assignment: write to scoreboard (score_write has side effects, DCE-safe)
+      if (ctx.globalVarNames.has(expr.target)) {
+        const globalObj = `__${ctx.getNamespace()}`
+        ctx.emit({ kind: 'score_write', player: expr.target, obj: globalObj, src: val })
+        // Also update scope temp so subsequent reads in this function see the new value
+        const t = ctx.freshTemp()
+        ctx.emit({ kind: 'score_read', dst: t, player: expr.target, obj: globalObj })
+        scope.set(expr.target, t)
+        return val
+      }
       // Reuse the existing temp for this variable so that updates inside
       // if/while bodies are visible to outer code (we target mutable
       // scoreboard slots, not true SSA registers).
@@ -2074,6 +2116,72 @@ function lowerExpr(
 
       // Handle builtin calls → raw MC commands
       if (BUILTIN_SET.has(expr.fn)) {
+        // Special case: say() with f_string → MC macro function ($say template)
+        // MC `say` is plain text and cannot reference scoreboards directly;
+        // use function macros (MC 1.20.2+) to interpolate variables.
+        if (expr.fn === 'say' && expr.args[0]?.kind === 'f_string') {
+          const fstr = precomputeFStringParts(expr.args[0], ctx, scope)
+          if (fstr.kind === 'f_string') {
+            const ns = ctx.getNamespace()
+            const obj = `__${ns}`
+            const helperName = `${ctx.getFnName()}__say_macro_${ctx.freshTemp()}`
+
+            // Build macro template: "text $(var) more text"
+            let template = 'say '
+            const macroVarNames: string[] = []
+            for (const part of fstr.parts) {
+              if (part.kind === 'text') {
+                template += part.value
+              } else {
+                const inner = part.expr as HIRExpr
+                if (inner.kind === 'ident') {
+                  // Strip leading $ from temp names for macro param names
+                  const varName = inner.name.startsWith('$') ? inner.name.slice(1) : inner.name
+                  template += `$(${varName})`
+                  macroVarNames.push(inner.name)
+                } else if (inner.kind === 'int_lit') {
+                  template += String(inner.value)
+                } else {
+                  template += '?'
+                }
+              }
+            }
+
+            // Emit: copy each scoreboard var to rs:macro_args storage
+            for (const varName of macroVarNames) {
+              const cleanName = varName.startsWith('$') ? varName.slice(1) : varName
+              ctx.emit({
+                kind: 'call', dst: null,
+                fn: `__raw:execute store result storage rs:macro_args ${cleanName} int 1 run scoreboard players get ${varName} ${obj}`,
+                args: [],
+              })
+            }
+
+            // Build helper MIR function with isMacro: true
+            const helperCtx = new FnContext(ns, helperName, ctx.structDefs, ctx.implMethods)
+            helperCtx.emit({ kind: 'call', dst: null, fn: `__raw:$${template}`, args: [] })
+            helperCtx.terminate({ kind: 'return', value: null })
+            const helperReachable = computeReachable(helperCtx.blocks, 'entry')
+            const helperBlocks = helperCtx.blocks.filter(b => helperReachable.has(b.id))
+            computePreds(helperBlocks)
+            ctx.helperFunctions.push({
+              name: helperName,
+              params: [],
+              blocks: helperBlocks,
+              entry: 'entry',
+              isMacro: true,
+              sourceSnippet: 'say macro helper',
+            })
+
+            // Emit: function <helper> with storage rs:macro_args
+            ctx.emit({ kind: 'call', dst: null, fn: `__raw:function ${ns}:${helperName} with storage rs:macro_args`, args: [] })
+
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'const', dst: t, value: 0 })
+            return { kind: 'temp', name: t }
+          }
+        }
+
         // For text builtins with f-string args, precompute complex expressions to temp vars
         const TEXT_BUILTINS_SET = new Set(['tell', 'tellraw', 'title', 'subtitle', 'actionbar', 'announce'])
         let resolvedArgs = expr.args
@@ -2249,6 +2357,7 @@ function lowerExpr(
                 ctx.constValues,
                 ctx.singletonStructs,
                 ctx.displayImpls,
+                ctx.globalVarNames,
               )
               ctx.specializedFnsRegistry.set(specializedName, [specFn, ...specHelpers])
             }

package/src/optimizer/interprocedural.ts

@@ -58,7 +58,7 @@ function runOnePass(mod: MIRModule): MIRModule {
         if (fnMap.has(mangledName) || added.has(mangledName)) continue
 
         // Create specialized clone
-        const specialized = specialize(callee, constArgs.map(a => a.value), mangledName)
+        const specialized = specialize(callee, constArgs.map(a => a.value), mangledName, mod.objective)
         newFunctions.push(specialized)
         added.add(mangledName)
         fnMap.set(mangledName, specialized)
@@ -89,7 +89,27 @@ function mangleName(name: string, args: number[]): string {
   return `${name}__const_${args.map(v => v < 0 ? `n${Math.abs(v)}` : String(v)).join('_')}`
 }
 
-function specialize(fn: MIRFunction, args: number[], newName: string): MIRFunction {
+/**
+ * Returns true if the function has any __raw: calls that directly reference
+ * scoreboard param slots ($p0, $p1, ...) by name in the raw command string.
+ * Such functions use the raw() pattern to read params via scoreboard, so the
+ * specialized clone must pre-set those slots before executing the body.
+ */
+function hasRawParamRefs(fn: MIRFunction, paramCount: number): boolean {
+  for (let i = 0; i < paramCount; i++) {
+    const pattern = `$p${i}`
+    for (const block of fn.blocks) {
+      for (const instr of block.instrs) {
+        if (instr.kind === 'call' && instr.fn.startsWith('__raw:') && instr.fn.includes(pattern)) {
+          return true
+        }
+      }
+    }
+  }
+  return false
+}
+
+function specialize(fn: MIRFunction, args: number[], newName: string, objective: string): MIRFunction {
   // Build substitution map: param.name → const operand
   const sub = new Map<Temp, Operand>()
   for (let i = 0; i < fn.params.length; i++) {
@@ -97,6 +117,24 @@ function specialize(fn: MIRFunction, args: number[], newName: string): MIRFuncti
   }
 
   const newBlocks = fn.blocks.map(block => substituteBlock(block, sub))
+
+  // If the function uses raw() commands that read from $p<i> scoreboard slots
+  // directly, we must pre-set those slots in the entry block so the raw commands
+  // see the correct values (the normal call convention sets $p<i> at the call
+  // site, but the specialized function is called with no args).
+  if (hasRawParamRefs(fn, args.length)) {
+    const entryBlock = newBlocks.find(b => b.id === fn.entry)
+    if (entryBlock) {
+      const scoreWrites: MIRInstr[] = args.map((value, i) => ({
+        kind: 'score_write' as const,
+        player: `$p${i}`,
+        obj: objective,
+        src: { kind: 'const' as const, value },
+      }))
+      entryBlock.instrs = [...scoreWrites, ...entryBlock.instrs]
+    }
+  }
+
   const specialized: MIRFunction = {
     ...fn,
     name: newName,

package/src/parser/decl-parser.ts

@@ -0,0 +1,349 @@
+/**
+ * DeclParser — declaration parsing (fn/struct/enum/impl/interface/const/global/import).
+ * Extends StmtParser so declaration methods can call block/statement methods.
+ */
+
+import type {
+  FnDecl, StructDecl, StructField, EnumDecl, EnumVariant, ImplBlock,
+  InterfaceDecl, InterfaceMethod, ConstDecl, GlobalDecl, Decorator,
+  TypeNode, Expr,
+} from '../ast/types'
+import { StmtParser } from './stmt-parser'
+
+export class DeclParser extends StmtParser {
+  // -------------------------------------------------------------------------
+  // Struct
+  // -------------------------------------------------------------------------
+
+  parseStructDecl(): StructDecl {
+    const structToken = this.expect('struct')
+    const name = this.expect('ident').value
+    const extendsName = this.match('extends') ? this.expect('ident').value : undefined
+    this.expect('{')
+
+    const fields: StructField[] = []
+    while (!this.check('}') && !this.check('eof')) {
+      const fieldName = this.expect('ident').value
+      this.expect(':')
+      const fieldType = this.parseType()
+      fields.push({ name: fieldName, type: fieldType })
+      this.match(',')
+    }
+
+    this.expect('}')
+    return this.withLoc({ name, extends: extendsName, fields }, structToken)
+  }
+
+  // -------------------------------------------------------------------------
+  // Enum
+  // -------------------------------------------------------------------------
+
+  parseEnumDecl(): EnumDecl {
+    const enumToken = this.expect('enum')
+    const name = this.expect('ident').value
+    this.expect('{')
+
+    const variants: EnumVariant[] = []
+    let nextValue = 0
+
+    while (!this.check('}') && !this.check('eof')) {
+      const variantToken = this.expect('ident')
+      const variant: EnumVariant = { name: variantToken.value }
+
+      if (this.check('(')) {
+        this.advance()
+        const fields: { name: string; type: TypeNode }[] = []
+        while (!this.check(')') && !this.check('eof')) {
+          const fieldName = this.expect('ident').value
+          this.expect(':')
+          const fieldType = this.parseType()
+          fields.push({ name: fieldName, type: fieldType })
+          if (!this.match(',')) break
+        }
+        this.expect(')')
+        variant.fields = fields
+      }
+
+      if (this.match('=')) {
+        const valueToken = this.expect('int_lit')
+        variant.value = parseInt(valueToken.value, 10)
+        nextValue = variant.value + 1
+      } else {
+        variant.value = nextValue++
+      }
+
+      variants.push(variant)
+      if (!this.match(',')) break
+    }
+
+    this.expect('}')
+    return this.withLoc({ name, variants }, enumToken)
+  }
+
+  // -------------------------------------------------------------------------
+  // Impl Block
+  // -------------------------------------------------------------------------
+
+  parseImplBlock(): ImplBlock {
+    const implToken = this.expect('impl')
+    let traitName: string | undefined
+    let typeName: string
+    const firstName = this.expect('ident').value
+    if (this.match('for')) {
+      traitName = firstName
+      typeName = this.expect('ident').value
+    } else {
+      typeName = firstName
+    }
+    this.expect('{')
+
+    const methods: FnDecl[] = []
+    while (!this.check('}') && !this.check('eof')) {
+      methods.push(this.parseFnDecl(typeName))
+    }
+
+    this.expect('}')
+    return this.withLoc({ kind: 'impl_block', traitName, typeName, methods }, implToken)
+  }
+
+  // -------------------------------------------------------------------------
+  // Interface
+  // -------------------------------------------------------------------------
+
+  parseInterfaceDecl(): InterfaceDecl {
+    const ifaceToken = this.expect('interface')
+    const name = this.expect('ident').value
+    this.expect('{')
+
+    const methods: InterfaceMethod[] = []
+    while (!this.check('}') && !this.check('eof')) {
+      const fnToken = this.expect('fn')
+      const methodName = this.expect('ident').value
+      this.expect('(')
+      const params = this.parseInterfaceParams()
+      this.expect(')')
+      let returnType: TypeNode | undefined
+      if (this.match(':')) returnType = this.parseType()
+      methods.push(this.withLoc({ name: methodName, params, returnType }, fnToken) as InterfaceMethod)
+    }
+
+    this.expect('}')
+    return this.withLoc({ name, methods }, ifaceToken) as InterfaceDecl
+  }
+
+  // -------------------------------------------------------------------------
+  // Const / Global
+  // -------------------------------------------------------------------------
+
+  parseConstDecl(): ConstDecl {
+    const constToken = this.expect('const')
+    const name = this.expect('ident').value
+    let type: TypeNode | undefined
+    if (this.match(':')) type = this.parseType()
+    this.expect('=')
+    const value = this.parseLiteralExpr()
+    this.match(';')
+    const inferredType: TypeNode = type ?? (
+      value.kind === 'str_lit' ? { kind: 'named', name: 'string' } :
+      value.kind === 'bool_lit' ? { kind: 'named', name: 'bool' } :
+      value.kind === 'float_lit' ? { kind: 'named', name: 'fixed' } :
+      { kind: 'named', name: 'int' }
+    )
+    return this.withLoc({ name, type: inferredType, value }, constToken)
+  }
+
+  parseGlobalDecl(mutable: boolean): GlobalDecl {
+    const token = this.advance() // consume 'let'
+    const name = this.expect('ident').value
+    this.expect(':')
+    const type = this.parseType()
+    let init: Expr
+    if (this.match('=')) {
+      init = this.parseExpr()
+    } else {
+      init = { kind: 'int_lit', value: 0 }
+    }
+    this.match(';')
+    return this.withLoc({ kind: 'global', name, type, init, mutable }, token)
+  }
+
+  // -------------------------------------------------------------------------
+  // Function
+  // -------------------------------------------------------------------------
+
+  parseExportedFnDecl(): FnDecl {
+    this.expect('export')
+    const fn = this.parseFnDecl()
+    fn.isExported = true
+    return fn
+  }
+
+  parseFnDecl(implTypeName?: string): FnDecl {
+    const decorators = this.parseDecorators()
+    const watchObjective = decorators.find(decorator => decorator.name === 'watch')?.args?.objective
+
+    let isExported: boolean | undefined
+    const filteredDecorators = decorators.filter(d => {
+      if (d.name === 'keep') {
+        isExported = true
+        return false
+      }
+      return true
+    })
+
+    const fnToken = this.expect('fn')
+    const name = this.expect('ident').value
+
+    let typeParams: string[] | undefined
+    if (this.check('<')) {
+      this.advance()
+      typeParams = []
+      do {
+        typeParams.push(this.expect('ident').value)
+      } while (this.match(','))
+      this.expect('>')
+    }
+
+    this.expect('(')
+    const params = this.parseParams(implTypeName)
+    this.expect(')')
+
+    let returnType: TypeNode = { kind: 'named', name: 'void' }
+    if (this.match('->') || this.match(':')) {
+      returnType = this.parseType()
+    }
+
+    const body = this.parseBlock()
+    const closingBraceLine = this.tokens[this.pos - 1]?.line
+
+    const fn: FnDecl = this.withLoc(
+      { name, typeParams, params, returnType, decorators: filteredDecorators, body,
+        isLibraryFn: this.inLibraryMode || undefined, isExported, watchObjective },
+      fnToken,
+    )
+    if (fn.span && closingBraceLine) fn.span.endLine = closingBraceLine
+    return fn
+  }
+
+  parseDeclareStub(): void {
+    this.expect('fn')
+    this.expect('ident')
+    this.expect('(')
+    let depth = 1
+    while (!this.check('eof') && depth > 0) {
+      const t = this.advance()
+      if (t.kind === '(') depth++
+      else if (t.kind === ')') depth--
+    }
+    if (this.match(':') || this.match('->')) {
+      this.parseType()
+    }
+    this.match(';')
+  }
+
+  // -------------------------------------------------------------------------
+  // Decorators
+  // -------------------------------------------------------------------------
+
+  private parseDecorators(): Decorator[] {
+    const decorators: Decorator[] = []
+    while (this.check('decorator')) {
+      const token = this.advance()
+      const decorator = this.parseDecoratorValue(token.value)
+      decorators.push(decorator)
+    }
+    return decorators
+  }
+
+  parseDecoratorValue(value: string): Decorator {
+    const match = value.match(/^@([A-Za-z_][A-Za-z0-9_-]*)(?:\((.*)\))?$/s)
+    if (!match) {
+      this.error(`Invalid decorator: ${value}`)
+    }
+
+    const name = match[1] as Decorator['name']
+    const argsStr = match[2]
+
+    if (!argsStr) return { name }
+
+    if (name === 'profile' || name === 'benchmark' || name === 'memoize') {
+      this.error(`@${name} decorator does not accept arguments`)
+    }
+
+    const args: Decorator['args'] = {}
+
+    if (name === 'on') {
+      const eventTypeMatch = argsStr.match(/^([A-Za-z_][A-Za-z0-9_]*)$/)
+      if (eventTypeMatch) {
+        args.eventType = eventTypeMatch[1]
+        return { name, args }
+      }
+    }
+
+    if (name === 'watch' || name === 'on_trigger' || name === 'on_advancement' || name === 'on_craft' || name === 'on_join_team') {
+      const strMatch = argsStr.match(/^"([^"]*)"$/)
+      if (strMatch) {
+        if (name === 'watch') args.objective = strMatch[1]
+        else if (name === 'on_trigger') args.trigger = strMatch[1]
+        else if (name === 'on_advancement') args.advancement = strMatch[1]
+        else if (name === 'on_craft') args.item = strMatch[1]
+        else if (name === 'on_join_team') args.team = strMatch[1]
+        return { name, args }
+      }
+    }
+
+    if (name === 'config') {
+      const configMatch = argsStr.match(/^"([^"]+)"\s*,\s*default\s*:\s*(-?\d+(?:\.\d+)?)$/)
+      if (configMatch) {
+        return { name, args: { configKey: configMatch[1], configDefault: parseFloat(configMatch[2]) } }
+      }
+      const keyOnlyMatch = argsStr.match(/^"([^"]+)"$/)
+      if (keyOnlyMatch) {
+        return { name, args: { configKey: keyOnlyMatch[1] } }
+      }
+      this.error(`Invalid @config syntax. Expected: @config("key", default: value) or @config("key")`)
+    }
+
+    if (name === 'deprecated') {
+      const strMatch = argsStr.match(/^"([^"]*)"$/)
+      if (strMatch) return { name, args: { message: strMatch[1] } }
+      return { name, args: {} }
+    }
+
+    if (name === 'test') {
+      const strMatch = argsStr.match(/^"([^"]*)"$/)
+      if (strMatch) return { name, args: { testLabel: strMatch[1] } }
+      return { name, args: { testLabel: '' } }
+    }
+
+    if (name === 'require_on_load') {
+      const rawArgs: NonNullable<Decorator['rawArgs']> = []
+      for (const part of argsStr.split(',')) {
+        const trimmed = part.trim()
+        const identMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)$/)
+        if (identMatch) {
+          rawArgs.push({ kind: 'string', value: identMatch[1] })
+        } else {
+          const strMatch = trimmed.match(/^"([^"]*)"$/)
+          if (strMatch) rawArgs.push({ kind: 'string', value: strMatch[1] })
+        }
+      }
+      return { name, rawArgs }
+    }
+
+    for (const part of argsStr.split(',')) {
+      const [key, val] = part.split('=').map(s => s.trim())
+      if (key === 'rate') args.rate = parseInt(val, 10)
+      else if (key === 'ticks') args.ticks = parseInt(val, 10)
+      else if (key === 'batch') args.batch = parseInt(val, 10)
+      else if (key === 'onDone') args.onDone = val.replace(/^["']|["']$/g, '')
+      else if (key === 'trigger') args.trigger = val
+      else if (key === 'advancement') args.advancement = val
+      else if (key === 'item') args.item = val
+      else if (key === 'team') args.team = val
+      else if (key === 'max') args.max = parseInt(val, 10)
+    }
+
+    return { name, args }
+  }
+}