@gwigz/slua-tstl-plugin 1.2.0 → 1.3.0

package/README.md

@@ -354,7 +354,10 @@ Safe for string and number defaults (both truthy in Lua). Not applied to `false`
 
 ## Keeping output small
 
-Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean:
+Some TypeScript patterns pull in large TSTL runtime helpers. Here are recommendations for keeping output lean.
+
+> [!TIP]
+> Install [`@gwigz/slua-oxlint-config`](../oxlint-config) to enforce these recommendations at lint time.
 
 ### Avoid `delete` on objects
 
@@ -444,3 +447,7 @@ const seen: Record<string, boolean> = {}
 ```bash
 bun run build
 ```
+
+## Documentation
+
+Full API reference and usage examples are available at [slua.gwigz.link/docs/slua](https://slua.gwigz.link/docs/slua).

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.2.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
+    }
   }
 }