@defold-typescript/transpiler 0.43.0 → 0.44.0

package/dist/hsm-builtin.d.ts

@@ -1,6 +1,7 @@
-import type { Plugin } from "typescript-to-lua";
+import { type Plugin } from "typescript-to-lua";
 export declare const HSM_MODULE_SPECIFIER = "@defold-typescript/types/hsm";
 export declare const HSM_REQUIRE_ROOT = "defold_typescript_hsm";
+export declare const HSM_LUALIB_MODULES: ReadonlySet<string>;
 export interface HsmModule {
     /** The source file's basename without `.ts`. */
     readonly name: string;

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { buildGuiFlipbookIndex } from "./gui-flipbook-index";
 export type { GuiNodeIndex } from "./gui-node-index";
 export { buildGuiNodeIndex, guiScriptResourceOf, guiScriptResourcesOf, } from "./gui-node-index";
 export type { HsmModule } from "./hsm-builtin";
-export { HSM_MODULE_SPECIFIER, HSM_REQUIRE_ROOT, hsmModules, hsmRequireName, hsmSourceFiles, resolveHsmSourceDir, } from "./hsm-builtin";
+export { HSM_MODULE_SPECIFIER, HSM_REQUIRE_ROOT, hsmModules, hsmRequireName, hsmSourceFiles, requireHsmSourceDir, resolveHsmSourceDir, } from "./hsm-builtin";
 export { buildInputActionIndex } from "./input-action-index";
 export type { ExtensionDependency, LibraryIncludedEntries, LibrarySceneDocument, LibrarySceneDocuments, LibrarySharedEntry, } from "./library-dependencies";
 export { archiveWrapperOf, isContainedResourcePath, LIBRARY_DEPENDENCY_ROOT, libraryIncludedEntries, readGameProjectDependencies, readLibrarySceneDocuments, } from "./library-dependencies";

package/dist/index.js

@@ -1388,6 +1388,7 @@ import { existsSync, readdirSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as ts4 from "typescript";
+import { LuaLibFeature } from "typescript-to-lua";
 
 // src/lua-require-scan.ts
 var PLACEHOLDER = "\x00";
@@ -1485,6 +1486,7 @@ function scanEmittedRequires(lua) {
 // src/hsm-builtin.ts
 var HSM_MODULE_SPECIFIER = "@defold-typescript/types/hsm";
 var HSM_REQUIRE_ROOT = "defold_typescript_hsm";
+var HSM_LUALIB_MODULES = new Set(["async"]);
 function hsmRequireName(name) {
   return `${HSM_REQUIRE_ROOT}.${name}`;
 }
@@ -1575,6 +1577,33 @@ function hsmClosure(chunks, compile) {
 function lowerSpecifier(module) {
   return ts4.factory.createStringLiteral(`@NoResolution:${module.requireName}`);
 }
+function loweredAnything(lowered) {
+  return Array.isArray(lowered) ? lowered.length > 0 : lowered !== undefined;
+}
+function importSurvivesElision(node, context) {
+  const clause = node.importClause;
+  if (clause === undefined) {
+    return true;
+  }
+  const { resolver } = context;
+  if (clause.name !== undefined && resolver.isReferencedAliasDeclaration(clause)) {
+    return true;
+  }
+  const bindings = clause.namedBindings;
+  if (bindings === undefined) {
+    return false;
+  }
+  if (ts4.isNamespaceImport(bindings)) {
+    return resolver.isReferencedAliasDeclaration(bindings);
+  }
+  return bindings.elements.some((element) => resolver.isReferencedAliasDeclaration(element));
+}
+function registerLualib(module, emitted, context) {
+  if (emitted && HSM_LUALIB_MODULES.has(module.name)) {
+    context.usedLuaLibFeatures.add(LuaLibFeature.Promise);
+    context.usedLuaLibFeatures.add(LuaLibFeature.New);
+  }
+}
 var hsmLoweringPlugin = {
   visitors: {
     [ts4.SyntaxKind.ImportDeclaration]: (node, context) => {
@@ -1582,6 +1611,7 @@ var hsmLoweringPlugin = {
       if (module === undefined) {
         return context.superTransformStatements(node);
       }
+      registerLualib(module, importSurvivesElision(node, context), context);
       return context.superTransformStatements(ts4.factory.updateImportDeclaration(node, node.modifiers, node.importClause, lowerSpecifier(module), node.attributes));
     },
     [ts4.SyntaxKind.ExportDeclaration]: (node, context) => {
@@ -1589,7 +1619,9 @@ var hsmLoweringPlugin = {
       if (module === undefined) {
         return context.superTransformStatements(node);
       }
-      return context.superTransformStatements(ts4.factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, lowerSpecifier(module), node.attributes));
+      const lowered = context.superTransformStatements(ts4.factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, lowerSpecifier(module), node.attributes));
+      registerLualib(module, loweredAnything(lowered), context);
+      return lowered;
     }
   }
 };
@@ -2239,7 +2271,7 @@ var messageGuardLoweringPlugin = {
 
 // src/timers-lowering.ts
 import * as ts7 from "typescript";
-import { LuaLibFeature } from "typescript-to-lua";
+import { LuaLibFeature as LuaLibFeature2 } from "typescript-to-lua";
 function isTimersSpecifier(node) {
   return ts7.isStringLiteral(node) && node.text === TIMERS_MODULE_SPECIFIER;
 }
@@ -2253,8 +2285,8 @@ var timersLoweringPlugin = {
       if (!isTimersSpecifier(node.moduleSpecifier)) {
         return context.superTransformStatements(node);
       }
-      context.usedLuaLibFeatures.add(LuaLibFeature.Promise);
-      context.usedLuaLibFeatures.add(LuaLibFeature.New);
+      context.usedLuaLibFeatures.add(LuaLibFeature2.Promise);
+      context.usedLuaLibFeatures.add(LuaLibFeature2.New);
       const rewritten = ts7.factory.updateImportDeclaration(node, node.modifiers, node.importClause, ts7.factory.createStringLiteral(TIMERS_REQUIRE_PATH), node.attributes);
       return context.superTransformStatements(rewritten);
     }
@@ -3650,6 +3682,9 @@ function transpileProject(input) {
   return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys, companionEmit.companions);
 }
 var compiledHsm;
+function requiresLualib(lua) {
+  return scanEmittedRequires(lua).some(({ path: requirePath }) => requirePath === "lualib_bundle");
+}
 function compileHsmModules() {
   if (compiledHsm !== undefined) {
     return compiledHsm;
@@ -3667,14 +3702,17 @@ function compileHsmModules() {
   const lua = {};
   for (const file of result.transpiledFiles) {
     if (isLualibBundle(file)) {
-      problems.push("the compiled Lua requires lualib_bundle");
       continue;
     }
     const source = file.sourceFiles.find((s) => nameByKey.has(s.fileName));
     const name = source === undefined ? undefined : nameByKey.get(source.fileName);
-    if (name !== undefined && typeof file.lua === "string") {
-      lua[name] = file.lua;
+    if (name === undefined || typeof file.lua !== "string") {
+      continue;
+    }
+    if (!HSM_LUALIB_MODULES.has(name) && requiresLualib(file.lua)) {
+      problems.push(`the compiled ${name} module requires lualib_bundle`);
     }
+    lua[name] = file.lua;
   }
   if (problems.length > 0) {
     throw new Error(`@defold-typescript/transpiler: the hsm library does not compile:
@@ -4282,6 +4320,7 @@ export {
   readLibrarySceneDocuments,
   readSceneDocuments,
   relativeAddressesFrom,
+  requireHsmSourceDir,
   requirePathForRel,
   resolveClassifiedSlotAtPosition,
   resolveHsmSourceDir,

package/dist/transpile.d.ts

@@ -38,7 +38,8 @@ export declare function transpileProject(input: TranspileProjectInput): Transpil
  * project gets always comes from the compiler that builds it. Each file sits at
  * `defold_typescript_hsm/<module>.ts`, so a require between modules is already
  * spelled the way the user's lowered imports are. Throws when the compile
- * reports anything or needs the lualib bundle, which hsm must never do.
+ * reports anything, or when a module outside `HSM_LUALIB_MODULES` needs the
+ * lualib bundle.
  */
 export declare function compileHsmModules(): Readonly<Record<string, string>>;
 export declare function transpile(source: string): TranspileResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,8 +35,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.43.0",
+    "@defold-typescript/types": "0.44.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
+    "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"
   }
 }

package/src/hsm-builtin.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as ts from "typescript";
-import type { Plugin } from "typescript-to-lua";
+import { LuaLibFeature, type Plugin, type TransformationContext } from "typescript-to-lua";
 import { scanEmittedRequires } from "./lua-require-scan";
 
 // `@defold-typescript/types/hsm` is the `index` module; every other module is a
@@ -12,6 +12,10 @@ import { scanEmittedRequires } from "./lua-require-scan";
 export const HSM_MODULE_SPECIFIER = "@defold-typescript/types/hsm";
 export const HSM_REQUIRE_ROOT = "defold_typescript_hsm";
 
+// The hsm modules whose Lua requires the lualib bundle. Every other module stays
+// plain Lua, so a program that imports none of these ships no bundle.
+export const HSM_LUALIB_MODULES: ReadonlySet<string> = new Set(["async"]);
+
 export interface HsmModule {
   /** The source file's basename without `.ts`. */
   readonly name: string;
@@ -152,12 +156,56 @@ export function hsmClosure(
 
 // Rewrite an hsm specifier to its flat require, the way the timers lowering
 // does: `@NoResolution:` keeps TSTL from looking for a Lua source behind the
-// `.d.ts` the import type-checks against. No lualib feature is registered,
-// because hsm compiles to plain Lua.
+// `.d.ts` the import type-checks against.
 function lowerSpecifier(module: HsmModule): ts.StringLiteral {
   return ts.factory.createStringLiteral(`@NoResolution:${module.requireName}`);
 }
 
+type Lowered = ReturnType<TransformationContext["superTransformStatements"]>;
+
+function loweredAnything(lowered: Lowered): boolean {
+  return Array.isArray(lowered) ? lowered.length > 0 : lowered !== undefined;
+}
+
+// The same resolver verdict TSTL's own import transform uses to decide which
+// bindings it requires, so the bundle and the emitted require cannot disagree.
+// Takes the original node: the resolver has no binding for a synthesized copy.
+function importSurvivesElision(
+  node: ts.ImportDeclaration,
+  context: TransformationContext,
+): boolean {
+  const clause = node.importClause;
+  if (clause === undefined) {
+    return true;
+  }
+  const { resolver } = context;
+  if (clause.name !== undefined && resolver.isReferencedAliasDeclaration(clause)) {
+    return true;
+  }
+  const bindings = clause.namedBindings;
+  if (bindings === undefined) {
+    return false;
+  }
+  if (ts.isNamespaceImport(bindings)) {
+    return resolver.isReferencedAliasDeclaration(bindings);
+  }
+  return bindings.elements.some((element) => resolver.isReferencedAliasDeclaration(element));
+}
+
+// TSTL writes `lualib_bundle.lua` only for features a user chunk registers; it
+// never sees the hsm module's own source, which the CLI writes beside the build.
+// An elided import (type-only, unused) registers nothing. The import visitor
+// passes the resolver's elision verdict, because TSTL's import transform always
+// returns nothing and queues its require on the scope instead; the export
+// visitor passes whether its lowered statements are non-empty, because TSTL's
+// export transform returns them.
+function registerLualib(module: HsmModule, emitted: boolean, context: TransformationContext): void {
+  if (emitted && HSM_LUALIB_MODULES.has(module.name)) {
+    context.usedLuaLibFeatures.add(LuaLibFeature.Promise);
+    context.usedLuaLibFeatures.add(LuaLibFeature.New);
+  }
+}
+
 export const hsmLoweringPlugin: Plugin = {
   visitors: {
     [ts.SyntaxKind.ImportDeclaration]: (node, context) => {
@@ -165,6 +213,7 @@ export const hsmLoweringPlugin: Plugin = {
       if (module === undefined) {
         return context.superTransformStatements(node);
       }
+      registerLualib(module, importSurvivesElision(node, context), context);
       return context.superTransformStatements(
         ts.factory.updateImportDeclaration(
           node,
@@ -180,7 +229,7 @@ export const hsmLoweringPlugin: Plugin = {
       if (module === undefined) {
         return context.superTransformStatements(node);
       }
-      return context.superTransformStatements(
+      const lowered = context.superTransformStatements(
         ts.factory.updateExportDeclaration(
           node,
           node.modifiers,
@@ -190,6 +239,8 @@ export const hsmLoweringPlugin: Plugin = {
           node.attributes,
         ),
       );
+      registerLualib(module, loweredAnything(lowered), context);
+      return lowered;
     },
   },
 };

package/src/index.ts

@@ -27,6 +27,7 @@ export {
   hsmModules,
   hsmRequireName,
   hsmSourceFiles,
+  requireHsmSourceDir,
   resolveHsmSourceDir,
 } from "./hsm-builtin";
 export { buildInputActionIndex } from "./input-action-index";

package/src/transpile.ts

@@ -10,6 +10,7 @@ import {
   GO_PROPERTY_DIRECT_CALL_MESSAGE,
 } from "./go-property-direct-call";
 import {
+  HSM_LUALIB_MODULES,
   HSM_REQUIRE_ROOT,
   hsmClosure,
   hsmLoweringPlugin,
@@ -17,6 +18,7 @@ import {
   requireHsmSourceDir,
 } from "./hsm-builtin";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
+import { scanEmittedRequires } from "./lua-require-scan";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
 import { importsTimersModule, timersLoweringPlugin } from "./timers-lowering";
@@ -371,13 +373,18 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
 
 let compiledHsm: Readonly<Record<string, string>> | undefined;
 
+function requiresLualib(lua: string): boolean {
+  return scanEmittedRequires(lua).some(({ path: requirePath }) => requirePath === "lualib_bundle");
+}
+
 /**
  * Every `hsm` module compiled to Lua, keyed by module name, once per process.
  * The source is the shipped TypeScript, never a prebuilt Lua copy, so the Lua a
  * project gets always comes from the compiler that builds it. Each file sits at
  * `defold_typescript_hsm/<module>.ts`, so a require between modules is already
  * spelled the way the user's lowered imports are. Throws when the compile
- * reports anything or needs the lualib bundle, which hsm must never do.
+ * reports anything, or when a module outside `HSM_LUALIB_MODULES` needs the
+ * lualib bundle.
  */
 export function compileHsmModules(): Readonly<Record<string, string>> {
   if (compiledHsm !== undefined) {
@@ -399,14 +406,17 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
   const lua: Record<string, string> = {};
   for (const file of result.transpiledFiles) {
     if (isLualibBundle(file)) {
-      problems.push("the compiled Lua requires lualib_bundle");
       continue;
     }
     const source = file.sourceFiles.find((s) => nameByKey.has(s.fileName));
     const name = source === undefined ? undefined : nameByKey.get(source.fileName);
-    if (name !== undefined && typeof file.lua === "string") {
-      lua[name] = file.lua;
+    if (name === undefined || typeof file.lua !== "string") {
+      continue;
+    }
+    if (!HSM_LUALIB_MODULES.has(name) && requiresLualib(file.lua)) {
+      problems.push(`the compiled ${name} module requires lualib_bundle`);
     }
+    lua[name] = file.lua;
   }
   if (problems.length > 0) {
     throw new Error(