@tilua/parser 2.4.0 → 3.0.1

package/dist/index.js

@@ -629,7 +629,8 @@ var DECLARATION_STATEMENTS = /* @__PURE__ */ new Set([
   "ExportNamedStatement",
   "ExportAllStatement",
   "DeclareStatement",
-  "DeclareClassStatement"
+  "DeclareClassStatement",
+  "DeclareMetatableStatement"
 ]);
 function spanFrom(start, end) {
   return {
@@ -1247,6 +1248,9 @@ var Parser = class {
       if (p1.type === "Identifier" && p1.value === "class" && this.peek(2).type === "Identifier") {
         return this.parseDeclareClassStatement();
       }
+      if (p1.type === "Identifier" && p1.value === "metatable" && !this.punctuatorAt(2, ":")) {
+        return this.parseDeclareMetatableStatement();
+      }
       if (p1.type === "Identifier" || p1.type === "Keyword" && p1.value === "function") {
         return this.parseDeclareStatement();
       }
@@ -1299,6 +1303,17 @@ var Parser = class {
     }
     return tokenIdentifier(first);
   }
+  // `declare metatable<T> T[]: { __index: { ... } }`
+  parseDeclareMetatableStatement() {
+    const start = this.current();
+    this.advance();
+    this.advance();
+    const generics = this.checkOperator("<") ? this.parseGenericTypeParameterList() : [];
+    const target = this.parseType();
+    this.expectPunctuator(":");
+    const metatable = this.parseType();
+    return { type: "DeclareMetatableStatement", generics, target, metatable, ...spanFrom(start, this.previous()) };
+  }
   // `declare class Name extends Base { member: T, ... }`
   parseDeclareClassStatement() {
     const start = this.current();
@@ -2007,6 +2022,14 @@ var Parser = class {
   parseExpressionStatement() {
     const start = this.current();
     if (this.checkPunctuator("{") || this.checkPunctuator("[")) {
+      const call = this.tryParse(() => {
+        const errors = this.errors.length;
+        const expression2 = this.parseAtom();
+        if (expression2.type !== "MethodCallExpression" && expression2.type !== "CallExpression") throw new ParseRecover("not a call");
+        if (this.errors.length > errors) throw new ParseRecover("not a call");
+        return expression2;
+      });
+      if (call) return { type: "CallStatement", expression: call, ...spanFrom(start, this.previous()) };
       const target = this.checkPunctuator("{") ? this.parseObjectPattern(true) : this.parseArrayPattern(true);
       return this.parseAssignmentRest(start, target);
     }
@@ -2328,11 +2351,9 @@ var Parser = class {
     if (t.type === "Identifier" && t.value === "class") {
       return this.parseClassExpression();
     }
-    if (t.type === "Punctuator" && t.value === "{") {
-      return this.parseTableExpression();
-    }
-    if (t.type === "Punctuator" && t.value === "[") {
-      return this.parseArrayExpression();
+    if (t.type === "Punctuator" && (t.value === "{" || t.value === "[")) {
+      const literal2 = t.value === "{" ? this.parseTableExpression() : this.parseArrayExpression();
+      return this.checkPunctuator(":") && this.startsMethodCall() ? this.parseSuffixes(literal2) : literal2;
     }
     if (this.checkType("Identifier") && this.punctuatorAt(1, "=>")) return this.parseArrow();
     if (this.checkPunctuator("(") || this.checkOperator("<")) {
@@ -2409,6 +2430,11 @@ var Parser = class {
     } else {
       this.error("Expected identifier or '('");
     }
+    return this.parseSuffixes(base);
+  }
+  /** What follows a prefix expression's base: `.name`, `[key]`, `:m(...)`,
+   *  a call, and their optional forms. */
+  parseSuffixes(base) {
     while (true) {
       if (this.checkPunctuator("?") && this.touchesNext()) {
         const next = this.peek(1);
@@ -3762,6 +3788,10 @@ var Analyzer = class {
   moduleScope = this.globalScope;
   /** How many function bodies enclose the walk. */
   functionDepth = 0;
+  /** How many loops enclose the walk inside the nearest function body. A
+   *  function starts again at 0: `continue` in `xs:map(x => ...)` has no
+   *  loop to go on with, whatever loop the call is written in. */
+  loopDepth = 0;
   /** Function declarations already declared by their block's hoisting, with
    *  the function depth of that block. */
   hoisted = /* @__PURE__ */ new Map();
@@ -4114,11 +4144,11 @@ var Analyzer = class {
         return;
       case "WhileStatement":
         this.visitExpression(stmt.condition, scope);
-        this.visitBlockInNewScope(stmt.body, scope);
+        this.inLoop(() => this.visitBlockInNewScope(stmt.body, scope));
         return;
       case "RepeatStatement": {
         const bodyScope = childScope(scope);
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         this.visitExpression(stmt.condition, bodyScope);
         return;
       }
@@ -4136,14 +4166,14 @@ var Analyzer = class {
         if (stmt.step) this.visitExpression(stmt.step, scope);
         const bodyScope = childScope(scope);
         this.declare(bodyScope, stmt.variable.name, "for-numeric", stmt.variable);
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         return;
       }
       case "GenericForStatement": {
         this.visitExpression(stmt.iterator, scope);
         const bodyScope = childScope(scope);
         this.declarePattern(bodyScope, stmt.variable, "for-generic", scope, stmt.kind === "const");
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         return;
       }
       case "ReturnStatement":
@@ -4151,6 +4181,15 @@ var Analyzer = class {
         return;
       case "BreakStatement":
       case "ContinueStatement":
+        if (this.loopDepth === 0) {
+          const word = stmt.type === "BreakStatement" ? "break" : "continue";
+          this.diagnostics.push({
+            node: stmt,
+            message: this.functionDepth > 0 ? `'${word}' is not inside a loop of this function; to skip a value in a callback, 'return' from it` : `'${word}' is not inside a loop`,
+            kind: "outside-loop"
+          });
+        }
+        return;
       case "ErrorStatement":
         return;
       case "DeclareStatement":
@@ -4159,6 +4198,11 @@ var Analyzer = class {
       case "DeclareClassStatement":
         this.visitType(stmt.body, scope);
         return;
+      case "DeclareMetatableStatement":
+        this.visitGenerics(stmt.generics, scope);
+        this.visitType(stmt.target, scope);
+        this.visitType(stmt.metatable, scope);
+        return;
       case "TypeAliasStatement":
       case "ExportTypeAliasStatement":
         this.visitGenerics(
@@ -4201,6 +4245,15 @@ var Analyzer = class {
         return;
     }
   }
+  /** Visit a loop's body, where `break` and `continue` have a loop. */
+  inLoop(visit) {
+    this.loopDepth++;
+    try {
+      visit();
+    } finally {
+      this.loopDepth--;
+    }
+  }
   // ---------------- functions ----------------
   visitFunctionBody(func, outerScope, isMethod = false) {
     const fnScope = childScope(outerScope);
@@ -4216,11 +4269,14 @@ var Analyzer = class {
       }
     });
     this.visitType(func.returnType, fnScope);
+    const loops = this.loopDepth;
     this.functionDepth++;
+    this.loopDepth = 0;
     try {
       this.visitBlock(func.body, fnScope);
     } finally {
       this.functionDepth--;
+      this.loopDepth = loops;
     }
   }
   /** An overload signature: no body and no bindings, but its types can hold
@@ -4424,6 +4480,104 @@ type Mutable<T> = { -readonly [K in keyof T]: T[K] }
 type Pick<T, K> = { [P in K]: T[P] }
 type Omit<T, K> = Pick<T, Exclude<keyof T, K>>
 type Record<K, V> = { [P in K]: V }
+
+-- ============================================================
+-- The metatables of the language's own values
+-- ============================================================
+
+-- A string's methods. The first group is Lua's string library, which a
+-- string really answers to; where Lua answers several values, tilua answers
+-- one, as the global functions do (\`find\` is an array, \`gsub\` the new
+-- string). The second group is written the way JavaScript writes it.
+--
+-- Positions are Lua's: \`sub\` and \`slice\` count from 1, and \`indexOf\` is
+-- \`nil\` when the text is not there.
+declare metatable string: {
+    __index: {
+        upper: (self: string) => string,
+        lower: (self: string) => string,
+        len: (self: string) => number,
+        sub: (self: string, i: number, j?: number) => string,
+        rep: (self: string, n: number, separator?: string) => string,
+        reverse: (self: string) => string,
+        format: (self: string, ...args: unknown[]) => string,
+        byte: ((self: string, i?: number) => number) & ((self: string, i: number, j: number) => number[]),
+        find: (self: string, pattern: string, init?: number, plain?: boolean) => [number, number, ...string[]] | nil,
+        match: (self: string, pattern: string, init?: number) => [...string[]] | nil,
+        gmatch: (self: string, pattern: string) => () => [string, ...string[]] | nil,
+        gsub: (self: string, pattern: string, replacement: unknown, n?: number) => string,
+
+        trim: (self: string) => string,
+        trimStart: (self: string) => string,
+        trimEnd: (self: string) => string,
+        startsWith: (self: string, text: string) => boolean,
+        endsWith: (self: string, text: string) => boolean,
+        includes: (self: string, text: string) => boolean,
+        indexOf: (self: string, text: string, start?: number) => number | nil,
+        slice: (self: string, start?: number, stop?: number) => string,
+        replace: (self: string, text: string, replacement: string) => string,
+        replaceAll: (self: string, text: string, replacement: string) => string,
+        padStart: (self: string, length: number, padding?: string) => string,
+        padEnd: (self: string, length: number, padding?: string) => string,
+    },
+}
+
+-- An array's methods. Lua gives an array no metatable: the compiler lowers
+-- each call to a plain function, so they work on any array, one a Lua
+-- library made included.
+--
+-- Indices are Lua's: the first element is 1, and \`indexOf\` / \`findIndex\`
+-- answer \`nil\` rather than JavaScript's -1. \`sort\` takes Lua's comparator
+-- (true when \`a\` comes first). \`push\`, \`pop\`, \`shift\`, \`unshift\`,
+-- \`sort\` and \`reverse\` change the array; everything else returns a new one.
+-- A \`filter\` whose test is a guard \u2014 \`v is S\`, or \`v => v ~= nil\` \u2014
+-- answers an array of what it let through.
+declare metatable<T> T[]: {
+    __index: {
+        find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,
+        findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,
+        filter: (<S extends T>(self: T[], test: (value: T, index: number) => value is S) => S[])
+            & ((self: T[], test: (value: T, index: number) => boolean) => T[]),
+        map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],
+        forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,
+        some: (self: T[], test: (value: T, index: number) => boolean) => boolean,
+        every: (self: T[], test: (value: T, index: number) => boolean) => boolean,
+        reduce: <U>(self: T[], step: (total: U, value: T, index: number) => U, initial: U) => U,
+        includes: (self: T[], value: T) => boolean,
+        indexOf: (self: T[], value: T, start?: number) => number | nil,
+        join: (self: T[], separator?: string) => string,
+        concat: (self: T[], ...others: T[][]) => T[],
+        slice: (self: T[], start?: number, stop?: number) => T[],
+        flat: (self: T[]) => T[],
+        reverse: (self: T[]) => T[],
+        sort: (self: T[], compare?: (a: T, b: T) => boolean) => T[],
+        push: (self: T[], ...args: T[]) => number,
+        pop: (self: T[]) => T | nil,
+        shift: (self: T[]) => T | nil,
+        unshift: (self: T[], ...args: T[]) => number,
+    },
+}
+
+-- A table's methods. Unlike JavaScript's \`Object.keys\`, they answer a
+-- tuple, in the order the table's type wrote its members:
+--
+--     const point = { x: 1, y: "up" }
+--     point:keys()     -- ["x", "y"]
+--     point:values()   -- [number, string]
+--     point:entries()  -- [["x", number], ["y", string]]
+--
+-- A Lua table has no order of its own, so the compiler hands its runtime the
+-- keys as the type lists them. An optional member keeps its place, holding
+-- \`nil\` when it is missing; an indexer's keys follow the named ones. A
+-- member of the table's own with one of these names is what a call reaches,
+-- and a class instance, which has a metatable of its own, has none of them.
+declare metatable<T extends {}> T: {
+    __index: {
+        keys: (self: T) => ObjectKeys<T>,
+        values: (self: T) => ObjectValues<T>,
+        entries: (self: T) => ObjectEntries<T>,
+    },
+}
 `;
 var prelude;
 function preludeProgram() {
@@ -4522,8 +4676,14 @@ function substitute(t, subst) {
   if (subst.size === 0) return t;
   if (!containsTypeParam(t)) return t;
   switch (t.kind) {
-    case "typeParam":
-      return subst.get(t.name) ?? t;
+    case "typeParam": {
+      const bound = subst.get(t.name);
+      if (bound) return bound;
+      if (t.constraint && containsTypeParam(t.constraint)) {
+        return { ...t, constraint: substitute(t.constraint, new Map([...subst, [t.name, t]])) };
+      }
+      return t;
+    }
     case "array":
       return { ...arrayOf(substitute(t.element, subst)), readonly: t.readonly };
     case "tuple":
@@ -4668,6 +4828,10 @@ function unify(param, arg, vars, out, how = "union") {
       if (arg.kind === "function") {
         param.params.forEach((p, i) => arg.params[i] && unify(p.type, arg.params[i].type, vars, out));
         unify(param.returns, arg.returns, vars, out);
+        const wanted = param.predicate, given = arg.predicate;
+        if (wanted?.type && given?.type && wanted.param === given.param && !wanted.asserts && !given.asserts) {
+          unify(wanted.type, given.type, vars, out);
+        }
       }
       return;
     case "object":
@@ -4923,6 +5087,11 @@ function isAssignableInner(a, b) {
     for (let i = 0; i < n; i++) {
       if (!isAssignable(a.params[i].type, b.params[i].type) && !isAssignable(b.params[i].type, a.params[i].type)) return false;
     }
+    const wanted = b.predicate;
+    if (wanted?.type && !wanted.asserts) {
+      const given = a.predicate;
+      if (!given?.type || given.asserts || given.param !== wanted.param || !isAssignable(given.type, wanted.type)) return false;
+    }
     return isAssignable(a.returns, b.returns);
   }
   if (b.kind === "typeParam") return false;
@@ -5057,7 +5226,7 @@ function containsFreeTypeParam(t, seen, bound) {
       return [...t.properties.values()].some((v) => containsTypeParam(v.type, seen, bound)) || !!t.indexer && (containsTypeParam(t.indexer.key, seen, bound) || containsTypeParam(t.indexer.value, seen, bound));
     case "function": {
       const inner = t.typeParams?.length ? /* @__PURE__ */ new Set([...bound, ...t.typeParams]) : bound;
-      return t.params.some((p) => containsTypeParam(p.type, seen, inner)) || !!t.varargs && containsTypeParam(t.varargs, seen, inner) || containsTypeParam(t.returns, seen, inner);
+      return t.params.some((p) => containsTypeParam(p.type, seen, inner)) || !!t.varargs && containsTypeParam(t.varargs, seen, inner) || containsTypeParam(t.returns, seen, inner) || !!t.predicate?.type && containsTypeParam(t.predicate.type, seen, inner);
     }
     case "genericRef":
       return t.typeArguments.some((a) => containsTypeParam(a, seen, bound));
@@ -5482,9 +5651,14 @@ function isFreshLiteralExpr(e) {
     case "StringLiteral":
     case "BooleanLiteral":
     case "InterpolatedStringExpression":
+      return true;
+    // A table or array literal widened the literals written in it as it
+    // was read (`widenUnlessAsked`), and keeps what it read from
+    // elsewhere — `{ key: name }`, `[...names]` — so there is nothing
+    // left for the binding to widen.
     case "TableExpression":
     case "ArrayExpression":
-      return true;
+      return false;
     case "ParenthesizedExpression":
       return isFreshLiteralExpr(e.expression);
     case "UnaryExpression":
@@ -5499,6 +5673,30 @@ function isFreshLiteralExpr(e) {
       return false;
   }
 }
+function overloadTier(f) {
+  const takesGuard = f.params.some((p) => p.type.kind === "function" && p.type.predicate?.type && !p.type.predicate.asserts);
+  if (takesGuard) return 0;
+  return (f.typeParams?.length ?? 0) > 0 ? 2 : 1;
+}
+function writesLiteral(e) {
+  switch (e.type) {
+    case "NumberLiteral":
+    case "StringLiteral":
+    case "BooleanLiteral":
+    case "InterpolatedStringExpression":
+      return true;
+    case "ParenthesizedExpression":
+      return writesLiteral(e.expression);
+    case "UnaryExpression":
+      return writesLiteral(e.argument);
+    case "IfElseExpression":
+      return e.clauses.some((c) => writesLiteral(c.body)) || writesLiteral(e.alternate);
+    case "BinaryExpression":
+      return (e.operator === "or" || e.operator === "and") && (writesLiteral(e.left) || writesLiteral(e.right));
+    default:
+      return false;
+  }
+}
 function collectInferNames(node) {
   const out = [];
   const walk = (n) => {
@@ -5789,6 +5987,10 @@ var TypeAnalyzer = class {
   typeOfTypeNode = /* @__PURE__ */ new Map();
   expectedTypeOf = /* @__PURE__ */ new Map();
   loops = /* @__PURE__ */ new Map();
+  /** Every `declare metatable`, libraries first, in declaration order. */
+  metatables = [];
+  metatableCache = /* @__PURE__ */ new WeakMap();
+  methodSources = /* @__PURE__ */ new Map();
   /** Public: each alias resolved once (generic aliases keep their params as
    *  `typeParam` nodes in the body). */
   aliases = new LazyMap();
@@ -5855,6 +6057,9 @@ var TypeAnalyzer = class {
     this.registerNestedClasses();
     this.registerNestedAliases();
     for (const lib of this.options.libs ?? []) this.harvestDeclares(lib.body);
+    this.harvestMetatables(preludeProgram().body, { origin: "language" });
+    (this.options.libs ?? []).forEach((lib, i) => this.harvestMetatables(lib.body, { origin: "library", library: i }));
+    this.harvestMetatables(this.program.body, { origin: "program" });
     this.registerImportedTypes();
     this.resolveAllAliases();
     this.harvestDeclares(this.program.body, true);
@@ -5886,6 +6091,8 @@ var TypeAnalyzer = class {
       expectedTypeOf: this.expectedTypeOf,
       aliases: this.resolveDeferredAliases(),
       loops: this.loops,
+      methodSources: this.methodSources,
+      metatableMembers: (type) => this.metatableMembers(type),
       diagnostics: this.diagnostics
     };
   }
@@ -5943,8 +6150,7 @@ var TypeAnalyzer = class {
   }
   /** `layering` is on for the prelude and for definitions files: a second
    *  library that declares an alias already declared *adds* to it, the way a
-   *  second `declare` of a table's name does, so `@tilua-types/roblox` can give
-   *  `StringMethods` Luau's `split` without restating Lua's. The file being
+   *  second `declare` of a table's name does. The file being
    *  analysed is not a layer: its own alias replaces what the libraries
    *  gave, which is how a project opts out of a set. */
   registerAliasDefs(block, layering = false) {
@@ -6862,7 +7068,7 @@ var TypeAnalyzer = class {
       if (record.type === "TypeReference" && typeof record.base === "string") {
         const name = typeof record.namespace === "string" ? `${record.namespace}.${record.base}` : record.base;
         const resolved = this.typeOfTypeNode.get(node);
-        const unresolved = resolved?.kind === "genericRef" && resolved.name === name && !this.aliasDefs.has(name) && !this.importedTypes.has(name) && this.options.libTypes?.[name] === void 0 && !STRING_INTRINSICS.has(name) && !this.importedNames().has(name.split(".")[0]);
+        const unresolved = resolved?.kind === "genericRef" && resolved.name === name && !this.aliasDefs.has(name) && !this.importedTypes.has(name) && this.options.libTypes?.[name] === void 0 && !INTRINSICS.has(name) && !this.importedNames().has(name.split(".")[0]);
         const at = node;
         const key = `${at.line.start}:${at.column.start}`;
         if (unresolved && !reported.has(key)) {
@@ -6980,7 +7186,7 @@ var TypeAnalyzer = class {
           const tp = this.lookupTypeParam(node.base);
           if (tp) return typeParam(tp.name, tp.constraint, tp.isConst);
           if (node.typeArguments.length === 1 && !this.aliasDefs.has(node.base)) {
-            const intrinsic = this.applyStringIntrinsic(
+            const intrinsic = this.applyIntrinsic(
               node.base,
               this.resolveType(node.typeArguments[0])
             );
@@ -7187,7 +7393,7 @@ var TypeAnalyzer = class {
           return difference(this.reduceType(t.base), this.reduceType(t.excluded));
         case "genericRef": {
           if (t.typeArguments.length !== 1 || this.aliasDefs.has(t.name)) return t;
-          return this.applyStringIntrinsic(t.name, t.typeArguments[0]) ?? t;
+          return this.applyIntrinsic(t.name, t.typeArguments[0]) ?? t;
         }
         case "conditional":
           return this.reduceConditional(t);
@@ -7300,6 +7506,41 @@ var TypeAnalyzer = class {
     }
     return union(combos.map((c) => literal(c)));
   }
+  /** A type function the analyzer supplies, since tilua cannot write it. */
+  applyIntrinsic(name, arg) {
+    return this.applyStringIntrinsic(name, arg) ?? this.applyObjectIntrinsic(name, arg);
+  }
+  /** `ObjectKeys<T>`, `ObjectValues<T>`, `ObjectEntries<T>`: an object's
+   *  members as a tuple, in the order they were written — `{ a: 1, b: "x" }`
+   *  has keys `["a", "b"]`, values `[number, string]` and entries
+   *  `[["a", number], ["b", string]]`. TypeScript answers `string[]` for
+   *  `Object.keys`, since its objects have no order; tilua's lowering hands
+   *  the runtime the written order, so the tuple is what runs. An indexer's
+   *  keys follow the named ones, as the tuple's rest. */
+  applyObjectIntrinsic(name, arg) {
+    if (!OBJECT_INTRINSICS.has(name)) return void 0;
+    const t = this.expand(this.reduceType(arg));
+    if (containsTypeParam(t)) return void 0;
+    if (t.kind === "union") return union(t.types.map((m) => this.applyObjectIntrinsic(name, m) ?? unknownType));
+    const parts = t.kind === "intersection" ? t.types.map((m) => this.expand(m)) : [t];
+    if (!parts.every((m) => m.kind === "object" && !m.class)) return unknownType;
+    const properties = /* @__PURE__ */ new Map();
+    let indexer;
+    for (const part of parts) {
+      for (const [key, property] of part.properties) properties.set(key, property);
+      indexer ??= part.indexer;
+    }
+    const entries = [...properties].map(([key, p]) => [literal(key), p.optional ? optional(p.type) : p.type]);
+    const listed = (elements, rest) => !elements.length && rest ? arrayOf(rest) : tuple(elements, rest);
+    switch (name) {
+      case "ObjectKeys":
+        return listed(entries.map(([key]) => key), indexer?.key);
+      case "ObjectValues":
+        return listed(entries.map(([, value]) => value), indexer?.value);
+      default:
+        return listed(entries.map((entry) => tuple([...entry])), indexer && tuple([indexer.key, indexer.value]));
+    }
+  }
   /** TypeScript's four string intrinsics. They cannot be written in tilua —
    *  there is no character-level type arithmetic — so the analyzer supplies
    *  them, and only them, as named type functions. */
@@ -7838,7 +8079,9 @@ var TypeAnalyzer = class {
     const waits = written.map((a, i) => this.waitsOnInference(a, expected[i]));
     if (!waits.some(Boolean)) return written.map((a) => this.infer(a, env));
     const argTypes = written.map((a, i) => waits[i] ? this.quietly(() => this.infer(a, env)) : this.infer(a, env));
-    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), this.spreadOf(written, selfOf(fns[0])));
+    const spread = this.spreadOf(written, selfOf(fns[0]));
+    const provisional = argTypes.map((t, i) => waits[i] ? anyType : t);
+    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), spread) ?? this.pickOverload(fns, provisional, (f) => extra(f, provisional), spread);
     const subst = picked?.typeParams?.length ? this.inferTypeArgs(picked, extra(picked, argTypes)) : void 0;
     written.forEach((a, i) => {
       if (!waits[i]) return;
@@ -8029,6 +8272,16 @@ var TypeAnalyzer = class {
       }
       const id = this.bindingIdByName(p.name, p);
       const t = this.paramType(p, env);
+      if (p.default && p.typeAnnotation) {
+        const given = this.infer(p.default, env);
+        const declared = this.resolveType(p.typeAnnotation);
+        if (this.emitDiagnostics && !isAssignable(given, declared)) {
+          this.diagnostics.push({
+            node: p.default,
+            message: `Type '${briefType(given)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(given, declared)
+          });
+        }
+      }
       if (id !== void 0) {
         this.bindingType.set(id, t);
         this.setBinding(env, id, t);
@@ -8126,9 +8379,9 @@ var TypeAnalyzer = class {
    *  lets `typeof` declare `(v: number) -> "number"` alongside a trailing
    *  `<T>(v: T) -> string` and still pick the precise one. */
   pickOverload(fns, argTypes, argsFor, spread) {
-    for (const generic of [false, true]) {
+    for (const tier of [0, 1, 2]) {
       for (const f of fns) {
-        if ((f.typeParams?.length ?? 0) > 0 !== generic) continue;
+        if (overloadTier(f) !== tier) continue;
         if (this.overloadAccepts(f, argsFor ? argsFor(f) : argTypes, spread)) return f;
       }
     }
@@ -8154,7 +8407,7 @@ var TypeAnalyzer = class {
     if (position < 0) return void 0;
     const members = this.expand(argTypes[position]).types;
     if (members.length > 32) return void 0;
-    const rank = (f) => ((f.typeParams?.length ?? 0) > 0 ? fns.length : 0) + fns.indexOf(f);
+    const rank = (f) => overloadTier(f) * fns.length + fns.indexOf(f);
     const limit = picked ? rank(picked) : Infinity;
     const results = [];
     for (const member of members) {
@@ -8547,10 +8800,38 @@ var TypeAnalyzer = class {
         returns,
         void 0,
         names,
-        this.resolvePredicate(func.predicate, params)
+        func.predicate || func.returnType ? this.resolvePredicate(func.predicate, params) : this.inferPredicate(func, params, returns, bodyEnv)
       ), func.params);
     });
   }
+  /** `v => v ~= nil` is a guard without saying so, as TypeScript reads it:
+   *  a body that is one `return` of a boolean which, true, narrows a
+   *  parameter — and, false, leaves it exactly what that excludes. Then
+   *  `list:filter(v => v ~= nil)` knows what it kept. */
+  inferPredicate(func, params, returns, env) {
+    const only = func.body.statements.length === 1 ? func.body.statements[0] : void 0;
+    if (only?.type !== "ReturnStatement" || !only.argument) return void 0;
+    if (returns.kind === "any" || returns.kind === "never" || !isAssignable(returns, booleanType)) return void 0;
+    const cond = only.argument;
+    for (let i = 0; i < params.length; i++) {
+      const p = func.params[i];
+      if (p.pattern || p.rest) continue;
+      const id = this.bindingIdByName(p.name, p);
+      if (id === void 0) continue;
+      const declared = params[i].type;
+      const key = bindKey(id);
+      const t = forkEnv(env);
+      const f = forkEnv(env);
+      this.silently(() => this.applyNarrowing(cond, env, t, f));
+      const yes = t.get(key);
+      if (!yes || equalTypes(yes, declared) || !isAssignable(yes, declared)) continue;
+      const no = this.expand(f.get(key) ?? declared);
+      const rest = no.kind === "union" ? no.types : [no];
+      if (rest.some((m) => m.kind !== "never" && isAssignable(m, yes))) continue;
+      return { param: i, type: yes, asserts: false };
+    }
+    return void 0;
+  }
   /** Where the return types of the function being walked are collected, so
    *  each is read where it is written — inside the branch that narrowed it —
    *  rather than in whatever state the body ends in. */
@@ -8981,28 +9262,122 @@ var TypeAnalyzer = class {
       this.resolvingAliases.delete(t.name);
     }
   }
-  /** `names:filter(f)`, `text:trim()` — the methods arrays and strings have.
-   *  They are written in the prelude as `ArrayMethods<T>` and
-   *  `StringMethods`, so a file (or a type library) that declares one of
-   *  those names again replaces the whole set, and nothing here is a special
-   *  case in the analyzer. The build lowers each call to a plain function. */
-  builtInMethod(t, name) {
-    const parts = (t.kind === "union" ? t.types : [t]).map((m) => this.expand(m));
-    const elements = parts.map((m) => m.kind === "array" ? m.element : m.kind === "tuple" ? union(m.elements) : void 0);
-    const element = elements.every((e) => e !== void 0) ? union(elements) : void 0;
-    const isString = (m) => m.kind === "primitive" && m.name === "string" || m.kind === "literal" && m.base === "string" || m.kind === "templateLiteral";
-    const methodTable = element !== void 0 ? "ArrayMethods" : parts.every(isString) ? "StringMethods" : void 0;
-    const def = methodTable === void 0 ? void 0 : this.aliasDefs.get(methodTable);
-    if (!def || def.class) return void 0;
-    const table = this.expand(this.instantiateAlias(def, element !== void 0 ? [element] : []));
-    const layers = table.kind === "intersection" ? table.types.map((m) => this.expand(m)) : [table];
-    for (let i = layers.length - 1; i >= 0; i--) {
-      const part = layers[i];
-      const property = part.kind === "object" ? part.properties.get(name) : void 0;
-      if (property) return property.type;
+  // --------------------------------------------------------
+  // Metatables
+  // --------------------------------------------------------
+  harvestMetatables(block, source) {
+    for (const stmt of block.statements) {
+      if (stmt.type === "DeclareMetatableStatement") this.metatables.push({ node: stmt, source });
+    }
+  }
+  resolvedMetatable(entry) {
+    entry.resolved ??= this.withTypeParams(entry.node.generics, () => ({
+      target: this.resolveType(entry.node.target),
+      metatable: this.resolveType(entry.node.metatable)
+    }));
+    return entry.resolved;
+  }
+  /** Does a value (`whole`, whose union members are `parts`) have the
+   *  metatable `entry` declares — and if so how specifically, and what its
+   *  type parameters stand for there. Three kinds of target:
+   *
+   *   - `<T> T[]`: every array and tuple, `T` what they hold;
+   *   - `<T extends C> T`: every value that is a `C` other than a class
+   *     instance, which has a metatable of its own; `T` the value itself;
+   *   - a type with no parameters (`string`): every value that is one.
+   *
+   *  A bare parameter matches the most, so it is the least specific: an
+   *  array that is also a `{}` takes an array's metatable. */
+  matchMetatable(entry, whole, parts) {
+    if (!parts.length || parts.some((m) => m.kind === "any" || m.kind === "unknown" || m.kind === "never")) return void 0;
+    const { target } = this.resolvedMetatable(entry);
+    if (target.kind === "array" && target.element.kind === "typeParam") {
+      const elements = parts.map((m) => m.kind === "array" ? m.element : m.kind === "tuple" ? union(tupleMembers(m)) : void 0);
+      if (!elements.every((e) => e !== void 0)) return void 0;
+      return { specificity: 2, bindings: /* @__PURE__ */ new Map([[target.element.name, union(elements)]]) };
+    }
+    if (target.kind === "typeParam") {
+      const constraint = target.constraint;
+      if (parts.some((m) => m.kind === "object" && m.class)) return void 0;
+      if (constraint && !parts.every((m) => isAssignable(m, constraint))) return void 0;
+      return { specificity: 1, bindings: /* @__PURE__ */ new Map([[target.name, whole]]) };
+    }
+    if (containsTypeParam(target)) return void 0;
+    return parts.every((m) => isAssignable(m, target)) ? { specificity: 2, bindings: /* @__PURE__ */ new Map() } : void 0;
+  }
+  /** The metatables `t` has: every declaration of the most specific target
+   *  it matches, instantiated for it, in declaration order — a later one
+   *  adds to an earlier, the way a library layers on another. A type
+   *  parameter is read at its constraint. */
+  metatablesOf(t) {
+    if (!this.metatables.length) return [];
+    const cached = this.metatableCache.get(t);
+    if (cached) return cached;
+    const expanded = this.expand(t);
+    const parts = (expanded.kind === "union" ? expanded.types : [expanded]).map((m) => this.expand(m)).map((m) => m.kind === "typeParam" && m.constraint ? this.expand(m.constraint) : m);
+    const whole = union(parts);
+    const matches = this.metatables.flatMap((entry) => {
+      const match = this.matchMetatable(entry, whole, parts);
+      return match ? [{ entry, ...match }] : [];
+    });
+    const best = Math.max(0, ...matches.map((m) => m.specificity));
+    const found = matches.filter((m) => m.specificity === best).map(({ entry, bindings }) => ({
+      type: this.expand(this.reduceType(substitute(this.resolvedMetatable(entry).metatable, bindings))),
+      source: entry.source
+    }));
+    this.metatableCache.set(t, found);
+    return found;
+  }
+  /** The `__index` tables of `t`'s metatables, each with the library that
+   *  declared it, in declaration order. */
+  metatableIndexes(t) {
+    return this.metatablesOf(t).flatMap(({ type, source }) => {
+      const parts = type.kind === "intersection" ? type.types.map((m) => this.expand(m)) : [type];
+      return parts.flatMap((part) => {
+        const index = part.kind === "object" ? part.properties.get("__index") : void 0;
+        if (!index) return [];
+        const table = this.expand(index.type);
+        return (table.kind === "intersection" ? table.types.map((m) => this.expand(m)) : [table]).map((m) => ({ table: m, source }));
+      });
+    });
+  }
+  /** `name` read through `t`'s metatable: `text:upper()` is `upper` in the
+   *  string metatable's `__index`. The last declaration to give the name
+   *  wins. The language's own metatables are declared in the prelude, in
+   *  tilua, like any library's; a library adds to them the same way. */
+  metatableMember(t, name) {
+    const indexes = this.metatableIndexes(t);
+    for (let i = indexes.length - 1; i >= 0; i--) {
+      const { table, source } = indexes[i];
+      const property = table.kind === "object" ? table.properties.get(name) : void 0;
+      if (property) return { type: property.type, source };
     }
     return void 0;
   }
+  metatableMethod(t, name) {
+    return this.metatableMember(t, name)?.type;
+  }
+  hasMetatable(t) {
+    return this.metatablesOf(t).length > 0;
+  }
+  metatableMembers(t) {
+    const members = /* @__PURE__ */ new Map();
+    for (const { table } of this.metatableIndexes(t)) {
+      if (table.kind !== "object") continue;
+      for (const [name, property] of table.properties) members.set(name, property.type);
+    }
+    return members;
+  }
+  /** `text:upper()`, `scores:keys()`: the method a value's metatable gives
+   *  it, when the value has no member of that name of its own. Called with
+   *  `:`, it answers before an object's indexer, since a metatable's
+   *  `__index` is only read for a key the table does not hold. */
+  receiverMetatableMember(objType, name) {
+    const t = this.expand(objType);
+    const parts = (t.kind === "union" ? t.types : [t]).map((m) => this.expand(m));
+    if (parts.some((m) => m.kind === "object" && m.properties.has(name))) return void 0;
+    return this.metatableMember(t, name);
+  }
   /** The most a deferred type could turn out to be. A conditional is one of
    *  its branches, and the true branch stands for a member of what was
    *  tested (`T` in `T extends U ? T : never`); an indexed access reads
@@ -9068,7 +9443,7 @@ var TypeAnalyzer = class {
     if (index.kind !== "literal" || typeof index.value !== "string") return void 0;
     const parts = this.stringParts(object);
     if (!parts) return void 0;
-    const found = parts.map((part) => this.builtInMethod(part, index.value));
+    const found = parts.map((part) => this.metatableMethod(part, index.value));
     return found.every((t) => t !== void 0) ? union(found) : void 0;
   }
   /** The members of `t` when every one of them is a string — `"a" | "b"` is
@@ -9089,13 +9464,13 @@ var TypeAnalyzer = class {
    *  not one of them is a mistake worth reporting, rather than the nil Lua
    *  would hand back. */
   checkStringMember(node, object, key) {
-    if (!this.emitDiagnostics || !this.aliasDefs.has("StringMethods")) return;
+    if (!this.emitDiagnostics || !this.hasMetatable(stringType)) return;
     const parts = this.stringParts(object);
     if (!parts) return;
     const keys = (key.kind === "union" ? key.types : [key]).map((m) => this.expand(m));
     if (!keys.length || !keys.every((m) => m.kind === "literal" && typeof m.value === "string")) return;
     const names = keys.map((m) => String(m.value));
-    if (names.some((name) => parts.some((part) => this.builtInMethod(part, name)))) return;
+    if (names.some((name) => parts.some((part) => this.metatableMethod(part, name)))) return;
     this.diagnostics.push({
       node,
       message: names.length === 1 ? `'${names[0]}' does not exist on a string` : `'${briefType(key)}' does not name a member of a string`
@@ -9127,24 +9502,24 @@ var TypeAnalyzer = class {
       switch (part.kind) {
         case "primitive":
           if (part.name === "nil") continue;
-          if (part.name === "string" && !this.aliasDefs.has("StringMethods")) return false;
-          if (part.name === "string" && this.builtInMethod(part, name)) continue;
+          if (part.name === "string" && !this.hasMetatable(part)) return false;
+          if (part.name === "string" && this.metatableMethod(part, name)) continue;
           break;
         case "literal":
         case "templateLiteral":
           if (part.kind === "templateLiteral" || part.base === "string") {
-            if (!this.aliasDefs.has("StringMethods")) return false;
+            if (!this.hasMetatable(part)) return false;
           }
-          if (this.builtInMethod(part, name)) continue;
+          if (this.metatableMethod(part, name)) continue;
           break;
         case "array":
         case "tuple":
-          if (!this.aliasDefs.has("ArrayMethods")) return false;
-          if (this.builtInMethod(part, name)) continue;
+          if (!this.hasMetatable(part)) return false;
+          if (this.metatableMethod(part, name)) continue;
           break;
         case "object":
           if (part.properties.has(name)) continue;
-          if (part.indexer || part.properties.size === 0 && !part.class || this.builtInMethod(part, name)) return false;
+          if (part.indexer || part.properties.size === 0 && !part.class || this.metatableMethod(part, name)) return false;
           break;
         default:
           return false;
@@ -9279,10 +9654,10 @@ var TypeAnalyzer = class {
       if (p) return p.optional ? optional(p.type) : p.type;
       if (t.indexer) return t.indexer.value;
     }
-    const built = this.builtInMethod(t, name);
+    const built = this.metatableMethod(t, name);
     if (built) return built;
     if (t.kind === "union") {
-      const built2 = this.builtInMethod(t, name);
+      const built2 = this.metatableMethod(t, name);
       if (built2) return built2;
       return union(t.types.map((m) => this.propertyType(m, name)));
     }
@@ -9578,6 +9953,27 @@ var TypeAnalyzer = class {
           elseEnv = whenFalse;
         }
         branches.push(this.infer(expr.alternate, elseEnv));
+        const bodies = [...expr.clauses.map((c) => c.body), expr.alternate].map(unwrapParens);
+        const isEmpty = (e) => e.type === "TableExpression" && e.fields.length === 0 || e.type === "ArrayExpression" && e.elements.length === 0;
+        const others = union(branches.filter((_, i) => !isEmpty(bodies[i])));
+        const parts = (others.kind === "union" ? others.types : [others]).map((m) => this.expand(m)).filter((m) => !(m.kind === "primitive" && m.name === "nil"));
+        const fits = (e) => {
+          if (!parts.length) return void 0;
+          if (e.type === "ArrayExpression") {
+            if (parts.every((m) => m.kind === "array")) return others;
+            return parts.every((m) => m.kind === "array" || m.kind === "tuple") ? tuple([]) : void 0;
+          }
+          return parts.every((m) => m.kind === "object" && !m.class && [...m.properties.values()].every((prop) => prop.optional)) ? others : void 0;
+        };
+        if (bodies.some(isEmpty) && others.kind !== "never" && others.kind !== "any" && bodies.every((body) => !isEmpty(body) || fits(body))) {
+          const typed = bodies.map((body, i) => {
+            if (!isEmpty(body)) return branches[i];
+            const t = fits(body);
+            this.typeOf.set(body, t);
+            return t;
+          });
+          return union(typed);
+        }
         return union(branches);
       }
     }
@@ -9683,7 +10079,9 @@ var TypeAnalyzer = class {
     this.checkPrivateMember(expr.method, objType, expr.method.name);
     this.checkStringMember(expr.method, objType, literal(expr.method.name));
     this.checkMissingMember(expr.method, objType, expr.method.name);
-    const method = this.propertyType(objType, expr.method.name);
+    const fromMetatable = this.receiverMetatableMember(objType, expr.method.name);
+    if (fromMetatable) this.methodSources.set(expr, fromMetatable.source);
+    const method = fromMetatable?.type ?? this.propertyType(objType, expr.method.name);
     const united = this.unionSignatures(method);
     const fns = united ?? this.overloadsOf(method);
     const explicit = this.explicitTypeArguments(expr, fns);
@@ -9882,23 +10280,87 @@ var TypeAnalyzer = class {
     if (wantedTuple && !asConst) return this.inferTupleLiteral(expr, env, wantedTuple);
     const elems = [];
     let hadSpread = false;
+    const written = [];
     for (const el of expr.elements) {
       if (el.type === "SpreadElement") {
         hadSpread = true;
-        const s = this.infer(el.argument, env);
-        if (s.kind === "array") elems.push(s.element);
-        else if (s.kind === "tuple") elems.push(...s.elements);
-        else elems.push(unknownType);
+        const spread = this.infer(el.argument, env);
+        written.push({ spread: true, type: spread });
+        elems.push(...this.spreadElements(spread));
       } else {
-        elems.push(asConst ? this.inferAsConst(el, env) : this.infer(el, env));
+        const t = asConst ? this.inferAsConst(el, env) : this.infer(el, env);
+        written.push({ spread: false, type: asConst ? t : this.widenUnlessAsked(t, el) });
+        elems.push(t);
       }
     }
     if (asConst && !hadSpread) return tuple(elems);
+    if (hadSpread) {
+      const tuples = this.spreadTuples(written);
+      if (tuples) return union(tuples.map((elements) => tuple(elements)));
+    }
     return arrayOf(elems.length ? union(elems.map((t, i) => {
       const element = expr.elements[i];
       return asConst || !element || element.type === "SpreadElement" ? t : this.widenUnlessAsked(t, element);
     })) : unknownType);
   }
+  /** The tuples an array literal with spreads is, when every spread is a
+   *  tuple of known length or a union of them: one per way the unions go.
+   *  `undefined` when a spread's length is not known (an array, a tuple
+   *  with a rest), or the ways multiply past what is worth listing. */
+  spreadTuples(written) {
+    const MAX = 32;
+    let variants = [[]];
+    for (const { spread, type } of written) {
+      if (!spread) {
+        variants = variants.map((v) => [...v, type]);
+        continue;
+      }
+      const options = this.fixedTuples(type);
+      if (!options) return void 0;
+      const next = [];
+      for (const v of variants) for (const option of options) next.push([...v, ...option]);
+      if (next.length > MAX) return void 0;
+      variants = next;
+    }
+    return variants;
+  }
+  /** A tuple of known length's members, or a union of such tuples' — each
+   *  a way the value can be. `nil` in a union spreads nothing. */
+  fixedTuples(t, depth = 0) {
+    if (depth > 8) return void 0;
+    const held = this.expand(t);
+    if (held.kind === "tuple") return held.rest ? void 0 : [held.elements];
+    if (held.kind !== "union") return void 0;
+    const out = [];
+    for (const member of held.types) {
+      if (member.kind === "primitive" && member.name === "nil") continue;
+      const options = this.fixedTuples(member, depth + 1);
+      if (!options) return void 0;
+      out.push(...options);
+    }
+    return out.length ? out : void 0;
+  }
+  /** What `...xs` puts into an array: an array's element, a tuple's members,
+   *  and for a union each member's — `...(host ? extra : [])` adds `extra`'s
+   *  elements and the empty tuple nothing. Anything else, `unknown`. */
+  spreadElements(t, depth = 0) {
+    const held = this.expand(t);
+    if (depth > 8) return [unknownType];
+    switch (held.kind) {
+      case "array":
+        return [held.element];
+      case "tuple":
+        return tupleMembers(held);
+      case "union":
+        return held.types.filter((m) => !(m.kind === "primitive" && m.name === "nil")).flatMap((m) => this.spreadElements(m, depth + 1));
+      case "typeParam":
+        return held.constraint ? this.spreadElements(held.constraint, depth + 1) : [unknownType];
+      case "any":
+        return [anyType];
+      default:
+        return [unknownType];
+    }
+  }
   /** `[a, b, ...more]` where a tuple is wanted: the places it names are the
    *  tuple's, and what comes after them — more elements, or a spread — is
    *  its rest. */
@@ -9909,10 +10371,7 @@ var TypeAnalyzer = class {
     expr.elements.forEach((element, i) => {
       if (element.type === "SpreadElement") {
         spread = true;
-        const held = this.expand(this.infer(element.argument, env));
-        if (held.kind === "array") tail.push(held.element);
-        else if (held.kind === "tuple") tail.push(...tupleMembers(held));
-        else tail.push(unknownType);
+        tail.push(...this.spreadElements(this.infer(element.argument, env)));
         return;
       }
       const t = this.widenUnlessAsked(this.infer(element, env), element);
@@ -9929,6 +10388,7 @@ var TypeAnalyzer = class {
    *  The context was recorded by `applyContext` before the value was
    *  inferred, so this is a lookup rather than a second pass. */
   widenUnlessAsked(value, at) {
+    if (!writesLiteral(at)) return value;
     const wanted = this.expectedTypeOf.get(at);
     if (value.kind === "literal") {
       const arms = this.contextArms.get(at);
@@ -10925,6 +11385,8 @@ function containsTypeQuery(node) {
   return found;
 }
 var STRING_INTRINSICS = /* @__PURE__ */ new Set(["Uppercase", "Lowercase", "Capitalize", "Uncapitalize"]);
+var OBJECT_INTRINSICS = /* @__PURE__ */ new Set(["ObjectKeys", "ObjectValues", "ObjectEntries"]);
+var INTRINSICS = /* @__PURE__ */ new Set([...STRING_INTRINSICS, ...OBJECT_INTRINSICS]);
 function briefType(t) {
   if (t.kind === "union" && t.types.length > 8) {
     const shown = t.types.slice(0, 6).map(formatType).join(" | ");
@@ -11132,7 +11594,8 @@ function resolveTypeLibraries(config, host = nodeHost) {
     }
     addFile(entryFile);
     const lowering = loweringModule(directory, host, problems, config);
-    if (lowering) lowerings.push(lowering);
+    const library = files.findIndex((file) => pathKey(file) === pathKey(entryFile));
+    if (lowering) lowerings.push({ ...lowering, library });
   };
   for (const entry of config.types) {
     const relative = entry.startsWith("./") || entry.startsWith("../") || entry.startsWith("/") || /^[A-Za-z]:[\\/]/.test(entry);