@defold-typescript/transpiler 0.29.0 → 0.31.0

package/dist/library-dependencies.d.ts

@@ -0,0 +1,47 @@
+import { type SceneReadHost } from "./scene-documents";
+export interface ExtensionDependency {
+    readonly index: number;
+    readonly url: string;
+}
+export declare function readGameProjectDependencies(gameProjectText: string): ExtensionDependency[];
+export declare function archiveWrapperOf(entries: readonly string[]): string | undefined;
+export interface LibrarySharedEntry {
+    readonly entry: string;
+    readonly path: string;
+}
+export interface LibraryIncludedEntries {
+    readonly shared: LibrarySharedEntry[];
+    readonly reasons: string[];
+    readonly refused: string[];
+}
+export declare function isContainedResourcePath(path: string): boolean;
+export declare function libraryIncludedEntries(entries: readonly string[], gameProjectText: string | undefined): LibraryIncludedEntries;
+export declare const LIBRARY_DEPENDENCY_ROOT = ".defold-types/dependencies";
+export interface LibrarySceneDocument {
+    readonly displayPath: string;
+    readonly hostPath: string;
+    readonly url: string;
+    readonly text: string;
+}
+export interface LibrarySceneDocuments {
+    readonly documents: LibrarySceneDocument[];
+    readonly unreadable: string[];
+}
+/**
+ * The scene sources the project's resolved library dependencies contribute,
+ * read out of the surface `resolve` materialized.
+ *
+ * Each document is keyed by its **merged** Defold resource path, not by one
+ * namespaced with its origin: Defold folds a library's `[library] include_dirs`
+ * into the consuming project's root namespace, and `scene-object-path-index.ts`
+ * resolves a `collection: "/druid/foo.collection"` reference by exactly that
+ * key — so an origin-namespaced key would strand every cross-document
+ * reference. The origin travels beside the document instead.
+ *
+ * Every refusal is one `unreadable` line naming the URL where one is known: an
+ * absent or unusable manifest, a declared dependency the last `resolve` did not
+ * materialize, a materialized directory `game.project` no longer declares, and
+ * a file that would not read. A dependency that contributes nothing silently is
+ * exactly the hole `readSceneDocuments` promises not to have.
+ */
+export declare function readLibrarySceneDocuments(host: SceneReadHost, projectRoot: string, extensions?: readonly string[]): LibrarySceneDocuments;

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

@@ -0,0 +1,14 @@
+import type { SceneCollectionRoles } from "./scene-collection-roles";
+/**
+ * The global augmentation that fills `SceneGameObjectAddresses` and
+ * `SceneComponentAddresses` from already-read scene sources — keys are
+ * project-relative display paths, values are file text. `roles` says which
+ * world each collection is, so a path key carries the world it resolves in.
+ *
+ * Pure, like the two indexes it composes: the filesystem walk belongs to the
+ * caller. Keys are sorted so a project whose scenes did not change re-emits a
+ * 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.
+ */
+export declare function buildSceneAddressDeclaration(documents: ReadonlyMap<string, string>, roles: SceneCollectionRoles): string;

package/dist/scene-collection-roles.d.ts

@@ -0,0 +1,30 @@
+export interface SceneCollectionRoles {
+    /** The one collection `[bootstrap] main_collection` names, whose paths are bare. */
+    readonly bootstrap?: string | undefined;
+    /** Proxied collections, mapped to the socket `CollectionDesc.name` gives them. */
+    readonly sockets: ReadonlyMap<string, string>;
+    /** Collections another collection instances, whose paths exist only under that id. */
+    readonly instanced: ReadonlySet<string>;
+    /** Collection-factory prototypes, whose objects have no static path at all. */
+    readonly factoryPrototypes: ReadonlySet<string>;
+    readonly incomplete: readonly string[];
+}
+export interface SceneCollectionRolesInput {
+    /** The `.go`/`.collection` universe, keyed by display path. */
+    readonly documents: ReadonlyMap<string, string>;
+    /** The `.collectionproxy`/`.collectionfactory` documents, keyed by display path. */
+    readonly references: ReadonlyMap<string, string>;
+    /** `game.project`'s text, or `undefined` when the walk could not read it. */
+    readonly gameProject: string | undefined;
+}
+/**
+ * Classify every collection the project declares into the world it is: the one
+ * bootstrap root, a proxy world addressed through its own socket, a collection
+ * instanced inside another, or a factory prototype with no static address.
+ *
+ * Pure, like the indexes it feeds — the filesystem walk belongs to the caller.
+ * There is deliberately no everything-else-is-a-root fallback: that fallback is
+ * what offers a bare `/enemy` for an object living in another world, and losing
+ * a completion is safe where offering a false one is not.
+ */
+export declare function buildSceneCollectionRoles(input: SceneCollectionRolesInput): SceneCollectionRoles;

package/dist/scene-component-index.d.ts

@@ -1,5 +1,25 @@
+import { type SceneMessage } from "./scene-text-format";
 export interface SceneComponentIndex {
     readonly ids: ReadonlySet<string>;
     readonly incomplete: readonly string[];
 }
+export interface ComponentDeclarations {
+    readonly ids: Set<string>;
+    readonly resources: Map<string, string>;
+}
+/**
+ * Every component id one already-parsed scene message declares, plus the
+ * resource each *referenced* component names, following the two `data:`
+ * payloads Defold embeds a whole document in. Exported because the game-object
+ * path walk attributes components to the object that owns them and must read
+ * the same rule this index reads — a second collector is exactly how the two
+ * universes drift apart.
+ *
+ * `blockName` names the block `message` was taken from, because the `data:`
+ * re-parse is keyed off it: a whole document is `""`, while a single
+ * `embedded_instances` block has to say so or its payload is never opened.
+ */
+export declare function collectComponentDeclarations(message: SceneMessage, displayPath: string, incomplete: string[], blockName?: string): ComponentDeclarations;
+/** The id half of {@link collectComponentDeclarations}, for callers that join no resources. */
+export declare function collectComponentIds(message: SceneMessage, displayPath: string, incomplete: string[], blockName?: string): Set<string>;
 export declare function buildSceneComponentIndex(documents: ReadonlyMap<string, string>): SceneComponentIndex;

package/dist/scene-documents.d.ts

@@ -0,0 +1,21 @@
+export interface SceneReadHost {
+    readDirectory?(path: string, extensions?: readonly string[]): string[];
+    readFile(path: string): string | undefined;
+}
+export declare const SCENE_EXTENSIONS: string[];
+export declare const GUI_EXTENSIONS: string[];
+export declare const INPUT_BINDING_EXTENSIONS: string[];
+export declare const COLLECTION_REFERENCE_EXTENSIONS: string[];
+export declare const ANIMATION_ASSET_EXTENSIONS: string[];
+export declare const LIBRARY_SCENE_EXTENSIONS: string[];
+export declare const PROJECT_EXTENSIONS: string[];
+export declare const GAME_PROJECT_DOCUMENT = "game.project";
+export declare function displayPathOf(projectRoot: string, filePath: string): string;
+export declare function isExcludedProjectPath(displayPath: string): boolean;
+export declare function readSceneDocuments(host: SceneReadHost, projectRoot: string, extensions?: readonly string[]): {
+    documents: Map<string, string>;
+    origins: Map<string, string>;
+    unreadable: string[];
+    paths: string[];
+};
+export declare function listProjectResourcePaths(host: SceneReadHost, projectRoot: string, extensions: readonly string[]): Set<string>;

package/dist/scene-naming-context.d.ts

@@ -0,0 +1,66 @@
+import type { SceneObjectPathIndex } from "./scene-object-path-index";
+/**
+ * One place a script runs, and the addressing frame it runs in. At runtime an
+ * instance carries `m_CollectionPathHashState` seeded from its compiled id up
+ * to and including the last `/`, and `GetAbsoluteIdentifier` resolves a
+ * relative string by continuing that hash — so a relative address written in a
+ * script means one thing from this object and nothing anywhere else.
+ */
+export interface NamingContext {
+    /** The world-qualified composed path of the object hosting the script. */
+    readonly object: string;
+    /** The proxy socket this object lives behind, or `undefined` in the bootstrap world. */
+    readonly socket: string | undefined;
+    /**
+     * `object` through its last `/`, inclusive — the collection path a relative
+     * address continues. World-qualified by construction, so a relative address
+     * can never resolve across a world.
+     */
+    readonly prefix: string;
+}
+/**
+ * The proxy socket an address names, or `undefined` when it names none — a
+ * bootstrap-world path, a relative path, a bare `#fragment`.
+ *
+ * Defold's address grammar is `[socket:][path][#fragment]` with both bracketed
+ * halves optional, so `mylevel:`, `mylevel:enemy` and `mylevel:#body` are as
+ * socket-qualified as `mylevel:/path`. The socket is therefore read from the
+ * `:` delimiter rather than from a following `/`: the head is the address up to
+ * the first `/` or `#` (the whole address when it carries neither), and the
+ * socket is the text before that head's first `:`. A `:` inside a path segment
+ * (`/level:1/enemy`) is not a socket, because the `/` closes the head first,
+ * and an empty socket (`:path`) is none.
+ *
+ * Exported because a written address literal and a composed object path are the
+ * same shape: the cross-world check reads a socket out of source text with this
+ * one rule rather than a second reader that could disagree with the contexts it
+ * compares against.
+ */
+export declare function socketOfAddress(address: string): string | undefined;
+/**
+ * Every naming context each script resource runs in, keyed by that resource and
+ * sorted by object path.
+ *
+ * `guiScripts` maps a `.gui` display path to the gui-script resource it names,
+ * which the caller builds with `guiScriptResourceOf` — the walk needs no `.gui`
+ * documents of its own.
+ *
+ * A script hosted by several objects has several contexts, and that is not
+ * ambiguity: a `.go` instanced in two collections genuinely runs in both, and
+ * it is the consumer's provenance that tells an author which context an entry
+ * resolves from.
+ */
+export declare function buildScriptNamingContexts(index: SceneObjectPathIndex, guiScripts: ReadonlyMap<string, string>): ReadonlyMap<string, readonly NamingContext[]>;
+/**
+ * The relative forms a script may write from one naming context: every object
+ * path under the context's prefix with that prefix stripped, and each of those
+ * joined to the components its object owns.
+ *
+ * An object `componentsOf` withheld still contributes its path — the object is
+ * provably there — but no `#component` join, because which components it owns
+ * was never read.
+ */
+export declare function relativeAddressesFrom(index: SceneObjectPathIndex, context: NamingContext): {
+    readonly paths: ReadonlySet<string>;
+    readonly addresses: ReadonlySet<string>;
+};

package/dist/scene-object-path-index.d.ts

@@ -1,6 +1,9 @@
+import type { SceneCollectionRoles } from "./scene-collection-roles";
 export interface SceneObjectPathIndex {
     readonly paths: ReadonlySet<string>;
     readonly declaredIn: ReadonlyMap<string, readonly string[]>;
+    readonly componentsOf: ReadonlyMap<string, readonly string[]>;
+    readonly componentResourcesOf: ReadonlyMap<string, ReadonlyMap<string, string>>;
     readonly incomplete: readonly string[];
 }
-export declare function buildSceneObjectPathIndex(documents: ReadonlyMap<string, string>): SceneObjectPathIndex;
+export declare function buildSceneObjectPathIndex(documents: ReadonlyMap<string, string>, roles: SceneCollectionRoles): SceneObjectPathIndex;

package/dist/url-address-literals.d.ts

@@ -0,0 +1,10 @@
+import * as ts from "typescript";
+export declare function isAmbient(fileName: string): boolean;
+export declare function canonicalHashSymbols(checker: ts.TypeChecker, program: ts.Program): ReadonlySet<ts.Symbol>;
+/**
+ * The address text a slot expression is statically known to carry — a quoted or
+ * backtick-quoted literal's own text, or the string a `Hash`-typed value was
+ * hashed from — and `undefined` for everything a project only settles at
+ * runtime: a substituted template, a bare `Hash`, a `Url`, a `string`.
+ */
+export declare function staticAddressTextOf(checker: ts.TypeChecker, node: ts.Expression, canonical: ReadonlySet<ts.Symbol>): string | undefined;

package/dist/url-address-slots.d.ts

@@ -1,4 +1,4 @@
-import type { UrlParameterClass, UrlParameterTable } from "@defold-typescript/types";
+import type { UrlParameterClass, UrlParameterEntry, UrlParameterTable } from "@defold-typescript/types";
 import * as ts from "typescript";
 export interface ClassifiedSlot {
     readonly class: UrlParameterClass;
@@ -6,10 +6,12 @@ export interface ClassifiedSlot {
     readonly textStart: number;
     readonly fragmentStart: number;
     readonly addressText?: string;
+    readonly nodeParameter?: string;
     readonly resourceExtensions?: readonly string[];
 }
 export declare function isAddressClass(parameterClass: UrlParameterClass): boolean;
 export declare function isFragmentCaret(slot: ClassifiedSlot, position: number): boolean;
+export declare function addressEntryOfArgument(checker: ts.TypeChecker, table: UrlParameterTable, argument: ts.Expression): UrlParameterEntry | undefined;
 export declare function addressClassOfArgument(checker: ts.TypeChecker, table: UrlParameterTable, argument: ts.Expression): UrlParameterClass;
 export declare function resolveClassifiedSlotAtPosition(input: {
     program: ts.Program;

package/dist/url-cross-world-address.d.ts

@@ -0,0 +1,41 @@
+import type { UrlParameterEntry, UrlParameterTable } from "@defold-typescript/types";
+import * as ts from "typescript";
+/** One address naming a world the script writing it cannot reach. */
+export interface CrossWorldAddressFinding {
+    readonly fileName: string;
+    readonly start: number;
+    readonly length: number;
+    /** The statically-known address text, as written or as hashed. */
+    readonly address: string;
+    /** The foreign proxy socket that text names. */
+    readonly socket: string;
+    readonly message: string;
+}
+/**
+ * Whether this slot refuses a socket-qualified address naming another world.
+ *
+ * The negation of `slotAcceptsForeignSocket` in `@defold-typescript/types`, and
+ * deliberately fails open the same way: a slot carrying no judgment refuses
+ * nothing, so nothing is reported on a slot nobody classified.
+ */
+export declare function slotRejectsForeignSocket(entry: UrlParameterEntry): boolean;
+/**
+ * Report every address-slot expression whose statically-known text names a proxy
+ * socket the script writing it does not run in, at a slot that resolves through
+ * an instance or component handle rather than the message bus.
+ *
+ * Deliberately not folded into `checkUrlFragmentReachability`: that check
+ * suppresses index-wide on an incomplete component universe, while this one's
+ * honesty rule is per file — a script whose naming contexts could not be
+ * resolved is reported on at all, because unknown is not wrong. Fusing them
+ * would put one check's early return in front of the other's findings.
+ *
+ * `worldsOf` answers with the sockets of every naming context the file's script
+ * runs in; an empty answer is the unknown case and yields nothing.
+ */
+export declare function checkCrossWorldAddresses(input: {
+    program: ts.Program;
+    table: UrlParameterTable;
+    worldsOf: (fileName: string) => readonly (string | undefined)[];
+    sourceFiles?: readonly ts.SourceFile[];
+}): readonly CrossWorldAddressFinding[];

package/dist/url-fragment-reachability.d.ts

@@ -1,6 +1,7 @@
 import type { UrlParameterTable } from "@defold-typescript/types";
 import * as ts from "typescript";
 import type { SceneComponentIndex } from "./scene-component-index";
+import type { SceneObjectPathIndex } from "./scene-object-path-index";
 export interface UrlFragmentFinding {
     readonly fileName: string;
     readonly start: number;
@@ -8,6 +9,7 @@ export interface UrlFragmentFinding {
     readonly fragment: string;
     readonly message: string;
 }
+export type SceneObjectComponents = Pick<SceneObjectPathIndex, "paths" | "componentsOf" | "incomplete">;
 export type UrlFragmentReport = {
     readonly kind: "suppressed";
     readonly reasons: readonly string[];
@@ -19,5 +21,6 @@ export declare function checkUrlFragmentReachability(input: {
     program: ts.Program;
     table: UrlParameterTable;
     index: SceneComponentIndex;
+    objects?: SceneObjectComponents;
     sourceFiles?: readonly ts.SourceFile[];
 }): UrlFragmentReport;

package/package.json

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

package/src/animation-sources.ts

@@ -0,0 +1,90 @@
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
+
+// Resource paths inside a scene are project-absolute; an index keyed off one
+// drops the leading `/`, so a caller maps the file it holds forward through the
+// build's output-path math and looks the result up.
+export function resourceKey(resource: string): string {
+  return resource.startsWith("/") ? resource.slice(1) : resource;
+}
+
+// The keys a caller supplies name files on the host, so they may arrive with
+// native separators; the resource paths they are matched against come out of
+// scene content and are always `/`-separated. Normalizing here enforces that
+// contract at the boundary instead of leaving it to whichever caller happens
+// to build the maps.
+export function normalizeDocumentKey(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+const SPRITE_SUFFIX = ".sprite";
+const MODEL_SUFFIX = ".model";
+const ANIMATION_SET_SUFFIX = ".animationset";
+
+// The documents that carry only a hop to the ids, never the ids themselves: a
+// `.sprite` names its tile source, a `.model` names its animation set, and a
+// `.animationset` names the files whose basenames are the ids. Reading any of
+// them for `animations { id: … }` yields an empty set that is indistinguishable
+// from a real source declaring nothing.
+const HOP_ONLY_SUFFIXES = [SPRITE_SUFFIX, MODEL_SUFFIX, ANIMATION_SET_SUFFIX];
+
+function childrenOf(message: SceneMessage, name: string): readonly SceneMessage[] {
+  return message.messages.get(name) ?? [];
+}
+
+// Only `animations { id: … }` counts. Defold may also expose a bare
+// `images { image: … }` entry as a one-frame animation named after the file,
+// which is unverified here — and a wrong suggestion in an animation slot is a
+// runtime crash rather than a no-op.
+export function declaredAnimations(document: SceneMessage): Set<string> {
+  const ids = new Set<string>();
+  for (const animation of childrenOf(document, "animations")) {
+    for (const id of animation.fields.get("id") ?? []) {
+      if (id !== "") ids.add(id);
+    }
+  }
+  return ids;
+}
+
+// The animation ids every asset document declares, keyed by display path, with
+// each unreadable document named in `unresolved` instead of silently declaring
+// nothing. The hop-only kinds are skipped: they declare no ids of their own,
+// only the path to the document that does, which their own readers parse them
+// for.
+//
+// One reader for both animation indexes, so a sprite component and a gui
+// texture can never disagree about what an atlas declares.
+export function readAnimationSources(
+  assets: ReadonlyMap<string, string>,
+  unresolved: string[],
+): Map<string, Set<string>> {
+  const animationsByTileSet = new Map<string, Set<string>>();
+  for (const [path, text] of assets) {
+    const displayPath = normalizeDocumentKey(path);
+    if (HOP_ONLY_SUFFIXES.some((suffix) => displayPath.endsWith(suffix))) continue;
+    let document: SceneMessage;
+    try {
+      document = parseSceneTextFormat(text);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
+      continue;
+    }
+    animationsByTileSet.set(displayPath, declaredAnimations(document));
+  }
+  return animationsByTileSet;
+}
+
+// The entry paths a `.animationset` lists, in document order. The values are
+// resource paths, not ids: `AnimationSetBuilder` stamps the owning set's name
+// on every animation a file contains, so the id an entry contributes is derived
+// from its path rather than read out of the file it names. Empty values are
+// dropped the way an empty animation id is.
+export function animationSetEntries(document: SceneMessage): string[] {
+  const entries: string[] = [];
+  for (const entry of childrenOf(document, "animations")) {
+    for (const animation of entry.fields.get("animation") ?? []) {
+      if (animation !== "") entries.push(animation);
+    }
+  }
+  return entries;
+}