@defold-typescript/transpiler 0.51.0 → 0.52.0

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { HSM_MODULE_SPECIFIER, HSM_REQUIRE_ROOT, hsmModules, hsmRequireName, hsm
 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";
+export { scanEmittedRequires } from "./lua-require-scan";
 export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
 export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
 export { computeOutputRel, DEFAULT_INCLUDE, parseBuildConfig, projectRelativeBase, requirePathForRel, SCRIPT_SUFFIX_BY_KIND, stripIncludeBase, } from "./output-paths";

package/dist/index.js

@@ -172,22 +172,26 @@ var FACTORY_SPECIFIERS = new Set([
   `${FACTORY_MODULE}/gui-script`,
   `${FACTORY_MODULE}/render-script`
 ]);
-function resolvesToFactoryExport(callee, checker) {
+function factoryExportName(callee, checker) {
   let symbol = checker.getSymbolAtLocation(callee);
   if (symbol === undefined) {
-    return false;
+    return;
   }
   if (symbol.flags & ts2.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
-  if (!FACTORY_NAMES.has(symbol.getName())) {
-    return false;
+  const name = symbol.getName();
+  if (!FACTORY_NAMES.has(name)) {
+    return;
   }
   const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
   if (declaration === undefined) {
-    return false;
+    return;
   }
-  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE);
+  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE) ? name : undefined;
+}
+function resolvesToFactoryExport(callee, checker) {
+  return factoryExportName(callee, checker) !== undefined;
 }
 function isThisParameter2(param) {
   return ts2.isIdentifier(param.name) && ts2.identifierToKeywordKind(param.name) === ts2.SyntaxKind.ThisKeyword;
@@ -270,6 +274,15 @@ function emitInitMerge(fn, context, property) {
   const initFn = createFunctionExpression2(createBlock2([stateDecl, guard]), [createIdentifier2("self")], undefined, NodeFlags2.Declaration, fn);
   return [builderDecl, createAssignmentStatement(createIdentifier2("init"), initFn, property)];
 }
+var RESOURCE_PROPERTY_MARKERS = new Set([
+  "resource.atlas",
+  "resource.buffer",
+  "resource.font",
+  "resource.material",
+  "resource.render_target",
+  "resource.texture",
+  "resource.tile_source"
+]);
 function propertyMembers(property) {
   if (!ts2.isPropertyAssignment(property) || !ts2.isObjectLiteralExpression(property.initializer)) {
     return [];
@@ -306,11 +319,108 @@ function isPropertiesHook(property) {
 function emitPropertyRegistrations(property, context) {
   return propertyMembers(property).map(({ name, initializer }) => createExpressionStatement(createCallExpression2(createTableIndexExpression(createIdentifier2("go"), createStringLiteral2("property")), [createStringLiteral2(name), context.transformExpression(initializer)])));
 }
+function scriptOnlyProperties(property, factory) {
+  const file = property.getSourceFile();
+  const start = property.getStart(file);
+  return {
+    file,
+    start,
+    length: property.getEnd() - start,
+    category: ts2.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${factory}\` cannot declare \`properties\`: Defold builds \`go.property\` only in \`.script\` files. Declare the property in a \`defineScript\` and send its value with \`msg.post\`.`
+  };
+}
+function outermostWrapper(node) {
+  let current = node;
+  while (ts2.isParenthesizedExpression(current.parent) || ts2.isAsExpression(current.parent) || ts2.isSatisfiesExpression(current.parent) || ts2.isNonNullExpression(current.parent) || ts2.isTypeAssertionExpression(current.parent)) {
+    current = current.parent;
+  }
+  return current;
+}
+function innermostExpression(node) {
+  let current = node;
+  while (ts2.isParenthesizedExpression(current) || ts2.isAsExpression(current) || ts2.isSatisfiesExpression(current) || ts2.isNonNullExpression(current) || ts2.isTypeAssertionExpression(current)) {
+    current = current.expression;
+  }
+  return current;
+}
+function globalName(symbol, checker) {
+  if (symbol === undefined) {
+    return;
+  }
+  const fqn = checker.getFullyQualifiedName(symbol);
+  return fqn.startsWith("global.") ? fqn.slice("global.".length) : undefined;
+}
+function calledGlobal(call, checker) {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (declaration === undefined || !ts2.isFunctionDeclaration(declaration) || declaration.name === undefined) {
+    return;
+  }
+  return globalName(checker.getSymbolAtLocation(declaration.name), checker);
+}
+function isPropertyDefault(call, checker) {
+  const value = outermostWrapper(call);
+  const parent = value.parent;
+  if (ts2.isCallExpression(parent)) {
+    return parent.arguments[1] === value && calledGlobal(parent, checker) === "go.property";
+  }
+  const properties = parent?.parent?.parent;
+  if (properties === undefined || !ts2.isPropertyAssignment(properties) || !isPropertiesHook(properties)) {
+    return false;
+  }
+  const hooks = properties.parent;
+  return ts2.isObjectLiteralExpression(hooks) && factoryHooks(hooks.parent, checker) === hooks && propertyMembers(properties).some((member) => member.initializer === value);
+}
+function misplacedMarker(node, marker) {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts2.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${marker}\` is a build-time marker: Defold's build reads it only in a \`go.property\` default, and the engine binds no such function. Use it as a \`defineScript\` \`properties\` default.`
+  };
+}
+function readsAsMarker(call) {
+  const callee = innermostExpression(call.expression);
+  if (ts2.isOptionalChain(call) || ts2.isOptionalChain(callee)) {
+    return false;
+  }
+  if (!ts2.isPropertyAccessExpression(callee) && !(ts2.isElementAccessExpression(callee) && ts2.isStringLiteralLike(innermostExpression(callee.argumentExpression)))) {
+    return false;
+  }
+  const receiver = innermostExpression(callee.expression);
+  if (!ts2.isIdentifier(receiver) || receiver.text !== "resource") {
+    return false;
+  }
+  const [path] = call.arguments;
+  return path === undefined || ts2.isStringLiteralLike(innermostExpression(path));
+}
+function unreadableMarker(node, marker) {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts2.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${marker}\` in a property default must be written \`${marker}("<path>")\`, with a string literal path: Defold's build reads no other form.`
+  };
+}
+function isCallee(node) {
+  const callee = outermostWrapper(node);
+  return ts2.isCallExpression(callee.parent) && callee.parent.expression === callee;
+}
 function eraseFactoryCall(expression, context) {
   const hooks = factoryHooks(expression, context.checker);
-  if (hooks === undefined) {
+  if (hooks === undefined || !ts2.isCallExpression(expression)) {
     return;
   }
+  const factory = factoryExportName(expression.expression, context.checker);
   const registrations = [];
   const statements = [];
   for (const property of hooks.properties) {
@@ -319,7 +429,11 @@ function eraseFactoryCall(expression, context) {
       continue;
     }
     if (name === "properties") {
-      registrations.push(...emitPropertyRegistrations(property, context));
+      if (factory === "defineScript") {
+        registrations.push(...emitPropertyRegistrations(property, context));
+      } else if (factory !== undefined && propertyMembers(property).length > 0) {
+        context.diagnostics.push(scriptOnlyProperties(property, factory));
+      }
       continue;
     }
     const fn = hookFunction(property);
@@ -373,7 +487,37 @@ var lifecycleErasurePlugin = {
       }
       return context.superTransformStatements(node);
     },
-    [ts2.SyntaxKind.ImportDeclaration]: (node, context) => isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node)
+    [ts2.SyntaxKind.ImportDeclaration]: (node, context) => isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node),
+    [ts2.SyntaxKind.CallExpression]: (node, context) => {
+      const marker = node.parent === undefined ? undefined : calledGlobal(node, context.checker);
+      if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+        if (!isPropertyDefault(node, context.checker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        } else if (!readsAsMarker(node)) {
+          context.diagnostics.push(unreadableMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts2.SyntaxKind.PropertyAccessExpression]: (node, context) => {
+      if (node.parent !== undefined && !isCallee(node)) {
+        const marker = globalName(context.checker.getSymbolAtLocation(node.name), context.checker);
+        if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts2.SyntaxKind.ElementAccessExpression]: (node, context) => {
+      if (node.parent !== undefined && !isCallee(node)) {
+        const key = innermostExpression(node.argumentExpression);
+        const marker = ts2.isStringLiteralLike(key) ? globalName(context.checker.getPropertyOfType(context.checker.getTypeAtLocation(node.expression), key.text), context.checker) : undefined;
+        if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    }
   }
 };
 
@@ -3694,6 +3838,7 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
     }
   }
   const hsm = hsmClosure([...Object.values(lua), ...Object.values(companions)], compileHsmModules);
+  const hsmSourceMaps = hsm === undefined ? undefined : selectHsmSourceMaps(Object.keys(hsm));
   return {
     lua,
     sourceMaps,
@@ -3701,9 +3846,21 @@ function collectOutputs(transpiledFiles, diagnostics, userKeys, emittedCompanion
     ...Object.keys(companions).length > 0 ? { companions } : {},
     ...lualib !== undefined ? { lualib } : {},
     ...timersImported ? { timersRuntime: TIMERS_RUNTIME } : {},
-    ...hsm !== undefined ? { hsmModules: hsm } : {}
+    ...hsm !== undefined ? { hsmModules: hsm } : {},
+    ...hsmSourceMaps !== undefined ? { hsmSourceMaps } : {}
   };
 }
+function selectHsmSourceMaps(names) {
+  const maps = compileHsmSourceMaps();
+  const selected = {};
+  for (const name of names) {
+    const map = maps[name];
+    if (map !== undefined) {
+      selected[name] = map;
+    }
+  }
+  return selected;
+}
 function transpileVirtual(files, companionEmit, overrides = {}) {
   return tstl2.transpileVirtualProject({ ...AMBIENT_FILES, ...files }, {
     luaTarget: tstl2.LuaTarget.Lua51,
@@ -3738,6 +3895,12 @@ function requiresLualib(lua) {
   return scanEmittedRequires(lua).some(({ path: requirePath }) => requirePath === "lualib_bundle");
 }
 function compileHsmModules() {
+  return compileHsm().lua;
+}
+function compileHsmSourceMaps() {
+  return compileHsm().sourceMaps;
+}
+function compileHsm() {
   if (compiledHsm !== undefined) {
     return compiledHsm;
   }
@@ -3752,6 +3915,7 @@ function compileHsmModules() {
   const result = transpileVirtual(files, createCompanionEmitPlugin(), { removeComments: true });
   const problems = result.diagnostics.map((d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`);
   const lua = {};
+  const sourceMaps = {};
   for (const file of result.transpiledFiles) {
     if (isLualibBundle(file)) {
       continue;
@@ -3765,14 +3929,17 @@ function compileHsmModules() {
       problems.push(`the compiled ${name} module requires lualib_bundle`);
     }
     lua[name] = file.lua;
+    if (typeof file.luaSourceMap === "string") {
+      sourceMaps[name] = file.luaSourceMap;
+    }
   }
   if (problems.length > 0) {
     throw new Error(`@defold-typescript/transpiler: the hsm library does not compile:
   ${problems.join(`
   `)}`);
   }
-  compiledHsm = lua;
-  return lua;
+  compiledHsm = { lua, sourceMaps };
+  return compiledHsm;
 }
 function transpile(source) {
   const project = transpileProject({ files: { "main.ts": source } });
@@ -4379,6 +4546,7 @@ export {
   resolveClassifiedSlotAtPosition,
   resolveHsmSourceDir,
   rewriteEmittedRequires,
+  scanEmittedRequires,
   slotRejectsForeignSocket,
   socketOfAddress,
   stripIncludeBase,

package/dist/lifecycle-erasure.d.ts

@@ -3,6 +3,7 @@ import { type Plugin } from "typescript-to-lua";
 export declare const FACTORY_MODULE = "@defold-typescript/types";
 export declare const FACTORY_NAMES: Set<string>;
 export declare function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean;
+export declare const RESOURCE_PROPERTY_MARKERS: ReadonlySet<string>;
 export interface PropertyMember {
     readonly name: string;
     readonly initializer: ts.Expression;

package/dist/transpile.d.ts

@@ -22,6 +22,7 @@ export interface TranspileProjectResult {
     readonly lualib?: string;
     readonly timersRuntime?: string;
     readonly hsmModules?: Readonly<Record<string, string>>;
+    readonly hsmSourceMaps?: Readonly<Record<string, string>>;
 }
 export declare const AMBIENT_FILES: Readonly<Record<string, string>>;
 interface CollectableFile {
@@ -42,5 +43,7 @@ export declare function transpileProject(input: TranspileProjectInput): Transpil
  * lualib bundle.
  */
 export declare function compileHsmModules(): Readonly<Record<string, string>>;
+/** The source map of every module `compileHsmModules` returns, under the same keys. */
+export declare function compileHsmSourceMaps(): Readonly<Record<string, string>>;
 export declare function transpile(source: string): TranspileResult;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.51.0",
+  "version": "0.52.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.51.0",
+    "@defold-typescript/types": "0.52.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"

package/src/hsm-builtin.ts

@@ -7,8 +7,8 @@ import { scanEmittedRequires } from "./lua-require-scan";
 
 // `@defold-typescript/types/hsm` is the `index` module; every other module is a
 // subpath of it. Each lowers to a require of `defold_typescript_hsm.<module>`,
-// which the CLI writes under the output root the way it writes the timers
-// runtime.
+// which the CLI respells to the module's place in its runtime folder, the way it
+// handles the timers runtime.
 export const HSM_MODULE_SPECIFIER = "@defold-typescript/types/hsm";
 export const HSM_REQUIRE_ROOT = "defold_typescript_hsm";
 

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   readGameProjectDependencies,
   readLibrarySceneDocuments,
 } from "./library-dependencies";
+export { scanEmittedRequires } from "./lua-require-scan";
 export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
 export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
 export {

package/src/lifecycle-erasure.ts

@@ -35,22 +35,29 @@ const FACTORY_SPECIFIERS = new Set([
   `${FACTORY_MODULE}/render-script`,
 ]);
 
-export function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+// The lifecycle factory a callee resolves to, aliases followed, or `undefined`
+// when it is not one of this package's factory exports.
+function factoryExportName(callee: ts.Expression, checker: ts.TypeChecker): string | undefined {
   let symbol = checker.getSymbolAtLocation(callee);
   if (symbol === undefined) {
-    return false;
+    return undefined;
   }
   if (symbol.flags & ts.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
-  if (!FACTORY_NAMES.has(symbol.getName())) {
-    return false;
+  const name = symbol.getName();
+  if (!FACTORY_NAMES.has(name)) {
+    return undefined;
   }
   const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
   if (declaration === undefined) {
-    return false;
+    return undefined;
   }
-  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE);
+  return declaration.getSourceFile().fileName.includes(FACTORY_MODULE) ? name : undefined;
+}
+
+export function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+  return factoryExportName(callee, checker) !== undefined;
 }
 
 function isThisParameter(param: ts.ParameterDeclaration): boolean {
@@ -208,6 +215,20 @@ function emitInitMerge(
   return [builderDecl, createAssignmentStatement(createIdentifier("init"), initFn, property)];
 }
 
+// Build-time markers, never engine functions: bob reads `resource.<kind>("path")`
+// only as a `go.property` default (`LuaScanner.java:923-933` at defold
+// `a81dbb04`), and the engine's `resource` table registers none of them
+// (`script_resource.cpp:3447-3463` in 1.14.0). Called anywhere else, each is nil.
+export const RESOURCE_PROPERTY_MARKERS: ReadonlySet<string> = new Set([
+  "resource.atlas",
+  "resource.buffer",
+  "resource.font",
+  "resource.material",
+  "resource.render_target",
+  "resource.texture",
+  "resource.tile_source",
+]);
+
 export interface PropertyMember {
   readonly name: string;
   readonly initializer: ts.Expression;
@@ -275,14 +296,171 @@ function emitPropertyRegistrations(
   );
 }
 
+// Defold builds `go.property` only in `.script` files, so a GUI or render
+// script's `properties` block has nothing it could lower to.
+function scriptOnlyProperties(
+  property: ts.ObjectLiteralElementLike,
+  factory: string,
+): ts.Diagnostic {
+  const file = property.getSourceFile();
+  const start = property.getStart(file);
+  return {
+    file,
+    start,
+    length: property.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `\`${factory}\` cannot declare \`properties\`: Defold builds \`go.property\` only in \`.script\` files. Declare the property in a \`defineScript\` and send its value with \`msg.post\`.`,
+  };
+}
+
+// The outermost expression that only wraps `node` in parentheses or a type-only
+// form, so `(resource.atlas("/a.atlas") as Hash)` sits where the bare call would.
+function outermostWrapper(node: ts.Expression): ts.Expression {
+  let current = node;
+  while (
+    ts.isParenthesizedExpression(current.parent) ||
+    ts.isAsExpression(current.parent) ||
+    ts.isSatisfiesExpression(current.parent) ||
+    ts.isNonNullExpression(current.parent) ||
+    ts.isTypeAssertionExpression(current.parent)
+  ) {
+    current = current.parent;
+  }
+  return current;
+}
+
+// The inverse of `outermostWrapper`: the expression a run of parentheses and
+// type-only forms wraps, which TSTL emits in place of the whole run.
+function innermostExpression(node: ts.Expression): ts.Expression {
+  let current = node;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isTypeAssertionExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+// Keyed by the declaration's fully qualified name: only a symbol declared in an
+// ambient `declare global` block carries the `global.` prefix, so a project's
+// own `resource` never matches.
+function globalName(symbol: ts.Symbol | undefined, checker: ts.TypeChecker): string | undefined {
+  if (symbol === undefined) {
+    return undefined;
+  }
+  const fqn = checker.getFullyQualifiedName(symbol);
+  return fqn.startsWith("global.") ? fqn.slice("global.".length) : undefined;
+}
+
+function calledGlobal(call: ts.CallExpression, checker: ts.TypeChecker): string | undefined {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (
+    declaration === undefined ||
+    !ts.isFunctionDeclaration(declaration) ||
+    declaration.name === undefined
+  ) {
+    return undefined;
+  }
+  return globalName(checker.getSymbolAtLocation(declaration.name), checker);
+}
+
+// A `properties` default of a factory call, or the default argument of a
+// direct `go.property` call: the two places bob reads a marker.
+function isPropertyDefault(call: ts.CallExpression, checker: ts.TypeChecker): boolean {
+  const value = outermostWrapper(call);
+  const parent = value.parent;
+  if (ts.isCallExpression(parent)) {
+    return parent.arguments[1] === value && calledGlobal(parent, checker) === "go.property";
+  }
+  const properties = parent?.parent?.parent;
+  if (
+    properties === undefined ||
+    !ts.isPropertyAssignment(properties) ||
+    !isPropertiesHook(properties)
+  ) {
+    return false;
+  }
+  const hooks = properties.parent;
+  return (
+    ts.isObjectLiteralExpression(hooks) &&
+    factoryHooks(hooks.parent as ts.Expression, checker) === hooks &&
+    propertyMembers(properties).some((member) => member.initializer === value)
+  );
+}
+
+function misplacedMarker(node: ts.Expression, marker: 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: `\`${marker}\` is a build-time marker: Defold's build reads it only in a \`go.property\` default, and the engine binds no such function. Use it as a \`defineScript\` \`properties\` default.`,
+  };
+}
+
+// Bob reads a default as a marker only when the emitted text is
+// `resource.<kind>("<path>")` or `resource.<kind>()`: the object token must be
+// `resource` with a dot `NAME` key, and the first argument a string literal or
+// absent (`LuaScanner.java:801-822`, `:923-933` and `:493-510` at defold
+// `a81dbb04`). The receiver test is textual like bob's; the marker resolution
+// has already excluded a project's own `resource`.
+function readsAsMarker(call: ts.CallExpression): boolean {
+  const callee = innermostExpression(call.expression);
+  if (ts.isOptionalChain(call) || ts.isOptionalChain(callee)) {
+    return false;
+  }
+  if (
+    !ts.isPropertyAccessExpression(callee) &&
+    !(
+      ts.isElementAccessExpression(callee) &&
+      ts.isStringLiteralLike(innermostExpression(callee.argumentExpression))
+    )
+  ) {
+    return false;
+  }
+  const receiver = innermostExpression(callee.expression);
+  if (!ts.isIdentifier(receiver) || receiver.text !== "resource") {
+    return false;
+  }
+  const [path] = call.arguments;
+  return path === undefined || ts.isStringLiteralLike(innermostExpression(path));
+}
+
+function unreadableMarker(node: ts.CallExpression, marker: 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: `\`${marker}\` in a property default must be written \`${marker}("<path>")\`, with a string literal path: Defold's build reads no other form.`,
+  };
+}
+
+function isCallee(node: ts.Expression): boolean {
+  const callee = outermostWrapper(node);
+  return ts.isCallExpression(callee.parent) && callee.parent.expression === callee;
+}
+
 function eraseFactoryCall(
   expression: ts.Expression,
   context: TransformationContext,
 ): Statement[] | undefined {
   const hooks = factoryHooks(expression, context.checker);
-  if (hooks === undefined) {
+  if (hooks === undefined || !ts.isCallExpression(expression)) {
     return undefined;
   }
+  const factory = factoryExportName(expression.expression, context.checker);
   const registrations: Statement[] = [];
   const statements: Statement[] = [];
   for (const property of hooks.properties) {
@@ -291,7 +469,11 @@ function eraseFactoryCall(
       continue;
     }
     if (name === "properties") {
-      registrations.push(...emitPropertyRegistrations(property, context));
+      if (factory === "defineScript") {
+        registrations.push(...emitPropertyRegistrations(property, context));
+      } else if (factory !== undefined && propertyMembers(property).length > 0) {
+        context.diagnostics.push(scriptOnlyProperties(property, factory));
+      }
       continue;
     }
     const fn = hookFunction(property);
@@ -374,5 +556,48 @@ export const lifecycleErasurePlugin: Plugin = {
     },
     [ts.SyntaxKind.ImportDeclaration]: (node, context) =>
       isFactoryOnlyImport(node) ? [] : context.superTransformStatements(node),
+    // TSTL's optional-chain lowering also visits nodes it synthesizes, which have
+    // no parent and no source span; only parsed nodes are checked.
+    [ts.SyntaxKind.CallExpression]: (node, context) => {
+      const marker = node.parent === undefined ? undefined : calledGlobal(node, context.checker);
+      if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+        if (!isPropertyDefault(node, context.checker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        } else if (!readsAsMarker(node)) {
+          context.diagnostics.push(unreadableMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts.SyntaxKind.PropertyAccessExpression]: (node, context) => {
+      if (node.parent !== undefined && !isCallee(node)) {
+        const marker = globalName(context.checker.getSymbolAtLocation(node.name), context.checker);
+        if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts.SyntaxKind.ElementAccessExpression]: (node, context) => {
+      if (node.parent !== undefined && !isCallee(node)) {
+        // The checker resolves a string key only when it is the direct argument,
+        // so a wrapped key is looked up by name on the receiver's type, as the
+        // checker does for a direct one.
+        const key = innermostExpression(node.argumentExpression);
+        const marker = ts.isStringLiteralLike(key)
+          ? globalName(
+              context.checker.getPropertyOfType(
+                context.checker.getTypeAtLocation(node.expression),
+                key.text,
+              ),
+              context.checker,
+            )
+          : undefined;
+        if (marker !== undefined && RESOURCE_PROPERTY_MARKERS.has(marker)) {
+          context.diagnostics.push(misplacedMarker(node, marker));
+        }
+      }
+      return context.superTransformExpression(node);
+    },
   },
 };

package/src/timers-runtime.ts

@@ -1,7 +1,7 @@
 // The importable polyfill specifier (matched by the type checker and the
 // lowering pass) and the flat Lua require name the import is rewritten to. The
-// CLI writes the runtime to `<require name>.lua` at the output root, mirroring
-// `lualib_bundle`, so `require("defold_typescript_timers")` resolves in Defold.
+// CLI writes the runtime into its runtime folder beside `lualib_bundle` and
+// respells every `require("defold_typescript_timers")` to that path.
 export const TIMERS_MODULE_SPECIFIER = "@defold-typescript/types/timers";
 export const TIMERS_REQUIRE_NAME = "defold_typescript_timers";
 

package/src/transpile.ts

@@ -63,23 +63,27 @@ export interface TranspileProjectResult {
   // 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
+  // runtime requires the bundle. The emitted `require("lualib_bundle")` is an
+  // internal name the CLI respells to where it writes the bundle. 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
-  // not erased — it lowers to `require("defold_typescript_timers")`, so the CLI
-  // must write this to the output root. Present only when a user file imports
-  // the module (pay-for-use).
+  // not erased — it lowers to `require("defold_typescript_timers")`, an
+  // internal name the CLI respells to where it writes this. Present only when
+  // a user file imports the module (pay-for-use).
   readonly timersRuntime?: string;
   // The compiled `hsm` modules the program requires, keyed by module name
   // (`index`, `defold`, ...). An hsm import lowers to
-  // `require("defold_typescript_hsm.<module>")`, so the CLI must write each one
-  // under the output root. Present only when some chunk requires one
-  // (pay-for-use); never carries a source map, since the `.ts` it would point
-  // at is not in the user's project.
+  // `require("defold_typescript_hsm.<module>")`, an internal name the CLI
+  // respells to where it writes each one. Present only when some chunk requires one
+  // (pay-for-use).
   readonly hsmModules?: Readonly<Record<string, string>>;
+  // The source map of each module in `hsmModules`, under the same keys. Its
+  // `sources` names `<module>.ts` with an empty `sourceRoot`: only the CLI knows
+  // where the module is written and where the hsm source sits, so it sets the
+  // root that joins them.
+  readonly hsmSourceMaps?: Readonly<Record<string, string>>;
 }
 
 function flattenDiagnosticMessage(
@@ -313,6 +317,7 @@ export function collectOutputs(
   }
 
   const hsm = hsmClosure([...Object.values(lua), ...Object.values(companions)], compileHsmModules);
+  const hsmSourceMaps = hsm === undefined ? undefined : selectHsmSourceMaps(Object.keys(hsm));
 
   return {
     lua,
@@ -322,9 +327,22 @@ export function collectOutputs(
     ...(lualib !== undefined ? { lualib } : {}),
     ...(timersImported ? { timersRuntime: TIMERS_RUNTIME } : {}),
     ...(hsm !== undefined ? { hsmModules: hsm } : {}),
+    ...(hsmSourceMaps !== undefined ? { hsmSourceMaps } : {}),
   };
 }
 
+function selectHsmSourceMaps(names: readonly string[]): Record<string, string> {
+  const maps = compileHsmSourceMaps();
+  const selected: Record<string, string> = {};
+  for (const name of names) {
+    const map = maps[name];
+    if (map !== undefined) {
+      selected[name] = map;
+    }
+  }
+  return selected;
+}
+
 function transpileVirtual(
   files: Readonly<Record<string, string>>,
   companionEmit: ReturnType<typeof createCompanionEmitPlugin>,
@@ -382,7 +400,12 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
   );
 }
 
-let compiledHsm: Readonly<Record<string, string>> | undefined;
+interface CompiledHsm {
+  readonly lua: Readonly<Record<string, string>>;
+  readonly sourceMaps: Readonly<Record<string, string>>;
+}
+
+let compiledHsm: CompiledHsm | undefined;
 
 function requiresLualib(lua: string): boolean {
   return scanEmittedRequires(lua).some(({ path: requirePath }) => requirePath === "lualib_bundle");
@@ -398,6 +421,15 @@ function requiresLualib(lua: string): boolean {
  * lualib bundle.
  */
 export function compileHsmModules(): Readonly<Record<string, string>> {
+  return compileHsm().lua;
+}
+
+/** The source map of every module `compileHsmModules` returns, under the same keys. */
+export function compileHsmSourceMaps(): Readonly<Record<string, string>> {
+  return compileHsm().sourceMaps;
+}
+
+function compileHsm(): CompiledHsm {
   if (compiledHsm !== undefined) {
     return compiledHsm;
   }
@@ -417,6 +449,7 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
     (d) => `${d.file?.fileName ?? "(project)"}: ${flattenDiagnosticMessage(d.messageText)}`,
   );
   const lua: Record<string, string> = {};
+  const sourceMaps: Record<string, string> = {};
   for (const file of result.transpiledFiles) {
     if (isLualibBundle(file)) {
       continue;
@@ -430,14 +463,17 @@ export function compileHsmModules(): Readonly<Record<string, string>> {
       problems.push(`the compiled ${name} module requires lualib_bundle`);
     }
     lua[name] = file.lua;
+    if (typeof file.luaSourceMap === "string") {
+      sourceMaps[name] = file.luaSourceMap;
+    }
   }
   if (problems.length > 0) {
     throw new Error(
       `@defold-typescript/transpiler: the hsm library does not compile:\n  ${problems.join("\n  ")}`,
     );
   }
-  compiledHsm = lua;
-  return lua;
+  compiledHsm = { lua, sourceMaps };
+  return compiledHsm;
 }
 
 export function transpile(source: string): TranspileResult {