@tilua/parser 2.2.0 → 2.3.0

package/README.md

@@ -593,9 +593,17 @@ An array is a table, at runtime as much as in the types: `return [a, b]` is
 a Roblox method such as `FindPartOnRay` — the type library puts a function of
 its own in place of that global or method, which answers one value, as its
 type says. A tuple may end in a rest,
-`[string, ...number[]]`: that many, then any number more. `const a, b = 1, 2`
-still pairs names with values one each; `const a, b = f()` is a name short,
-and says to write `const [a, b] = f()`.
+`[string, ...number[]]`: that many, then any number more.
+
+A declaration and an assignment take one value, and a call is one value
+wherever it is written — an argument, a `return`. Luau's `local a, b = 1, 2`
+is an error that says to write `const [a, b] = [1, 2]`. Where a Luau function
+answers several values and nothing gathers them, ask for all of them by making
+the call an array's last element:
+
+```luau
+const [a, b] = [require(module)]    -- { require(module) }: every value
+```
 
 **A loop takes one value too** — `for (const item in source)`, and several are
 an array the pattern takes apart:

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() : this.parseArrayPattern();
+      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,8 +2664,8 @@ 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();
@@ -3134,7 +3156,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 +3169,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 = {
@@ -4078,10 +4123,9 @@ 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);
+        this.visitType(stmt.name.typeAnnotation, scope);
+        this.declarePattern(scope, stmt.name, "local", scope, stmt.kind === "const");
         return;
       }
       case "FunctionDeclaration": {
@@ -4115,16 +4159,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 +5491,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 +5730,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 +6209,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 : [];
@@ -7456,35 +7495,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 +7575,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 +7773,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) {
@@ -9778,7 +9756,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 +10706,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 +10720,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 +10742,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 +10756,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 +10769,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;
   }

package/dist/index.d.cts

@@ -242,14 +242,17 @@ interface DeclareClassStatement extends BaseNode {
 interface ErrorStatement extends BaseNode {
     type: "ErrorStatement";
 }
-/** `const x = 1` / `let x, y = a, b` — the only variable-binding form in tilua
- *  (Luau's `local` is gone). `const` bindings are immutable and infer literal
- *  types (`const n = 1` → `1`); `let` bindings are mutable and widen. */
+/** `const x = 1` / `let [a, b] = pair` — the only variable-binding form in
+ *  tilua (Luau's `local` is gone). One name, or one pattern, and one value:
+ *  several are taken from an array with a destructuring. `const` bindings are
+ *  immutable and infer literal types (`const n = 1` → `1`); `let` bindings
+ *  are mutable and widen. */
 interface VariableDeclaration extends BaseNode {
     type: "VariableDeclaration";
     kind: "const" | "let";
-    names: BindingTarget[];
-    init: Expression[];
+    name: BindingTarget;
+    /** Absent only on `let x`. */
+    init?: Expression;
 }
 type BindingTarget = IdentifierPattern | ObjectPattern | ArrayPattern;
 interface IdentifierPattern extends BaseNode {
@@ -448,10 +451,11 @@ interface ClassConstructor extends BaseNode {
 interface SuperExpression extends BaseNode {
     type: "SuperExpression";
 }
+/** `x = v` / `[a, b] = [b, a]` — one target, one value. */
 interface AssignmentStatement extends BaseNode {
     type: "AssignmentStatement";
-    targets: (Expression | ObjectPattern | ArrayPattern)[];
-    values: Expression[];
+    target: Expression | ObjectPattern | ArrayPattern;
+    value: Expression;
 }
 interface CompoundAssignmentStatement extends BaseNode {
     type: "CompoundAssignmentStatement";
@@ -672,9 +676,7 @@ interface ArrayExpression extends BaseNode {
  *  only produces one in those two places.
  *
  *  Lua spreads with `table.unpack`, which only yields every value when it is
- *  written last; anywhere else the compiler builds the whole list first. Bare
- *  `...` is unaffected — that is the vararg pack, and `f(...)` passes it on
- *  as it always did. */
+ *  written last; anywhere else the compiler builds the whole list first. */
 interface SpreadElement extends BaseNode {
     type: "SpreadElement";
     argument: Expression;

package/dist/index.d.ts

@@ -242,14 +242,17 @@ interface DeclareClassStatement extends BaseNode {
 interface ErrorStatement extends BaseNode {
     type: "ErrorStatement";
 }
-/** `const x = 1` / `let x, y = a, b` — the only variable-binding form in tilua
- *  (Luau's `local` is gone). `const` bindings are immutable and infer literal
- *  types (`const n = 1` → `1`); `let` bindings are mutable and widen. */
+/** `const x = 1` / `let [a, b] = pair` — the only variable-binding form in
+ *  tilua (Luau's `local` is gone). One name, or one pattern, and one value:
+ *  several are taken from an array with a destructuring. `const` bindings are
+ *  immutable and infer literal types (`const n = 1` → `1`); `let` bindings
+ *  are mutable and widen. */
 interface VariableDeclaration extends BaseNode {
     type: "VariableDeclaration";
     kind: "const" | "let";
-    names: BindingTarget[];
-    init: Expression[];
+    name: BindingTarget;
+    /** Absent only on `let x`. */
+    init?: Expression;
 }
 type BindingTarget = IdentifierPattern | ObjectPattern | ArrayPattern;
 interface IdentifierPattern extends BaseNode {
@@ -448,10 +451,11 @@ interface ClassConstructor extends BaseNode {
 interface SuperExpression extends BaseNode {
     type: "SuperExpression";
 }
+/** `x = v` / `[a, b] = [b, a]` — one target, one value. */
 interface AssignmentStatement extends BaseNode {
     type: "AssignmentStatement";
-    targets: (Expression | ObjectPattern | ArrayPattern)[];
-    values: Expression[];
+    target: Expression | ObjectPattern | ArrayPattern;
+    value: Expression;
 }
 interface CompoundAssignmentStatement extends BaseNode {
     type: "CompoundAssignmentStatement";
@@ -672,9 +676,7 @@ interface ArrayExpression extends BaseNode {
  *  only produces one in those two places.
  *
  *  Lua spreads with `table.unpack`, which only yields every value when it is
- *  written last; anywhere else the compiler builds the whole list first. Bare
- *  `...` is unaffected — that is the vararg pack, and `f(...)` passes it on
- *  as it always did. */
+ *  written last; anywhere else the compiler builds the whole list first. */
 interface SpreadElement extends BaseNode {
     type: "SpreadElement";
     argument: Expression;

package/dist/index.js

@@ -864,10 +864,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 = () => {
@@ -1459,7 +1459,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) {
@@ -1473,14 +1473,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();
@@ -1961,7 +1981,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()) };
@@ -1987,28 +2007,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() : this.parseArrayPattern();
+      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)) {
@@ -2034,6 +2041,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
   // ============================================================
@@ -2517,8 +2539,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") {
@@ -2537,8 +2559,8 @@ 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();
@@ -3029,7 +3051,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,
@@ -3042,6 +3064,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 = {
@@ -3973,10 +4018,9 @@ 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);
+        this.visitType(stmt.name.typeAnnotation, scope);
+        this.declarePattern(scope, stmt.name, "local", scope, stmt.kind === "const");
         return;
       }
       case "FunctionDeclaration": {
@@ -4010,16 +4054,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;
       }
@@ -5343,7 +5386,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);
@@ -5582,12 +5625,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;
@@ -6063,12 +6104,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 : [];
@@ -7351,35 +7390,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": {
@@ -7436,48 +7470,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":
@@ -7641,55 +7668,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) {
@@ -9673,7 +9651,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. */
@@ -10595,13 +10601,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);
@@ -10610,11 +10615,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);
         }
       }
@@ -10632,11 +10637,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;
@@ -10647,11 +10651,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);
@@ -10660,7 +10664,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;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilua/parser",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "tilua parser for roblox",
   "main": "./dist/index.js",
   "module": "./dist/index.js",