@defold-typescript/transpiler 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -7,8 +7,11 @@ export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
 export { computeOutputRel, DEFAULT_INCLUDE, parseBuildConfig, SCRIPT_SUFFIX_BY_KIND, stripIncludeBase, } from "./output-paths";
 export { getProgramDiagnostics } from "./program-diagnostics";
 export { isDefignoredPath, SCAFFOLDED_DEFIGNORE_LINES } from "./project-resources";
+export { buildSceneAddressDeclaration } from "./scene-address-declaration";
 export type { SceneComponentIndex } from "./scene-component-index";
 export { buildSceneComponentIndex } from "./scene-component-index";
+export type { SceneReadHost } from "./scene-documents";
+export { ANIMATION_ASSET_EXTENSIONS, displayPathOf, GAME_PROJECT_DOCUMENT, GUI_EXTENSIONS, INPUT_BINDING_EXTENSIONS, isExcludedProjectPath, listProjectResourcePaths, PROJECT_EXTENSIONS, readSceneDocuments, SCENE_EXTENSIONS, } from "./scene-documents";
 export type { SceneObjectPathIndex } from "./scene-object-path-index";
 export { buildSceneObjectPathIndex } from "./scene-object-path-index";
 export type { SceneMessage } from "./scene-text-format";

package/dist/index.js

@@ -876,6 +876,7 @@ function buildSceneComponentIndex(documents) {
   }
   return { ids, incomplete };
 }
+
 // src/scene-object-path-index.ts
 var LEAF_BLOCKS = ["instances", "embedded_instances"];
 function resourceKey(resource) {
@@ -971,6 +972,93 @@ function buildSceneObjectPathIndex(documents) {
     declarers.sort();
   return { paths, declaredIn, incomplete };
 }
+
+// src/scene-address-declaration.ts
+var 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.
+`;
+function componentAddressesOf(documents) {
+  return [...buildSceneComponentIndex(documents).ids].map((id) => `#${id}`);
+}
+function bodyOf(keys) {
+  if (keys.length === 0)
+    return "{}";
+  const members = keys.map((key) => `    ${JSON.stringify(key)}: true;
+`).sort().join("");
+  return `{
+${members}  }`;
+}
+function buildSceneAddressDeclaration(documents) {
+  const paths = [...buildSceneObjectPathIndex(documents).paths];
+  const components = componentAddressesOf(documents);
+  return `${BANNER}
+declare global {
+  interface SceneGameObjectAddresses ${bodyOf(paths)}
+
+  interface SceneComponentAddresses ${bodyOf(components)}
+}
+
+export {};
+`;
+}
+// src/scene-documents.ts
+var SCENE_EXTENSIONS = [".go", ".collection"];
+var GUI_EXTENSIONS = [".gui"];
+var INPUT_BINDING_EXTENSIONS = [".input_binding"];
+var ANIMATION_ASSET_EXTENSIONS = [".atlas", ".tilesource", ".sprite"];
+var PROJECT_EXTENSIONS = [".project"];
+var GAME_PROJECT_DOCUMENT = "game.project";
+function displayPathOf(projectRoot, filePath) {
+  const path2 = filePath.replace(/\\/g, "/");
+  const root = projectRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+  return path2.startsWith(`${root}/`) ? path2.slice(root.length + 1) : path2;
+}
+function isBuildOutput(displayPath) {
+  return displayPath.split("/").includes("build");
+}
+function isExcludedProjectPath(displayPath) {
+  return isBuildOutput(displayPath) || isDefignoredPath(displayPath);
+}
+function readSceneDocuments(host, projectRoot, extensions = SCENE_EXTENSIONS) {
+  const documents = new Map;
+  const unreadable = [];
+  const paths = [];
+  if (!host.readDirectory) {
+    unreadable.push("the editor host cannot enumerate project files, so no scene source was read");
+    return { documents, 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);
+  }
+  return { documents, unreadable, paths };
+}
+function listProjectResourcePaths(host, projectRoot, extensions) {
+  if (!host.readDirectory)
+    return new Set;
+  const paths = [];
+  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());
+}
 // src/session.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
@@ -1807,13 +1895,17 @@ export {
   transpile,
   stripIncludeBase,
   resolveClassifiedSlotAtPosition,
+  readSceneDocuments,
   parseSceneTextFormat,
   parseBuildConfig,
+  listProjectResourcePaths,
   isFragmentCaret,
+  isExcludedProjectPath,
   isDefignoredPath,
   isAddressClass,
   getProgramDiagnostics,
   findMainEntryFactoryImports,
+  displayPathOf,
   createTranspileSession,
   computeOutputRel,
   componentIdOfSameObjectAddress,
@@ -1821,12 +1913,19 @@ export {
   buildSpriteAnimationIndex,
   buildSceneObjectPathIndex,
   buildSceneComponentIndex,
+  buildSceneAddressDeclaration,
   buildInputActionIndex,
   buildGuiNodeIndex,
   buildConfigKeyIndex,
   addressClassOfArgument,
   SceneTextFormatError,
   SCRIPT_SUFFIX_BY_KIND,
+  SCENE_EXTENSIONS,
   SCAFFOLDED_DEFIGNORE_LINES,
-  DEFAULT_INCLUDE
+  PROJECT_EXTENSIONS,
+  INPUT_BINDING_EXTENSIONS,
+  GUI_EXTENSIONS,
+  GAME_PROJECT_DOCUMENT,
+  DEFAULT_INCLUDE,
+  ANIMATION_ASSET_EXTENSIONS
 };

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

@@ -0,0 +1,12 @@
+/**
+ * The global augmentation that fills `SceneGameObjectAddresses` and
+ * `SceneComponentAddresses` from already-read scene sources — keys are
+ * project-relative display paths, values are file text.
+ *
+ * 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>): string;

package/dist/scene-documents.d.ts

@@ -0,0 +1,18 @@
+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 ANIMATION_ASSET_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>;
+    unreadable: string[];
+    paths: string[];
+};
+export declare function listProjectResourcePaths(host: SceneReadHost, projectRoot: string, extensions: readonly string[]): Set<string>;

package/package.json

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

package/src/index.ts

@@ -13,8 +13,22 @@ export {
 } from "./output-paths";
 export { getProgramDiagnostics } from "./program-diagnostics";
 export { isDefignoredPath, SCAFFOLDED_DEFIGNORE_LINES } from "./project-resources";
+export { buildSceneAddressDeclaration } from "./scene-address-declaration";
 export type { SceneComponentIndex } from "./scene-component-index";
 export { buildSceneComponentIndex } from "./scene-component-index";
+export type { SceneReadHost } from "./scene-documents";
+export {
+  ANIMATION_ASSET_EXTENSIONS,
+  displayPathOf,
+  GAME_PROJECT_DOCUMENT,
+  GUI_EXTENSIONS,
+  INPUT_BINDING_EXTENSIONS,
+  isExcludedProjectPath,
+  listProjectResourcePaths,
+  PROJECT_EXTENSIONS,
+  readSceneDocuments,
+  SCENE_EXTENSIONS,
+} from "./scene-documents";
 export type { SceneObjectPathIndex } from "./scene-object-path-index";
 export { buildSceneObjectPathIndex } from "./scene-object-path-index";
 export type { SceneMessage } from "./scene-text-format";

package/src/scene-address-declaration.ts

@@ -0,0 +1,57 @@
+import { buildSceneComponentIndex } from "./scene-component-index";
+import { buildSceneObjectPathIndex } 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.
+`;
+
+// `buildSceneComponentIndex` reports bare component ids with no owning object,
+// so the same-object form `#id` is the whole address the index can prove. A
+// `/path#id` key would be a cross product of two universes that were never
+// joined: it would claim every object owns every component.
+function componentAddressesOf(documents: ReadonlyMap<string, string>): string[] {
+  return [...buildSceneComponentIndex(documents).ids].map((id) => `#${id}`);
+}
+
+// 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.
+ *
+ * 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>): string {
+  const paths = [...buildSceneObjectPathIndex(documents).paths];
+  const components = componentAddressesOf(documents);
+
+  return `${BANNER}
+declare global {
+  interface SceneGameObjectAddresses ${bodyOf(paths)}
+
+  interface SceneComponentAddresses ${bodyOf(components)}
+}
+
+export {};
+`;
+}

package/src/scene-documents.ts

@@ -0,0 +1,126 @@
+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 documents an animation id is declared by: an atlas or tile source names
+// the ids, and a `.sprite` is the hop a referenced component takes to reach one.
+export const ANIMATION_ASSET_EXTENSIONS = [".atlas", ".tilesource", ".sprite"];
+
+// 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.
+export function readSceneDocuments(
+  host: SceneReadHost,
+  projectRoot: string,
+  extensions: readonly string[] = SCENE_EXTENSIONS,
+): { documents: Map<string, string>; unreadable: string[]; paths: string[] } {
+  const documents = 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, 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);
+  }
+
+  return { documents, 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());
+}