@gwigz/slua-tstl-plugin 1.1.0 → 1.2.0

package/README.md

@@ -180,6 +180,22 @@ This only applies when the argument is directly a `/` expression. `Math.floor(x)
 > [!WARNING]
 > JavaScript integer truncation idioms `~~x` and `x | 0` do **not** map cleanly to Luau. `~~x` emits `bit32.bnot(bit32.bnot(x))` and `x | 0` emits `bit32.bor(x, 0)`, neither of which preserves correct semantics for negative numbers (the `bit32` library operates on unsigned 32-bit integers). Use `math.floor(x)` for floor truncation instead.
 
+### Passthrough arrow closures
+
+Zero-parameter arrow functions that just call another zero-parameter function are collapsed to a direct function reference:
+
+| TypeScript                                  | Lua output                          |
+| ------------------------------------------- | ----------------------------------- |
+| `LLTimers.once(1, () => patchNext())`       | `LLTimers:once(1, patchNext)`       |
+| `LLEvents.on("on_rez", () => refreshUrl())` | `LLEvents:on("on_rez", refreshUrl)` |
+
+This applies when:
+
+- The arrow has zero parameters
+- The body is a single call with zero arguments
+- The callee is a simple identifier (not a method call)
+- The callee's type signature has zero parameters (so extra args from the caller are harmlessly ignored)
+
 ## Optimizations
 
 Pass `optimize: true` to enable all optimizations, or pass an object to pick individual flags. All flags default to `false` when not specified.
@@ -306,6 +322,36 @@ local msg = "items: " .. count
 
 Non-numeric types (booleans, `any`, etc.) still get wrapped in `tostring()`.
 
+### `defaultParams`
+
+Collapses default-parameter nil-checks into a single `or` expression.
+
+```typescript
+function respondPoll(extraHtml = "") {
+  // ...
+}
+```
+
+Default output:
+
+```lua
+function respondPoll(extraHtml)
+    if extraHtml == nil then
+        extraHtml = ""
+    end
+end
+```
+
+Optimized output:
+
+```lua
+function respondPoll(extraHtml)
+    extraHtml = extraHtml or ""
+end
+```
+
+Safe for string and number defaults (both truthy in Lua). Not applied to `false` defaults.
+
 ## Keeping output small
 
 Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean:

package/dist/define.d.ts

@@ -0,0 +1,19 @@
+import * as ts from "typescript";
+export type DefineMap = Map<string, boolean | number | string>;
+/**
+ * Attempt to statically evaluate a TS expression against the define map.
+ * Returns the resolved value, or `undefined` if the expression cannot be
+ * statically resolved (i.e. it should be left to the normal transpiler).
+ *
+ * Supported forms:
+ * - Bare identifier: `CONFIG_X` -> lookup
+ * - Negation: `!CONFIG_X`
+ * - Strict equality: `CONFIG_X === true`, `CONFIG_X !== false`, etc.
+ */
+export declare function tryEvaluateCondition(expr: ts.Expression, defineMap: DefineMap): boolean | undefined;
+/**
+ * Check whether a node has a `@define FLAG` JSDoc tag whose flag
+ * is in the define map and resolves to falsy. When true, the
+ * entire declaration should be stripped from the output.
+ */
+export declare function shouldStripDefineGuard(node: ts.Node, defineMap: DefineMap): boolean;

package/dist/define.js

@@ -0,0 +1,83 @@
+import * as ts from "typescript";
+/**
+ * Attempt to statically evaluate a TS expression against the define map.
+ * Returns the resolved value, or `undefined` if the expression cannot be
+ * statically resolved (i.e. it should be left to the normal transpiler).
+ *
+ * Supported forms:
+ * - Bare identifier: `CONFIG_X` -> lookup
+ * - Negation: `!CONFIG_X`
+ * - Strict equality: `CONFIG_X === true`, `CONFIG_X !== false`, etc.
+ */
+export function tryEvaluateCondition(expr, defineMap) {
+    // Bare identifier: CONFIG_X
+    if (ts.isIdentifier(expr)) {
+        const value = defineMap.get(expr.text);
+        return value === undefined ? undefined : !!value;
+    }
+    // Negation: !CONFIG_X
+    if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.ExclamationToken) {
+        const inner = tryEvaluateCondition(expr.operand, defineMap);
+        return inner === undefined ? undefined : !inner;
+    }
+    // Strict equality/inequality: CONFIG_X === true, CONFIG_X !== false, etc.
+    if (ts.isBinaryExpression(expr)) {
+        const op = expr.operatorToken.kind;
+        if (op !== ts.SyntaxKind.EqualsEqualsEqualsToken &&
+            op !== ts.SyntaxKind.ExclamationEqualsEqualsToken) {
+            return undefined;
+        }
+        let identValue;
+        let literalValue;
+        // Try both orientations: CONFIG_X === true  or  true === CONFIG_X
+        if (ts.isIdentifier(expr.left)) {
+            identValue = defineMap.get(expr.left.text);
+            literalValue = extractLiteral(expr.right);
+        }
+        else if (ts.isIdentifier(expr.right)) {
+            identValue = defineMap.get(expr.right.text);
+            literalValue = extractLiteral(expr.left);
+        }
+        if (identValue === undefined || literalValue === undefined)
+            return undefined;
+        const equal = identValue === literalValue;
+        return op === ts.SyntaxKind.EqualsEqualsEqualsToken ? equal : !equal;
+    }
+    return undefined;
+}
+/**
+ * Check whether a node has a `@define FLAG` JSDoc tag whose flag
+ * is in the define map and resolves to falsy. When true, the
+ * entire declaration should be stripped from the output.
+ */
+export function shouldStripDefineGuard(node, defineMap) {
+    const jsDocs = node.jsDoc;
+    if (!jsDocs || jsDocs.length === 0)
+        return false;
+    for (const tag of ts.getJSDocTags(node)) {
+        if (tag.tagName.text === "define" && typeof tag.comment === "string") {
+            const flag = tag.comment.trim();
+            if (defineMap.has(flag) && !defineMap.get(flag)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function extractLiteral(expr) {
+    if (expr.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (expr.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (ts.isNumericLiteral(expr))
+        return Number(expr.text);
+    if (ts.isStringLiteral(expr))
+        return expr.text;
+    // Handle negative numbers: -123
+    if (ts.isPrefixUnaryExpression(expr) &&
+        expr.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(expr.operand)) {
+        return -Number(expr.operand.text);
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -1,10 +1,13 @@
 import * as tstl from "typescript-to-lua";
 import type { CallTransform } from "./transforms.js";
 import type { OptimizeFlags } from "./optimize.js";
-export type { CallTransform, OptimizeFlags };
+import type { DefineMap } from "./define.js";
+export type { CallTransform, OptimizeFlags, DefineMap };
 export interface SluaPluginOptions {
     /** Enable per-transform output optimizations. Pass `true` to enable all. */
     optimize?: boolean | OptimizeFlags;
+    /** Compile-time defines for dead code elimination. */
+    define?: Record<string, boolean | number | string>;
     [key: string]: any;
 }
 declare function createPlugin(options?: SluaPluginOptions): tstl.Plugin;

package/dist/index.js

@@ -1,16 +1,91 @@
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
 import { PASCAL_TO_LOWER, TSTL_KEYWORD_FIXUPS, BINARY_BITWISE_OPS, COMPOUND_BITWISE_OPS, } from "./constants.js";
-import { createBit32Call, isMathFloor, isStringOrNumberLike, extractBtestPattern, extractIndexOfPresence, extractConcatSelfAssignment, extractSpreadSelfAssignment, emitChainedExtend, getLLIndexSemantics, emitLLIndexCall, isDetectedEventIndex, createNamespacedCall, createStringFindCall, escapeRegex, } from "./utils.js";
+import { createBit32Call, isMathFloor, isStringOrNumberLike, extractBtestPattern, extractIndexOfPresence, extractConcatSelfAssignment, extractSpreadSelfAssignment, emitChainedExtend, getLLIndexSemantics, emitLLIndexCall, isDetectedEventIndex, createNamespacedCall, createStringFindCall, } from "./utils.js";
 import { CALL_TRANSFORMS } from "./transforms.js";
 import { createOptimizeTransforms, countFilterCalls, ALL_OPTIMIZE } from "./optimize.js";
+import { tryEvaluateCondition, shouldStripDefineGuard } from "./define.js";
+import { stripInternalJSDocTags, stripEmptyModuleBoilerplate, collapseDefaultParamNilChecks, shortenTempNames, collapseFieldAccesses, inlineForwardDeclarations, } from "./lua-transforms.js";
 function createPlugin(options = {}) {
     const opt = options.optimize === true ? ALL_OPTIMIZE : options.optimize || {};
     const filterSkipFiles = new Set();
     const optTransforms = opt.filter ? createOptimizeTransforms(filterSkipFiles) : [];
     const transforms = [...CALL_TRANSFORMS, ...optTransforms];
+    const defineMap = new Map(options.define ? Object.entries(options.define) : []);
     const plugin = {
         visitors: {
+            [ts.SyntaxKind.Identifier]: defineMap.size > 0
+                ? (node, context) => {
+                    const value = defineMap.get(node.text);
+                    if (value === undefined)
+                        return context.superTransformExpression(node);
+                    // Don't replace if this identifier is:
+                    // - A property name in a property access (obj.CONFIG_X)
+                    // - A declaration name (const CONFIG_X = ...)
+                    // - A parameter name
+                    // - A property assignment name ({ CONFIG_X: ... })
+                    // - A shorthand property assignment name ({ CONFIG_X })
+                    const parent = node.parent;
+                    if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if ((ts.isVariableDeclaration(parent) ||
+                        ts.isFunctionDeclaration(parent) ||
+                        ts.isParameter(parent) ||
+                        ts.isEnumMember(parent)) &&
+                        parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if (ts.isPropertyAssignment(parent) && parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) {
+                        return context.superTransformExpression(node);
+                    }
+                    if (typeof value === "boolean") {
+                        return tstl.createBooleanLiteral(value, node);
+                    }
+                    if (typeof value === "number") {
+                        return tstl.createNumericLiteral(value, node);
+                    }
+                    return tstl.createStringLiteral(value, node);
+                }
+                : undefined,
+            [ts.SyntaxKind.IfStatement]: defineMap.size > 0
+                ? (node, context) => {
+                    const result = tryEvaluateCondition(node.expression, defineMap);
+                    if (result === undefined) {
+                        return context.superTransformStatements(node);
+                    }
+                    if (result) {
+                        const stmts = ts.isBlock(node.thenStatement)
+                            ? [...node.thenStatement.statements]
+                            : [node.thenStatement];
+                        return stmts.flatMap((s) => context.transformStatements(s));
+                    }
+                    if (node.elseStatement) {
+                        const stmts = ts.isBlock(node.elseStatement)
+                            ? [...node.elseStatement.statements]
+                            : [node.elseStatement];
+                        return stmts.flatMap((s) => context.transformStatements(s));
+                    }
+                    return [];
+                }
+                : undefined,
+            [ts.SyntaxKind.FunctionDeclaration]: defineMap.size > 0
+                ? (node, context) => {
+                    if (shouldStripDefineGuard(node, defineMap))
+                        return [];
+                    return context.superTransformStatements(node);
+                }
+                : undefined,
+            [ts.SyntaxKind.VariableStatement]: defineMap.size > 0
+                ? (node, context) => {
+                    if (shouldStripDefineGuard(node, defineMap))
+                        return [];
+                    return context.superTransformStatements(node);
+                }
+                : undefined,
             [ts.SyntaxKind.PropertyAccessExpression]: (node, context) => {
                 const result = context.superTransformExpression(node);
                 // Rewrite identifiers in the Lua AST (PascalCase -> lowercase, TSTL keyword fixups).
@@ -187,6 +262,35 @@ function createPlugin(options = {}) {
                 }
                 return parts.reduce((prev, current) => tstl.createBinaryExpression(prev, current, tstl.SyntaxKind.ConcatOperator));
             },
+            // Collapse `() => fn()` to just `fn` when fn has zero parameters.
+            // Extra args from the caller are harmlessly ignored by zero-param functions.
+            [ts.SyntaxKind.ArrowFunction]: (node, context) => {
+                if (node.parameters.length === 0) {
+                    let callExpr;
+                    if (ts.isCallExpression(node.body)) {
+                        callExpr = node.body;
+                    }
+                    else if (ts.isBlock(node.body) && node.body.statements.length === 1) {
+                        const stmt = node.body.statements[0];
+                        if (ts.isExpressionStatement(stmt) && ts.isCallExpression(stmt.expression)) {
+                            callExpr = stmt.expression;
+                        }
+                        else if (ts.isReturnStatement(stmt) &&
+                            stmt.expression &&
+                            ts.isCallExpression(stmt.expression)) {
+                            callExpr = stmt.expression;
+                        }
+                    }
+                    if (callExpr && callExpr.arguments.length === 0 && ts.isIdentifier(callExpr.expression)) {
+                        const type = context.checker.getTypeAtLocation(callExpr.expression);
+                        const sigs = type.getCallSignatures();
+                        if (sigs.length > 0 && sigs.every((s) => s.parameters.length === 0)) {
+                            return context.transformExpression(callExpr.expression);
+                        }
+                    }
+                }
+                return context.superTransformExpression(node);
+            },
         },
         beforeTransform(program, compilerOptions) {
             const diagnostics = [];
@@ -214,152 +318,34 @@ function createPlugin(options = {}) {
             }
             return diagnostics;
         },
-        beforeEmit(program, _options, _emitHost, result) {
-            // Strip internal @indexArg / @indexReturn JSDoc tags from Lua comments.
-            // These are only consumed by the plugin at transpile time; they should
-            // not leak into the output as Lua comments.
-            for (const file of result) {
-                file.code = file.code
-                    .replace(/^--\s*@index(?:Arg|Return)\b.*\n/gm, "")
-                    .replace(/^(---.*)\n(?:-- *\n)+(?=local |ll\.)/gm, "$1\n");
-            }
-            // Strip empty module boilerplate from files without explicit exports.
-            // `moduleDetection: "force"` causes TSTL to wrap every file as a module;
-            // standalone SLua scripts don't need the ____exports wrapper.
+        afterPrint(program, _options, emitHost, result) {
             for (const file of result) {
-                if (!file.code.includes("local ____exports = {}\n"))
+                if (!file.luaAst)
                     continue;
-                if (!file.code.trimEnd().endsWith("return ____exports"))
-                    continue;
-                const hasExplicitExports = file.sourceFiles?.some((sf) => sf.statements.some((s) => ts.isExportDeclaration(s) ||
-                    ts.isExportAssignment(s) ||
-                    (ts.canHaveModifiers(s) &&
-                        ts.getModifiers(s)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))));
-                if (!hasExplicitExports) {
-                    file.code = file.code
-                        .replace(/local ____exports = \{\}\n/, "")
-                        .replace(/\nreturn ____exports\n?$/, "\n");
-                }
-            }
-            // Shorten TSTL destructuring temp names: ____fn_result_N -> _rN
-            // Then collapse consecutive field accesses into multi-assignment:
-            // local a = _r0.x\nlocal b = _r0.y -> local a, b = _r0.x, _r0.y
-            if (opt.shortenTemps) {
-                for (const file of result) {
-                    const seen = new Map();
-                    let counter = 0;
-                    // Collect all unique temp names in order of first occurrence
-                    for (const match of file.code.matchAll(/____\w+_result_\d+/g)) {
-                        if (!seen.has(match[0])) {
-                            seen.set(match[0], `_r${counter++}`);
-                        }
-                    }
-                    // Replace all long names with short aliases in a single pass
-                    if (seen.size > 0) {
-                        const combined = new RegExp(`\\b(${[...seen.keys()].join("|")})\\b`, "g");
-                        file.code = file.code.replace(combined, (m) => seen.get(m) ?? m);
-                    }
-                    // Collapse consecutive field accesses from the same temp into multi-assignment
-                    const lines = file.code.split("\n");
-                    const collapsed = [];
-                    let li = 0;
-                    while (li < lines.length) {
-                        const m = lines[li].match(/^(\s*)local\s+(\w+)\s*=\s*(_r\d+)\.(\w+)\s*$/);
-                        if (m) {
-                            const [, indent, name, temp, field] = m;
-                            const names = [name];
-                            const accesses = [`${temp}.${field}`];
-                            const nextRe = new RegExp(`^${escapeRegex(indent)}local\\s+(\\w+)\\s*=\\s*${temp}\\.(\\w+)\\s*$`);
-                            while (li + 1 < lines.length) {
-                                const next = lines[li + 1].match(nextRe);
-                                if (!next)
-                                    break;
-                                names.push(next[1]);
-                                accesses.push(`${temp}.${next[2]}`);
-                                li++;
-                            }
-                            if (names.length > 1) {
-                                collapsed.push(`${indent}local ${names.join(", ")} = ${accesses.join(", ")}`);
-                            }
-                            else {
-                                collapsed.push(lines[li]);
-                            }
-                        }
-                        else {
-                            collapsed.push(lines[li]);
-                        }
-                        li++;
-                    }
-                    file.code = collapsed.join("\n");
+                let dirty = false;
+                // Always-on transforms
+                dirty = stripInternalJSDocTags(file.luaAst) || dirty;
+                dirty = stripEmptyModuleBoilerplate(file.luaAst, file.sourceFiles) || dirty;
+                // Opt-in transforms
+                if (opt.defaultParams)
+                    dirty = collapseDefaultParamNilChecks(file.luaAst) || dirty;
+                if (opt.shortenTemps) {
+                    dirty = shortenTempNames(file.luaAst) || dirty;
+                    dirty = collapseFieldAccesses(file.luaAst) || dirty;
                 }
-            }
-            // Merge forward-declared `local x` with its first `x = value` assignment.
-            // Only inlines when there are no references to x between declaration and assignment.
-            if (opt.inlineLocals) {
-                for (const file of result) {
-                    const lines = file.code.split("\n");
-                    const removedLines = new Set();
-                    for (let i = 0; i < lines.length; i++) {
-                        if (removedLines.has(i))
-                            continue;
-                        // Match forward declaration: `local var1, var2, ...` with no `=`
-                        const declMatch = lines[i].match(/^(\s*)local\s+((?:\w+(?:,\s*)*)*\w+)\s*$/);
-                        if (!declMatch)
-                            continue;
-                        const indent = declMatch[1];
-                        const escapedIndent = escapeRegex(indent);
-                        const vars = declMatch[2]
-                            .split(/,\s*/)
-                            .map((v) => v.trim())
-                            .filter(Boolean);
-                        const inlined = new Set();
-                        for (const varName of vars) {
-                            // Hoist regex compilation outside inner loop; negative lookahead
-                            // rejects multi-variable assignment lines like `a, b = fn()`
-                            const assignRe = new RegExp(`^${escapedIndent}${varName}(?!\\s*,)\\s*=\\s*(.+)$`);
-                            const refRe = new RegExp(`\\b${varName}\\b`);
-                            for (let j = i + 1; j < lines.length; j++) {
-                                if (removedLines.has(j))
-                                    continue;
-                                // Check for bare single-variable assignment at same indentation
-                                const assignMatch = lines[j].match(assignRe);
-                                if (assignMatch) {
-                                    // Don't inline if RHS references the variable (self-referencing)
-                                    if (refRe.test(assignMatch[1]))
-                                        break;
-                                    lines[j] = `${indent}local ${varName} = ${assignMatch[1]}`;
-                                    inlined.add(varName);
-                                    break;
-                                }
-                                // Reference to varName prevents inlining
-                                if (refRe.test(lines[j]))
-                                    break;
-                            }
-                        }
-                        if (inlined.size === 0)
-                            continue;
-                        const remaining = vars.filter((v) => !inlined.has(v));
-                        if (remaining.length === 0) {
-                            removedLines.add(i);
-                        }
-                        else {
-                            lines[i] = `${indent}local ${remaining.join(", ")}`;
-                        }
-                    }
-                    file.code = lines.filter((_, idx) => !removedLines.has(idx)).join("\n");
+                if (opt.inlineLocals)
+                    dirty = inlineForwardDeclarations(file.luaAst) || dirty;
+                // Re-print if AST was modified
+                if (dirty) {
+                    const printer = new tstl.LuaPrinter(emitHost, program, file.fileName);
+                    const printed = printer.print(file.luaAst);
+                    file.code = printed.code;
+                    file.sourceMap = printed.sourceMap;
+                    file.sourceMapNode = printed.sourceMapNode;
                 }
-            }
-        },
-        // Compound assignment runs in afterEmit so it applies after other plugins
-        // that may also post-process the Lua source in beforeEmit.
-        // `+=` is Luau-only syntax and would be garbled by Lua 5.1 parsers.
-        afterEmit(_program, _options, emitHost, result) {
-            if (!opt.compoundAssignment)
-                return;
-            for (const file of result) {
-                file.code = file.code.replace(/^(\s*)(\w+) = \2 (\/\/|\.\.|[+\-*/%^]) (\S+)(\s*(?:--.*)?)$/gm, "$1$2 $3= $4$5");
-                if (emitHost.writeFile) {
-                    emitHost.writeFile(file.outputPath, file.code, false);
+                // Compound assignment stays as regex (no Lua AST node for +=)
+                if (opt.compoundAssignment) {
+                    file.code = file.code.replace(/^(\s*)(\w+) = \2 (\/\/|\.\.|[+\-*/%^]) (\S+)(\s*(?:--.*)?)$/gm, "$1$2 $3= $4$5");
                 }
             }
         },

package/dist/lua-ast-walk.d.ts

@@ -0,0 +1,10 @@
+import * as lua from "typescript-to-lua";
+export type BlockVisitor = (statements: lua.Statement[]) => void;
+/** Walk all statement arrays in a File. Depth-first. */
+export declare function walkBlocks(file: lua.File, visitor: BlockVisitor): void;
+type IdentifierCallback = (id: lua.Identifier) => void;
+/** Walk all Identifier nodes in a File. Callback may mutate id.text. */
+export declare function walkIdentifiers(file: lua.File, cb: IdentifierCallback): void;
+/** Check if an expression tree contains an Identifier with the given name. */
+export declare function containsIdentifier(node: lua.Node, name: string): boolean;
+export {};

package/dist/lua-ast-walk.js

@@ -0,0 +1,422 @@
+import * as lua from "typescript-to-lua";
+function walkExpression(expr, blockVisitor) {
+    switch (expr.kind) {
+        case lua.SyntaxKind.StringLiteral:
+        case lua.SyntaxKind.NumericLiteral:
+        case lua.SyntaxKind.NilKeyword:
+        case lua.SyntaxKind.DotsKeyword:
+        case lua.SyntaxKind.ArgKeyword:
+        case lua.SyntaxKind.TrueKeyword:
+        case lua.SyntaxKind.FalseKeyword:
+        case lua.SyntaxKind.Identifier:
+            break;
+        case lua.SyntaxKind.BinaryExpression: {
+            const bin = expr;
+            walkExpression(bin.left, blockVisitor);
+            walkExpression(bin.right, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.UnaryExpression:
+            walkExpression(expr.operand, blockVisitor);
+            break;
+        case lua.SyntaxKind.ParenthesizedExpression:
+            walkExpression(expr.expression, blockVisitor);
+            break;
+        case lua.SyntaxKind.ConditionalExpression: {
+            const cond = expr;
+            walkExpression(cond.condition, blockVisitor);
+            walkExpression(cond.whenTrue, blockVisitor);
+            walkExpression(cond.whenFalse, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.CallExpression: {
+            const call = expr;
+            walkExpression(call.expression, blockVisitor);
+            for (const p of call.params)
+                walkExpression(p, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.MethodCallExpression: {
+            const mc = expr;
+            walkExpression(mc.prefixExpression, blockVisitor);
+            for (const p of mc.params)
+                walkExpression(p, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.TableIndexExpression: {
+            const ti = expr;
+            walkExpression(ti.table, blockVisitor);
+            walkExpression(ti.index, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.TableExpression:
+            for (const f of expr.fields) {
+                walkExpression(f.value, blockVisitor);
+                if (f.key)
+                    walkExpression(f.key, blockVisitor);
+            }
+            break;
+        case lua.SyntaxKind.FunctionExpression: {
+            const fn = expr;
+            walkBlock(fn.body, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.TableFieldExpression: {
+            const tf = expr;
+            walkExpression(tf.value, blockVisitor);
+            if (tf.key)
+                walkExpression(tf.key, blockVisitor);
+            break;
+        }
+    }
+}
+function walkStatement(stmt, blockVisitor) {
+    switch (stmt.kind) {
+        case lua.SyntaxKind.DoStatement:
+            walkBlock(stmt, blockVisitor);
+            break;
+        case lua.SyntaxKind.VariableDeclarationStatement: {
+            const vds = stmt;
+            if (vds.right) {
+                for (const r of vds.right)
+                    walkExpression(r, blockVisitor);
+            }
+            break;
+        }
+        case lua.SyntaxKind.AssignmentStatement: {
+            const as_ = stmt;
+            for (const l of as_.left)
+                walkExpression(l, blockVisitor);
+            for (const r of as_.right)
+                walkExpression(r, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.IfStatement: {
+            const is_ = stmt;
+            walkExpression(is_.condition, blockVisitor);
+            walkBlock(is_.ifBlock, blockVisitor);
+            if (is_.elseBlock) {
+                if (lua.isIfStatement(is_.elseBlock)) {
+                    walkStatement(is_.elseBlock, blockVisitor);
+                }
+                else {
+                    walkBlock(is_.elseBlock, blockVisitor);
+                }
+            }
+            break;
+        }
+        case lua.SyntaxKind.WhileStatement: {
+            const ws = stmt;
+            walkExpression(ws.condition, blockVisitor);
+            walkBlock(ws.body, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.RepeatStatement: {
+            const rs = stmt;
+            walkExpression(rs.condition, blockVisitor);
+            walkBlock(rs.body, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.ForStatement: {
+            const fs = stmt;
+            walkExpression(fs.controlVariableInitializer, blockVisitor);
+            walkExpression(fs.limitExpression, blockVisitor);
+            if (fs.stepExpression)
+                walkExpression(fs.stepExpression, blockVisitor);
+            walkBlock(fs.body, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.ForInStatement: {
+            const fis = stmt;
+            for (const e of fis.expressions)
+                walkExpression(e, blockVisitor);
+            walkBlock(fis.body, blockVisitor);
+            break;
+        }
+        case lua.SyntaxKind.ReturnStatement:
+            for (const e of stmt.expressions)
+                walkExpression(e, blockVisitor);
+            break;
+        case lua.SyntaxKind.ExpressionStatement:
+            walkExpression(stmt.expression, blockVisitor);
+            break;
+        case lua.SyntaxKind.GotoStatement:
+        case lua.SyntaxKind.LabelStatement:
+        case lua.SyntaxKind.BreakStatement:
+        case lua.SyntaxKind.ContinueStatement:
+            break;
+    }
+}
+function walkBlock(block, blockVisitor) {
+    blockVisitor(block.statements);
+    for (const stmt of block.statements) {
+        walkStatement(stmt, blockVisitor);
+    }
+}
+/** Walk all statement arrays in a File. Depth-first. */
+export function walkBlocks(file, visitor) {
+    walkBlock(file, visitor);
+}
+function walkExpressionIds(expr, cb) {
+    switch (expr.kind) {
+        case lua.SyntaxKind.Identifier:
+            cb(expr);
+            break;
+        case lua.SyntaxKind.StringLiteral:
+        case lua.SyntaxKind.NumericLiteral:
+        case lua.SyntaxKind.NilKeyword:
+        case lua.SyntaxKind.DotsKeyword:
+        case lua.SyntaxKind.ArgKeyword:
+        case lua.SyntaxKind.TrueKeyword:
+        case lua.SyntaxKind.FalseKeyword:
+            break;
+        case lua.SyntaxKind.BinaryExpression: {
+            const bin = expr;
+            walkExpressionIds(bin.left, cb);
+            walkExpressionIds(bin.right, cb);
+            break;
+        }
+        case lua.SyntaxKind.UnaryExpression:
+            walkExpressionIds(expr.operand, cb);
+            break;
+        case lua.SyntaxKind.ParenthesizedExpression:
+            walkExpressionIds(expr.expression, cb);
+            break;
+        case lua.SyntaxKind.ConditionalExpression: {
+            const cond = expr;
+            walkExpressionIds(cond.condition, cb);
+            walkExpressionIds(cond.whenTrue, cb);
+            walkExpressionIds(cond.whenFalse, cb);
+            break;
+        }
+        case lua.SyntaxKind.CallExpression: {
+            const call = expr;
+            walkExpressionIds(call.expression, cb);
+            for (const p of call.params)
+                walkExpressionIds(p, cb);
+            break;
+        }
+        case lua.SyntaxKind.MethodCallExpression: {
+            const mc = expr;
+            walkExpressionIds(mc.prefixExpression, cb);
+            walkExpressionIds(mc.name, cb);
+            for (const p of mc.params)
+                walkExpressionIds(p, cb);
+            break;
+        }
+        case lua.SyntaxKind.TableIndexExpression: {
+            const ti = expr;
+            walkExpressionIds(ti.table, cb);
+            walkExpressionIds(ti.index, cb);
+            break;
+        }
+        case lua.SyntaxKind.TableExpression:
+            for (const f of expr.fields) {
+                walkExpressionIds(f.value, cb);
+                if (f.key)
+                    walkExpressionIds(f.key, cb);
+            }
+            break;
+        case lua.SyntaxKind.FunctionExpression: {
+            const fn = expr;
+            if (fn.params) {
+                for (const p of fn.params)
+                    cb(p);
+            }
+            walkBlockIds(fn.body, cb);
+            break;
+        }
+        case lua.SyntaxKind.TableFieldExpression: {
+            const tf = expr;
+            walkExpressionIds(tf.value, cb);
+            if (tf.key)
+                walkExpressionIds(tf.key, cb);
+            break;
+        }
+    }
+}
+function walkStatementIds(stmt, cb) {
+    switch (stmt.kind) {
+        case lua.SyntaxKind.DoStatement:
+            walkBlockIds(stmt, cb);
+            break;
+        case lua.SyntaxKind.VariableDeclarationStatement: {
+            const vds = stmt;
+            for (const l of vds.left)
+                cb(l);
+            if (vds.right) {
+                for (const r of vds.right)
+                    walkExpressionIds(r, cb);
+            }
+            break;
+        }
+        case lua.SyntaxKind.AssignmentStatement: {
+            const as_ = stmt;
+            for (const l of as_.left)
+                walkExpressionIds(l, cb);
+            for (const r of as_.right)
+                walkExpressionIds(r, cb);
+            break;
+        }
+        case lua.SyntaxKind.IfStatement: {
+            const is_ = stmt;
+            walkExpressionIds(is_.condition, cb);
+            walkBlockIds(is_.ifBlock, cb);
+            if (is_.elseBlock) {
+                if (lua.isIfStatement(is_.elseBlock)) {
+                    walkStatementIds(is_.elseBlock, cb);
+                }
+                else {
+                    walkBlockIds(is_.elseBlock, cb);
+                }
+            }
+            break;
+        }
+        case lua.SyntaxKind.WhileStatement: {
+            const ws = stmt;
+            walkExpressionIds(ws.condition, cb);
+            walkBlockIds(ws.body, cb);
+            break;
+        }
+        case lua.SyntaxKind.RepeatStatement: {
+            const rs = stmt;
+            walkExpressionIds(rs.condition, cb);
+            walkBlockIds(rs.body, cb);
+            break;
+        }
+        case lua.SyntaxKind.ForStatement: {
+            const fs = stmt;
+            cb(fs.controlVariable);
+            walkExpressionIds(fs.controlVariableInitializer, cb);
+            walkExpressionIds(fs.limitExpression, cb);
+            if (fs.stepExpression)
+                walkExpressionIds(fs.stepExpression, cb);
+            walkBlockIds(fs.body, cb);
+            break;
+        }
+        case lua.SyntaxKind.ForInStatement: {
+            const fis = stmt;
+            for (const n of fis.names)
+                cb(n);
+            for (const e of fis.expressions)
+                walkExpressionIds(e, cb);
+            walkBlockIds(fis.body, cb);
+            break;
+        }
+        case lua.SyntaxKind.ReturnStatement:
+            for (const e of stmt.expressions)
+                walkExpressionIds(e, cb);
+            break;
+        case lua.SyntaxKind.ExpressionStatement:
+            walkExpressionIds(stmt.expression, cb);
+            break;
+        case lua.SyntaxKind.GotoStatement:
+        case lua.SyntaxKind.LabelStatement:
+        case lua.SyntaxKind.BreakStatement:
+        case lua.SyntaxKind.ContinueStatement:
+            break;
+    }
+}
+function walkBlockIds(block, cb) {
+    for (const stmt of block.statements) {
+        walkStatementIds(stmt, cb);
+    }
+}
+/** Walk all Identifier nodes in a File. Callback may mutate id.text. */
+export function walkIdentifiers(file, cb) {
+    walkBlockIds(file, cb);
+}
+/** Check if an expression tree contains an Identifier with the given name. */
+export function containsIdentifier(node, name) {
+    if (lua.isIdentifier(node)) {
+        return node.text === name;
+    }
+    // Walk expressions
+    if (lua.isBinaryExpression(node)) {
+        return containsIdentifier(node.left, name) || containsIdentifier(node.right, name);
+    }
+    if (lua.isUnaryExpression(node)) {
+        return containsIdentifier(node.operand, name);
+    }
+    if (lua.isParenthesizedExpression(node)) {
+        return containsIdentifier(node.expression, name);
+    }
+    if (lua.isConditionalExpression(node)) {
+        return (containsIdentifier(node.condition, name) ||
+            containsIdentifier(node.whenTrue, name) ||
+            containsIdentifier(node.whenFalse, name));
+    }
+    if (lua.isCallExpression(node)) {
+        return (containsIdentifier(node.expression, name) ||
+            node.params.some((p) => containsIdentifier(p, name)));
+    }
+    if (lua.isMethodCallExpression(node)) {
+        return (containsIdentifier(node.prefixExpression, name) ||
+            containsIdentifier(node.name, name) ||
+            node.params.some((p) => containsIdentifier(p, name)));
+    }
+    if (lua.isTableIndexExpression(node)) {
+        return containsIdentifier(node.table, name) || containsIdentifier(node.index, name);
+    }
+    if (lua.isTableExpression(node)) {
+        return node.fields.some((f) => containsIdentifier(f.value, name) || (f.key ? containsIdentifier(f.key, name) : false));
+    }
+    if (lua.isTableFieldExpression(node)) {
+        return (containsIdentifier(node.value, name) ||
+            (node.key ? containsIdentifier(node.key, name) : false));
+    }
+    if (lua.isFunctionExpression(node)) {
+        return node.body.statements.some((s) => containsIdentifierInStatement(s, name));
+    }
+    // Walk statements
+    if (lua.isDoStatement(node)) {
+        return node.statements.some((s) => containsIdentifierInStatement(s, name));
+    }
+    if (lua.isVariableDeclarationStatement(node)) {
+        return (node.left.some((l) => l.text === name) ||
+            (node.right?.some((r) => containsIdentifier(r, name)) ?? false));
+    }
+    if (lua.isAssignmentStatement(node)) {
+        return (node.left.some((l) => containsIdentifier(l, name)) ||
+            node.right.some((r) => containsIdentifier(r, name)));
+    }
+    if (lua.isIfStatement(node)) {
+        if (containsIdentifier(node.condition, name))
+            return true;
+        if (node.ifBlock.statements.some((s) => containsIdentifierInStatement(s, name)))
+            return true;
+        if (node.elseBlock) {
+            if (lua.isIfStatement(node.elseBlock))
+                return containsIdentifier(node.elseBlock, name);
+            return node.elseBlock.statements.some((s) => containsIdentifierInStatement(s, name));
+        }
+        return false;
+    }
+    if (lua.isReturnStatement(node)) {
+        return node.expressions.some((e) => containsIdentifier(e, name));
+    }
+    if (lua.isExpressionStatement(node)) {
+        return containsIdentifier(node.expression, name);
+    }
+    if (lua.isIterationStatement(node)) {
+        if (lua.isForStatement(node)) {
+            return (node.controlVariable.text === name ||
+                containsIdentifier(node.controlVariableInitializer, name) ||
+                containsIdentifier(node.limitExpression, name) ||
+                (node.stepExpression ? containsIdentifier(node.stepExpression, name) : false) ||
+                node.body.statements.some((s) => containsIdentifierInStatement(s, name)));
+        }
+        if (lua.isForInStatement(node)) {
+            return (node.names.some((n) => n.text === name) ||
+                node.expressions.some((e) => containsIdentifier(e, name)) ||
+                node.body.statements.some((s) => containsIdentifierInStatement(s, name)));
+        }
+        // While / Repeat
+        return (containsIdentifier(node.condition, name) ||
+            node.body.statements.some((s) => containsIdentifierInStatement(s, name)));
+    }
+    return false;
+}
+function containsIdentifierInStatement(stmt, name) {
+    return containsIdentifier(stmt, name);
+}

package/dist/lua-transforms.d.ts

@@ -0,0 +1,41 @@
+import * as ts from "typescript";
+import * as lua from "typescript-to-lua";
+/**
+ * Strip internal JSDoc tags from Lua comments (@indexArg, @indexReturn, @define).
+ * These are only consumed by the plugin at transpile time.
+ *
+ * TSTL generates JSDoc as flat string arrays in leadingComments:
+ *   ["-", " @define FLAG", " continuation line", " @indexArg 0"]
+ * Each string becomes a `-- <text>` line. When we find a tag line, we also
+ * remove its continuation lines (those starting with ` ` but not ` @`).
+ */
+export declare function stripInternalJSDocTags(file: lua.File): boolean;
+/**
+ * Strip empty module boilerplate from files without explicit exports.
+ * `moduleDetection: "force"` causes TSTL to wrap every file as a module;
+ * standalone SLua scripts don't need the ____exports wrapper.
+ */
+export declare function stripEmptyModuleBoilerplate(file: lua.File, sourceFiles: readonly ts.SourceFile[] | undefined): boolean;
+/**
+ * Collapse default-parameter nil-checks into `x = x or <literal>`.
+ * Matches: if x == nil then x = <literal> end
+ * Safe for strings and numbers (both truthy in Lua); the TS source only
+ * generates these for string/number defaults.
+ */
+export declare function collapseDefaultParamNilChecks(file: lua.File): boolean;
+/**
+ * Shorten TSTL destructuring temp names: ____*_result_* -> _rN.
+ * Two-pass: collect unique names in order, then rename all identifiers.
+ */
+export declare function shortenTempNames(file: lua.File): boolean;
+/**
+ * Collapse consecutive field accesses from the same shortened temp into
+ * multi-assignment: `local a = _r0.x; local b = _r0.y` -> `local a, b = _r0.x, _r0.y`.
+ * Only collapses when the base matches `_r\d+` (shortened temps).
+ */
+export declare function collapseFieldAccesses(file: lua.File): boolean;
+/**
+ * Merge forward-declared `local x` with its first `x = value` assignment.
+ * Only inlines when there are no references to x between declaration and assignment.
+ */
+export declare function inlineForwardDeclarations(file: lua.File): boolean;

package/dist/lua-transforms.js

@@ -0,0 +1,302 @@
+import * as ts from "typescript";
+import * as lua from "typescript-to-lua";
+import { walkBlocks, walkIdentifiers, containsIdentifier } from "./lua-ast-walk.js";
+const JSDOC_TAG_RE = /@(?:index(?:Arg|Return)|define)\b/;
+/**
+ * Strip internal JSDoc tags from Lua comments (@indexArg, @indexReturn, @define).
+ * These are only consumed by the plugin at transpile time.
+ *
+ * TSTL generates JSDoc as flat string arrays in leadingComments:
+ *   ["-", " @define FLAG", " continuation line", " @indexArg 0"]
+ * Each string becomes a `-- <text>` line. When we find a tag line, we also
+ * remove its continuation lines (those starting with ` ` but not ` @`).
+ */
+export function stripInternalJSDocTags(file) {
+    let changed = false;
+    walkBlocks(file, (statements) => {
+        for (const stmt of statements) {
+            if (!stmt.leadingComments || stmt.leadingComments.length === 0)
+                continue;
+            const filtered = [];
+            let skip = false;
+            for (const comment of stmt.leadingComments) {
+                if (typeof comment === "string") {
+                    if (JSDOC_TAG_RE.test(comment)) {
+                        // Tag line, skip it and subsequent continuation lines
+                        skip = true;
+                        continue;
+                    }
+                    if (skip) {
+                        // Continuation line: starts with space but not with ` @tag`
+                        if (comment.startsWith(" ") && !comment.match(/^ @\w/)) {
+                            continue;
+                        }
+                        // Not a continuation, stop skipping
+                        skip = false;
+                    }
+                    filtered.push(comment);
+                }
+                else {
+                    // Block comment (string[]), strip if any line contains the tag
+                    skip = false;
+                    if (comment.some((line) => JSDOC_TAG_RE.test(line))) {
+                        continue;
+                    }
+                    filtered.push(comment);
+                }
+            }
+            // If only the JSDoc opener "-" remains, remove it too
+            if (filtered.length === 1 && filtered[0] === "-") {
+                filtered.length = 0;
+            }
+            if (filtered.length !== stmt.leadingComments.length) {
+                stmt.leadingComments = filtered.length > 0 ? filtered : undefined;
+                changed = true;
+            }
+        }
+    });
+    return changed;
+}
+/**
+ * Strip empty module boilerplate from files without explicit exports.
+ * `moduleDetection: "force"` causes TSTL to wrap every file as a module;
+ * standalone SLua scripts don't need the ____exports wrapper.
+ */
+export function stripEmptyModuleBoilerplate(file, sourceFiles) {
+    const stmts = file.statements;
+    if (stmts.length < 2)
+        return false;
+    // Find `local ____exports = {}` at top level
+    const declIdx = stmts.findIndex((s) => lua.isVariableDeclarationStatement(s) &&
+        s.left.length === 1 &&
+        s.left[0].text === "____exports" &&
+        s.right &&
+        s.right.length === 1 &&
+        lua.isTableExpression(s.right[0]) &&
+        s.right[0].fields.length === 0);
+    if (declIdx === -1)
+        return false;
+    // Find `return ____exports` at end
+    const last = stmts[stmts.length - 1];
+    if (!lua.isReturnStatement(last) ||
+        last.expressions.length !== 1 ||
+        !lua.isIdentifier(last.expressions[0]) ||
+        last.expressions[0].text !== "____exports") {
+        return false;
+    }
+    // Check TS source files for explicit exports
+    const hasExplicitExports = sourceFiles?.some((sf) => sf.statements.some((s) => ts.isExportDeclaration(s) ||
+        ts.isExportAssignment(s) ||
+        (ts.canHaveModifiers(s) &&
+            ts.getModifiers(s)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))));
+    if (hasExplicitExports)
+        return false;
+    // Remove both: the decl and the return
+    stmts.splice(stmts.length - 1, 1); // remove return first (higher index)
+    stmts.splice(declIdx, 1); // then remove decl
+    return true;
+}
+/**
+ * Collapse default-parameter nil-checks into `x = x or <literal>`.
+ * Matches: if x == nil then x = <literal> end
+ * Safe for strings and numbers (both truthy in Lua); the TS source only
+ * generates these for string/number defaults.
+ */
+export function collapseDefaultParamNilChecks(file) {
+    let changed = false;
+    walkBlocks(file, (statements) => {
+        for (let i = 0; i < statements.length; i++) {
+            const stmt = statements[i];
+            if (!lua.isIfStatement(stmt))
+                continue;
+            if (stmt.elseBlock)
+                continue;
+            // condition: x == nil
+            if (!lua.isBinaryExpression(stmt.condition))
+                continue;
+            if (stmt.condition.operator !== lua.SyntaxKind.EqualityOperator)
+                continue;
+            if (!lua.isIdentifier(stmt.condition.left))
+                continue;
+            if (!lua.isNilLiteral(stmt.condition.right))
+                continue;
+            const paramName = stmt.condition.left;
+            // ifBlock has exactly 1 statement: x = <literal>
+            if (stmt.ifBlock.statements.length !== 1)
+                continue;
+            const inner = stmt.ifBlock.statements[0];
+            if (!lua.isAssignmentStatement(inner))
+                continue;
+            if (inner.left.length !== 1 || inner.right.length !== 1)
+                continue;
+            const assignTarget = inner.left[0];
+            if (!lua.isIdentifier(assignTarget))
+                continue;
+            if (assignTarget.text !== paramName.text)
+                continue;
+            const literal = inner.right[0];
+            if (!lua.isStringLiteral(literal) && !lua.isNumericLiteral(literal)) {
+                continue;
+            }
+            // Replace with: x = x or <literal>
+            const orExpr = lua.createBinaryExpression(lua.cloneIdentifier(paramName), literal, lua.SyntaxKind.OrOperator);
+            const assignment = lua.createAssignmentStatement(lua.cloneIdentifier(paramName), orExpr);
+            // Preserve leading comments from the if statement
+            if (stmt.leadingComments) {
+                assignment.leadingComments = stmt.leadingComments;
+            }
+            statements[i] = assignment;
+            changed = true;
+        }
+    });
+    return changed;
+}
+/**
+ * Shorten TSTL destructuring temp names: ____*_result_* -> _rN.
+ * Two-pass: collect unique names in order, then rename all identifiers.
+ */
+export function shortenTempNames(file) {
+    const seen = new Map();
+    let counter = 0;
+    const tempRe = /^____\w+_result_\d+$/;
+    // Pass 1: collect unique temp names in order of first occurrence
+    walkIdentifiers(file, (id) => {
+        if (tempRe.test(id.text) && !seen.has(id.text)) {
+            seen.set(id.text, `_r${counter++}`);
+        }
+    });
+    if (seen.size === 0)
+        return false;
+    // Pass 2: rename all matching identifiers
+    walkIdentifiers(file, (id) => {
+        const short = seen.get(id.text);
+        if (short)
+            id.text = short;
+    });
+    return true;
+}
+/**
+ * Collapse consecutive field accesses from the same shortened temp into
+ * multi-assignment: `local a = _r0.x; local b = _r0.y` -> `local a, b = _r0.x, _r0.y`.
+ * Only collapses when the base matches `_r\d+` (shortened temps).
+ */
+export function collapseFieldAccesses(file) {
+    let changed = false;
+    const tempBaseRe = /^_r\d+$/;
+    walkBlocks(file, (statements) => {
+        let i = 0;
+        while (i < statements.length) {
+            const stmt = statements[i];
+            // Match: local <name> = <temp>.<field>
+            if (!lua.isVariableDeclarationStatement(stmt) ||
+                stmt.left.length !== 1 ||
+                !stmt.right ||
+                stmt.right.length !== 1 ||
+                !lua.isTableIndexExpression(stmt.right[0]) ||
+                !lua.isIdentifier(stmt.right[0].table) ||
+                !tempBaseRe.test(stmt.right[0].table.text)) {
+                i++;
+                continue;
+            }
+            const baseName = stmt.right[0].table.text;
+            // Look ahead for consecutive field accesses on the same base
+            const left = [...stmt.left];
+            const right = [...stmt.right];
+            let end = i + 1;
+            while (end < statements.length) {
+                const next = statements[end];
+                if (lua.isVariableDeclarationStatement(next) &&
+                    next.left.length === 1 &&
+                    next.right &&
+                    next.right.length === 1 &&
+                    lua.isTableIndexExpression(next.right[0]) &&
+                    lua.isIdentifier(next.right[0].table) &&
+                    next.right[0].table.text === baseName) {
+                    left.push(...next.left);
+                    right.push(...next.right);
+                    end++;
+                }
+                else {
+                    break;
+                }
+            }
+            if (end - i > 1) {
+                // Create merged multi-assignment
+                const merged = lua.createVariableDeclarationStatement(left, right);
+                if (stmt.leadingComments) {
+                    merged.leadingComments = stmt.leadingComments;
+                }
+                statements.splice(i, end - i, merged);
+                changed = true;
+            }
+            i++;
+        }
+    });
+    return changed;
+}
+/**
+ * Merge forward-declared `local x` with its first `x = value` assignment.
+ * Only inlines when there are no references to x between declaration and assignment.
+ */
+export function inlineForwardDeclarations(file) {
+    let changed = false;
+    walkBlocks(file, (statements) => {
+        for (let i = 0; i < statements.length; i++) {
+            const stmt = statements[i];
+            // Match forward declaration: `local var1, var2, ...` with no initializer
+            if (!lua.isVariableDeclarationStatement(stmt) || (stmt.right && stmt.right.length > 0)) {
+                continue;
+            }
+            const vars = stmt.left;
+            const inlined = new Set();
+            for (const varId of vars) {
+                const varName = varId.text;
+                // Scan forward for assignment to same identifier
+                for (let j = i + 1; j < statements.length; j++) {
+                    const candidate = statements[j];
+                    if (lua.isAssignmentStatement(candidate) &&
+                        candidate.left.length === 1 &&
+                        lua.isIdentifier(candidate.left[0]) &&
+                        candidate.left[0].text === varName &&
+                        candidate.right.length === 1) {
+                        // Don't inline if RHS references the variable (self-referencing)
+                        if (containsIdentifier(candidate.right[0], varName))
+                            break;
+                        // Don't inline multi-variable assignments like `a, b = fn()`
+                        // (already handled by the length check above)
+                        // Replace assignment with variable declaration
+                        const newDecl = lua.createVariableDeclarationStatement(lua.cloneIdentifier(candidate.left[0]), candidate.right[0]);
+                        if (candidate.leadingComments) {
+                            newDecl.leadingComments = candidate.leadingComments;
+                        }
+                        statements[j] = newDecl;
+                        inlined.add(varName);
+                        break;
+                    }
+                    // Reference to varName prevents inlining
+                    if (containsIdentifier(candidate, varName))
+                        break;
+                }
+            }
+            if (inlined.size === 0)
+                continue;
+            changed = true;
+            const remaining = vars.filter((v) => !inlined.has(v.text));
+            if (remaining.length === 0) {
+                // Remove the forward declaration entirely
+                statements.splice(i, 1);
+                i--; // re-check this index
+            }
+            else {
+                // Keep remaining vars in the forward declaration
+                statements[i] = lua.createVariableDeclarationStatement(remaining);
+                if (stmt.leadingComments) {
+                    ;
+                    statements[i].leadingComments =
+                        stmt.leadingComments;
+                }
+            }
+        }
+    });
+    return changed;
+}

package/dist/optimize.d.ts

@@ -15,6 +15,8 @@ export interface OptimizeFlags {
     inlineLocals?: boolean;
     /** Strip `tostring()` from number-typed template literal interpolations. */
     numericConcat?: boolean;
+    /** Collapse `if x == nil then x = <literal> end` to `x = x or <literal>`. */
+    defaultParams?: boolean;
 }
 export declare const ALL_OPTIMIZE: Required<OptimizeFlags>;
 /**

package/dist/optimize.js

@@ -9,6 +9,7 @@ export const ALL_OPTIMIZE = {
     shortenTemps: true,
     inlineLocals: true,
     numericConcat: true,
+    defaultParams: true,
 };
 /**
  * Count `arr.filter(cb)` calls and return a set of file names where inlining

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwigz/slua-tstl-plugin",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "TypeScriptToLua plugin for targeting Second Life's SLua runtime",
   "license": "MIT",
   "repository": {