@tilua/parser 3.0.0 → 3.0.1

package/dist/index.cjs

@@ -3893,6 +3893,10 @@ var Analyzer = class {
   moduleScope = this.globalScope;
   /** How many function bodies enclose the walk. */
   functionDepth = 0;
+  /** How many loops enclose the walk inside the nearest function body. A
+   *  function starts again at 0: `continue` in `xs:map(x => ...)` has no
+   *  loop to go on with, whatever loop the call is written in. */
+  loopDepth = 0;
   /** Function declarations already declared by their block's hoisting, with
    *  the function depth of that block. */
   hoisted = /* @__PURE__ */ new Map();
@@ -4245,11 +4249,11 @@ var Analyzer = class {
         return;
       case "WhileStatement":
         this.visitExpression(stmt.condition, scope);
-        this.visitBlockInNewScope(stmt.body, scope);
+        this.inLoop(() => this.visitBlockInNewScope(stmt.body, scope));
         return;
       case "RepeatStatement": {
         const bodyScope = childScope(scope);
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         this.visitExpression(stmt.condition, bodyScope);
         return;
       }
@@ -4267,14 +4271,14 @@ var Analyzer = class {
         if (stmt.step) this.visitExpression(stmt.step, scope);
         const bodyScope = childScope(scope);
         this.declare(bodyScope, stmt.variable.name, "for-numeric", stmt.variable);
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         return;
       }
       case "GenericForStatement": {
         this.visitExpression(stmt.iterator, scope);
         const bodyScope = childScope(scope);
         this.declarePattern(bodyScope, stmt.variable, "for-generic", scope, stmt.kind === "const");
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         return;
       }
       case "ReturnStatement":
@@ -4282,6 +4286,15 @@ var Analyzer = class {
         return;
       case "BreakStatement":
       case "ContinueStatement":
+        if (this.loopDepth === 0) {
+          const word = stmt.type === "BreakStatement" ? "break" : "continue";
+          this.diagnostics.push({
+            node: stmt,
+            message: this.functionDepth > 0 ? `'${word}' is not inside a loop of this function; to skip a value in a callback, 'return' from it` : `'${word}' is not inside a loop`,
+            kind: "outside-loop"
+          });
+        }
+        return;
       case "ErrorStatement":
         return;
       case "DeclareStatement":
@@ -4337,6 +4350,15 @@ var Analyzer = class {
         return;
     }
   }
+  /** Visit a loop's body, where `break` and `continue` have a loop. */
+  inLoop(visit) {
+    this.loopDepth++;
+    try {
+      visit();
+    } finally {
+      this.loopDepth--;
+    }
+  }
   // ---------------- functions ----------------
   visitFunctionBody(func, outerScope, isMethod = false) {
     const fnScope = childScope(outerScope);
@@ -4352,11 +4374,14 @@ var Analyzer = class {
       }
     });
     this.visitType(func.returnType, fnScope);
+    const loops = this.loopDepth;
     this.functionDepth++;
+    this.loopDepth = 0;
     try {
       this.visitBlock(func.body, fnScope);
     } finally {
       this.functionDepth--;
+      this.loopDepth = loops;
     }
   }
   /** An overload signature: no body and no bindings, but its types can hold
@@ -4610,11 +4635,14 @@ declare metatable string: {
 -- answer \`nil\` rather than JavaScript's -1. \`sort\` takes Lua's comparator
 -- (true when \`a\` comes first). \`push\`, \`pop\`, \`shift\`, \`unshift\`,
 -- \`sort\` and \`reverse\` change the array; everything else returns a new one.
+-- A \`filter\` whose test is a guard \u2014 \`v is S\`, or \`v => v ~= nil\` \u2014
+-- answers an array of what it let through.
 declare metatable<T> T[]: {
     __index: {
         find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,
         findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,
-        filter: (self: T[], test: (value: T, index: number) => boolean) => T[],
+        filter: (<S extends T>(self: T[], test: (value: T, index: number) => value is S) => S[])
+            & ((self: T[], test: (value: T, index: number) => boolean) => T[]),
         map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],
         forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,
         some: (self: T[], test: (value: T, index: number) => boolean) => boolean,
@@ -4753,8 +4781,14 @@ function substitute(t, subst) {
   if (subst.size === 0) return t;
   if (!containsTypeParam(t)) return t;
   switch (t.kind) {
-    case "typeParam":
-      return subst.get(t.name) ?? t;
+    case "typeParam": {
+      const bound = subst.get(t.name);
+      if (bound) return bound;
+      if (t.constraint && containsTypeParam(t.constraint)) {
+        return { ...t, constraint: substitute(t.constraint, new Map([...subst, [t.name, t]])) };
+      }
+      return t;
+    }
     case "array":
       return { ...arrayOf(substitute(t.element, subst)), readonly: t.readonly };
     case "tuple":
@@ -4899,6 +4933,10 @@ function unify(param, arg, vars, out, how = "union") {
       if (arg.kind === "function") {
         param.params.forEach((p, i) => arg.params[i] && unify(p.type, arg.params[i].type, vars, out));
         unify(param.returns, arg.returns, vars, out);
+        const wanted = param.predicate, given = arg.predicate;
+        if (wanted?.type && given?.type && wanted.param === given.param && !wanted.asserts && !given.asserts) {
+          unify(wanted.type, given.type, vars, out);
+        }
       }
       return;
     case "object":
@@ -5154,6 +5192,11 @@ function isAssignableInner(a, b) {
     for (let i = 0; i < n; i++) {
       if (!isAssignable(a.params[i].type, b.params[i].type) && !isAssignable(b.params[i].type, a.params[i].type)) return false;
     }
+    const wanted = b.predicate;
+    if (wanted?.type && !wanted.asserts) {
+      const given = a.predicate;
+      if (!given?.type || given.asserts || given.param !== wanted.param || !isAssignable(given.type, wanted.type)) return false;
+    }
     return isAssignable(a.returns, b.returns);
   }
   if (b.kind === "typeParam") return false;
@@ -5288,7 +5331,7 @@ function containsFreeTypeParam(t, seen, bound) {
       return [...t.properties.values()].some((v) => containsTypeParam(v.type, seen, bound)) || !!t.indexer && (containsTypeParam(t.indexer.key, seen, bound) || containsTypeParam(t.indexer.value, seen, bound));
     case "function": {
       const inner = t.typeParams?.length ? /* @__PURE__ */ new Set([...bound, ...t.typeParams]) : bound;
-      return t.params.some((p) => containsTypeParam(p.type, seen, inner)) || !!t.varargs && containsTypeParam(t.varargs, seen, inner) || containsTypeParam(t.returns, seen, inner);
+      return t.params.some((p) => containsTypeParam(p.type, seen, inner)) || !!t.varargs && containsTypeParam(t.varargs, seen, inner) || containsTypeParam(t.returns, seen, inner) || !!t.predicate?.type && containsTypeParam(t.predicate.type, seen, inner);
     }
     case "genericRef":
       return t.typeArguments.some((a) => containsTypeParam(a, seen, bound));
@@ -5713,9 +5756,14 @@ function isFreshLiteralExpr(e) {
     case "StringLiteral":
     case "BooleanLiteral":
     case "InterpolatedStringExpression":
+      return true;
+    // A table or array literal widened the literals written in it as it
+    // was read (`widenUnlessAsked`), and keeps what it read from
+    // elsewhere — `{ key: name }`, `[...names]` — so there is nothing
+    // left for the binding to widen.
     case "TableExpression":
     case "ArrayExpression":
-      return true;
+      return false;
     case "ParenthesizedExpression":
       return isFreshLiteralExpr(e.expression);
     case "UnaryExpression":
@@ -5730,6 +5778,30 @@ function isFreshLiteralExpr(e) {
       return false;
   }
 }
+function overloadTier(f) {
+  const takesGuard = f.params.some((p) => p.type.kind === "function" && p.type.predicate?.type && !p.type.predicate.asserts);
+  if (takesGuard) return 0;
+  return (f.typeParams?.length ?? 0) > 0 ? 2 : 1;
+}
+function writesLiteral(e) {
+  switch (e.type) {
+    case "NumberLiteral":
+    case "StringLiteral":
+    case "BooleanLiteral":
+    case "InterpolatedStringExpression":
+      return true;
+    case "ParenthesizedExpression":
+      return writesLiteral(e.expression);
+    case "UnaryExpression":
+      return writesLiteral(e.argument);
+    case "IfElseExpression":
+      return e.clauses.some((c) => writesLiteral(c.body)) || writesLiteral(e.alternate);
+    case "BinaryExpression":
+      return (e.operator === "or" || e.operator === "and") && (writesLiteral(e.left) || writesLiteral(e.right));
+    default:
+      return false;
+  }
+}
 function collectInferNames(node) {
   const out = [];
   const walk = (n) => {
@@ -8112,7 +8184,9 @@ var TypeAnalyzer = class {
     const waits = written.map((a, i) => this.waitsOnInference(a, expected[i]));
     if (!waits.some(Boolean)) return written.map((a) => this.infer(a, env));
     const argTypes = written.map((a, i) => waits[i] ? this.quietly(() => this.infer(a, env)) : this.infer(a, env));
-    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), this.spreadOf(written, selfOf(fns[0])));
+    const spread = this.spreadOf(written, selfOf(fns[0]));
+    const provisional = argTypes.map((t, i) => waits[i] ? anyType : t);
+    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), spread) ?? this.pickOverload(fns, provisional, (f) => extra(f, provisional), spread);
     const subst = picked?.typeParams?.length ? this.inferTypeArgs(picked, extra(picked, argTypes)) : void 0;
     written.forEach((a, i) => {
       if (!waits[i]) return;
@@ -8303,6 +8377,16 @@ var TypeAnalyzer = class {
       }
       const id = this.bindingIdByName(p.name, p);
       const t = this.paramType(p, env);
+      if (p.default && p.typeAnnotation) {
+        const given = this.infer(p.default, env);
+        const declared = this.resolveType(p.typeAnnotation);
+        if (this.emitDiagnostics && !isAssignable(given, declared)) {
+          this.diagnostics.push({
+            node: p.default,
+            message: `Type '${briefType(given)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(given, declared)
+          });
+        }
+      }
       if (id !== void 0) {
         this.bindingType.set(id, t);
         this.setBinding(env, id, t);
@@ -8400,9 +8484,9 @@ var TypeAnalyzer = class {
    *  lets `typeof` declare `(v: number) -> "number"` alongside a trailing
    *  `<T>(v: T) -> string` and still pick the precise one. */
   pickOverload(fns, argTypes, argsFor, spread) {
-    for (const generic of [false, true]) {
+    for (const tier of [0, 1, 2]) {
       for (const f of fns) {
-        if ((f.typeParams?.length ?? 0) > 0 !== generic) continue;
+        if (overloadTier(f) !== tier) continue;
         if (this.overloadAccepts(f, argsFor ? argsFor(f) : argTypes, spread)) return f;
       }
     }
@@ -8428,7 +8512,7 @@ var TypeAnalyzer = class {
     if (position < 0) return void 0;
     const members = this.expand(argTypes[position]).types;
     if (members.length > 32) return void 0;
-    const rank = (f) => ((f.typeParams?.length ?? 0) > 0 ? fns.length : 0) + fns.indexOf(f);
+    const rank = (f) => overloadTier(f) * fns.length + fns.indexOf(f);
     const limit = picked ? rank(picked) : Infinity;
     const results = [];
     for (const member of members) {
@@ -8821,10 +8905,38 @@ var TypeAnalyzer = class {
         returns,
         void 0,
         names,
-        this.resolvePredicate(func.predicate, params)
+        func.predicate || func.returnType ? this.resolvePredicate(func.predicate, params) : this.inferPredicate(func, params, returns, bodyEnv)
       ), func.params);
     });
   }
+  /** `v => v ~= nil` is a guard without saying so, as TypeScript reads it:
+   *  a body that is one `return` of a boolean which, true, narrows a
+   *  parameter — and, false, leaves it exactly what that excludes. Then
+   *  `list:filter(v => v ~= nil)` knows what it kept. */
+  inferPredicate(func, params, returns, env) {
+    const only = func.body.statements.length === 1 ? func.body.statements[0] : void 0;
+    if (only?.type !== "ReturnStatement" || !only.argument) return void 0;
+    if (returns.kind === "any" || returns.kind === "never" || !isAssignable(returns, booleanType)) return void 0;
+    const cond = only.argument;
+    for (let i = 0; i < params.length; i++) {
+      const p = func.params[i];
+      if (p.pattern || p.rest) continue;
+      const id = this.bindingIdByName(p.name, p);
+      if (id === void 0) continue;
+      const declared = params[i].type;
+      const key = bindKey(id);
+      const t = forkEnv(env);
+      const f = forkEnv(env);
+      this.silently(() => this.applyNarrowing(cond, env, t, f));
+      const yes = t.get(key);
+      if (!yes || equalTypes(yes, declared) || !isAssignable(yes, declared)) continue;
+      const no = this.expand(f.get(key) ?? declared);
+      const rest = no.kind === "union" ? no.types : [no];
+      if (rest.some((m) => m.kind !== "never" && isAssignable(m, yes))) continue;
+      return { param: i, type: yes, asserts: false };
+    }
+    return void 0;
+  }
   /** Where the return types of the function being walked are collected, so
    *  each is read where it is written — inside the branch that narrowed it —
    *  rather than in whatever state the body ends in. */
@@ -9946,6 +10058,27 @@ var TypeAnalyzer = class {
           elseEnv = whenFalse;
         }
         branches.push(this.infer(expr.alternate, elseEnv));
+        const bodies = [...expr.clauses.map((c) => c.body), expr.alternate].map(unwrapParens);
+        const isEmpty = (e) => e.type === "TableExpression" && e.fields.length === 0 || e.type === "ArrayExpression" && e.elements.length === 0;
+        const others = union(branches.filter((_, i) => !isEmpty(bodies[i])));
+        const parts = (others.kind === "union" ? others.types : [others]).map((m) => this.expand(m)).filter((m) => !(m.kind === "primitive" && m.name === "nil"));
+        const fits = (e) => {
+          if (!parts.length) return void 0;
+          if (e.type === "ArrayExpression") {
+            if (parts.every((m) => m.kind === "array")) return others;
+            return parts.every((m) => m.kind === "array" || m.kind === "tuple") ? tuple([]) : void 0;
+          }
+          return parts.every((m) => m.kind === "object" && !m.class && [...m.properties.values()].every((prop) => prop.optional)) ? others : void 0;
+        };
+        if (bodies.some(isEmpty) && others.kind !== "never" && others.kind !== "any" && bodies.every((body) => !isEmpty(body) || fits(body))) {
+          const typed = bodies.map((body, i) => {
+            if (!isEmpty(body)) return branches[i];
+            const t = fits(body);
+            this.typeOf.set(body, t);
+            return t;
+          });
+          return union(typed);
+        }
         return union(branches);
       }
     }
@@ -10252,23 +10385,87 @@ var TypeAnalyzer = class {
     if (wantedTuple && !asConst) return this.inferTupleLiteral(expr, env, wantedTuple);
     const elems = [];
     let hadSpread = false;
+    const written = [];
     for (const el of expr.elements) {
       if (el.type === "SpreadElement") {
         hadSpread = true;
-        const s = this.infer(el.argument, env);
-        if (s.kind === "array") elems.push(s.element);
-        else if (s.kind === "tuple") elems.push(...s.elements);
-        else elems.push(unknownType);
+        const spread = this.infer(el.argument, env);
+        written.push({ spread: true, type: spread });
+        elems.push(...this.spreadElements(spread));
       } else {
-        elems.push(asConst ? this.inferAsConst(el, env) : this.infer(el, env));
+        const t = asConst ? this.inferAsConst(el, env) : this.infer(el, env);
+        written.push({ spread: false, type: asConst ? t : this.widenUnlessAsked(t, el) });
+        elems.push(t);
       }
     }
     if (asConst && !hadSpread) return tuple(elems);
+    if (hadSpread) {
+      const tuples = this.spreadTuples(written);
+      if (tuples) return union(tuples.map((elements) => tuple(elements)));
+    }
     return arrayOf(elems.length ? union(elems.map((t, i) => {
       const element = expr.elements[i];
       return asConst || !element || element.type === "SpreadElement" ? t : this.widenUnlessAsked(t, element);
     })) : unknownType);
   }
+  /** The tuples an array literal with spreads is, when every spread is a
+   *  tuple of known length or a union of them: one per way the unions go.
+   *  `undefined` when a spread's length is not known (an array, a tuple
+   *  with a rest), or the ways multiply past what is worth listing. */
+  spreadTuples(written) {
+    const MAX = 32;
+    let variants = [[]];
+    for (const { spread, type } of written) {
+      if (!spread) {
+        variants = variants.map((v) => [...v, type]);
+        continue;
+      }
+      const options = this.fixedTuples(type);
+      if (!options) return void 0;
+      const next = [];
+      for (const v of variants) for (const option of options) next.push([...v, ...option]);
+      if (next.length > MAX) return void 0;
+      variants = next;
+    }
+    return variants;
+  }
+  /** A tuple of known length's members, or a union of such tuples' — each
+   *  a way the value can be. `nil` in a union spreads nothing. */
+  fixedTuples(t, depth = 0) {
+    if (depth > 8) return void 0;
+    const held = this.expand(t);
+    if (held.kind === "tuple") return held.rest ? void 0 : [held.elements];
+    if (held.kind !== "union") return void 0;
+    const out = [];
+    for (const member of held.types) {
+      if (member.kind === "primitive" && member.name === "nil") continue;
+      const options = this.fixedTuples(member, depth + 1);
+      if (!options) return void 0;
+      out.push(...options);
+    }
+    return out.length ? out : void 0;
+  }
+  /** What `...xs` puts into an array: an array's element, a tuple's members,
+   *  and for a union each member's — `...(host ? extra : [])` adds `extra`'s
+   *  elements and the empty tuple nothing. Anything else, `unknown`. */
+  spreadElements(t, depth = 0) {
+    const held = this.expand(t);
+    if (depth > 8) return [unknownType];
+    switch (held.kind) {
+      case "array":
+        return [held.element];
+      case "tuple":
+        return tupleMembers(held);
+      case "union":
+        return held.types.filter((m) => !(m.kind === "primitive" && m.name === "nil")).flatMap((m) => this.spreadElements(m, depth + 1));
+      case "typeParam":
+        return held.constraint ? this.spreadElements(held.constraint, depth + 1) : [unknownType];
+      case "any":
+        return [anyType];
+      default:
+        return [unknownType];
+    }
+  }
   /** `[a, b, ...more]` where a tuple is wanted: the places it names are the
    *  tuple's, and what comes after them — more elements, or a spread — is
    *  its rest. */
@@ -10279,10 +10476,7 @@ var TypeAnalyzer = class {
     expr.elements.forEach((element, i) => {
       if (element.type === "SpreadElement") {
         spread = true;
-        const held = this.expand(this.infer(element.argument, env));
-        if (held.kind === "array") tail.push(held.element);
-        else if (held.kind === "tuple") tail.push(...tupleMembers(held));
-        else tail.push(unknownType);
+        tail.push(...this.spreadElements(this.infer(element.argument, env)));
         return;
       }
       const t = this.widenUnlessAsked(this.infer(element, env), element);
@@ -10299,6 +10493,7 @@ var TypeAnalyzer = class {
    *  The context was recorded by `applyContext` before the value was
    *  inferred, so this is a lookup rather than a second pass. */
   widenUnlessAsked(value, at) {
+    if (!writesLiteral(at)) return value;
     const wanted = this.expectedTypeOf.get(at);
     if (value.kind === "literal") {
       const arms = this.contextArms.get(at);

package/dist/index.d.cts

@@ -1064,7 +1064,7 @@ interface ScopeDiagnostic {
         };
     };
     message: string;
-    kind: "redeclare" | "const-assign" | "type-only" | "undeclared" | "use-before-define";
+    kind: "redeclare" | "const-assign" | "type-only" | "undeclared" | "use-before-define" | "outside-loop";
 }
 interface ScopeAnalysis {
     /** Every Identifier that appears in a variable *usage* position (i.e.
@@ -1601,7 +1601,7 @@ resolveModule?: (specifier: string) => ModuleExports | undefined): ModuleExports
  * `ObjectValues<T>` and `ObjectEntries<T>`, an object's members as tuples in
  * the order they were written.
  */
-declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...args: unknown[]) => infer R ? R : never\ntype Parameters<T> = T extends (...args: infer P) => unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n\n-- ============================================================\n-- The metatables of the language's own values\n-- ============================================================\n\n-- A string's methods. The first group is Lua's string library, which a\n-- string really answers to; where Lua answers several values, tilua answers\n-- one, as the global functions do (`find` is an array, `gsub` the new\n-- string). The second group is written the way JavaScript writes it.\n--\n-- Positions are Lua's: `sub` and `slice` count from 1, and `indexOf` is\n-- `nil` when the text is not there.\ndeclare metatable string: {\n    __index: {\n        upper: (self: string) => string,\n        lower: (self: string) => string,\n        len: (self: string) => number,\n        sub: (self: string, i: number, j?: number) => string,\n        rep: (self: string, n: number, separator?: string) => string,\n        reverse: (self: string) => string,\n        format: (self: string, ...args: unknown[]) => string,\n        byte: ((self: string, i?: number) => number) & ((self: string, i: number, j: number) => number[]),\n        find: (self: string, pattern: string, init?: number, plain?: boolean) => [number, number, ...string[]] | nil,\n        match: (self: string, pattern: string, init?: number) => [...string[]] | nil,\n        gmatch: (self: string, pattern: string) => () => [string, ...string[]] | nil,\n        gsub: (self: string, pattern: string, replacement: unknown, n?: number) => string,\n\n        trim: (self: string) => string,\n        trimStart: (self: string) => string,\n        trimEnd: (self: string) => string,\n        startsWith: (self: string, text: string) => boolean,\n        endsWith: (self: string, text: string) => boolean,\n        includes: (self: string, text: string) => boolean,\n        indexOf: (self: string, text: string, start?: number) => number | nil,\n        slice: (self: string, start?: number, stop?: number) => string,\n        replace: (self: string, text: string, replacement: string) => string,\n        replaceAll: (self: string, text: string, replacement: string) => string,\n        padStart: (self: string, length: number, padding?: string) => string,\n        padEnd: (self: string, length: number, padding?: string) => string,\n    },\n}\n\n-- An array's methods. Lua gives an array no metatable: the compiler lowers\n-- each call to a plain function, so they work on any array, one a Lua\n-- library made included.\n--\n-- Indices are Lua's: the first element is 1, and `indexOf` / `findIndex`\n-- answer `nil` rather than JavaScript's -1. `sort` takes Lua's comparator\n-- (true when `a` comes first). `push`, `pop`, `shift`, `unshift`,\n-- `sort` and `reverse` change the array; everything else returns a new one.\ndeclare metatable<T> T[]: {\n    __index: {\n        find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,\n        findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,\n        filter: (self: T[], test: (value: T, index: number) => boolean) => T[],\n        map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],\n        forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,\n        some: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        every: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        reduce: <U>(self: T[], step: (total: U, value: T, index: number) => U, initial: U) => U,\n        includes: (self: T[], value: T) => boolean,\n        indexOf: (self: T[], value: T, start?: number) => number | nil,\n        join: (self: T[], separator?: string) => string,\n        concat: (self: T[], ...others: T[][]) => T[],\n        slice: (self: T[], start?: number, stop?: number) => T[],\n        flat: (self: T[]) => T[],\n        reverse: (self: T[]) => T[],\n        sort: (self: T[], compare?: (a: T, b: T) => boolean) => T[],\n        push: (self: T[], ...args: T[]) => number,\n        pop: (self: T[]) => T | nil,\n        shift: (self: T[]) => T | nil,\n        unshift: (self: T[], ...args: T[]) => number,\n    },\n}\n\n-- A table's methods. Unlike JavaScript's `Object.keys`, they answer a\n-- tuple, in the order the table's type wrote its members:\n--\n--     const point = { x: 1, y: \"up\" }\n--     point:keys()     -- [\"x\", \"y\"]\n--     point:values()   -- [number, string]\n--     point:entries()  -- [[\"x\", number], [\"y\", string]]\n--\n-- A Lua table has no order of its own, so the compiler hands its runtime the\n-- keys as the type lists them. An optional member keeps its place, holding\n-- `nil` when it is missing; an indexer's keys follow the named ones. A\n-- member of the table's own with one of these names is what a call reaches,\n-- and a class instance, which has a metatable of its own, has none of them.\ndeclare metatable<T extends {}> T: {\n    __index: {\n        keys: (self: T) => ObjectKeys<T>,\n        values: (self: T) => ObjectValues<T>,\n        entries: (self: T) => ObjectEntries<T>,\n    },\n}\n";
+declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...args: unknown[]) => infer R ? R : never\ntype Parameters<T> = T extends (...args: infer P) => unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n\n-- ============================================================\n-- The metatables of the language's own values\n-- ============================================================\n\n-- A string's methods. The first group is Lua's string library, which a\n-- string really answers to; where Lua answers several values, tilua answers\n-- one, as the global functions do (`find` is an array, `gsub` the new\n-- string). The second group is written the way JavaScript writes it.\n--\n-- Positions are Lua's: `sub` and `slice` count from 1, and `indexOf` is\n-- `nil` when the text is not there.\ndeclare metatable string: {\n    __index: {\n        upper: (self: string) => string,\n        lower: (self: string) => string,\n        len: (self: string) => number,\n        sub: (self: string, i: number, j?: number) => string,\n        rep: (self: string, n: number, separator?: string) => string,\n        reverse: (self: string) => string,\n        format: (self: string, ...args: unknown[]) => string,\n        byte: ((self: string, i?: number) => number) & ((self: string, i: number, j: number) => number[]),\n        find: (self: string, pattern: string, init?: number, plain?: boolean) => [number, number, ...string[]] | nil,\n        match: (self: string, pattern: string, init?: number) => [...string[]] | nil,\n        gmatch: (self: string, pattern: string) => () => [string, ...string[]] | nil,\n        gsub: (self: string, pattern: string, replacement: unknown, n?: number) => string,\n\n        trim: (self: string) => string,\n        trimStart: (self: string) => string,\n        trimEnd: (self: string) => string,\n        startsWith: (self: string, text: string) => boolean,\n        endsWith: (self: string, text: string) => boolean,\n        includes: (self: string, text: string) => boolean,\n        indexOf: (self: string, text: string, start?: number) => number | nil,\n        slice: (self: string, start?: number, stop?: number) => string,\n        replace: (self: string, text: string, replacement: string) => string,\n        replaceAll: (self: string, text: string, replacement: string) => string,\n        padStart: (self: string, length: number, padding?: string) => string,\n        padEnd: (self: string, length: number, padding?: string) => string,\n    },\n}\n\n-- An array's methods. Lua gives an array no metatable: the compiler lowers\n-- each call to a plain function, so they work on any array, one a Lua\n-- library made included.\n--\n-- Indices are Lua's: the first element is 1, and `indexOf` / `findIndex`\n-- answer `nil` rather than JavaScript's -1. `sort` takes Lua's comparator\n-- (true when `a` comes first). `push`, `pop`, `shift`, `unshift`,\n-- `sort` and `reverse` change the array; everything else returns a new one.\n-- A `filter` whose test is a guard \u2014 `v is S`, or `v => v ~= nil` \u2014\n-- answers an array of what it let through.\ndeclare metatable<T> T[]: {\n    __index: {\n        find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,\n        findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,\n        filter: (<S extends T>(self: T[], test: (value: T, index: number) => value is S) => S[])\n            & ((self: T[], test: (value: T, index: number) => boolean) => T[]),\n        map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],\n        forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,\n        some: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        every: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        reduce: <U>(self: T[], step: (total: U, value: T, index: number) => U, initial: U) => U,\n        includes: (self: T[], value: T) => boolean,\n        indexOf: (self: T[], value: T, start?: number) => number | nil,\n        join: (self: T[], separator?: string) => string,\n        concat: (self: T[], ...others: T[][]) => T[],\n        slice: (self: T[], start?: number, stop?: number) => T[],\n        flat: (self: T[]) => T[],\n        reverse: (self: T[]) => T[],\n        sort: (self: T[], compare?: (a: T, b: T) => boolean) => T[],\n        push: (self: T[], ...args: T[]) => number,\n        pop: (self: T[]) => T | nil,\n        shift: (self: T[]) => T | nil,\n        unshift: (self: T[], ...args: T[]) => number,\n    },\n}\n\n-- A table's methods. Unlike JavaScript's `Object.keys`, they answer a\n-- tuple, in the order the table's type wrote its members:\n--\n--     const point = { x: 1, y: \"up\" }\n--     point:keys()     -- [\"x\", \"y\"]\n--     point:values()   -- [number, string]\n--     point:entries()  -- [[\"x\", number], [\"y\", string]]\n--\n-- A Lua table has no order of its own, so the compiler hands its runtime the\n-- keys as the type lists them. An optional member keeps its place, holding\n-- `nil` when it is missing; an indexer's keys follow the named ones. A\n-- member of the table's own with one of these names is what a call reaches,\n-- and a class instance, which has a metatable of its own, has none of them.\ndeclare metatable<T extends {}> T: {\n    __index: {\n        keys: (self: T) => ObjectKeys<T>,\n        values: (self: T) => ObjectValues<T>,\n        entries: (self: T) => ObjectEntries<T>,\n    },\n}\n";
 
 interface ProjectHost {
     /** A file's text, or `undefined` when there is no such file. */

package/dist/index.d.ts

@@ -1064,7 +1064,7 @@ interface ScopeDiagnostic {
         };
     };
     message: string;
-    kind: "redeclare" | "const-assign" | "type-only" | "undeclared" | "use-before-define";
+    kind: "redeclare" | "const-assign" | "type-only" | "undeclared" | "use-before-define" | "outside-loop";
 }
 interface ScopeAnalysis {
     /** Every Identifier that appears in a variable *usage* position (i.e.
@@ -1601,7 +1601,7 @@ resolveModule?: (specifier: string) => ModuleExports | undefined): ModuleExports
  * `ObjectValues<T>` and `ObjectEntries<T>`, an object's members as tuples in
  * the order they were written.
  */
-declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...args: unknown[]) => infer R ? R : never\ntype Parameters<T> = T extends (...args: infer P) => unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n\n-- ============================================================\n-- The metatables of the language's own values\n-- ============================================================\n\n-- A string's methods. The first group is Lua's string library, which a\n-- string really answers to; where Lua answers several values, tilua answers\n-- one, as the global functions do (`find` is an array, `gsub` the new\n-- string). The second group is written the way JavaScript writes it.\n--\n-- Positions are Lua's: `sub` and `slice` count from 1, and `indexOf` is\n-- `nil` when the text is not there.\ndeclare metatable string: {\n    __index: {\n        upper: (self: string) => string,\n        lower: (self: string) => string,\n        len: (self: string) => number,\n        sub: (self: string, i: number, j?: number) => string,\n        rep: (self: string, n: number, separator?: string) => string,\n        reverse: (self: string) => string,\n        format: (self: string, ...args: unknown[]) => string,\n        byte: ((self: string, i?: number) => number) & ((self: string, i: number, j: number) => number[]),\n        find: (self: string, pattern: string, init?: number, plain?: boolean) => [number, number, ...string[]] | nil,\n        match: (self: string, pattern: string, init?: number) => [...string[]] | nil,\n        gmatch: (self: string, pattern: string) => () => [string, ...string[]] | nil,\n        gsub: (self: string, pattern: string, replacement: unknown, n?: number) => string,\n\n        trim: (self: string) => string,\n        trimStart: (self: string) => string,\n        trimEnd: (self: string) => string,\n        startsWith: (self: string, text: string) => boolean,\n        endsWith: (self: string, text: string) => boolean,\n        includes: (self: string, text: string) => boolean,\n        indexOf: (self: string, text: string, start?: number) => number | nil,\n        slice: (self: string, start?: number, stop?: number) => string,\n        replace: (self: string, text: string, replacement: string) => string,\n        replaceAll: (self: string, text: string, replacement: string) => string,\n        padStart: (self: string, length: number, padding?: string) => string,\n        padEnd: (self: string, length: number, padding?: string) => string,\n    },\n}\n\n-- An array's methods. Lua gives an array no metatable: the compiler lowers\n-- each call to a plain function, so they work on any array, one a Lua\n-- library made included.\n--\n-- Indices are Lua's: the first element is 1, and `indexOf` / `findIndex`\n-- answer `nil` rather than JavaScript's -1. `sort` takes Lua's comparator\n-- (true when `a` comes first). `push`, `pop`, `shift`, `unshift`,\n-- `sort` and `reverse` change the array; everything else returns a new one.\ndeclare metatable<T> T[]: {\n    __index: {\n        find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,\n        findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,\n        filter: (self: T[], test: (value: T, index: number) => boolean) => T[],\n        map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],\n        forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,\n        some: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        every: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        reduce: <U>(self: T[], step: (total: U, value: T, index: number) => U, initial: U) => U,\n        includes: (self: T[], value: T) => boolean,\n        indexOf: (self: T[], value: T, start?: number) => number | nil,\n        join: (self: T[], separator?: string) => string,\n        concat: (self: T[], ...others: T[][]) => T[],\n        slice: (self: T[], start?: number, stop?: number) => T[],\n        flat: (self: T[]) => T[],\n        reverse: (self: T[]) => T[],\n        sort: (self: T[], compare?: (a: T, b: T) => boolean) => T[],\n        push: (self: T[], ...args: T[]) => number,\n        pop: (self: T[]) => T | nil,\n        shift: (self: T[]) => T | nil,\n        unshift: (self: T[], ...args: T[]) => number,\n    },\n}\n\n-- A table's methods. Unlike JavaScript's `Object.keys`, they answer a\n-- tuple, in the order the table's type wrote its members:\n--\n--     const point = { x: 1, y: \"up\" }\n--     point:keys()     -- [\"x\", \"y\"]\n--     point:values()   -- [number, string]\n--     point:entries()  -- [[\"x\", number], [\"y\", string]]\n--\n-- A Lua table has no order of its own, so the compiler hands its runtime the\n-- keys as the type lists them. An optional member keeps its place, holding\n-- `nil` when it is missing; an indexer's keys follow the named ones. A\n-- member of the table's own with one of these names is what a call reaches,\n-- and a class instance, which has a metatable of its own, has none of them.\ndeclare metatable<T extends {}> T: {\n    __index: {\n        keys: (self: T) => ObjectKeys<T>,\n        values: (self: T) => ObjectValues<T>,\n        entries: (self: T) => ObjectEntries<T>,\n    },\n}\n";
+declare const PRELUDE_SOURCE = "\n-- In Luau only `nil` and `false` are falsy: `0` and `\"\"` are truthy.\n-- These are what truthiness narrowing computes, made available to write down.\ntype Falsy = nil | false\ntype Truthy<T> = T - Falsy\n\n-- `-` is set difference. Over a union it drops members; over a concrete type\n-- it simplifies away; over an opaque type (`unknown`, an unresolved parameter)\n-- it is kept, so `Exclude<unknown, 1>` stays `unknown - 1`.\ntype Exclude<T, U> = T - U\ntype Extract<T, U> = T extends U ? T : never\ntype NonNullable<T> = T - nil\n\ntype ReturnType<T> = T extends (...args: unknown[]) => infer R ? R : never\ntype Parameters<T> = T extends (...args: infer P) => unknown ? P : never\n\ntype Partial<T> = { [K in keyof T]?: T[K] }\ntype Required<T> = { [K in keyof T]-?: T[K] }\ntype Readonly<T> = { readonly [K in keyof T]: T[K] }\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] }\n\ntype Pick<T, K> = { [P in K]: T[P] }\ntype Omit<T, K> = Pick<T, Exclude<keyof T, K>>\ntype Record<K, V> = { [P in K]: V }\n\n-- ============================================================\n-- The metatables of the language's own values\n-- ============================================================\n\n-- A string's methods. The first group is Lua's string library, which a\n-- string really answers to; where Lua answers several values, tilua answers\n-- one, as the global functions do (`find` is an array, `gsub` the new\n-- string). The second group is written the way JavaScript writes it.\n--\n-- Positions are Lua's: `sub` and `slice` count from 1, and `indexOf` is\n-- `nil` when the text is not there.\ndeclare metatable string: {\n    __index: {\n        upper: (self: string) => string,\n        lower: (self: string) => string,\n        len: (self: string) => number,\n        sub: (self: string, i: number, j?: number) => string,\n        rep: (self: string, n: number, separator?: string) => string,\n        reverse: (self: string) => string,\n        format: (self: string, ...args: unknown[]) => string,\n        byte: ((self: string, i?: number) => number) & ((self: string, i: number, j: number) => number[]),\n        find: (self: string, pattern: string, init?: number, plain?: boolean) => [number, number, ...string[]] | nil,\n        match: (self: string, pattern: string, init?: number) => [...string[]] | nil,\n        gmatch: (self: string, pattern: string) => () => [string, ...string[]] | nil,\n        gsub: (self: string, pattern: string, replacement: unknown, n?: number) => string,\n\n        trim: (self: string) => string,\n        trimStart: (self: string) => string,\n        trimEnd: (self: string) => string,\n        startsWith: (self: string, text: string) => boolean,\n        endsWith: (self: string, text: string) => boolean,\n        includes: (self: string, text: string) => boolean,\n        indexOf: (self: string, text: string, start?: number) => number | nil,\n        slice: (self: string, start?: number, stop?: number) => string,\n        replace: (self: string, text: string, replacement: string) => string,\n        replaceAll: (self: string, text: string, replacement: string) => string,\n        padStart: (self: string, length: number, padding?: string) => string,\n        padEnd: (self: string, length: number, padding?: string) => string,\n    },\n}\n\n-- An array's methods. Lua gives an array no metatable: the compiler lowers\n-- each call to a plain function, so they work on any array, one a Lua\n-- library made included.\n--\n-- Indices are Lua's: the first element is 1, and `indexOf` / `findIndex`\n-- answer `nil` rather than JavaScript's -1. `sort` takes Lua's comparator\n-- (true when `a` comes first). `push`, `pop`, `shift`, `unshift`,\n-- `sort` and `reverse` change the array; everything else returns a new one.\n-- A `filter` whose test is a guard \u2014 `v is S`, or `v => v ~= nil` \u2014\n-- answers an array of what it let through.\ndeclare metatable<T> T[]: {\n    __index: {\n        find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,\n        findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,\n        filter: (<S extends T>(self: T[], test: (value: T, index: number) => value is S) => S[])\n            & ((self: T[], test: (value: T, index: number) => boolean) => T[]),\n        map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],\n        forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,\n        some: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        every: (self: T[], test: (value: T, index: number) => boolean) => boolean,\n        reduce: <U>(self: T[], step: (total: U, value: T, index: number) => U, initial: U) => U,\n        includes: (self: T[], value: T) => boolean,\n        indexOf: (self: T[], value: T, start?: number) => number | nil,\n        join: (self: T[], separator?: string) => string,\n        concat: (self: T[], ...others: T[][]) => T[],\n        slice: (self: T[], start?: number, stop?: number) => T[],\n        flat: (self: T[]) => T[],\n        reverse: (self: T[]) => T[],\n        sort: (self: T[], compare?: (a: T, b: T) => boolean) => T[],\n        push: (self: T[], ...args: T[]) => number,\n        pop: (self: T[]) => T | nil,\n        shift: (self: T[]) => T | nil,\n        unshift: (self: T[], ...args: T[]) => number,\n    },\n}\n\n-- A table's methods. Unlike JavaScript's `Object.keys`, they answer a\n-- tuple, in the order the table's type wrote its members:\n--\n--     const point = { x: 1, y: \"up\" }\n--     point:keys()     -- [\"x\", \"y\"]\n--     point:values()   -- [number, string]\n--     point:entries()  -- [[\"x\", number], [\"y\", string]]\n--\n-- A Lua table has no order of its own, so the compiler hands its runtime the\n-- keys as the type lists them. An optional member keeps its place, holding\n-- `nil` when it is missing; an indexer's keys follow the named ones. A\n-- member of the table's own with one of these names is what a call reaches,\n-- and a class instance, which has a metatable of its own, has none of them.\ndeclare metatable<T extends {}> T: {\n    __index: {\n        keys: (self: T) => ObjectKeys<T>,\n        values: (self: T) => ObjectValues<T>,\n        entries: (self: T) => ObjectEntries<T>,\n    },\n}\n";
 
 interface ProjectHost {
     /** A file's text, or `undefined` when there is no such file. */

package/dist/index.js

@@ -3788,6 +3788,10 @@ var Analyzer = class {
   moduleScope = this.globalScope;
   /** How many function bodies enclose the walk. */
   functionDepth = 0;
+  /** How many loops enclose the walk inside the nearest function body. A
+   *  function starts again at 0: `continue` in `xs:map(x => ...)` has no
+   *  loop to go on with, whatever loop the call is written in. */
+  loopDepth = 0;
   /** Function declarations already declared by their block's hoisting, with
    *  the function depth of that block. */
   hoisted = /* @__PURE__ */ new Map();
@@ -4140,11 +4144,11 @@ var Analyzer = class {
         return;
       case "WhileStatement":
         this.visitExpression(stmt.condition, scope);
-        this.visitBlockInNewScope(stmt.body, scope);
+        this.inLoop(() => this.visitBlockInNewScope(stmt.body, scope));
         return;
       case "RepeatStatement": {
         const bodyScope = childScope(scope);
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         this.visitExpression(stmt.condition, bodyScope);
         return;
       }
@@ -4162,14 +4166,14 @@ var Analyzer = class {
         if (stmt.step) this.visitExpression(stmt.step, scope);
         const bodyScope = childScope(scope);
         this.declare(bodyScope, stmt.variable.name, "for-numeric", stmt.variable);
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         return;
       }
       case "GenericForStatement": {
         this.visitExpression(stmt.iterator, scope);
         const bodyScope = childScope(scope);
         this.declarePattern(bodyScope, stmt.variable, "for-generic", scope, stmt.kind === "const");
-        this.visitBlock(stmt.body, bodyScope);
+        this.inLoop(() => this.visitBlock(stmt.body, bodyScope));
         return;
       }
       case "ReturnStatement":
@@ -4177,6 +4181,15 @@ var Analyzer = class {
         return;
       case "BreakStatement":
       case "ContinueStatement":
+        if (this.loopDepth === 0) {
+          const word = stmt.type === "BreakStatement" ? "break" : "continue";
+          this.diagnostics.push({
+            node: stmt,
+            message: this.functionDepth > 0 ? `'${word}' is not inside a loop of this function; to skip a value in a callback, 'return' from it` : `'${word}' is not inside a loop`,
+            kind: "outside-loop"
+          });
+        }
+        return;
       case "ErrorStatement":
         return;
       case "DeclareStatement":
@@ -4232,6 +4245,15 @@ var Analyzer = class {
         return;
     }
   }
+  /** Visit a loop's body, where `break` and `continue` have a loop. */
+  inLoop(visit) {
+    this.loopDepth++;
+    try {
+      visit();
+    } finally {
+      this.loopDepth--;
+    }
+  }
   // ---------------- functions ----------------
   visitFunctionBody(func, outerScope, isMethod = false) {
     const fnScope = childScope(outerScope);
@@ -4247,11 +4269,14 @@ var Analyzer = class {
       }
     });
     this.visitType(func.returnType, fnScope);
+    const loops = this.loopDepth;
     this.functionDepth++;
+    this.loopDepth = 0;
     try {
       this.visitBlock(func.body, fnScope);
     } finally {
       this.functionDepth--;
+      this.loopDepth = loops;
     }
   }
   /** An overload signature: no body and no bindings, but its types can hold
@@ -4505,11 +4530,14 @@ declare metatable string: {
 -- answer \`nil\` rather than JavaScript's -1. \`sort\` takes Lua's comparator
 -- (true when \`a\` comes first). \`push\`, \`pop\`, \`shift\`, \`unshift\`,
 -- \`sort\` and \`reverse\` change the array; everything else returns a new one.
+-- A \`filter\` whose test is a guard \u2014 \`v is S\`, or \`v => v ~= nil\` \u2014
+-- answers an array of what it let through.
 declare metatable<T> T[]: {
     __index: {
         find: (self: T[], test: (value: T, index: number) => boolean) => T | nil,
         findIndex: (self: T[], test: (value: T, index: number) => boolean) => number | nil,
-        filter: (self: T[], test: (value: T, index: number) => boolean) => T[],
+        filter: (<S extends T>(self: T[], test: (value: T, index: number) => value is S) => S[])
+            & ((self: T[], test: (value: T, index: number) => boolean) => T[]),
         map: <U>(self: T[], transform: (value: T, index: number) => U) => U[],
         forEach: (self: T[], visit: (value: T, index: number) => nil) => nil,
         some: (self: T[], test: (value: T, index: number) => boolean) => boolean,
@@ -4648,8 +4676,14 @@ function substitute(t, subst) {
   if (subst.size === 0) return t;
   if (!containsTypeParam(t)) return t;
   switch (t.kind) {
-    case "typeParam":
-      return subst.get(t.name) ?? t;
+    case "typeParam": {
+      const bound = subst.get(t.name);
+      if (bound) return bound;
+      if (t.constraint && containsTypeParam(t.constraint)) {
+        return { ...t, constraint: substitute(t.constraint, new Map([...subst, [t.name, t]])) };
+      }
+      return t;
+    }
     case "array":
       return { ...arrayOf(substitute(t.element, subst)), readonly: t.readonly };
     case "tuple":
@@ -4794,6 +4828,10 @@ function unify(param, arg, vars, out, how = "union") {
       if (arg.kind === "function") {
         param.params.forEach((p, i) => arg.params[i] && unify(p.type, arg.params[i].type, vars, out));
         unify(param.returns, arg.returns, vars, out);
+        const wanted = param.predicate, given = arg.predicate;
+        if (wanted?.type && given?.type && wanted.param === given.param && !wanted.asserts && !given.asserts) {
+          unify(wanted.type, given.type, vars, out);
+        }
       }
       return;
     case "object":
@@ -5049,6 +5087,11 @@ function isAssignableInner(a, b) {
     for (let i = 0; i < n; i++) {
       if (!isAssignable(a.params[i].type, b.params[i].type) && !isAssignable(b.params[i].type, a.params[i].type)) return false;
     }
+    const wanted = b.predicate;
+    if (wanted?.type && !wanted.asserts) {
+      const given = a.predicate;
+      if (!given?.type || given.asserts || given.param !== wanted.param || !isAssignable(given.type, wanted.type)) return false;
+    }
     return isAssignable(a.returns, b.returns);
   }
   if (b.kind === "typeParam") return false;
@@ -5183,7 +5226,7 @@ function containsFreeTypeParam(t, seen, bound) {
       return [...t.properties.values()].some((v) => containsTypeParam(v.type, seen, bound)) || !!t.indexer && (containsTypeParam(t.indexer.key, seen, bound) || containsTypeParam(t.indexer.value, seen, bound));
     case "function": {
       const inner = t.typeParams?.length ? /* @__PURE__ */ new Set([...bound, ...t.typeParams]) : bound;
-      return t.params.some((p) => containsTypeParam(p.type, seen, inner)) || !!t.varargs && containsTypeParam(t.varargs, seen, inner) || containsTypeParam(t.returns, seen, inner);
+      return t.params.some((p) => containsTypeParam(p.type, seen, inner)) || !!t.varargs && containsTypeParam(t.varargs, seen, inner) || containsTypeParam(t.returns, seen, inner) || !!t.predicate?.type && containsTypeParam(t.predicate.type, seen, inner);
     }
     case "genericRef":
       return t.typeArguments.some((a) => containsTypeParam(a, seen, bound));
@@ -5608,9 +5651,14 @@ function isFreshLiteralExpr(e) {
     case "StringLiteral":
     case "BooleanLiteral":
     case "InterpolatedStringExpression":
+      return true;
+    // A table or array literal widened the literals written in it as it
+    // was read (`widenUnlessAsked`), and keeps what it read from
+    // elsewhere — `{ key: name }`, `[...names]` — so there is nothing
+    // left for the binding to widen.
     case "TableExpression":
     case "ArrayExpression":
-      return true;
+      return false;
     case "ParenthesizedExpression":
       return isFreshLiteralExpr(e.expression);
     case "UnaryExpression":
@@ -5625,6 +5673,30 @@ function isFreshLiteralExpr(e) {
       return false;
   }
 }
+function overloadTier(f) {
+  const takesGuard = f.params.some((p) => p.type.kind === "function" && p.type.predicate?.type && !p.type.predicate.asserts);
+  if (takesGuard) return 0;
+  return (f.typeParams?.length ?? 0) > 0 ? 2 : 1;
+}
+function writesLiteral(e) {
+  switch (e.type) {
+    case "NumberLiteral":
+    case "StringLiteral":
+    case "BooleanLiteral":
+    case "InterpolatedStringExpression":
+      return true;
+    case "ParenthesizedExpression":
+      return writesLiteral(e.expression);
+    case "UnaryExpression":
+      return writesLiteral(e.argument);
+    case "IfElseExpression":
+      return e.clauses.some((c) => writesLiteral(c.body)) || writesLiteral(e.alternate);
+    case "BinaryExpression":
+      return (e.operator === "or" || e.operator === "and") && (writesLiteral(e.left) || writesLiteral(e.right));
+    default:
+      return false;
+  }
+}
 function collectInferNames(node) {
   const out = [];
   const walk = (n) => {
@@ -8007,7 +8079,9 @@ var TypeAnalyzer = class {
     const waits = written.map((a, i) => this.waitsOnInference(a, expected[i]));
     if (!waits.some(Boolean)) return written.map((a) => this.infer(a, env));
     const argTypes = written.map((a, i) => waits[i] ? this.quietly(() => this.infer(a, env)) : this.infer(a, env));
-    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), this.spreadOf(written, selfOf(fns[0])));
+    const spread = this.spreadOf(written, selfOf(fns[0]));
+    const provisional = argTypes.map((t, i) => waits[i] ? anyType : t);
+    const picked = this.pickOverload(fns, argTypes, (f) => extra(f, argTypes), spread) ?? this.pickOverload(fns, provisional, (f) => extra(f, provisional), spread);
     const subst = picked?.typeParams?.length ? this.inferTypeArgs(picked, extra(picked, argTypes)) : void 0;
     written.forEach((a, i) => {
       if (!waits[i]) return;
@@ -8198,6 +8272,16 @@ var TypeAnalyzer = class {
       }
       const id = this.bindingIdByName(p.name, p);
       const t = this.paramType(p, env);
+      if (p.default && p.typeAnnotation) {
+        const given = this.infer(p.default, env);
+        const declared = this.resolveType(p.typeAnnotation);
+        if (this.emitDiagnostics && !isAssignable(given, declared)) {
+          this.diagnostics.push({
+            node: p.default,
+            message: `Type '${briefType(given)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(given, declared)
+          });
+        }
+      }
       if (id !== void 0) {
         this.bindingType.set(id, t);
         this.setBinding(env, id, t);
@@ -8295,9 +8379,9 @@ var TypeAnalyzer = class {
    *  lets `typeof` declare `(v: number) -> "number"` alongside a trailing
    *  `<T>(v: T) -> string` and still pick the precise one. */
   pickOverload(fns, argTypes, argsFor, spread) {
-    for (const generic of [false, true]) {
+    for (const tier of [0, 1, 2]) {
       for (const f of fns) {
-        if ((f.typeParams?.length ?? 0) > 0 !== generic) continue;
+        if (overloadTier(f) !== tier) continue;
         if (this.overloadAccepts(f, argsFor ? argsFor(f) : argTypes, spread)) return f;
       }
     }
@@ -8323,7 +8407,7 @@ var TypeAnalyzer = class {
     if (position < 0) return void 0;
     const members = this.expand(argTypes[position]).types;
     if (members.length > 32) return void 0;
-    const rank = (f) => ((f.typeParams?.length ?? 0) > 0 ? fns.length : 0) + fns.indexOf(f);
+    const rank = (f) => overloadTier(f) * fns.length + fns.indexOf(f);
     const limit = picked ? rank(picked) : Infinity;
     const results = [];
     for (const member of members) {
@@ -8716,10 +8800,38 @@ var TypeAnalyzer = class {
         returns,
         void 0,
         names,
-        this.resolvePredicate(func.predicate, params)
+        func.predicate || func.returnType ? this.resolvePredicate(func.predicate, params) : this.inferPredicate(func, params, returns, bodyEnv)
       ), func.params);
     });
   }
+  /** `v => v ~= nil` is a guard without saying so, as TypeScript reads it:
+   *  a body that is one `return` of a boolean which, true, narrows a
+   *  parameter — and, false, leaves it exactly what that excludes. Then
+   *  `list:filter(v => v ~= nil)` knows what it kept. */
+  inferPredicate(func, params, returns, env) {
+    const only = func.body.statements.length === 1 ? func.body.statements[0] : void 0;
+    if (only?.type !== "ReturnStatement" || !only.argument) return void 0;
+    if (returns.kind === "any" || returns.kind === "never" || !isAssignable(returns, booleanType)) return void 0;
+    const cond = only.argument;
+    for (let i = 0; i < params.length; i++) {
+      const p = func.params[i];
+      if (p.pattern || p.rest) continue;
+      const id = this.bindingIdByName(p.name, p);
+      if (id === void 0) continue;
+      const declared = params[i].type;
+      const key = bindKey(id);
+      const t = forkEnv(env);
+      const f = forkEnv(env);
+      this.silently(() => this.applyNarrowing(cond, env, t, f));
+      const yes = t.get(key);
+      if (!yes || equalTypes(yes, declared) || !isAssignable(yes, declared)) continue;
+      const no = this.expand(f.get(key) ?? declared);
+      const rest = no.kind === "union" ? no.types : [no];
+      if (rest.some((m) => m.kind !== "never" && isAssignable(m, yes))) continue;
+      return { param: i, type: yes, asserts: false };
+    }
+    return void 0;
+  }
   /** Where the return types of the function being walked are collected, so
    *  each is read where it is written — inside the branch that narrowed it —
    *  rather than in whatever state the body ends in. */
@@ -9841,6 +9953,27 @@ var TypeAnalyzer = class {
           elseEnv = whenFalse;
         }
         branches.push(this.infer(expr.alternate, elseEnv));
+        const bodies = [...expr.clauses.map((c) => c.body), expr.alternate].map(unwrapParens);
+        const isEmpty = (e) => e.type === "TableExpression" && e.fields.length === 0 || e.type === "ArrayExpression" && e.elements.length === 0;
+        const others = union(branches.filter((_, i) => !isEmpty(bodies[i])));
+        const parts = (others.kind === "union" ? others.types : [others]).map((m) => this.expand(m)).filter((m) => !(m.kind === "primitive" && m.name === "nil"));
+        const fits = (e) => {
+          if (!parts.length) return void 0;
+          if (e.type === "ArrayExpression") {
+            if (parts.every((m) => m.kind === "array")) return others;
+            return parts.every((m) => m.kind === "array" || m.kind === "tuple") ? tuple([]) : void 0;
+          }
+          return parts.every((m) => m.kind === "object" && !m.class && [...m.properties.values()].every((prop) => prop.optional)) ? others : void 0;
+        };
+        if (bodies.some(isEmpty) && others.kind !== "never" && others.kind !== "any" && bodies.every((body) => !isEmpty(body) || fits(body))) {
+          const typed = bodies.map((body, i) => {
+            if (!isEmpty(body)) return branches[i];
+            const t = fits(body);
+            this.typeOf.set(body, t);
+            return t;
+          });
+          return union(typed);
+        }
         return union(branches);
       }
     }
@@ -10147,23 +10280,87 @@ var TypeAnalyzer = class {
     if (wantedTuple && !asConst) return this.inferTupleLiteral(expr, env, wantedTuple);
     const elems = [];
     let hadSpread = false;
+    const written = [];
     for (const el of expr.elements) {
       if (el.type === "SpreadElement") {
         hadSpread = true;
-        const s = this.infer(el.argument, env);
-        if (s.kind === "array") elems.push(s.element);
-        else if (s.kind === "tuple") elems.push(...s.elements);
-        else elems.push(unknownType);
+        const spread = this.infer(el.argument, env);
+        written.push({ spread: true, type: spread });
+        elems.push(...this.spreadElements(spread));
       } else {
-        elems.push(asConst ? this.inferAsConst(el, env) : this.infer(el, env));
+        const t = asConst ? this.inferAsConst(el, env) : this.infer(el, env);
+        written.push({ spread: false, type: asConst ? t : this.widenUnlessAsked(t, el) });
+        elems.push(t);
       }
     }
     if (asConst && !hadSpread) return tuple(elems);
+    if (hadSpread) {
+      const tuples = this.spreadTuples(written);
+      if (tuples) return union(tuples.map((elements) => tuple(elements)));
+    }
     return arrayOf(elems.length ? union(elems.map((t, i) => {
       const element = expr.elements[i];
       return asConst || !element || element.type === "SpreadElement" ? t : this.widenUnlessAsked(t, element);
     })) : unknownType);
   }
+  /** The tuples an array literal with spreads is, when every spread is a
+   *  tuple of known length or a union of them: one per way the unions go.
+   *  `undefined` when a spread's length is not known (an array, a tuple
+   *  with a rest), or the ways multiply past what is worth listing. */
+  spreadTuples(written) {
+    const MAX = 32;
+    let variants = [[]];
+    for (const { spread, type } of written) {
+      if (!spread) {
+        variants = variants.map((v) => [...v, type]);
+        continue;
+      }
+      const options = this.fixedTuples(type);
+      if (!options) return void 0;
+      const next = [];
+      for (const v of variants) for (const option of options) next.push([...v, ...option]);
+      if (next.length > MAX) return void 0;
+      variants = next;
+    }
+    return variants;
+  }
+  /** A tuple of known length's members, or a union of such tuples' — each
+   *  a way the value can be. `nil` in a union spreads nothing. */
+  fixedTuples(t, depth = 0) {
+    if (depth > 8) return void 0;
+    const held = this.expand(t);
+    if (held.kind === "tuple") return held.rest ? void 0 : [held.elements];
+    if (held.kind !== "union") return void 0;
+    const out = [];
+    for (const member of held.types) {
+      if (member.kind === "primitive" && member.name === "nil") continue;
+      const options = this.fixedTuples(member, depth + 1);
+      if (!options) return void 0;
+      out.push(...options);
+    }
+    return out.length ? out : void 0;
+  }
+  /** What `...xs` puts into an array: an array's element, a tuple's members,
+   *  and for a union each member's — `...(host ? extra : [])` adds `extra`'s
+   *  elements and the empty tuple nothing. Anything else, `unknown`. */
+  spreadElements(t, depth = 0) {
+    const held = this.expand(t);
+    if (depth > 8) return [unknownType];
+    switch (held.kind) {
+      case "array":
+        return [held.element];
+      case "tuple":
+        return tupleMembers(held);
+      case "union":
+        return held.types.filter((m) => !(m.kind === "primitive" && m.name === "nil")).flatMap((m) => this.spreadElements(m, depth + 1));
+      case "typeParam":
+        return held.constraint ? this.spreadElements(held.constraint, depth + 1) : [unknownType];
+      case "any":
+        return [anyType];
+      default:
+        return [unknownType];
+    }
+  }
   /** `[a, b, ...more]` where a tuple is wanted: the places it names are the
    *  tuple's, and what comes after them — more elements, or a spread — is
    *  its rest. */
@@ -10174,10 +10371,7 @@ var TypeAnalyzer = class {
     expr.elements.forEach((element, i) => {
       if (element.type === "SpreadElement") {
         spread = true;
-        const held = this.expand(this.infer(element.argument, env));
-        if (held.kind === "array") tail.push(held.element);
-        else if (held.kind === "tuple") tail.push(...tupleMembers(held));
-        else tail.push(unknownType);
+        tail.push(...this.spreadElements(this.infer(element.argument, env)));
         return;
       }
       const t = this.widenUnlessAsked(this.infer(element, env), element);
@@ -10194,6 +10388,7 @@ var TypeAnalyzer = class {
    *  The context was recorded by `applyContext` before the value was
    *  inferred, so this is a lookup rather than a second pass. */
   widenUnlessAsked(value, at) {
+    if (!writesLiteral(at)) return value;
     const wanted = this.expectedTypeOf.get(at);
     if (value.kind === "literal") {
       const arms = this.contextArms.get(at);

package/package.json

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