@tilua/parser 2.1.0 → 2.3.0

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;
       }
@@ -4565,14 +4608,17 @@ function classArguments(t, name) {
   if (t.kind === "object") return t.class?.typeArguments?.get(name);
   return void 0;
 }
-function unify(param, arg, vars, out) {
+function unify(param, arg, vars, out, how = "union") {
   if (param.kind === "typeParam" && param.constraint && !vars.has(param.name)) {
-    unify(param.constraint, arg, vars, out);
+    unify(param.constraint, arg, vars, out, how);
     return;
   }
   if (param.kind === "typeParam" && vars.has(param.name)) {
     const prev = out.get(param.name);
-    out.set(param.name, prev ? union([prev, arg]) : arg);
+    if (!prev) out.set(param.name, arg);
+    else if (isAssignable(arg, prev)) {
+    } else if (isAssignable(prev, arg)) out.set(param.name, arg);
+    else if (how === "union") out.set(param.name, union([prev, arg]));
     return;
   }
   if (arg.kind === "any" || arg.kind === "never") return;
@@ -5340,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);
@@ -5579,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;
@@ -6060,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 : [];
@@ -7348,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": {
@@ -7433,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":
@@ -7638,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) {
@@ -7757,8 +7738,10 @@ var TypeAnalyzer = class {
   // --------------------------------------------------------
   // Functions
   // --------------------------------------------------------
-  visitFunctionBody(func, outerEnv) {
-    this.withTypeParams(func.generics, () => this.visitFunctionBodyInner(func, outerEnv));
+  /** `returns`, when given, collects the type of each `return` the walk
+   *  reads — see `inferFunctionBody`. */
+  visitFunctionBody(func, outerEnv, returns) {
+    this.withTypeParams(func.generics, () => this.visitFunctionBodyInner(func, outerEnv, returns));
   }
   /** A parameter's type: annotation, else a shape synthesized from a
    *  destructuring pattern, else inferred from its default, else `any`. */
@@ -7807,6 +7790,53 @@ var TypeAnalyzer = class {
    *  it, as in TypeScript: `signal:Connect(function(player) ... end)` knows
    *  `player` from `Connect`'s callback type. Anything else is inferred as
    *  usual. */
+  /** The arguments of a call, in two passes where one is needed.
+   *
+   *  A function written at the call site with a parameter nothing annotates
+   *  reads that parameter from the signature — and where the signature says
+   *  `(v: T) => U`, `T` is only known once the other arguments have been
+   *  read. So such an argument is read once quietly, to get a shape to pick
+   *  a signature with, and then again with `T` in hand: `map(xs, v => v + 1)`
+   *  has its `v` a number by then, and `U` follows from what the body
+   *  answers. Everything else is read once, as it always was. */
+  inferArguments(written, fns, selfOf, extra, env) {
+    const expected = this.expectedArguments(written, fns, selfOf);
+    written.forEach((a, i) => this.applyContext(a, expected[i]));
+    const waits = written.map((a, i) => this.waitsOnInference(a, expected[i]));
+    if (!waits.some(Boolean)) return written.map((a) => this.infer(a, env));
+    const argTypes = written.map((a, i) => waits[i] ? this.quietly(() => this.infer(a, env)) : this.infer(a, env));
+    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), this.spreadOf(written, selfOf(fns[0])));
+    const subst = picked?.typeParams?.length ? this.inferTypeArgs(picked, extra(picked, argTypes)) : void 0;
+    written.forEach((a, i) => {
+      if (!waits[i]) return;
+      if (picked && subst) {
+        const self = selfOf(picked);
+        const declared = i + self < picked.params.length ? picked.params[i + self].type : picked.varargs;
+        if (declared) this.applyContext(a, this.reduceType(substitute(declared, subst)));
+      }
+      argTypes[i] = this.infer(a, env);
+    });
+    return argTypes;
+  }
+  /** Is this argument a function whose own type waits on the call's? */
+  waitsOnInference(arg, expected) {
+    if (!expected || !containsTypeParam(expected)) return false;
+    let e = arg;
+    while (e.type === "ParenthesizedExpression") e = e.expression;
+    if (e.type !== "FunctionExpression") return false;
+    return e.func.params.some((p) => !p.typeAnnotation && !p.default && !p.pattern && p.name !== "self" && p.name !== "this");
+  }
+  /** Read something without saying anything about it: a first pass whose
+   *  only purpose is a shape to go on. */
+  quietly(read) {
+    const was = this.emitDiagnostics;
+    this.emitDiagnostics = false;
+    try {
+      return read();
+    } finally {
+      this.emitDiagnostics = was;
+    }
+  }
   applyContext(expr, expected) {
     let e = expr;
     while (e.type === "ParenthesizedExpression") e = e.expression;
@@ -7955,7 +7985,7 @@ var TypeAnalyzer = class {
       this.contextualReturns.pop();
     }
   }
-  visitFunctionBodyInner(func, outerEnv) {
+  visitFunctionBodyInner(func, outerEnv, returns) {
     const env = forkEnv(outerEnv);
     for (const p of func.params) {
       if (p.pattern) {
@@ -7972,7 +8002,7 @@ var TypeAnalyzer = class {
         if (p.typeAnnotation) this.annotated.add(id);
       }
     }
-    this.withVarargs(func, () => this.collectReturns(void 0, () => {
+    this.withVarargs(func, () => this.collectReturns(returns, () => {
       this.visitBlock(func.body, env);
       this.checkReturnsAtAll(func, this.declaredReturns[this.declaredReturns.length - 1]);
     }));
@@ -8026,7 +8056,7 @@ var TypeAnalyzer = class {
       if (arg === void 0) return;
       const param = p.type.kind === "typeParam" && p.type.constraint ? { ...p.type, constraint: this.reduceType(p.type.constraint) } : p.type;
       const preserve = keepsLiterals(param) || param.kind !== "typeParam" && containsTypeParam(param);
-      unify(p.type, preserve ? arg : widen(arg), vars, subst);
+      unify(p.type, preserve ? arg : widen(arg), vars, subst, "first");
     });
     if (f.varargs && f.restIsWhole) {
       const rest = argTypes.slice(f.params.length).map((a) => a === void 0 ? unknownType : widen(a));
@@ -8377,7 +8407,12 @@ var TypeAnalyzer = class {
       asserts: node.asserts
     };
   }
-  inferFunctionBody(func, env) {
+  /** `visited`, when given, is what the real walk of the body just
+   *  collected from its `return`s: a function expression is walked before
+   *  its type is asked for, so there is nothing left to guess, and walking
+   *  the body a second time only to read them made every callback nested in
+   *  another cost twice its parent's. */
+  inferFunctionBody(func, env, visited) {
     const names = func.generics.map((g) => g.name);
     return this.withTypeParams(func.generics, () => {
       const params = func.params.flatMap((p) => {
@@ -8406,6 +8441,8 @@ var TypeAnalyzer = class {
         returns = this.resolveType(func.returnType);
       } else if (func.predicate) {
         returns = booleanType;
+      } else if (visited) {
+        returns = visited.length ? union([...visited]) : this.withVarargs(func, () => this.silently(() => this.inferReturnType(func.body, bodyEnv)));
       } else {
         const collected = [];
         returns = this.withVarargs(func, () => this.silently(() => {
@@ -9278,10 +9315,12 @@ var TypeAnalyzer = class {
         return this.inferArray(expr, env, false);
       case "TableExpression":
         return this.inferObject(expr, env, false);
-      case "FunctionExpression":
+      case "FunctionExpression": {
         this.checkParamOrder(expr.func.params, expr);
-        this.visitFunctionBody(expr.func, env);
-        return this.inferFunctionBody(expr.func, env);
+        const returned = [];
+        this.visitFunctionBody(expr.func, env, returned);
+        return this.inferFunctionBody(expr.func, env, returned);
+      }
       case "ParenthesizedExpression":
         return this.infer(expr.expression, env);
       case "TypeAssertionExpression": {
@@ -9485,9 +9524,7 @@ var TypeAnalyzer = class {
     const united = this.unionSignatures(callee);
     const fns = united ?? this.overloadsOf(callee);
     const explicit = this.explicitTypeArguments(expr, fns);
-    const expected = this.expectedArguments(expr.arguments, fns, () => 0);
-    expr.arguments.forEach((a, i) => this.applyContext(a, expected[i]));
-    const argTypes = expr.arguments.map((a) => this.infer(a, env));
+    const argTypes = this.inferArguments(expr.arguments, fns, () => 0, (_, args) => args, env);
     if (fns.length) {
       this.recordExpected(expr.arguments, fns, () => 0, () => argTypes);
       const spread = this.spreadOf(expr.arguments);
@@ -9552,9 +9589,13 @@ var TypeAnalyzer = class {
     const united = this.unionSignatures(method);
     const fns = united ?? this.overloadsOf(method);
     const explicit = this.explicitTypeArguments(expr, fns);
-    const expected = this.expectedArguments(expr.arguments, fns, (f) => this.takesSelf(f) ? 1 : 0);
-    expr.arguments.forEach((a, i) => this.applyContext(a, expected[i]));
-    const argTypes = expr.arguments.map((a) => this.infer(a, env));
+    const argTypes = this.inferArguments(
+      expr.arguments,
+      fns,
+      (f) => this.takesSelf(f) ? 1 : 0,
+      (f, args) => this.takesSelf(f) ? [objType, ...args] : args,
+      env
+    );
     if (fns.length) {
       const withSelf = (f) => this.takesSelf(f) ? [objType, ...argTypes] : argTypes;
       const selfOf = (f) => this.takesSelf(f) ? 1 : 0;
@@ -9610,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. */
@@ -10532,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);
@@ -10547,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);
         }
       }
@@ -10569,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;
@@ -10584,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);
@@ -10597,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;
   }