@defold-typescript/tstl-plugin 0.29.0 → 0.31.0

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.29.0",
+  "version": "0.31.0",
   "description": "TypeScript language-service plugin surfacing Defold transpiler diagnostics live in the editor.",
   "license": "MIT",
   "repository": {
@@ -11,32 +11,34 @@
   "homepage": "https://github.com/defold-typescript/toolchain#readme",
   "bugs": "https://github.com/defold-typescript/toolchain/issues",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "bun": "./src/index.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
     "dist",
     "src",
     "!src/**/*.test.ts",
+    "!src/**/completion-harness.ts",
     "!src/**/__snapshots__"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --target=node --format=esm --packages=external --outdir=dist && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build": "rm -rf dist && bun build src/index.ts --target=node --format=esm --packages=external --outdir=dist && cp src/require-entry.cjs dist/index.cjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/transpiler": "0.29.0",
-    "@defold-typescript/types": "0.29.0"
+    "@defold-typescript/transpiler": "0.31.0",
+    "@defold-typescript/types": "0.31.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0 <7"

package/src/build-config.ts

@@ -1,5 +1,9 @@
-import { type BuildConfig, DEFAULT_INCLUDE, parseBuildConfig } from "@defold-typescript/transpiler";
-import type { SceneReadHost } from "./scene-documents";
+import {
+  type BuildConfig,
+  DEFAULT_INCLUDE,
+  parseBuildConfig,
+  type SceneReadHost,
+} from "@defold-typescript/transpiler";
 
 // Alongside output is what the build itself does with no `outDir`, so it is also
 // the honest answer when the config cannot be read: a wrong guess would offer

package/src/index.ts

@@ -1,18 +1,24 @@
 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,
+  displayPathOf,
+  GAME_PROJECT_DOCUMENT,
+  GUI_EXTENSIONS,
   getProgramDiagnostics,
+  INPUT_BINDING_EXTENSIONS,
   isAddressClass,
   isFragmentCaret,
+  PROJECT_EXTENSIONS,
   resolveClassifiedSlotAtPosition,
 } from "@defold-typescript/transpiler";
 import type { UrlParameterTable } from "@defold-typescript/types";
@@ -25,20 +31,16 @@ import {
   CONTRIBUTED_ENTRY_KIND,
   DEFOLD_COMPLETION_SOURCE,
 } from "./scene-completions";
-import {
-  ANIMATION_ASSET_EXTENSIONS,
-  displayPathOf,
-  GAME_PROJECT_DOCUMENT,
-  GUI_EXTENSIONS,
-  INPUT_BINDING_EXTENSIONS,
-  PROJECT_EXTENSIONS,
-} from "./scene-documents";
+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);
 
@@ -78,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
@@ -133,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,
     }),
@@ -212,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 }],
   };
 }
@@ -306,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[] => {
@@ -321,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
@@ -356,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/require-entry.cjs

@@ -0,0 +1,6 @@
+// tsserver resolves a plugin with Node10 resolution — `exports` is not
+// consulted — and then rejects the loaded value unless it is itself a function.
+// `require()` of the ESM entry yields the namespace object instead, so this
+// CommonJS shim is what `main` points at: it unwraps the factory, and the ESM
+// bundle stays the single build of the plugin.
+module.exports = require("./index.js").default;

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,12 +1,20 @@
-import type * as ts from "typescript";
 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 "./scene-documents";
+} from "@defold-typescript/transpiler";
+import type * as ts from "typescript";
 
 // `SceneReadHost` plus the two watch facilities `ts.System` declares as
 // optional, typed off the editor's own callback types so the real
@@ -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),
+    }),
+  );
+}