@defold-typescript/tstl-plugin 0.24.0 → 0.25.0

package/src/index.ts

@@ -1,5 +1,237 @@
-import { getProgramDiagnostics } from "@defold-typescript/transpiler";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import {
+  buildConfigKeyIndex,
+  buildGuiNodeIndex,
+  buildInputActionIndex,
+  buildSceneComponentIndex,
+  buildSceneObjectPathIndex,
+  buildSpriteAnimationIndex,
+  type ClassifiedSlot,
+  componentIdOfSameObjectAddress,
+  computeOutputRel,
+  getProgramDiagnostics,
+  isAddressClass,
+  isFragmentCaret,
+  resolveClassifiedSlotAtPosition,
+} from "@defold-typescript/transpiler";
+import type { UrlParameterTable } from "@defold-typescript/types";
 import type * as ts from "typescript";
+import { readBuildConfigFromHost } from "./build-config";
+import {
+  buildAddressPathCompletionEntries,
+  buildSceneCompletionEntries,
+  buildWholeLiteralCompletionEntries,
+  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 {
+  createSceneIndexCache,
+  type SceneIndexCache,
+  type SceneWatchHost,
+} from "./scene-index-cache";
+import { resolveEntryProvenance } from "./scene-provenance";
+
+const requireFromHere = createRequire(import.meta.url);
+
+// The JSON subpath, never the package's `.` entry: `@defold-typescript/types`
+// resolves that entry to TypeScript source, which would survive
+// `--packages=external` into the packed plugin and fail under plain node the
+// way bug-88 did. A declared subpath of plain JSON carries none of that hazard.
+// Resolved and read rather than `require`d, so the value never depends on
+// whether something else in the host process already imported it as a module.
+let urlParameterTable: UrlParameterTable | undefined;
+function loadUrlParameterTable(): UrlParameterTable | undefined {
+  if (!urlParameterTable) {
+    try {
+      const path = requireFromHere.resolve("@defold-typescript/types/url-parameters.json");
+      urlParameterTable = JSON.parse(readFileSync(path, "utf8")) as UrlParameterTable;
+    } catch {
+      return undefined;
+    }
+  }
+  return urlParameterTable;
+}
+
+// A slot resolves for a caret anywhere inside the quotes, but a component
+// entry's `replacementSpan` only ever covers the fragment — so offering one to
+// a caret in the path would edit text the author is not standing on. The guard
+// is above the walk, so a caret in the path costs no `.go`/`.collection` parse.
+function componentEntries(
+  slot: ClassifiedSlot,
+  position: number,
+  cache: SceneIndexCache,
+  baseEntries: readonly ts.CompletionEntry[],
+): ts.CompletionEntry[] {
+  if (!isFragmentCaret(slot, position)) {
+    return [];
+  }
+  // A partial universe still suggests — unlike the reachability report, a
+  // suggestion claims nothing about what is absent.
+  return buildSceneCompletionEntries({
+    slot,
+    ids: cache.derived(
+      "component-ids",
+      () => buildSceneComponentIndex(cache.documents().documents).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.
+function objectPathEntries(
+  slot: ClassifiedSlot,
+  position: number,
+  cache: SceneIndexCache,
+  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,
+  });
+}
+
+// No caret guard: the span is the whole literal, so an entry is well-formed
+// wherever inside the quotes the caret sits. Node ids are scoped to the single
+// `.gui` that names this file's generated script — a project-wide union would
+// offer ids `gui.get_node` could never resolve at runtime. A scene names an
+// output resource, and an output path cannot say which include base produced it,
+// so the file being edited is mapped forward through the build's own math rather
+// than the resource being mapped back.
+function nodeEntries(
+  slot: ClassifiedSlot,
+  cache: SceneIndexCache,
+  fileName: string,
+  baseEntries: readonly ts.CompletionEntry[],
+): ts.CompletionEntry[] {
+  const { projectRoot } = cache;
+  const index = cache.derived("gui-nodes", () =>
+    buildGuiNodeIndex(cache.documents(GUI_EXTENSIONS).documents),
+  );
+  const config = readBuildConfigFromHost(cache.host, projectRoot);
+  const resource = computeOutputRel(displayPathOf(projectRoot, fileName), config, "gui-script");
+  const ids = index.byScriptResource.get(resource);
+  return ids === undefined ? [] : buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
+}
+
+// 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.
+function animationEntries(
+  slot: ClassifiedSlot,
+  cache: SceneIndexCache,
+  fileName: string,
+  baseEntries: readonly ts.CompletionEntry[],
+): ts.CompletionEntry[] {
+  const component = componentIdOfSameObjectAddress(slot.addressText ?? "");
+  if (component === undefined) {
+    return [];
+  }
+  const { projectRoot } = cache;
+  const index = cache.derived("sprite-animations", () =>
+    buildSpriteAnimationIndex({
+      scenes: cache.documents().documents,
+      assets: cache.documents(ANIMATION_ASSET_EXTENSIONS).documents,
+    }),
+  );
+  const config = readBuildConfigFromHost(cache.host, projectRoot);
+  const resource = computeOutputRel(displayPathOf(projectRoot, fileName), config, "script");
+  const ids = index.byScriptResource.get(resource)?.get(component);
+  return ids === undefined ? [] : buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
+}
+
+// The one kind needing no scene at all: the candidates are the project's own
+// files of the extensions the slot's entry declares, so there is nothing to
+// resolve ownership through and no document to parse. Same whole-literal span as
+// a node id — a resource path is the entire text between the quotes.
+function resourceEntries(
+  slot: ClassifiedSlot,
+  cache: SceneIndexCache,
+  baseEntries: readonly ts.CompletionEntry[],
+): ts.CompletionEntry[] {
+  const extensions = slot.resourceExtensions;
+  if (extensions === undefined || extensions.length === 0) {
+    return [];
+  }
+  const ids = cache.resourcePaths(extensions);
+  return buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
+}
+
+// The kind whose candidates come from a single project file rather than a walk
+// of many: `game.project` is the whole universe, since a key it never writes
+// answers the reader's default at runtime. Same whole-literal span as a resource
+// path — a config key is the entire text between the quotes, including any `#`
+// a `dependencies#0`-shaped key carries.
+function configKeyEntries(
+  slot: ClassifiedSlot,
+  cache: SceneIndexCache,
+  baseEntries: readonly ts.CompletionEntry[],
+): ts.CompletionEntry[] {
+  const text = cache.documents(PROJECT_EXTENSIONS).documents.get(GAME_PROJECT_DOCUMENT);
+  if (text === undefined) {
+    return [];
+  }
+  const ids = cache.derived("config-keys", () => buildConfigKeyIndex(text));
+  return buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
+}
+
+// The kind with no scene, no owner and no sibling to resolve through: the slot
+// resolver has already settled that this `hash("…")` is compared against an
+// `on_input` action id, so every action the project declares is a candidate.
+// Same whole-literal span as a config key.
+function actionIdEntries(
+  slot: ClassifiedSlot,
+  cache: SceneIndexCache,
+  baseEntries: readonly ts.CompletionEntry[],
+): ts.CompletionEntry[] {
+  const ids = cache.derived("input-actions", () =>
+    buildInputActionIndex(cache.documents(INPUT_BINDING_EXTENSIONS).documents),
+  );
+  return buildWholeLiteralCompletionEntries({ slot, ids, baseEntries });
+}
+
+// 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 {
+  return {
+    name: entryName,
+    kind: CONTRIBUTED_ENTRY_KIND,
+    kindModifiers: "",
+    displayParts: [{ kind: "stringLiteral", text: JSON.stringify(entryName) }],
+    documentation: [
+      {
+        kind: "text",
+        text: `Declared in ${declaredIn.join(", ")}`,
+      },
+    ],
+    source: [{ kind: "text", text: DEFOLD_COMPLETION_SOURCE }],
+  };
+}
 
 // A TS language-service plugin is loaded by package name and its main is called
 // as this `init` factory; the editor passes its own `typescript` instance so the
@@ -21,6 +253,63 @@ export default function init(modules: { typescript: typeof import("typescript")
       }
     }
 
+    // One index for the life of this language service, shared by every
+    // completion surface. A host that cannot enumerate files gets none at all —
+    // the same early return the completion path already takes.
+    const serverHost = info.serverHost as SceneWatchHost | undefined;
+    const cache = serverHost?.readDirectory
+      ? createSceneIndexCache(serverHost, info.project.getCurrentDirectory())
+      : undefined;
+
+    // Set after the member-copy loop, which would otherwise leave `dispose`
+    // forwarding straight to the base — closing the project without ever closing
+    // a watcher, and silently, because the forwarder does exist.
+    proxy.dispose = () => {
+      cache?.dispose();
+      const disposeBase = (base as Partial<ts.LanguageService>).dispose;
+      disposeBase?.call(base);
+    };
+
+    // Set after the member-copy loop for the same reason as `dispose`. Claimed
+    // only when the host round-tripped our own discriminator, the slot still
+    // resolves, and the entry's universe really names a declaring file — every
+    // other request is handed to the base member exactly as received, because a
+    // fabricated panel is worse than the editor's own.
+    proxy.getCompletionEntryDetails = (
+      fileName: string,
+      position: number,
+      entryName: string,
+      formatOptions: ts.FormatCodeOptions | ts.FormatCodeSettings | undefined,
+      source: string | undefined,
+      preferences: ts.UserPreferences | undefined,
+      data: ts.CompletionEntryData | undefined,
+    ): ts.CompletionEntryDetails | undefined => {
+      const forward = () =>
+        base.getCompletionEntryDetails?.(
+          fileName,
+          position,
+          entryName,
+          formatOptions,
+          source,
+          preferences,
+          data,
+        );
+      if (source !== DEFOLD_COMPLETION_SOURCE || !cache) {
+        return forward();
+      }
+      const program = base.getProgram();
+      const table = loadUrlParameterTable();
+      if (!program || !table) {
+        return forward();
+      }
+      const slot = resolveClassifiedSlotAtPosition({ program, table, fileName, position });
+      if (!slot) {
+        return forward();
+      }
+      const declaredIn = resolveEntryProvenance({ slot, position, cache, fileName, entryName });
+      return declaredIn.length === 0 ? forward() : provenancePanel(entryName, declaredIn);
+    };
+
     proxy.getSemanticDiagnostics = (fileName: string): ts.Diagnostic[] => {
       const prior = base.getSemanticDiagnostics(fileName);
       const program = base.getProgram();
@@ -35,6 +324,65 @@ export default function init(modules: { typescript: typeof import("typescript")
       return [...prior, ...transpiler];
     };
 
+    // Strictly additive: every path that cannot produce a suggestion returns the
+    // base result untouched, because a plugin that swallows the editor's own
+    // completions is worse than one that offers nothing.
+    proxy.getCompletionsAtPosition = (
+      fileName: string,
+      position: number,
+      options: ts.GetCompletionsAtPositionOptions | undefined,
+      formattingSettings?: ts.FormatCodeSettings,
+    ): ts.WithMetadata<ts.CompletionInfo> | undefined => {
+      const prior = base.getCompletionsAtPosition(fileName, position, options, formattingSettings);
+      const program = base.getProgram();
+      const table = loadUrlParameterTable();
+      if (!program || !table) {
+        return prior;
+      }
+      const slot = resolveClassifiedSlotAtPosition({ program, table, fileName, position });
+      if (!slot) {
+        return prior;
+      }
+      if (!cache) {
+        return prior;
+      }
+
+      // Read through the index the host's own watchers invalidate, so a slot the
+      // author keeps typing in costs no walk after the first — and still reflects
+      // a scene edited, added or removed. On a host missing either watch
+      // facility the cache delegates straight through, walking per request the
+      // way this path always did.
+      const baseEntries = prior?.entries ?? [];
+      const entries = isAddressClass(slot.class)
+        ? [
+            ...componentEntries(slot, position, cache, baseEntries),
+            ...objectPathEntries(slot, position, cache, 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;
+      }
+      if (!prior) {
+        return {
+          isGlobalCompletion: false,
+          isMemberCompletion: false,
+          isNewIdentifierLocation: false,
+          entries,
+        };
+      }
+      return { ...prior, entries: [...prior.entries, ...entries] };
+    };
+
     return proxy;
   }
 

package/src/scene-completions.ts

@@ -0,0 +1,114 @@
+import type { ClassifiedSlot } from "@defold-typescript/transpiler";
+import type ts from "typescript";
+
+// The editor's own `ts` is not in scope here and is not needed: this is a
+// string-enum member whose value is its name, and the plugin builds plain data.
+// Exported because the details panel restates the kind of the entry it answers
+// for, and a second literal there could drift from what was offered.
+export const CONTRIBUTED_ENTRY_KIND = "string" as ts.ScriptElementKind;
+
+// `sortText` is compared as a string, and TypeScript's own priorities are
+// "10"–"18" with `"z"`-prefixed deprecated variants, so "z18" is the greatest
+// key it produces. A string that strictly extends the greatest key present
+// sorts after it, and therefore after every key at or below it — which is how
+// one derived key lands the contributed entries last however the base list is
+// keyed, including keys no host of ours chose. The "zz" seed is the floor for
+// an empty base, where there is no maximum to extend: above everything
+// TypeScript emits, rather than below it the way a bare "z" would be. One
+// shared key for every entry, so their alphabetical order survives a tie
+// broken on the label.
+function keyAboveAll(baseEntries: readonly ts.CompletionEntry[]): string {
+  return `${baseEntries.reduce(
+    (greatest, base) => (base.sortText > greatest ? base.sortText : greatest),
+    "zz",
+  )}0`;
+}
+
+// The one `ts.CompletionEntry` field the host round-trips verbatim as the
+// details request's `source` argument, which is what lets a later request
+// recognize an entry as ours rather than guess from its name. Namespaced rather
+// than a bare word because a host is free to surface it beside the label.
+export const DEFOLD_COMPLETION_SOURCE = "defold-typescript/scene";
+
+function entriesFor(
+  ids: ReadonlySet<string>,
+  offeredName: (id: string) => string,
+  baseEntries: readonly ts.CompletionEntry[],
+  replacementSpan: { start: number; length: number },
+): ts.CompletionEntry[] {
+  // Where a project has generated the scene-derived union, the base service
+  // already offers the whole literal. Drop our duplicate rather than the base's:
+  // the plugin only ever adds.
+  const offered = new Set(baseEntries.map((base) => base.name));
+  const sortText = keyAboveAll(baseEntries);
+  return [...ids]
+    .sort()
+    .filter((id) => !offered.has(offeredName(id)))
+    .map((id) => ({
+      name: id,
+      kind: CONTRIBUTED_ENTRY_KIND,
+      kindModifiers: "",
+      sortText,
+      replacementSpan,
+      source: DEFOLD_COMPLETION_SOURCE,
+    }));
+}
+
+// One entry per component id, each replacing only the `#fragment` span inside
+// the quotes. Nothing here touches the filesystem or the host, so the whole
+// judgment is a function of the slot, the id universe, and what the base
+// service already offers.
+export function buildSceneCompletionEntries(input: {
+  slot: ClassifiedSlot;
+  ids: ReadonlySet<string>;
+  baseEntries: readonly ts.CompletionEntry[];
+}): ts.CompletionEntry[] {
+  const { slot, ids, baseEntries } = input;
+  if (slot.fragmentStart === -1) return [];
+
+  const fragmentOffset = slot.fragmentStart - slot.textStart;
+  const prefix = slot.text.slice(0, fragmentOffset);
+  return entriesFor(ids, (id) => `${prefix}${id}`, baseEntries, {
+    start: slot.fragmentStart,
+    length: slot.text.length - fragmentOffset,
+  });
+}
+
+// One entry per game-object path, each replacing only the path half inside the
+// quotes — the mirror image of `buildSceneCompletionEntries`, which keeps the
+// path and edits the fragment. A literal carrying no `#` is all path, so its
+// span is the whole text; `offeredName` re-attaches the surviving fragment so
+// the dedup compares the literal an accepted entry would produce, not a bare id.
+export function buildAddressPathCompletionEntries(input: {
+  slot: ClassifiedSlot;
+  paths: ReadonlySet<string>;
+  baseEntries: readonly ts.CompletionEntry[];
+}): ts.CompletionEntry[] {
+  const { slot, paths, baseEntries } = input;
+  // `fragmentStart` is the first character *after* the `#`, so the separator
+  // itself belongs to the surviving suffix rather than to the replaced span.
+  const length =
+    slot.fragmentStart === -1 ? slot.text.length : slot.fragmentStart - slot.textStart - 1;
+  const suffix = slot.text.slice(length);
+  return entriesFor(paths, (path) => `${path}${suffix}`, baseEntries, {
+    start: slot.textStart,
+    length,
+  });
+}
+
+// One entry per id, for the kinds whose literal is the name outright — a `.gui`
+// node id and an atlas animation id. Unlike an address, neither has a path half
+// to keep: the whole inside-quotes text is the name, so accepting an entry
+// replaces all of it and no caret guard is needed. One builder rather than two,
+// because a second copy would be free to drift on span or dedup.
+export function buildWholeLiteralCompletionEntries(input: {
+  slot: ClassifiedSlot;
+  ids: ReadonlySet<string>;
+  baseEntries: readonly ts.CompletionEntry[];
+}): ts.CompletionEntry[] {
+  const { slot, ids, baseEntries } = input;
+  return entriesFor(ids, (id) => id, baseEntries, {
+    start: slot.textStart,
+    length: slot.text.length,
+  });
+}

package/src/scene-documents.ts

@@ -0,0 +1,126 @@
+import { isDefignoredPath } from "@defold-typescript/transpiler";
+
+// The narrow slice of `ts.server.ServerHost` this needs: the real host
+// satisfies it structurally, and a test fake is two methods rather than a whole
+// server. `readDirectory` is optional because a host may not provide it, and a
+// plugin that throws takes the editor's completions down with it.
+export interface SceneReadHost {
+  readDirectory?(path: string, extensions?: readonly string[]): string[];
+  readFile(path: string): string | undefined;
+}
+
+export const SCENE_EXTENSIONS = [".go", ".collection"];
+
+// The extension sets more than one reader asks the host for. They live here
+// rather than beside either caller because the index cache serves exactly the
+// sets it is handed: a second definition that drifted would walk — and watch —
+// a universe the other reader never invalidates.
+export const GUI_EXTENSIONS = [".gui"];
+export const INPUT_BINDING_EXTENSIONS = [".input_binding"];
+
+// The documents an animation id is declared by: an atlas or tile source names
+// the ids, and a `.sprite` is the hop a referenced component takes to reach one.
+export const ANIMATION_ASSET_EXTENSIONS = [".atlas", ".tilesource", ".sprite"];
+
+// The walk returns every `.project` the project holds, so the lookup is by
+// display path — a vendored `*.project` declares keys this project's readers
+// cannot resolve.
+export const PROJECT_EXTENSIONS = [".project"];
+export const GAME_PROJECT_DOCUMENT = "game.project";
+
+// The project-relative name a file is keyed by — the same name the editor
+// reports for a program file, so a scene's claim on a script can be looked up
+// against the file being edited.
+export function displayPathOf(projectRoot: string, filePath: string): string {
+  const path = filePath.replace(/\\/g, "/");
+  const root = projectRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+  return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}
+
+// What both walks exclude is what Defold does not load as a project resource:
+// `build/` output, plus the directories the scaffolded `.defignore` names
+// (`isDefignoredPath`, root-anchored because a `.defignore` line is a
+// root-relative path).
+//
+// Bob writes `_generated_*.go` copies of the project's scenes under `build/`;
+// reading them would report every id twice, against files no author edits. The
+// segment test runs on the project-relative path, so a project that itself
+// lives under a directory named `build` is not excluded wholesale — a different
+// rule from `.defignore`'s, because bob writes those copies below whatever
+// depth it is pointed at.
+function isBuildOutput(displayPath: string): boolean {
+  return displayPath.split("/").includes("build");
+}
+
+// The single rule, exported because the index cache filters watch events with
+// it: a copy in the watcher could drift from what the walks exclude, and an
+// event the walk would have ignored is exactly the event that must not throw the
+// cache away — bob writes `_generated_*.go` throughout a build.
+export function isExcludedProjectPath(displayPath: string): boolean {
+  return isBuildOutput(displayPath) || isDefignoredPath(displayPath);
+}
+
+// Read the project's own scene sources through the editor host — by default the
+// `.go`/`.collection` set the component-id universe is built from, or whatever
+// `extensions` names instead. The two universes stay disjoint: a `.gui` declares
+// node ids, not component ids, so folding it into the default would feed gui
+// text to `buildSceneComponentIndex`. Keys are project-relative display paths,
+// matching what `buildSceneComponentIndex` reports in `incomplete`, and every
+// file that could not be read is named in `unreadable` — a universe with a
+// silent hole cannot be reasoned about. `paths` names the host paths actually
+// read — what a watcher must be registered on, which cannot be reconstructed
+// from a display path for a file outside the project root.
+export function readSceneDocuments(
+  host: SceneReadHost,
+  projectRoot: string,
+  extensions: readonly string[] = SCENE_EXTENSIONS,
+): { documents: Map<string, string>; unreadable: string[]; paths: string[] } {
+  const documents = new Map<string, string>();
+  const unreadable: string[] = [];
+  const paths: string[] = [];
+
+  if (!host.readDirectory) {
+    unreadable.push("the editor host cannot enumerate project files, so no scene source was read");
+    return { documents, unreadable, paths };
+  }
+
+  for (const filePath of host.readDirectory(projectRoot, extensions)) {
+    const displayPath = displayPathOf(projectRoot, filePath);
+    if (isExcludedProjectPath(displayPath)) continue;
+    const text = host.readFile(filePath);
+    if (text === undefined) {
+      unreadable.push(`${displayPath}: could not be read`);
+      continue;
+    }
+    documents.set(displayPath, text);
+    paths.push(filePath);
+  }
+
+  return { documents, unreadable, paths };
+}
+
+// The project's own files of the given kinds, as the `/`-prefixed
+// project-relative paths a Defold resource property names. Nothing is read: a
+// resource path is the whole suggestion, so the walk is the entire universe.
+//
+// The extension filter is re-applied rather than trusted. `readSceneDocuments`
+// can take the host at its word because a wrong document merely contributes no
+// ids, but here a wrong file *is* the suggestion — a host that ignored its
+// `extensions` argument would turn a `.font` slot into a project-wide file dump.
+export function listProjectResourcePaths(
+  host: SceneReadHost,
+  projectRoot: string,
+  extensions: readonly string[],
+): Set<string> {
+  if (!host.readDirectory) return new Set();
+
+  const paths: string[] = [];
+  for (const filePath of host.readDirectory(projectRoot, extensions)) {
+    const displayPath = displayPathOf(projectRoot, filePath);
+    if (isExcludedProjectPath(displayPath)) continue;
+    if (!extensions.some((extension) => displayPath.endsWith(extension))) continue;
+    paths.push(`/${displayPath}`);
+  }
+
+  return new Set(paths.sort());
+}