redscript-mc 1.2.20 → 1.2.24

package/src/__tests__/var-allocator.test.ts

@@ -0,0 +1,75 @@
+import { VarAllocator } from '../codegen/var-allocator'
+
+describe('VarAllocator', () => {
+  describe('mangle mode (default)', () => {
+    it('generates sequential names: a, b, ..., z, aa, ab', () => {
+      const alloc = new VarAllocator(true)
+      const names: string[] = []
+      for (let i = 0; i < 28; i++) {
+        names.push(alloc.alloc(`var${i}`))
+      }
+      expect(names[0]).toBe('$a')
+      expect(names[1]).toBe('$b')
+      expect(names[25]).toBe('$z')
+      expect(names[26]).toBe('$aa')
+      expect(names[27]).toBe('$ab')
+    })
+
+    it('caches: same name returns same result', () => {
+      const alloc = new VarAllocator(true)
+      const first = alloc.alloc('x')
+      const second = alloc.alloc('x')
+      expect(first).toBe(second)
+    })
+
+    it('constant() is content-addressed: same value returns same result', () => {
+      const alloc = new VarAllocator(true)
+      const first = alloc.constant(42)
+      const second = alloc.constant(42)
+      expect(first).toBe(second)
+    })
+
+    it('different variables get different names', () => {
+      const alloc = new VarAllocator(true)
+      const a = alloc.alloc('foo')
+      const b = alloc.alloc('bar')
+      expect(a).not.toBe(b)
+    })
+
+    it('alloc, constant, and internal share the same sequential pool', () => {
+      const alloc = new VarAllocator(true)
+      const v = alloc.alloc('x')       // $a
+      const c = alloc.constant(1)       // $b
+      const i = alloc.internal('ret')   // $c
+      expect(v).toBe('$a')
+      expect(c).toBe('$b')
+      expect(i).toBe('$c')
+    })
+
+    it('strips $ prefix from variable names', () => {
+      const alloc = new VarAllocator(true)
+      const a = alloc.alloc('$foo')
+      const b = alloc.alloc('foo')
+      expect(a).toBe(b) // same underlying name
+    })
+  })
+
+  describe('no-mangle mode', () => {
+    it('uses $<name> for user vars', () => {
+      const alloc = new VarAllocator(false)
+      expect(alloc.alloc('counter')).toBe('$counter')
+    })
+
+    it('uses $const_<value> for constants', () => {
+      const alloc = new VarAllocator(false)
+      expect(alloc.constant(10)).toBe('$const_10')
+      expect(alloc.constant(-3)).toBe('$const_-3')
+    })
+
+    it('uses $<suffix> for internals', () => {
+      const alloc = new VarAllocator(false)
+      expect(alloc.internal('ret')).toBe('$ret')
+      expect(alloc.internal('p0')).toBe('$p0')
+    })
+  })
+})

package/src/ast/types.ts

@@ -25,15 +25,19 @@ export interface Span {
 export type PrimitiveType = 'int' | 'bool' | 'float' | 'string' | 'void' | 'BlockPos' | 'byte' | 'short' | 'long' | 'double' | 'format_string'
 
 // Entity type hierarchy
-export type EntityTypeName = 
+export type EntityTypeName =
   | 'entity'      // Base type
   | 'Player'      // @a, @p, @r
   | 'Mob'         // Base mob type
   | 'HostileMob'  // Hostile mobs
   | 'PassiveMob'  // Passive mobs
-  // Specific mob types (common ones)
+  // Hostile mob types
   | 'Zombie' | 'Skeleton' | 'Creeper' | 'Spider' | 'Enderman'
-  | 'Pig' | 'Cow' | 'Sheep' | 'Chicken' | 'Villager'
+  | 'Blaze' | 'Witch' | 'Slime' | 'ZombieVillager' | 'Husk'
+  | 'Drowned' | 'Stray' | 'WitherSkeleton' | 'CaveSpider'
+  // Passive mob types
+  | 'Pig' | 'Cow' | 'Sheep' | 'Chicken' | 'Villager' | 'WanderingTrader'
+  // Non-mob entities
   | 'ArmorStand' | 'Item' | 'Arrow'
 
 export type TypeNode =
@@ -43,7 +47,7 @@ export type TypeNode =
   | { kind: 'enum'; name: string }
   | { kind: 'function_type'; params: TypeNode[]; return: TypeNode }
   | { kind: 'entity'; entityType: EntityTypeName }  // Entity types
-  | { kind: 'selector' }  // Selector type (multiple entities)
+  | { kind: 'selector'; entityType?: string }  // Selector type, optionally parameterized: selector<Player>
 
 export interface LambdaParam {
   name: string

package/src/cli.ts

@@ -53,6 +53,7 @@ Options:
   --namespace <ns>       Datapack namespace (default: derived from filename)
   --target <target>      Output target: datapack (default), cmdblock, or structure
   --no-dce               Disable AST dead code elimination
+  --no-mangle            Disable variable name mangling (use readable names)
   --stats                Print optimizer statistics
   --hot-reload <url>     After each successful compile, POST to <url>/reload
                          (use with redscript-testharness; e.g. http://localhost:25561)
@@ -166,8 +167,9 @@ function parseArgs(args: string[]): {
   help?: boolean
   hotReload?: string
   dce?: boolean
+  mangle?: boolean
 } {
-  const result: ReturnType<typeof parseArgs> = { dce: true }
+  const result: ReturnType<typeof parseArgs> = { dce: true, mangle: true }
   let i = 0
 
   while (i < args.length) {
@@ -194,6 +196,9 @@ function parseArgs(args: string[]): {
     } else if (arg === '--no-dce') {
       result.dce = false
       i++
+    } else if (arg === '--no-mangle') {
+      result.mangle = false
+      i++
     } else if (arg === '--hot-reload') {
       result.hotReload = args[++i]
       i++
@@ -217,13 +222,19 @@ function deriveNamespace(filePath: string): string {
   return basename.toLowerCase().replace(/[^a-z0-9]/g, '_')
 }
 
-function printWarnings(warnings: Array<{ code: string; message: string }> | undefined): void {
+function printWarnings(warnings: Array<{ code: string; message: string; line?: number; col?: number; filePath?: string }> | undefined): void {
   if (!warnings || warnings.length === 0) {
     return
   }
 
   for (const warning of warnings) {
-    console.error(`Warning [${warning.code}]: ${warning.message}`)
+    const loc = warning.filePath
+      ? `${warning.filePath}:${warning.line ?? '?'}`
+      : warning.line != null
+        ? `line ${warning.line}`
+        : null
+    const locStr = loc ? ` (${loc})` : ''
+    console.error(`Warning [${warning.code}]: ${warning.message}${locStr}`)
   }
 }
 
@@ -250,7 +261,8 @@ function compileCommand(
   namespace: string,
   target: string = 'datapack',
   showStats = false,
-  dce = true
+  dce = true,
+  mangle = true
 ): void {
   // Read source file
   if (!fs.existsSync(file)) {
@@ -262,7 +274,7 @@ function compileCommand(
 
   try {
     if (target === 'cmdblock') {
-      const result = compile(source, { namespace, filePath: file, dce })
+      const result = compile(source, { namespace, filePath: file, dce, mangle })
       printWarnings(result.warnings)
 
       // Generate command block JSON
@@ -282,7 +294,7 @@ function compileCommand(
         printOptimizationStats(result.stats)
       }
     } else if (target === 'structure') {
-      const structure = compileToStructure(source, namespace, file, { dce })
+      const structure = compileToStructure(source, namespace, file, { dce, mangle })
       fs.mkdirSync(path.dirname(output), { recursive: true })
       fs.writeFileSync(output, structure.buffer)
 
@@ -293,7 +305,7 @@ function compileCommand(
         printOptimizationStats(structure.stats)
       }
     } else {
-      const result = compile(source, { namespace, filePath: file, dce })
+      const result = compile(source, { namespace, filePath: file, dce, mangle })
       printWarnings(result.warnings)
 
       // Default: generate datapack
@@ -308,6 +320,13 @@ function compileCommand(
         fs.writeFileSync(filePath, dataFile.content)
       }
 
+      // Write sourcemap alongside datapack when mangle mode is active
+      if (mangle && result.sourceMap && Object.keys(result.sourceMap).length > 0) {
+        const mapPath = path.join(output, `${namespace}.map.json`)
+        fs.writeFileSync(mapPath, JSON.stringify(result.sourceMap, null, 2))
+        console.log(`  Sourcemap: ${mapPath}`)
+      }
+
       console.log(`✓ Compiled ${file} to ${output}/`)
       console.log(`  Namespace: ${namespace}`)
       console.log(`  Functions: ${result.ir.functions.length}`)
@@ -488,7 +507,8 @@ async function main(): Promise<void> {
         namespace,
         target,
         parsed.stats,
-        parsed.dce
+        parsed.dce,
+        parsed.mangle
       )
       }
       break

package/src/codegen/mcfunction/index.ts

@@ -19,6 +19,7 @@
 import type { IRBlock, IRFunction, IRModule, Operand, Terminator } from '../../ir/types'
 import { optimizeCommandFunctions, type OptimizationStats, createEmptyOptimizationStats, mergeOptimizationStats } from '../../optimizer/commands'
 import { EVENT_TYPES, isEventTypeName, type EventTypeName } from '../../events/types'
+import { VarAllocator } from '../var-allocator'
 
 // ---------------------------------------------------------------------------
 // Utilities
@@ -26,21 +27,12 @@ import { EVENT_TYPES, isEventTypeName, type EventTypeName } from '../../events/t
 
 const OBJ = 'rs'  // scoreboard objective name
 
-function varRef(name: string): string {
-  // Ensure fake player prefix
-  return name.startsWith('$') ? name : `$${name}`
-}
-
-function operandToScore(op: Operand): string {
-  if (op.kind === 'var')   return `${varRef(op.name)} ${OBJ}`
-  if (op.kind === 'const') return `$const_${op.value} ${OBJ}`
+function operandToScore(op: Operand, alloc: VarAllocator): string {
+  if (op.kind === 'var')   return `${alloc.alloc(op.name)} ${OBJ}`
+  if (op.kind === 'const') return `${alloc.constant(op.value)} ${OBJ}`
   throw new Error(`Cannot convert storage operand to score: ${op.path}`)
 }
 
-function constSetup(value: number): string {
-  return `scoreboard players set $const_${value} ${OBJ} ${value}`
-}
-
 // Collect all constants used in a function for pre-setup
 function collectConsts(fn: IRFunction): Set<number> {
   const consts = new Set<number>()
@@ -71,17 +63,17 @@ const BOP_OP: Record<string, string> = {
 // Instruction codegen
 // ---------------------------------------------------------------------------
 
-function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns: string): string[] {
+function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns: string, alloc: VarAllocator): string[] {
   const lines: string[] = []
 
   switch (instr.op) {
     case 'assign': {
-      const dst = varRef(instr.dst)
+      const dst = alloc.alloc(instr.dst)
       const src = instr.src as Operand
       if (src.kind === 'const') {
         lines.push(`scoreboard players set ${dst} ${OBJ} ${src.value}`)
       } else if (src.kind === 'var') {
-        lines.push(`scoreboard players operation ${dst} ${OBJ} = ${varRef(src.name)} ${OBJ}`)
+        lines.push(`scoreboard players operation ${dst} ${OBJ} = ${alloc.alloc(src.name)} ${OBJ}`)
       } else {
         lines.push(`execute store result score ${dst} ${OBJ} run data get storage ${src.path}`)
       }
@@ -89,19 +81,19 @@ function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns:
     }
 
     case 'binop': {
-      const dst = varRef(instr.dst)
+      const dst = alloc.alloc(instr.dst)
       const bop = BOP_OP[instr.bop as string] ?? '+='
       // Copy lhs → dst, then apply op with rhs
-      lines.push(...emitInstr({ op: 'assign', dst: instr.dst, src: instr.lhs }, ns))
-      lines.push(`scoreboard players operation ${dst} ${OBJ} ${bop} ${operandToScore(instr.rhs)}`)
+      lines.push(...emitInstr({ op: 'assign', dst: instr.dst, src: instr.lhs }, ns, alloc))
+      lines.push(`scoreboard players operation ${dst} ${OBJ} ${bop} ${operandToScore(instr.rhs, alloc)}`)
       break
     }
 
     case 'cmp': {
       // MC doesn't have a direct compare-to-register; use execute store
-      const dst = varRef(instr.dst)
-      const lhsScore = operandToScore(instr.lhs)
-      const rhsScore = operandToScore(instr.rhs)
+      const dst = alloc.alloc(instr.dst)
+      const lhsScore = operandToScore(instr.lhs, alloc)
+      const rhsScore = operandToScore(instr.rhs, alloc)
       lines.push(`scoreboard players set ${dst} ${OBJ} 0`)
       switch (instr.cop) {
         case '==':
@@ -127,13 +119,15 @@ function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns:
     }
 
     case 'call': {
-      // Push args as fake players $p0, $p1, ...
+      // Push args as param fake players
       for (let i = 0; i < instr.args.length; i++) {
-        lines.push(...emitInstr({ op: 'assign', dst: `$p${i}`, src: instr.args[i] }, ns))
+        const paramName = alloc.internal(`p${i}`)
+        lines.push(...emitInstr({ op: 'assign', dst: paramName, src: instr.args[i] }, ns, alloc))
       }
       lines.push(`function ${ns}:${instr.fn}`)
       if (instr.dst) {
-        lines.push(`scoreboard players operation ${varRef(instr.dst)} ${OBJ} = $ret ${OBJ}`)
+        const retName = alloc.internal('ret')
+        lines.push(`scoreboard players operation ${alloc.alloc(instr.dst)} ${OBJ} = ${retName} ${OBJ}`)
       }
       break
     }
@@ -150,31 +144,33 @@ function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns:
 // Terminator codegen
 // ---------------------------------------------------------------------------
 
-function emitTerm(term: Terminator, ns: string, fnName: string): string[] {
+function emitTerm(term: Terminator, ns: string, fnName: string, alloc: VarAllocator): string[] {
   const lines: string[] = []
   switch (term.op) {
     case 'jump':
       lines.push(`function ${ns}:${fnName}/${term.target}`)
       break
     case 'jump_if':
-      lines.push(`execute if score ${varRef(term.cond)} ${OBJ} matches 1.. run function ${ns}:${fnName}/${term.then}`)
-      lines.push(`execute if score ${varRef(term.cond)} ${OBJ} matches ..0 run function ${ns}:${fnName}/${term.else_}`)
+      lines.push(`execute if score ${alloc.alloc(term.cond)} ${OBJ} matches 1.. run function ${ns}:${fnName}/${term.then}`)
+      lines.push(`execute if score ${alloc.alloc(term.cond)} ${OBJ} matches ..0 run function ${ns}:${fnName}/${term.else_}`)
       break
     case 'jump_unless':
-      lines.push(`execute if score ${varRef(term.cond)} ${OBJ} matches ..0 run function ${ns}:${fnName}/${term.then}`)
-      lines.push(`execute if score ${varRef(term.cond)} ${OBJ} matches 1.. run function ${ns}:${fnName}/${term.else_}`)
+      lines.push(`execute if score ${alloc.alloc(term.cond)} ${OBJ} matches ..0 run function ${ns}:${fnName}/${term.then}`)
+      lines.push(`execute if score ${alloc.alloc(term.cond)} ${OBJ} matches 1.. run function ${ns}:${fnName}/${term.else_}`)
       break
-    case 'return':
+    case 'return': {
+      const retName = alloc.internal('ret')
       if (term.value) {
-        lines.push(...emitInstr({ op: 'assign', dst: '$ret', src: term.value }, ns))
+        lines.push(...emitInstr({ op: 'assign', dst: retName, src: term.value }, ns, alloc))
       }
       // In MC 1.20+, use `return` command
       if (term.value?.kind === 'const') {
         lines.push(`return ${term.value.value}`)
       } else if (term.value?.kind === 'var') {
-        lines.push(`return run scoreboard players get ${varRef(term.value.name)} ${OBJ}`)
+        lines.push(`return run scoreboard players get ${alloc.alloc(term.value.name)} ${OBJ}`)
       }
       break
+    }
     case 'tick_yield':
       lines.push(`schedule function ${ns}:${fnName}/${term.continuation} 1t replace`)
       break
@@ -220,7 +216,7 @@ function applyFunctionOptimization(
 
   // Filter out files for functions that were removed (inlined trivial functions)
   const optimizedNames = new Set(optimized.functions.map(fn => fn.name))
-  
+
   return {
     files: files
       .filter(file => {
@@ -248,10 +244,12 @@ export interface DatapackGenerationResult {
   files: DatapackFile[]
   advancements: DatapackFile[]
   stats: OptimizationStats
+  sourceMap?: Record<string, string>
 }
 
 export interface DatapackGenerationOptions {
   optimizeCommands?: boolean
+  mangle?: boolean
 }
 
 export function countMcfunctionCommands(files: DatapackFile[]): number {
@@ -272,7 +270,8 @@ export function generateDatapackWithStats(
   module: IRModule,
   options: DatapackGenerationOptions = {},
 ): DatapackGenerationResult {
-  const { optimizeCommands = true } = options
+  const { optimizeCommands = true, mangle = false } = options
+  const alloc = new VarAllocator(mangle)
   const files: DatapackFile[] = []
   const advancements: DatapackFile[] = []
   const ns = module.namespace
@@ -307,7 +306,7 @@ export function generateDatapackWithStats(
     `scoreboard objectives add ${OBJ} dummy`,
   ]
   for (const g of module.globals) {
-    loadLines.push(`scoreboard players set ${varRef(g.name)} ${OBJ} ${g.init}`)
+    loadLines.push(`scoreboard players set ${alloc.alloc(g.name)} ${OBJ} ${g.init}`)
   }
 
   // Add trigger objectives
@@ -349,13 +348,19 @@ export function generateDatapackWithStats(
     })
   }
 
-  // Generate each function (and collect constants for load)
+  // Collect all constants across all functions first (deduplicated)
+  const allConsts = new Set<number>()
+  for (const fn of module.functions) {
+    for (const c of collectConsts(fn)) allConsts.add(c)
+  }
+  if (allConsts.size > 0) {
+    loadLines.push(...Array.from(allConsts).sort((a, b) => a - b).map(
+      value => `scoreboard players set ${alloc.constant(value)} ${OBJ} ${value}`
+    ))
+  }
+
+  // Generate each function
   for (const fn of module.functions) {
-    // Constant setup — place constants in __load.mcfunction
-    const consts = collectConsts(fn)
-    if (consts.size > 0) {
-      loadLines.push(...Array.from(consts).map(constSetup))
-    }
 
     // Entry block → <fn_name>.mcfunction
     // Continuation blocks → <fn_name>/<label>.mcfunction
@@ -366,14 +371,14 @@ export function generateDatapackWithStats(
       // Param setup in entry block
       if (i === 0) {
         for (let j = 0; j < fn.params.length; j++) {
-          lines.push(`scoreboard players operation ${varRef(fn.params[j])} ${OBJ} = $p${j} ${OBJ}`)
+          lines.push(`scoreboard players operation ${alloc.alloc(fn.params[j])} ${OBJ} = ${alloc.internal(`p${j}`)} ${OBJ}`)
         }
       }
 
       for (const instr of block.instrs) {
-        lines.push(...emitInstr(instr as any, ns))
+        lines.push(...emitInstr(instr as any, ns, alloc))
       }
-      lines.push(...emitTerm(block.term, ns, fn.name))
+      lines.push(...emitTerm(block.term, ns, fn.name, alloc))
 
       const filePath = i === 0
         ? `data/${ns}/function/${fn.name}.mcfunction`
@@ -404,12 +409,12 @@ export function generateDatapackWithStats(
 
   // __tick.mcfunction — calls all @tick functions + trigger check
   const tickLines = ['# RedScript tick dispatcher']
-  
+
   // Call all @tick functions
   for (const fnName of tickFunctionNames) {
     tickLines.push(`function ${ns}:${fnName}`)
   }
-  
+
   // Call trigger check if there are triggers
   if (triggerNames.size > 0) {
     tickLines.push(`# Trigger checks`)
@@ -502,13 +507,15 @@ export function generateDatapackWithStats(
   }
 
   const stats = createEmptyOptimizationStats()
+  const sourceMap = mangle ? alloc.toSourceMap() : undefined
+
   if (!optimizeCommands) {
-    return { files, advancements, stats }
+    return { files, advancements, stats, sourceMap }
   }
 
   const optimized = applyFunctionOptimization(files)
   mergeOptimizationStats(stats, optimized.stats)
-  return { files: optimized.files, advancements, stats }
+  return { files: optimized.files, advancements, stats, sourceMap }
 }
 
 export function generateDatapack(module: IRModule): DatapackFile[] {

package/src/codegen/structure/index.ts

@@ -10,6 +10,7 @@ import { preprocessSource } from '../../compile'
 import type { IRCommand, IRFunction, IRModule } from '../../ir/types'
 import type { DatapackFile } from '../mcfunction'
 import { EVENT_TYPES, isEventTypeName, type EventTypeName } from '../../events/types'
+import { VarAllocator } from '../var-allocator'
 
 const DATA_VERSION = 3953
 const MAX_WIDTH = 16
@@ -54,16 +55,13 @@ export interface StructureCompileResult {
 
 export interface StructureCompileOptions {
   dce?: boolean
+  mangle?: boolean
 }
 
 function escapeJsonString(value: string): string {
   return JSON.stringify(value).slice(1, -1)
 }
 
-function varRef(name: string): string {
-  return name.startsWith('$') ? name : `$${name}`
-}
-
 function collectConsts(fn: IRFunction): Set<number> {
   const consts = new Set<number>()
   for (const block of fn.blocks) {
@@ -85,11 +83,8 @@ function collectConsts(fn: IRFunction): Set<number> {
   return consts
 }
 
-function constSetup(value: number): string {
-  return `scoreboard players set $const_${value} ${OBJ} ${value}`
-}
-
-function collectCommandEntriesFromModule(module: IRModule): CommandEntry[] {
+function collectCommandEntriesFromModule(module: IRModule, mangle = false): CommandEntry[] {
+  const alloc = new VarAllocator(mangle)
   const entries: CommandEntry[] = []
   const triggerHandlers = module.functions.filter(fn => fn.isTriggerHandler && fn.triggerName)
   const triggerNames = new Set(triggerHandlers.map(fn => fn.triggerName!))
@@ -99,14 +94,14 @@ function collectCommandEntriesFromModule(module: IRModule): CommandEntry[] {
   const eventTypes = new Set<EventTypeName>(eventHandlers.map(fn => fn.eventHandler.eventType))
   const loadCommands = [
     `scoreboard objectives add ${OBJ} dummy`,
-    ...module.globals.map(g => `scoreboard players set ${varRef(g.name)} ${OBJ} ${g.init}`),
+    ...module.globals.map(g => `scoreboard players set ${alloc.alloc(g.name)} ${OBJ} ${g.init}`),
     ...Array.from(triggerNames).flatMap(triggerName => [
       `scoreboard objectives add ${triggerName} trigger`,
       `scoreboard players enable @a ${triggerName}`,
     ]),
     ...Array.from(
       new Set(module.functions.flatMap(fn => Array.from(collectConsts(fn))))
-    ).map(constSetup),
+    ).map(value => `scoreboard players set ${alloc.constant(value)} ${OBJ} ${value}`),
   ]
 
   for (const eventType of eventTypes) {
@@ -289,10 +284,10 @@ function createBlockTag(entry: CommandEntry, index: number): CompoundTag {
   })
 }
 
-export function generateStructure(input: IRModule | DatapackFile[]): StructureCompileResult {
+export function generateStructure(input: IRModule | DatapackFile[], options?: { mangle?: boolean }): StructureCompileResult {
   const entries = Array.isArray(input)
     ? collectCommandEntriesFromFiles(input)
-    : collectCommandEntriesFromModule(input)
+    : collectCommandEntriesFromModule(input, options?.mangle)
 
   const blockTags = entries.map(createBlockTag)
   const sizeX = Math.max(1, Math.min(MAX_WIDTH, entries.length || 1))
@@ -345,7 +340,7 @@ export function compileToStructure(
     functions: structureOptimized.functions,
   }
   return {
-    ...generateStructure(optimizedModule),
+    ...generateStructure(optimizedModule, { mangle: options.mangle }),
     stats,
   }
 }

package/src/codegen/var-allocator.ts

@@ -0,0 +1,71 @@
+/**
+ * VarAllocator — assigns scoreboard fake-player names to variables.
+ *
+ * mangle=true:  sequential short names ($a, $b, ..., $z, $aa, $ab, ...)
+ * mangle=false: legacy names ($<name> for vars, $const_<v> for consts, $p0/$ret for internals)
+ */
+
+export class VarAllocator {
+  private readonly mangle: boolean
+  private seq = 0
+  private readonly varCache = new Map<string, string>()
+  private readonly constCache = new Map<number, string>()
+  private readonly internalCache = new Map<string, string>()
+
+  constructor(mangle = true) {
+    this.mangle = mangle
+  }
+
+  /** Allocate a name for a user variable. Strips leading '$' if present. */
+  alloc(originalName: string): string {
+    const clean = originalName.startsWith('$') ? originalName.slice(1) : originalName
+    const cached = this.varCache.get(clean)
+    if (cached) return cached
+    const name = this.mangle ? `$${this.nextSeqName()}` : `$${clean}`
+    this.varCache.set(clean, name)
+    return name
+  }
+
+  /** Allocate a name for a constant value (content-addressed). */
+  constant(value: number): string {
+    const cached = this.constCache.get(value)
+    if (cached) return cached
+    const name = this.mangle ? `$${this.nextSeqName()}` : `$const_${value}`
+    this.constCache.set(value, name)
+    return name
+  }
+
+  /** Allocate a name for a compiler internal (e.g. "ret", "p0"). */
+  internal(suffix: string): string {
+    const cached = this.internalCache.get(suffix)
+    if (cached) return cached
+    const name = this.mangle ? `$${this.nextSeqName()}` : `$${suffix}`
+    this.internalCache.set(suffix, name)
+    return name
+  }
+
+  /** Generate the next sequential name: a, b, ..., z, aa, ab, ..., az, ba, ... */
+  private nextSeqName(): string {
+    const n = this.seq++
+    let result = ''
+    let remaining = n
+    do {
+      result = String.fromCharCode(97 + (remaining % 26)) + result
+      remaining = Math.floor(remaining / 26) - 1
+    } while (remaining >= 0)
+    return result
+  }
+
+  /**
+   * Returns a sourcemap object mapping allocated name → original name.
+   * Useful for debugging: write to <output>.map.json alongside the datapack.
+   * Only meaningful when mangle=true.
+   */
+  toSourceMap(): Record<string, string> {
+    const map: Record<string, string> = {}
+    for (const [orig, alloc] of this.varCache)    map[alloc] = orig
+    for (const [val,  alloc] of this.constCache)  map[alloc] = `const(${val})`
+    for (const [suf,  alloc] of this.internalCache) map[alloc] = `__${suf}`
+    return map
+  }
+}

package/src/compile.ts

@@ -52,6 +52,24 @@ export interface PreprocessedSource {
   ranges: SourceRange[]
 }
 
+/**
+ * Resolve a combined-source line number back to the original file and line.
+ * Returns { filePath, line } if a mapping is found, otherwise returns the input unchanged.
+ */
+export function resolveSourceLine(
+  combinedLine: number,
+  ranges: SourceRange[],
+  fallbackFile?: string
+): { filePath?: string; line: number } {
+  for (const range of ranges) {
+    if (combinedLine >= range.startLine && combinedLine <= range.endLine) {
+      const localLine = combinedLine - range.startLine + 1
+      return { filePath: range.filePath, line: localLine }
+    }
+  }
+  return { filePath: fallbackFile, line: combinedLine }
+}
+
 const IMPORT_RE = /^\s*import\s+"([^"]+)"\s*;?\s*$/
 
 interface PreprocessOptions {