@defold-typescript/transpiler 0.36.0 → 0.38.0

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export type { ExtensionDependency, LibraryIncludedEntries, LibrarySceneDocument,
 export { archiveWrapperOf, isContainedResourcePath, LIBRARY_DEPENDENCY_ROOT, libraryIncludedEntries, readGameProjectDependencies, readLibrarySceneDocuments, } from "./library-dependencies";
 export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
 export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
-export { computeOutputRel, DEFAULT_INCLUDE, parseBuildConfig, requirePathForRel, SCRIPT_SUFFIX_BY_KIND, stripIncludeBase, } from "./output-paths";
+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";

package/dist/index.js

@@ -56,7 +56,7 @@ function resolvesToDispatchExport(callee, checker) {
   }
   return declaration.getSourceFile().fileName.includes(DISPATCH_MODULE);
 }
-function handlerName(property) {
+function handlerName(property, checker) {
   const name = property.name;
   if (name === undefined) {
     return;
@@ -64,8 +64,29 @@ function handlerName(property) {
   if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
     return name.text;
   }
+  if (ts.isNumericLiteral(name)) {
+    return String(Number(name.text));
+  }
+  if (ts.isComputedPropertyName(name)) {
+    const type = checker.getTypeAtLocation(name.expression);
+    if (type.isStringLiteral() || type.isNumberLiteral()) {
+      return String(type.value);
+    }
+  }
   return;
 }
+function unlowerableHandler(node, text) {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText: `${DISPATCH_NAME} cannot lower \`${text}\`: pass an object literal whose keys are an identifier, a quoted or numeric literal, or a computed literal constant, each with its handler written inline.`
+  };
+}
 function handlerFunction(property) {
   if (ts.isMethodDeclaration(property) && property.body !== undefined) {
     return property;
@@ -104,8 +125,11 @@ function handlerBody(fn, context) {
 var messageDispatchLoweringPlugin = {
   visitors: {
     [ts.SyntaxKind.CallExpression]: (node, context) => {
+      if (!resolvesToDispatchExport(node.expression, context.checker)) {
+        return context.superTransformExpression(node);
+      }
       const [handlersArg] = node.arguments;
-      if (node.arguments.length === 1 && handlersArg !== undefined && ts.isObjectLiteralExpression(handlersArg) && resolvesToDispatchExport(node.expression, context.checker)) {
+      if (node.arguments.length === 1 && handlersArg !== undefined && ts.isObjectLiteralExpression(handlersArg)) {
         let chain;
         const properties = [...handlersArg.properties];
         for (let i = properties.length - 1;i >= 0; i--) {
@@ -113,9 +137,11 @@ var messageDispatchLoweringPlugin = {
           if (property === undefined) {
             continue;
           }
-          const name = handlerName(property);
+          const name = handlerName(property, context.checker);
           const fn = handlerFunction(property);
           if (name === undefined || fn === undefined) {
+            const offending = property.name ?? property;
+            context.diagnostics.push(unlowerableHandler(property, offending.getText()));
             continue;
           }
           const condition = createBinaryExpression(createIdentifier("message_id"), createCallExpression(createIdentifier("hash"), [createStringLiteral(name)]), SyntaxKind2.EqualityOperator);
@@ -130,6 +156,8 @@ var messageDispatchLoweringPlugin = {
         ];
         return createFunctionExpression(createBlock(chain === undefined ? [] : [chain]), params, undefined, NodeFlags.Declaration, node);
       }
+      const offending = handlersArg ?? node;
+      context.diagnostics.push(unlowerableHandler(offending, offending.getText()));
       return context.superTransformExpression(node);
     }
   }
@@ -1993,6 +2021,17 @@ function stripIncludeBase(pattern) {
   const lastSlash = upToWildcard.lastIndexOf("/");
   return lastSlash === -1 ? "" : upToWildcard.slice(0, lastSlash + 1);
 }
+var ABSOLUTE_SPELLING_RE = /^(\/|\\\\|[A-Za-z]:[\\/])/;
+function projectRelativeBase(pattern) {
+  if (ABSOLUTE_SPELLING_RE.test(pattern)) {
+    return;
+  }
+  const base = path.posix.normalize(stripIncludeBase(pattern.split("\\").join("/")));
+  if (base === ".." || base.startsWith("../")) {
+    return;
+  }
+  return base === "." || base === "./" ? "" : base;
+}
 function relUnderOutDir(rel, config) {
   const { outDir, include } = config;
   if (outDir === undefined || outDir === "" || outDir === ".") {
@@ -2421,20 +2460,71 @@ function componentAddressesOf(documents, paths) {
   }
   return keys;
 }
-function bodyOf(keys) {
-  if (keys.length === 0)
+function bareScriptsOf(documents, paths) {
+  const agreed = new Map;
+  const record = (id, resource) => {
+    if (!agreed.has(id))
+      agreed.set(id, resource);
+    else if (agreed.get(id) !== resource)
+      agreed.set(id, undefined);
+  };
+  for (const [path, ids] of paths.componentsOf) {
+    const resources = paths.componentResourcesOf.get(path);
+    for (const id of ids)
+      record(id, resources?.get(id));
+  }
+  for (const [displayPath, text] of documents) {
+    let declarations;
+    try {
+      declarations = collectComponentDeclarations(parseSceneTextFormat(text), displayPath, []);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError))
+        throw error;
+      continue;
+    }
+    for (const id of declarations.ids)
+      record(id, declarations.resources.get(id));
+  }
+  return agreed;
+}
+function componentValuesOf(documents, paths, scriptModules) {
+  const values = new Map;
+  const moduleOf = (resource) => resource === undefined ? undefined : scriptModules.get(resource);
+  const keys = componentAddressesOf(documents, paths);
+  if (scriptModules.size === 0) {
+    for (const key of keys)
+      values.set(key, undefined);
+    return values;
+  }
+  const bare = bareScriptsOf(documents, paths);
+  for (const key of keys) {
+    const hash = key.indexOf("#");
+    const path = key.slice(0, hash);
+    const id = key.slice(hash + 1);
+    values.set(key, moduleOf(path === "" ? bare.get(id) : paths.componentResourcesOf.get(path)?.get(id)));
+  }
+  return values;
+}
+function bodyOf(values) {
+  if (values.size === 0)
     return "{}";
-  const members = keys.map((key) => `    ${JSON.stringify(key)}: true;
-`).sort().join("");
+  const members = [...values].map(([key, specifier]) => {
+    const value = specifier === undefined ? "true" : `typeof import(${JSON.stringify(specifier)}).default`;
+    return `    ${JSON.stringify(key)}: ${value};
+`;
+  }).sort().join("");
   return `{
 ${members}  }`;
 }
-function buildSceneAddressDeclaration(documents, roles) {
+function trueValues(keys) {
+  return new Map([...keys].map((key) => [key, undefined]));
+}
+function buildSceneAddressDeclaration(documents, roles, scriptModules = new Map) {
   const index = buildSceneObjectPathIndex(documents, roles);
-  const components = componentAddressesOf(documents, index);
+  const components = componentValuesOf(documents, index, scriptModules);
   return `${BANNER}
 declare global {
-  interface SceneGameObjectAddresses ${bodyOf([...index.paths])}
+  interface SceneGameObjectAddresses ${bodyOf(trueValues(index.paths))}
 
   interface SceneComponentAddresses ${bodyOf(components)}
 }
@@ -3901,6 +3991,7 @@ export {
   listProjectResourcePaths,
   parseBuildConfig,
   parseSceneTextFormat,
+  projectRelativeBase,
   readGameProjectDependencies,
   readGameProjectSetting,
   readLibrarySceneDocuments,

package/dist/output-paths.d.ts

@@ -8,6 +8,7 @@ export declare const DEFAULT_INCLUDE: string[];
 export declare const SCRIPT_SUFFIX_BY_KIND: Record<ScriptKind, string>;
 export declare function parseBuildConfig(raw: string): BuildConfig;
 export declare function stripIncludeBase(pattern: string): string;
+export declare function projectRelativeBase(pattern: string): string | undefined;
 /**
  * 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

package/dist/scene-address-declaration.d.ts

@@ -10,5 +10,11 @@ import type { SceneCollectionRoles } from "./scene-collection-roles";
  * byte-identical file, and a document map built in a different order emits the
  * same bytes as well; a `Set` iteration order leaking into the output would
  * make every regeneration rewrite the file and re-check the whole program.
+ *
+ * `scriptModules` maps a script resource a scene names to the import specifier
+ * of the program source that compiles to it, relative to the declaration file.
+ * A component address whose resource maps is written as that module's default
+ * export, so `msg.post` can read the script's messages off it; every other
+ * address stays `true`. Omitted, every address is `true`.
  */
-export declare function buildSceneAddressDeclaration(documents: ReadonlyMap<string, string>, roles: SceneCollectionRoles): string;
+export declare function buildSceneAddressDeclaration(documents: ReadonlyMap<string, string>, roles: SceneCollectionRoles, scriptModules?: ReadonlyMap<string, string>): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.36.0",
+  "version": "0.38.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.36.0",
+    "@defold-typescript/types": "0.38.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript-to-lua": "^1.36.0"
   }

package/src/index.ts

@@ -42,6 +42,7 @@ export {
   computeOutputRel,
   DEFAULT_INCLUDE,
   parseBuildConfig,
+  projectRelativeBase,
   requirePathForRel,
   SCRIPT_SUFFIX_BY_KIND,
   stripIncludeBase,

package/src/message-dispatch-lowering.ts

@@ -47,7 +47,10 @@ type HandlerFunction = (ts.MethodDeclaration | ts.FunctionExpression | ts.ArrowF
   body: ts.ConciseBody;
 };
 
-function handlerName(property: ts.ObjectLiteralElementLike): string | undefined {
+function handlerName(
+  property: ts.ObjectLiteralElementLike,
+  checker: ts.TypeChecker,
+): string | undefined {
   const name = property.name;
   if (name === undefined) {
     return undefined;
@@ -55,9 +58,31 @@ function handlerName(property: ts.ObjectLiteralElementLike): string | undefined
   if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
     return name.text;
   }
+  if (ts.isNumericLiteral(name)) {
+    return String(Number(name.text));
+  }
+  if (ts.isComputedPropertyName(name)) {
+    const type = checker.getTypeAtLocation(name.expression);
+    if (type.isStringLiteral() || type.isNumberLiteral()) {
+      return String(type.value);
+    }
+  }
   return undefined;
 }
 
+function unlowerableHandler(node: ts.Node, text: 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: `${DISPATCH_NAME} cannot lower \`${text}\`: pass an object literal whose keys are an identifier, a quoted or numeric literal, or a computed literal constant, each with its handler written inline.`,
+  };
+}
+
 function handlerFunction(property: ts.ObjectLiteralElementLike): HandlerFunction | undefined {
   if (ts.isMethodDeclaration(property) && property.body !== undefined) {
     return property as HandlerFunction;
@@ -108,12 +133,14 @@ function handlerBody(fn: HandlerFunction, context: TransformationContext): State
 export const messageDispatchLoweringPlugin: Plugin = {
   visitors: {
     [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      if (!resolvesToDispatchExport(node.expression, context.checker)) {
+        return context.superTransformExpression(node);
+      }
       const [handlersArg] = node.arguments;
       if (
         node.arguments.length === 1 &&
         handlersArg !== undefined &&
-        ts.isObjectLiteralExpression(handlersArg) &&
-        resolvesToDispatchExport(node.expression, context.checker)
+        ts.isObjectLiteralExpression(handlersArg)
       ) {
         let chain: IfStatement | undefined;
         const properties = [...handlersArg.properties];
@@ -122,9 +149,11 @@ export const messageDispatchLoweringPlugin: Plugin = {
           if (property === undefined) {
             continue;
           }
-          const name = handlerName(property);
+          const name = handlerName(property, context.checker);
           const fn = handlerFunction(property);
           if (name === undefined || fn === undefined) {
+            const offending = property.name ?? property;
+            context.diagnostics.push(unlowerableHandler(property, offending.getText()));
             continue;
           }
           const condition = createBinaryExpression(
@@ -149,6 +178,8 @@ export const messageDispatchLoweringPlugin: Plugin = {
           node,
         );
       }
+      const offending = handlersArg ?? node;
+      context.diagnostics.push(unlowerableHandler(offending, offending.getText()));
       return context.superTransformExpression(node);
     },
   },

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 === ".") {

package/src/scene-address-declaration.ts

@@ -1,6 +1,7 @@
 import type { SceneCollectionRoles } from "./scene-collection-roles";
-import { buildSceneComponentIndex } from "./scene-component-index";
+import { buildSceneComponentIndex, collectComponentDeclarations } from "./scene-component-index";
 import { buildSceneObjectPathIndex, type SceneObjectPathIndex } from "./scene-object-path-index";
+import { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
 
 const BANNER = `// Generated from this project's scenes by \`defold-typescript scene-types\`.
 // Do not edit: every run rewrites it from the .go/.collection sources.
@@ -28,19 +29,88 @@ function componentAddressesOf(
   return keys;
 }
 
+// What a component address resolves to: `true` for an address that names no
+// script this program compiles, else the specifier of the script module it hosts.
+type AddressValues = ReadonlyMap<string, string | undefined>;
+
+// A bare `#id` is typed only when every declaration of that id anywhere in the
+// project names the same mapped script. The per-object walk covers each object a
+// world reaches; the per-document pass covers what it cannot — a factory
+// prototype with no static path, an embedded component under the same id — so a
+// bare address never borrows one object's script for another's component.
+function bareScriptsOf(
+  documents: ReadonlyMap<string, string>,
+  paths: SceneObjectPathIndex,
+): Map<string, string | undefined> {
+  const agreed = new Map<string, string | undefined>();
+  const record = (id: string, resource: string | undefined): void => {
+    if (!agreed.has(id)) agreed.set(id, resource);
+    else if (agreed.get(id) !== resource) agreed.set(id, undefined);
+  };
+  for (const [path, ids] of paths.componentsOf) {
+    const resources = paths.componentResourcesOf.get(path);
+    for (const id of ids) record(id, resources?.get(id));
+  }
+  for (const [displayPath, text] of documents) {
+    let declarations: ReturnType<typeof collectComponentDeclarations>;
+    try {
+      declarations = collectComponentDeclarations(parseSceneTextFormat(text), displayPath, []);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      continue;
+    }
+    for (const id of declarations.ids) record(id, declarations.resources.get(id));
+  }
+  return agreed;
+}
+
+function componentValuesOf(
+  documents: ReadonlyMap<string, string>,
+  paths: SceneObjectPathIndex,
+  scriptModules: ReadonlyMap<string, string>,
+): AddressValues {
+  const values = new Map<string, string | undefined>();
+  const moduleOf = (resource: string | undefined): string | undefined =>
+    resource === undefined ? undefined : scriptModules.get(resource);
+  const keys = componentAddressesOf(documents, paths);
+  if (scriptModules.size === 0) {
+    for (const key of keys) values.set(key, undefined);
+    return values;
+  }
+  const bare = bareScriptsOf(documents, paths);
+  for (const key of keys) {
+    const hash = key.indexOf("#");
+    const path = key.slice(0, hash);
+    const id = key.slice(hash + 1);
+    values.set(
+      key,
+      moduleOf(path === "" ? bare.get(id) : paths.componentResourcesOf.get(path)?.get(id)),
+    );
+  }
+  return values;
+}
+
 // An interface with no members closes on the same line: an empty body written
 // across two lines is what a formatter would collapse, and the generated file
 // has to survive a consumer's formatter run byte-identical or every regeneration
 // looks like a change.
-function bodyOf(keys: readonly string[]): string {
-  if (keys.length === 0) return "{}";
-  const members = keys
-    .map((key) => `    ${JSON.stringify(key)}: true;\n`)
+function bodyOf(values: AddressValues): string {
+  if (values.size === 0) return "{}";
+  const members = [...values]
+    .map(([key, specifier]) => {
+      const value =
+        specifier === undefined ? "true" : `typeof import(${JSON.stringify(specifier)}).default`;
+      return `    ${JSON.stringify(key)}: ${value};\n`;
+    })
     .sort()
     .join("");
   return `{\n${members}  }`;
 }
 
+function trueValues(keys: Iterable<string>): AddressValues {
+  return new Map([...keys].map((key) => [key, undefined]));
+}
+
 /**
  * The global augmentation that fills `SceneGameObjectAddresses` and
  * `SceneComponentAddresses` from already-read scene sources — keys are
@@ -52,19 +122,26 @@ function bodyOf(keys: readonly string[]): string {
  * byte-identical file, and a document map built in a different order emits the
  * same bytes as well; a `Set` iteration order leaking into the output would
  * make every regeneration rewrite the file and re-check the whole program.
+ *
+ * `scriptModules` maps a script resource a scene names to the import specifier
+ * of the program source that compiles to it, relative to the declaration file.
+ * A component address whose resource maps is written as that module's default
+ * export, so `msg.post` can read the script's messages off it; every other
+ * address stays `true`. Omitted, every address is `true`.
  */
 export function buildSceneAddressDeclaration(
   documents: ReadonlyMap<string, string>,
   roles: SceneCollectionRoles,
+  scriptModules: ReadonlyMap<string, string> = new Map(),
 ): string {
   // One walk for both key sets: the qualified component addresses are the path
   // universe joined to its own prototypes, not a second index over the same files.
   const index = buildSceneObjectPathIndex(documents, roles);
-  const components = componentAddressesOf(documents, index);
+  const components = componentValuesOf(documents, index, scriptModules);
 
   return `${BANNER}
 declare global {
-  interface SceneGameObjectAddresses ${bodyOf([...index.paths])}
+  interface SceneGameObjectAddresses ${bodyOf(trueValues(index.paths))}
 
   interface SceneComponentAddresses ${bodyOf(components)}
 }