@defold-typescript/tstl-plugin 0.29.0 → 0.31.0

package/src/scene-provenance.ts

@@ -1,26 +1,26 @@
 import {
+  ANIMATION_ASSET_EXTENSIONS,
+  buildComponentAnimationIndex,
   buildConfigKeyIndex,
+  buildGuiFlipbookIndex,
   buildGuiNodeIndex,
   buildInputActionIndex,
   buildSceneComponentIndex,
   buildSceneObjectPathIndex,
-  buildSpriteAnimationIndex,
   type ClassifiedSlot,
   componentIdOfSameObjectAddress,
   computeOutputRel,
-  isAddressClass,
-  isFragmentCaret,
-} from "@defold-typescript/transpiler";
-import { readBuildConfigFromHost } from "./build-config";
-import {
-  ANIMATION_ASSET_EXTENSIONS,
   displayPathOf,
   GAME_PROJECT_DOCUMENT,
   GUI_EXTENSIONS,
   INPUT_BINDING_EXTENSIONS,
+  isAddressClass,
+  isFragmentCaret,
   PROJECT_EXTENSIONS,
-} from "./scene-documents";
-import type { SceneIndexCache } from "./scene-index-cache";
+} from "@defold-typescript/transpiler";
+import { readBuildConfigFromHost } from "./build-config";
+import { type SceneIndexCache, sceneCollectionRolesOf } from "./scene-index-cache";
+import { relativeUniverseFor } from "./scene-relative-addresses";
 
 // Keys of their own under the same cache the completion indexes use, so a
 // provenance map is thrown away with every index it was derived beside — and
@@ -29,7 +29,8 @@ const COMPONENT_PROVENANCE = "provenance:component-ids";
 const ACTION_PROVENANCE = "provenance:input-actions";
 const GUI_PROVENANCE = "provenance:gui-nodes";
 const PATH_PROVENANCE = "provenance:object-paths";
-const ANIMATION_PROVENANCE = "provenance:sprite-animations";
+const ANIMATION_PROVENANCE = "provenance:component-animations";
+const GUI_ANIMATION_PROVENANCE = "provenance:gui-flipbook";
 
 type Provenance = ReadonlyMap<string, readonly string[]>;
 
@@ -125,16 +126,48 @@ function nodeProvenance(cache: SceneIndexCache, fileName: string): Provenance {
 function pathProvenance(cache: SceneIndexCache): Provenance {
   return cache.derived(
     PATH_PROVENANCE,
-    () => buildSceneObjectPathIndex(cache.documents().documents).declaredIn,
+    () =>
+      buildSceneObjectPathIndex(cache.documents().documents, sceneCollectionRolesOf(cache))
+        .declaredIn,
   );
 }
 
-// Scoped exactly the way the animation completion is: to the sprite component
-// the slot's sibling literal addresses on the one game object owning this
-// script, resolved through the same helper so the two cannot disagree about
-// which sprite is addressed. The tile set is reported only for an id it really
-// declares — a panel naming a file that does not carry the name is the
-// fabricated answer this surface exists to avoid.
+// Scoped exactly the way the gui flipbook completion is: to the `.gui` scene
+// naming this file's generated gui script. The index already records which
+// named texture declared each id, so the answer is read straight off it — and
+// an id no named texture carries is answered with silence rather than the
+// scene that failed to declare it.
+function guiAnimationProvenance(input: {
+  cache: SceneIndexCache;
+  fileName: string;
+  entryName: string;
+}): readonly string[] {
+  const { cache, fileName, entryName } = input;
+  const index = cache.derived(GUI_ANIMATION_PROVENANCE, () =>
+    buildGuiFlipbookIndex({
+      scenes: cache.documents(GUI_EXTENSIONS).documents,
+      assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents,
+    }),
+  );
+  const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
+  const resource = computeOutputRel(
+    displayPathOf(cache.projectRoot, fileName),
+    config,
+    "gui-script",
+  );
+  const declarers = index.byScriptResource.get(resource)?.get(entryName);
+  return declarers === undefined ? [] : [...declarers].sort();
+}
+
+// Scoped exactly the way the animation completion is: to the sprite or model
+// component the slot's sibling literal addresses on the one game object owning
+// this script, resolved through the same helper so the two cannot disagree
+// about which component is addressed. The declaring document — an atlas for a
+// sprite, and for a model the animation set that lists the entry producing the
+// id — is reported only for an id it really declares: the per-id map's key set
+// *is* the component's id set, so a miss there already means this component
+// does not carry the name, and a panel naming a file that does not carry it is
+// the fabricated answer this surface exists to avoid.
 function animationProvenance(input: {
   slot: ClassifiedSlot;
   cache: SceneIndexCache;
@@ -142,19 +175,21 @@ function animationProvenance(input: {
   entryName: string;
 }): readonly string[] {
   const { slot, cache, fileName, entryName } = input;
+  if (slot.nodeParameter !== undefined) {
+    return guiAnimationProvenance({ cache, fileName, entryName });
+  }
   const component = componentIdOfSameObjectAddress(slot.addressText ?? "");
   if (component === undefined) return [];
   const index = cache.derived(ANIMATION_PROVENANCE, () =>
-    buildSpriteAnimationIndex({
+    buildComponentAnimationIndex({
       scenes: cache.documents().documents,
       assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents,
     }),
   );
   const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
   const resource = computeOutputRel(displayPathOf(cache.projectRoot, fileName), config, "script");
-  const tileSet = index.tileSetByScriptResource.get(resource)?.get(component);
-  if (tileSet === undefined) return [];
-  return index.byScriptResource.get(resource)?.get(component)?.has(entryName) ? [tileSet] : [];
+  const source = index.sourceByScriptResource.get(resource)?.get(component)?.get(entryName);
+  return source === undefined ? [] : [source];
 }
 
 // A config key is declared by the one file that answers a reader at runtime, and
@@ -177,6 +212,37 @@ function constantProvenance(
   return cache.resourcePaths(extensions).has(entryName) ? [entryName.replace(/^\//, "")] : [];
 }
 
+/**
+ * The sentence a relative entry's panel carries, or `undefined` where the entry
+ * is not one — a fragment caret, a slot that names no address, or a name this
+ * file's relative universe does not offer.
+ *
+ * A relative address is valid from the object hosting the script and nowhere
+ * else, so the objects it resolves from *are* its provenance: naming a declaring
+ * file instead would answer a question the author is not asking. Where the entry
+ * resolves from only some of the contexts this script runs in, the others are
+ * named too — a sometimes-valid entry that read as an always-valid one is the
+ * wrong-suggestion class this panel exists to close.
+ */
+export function resolveRelativeEntryProvenance(input: {
+  slot: ClassifiedSlot;
+  position: number;
+  cache: SceneIndexCache;
+  fileName: string;
+  entryName: string;
+}): string | undefined {
+  const { slot, position, cache, fileName, entryName } = input;
+  if (!isAddressClass(slot.class) || isFragmentCaret(slot, position)) return undefined;
+  const universe = relativeUniverseFor(cache, fileName);
+  const resolvesFrom = universe.contextsByEntry.get(entryName);
+  if (resolvesFrom === undefined) return undefined;
+  const others = universe.contexts
+    .map((context) => context.object)
+    .filter((object) => !resolvesFrom.includes(object));
+  const relative = `Relative to ${resolvesFrom.join(", ")}`;
+  return others.length === 0 ? relative : `${relative}; not from ${others.join(", ")}`;
+}
+
 // The display paths of the project files that declare `entryName` in the
 // universe this slot draws from, sorted, empty when the project does not name
 // one exactly. Every kind the completion path offers is answered here; silence

package/src/scene-relative-addresses.ts

@@ -0,0 +1,145 @@
+import {
+  buildSceneObjectPathIndex,
+  buildScriptNamingContexts,
+  computeOutputRel,
+  displayPathOf,
+  GUI_EXTENSIONS,
+  guiScriptResourcesOf,
+  type NamingContext,
+  relativeAddressesFrom,
+  type SceneObjectPathIndex,
+} from "@defold-typescript/transpiler";
+import { readBuildConfigFromHost } from "./build-config";
+import { type SceneIndexCache, sceneCollectionRolesOf } from "./scene-index-cache";
+
+// The relative forms the file being edited may write, and the objects each one
+// resolves from. Unlike every other completion universe this is per-file by
+// construction: a relative address continues the collection path of the object
+// hosting the script, so it means one thing from there and nothing anywhere
+// else.
+export interface RelativeUniverse {
+  /** Every object hosting this file's generated script, sorted by object path. */
+  readonly contexts: readonly NamingContext[];
+  /** Relative game-object paths, valid from at least one context. */
+  readonly paths: ReadonlySet<string>;
+  /** Those paths joined to the components their object owns. */
+  readonly addresses: ReadonlySet<string>;
+  /** Entry name -> the sorted object paths it resolves from. */
+  readonly contextsByEntry: ReadonlyMap<string, readonly string[]>;
+}
+
+const CONTEXTS = "relative:naming-contexts";
+
+interface ProjectContexts {
+  readonly index: SceneObjectPathIndex;
+  readonly byScriptResource: ReadonlyMap<string, readonly NamingContext[]>;
+}
+
+function projectContexts(cache: SceneIndexCache): ProjectContexts {
+  return cache.derived(CONTEXTS, () => {
+    const index = buildSceneObjectPathIndex(
+      cache.documents().documents,
+      sceneCollectionRolesOf(cache),
+    );
+    // A `.gui` names the gui script it drives, and that indirection is the only
+    // way a gui script reaches an object: the edge is read through the same
+    // shared builder the CLI's walk uses rather than a second reader.
+    const guiScripts = guiScriptResourcesOf(cache.documents(GUI_EXTENSIONS).documents);
+    return { index, byScriptResource: buildScriptNamingContexts(index, guiScripts) };
+  });
+}
+
+/**
+ * Every game-object path the project declares and the components each owns —
+ * the index a check scopes an absolute `#fragment` address against.
+ *
+ * Read off the walk `projectContexts` already caches rather than built again:
+ * the naming contexts are derived *from* this index, so the reachability path
+ * costs no second `.go`/`.collection` parse.
+ */
+export function projectObjectIndex(cache: SceneIndexCache): SceneObjectPathIndex {
+  return projectContexts(cache).index;
+}
+
+/**
+ * The relative universe the file at `fileName` may write from, keyed per file
+ * under the same cache the absolute indexes live in.
+ *
+ * The file is mapped *forward* to the script resource a scene would name — the
+ * same direction `nodeEntries` takes, because an output path cannot say which
+ * include base produced it. Both script kinds are resolved and their contexts
+ * unioned: a `.ts` is named as a `.script` by a game object and as a
+ * `.gui_script` by a `.gui`, and nothing in the file itself says which.
+ */
+export function relativeUniverseFor(cache: SceneIndexCache, fileName: string): RelativeUniverse {
+  return cache.derived(`relative-universe:${fileName}`, () => {
+    const { index, byScriptResource } = projectContexts(cache);
+    const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
+    const rel = displayPathOf(cache.projectRoot, fileName);
+
+    const byObject = new Map<string, NamingContext>();
+    for (const kind of ["script", "gui-script"] as const) {
+      for (const context of byScriptResource.get(computeOutputRel(rel, config, kind)) ?? []) {
+        byObject.set(context.object, context);
+      }
+    }
+    const contexts = [...byObject.values()].sort((a, b) => a.object.localeCompare(b.object));
+
+    const paths = new Set<string>();
+    const addresses = new Set<string>();
+    const contextsByEntry = new Map<string, string[]>();
+    for (const context of contexts) {
+      const relative = relativeAddressesFrom(index, context);
+      for (const entry of relative.paths) {
+        paths.add(entry);
+        contextsByEntry.set(entry, [...(contextsByEntry.get(entry) ?? []), context.object]);
+      }
+      for (const entry of relative.addresses) {
+        addresses.add(entry);
+        contextsByEntry.set(entry, [...(contextsByEntry.get(entry) ?? []), context.object]);
+      }
+    }
+    for (const objects of contextsByEntry.values()) objects.sort();
+
+    return { contexts, paths, addresses, contextsByEntry };
+  });
+}
+
+/**
+ * The worlds the file's script runs in, as `checkCrossWorldAddresses` asks for
+ * them: the de-duplicated sockets of every naming context hosting it, with the
+ * bootstrap world carried as `undefined`.
+ *
+ * The same answer `scriptWorldsForBuild` gives the CLI, reached through the
+ * chain that resolver was modelled on — so an address the build calls foreign is
+ * foreign in the editor too. An empty answer is the honest unknown: a script no
+ * scene hosts runs in no world this project can prove, and the check reports
+ * nothing for it.
+ */
+export function worldsFor(
+  cache: SceneIndexCache,
+  fileName: string,
+): readonly (string | undefined)[] {
+  const sockets = new Set<string | undefined>();
+  for (const context of relativeUniverseFor(cache, fileName).contexts) {
+    sockets.add(context.socket);
+  }
+  return [...sockets];
+}
+
+/**
+ * Whether a bare `/path` can resolve from where this file runs. A bare address
+ * continues the caller's own world, so one offered to a script running behind a
+ * proxy names an object that world cannot reach.
+ *
+ * A file with no naming context offers them: nothing is known about where it
+ * runs, and withholding every bare path would delete the completions the
+ * absolute universe has always provided. Socket-qualified keys are never
+ * touched — whether a slot accepts a foreign socket is a different question.
+ */
+export function offersBareWorld(universe: RelativeUniverse): boolean {
+  return (
+    universe.contexts.length === 0 ||
+    universe.contexts.some((context) => context.socket === undefined)
+  );
+}

package/dist/scene-documents.d.ts

@@ -1,18 +0,0 @@
-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/src/scene-documents.ts

@@ -1,126 +0,0 @@
-import { isDefignoredPath } from "@defold-typescript/transpiler";
-
-// 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());
-}