@defold-typescript/transpiler 0.53.0 → 0.54.0

package/dist/index.js

@@ -1665,6 +1665,41 @@ function mask(lua) {
   return { text, literals };
 }
 var REQUIRE_RE = new RegExp(String.raw`(?<![A-Za-z0-9_.])require\s*\(\s*${PLACEHOLDER}(\d+)${PLACEHOLDER}\s*\)`, "g");
+function isLuaSpace(c) {
+  return c === " " || c === "\t" || c === `
+` || c === "\r";
+}
+var REQUIRE_WORD = "require";
+function callSpan(lua, literal) {
+  let i = literal.start - 1;
+  while (isLuaSpace(lua[i])) {
+    i--;
+  }
+  if (lua[i] !== "(") {
+    return;
+  }
+  i--;
+  while (isLuaSpace(lua[i])) {
+    i--;
+  }
+  const wordEnd = i + 1;
+  const wordStart = wordEnd - REQUIRE_WORD.length;
+  if (wordStart < 0 || lua.slice(wordStart, wordEnd) !== REQUIRE_WORD) {
+    return;
+  }
+  const before = lua[wordStart - 1];
+  if (before !== undefined && /[A-Za-z0-9_.]/.test(before)) {
+    return;
+  }
+  let j = literal.end;
+  while (isLuaSpace(lua[j])) {
+    j++;
+  }
+  if (lua[j] !== ")") {
+    return;
+  }
+  return { callStart: wordStart, callEnd: j + 1 };
+}
 function scanEmittedRequires(lua) {
   const { text, literals } = mask(lua);
   const sites = [];
@@ -1673,7 +1708,12 @@ function scanEmittedRequires(lua) {
     if (literal === undefined) {
       continue;
     }
-    sites.push({ path: literal.value, start: literal.start, end: literal.end });
+    sites.push({
+      path: literal.value,
+      start: literal.start,
+      end: literal.end,
+      ...callSpan(lua, literal)
+    });
   }
   return sites;
 }
@@ -3186,7 +3226,7 @@ function relativeAddressesFrom(index, context) {
 import { readFileSync as readFileSync2 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import * as path4 from "node:path";
-import * as ts16 from "typescript";
+import * as ts17 from "typescript";
 import * as tstl3 from "typescript-to-lua";
 
 // src/companion-emit.ts
@@ -3735,6 +3775,128 @@ var editorScriptErasurePlugin = {
   }
 };
 
+// src/native-global-modules.ts
+import * as ts15 from "typescript";
+var GLOBAL_TABLE_TAG = "globalTable";
+var GLOBAL_TABLE_REQUIRE_MARKER = "@defold-typescript:global-table:";
+var NO_RESOLUTION_PREFIX = "@NoResolution:";
+var LUA_GLOBAL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+function resolveGlobalTableTag(specifier, checker) {
+  if (!ts15.isStringLiteral(specifier)) {
+    return { kind: "untagged" };
+  }
+  const symbol = checker.getSymbolAtLocation(specifier);
+  for (const declaration of symbol?.declarations ?? []) {
+    if (!ts15.isModuleDeclaration(declaration) || !ts15.isStringLiteral(declaration.name)) {
+      continue;
+    }
+    const tag = ts15.getJSDocTags(declaration).find((t) => t.tagName.text === GLOBAL_TABLE_TAG);
+    if (tag === undefined) {
+      continue;
+    }
+    const comment = ts15.getTextOfJSDocComment(tag.comment)?.trim();
+    const globalName = comment === undefined || comment === "" ? specifier.text : comment.split(/\s+/)[0] ?? specifier.text;
+    if (!LUA_GLOBAL_NAME_RE.test(globalName)) {
+      return { kind: "invalid", globalName, moduleId: specifier.text };
+    }
+    return { kind: "tagged", globalName };
+  }
+  return { kind: "untagged" };
+}
+function markerRequirePath(globalName) {
+  return `${NO_RESOLUTION_PREFIX}${GLOBAL_TABLE_REQUIRE_MARKER}${globalName}`;
+}
+function invalidGlobalName(node, resolution) {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts15.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `@${GLOBAL_TABLE_TAG} on module "${resolution.moduleId}" names \`${resolution.globalName}\`, which is not a valid Lua global name; use dotted identifiers (\`pixels\`, \`b2d.body\`).`
+  };
+}
+var nativeGlobalModulesPlugin = {
+  visitors: {
+    [ts15.SyntaxKind.ImportDeclaration]: (node, context) => {
+      const resolution = resolveGlobalTableTag(node.moduleSpecifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(node.moduleSpecifier, resolution));
+        return context.superTransformStatements(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformStatements(node);
+      }
+      if (node.importClause === undefined) {
+        return [];
+      }
+      const rewritten = ts15.factory.updateImportDeclaration(node, node.modifiers, node.importClause, ts15.factory.createStringLiteral(markerRequirePath(resolution.globalName)), node.attributes);
+      return context.superTransformStatements(rewritten);
+    },
+    [ts15.SyntaxKind.ExportDeclaration]: (node, context) => {
+      const specifier = node.moduleSpecifier;
+      if (specifier === undefined) {
+        return context.superTransformStatements(node);
+      }
+      const resolution = resolveGlobalTableTag(specifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(specifier, resolution));
+        return context.superTransformStatements(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformStatements(node);
+      }
+      const rewritten = ts15.factory.updateExportDeclaration(node, node.modifiers, node.isTypeOnly, node.exportClause, ts15.factory.createStringLiteral(markerRequirePath(resolution.globalName)), node.attributes);
+      return context.superTransformStatements(rewritten);
+    },
+    [ts15.SyntaxKind.CallExpression]: (node, context) => {
+      const specifier = node.arguments[0];
+      if (node.expression.kind !== ts15.SyntaxKind.ImportKeyword || specifier === undefined) {
+        return context.superTransformExpression(node);
+      }
+      const resolution = resolveGlobalTableTag(specifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(specifier, resolution));
+        return context.superTransformExpression(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformExpression(node);
+      }
+      const rewritten = ts15.factory.updateCallExpression(node, node.expression, node.typeArguments, [
+        ts15.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        ...node.arguments.slice(1)
+      ]);
+      return context.superTransformExpression(rewritten);
+    }
+  }
+};
+function rewriteGlobalAliasRequires(lua) {
+  let out = "";
+  let cursor = 0;
+  for (const site of scanEmittedRequires(lua)) {
+    if (!site.path.startsWith(GLOBAL_TABLE_REQUIRE_MARKER)) {
+      continue;
+    }
+    if (site.callStart === undefined || site.callEnd === undefined) {
+      continue;
+    }
+    out += lua.slice(cursor, site.callStart);
+    out += `_G.${site.path.slice(GLOBAL_TABLE_REQUIRE_MARKER.length)}`;
+    cursor = site.callEnd;
+  }
+  return out + lua.slice(cursor);
+}
+function findGlobalAliasMarkerLeak(lua) {
+  for (const site of scanEmittedRequires(lua)) {
+    if (site.path.startsWith(GLOBAL_TABLE_REQUIRE_MARKER)) {
+      return site.path.slice(GLOBAL_TABLE_REQUIRE_MARKER.length);
+    }
+  }
+  return;
+}
+
 // src/transpile.ts
 import { readdirSync as readdirSync2, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -3742,17 +3904,17 @@ import * as path3 from "node:path";
 import * as tstl2 from "typescript-to-lua";
 
 // src/go-property-direct-call.ts
-import * as ts15 from "typescript";
+import * as ts16 from "typescript";
 var GO_PROPERTY_DIRECT_CALL_MESSAGE = "`go.property` called directly is deprecated; declare the property in `defineScript({ properties })` so it types onto `self` (the transpiler emits the registration for you).";
 function findDirectGoPropertyCalls(sourceFile) {
   const calls = [];
   const visit = (node) => {
-    if (ts15.isCallExpression(node) && ts15.isPropertyAccessExpression(node.expression) && node.expression.name.text === "property" && ts15.isIdentifier(node.expression.expression) && node.expression.expression.text === "go") {
+    if (ts16.isCallExpression(node) && ts16.isPropertyAccessExpression(node.expression) && node.expression.name.text === "property" && ts16.isIdentifier(node.expression.expression) && node.expression.expression.text === "go") {
       calls.push(node);
     }
-    ts15.forEachChild(node, visit);
+    ts16.forEachChild(node, visit);
   };
-  ts15.forEachChild(sourceFile, visit);
+  ts16.forEachChild(sourceFile, visit);
   return calls;
 }
 
@@ -3860,6 +4022,7 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
   const lua = {};
   const sourceMaps = {};
   const companions = {};
+  const markerLeaks = [];
   let lualib;
   for (const file of transpiledFiles) {
     if (isLualibBundle(file) && typeof file.lua === "string") {
@@ -3870,13 +4033,23 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
     if (!userSource || typeof file.lua !== "string") {
       continue;
     }
-    lua[userSource.fileName] = file.lua;
+    const swapped = rewriteGlobalAliasRequires(file.lua);
+    lua[userSource.fileName] = swapped;
+    const leaked = findGlobalAliasMarkerLeak(swapped);
+    if (leaked !== undefined) {
+      markerLeaks.push({ file: userSource.fileName, globalName: leaked });
+    }
     if (typeof file.luaSourceMap === "string") {
       sourceMaps[userSource.fileName] = file.luaSourceMap;
     }
     const companion = emittedCompanions.get(userSource.fileName);
     if (companion !== undefined) {
-      companions[userSource.fileName] = companion;
+      const swappedCompanion = rewriteGlobalAliasRequires(companion);
+      companions[userSource.fileName] = swappedCompanion;
+      const companionLeak = findGlobalAliasMarkerLeak(swappedCompanion);
+      if (companionLeak !== undefined) {
+        markerLeaks.push({ file: userSource.fileName, globalName: companionLeak });
+      }
     }
   }
   const collectedDiagnostics = diagnostics.map((d) => {
@@ -3891,6 +4064,12 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
     const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
     return { file: fileName, message, line: line + 1, column: character + 1 };
   });
+  for (const leak of markerLeaks) {
+    collectedDiagnostics.push({
+      file: leak.file,
+      message: `@globalTable lowering left an unrewritten require for \`${leak.globalName}\` in the emitted chunk; the output would fail to load in Defold.`
+    });
+  }
   const scanned = new Set;
   let timersImported = false;
   for (const file of transpiledFiles) {
@@ -3951,6 +4130,7 @@ function transpileVirtual(files, companionEmit, overrides = {}) {
       { plugin: physicsEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: nativeGlobalModulesPlugin },
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin }
@@ -4042,6 +4222,7 @@ function compilerOptions(companionEmit) {
       { plugin: physicsEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: nativeGlobalModulesPlugin },
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin }
@@ -4086,7 +4267,7 @@ function createTranspileSession() {
       if (cached) {
         return cached;
       }
-      const created = ts16.createSourceFile(fileName, content, ts16.ScriptTarget.Latest, false);
+      const created = ts17.createSourceFile(fileName, content, ts17.ScriptTarget.Latest, false);
       sourceFileCache.set(normalized, created);
       return created;
     }
@@ -4105,7 +4286,7 @@ function createTranspileSession() {
         return cached;
       }
       const fileContent = readFileSync2(filePath, "utf8");
-      const created = ts16.createSourceFile(filePath, fileContent, ts16.ScriptTarget.Latest, false);
+      const created = ts17.createSourceFile(filePath, fileContent, ts17.ScriptTarget.Latest, false);
       libCache.set(fileName, created);
       return created;
     }
@@ -4118,10 +4299,10 @@ function createTranspileSession() {
     return AMBIENT_FILES[normalized];
   }
   const host = {
-    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts16.sys.fileExists(fileName),
+    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts17.sys.fileExists(fileName),
     getCanonicalFileName: (fileName) => fileName,
     getCurrentDirectory: () => "",
-    getDefaultLibFileName: ts16.getDefaultLibFileName,
+    getDefaultLibFileName: ts17.getDefaultLibFileName,
     readFile: () => "",
     getNewLine: () => `
 `,
@@ -4143,15 +4324,15 @@ function createTranspileSession() {
     const userKeys = new Set(userFiles.keys());
     const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
     const companionEmit = createCompanionEmitPlugin();
-    program = ts16.createProgram(rootNames, compilerOptions(companionEmit), host, program);
-    const preEmitDiagnostics = ts16.getPreEmitDiagnostics(program);
+    program = ts17.createProgram(rootNames, compilerOptions(companionEmit), host, program);
+    const preEmitDiagnostics = ts17.getPreEmitDiagnostics(program);
     const collector = createOutputCollector();
     const { diagnostics: transpileDiagnostics } = new tstl3.Transpiler().emit({
       program,
       writeFile: collector.writeFile
     });
     const diagnostics = [
-      ...ts16.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
+      ...ts17.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
     ];
     return collectOutputs(collector.files, diagnostics, userKeys, companionEmit.companions);
   }
@@ -4161,7 +4342,7 @@ function createTranspileSession() {
   };
 }
 // src/text-script-property.ts
-import * as ts17 from "typescript";
+import * as ts18 from "typescript";
 function findTextScriptProperties(program, fileNames) {
   const checker = program.getTypeChecker();
   const findings = [];
@@ -4172,7 +4353,7 @@ function findTextScriptProperties(program, fileNames) {
     }
     const located = [];
     const visit = (node) => {
-      if (ts17.isCallExpression(node)) {
+      if (ts18.isCallExpression(node)) {
         const hooks = factoryHooks(node, checker);
         for (const property of hooks?.properties ?? []) {
           if (!isPropertiesHook(property)) {
@@ -4185,7 +4366,7 @@ function findTextScriptProperties(program, fileNames) {
           }
         }
       }
-      ts17.forEachChild(node, visit);
+      ts18.forEachChild(node, visit);
     };
     visit(sourceFile);
     for (const call of findDirectGoPropertyCalls(sourceFile)) {
@@ -4194,7 +4375,7 @@ function findTextScriptProperties(program, fileNames) {
         continue;
       }
       if (mayHoldString(checker.getTypeAtLocation(value), checker)) {
-        const name = ts17.isStringLiteralLike(nameArgument) ? nameArgument.text : nameArgument.getText(sourceFile);
+        const name = ts18.isStringLiteralLike(nameArgument) ? nameArgument.text : nameArgument.getText(sourceFile);
         located.push({ name, value });
       }
     }
@@ -4211,20 +4392,20 @@ function mayHoldString(type, checker, visited = new Set) {
     return false;
   }
   visited.add(type);
-  if (type.flags & ts17.TypeFlags.StringLike) {
+  if (type.flags & ts18.TypeFlags.StringLike) {
     return true;
   }
   if (type.isUnionOrIntersection()) {
     return type.types.some((member) => mayHoldString(member, checker, visited));
   }
-  if (type.flags & ts17.TypeFlags.Instantiable) {
+  if (type.flags & ts18.TypeFlags.Instantiable) {
     const constraint = checker.getBaseConstraintOfType(type);
     return constraint !== undefined && constraint !== type ? mayHoldString(constraint, checker, visited) : false;
   }
   return false;
 }
 // src/url-address-slots.ts
-import * as ts18 from "typescript";
+import * as ts19 from "typescript";
 var ADDRESS_CLASSES = {
   "game-object": true,
   component: true,
@@ -4243,7 +4424,7 @@ function isFragmentCaret(slot, position) {
   return slot.fragmentStart !== -1 && position >= slot.fragmentStart;
 }
 function tableKey(checker, callee) {
-  const symbol = checker.getSymbolAtLocation(ts18.isIdentifier(callee) ? callee : callee.name);
+  const symbol = checker.getSymbolAtLocation(ts19.isIdentifier(callee) ? callee : callee.name);
   if (!symbol)
     return;
   const fqn = checker.getFullyQualifiedName(symbol);
@@ -4251,43 +4432,43 @@ function tableKey(checker, callee) {
 }
 function parameterName(checker, call, index) {
   const declaration = checker.getResolvedSignature(call)?.declaration;
-  if (!declaration || !ts18.isFunctionLike(declaration))
+  if (!declaration || !ts19.isFunctionLike(declaration))
     return;
   const parameter = declaration.parameters[index];
-  if (!parameter || parameter.dotDotDotToken || !ts18.isIdentifier(parameter.name))
+  if (!parameter || parameter.dotDotDotToken || !ts19.isIdentifier(parameter.name))
     return;
   return parameter.name.text;
 }
 var EQUALITY_OPERATORS = new Set([
-  ts18.SyntaxKind.EqualsEqualsEqualsToken,
-  ts18.SyntaxKind.ExclamationEqualsEqualsToken,
-  ts18.SyntaxKind.EqualsEqualsToken,
-  ts18.SyntaxKind.ExclamationEqualsToken
+  ts19.SyntaxKind.EqualsEqualsEqualsToken,
+  ts19.SyntaxKind.ExclamationEqualsEqualsToken,
+  ts19.SyntaxKind.EqualsEqualsToken,
+  ts19.SyntaxKind.ExclamationEqualsToken
 ]);
 function comparisonSatisfied(checker, entry, call) {
   if (entry.comparedParameter === undefined)
     return true;
   let node = call;
-  while (ts18.isParenthesizedExpression(node.parent))
+  while (ts19.isParenthesizedExpression(node.parent))
     node = node.parent;
   const comparison = node.parent;
-  if (!ts18.isBinaryExpression(comparison))
+  if (!ts19.isBinaryExpression(comparison))
     return false;
   if (!EQUALITY_OPERATORS.has(comparison.operatorToken.kind))
     return false;
   const other = comparison.left === node ? comparison.right : comparison.left;
   const symbol = checker.getSymbolAtLocation(other);
-  return (symbol?.declarations ?? []).some((declaration) => ts18.isParameter(declaration) && ts18.isIdentifier(declaration.name) && declaration.name.text === entry.comparedParameter);
+  return (symbol?.declarations ?? []).some((declaration) => ts19.isParameter(declaration) && ts19.isIdentifier(declaration.name) && declaration.name.text === entry.comparedParameter);
 }
 function classifiedEntryOfArgument(checker, table, argument) {
   const call = argument.parent;
-  if (!ts18.isCallExpression(call))
+  if (!ts19.isCallExpression(call))
     return;
   const argumentIndex = call.arguments.indexOf(argument);
   if (argumentIndex === -1)
     return;
   const callee = call.expression;
-  if (!ts18.isPropertyAccessExpression(callee) && !ts18.isIdentifier(callee))
+  if (!ts19.isPropertyAccessExpression(callee) && !ts19.isIdentifier(callee))
     return;
   const fqn = tableKey(checker, callee);
   if (fqn === undefined)
@@ -4304,10 +4485,10 @@ function classifiedEntryOfArgument(checker, table, argument) {
 }
 function slotThroughHashedCall(checker, table, literal) {
   const call = literal.parent;
-  if (!ts18.isCallExpression(call))
+  if (!ts19.isCallExpression(call))
     return;
   const callee = call.expression;
-  if (!ts18.isPropertyAccessExpression(callee) && !ts18.isIdentifier(callee))
+  if (!ts19.isPropertyAccessExpression(callee) && !ts19.isIdentifier(callee))
     return;
   if (tableKey(checker, callee) !== "hash")
     return;
@@ -4325,24 +4506,24 @@ function addressTextOf(checker, entry, call) {
   if (entry.addressParameter === undefined)
     return;
   const declaration = checker.getResolvedSignature(call)?.declaration;
-  if (!declaration || !ts18.isFunctionLike(declaration))
+  if (!declaration || !ts19.isFunctionLike(declaration))
     return;
-  const index = declaration.parameters.findIndex((parameter) => !parameter.dotDotDotToken && ts18.isIdentifier(parameter.name) && parameter.name.text === entry.addressParameter);
+  const index = declaration.parameters.findIndex((parameter) => !parameter.dotDotDotToken && ts19.isIdentifier(parameter.name) && parameter.name.text === entry.addressParameter);
   if (index === -1)
     return;
   const argument = call.arguments[index];
-  return argument && ts18.isStringLiteralLike(argument) ? argument.text : undefined;
+  return argument && ts19.isStringLiteralLike(argument) ? argument.text : undefined;
 }
 function innermostLiteralAt(sourceFile, position) {
   let found;
   const visit = (node) => {
     if (position < node.getStart(sourceFile) || position > node.getEnd())
       return;
-    if (ts18.isStringLiteralLike(node))
+    if (ts19.isStringLiteralLike(node))
       found = node;
-    ts18.forEachChild(node, visit);
+    ts19.forEachChild(node, visit);
   };
-  ts18.forEachChild(sourceFile, visit);
+  ts19.forEachChild(sourceFile, visit);
   return found;
 }
 function resolveClassifiedSlotAtPosition(input) {
@@ -4376,23 +4557,23 @@ function resolveClassifiedSlotAtPosition(input) {
   };
 }
 // src/url-cross-world-address.ts
-import * as ts20 from "typescript";
+import * as ts21 from "typescript";
 
 // src/url-address-literals.ts
-import * as ts19 from "typescript";
+import * as ts20 from "typescript";
 function isAmbient2(fileName) {
   return /[\\/]node_modules[\\/]/.test(fileName) || /(^|[\\/])lib\.[^\\/]*\.d\.ts$/.test(fileName);
 }
 function referenceTargetSymbol(type) {
-  if ((type.flags & ts19.TypeFlags.Object) === 0)
+  if ((type.flags & ts20.TypeFlags.Object) === 0)
     return;
-  if ((type.objectFlags & ts19.ObjectFlags.Reference) === 0)
+  if ((type.objectFlags & ts20.ObjectFlags.Reference) === 0)
     return;
   return type.target.symbol;
 }
 function ambientHashAliasTargets(checker, anchor) {
   const targets = new Set;
-  for (const symbol of checker.getSymbolsInScope(anchor, ts19.SymbolFlags.Type)) {
+  for (const symbol of checker.getSymbolsInScope(anchor, ts20.SymbolFlags.Type)) {
     if (symbol.name !== "Hash")
       continue;
     const target = referenceTargetSymbol(checker.getDeclaredTypeOfSymbol(symbol));
@@ -4408,7 +4589,7 @@ function canonicalHashSymbols(checker, program) {
   if (!anchor)
     return canonical;
   const aliased = ambientHashAliasTargets(checker, anchor);
-  for (const symbol of checker.getSymbolsInScope(anchor, ts19.SymbolFlags.Function)) {
+  for (const symbol of checker.getSymbolsInScope(anchor, ts20.SymbolFlags.Function)) {
     if (symbol.name !== "hash")
       continue;
     const declaration = symbol.declarations?.[0];
@@ -4430,7 +4611,7 @@ function hashedSourceOfType(checker, type, canonical) {
   return source?.isStringLiteral() ? source.value : undefined;
 }
 function staticAddressTextOf(checker, node, canonical) {
-  return ts19.isStringLiteralLike(node) ? node.text : hashedSourceOfType(checker, checker.getTypeAtLocation(node), canonical);
+  return ts20.isStringLiteralLike(node) ? node.text : hashedSourceOfType(checker, checker.getTypeAtLocation(node), canonical);
 }
 
 // src/url-cross-world-address.ts
@@ -4454,7 +4635,7 @@ function checkCrossWorldAddresses(input) {
     if (worlds.length === 0)
       continue;
     const visit = (node) => {
-      if (ts20.isExpression(node)) {
+      if (ts21.isExpression(node)) {
         const entry = addressEntryOfArgument(checker, table, node);
         if (entry !== undefined && slotRejectsForeignSocket(entry)) {
           const address = staticAddressTextOf(checker, node, canonical);
@@ -4471,14 +4652,14 @@ function checkCrossWorldAddresses(input) {
           }
         }
       }
-      ts20.forEachChild(node, visit);
+      ts21.forEachChild(node, visit);
     };
-    ts20.forEachChild(sourceFile, visit);
+    ts21.forEachChild(sourceFile, visit);
   }
   return findings;
 }
 // src/url-fragment-reachability.ts
-import * as ts21 from "typescript";
+import * as ts22 from "typescript";
 function pathOfKey(key) {
   const socket = socketOfAddress(key);
   return socket === undefined ? key : key.slice(socket.length + 1);
@@ -4523,7 +4704,7 @@ function checkUrlFragmentReachability(input) {
     if (isAmbient2(sourceFile.fileName))
       continue;
     const visit = (node) => {
-      if (ts21.isExpression(node) && isAddressClass(addressClassOfArgument(checker, table, node))) {
+      if (ts22.isExpression(node) && isAddressClass(addressClassOfArgument(checker, table, node))) {
         const text = staticAddressTextOf(checker, node, canonical);
         if (text !== undefined) {
           const hash = text.indexOf("#");
@@ -4542,9 +4723,9 @@ function checkUrlFragmentReachability(input) {
           }
         }
       }
-      ts21.forEachChild(node, visit);
+      ts22.forEachChild(node, visit);
     };
-    ts21.forEachChild(sourceFile, visit);
+    ts22.forEachChild(sourceFile, visit);
   }
   return { kind: "checked", findings };
 }

package/dist/lua-require-scan.d.ts

@@ -5,6 +5,10 @@ export interface EmittedRequireSite {
     readonly start: number;
     /** Offset one past its closing delimiter. */
     readonly end: number;
+    /** Offset of the `require` keyword, when the whole call is recoverable. */
+    readonly callStart?: number;
+    /** Offset one past the closing paren, when the whole call is recoverable. */
+    readonly callEnd?: number;
 }
 /**
  * Every code-position `require` of a string literal in an emitted Lua chunk, in

package/dist/native-global-modules.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from "typescript-to-lua";
+export declare const GLOBAL_TABLE_REQUIRE_MARKER = "@defold-typescript:global-table:";
+export declare const nativeGlobalModulesPlugin: Plugin;
+/**
+ * Replace every marker require the scanner can span with the global name it
+ * encodes: `local p = require("<marker>pixels")` becomes `local p = _G.pixels`,
+ * rooted in `_G` so no local in scope — including one named `pixels` — can
+ * shadow the global. A marker site without a recoverable call span is left in
+ * place for `findGlobalAliasMarkerLeak` to fail the build on.
+ */
+export declare function rewriteGlobalAliasRequires(lua: string): string;
+/**
+ * The global name of the first marker require surviving in a chunk after the
+ * swap, or undefined when the chunk is clean. Only require paths the scanner
+ * yields count — marker text in an ordinary string or comment is user data,
+ * not a leak. A survivor means an emit shape the swap cannot reach; the output
+ * would fail to load in Defold, so the caller turns it into a build error
+ * rather than shipping it.
+ */
+export declare function findGlobalAliasMarkerLeak(lua: string): string | undefined;

package/package.json

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

package/src/native-global-modules.ts

@@ -0,0 +1,183 @@
+import * as ts from "typescript";
+import type { Plugin } from "typescript-to-lua";
+import { scanEmittedRequires } from "./lua-require-scan";
+
+const GLOBAL_TABLE_TAG = "globalTable";
+
+// Survives into the emitted require path, so it must collide with no real
+// module path a build can own: `@` and `:` are impossible in one.
+export const GLOBAL_TABLE_REQUIRE_MARKER = "@defold-typescript:global-table:";
+
+// `@NoResolution:` tells TSTL's resolver to leave the path alone (the module
+// has no source file in the program); the resolver strips the prefix, leaving
+// the marker path for the post-pass swap.
+const NO_RESOLUTION_PREFIX = "@NoResolution:";
+
+const LUA_GLOBAL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+type TagResolution =
+  | { readonly kind: "untagged" }
+  | { readonly kind: "tagged"; readonly globalName: string }
+  | { readonly kind: "invalid"; readonly globalName: string; readonly moduleId: string };
+
+// The tag is consulted only when the specifier resolves to an ambient
+// `declare module "<id>"`; a real source file sharing the id resolves to the
+// file and stays on the ordinary require lane.
+function resolveGlobalTableTag(specifier: ts.Expression, checker: ts.TypeChecker): TagResolution {
+  if (!ts.isStringLiteral(specifier)) {
+    return { kind: "untagged" };
+  }
+  const symbol = checker.getSymbolAtLocation(specifier);
+  for (const declaration of symbol?.declarations ?? []) {
+    if (!ts.isModuleDeclaration(declaration) || !ts.isStringLiteral(declaration.name)) {
+      continue;
+    }
+    const tag = ts.getJSDocTags(declaration).find((t) => t.tagName.text === GLOBAL_TABLE_TAG);
+    if (tag === undefined) {
+      continue;
+    }
+    const comment = ts.getTextOfJSDocComment(tag.comment)?.trim();
+    const globalName =
+      comment === undefined || comment === ""
+        ? specifier.text
+        : (comment.split(/\s+/)[0] ?? specifier.text);
+    if (!LUA_GLOBAL_NAME_RE.test(globalName)) {
+      return { kind: "invalid", globalName, moduleId: specifier.text };
+    }
+    return { kind: "tagged", globalName };
+  }
+  return { kind: "untagged" };
+}
+
+function markerRequirePath(globalName: string): string {
+  return `${NO_RESOLUTION_PREFIX}${GLOBAL_TABLE_REQUIRE_MARKER}${globalName}`;
+}
+
+function invalidGlobalName(
+  node: ts.Node,
+  resolution: {
+    readonly globalName: string;
+    readonly moduleId: string;
+  },
+): ts.Diagnostic {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `@${GLOBAL_TABLE_TAG} on module "${resolution.moduleId}" names \`${resolution.globalName}\`, which is not a valid Lua global name; use dotted identifiers (\`pixels\`, \`b2d.body\`).`,
+  };
+}
+
+export const nativeGlobalModulesPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.ImportDeclaration]: (node, context) => {
+      const resolution = resolveGlobalTableTag(node.moduleSpecifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(node.moduleSpecifier, resolution));
+        return context.superTransformStatements(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformStatements(node);
+      }
+      if (node.importClause === undefined) {
+        // A side-effect import of a runtime global loads nothing.
+        return [];
+      }
+      const rewritten = ts.factory.updateImportDeclaration(
+        node,
+        node.modifiers,
+        node.importClause,
+        ts.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        node.attributes,
+      );
+      return context.superTransformStatements(rewritten);
+    },
+    [ts.SyntaxKind.ExportDeclaration]: (node, context) => {
+      const specifier = node.moduleSpecifier;
+      if (specifier === undefined) {
+        return context.superTransformStatements(node);
+      }
+      const resolution = resolveGlobalTableTag(specifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(specifier, resolution));
+        return context.superTransformStatements(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformStatements(node);
+      }
+      const rewritten = ts.factory.updateExportDeclaration(
+        node,
+        node.modifiers,
+        node.isTypeOnly,
+        node.exportClause,
+        ts.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        node.attributes,
+      );
+      return context.superTransformStatements(rewritten);
+    },
+    [ts.SyntaxKind.CallExpression]: (node, context) => {
+      const specifier = node.arguments[0];
+      if (node.expression.kind !== ts.SyntaxKind.ImportKeyword || specifier === undefined) {
+        return context.superTransformExpression(node);
+      }
+      const resolution = resolveGlobalTableTag(specifier, context.checker);
+      if (resolution.kind === "invalid") {
+        context.diagnostics.push(invalidGlobalName(specifier, resolution));
+        return context.superTransformExpression(node);
+      }
+      if (resolution.kind === "untagged") {
+        return context.superTransformExpression(node);
+      }
+      const rewritten = ts.factory.updateCallExpression(node, node.expression, node.typeArguments, [
+        ts.factory.createStringLiteral(markerRequirePath(resolution.globalName)),
+        ...node.arguments.slice(1),
+      ]);
+      return context.superTransformExpression(rewritten);
+    },
+  },
+};
+
+/**
+ * Replace every marker require the scanner can span with the global name it
+ * encodes: `local p = require("<marker>pixels")` becomes `local p = _G.pixels`,
+ * rooted in `_G` so no local in scope — including one named `pixels` — can
+ * shadow the global. A marker site without a recoverable call span is left in
+ * place for `findGlobalAliasMarkerLeak` to fail the build on.
+ */
+export function rewriteGlobalAliasRequires(lua: string): string {
+  let out = "";
+  let cursor = 0;
+  for (const site of scanEmittedRequires(lua)) {
+    if (!site.path.startsWith(GLOBAL_TABLE_REQUIRE_MARKER)) {
+      continue;
+    }
+    if (site.callStart === undefined || site.callEnd === undefined) {
+      continue;
+    }
+    out += lua.slice(cursor, site.callStart);
+    out += `_G.${site.path.slice(GLOBAL_TABLE_REQUIRE_MARKER.length)}`;
+    cursor = site.callEnd;
+  }
+  return out + lua.slice(cursor);
+}
+
+/**
+ * The global name of the first marker require surviving in a chunk after the
+ * swap, or undefined when the chunk is clean. Only require paths the scanner
+ * yields count — marker text in an ordinary string or comment is user data,
+ * not a leak. A survivor means an emit shape the swap cannot reach; the output
+ * would fail to load in Defold, so the caller turns it into a build error
+ * rather than shipping it.
+ */
+export function findGlobalAliasMarkerLeak(lua: string): string | undefined {
+  for (const site of scanEmittedRequires(lua)) {
+    if (site.path.startsWith(GLOBAL_TABLE_REQUIRE_MARKER)) {
+      return site.path.slice(GLOBAL_TABLE_REQUIRE_MARKER.length);
+    }
+  }
+  return undefined;
+}

package/src/session.ts

@@ -9,6 +9,7 @@ import { hsmLoweringPlugin } from "./hsm-builtin";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import { nativeGlobalModulesPlugin } from "./native-global-modules";
 import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { timersLoweringPlugin } from "./timers-lowering";
 import { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
@@ -54,6 +55,7 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
       { plugin: physicsEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: nativeGlobalModulesPlugin },
       { plugin: hsmLoweringPlugin },
       { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin },

package/src/transpile.ts

@@ -21,6 +21,11 @@ import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { scanEmittedRequires } from "./lua-require-scan";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
+import {
+  findGlobalAliasMarkerLeak,
+  nativeGlobalModulesPlugin,
+  rewriteGlobalAliasRequires,
+} from "./native-global-modules";
 import { physicsEventGuardLoweringPlugin } from "./physics-event-guard-lowering";
 import { importsTimersModule, timersLoweringPlugin } from "./timers-lowering";
 import { TIMERS_RUNTIME } from "./timers-runtime";
@@ -258,6 +263,7 @@ export function collectOutputs(
   const lua: Record<string, string> = {};
   const sourceMaps: Record<string, string> = {};
   const companions: Record<string, string> = {};
+  const markerLeaks: { file: string; globalName: string }[] = [];
   let lualib: string | undefined;
   for (const file of transpiledFiles) {
     if (isLualibBundle(file) && typeof file.lua === "string") {
@@ -268,13 +274,25 @@ export function collectOutputs(
     if (!userSource || typeof file.lua !== "string") {
       continue;
     }
-    lua[userSource.fileName] = file.lua;
+    // Column offsets after a swap shift, as they already do under the CLI's
+    // require respelling — accepted.
+    const swapped = rewriteGlobalAliasRequires(file.lua);
+    lua[userSource.fileName] = swapped;
+    const leaked = findGlobalAliasMarkerLeak(swapped);
+    if (leaked !== undefined) {
+      markerLeaks.push({ file: userSource.fileName, globalName: leaked });
+    }
     if (typeof file.luaSourceMap === "string") {
       sourceMaps[userSource.fileName] = file.luaSourceMap;
     }
     const companion = emittedCompanions.get(userSource.fileName);
     if (companion !== undefined) {
-      companions[userSource.fileName] = companion;
+      const swappedCompanion = rewriteGlobalAliasRequires(companion);
+      companions[userSource.fileName] = swappedCompanion;
+      const companionLeak = findGlobalAliasMarkerLeak(swappedCompanion);
+      if (companionLeak !== undefined) {
+        markerLeaks.push({ file: userSource.fileName, globalName: companionLeak });
+      }
     }
   }
 
@@ -291,6 +309,15 @@ export function collectOutputs(
     return { file: fileName, message, line: line + 1, column: character + 1 };
   });
 
+  // A surviving marker is a build error, not a fallback: the alternative —
+  // leaving the original require — fails silently at load time in Defold.
+  for (const leak of markerLeaks) {
+    collectedDiagnostics.push({
+      file: leak.file,
+      message: `@globalTable lowering left an unrewritten require for \`${leak.globalName}\` in the emitted chunk; the output would fail to load in Defold.`,
+    });
+  }
+
   // Advisory scan of the user TypeScript AST for the deprecated direct
   // `go.property` call, plus detection of the timers polyfill import. Run here
   // (shared by transpileProject and the watch session) so both paths report it
@@ -378,6 +405,7 @@ function transpileVirtual(
         { plugin: physicsEventGuardLoweringPlugin },
         { plugin: messageDispatchLoweringPlugin },
         { plugin: timersLoweringPlugin },
+        { plugin: nativeGlobalModulesPlugin },
         { plugin: hsmLoweringPlugin },
         { plugin: typeApplicationErasurePlugin },
         { plugin: companionEmit.plugin },