@defold-typescript/transpiler 0.40.0 → 0.42.0

package/dist/lifecycle-erasure.d.ts

@@ -3,5 +3,12 @@ import { type Plugin } from "typescript-to-lua";
 export declare const FACTORY_MODULE = "@defold-typescript/types";
 export declare const FACTORY_NAMES: Set<string>;
 export declare function resolvesToFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean;
+export interface PropertyMember {
+    readonly name: string;
+    readonly initializer: ts.Expression;
+}
+export declare function propertyMembers(property: ts.ObjectLiteralElementLike): PropertyMember[];
+export declare function factoryHooks(expression: ts.Expression, checker: ts.TypeChecker): ts.ObjectLiteralExpression | undefined;
+export declare function isPropertiesHook(property: ts.ObjectLiteralElementLike): boolean;
 export declare function isFactoryOnlyImport(node: ts.ImportDeclaration): boolean;
 export declare const lifecycleErasurePlugin: Plugin;

package/dist/project-resources.d.ts

@@ -1,2 +1,3 @@
 export declare const SCAFFOLDED_DEFIGNORE_LINES: string[];
-export declare function isDefignoredPath(displayPath: string): boolean;
+export declare function parseDefignore(text: string): string[];
+export declare function isDefignoredPath(displayPath: string, lines?: readonly string[]): boolean;

package/dist/text-script-property.d.ts

@@ -0,0 +1,16 @@
+import * as ts from "typescript";
+export interface TextScriptPropertyFinding {
+    readonly name: string;
+    readonly file: string;
+    /** 1-based line of the default's initializer or the direct call's value. */
+    readonly line: number;
+    /** 1-based column of the default's initializer or the direct call's value. */
+    readonly column: number;
+}
+export declare function findTextScriptProperties(program: ts.Program, fileNames: readonly string[]): TextScriptPropertyFinding[];
+/**
+ * Whether a value of `type` may be a string at runtime: a string-like type, a
+ * union or intersection with such a member, or a type parameter or other
+ * instantiable type whose constraint may hold one.
+ */
+export declare function mayHoldString(type: ts.Type, checker: ts.TypeChecker, visited?: Set<ts.Type>): boolean;

package/dist/type-application-erasure.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "typescript-to-lua";
+export declare const TYPE_APPLICATION_APIS: ReadonlySet<string>;
+export declare const typeApplicationErasurePlugin: Plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.40.0",
+    "@defold-typescript/types": "0.42.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript-to-lua": "^1.36.0"
   }

package/src/index.ts

@@ -48,7 +48,11 @@ export {
   stripIncludeBase,
 } from "./output-paths";
 export { getProgramDiagnostics } from "./program-diagnostics";
-export { isDefignoredPath, SCAFFOLDED_DEFIGNORE_LINES } from "./project-resources";
+export {
+  isDefignoredPath,
+  parseDefignore,
+  SCAFFOLDED_DEFIGNORE_LINES,
+} from "./project-resources";
 export { rewriteEmittedRequires } from "./require-rewrite";
 export { buildSceneAddressDeclaration } from "./scene-address-declaration";
 export type { SceneCollectionRoles, SceneCollectionRolesInput } from "./scene-collection-roles";
@@ -86,6 +90,8 @@ export type { SceneMessage } from "./scene-text-format";
 export { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
 export type { TranspileSession } from "./session";
 export { createTranspileSession } from "./session";
+export type { TextScriptPropertyFinding } from "./text-script-property";
+export { findTextScriptProperties } from "./text-script-property";
 export { TIMERS_REQUIRE_NAME } from "./timers-runtime";
 export type {
   TranspileDiagnostic,

package/src/lifecycle-erasure.ts

@@ -208,18 +208,19 @@ function emitInitMerge(
   return [builderDecl, createAssignmentStatement(createIdentifier("init"), initFn, property)];
 }
 
-// The value-keyed `properties` field maps each `key: default` to a chunk-scope
-// `go.property("key", default)` the editor reads. Emitted before the hook
-// assignments and after the source's `local` consts, so a default referencing a
-// module const resolves.
-function emitPropertyRegistrations(
-  property: ts.ObjectLiteralElementLike,
-  context: TransformationContext,
-): Statement[] {
+export interface PropertyMember {
+  readonly name: string;
+  readonly initializer: ts.Expression;
+}
+
+// The `key: default` members of a factory's `properties` field that register as
+// script properties: a property assignment keyed by an identifier or a string
+// literal. Shared by the emitter and every analysis of what it registers.
+export function propertyMembers(property: ts.ObjectLiteralElementLike): PropertyMember[] {
   if (!ts.isPropertyAssignment(property) || !ts.isObjectLiteralExpression(property.initializer)) {
     return [];
   }
-  const registrations: Statement[] = [];
+  const members: PropertyMember[] = [];
   for (const member of property.initializer.properties) {
     if (!ts.isPropertyAssignment(member)) {
       continue;
@@ -228,32 +229,60 @@ function emitPropertyRegistrations(
     if (!ts.isIdentifier(key) && !ts.isStringLiteral(key)) {
       continue;
     }
-    registrations.push(
-      createExpressionStatement(
-        createCallExpression(
-          createTableIndexExpression(createIdentifier("go"), createStringLiteral("property")),
-          [createStringLiteral(key.text), context.transformExpression(member.initializer)],
-        ),
-      ),
-    );
+    members.push({ name: key.text, initializer: member.initializer });
   }
-  return registrations;
+  return members;
 }
 
-function eraseFactoryCall(
+// The hooks object literal of a call to a lifecycle factory, or `undefined` when
+// the expression is not one the erasure rewrites.
+export function factoryHooks(
   expression: ts.Expression,
-  context: TransformationContext,
-): Statement[] | undefined {
+  checker: ts.TypeChecker,
+): ts.ObjectLiteralExpression | undefined {
   if (!ts.isCallExpression(expression)) {
     return undefined;
   }
-  if (!resolvesToFactoryExport(expression.expression, context.checker)) {
+  if (!resolvesToFactoryExport(expression.expression, checker)) {
     return undefined;
   }
   const hooks = expression.arguments[0];
   if (hooks === undefined || !ts.isObjectLiteralExpression(hooks)) {
     return undefined;
   }
+  return hooks;
+}
+
+export function isPropertiesHook(property: ts.ObjectLiteralElementLike): boolean {
+  return hookName(property) === "properties";
+}
+
+// The value-keyed `properties` field maps each `key: default` to a chunk-scope
+// `go.property("key", default)` the editor reads. Emitted before the hook
+// assignments and after the source's `local` consts, so a default referencing a
+// module const resolves.
+function emitPropertyRegistrations(
+  property: ts.ObjectLiteralElementLike,
+  context: TransformationContext,
+): Statement[] {
+  return propertyMembers(property).map(({ name, initializer }) =>
+    createExpressionStatement(
+      createCallExpression(
+        createTableIndexExpression(createIdentifier("go"), createStringLiteral("property")),
+        [createStringLiteral(name), context.transformExpression(initializer)],
+      ),
+    ),
+  );
+}
+
+function eraseFactoryCall(
+  expression: ts.Expression,
+  context: TransformationContext,
+): Statement[] | undefined {
+  const hooks = factoryHooks(expression, context.checker);
+  if (hooks === undefined) {
+    return undefined;
+  }
   const registrations: Statement[] = [];
   const statements: Statement[] = [];
   for (const property of hooks.properties) {

package/src/program-diagnostics.ts

@@ -1,10 +1,10 @@
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
-import { arrayIndexOptionLoweringPlugin } from "./array-index-option-lowering";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
 import { timersLoweringPlugin } from "./timers-lowering";
+import { typeApplicationErasurePlugin } from "./type-application-erasure";
 import { windowEventGuardLoweringPlugin } from "./window-event-guard-lowering";
 
 // The same lua plugins the build path lists (transpile.ts / session.ts), so the
@@ -15,7 +15,7 @@ const LUA_PLUGINS: tstl.Plugin[] = [
   windowEventGuardLoweringPlugin,
   messageDispatchLoweringPlugin,
   timersLoweringPlugin,
-  arrayIndexOptionLoweringPlugin,
+  typeApplicationErasurePlugin,
 ];
 
 const noopWriteFile: ts.WriteFileCallback = () => {};

package/src/project-resources.ts

@@ -9,12 +9,25 @@
 // `.vscode`).
 export const SCAFFOLDED_DEFIGNORE_LINES = ["/node_modules", "/.defold-types", "/.vscode"];
 
-// Whether a project-relative display path lies under one of the lines `init`
-// scaffolds. Root-anchored, because a `.defignore` line is a root-relative
-// path: `assets/node_modules/tiles.atlas` is a resource Defold loads.
-export function isDefignoredPath(displayPath: string): boolean {
+// A project's own `.defignore` text as root-anchored lines, the shape
+// `isDefignoredPath` matches against. A line without its leading `/` names the
+// same root-relative path.
+export function parseDefignore(text: string): string[] {
+  return text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .map((line) => (line.startsWith("/") ? line : `/${line}`));
+}
+
+// Whether a project-relative display path lies under one of `lines`, by
+// default the ones `init` scaffolds. Root-anchored, because a `.defignore` line
+// is a root-relative path: `assets/node_modules/tiles.atlas` is a resource
+// Defold loads.
+export function isDefignoredPath(
+  displayPath: string,
+  lines: readonly string[] = SCAFFOLDED_DEFIGNORE_LINES,
+): boolean {
   const rooted = `/${displayPath.replace(/^\/+/, "")}`;
-  return SCAFFOLDED_DEFIGNORE_LINES.some(
-    (line) => rooted === line || rooted.startsWith(`${line}/`),
-  );
+  return lines.some((line) => rooted === line || rooted.startsWith(`${line}/`));
 }

package/src/session.ts

@@ -3,7 +3,6 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
-import { arrayIndexOptionLoweringPlugin } from "./array-index-option-lowering";
 import { type CompanionEmitter, createCompanionEmitPlugin } from "./companion-emit";
 import { editorScriptErasurePlugin } from "./editor-script-erasure";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
@@ -11,6 +10,7 @@ import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
 import { timersLoweringPlugin } from "./timers-lowering";
 import { AMBIENT_FILES, collectOutputs, type TranspileProjectResult } from "./transpile";
+import { typeApplicationErasurePlugin } from "./type-application-erasure";
 import { windowEventGuardLoweringPlugin } from "./window-event-guard-lowering";
 
 export interface TranspileSession {
@@ -44,7 +44,7 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
-      { plugin: arrayIndexOptionLoweringPlugin },
+      { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin },
     ],
   };

package/src/text-script-property.ts

@@ -0,0 +1,100 @@
+import * as ts from "typescript";
+import { findDirectGoPropertyCalls } from "./go-property-direct-call";
+import { factoryHooks, isPropertiesHook, propertyMembers } from "./lifecycle-erasure";
+
+export interface TextScriptPropertyFinding {
+  readonly name: string;
+  readonly file: string;
+  /** 1-based line of the default's initializer or the direct call's value. */
+  readonly line: number;
+  /** 1-based column of the default's initializer or the direct call's value. */
+  readonly column: number;
+}
+
+// The script properties whose default may hold a string, declared either in a
+// `properties` field or by a direct `go.property` call. Defold registers a
+// string `go.property` only from 1.13.2, so a build for an older target must
+// refuse them; typed rather than literal-driven, so a const holding a string
+// counts.
+export function findTextScriptProperties(
+  program: ts.Program,
+  fileNames: readonly string[],
+): TextScriptPropertyFinding[] {
+  const checker = program.getTypeChecker();
+  const findings: TextScriptPropertyFinding[] = [];
+
+  for (const file of fileNames) {
+    const sourceFile = program.getSourceFile(file);
+    if (sourceFile === undefined) {
+      continue;
+    }
+    const located: { name: string; value: ts.Node }[] = [];
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node)) {
+        const hooks = factoryHooks(node, checker);
+        for (const property of hooks?.properties ?? []) {
+          if (!isPropertiesHook(property)) {
+            continue;
+          }
+          for (const { name, initializer } of propertyMembers(property)) {
+            if (mayHoldString(checker.getTypeAtLocation(initializer), checker)) {
+              located.push({ name, value: initializer });
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    for (const call of findDirectGoPropertyCalls(sourceFile)) {
+      const [nameArgument, value] = call.arguments;
+      if (nameArgument === undefined || value === undefined) {
+        continue;
+      }
+      if (mayHoldString(checker.getTypeAtLocation(value), checker)) {
+        const name = ts.isStringLiteralLike(nameArgument)
+          ? nameArgument.text
+          : nameArgument.getText(sourceFile);
+        located.push({ name, value });
+      }
+    }
+    located.sort(
+      (left, right) => left.value.getStart(sourceFile) - right.value.getStart(sourceFile),
+    );
+    for (const { name, value } of located) {
+      const position = sourceFile.getLineAndCharacterOfPosition(value.getStart(sourceFile));
+      findings.push({ name, file, line: position.line + 1, column: position.character + 1 });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Whether a value of `type` may be a string at runtime: a string-like type, a
+ * union or intersection with such a member, or a type parameter or other
+ * instantiable type whose constraint may hold one.
+ */
+export function mayHoldString(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  visited: Set<ts.Type> = new Set(),
+): boolean {
+  if (visited.has(type)) {
+    return false;
+  }
+  visited.add(type);
+  if (type.flags & ts.TypeFlags.StringLike) {
+    return true;
+  }
+  if (type.isUnionOrIntersection()) {
+    return type.types.some((member) => mayHoldString(member, checker, visited));
+  }
+  if (type.flags & ts.TypeFlags.Instantiable) {
+    const constraint = checker.getBaseConstraintOfType(type);
+    return constraint !== undefined && constraint !== type
+      ? mayHoldString(constraint, checker, visited)
+      : false;
+  }
+  return false;
+}

package/src/transpile.ts

@@ -3,7 +3,6 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import type * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
-import { arrayIndexOptionLoweringPlugin } from "./array-index-option-lowering";
 import { createCompanionEmitPlugin } from "./companion-emit";
 import { editorScriptErasurePlugin } from "./editor-script-erasure";
 import {
@@ -15,6 +14,7 @@ import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
 import { importsTimersModule, timersLoweringPlugin } from "./timers-lowering";
 import { TIMERS_RUNTIME } from "./timers-runtime";
+import { typeApplicationErasurePlugin } from "./type-application-erasure";
 import { windowEventGuardLoweringPlugin } from "./window-event-guard-lowering";
 
 export interface TranspileResult {
@@ -322,7 +322,7 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
-      { plugin: arrayIndexOptionLoweringPlugin },
+      { plugin: typeApplicationErasurePlugin },
       { plugin: companionEmit.plugin },
     ],
   });

package/src/type-application-erasure.ts

@@ -0,0 +1,34 @@
+import * as ts from "typescript";
+import type { Expression, Plugin } from "typescript-to-lua";
+
+// The Defold functions declared with a curried type-application overload,
+// `go.get<P>()(url, property)`: the empty call only fixes `P` for the checker.
+export const TYPE_APPLICATION_APIS: ReadonlySet<string> = new Set(["go.get", "go.set"]);
+
+// Keyed by the declaration's fully qualified name: only a symbol declared in
+// an ambient `declare global` block carries the `global.` prefix, so a
+// project's own `go` never matches.
+function isTypeApplication(call: ts.CallExpression, checker: ts.TypeChecker): boolean {
+  if (call.arguments.length !== 0) return false;
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (declaration === undefined || !ts.isFunctionDeclaration(declaration)) return false;
+  if (declaration.parameters.length !== 0 || declaration.typeParameters === undefined) return false;
+  if (declaration.name === undefined) return false;
+  const symbol = checker.getSymbolAtLocation(declaration.name);
+  if (symbol === undefined) return false;
+  const fqn = checker.getFullyQualifiedName(symbol);
+  return fqn.startsWith("global.") && TYPE_APPLICATION_APIS.has(fqn.slice("global.".length));
+}
+
+// `go.get<P>()` becomes `go.get`, so the curried call reaches the engine as
+// `go.get(url, property)` and a stored `go.get<P>()` is the function itself.
+export const typeApplicationErasurePlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      if (isTypeApplication(node, context.checker)) {
+        return context.transformExpression(node.expression);
+      }
+      return context.superTransformExpression(node);
+    },
+  },
+};

package/dist/array-index-option-lowering.d.ts

@@ -1,6 +0,0 @@
-import { type Plugin } from "typescript-to-lua";
-export declare const ONE_BASED_INDEX_OPTION_APIS: ReadonlySet<string>;
-export declare const INDEX_OPTION_VARIABLE_MESSAGE = "`options.index` is zero-based and is converted to Defold's 1-based index only in an object literal written at the call; pass the options inline.";
-export declare const INDEX_OPTION_SPREAD_MESSAGE = "A spread carrying `index` cannot be converted to Defold's 1-based index; write `index` explicitly after the spread.";
-export declare const INDEX_OPTION_UNDEFINED_MESSAGE = "`options.index` may be undefined here, so it cannot be converted to Defold's 1-based index; pass a number, or leave `index` out.";
-export declare const arrayIndexOptionLoweringPlugin: Plugin;

package/src/array-index-option-lowering.ts

@@ -1,212 +0,0 @@
-import * as ts from "typescript";
-import {
-  createBinaryExpression,
-  createNumericLiteral,
-  type Expression,
-  getOriginalPos,
-  isCallExpression,
-  isNumericLiteral,
-  isStringLiteral,
-  isTableExpression,
-  type Plugin,
-  SyntaxKind,
-  setNodePosition,
-  type TableExpression,
-} from "typescript-to-lua";
-
-// The Defold functions whose `options.index` upstream documents as "index into
-// array property (1 based)". TypeScript authors it zero-based; the lowering
-// adds the one Lua expects.
-export const ONE_BASED_INDEX_OPTION_APIS: ReadonlySet<string> = new Set([
-  "go.get",
-  "go.set",
-  "gui.get",
-  "gui.set",
-]);
-
-export const INDEX_OPTION_VARIABLE_MESSAGE =
-  "`options.index` is zero-based and is converted to Defold's 1-based index only in an object literal written at the call; pass the options inline.";
-export const INDEX_OPTION_SPREAD_MESSAGE =
-  "A spread carrying `index` cannot be converted to Defold's 1-based index; write `index` explicitly after the spread.";
-export const INDEX_OPTION_UNDEFINED_MESSAGE =
-  "`options.index` may be undefined here, so it cannot be converted to Defold's 1-based index; pass a number, or leave `index` out.";
-
-const OPTIONS_PARAMETER = "options";
-const INDEX_KEY = "index";
-
-const loweredLiterals = new WeakSet<ts.Node>();
-
-// Keyed like `tableKey` in url-address-slots.ts: only a symbol declared in an
-// ambient `declare global` block carries the `global.` prefix, so a project's
-// own `go` or `gui` never matches. Walking up from the signature declaration
-// reaches `go.get<P>()` from the function type its curried inner call resolves to.
-function oneBasedApi(declaration: ts.Declaration, checker: ts.TypeChecker): boolean {
-  let node: ts.Node | undefined = declaration;
-  while (node !== undefined && !ts.isFunctionDeclaration(node)) node = node.parent;
-  if (node?.name === undefined) return false;
-  const symbol = checker.getSymbolAtLocation(node.name);
-  if (symbol === undefined) return false;
-  const fqn = checker.getFullyQualifiedName(symbol);
-  return fqn.startsWith("global.") && ONE_BASED_INDEX_OPTION_APIS.has(fqn.slice("global.".length));
-}
-
-function optionsArgument(
-  call: ts.CallExpression,
-  checker: ts.TypeChecker,
-): ts.Expression | undefined {
-  const declaration = checker.getResolvedSignature(call)?.declaration;
-  if (declaration === undefined || !ts.isFunctionLike(declaration)) return undefined;
-  if (!oneBasedApi(declaration, checker)) return undefined;
-  const index = declaration.parameters.findIndex(
-    (parameter) =>
-      parameter.dotDotDotToken === undefined &&
-      ts.isIdentifier(parameter.name) &&
-      parameter.name.text === OPTIONS_PARAMETER,
-  );
-  return index === -1 ? undefined : call.arguments[index];
-}
-
-function unwrap(expression: ts.Expression): ts.Expression {
-  let current = expression;
-  while (
-    ts.isParenthesizedExpression(current) ||
-    ts.isAsExpression(current) ||
-    ts.isSatisfiesExpression(current) ||
-    ts.isNonNullExpression(current) ||
-    ts.isTypeAssertionExpression(current)
-  ) {
-    current = current.expression;
-  }
-  return current;
-}
-
-function someConstituent(type: ts.Type, predicate: (type: ts.Type) => boolean): boolean {
-  return type.isUnion() ? type.types.some(predicate) : predicate(type);
-}
-
-function carriesIndex(type: ts.Type): boolean {
-  return someConstituent(type, (t) => t.getProperty(INDEX_KEY) !== undefined);
-}
-
-function admitsUndefined(type: ts.Type): boolean {
-  return someConstituent(
-    type,
-    (t) => (t.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0,
-  );
-}
-
-function propertyName(
-  property: ts.ObjectLiteralElementLike,
-  checker: ts.TypeChecker,
-): string | undefined {
-  const name = property.name;
-  if (name === undefined) return undefined;
-  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
-    return name.text;
-  }
-  if (ts.isComputedPropertyName(name)) {
-    const type = checker.getTypeAtLocation(name.expression);
-    if (type.isStringLiteral()) return type.value;
-  }
-  return undefined;
-}
-
-function indexValueType(
-  property: ts.ObjectLiteralElementLike,
-  checker: ts.TypeChecker,
-): ts.Type | undefined {
-  if (ts.isPropertyAssignment(property)) return checker.getTypeAtLocation(property.initializer);
-  if (ts.isShorthandPropertyAssignment(property)) return checker.getTypeAtLocation(property.name);
-  return undefined;
-}
-
-function rejection(node: ts.Node, messageText: string): ts.Diagnostic {
-  const file = node.getSourceFile();
-  const start = node.getStart(file);
-  return {
-    file,
-    start,
-    length: node.getEnd() - start,
-    category: ts.DiagnosticCategory.Error,
-    code: 0,
-    messageText,
-  };
-}
-
-// The first reason `options` cannot be lowered, or `undefined` when it can.
-function rejectOptions(options: ts.Expression, checker: ts.TypeChecker): ts.Diagnostic | undefined {
-  const literal = unwrap(options);
-  if (!ts.isObjectLiteralExpression(literal)) {
-    return carriesIndex(checker.getTypeAtLocation(literal))
-      ? rejection(options, INDEX_OPTION_VARIABLE_MESSAGE)
-      : undefined;
-  }
-  let uncoveredSpread: ts.SpreadAssignment | undefined;
-  let explicitIndex: ts.ObjectLiteralElementLike | undefined;
-  for (const property of literal.properties) {
-    if (ts.isSpreadAssignment(property)) {
-      if (carriesIndex(checker.getTypeAtLocation(property.expression))) uncoveredSpread = property;
-    } else if (propertyName(property, checker) === INDEX_KEY) {
-      uncoveredSpread = undefined;
-      explicitIndex = property;
-    }
-  }
-  if (uncoveredSpread !== undefined) return rejection(uncoveredSpread, INDEX_OPTION_SPREAD_MESSAGE);
-  const valueType = explicitIndex && indexValueType(explicitIndex, checker);
-  if (explicitIndex !== undefined && valueType !== undefined && admitsUndefined(valueType)) {
-    return rejection(explicitIndex, INDEX_OPTION_UNDEFINED_MESSAGE);
-  }
-  return undefined;
-}
-
-function plusOne(value: Expression): Expression {
-  if (isNumericLiteral(value)) {
-    return setNodePosition(createNumericLiteral(value.value + 1), getOriginalPos(value));
-  }
-  return setNodePosition(
-    createBinaryExpression(value, createNumericLiteral(1), SyntaxKind.AdditionOperator),
-    getOriginalPos(value),
-  );
-}
-
-// `rejectOptions` guarantees the last `index` field is the effective one: a
-// spread carrying `index` after it is rejected. Every earlier one is shadowed
-// and keeps its source value.
-function offsetEffectiveIndexField(tables: readonly TableExpression[]): void {
-  for (const field of tables.flatMap((table) => table.fields).reverse()) {
-    if (field.key !== undefined && isStringLiteral(field.key) && field.key.value === INDEX_KEY) {
-      field.value = plusOne(field.value);
-      return;
-    }
-  }
-}
-
-export const arrayIndexOptionLoweringPlugin: Plugin = {
-  visitors: {
-    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
-      const options = optionsArgument(node, context.checker);
-      if (options !== undefined) {
-        const diagnostic = rejectOptions(options, context.checker);
-        if (diagnostic !== undefined) {
-          context.diagnostics.push(diagnostic);
-        } else {
-          const literal = unwrap(options);
-          if (ts.isObjectLiteralExpression(literal)) loweredLiterals.add(literal);
-        }
-      }
-      return context.superTransformExpression(node);
-    },
-    // A spread lowers the literal to `__TS__ObjectAssign({}, base, {index = …})`,
-    // so the table carrying `index` can sit one call deep.
-    [ts.SyntaxKind.ObjectLiteralExpression]: (node, context): Expression => {
-      const result = context.superTransformExpression(node);
-      if (!loweredLiterals.has(node)) return result;
-      if (isTableExpression(result)) {
-        offsetEffectiveIndexField([result]);
-      } else if (isCallExpression(result)) {
-        offsetEffectiveIndexField(result.params.filter(isTableExpression));
-      }
-      return result;
-    },
-  },
-};