@defold-typescript/types 0.53.0 → 0.54.0

package/src/index-slot-classifications.ts

@@ -1,5 +1,4 @@
 import { htmlToDocText } from "./doc-comment";
-import { LIBRARY_INDEX_SLOT_CLASSIFICATIONS } from "./library-index-slot-classifications";
 
 // The class records the base Defold itself counts from. TypeScript passes every
 // engine position to Defold, and takes it back, unchanged in that base:
@@ -543,36 +542,101 @@ export function withIndexBaseNotes(
   return appendNotes(doc, indexBaseNotes(elementName, kind, slotName));
 }
 
+// The class records the base the library itself counts from, which TypeScript
+// passes through unchanged, exactly as `INDEX_SLOT_CLASSIFICATIONS` records
+// Defold's.
+export type LibraryIndexSlotClassifications = ReadonlyMap<
+  string,
+  Pick<IndexSlotClassification, "class" | "evidence">
+>;
+
+const INDEX_SLOT_CLASSES: ReadonlySet<string> = new Set<IndexSlotClass>([
+  "native-1",
+  "native-0",
+  "not-a-position",
+]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Keyed `<page>/<element>:<param|return|field>:<slot>[:<field>]`, `<page>` being
+// the library page key (`gooey`, `spine.gui`, `rive.cmd`), so a library slot
+// never shares a key with an engine one (`spine.gui` documents `gui.*`). A class
+// field is keyed `<page>/<Typedef>:field:<member>`, a callback argument as a
+// field of its callback slot, and each positional value of an unnamed
+// multi-value return as a field of that return (`cast:return::tile_x`). A
+// typedef method is keyed by its bare name, so one key covers every class of the
+// page that declares that method.
+// `docs-site/app/lib/library-index-slot-gate.test.ts` reds on a scanned slot
+// missing from `library-types/index-slot-classifications.json` and on an entry
+// no library page declares.
+export function parseLibraryIndexSlotClassifications(
+  json: unknown,
+): LibraryIndexSlotClassifications {
+  if (!isPlainObject(json)) {
+    throw new Error("library index-slot classifications must be a JSON object");
+  }
+  const map = new Map<string, Pick<IndexSlotClassification, "class" | "evidence">>();
+  for (const [key, value] of Object.entries(json)) {
+    if (!isPlainObject(value)) {
+      throw new Error(`library index-slot classification ${key} must be an object`);
+    }
+    const { class: slotClass, evidence } = value;
+    if (typeof slotClass !== "string" || !INDEX_SLOT_CLASSES.has(slotClass)) {
+      throw new Error(
+        `library index-slot classification ${key} has class ${JSON.stringify(slotClass)}, not one of ${[...INDEX_SLOT_CLASSES].join(", ")}`,
+      );
+    }
+    if (typeof evidence !== "string" || evidence.trim() === "") {
+      throw new Error(`library index-slot classification ${key} needs a non-blank evidence string`);
+    }
+    map.set(key, { class: slotClass as IndexSlotClass, evidence });
+  }
+  return map;
+}
+
 // The same notes for a slot or class field of a library page, read from the
 // library map under that page's key and naming the library as the receiver.
 export function libraryIndexBaseNotes(
+  classifications: LibraryIndexSlotClassifications,
   page: string,
   elementName: string,
   kind: "param" | "return" | "field",
   slotName: string,
 ): string[] {
   return slotBaseNotes(
-    LIBRARY_INDEX_SLOT_CLASSIFICATIONS,
+    classifications,
     `\`${page}\``,
     `${page}/${elementName}:${kind}:${slotName}`,
   );
 }
 
 export function withLibraryIndexBaseNotes(
+  classifications: LibraryIndexSlotClassifications,
   page: string,
   elementName: string,
   kind: "param" | "return" | "field",
   slotName: string,
   doc: string,
 ): string {
-  return appendNotes(doc, libraryIndexBaseNotes(page, elementName, kind, slotName));
+  return appendNotes(
+    doc,
+    libraryIndexBaseNotes(classifications, page, elementName, kind, slotName),
+  );
 }
 
 // Where a declaration's index notes come from: the engine map, naming Defold, or
-// the library map under each listed page, naming that library. A library or
-// extension declaration never reads the engine map, so an element it shares a
-// name with (`spine.gui` declares `gui.*`) never claims Defold as its receiver.
-export type IndexBaseSource = "engine" | { readonly pages: readonly string[] };
+// the caller's library map under each listed page, naming that library. A
+// library or extension declaration never reads the engine map, so an element it
+// shares a name with (`spine.gui` declares `gui.*`) never claims Defold as its
+// receiver.
+export type IndexBaseSource =
+  | "engine"
+  | {
+      readonly pages: readonly string[];
+      readonly classifications: LibraryIndexSlotClassifications;
+    };
 
 export type IndexBaseNoteResolver = (
   elementName: string,
@@ -582,7 +646,9 @@ export type IndexBaseNoteResolver = (
 
 export function indexBaseNoteResolver(source: IndexBaseSource): IndexBaseNoteResolver {
   if (source === "engine") return indexBaseNotes;
-  const { pages } = source;
+  const { pages, classifications } = source;
   return (elementName, kind, slotName) =>
-    pages.flatMap((page) => libraryIndexBaseNotes(page, elementName, kind, slotName));
+    pages.flatMap((page) =>
+      libraryIndexBaseNotes(classifications, page, elementName, kind, slotName),
+    );
 }

package/src/index.ts

@@ -88,11 +88,12 @@ export {
   INDEX_SLOT_CLASSIFICATIONS,
   type IndexSlotClass,
   type IndexSlotClassification,
+  type LibraryIndexSlotClassifications,
   libraryIndexBaseNotes,
+  parseLibraryIndexSlotClassifications,
   withIndexBaseNotes,
   withLibraryIndexBaseNotes,
 } from "./index-slot-classifications";
-export { LIBRARY_INDEX_SLOT_CLASSIFICATIONS } from "./library-index-slot-classifications";
 export {
   hasTopLevelUnion,
   luaMultiReturn,
@@ -131,6 +132,7 @@ export {
   type ModuleWrapOptions,
   type WrapOptions,
   wrapAsAmbientGlobal,
+  wrapAsGlobalTableModule,
   wrapAsModule,
 } from "./publish-dts";
 export {

package/src/publish-dts.ts

@@ -45,6 +45,22 @@ export function wrapAsAmbientGlobal(opts: WrapOptions): string {
   return `/** @noSelfInFile */\n${importLine}declare global {\n${indented}\n}\n\nexport {};\n`;
 }
 
+// The emitted namespace as an ambient `declare module "<namespace>"` tagged
+// `@globalTable`, so an import lowers to a local alias of the global the
+// extension registers. The description stays a separate JSDoc above the tag,
+// since TypeScript reads tags from the last one. The body keeps the namespace's
+// indentation, and engine handles resolve as ambient globals, as in
+// `wrapAsModule`.
+export function wrapAsGlobalTableModule(opts: WrapOptions): string {
+  const body = opts.emitted
+    .replace(
+      /(^|\n)declare\s+namespace\s+[\w$.]+\s*\{/,
+      (_match, lead) => `${lead}/** @globalTable */\ndeclare module "${opts.namespace}" {`,
+    )
+    .trimEnd();
+  return `/** @noSelfInFile */\n${body}\n`;
+}
+
 export function wrapAsModule(opts: ModuleWrapOptions): string {
   // ambient-globals-only: the module form references engine handles (`Hash`,
   // `Vector3`, ...) as ambient globals and emits no top-level import. A top-level

package/src/script-api.ts

@@ -22,18 +22,12 @@ export interface RefDocConstantElement {
   name: string;
   brief: string;
   description: string;
+  /** The scalar's declared `type:` tokens; an engine `CONSTANT` carries none. */
+  types: string[];
 }
 
 export type RefDocElement = RefDocFunctionElement | RefDocConstantElement;
 
-export interface ScriptApiOptions {
-  // Also carry scalar members as CONSTANT elements and function `examples:` as
-  // ref-doc examples HTML, and nested callback arguments, table fields and
-  // optional flags on each slot. Off for the typing lanes, whose emitter and
-  // frozen goldens only ever see flat functions without examples.
-  complete?: boolean;
-}
-
 export interface RefDoc {
   info: { namespace: string; brief: string; description: string };
   elements: RefDocElement[];
@@ -47,6 +41,11 @@ function stringOr(value: unknown, fallback: string): string {
   return typeof value === "string" ? value : fallback;
 }
 
+// A `.script_api` spells a slot that takes one of a set of named constants as
+// `enum`; the core ref-doc token for the same meaning is `constant`, which the
+// emitter expands to the constants the slot's doc names.
+const TYPE_TOKEN_ALIASES: ReadonlyMap<string, string> = new Map([["enum", "constant"]]);
+
 // A `.script_api` `type:` may spell a union inline (`string | nil`), where the
 // core ref-doc format carries one token per alternative. Splitting here keeps the
 // downstream emitter and fidelity resolver working in single tokens. A `type:`
@@ -57,7 +56,8 @@ function splitTypeTokens(type: unknown): string[] {
   return type
     .split("|")
     .map((token) => token.trim())
-    .filter((token) => token.length > 0);
+    .filter((token) => token.length > 0)
+    .map((token) => TYPE_TOKEN_ALIASES.get(token) ?? token);
 }
 
 // Upstream writes a slot list either as a YAML list or, for a lone slot, as a
@@ -79,13 +79,12 @@ function isFunctionName(name: string): boolean {
   return name !== "None" && FUNCTION_NAME.test(name);
 }
 
-function mapSlot(item: Record<string, unknown>, complete: boolean): RefDocParameter {
+function mapSlot(item: Record<string, unknown>): RefDocParameter {
   const slot: RefDocParameter = {
     name: stringOr(item.name, "").replace(REQUIRED_SUFFIX, ""),
     doc: stringOr(item.desc, ""),
     types: splitTypeTokens(item.type),
   };
-  if (!complete) return slot;
   // A callback lists its arguments under `parameters:` and a table its keys under
   // `fields:` or `members:`; the ref-doc format carries all as `fields`. A
   // callback's own `self` is kept, since the engine really passes it to the callback.
@@ -94,18 +93,18 @@ function mapSlot(item: Record<string, unknown>, complete: boolean): RefDocParame
     ...slotList(item.fields),
     ...slotList(item.members),
   ];
-  if (nested.length > 0) slot.fields = nested.map((child) => mapSlot(child, complete));
+  if (nested.length > 0) slot.fields = nested.map(mapSlot);
   if (item.optional === true) slot.is_optional = "True";
   return slot;
 }
 
-function mapParameters(raw: unknown, complete: boolean): RefDocParameter[] {
+function mapParameters(raw: unknown): RefDocParameter[] {
   const out: RefDocParameter[] = [];
   for (const item of slotList(raw)) {
     // The script_api lists the implicit `self` the engine passes; the emitter
     // stamps @noSelfInFile, so generated signatures must not declare it.
     if (stringOr(item.name, "") === "self") continue;
-    out.push(mapSlot(item, complete));
+    out.push(mapSlot(item));
   }
   return out;
 }
@@ -153,22 +152,23 @@ function isScalar(member: Record<string, unknown>): boolean {
 
 /**
  * Convert a parsed Defold extension `.script_api` document into the core
- * ref-doc JSON object shape that `parseDefoldApiDoc` consumes. By default only
- * `type: function` members are carried; scalar members (constants) are
- * dropped, matching the core ref-doc pipeline where non-function elements
- * never reach the emitter. With `complete`, scalar members at the top level and
- * one table deep are also carried as CONSTANT elements, and each function's
- * `examples:` becomes `codehilite` examples HTML that keeps each fence's
- * language, and each slot's nested `parameters:`/`fields:` and `optional: true`
- * become ref-doc `fields` and `is_optional`, for the docs pages.
+ * ref-doc JSON object shape that `parseDefoldApiDoc` consumes. `type: function`
+ * members become FUNCTION elements; scalar members at the top level and one
+ * table deep become CONSTANT elements carrying their `type:` tokens, so a
+ * `type: string` scalar reaches the emitter as a string constant; each
+ * function's `examples:` becomes
+ * `codehilite` examples HTML that keeps each fence's language; and each slot's
+ * nested `parameters:`/`fields:` and `optional: true` become ref-doc `fields`
+ * and `is_optional`. The Libraries pages, the `script-api` lane, the extension
+ * goldens and `resolve` all read this one conversion.
  *
- * Upstream dialects are normalized in both modes: a function's slots are read
- * from the first present of `parameters:`, `params:` or `members:` and its
- * returns from `returns:` or `return:`, any slot list may be a single mapping,
- * a table slot's `members:` nest like `fields:`, a `(REQUIRED)` name suffix is
- * dropped, and a function named `None` or not a Lua identifier is skipped.
+ * Upstream dialects are normalized: a function's slots are read from the first
+ * present of `parameters:`, `params:` or `members:` and its returns from
+ * `returns:` or `return:`, any slot list may be a single mapping, a table slot's
+ * `members:` nest like `fields:`, a `(REQUIRED)` name suffix is dropped, and a
+ * function named `None` or not a Lua identifier is skipped.
  */
-export function scriptApiToRefDoc(parsed: unknown, options: ScriptApiOptions = {}): RefDoc {
+export function scriptApiToRefDoc(parsed: unknown): RefDoc {
   if (!Array.isArray(parsed)) {
     throw new Error("scriptApiToRefDoc: expected a top-level YAML list");
   }
@@ -193,13 +193,10 @@ export function scriptApiToRefDoc(parsed: unknown, options: ScriptApiOptions = {
       type: "FUNCTION",
       name,
       description: stringOr(member.desc, ""),
-      parameters: mapParameters(
-        member.parameters ?? member.params ?? member.members,
-        options.complete === true,
-      ),
-      returnvalues: mapParameters(member.returns ?? member.return, options.complete === true),
+      parameters: mapParameters(member.parameters ?? member.params ?? member.members),
+      returnvalues: mapParameters(member.returns ?? member.return),
     };
-    const examples = options.complete ? examplesHtml(member.examples) : "";
+    const examples = examplesHtml(member.examples);
     if (examples !== "") element.examples = examples;
     return element;
   };
@@ -211,6 +208,7 @@ export function scriptApiToRefDoc(parsed: unknown, options: ScriptApiOptions = {
     name,
     brief: stringOr(member.desc, ""),
     description: stringOr(member.desc, ""),
+    types: splitTypeTokens(member.type),
   });
   for (const member of members) {
     if (!isRecord(member)) continue;
@@ -219,7 +217,7 @@ export function scriptApiToRefDoc(parsed: unknown, options: ScriptApiOptions = {
       elements.push(fnElement(`${namespace}.${stringOr(member.name, "")}`, member));
       continue;
     }
-    if (options.complete && isScalar(member)) {
+    if (isScalar(member)) {
       elements.push(constantElement(`${namespace}.${stringOr(member.name, "")}`, member));
       continue;
     }
@@ -236,7 +234,7 @@ export function scriptApiToRefDoc(parsed: unknown, options: ScriptApiOptions = {
         if (subMember.type === "function") {
           if (isFunctionName(stringOr(subMember.name, "")))
             elements.push(fnElement(name, subMember));
-        } else if (options.complete && isScalar(subMember)) {
+        } else if (isScalar(subMember)) {
           elements.push(constantElement(name, subMember));
         }
       }
@@ -249,6 +247,6 @@ export function scriptApiToRefDoc(parsed: unknown, options: ScriptApiOptions = {
   return doc;
 }
 
-export function parseScriptApi(yamlText: string, options: ScriptApiOptions = {}): RefDoc {
-  return scriptApiToRefDoc(parse(yamlText), options);
+export function parseScriptApi(yamlText: string): RefDoc {
+  return scriptApiToRefDoc(parse(yamlText));
 }

package/src/library-index-slot-classifications.ts

@@ -1,332 +0,0 @@
-import type { IndexSlotClassification } from "./index-slot-classifications";
-
-// The class records the base the library itself counts from, which TypeScript
-// passes through unchanged, exactly as `INDEX_SLOT_CLASSIFICATIONS` records
-// Defold's.
-type LibraryIndexSlotClassification = Pick<IndexSlotClassification, "class" | "evidence">;
-
-const RIVE_LIST_INDEX =
-  "passes the index to rive::CommandQueue unchanged, which counts list entries from 0 (-1 appends)";
-
-const SPINE_GUI_TRACK_PROSE: Readonly<Record<string, string>> = {
-  "gui.cancel_spine": "The track number to cancel (1-based)",
-  "gui.get_spine_animation": "The track number to get animation from (1-based)",
-  "gui.set_spine_cursor": "The track number to set cursor for (1-based)",
-  "gui.get_spine_cursor": "The track number to get cursor from (1-based)",
-  "gui.set_spine_playback_rate": "The track number to set playback rate for (1-based)",
-  "gui.get_spine_playback_rate": "The track number to get playback rate from (1-based)",
-};
-
-// Keyed `<page>/<element>:<param|return|field>:<slot>[:<field>]`, `<page>` being
-// the library page key (`gooey`, `spine.gui`, `rive.cmd`), so a library slot
-// never shares a key with an engine one (`spine.gui` documents `gui.*`). A class
-// field is keyed `<page>/<Typedef>:field:<member>`, a callback argument as a
-// field of its callback slot, and each positional value of an unnamed
-// multi-value return as a field of that return (`cast:return::tile_x`). A
-// typedef method is keyed by its bare name, so one key covers every class of the
-// page that declares that method.
-// `docs-site/app/lib/library-index-slot-gate.test.ts` reds on a scanned slot
-// missing here and on an entry no library page declares.
-export const LIBRARY_INDEX_SLOT_CLASSIFICATIONS: ReadonlyMap<
-  string,
-  LibraryIndexSlotClassification
-> = new Map<string, LibraryIndexSlotClassification>([
-  [
-    "boom/z:param:index",
-    { class: "not-a-position", evidence: "a draw order: a bigger z draws on top" },
-  ],
-  [
-    "bridge/bridge.daily_rewards.get_current_day:param:on_success:day",
-    {
-      class: "native-0",
-      evidence: "Returns the 0-based index of the reward the player is currently on",
-    },
-  ],
-  [
-    "crazygames/crazygames.list_friends:param:page",
-    { class: "native-1", evidence: "Page number, starting at 1" },
-  ],
-  [
-    "decore/system:field:index",
-    {
-      class: "native-1",
-      evidence: "internal/ecs.lua:tiny_manageSystems sets systems[j].index = j",
-    },
-  ],
-  [
-    "druid/scroll_to_index:param:index",
-    {
-      class: "native-1",
-      evidence:
-        "scroll.lua:scroll_to_index clamps to 1 .. #points; data_list.lua:scroll_to_index hands it to grid:get_pos",
-    },
-  ],
-  [
-    "druid/get_pos:param:index",
-    {
-      class: "native-1",
-      evidence: "static_grid.lua:get_pos places index 1 at row 0, column 0",
-    },
-  ],
-  [
-    "druid/get_index_xy:return:",
-    {
-      class: "native-1",
-      evidence: "static_grid.lua:get_index_xy returns (col + 1) + row * in_row",
-    },
-  ],
-  [
-    "druid/get_index:return:",
-    {
-      class: "native-1",
-      evidence: "static_grid.lua:get_index returns get_index_xy's index",
-    },
-  ],
-  [
-    "druid/get_index_by_node:return:",
-    {
-      class: "native-1",
-      evidence: "static_grid.lua:get_index_by_node returns the node's key in the nodes array",
-    },
-  ],
-  [
-    "druid/add:param:index",
-    {
-      class: "native-1",
-      evidence:
-        "static_grid.lua:add and data_list.lua:add insert with helper.insert_with_shift, defaulting to the count + 1",
-    },
-  ],
-  [
-    "druid/remove:param:index",
-    {
-      class: "native-1",
-      evidence:
-        "static_grid.lua:remove and data_list.lua:remove call helper.remove_with_shift at index",
-    },
-  ],
-  ...["druid/init:param:create_function", "druid/new_data_list:param:create_function"].map(
-    (key): [string, LibraryIndexSlotClassification] => [
-      key,
-      {
-        class: "not-a-position",
-        evidence: "a callback; data_list.lua passes it the 1-based data index",
-      },
-    ],
-  ),
-  ...["cursor_index", "start_index", "end_index"].map(
-    (slot): [string, LibraryIndexSlotClassification] => [
-      `druid/select_cursor:param:${slot}`,
-      {
-        class: "native-0",
-        evidence:
-          "input.lua:select_cursor clamps to 0 .. utf8.len(value); 0 is before the first character",
-      },
-    ],
-  ),
-  ...["druid/druid_grid:field:first_index", "druid/druid_grid:field:last_index"].map(
-    (key): [string, LibraryIndexSlotClassification] => [
-      key,
-      {
-        class: "native-1",
-        evidence:
-          "static_grid.lua:_update_indexes takes the least and greatest key of the nodes array",
-      },
-    ],
-  ),
-  ...["druid/druid_data_list:field:top_index", "druid/druid_data_list:field:last_index"].map(
-    (key): [string, LibraryIndexSlotClassification] => [
-      key,
-      { class: "native-1", evidence: "data_list.lua:init starts both at 1, the first data index" },
-    ],
-  ),
-  [
-    "druid/set_node_index:param:node",
-    { class: "not-a-position", evidence: "the node to move; its prose reads `the index of`" },
-  ],
-  [
-    "druid/set_node_index:param:index",
-    {
-      class: "native-1",
-      evidence: "layout.lua:set_node_index calls table.insert(self.entities, index, node)",
-    },
-  ],
-  [
-    "event/is_subscribed:return:",
-    {
-      class: "not-a-position",
-      evidence:
-        "both unnamed returns share this key: a boolean, then the 1-based callback index (event.lua:is_subscribed); no note fits both",
-    },
-  ],
-  [
-    "gooey/set_focus:param:index",
-    {
-      class: "native-1",
-      evidence:
-        "gooey.lua:set_focus reads group.components[index]; focus moves over 1 .. #components",
-    },
-  ],
-  [
-    "imgui/imgui.set_mouse_button:param:index",
-    {
-      class: "native-0",
-      evidence: "extension_imgui.cpp:imgui_SetMouseButton writes io.MouseDown[index]",
-    },
-  ],
-  [
-    "imgui/imgui.table_set_column_index:param:column_index",
-    {
-      class: "native-0",
-      evidence:
-        "extension_imgui.cpp:imgui_TableSetColumnIndex passes it to ImGui::TableSetColumnIndex unchanged",
-    },
-  ],
-  ...["imgui.set_style_color", "imgui.push_style_color"].map(
-    (fn): [string, LibraryIndexSlotClassification] => [
-      `imgui/${fn}:param:color_index`,
-      { class: "not-a-position", evidence: "an `imgui.ImGuiCol_*` constant" },
-    ],
-  ),
-  ...[
-    "imgui/imgui.font_add_ttf_file:return:font_index",
-    "imgui/imgui.font_add_ttf_data:return:font_index",
-    "imgui/imgui.font_push:param:font_index",
-  ].map((key): [string, LibraryIndexSlotClassification] => [
-    key,
-    {
-      class: "native-0",
-      evidence:
-        "extension_imgui.cpp:imgui_StoreFont returns Size() - 1, and imgui_GetFont accepts 0 .. Size() - 1",
-    },
-  ]),
-  ...[
-    "node_repeat/NodeRepeatAnimation:field:current_frame",
-    "sprite_repeat/SpriteRepeatAnimation:field:current_frame",
-  ].map((key): [string, LibraryIndexSlotClassification] => [
-    key,
-    { class: "native-1", evidence: "The 1-based index of the frame shown next" },
-  ]),
-  [
-    "narrator/choose:param:index",
-    { class: "native-1", evidence: "story.lua:choose asserts index within 1 .. #choices" },
-  ],
-  [
-    "panthera/panthera_animation:field:animation_keys_index",
-    {
-      class: "native-1",
-      evidence: "panthera.lua:update_animation walks keys from animation_keys_index to #keys",
-    },
-  ],
-  ...[
-    ["referenceListViewModelInstance", "index"],
-    ["insertViewModelInstanceListViewModel", "index"],
-    ["swapViewModelInstanceListValues", "indexa"],
-    ["swapViewModelInstanceListValues", "indexb"],
-    ["removeViewModelInstanceListViewModelIndex", "index"],
-  ].map(([fn, slot]): [string, LibraryIndexSlotClassification] => [
-    `rive.cmd/rive.cmd.${fn}:param:${slot}`,
-    { class: "native-0", evidence: `script_rive_cmd.cpp:Script_${fn} ${RIVE_LIST_INDEX}` },
-  ]),
-  ...[
-    "get_bundle_list",
-    "get_bundle_list_in_group",
-    "get_games_list",
-    "get_games_group",
-    "get_game_keys_group",
-    "get_user_games",
-    "get_virtual_items",
-    "get_virtual_currency",
-    "get_virtual_currency_package",
-    "get_virtual_items_group",
-    "get_sellable_items",
-    "get_sellable_items_group",
-    "get_reward_chains_list",
-  ].map((fn): [string, LibraryIndexSlotClassification] => [
-    `shop/shop.${fn}:param:offset`,
-    { class: "native-0", evidence: "the count starts from 0" },
-  ]),
-  [
-    "spine/spine.play_anim:param:options:track",
-    {
-      class: "native-1",
-      evidence: "script_spine.cpp defaults track to 1; comp_spine_model.cpp plays on m_Track - 1",
-    },
-  ],
-  [
-    "spine/spine.cancel:param:options:track",
-    { class: "native-1", evidence: "comp_spine_model.cpp cancels on m_Track - 1" },
-  ],
-  [
-    "spine/spine.play_anim:param:callback_function:message:track",
-    { class: "native-1", evidence: "comp_spine_model.cpp sends entry->trackIndex + 1" },
-  ],
-  [
-    "spine.gui/gui.play_spine_anim:param:play_properties:track",
-    { class: "native-1", evidence: "The track number for the animation (1-based)" },
-  ],
-  [
-    "spine.gui/gui.play_spine_anim:param:callback_function:message:track",
-    { class: "native-1", evidence: "gui_node_spine.cpp sends entry->trackIndex + 1" },
-  ],
-  ...Object.entries(SPINE_GUI_TRACK_PROSE).map(
-    ([fn, evidence]): [string, LibraryIndexSlotClassification] => [
-      `spine.gui/${fn}:param:options:track`,
-      { class: "native-1", evidence },
-    ],
-  ),
-  [
-    "steam/steam.friends_get_friend_by_index:param:iFriend",
-    { class: "native-0", evidence: "Is a index of range [0, GetFriendCount())" },
-  ],
-  [
-    "steam/steam.matchmaking_get_lobby_by_index:param:index",
-    { class: "native-0", evidence: "from 0 to LobbyMatchList_t.m_nLobbiesMatching" },
-  ],
-  ...[
-    ["matchmaking_get_lobby_member_by_index", "steam_matchmaking.cpp", "GetLobbyMemberByIndex"],
-    ["matchmaking_get_lobby_data_by_index", "steam_matchmaking.cpp", "GetLobbyDataByIndex"],
-    [
-      "user_stats_get_downloaded_leaderboard_entry",
-      "steam_userstats.cpp",
-      "GetDownloadedLeaderboardEntry",
-    ],
-  ].map(([fn, file, call]): [string, LibraryIndexSlotClassification] => [
-    `steam/steam.${fn}:param:index`,
-    { class: "native-0", evidence: `${file} passes it to Steamworks ${call}, which counts from 0` },
-  ]),
-  [
-    "steam/steam.user_stats_get_achievement_name:param:index",
-    { class: "native-0", evidence: "Get achievement name iAchievement in [0,GetNumAchievements)" },
-  ],
-  [
-    "steam/steam.matchmaking_get_lobby_chat_entry:param:index",
-    { class: "not-a-position", evidence: "the `m_iChatID` a `LobbyChatMsg_t` callback carries" },
-  ],
-  [
-    "tile_raycast/cast:return:",
-    {
-      class: "not-a-position",
-      evidence:
-        "a tuple: `hit`, `tile_id`, `intersection_x`, `intersection_y` and `side` address nothing by position; `tile_x`, `tile_y` and `array_id` are keyed on their own",
-    },
-  ],
-  ...(["tile_x", "tile_y"] as const).map((value): [string, LibraryIndexSlotClassification] => [
-    `tile_raycast/cast:return::${value}`,
-    {
-      class: "native-1",
-      evidence:
-        "Tile coordinates and array indices are 1-based; set_at/get_at subtract 1 from them (tileraycast.cpp)",
-    },
-  ]),
-  [
-    "tile_raycast/cast:return::array_id",
-    { class: "native-1", evidence: "Tile coordinates and array indices are 1-based" },
-  ],
-  ...(["set_at", "get_at"] as const).flatMap((fn) =>
-    (["tile_x", "tile_y"] as const).map((slot): [string, LibraryIndexSlotClassification] => [
-      `tile_raycast/${fn}:param:${slot}`,
-      { class: "native-1", evidence: "tileraycast.cpp subtracts 1 from the checked coordinate" },
-    ]),
-  ),
-]);