redscript-mc 1.2.30 → 2.0.0

package/dist/src/codegen/structure/index.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateStructure = generateStructure;
+exports.compileToStructure = compileToStructure;
+const lexer_1 = require("../../lexer");
+const parser_1 = require("../../parser");
+const lowering_1 = require("../../lowering");
+const nbt_1 = require("../../nbt");
+const commands_1 = require("../../optimizer/commands");
+const passes_1 = require("../../optimizer/passes");
+const structure_1 = require("../../optimizer/structure");
+const dce_1 = require("../../optimizer/dce");
+const compile_1 = require("../../compile");
+const types_1 = require("../../events/types");
+const var_allocator_1 = require("../var-allocator");
+const DATA_VERSION = 3953;
+const MAX_WIDTH = 16;
+const OBJ = 'rs';
+const PALETTE_IMPULSE = 0;
+const PALETTE_CHAIN_UNCONDITIONAL = 1;
+const PALETTE_CHAIN_CONDITIONAL = 2;
+const PALETTE_REPEAT = 3;
+const palette = [
+    { Name: 'minecraft:command_block', Properties: { conditional: 'false', facing: 'east' } },
+    { Name: 'minecraft:chain_command_block', Properties: { conditional: 'false', facing: 'east' } },
+    { Name: 'minecraft:chain_command_block', Properties: { conditional: 'true', facing: 'east' } },
+    { Name: 'minecraft:repeating_command_block', Properties: { conditional: 'false', facing: 'east' } },
+    { Name: 'minecraft:air', Properties: {} },
+];
+function escapeJsonString(value) {
+    return JSON.stringify(value).slice(1, -1);
+}
+function collectConsts(fn) {
+    const consts = new Set();
+    for (const block of fn.blocks) {
+        for (const instr of block.instrs) {
+            if (instr.op === 'assign' && instr.src.kind === 'const')
+                consts.add(instr.src.value);
+            if (instr.op === 'binop') {
+                if (instr.lhs.kind === 'const')
+                    consts.add(instr.lhs.value);
+                if (instr.rhs.kind === 'const')
+                    consts.add(instr.rhs.value);
+            }
+            if (instr.op === 'cmp') {
+                if (instr.lhs.kind === 'const')
+                    consts.add(instr.lhs.value);
+                if (instr.rhs.kind === 'const')
+                    consts.add(instr.rhs.value);
+            }
+        }
+        if (block.term.op === 'return' && block.term.value?.kind === 'const') {
+            consts.add(block.term.value.value);
+        }
+    }
+    return consts;
+}
+function collectCommandEntriesFromModule(module, mangle = false) {
+    const alloc = new var_allocator_1.VarAllocator(mangle);
+    const entries = [];
+    const triggerHandlers = module.functions.filter(fn => fn.isTriggerHandler && fn.triggerName);
+    const triggerNames = new Set(triggerHandlers.map(fn => fn.triggerName));
+    const eventHandlers = module.functions.filter((fn) => !!fn.eventHandler && (0, types_1.isEventTypeName)(fn.eventHandler.eventType));
+    const eventTypes = new Set(eventHandlers.map(fn => fn.eventHandler.eventType));
+    const loadCommands = [
+        `scoreboard objectives add ${OBJ} dummy`,
+        ...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(value => `scoreboard players set ${alloc.constant(value)} ${OBJ} ${value}`),
+    ];
+    for (const eventType of eventTypes) {
+        if (eventType === 'PlayerDeath') {
+            loadCommands.push('scoreboard objectives add rs.deaths deathCount');
+        }
+        else if (eventType === 'EntityKill') {
+            loadCommands.push('scoreboard objectives add rs.kills totalKillCount');
+        }
+    }
+    // Call @load functions from __load
+    for (const fn of module.functions) {
+        if (fn.isLoadInit) {
+            loadCommands.push(`function ${module.namespace}:${fn.name}`);
+        }
+    }
+    const sections = [];
+    if (loadCommands.length > 0) {
+        sections.push({
+            name: '__load',
+            commands: loadCommands.map(cmd => ({ cmd })),
+        });
+    }
+    for (const triggerName of triggerNames) {
+        const handlers = triggerHandlers.filter(fn => fn.triggerName === triggerName);
+        sections.push({
+            name: `__trigger_${triggerName}_dispatch`,
+            commands: [
+                ...handlers.map(handler => ({ cmd: `function ${module.namespace}:${handler.name}` })),
+                { cmd: `scoreboard players set @s ${triggerName} 0` },
+                { cmd: `scoreboard players enable @s ${triggerName}` },
+            ],
+        });
+    }
+    for (const fn of module.functions) {
+        if (!fn.commands || fn.commands.length === 0)
+            continue;
+        sections.push({
+            name: fn.name,
+            commands: fn.commands,
+        });
+    }
+    const tickCommands = [];
+    for (const fn of module.functions.filter(candidate => candidate.isTickLoop)) {
+        tickCommands.push({ cmd: `function ${module.namespace}:${fn.name}` });
+    }
+    if (triggerNames.size > 0) {
+        for (const triggerName of triggerNames) {
+            tickCommands.push({
+                cmd: `execute as @a[scores={${triggerName}=1..}] run function ${module.namespace}:__trigger_${triggerName}_dispatch`,
+            });
+        }
+    }
+    if (eventHandlers.length > 0) {
+        for (const eventType of eventTypes) {
+            const tag = types_1.EVENT_TYPES[eventType].tag;
+            const handlers = eventHandlers.filter(fn => fn.eventHandler?.eventType === eventType);
+            for (const handler of handlers) {
+                tickCommands.push({
+                    cmd: `execute as @a[tag=${tag}] run function ${module.namespace}:${handler.name}`,
+                });
+            }
+            tickCommands.push({
+                cmd: `tag @a[tag=${tag}] remove ${tag}`,
+            });
+        }
+    }
+    if (tickCommands.length > 0) {
+        sections.push({
+            name: '__tick',
+            commands: tickCommands,
+            repeat: true,
+        });
+    }
+    for (const section of sections) {
+        for (let i = 0; i < section.commands.length; i++) {
+            const command = section.commands[i];
+            const state = i === 0
+                ? (section.repeat ? PALETTE_REPEAT : PALETTE_IMPULSE)
+                : (command.conditional ? PALETTE_CHAIN_CONDITIONAL : PALETTE_CHAIN_UNCONDITIONAL);
+            entries.push({
+                functionName: section.name,
+                lineNumber: i + 1,
+                command: command.cmd,
+                conditional: Boolean(command.conditional),
+                state,
+                isRepeat: Boolean(section.repeat && i === 0),
+            });
+        }
+    }
+    return entries;
+}
+function toFunctionName(file) {
+    const match = file.path.match(/^data\/[^/]+\/function\/(.+)\.mcfunction$/);
+    return match?.[1] ?? null;
+}
+function collectCommandEntriesFromFiles(files) {
+    const entries = [];
+    for (const file of files) {
+        const functionName = toFunctionName(file);
+        if (!functionName)
+            continue;
+        const lines = file.content.split('\n');
+        let isFirstCommand = true;
+        const isTickFunction = functionName === '__tick';
+        for (let i = 0; i < lines.length; i++) {
+            const command = lines[i].trim();
+            if (command === '' || command.startsWith('#'))
+                continue;
+            const state = isFirstCommand
+                ? (isTickFunction ? PALETTE_REPEAT : PALETTE_IMPULSE)
+                : PALETTE_CHAIN_UNCONDITIONAL;
+            entries.push({
+                functionName,
+                lineNumber: i + 1,
+                command,
+                conditional: false,
+                state,
+                isRepeat: isTickFunction && isFirstCommand,
+            });
+            isFirstCommand = false;
+        }
+    }
+    return entries;
+}
+function createPaletteTag() {
+    return palette.map(entry => nbt_1.nbt.compound({
+        Name: nbt_1.nbt.string(entry.Name),
+        Properties: nbt_1.nbt.compound(Object.fromEntries(Object.entries(entry.Properties).map(([key, value]) => [key, nbt_1.nbt.string(value)]))),
+    }));
+}
+function createBlockEntityTag(entry) {
+    return nbt_1.nbt.compound({
+        id: nbt_1.nbt.string('minecraft:command_block'),
+        Command: nbt_1.nbt.string(entry.command),
+        auto: nbt_1.nbt.byte(entry.isRepeat ? 1 : 0),
+        powered: nbt_1.nbt.byte(0),
+        conditionMet: nbt_1.nbt.byte(0),
+        UpdateLastExecution: nbt_1.nbt.byte(1),
+        LastExecution: nbt_1.nbt.long(0n),
+        TrackOutput: nbt_1.nbt.byte(1),
+        SuccessCount: nbt_1.nbt.int(0),
+        LastOutput: nbt_1.nbt.string(''),
+        CustomName: nbt_1.nbt.string(`{"text":"${escapeJsonString(`${entry.functionName}:${entry.lineNumber}`)}"}`),
+    });
+}
+function createBlockTag(entry, index) {
+    const x = index % MAX_WIDTH;
+    const z = Math.floor(index / MAX_WIDTH) % MAX_WIDTH;
+    const y = Math.floor(index / (MAX_WIDTH * MAX_WIDTH));
+    return nbt_1.nbt.compound({
+        pos: nbt_1.nbt.list(3 /* TagType.Int */, [nbt_1.nbt.int(x), nbt_1.nbt.int(y), nbt_1.nbt.int(z)]),
+        state: nbt_1.nbt.int(entry.state),
+        nbt: createBlockEntityTag(entry),
+    });
+}
+function generateStructure(input, options) {
+    const entries = Array.isArray(input)
+        ? collectCommandEntriesFromFiles(input)
+        : collectCommandEntriesFromModule(input, options?.mangle);
+    const blockTags = entries.map(createBlockTag);
+    const sizeX = Math.max(1, Math.min(MAX_WIDTH, entries.length || 1));
+    const sizeZ = Math.max(1, Math.min(MAX_WIDTH, Math.ceil(entries.length / MAX_WIDTH) || 1));
+    const sizeY = Math.max(1, Math.ceil(entries.length / (MAX_WIDTH * MAX_WIDTH)) || 1);
+    const root = nbt_1.nbt.compound({
+        DataVersion: nbt_1.nbt.int(DATA_VERSION),
+        size: nbt_1.nbt.list(3 /* TagType.Int */, [nbt_1.nbt.int(sizeX), nbt_1.nbt.int(sizeY), nbt_1.nbt.int(sizeZ)]),
+        palette: nbt_1.nbt.list(10 /* TagType.Compound */, createPaletteTag()),
+        blocks: nbt_1.nbt.list(10 /* TagType.Compound */, blockTags),
+        entities: nbt_1.nbt.list(10 /* TagType.Compound */, []),
+    });
+    return {
+        buffer: (0, nbt_1.writeNbt)(root, ''),
+        blockCount: entries.length,
+        blocks: entries.map(entry => ({
+            command: entry.command,
+            conditional: entry.conditional,
+            state: entry.state,
+            functionName: entry.functionName,
+            lineNumber: entry.lineNumber,
+        })),
+    };
+}
+function compileToStructure(source, namespace, filePath, options = {}) {
+    const preprocessedSource = (0, compile_1.preprocessSource)(source, { filePath });
+    const tokens = new lexer_1.Lexer(preprocessedSource, filePath).tokenize();
+    const parsedAst = new parser_1.Parser(tokens, preprocessedSource, filePath).parse(namespace);
+    const dceResult = options.dce ?? true ? (0, dce_1.eliminateDeadCode)(parsedAst) : { program: parsedAst, warnings: [] };
+    const ast = dceResult.program;
+    const ir = new lowering_1.Lowering(namespace).lower(ast);
+    const stats = (0, commands_1.createEmptyOptimizationStats)();
+    const optimizedIRFunctions = ir.functions.map(fn => {
+        const optimized = (0, passes_1.optimizeWithStats)(fn);
+        (0, commands_1.mergeOptimizationStats)(stats, optimized.stats);
+        return optimized.fn;
+    });
+    const structureOptimized = (0, structure_1.optimizeForStructureWithStats)(optimizedIRFunctions, namespace);
+    (0, commands_1.mergeOptimizationStats)(stats, structureOptimized.stats);
+    const optimizedModule = {
+        ...ir,
+        functions: structureOptimized.functions,
+    };
+    return {
+        ...generateStructure(optimizedModule, { mangle: options.mangle }),
+        stats,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/codegen/var-allocator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare class VarAllocator {
+    private readonly mangle;
+    private seq;
+    private readonly varCache;
+    private readonly constCache;
+    private readonly internalCache;
+    constructor(mangle?: boolean);
+    /** Allocate a name for a user variable. Strips leading '$' if present. */
+    alloc(originalName: string): string;
+    /** Allocate a name for a constant value (content-addressed). */
+    constant(value: number): string;
+    /**
+     * Look up the allocated name for a raw scoreboard fake-player name such as
+     * "$_2", "$x", "$p0", or "$ret".  Returns the mangled name when mangle=true,
+     * or the original name when mangle=false or the name is not yet known.
+     *
+     * Unlike alloc/internal/constant this does NOT create a new slot — it only
+     * resolves names that were already registered.  Used by the codegen to
+     * rewrite variable references inside `raw` IR instructions.
+     */
+    resolve(rawName: string): string;
+    /**
+     * Rewrite all $varname tokens in a raw mcfunction command string so that
+     * IR variable names are replaced by their allocated (possibly mangled) names.
+     * Tokens that are not registered in the allocator are left untouched (they
+     * are literal scoreboard fake-player names like "out" or "#rs").
+     */
+    resolveRaw(cmd: string): string;
+    /** Allocate a name for a compiler internal (e.g. "ret", "p0"). */
+    internal(suffix: string): string;
+    /** Generate the next sequential name: a, b, ..., z, aa, ab, ..., az, ba, ... */
+    private nextSeqName;
+    /**
+     * 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>;
+}

package/dist/src/codegen/var-allocator.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VarAllocator = void 0;
+class VarAllocator {
+    constructor(mangle = true) {
+        this.seq = 0;
+        this.varCache = new Map();
+        this.constCache = new Map();
+        this.internalCache = new Map();
+        this.mangle = mangle;
+    }
+    /** Allocate a name for a user variable. Strips leading '$' if present. */
+    alloc(originalName) {
+        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) {
+        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;
+    }
+    /**
+     * Look up the allocated name for a raw scoreboard fake-player name such as
+     * "$_2", "$x", "$p0", or "$ret".  Returns the mangled name when mangle=true,
+     * or the original name when mangle=false or the name is not yet known.
+     *
+     * Unlike alloc/internal/constant this does NOT create a new slot — it only
+     * resolves names that were already registered.  Used by the codegen to
+     * rewrite variable references inside `raw` IR instructions.
+     */
+    resolve(rawName) {
+        const clean = rawName.startsWith('$') ? rawName.slice(1) : rawName;
+        // Check every cache in priority order: vars, internals, consts
+        return (this.varCache.get(clean) ??
+            this.internalCache.get(clean) ??
+            rawName // not registered → return as-is (literal fake player, not a var)
+        );
+    }
+    /**
+     * Rewrite all $varname tokens in a raw mcfunction command string so that
+     * IR variable names are replaced by their allocated (possibly mangled) names.
+     * Tokens that are not registered in the allocator are left untouched (they
+     * are literal scoreboard fake-player names like "out" or "#rs").
+     */
+    resolveRaw(cmd) {
+        return cmd.replace(/\$[A-Za-z_][A-Za-z0-9_]*/g, (tok) => this.resolve(tok));
+    }
+    /** Allocate a name for a compiler internal (e.g. "ret", "p0"). */
+    internal(suffix) {
+        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, ... */
+    nextSeqName() {
+        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() {
+        const map = {};
+        for (const [orig, alloc] of this.varCache) {
+            // Skip compiler-generated temporaries (start with _ followed by digits)
+            if (/^_\d+$/.test(orig))
+                continue;
+            map[alloc] = orig;
+        }
+        for (const [val, alloc] of this.constCache)
+            map[alloc] = `const:${val}`;
+        for (const [suf, alloc] of this.internalCache)
+            map[alloc] = `internal:${suf}`;
+        return map;
+    }
+}
+exports.VarAllocator = VarAllocator;
+//# sourceMappingURL=var-allocator.js.map

package/dist/src/compile.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RedScript Compile API
+ *
+ * Preprocessing utilities and v2 compile re-export.
+ */
+export { compile, CompileOptions, CompileResult } from '../src2/emit/compile';
+export type { DatapackFile } from '../src2/emit/index';
+export interface SourceRange {
+    startLine: number;
+    endLine: number;
+    filePath: string;
+}
+export interface PreprocessedSource {
+    source: string;
+    ranges: SourceRange[];
+    /** Imported files that declared `module library;` — parsed separately
+     *  in library mode so their functions are DCE-eligible.  Never concatenated
+     *  into `source`. */
+    libraryImports?: Array<{
+        source: string;
+        filePath: string;
+    }>;
+}
+/**
+ * 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 declare function resolveSourceLine(combinedLine: number, ranges: SourceRange[], fallbackFile?: string): {
+    filePath?: string;
+    line: number;
+};
+interface PreprocessOptions {
+    filePath?: string;
+    seen?: Set<string>;
+}
+export declare function preprocessSourceWithMetadata(source: string, options?: PreprocessOptions): PreprocessedSource;
+export declare function preprocessSource(source: string, options?: PreprocessOptions): string;

package/dist/src/compile.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * RedScript Compile API
+ *
+ * Preprocessing utilities and v2 compile re-export.
+ */
+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 = void 0;
+exports.resolveSourceLine = resolveSourceLine;
+exports.preprocessSourceWithMetadata = preprocessSourceWithMetadata;
+exports.preprocessSource = preprocessSource;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const diagnostics_1 = require("./diagnostics");
+// ---------------------------------------------------------------------------
+// Re-export v2 compile
+// ---------------------------------------------------------------------------
+var compile_1 = require("../src2/emit/compile");
+Object.defineProperty(exports, "compile", { enumerable: true, get: function () { return compile_1.compile; } });
+/**
+ * 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.
+ */
+function resolveSourceLine(combinedLine, ranges, fallbackFile) {
+    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*$/;
+/** Returns true if the source file declares `module library;` at its top
+ *  (before any non-comment/non-blank lines). */
+function isLibrarySource(source) {
+    for (const line of source.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('//'))
+            continue;
+        return /^module\s+library\s*;/.test(trimmed);
+    }
+    return false;
+}
+function countLines(source) {
+    return source === '' ? 0 : source.split('\n').length;
+}
+function offsetRanges(ranges, lineOffset) {
+    return ranges.map(range => ({
+        startLine: range.startLine + lineOffset,
+        endLine: range.endLine + lineOffset,
+        filePath: range.filePath,
+    }));
+}
+function preprocessSourceWithMetadata(source, options = {}) {
+    const { filePath } = options;
+    const seen = options.seen ?? new Set();
+    if (filePath) {
+        seen.add(path.resolve(filePath));
+    }
+    const lines = source.split('\n');
+    const imports = [];
+    /** Library imports: `module library;` files routed here instead of concatenated. */
+    const libraryImports = [];
+    const bodyLines = [];
+    let parsingHeader = true;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        const match = line.match(IMPORT_RE);
+        if (parsingHeader && match) {
+            if (!filePath) {
+                throw new diagnostics_1.DiagnosticError('ParseError', 'Import statements require a file path', { line: i + 1, col: 1 }, lines);
+            }
+            const importPath = path.resolve(path.dirname(filePath), match[1]);
+            if (!seen.has(importPath)) {
+                seen.add(importPath);
+                let importedSource;
+                try {
+                    importedSource = fs.readFileSync(importPath, 'utf-8');
+                }
+                catch {
+                    throw new diagnostics_1.DiagnosticError('ParseError', `Cannot import '${match[1]}'`, { file: filePath, line: i + 1, col: 1 }, lines);
+                }
+                if (isLibrarySource(importedSource)) {
+                    // Library file: parse separately so its functions are DCE-eligible.
+                    // Also collect any transitive library imports inside it.
+                    const nested = preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen });
+                    libraryImports.push({ source: importedSource, filePath: importPath });
+                    // Propagate transitive library imports (e.g. math.mcrs imports vec.mcrs)
+                    if (nested.libraryImports)
+                        libraryImports.push(...nested.libraryImports);
+                }
+                else {
+                    imports.push(preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen }));
+                }
+            }
+            continue;
+        }
+        if (parsingHeader && (trimmed === '' || trimmed.startsWith('//'))) {
+            bodyLines.push(line);
+            continue;
+        }
+        parsingHeader = false;
+        bodyLines.push(line);
+    }
+    const body = bodyLines.join('\n');
+    const parts = [...imports.map(entry => entry.source), body].filter(Boolean);
+    const combined = parts.join('\n');
+    const ranges = [];
+    let lineOffset = 0;
+    for (const entry of imports) {
+        ranges.push(...offsetRanges(entry.ranges, lineOffset));
+        lineOffset += countLines(entry.source);
+    }
+    if (filePath && body) {
+        ranges.push({
+            startLine: lineOffset + 1,
+            endLine: lineOffset + countLines(body),
+            filePath: path.resolve(filePath),
+        });
+    }
+    return {
+        source: combined,
+        ranges,
+        libraryImports: libraryImports.length > 0 ? libraryImports : undefined,
+    };
+}
+function preprocessSource(source, options = {}) {
+    return preprocessSourceWithMetadata(source, options).source;
+}
+//# sourceMappingURL=compile.js.map

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

@@ -0,0 +1,44 @@
+/**
+ * RedScript Diagnostics
+ *
+ * Error reporting with file path, line, column, and formatted error messages.
+ */
+export type DiagnosticKind = 'LexError' | 'ParseError' | 'LoweringError' | 'TypeError';
+export interface DiagnosticLocation {
+    file?: string;
+    line: number;
+    col: number;
+}
+export declare class DiagnosticError extends Error {
+    readonly kind: DiagnosticKind;
+    readonly location: DiagnosticLocation;
+    readonly sourceLines?: string[];
+    constructor(kind: DiagnosticKind, message: string, location: DiagnosticLocation, sourceLines?: string[]);
+    /**
+     * Format the error for display:
+     * ```
+     * Error: [ParseError] line 5, col 12: Expected ';' after statement
+     *   5 |   let x = 42
+     *                   ^ expected ';'
+     * ```
+     */
+    format(): string;
+    toString(): string;
+}
+export declare class DiagnosticCollector {
+    private diagnostics;
+    private sourceLines;
+    private filePath?;
+    constructor(source?: string, filePath?: string);
+    error(kind: DiagnosticKind, message: string, line: number, col: number): void;
+    hasErrors(): boolean;
+    getErrors(): DiagnosticError[];
+    formatAll(): string;
+    throwFirst(): never;
+}
+/**
+ * Create a DiagnosticError from a raw error message that includes line/col info
+ * e.g., "Expected ';' at line 5, col 12"
+ */
+export declare function parseErrorMessage(kind: DiagnosticKind, rawMessage: string, sourceLines?: string[], filePath?: string): DiagnosticError;
+export declare function formatError(error: Error | DiagnosticError, source?: string): string;