@defold-typescript/transpiler 0.35.0 → 0.37.0

package/src/index.ts

@@ -1,9 +1,17 @@
+export type {
+  ClosureSite,
+  ClosureViolation,
+  ClosureViolationKind,
+  CompanionClosure,
+} from "./companion-closure";
+export { COMPANION_INTERNAL_FIELD, computeCompanionClosure } from "./companion-closure";
 export type { ComponentAnimationIndex } from "./component-animation-index";
 export {
   buildComponentAnimationIndex,
   componentIdOfSameObjectAddress,
 } from "./component-animation-index";
 export { buildConfigKeyIndex, readGameProjectSetting } from "./config-key-index";
+export { findEmittedRequires, LUALIB_REQUIRE_NAME } from "./emitted-requires";
 export type { GuiFlipbookIndex } from "./gui-flipbook-index";
 export { buildGuiFlipbookIndex } from "./gui-flipbook-index";
 export type { GuiNodeIndex } from "./gui-node-index";
@@ -34,11 +42,14 @@ export {
   computeOutputRel,
   DEFAULT_INCLUDE,
   parseBuildConfig,
+  projectRelativeBase,
+  requirePathForRel,
   SCRIPT_SUFFIX_BY_KIND,
   stripIncludeBase,
 } from "./output-paths";
 export { getProgramDiagnostics } from "./program-diagnostics";
 export { isDefignoredPath, SCAFFOLDED_DEFIGNORE_LINES } from "./project-resources";
+export { rewriteEmittedRequires } from "./require-rewrite";
 export { buildSceneAddressDeclaration } from "./scene-address-declaration";
 export type { SceneCollectionRoles, SceneCollectionRolesInput } from "./scene-collection-roles";
 export { buildSceneCollectionRoles } from "./scene-collection-roles";
@@ -75,6 +86,7 @@ export type { SceneMessage } from "./scene-text-format";
 export { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
 export type { TranspileSession } from "./session";
 export { createTranspileSession } from "./session";
+export { TIMERS_REQUIRE_NAME } from "./timers-runtime";
 export type {
   TranspileDiagnostic,
   TranspileProjectInput,

package/src/lifecycle-erasure.ts

@@ -35,7 +35,7 @@ const FACTORY_SPECIFIERS = new Set([
   `${FACTORY_MODULE}/render-script`,
 ]);
 
-function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+export function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
   let symbol = checker.getSymbolAtLocation(callee);
   if (symbol === undefined) {
     return false;

package/src/output-paths.ts

@@ -46,6 +46,30 @@ export function stripIncludeBase(pattern: string): string {
   return lastSlash === -1 ? "" : upToWildcard.slice(0, lastSlash + 1);
 }
 
+// A root is a folder inside the project a tool can safely speak for, so a
+// pattern that resolves to the project root, escapes `cwd`, or is absolute in
+// any spelling yields nothing. Escape is the normalized `..` *segment*, not a
+// two-period prefix: `..local` is an ordinary folder name. Absoluteness is
+// decided by string shape, never by `path.isAbsolute`, which answers for the
+// host OS and would wave a Windows drive or UNC path through on a POSIX runner.
+const ABSOLUTE_SPELLING_RE = /^(\/|\\\\|[A-Za-z]:[\\/])/;
+
+// The folder an include pattern speaks for, as a project-relative posix base
+// (`""` for the project root itself), or `undefined` when the pattern reaches
+// outside the project. The scaffold-rule roots, the starter target and the
+// debug launch derivation all answer "which project folder does this pattern
+// speak for" here, so the three cannot drift.
+export function projectRelativeBase(pattern: string): string | undefined {
+  if (ABSOLUTE_SPELLING_RE.test(pattern)) {
+    return undefined;
+  }
+  const base = path.posix.normalize(stripIncludeBase(pattern.split("\\").join("/")));
+  if (base === ".." || base.startsWith("../")) {
+    return undefined;
+  }
+  return base === "." || base === "./" ? "" : base;
+}
+
 function relUnderOutDir(rel: string, config: BuildConfig): string {
   const { outDir, include } = config;
   if (outDir === undefined || outDir === "" || outDir === ".") {
@@ -60,6 +84,26 @@ function relUnderOutDir(rel: string, config: BuildConfig): string {
   return path.posix.join(outDir, relUnderBase);
 }
 
+/**
+ * The `require` path Lua reaches a rel by, mirroring the segment math TSTL
+ * applies when it emits one: the extension comes off the last segment, then
+ * every remaining `.` becomes `_` *within* a segment, because Lua reads a dot as
+ * a path separator and `src/foo.bar.lua` would otherwise be unreachable as
+ * `require("src.foo.bar")`. Both sides of the resolution check key through this,
+ * so a require and the output meant to satisfy it cannot be spelled differently.
+ */
+export function requirePathForRel(rel: string): string {
+  const segments = rel
+    .split("/")
+    .filter((segment) => segment !== "" && segment !== "." && segment !== "..");
+  const last = segments.length - 1;
+  const lastSegment = segments[last];
+  if (lastSegment !== undefined) {
+    segments[last] = lastSegment.replace(/\.[^.]*$/, "");
+  }
+  return segments.map((segment) => segment.replace(/\./g, "_")).join(".");
+}
+
 export function computeOutputRel(rel: string, config: BuildConfig, kind: SourceOutputKind): string {
   const baseRel = relUnderOutDir(rel, config);
   if (kind === "module") {

package/src/require-rewrite.ts

@@ -0,0 +1,36 @@
+import { scanEmittedRequires } from "./lua-require-scan";
+
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Repoint every code-position `require` whose module path `rewrites` maps, and
+ * leave the chunk byte-identical everywhere else.
+ *
+ * Built in one pass over the spans the shared scanner reports rather than by
+ * iterated replacement: a chunk is rewritten against the map it was scanned
+ * with, so a mapped value that is itself a key is never re-entered, and two
+ * paths sharing a prefix cannot bleed into each other. The generated runtimes
+ * are rewritten like any other require — unlike the resolution check, which
+ * exempts them, the rewriter has to move them when the build writes them under
+ * an `outDir`.
+ */
+export function rewriteEmittedRequires(lua: string, rewrites: ReadonlyMap<string, string>): string {
+  if (rewrites.size === 0) {
+    return lua;
+  }
+
+  let out = "";
+  let cursor = 0;
+  for (const { path, start, end } of scanEmittedRequires(lua)) {
+    const mapped = rewrites.get(path);
+    if (mapped === undefined) {
+      continue;
+    }
+    out += lua.slice(cursor, start) + quote(mapped);
+    cursor = end;
+  }
+
+  return cursor === 0 ? lua : out + lua.slice(cursor);
+}

package/src/session.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
+import { type CompanionEmitter, createCompanionEmitPlugin } from "./companion-emit";
 import { editorScriptErasurePlugin } from "./editor-script-erasure";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
@@ -18,28 +19,34 @@ export interface TranspileSession {
 
 const requireFromHere = createRequire(import.meta.url);
 
-const COMPILER_OPTIONS: tstl.CompilerOptions = {
-  luaTarget: tstl.LuaTarget.Lua51,
-  sourceMap: true,
-  // Already-resolved CompilerOptions, so the value is the lib file name, not the
-  // tsconfig spelling "ES2022". Drops the default `lib.dom`, whose `declare var
-  // window` shadows Defold's `window` namespace. Keep in lockstep with transpile.ts.
-  lib: ["lib.es2022.d.ts"],
-  // Don't cross-check the seeded ambient .d.ts surface against itself; only user
-  // files matter (mirrors transpileProject and the editor's skipLibCheck).
-  skipLibCheck: true,
-  // Defold scripts are not OO: free helper functions never receive a context,
-  // so suppress TSTL's implicit `self` parameter and the `_G` call-site filler.
-  noImplicitSelf: true,
-  luaPlugins: [
-    { plugin: lifecycleErasurePlugin },
-    { plugin: editorScriptErasurePlugin },
-    { plugin: messageGuardLoweringPlugin },
-    { plugin: windowEventGuardLoweringPlugin },
-    { plugin: messageDispatchLoweringPlugin },
-    { plugin: timersLoweringPlugin },
-  ],
-};
+// A function rather than a const because the companion emitter carries the
+// chunks of one transpile: a shared instance would hand an editor rebuild the
+// companions of the rebuild before it. Keep in lockstep with transpile.ts.
+function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions {
+  return {
+    luaTarget: tstl.LuaTarget.Lua51,
+    sourceMap: true,
+    // Already-resolved CompilerOptions, so the value is the lib file name, not the
+    // tsconfig spelling "ES2022". Drops the default `lib.dom`, whose `declare var
+    // window` shadows Defold's `window` namespace.
+    lib: ["lib.es2022.d.ts"],
+    // Don't cross-check the seeded ambient .d.ts surface against itself; only user
+    // files matter (mirrors transpileProject and the editor's skipLibCheck).
+    skipLibCheck: true,
+    // Defold scripts are not OO: free helper functions never receive a context,
+    // so suppress TSTL's implicit `self` parameter and the `_G` call-site filler.
+    noImplicitSelf: true,
+    luaPlugins: [
+      { plugin: lifecycleErasurePlugin },
+      { plugin: editorScriptErasurePlugin },
+      { plugin: messageGuardLoweringPlugin },
+      { plugin: windowEventGuardLoweringPlugin },
+      { plugin: messageDispatchLoweringPlugin },
+      { plugin: timersLoweringPlugin },
+      { plugin: companionEmit.plugin },
+    ],
+  };
+}
 
 function normalizeSlashes(p: string): string {
   return p.replace(/\\/g, "/");
@@ -151,7 +158,8 @@ export function createTranspileSession(): TranspileSession {
     const userKeys = new Set(userFiles.keys());
     const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
 
-    program = ts.createProgram(rootNames, COMPILER_OPTIONS, host, program);
+    const companionEmit = createCompanionEmitPlugin();
+    program = ts.createProgram(rootNames, compilerOptions(companionEmit), host, program);
 
     const preEmitDiagnostics = ts.getPreEmitDiagnostics(program);
     const collector = createOutputCollector();
@@ -163,7 +171,7 @@ export function createTranspileSession(): TranspileSession {
       ...ts.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics]),
     ];
 
-    return collectOutputs(collector.files, diagnostics, userKeys);
+    return collectOutputs(collector.files, diagnostics, userKeys, companionEmit.companions);
   }
 
   return {

package/src/timers-lowering.ts

@@ -1,5 +1,5 @@
 import * as ts from "typescript";
-import type { Plugin } from "typescript-to-lua";
+import { LuaLibFeature, type Plugin } from "typescript-to-lua";
 import { TIMERS_MODULE_SPECIFIER, TIMERS_REQUIRE_NAME } from "./timers-runtime";
 
 function isTimersSpecifier(node: ts.Expression): node is ts.StringLiteral {
@@ -30,6 +30,15 @@ export const timersLoweringPlugin: Plugin = {
       if (!isTimersSpecifier(node.moduleSpecifier)) {
         return context.superTransformStatements(node);
       }
+      // This chunk reads neither helper, but the hand-authored runtime the
+      // rewritten require loads does, and TSTL synthesizes `lualib_bundle.lua`
+      // only for features registered here — it never sees the runtime source.
+      // Registering both (rather than only `Promise`, which recursively pulls
+      // `New`) also keeps the emitted prelude complete under
+      // `luaLibImport: "require-minimal"`, where the bundle is rebuilt from a
+      // scan of the emitted chunks' `local X = ____lualib.X` lines.
+      context.usedLuaLibFeatures.add(LuaLibFeature.Promise);
+      context.usedLuaLibFeatures.add(LuaLibFeature.New);
       const rewritten = ts.factory.updateImportDeclaration(
         node,
         node.modifiers,

package/src/timers-runtime.ts

@@ -7,9 +7,10 @@ export const TIMERS_REQUIRE_NAME = "defold_typescript_timers";
 
 // Hand-authored runtime Lua. Unlike `defineScript` (which `lifecycle-erasure`
 // removes), these wrappers have real behavior, so the Lua must reach the Defold
-// project. `__TS__Promise`/`__TS__New` come from the lualib bundle the build
-// already writes alongside this file; `wait` resolves its promise from inside
-// the `timer.delay` callback, the only thing that advances it (no event loop).
+// project. `__TS__Promise`/`__TS__New` come from the lualib bundle that exists
+// because the import lowering registers those two features when it rewrites the
+// polyfill specifier; `wait` resolves its promise from inside the `timer.delay`
+// callback, the only thing that advances it (no event loop).
 export const TIMERS_RUNTIME = `local ____lualib = require("lualib_bundle")
 local __TS__Promise = ____lualib.__TS__Promise
 local __TS__New = ____lualib.__TS__New

package/src/transpile.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import type * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
+import { createCompanionEmitPlugin } from "./companion-emit";
 import { editorScriptErasurePlugin } from "./editor-script-erasure";
 import {
   findDirectGoPropertyCalls,
@@ -43,10 +44,17 @@ export interface TranspileProjectResult {
   readonly lua: Readonly<Record<string, string>>;
   readonly sourceMaps: Readonly<Record<string, string>>;
   readonly diagnostics: readonly TranspileDiagnostic[];
-  // TSTL synthesizes this bundle (no user source) whenever a lualib feature
-  // (`Object.keys`, spread, `__TS__TypeOf`, ...) is used; the emitted
-  // `require("lualib_bundle")` only resolves in Defold if the CLI writes it to
-  // the output root. Absent when no feature pulls it in.
+  // The companion module a script-kind source with runtime value exports emits
+  // alongside its script, keyed by the same source rel as `lua`. The script's
+  // own chunk requires it at the module-kind output path, so the CLI must write
+  // it there. Absent for a source that emits a single chunk.
+  readonly companions?: Readonly<Record<string, string>>;
+  // TSTL synthesizes this bundle (no user source) whenever a lualib feature is
+  // registered — either by a user source using one (`Object.keys`, spread,
+  // `__TS__TypeOf`, ...) or by the timers import lowering, whose generated
+  // runtime requires the bundle. The emitted `require("lualib_bundle")` only
+  // resolves in Defold if the CLI writes it to the output root. Absent when
+  // neither trigger fires.
   readonly lualib?: string;
   // Hand-authored runtime Lua for the `@defold-typescript/types/timers`
   // polyfills (`setTimeout`/`wait`/...). Unlike `defineScript`, the import is
@@ -215,9 +223,11 @@ export function collectOutputs(
   transpiledFiles: readonly CollectableFile[],
   diagnostics: readonly ts.Diagnostic[],
   userKeys: ReadonlySet<string>,
+  emittedCompanions: ReadonlyMap<string, string> = new Map(),
 ): TranspileProjectResult {
   const lua: Record<string, string> = {};
   const sourceMaps: Record<string, string> = {};
+  const companions: Record<string, string> = {};
   let lualib: string | undefined;
   for (const file of transpiledFiles) {
     if (isLualibBundle(file) && typeof file.lua === "string") {
@@ -232,6 +242,10 @@ export function collectOutputs(
     if (typeof file.luaSourceMap === "string") {
       sourceMaps[userSource.fileName] = file.luaSourceMap;
     }
+    const companion = emittedCompanions.get(userSource.fileName);
+    if (companion !== undefined) {
+      companions[userSource.fileName] = companion;
+    }
   }
 
   const collectedDiagnostics: TranspileDiagnostic[] = diagnostics.map((d) => {
@@ -276,6 +290,7 @@ export function collectOutputs(
     lua,
     sourceMaps,
     diagnostics: collectedDiagnostics,
+    ...(Object.keys(companions).length > 0 ? { companions } : {}),
     ...(lualib !== undefined ? { lualib } : {}),
     ...(timersImported ? { timersRuntime: TIMERS_RUNTIME } : {}),
   };
@@ -284,6 +299,7 @@ export function collectOutputs(
 export function transpileProject(input: TranspileProjectInput): TranspileProjectResult {
   const userKeys = new Set(Object.keys(input.files));
   const merged: Record<string, string> = { ...AMBIENT_FILES, ...input.files };
+  const companionEmit = createCompanionEmitPlugin();
 
   const result = tstl.transpileVirtualProject(merged, {
     luaTarget: tstl.LuaTarget.Lua51,
@@ -305,10 +321,16 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: companionEmit.plugin },
     ],
   });
 
-  return collectOutputs(result.transpiledFiles, result.diagnostics, userKeys);
+  return collectOutputs(
+    result.transpiledFiles,
+    result.diagnostics,
+    userKeys,
+    companionEmit.companions,
+  );
 }
 
 export function transpile(source: string): TranspileResult {