@tilua/parser 2.3.0 → 3.0.0

package/dist/index.cjs

@@ -734,7 +734,8 @@ var DECLARATION_STATEMENTS = /* @__PURE__ */ new Set([
   "ExportNamedStatement",
   "ExportAllStatement",
   "DeclareStatement",
-  "DeclareClassStatement"
+  "DeclareClassStatement",
+  "DeclareMetatableStatement"
 ]);
 function spanFrom(start, end) {
   return {
@@ -1352,6 +1353,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();
       }
@@ -1404,6 +1408,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();
@@ -2112,7 +2127,15 @@ var Parser = class {
   parseExpressionStatement() {
     const start = this.current();
     if (this.checkPunctuator("{") || this.checkPunctuator("[")) {
-      const target = this.checkPunctuator("{") ? this.parseObjectPattern() : this.parseArrayPattern();
+      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);
     }
     const statementStart = this.cursor;
@@ -2433,11 +2456,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("<")) {
@@ -2514,6 +2535,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);
@@ -2667,8 +2693,8 @@ var Parser = class {
   /** An assignment target after the first — Luau's `a, b = ...`, read only
    *  to be reported: a prefix expression or a destructuring pattern. */
   parseAssignTarget() {
-    if (this.checkPunctuator("{")) return this.parseObjectPattern();
-    if (this.checkPunctuator("[")) return this.parseArrayPattern();
+    if (this.checkPunctuator("{")) return this.parseObjectPattern(true);
+    if (this.checkPunctuator("[")) return this.parseArrayPattern(true);
     return this.parsePrefixExpression();
   }
   /** Does a call's argument list start here? Lua's three forms: `(`, a
@@ -2847,13 +2873,17 @@ var Parser = class {
   /** Parses a binding target. When `topLevel`, also consumes a trailing
    *  `<attr>` list (identifier only) and a `: Type` annotation — these are
    *  only valid at the outermost level of a `local` / parameter binding,
-   *  never nested inside another pattern. */
-  parseBindingTarget(topLevel) {
+   *  never nested inside another pattern. When `assign`, the pattern is a
+   *  destructuring assignment's (`[t[i], t[j]] = ...`), and a leaf is any
+   *  place a value can be assigned to: a name, a member or an index. */
+  parseBindingTarget(topLevel, assign = false) {
     let target;
     if (this.checkPunctuator("{")) {
-      target = this.parseObjectPattern();
+      target = this.parseObjectPattern(assign);
     } else if (this.checkPunctuator("[")) {
-      target = this.parseArrayPattern();
+      target = this.parseArrayPattern(assign);
+    } else if (assign) {
+      return this.parseAssignPatternLeaf();
     } else {
       const nameTok = this.expectIdentifier();
       let attributes;
@@ -2875,10 +2905,25 @@ var Parser = class {
     }
     return target;
   }
-  parseObjectPattern() {
-    return this.inBrackets(() => this.parseObjectPatternInner());
+  /** A leaf of a destructuring assignment: `a`, `a.b` or `a[i]`. */
+  parseAssignPatternLeaf() {
+    const expression = this.parsePrefixExpression();
+    if (expression.type === "Identifier") {
+      return { type: "IdentifierPattern", name: expression.name, line: expression.line, column: expression.column };
+    }
+    if (expression.type === "MemberExpression" || expression.type === "IndexExpression") {
+      this.rejectOptionalTarget(expression);
+      return expression;
+    }
+    const err = new ParseError("Only a name, a member or an index can be assigned to", expression.line.start, expression.column.start);
+    if (!this.recover) throw err;
+    this.record(err);
+    return { type: "IdentifierPattern", name: "", line: expression.line, column: expression.column };
+  }
+  parseObjectPattern(assign = false) {
+    return this.inBrackets(() => this.parseObjectPatternInner(assign));
   }
-  parseObjectPatternInner() {
+  parseObjectPatternInner(assign) {
     const start = this.current();
     this.expectPunctuator("{");
     const properties = [];
@@ -2886,7 +2931,7 @@ var Parser = class {
     while (!this.checkPunctuator("}")) {
       if (this.checkOperator("...")) {
         this.advance();
-        rest = this.parseBindingTarget(false);
+        rest = this.parseBindingTarget(false, assign);
         break;
       }
       const propStart = this.current();
@@ -2899,17 +2944,17 @@ var Parser = class {
         key = this.parseExpression();
         this.expectPunctuator("]");
         this.expectPunctuator(":");
-        value = this.parseBindingTarget(false);
+        value = this.parseBindingTarget(false, assign);
       } else if (this.checkType("Literal") && this.current().kind === "string") {
         const t = this.advance();
         key = { type: "StringLiteral", value: t.value, raw: t.raw, ...spanFrom(t, t) };
         this.expectPunctuator(":");
-        value = this.parseBindingTarget(false);
+        value = this.parseBindingTarget(false, assign);
       } else {
         const nameTok = this.expectIdentifier();
         key = { type: "Identifier", name: nameTok.value, ...spanFrom(nameTok, nameTok) };
         if (this.matchPunctuator(":")) {
-          value = this.parseBindingTarget(false);
+          value = this.parseBindingTarget(false, assign);
         } else {
           shorthand = true;
           value = { type: "IdentifierPattern", name: nameTok.value, ...spanFrom(nameTok, nameTok) };
@@ -2932,10 +2977,10 @@ var Parser = class {
     this.expectPunctuator("}");
     return { type: "ObjectPattern", properties, rest, ...spanFrom(start, this.previous()) };
   }
-  parseArrayPattern() {
-    return this.inBrackets(() => this.parseArrayPatternInner());
+  parseArrayPattern(assign = false) {
+    return this.inBrackets(() => this.parseArrayPatternInner(assign));
   }
-  parseArrayPatternInner() {
+  parseArrayPatternInner(assign) {
     const start = this.current();
     this.expectPunctuator("[");
     const elements = [];
@@ -2943,7 +2988,7 @@ var Parser = class {
     while (!this.checkPunctuator("]")) {
       if (this.checkOperator("...")) {
         this.advance();
-        rest = this.parseBindingTarget(false);
+        rest = this.parseBindingTarget(false, assign);
         break;
       }
       if (this.checkPunctuator(",")) {
@@ -2952,7 +2997,7 @@ var Parser = class {
         continue;
       }
       const elStart = this.current();
-      const value = this.parseBindingTarget(false);
+      const value = this.parseBindingTarget(false, assign);
       let def;
       if (this.matchOperator("=")) def = this.parseExpression();
       elements.push({ type: "ArrayPatternElement", value, default: def, ...spanFrom(elStart, this.previous()) });
@@ -4089,6 +4134,10 @@ var Analyzer = class {
           this.checkConstAssign(id, t);
           return;
         }
+        case "MemberExpression":
+        case "IndexExpression":
+          this.visitExpression(t, scope);
+          return;
         case "ObjectPattern":
           for (const p of t.properties) {
             if (p.computed) this.visitExpression(p.key, scope);
@@ -4124,7 +4173,9 @@ var Analyzer = class {
     switch (stmt.type) {
       case "VariableDeclaration": {
         if (stmt.init) this.visitExpression(stmt.init, scope);
-        this.visitType(stmt.name.typeAnnotation, scope);
+        if (stmt.name.type !== "MemberExpression" && stmt.name.type !== "IndexExpression") {
+          this.visitType(stmt.name.typeAnnotation, scope);
+        }
         this.declarePattern(scope, stmt.name, "local", scope, stmt.kind === "const");
         return;
       }
@@ -4239,6 +4290,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(
@@ -4504,6 +4560,101 @@ 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.
+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: (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() {
@@ -5869,6 +6020,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();
@@ -5935,6 +6090,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);
@@ -5966,6 +6124,8 @@ var TypeAnalyzer = class {
       expectedTypeOf: this.expectedTypeOf,
       aliases: this.resolveDeferredAliases(),
       loops: this.loops,
+      methodSources: this.methodSources,
+      metatableMembers: (type) => this.metatableMembers(type),
       diagnostics: this.diagnostics
     };
   }
@@ -6023,8 +6183,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) {
@@ -6541,6 +6700,14 @@ var TypeAnalyzer = class {
         report(stmt.superclass, known ? `'${stmt.superclass.name}' is not a class; a class can only extend another class` : `Cannot find class '${stmt.superclass.name}'`);
       }
     }
+    this.withClass(stmt, () => this.withTypeParams(this.classTypeParams(stmt), () => {
+      this.withSelfType(this.selfTypeOf(stmt), () => {
+        for (const member of stmt.members) {
+          if (member.type !== "ClassMethod" || !member.signatures) continue;
+          for (const signature of member.signatures) this.checkOverload(member.func, signature);
+        }
+      });
+    }));
     for (const member of stmt.members) {
       if (member.type === "ClassConstructor") continue;
       if (CLASS_RESERVED.has(member.name.name)) {
@@ -6934,7 +7101,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)) {
@@ -7052,7 +7219,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])
             );
@@ -7259,7 +7426,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);
@@ -7372,6 +7539,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. */
@@ -8047,7 +8249,7 @@ var TypeAnalyzer = class {
   /** Synthesize a type from a destructuring pattern used without an
    *  annotation (`function f({ a, b = 1 })`). */
   patternToType(target, env) {
-    const leaf = (v, def) => v.type !== "IdentifierPattern" ? this.patternToType(v, env) : v.typeAnnotation ? this.resolveType(v.typeAnnotation) : def ? widen(this.infer(def, env)) : anyType;
+    const leaf = (v, def) => v.type === "ObjectPattern" || v.type === "ArrayPattern" ? this.patternToType(v, env) : v.type !== "IdentifierPattern" ? anyType : v.typeAnnotation ? this.resolveType(v.typeAnnotation) : def ? widen(this.infer(def, env)) : anyType;
     if (target.type === "ObjectPattern") {
       const entries = [];
       for (const p of target.properties) {
@@ -8453,6 +8655,7 @@ var TypeAnalyzer = class {
    *  can actually be. An annotation, a pattern or a default still wins. */
   paramsFromSignatures(func, signatures) {
     if (!signatures?.length) return;
+    for (const signature of signatures) this.checkOverload(func, signature);
     const resolved = signatures.map((sig) => this.signatureToFnType(sig));
     func.params.forEach((param, i) => {
       if (param.typeAnnotation || param.pattern || param.default) return;
@@ -8466,6 +8669,64 @@ var TypeAnalyzer = class {
       if (candidates.length) this.contextualParams.set(param, union(candidates));
     });
   }
+  /** The implementation is what runs for every signature of an overload
+   *  set, so each signature must be one it can serve: no parameter it does
+   *  not have, no fewer arguments than it requires, no argument type it does
+   *  not accept, and a return it can give. Stricter than TypeScript, which
+   *  lets a signature name parameters the implementation never reads. */
+  checkOverload(func, signature) {
+    if (!this.emitDiagnostics) return;
+    const node = signature;
+    const report = (message) => {
+      this.diagnostics.push({ node, message });
+    };
+    const own = (params) => params.filter((p, i) => !p.rest && !(i === 0 && !p.typeAnnotation && (p.name === "self" || p.name === "this")));
+    const implementation = own(func.params);
+    const offered = own(signature.params);
+    const implementationRest = func.params.some((p) => p.rest);
+    const signatureRest = signature.params.some((p) => p.rest);
+    const label = (p) => p.pattern ? "a destructured parameter" : `'${p.name}'`;
+    if (!implementationRest) {
+      const extra = offered[implementation.length];
+      if (extra) {
+        report(`This overload takes parameter ${label(extra)}, which the implementation does not have: it takes ${implementation.length} parameter${implementation.length === 1 ? "" : "s"}`);
+        return;
+      }
+      if (signatureRest) {
+        report("This overload takes a rest parameter, which the implementation does not have");
+        return;
+      }
+    }
+    if (!signatureRest) {
+      let required = 0;
+      implementation.forEach((p, i) => {
+        if (!p.optional && p.default === void 0) required = i + 1;
+      });
+      if (offered.length < required) {
+        report(`The implementation requires ${required} argument${required === 1 ? "" : "s"}, and this overload passes at most ${offered.length}`);
+        return;
+      }
+    }
+    if (signature.generics.length || func.generics.length) return;
+    for (let i = 0; i < offered.length && i < implementation.length; i++) {
+      const target = implementation[i];
+      if (!target.typeAnnotation && target.default === void 0) continue;
+      let accepted = this.paramType(target, /* @__PURE__ */ new Map());
+      if (target.default !== void 0) accepted = optional(accepted);
+      const given = this.paramType(offered[i], /* @__PURE__ */ new Map());
+      if (!isAssignable(given, accepted)) {
+        report(`Parameter ${label(offered[i])} of this overload is '${briefType(given)}', which the implementation's '${briefType(accepted)}' does not accept`);
+        return;
+      }
+    }
+    if (signature.returnType && func.returnType) {
+      const promised = this.resolveType(signature.returnType);
+      const returned = this.resolveType(func.returnType);
+      if (!isAssignable(promised, returned) && !isAssignable(returned, promised)) {
+        report(`This overload returns '${briefType(promised)}', which the implementation's '${briefType(returned)}' cannot be`);
+      }
+    }
+  }
   signatureToFnType(sig) {
     const names = sig.generics.map((g) => g.name);
     const record = (type) => {
@@ -8890,6 +9151,12 @@ var TypeAnalyzer = class {
         }
         return;
       }
+      case "MemberExpression":
+      case "IndexExpression":
+        this.infer(target, env);
+        this.checkReadonlyAssign(target, env);
+        this.assignToRef(target, widen(valueType), env);
+        return;
       case "ObjectPattern": {
         for (const p of target.properties) {
           const key = !p.computed && p.key.type === "Identifier" ? p.key.name : !p.computed && p.key.type === "StringLiteral" ? p.key.value : void 0;
@@ -8988,28 +9255,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
@@ -9075,7 +9436,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
@@ -9096,13 +9457,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`
@@ -9134,24 +9495,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;
@@ -9286,10 +9647,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)));
     }
@@ -9690,7 +10051,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);
@@ -10932,6 +11295,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(" | ");
@@ -11139,7 +11504,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);