@defold-typescript/transpiler 0.30.0 → 0.32.0

package/src/url-fragment-reachability.ts

@@ -6,6 +6,9 @@
 import type { UrlParameterTable } from "@defold-typescript/types";
 import * as ts from "typescript";
 import type { SceneComponentIndex } from "./scene-component-index";
+import { socketOfAddress } from "./scene-naming-context";
+import type { SceneObjectPathIndex } from "./scene-object-path-index";
+import { canonicalHashSymbols, isAmbient, staticAddressTextOf } from "./url-address-literals";
 import { addressClassOfArgument, isAddressClass } from "./url-address-slots";
 
 export interface UrlFragmentFinding {
@@ -16,103 +19,72 @@ export interface UrlFragmentFinding {
   readonly message: string;
 }
 
-export type UrlFragmentReport =
-  | { readonly kind: "suppressed"; readonly reasons: readonly string[] }
-  | { readonly kind: "checked"; readonly findings: readonly UrlFragmentFinding[] };
+// The half of the joined index this check reads: which objects exist, what each
+// owns, and — the precondition rather than decoration — whether the walk placed
+// every world it found. `incomplete` is carried because a world it could not
+// place contributes no key at all, so nothing downstream can notice its absence.
+export type SceneObjectComponents = Pick<
+  SceneObjectPathIndex,
+  "paths" | "componentsOf" | "incomplete"
+>;
 
-function isAmbient(fileName: string): boolean {
-  return /[\\/]node_modules[\\/]/.test(fileName) || /(^|[\\/])lib\.[^\\/]*\.d\.ts$/.test(fileName);
+// The path portion of an index key, with any proxy socket stripped: `/enemy` for
+// both the bootstrap `/enemy` and the proxied `mylevel:/enemy`.
+function pathOfKey(key: string): string {
+  const socket = socketOfAddress(key);
+  return socket === undefined ? key : key.slice(socket.length + 1);
 }
 
-// The symbol a generic type reference was instantiated from — `undefined` for
-// anything that is not one.
-function referenceTargetSymbol(type: ts.Type): ts.Symbol | undefined {
-  if ((type.flags & ts.TypeFlags.Object) === 0) return undefined;
-  if (((type as ts.ObjectType).objectFlags & ts.ObjectFlags.Reference) === 0) return undefined;
-  return (type as ts.TypeReference).target.symbol;
-}
-
-// What the global `Hash` *type* name means in scope at the anchor, as symbols.
-// The shipped `type Hash<S extends string = string> = Core.Hash<S>` yields the
-// `Core.Hash` symbol; a project's `Project.Hash` is not in global scope under
-// the bare name and never appears, and a project cannot add a second global
-// `Hash` type without a duplicate-identifier error — so unlike the *name*, this
-// anchor cannot be shadowed.
-function ambientHashAliasTargets(checker: ts.TypeChecker, anchor: ts.Node): ReadonlySet<ts.Symbol> {
-  const targets = new Set<ts.Symbol>();
-  for (const symbol of checker.getSymbolsInScope(anchor, ts.SymbolFlags.Type)) {
-    if (symbol.name !== "Hash") continue;
-    const target = referenceTargetSymbol(checker.getDeclaredTypeOfSymbol(symbol));
-    if (target) targets.add(target);
-  }
-  return targets;
-}
+// The components the object an address names declares, or `undefined` wherever
+// the answer is not provable — no object index, a fragment with no path, a
+// relative path, a path no world declares, or a path some world declares but
+// whose prototype could not be read. Every one of those falls back to the
+// project-wide id set, because withholding a finding is the only safe direction.
+function declaredComponentsOf(
+  objects: SceneObjectComponents | undefined,
+  path: string,
+): readonly string[] | undefined {
+  if (objects === undefined || path === "") return undefined;
 
-// The declarations *the* `Hash` can come from, resolved from the two anchors the
-// shipped ambient declarations carry one line apart rather than from the file
-// `Hash` happens to be declared in. A path test answers differently for an
-// installed `node_modules/@defold-typescript/types/…` and a workspace-resolved
-// `packages/types/…` copy of the very same declarations, which silently emptied
-// this report for anyone consuming the package through a `paths` mapping or a
-// symlink (bug-121); a symbol identity holds under both.
-//
-// The answer is the *intersection* of the two anchors. The `hash` function is
-// the scope-and-fail-closed anchor: its scope anchor is an ambient file so that
-// no user module's own `hash` participates, and every call signature is walked
-// because a project's global-script `function hash(s: string): string` *merges*
-// into this symbol rather than replacing it — the declarations then span both
-// files and a fully-qualified-name test would reject the real one. The global
-// `Hash` alias is the identity anchor: the function alone is not enough, because
-// a merged project overload contributes its own signatures, and testing what
-// they return by *name* admits any project type called `Hash` and then reports a
-// type argument that was never an address (bug-122). Asking the checker instead
-// of the filesystem is the same discipline as `tableKey` in
-// `url-address-slots.ts`.
-function canonicalHashSymbols(
-  checker: ts.TypeChecker,
-  program: ts.Program,
-): ReadonlySet<ts.Symbol> {
-  const files = program.getSourceFiles();
-  const anchor = files.find((file) => isAmbient(file.fileName)) ?? files[0];
-  const canonical = new Set<ts.Symbol>();
-  if (!anchor) return canonical;
+  // A world `buildSceneCollectionRoles` could not place composes no key, so it
+  // is invisible to the withheld-`componentsOf` rule below: that rule defends a
+  // key that is in `paths`, and this one never got there. Every address form
+  // withdraws together, because `incomplete` carries free prose and there is no
+  // structured way to ask whether a given hole could own a given path. The
+  // project-wide test still runs — this is a fallback, never a suppression.
+  if (objects.incomplete.length > 0) return undefined;
 
-  const aliased = ambientHashAliasTargets(checker, anchor);
+  if (socketOfAddress(path) !== undefined) {
+    return objects.paths.has(path) ? objects.componentsOf.get(path) : undefined;
+  }
+  if (!path.startsWith("/")) return undefined;
 
-  for (const symbol of checker.getSymbolsInScope(anchor, ts.SymbolFlags.Function)) {
-    if (symbol.name !== "hash") continue;
-    const declaration = symbol.declarations?.[0];
-    if (!declaration) continue;
-    for (const signature of checker
-      .getTypeOfSymbolAtLocation(symbol, declaration)
-      .getCallSignatures()) {
-      const target = referenceTargetSymbol(signature.getReturnType());
-      if (target && aliased.has(target)) canonical.add(target);
-    }
+  // A bare absolute path names one object per world, and the script writing it
+  // could be running in any of them, so the union is the only claim that holds
+  // whichever world it is. One withheld key withholds the whole union: a
+  // readable sibling must not stand in for a prototype nobody could read.
+  const declared = new Set<string>();
+  let known = false;
+  for (const key of objects.paths) {
+    if (pathOfKey(key) !== path) continue;
+    const owned = objects.componentsOf.get(key);
+    if (owned === undefined) return undefined;
+    known = true;
+    for (const id of owned) declared.add(id);
   }
-  return canonical;
+  return known ? [...declared].sort() : undefined;
 }
 
-// The string a `Hash` was hashed from, recovered from its type argument —
-// `undefined` for anything else, including a bare `Hash`, a `Url`, a `string`,
-// and a union. `hash` records the argument in `Hash<S>` (see the `Hash` JSDoc in
-// `@defold-typescript/types`), so `const SPRITE = hash("#sprite")` carries the
-// text on the constant's type and no reassignment tracking is needed.
-//
-// The interface must be *the* `Hash`: a project's own generic type named `Hash`
-// resolves to its own declaration, and reading a type argument off it would
-// report a fragment that was never an address. `canonical` is what settles that.
-function hashedSourceOfType(
-  checker: ts.TypeChecker,
-  type: ts.Type,
-  canonical: ReadonlySet<ts.Symbol>,
-): string | undefined {
-  const target = referenceTargetSymbol(type);
-  if (!target || !canonical.has(target)) return undefined;
-  const [source] = checker.getTypeArguments(type as ts.TypeReference);
-  return source?.isStringLiteral() ? source.value : undefined;
+function declaredPhrase(ids: readonly string[]): string {
+  return ids.length === 0
+    ? "it declares no components at all"
+    : `it declares ${ids.map((id) => `"${id}"`).join(", ")}`;
 }
 
+export type UrlFragmentReport =
+  | { readonly kind: "suppressed"; readonly reasons: readonly string[] }
+  | { readonly kind: "checked"; readonly findings: readonly UrlFragmentFinding[] };
+
 // Report every address-slot expression whose text is statically known — a
 // quoted or backtick-quoted literal, or a value whose `Hash` type still carries
 // the string it was hashed from — whose `#fragment` names a component no
@@ -126,9 +98,10 @@ export function checkUrlFragmentReachability(input: {
   program: ts.Program;
   table: UrlParameterTable;
   index: SceneComponentIndex;
+  objects?: SceneObjectComponents;
   sourceFiles?: readonly ts.SourceFile[];
 }): UrlFragmentReport {
-  const { program, table, index, sourceFiles } = input;
+  const { program, table, index, objects, sourceFiles } = input;
   if (index.incomplete.length > 0) {
     return { kind: "suppressed", reasons: index.incomplete };
   }
@@ -147,21 +120,27 @@ export function checkUrlFragmentReachability(input: {
 
     const visit = (node: ts.Node): void => {
       if (ts.isExpression(node) && isAddressClass(addressClassOfArgument(checker, table, node))) {
-        const text = ts.isStringLiteralLike(node)
-          ? node.text
-          : hashedSourceOfType(checker, checker.getTypeAtLocation(node), canonical);
+        const text = staticAddressTextOf(checker, node, canonical);
         if (text !== undefined) {
           const hash = text.indexOf("#");
           const fragment = hash === -1 ? "" : text.slice(hash + 1);
-          if (fragment !== "" && !index.ids.has(fragment)) {
+          const declared =
+            fragment === "" ? undefined : declaredComponentsOf(objects, text.slice(0, hash));
+          const reachable =
+            declared === undefined ? index.ids.has(fragment) : declared.includes(fragment);
+          if (fragment !== "" && !reachable) {
+            const path = text.slice(0, hash);
             findings.push({
               fileName: sourceFile.fileName,
               start: node.getStart(sourceFile),
               length: node.getWidth(sourceFile),
               fragment,
               message:
-                `no \`.go\` or \`.collection\` in this project declares a component with the id ` +
-                `"${fragment}", so this address cannot resolve at runtime`,
+                declared === undefined
+                  ? `no \`.go\` or \`.collection\` in this project declares a component with the id ` +
+                    `"${fragment}", so this address cannot resolve at runtime`
+                  : `the game object "${path}" declares no component with the id "${fragment}" ` +
+                    `(${declaredPhrase(declared)}), so this address cannot resolve at runtime`,
             });
           }
         }

package/src/sprite-animation-index.ts

@@ -1,241 +0,0 @@
-import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
-
-// The animation ids each script may play, keyed first by the project-relative
-// resource path of the `.script` that owns them and then by the id of the
-// sprite component they belong to, plus an honest record of every link that
-// could not be settled. A missing key means nothing may be offered for it; an
-// empty set means the component resolved and declares no animation.
-export interface SpriteAnimationIndex {
-  readonly byScriptResource: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
-  // The display path of the tile source each keyed component's ids were read
-  // from, under the same two keys. Present for exactly the components
-  // `byScriptResource` keys, so the two can never disagree about a resource.
-  readonly tileSetByScriptResource: ReadonlyMap<string, ReadonlyMap<string, string>>;
-  readonly unresolved: readonly string[];
-}
-
-// Resource paths inside a scene are project-absolute; the index is keyed the
-// way `buildGuiNodeIndex` keys its own, with the leading `/` dropped, so a
-// caller maps the file it holds forward through the build's output-path math
-// and looks the result up here.
-function resourceKey(resource: string): string {
-  return resource.startsWith("/") ? resource.slice(1) : resource;
-}
-
-// The keys a caller supplies name files on the host, so they may arrive with
-// native separators; the resource paths they are matched against come out of
-// scene content and are always `/`-separated. Normalizing here enforces that
-// contract at the boundary instead of leaving it to whichever caller happens
-// to build the maps.
-function normalizeDocumentKey(path: string): string {
-  return path.replaceAll("\\", "/");
-}
-
-const SCRIPT_SUFFIX = ".script";
-const SPRITE_SUFFIX = ".sprite";
-
-function firstField(message: SceneMessage, name: string): string | undefined {
-  return (message.fields.get(name) ?? [])[0];
-}
-
-function childrenOf(message: SceneMessage, name: string): readonly SceneMessage[] {
-  return message.messages.get(name) ?? [];
-}
-
-// Only `animations { id: … }` counts. Defold may also expose a bare
-// `images { image: … }` entry as a one-frame animation named after the file,
-// which is unverified here — and a wrong suggestion in this slot is a runtime
-// crash rather than a no-op.
-function declaredAnimations(document: SceneMessage): Set<string> {
-  const ids = new Set<string>();
-  for (const animation of childrenOf(document, "animations")) {
-    for (const id of animation.fields.get("id") ?? []) {
-      if (id !== "") ids.add(id);
-    }
-  }
-  return ids;
-}
-
-interface AssetIndex {
-  readonly animationsByTileSet: Map<string, Set<string>>;
-  readonly tileSetBySprite: Map<string, string>;
-}
-
-function readAssets(assets: ReadonlyMap<string, string>, unresolved: string[]): AssetIndex {
-  const animationsByTileSet = new Map<string, Set<string>>();
-  const tileSetBySprite = new Map<string, string>();
-
-  for (const [path, text] of assets) {
-    const displayPath = normalizeDocumentKey(path);
-    let document: SceneMessage;
-    try {
-      document = parseSceneTextFormat(text);
-    } catch (error) {
-      if (!(error instanceof SceneTextFormatError)) throw error;
-      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
-      continue;
-    }
-    if (displayPath.endsWith(SPRITE_SUFFIX)) {
-      const tileSet = firstField(document, "tile_set");
-      if (tileSet !== undefined) tileSetBySprite.set(displayPath, resourceKey(tileSet));
-      continue;
-    }
-    animationsByTileSet.set(displayPath, declaredAnimations(document));
-  }
-
-  return { animationsByTileSet, tileSetBySprite };
-}
-
-// The sprite components of one game object, as `id -> tile_set resource`. An
-// embedded sprite carries its own payload; a referenced one names a `.sprite`
-// document that carries it instead.
-function spriteTileSets(
-  object: SceneMessage,
-  displayPath: string,
-  assets: AssetIndex,
-  unresolved: string[],
-): Map<string, string> {
-  const tileSets = new Map<string, string>();
-
-  for (const embedded of childrenOf(object, "embedded_components")) {
-    if (firstField(embedded, "type") !== "sprite") continue;
-    const id = firstField(embedded, "id");
-    const payload = firstField(embedded, "data");
-    if (id === undefined || payload === undefined) continue;
-    try {
-      const tileSet = firstField(parseSceneTextFormat(payload), "tile_set");
-      if (tileSet !== undefined) tileSets.set(id, resourceKey(tileSet));
-    } catch (error) {
-      if (!(error instanceof SceneTextFormatError)) throw error;
-      unresolved.push(
-        `${displayPath}: the embedded sprite "${id}" could not be read (${error.message})`,
-      );
-    }
-  }
-
-  for (const referenced of childrenOf(object, "components")) {
-    const component = firstField(referenced, "component");
-    const id = firstField(referenced, "id");
-    if (id === undefined || component === undefined || !component.endsWith(SPRITE_SUFFIX)) continue;
-    const tileSet = assets.tileSetBySprite.get(resourceKey(component));
-    if (tileSet === undefined) {
-      unresolved.push(
-        `${displayPath}: the sprite component "${id}" names ${component}, which is not among the project's sprite documents`,
-      );
-      continue;
-    }
-    tileSets.set(id, tileSet);
-  }
-
-  return tileSets;
-}
-
-function scriptResourcesOf(object: SceneMessage): string[] {
-  const resources: string[] = [];
-  for (const component of childrenOf(object, "components")) {
-    const resource = firstField(component, "component");
-    if (resource === undefined || !resource.endsWith(SCRIPT_SUFFIX)) continue;
-    const key = resourceKey(resource);
-    if (key !== SCRIPT_SUFFIX.slice(1)) resources.push(key);
-  }
-  return resources;
-}
-
-function isGameObject(message: SceneMessage): boolean {
-  return message.messages.has("components") || message.messages.has("embedded_components");
-}
-
-export function buildSpriteAnimationIndex(input: {
-  scenes: ReadonlyMap<string, string>;
-  assets: ReadonlyMap<string, string>;
-}): SpriteAnimationIndex {
-  const unresolved: string[] = [];
-  const assets = readAssets(input.assets, unresolved);
-  const byScriptResource = new Map<string, ReadonlyMap<string, ReadonlySet<string>>>();
-  const tileSetByScriptResource = new Map<string, ReadonlyMap<string, string>>();
-  const claimedBy = new Map<string, string>();
-
-  // A `.go` document is a game object at its root; a `.collection` carries one
-  // inside each `embedded_instances` `data:` payload, decoded exactly one level
-  // at a time. No `instances { prototype: }` edge is followed: the referenced
-  // `.go` is its own document and already claims its own script.
-  function walk(message: SceneMessage, blockName: string, displayPath: string): void {
-    if (isGameObject(message)) {
-      claim(message, displayPath);
-    }
-    if (blockName === "embedded_instances") {
-      for (const payload of message.fields.get("data") ?? []) {
-        try {
-          walk(parseSceneTextFormat(payload), "", displayPath);
-        } catch (error) {
-          if (!(error instanceof SceneTextFormatError)) throw error;
-          unresolved.push(
-            `${displayPath}: an embedded game object could not be read (${error.message})`,
-          );
-        }
-      }
-    }
-    for (const [name, nested] of message.messages) {
-      for (const child of nested) {
-        walk(child, name, displayPath);
-      }
-    }
-  }
-
-  function claim(object: SceneMessage, displayPath: string): void {
-    const scripts = scriptResourcesOf(object);
-    if (scripts.length === 0) return;
-
-    const tileSets = spriteTileSets(object, displayPath, assets, unresolved);
-    const animations = new Map<string, ReadonlySet<string>>();
-    const declaringTileSets = new Map<string, string>();
-    for (const [id, tileSet] of tileSets) {
-      const declared = assets.animationsByTileSet.get(tileSet);
-      if (declared === undefined) {
-        unresolved.push(
-          `${displayPath}: the sprite component "${id}" names the tile source /${tileSet}, which is not among the project's asset documents`,
-        );
-        continue;
-      }
-      animations.set(id, declared);
-      declaringTileSets.set(id, tileSet);
-    }
-
-    for (const key of scripts) {
-      const owner = claimedBy.get(key);
-      if (owner !== undefined) {
-        byScriptResource.delete(key);
-        tileSetByScriptResource.delete(key);
-        unresolved.push(
-          `${key}: claimed by both ${owner} and ${displayPath}, so its sprite animations are ambiguous`,
-        );
-        continue;
-      }
-      claimedBy.set(key, displayPath);
-      byScriptResource.set(key, animations);
-      tileSetByScriptResource.set(key, declaringTileSets);
-    }
-  }
-
-  for (const [path, text] of input.scenes) {
-    const displayPath = normalizeDocumentKey(path);
-    try {
-      walk(parseSceneTextFormat(text), "", displayPath);
-    } catch (error) {
-      if (!(error instanceof SceneTextFormatError)) throw error;
-      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
-    }
-  }
-
-  return { byScriptResource, tileSetByScriptResource, unresolved };
-}
-
-// The component id a same-object `"#id"` address names, or `undefined` for
-// every other form. A path form names a component on a *different* game
-// object, so its id must never be resolved against this script's own.
-export function componentIdOfSameObjectAddress(address: string): string | undefined {
-  if (!address.startsWith("#")) return undefined;
-  const id = address.slice(1);
-  if (id === "" || id.includes("/") || id.includes("#")) return undefined;
-  return id;
-}