redscript-mc 2.6.2 → 3.0.0

package/dist/src/emit/compile.js

@@ -4,14 +4,50 @@
  *
  * Pipeline: source → Lexer → Parser → TypeCheck → HIR → MIR → optimize → LIR → emit
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compile = compile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const lexer_1 = require("../lexer");
 const parser_1 = require("../parser");
 const compile_1 = require("../compile");
 const diagnostics_1 = require("../diagnostics");
 const lower_1 = require("../hir/lower");
 const monomorphize_1 = require("../hir/monomorphize");
+const deprecated_1 = require("../hir/deprecated");
 const lower_2 = require("../mir/lower");
 const pipeline_1 = require("../optimizer/pipeline");
 const lower_3 = require("../lir/lower");
@@ -22,39 +58,153 @@ const budget_1 = require("../lir/budget");
 const mc_version_1 = require("../types/mc-version");
 const typechecker_1 = require("../typechecker");
 const types_1 = require("../events/types");
+function annotateFunctionSourceFiles(program, sourceFile) {
+    if (!sourceFile)
+        return;
+    for (const fn of program.declarations)
+        fn.sourceFile = sourceFile;
+    for (const impl of program.implBlocks) {
+        for (const method of impl.methods)
+            method.sourceFile = sourceFile;
+    }
+}
+function pruneLibraryFunctionFiles(files, libraryPaths) {
+    if (libraryPaths.size === 0)
+        return files;
+    const fnPathToFilePath = new Map();
+    for (const file of files) {
+        const match = file.path.match(/^data\/([^/]+)\/function\/(.+)\.mcfunction$/);
+        if (match) {
+            fnPathToFilePath.set(`${match[1]}:${match[2]}`, file.path);
+        }
+    }
+    const callGraph = new Map();
+    const callPattern = /\bfunction\s+([\w\-]+:[\w\-./]+)/g;
+    for (const file of files) {
+        if (!file.path.endsWith('.mcfunction'))
+            continue;
+        const called = new Set();
+        let match;
+        callPattern.lastIndex = 0;
+        while ((match = callPattern.exec(file.content)) !== null) {
+            called.add(match[1]);
+        }
+        callGraph.set(file.path, called);
+    }
+    const reachableFiles = new Set();
+    const queue = [];
+    for (const file of files) {
+        if (!file.path.endsWith('.mcfunction'))
+            continue;
+        if (libraryPaths.has(file.path))
+            continue;
+        queue.push(file.path);
+        reachableFiles.add(file.path);
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const called = callGraph.get(current) ?? new Set();
+        for (const fnPath of called) {
+            const filePath = fnPathToFilePath.get(fnPath);
+            if (filePath && !reachableFiles.has(filePath)) {
+                reachableFiles.add(filePath);
+                queue.push(filePath);
+            }
+        }
+    }
+    return files.filter(file => !libraryPaths.has(file.path) || reachableFiles.has(file.path));
+}
 function compile(source, options = {}) {
-    const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = mc_version_1.DEFAULT_MC_VERSION, lenient = false, includeDirs } = options;
+    const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = mc_version_1.DEFAULT_MC_VERSION, lenient = false, includeDirs, stopAfterCheck = false, debug = false, } = options;
     const warnings = [];
     // Preprocess: resolve import directives, merge imported sources
     const preprocessed = (0, compile_1.preprocessSourceWithMetadata)(source, { filePath, includeDirs });
     const processedSource = preprocessed.source;
-    // Stage 1: Lex + Parse → AST
-    const lexer = new lexer_1.Lexer(processedSource);
-    const tokens = lexer.tokenize();
-    const parser = new parser_1.Parser(tokens, processedSource, filePath);
-    const ast = parser.parse(namespace);
-    warnings.push(...parser.warnings);
-    // Merge library imports (files with `module library;`) into AST
-    for (const li of preprocessed.libraryImports ?? []) {
-        const libPreprocessed = (0, compile_1.preprocessSourceWithMetadata)(li.source, { filePath: li.filePath });
-        const libTokens = new lexer_1.Lexer(libPreprocessed.source, li.filePath).tokenize();
-        const libParser = new parser_1.Parser(libTokens, libPreprocessed.source, li.filePath);
-        const libAst = libParser.parse(namespace);
-        warnings.push(...libParser.warnings);
-        for (const fn of libAst.declarations)
-            fn.isLibraryFn = true;
-        ast.declarations.push(...libAst.declarations);
-        ast.structs.push(...libAst.structs);
-        ast.implBlocks.push(...libAst.implBlocks);
-        ast.enums.push(...libAst.enums);
-        ast.consts.push(...libAst.consts);
-        ast.globals.push(...libAst.globals);
-    }
-    // Merge librarySources (v1 compat: inline library strings) before HIR
-    if (options.librarySources) {
-        for (const libSrc of options.librarySources) {
-            const libTokens = new lexer_1.Lexer(libSrc).tokenize();
-            const libAst = new parser_1.Parser(libTokens, libSrc).parse(namespace);
+    try {
+        // Stage 1: Lex + Parse → AST
+        const lexer = new lexer_1.Lexer(processedSource);
+        const tokens = lexer.tokenize();
+        const parser = new parser_1.Parser(tokens, processedSource, filePath);
+        const ast = parser.parse(namespace);
+        annotateFunctionSourceFiles(ast, filePath);
+        warnings.push(...parser.warnings);
+        if (parser.parseErrors.length > 0) {
+            throw stopAfterCheck ? new diagnostics_1.DiagnosticBundleError(parser.parseErrors) : parser.parseErrors[0];
+        }
+        // Resolve whole-module file imports: `import player_utils;` (no `::` symbol)
+        const seenModuleImports = new Set();
+        function resolveModuleFilePath(modName, fromFile) {
+            const candidates = [`${modName}.mcrs`, modName];
+            const stdlibDir = path.resolve(__dirname, '..', 'src', 'stdlib');
+            for (const candidate of candidates) {
+                if (fromFile) {
+                    const rel = path.resolve(path.dirname(fromFile), candidate);
+                    if (fs.existsSync(rel))
+                        return rel;
+                }
+                const stdlib = path.resolve(stdlibDir, candidate);
+                if (fs.existsSync(stdlib))
+                    return stdlib;
+                for (const dir of includeDirs ?? []) {
+                    const extra = path.resolve(dir, candidate);
+                    if (fs.existsSync(extra))
+                        return extra;
+                }
+            }
+            return null;
+        }
+        function mergeWholeModuleImport(modFilePath) {
+            if (seenModuleImports.has(modFilePath))
+                return;
+            seenModuleImports.add(modFilePath);
+            const modSource = fs.readFileSync(modFilePath, 'utf-8');
+            const modPreprocessed = (0, compile_1.preprocessSourceWithMetadata)(modSource, { filePath: modFilePath, includeDirs });
+            const modTokens = new lexer_1.Lexer(modPreprocessed.source, modFilePath).tokenize();
+            const modParser = new parser_1.Parser(modTokens, modPreprocessed.source, modFilePath);
+            const modAst = modParser.parse(namespace);
+            annotateFunctionSourceFiles(modAst, modFilePath);
+            warnings.push(...modParser.warnings);
+            if (modParser.parseErrors.length > 0) {
+                throw stopAfterCheck ? new diagnostics_1.DiagnosticBundleError(modParser.parseErrors) : modParser.parseErrors[0];
+            }
+            for (const fn of modAst.declarations)
+                fn.isLibraryFn = true;
+            for (const imp of modAst.imports) {
+                if (imp.symbol !== undefined)
+                    continue;
+                const nestedPath = resolveModuleFilePath(imp.moduleName, modFilePath);
+                if (!nestedPath) {
+                    warnings.push(`[ImportWarning] Module '${imp.moduleName}' not found (imported in ${modFilePath})`);
+                    continue;
+                }
+                mergeWholeModuleImport(nestedPath);
+            }
+            ast.declarations.push(...modAst.declarations);
+            ast.structs.push(...modAst.structs);
+            ast.implBlocks.push(...modAst.implBlocks);
+            ast.enums.push(...modAst.enums);
+            ast.consts.push(...modAst.consts);
+            ast.globals.push(...modAst.globals);
+        }
+        for (const imp of ast.imports) {
+            if (imp.symbol !== undefined)
+                continue;
+            const resolved = resolveModuleFilePath(imp.moduleName, filePath);
+            if (!resolved) {
+                throw new diagnostics_1.DiagnosticError('ParseError', `Module '${imp.moduleName}' not found. Make sure '${imp.moduleName}.mcrs' exists relative to this file or in the stdlib.`, imp.span ?? { line: 1, col: 1 });
+            }
+            mergeWholeModuleImport(resolved);
+        }
+        for (const li of preprocessed.libraryImports ?? []) {
+            const libPreprocessed = (0, compile_1.preprocessSourceWithMetadata)(li.source, { filePath: li.filePath });
+            const libTokens = new lexer_1.Lexer(libPreprocessed.source, li.filePath).tokenize();
+            const libParser = new parser_1.Parser(libTokens, libPreprocessed.source, li.filePath);
+            const libAst = libParser.parse(namespace);
+            annotateFunctionSourceFiles(libAst, li.filePath);
+            warnings.push(...libParser.warnings);
+            if (libParser.parseErrors.length > 0) {
+                throw stopAfterCheck ? new diagnostics_1.DiagnosticBundleError(libParser.parseErrors) : libParser.parseErrors[0];
+            }
             for (const fn of libAst.declarations)
                 fn.isLibraryFn = true;
             ast.declarations.push(...libAst.declarations);
@@ -64,45 +214,107 @@ function compile(source, options = {}) {
             ast.consts.push(...libAst.consts);
             ast.globals.push(...libAst.globals);
         }
-    }
-    // Stage 1b: Type checking
-    // Run TypeChecker on the merged AST. In error-mode (default), throw on first type error.
-    // In lenient mode, demote type errors to warnings.
-    {
-        const checker = new typechecker_1.TypeChecker(processedSource, filePath);
-        const typeErrors = checker.check(ast);
-        // Collect lint warnings (non-blocking — always added regardless of error mode)
-        warnings.push(...checker.getWarnings());
-        if (typeErrors.length > 0) {
-            if (lenient) {
-                for (const e of typeErrors) {
-                    warnings.push(`[TypeError] line ${e.location.line}, col ${e.location.col}: ${e.message}`);
+        if (options.librarySources) {
+            for (const libSrc of options.librarySources) {
+                const libTokens = new lexer_1.Lexer(libSrc).tokenize();
+                const libParser = new parser_1.Parser(libTokens, libSrc);
+                const libAst = libParser.parse(namespace);
+                warnings.push(...libParser.warnings);
+                if (libParser.parseErrors.length > 0) {
+                    throw stopAfterCheck ? new diagnostics_1.DiagnosticBundleError(libParser.parseErrors) : libParser.parseErrors[0];
                 }
+                for (const fn of libAst.declarations)
+                    fn.isLibraryFn = true;
+                ast.declarations.push(...libAst.declarations);
+                ast.structs.push(...libAst.structs);
+                ast.implBlocks.push(...libAst.implBlocks);
+                ast.enums.push(...libAst.enums);
+                ast.consts.push(...libAst.consts);
+                ast.globals.push(...libAst.globals);
             }
-            else {
-                throw typeErrors[0];
+        }
+        {
+            const configValues = options.config ?? {};
+            const configGlobalNames = new Set();
+            for (const g of ast.globals) {
+                if (g.configKey !== undefined) {
+                    const resolvedValue = Object.prototype.hasOwnProperty.call(configValues, g.configKey)
+                        ? configValues[g.configKey]
+                        : (g.configDefault ?? 0);
+                    const intValue = Math.round(resolvedValue);
+                    ast.consts.push({
+                        name: g.name,
+                        type: { kind: 'named', name: 'int' },
+                        value: { kind: 'int_lit', value: intValue },
+                        span: g.span,
+                    });
+                    configGlobalNames.add(g.name);
+                }
+            }
+            if (configGlobalNames.size > 0) {
+                ast.globals = ast.globals.filter(g => !configGlobalNames.has(g.name));
+            }
+        }
+        {
+            const checker = new typechecker_1.TypeChecker(processedSource, filePath);
+            const typeErrors = checker.check(ast);
+            warnings.push(...checker.getWarnings());
+            if (typeErrors.length > 0) {
+                if (lenient) {
+                    for (const e of typeErrors) {
+                        warnings.push(`[TypeError] line ${e.location.line}, col ${e.location.col}: ${e.message}`);
+                    }
+                }
+                else {
+                    throw stopAfterCheck ? new diagnostics_1.DiagnosticBundleError(typeErrors) : typeErrors[0];
+                }
             }
         }
-    }
-    // Stage 2–7: lower, optimize, emit
-    // Wrap non-DiagnosticError from later stages so CLI always gets structured errors.
-    try {
         // Stage 2: AST → HIR
         const hirRaw = (0, lower_1.lowerToHIR)(ast);
         // Stage 2b: Monomorphize generic functions
         const hir = (0, monomorphize_1.monomorphize)(hirRaw);
-        // Extract @tick, @load, @coroutine, @schedule, and @on handlers from HIR (before decorator info is lost)
+        const libraryFilePaths = new Set(hir.functions
+            .filter(fn => fn.isLibraryFn && fn.decorators.length === 0)
+            .map(fn => `data/${namespace}/function/${fn.name}.mcfunction`));
+        // Stage 2c: Deprecated usage check — emit warnings for calls to @deprecated functions
+        warnings.push(...(0, deprecated_1.checkDeprecatedCalls)(hir));
+        if (stopAfterCheck) {
+            return { files: [], warnings, success: true };
+        }
+        // Extract decorator metadata before HIR lowering discards it.
         const tickFunctions = [];
         const loadFunctions = [];
+        const watchFunctions = [];
+        const inlineFunctions = new Set();
+        const noInlineFunctions = new Set();
         const coroutineInfos = [];
         const scheduleFunctions = [];
+        const profiledFunctions = [];
+        const throttleFunctions = [];
+        const retryFunctions = [];
+        const memoizeFunctions = [];
         const eventHandlers = new Map();
         for (const fn of hir.functions) {
+            if (fn.watchObjective) {
+                watchFunctions.push({ name: fn.name, objective: fn.watchObjective });
+            }
+            else {
+                // Fallback: extract from decorator if watchObjective not propagated
+                const watchDec = fn.decorators?.find(d => d.name === 'watch' && d.args?.objective);
+                if (watchDec?.args?.objective) {
+                    watchFunctions.push({ name: fn.name, objective: watchDec.args.objective });
+                }
+            }
             for (const dec of fn.decorators) {
                 if (dec.name === 'tick')
                     tickFunctions.push(fn.name);
                 if (dec.name === 'load')
                     loadFunctions.push(fn.name);
+                if (dec.name === 'inline')
+                    inlineFunctions.add(fn.name);
+                if (dec.name === 'no-inline')
+                    noInlineFunctions.add(fn.name);
                 if (dec.name === 'coroutine') {
                     coroutineInfos.push({
                         fnName: fn.name,
@@ -113,6 +325,18 @@ function compile(source, options = {}) {
                 if (dec.name === 'schedule') {
                     scheduleFunctions.push({ name: fn.name, ticks: dec.args?.ticks ?? 1 });
                 }
+                if (dec.name === 'profile') {
+                    profiledFunctions.push(fn.name);
+                }
+                if (dec.name === 'throttle' && dec.args?.ticks) {
+                    throttleFunctions.push({ name: fn.name, ticks: dec.args.ticks });
+                }
+                if (dec.name === 'retry' && dec.args?.max) {
+                    retryFunctions.push({ name: fn.name, max: dec.args.max });
+                }
+                if (dec.name === 'memoize') {
+                    memoizeFunctions.push(fn.name);
+                }
                 if (dec.name === 'on' && dec.args?.eventType) {
                     const evType = dec.args.eventType;
                     if ((0, types_1.isEventTypeName)(evType)) {
@@ -125,6 +349,12 @@ function compile(source, options = {}) {
         }
         // Stage 3: HIR → MIR
         const mir = (0, lower_2.lowerToMIR)(hir, filePath);
+        if (inlineFunctions.size > 0) {
+            mir.inlineFunctions = inlineFunctions;
+        }
+        if (noInlineFunctions.size > 0) {
+            mir.noInlineFunctions = noInlineFunctions;
+        }
         // Stage 4: MIR optimization
         const mirOpt = (0, pipeline_1.optimizeModule)(mir);
         // Stage 4b: Coroutine transform (opt-in, only for @coroutine functions)
@@ -157,15 +387,130 @@ function compile(source, options = {}) {
                 }
             }
         }
+        // Stage 6.9: Inject synthetic LIR functions for @singleton structs
+        // Each @singleton struct gets:
+        //   - A "<StructName>_get" function that reads all fields from scoreboard
+        //   - A "<StructName>_set" function that writes all fields back to scoreboard
+        // Fields are stored in scoreboard objectives named "_sng_<StructName>_<fieldName>"
+        // (max 16 chars for objective name — truncated with hash suffix if needed)
+        const singletonObjectives = [];
+        for (const s of hir.structs) {
+            if (!s.isSingleton)
+                continue;
+            const structName = s.name;
+            const objective = lirOpt.objective; // the main ns objective for return values
+            // Build _get function: reads each field from its own scoreboard objective
+            // Return struct fields via __rf_<field> slots in the main objective
+            const getInstrs = [];
+            for (const field of s.fields) {
+                const fieldObj = singletonObjectiveName(structName, field.name);
+                if (!singletonObjectives.includes(fieldObj)) {
+                    singletonObjectives.push(fieldObj);
+                }
+                // copy: scoreboard players operation $__rf_<field> <obj> = __sng_<S>_<f> <fieldObj>
+                getInstrs.push({
+                    kind: 'score_copy',
+                    dst: { player: `$__rf_${field.name}`, obj: objective },
+                    src: { player: `__sng`, obj: fieldObj },
+                });
+            }
+            // Return value placeholder
+            getInstrs.push({ kind: 'score_set', dst: { player: '$ret', obj: objective }, value: 0 });
+            // Use `::` naming so it matches how static_call `GameState::get` is qualified
+            // fnNameToPath converts `GameState::get` → `data/<ns>/function/gamestate/get.mcfunction`
+            lirOpt.functions.push({
+                name: `${structName}::get`,
+                instructions: getInstrs,
+                isMacro: false,
+                macroParams: [],
+            });
+            // Build _set function: writes each field back to its scoreboard objective
+            // Parameters come in via $p0..$pN slots (one per field)
+            const setInstrs = [];
+            for (let i = 0; i < s.fields.length; i++) {
+                const field = s.fields[i];
+                const fieldObj = singletonObjectiveName(structName, field.name);
+                setInstrs.push({
+                    kind: 'score_copy',
+                    dst: { player: `__sng`, obj: fieldObj },
+                    src: { player: `$p${i}`, obj: objective },
+                });
+            }
+            setInstrs.push({ kind: 'score_set', dst: { player: '$ret', obj: objective }, value: 0 });
+            lirOpt.functions.push({
+                name: `${structName}::set`,
+                instructions: setInstrs,
+                isMacro: false,
+                macroParams: [],
+            });
+        }
+        // Stage 6.95: Rename @memoize functions to <fn>_impl in LIR,
+        // rewriting recursive self-calls so the wrapper becomes the public entry point.
+        for (const fnName of memoizeFunctions) {
+            const lirFn = lirOpt.functions.find(f => f.name === fnName);
+            if (!lirFn)
+                continue;
+            const implName = `${fnName}_impl`;
+            lirFn.name = implName;
+            // Rewrite recursive calls: any call to fnName inside this function → implName
+            for (const instr of lirFn.instructions) {
+                if ('fn' in instr && instr.fn === fnName) {
+                    ;
+                    instr.fn = implName;
+                }
+            }
+        }
         // Stage 7: LIR → .mcfunction
-        const files = (0, index_1.emit)(lirOpt, { namespace, tickFunctions, loadFunctions, scheduleFunctions, generateSourceMap, mcVersion, eventHandlers });
-        return { files, warnings, success: true };
+        const files = (0, index_1.emit)(lirOpt, {
+            namespace,
+            tickFunctions,
+            loadFunctions,
+            watchFunctions,
+            scheduleFunctions,
+            generateSourceMap,
+            mcVersion,
+            eventHandlers,
+            singletonObjectives,
+            profiledFunctions,
+            enableProfiling: debug,
+            throttleFunctions,
+            retryFunctions,
+            memoizeFunctions,
+        });
+        const prunedFiles = pruneLibraryFunctionFiles(files, libraryFilePaths);
+        return { files: prunedFiles, warnings, success: true };
     }
     catch (err) {
+        if (stopAfterCheck) {
+            if (err instanceof diagnostics_1.CheckFailedError)
+                throw err;
+            if (err instanceof diagnostics_1.DiagnosticBundleError) {
+                throw new diagnostics_1.CheckFailedError(err.diagnostics, warnings);
+            }
+            if (err instanceof diagnostics_1.DiagnosticError) {
+                throw new diagnostics_1.CheckFailedError([err], warnings);
+            }
+            const sourceLines = processedSource.split('\n');
+            throw new diagnostics_1.CheckFailedError([(0, diagnostics_1.parseErrorMessage)('LoweringError', err.message, sourceLines, filePath)], warnings);
+        }
         if (err instanceof diagnostics_1.DiagnosticError)
             throw err;
         const sourceLines = processedSource.split('\n');
         throw (0, diagnostics_1.parseErrorMessage)('LoweringError', err.message, sourceLines, filePath);
     }
 }
+/**
+ * Compute a scoreboard objective name for a @singleton struct field.
+ * Format: _s_<struct>_<field>, truncated so total length ≤ 16 chars.
+ * If struct+field combined (with _s_ and _) exceeds 16:
+ *   use first 4 chars of struct, first 8 chars of field.
+ */
+function singletonObjectiveName(structName, fieldName) {
+    const overhead = 5; // "_s_" (3) + "_" (1) = 4, +1 for safety  -- actually "_s_" + "_" = 4
+    // Budget: 16 - 4 = 12 chars for struct + field combined
+    if (structName.length + fieldName.length <= 12) {
+        return `_s_${structName}_${fieldName}`;
+    }
+    return `_s_${structName.slice(0, 4)}_${fieldName.slice(0, 8)}`;
+}
 //# sourceMappingURL=compile.js.map

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

@@ -10,6 +10,10 @@ export interface DatapackFile {
     path: string;
     content: string;
 }
+export interface WatchFunction {
+    name: string;
+    objective: string;
+}
 export interface EmitOptions {
     namespace: string;
     tickFunctions?: string[];
@@ -18,11 +22,47 @@ export interface EmitOptions {
         name: string;
         ticks: number;
     }>;
+    watchFunctions?: WatchFunction[];
     /** When true, generate a .sourcemap.json sidecar file for each .mcfunction */
     generateSourceMap?: boolean;
     /** Target Minecraft version; controls which MC features are used in codegen */
     mcVersion?: McVersion;
     /** Map of EventTypeName → list of fully-qualified function references for @on handlers */
     eventHandlers?: Map<string, string[]>;
+    /** Scoreboard objective names for @singleton struct fields — added to load.mcfunction */
+    singletonObjectives?: string[];
+    /** Functions decorated with @profile. */
+    profiledFunctions?: string[];
+    /** Emit debug-only profiling instrumentation and helpers. */
+    enableProfiling?: boolean;
+    /** Functions decorated with @throttle. */
+    throttleFunctions?: Array<{
+        name: string;
+        ticks: number;
+    }>;
+    /** Functions decorated with @retry. */
+    retryFunctions?: Array<{
+        name: string;
+        max: number;
+    }>;
+    /** Functions decorated with @memoize — single-arg int result caching (LRU-1). */
+    memoizeFunctions?: string[];
 }
 export declare function emit(module: LIRModule, options: EmitOptions): DatapackFile[];
+/**
+ * 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)
+ */
+export declare function flattenExecute(cmd: string): string;