@defold-typescript/tstl-plugin 0.30.0 → 0.31.0

package/dist/completion-harness.d.ts

@@ -5,8 +5,14 @@ export type PluginFactory = (modules: {
     create(info: ts.server.PluginCreateInfo): ts.LanguageService;
 };
 export declare const SCENE_DOCUMENTS: Record<string, string>;
+export declare const BOOTSTRAP_MAIN = "[bootstrap]\nmain_collection = /main.collectionc\n";
+export declare function scriptObject(id: string, resource: string): string;
+export declare function proxyObject(collection: string): string;
+export declare const TWO_WORLD_DOCUMENTS: Record<string, string>;
 export interface ProxyHost {
     documents: Record<string, string>;
+    /** Listed by `readDirectory`, but answered `undefined` by `readFile`. */
+    unreadable: Set<string>;
     directoryReads: string[][];
     openWatchers: number;
     fireDirectory(hostPath: string): void;
@@ -20,7 +26,12 @@ export interface CompletionSetup {
 export declare function completionSetup(options: {
     source: string;
     base: ts.WithMetadata<ts.CompletionInfo> | undefined;
+    /** Further program files beside the edited one, so a check can be scoped to it. */
+    sources?: Record<string, string>;
     documents?: Record<string, string>;
+    /** Scene sources the host lists but cannot read, so a walk composes a real hole. */
+    unreadable?: readonly string[];
+    baseDiagnostics?: ts.Diagnostic[];
     serverHost?: boolean;
     watch?: boolean;
     baseDispose?: boolean;

package/dist/index.js

@@ -3,22 +3,22 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import {
   ANIMATION_ASSET_EXTENSIONS as ANIMATION_ASSET_EXTENSIONS2,
+  buildComponentAnimationIndex as buildComponentAnimationIndex2,
   buildConfigKeyIndex as buildConfigKeyIndex2,
+  buildGuiFlipbookIndex as buildGuiFlipbookIndex2,
   buildGuiNodeIndex as buildGuiNodeIndex2,
   buildInputActionIndex as buildInputActionIndex2,
-  buildSceneComponentIndex as buildSceneComponentIndex2,
-  buildSceneObjectPathIndex as buildSceneObjectPathIndex2,
-  buildSpriteAnimationIndex as buildSpriteAnimationIndex2,
+  buildSceneObjectPathIndex as buildSceneObjectPathIndex3,
   componentIdOfSameObjectAddress as componentIdOfSameObjectAddress2,
-  computeOutputRel as computeOutputRel2,
-  displayPathOf as displayPathOf3,
-  GAME_PROJECT_DOCUMENT as GAME_PROJECT_DOCUMENT2,
-  GUI_EXTENSIONS as GUI_EXTENSIONS2,
+  computeOutputRel as computeOutputRel3,
+  displayPathOf as displayPathOf4,
+  GAME_PROJECT_DOCUMENT as GAME_PROJECT_DOCUMENT3,
+  GUI_EXTENSIONS as GUI_EXTENSIONS3,
   getProgramDiagnostics,
   INPUT_BINDING_EXTENSIONS as INPUT_BINDING_EXTENSIONS2,
   isAddressClass as isAddressClass2,
   isFragmentCaret as isFragmentCaret2,
-  PROJECT_EXTENSIONS as PROJECT_EXTENSIONS2,
+  PROJECT_EXTENSIONS as PROJECT_EXTENSIONS3,
   resolveClassifiedSlotAtPosition
 } from "@defold-typescript/transpiler";
 
@@ -87,11 +87,23 @@ function buildWholeLiteralCompletionEntries(input) {
   });
 }
 
+// src/scene-diagnostics.ts
+import {
+  checkCrossWorldAddresses,
+  checkUrlFragmentReachability
+} from "@defold-typescript/transpiler";
+
 // src/scene-index-cache.ts
 import {
+  buildSceneCollectionRoles,
+  buildSceneComponentIndex,
+  COLLECTION_REFERENCE_EXTENSIONS,
   displayPathOf,
+  GAME_PROJECT_DOCUMENT,
   isExcludedProjectPath,
+  LIBRARY_DEPENDENCY_ROOT,
   listProjectResourcePaths,
+  PROJECT_EXTENSIONS,
   readSceneDocuments,
   SCENE_EXTENSIONS
 } from "@defold-typescript/transpiler";
@@ -122,6 +134,9 @@ function createSceneIndexCache(host, projectRoot) {
   }
   function affectsCache(hostPath) {
     const displayPath = displayPathOf(projectRoot, hostPath);
+    if (displayPath === LIBRARY_DEPENDENCY_ROOT || displayPath.startsWith(`${LIBRARY_DEPENDENCY_ROOT}/`)) {
+      return true;
+    }
     if (isExcludedProjectPath(displayPath))
       return false;
     for (const extension of servedExtensions) {
@@ -207,31 +222,145 @@ function createSceneIndexCache(host, projectRoot) {
     }
   };
 }
+function sceneComponentIndexOf(cache) {
+  return cache.derived("component-index", () => buildSceneComponentIndex(cache.documents().documents));
+}
+function sceneCollectionRolesOf(cache) {
+  return cache.derived("collection-roles", () => buildSceneCollectionRoles({
+    documents: cache.documents().documents,
+    references: cache.documents(COLLECTION_REFERENCE_EXTENSIONS).documents,
+    gameProject: cache.documents(PROJECT_EXTENSIONS).documents.get(GAME_PROJECT_DOCUMENT)
+  }));
+}
+
+// src/scene-relative-addresses.ts
+import {
+  buildSceneObjectPathIndex,
+  buildScriptNamingContexts,
+  computeOutputRel,
+  displayPathOf as displayPathOf2,
+  GUI_EXTENSIONS,
+  guiScriptResourcesOf,
+  relativeAddressesFrom
+} from "@defold-typescript/transpiler";
+var CONTEXTS = "relative:naming-contexts";
+function projectContexts(cache) {
+  return cache.derived(CONTEXTS, () => {
+    const index = buildSceneObjectPathIndex(cache.documents().documents, sceneCollectionRolesOf(cache));
+    const guiScripts = guiScriptResourcesOf(cache.documents(GUI_EXTENSIONS).documents);
+    return { index, byScriptResource: buildScriptNamingContexts(index, guiScripts) };
+  });
+}
+function projectObjectIndex(cache) {
+  return projectContexts(cache).index;
+}
+function relativeUniverseFor(cache, fileName) {
+  return cache.derived(`relative-universe:${fileName}`, () => {
+    const { index, byScriptResource } = projectContexts(cache);
+    const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
+    const rel = displayPathOf2(cache.projectRoot, fileName);
+    const byObject = new Map;
+    for (const kind of ["script", "gui-script"]) {
+      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;
+    const addresses = new Set;
+    const contextsByEntry = new Map;
+    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 };
+  });
+}
+function worldsFor(cache, fileName) {
+  const sockets = new Set;
+  for (const context of relativeUniverseFor(cache, fileName).contexts) {
+    sockets.add(context.socket);
+  }
+  return [...sockets];
+}
+function offersBareWorld(universe) {
+  return universe.contexts.length === 0 || universe.contexts.some((context) => context.socket === undefined);
+}
+
+// src/scene-diagnostics.ts
+var DEFOLD_DIAGNOSTIC_SOURCE = "defold-typescript";
+var UNREACHABLE_FRAGMENT_CODE = 9000101;
+var FOREIGN_SOCKET_CODE = 9000102;
+function suggestion(typescript, file, finding, code) {
+  return {
+    file,
+    start: finding.start,
+    length: finding.length,
+    messageText: finding.message,
+    category: typescript.DiagnosticCategory.Suggestion,
+    source: DEFOLD_DIAGNOSTIC_SOURCE,
+    code
+  };
+}
+function sceneReachabilityDiagnostics(input) {
+  const { ts: typescript, program, table, cache, fileName } = input;
+  const sourceFile = program.getSourceFile(fileName);
+  if (!sourceFile) {
+    return [];
+  }
+  const index = sceneComponentIndexOf(cache);
+  const report = checkUrlFragmentReachability({
+    program,
+    table,
+    index: { ids: index.ids, incomplete: [...index.incomplete, ...cache.documents().unreadable] },
+    objects: projectObjectIndex(cache),
+    sourceFiles: [sourceFile]
+  });
+  const fragments = report.kind === "suppressed" ? [] : report.findings.map((finding) => suggestion(typescript, sourceFile, finding, UNREACHABLE_FRAGMENT_CODE));
+  const crossWorld = checkCrossWorldAddresses({
+    program,
+    table,
+    worldsOf: (name) => worldsFor(cache, name),
+    sourceFiles: [sourceFile]
+  }).map((finding) => suggestion(typescript, sourceFile, finding, FOREIGN_SOCKET_CODE));
+  return [...fragments, ...crossWorld];
+}
 
 // src/scene-provenance.ts
 import {
   ANIMATION_ASSET_EXTENSIONS,
+  buildComponentAnimationIndex,
   buildConfigKeyIndex,
+  buildGuiFlipbookIndex,
   buildGuiNodeIndex,
   buildInputActionIndex,
-  buildSceneComponentIndex,
-  buildSceneObjectPathIndex,
-  buildSpriteAnimationIndex,
+  buildSceneComponentIndex as buildSceneComponentIndex2,
+  buildSceneObjectPathIndex as buildSceneObjectPathIndex2,
   componentIdOfSameObjectAddress,
-  computeOutputRel,
-  displayPathOf as displayPathOf2,
-  GAME_PROJECT_DOCUMENT,
-  GUI_EXTENSIONS,
+  computeOutputRel as computeOutputRel2,
+  displayPathOf as displayPathOf3,
+  GAME_PROJECT_DOCUMENT as GAME_PROJECT_DOCUMENT2,
+  GUI_EXTENSIONS as GUI_EXTENSIONS2,
   INPUT_BINDING_EXTENSIONS,
   isAddressClass,
   isFragmentCaret,
-  PROJECT_EXTENSIONS
+  PROJECT_EXTENSIONS as PROJECT_EXTENSIONS2
 } from "@defold-typescript/transpiler";
 var COMPONENT_PROVENANCE = "provenance:component-ids";
 var ACTION_PROVENANCE = "provenance:input-actions";
 var GUI_PROVENANCE = "provenance:gui-nodes";
 var PATH_PROVENANCE = "provenance:object-paths";
-var ANIMATION_PROVENANCE = "provenance:sprite-animations";
+var ANIMATION_PROVENANCE = "provenance:component-animations";
+var GUI_ANIMATION_PROVENANCE = "provenance:gui-flipbook";
 function byDeclaringDocument(documents, idsOf) {
   const declarers = new Map;
   for (const [displayPath, text] of documents) {
@@ -275,49 +404,73 @@ function byClaimedScript(documents) {
   return byResource;
 }
 function componentProvenance(cache) {
-  return cache.derived(COMPONENT_PROVENANCE, () => byDeclaringDocument(cache.documents().documents, (narrowed) => buildSceneComponentIndex(narrowed).ids));
+  return cache.derived(COMPONENT_PROVENANCE, () => byDeclaringDocument(cache.documents().documents, (narrowed) => buildSceneComponentIndex2(narrowed).ids));
 }
 function actionProvenance(cache) {
   return cache.derived(ACTION_PROVENANCE, () => byDeclaringDocument(cache.documents(INPUT_BINDING_EXTENSIONS).documents, (narrowed) => buildInputActionIndex(narrowed)));
 }
 function nodeProvenance(cache, fileName) {
-  const byResource = cache.derived(GUI_PROVENANCE, () => byClaimedScript(cache.documents(GUI_EXTENSIONS).documents));
+  const byResource = cache.derived(GUI_PROVENANCE, () => byClaimedScript(cache.documents(GUI_EXTENSIONS2).documents));
   const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
-  const resource = computeOutputRel(displayPathOf2(cache.projectRoot, fileName), config, "gui-script");
+  const resource = computeOutputRel2(displayPathOf3(cache.projectRoot, fileName), config, "gui-script");
   return byResource.get(resource) ?? new Map;
 }
 function pathProvenance(cache) {
-  return cache.derived(PATH_PROVENANCE, () => buildSceneObjectPathIndex(cache.documents().documents).declaredIn);
+  return cache.derived(PATH_PROVENANCE, () => buildSceneObjectPathIndex2(cache.documents().documents, sceneCollectionRolesOf(cache)).declaredIn);
+}
+function guiAnimationProvenance(input) {
+  const { cache, fileName, entryName } = input;
+  const index = cache.derived(GUI_ANIMATION_PROVENANCE, () => buildGuiFlipbookIndex({
+    scenes: cache.documents(GUI_EXTENSIONS2).documents,
+    assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents
+  }));
+  const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
+  const resource = computeOutputRel2(displayPathOf3(cache.projectRoot, fileName), config, "gui-script");
+  const declarers = index.byScriptResource.get(resource)?.get(entryName);
+  return declarers === undefined ? [] : [...declarers].sort();
 }
 function animationProvenance(input) {
   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({
+  const index = cache.derived(ANIMATION_PROVENANCE, () => buildComponentAnimationIndex({
     scenes: cache.documents().documents,
     assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents
   }));
   const config = readBuildConfigFromHost(cache.host, cache.projectRoot);
-  const resource = computeOutputRel(displayPathOf2(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 resource = computeOutputRel2(displayPathOf3(cache.projectRoot, fileName), config, "script");
+  const source = index.sourceByScriptResource.get(resource)?.get(component)?.get(entryName);
+  return source === undefined ? [] : [source];
 }
 function constantProvenance(slot, cache, entryName) {
   if (slot.class === "config-key") {
-    const text = cache.documents(PROJECT_EXTENSIONS).documents.get(GAME_PROJECT_DOCUMENT);
+    const text = cache.documents(PROJECT_EXTENSIONS2).documents.get(GAME_PROJECT_DOCUMENT2);
     if (text === undefined)
       return [];
     const keys = cache.derived("config-keys", () => buildConfigKeyIndex(text));
-    return keys.has(entryName) ? [GAME_PROJECT_DOCUMENT] : [];
+    return keys.has(entryName) ? [GAME_PROJECT_DOCUMENT2] : [];
   }
   const extensions = slot.resourceExtensions;
   if (extensions === undefined || extensions.length === 0)
     return [];
   return cache.resourcePaths(extensions).has(entryName) ? [entryName.replace(/^\//, "")] : [];
 }
+function resolveRelativeEntryProvenance(input) {
+  const { slot, position, cache, fileName, entryName } = input;
+  if (!isAddressClass(slot.class) || isFragmentCaret(slot, position))
+    return;
+  const universe = relativeUniverseFor(cache, fileName);
+  const resolvesFrom = universe.contextsByEntry.get(entryName);
+  if (resolvesFrom === undefined)
+    return;
+  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(", ")}`;
+}
 function resolveEntryProvenance(input) {
   const { slot, position, cache, fileName, entryName } = input;
   if (isAddressClass(slot.class)) {
@@ -361,40 +514,60 @@ function componentEntries(slot, position, cache, baseEntries) {
   }
   return buildSceneCompletionEntries({
     slot,
-    ids: cache.derived("component-ids", () => buildSceneComponentIndex2(cache.documents().documents).ids),
+    ids: sceneComponentIndexOf(cache).ids,
     baseEntries
   });
 }
-function objectPathEntries(slot, position, cache, baseEntries) {
+function objectPathEntries(slot, position, cache, fileName, baseEntries) {
   if (isFragmentCaret2(slot, position)) {
     return [];
   }
-  return buildAddressPathCompletionEntries({
-    slot,
-    paths: cache.derived("object-paths", () => buildSceneObjectPathIndex2(cache.documents().documents).paths),
-    baseEntries
-  });
+  const universe = relativeUniverseFor(cache, fileName);
+  const bare = offersBareWorld(universe);
+  const absolute = cache.derived("object-paths", () => buildSceneObjectPathIndex3(cache.documents().documents, sceneCollectionRolesOf(cache)).paths);
+  const paths = new Set;
+  for (const key of absolute) {
+    if (bare || !key.startsWith("/"))
+      paths.add(key);
+  }
+  for (const key of universe.paths)
+    paths.add(key);
+  const entries = buildAddressPathCompletionEntries({ slot, paths, baseEntries });
+  if (slot.fragmentStart === -1) {
+    entries.push(...buildWholeLiteralCompletionEntries({ slot, ids: universe.addresses, baseEntries }));
+  }
+  return entries;
 }
 function nodeEntries(slot, cache, fileName, baseEntries) {
   const { projectRoot } = cache;
-  const index = cache.derived("gui-nodes", () => buildGuiNodeIndex2(cache.documents(GUI_EXTENSIONS2).documents));
+  const index = cache.derived("gui-nodes", () => buildGuiNodeIndex2(cache.documents(GUI_EXTENSIONS3).documents));
   const config = readBuildConfigFromHost(cache.host, projectRoot);
-  const resource = computeOutputRel2(displayPathOf3(projectRoot, fileName), config, "gui-script");
+  const resource = computeOutputRel3(displayPathOf4(projectRoot, fileName), config, "gui-script");
   const ids = index.byScriptResource.get(resource);
   return ids === undefined ? [] : buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
 }
 function animationEntries(slot, cache, fileName, baseEntries) {
+  const { projectRoot } = cache;
+  if (slot.nodeParameter !== undefined) {
+    const index2 = cache.derived("gui-flipbook", () => buildGuiFlipbookIndex2({
+      scenes: cache.documents(GUI_EXTENSIONS3).documents,
+      assets: cache.documents(ANIMATION_ASSET_EXTENSIONS2).documents
+    }));
+    const config2 = readBuildConfigFromHost(cache.host, projectRoot);
+    const resource2 = computeOutputRel3(displayPathOf4(projectRoot, fileName), config2, "gui-script");
+    const declared = index2.byScriptResource.get(resource2);
+    return declared === undefined ? [] : buildWholeLiteralCompletionEntries({ slot, ids: new Set(declared.keys()), baseEntries });
+  }
   const component = componentIdOfSameObjectAddress2(slot.addressText ?? "");
   if (component === undefined) {
     return [];
   }
-  const { projectRoot } = cache;
-  const index = cache.derived("sprite-animations", () => buildSpriteAnimationIndex2({
+  const index = cache.derived("component-animations", () => buildComponentAnimationIndex2({
     scenes: cache.documents().documents,
     assets: cache.documents(ANIMATION_ASSET_EXTENSIONS2).documents
   }));
   const config = readBuildConfigFromHost(cache.host, projectRoot);
-  const resource = computeOutputRel2(displayPathOf3(projectRoot, fileName), config, "script");
+  const resource = computeOutputRel3(displayPathOf4(projectRoot, fileName), config, "script");
   const ids = index.byScriptResource.get(resource)?.get(component);
   return ids === undefined ? [] : buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
 }
@@ -407,7 +580,7 @@ function resourceEntries(slot, cache, baseEntries) {
   return buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
 }
 function configKeyEntries(slot, cache, baseEntries) {
-  const text = cache.documents(PROJECT_EXTENSIONS2).documents.get(GAME_PROJECT_DOCUMENT2);
+  const text = cache.documents(PROJECT_EXTENSIONS3).documents.get(GAME_PROJECT_DOCUMENT3);
   if (text === undefined) {
     return [];
   }
@@ -418,18 +591,13 @@ function actionIdEntries(slot, cache, baseEntries) {
   const ids = cache.derived("input-actions", () => buildInputActionIndex2(cache.documents(INPUT_BINDING_EXTENSIONS2).documents));
   return buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
 }
-function provenancePanel(entryName, declaredIn) {
+function provenancePanel(entryName, documentation) {
   return {
     name: entryName,
     kind: CONTRIBUTED_ENTRY_KIND,
     kindModifiers: "",
     displayParts: [{ kind: "stringLiteral", text: JSON.stringify(entryName) }],
-    documentation: [
-      {
-        kind: "text",
-        text: `Declared in ${declaredIn.join(", ")}`
-      }
-    ],
+    documentation: [{ kind: "text", text: documentation }],
     source: [{ kind: "text", text: DEFOLD_COMPLETION_SOURCE }]
   };
 }
@@ -467,8 +635,18 @@ function init(modules) {
       if (!slot) {
         return forward();
       }
+      const relative = resolveRelativeEntryProvenance({
+        slot,
+        position,
+        cache,
+        fileName,
+        entryName
+      });
+      if (relative !== undefined) {
+        return provenancePanel(entryName, relative);
+      }
       const declaredIn = resolveEntryProvenance({ slot, position, cache, fileName, entryName });
-      return declaredIn.length === 0 ? forward() : provenancePanel(entryName, declaredIn);
+      return declaredIn.length === 0 ? forward() : provenancePanel(entryName, `Declared in ${declaredIn.join(", ")}`);
     };
     proxy.getSemanticDiagnostics = (fileName) => {
       const prior = base.getSemanticDiagnostics(fileName);
@@ -477,7 +655,9 @@ function init(modules) {
         return prior;
       }
       const transpiler = getProgramDiagnostics(program, program.getSourceFile(fileName)).map((diagnostic) => ({ ...diagnostic, category: ts.DiagnosticCategory.Suggestion }));
-      return [...prior, ...transpiler];
+      const table = loadUrlParameterTable();
+      const scene = cache && table ? sceneReachabilityDiagnostics({ ts, program, table, cache, fileName }) : [];
+      return [...prior, ...transpiler, ...scene];
     };
     proxy.getCompletionsAtPosition = (fileName, position, options, formattingSettings) => {
       const prior = base.getCompletionsAtPosition(fileName, position, options, formattingSettings);
@@ -496,7 +676,7 @@ function init(modules) {
       const baseEntries = prior?.entries ?? [];
       const entries = isAddressClass2(slot.class) ? [
         ...componentEntries(slot, position, cache, baseEntries),
-        ...objectPathEntries(slot, position, cache, baseEntries)
+        ...objectPathEntries(slot, position, cache, fileName, baseEntries)
       ] : slot.class === "gui-node" ? nodeEntries(slot, cache, fileName, baseEntries) : slot.class === "animation" ? animationEntries(slot, cache, fileName, baseEntries) : slot.class === "resource-path" ? resourceEntries(slot, cache, baseEntries) : slot.class === "config-key" ? configKeyEntries(slot, cache, baseEntries) : slot.class === "action-id" ? actionIdEntries(slot, cache, baseEntries) : [];
       if (entries.length === 0) {
         return prior;

package/dist/scene-diagnostics.d.ts

@@ -0,0 +1,29 @@
+import type { UrlParameterTable } from "@defold-typescript/types";
+import type * as ts from "typescript";
+import { type SceneIndexCache } from "./scene-index-cache";
+/** The `source` an editor renders beside the message, and `--json` never sees. */
+export declare const DEFOLD_DIAGNOSTIC_SOURCE = "defold-typescript";
+/**
+ * The address findings the editor surfaces on the file being edited, as
+ * advisory suggestions.
+ *
+ * Every path that cannot produce one answers with an empty array. A suppressed
+ * reachability report is the important case: there is no file span on which a
+ * "the check did not run" notice could honestly sit, and a speculative squiggle
+ * is worse than none — the build says so in prose instead, where a whole-project
+ * line has somewhere to go.
+ *
+ * The *whole* hole is one index, composed the way `sceneIndexForBuild` composes
+ * it: what the parse could not read plus what the walk could not reach. The
+ * completion path deliberately reads a partial universe — a suggestion claims
+ * nothing about what is absent — but a finding does, so a component declared
+ * only by an unresolved dependency suppresses the check rather than reporting
+ * the address as unreachable.
+ */
+export declare function sceneReachabilityDiagnostics(input: {
+    ts: typeof import("typescript");
+    program: ts.Program;
+    table: UrlParameterTable;
+    cache: SceneIndexCache;
+    fileName: string;
+}): ts.Diagnostic[];

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

@@ -1,4 +1,4 @@
-import { readSceneDocuments, type SceneReadHost } from "@defold-typescript/transpiler";
+import { readSceneDocuments, type SceneCollectionRoles, type SceneComponentIndex, type SceneReadHost } from "@defold-typescript/transpiler";
 import type * as ts from "typescript";
 export interface SceneWatchHost extends SceneReadHost {
     watchFile?(path: string, callback: ts.FileWatcherCallback, pollingInterval?: number): ts.FileWatcher;
@@ -13,3 +13,5 @@ export interface SceneIndexCache {
     dispose(): void;
 }
 export declare function createSceneIndexCache(host: SceneWatchHost, projectRoot: string): SceneIndexCache;
+export declare function sceneComponentIndexOf(cache: SceneIndexCache): SceneComponentIndex;
+export declare function sceneCollectionRolesOf(cache: SceneIndexCache): SceneCollectionRoles;

package/dist/scene-provenance.d.ts

@@ -1,5 +1,24 @@
 import { type ClassifiedSlot } from "@defold-typescript/transpiler";
-import type { SceneIndexCache } from "./scene-index-cache";
+import { type SceneIndexCache } from "./scene-index-cache";
+/**
+ * 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 declare function resolveRelativeEntryProvenance(input: {
+    slot: ClassifiedSlot;
+    position: number;
+    cache: SceneIndexCache;
+    fileName: string;
+    entryName: string;
+}): string | undefined;
 export declare function resolveEntryProvenance(input: {
     slot: ClassifiedSlot;
     position: number;

package/dist/scene-relative-addresses.d.ts

@@ -0,0 +1,55 @@
+import { type NamingContext, type SceneObjectPathIndex } from "@defold-typescript/transpiler";
+import { type SceneIndexCache } from "./scene-index-cache";
+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[]>;
+}
+/**
+ * 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 declare function projectObjectIndex(cache: SceneIndexCache): SceneObjectPathIndex;
+/**
+ * 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 declare function relativeUniverseFor(cache: SceneIndexCache, fileName: string): RelativeUniverse;
+/**
+ * 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 declare function worldsFor(cache: SceneIndexCache, fileName: string): readonly (string | undefined)[];
+/**
+ * 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 declare function offersBareWorld(universe: RelativeUniverse): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/tstl-plugin",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "TypeScript language-service plugin surfacing Defold transpiler diagnostics live in the editor.",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/transpiler": "0.30.0",
-    "@defold-typescript/types": "0.30.0"
+    "@defold-typescript/transpiler": "0.31.0",
+    "@defold-typescript/types": "0.31.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0 <7"

package/src/index.ts

@@ -2,12 +2,12 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import {
   ANIMATION_ASSET_EXTENSIONS,
+  buildComponentAnimationIndex,
   buildConfigKeyIndex,
+  buildGuiFlipbookIndex,
   buildGuiNodeIndex,
   buildInputActionIndex,
-  buildSceneComponentIndex,
   buildSceneObjectPathIndex,
-  buildSpriteAnimationIndex,
   type ClassifiedSlot,
   componentIdOfSameObjectAddress,
   computeOutputRel,
@@ -31,12 +31,16 @@ import {
   CONTRIBUTED_ENTRY_KIND,
   DEFOLD_COMPLETION_SOURCE,
 } from "./scene-completions";
+import { sceneReachabilityDiagnostics } from "./scene-diagnostics";
 import {
   createSceneIndexCache,
   type SceneIndexCache,
   type SceneWatchHost,
+  sceneCollectionRolesOf,
+  sceneComponentIndexOf,
 } from "./scene-index-cache";
-import { resolveEntryProvenance } from "./scene-provenance";
+import { resolveEntryProvenance, resolveRelativeEntryProvenance } from "./scene-provenance";
+import { offersBareWorld, relativeUniverseFor } from "./scene-relative-addresses";
 
 const requireFromHere = createRequire(import.meta.url);
 
@@ -76,35 +80,50 @@ function componentEntries(
   // suggestion claims nothing about what is absent.
   return buildSceneCompletionEntries({
     slot,
-    ids: cache.derived(
-      "component-ids",
-      () => buildSceneComponentIndex(cache.documents().documents).ids,
-    ),
+    ids: sceneComponentIndexOf(cache).ids,
     baseEntries,
   });
 }
 
 // The exact complement of `componentEntries`' guard, so precisely one of the two
-// universes answers any caret in an address. Project-wide like the component
-// universe, and for the same reason: what a path resolves to at runtime depends
-// on the collection that was loaded, which the file being edited does not say.
+// universes answers any caret in an address. The absolute half is project-wide
+// like the component universe, and for the same reason: what a path resolves to
+// at runtime depends on the collection that was loaded, which the file being
+// edited does not say. The relative half cannot be — a relative address
+// continues the collection path of the object hosting *this* script — so it is
+// read per file and merged in, and the caller's own world decides whether a bare
+// absolute path can resolve at all.
 function objectPathEntries(
   slot: ClassifiedSlot,
   position: number,
   cache: SceneIndexCache,
+  fileName: string,
   baseEntries: readonly ts.CompletionEntry[],
 ): ts.CompletionEntry[] {
   if (isFragmentCaret(slot, position)) {
     return [];
   }
-  return buildAddressPathCompletionEntries({
-    slot,
-    paths: cache.derived(
-      "object-paths",
-      () => buildSceneObjectPathIndex(cache.documents().documents).paths,
-    ),
-    baseEntries,
-  });
+  const universe = relativeUniverseFor(cache, fileName);
+  const bare = offersBareWorld(universe);
+  const absolute = cache.derived(
+    "object-paths",
+    () =>
+      buildSceneObjectPathIndex(cache.documents().documents, sceneCollectionRolesOf(cache)).paths,
+  );
+  const paths = new Set<string>();
+  for (const key of absolute) {
+    if (bare || !key.startsWith("/")) paths.add(key);
+  }
+  for (const key of universe.paths) paths.add(key);
+  const entries = buildAddressPathCompletionEntries({ slot, paths, baseEntries });
+  // A join is the whole literal, so accepting one where the author already typed
+  // a `#` would silently rewrite the fragment they are holding.
+  if (slot.fragmentStart === -1) {
+    entries.push(
+      ...buildWholeLiteralCompletionEntries({ slot, ids: universe.addresses, baseEntries }),
+    );
+  }
+  return entries;
 }
 
 // No caret guard: the span is the whole literal, so an entry is well-formed
@@ -131,24 +150,46 @@ function nodeEntries(
 }
 
 // Also no caret guard, and the same forward output-path mapping — but scoped
-// one step further than a node id: to the sprite component the slot's *sibling*
-// literal addresses on the one game object that owns this script. Every
-// unresolved link returns nothing rather than a project-wide guess, because a
-// `sprite.play_flipbook` id the addressed atlas does not declare is a runtime
-// crash.
+// one step further than a node id, in whichever of the two ways the slot's own
+// entry declares. Every unresolved link returns nothing rather than a
+// project-wide guess, because an animation id the resolved atlas does not
+// declare is a runtime crash.
+//
+// The branch is the table's own discriminator rather than a second arm in the
+// class chain: an `animation` entry names either an address companion or a node
+// companion, and the drift guard is what keeps it to exactly one.
 function animationEntries(
   slot: ClassifiedSlot,
   cache: SceneIndexCache,
   fileName: string,
   baseEntries: readonly ts.CompletionEntry[],
 ): ts.CompletionEntry[] {
+  const { projectRoot } = cache;
+  // Scoped to the `.gui` scene naming this file's generated gui script, never
+  // to the node the call addresses: `gui.set_texture` retargets a node at
+  // runtime, so the scene's textures are the honest universe.
+  if (slot.nodeParameter !== undefined) {
+    const index = cache.derived("gui-flipbook", () =>
+      buildGuiFlipbookIndex({
+        scenes: cache.documents(GUI_EXTENSIONS).documents,
+        assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents,
+      }),
+    );
+    const config = readBuildConfigFromHost(cache.host, projectRoot);
+    const resource = computeOutputRel(displayPathOf(projectRoot, fileName), config, "gui-script");
+    const declared = index.byScriptResource.get(resource);
+    return declared === undefined
+      ? []
+      : buildWholeLiteralCompletionEntries({ slot, ids: new Set(declared.keys()), baseEntries });
+  }
+  // Scoped to the sprite or model component the slot's *sibling* literal
+  // addresses on the one game object that owns this script.
   const component = componentIdOfSameObjectAddress(slot.addressText ?? "");
   if (component === undefined) {
     return [];
   }
-  const { projectRoot } = cache;
-  const index = cache.derived("sprite-animations", () =>
-    buildSpriteAnimationIndex({
+  const index = cache.derived("component-animations", () =>
+    buildComponentAnimationIndex({
       scenes: cache.documents().documents,
       assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents,
     }),
@@ -210,23 +251,17 @@ function actionIdEntries(
 }
 
 // The panel a claimed request is answered with. `documentation` rather than
-// `displayParts` carries the paths because a host renders the former as the
-// body of the panel, which is where a list of files reads as one.
-function provenancePanel(
-  entryName: string,
-  declaredIn: readonly string[],
-): ts.CompletionEntryDetails {
+// `displayParts` carries the sentence because a host renders the former as the
+// body of the panel, which is where a list of files — or of objects — reads as
+// one. The sentence is the caller's, since an absolute entry is answered with
+// the files declaring it and a relative one with the objects it resolves from.
+function provenancePanel(entryName: string, documentation: string): ts.CompletionEntryDetails {
   return {
     name: entryName,
     kind: CONTRIBUTED_ENTRY_KIND,
     kindModifiers: "",
     displayParts: [{ kind: "stringLiteral", text: JSON.stringify(entryName) }],
-    documentation: [
-      {
-        kind: "text",
-        text: `Declared in ${declaredIn.join(", ")}`,
-      },
-    ],
+    documentation: [{ kind: "text", text: documentation }],
     source: [{ kind: "text", text: DEFOLD_COMPLETION_SOURCE }],
   };
 }
@@ -304,8 +339,23 @@ export default function init(modules: { typescript: typeof import("typescript")
       if (!slot) {
         return forward();
       }
+      // Tried first because the two universes are disjoint by construction and
+      // only this one knows which object an entry is relative to; a name it does
+      // not carry falls straight through to the declaring-file answer.
+      const relative = resolveRelativeEntryProvenance({
+        slot,
+        position,
+        cache,
+        fileName,
+        entryName,
+      });
+      if (relative !== undefined) {
+        return provenancePanel(entryName, relative);
+      }
       const declaredIn = resolveEntryProvenance({ slot, position, cache, fileName, entryName });
-      return declaredIn.length === 0 ? forward() : provenancePanel(entryName, declaredIn);
+      return declaredIn.length === 0
+        ? forward()
+        : provenancePanel(entryName, `Declared in ${declaredIn.join(", ")}`);
     };
 
     proxy.getSemanticDiagnostics = (fileName: string): ts.Diagnostic[] => {
@@ -319,7 +369,13 @@ export default function init(modules: { typescript: typeof import("typescript")
       const transpiler = getProgramDiagnostics(program, program.getSourceFile(fileName)).map(
         (diagnostic) => ({ ...diagnostic, category: ts.DiagnosticCategory.Suggestion }),
       );
-      return [...prior, ...transpiler];
+      // The same advisory posture, and the same absent-cache early return the
+      // completion path takes: a host that cannot enumerate files has no scene
+      // universe, and an empty one would report every address as unreachable.
+      const table = loadUrlParameterTable();
+      const scene =
+        cache && table ? sceneReachabilityDiagnostics({ ts, program, table, cache, fileName }) : [];
+      return [...prior, ...transpiler, ...scene];
     };
 
     // Strictly additive: every path that cannot produce a suggestion returns the
@@ -354,7 +410,7 @@ export default function init(modules: { typescript: typeof import("typescript")
       const entries = isAddressClass(slot.class)
         ? [
             ...componentEntries(slot, position, cache, baseEntries),
-            ...objectPathEntries(slot, position, cache, baseEntries),
+            ...objectPathEntries(slot, position, cache, fileName, baseEntries),
           ]
         : slot.class === "gui-node"
           ? nodeEntries(slot, cache, fileName, baseEntries)

package/src/scene-diagnostics.ts

@@ -0,0 +1,92 @@
+import {
+  checkCrossWorldAddresses,
+  checkUrlFragmentReachability,
+} from "@defold-typescript/transpiler";
+import type { UrlParameterTable } from "@defold-typescript/types";
+import type * as ts from "typescript";
+import { type SceneIndexCache, sceneComponentIndexOf } from "./scene-index-cache";
+import { projectObjectIndex, worldsFor } from "./scene-relative-addresses";
+
+/** The `source` an editor renders beside the message, and `--json` never sees. */
+export const DEFOLD_DIAGNOSTIC_SOURCE = "defold-typescript";
+
+// A range neither TypeScript (< 100000) nor tstl occupies, so a host filtering
+// by code can tell the two address findings apart from each other and from
+// everything else the language service reports.
+const UNREACHABLE_FRAGMENT_CODE = 9_000_101;
+const FOREIGN_SOCKET_CODE = 9_000_102;
+
+function suggestion(
+  typescript: typeof import("typescript"),
+  file: ts.SourceFile,
+  finding: { readonly start: number; readonly length: number; readonly message: string },
+  code: number,
+): ts.Diagnostic {
+  return {
+    file,
+    start: finding.start,
+    length: finding.length,
+    messageText: finding.message,
+    category: typescript.DiagnosticCategory.Suggestion,
+    source: DEFOLD_DIAGNOSTIC_SOURCE,
+    code,
+  };
+}
+
+/**
+ * The address findings the editor surfaces on the file being edited, as
+ * advisory suggestions.
+ *
+ * Every path that cannot produce one answers with an empty array. A suppressed
+ * reachability report is the important case: there is no file span on which a
+ * "the check did not run" notice could honestly sit, and a speculative squiggle
+ * is worse than none — the build says so in prose instead, where a whole-project
+ * line has somewhere to go.
+ *
+ * The *whole* hole is one index, composed the way `sceneIndexForBuild` composes
+ * it: what the parse could not read plus what the walk could not reach. The
+ * completion path deliberately reads a partial universe — a suggestion claims
+ * nothing about what is absent — but a finding does, so a component declared
+ * only by an unresolved dependency suppresses the check rather than reporting
+ * the address as unreachable.
+ */
+export function sceneReachabilityDiagnostics(input: {
+  ts: typeof import("typescript");
+  program: ts.Program;
+  table: UrlParameterTable;
+  cache: SceneIndexCache;
+  fileName: string;
+}): ts.Diagnostic[] {
+  const { ts: typescript, program, table, cache, fileName } = input;
+  const sourceFile = program.getSourceFile(fileName);
+  if (!sourceFile) {
+    return [];
+  }
+  const index = sceneComponentIndexOf(cache);
+  const report = checkUrlFragmentReachability({
+    program,
+    table,
+    index: { ids: index.ids, incomplete: [...index.incomplete, ...cache.documents().unreadable] },
+    objects: projectObjectIndex(cache),
+    sourceFiles: [sourceFile],
+  });
+  const fragments =
+    report.kind === "suppressed"
+      ? []
+      : report.findings.map((finding) =>
+          suggestion(typescript, sourceFile, finding, UNREACHABLE_FRAGMENT_CODE),
+        );
+
+  // Outside the branch above, never inside it: the two honesty rules are
+  // independent — one suppresses index-wide on an incomplete component universe,
+  // the other withholds per file on an unresolvable world — which is the reason
+  // the transpiler kept them as two exports rather than one.
+  const crossWorld = checkCrossWorldAddresses({
+    program,
+    table,
+    worldsOf: (name) => worldsFor(cache, name),
+    sourceFiles: [sourceFile],
+  }).map((finding) => suggestion(typescript, sourceFile, finding, FOREIGN_SOCKET_CODE));
+
+  return [...fragments, ...crossWorld];
+}

package/src/scene-index-cache.ts

@@ -1,9 +1,17 @@
 import {
+  buildSceneCollectionRoles,
+  buildSceneComponentIndex,
+  COLLECTION_REFERENCE_EXTENSIONS,
   displayPathOf,
+  GAME_PROJECT_DOCUMENT,
   isExcludedProjectPath,
+  LIBRARY_DEPENDENCY_ROOT,
   listProjectResourcePaths,
+  PROJECT_EXTENSIONS,
   readSceneDocuments,
   SCENE_EXTENSIONS,
+  type SceneCollectionRoles,
+  type SceneComponentIndex,
   type SceneReadHost,
 } from "@defold-typescript/transpiler";
 import type * as ts from "typescript";
@@ -81,6 +89,19 @@ export function createSceneIndexCache(host: SceneWatchHost, projectRoot: string)
 
   function affectsCache(hostPath: string): boolean {
     const displayPath = displayPathOf(projectRoot, hostPath);
+    // `resolve` rewrites this surface wholesale, and `.defold-types/` is
+    // `.defignore`d — so the exclusion test below would throw the event away and
+    // leave the editor offering ids from a dependency the author just removed.
+    // The manifest counts too: it alone changes when a dependency is dropped.
+    // The root itself, not only its descendants: removing the last dependency
+    // deletes the whole directory and writes nothing inside it, so that event is
+    // the only one a watcher reports.
+    if (
+      displayPath === LIBRARY_DEPENDENCY_ROOT ||
+      displayPath.startsWith(`${LIBRARY_DEPENDENCY_ROOT}/`)
+    ) {
+      return true;
+    }
     if (isExcludedProjectPath(displayPath)) return false;
     for (const extension of servedExtensions) {
       if (displayPath.endsWith(extension)) return true;
@@ -166,3 +187,30 @@ export function createSceneIndexCache(host: SceneWatchHost, projectRoot: string)
     },
   };
 }
+
+// The component-id universe, whole — ids *and* the walk's own record of what it
+// could not prove — read through the cache so one walk serves both readers. The
+// two disagree about what to do with the hole rather than about how to build it:
+// a completion suggests from a partial universe, a finding must not, so the
+// index is shared here and each caller applies its own rule.
+export function sceneComponentIndexOf(cache: SceneIndexCache): SceneComponentIndex {
+  return cache.derived("component-index", () =>
+    buildSceneComponentIndex(cache.documents().documents),
+  );
+}
+
+// The world each collection is, read through the cache so the completion path
+// and the provenance path share one classification — and so the walk over the
+// proxy/factory documents and `game.project` is invalidated by the same
+// watchers the scene walk is. Both call sites go through here rather than
+// building roles of their own, which is what would let one of them drift back
+// to offering every collection's paths bare.
+export function sceneCollectionRolesOf(cache: SceneIndexCache): SceneCollectionRoles {
+  return cache.derived("collection-roles", () =>
+    buildSceneCollectionRoles({
+      documents: cache.documents().documents,
+      references: cache.documents(COLLECTION_REFERENCE_EXTENSIONS).documents,
+      gameProject: cache.documents(PROJECT_EXTENSIONS).documents.get(GAME_PROJECT_DOCUMENT),
+    }),
+  );
+}

package/src/scene-provenance.ts

@@ -1,11 +1,12 @@
 import {
   ANIMATION_ASSET_EXTENSIONS,
+  buildComponentAnimationIndex,
   buildConfigKeyIndex,
+  buildGuiFlipbookIndex,
   buildGuiNodeIndex,
   buildInputActionIndex,
   buildSceneComponentIndex,
   buildSceneObjectPathIndex,
-  buildSpriteAnimationIndex,
   type ClassifiedSlot,
   componentIdOfSameObjectAddress,
   computeOutputRel,
@@ -18,7 +19,8 @@ import {
   PROJECT_EXTENSIONS,
 } from "@defold-typescript/transpiler";
 import { readBuildConfigFromHost } from "./build-config";
-import type { SceneIndexCache } from "./scene-index-cache";
+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
@@ -27,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[]>;
 
@@ -123,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;
@@ -140,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
@@ -175,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)
+  );
+}