@defold-typescript/transpiler 0.29.0 → 0.31.0

package/src/scene-collection-roles.ts

@@ -0,0 +1,267 @@
+import { readGameProjectSetting } from "./config-key-index";
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
+
+// Which world each collection is, so an address can say where it resolves. A
+// game object's address has two axes — which world, then which path inside it —
+// and only these roles can tell them apart. Shaped like the indexes it feeds: a
+// non-empty `incomplete` means the classification is not provably whole, so no
+// consumer may conclude a collection has no role.
+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;
+}
+
+// The two places Defold embeds a whole escaped document in `data:`, the same
+// rule `buildSceneComponentIndex` states — every other `data:` is a plain scalar.
+const EMBEDDING_BLOCKS = new Set(["embedded_instances", "embedded_components"]);
+
+// A component reference and the field its document holds the target under: a
+// proxy names the collection it opens as a world, a factory names the prototype
+// it spawns copies of.
+const REFERENCE_KINDS = [
+  { extension: ".collectionproxy", type: "collectionproxy", field: "collection" },
+  { extension: ".collectionfactory", type: "collectionfactory", field: "prototype" },
+] as const;
+
+type ReferenceKind = (typeof REFERENCE_KINDS)[number];
+
+// Matches `scene-object-path-index.ts`: resource paths inside a scene are
+// project-absolute, documents are keyed by project-relative display path.
+function resourceKey(resource: string): string {
+  return resource.startsWith("/") ? resource.slice(1) : resource;
+}
+
+// `game.project` and a `.collectionproxy` name the *compiled* resource the
+// engine loads (`/main/main.collectionc`), not the source the walk read — the
+// same normalisation `resolveBootPathScripts` applies to its own boot walk.
+// Without it every real project fails to find its bootstrap world.
+function collectionKey(resource: string): string {
+  return resourceKey(resource).replace(/\.collectionc$/, ".collection");
+}
+
+function firstField(message: SceneMessage, name: string): string | undefined {
+  return (message.fields.get(name) ?? [])[0];
+}
+
+// Only a `.collection` is a world. A `.go` is a prototype, so running the role
+// rules over it would make every prototype in the project a role-less
+// "reachable no way" entry and drown the honest ones.
+function isCollection(displayPath: string): boolean {
+  return displayPath.endsWith(".collection");
+}
+
+/**
+ * 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 function buildSceneCollectionRoles(input: SceneCollectionRolesInput): SceneCollectionRoles {
+  const { documents, references, gameProject } = input;
+  const incomplete: string[] = [];
+
+  const parsed = new Map<string, SceneMessage>();
+  for (const [displayPath, text] of documents) {
+    try {
+      parsed.set(displayPath, parseSceneTextFormat(text));
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      incomplete.push(`${displayPath}: could not be parsed (${error.message})`);
+    }
+  }
+
+  const instanced = new Set<string>();
+  for (const document of parsed.values()) {
+    for (const block of document.messages.get("collection_instances") ?? []) {
+      const collection = firstField(block, "collection");
+      if (collection !== undefined) instanced.add(resourceKey(collection));
+    }
+  }
+
+  const proxied = new Set<string>();
+  const factoryPrototypes = new Set<string>();
+
+  function record(kind: ReferenceKind, resource: string): void {
+    (kind.type === "collectionproxy" ? proxied : factoryPrototypes).add(collectionKey(resource));
+  }
+
+  // A standalone reference is a component file of its own; its target lives in
+  // the reference document rather than in the scene that points at it, so a
+  // reference the walk never read is a named gap and not a dropped edge.
+  function followReferenceDocument(displayPath: string, resource: string): void {
+    const kind = REFERENCE_KINDS.find((candidate) => resource.endsWith(candidate.extension));
+    if (kind === undefined) return;
+    const text = references.get(resourceKey(resource));
+    if (text === undefined) {
+      incomplete.push(
+        `${displayPath}: the component ${resource} is not among the project's readable ${kind.extension} documents, so the collection it names is unclassified`,
+      );
+      return;
+    }
+    let document: SceneMessage;
+    try {
+      document = parseSceneTextFormat(text);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      incomplete.push(`${resourceKey(resource)}: could not be parsed (${error.message})`);
+      return;
+    }
+    const target = firstField(document, kind.field);
+    if (target === undefined) {
+      incomplete.push(
+        `${resourceKey(resource)}: declares no ${kind.field}:, so the collection it names is unclassified`,
+      );
+      return;
+    }
+    record(kind, target);
+  }
+
+  function walk(
+    message: SceneMessage,
+    blockName: string,
+    displayPath: string,
+    depth: number,
+  ): void {
+    if (blockName === "components") {
+      const component = firstField(message, "component");
+      if (component !== undefined) followReferenceDocument(displayPath, component);
+    }
+
+    const payloads: SceneMessage[] = [];
+    if (EMBEDDING_BLOCKS.has(blockName)) {
+      for (const payload of message.fields.get("data") ?? []) {
+        try {
+          payloads.push(parseSceneTextFormat(payload));
+        } catch (error) {
+          if (!(error instanceof SceneTextFormatError)) throw error;
+          incomplete.push(
+            `${displayPath}: embedded payload at depth ${depth + 1} could not be parsed (${error.message})`,
+          );
+        }
+      }
+    }
+
+    if (blockName === "embedded_components") {
+      const type = firstField(message, "type");
+      const kind = REFERENCE_KINDS.find((candidate) => candidate.type === type);
+      if (kind !== undefined) {
+        for (const payload of payloads) {
+          const target = firstField(payload, kind.field);
+          if (target === undefined) {
+            incomplete.push(
+              `${displayPath}: the embedded ${kind.type} declares no ${kind.field}:, so the collection it names is unclassified`,
+            );
+            continue;
+          }
+          record(kind, target);
+        }
+      }
+    }
+
+    for (const payload of payloads) walk(payload, "", displayPath, depth + 1);
+    for (const [name, nested] of message.messages) {
+      for (const child of nested) walk(child, name, displayPath, depth);
+    }
+  }
+
+  for (const [displayPath, document] of parsed) walk(document, "", displayPath, 0);
+
+  // The socket is the proxied collection's own `name:` — `CollectionDesc.name`,
+  // which the editor writes on the collection itself and which is deliberately
+  // neither the proxy component's id nor the file's basename.
+  const sockets = new Map<string, string>();
+  const byName = new Map<string, string[]>();
+  for (const displayPath of [...proxied].sort()) {
+    const document = parsed.get(displayPath);
+    if (document === undefined) {
+      incomplete.push(
+        `${displayPath}: is opened as a collection proxy but is not among the project's readable scene documents, so its world has no name`,
+      );
+      continue;
+    }
+    const name = firstField(document, "name");
+    if (name === undefined || name === "") {
+      incomplete.push(
+        `${displayPath}: is opened as a collection proxy but declares no name:, so its world cannot be addressed`,
+      );
+      continue;
+    }
+    sockets.set(displayPath, name);
+    byName.set(name, [...(byName.get(name) ?? []), displayPath]);
+  }
+  for (const [name, holders] of byName) {
+    if (holders.length > 1) {
+      incomplete.push(
+        `${holders.join(", ")}: all declare name: "${name}", so an address under that socket does not say which world it means`,
+      );
+    }
+  }
+
+  // A project the walk found no collection in has no world to name, so an
+  // absent `[bootstrap]` says nothing a reader could act on — the same posture
+  // `sceneIndexForBuild` takes towards a scene-less project. A project that does
+  // have collections is a different case: there the absence is exactly why no
+  // address is offered bare, so it is always named.
+  const hasCollections = [...parsed.keys()].some(isCollection);
+
+  let bootstrap: string | undefined;
+  if (gameProject === undefined) {
+    if (hasCollections) {
+      incomplete.push(
+        "game.project could not be read, so no collection is known to be the bootstrap world and no address is offered unqualified",
+      );
+    }
+  } else {
+    const main = readGameProjectSetting(gameProject, "bootstrap", "main_collection");
+    if (main === undefined) {
+      if (hasCollections) {
+        incomplete.push(
+          "game.project declares no [bootstrap] main_collection, so no collection is the bootstrap world",
+        );
+      }
+    } else if (!parsed.has(collectionKey(main))) {
+      incomplete.push(
+        `game.project names ${main} as [bootstrap] main_collection, which is not among the project's readable scene documents`,
+      );
+    } else {
+      bootstrap = collectionKey(main);
+    }
+  }
+
+  for (const displayPath of parsed.keys()) {
+    if (!isCollection(displayPath)) continue;
+    if (
+      displayPath === bootstrap ||
+      sockets.has(displayPath) ||
+      instanced.has(displayPath) ||
+      factoryPrototypes.has(displayPath)
+    ) {
+      continue;
+    }
+    incomplete.push(
+      `${displayPath}: is reached by no bootstrap, proxy, instance or factory reference, so which world its objects live in is unknown`,
+    );
+  }
+
+  return { bootstrap, sockets, instanced, factoryPrototypes, incomplete };
+}

package/src/scene-component-index.ts

@@ -20,23 +20,56 @@ const COMPONENT_BLOCKS = new Set(["components", "embedded_components"]);
 // projects as unreadable and suppress the check for good.
 const EMBEDDING_BLOCKS = new Set(["embedded_instances", "embedded_components"]);
 
+// A component id and the resource it references, where one is referenced at all.
+// The two axes are gathered by one pass because they are read off the same
+// block: a second walk over the same documents is exactly how the id universe
+// and the resource universe drift apart.
+export interface ComponentDeclarations {
+  readonly ids: Set<string>;
+  readonly resources: Map<string, string>;
+}
+
+// Resource paths inside a scene are project-absolute; documents are keyed by
+// project-relative display path, the same convention `resourceKey` follows in
+// `scene-object-path-index.ts`.
+function resourceKey(resource: string): string {
+  return resource.startsWith("/") ? resource.slice(1) : resource;
+}
+
 function collect(
   message: SceneMessage,
   blockName: string,
   depth: number,
   displayPath: string,
-  ids: Set<string>,
+  declarations: ComponentDeclarations,
   incomplete: string[],
 ): void {
   if (COMPONENT_BLOCKS.has(blockName)) {
-    for (const id of message.fields.get("id") ?? []) {
-      ids.add(id);
+    const declared = message.fields.get("id") ?? [];
+    for (const id of declared) {
+      declarations.ids.add(id);
+    }
+    // `embedded_components` is skipped on purpose: its payload *is* the
+    // component, so it names no resource and must never be credited with one.
+    if (blockName === "components") {
+      const [id] = declared;
+      const [component] = message.fields.get("component") ?? [];
+      if (id !== undefined && id !== "" && component !== undefined) {
+        declarations.resources.set(id, resourceKey(component));
+      }
     }
   }
   if (EMBEDDING_BLOCKS.has(blockName)) {
     for (const payload of message.fields.get("data") ?? []) {
       try {
-        collect(parseSceneTextFormat(payload), "", depth + 1, displayPath, ids, incomplete);
+        collect(
+          parseSceneTextFormat(payload),
+          "",
+          depth + 1,
+          displayPath,
+          declarations,
+          incomplete,
+        );
       } catch (error) {
         if (!(error instanceof SceneTextFormatError)) throw error;
         incomplete.push(
@@ -47,11 +80,44 @@ function collect(
   }
   for (const [name, nested] of message.messages) {
     for (const child of nested) {
-      collect(child, name, depth, displayPath, ids, incomplete);
+      collect(child, name, depth, displayPath, declarations, incomplete);
     }
   }
 }
 
+/**
+ * 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 function collectComponentDeclarations(
+  message: SceneMessage,
+  displayPath: string,
+  incomplete: string[],
+  blockName = "",
+): ComponentDeclarations {
+  const declarations: ComponentDeclarations = { ids: new Set(), resources: new Map() };
+  collect(message, blockName, 0, displayPath, declarations, incomplete);
+  return declarations;
+}
+
+/** The id half of {@link collectComponentDeclarations}, for callers that join no resources. */
+export function collectComponentIds(
+  message: SceneMessage,
+  displayPath: string,
+  incomplete: string[],
+  blockName = "",
+): Set<string> {
+  return collectComponentDeclarations(message, displayPath, incomplete, blockName).ids;
+}
+
 // Build the component-id universe from already-read scene sources: keys are
 // display paths, values are file text. Pure — the filesystem walk belongs to the
 // caller, so a test can drive this from inline strings and a build can drive it
@@ -69,7 +135,9 @@ export function buildSceneComponentIndex(
 
   for (const [displayPath, text] of documents) {
     try {
-      collect(parseSceneTextFormat(text), "", 0, displayPath, ids, incomplete);
+      for (const id of collectComponentIds(parseSceneTextFormat(text), displayPath, incomplete)) {
+        ids.add(id);
+      }
     } catch (error) {
       if (!(error instanceof SceneTextFormatError)) throw error;
       incomplete.push(`${displayPath}: could not be parsed (${error.message})`);

package/src/scene-documents.ts

@@ -0,0 +1,186 @@
+import { readLibrarySceneDocuments } from "./library-dependencies";
+import { isDefignoredPath } from "./project-resources";
+
+// The narrow slice of `ts.server.ServerHost` this needs: the real host
+// satisfies it structurally, and a test fake is two methods rather than a whole
+// server. `readDirectory` is optional because a host may not provide it, and a
+// plugin that throws takes the editor's completions down with it.
+export interface SceneReadHost {
+  readDirectory?(path: string, extensions?: readonly string[]): string[];
+  readFile(path: string): string | undefined;
+}
+
+export const SCENE_EXTENSIONS = [".go", ".collection"];
+
+// The extension sets more than one reader asks the host for. They live here
+// rather than beside either caller because the index cache serves exactly the
+// sets it is handed: a second definition that drifted would walk — and watch —
+// a universe the other reader never invalidates.
+export const GUI_EXTENSIONS = [".gui"];
+export const INPUT_BINDING_EXTENSIONS = [".input_binding"];
+
+// The component files that name a collection without instancing it: a
+// `.collectionproxy` opens it as its own world, a `.collectionfactory` spawns
+// copies of it at runtime. Deliberately not folded into `SCENE_EXTENSIONS`,
+// which would feed non-scene text to `buildSceneComponentIndex`.
+export const COLLECTION_REFERENCE_EXTENSIONS = [".collectionproxy", ".collectionfactory"];
+
+// The documents an animation id is declared by, plus every hop taken to reach
+// one: an atlas or tile source names a sprite's ids outright, a `.animationset`
+// names the files whose basenames are a model's ids, and a `.sprite` or
+// `.model` is the hop a referenced component takes to reach either.
+export const ANIMATION_ASSET_EXTENSIONS = [
+  ".atlas",
+  ".tilesource",
+  ".sprite",
+  ".model",
+  ".animationset",
+];
+
+// The file kinds a library shares into the address universe: the documents that
+// declare ids, plus the ones that *classify* a collection into the world it is —
+// a library's own `.collectionproxy` is what says its collection is a proxy
+// world rather than reached by nothing. `.input_binding` and `.project` are
+// deliberately absent: `game.project` names exactly one active binding file, and
+// a vendored `*.project` declares keys this project's readers cannot resolve —
+// the rule `PROJECT_EXTENSIONS` states below.
+//
+// It lives here rather than beside its reader for the reason the sets above do,
+// plus one more: `library-dependencies.ts` and this file import each other, and
+// a constant built from these arrays at that module's top level would read them
+// before this one had run.
+export const LIBRARY_SCENE_EXTENSIONS = [
+  ...SCENE_EXTENSIONS,
+  ...GUI_EXTENSIONS,
+  ...ANIMATION_ASSET_EXTENSIONS,
+  ...COLLECTION_REFERENCE_EXTENSIONS,
+];
+
+// The walk returns every `.project` the project holds, so the lookup is by
+// display path — a vendored `*.project` declares keys this project's readers
+// cannot resolve.
+export const PROJECT_EXTENSIONS = [".project"];
+export const GAME_PROJECT_DOCUMENT = "game.project";
+
+// The project-relative name a file is keyed by — the same name the editor
+// reports for a program file, so a scene's claim on a script can be looked up
+// against the file being edited.
+export function displayPathOf(projectRoot: string, filePath: string): string {
+  const path = filePath.replace(/\\/g, "/");
+  const root = projectRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+  return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}
+
+// What both walks exclude is what Defold does not load as a project resource:
+// `build/` output, plus the directories the scaffolded `.defignore` names
+// (`isDefignoredPath`, root-anchored because a `.defignore` line is a
+// root-relative path).
+//
+// Bob writes `_generated_*.go` copies of the project's scenes under `build/`;
+// reading them would report every id twice, against files no author edits. The
+// segment test runs on the project-relative path, so a project that itself
+// lives under a directory named `build` is not excluded wholesale — a different
+// rule from `.defignore`'s, because bob writes those copies below whatever
+// depth it is pointed at.
+function isBuildOutput(displayPath: string): boolean {
+  return displayPath.split("/").includes("build");
+}
+
+// The single rule, exported because the index cache filters watch events with
+// it: a copy in the watcher could drift from what the walks exclude, and an
+// event the walk would have ignored is exactly the event that must not throw the
+// cache away — bob writes `_generated_*.go` throughout a build.
+export function isExcludedProjectPath(displayPath: string): boolean {
+  return isBuildOutput(displayPath) || isDefignoredPath(displayPath);
+}
+
+// Read the project's own scene sources through the editor host — by default the
+// `.go`/`.collection` set the component-id universe is built from, or whatever
+// `extensions` names instead. The two universes stay disjoint: a `.gui` declares
+// node ids, not component ids, so folding it into the default would feed gui
+// text to `buildSceneComponentIndex`. Keys are project-relative display paths,
+// matching what `buildSceneComponentIndex` reports in `incomplete`, and every
+// file that could not be read is named in `unreadable` — a universe with a
+// silent hole cannot be reasoned about. `paths` names the host paths actually
+// read — what a watcher must be registered on, which cannot be reconstructed
+// from a display path for a file outside the project root.
+//
+// The universe is the project plus whatever `resolve` last materialized from its
+// library dependencies: a library document joins it under the merged Defold
+// resource path it is addressed by, with its origin recorded in `origins` rather
+// than folded into the key, and the project's own file wins a collision. Which
+// makes the universe only as current as the last `resolve` — so a dependency
+// that is declared but unresolved, unreadable or shadowed is a named
+// `unreadable` line, never a silent omission.
+export function readSceneDocuments(
+  host: SceneReadHost,
+  projectRoot: string,
+  extensions: readonly string[] = SCENE_EXTENSIONS,
+): {
+  documents: Map<string, string>;
+  origins: Map<string, string>;
+  unreadable: string[];
+  paths: string[];
+} {
+  const documents = new Map<string, string>();
+  const origins = new Map<string, string>();
+  const unreadable: string[] = [];
+  const paths: string[] = [];
+
+  if (!host.readDirectory) {
+    unreadable.push("the editor host cannot enumerate project files, so no scene source was read");
+    return { documents, origins, unreadable, paths };
+  }
+
+  for (const filePath of host.readDirectory(projectRoot, extensions)) {
+    const displayPath = displayPathOf(projectRoot, filePath);
+    if (isExcludedProjectPath(displayPath)) continue;
+    const text = host.readFile(filePath);
+    if (text === undefined) {
+      unreadable.push(`${displayPath}: could not be read`);
+      continue;
+    }
+    documents.set(displayPath, text);
+    paths.push(filePath);
+  }
+
+  const library = readLibrarySceneDocuments(host, projectRoot, extensions);
+  unreadable.push(...library.unreadable);
+  for (const { displayPath, hostPath, url, text } of library.documents) {
+    if (documents.has(displayPath)) {
+      unreadable.push(`${displayPath}: also declared by ${url}; the project's own file is used`);
+      continue;
+    }
+    documents.set(displayPath, text);
+    origins.set(displayPath, url);
+    paths.push(hostPath);
+  }
+
+  return { documents, origins, unreadable, paths };
+}
+
+// The project's own files of the given kinds, as the `/`-prefixed
+// project-relative paths a Defold resource property names. Nothing is read: a
+// resource path is the whole suggestion, so the walk is the entire universe.
+//
+// The extension filter is re-applied rather than trusted. `readSceneDocuments`
+// can take the host at its word because a wrong document merely contributes no
+// ids, but here a wrong file *is* the suggestion — a host that ignored its
+// `extensions` argument would turn a `.font` slot into a project-wide file dump.
+export function listProjectResourcePaths(
+  host: SceneReadHost,
+  projectRoot: string,
+  extensions: readonly string[],
+): Set<string> {
+  if (!host.readDirectory) return new Set();
+
+  const paths: string[] = [];
+  for (const filePath of host.readDirectory(projectRoot, extensions)) {
+    const displayPath = displayPathOf(projectRoot, filePath);
+    if (isExcludedProjectPath(displayPath)) continue;
+    if (!extensions.some((extension) => displayPath.endsWith(extension))) continue;
+    paths.push(`/${displayPath}`);
+  }
+
+  return new Set(paths.sort());
+}