@defold-typescript/transpiler 0.29.0 → 0.31.0

package/src/index.ts

@@ -1,7 +1,33 @@
-export { buildConfigKeyIndex } from "./config-key-index";
+export type { ComponentAnimationIndex } from "./component-animation-index";
+export {
+  buildComponentAnimationIndex,
+  componentIdOfSameObjectAddress,
+} from "./component-animation-index";
+export { buildConfigKeyIndex, readGameProjectSetting } from "./config-key-index";
+export type { GuiFlipbookIndex } from "./gui-flipbook-index";
+export { buildGuiFlipbookIndex } from "./gui-flipbook-index";
 export type { GuiNodeIndex } from "./gui-node-index";
-export { buildGuiNodeIndex } from "./gui-node-index";
+export {
+  buildGuiNodeIndex,
+  guiScriptResourceOf,
+  guiScriptResourcesOf,
+} from "./gui-node-index";
 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 { findMainEntryFactoryImports } from "./main-entry-factory-imports";
 export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
 export {
@@ -13,19 +39,42 @@ export {
 } from "./output-paths";
 export { getProgramDiagnostics } from "./program-diagnostics";
 export { isDefignoredPath, SCAFFOLDED_DEFIGNORE_LINES } from "./project-resources";
-export type { SceneComponentIndex } from "./scene-component-index";
-export { buildSceneComponentIndex } from "./scene-component-index";
+export { buildSceneAddressDeclaration } from "./scene-address-declaration";
+export type { SceneCollectionRoles, SceneCollectionRolesInput } from "./scene-collection-roles";
+export { buildSceneCollectionRoles } from "./scene-collection-roles";
+export type { ComponentDeclarations, SceneComponentIndex } from "./scene-component-index";
+export {
+  buildSceneComponentIndex,
+  collectComponentDeclarations,
+  collectComponentIds,
+} from "./scene-component-index";
+export type { SceneReadHost } from "./scene-documents";
+export {
+  ANIMATION_ASSET_EXTENSIONS,
+  COLLECTION_REFERENCE_EXTENSIONS,
+  displayPathOf,
+  GAME_PROJECT_DOCUMENT,
+  GUI_EXTENSIONS,
+  INPUT_BINDING_EXTENSIONS,
+  isExcludedProjectPath,
+  LIBRARY_SCENE_EXTENSIONS,
+  listProjectResourcePaths,
+  PROJECT_EXTENSIONS,
+  readSceneDocuments,
+  SCENE_EXTENSIONS,
+} from "./scene-documents";
+export type { NamingContext } from "./scene-naming-context";
+export {
+  buildScriptNamingContexts,
+  relativeAddressesFrom,
+  socketOfAddress,
+} from "./scene-naming-context";
 export type { SceneObjectPathIndex } from "./scene-object-path-index";
 export { buildSceneObjectPathIndex } from "./scene-object-path-index";
 export type { SceneMessage } from "./scene-text-format";
 export { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
 export type { TranspileSession } from "./session";
 export { createTranspileSession } from "./session";
-export type { SpriteAnimationIndex } from "./sprite-animation-index";
-export {
-  buildSpriteAnimationIndex,
-  componentIdOfSameObjectAddress,
-} from "./sprite-animation-index";
 export type {
   TranspileDiagnostic,
   TranspileProjectInput,
@@ -36,9 +85,16 @@ export { transpile, transpileProject } from "./transpile";
 export type { ClassifiedSlot } from "./url-address-slots";
 export {
   addressClassOfArgument,
+  addressEntryOfArgument,
   isAddressClass,
   isFragmentCaret,
   resolveClassifiedSlotAtPosition,
 } from "./url-address-slots";
-export type { UrlFragmentFinding, UrlFragmentReport } from "./url-fragment-reachability";
+export type { CrossWorldAddressFinding } from "./url-cross-world-address";
+export { checkCrossWorldAddresses, slotRejectsForeignSocket } from "./url-cross-world-address";
+export type {
+  SceneObjectComponents,
+  UrlFragmentFinding,
+  UrlFragmentReport,
+} from "./url-fragment-reachability";
 export { checkUrlFragmentReachability } from "./url-fragment-reachability";

package/src/library-dependencies.ts

@@ -0,0 +1,337 @@
+// What a Defold library dependency declares and what it actually shares. Both
+// halves live here rather than beside the CLI resolver because the scene walk
+// needs them too: it must read the declared set to tell an unresolved dependency
+// from an absent one, and `packages/transpiler` cannot import `packages/cli`.
+//
+// `game.project` is read as the flat INI the editor writes, the same shape
+// `buildConfigKeyIndex` walks — a key may carry a `#` (`dependencies#0`), which
+// is part of its name and never a fragment.
+
+import {
+  displayPathOf,
+  GAME_PROJECT_DOCUMENT,
+  LIBRARY_SCENE_EXTENSIONS,
+  type SceneReadHost,
+} from "./scene-documents";
+
+export interface ExtensionDependency {
+  readonly index: number;
+  readonly url: string;
+}
+
+function isProjectHeader(line: string): boolean {
+  return line.trim() === "[project]";
+}
+
+function isSectionHeader(line: string): boolean {
+  return /^\[.+\]\s*$/.test(line.trim());
+}
+
+export function readGameProjectDependencies(gameProjectText: string): ExtensionDependency[] {
+  const lines = gameProjectText.split("\n");
+  const deps: ExtensionDependency[] = [];
+  let inProject = false;
+  for (const line of lines) {
+    if (isSectionHeader(line)) {
+      inProject = isProjectHeader(line);
+      continue;
+    }
+    if (!inProject) {
+      continue;
+    }
+    const match = line.match(/^dependencies#(\d+)\s*=\s*(.+)$/);
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      deps.push({ index: Number(match[1]), url: match[2] });
+    }
+  }
+  return deps;
+}
+
+// The leading directory every entry sits under — GitHub packs an archive under
+// `<repo>-<ref>/`, but a hand-rolled zip may not, and stripping a segment that
+// is not shared would rebase a real directory away.
+export function archiveWrapperOf(entries: readonly string[]): string | undefined {
+  let wrapper: string | undefined;
+  for (const entry of entries) {
+    const separator = entry.indexOf("/");
+    if (separator <= 0) {
+      return undefined;
+    }
+    const segment = entry.slice(0, separator);
+    if (wrapper === undefined) {
+      wrapper = segment;
+    } else if (wrapper !== segment) {
+      return undefined;
+    }
+  }
+  return wrapper;
+}
+
+function readLibraryIncludeDirs(gameProjectText: string): string[] {
+  let inLibrary = false;
+  for (const line of gameProjectText.split("\n")) {
+    if (isSectionHeader(line)) {
+      inLibrary = line.trim() === "[library]";
+      continue;
+    }
+    if (!inLibrary) {
+      continue;
+    }
+    const match = line.match(/^include_dirs\s*=\s*(.*)$/);
+    if (match?.[1] !== undefined) {
+      return match[1]
+        .split(",")
+        .map((dir) => dir.trim())
+        .filter((dir) => dir.length > 0);
+    }
+  }
+  return [];
+}
+
+export interface LibrarySharedEntry {
+  readonly entry: string;
+  readonly path: string;
+}
+
+export interface LibraryIncludedEntries {
+  readonly shared: LibrarySharedEntry[];
+  readonly reasons: string[];
+  // The entries that named an include dir and a scene kind but whose merged
+  // resource path would not stay inside it.
+  readonly refused: string[];
+}
+
+// The one containment rule both halves of the dependency surface read: the
+// reader refuses to share a path this rejects, and the CLI writer re-asserts it
+// before touching disk. A path only ever addresses something below its own root
+// when it is relative, canonical, and uses the single separator Defold does —
+// `path.join` normalizes `..` away rather than refusing it, and treats `\` as a
+// separator on Windows only, so neither can be left to it.
+export function isContainedResourcePath(path: string): boolean {
+  if (path.length === 0 || path.includes("\\")) {
+    return false;
+  }
+  return path
+    .split("/")
+    .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+
+// The scene sources a library actually shares: the entries under the directories
+// its own `game.project` names, at the resource path Defold itself would address
+// them by (wrapper stripped, include dir kept — a library's `druid/druid.gui` is
+// `/druid/druid.gui` in a project that depends on it).
+export function libraryIncludedEntries(
+  entries: readonly string[],
+  gameProjectText: string | undefined,
+): LibraryIncludedEntries {
+  if (gameProjectText === undefined) {
+    return {
+      shared: [],
+      reasons: ["ships no game.project, so it declares no [library] include_dirs"],
+      refused: [],
+    };
+  }
+
+  const includeDirs = new Set(readLibraryIncludeDirs(gameProjectText));
+  if (includeDirs.size === 0) {
+    return {
+      shared: [],
+      reasons: ["its game.project declares no [library] include_dirs"],
+      refused: [],
+    };
+  }
+
+  const wrapper = archiveWrapperOf(entries);
+  const shared: LibrarySharedEntry[] = [];
+  const refused: string[] = [];
+  for (const entry of entries) {
+    const path = wrapper === undefined ? entry : entry.slice(wrapper.length + 1);
+    const [head] = path.split("/");
+    if (head === undefined || !includeDirs.has(head)) {
+      continue;
+    }
+    const dot = path.lastIndexOf(".");
+    if (dot === -1 || !LIBRARY_SCENE_EXTENSIONS.includes(path.slice(dot).toLowerCase())) {
+      continue;
+    }
+    // Applied last so `refused` names only what was otherwise going to be
+    // shared: `../evil.collection` never named an include dir to begin with.
+    if (!isContainedResourcePath(path)) {
+      refused.push(entry);
+      continue;
+    }
+    shared.push({ entry, path });
+  }
+  shared.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { shared, reasons: [], refused };
+}
+
+// The gitignored surface `resolve` unpacks each dependency's shared scene
+// sources into, project-relative. Exported because the editor's index cache has
+// to recognize an event under it: a literal there would drift from the path the
+// walk composes.
+export const LIBRARY_DEPENDENCY_ROOT = ".defold-types/dependencies";
+const LIBRARY_DEPENDENCY_MANIFEST = `${LIBRARY_DEPENDENCY_ROOT}/dependencies.json`;
+
+export interface LibrarySceneDocument {
+  // The merged Defold resource path this document is addressed by, which is the
+  // key the whole universe shares — see the composition note below.
+  readonly displayPath: string;
+  // Where the host holds it, so a watcher can be registered on the real file.
+  readonly hostPath: string;
+  readonly url: string;
+  readonly text: string;
+}
+
+export interface LibrarySceneDocuments {
+  readonly documents: LibrarySceneDocument[];
+  readonly unreadable: string[];
+}
+
+function joinProject(projectRoot: string, relative: string): string {
+  return `${projectRoot.replace(/\\/g, "/").replace(/\/+$/, "")}/${relative}`;
+}
+
+// `undefined` for anything this cannot be read as: a manifest that is not JSON
+// and one whose shape says nothing about dependencies are the same hole to a
+// caller, and both are repaired the same way.
+function readMaterializedKeys(manifestText: string): Map<string, string> | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(manifestText);
+  } catch {
+    return undefined;
+  }
+  const entries = (parsed as { dependencies?: unknown } | null)?.dependencies;
+  if (!Array.isArray(entries)) return undefined;
+
+  const keyByUrl = new Map<string, string>();
+  for (const entry of entries) {
+    const { key, url } = (entry ?? {}) as { key?: unknown; url?: unknown };
+    if (typeof key === "string" && typeof url === "string") keyByUrl.set(url, key);
+  }
+  return keyByUrl;
+}
+
+/**
+ * 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 function readLibrarySceneDocuments(
+  host: SceneReadHost,
+  projectRoot: string,
+  extensions: readonly string[] = LIBRARY_SCENE_EXTENSIONS,
+): LibrarySceneDocuments {
+  const documents: LibrarySceneDocument[] = [];
+  const unreadable: string[] = [];
+
+  if (!host.readDirectory) return { documents, unreadable };
+
+  const gameProjectText = host.readFile(joinProject(projectRoot, GAME_PROJECT_DOCUMENT));
+  if (gameProjectText === undefined) return { documents, unreadable };
+
+  const declared = [...readGameProjectDependencies(gameProjectText)].sort(
+    (a, b) => a.index - b.index,
+  );
+  if (declared.length === 0) return { documents, unreadable };
+
+  const manifestText = host.readFile(joinProject(projectRoot, LIBRARY_DEPENDENCY_MANIFEST));
+  if (manifestText === undefined) {
+    for (const { url } of declared) {
+      unreadable.push(
+        `${url}: is declared by game.project but ${LIBRARY_DEPENDENCY_MANIFEST} is absent`,
+      );
+    }
+    return { documents, unreadable };
+  }
+
+  const keyByUrl = readMaterializedKeys(manifestText);
+  if (keyByUrl === undefined) {
+    for (const { url } of declared) {
+      unreadable.push(
+        `${url}: is declared by game.project but ${LIBRARY_DEPENDENCY_MANIFEST} is not a readable dependency manifest`,
+      );
+    }
+    return { documents, unreadable };
+  }
+
+  // Declared order decides a collision between two libraries, the way the
+  // `dependencies#N` order does in Defold itself — a host's directory order
+  // must not.
+  const resolved: { key: string; url: string }[] = [];
+  const urlByKey = new Map<string, string>();
+  for (const { url } of declared) {
+    const key = keyByUrl.get(url);
+    if (key === undefined) {
+      unreadable.push(
+        `${url}: is declared by game.project but was not materialized by the last resolve`,
+      );
+      continue;
+    }
+    resolved.push({ key, url });
+    urlByKey.set(key, url);
+  }
+
+  const root = joinProject(projectRoot, LIBRARY_DEPENDENCY_ROOT);
+  const filesByKey = new Map<string, string[]>();
+  const stray = new Set<string>();
+  for (const filePath of host.readDirectory(root, extensions)) {
+    const relative = displayPathOf(root, filePath);
+    // A host that answered for some directory other than the one it was handed
+    // would otherwise have its files keyed as though they sat under a
+    // dependency.
+    if (relative === filePath.replace(/\\/g, "/")) continue;
+    const separator = relative.indexOf("/");
+    if (separator <= 0) continue;
+    const key = relative.slice(0, separator);
+    const url = urlByKey.get(key);
+    if (url === undefined) {
+      stray.add(key);
+      continue;
+    }
+    const bucket = filesByKey.get(key);
+    if (bucket === undefined) filesByKey.set(key, [filePath]);
+    else bucket.push(filePath);
+  }
+
+  const claimed = new Map<string, string>();
+  for (const { key, url } of resolved) {
+    for (const hostPath of (filesByKey.get(key) ?? []).sort()) {
+      const displayPath = displayPathOf(root, hostPath).slice(key.length + 1);
+      if (displayPath === "") continue;
+      const owner = claimed.get(displayPath);
+      if (owner !== undefined) {
+        unreadable.push(`${displayPath}: also declared by ${url}; ${owner}'s file is used`);
+        continue;
+      }
+      const text = host.readFile(hostPath);
+      if (text === undefined) {
+        unreadable.push(`${displayPath}: could not be read from ${url}`);
+        continue;
+      }
+      claimed.set(displayPath, url);
+      documents.push({ displayPath, hostPath, url, text });
+    }
+  }
+
+  for (const key of [...stray].sort()) {
+    unreadable.push(
+      `${LIBRARY_DEPENDENCY_ROOT}/${key}: is materialized but no longer declared by game.project, so its scenes are left out`,
+    );
+  }
+
+  return { documents, unreadable };
+}

package/src/scene-address-declaration.ts

@@ -0,0 +1,74 @@
+import type { SceneCollectionRoles } from "./scene-collection-roles";
+import { buildSceneComponentIndex } from "./scene-component-index";
+import { buildSceneObjectPathIndex, type SceneObjectPathIndex } from "./scene-object-path-index";
+
+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.
+//
+// Each key is an address the project declares. The aliases in
+// \`@defold-typescript/types\` stay widened with \`(string & {})\`, so these keys
+// only add completions — an address composed at runtime is never rejected.
+`;
+
+// Two forms, from two universes that *are* joined now. `buildSceneComponentIndex`
+// reports bare component ids with no owning object, so the same-object form
+// `#id` stays the whole address it can prove on its own — a `/path#id` key built
+// from it alone would be a cross product claiming every object owns every
+// component. The object-qualified form comes instead from the path walk's
+// `componentsOf`, which attributes each id to the one object whose prototype
+// declared it, and so carries the same world axis a path key does.
+function componentAddressesOf(
+  documents: ReadonlyMap<string, string>,
+  paths: SceneObjectPathIndex,
+): string[] {
+  const keys = [...buildSceneComponentIndex(documents).ids].map((id) => `#${id}`);
+  for (const [path, ids] of paths.componentsOf) {
+    for (const id of ids) keys.push(`${path}#${id}`);
+  }
+  return keys;
+}
+
+// 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`)
+    .sort()
+    .join("");
+  return `{\n${members}  }`;
+}
+
+/**
+ * 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 function buildSceneAddressDeclaration(
+  documents: ReadonlyMap<string, string>,
+  roles: SceneCollectionRoles,
+): 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);
+
+  return `${BANNER}
+declare global {
+  interface SceneGameObjectAddresses ${bodyOf([...index.paths])}
+
+  interface SceneComponentAddresses ${bodyOf(components)}
+}
+
+export {};
+`;
+}