@gwigz/slua-tstl-plugin 1.1.0 → 1.3.0

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/dist/shake-plugin.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "rollup";
+interface ResolverOptions {
+    paths: Record<string, string[]>;
+    baseUrl: string;
+}
+/**
+ * Rollup plugin that resolves tsconfig `paths` to .ts source files
+ * and strips types so rollup can parse them for tree-shaking analysis.
+ */
+export declare function createTsconfigResolverPlugin(options: ResolverOptions): Plugin;
+export {};

package/dist/shake-plugin.js

@@ -0,0 +1,64 @@
+import * as ts from "typescript";
+import { dirname, join } from "node:path";
+const STRIP_TYPES_OPTIONS = {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    verbatimModuleSyntax: false,
+};
+/**
+ * Rollup plugin that resolves tsconfig `paths` to .ts source files
+ * and strips types so rollup can parse them for tree-shaking analysis.
+ */
+export function createTsconfigResolverPlugin(options) {
+    const { paths, baseUrl } = options;
+    const matchers = Object.entries(paths)
+        .filter(([pattern]) => pattern.includes("*"))
+        .map(([pattern, substitutions]) => {
+        const starIndex = pattern.indexOf("*");
+        return {
+            prefix: pattern.substring(0, starIndex),
+            suffix: pattern.substring(starIndex + 1),
+            substitutions,
+        };
+    });
+    return {
+        name: "tsconfig-resolver",
+        resolveId(source, importer) {
+            for (const { prefix, suffix, substitutions } of matchers) {
+                if (source.startsWith(prefix) && source.endsWith(suffix)) {
+                    const wildcard = source.slice(prefix.length, source.length - suffix.length || undefined);
+                    for (const sub of substitutions) {
+                        const resolved = sub.replace("*", wildcard);
+                        const full = join(baseUrl, resolved);
+                        if (ts.sys.fileExists(full)) {
+                            return full;
+                        }
+                    }
+                }
+            }
+            if (importer &&
+                importer.endsWith(".ts") &&
+                (source.startsWith("./") || source.startsWith("../"))) {
+                const dir = dirname(importer);
+                const withExt = join(dir, `${source}.ts`);
+                if (ts.sys.fileExists(withExt))
+                    return withExt;
+                const asIndex = join(dir, source, "index.ts");
+                if (ts.sys.fileExists(asIndex))
+                    return asIndex;
+            }
+            return null;
+        },
+        load(id) {
+            if (!id.endsWith(".ts"))
+                return null;
+            const source = ts.sys.readFile(id);
+            if (source === undefined)
+                return null;
+            const result = ts.transpileModule(source, {
+                compilerOptions: STRIP_TYPES_OPTIONS,
+            });
+            return result.outputText;
+        },
+    };
+}

package/dist/shake-strip.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Remove exported declarations (and their unreferenced internal dependencies)
+ * from TypeScript source, keeping only the declarations whose names are in
+ * `survivingExports` plus anything they transitively reference.
+ *
+ * Returns the modified TypeScript source string.
+ */
+export declare function stripDeadExports(source: string, survivingExports: Set<string>): string;

package/dist/shake-strip.js

@@ -0,0 +1,88 @@
+import * as ts from "typescript";
+/**
+ * Remove exported declarations (and their unreferenced internal dependencies)
+ * from TypeScript source, keeping only the declarations whose names are in
+ * `survivingExports` plus anything they transitively reference.
+ *
+ * Returns the modified TypeScript source string.
+ */
+export function stripDeadExports(source, survivingExports) {
+    const sourceFile = ts.createSourceFile("module.ts", source, ts.ScriptTarget.Latest, true);
+    // 1. Map declaration names to their nodes
+    const declarations = new Map();
+    const stmtNames = new Map();
+    for (const stmt of sourceFile.statements) {
+        const names = getDeclaredNames(stmt);
+        stmtNames.set(stmt, names);
+        for (const name of names) {
+            declarations.set(name, stmt);
+        }
+    }
+    // 2. Build reference graph: which declarations reference which others
+    const references = new Map();
+    for (const [name, node] of declarations) {
+        const refs = new Set();
+        collectReferences(node, declarations, refs);
+        refs.delete(name); // Remove self-reference
+        references.set(name, refs);
+    }
+    // 3. Walk from surviving exports to find all reachable declarations
+    const reachable = new Set();
+    function markReachable(name) {
+        if (reachable.has(name))
+            return;
+        reachable.add(name);
+        const refs = references.get(name);
+        if (refs) {
+            for (const ref of refs)
+                markReachable(ref);
+        }
+    }
+    for (const name of survivingExports) {
+        if (declarations.has(name))
+            markReachable(name);
+    }
+    // 4. Transform: remove unreachable declarations
+    const transformer = () => {
+        return (sf) => {
+            const filtered = sf.statements.filter((stmt) => {
+                const names = stmtNames.get(stmt) ?? [];
+                if (names.length === 0)
+                    return true;
+                return names.some((n) => reachable.has(n));
+            });
+            return ts.factory.updateSourceFile(sf, filtered);
+        };
+    };
+    const result = ts.transform(sourceFile, [transformer]);
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    const printed = printer.printFile(result.transformed[0]);
+    result.dispose();
+    return printed;
+}
+function getDeclaredNames(node) {
+    if (ts.isFunctionDeclaration(node) && node.name) {
+        return [node.name.text];
+    }
+    if (ts.isVariableStatement(node)) {
+        return node.declarationList.declarations
+            .filter((d) => ts.isIdentifier(d.name))
+            .map((d) => d.name.text);
+    }
+    if (ts.isClassDeclaration(node) && node.name) {
+        return [node.name.text];
+    }
+    // Re-exports: export { spawn } or export { spawn } from "./internal/spawn"
+    if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+        return node.exportClause.elements.map((e) => e.name.text);
+    }
+    return [];
+}
+function collectReferences(node, declarations, refs) {
+    if (ts.isIdentifier(node)) {
+        if (declarations.has(node.text)) {
+            refs.add(node.text);
+        }
+    }
+    ts.forEachChild(node, (child) => collectReferences(child, declarations, refs));
+}

package/dist/shake.d.ts

@@ -0,0 +1,13 @@
+export interface ShakeOptions {
+    /** Entry file paths (same files you'd pass as luaBundleEntry). */
+    entry: string[];
+    /** Path to tsconfig.json (used to resolve module paths). */
+    tsconfig: string;
+}
+export interface ShakeResult {
+    /** All files to pass to TSTL (entry files + module files). */
+    files: string[];
+    /** Map of module file path to Set of surviving export names. */
+    survivingExports: Map<string, Set<string>>;
+}
+export declare function shakeModules(options: ShakeOptions): Promise<ShakeResult>;

package/dist/shake.js

@@ -0,0 +1,74 @@
+import * as ts from "typescript";
+import { resolve, dirname } from "node:path";
+import { createTsconfigResolverPlugin } from "./shake-plugin.js";
+function readTsconfigPaths(tsconfigPath) {
+    const absolute = resolve(tsconfigPath);
+    const configFile = ts.readConfigFile(absolute, ts.sys.readFile);
+    if (configFile.error) {
+        const msg = ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n");
+        throw new Error(`shakeModules: failed to read tsconfig at ${absolute}: ${msg}`);
+    }
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(absolute));
+    if (parsed.errors.length > 0) {
+        const msg = parsed.errors
+            .map((e) => ts.flattenDiagnosticMessageText(e.messageText, "\n"))
+            .join("\n");
+        throw new Error(`shakeModules: tsconfig errors in ${absolute}: ${msg}`);
+    }
+    return {
+        paths: parsed.options.paths ?? {},
+        baseUrl: parsed.options.baseUrl ?? dirname(absolute),
+    };
+}
+export async function shakeModules(options) {
+    let rollup;
+    try {
+        rollup = await import("rollup");
+    }
+    catch {
+        throw new Error("shakeModules requires rollup as a peer dependency. Install it with: bun add -d rollup");
+    }
+    const { paths, baseUrl } = readTsconfigPaths(options.tsconfig);
+    const resolverPlugin = createTsconfigResolverPlugin({ paths, baseUrl });
+    const resolvedModuleFiles = new Set();
+    const entryFiles = options.entry.map((e) => resolve(e));
+    const wrappedPlugin = {
+        name: "tsconfig-resolver-wrapper",
+        resolveId(source, importer) {
+            const result = resolverPlugin.resolveId.call(this, source, importer);
+            if (typeof result === "string") {
+                resolvedModuleFiles.add(result);
+                return result;
+            }
+            if (!importer)
+                return null;
+            return { id: source, external: true };
+        },
+        load(id) {
+            return resolverPlugin.load.call(this, id);
+        },
+    };
+    const bundle = await rollup.rollup({
+        input: entryFiles,
+        plugins: [wrappedPlugin],
+        treeshake: true,
+    });
+    const { output } = await bundle.generate({
+        format: "esm",
+        preserveModules: true,
+    });
+    await bundle.close();
+    const survivingExports = new Map();
+    for (const chunk of output) {
+        if (chunk.type !== "chunk" || !chunk.facadeModuleId)
+            continue;
+        if (resolvedModuleFiles.has(chunk.facadeModuleId)) {
+            survivingExports.set(chunk.facadeModuleId, new Set(chunk.exports));
+        }
+    }
+    const fileSet = new Set(entryFiles);
+    for (const moduleFile of resolvedModuleFiles) {
+        fileSet.add(moduleFile);
+    }
+    return { files: [...fileSet], survivingExports };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwigz/slua-tstl-plugin",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "TypeScriptToLua plugin for targeting Second Life's SLua runtime",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./shake": {
+      "types": "./dist/shake.d.ts",
+      "default": "./dist/shake.js"
     }
   },
   "publishConfig": {
@@ -28,10 +32,16 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@gwigz/slua-types": "workspace:^",
     "typescript-to-lua": "^1.33.0"
   },
   "peerDependencies": {
-    "@gwigz/slua-types": "^1.0.0",
+    "rollup": "^4.0.0",
     "typescript": "~5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "rollup": {
+      "optional": true
+    }
   }
 }