@tilua/parser 2.2.0 → 2.4.0

package/dist/index.cjs

@@ -969,10 +969,10 @@ var Parser = class {
   expressionOr(stop) {
     return this.attempt(() => this.parseExpression(), stop, (start, from) => this.errorExpression(start, from));
   }
-  /** A comma-separated list of values: a `return`'s, a declaration's, an
-   *  assignment's. Each is one value; a spread belongs in a call's
-   *  arguments or an array, and is reported here — then read as one, so
-   *  the rest still means something. */
+  /** A comma-separated list of values where one belongs — a `return`'s, a
+   *  declaration's, an assignment's — read whole, so that writing several
+   *  is reported once and the rest still means something. A spread belongs
+   *  in a call's arguments or an array, and is reported here too. */
   expressionListOr(stop) {
     const until = () => stop() || this.checkPunctuator(",");
     const item = () => {
@@ -1564,7 +1564,7 @@ var Parser = class {
     }
     this.error("Expected 'const', 'let', 'function', 'class', 'type', 'default', '{' or '*' after 'export'");
   }
-  // `const x = ...` / `let x, y = ...`.
+  // `const x = ...` / `let [a, b] = ...`.
   // tilua has no `local` — `const` bindings are immutable, `let` mutable.
   /** `kind` reads the leading word as that keyword (recovery's `local`). */
   parseVariableDeclaration(as) {
@@ -1578,14 +1578,34 @@ var Parser = class {
     while (this.matchPunctuator(",")) {
       names.push(this.parseBindingTarget(true));
     }
-    let init = [];
+    let values = [];
     if (this.matchOperator("=")) {
-      init = this.expressionListOr(() => false);
+      values = this.expressionListOr(() => false);
     } else if (kind === "const") {
       if (!this.recover) this.error("'const' declaration requires an initializer");
       this.softError("'const' declaration requires an initializer");
     }
-    return { type: "VariableDeclaration", kind, names, init, ...spanFrom(start, this.previous()) };
+    let name = names[0];
+    let init = values[0];
+    if (names.length > 1 || values.length > 1) {
+      this.problemAt(start, `A declaration takes one value: take several from an array, '${kind} [a, b] = [x, y]'`);
+      if (names.length > 1) name = this.namesAsPattern(names);
+      if (values.length > 1) init = this.valuesAsArray(values);
+    }
+    return { type: "VariableDeclaration", kind, name, init, ...spanFrom(start, this.previous()) };
+  }
+  /** `a, b` written where one name goes, read as `[a, b]`. */
+  namesAsPattern(names) {
+    const elements = names.map((value) => ({
+      type: "ArrayPatternElement",
+      value,
+      ...spanFrom(value, value)
+    }));
+    return { type: "ArrayPattern", elements, ...spanFrom(names[0], names[names.length - 1]) };
+  }
+  /** `x, y` written where one value goes, read as `[x, y]`. */
+  valuesAsArray(values) {
+    return { type: "ArrayExpression", elements: values, ...spanFrom(values[0], values[values.length - 1]) };
   }
   parseIfStatement() {
     const start = this.current();
@@ -2066,7 +2086,7 @@ var Parser = class {
       argument = values[0];
       if (values.length > 1) {
         this.problemAt(start, "A function returns one value: return several as an array, 'return [a, b]'");
-        argument = { type: "ArrayExpression", elements: values, ...spanFrom(values[0], values[values.length - 1]) };
+        argument = this.valuesAsArray(values);
       }
     }
     return { type: "ReturnStatement", argument, ...spanFrom(start, this.previous()) };
@@ -2092,28 +2112,15 @@ var Parser = class {
   parseExpressionStatement() {
     const start = this.current();
     if (this.checkPunctuator("{") || this.checkPunctuator("[")) {
-      const targets = [
-        this.checkPunctuator("{") ? this.parseObjectPattern() : this.parseArrayPattern()
-      ];
-      while (this.matchPunctuator(",")) {
-        targets.push(this.parseAssignTarget());
-      }
-      this.expectOperator("=");
-      const values = this.expressionListOr(() => false);
-      return { type: "AssignmentStatement", targets, values, ...spanFrom(start, this.previous()) };
+      const target = this.checkPunctuator("{") ? this.parseObjectPattern(true) : this.parseArrayPattern(true);
+      return this.parseAssignmentRest(start, target);
     }
     const statementStart = this.cursor;
     const errorsAtStart = this.errors.length;
     const first = this.parsePrefixExpression();
     if (this.checkOperator("=") || this.checkPunctuator(",")) {
-      const targets = [first];
-      while (this.matchPunctuator(",")) {
-        targets.push(this.parseAssignTarget());
-      }
-      for (const target of targets) this.rejectOptionalTarget(target);
-      this.expectOperator("=");
-      const values = this.expressionListOr(() => false);
-      return { type: "AssignmentStatement", targets, values, ...spanFrom(start, this.previous()) };
+      this.rejectOptionalTarget(first);
+      return this.parseAssignmentRest(start, first);
     }
     const t = this.current();
     if (t.type === "Operator" && COMPOUND_ASSIGN_OPS.has(t.value)) {
@@ -2139,6 +2146,21 @@ var Parser = class {
     }
     return { type: "ExpressionStatement", expression, ...spanFrom(start, this.previous()) };
   }
+  /** From after an assignment's target: `= value`. Luau's `a, b = x, y`
+   *  is reported, and read as its first target taking its first value. */
+  parseAssignmentRest(start, target) {
+    let several = false;
+    while (this.matchPunctuator(",")) {
+      this.parseAssignTarget();
+      several = true;
+    }
+    this.expectOperator("=");
+    const values = this.expressionListOr(() => false);
+    if (several || values.length > 1) {
+      this.problemAt(start, "An assignment takes one value: take several from an array, '[a, b] = [x, y]'");
+    }
+    return { type: "AssignmentStatement", target, value: values[0], ...spanFrom(start, this.previous()) };
+  }
   // ============================================================
   // Expressions
   // ============================================================
@@ -2622,8 +2644,8 @@ var Parser = class {
   startsSuperUse() {
     return this.punctuatorAt(1, "(") || this.punctuatorAt(1, ".") && this.peek(2).type === "Identifier";
   }
-  /** After `...`, is there something to spread? Nothing following it means
-   *  the vararg pack, which is what `f(...)` has always passed on. */
+  /** After `...`, is there something to spread? tilua has no bare `...`:
+   *  a varying number of arguments is a rest parameter, `...args: T[]`. */
   startsSpread() {
     const next = this.peek(1);
     if (next.type === "Punctuator") {
@@ -2642,11 +2664,11 @@ var Parser = class {
     const token = this.peek(ahead);
     return token.type === "Punctuator" && token.value === value;
   }
-  /** An assignment target after the first: a prefix expression (`a.b`,
-   *  `a[i]`, `a`) or a nested destructuring pattern. */
+  /** 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
@@ -2825,13 +2847,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;
@@ -2853,10 +2879,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 = [];
@@ -2864,7 +2905,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();
@@ -2877,17 +2918,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) };
@@ -2910,10 +2951,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 = [];
@@ -2921,7 +2962,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(",")) {
@@ -2930,7 +2971,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()) });
@@ -3134,7 +3175,7 @@ var Parser = class {
       };
     })() : this.parseFunctionHead();
     this.expectPunctuator("=>");
-    const body = this.checkPunctuator("{") ? this.parseBraceBlock() : this.returnOf(this.parseExpression(0));
+    const body = this.checkPunctuator("{") ? this.parseBraceBlock() : this.parseArrowExpressionBody();
     const func = {
       type: "FunctionBody",
       generics: head.generics,
@@ -3147,6 +3188,29 @@ var Parser = class {
     };
     return { type: "FunctionExpression", func, ...spanFrom(start, this.previous()) };
   }
+  /** `() => value` returns the value. `() => a = 1` and `() => n += 1` are
+   *  an assignment, which is a statement: the body is that
+   *  statement, and the function returns nothing. */
+  parseArrowExpressionBody() {
+    const start = this.cursor;
+    const errors = this.errors.length;
+    const expression = this.parseExpression(0);
+    const t = this.current();
+    const assigns = t.type === "Operator" && (t.value === "=" || COMPOUND_ASSIGN_OPS.has(t.value));
+    if (!assigns) return this.returnOf(expression);
+    this.cursor = start;
+    this.errors.length = errors;
+    const first = this.current();
+    const target = this.parsePrefixExpression();
+    this.rejectOptionalTarget(target);
+    const opToken = this.current();
+    const op = opToken.value;
+    if (opToken.type !== "Operator" || op !== "=" && !COMPOUND_ASSIGN_OPS.has(op)) this.error("Expected '='");
+    this.advance();
+    const value = this.expressionOr(() => false);
+    const statement = op === "=" ? { type: "AssignmentStatement", target, value, ...spanFrom(first, this.previous()) } : { type: "CompoundAssignmentStatement", operator: op, target, value, ...spanFrom(first, this.previous()) };
+    return { type: "Block", statements: [statement], ...spanFrom(statement, statement) };
+  }
   /** A one-expression body: the value is what the function returns. */
   returnOf(expression) {
     const statement = {
@@ -4044,6 +4108,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);
@@ -4078,10 +4146,11 @@ var Analyzer = class {
   visitStatement(stmt, scope) {
     switch (stmt.type) {
       case "VariableDeclaration": {
-        for (const init of stmt.init) this.visitExpression(init, scope);
-        for (const name of stmt.names) this.visitType(name.typeAnnotation, scope);
-        const isConst = stmt.kind === "const";
-        for (const name of stmt.names) this.declarePattern(scope, name, "local", scope, isConst);
+        if (stmt.init) this.visitExpression(stmt.init, 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;
       }
       case "FunctionDeclaration": {
@@ -4115,16 +4184,15 @@ var Analyzer = class {
         return;
       }
       case "AssignmentStatement": {
-        for (const value of stmt.values) this.visitExpression(value, scope);
-        for (const target of stmt.targets) {
-          if (target.type === "Identifier") {
-            this.referenceAsAssignmentTarget(scope, target);
-          } else if (target.type === "ObjectPattern" || target.type === "ArrayPattern") {
-            this.assignPattern(scope, target);
-          } else {
-            this.visitExpression(target, scope);
-            this.checkModuleWrite(target);
-          }
+        this.visitExpression(stmt.value, scope);
+        const target = stmt.target;
+        if (target.type === "Identifier") {
+          this.referenceAsAssignmentTarget(scope, target);
+        } else if (target.type === "ObjectPattern" || target.type === "ArrayPattern") {
+          this.assignPattern(scope, target);
+        } else {
+          this.visitExpression(target, scope);
+          this.checkModuleWrite(target);
         }
         return;
       }
@@ -5448,7 +5516,7 @@ function moduleExports(program, scopes, types, resolveModule) {
             params: declaration.typeParams.map((g) => g.name)
           });
         }
-      } else for (const target of declaration.names) exportPattern(target);
+      } else exportPattern(declaration.name);
     } else if (stmt.type === "ExportTypeAliasStatement") {
       const name = stmt.alias.name.name;
       const type = types.aliases.get(name);
@@ -5687,12 +5755,10 @@ function assignedFields(block) {
   const names = /* @__PURE__ */ new Set();
   walkNodes(block, (node) => {
     const record = node;
-    const targets = record.type === "AssignmentStatement" ? record.targets : record.type === "CompoundAssignmentStatement" ? [record.target] : void 0;
-    for (const target of targets ?? []) {
-      const member = target;
-      if (member.type === "MemberExpression" && member.object?.type === "Identifier" && member.object.name === "this" && member.property?.name) {
-        names.add(member.property.name);
-      }
+    if (record.type !== "AssignmentStatement" && record.type !== "CompoundAssignmentStatement") return;
+    const member = record.target;
+    if (member.type === "MemberExpression" && member.object?.type === "Identifier" && member.object.name === "this" && member.property?.name) {
+      names.add(member.property.name);
     }
   });
   return names;
@@ -6168,12 +6234,10 @@ var TypeAnalyzer = class {
   classDisplayNames = /* @__PURE__ */ new WeakMap();
   /** `const Name = class ... end` — the name the class will be known by. */
   nameClassExpressions(stmt) {
-    stmt.names.forEach((target, i) => {
-      const value = stmt.init[i];
-      if (target.type === "IdentifierPattern" && value?.type === "ClassExpression" && !value.name) {
-        this.classDisplayNames.set(value, target.name);
-      }
-    });
+    const value = stmt.init;
+    if (stmt.name.type === "IdentifierPattern" && value?.type === "ClassExpression" && !value.name) {
+      this.classDisplayNames.set(value, stmt.name.name);
+    }
   }
   classTypeParams(stmt) {
     return stmt.type === "ClassDeclaration" ? stmt.typeParams : [];
@@ -6502,6 +6566,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)) {
@@ -7456,35 +7528,30 @@ var TypeAnalyzer = class {
     switch (stmt.type) {
       case "VariableDeclaration": {
         this.nameClassExpressions(stmt);
-        stmt.names.forEach((target, i) => {
-          if (target.type === "IdentifierPattern" && target.typeAnnotation && stmt.init[i]) {
-            this.applyContext(stmt.init[i], this.resolveType(target.typeAnnotation));
-          }
-        });
-        const { types: valueTypes, sources } = this.valueList(stmt.init, env);
-        this.checkValueCount(stmt, stmt.names.length, stmt.init, valueTypes);
-        stmt.names.forEach((target, i) => {
-          const inferred = valueTypes[i] ?? (stmt.init.length ? unknownType : nilType);
-          const source = sources[i];
-          if (this.emitDiagnostics && target.type === "IdentifierPattern" && target.typeAnnotation && source) {
-            const declared = this.resolveType(target.typeAnnotation);
-            if (declared.kind !== "any" && !this.namesNothing(declared) && !this.fitsAnnotation(source, declared, inferred, env)) {
-              this.diagnostics.push({
-                node: stmt,
-                message: `Type '${briefType(inferred)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(inferred, declared)
-              });
-            } else if (declared.kind !== "any") {
-              this.reportExcessProperties(source, declared);
-            }
-          }
-          const mode = this.initIsAsConst(source) ? "asconst" : !isFreshLiteralExpr(source) ? "keep" : stmt.kind === "const" ? "const" : "widen";
-          this.bindPattern(target, inferred, env, mode);
-          if (stmt.kind === "const") {
-            this.correlateDestructuring(target, inferred, env);
-            this.correlateIndexed(target, source, env);
-            this.aliasReference(target, source);
+        const target = stmt.name;
+        const source = stmt.init;
+        if (target.type === "IdentifierPattern" && target.typeAnnotation && source) {
+          this.applyContext(source, this.resolveType(target.typeAnnotation));
+        }
+        const inferred = source ? this.infer(source, env) : nilType;
+        if (this.emitDiagnostics && target.type === "IdentifierPattern" && target.typeAnnotation && source) {
+          const declared = this.resolveType(target.typeAnnotation);
+          if (declared.kind !== "any" && !this.namesNothing(declared) && !this.fitsAnnotation(source, declared, inferred, env)) {
+            this.diagnostics.push({
+              node: stmt,
+              message: `Type '${briefType(inferred)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(inferred, declared)
+            });
+          } else if (declared.kind !== "any") {
+            this.reportExcessProperties(source, declared);
           }
-        });
+        }
+        const mode = this.initIsAsConst(source) ? "asconst" : !isFreshLiteralExpr(source) ? "keep" : stmt.kind === "const" ? "const" : "widen";
+        this.bindPattern(target, inferred, env, mode);
+        if (stmt.kind === "const") {
+          this.correlateDestructuring(target, inferred, env);
+          this.correlateIndexed(target, source, env);
+          this.aliasReference(target, source);
+        }
         return;
       }
       case "ClassDeclaration": {
@@ -7541,48 +7608,41 @@ var TypeAnalyzer = class {
         return;
       }
       case "AssignmentStatement": {
-        stmt.targets.forEach((target, i) => {
-          const value = stmt.values[i];
-          if (!value) return;
-          if (target.type === "MemberExpression" || target.type === "IndexExpression") {
-            this.applyContext(value, this.infer(target, env));
-          } else if (target.type === "Identifier") {
-            const id = this.bindingIdOf(target);
-            if (id !== void 0 && this.annotated.has(id)) this.applyContext(value, this.bindingType.get(id));
-          }
-        });
-        const { types: valueTypes, sources } = this.valueList(stmt.values, env);
-        this.checkValueCount(stmt, stmt.targets.length, stmt.values, valueTypes);
-        stmt.targets.forEach((target, i) => {
-          const vt = valueTypes[i] ?? unknownType;
-          const source = sources[i];
-          if (target.type === "Identifier") {
-            const id = this.bindingIdOf(target);
-            if (id !== void 0) {
-              this.uncorrelate(id);
-              const next = isFreshLiteralExpr(source) ? widen(vt) : vt;
-              if (this.annotated.has(id)) {
-                const declared = this.bindingType.get(id);
-                if (this.emitDiagnostics && !isAssignable(next, declared) && declared.kind !== "any") {
-                  this.diagnostics.push({
-                    node: stmt,
-                    message: `Type '${briefType(next)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(next, declared)
-                  });
-                }
-                this.setBinding(env, id, narrowTo(declared, next));
-              } else {
-                this.setBinding(env, id, next);
-                this.bindingType.set(id, union([this.bindingType.get(id) ?? next, next]));
+        const target = stmt.target;
+        const source = stmt.value;
+        if (target.type === "MemberExpression" || target.type === "IndexExpression") {
+          this.applyContext(source, this.infer(target, env));
+        } else if (target.type === "Identifier") {
+          const id = this.bindingIdOf(target);
+          if (id !== void 0 && this.annotated.has(id)) this.applyContext(source, this.bindingType.get(id));
+        }
+        const vt = this.infer(source, env);
+        if (target.type === "Identifier") {
+          const id = this.bindingIdOf(target);
+          if (id !== void 0) {
+            this.uncorrelate(id);
+            const next = isFreshLiteralExpr(source) ? widen(vt) : vt;
+            if (this.annotated.has(id)) {
+              const declared = this.bindingType.get(id);
+              if (this.emitDiagnostics && !isAssignable(next, declared) && declared.kind !== "any") {
+                this.diagnostics.push({
+                  node: stmt,
+                  message: `Type '${briefType(next)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(next, declared)
+                });
               }
+              this.setBinding(env, id, narrowTo(declared, next));
+            } else {
+              this.setBinding(env, id, next);
+              this.bindingType.set(id, union([this.bindingType.get(id) ?? next, next]));
             }
-          } else if (target.type === "MemberExpression" || target.type === "IndexExpression") {
-            this.infer(target, env);
-            this.checkReadonlyAssign(target, env);
-            this.assignToRef(target, isFreshLiteralExpr(source) ? widen(vt) : vt, env);
-          } else if (target.type === "ObjectPattern" || target.type === "ArrayPattern") {
-            this.reassignPattern(target, vt, env);
           }
-        });
+        } else if (target.type === "MemberExpression" || target.type === "IndexExpression") {
+          this.infer(target, env);
+          this.checkReadonlyAssign(target, env);
+          this.assignToRef(target, isFreshLiteralExpr(source) ? widen(vt) : vt, env);
+        } else if (target.type === "ObjectPattern" || target.type === "ArrayPattern") {
+          this.reassignPattern(target, vt, env);
+        }
         return;
       }
       case "CompoundAssignmentStatement":
@@ -7746,55 +7806,6 @@ var TypeAnalyzer = class {
         return;
     }
   }
-  /** Flatten an expression list into the values it actually produces.
-   *
-   *  Lua's adjustment rule: every expression but the last contributes one
-   *  value, and the last contributes all of its values if it is a call or
-   *  `...`. That is what makes `local ok, err = pcall(f)` work, and it is
-   *  why `local x = f()` takes only the first value.
-   *
-   *  `sources` maps each produced value back to the expression it came from
-   *  (undefined for the 2nd and later values of a multi-value call), so the
-   *  caller can still do contextual typing against the written expression. */
-  valueList(exprs, env) {
-    const types = [];
-    const sources = [];
-    exprs.forEach((e, i) => {
-      const t = this.infer(e, env);
-      const last = i === exprs.length - 1;
-      if (e.type === "SpreadElement") {
-        const held = this.typeOf.get(e.argument);
-        const expanded = held && this.expand(held);
-        if (expanded?.kind === "tuple") {
-          for (const element of expanded.elements) {
-            types.push(element);
-            sources.push(e);
-          }
-          return;
-        }
-        types.push(t);
-        sources.push(e);
-        return;
-      }
-      void last;
-      types.push(t);
-      sources.push(e);
-    });
-    return { types, sources };
-  }
-  /** `const a, b = x, y` pairs names with values, one each. A call is one
-   *  value — several come back as an array — so `const a, b = f()` is a
-   *  name short of a value, and says how to take them apart. */
-  checkValueCount(node, names, values, types) {
-    if (!this.emitDiagnostics || !values.length || types.length >= names) return;
-    const last = values[values.length - 1];
-    const lastType = types[types.length - 1] && this.expand(types[types.length - 1]);
-    const call = last.type === "CallExpression" || last.type === "MethodCallExpression";
-    this.diagnostics.push({
-      node,
-      message: call && (lastType?.kind === "tuple" || lastType?.kind === "array") ? `A call is one value, here an array: take its parts with '[${Array.from({ length: names }, (_, i) => String.fromCharCode(97 + i)).join(", ")}] = ...'` : `${names} names, but ${types.length} ${types.length === 1 ? "value" : "values"}: each name needs one`
-    });
-  }
   /** Run `visit` with a fresh place to collect `break` states, and return
    *  what it collected. */
   withBreakScope(visit) {
@@ -8069,7 +8080,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) {
@@ -8475,6 +8486,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;
@@ -8488,6 +8500,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) => {
@@ -8912,6 +8982,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;
@@ -9778,7 +9854,35 @@ var TypeAnalyzer = class {
     }
     const read = this.expand(type);
     if (read.kind === "unknown" && read.declared) this.reportUnknownAccess(object);
-    return { type, shortCircuits: inChain !== void 0 || link.optional === true };
+    const optionalNil = link.optional === true && this.mayBeNil(inChain ?? full);
+    return { type, shortCircuits: inChain !== void 0 || optionalNil };
+  }
+  /** Whether a value of `raw` can be nil — `includesNil`, and also the types
+   *  that do not say: `any`, `unknown`, an unconstrained type parameter. */
+  mayBeNil(raw) {
+    const t = this.expand(raw);
+    switch (t.kind) {
+      case "primitive":
+        return t.name === "nil";
+      case "any":
+      case "unknown":
+        return true;
+      case "typeParam":
+        return t.constraint === void 0 || this.mayBeNil(t.constraint);
+      case "union":
+        return t.types.some((m) => this.mayBeNil(m));
+      case "never":
+      case "literal":
+      case "array":
+      case "tuple":
+      case "object":
+      case "function":
+      case "intersection":
+      case "templateLiteral":
+        return false;
+      default:
+        return true;
+    }
   }
   /** Objects already reported as possibly nil: a loop body is visited more
    *  than once. */
@@ -10700,13 +10804,12 @@ var TypeAnalyzer = class {
   computingAhead = /* @__PURE__ */ new Set();
   declaredAhead(id) {
     this.aheadDeclarations ??= this.indexAheadDeclarations();
-    const found = this.aheadDeclarations.get(id);
-    if (!found || this.computingAhead.has(id)) return void 0;
+    const statement = this.aheadDeclarations.get(id);
+    if (!statement || this.computingAhead.has(id)) return void 0;
     this.computingAhead.add(id);
     const wasEmitting = this.emitDiagnostics;
     this.emitDiagnostics = false;
     try {
-      const { statement, index } = found;
       let type;
       if (statement.type === "DeclareStatement") {
         type = this.resolveType(statement.valueType);
@@ -10715,11 +10818,11 @@ var TypeAnalyzer = class {
       } else if (statement.type === "ClassDeclaration") {
         type = this.classValueType(statement);
       } else if (statement.type === "VariableDeclaration") {
-        const target = statement.names[index];
+        const target = statement.name;
         if (target.type === "IdentifierPattern" && target.typeAnnotation) {
           type = this.resolveType(target.typeAnnotation);
-        } else if (statement.init[index]) {
-          const value = this.infer(statement.init[index], /* @__PURE__ */ new Map());
+        } else if (statement.init) {
+          const value = this.infer(statement.init, /* @__PURE__ */ new Map());
           type = statement.kind === "const" ? value : widen(value);
         }
       }
@@ -10737,11 +10840,10 @@ var TypeAnalyzer = class {
     for (const statement of this.program.body.statements) {
       const declaration = statement.type === "ExportStatement" ? statement.declaration : statement;
       if (declaration.type !== "VariableDeclaration") continue;
-      declaration.names.forEach((target, index) => {
-        if (target.type !== "IdentifierPattern") return;
-        const id = this.bindingIdByName(target.name, target);
-        if (id !== void 0) out.set(id, { statement: declaration, index });
-      });
+      const target = declaration.name;
+      if (target.type !== "IdentifierPattern") continue;
+      const id = this.bindingIdByName(target.name, target);
+      if (id !== void 0) out.set(id, declaration);
     }
     const visit = (node) => {
       if (!node || typeof node !== "object") return;
@@ -10752,11 +10854,11 @@ var TypeAnalyzer = class {
       const record = node;
       if (record.type === "ClassDeclaration" && record.name) {
         const id = this.bindingIdByName(record.name.name, record.name);
-        if (id !== void 0) out.set(id, { statement: node, index: 0 });
+        if (id !== void 0) out.set(id, node);
       }
       if (record.type === "FunctionDeclaration" && record.name) {
         const id = this.bindingIdByName(record.name.name, record.name);
-        if (id !== void 0) out.set(id, { statement: node, index: 0 });
+        if (id !== void 0) out.set(id, node);
       }
       for (const [key, value] of Object.entries(node)) {
         if (key !== "line" && key !== "column" && value && typeof value === "object") visit(value);
@@ -10765,7 +10867,7 @@ var TypeAnalyzer = class {
     visit(this.program.body);
     for (const [name, statement] of this.deferredDeclares) {
       const id = this.scopes.globalsByName.get(name);
-      if (id !== void 0) out.set(id, { statement, index: 0 });
+      if (id !== void 0) out.set(id, statement);
     }
     return out;
   }