@tilua/parser 1.0.2 → 2.0.0

package/dist/index.d.cts

@@ -326,8 +326,8 @@ interface FunctionSignature extends BaseNode {
     name?: Identifier;
     generics: GenericTypeParameter[];
     params: FunctionParameter[];
+    /** The last parameter is a rest parameter (`...rest: T[]`). */
     hasVarargs: boolean;
-    varargTypeAnnotation?: TypeNode;
     returnType?: TypeNode;
     /** `: v is T` / `: asserts v` instead of a plain return type. */
     predicate?: TypePredicateNode;
@@ -360,6 +360,12 @@ interface ClassDeclaration extends BaseNode {
     superclass?: Identifier;
     /** The arguments `extends Box<number>` was written with. */
     superArguments?: TypeNode[];
+    /** `implements Shape, Named` — shapes the instances are checked against.
+     *  Nothing at run time. */
+    implements?: TypeNode[];
+    /** `abstract class` — has no `new`; a class extending it does, once it
+     *  has written every `abstract` member. */
+    isAbstract?: boolean;
     members: ClassMember[];
 }
 /** `class ... end` written where a value goes: `const Counter = class ... end`,
@@ -371,19 +377,32 @@ interface ClassExpression extends BaseNode {
     name?: Identifier;
     superclass?: Identifier;
     superArguments?: TypeNode[];
+    implements?: TypeNode[];
+    isAbstract?: boolean;
     members: ClassMember[];
 }
 type ClassMember = ClassField | ClassMethod | ClassAccessor | ClassConstructor;
 /** The two ways a class is written. Everything after parsing treats them
  *  alike: only the name and the type parameters differ. */
 type ClassLike = ClassDeclaration | ClassExpression;
+/** `public` / `private` / `protected` written before a member. Only the type
+ *  checker reads it: a private member is still an ordinary key at runtime.
+ *  `protected` is reachable from the class and the classes extending it. */
+type ClassAccessibility = "public" | "private" | "protected";
 /** `x: number` / `x = 1` / `static count = 0`. An instance field is assigned
  *  when the instance is built, before the constructor body runs; a `static`
  *  one is assigned on the class table, once. */
 interface ClassField extends BaseNode {
     type: "ClassField";
+    /** Left out, the member is public. */
+    accessibility?: ClassAccessibility;
     name: Identifier;
     isStatic: boolean;
+    /** `readonly` — assigned where it is declared or in the constructor of
+     *  its own class, and nowhere else. */
+    isReadonly?: boolean;
+    /** `override` — the class it extends has a member of this name. */
+    isOverride?: boolean;
     typeAnnotation?: TypeNode;
     init?: Expression;
 }
@@ -391,20 +410,31 @@ interface ClassField extends BaseNode {
  *  A `static` one is a plain function on the class table, with no `this`. */
 interface ClassMethod extends BaseNode {
     type: "ClassMethod";
+    /** Left out, the member is public. */
+    accessibility?: ClassAccessibility;
     name: Identifier;
     isStatic: boolean;
     func: FunctionBody;
     /** TS-style overload signatures preceding the implementation. */
     signatures?: FunctionSignature[];
+    /** `abstract function area(): number` — a head with no body, which every
+     *  class extending this one that is not abstract itself has to write. */
+    isAbstract?: boolean;
+    /** `override` — the class it extends has a member of this name. */
+    isOverride?: boolean;
 }
 /** `get name(): T ... end` / `set name(v: T) ... end` — read and written as a
  *  property, run as a function. */
 interface ClassAccessor extends BaseNode {
     type: "ClassAccessor";
+    /** Left out, the member is public. */
+    accessibility?: ClassAccessibility;
     kind: "get" | "set";
     name: Identifier;
     isStatic: boolean;
     func: FunctionBody;
+    /** `override` — the class it extends has a member of this name. */
+    isOverride?: boolean;
 }
 /** `constructor(...) ... end` — runs on a fresh instance. A class that
  *  extends another must call `super(...)` before touching `this`. */
@@ -412,14 +442,6 @@ interface ClassConstructor extends BaseNode {
     type: "ClassConstructor";
     func: FunctionBody;
 }
-/** `new Name(args)` — builds an instance. Lowers to the class's own
- *  `Name.new(args)`, which is also callable by hand. */
-interface NewExpression extends BaseNode {
-    type: "NewExpression";
-    callee: Expression;
-    arguments: Expression[];
-    typeArguments?: (TypeNode | TypePackNode)[];
-}
 /** `super` — only inside a class that extends another: `super(...)` in the
  *  constructor runs the base's on this instance, and `super.method(...)` in a
  *  method calls the base's version of it. */
@@ -439,7 +461,7 @@ interface CompoundAssignmentStatement extends BaseNode {
 }
 interface CallStatement extends BaseNode {
     type: "CallStatement";
-    expression: CallExpression | MethodCallExpression | NewExpression;
+    expression: CallExpression | MethodCallExpression;
 }
 /** An expression written as a statement, where Lua would want a call or an
  *  assignment: `value` on a line of its own.
@@ -485,15 +507,21 @@ interface NumericForStatement extends BaseNode {
     step?: Expression;
     body: Block;
 }
+/** `for (const item in source)`. One value each time — several are an
+ *  array, taken apart with a pattern: `for (const [k, v] in pairs(t))`.
+ *  `let` instead of `const` when the body assigns to the name. */
 interface GenericForStatement extends BaseNode {
     type: "GenericForStatement";
-    variables: BindingTarget[];
-    iterators: Expression[];
+    kind: "const" | "let";
+    variable: BindingTarget;
+    iterator: Expression;
     body: Block;
 }
+/** `return` / `return value`. A function gives back one value; several are
+ *  an array — `return [a, b]`, a table. */
 interface ReturnStatement extends BaseNode {
     type: "ReturnStatement";
-    arguments: Expression[];
+    argument?: Expression;
 }
 interface BreakStatement extends BaseNode {
     type: "BreakStatement";
@@ -516,15 +544,14 @@ interface GenericTypeParameter extends BaseNode {
     name: string;
     /** The name as a node. Absent on parameters the analyzer synthesizes. */
     id?: Identifier;
-    isPack?: boolean;
     /** `<const T>` — infer the argument at its narrowest instead of widening
      *  it: literals stay literal and array literals become tuples. */
     isConst?: boolean;
     /** `<T extends C>` upper bound (TS style). */
     constraint?: TypeNode;
-    default?: TypeNode | TypePackNode;
+    default?: TypeNode;
 }
-type Expression = Identifier | NilLiteral | BooleanLiteral | NumberLiteral | StringLiteral | InterpolatedStringExpression | VarargExpression | FunctionExpression | TableExpression | ArrayExpression | BinaryExpression | UnaryExpression | MemberExpression | IndexExpression | CallExpression | MethodCallExpression | NewExpression | SuperExpression | ClassExpression | SpreadElement | ParenthesizedExpression | TypeAssertionExpression | SatisfiesExpression | AsConstExpression | IfElseExpression | ErrorExpression;
+type Expression = Identifier | NilLiteral | BooleanLiteral | NumberLiteral | StringLiteral | InterpolatedStringExpression | FunctionExpression | TableExpression | ArrayExpression | BinaryExpression | UnaryExpression | MemberExpression | IndexExpression | CallExpression | MethodCallExpression | SuperExpression | ClassExpression | SpreadElement | ParenthesizedExpression | TypeAssertionExpression | SatisfiesExpression | AsConstExpression | IfElseExpression | ErrorExpression;
 /** An expression that could not be parsed. Only produced in recovery mode
  *  (`parseWithRecovery`), where a broken initializer, condition, field value or
  *  argument keeps its place in the tree; its span covers the skipped tokens
@@ -571,15 +598,12 @@ interface InterpolatedStringExpression extends BaseNode {
     type: "InterpolatedStringExpression";
     parts: InterpolatedStringPart[];
 }
-interface VarargExpression extends BaseNode {
-    type: "VarargExpression";
-}
 interface FunctionParameter extends BaseNode {
     type: "FunctionParameter";
     /** `...rest: T[]` — every argument from this position on, as an array,
-     *  the way JavaScript's rest parameter collects them. It is always last,
-     *  and the function is a vararg function: `...` still means Lua's pack
-     *  (`const a, b = ...`), and this is the array of it. */
+     *  the way JavaScript's rest parameter collects them. It is always last.
+     *  It is the only way a function takes a varying number of arguments:
+     *  tilua has no bare `...`. */
     rest?: boolean;
     /** `name?: T` — the argument may be omitted, and its type admits `nil`. */
     optional?: boolean;
@@ -595,8 +619,9 @@ interface FunctionBody extends BaseNode {
     type: "FunctionBody";
     generics: GenericTypeParameter[];
     params: FunctionParameter[];
+    /** The last parameter is a rest parameter (`...rest: T[]`): the Lua
+     *  function takes varargs, and the body sees them as that array. */
     hasVarargs: boolean;
-    varargTypeAnnotation?: TypeNode;
     returnType?: TypeNode;
     /** `: v is T` / `: asserts v` instead of a plain return type. */
     predicate?: TypePredicateNode;
@@ -685,7 +710,7 @@ interface CallExpression extends BaseNode {
     callee: Expression;
     arguments: Expression[];
     /** `f<T>(x)` — type arguments written out rather than inferred. */
-    typeArguments?: (TypeNode | TypePackNode)[];
+    typeArguments?: TypeNode[];
     /** `f?.(...)` — see `MemberExpression.optional`. The call does not happen,
      *  and the arguments are not evaluated, when `callee` is nil. */
     optional?: boolean;
@@ -705,7 +730,7 @@ interface MethodCallExpression extends BaseNode {
     method: Identifier;
     arguments: Expression[];
     /** `obj:m<T>(x)` — see `CallExpression.typeArguments`. */
-    typeArguments?: (TypeNode | TypePackNode)[];
+    typeArguments?: TypeNode[];
     /** `object?:method(...)` — see `MemberExpression.optional`. The
      *  arguments are not evaluated when `object` is nil. */
     optional?: boolean;
@@ -744,7 +769,7 @@ interface IfElseExpression extends BaseNode {
     }[];
     alternate: Expression;
 }
-type TypeNode = TypeReference | TypeLiteralString | TypeLiteralBoolean | TypeLiteralNumber | TableTypeNode | ArrayTypeNode | TupleTypeNode | FunctionTypeNode | UnionTypeNode | IntersectionTypeNode | ParenthesizedTypeNode | TypeofTypeNode | VariadicTypeNode | TypePackNode | KeyofTypeNode | IndexedAccessTypeNode | ConditionalTypeNode | InferTypeNode | MappedTypeNode | TemplateLiteralTypeNode | DifferenceTypeNode;
+type TypeNode = TypeReference | TypeLiteralString | TypeLiteralBoolean | TypeLiteralNumber | TableTypeNode | ArrayTypeNode | TupleTypeNode | FunctionTypeNode | UnionTypeNode | IntersectionTypeNode | ParenthesizedTypeNode | TypeofTypeNode | KeyofTypeNode | IndexedAccessTypeNode | ConditionalTypeNode | InferTypeNode | MappedTypeNode | TemplateLiteralTypeNode | DifferenceTypeNode;
 /** `A - B` — every value of `A` that is not a `B`. Binds tighter than `|`
  *  and looser than `&`, so `A | B - C` is `A | (B - C)`.
  *
@@ -833,17 +858,11 @@ interface TypePredicateNode extends BaseNode {
     /** Absent for a bare `asserts x` (a truthiness assertion). */
     typeAnnotation?: TypeNode;
 }
-interface TypePackNode extends BaseNode {
-    type: "TypePackNode";
-    types: TypeNode[];
-    hasVarargs: boolean;
-    varargType?: TypeNode;
-}
 interface TypeReference extends BaseNode {
     type: "TypeReference";
     base: string;
     namespace?: string;
-    typeArguments: (TypeNode | TypePackNode)[];
+    typeArguments: TypeNode[];
 }
 interface TypeLiteralString extends BaseNode {
     type: "TypeLiteralString";
@@ -884,10 +903,13 @@ interface ArrayTypeNode extends BaseNode {
     type: "ArrayTypeNode";
     element: TypeNode;
 }
-/** `[number, string]` — fixed-length tuple type. */
+/** `[number, string]` — a tuple type; `[string, ...number[]]` ends in a rest
+ *  of as many more as there are. */
 interface TupleTypeNode extends BaseNode {
     type: "TupleTypeNode";
     elements: TypeNode[];
+    /** `...number[]` at the end: the array type the rest of it is. */
+    rest?: TypeNode;
 }
 interface FunctionTypeParameter extends BaseNode {
     type: "FunctionTypeParameter";
@@ -904,8 +926,6 @@ interface FunctionTypeNode extends BaseNode {
     type: "FunctionTypeNode";
     generics: GenericTypeParameter[];
     params: FunctionTypeParameter[];
-    hasVarargs: boolean;
-    varargType?: TypeNode;
     returnType: TypeNode;
     /** `(v: unknown) -> v is string` — a guard written as a function *type*. */
     predicate?: TypePredicateNode;
@@ -928,10 +948,6 @@ interface TypeofTypeNode extends BaseNode {
     type: "TypeofTypeNode";
     expression: Expression;
 }
-interface VariadicTypeNode extends BaseNode {
-    type: "VariadicTypeNode";
-    typeAnnotation: TypeNode;
-}
 type Node = Program | Block | Statement | Expression | TypeNode | FunctionBody | FunctionParameter | FunctionName | IfClause | TypedIdentifier | GenericTypeParameter | FunctionSignature | TypePredicateNode | TableField | SpreadElement | FunctionTypeParameter | TableTypeProperty | BindingTarget | ObjectPatternProperty | ArrayPatternElement;
 
 declare class ParseError extends Error {
@@ -1058,6 +1074,10 @@ declare function isGlobal(binding: Binding): boolean;
  *  undeclared, which is almost always a typo rather than an intentional
  *  implicit global. Handy for a "possibly undefined global" diagnostic. */
 declare function isUnassignedGlobal(binding: Binding): boolean;
+/** Globals tilua itself declares, whatever the type libraries do:
+ *  `scriptArgs` is the arguments the script was started with — Lua's
+ *  top-level `...` — as an array. */
+declare const LANGUAGE_GLOBALS: readonly string[];
 declare function analyzeScopes(program: Program, options?: AnalyzeScopesOptions): ScopeAnalysis;
 
 type Type = AnyType | UnknownType | NeverType | PrimitiveType | LiteralType | ArrayType | TupleType | ObjectType | FunctionType | UnionType | IntersectionType | TypeParamType | GenericRefType | KeyofType | IndexedAccessType | ConditionalType | InferType | MappedType | TemplateLiteralType | DifferenceType;
@@ -1100,23 +1120,31 @@ interface ArrayType {
     element: Type;
     alias?: string;
 }
-/** `[A, B, C]` — fixed length.
- *
- *  `isPack` marks the other thing this shape is used for: a *type pack*, the
- *  several values a Lua function returns (`(number, string)`). The two are
- *  structurally identical but behave differently in an expression list — a
- *  pack spreads across several names, a tuple is one value — so they have to
- *  be told apart. */
+/** `[A, B, C]` — fixed length; `[A, ...B[]]` — at least that, then any
+ *  number of `B`. `rest` is the element type of that tail. A tuple is an
+ *  array, a table like any other: several results are one of these. */
 interface TupleType {
     kind: "tuple";
     elements: Type[];
-    isPack?: boolean;
+    rest?: Type;
     alias?: string;
 }
 interface ObjectProperty {
     type: Type;
     optional: boolean;
     readonly?: boolean;
+    /** A class member written `private`: reachable only from inside the class
+     *  that declared it. `owner` is that class's node, compared by identity;
+     *  `className` is how a diagnostic names it. Checked, never lowered.
+     *  `protected` widens that to the classes extending it. */
+    private?: {
+        owner: object;
+        className: string;
+        protected?: boolean;
+    };
+    /** An `abstract` class member: declared, with nothing behind it until a
+     *  class extending this one writes it. */
+    abstract?: boolean;
 }
 interface ObjectType {
     kind: "object";
@@ -1178,8 +1206,14 @@ interface TypePredicate {
 interface FunctionType {
     kind: "function";
     params: FunctionParam[];
+    /** The type of each argument a rest parameter (`...args: T[]`) collects —
+     *  or, with `restIsWhole`, the rest parameter's own type. */
     varargs?: Type;
-    /** A tuple when the function returns multiple values. */
+    /** `...args: A` where `A` is a tuple, or a type parameter standing for
+     *  one (`<A extends unknown[]>`): `varargs` is `A` itself, and once `A`
+     *  is known its elements are the parameters. */
+    restIsWhole?: boolean;
+    /** What the function returns: one value — several are an array. */
     returns: Type;
     /** Names of the function's own generic parameters (`function f<T>(...)`).
      *  `params` / `returns` may contain `typeParam` nodes for these. */
@@ -1328,7 +1362,9 @@ declare const bufferType: PrimitiveType;
 declare function primitive(name: PrimitiveName): PrimitiveType;
 declare function literal(value: string | number | boolean): LiteralType;
 declare function arrayOf(element: Type): ArrayType;
-declare function tuple(elements: Type[], isPack?: boolean): TupleType;
+declare function tuple(elements: Type[], rest?: Type): TupleType;
+/** Every element type a tuple can hold, the rest's included. */
+declare function tupleMembers(t: TupleType): Type[];
 declare function objectType(entries: Iterable<[string, ObjectProperty]>, indexer?: ObjectType["indexer"], frozen?: boolean): ObjectType;
 declare function fn(params: FunctionParam[], returns: Type, varargs?: Type, typeParams?: string[], predicate?: TypePredicate): FunctionType;
 declare function substitute(t: Type, subst: Map<string, Type>): Type;
@@ -1393,6 +1429,20 @@ interface TypeDiagnostic {
     node: Expression | Statement | TypeNode | Block | ClassMember;
     message: string;
 }
+/** How a `for (const item in source)` walks its source — what lowering needs,
+ *  decided with the item's type so the two cannot drift apart.
+ *  - `values`: an array or a table, walked directly; the item is each value.
+ *  - `function`: an iterator function, called until it answers nil; the item
+ *    is each answer.
+ *  - `iteration`: `[step, state, first]`, as `pairs(t)` answers: `step` is
+ *    called with the state and the item before (`first` the first time) until
+ *    it answers nil.
+ *  `viaIter`: the source is an object whose `__iter` method gives the function
+ *  or the iteration. */
+interface LoopForm {
+    readonly walks: "values" | "function" | "iteration";
+    readonly viaIter: boolean;
+}
 interface TypeAnalysis {
     /** Inferred type of every expression node. */
     readonly typeOf: Map<Expression, Type>;
@@ -1404,7 +1454,7 @@ interface TypeAnalysis {
     /** What every type annotation node resolves to — `number`, `Shape`,
      *  `typeof x`, a property's type inside `{ ... }`. Inside a generic alias or
      *  function its parameters stay unresolved (`T`). */
-    readonly typeOfTypeNode: Map<TypeNode | TypePackNode, Type>;
+    readonly typeOfTypeNode: Map<TypeNode, Type>;
     /** What each call argument is expected to be: the parameter it lands on,
      *  with the signature's type parameters replaced by their constraints — a
      *  union when an overload set disagrees. Recorded even for a call that does
@@ -1414,13 +1464,9 @@ interface TypeAnalysis {
     /** Top-level type aliases, resolved — and the type names this module
      *  imports, so tooling treats both alike. */
     readonly aliases: Map<string, Type>;
-    /** The `for x in t` loops that walk a table directly, where tilua's one
-     *  variable takes the *value* — not an iterator such as `pairs(t)` or
-     *  `string.gmatch(s, p)`, whose variables are bound as written. Luau hands
-     *  the key over first, so lowering these needs a key variable in front.
-     *  Deciding that here keeps it next to the types the same choice produces:
-     *  the variable's type and the code bound to it cannot drift apart. */
-    readonly iteratesValues: ReadonlySet<GenericForStatement>;
+    /** How each `for (const item in source)` walks its source; see
+     *  `LoopForm`. A loop missing here walks values. */
+    readonly loops: ReadonlyMap<GenericForStatement, LoopForm>;
     readonly diagnostics: TypeDiagnostic[];
 }
 /** A type a module exports: the resolved type, plus the parameter names of a
@@ -1491,11 +1537,15 @@ resolveModule?: (specifier: string) => ModuleExports | undefined): ModuleExports
  * (`tilua.methods` in its package.json). Nothing about `filter` is written
  * into the analyzer.
  */
-declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...unknown) => infer R ? R : never\ntype Parameters<T> = T extends (...infer P) => unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n";
+declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...args: unknown[]) => infer R ? R : never\ntype Parameters<T> = T extends (...args: infer P) => unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n";
 
 interface ProjectHost {
     /** A file's text, or `undefined` when there is no such file. */
     readFile(path: string): string | undefined;
+    /** The names of the folders in a folder, or `undefined` when there is no
+     *  such folder. Only a `types` entry with a `*` in it lists anything; a
+     *  host without this cannot load one. */
+    readDirectory?(path: string): string[] | undefined;
 }
 declare const nodeHost: ProjectHost;
 
@@ -1609,9 +1659,20 @@ declare function resolveTypeLibraries(config: TiluaConfig, host?: ProjectHost):
 
 interface LoweringPlugin {
     /** Luau the plugin needs in the output, by a key it chooses. Each is a
-     *  file's worth of source with `__NAME__` standing for the local the
-     *  compiler gives it, and each is emitted once, at the top of the output,
-     *  only if `use` asked for it:
+     *  file's worth of source, emitted once, at the top of the output, only if
+     *  `use` asked for it. Two names in it are filled in by the compiler:
+     *
+     *   - `__NAME__`, the local the compiler gives this runtime;
+     *   - `__LINES__`, an expression holding the bundle's line map —
+     *     `{ [bundleLine] = { "src/a.tilua", sourceLine } }` — or `nil` when
+     *     the output is not a bundle. It is what turns a line Luau reports at
+     *     runtime back into a place in the project;
+     *   - `__FAIL__`, the bundle's error reporter, or `nil` outside a bundle:
+     *     a function that takes an error and returns it with the bundle's
+     *     positions replaced by the project's, followed by a traceback of
+     *     those. It is an `xpcall` handler — the one the entry runs under —
+     *     so a runtime that runs a callback on a thread of its own can report
+     *     that callback's errors the same way.
      *
      *      local __NAME__ = {}
      *      function __NAME__.filter(t, test) ... end
@@ -1621,24 +1682,84 @@ interface LoweringPlugin {
      *  method call, which is what a value that answers to the method itself
      *  wants — `text:upper()` reaches Lua's own. */
     methodCall?(call: MethodCall): MethodLowering | undefined;
+    /** What a call to a global — `print(...)`, `error(...)` — becomes. Asked
+     *  only when the name really is the global: a local the author called
+     *  `print` is theirs. `undefined` leaves the call as it was written. */
+    globalCall?(call: GlobalCall): CallLowering | undefined;
+    /** What a global read as a value — `task.spawn(print, x)`, `local p =
+     *  print` — becomes: a Luau expression, usually built from `use(...)`.
+     *  There is no call site to describe here, so this is where a plugin
+     *  that rewrites calls keeps the rest of the program consistent with it. */
+    globalValue?(value: GlobalValue): string | undefined;
+}
+/** Where a call was written. */
+interface CallSite {
+    /** The file, relative to the project root with `/` separators, or
+     *  `undefined` when a single source was compiled with no name. */
+    readonly file: string | undefined;
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based. */
+    readonly column: number;
+}
+/** What the compiler knows about one argument that the runtime will not. */
+interface ArgumentInfo {
+    /** Its type, as the analyzer worked it out. */
+    readonly type: Type | undefined;
+    /** That type as the editor would show it — `(x: number) => number` —
+     *  so a library can print it without depending on this package. */
+    readonly typeText: string | undefined;
+    /** The code it was written as, at the call. */
+    readonly source: string;
+    /** For a name, the code of what it names — the value of `const f = ...`,
+     *  or the whole `function f() { ... }` — when this file declares it. */
+    readonly declaration?: string;
+    /** Written `...xs`. */
+    readonly spread: boolean;
+}
+interface CallContext {
+    /** Where the call was written. */
+    readonly at: CallSite;
+    /** Each written argument, in order. */
+    readonly arguments: readonly ArgumentInfo[];
+    /** The local name the output gives one of `runtime`'s entries, emitting
+     *  it if this is the first call that needed it. */
+    use(runtime: string): string;
 }
-interface MethodCall {
+interface MethodCall extends CallContext {
     /** The name written after `:`. */
     readonly method: string;
     /** The receiver's type, as the analyzer worked it out. `undefined` when
      *  nothing typed it, where a plugin should decline rather than guess. */
     readonly receiver: Type | undefined;
+    /** The receiver's name when it is a global — `console` in
+     *  `console:log(x)` — and `undefined` for anything else, a local of the
+     *  same name included. */
+    readonly receiverGlobal: string | undefined;
     /** How many arguments were written. */
     readonly argumentCount: number;
-    /** The local name the output gives one of `runtime`'s entries, emitting
-     *  it if this is the first call that needed it. */
+}
+interface GlobalCall extends CallContext {
+    /** The global called. */
+    readonly name: string;
+}
+interface GlobalValue {
+    /** The global read. */
+    readonly name: string;
+    readonly at: CallSite;
     use(runtime: string): string;
 }
-interface MethodLowering {
+interface CallLowering {
     /** What to call instead: a name, or a `table.member` path — usually built
      *  from `use(...)`. */
     readonly callee: string;
-    /** Pass the receiver as the first argument. Default: yes. */
+    /** Luau expressions passed ahead of the written arguments — the call
+     *  site, say, or a table of what the compiler knew about them. */
+    readonly prepend?: readonly string[];
+}
+interface MethodLowering extends CallLowering {
+    /** Pass the receiver as the first argument, after `prepend`. Default:
+     *  yes. */
     readonly passReceiver?: boolean;
 }
 
@@ -1688,4 +1809,4 @@ declare const tilua: {
     readonly analyzeTypes: typeof analyzeTypes;
 };
 
-export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, type BuildTarget, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassAccessor, type ClassConstructor, type ClassDeclaration, type ClassExpression, type ClassField, type ClassInfo, type ClassLike, type ClassMember, type ClassMethod, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type ExpressionStatement, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NewExpression, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type SuperExpression, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type TiluaConfig, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypeOrigin, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, aliasNameOf, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, declaredUnknownType, tilua as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, setDeferredBound, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tilua, tokenize, tuple, typeParam, unify, union, unknownType, widen, withAliasName, withoutAliasName };
+export { type AnalyzeTypesOptions, type AnyType, type ArgumentInfo, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, type BuildTarget, CONFIG_FILE_NAMES, type CallExpression, type CallLowering, type CallSite, type CallStatement, type ClassAccessibility, type ClassAccessor, type ClassConstructor, type ClassDeclaration, type ClassExpression, type ClassField, type ClassInfo, type ClassLike, type ClassMember, type ClassMethod, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type ExpressionStatement, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type GlobalCall, type GlobalValue, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LANGUAGE_GLOBALS, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type SuperExpression, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type TiluaConfig, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypeOrigin, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VariableDeclaration, type WhileStatement, aliasNameOf, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, declaredUnknownType, tilua as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, setDeferredBound, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tilua, tokenize, tuple, tupleMembers, typeParam, unify, union, unknownType, widen, withAliasName, withoutAliasName };