redscript-mc 2.6.2 → 3.0.0

package/dist/src/emit/index.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.emit = emit;
+exports.flattenExecute = flattenExecute;
 const sourcemap_1 = require("./sourcemap");
 const mc_version_1 = require("../types/mc-version");
 // ---------------------------------------------------------------------------
@@ -17,10 +18,17 @@ function emit(module, options) {
     const tickFns = options.tickFunctions ?? [];
     const loadFns = options.loadFunctions ?? [];
     const scheduleFns = options.scheduleFunctions ?? [];
+    const watchFns = options.watchFunctions ?? [];
+    const profiledFns = options.profiledFunctions ?? [];
+    const enableProfiling = options.enableProfiling ?? false;
+    const throttleFns = options.throttleFunctions ?? [];
+    const retryFns = options.retryFunctions ?? [];
+    const memoizeFns = options.memoizeFunctions ?? [];
     const objective = module.objective;
     const genSourceMap = options.generateSourceMap ?? false;
     const mcVersion = options.mcVersion ?? mc_version_1.DEFAULT_MC_VERSION;
     const files = [];
+    const namespaceMapBuilder = genSourceMap ? new sourcemap_1.NamespaceSourceMapBuilder() : null;
     // pack.mcmeta
     files.push({
         path: 'pack.mcmeta',
@@ -28,8 +36,22 @@ function emit(module, options) {
             pack: { pack_format: 26, description: `RedScript datapack: ${namespace}` },
         }, null, 2) + '\n',
     });
+    const singletonObjectives = options.singletonObjectives ?? [];
     // load.mcfunction — creates the scoreboard objective
-    const loadCmds = [`scoreboard objectives add ${objective} dummy`];
+    const loadCmds = [
+        `scoreboard objectives add ${objective} dummy`,
+        ...watchFns.map(watch => `scoreboard objectives add ${watchPrevObjective(watch.name)} dummy`),
+        ...singletonObjectives.map(obj => `scoreboard objectives add ${obj} dummy`),
+        ...(enableProfiling && profiledFns.length > 0
+            ? [
+                'scoreboard objectives add __time dummy',
+                'scoreboard objectives add __profile dummy',
+            ]
+            : []),
+        ...throttleFns.map(t => `scoreboard objectives add ${throttleObjective(t.name)} dummy`),
+        ...retryFns.map(r => `scoreboard objectives add ${retryObjective(r.name)} dummy`),
+        ...(memoizeFns.length > 0 ? [`scoreboard objectives add __memo dummy`] : []),
+    ];
     files.push({
         path: `data/${namespace}/function/load.mcfunction`,
         content: loadCmds.join('\n') + '\n',
@@ -37,9 +59,10 @@ function emit(module, options) {
     // Each LIR function → .mcfunction file
     for (const fn of module.functions) {
         const fnPath = fnNameToPath(fn.name, namespace);
+        namespaceMapBuilder?.addFunctionMapping(qualifiedFunctionRef(fn.name, namespace), fn.sourceLoc, humanFunctionName(fn));
         if (genSourceMap) {
             const builder = new sourcemap_1.SourceMapBuilder(fnPath);
-            const lines = emitFunctionWithSourceMap(fn, namespace, objective, builder, mcVersion);
+            const lines = emitFunction(fn, namespace, objective, mcVersion, enableProfiling && profiledFns.includes(fn.name), builder);
             files.push({ path: fnPath, content: lines.join('\n') + '\n' });
             const map = builder.build();
             if (map) {
@@ -47,10 +70,27 @@ function emit(module, options) {
             }
         }
         else {
-            const lines = emitFunction(fn, namespace, objective, mcVersion);
+            const lines = emitFunction(fn, namespace, objective, mcVersion, enableProfiling && profiledFns.includes(fn.name));
             files.push({ path: fnPath, content: lines.join('\n') + '\n' });
         }
     }
+    const namespaceMap = namespaceMapBuilder?.build();
+    if (namespaceMap) {
+        files.push({
+            path: (0, sourcemap_1.namespaceSourceMapPath)(namespace),
+            content: (0, sourcemap_1.serializeSourceMap)(namespaceMap),
+        });
+    }
+    if (enableProfiling && profiledFns.length > 0) {
+        files.push({
+            path: `data/${namespace}/function/__profiler_reset.mcfunction`,
+            content: emitProfilerReset(profiledFns).join('\n') + '\n',
+        });
+        files.push({
+            path: `data/${namespace}/function/__profiler_report.mcfunction`,
+            content: emitProfilerReport(profiledFns).join('\n') + '\n',
+        });
+    }
     // @schedule wrapper functions: _schedule_xxx → schedule function ns:xxx Nt
     for (const { name, ticks } of scheduleFns) {
         files.push({
@@ -58,6 +98,118 @@ function emit(module, options) {
             content: `schedule function ${namespace}:${name} ${ticks}t\n`,
         });
     }
+    for (const watch of watchFns) {
+        const dispatcher = watchDispatcherName(watch.name);
+        const prevObjective = watchPrevObjective(watch.name);
+        const changedCondition = `unless score @s ${watch.objective} = @s ${prevObjective}`;
+        files.push({
+            path: fnNameToPath(dispatcher, namespace),
+            content: [
+                `execute as @a unless score @s ${prevObjective} = @s ${prevObjective} run scoreboard players operation @s ${prevObjective} = @s ${watch.objective}`,
+                `execute as @a ${changedCondition} run function ${namespace}:${watch.name}`,
+                `execute as @a ${changedCondition} run scoreboard players operation @s ${prevObjective} = @s ${watch.objective}`,
+            ].join('\n') + '\n',
+        });
+    }
+    // @throttle wrapper functions
+    for (const { name, ticks } of throttleFns) {
+        const obj = throttleObjective(name);
+        const inner = `${name}_inner`;
+        files.push({
+            path: fnNameToPath(throttleDispatcherName(name), namespace),
+            content: [
+                `scoreboard players add __throttle_${name} ${obj} 1`,
+                `execute if score __throttle_${name} ${obj} matches ${ticks}.. run function ${namespace}:${inner}`,
+                `execute if score __throttle_${name} ${obj} matches ${ticks}.. run scoreboard players set __throttle_${name} ${obj} 0`,
+            ].join('\n') + '\n',
+        });
+        // Rename the original function to _inner by emitting a redirect wrapper:
+        // The original LIR function keeps its original name; the dispatcher wraps it.
+        // We just need the dispatcher to call the real function as <name>_inner.
+        // Actually: the original compiled function stays as <name>. We generate
+        // a wrapper at <name>_inner that simply calls <name>.
+        files.push({
+            path: fnNameToPath(inner, namespace),
+            content: `function ${namespace}:${name}\n`,
+        });
+    }
+    // @retry wrapper functions
+    for (const { name, max } of retryFns) {
+        const obj = retryObjective(name);
+        const dispatcherName = retryDispatcherName(name);
+        // Dispatcher: if retries remaining > 0, call the function; if it returns 0, decrement counter
+        // We use a two-file approach:
+        //   __retry_<name>: decrements counter then calls the real function
+        //   __retry_<name>_init: sets the counter to max and schedules the first attempt
+        // Runtime logic:
+        //   - On success (fn returns nonzero): reset counter to 0
+        //   - On failure (fn returns 0): counter -= 1, schedule next tick
+        // Since we can't read a function return value in mcfunction directly,
+        // we use a storage-based approach: the function itself sets a "success" flag.
+        // Simpler scoreboard approach (matching task spec):
+        //   __retry_<name> obj tracks remaining attempts
+        //   Each tick, if counter > 0: call fn, if fn "failed" (set counter to 0 from outside) schedule retry
+        // Simplest correct approach:
+        //   generate a tick-registered dispatcher that:
+        //     1. if counter > 0, call the function
+        //     2. function sets __retry_<name>_result to 1 on success (convention)
+        //     3. if result == 0, decrement counter; else reset counter
+        // For simplicity, use the same pattern as @throttle but inverted:
+        //   The user's function sets a score $ret to signal success/failure.
+        //   We wrap it: if counter > 0, run the function.
+        //   After running, check $ret: if 0, keep counter; else reset to 0.
+        //   Next tick the dispatcher will retry if counter > 0.
+        //
+        // Minimal correct implementation (matching task spec — fn returns 0 = failure):
+        //   __retry_<name>_tick: registered as @tick
+        //     execute if score __retry_<name> <obj> matches 1.. run function ns:<name>
+        //     execute if score __retry_<name> <obj> matches 1.. if score $ret <obj> matches 0 run scoreboard players remove __retry_<name> <obj> 1
+        //     execute if score __retry_<name> <obj> matches 1.. unless score $ret <obj> matches 0 run scoreboard players set __retry_<name> <obj> 0
+        //   To start a retry sequence, something must set __retry_<name> <obj> to max.
+        //   We generate __retry_<name>_start: scoreboard players set __retry_<name> <obj> <max>
+        files.push({
+            path: fnNameToPath(dispatcherName, namespace),
+            content: [
+                `execute if score __retry_${name} ${obj} matches 1.. run function ${namespace}:${name}`,
+                `execute if score __retry_${name} ${obj} matches 1.. if score $ret ${obj} matches 0 run scoreboard players remove __retry_${name} ${obj} 1`,
+                `execute if score __retry_${name} ${obj} matches 1.. unless score $ret ${obj} matches 0 run scoreboard players set __retry_${name} ${obj} 0`,
+            ].join('\n') + '\n',
+        });
+        files.push({
+            path: fnNameToPath(`${name}_start`, namespace),
+            content: `scoreboard players set __retry_${name} ${obj} ${max}\n`,
+        });
+    }
+    // @memoize wrapper functions (LRU-1 cache: last call arg/result)
+    // The original compiled function has been renamed to <name>_impl.
+    // We generate <name>.mcfunction as the public entry point with cache logic:
+    //   Players in __memo objective:
+    //     __memo_<name>_key  — cached argument value
+    //     __memo_<name>_val  — cached return value
+    //     __memo_<name>_hit  — 1 if a cached result is available
+    //   On call ($p0 = argument):
+    //     1. If __memo_<name>_hit == 1 AND __memo_<name>_key == $p0 → copy cached val to $ret, return
+    //     2. Otherwise: call <name>_impl, store $p0 → key, $ret → val, set hit=1
+    for (const name of memoizeFns) {
+        const keyPlayer = `__memo_${name}_key`;
+        const valPlayer = `__memo_${name}_val`;
+        const hitPlayer = `__memo_${name}_hit`;
+        const implName = `${name}_impl`;
+        files.push({
+            path: fnNameToPath(name, namespace),
+            content: [
+                `# @memoize wrapper for ${name} (LRU-1 cache)`,
+                `# Cache hit: valid flag set AND key matches current arg`,
+                `execute if score ${hitPlayer} __memo matches 1 if score ${keyPlayer} __memo = $p0 ${objective} run scoreboard players operation $ret ${objective} = ${valPlayer} __memo`,
+                `execute if score ${hitPlayer} __memo matches 1 if score ${keyPlayer} __memo = $p0 ${objective} run return 0`,
+                `# Cache miss: call implementation, store result`,
+                `function ${namespace}:${implName}`,
+                `scoreboard players operation ${keyPlayer} __memo = $p0 ${objective}`,
+                `scoreboard players operation ${valPlayer} __memo = $ret ${objective}`,
+                `scoreboard players set ${hitPlayer} __memo 1`,
+            ].join('\n') + '\n',
+        });
+    }
     // Tag files for tick/load
     if (loadFns.length > 0 || true) {
         // Always include load.json — it must reference the load.mcfunction
@@ -67,8 +219,14 @@ function emit(module, options) {
             content: JSON.stringify({ values: loadValues }, null, 2) + '\n',
         });
     }
-    if (tickFns.length > 0) {
-        const tickValues = tickFns.map(fn => `${namespace}:${fn}`);
+    const allTickFns = [
+        ...tickFns,
+        ...watchFns.map(watch => watchDispatcherName(watch.name)),
+        ...throttleFns.map(t => throttleDispatcherName(t.name)),
+        ...retryFns.map(r => retryDispatcherName(r.name)),
+    ];
+    if (allTickFns.length > 0) {
+        const tickValues = allTickFns.map(fn => `${namespace}:${fn}`);
         files.push({
             path: 'data/minecraft/tags/function/tick.json',
             content: JSON.stringify({ values: tickValues }, null, 2) + '\n',
@@ -98,18 +256,30 @@ function emit(module, options) {
 // ---------------------------------------------------------------------------
 // Function emission
 // ---------------------------------------------------------------------------
-function emitFunction(fn, namespace, objective, mcVersion) {
+function emitFunction(fn, namespace, objective, mcVersion, isProfiled = false, builder) {
     const lines = [];
-    for (const instr of fn.instructions) {
-        lines.push(emitInstr(instr, namespace, objective, mcVersion));
+    const pushLine = (line, sourceLoc) => {
+        lines.push(line);
+        builder?.addLine(sourceLoc);
+    };
+    for (const line of emitFunctionHeader(fn))
+        pushLine(line);
+    if (isProfiled) {
+        for (const line of profilerStartLines(fn.name))
+            pushLine(line);
     }
-    return lines;
-}
-function emitFunctionWithSourceMap(fn, namespace, objective, builder, mcVersion) {
-    const lines = [];
+    let lastSourceMarker;
     for (const instr of fn.instructions) {
-        lines.push(emitInstr(instr, namespace, objective, mcVersion));
-        builder.addLine(instr.sourceLoc);
+        const marker = instr.sourceLoc ? formatSourceMarker(instr.sourceLoc) : undefined;
+        if (marker && marker !== lastSourceMarker) {
+            pushLine(`# src: ${marker}`);
+            lastSourceMarker = marker;
+        }
+        pushLine(flattenExecute(emitInstr(instr, namespace, objective, mcVersion)), instr.sourceLoc);
+    }
+    if (isProfiled) {
+        for (const line of profilerEndLines(fn.name))
+            pushLine(line);
     }
     return lines;
 }
@@ -118,6 +288,85 @@ function fnNameToPath(name, namespace) {
     const mcName = name.replace(/::/g, '/').toLowerCase();
     return `data/${namespace}/function/${mcName}.mcfunction`;
 }
+function qualifiedFunctionRef(name, namespace) {
+    return `${namespace}:${name.replace(/::/g, '/').toLowerCase()}`;
+}
+function humanFunctionName(fn) {
+    const match = fn.sourceSnippet?.match(/^fn\s+([^(]+)/);
+    return match?.[1] ?? fn.name.split('::').pop() ?? fn.name;
+}
+function emitFunctionHeader(fn) {
+    if (!fn.sourceLoc)
+        return [];
+    const lines = [];
+    lines.push(`# Generated from: ${fn.sourceLoc.file}:${fn.sourceLoc.line} (fn ${humanFunctionName(fn)})`);
+    if (fn.sourceSnippet) {
+        lines.push(`# Source: ${fn.sourceSnippet}`);
+    }
+    return lines;
+}
+function formatSourceMarker(sourceLoc) {
+    return `${sourceLoc.file}:${sourceLoc.line}`;
+}
+function watchDispatcherName(name) {
+    return `__watch_${name}`;
+}
+function watchPrevObjective(name) {
+    return `__watch_${name}_prev`;
+}
+function throttleDispatcherName(name) {
+    return `__throttle_${name}`;
+}
+function throttleObjective(name) {
+    return `__throttle`;
+}
+function retryDispatcherName(name) {
+    return `__retry_${name}`;
+}
+function retryObjective(name) {
+    return `__retry`;
+}
+function profilerSafeName(name) {
+    return name.replace(/[^A-Za-z0-9_]/g, '_');
+}
+function profilerStartPlayer(name) {
+    return `#prof_start_${profilerSafeName(name)}`;
+}
+function profilerDeltaPlayer(name) {
+    return `#prof_delta_${profilerSafeName(name)}`;
+}
+function profilerTotalPlayer(name) {
+    return `#prof_total_${profilerSafeName(name)}`;
+}
+function profilerCountPlayer(name) {
+    return `#prof_count_${profilerSafeName(name)}`;
+}
+function profilerStartLines(name) {
+    return [
+        `# __profiler_start_${name}`,
+        `scoreboard players set ${profilerStartPlayer(name)} __time 0`,
+        `execute store result score ${profilerStartPlayer(name)} __time run time query gametime`,
+    ];
+}
+function profilerEndLines(name) {
+    return [
+        `# __profiler_end_${name}`,
+        `scoreboard players set ${profilerDeltaPlayer(name)} __time 0`,
+        `execute store result score ${profilerDeltaPlayer(name)} __time run time query gametime`,
+        `scoreboard players operation ${profilerDeltaPlayer(name)} __time -= ${profilerStartPlayer(name)} __time`,
+        `scoreboard players operation ${profilerTotalPlayer(name)} __profile += ${profilerDeltaPlayer(name)} __time`,
+        `scoreboard players add ${profilerCountPlayer(name)} __profile 1`,
+    ];
+}
+function emitProfilerReset(profiledFns) {
+    return profiledFns.flatMap(name => [
+        `scoreboard players set ${profilerTotalPlayer(name)} __profile 0`,
+        `scoreboard players set ${profilerCountPlayer(name)} __profile 0`,
+    ]);
+}
+function emitProfilerReport(profiledFns) {
+    return profiledFns.map(name => (`tellraw @a [{"text":"[profile] ${name}: total="},{"score":{"name":"${profilerTotalPlayer(name)}","objective":"__profile"}},{"text":" ticks count="},{"score":{"name":"${profilerCountPlayer(name)}","objective":"__profile"}}]`));
+}
 // ---------------------------------------------------------------------------
 // Instruction emission
 // ---------------------------------------------------------------------------
@@ -215,6 +464,50 @@ function macroLineCompat(template) {
     // Replace $(param) with data-get-style substitution marker
     return template.replace(/\$\((\w+)\)/g, (_m, p) => `{storage:rs:macro_args,path:${p}}`);
 }
+// ---------------------------------------------------------------------------
+// Execute Chain Optimization
+// ---------------------------------------------------------------------------
+/**
+ * Flatten nested execute-if chains into a single execute with multiple conditions.
+ *
+ * MC allows chaining conditions:
+ *   execute if A run execute if B run X
+ * can be written as:
+ *   execute if A if B run X
+ *
+ * This reduces command-parsing overhead and improves TPS.
+ *
+ * Rules:
+ * - Only merges when the inner `run` clause is itself `execute if ...`
+ * - Does NOT merge `if ... run execute unless ...` — semantics differ
+ *   (unless negates, changing behavior in chain context)
+ * - Recursively flattens deeper nesting (3+ levels)
+ */
+function flattenExecute(cmd) {
+    // Match: execute <conditions> run execute if <rest>
+    // We only flatten when the inner execute starts with "if" (not "unless", "as", "at", etc.)
+    // Pattern: "execute <prefix> run execute if <suffix>"
+    const RUN_EXECUTE_IF = / run execute if /;
+    if (!RUN_EXECUTE_IF.test(cmd)) {
+        return cmd;
+    }
+    // Find the " run execute if " boundary
+    const idx = cmd.indexOf(' run execute if ');
+    if (idx === -1)
+        return cmd;
+    const outer = cmd.slice(0, idx); // "execute if A"
+    const inner = cmd.slice(idx + ' run '.length); // "execute if B run X"
+    // The outer must start with "execute"
+    if (!outer.startsWith('execute '))
+        return cmd;
+    // Inner starts with "execute if ..."
+    // Strip the "execute" prefix from inner to get the conditions + run tail
+    // Result: outer + " " + inner_conditions_and_tail
+    const innerWithoutExecute = inner.slice('execute '.length); // "if B run X"
+    const merged = `${outer} ${innerWithoutExecute}`;
+    // Recurse to handle 3+ levels
+    return flattenExecute(merged);
+}
 function emitSubcmd(sub) {
     switch (sub.kind) {
         case 'as':

package/dist/src/emit/modules.js

@@ -40,6 +40,9 @@ function compileModules(modules, options = {}) {
         const tokens = lexer.tokenize();
         const parser = new parser_1.Parser(tokens, mod.source, mod.filePath);
         const ast = parser.parse(namespace);
+        if (parser.parseErrors.length > 0) {
+            throw parser.parseErrors[0];
+        }
         // Verify declared module name matches provided name
         const declaredName = ast.moduleName;
         if (declaredName && declaredName !== mod.name) {
@@ -76,7 +79,13 @@ function compileModules(modules, options = {}) {
             if (!sourceExports) {
                 throw new diagnostics_1.DiagnosticError('LoweringError', `Module '${imp.moduleName}' not found (imported in '${modName}')`, { file: ast.namespace, line: 1, col: 1 });
             }
-            if (imp.symbol === '*') {
+            if (imp.symbol === undefined) {
+                // Whole-module file import (`import player_utils;`) — not a symbol import;
+                // this is resolved by the file-level compile() function, not compileModules.
+                // Skip here to avoid treating it as a cross-module symbol reference.
+                continue;
+            }
+            else if (imp.symbol === '*') {
                 // Wildcard: import all exports
                 for (const sym of sourceExports) {
                     resolved.set(sym, `${imp.moduleName}/${sym}`);
@@ -101,6 +110,8 @@ function compileModules(modules, options = {}) {
     }
     for (const ast of parsedModules.values()) {
         for (const imp of ast.imports) {
+            if (imp.symbol === undefined)
+                continue; // whole-module file import, skip
             const used = usedExports.get(imp.moduleName);
             if (!used)
                 continue;
@@ -261,6 +272,7 @@ function compileSingleModule(ast, namespace, objective, moduleName, filePath) {
         // Extract decorator metadata
         const tickFunctions = [];
         const loadFunctions = [];
+        const watchFunctions = [];
         const coroutineInfos = [];
         const scheduleFunctions = [];
         for (const fn of hir.functions) {
@@ -269,6 +281,9 @@ function compileSingleModule(ast, namespace, objective, moduleName, filePath) {
                     tickFunctions.push(fn.name);
                 if (dec.name === 'load')
                     loadFunctions.push(fn.name);
+                if (dec.name === 'watch' && dec.args?.objective) {
+                    watchFunctions.push({ name: fn.name, objective: dec.args.objective });
+                }
                 if (dec.name === 'coroutine') {
                     coroutineInfos.push({ fnName: fn.name, batch: dec.args?.batch ?? 10, onDone: dec.args?.onDone });
                 }
@@ -287,7 +302,7 @@ function compileSingleModule(ast, namespace, objective, moduleName, filePath) {
         const lir = (0, lower_3.lowerToLIR)(mirFinal);
         lir.objective = objective;
         const lirOpt = (0, pipeline_2.lirOptimizeModule)(lir);
-        const files = (0, index_1.emit)(lirOpt, { namespace, tickFunctions, loadFunctions, scheduleFunctions });
+        const files = (0, index_1.emit)(lirOpt, { namespace, tickFunctions, loadFunctions, watchFunctions, scheduleFunctions });
         // For named modules: rename the load.mcfunction to avoid path collision.
         // Rename `data/${ns}/function/load.mcfunction` → `data/${ns}/function/${modName}/_load.mcfunction`
         // and update the load tag reference accordingly.
@@ -429,7 +444,10 @@ function rewriteStmt(stmt, symbolMap) {
         case 'let_destruct':
             rewriteExpr(stmt.init, symbolMap);
             break;
-        // break, continue, raw: nothing to rewrite
+        case 'labeled_loop':
+            rewriteStmt(stmt.body, symbolMap);
+            break;
+        // break, continue, break_label, continue_label, raw: nothing to rewrite
     }
 }
 function rewriteExpr(expr, symbolMap) {

package/dist/src/emit/sourcemap.d.ts

@@ -1,40 +1,30 @@
 /**
- * Source Map Generation — Stage 7 auxiliary output.
- *
- * For each generated .mcfunction file, produces a parallel sourcemap.json
- * that maps output line numbers back to .mcrs source locations.
- *
- * Format:
- * {
- *   "version": 1,
- *   "generatedFile": "data/ns/function/main.mcfunction",
- *   "sources": ["src/main.mcrs"],
- *   "mappings": [
- *     { "line": 1, "source": 0, "sourceLine": 5, "sourceCol": 2 },
- *     ...
- *   ]
- * }
+ * Source map helpers for emitted `.mcfunction` files.
  */
 import type { SourceLoc } from '../lir/types';
 export interface SourceMapEntry {
-    /** 1-based output line number in the .mcfunction file */
     line: number;
-    /** Index into the `sources` array */
     source: number;
-    /** 1-based line in the source .mcrs file */
     sourceLine: number;
-    /** 1-based column in the source .mcrs file */
     sourceCol: number;
 }
 export interface SourceMap {
     version: 1;
-    /** Relative path to the generated .mcfunction file */
     generatedFile: string;
-    /** List of source file paths referenced by mappings */
     sources: string[];
-    /** One entry per mapped output line */
     mappings: SourceMapEntry[];
 }
+export interface NamespaceSourceMapEntry {
+    source: number;
+    line: number;
+    col?: number;
+    name?: string;
+}
+export interface NamespaceSourceMap {
+    version: 1;
+    sources: string[];
+    mappings: Record<string, NamespaceSourceMapEntry>;
+}
 export declare class SourceMapBuilder {
     private readonly generatedFile;
     private readonly sourceIndex;
@@ -42,12 +32,18 @@ export declare class SourceMapBuilder {
     private readonly mappings;
     private lineNumber;
     constructor(generatedFile: string);
-    /** Record the source location for the next output line. */
     addLine(sourceLoc: SourceLoc | undefined): void;
-    /** Return the completed SourceMap, or null if there are no mappings. */
     build(): SourceMap | null;
+    private getSourceIndex;
+}
+export declare class NamespaceSourceMapBuilder {
+    private readonly sourceIndex;
+    private readonly sources;
+    private readonly mappings;
+    addFunctionMapping(functionName: string, sourceLoc: SourceLoc | undefined, name?: string): void;
+    build(): NamespaceSourceMap | null;
+    private getSourceIndex;
 }
-/** Serialize a SourceMap to JSON string (pretty-printed). */
-export declare function serializeSourceMap(map: SourceMap): string;
-/** Given a .mcfunction path, return the path for the sidecar sourcemap.json. */
+export declare function serializeSourceMap(map: SourceMap | NamespaceSourceMap): string;
 export declare function sourceMapPath(mcfunctionPath: string): string;
+export declare function namespaceSourceMapPath(namespace: string): string;

package/dist/src/emit/sourcemap.js

@@ -1,28 +1,12 @@
 "use strict";
 /**
- * Source Map Generation — Stage 7 auxiliary output.
- *
- * For each generated .mcfunction file, produces a parallel sourcemap.json
- * that maps output line numbers back to .mcrs source locations.
- *
- * Format:
- * {
- *   "version": 1,
- *   "generatedFile": "data/ns/function/main.mcfunction",
- *   "sources": ["src/main.mcrs"],
- *   "mappings": [
- *     { "line": 1, "source": 0, "sourceLine": 5, "sourceCol": 2 },
- *     ...
- *   ]
- * }
+ * Source map helpers for emitted `.mcfunction` files.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SourceMapBuilder = void 0;
+exports.NamespaceSourceMapBuilder = exports.SourceMapBuilder = void 0;
 exports.serializeSourceMap = serializeSourceMap;
 exports.sourceMapPath = sourceMapPath;
-// ---------------------------------------------------------------------------
-// Builder — accumulates mappings as lines are emitted
-// ---------------------------------------------------------------------------
+exports.namespaceSourceMapPath = namespaceSourceMapPath;
 class SourceMapBuilder {
     constructor(generatedFile) {
         this.sourceIndex = new Map();
@@ -31,25 +15,17 @@ class SourceMapBuilder {
         this.lineNumber = 0;
         this.generatedFile = generatedFile;
     }
-    /** Record the source location for the next output line. */
     addLine(sourceLoc) {
         this.lineNumber++;
         if (!sourceLoc)
             return;
-        let idx = this.sourceIndex.get(sourceLoc.file);
-        if (idx === undefined) {
-            idx = this.sources.length;
-            this.sources.push(sourceLoc.file);
-            this.sourceIndex.set(sourceLoc.file, idx);
-        }
         this.mappings.push({
             line: this.lineNumber,
-            source: idx,
+            source: this.getSourceIndex(sourceLoc.file),
             sourceLine: sourceLoc.line,
             sourceCol: sourceLoc.col,
         });
     }
-    /** Return the completed SourceMap, or null if there are no mappings. */
     build() {
         if (this.mappings.length === 0)
             return null;
@@ -60,14 +36,60 @@ class SourceMapBuilder {
             mappings: [...this.mappings],
         };
     }
+    getSourceIndex(file) {
+        let idx = this.sourceIndex.get(file);
+        if (idx === undefined) {
+            idx = this.sources.length;
+            this.sources.push(file);
+            this.sourceIndex.set(file, idx);
+        }
+        return idx;
+    }
 }
 exports.SourceMapBuilder = SourceMapBuilder;
-/** Serialize a SourceMap to JSON string (pretty-printed). */
+class NamespaceSourceMapBuilder {
+    constructor() {
+        this.sourceIndex = new Map();
+        this.sources = [];
+        this.mappings = {};
+    }
+    addFunctionMapping(functionName, sourceLoc, name) {
+        if (!sourceLoc)
+            return;
+        this.mappings[functionName] = {
+            source: this.getSourceIndex(sourceLoc.file),
+            line: sourceLoc.line,
+            col: sourceLoc.col,
+            ...(name ? { name } : {}),
+        };
+    }
+    build() {
+        if (Object.keys(this.mappings).length === 0)
+            return null;
+        return {
+            version: 1,
+            sources: [...this.sources],
+            mappings: { ...this.mappings },
+        };
+    }
+    getSourceIndex(file) {
+        let idx = this.sourceIndex.get(file);
+        if (idx === undefined) {
+            idx = this.sources.length;
+            this.sources.push(file);
+            this.sourceIndex.set(file, idx);
+        }
+        return idx;
+    }
+}
+exports.NamespaceSourceMapBuilder = NamespaceSourceMapBuilder;
 function serializeSourceMap(map) {
     return JSON.stringify(map, null, 2) + '\n';
 }
-/** Given a .mcfunction path, return the path for the sidecar sourcemap.json. */
 function sourceMapPath(mcfunctionPath) {
     return mcfunctionPath.replace(/\.mcfunction$/, '.sourcemap.json');
 }
+function namespaceSourceMapPath(namespace) {
+    return `${namespace}.sourcemap.json`;
+}
 //# sourceMappingURL=sourcemap.js.map