@tilua/parser 3.0.0 → 3.1.0

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   CONFIG_FILE_NAMES: () => CONFIG_FILE_NAMES,
   Keywords: () => Keywords,
   LANGUAGE_GLOBALS: () => LANGUAGE_GLOBALS,
+  LUAU_KEYWORDS: () => LUAU_KEYWORDS,
   LexError: () => LexError,
   Operators: () => Operators,
   PRELUDE_SOURCE: () => PRELUDE_SOURCE,
@@ -45,20 +46,27 @@ __export(index_exports, {
   difference: () => difference,
   directivesOf: () => directivesOf,
   equalTypes: () => equalTypes,
+  escapeLuauString: () => escapeLuauString,
   falsyType: () => falsyType,
   findConfig: () => findConfig,
   fn: () => fn,
   formatType: () => formatType,
   getBinding: () => getBinding,
+  hasMembers: () => hasMembers,
   intersection: () => intersection,
   isAssignable: () => isAssignable,
   isClassType: () => isClassType,
+  isFunctionType: () => isFunctionType,
   isGlobal: () => isGlobal,
+  isIdentifier: () => isIdentifier,
+  isInstanceOf: () => isInstanceOf,
+  isLuauName: () => isLuauName,
   isPossiblyFalsy: () => isPossiblyFalsy,
   isPossiblyTruthy: () => isPossiblyTruthy,
   isUnassignedGlobal: () => isUnassignedGlobal,
   literal: () => literal,
   loadConfig: () => loadConfig,
+  luauString: () => luauString,
   matchInfer: () => matchInfer,
   moduleCandidates: () => moduleCandidates,
   moduleExports: () => moduleExports,
@@ -81,6 +89,7 @@ __export(index_exports, {
   readDirectives: () => readDirectives,
   resolveModulePath: () => resolveModulePath,
   resolveTypeLibraries: () => resolveTypeLibraries,
+  returnsTuple: () => returnsTuple,
   setAliasExpander: () => setAliasExpander,
   setDeferredBound: () => setDeferredBound,
   sourceMapTypes: () => sourceMapTypes,
@@ -99,7 +108,8 @@ __export(index_exports, {
   unknownType: () => unknownType,
   widen: () => widen,
   withAliasName: () => withAliasName,
-  withoutAliasName: () => withoutAliasName
+  withoutAliasName: () => withoutAliasName,
+  withoutNil: () => withoutNil2
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -708,7 +718,7 @@ function bindThis(func, at) {
   func.isMethod = true;
 }
 function bindThisParam(params, at) {
-  params.unshift({ type: "FunctionParameter", name: "this", ...spanFrom(at, at) });
+  params.unshift({ type: "FunctionParameter", name: "this", implicit: true, ...spanFrom(at, at) });
 }
 var ParseError = class extends Error {
   constructor(message, line, column) {
@@ -1765,7 +1775,7 @@ var Parser = class {
         };
       }
       if (isMethod) {
-        func.params.unshift({ type: "FunctionParameter", name: "self", ...spanFrom(target, target) });
+        func.params.unshift({ type: "FunctionParameter", name: "self", implicit: true, ...spanFrom(target, target) });
         func.isMethod = true;
       }
       return {
@@ -1959,47 +1969,7 @@ var Parser = class {
     const isStatic = modifiers.has("static");
     if (this.checkKeyword("function")) {
       this.advance();
-      const memberName = this.parseIdentifier();
-      if (modifiers.has("abstract")) {
-        const head = this.parseFunctionHead();
-        const func = {
-          type: "FunctionBody",
-          generics: head.generics,
-          params: head.params,
-          hasVarargs: head.hasVarargs,
-          returnType: head.returnType,
-          predicate: head.predicate,
-          body: { type: "Block", statements: [], ...spanFrom(head.start, this.previous()) },
-          ...spanFrom(head.start, this.previous())
-        };
-        if (!isStatic) bindThis(func, start);
-        if (!head.returnType) this.problem("An abstract method has no body to infer from: write its return type");
-        if (this.checkPunctuator("{")) this.problem("An abstract method has no body");
-        return { type: "ClassMethod", name: memberName, isStatic, func, isAbstract: true, ...spanFrom(start, this.previous()) };
-      }
-      const signatures = [];
-      let written = memberName;
-      while (true) {
-        const head = this.parseFunctionHead();
-        if (this.isClassOverloadContinuation(memberName.name, isStatic)) {
-          if (!isStatic) bindThisParam(head.params, start);
-          signatures.push({ ...this.headToSignature(head), name: written });
-          if (isStatic) this.advance();
-          this.expectKeyword("function");
-          written = this.parseIdentifier();
-          continue;
-        }
-        const func = this.headToBody(head, start);
-        if (!isStatic) bindThis(func, start);
-        return {
-          type: "ClassMethod",
-          name: memberName,
-          isStatic,
-          func,
-          signatures: signatures.length ? signatures : void 0,
-          ...spanFrom(start, this.previous())
-        };
-      }
+      return this.parseClassMethod(start, modifiers);
     }
     if (!isStatic && this.checkIdentifierValue("constructor") && this.punctuatorAt(1, "(")) {
       this.advance();
@@ -2009,6 +1979,9 @@ var Parser = class {
       bindThis(func, start);
       return { type: "ClassConstructor", func, ...spanFrom(start, this.previous()) };
     }
+    if (this.startsMethodShorthand(0)) {
+      return this.parseClassMethod(start, modifiers);
+    }
     if ((this.checkIdentifierValue("get") || this.checkIdentifierValue("set")) && this.peek(1).type === "Identifier" && this.punctuatorAt(2, "(")) {
       const kind = this.advance().value;
       const memberName = this.parseIdentifier();
@@ -2038,25 +2011,90 @@ var Parser = class {
       return { type: "ClassField", name: memberName, isStatic, typeAnnotation, init, ...spanFrom(start, this.previous()) };
     }
     if (this.recover) {
-      this.softError("Expected a class member: a field, 'function', 'constructor', 'get' or 'set'");
+      this.softError("Expected a class member: a field, a method, 'constructor', 'get' or 'set'");
       this.advance();
       return void 0;
     }
-    this.error("Expected a class member: a field, 'function', 'constructor', 'get' or 'set'");
+    this.error("Expected a class member: a field, a method, 'constructor', 'get' or 'set'");
+  }
+  /** A name at `offset` opening a method without `function`: `name(` or
+   *  `name<T>(`. A field's name is followed by `:` or `=` instead. */
+  startsMethodShorthand(offset) {
+    if (this.peek(offset).type !== "Identifier") return false;
+    const next = this.peek(offset + 1);
+    return (next.type === "Punctuator" || next.type === "Operator") && (next.value === "(" || next.value === "<");
+  }
+  /** A method, from its name on: `function` (if written) and the modifiers
+   *  are behind. */
+  parseClassMethod(start, modifiers) {
+    const isStatic = modifiers.has("static");
+    const memberName = this.parseIdentifier();
+    if (modifiers.has("abstract")) {
+      const head = this.parseFunctionHead();
+      const func = {
+        type: "FunctionBody",
+        generics: head.generics,
+        params: head.params,
+        hasVarargs: head.hasVarargs,
+        returnType: head.returnType,
+        predicate: head.predicate,
+        body: { type: "Block", statements: [], ...spanFrom(head.start, this.previous()) },
+        ...spanFrom(head.start, this.previous())
+      };
+      if (!isStatic) bindThis(func, start);
+      if (!head.returnType) this.problem("An abstract method has no body to infer from: write its return type");
+      if (this.checkPunctuator("{")) this.problem("An abstract method has no body");
+      return { type: "ClassMethod", name: memberName, isStatic, func, isAbstract: true, ...spanFrom(start, this.previous()) };
+    }
+    const signatures = [];
+    let written = memberName;
+    while (true) {
+      const head = this.parseFunctionHead();
+      const skip = this.classOverloadContinuation(memberName.name, isStatic);
+      if (skip !== void 0) {
+        if (!isStatic) bindThisParam(head.params, start);
+        signatures.push({ ...this.headToSignature(head), name: written });
+        for (let i = 0; i < skip; i++) this.advance();
+        written = this.parseIdentifier();
+        continue;
+      }
+      const func = this.headToBody(head, start);
+      if (!isStatic) bindThis(func, start);
+      return {
+        type: "ClassMethod",
+        name: memberName,
+        isStatic,
+        func,
+        signatures: signatures.length ? signatures : void 0,
+        ...spanFrom(start, this.previous())
+      };
+    }
   }
-  /** Give a class method its `this`: a real first parameter, the way
-   *  `function T:m()` gets a real `self`. Every later pass — scopes, types,
-   *  arity, lowering — then sees an ordinary parameter and needs to know
-   *  nothing about classes. */
   /** After a bodyless head inside a class body, does another declaration of
-   *  the same member follow? Then the head was an overload signature. */
-  isClassOverloadContinuation(name, isStatic) {
-    const offset = isStatic ? 1 : 0;
-    if (isStatic && !this.checkIdentifierValue("static")) return false;
+   *  the same member follow? Then the head was an overload signature, and
+   *  this is how many tokens stand before the next one's name: a `;` that
+   *  ends the head, as TypeScript writes it, the modifiers, and `function`
+   *  when it is written. `undefined` when no overload follows. Each head may
+   *  be written either way, with `function` or without. */
+  classOverloadContinuation(name, isStatic) {
+    let offset = 0;
+    if (this.punctuatorAt(0, ";")) offset++;
+    let sawStatic = false;
+    while (true) {
+      const t = this.peek(offset);
+      const word = t.type === "Identifier" ? t.value : void 0;
+      if (word === void 0 || !CLASS_MODIFIERS.has(word) || this.startsMethodShorthand(offset)) break;
+      if (word === "static") sawStatic = true;
+      offset++;
+    }
+    if (sawStatic !== isStatic) return void 0;
     const keyword = this.peek(offset);
-    if (!(keyword.type === "Keyword" && keyword.value === "function")) return false;
-    const named = this.peek(offset + 1);
-    return named.type === "Identifier" && named.value === name;
+    const hasKeyword = keyword.type === "Keyword" && keyword.value === "function";
+    if (hasKeyword) offset++;
+    const named = this.peek(offset);
+    if (!(named.type === "Identifier" && named.value === name)) return void 0;
+    if (!hasKeyword && !this.startsMethodShorthand(offset)) return void 0;
+    return offset;
   }
   operatorAt(ahead, value) {
     const token = this.peek(ahead);
@@ -3893,6 +3931,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 +4287,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 +4309,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 +4324,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 +4388,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 +4412,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 +4673,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,11 +4714,34 @@ declare metatable<T> T[]: {
 -- \`nil\` when it is missing; an indexer's keys follow the named ones. A
 -- member of the table's own with one of these names is what a call reaches,
 -- and a class instance, which has a metatable of its own, has none of them.
+--
+-- The rest are JavaScript's \`Object\` functions, written as methods of the
+-- table they take first:
+--
+--     point:hasOwn("x")           -- Object.hasOwn(point, "x")
+--     point:assign({ z: 3 })      -- Object.assign(point, { z: 3 })
+--     point:freeze()              -- Object.freeze(point)
+--
+-- \`hasOwn\` asks the table itself, not what its metatable's \`__index\`
+-- lends it. \`assign\` copies each source's members onto the table, later ones
+-- over earlier ones, skipping a \`nil\` source, and answers the table. \`freeze\`
+-- is Luau's \`table.freeze\`; under Lua 5.1, which cannot freeze a table, the
+-- table is answered as it is and \`isFrozen\` is false.
 declare metatable<T extends {}> T: {
     __index: {
         keys: (self: T) => ObjectKeys<T>,
         values: (self: T) => ObjectValues<T>,
         entries: (self: T) => ObjectEntries<T>,
+
+        hasOwn: (self: T, key: unknown) => boolean,
+        hasOwnProperty: (self: T, key: unknown) => boolean,
+        assign: (<U>(self: T, source: U) => T & U)
+            & (<U, V>(self: T, a: U, b: V) => T & U & V)
+            & (<U, V, W>(self: T, a: U, b: V, c: W) => T & U & V & W)
+            -- Generic like the rest: a plain signature would be tried first.
+            & (<S extends {}>(self: T, ...sources: S[]) => T),
+        freeze: (self: T) => Readonly<T>,
+        isFrozen: (self: T) => boolean,
     },
 }
 `;
@@ -4753,8 +4842,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 +4994,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 +5253,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 +5392,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 +5817,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 +5839,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 +8245,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 +8438,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 +8545,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 +8573,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 +8966,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 +10119,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 +10446,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 +10537,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 +10554,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);
@@ -11671,7 +11927,53 @@ function aliasTargets(config, specifier) {
 
 // src/project/sourcemap.ts
 var import_node_path4 = require("path");
+
+// src/luau.ts
+var LUAU_KEYWORDS = /* @__PURE__ */ new Set([
+  "and",
+  "break",
+  "do",
+  "else",
+  "elseif",
+  "end",
+  "false",
+  "for",
+  "function",
+  "if",
+  "in",
+  "local",
+  "nil",
+  "not",
+  "or",
+  "repeat",
+  "return",
+  "then",
+  "true",
+  "until",
+  "while"
+]);
 var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isIdentifier(name) {
+  return IDENTIFIER.test(name);
+}
+function isLuauName(name) {
+  return IDENTIFIER.test(name) && !LUAU_KEYWORDS.has(name);
+}
+var NAMED_ESCAPES = {
+  "\\": "\\\\",
+  '"': '\\"',
+  "\n": "\\n",
+  "\r": "\\r",
+  "	": "\\t"
+};
+function escapeLuauString(text) {
+  return text.replace(/[\\"\x00-\x1f\x7f]/g, (c) => NAMED_ESCAPES[c] ?? `\\${c.charCodeAt(0).toString().padStart(3, "0")}`);
+}
+function luauString(text) {
+  return `"${escapeLuauString(text)}"`;
+}
+
+// src/project/sourcemap.ts
 var INSTANCE_MEMBERS = /* @__PURE__ */ new Set(["Name", "ClassName", "Parent", "Archivable"]);
 var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".tilua", ".luau", ".lua"]);
 function sourceMapTypes(text, path, options) {
@@ -11698,7 +12000,7 @@ function sourceMapTypes(text, path, options) {
     const alias = aliasFor(segments);
     aliasOfNode.set(node, alias);
     for (const filePath of node.filePaths ?? []) aliasOfFile.set(fileKey((0, import_node_path4.resolve)(directory, filePath)), alias);
-    const className = IDENTIFIER.test(node.className) && options.classes.has(node.className) ? node.className : "Instance";
+    const className = isIdentifier(node.className) && options.classes.has(node.className) ? node.className : "Instance";
     const taken = options.membersOf?.(className) ?? INSTANCE_MEMBERS;
     const members = [];
     if (parent) members.push(`Parent: ${parent}`);
@@ -11707,7 +12009,7 @@ function sourceMapTypes(text, path, options) {
       if (!isNode(child)) continue;
       const childAlias = visit(child, [...segments, child.name], alias);
       const service = child.name === child.className && options.classes.has(child.className);
-      if (!IDENTIFIER.test(child.name) || taken.has(child.name) && !service || named.has(child.name)) continue;
+      if (!isIdentifier(child.name) || taken.has(child.name) && !service || named.has(child.name)) continue;
       named.add(child.name);
       members.push(`${child.name}: ${childAlias}`);
     }
@@ -11749,6 +12051,34 @@ function fileKey(path) {
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
+// src/loweringHelpers.ts
+function withoutNil2(type) {
+  if (!type) return [];
+  const members = type.kind === "union" ? type.types : [type];
+  return members.filter((m) => !(m.kind === "primitive" && m.name === "nil"));
+}
+function isFunctionType(type) {
+  const members = withoutNil2(type);
+  return members.length > 0 && members.every((m) => m.kind === "function" || m.kind === "intersection" && m.types.every(isFunctionType));
+}
+function everyObject(type, test) {
+  const members = withoutNil2(type);
+  return members.length > 0 && members.every((m) => m.kind === "object" && test(m));
+}
+function isInstanceOf(type, className) {
+  return everyObject(type, (m) => m.class !== void 0 && m.class.ancestors.includes(className));
+}
+function hasMembers(type, names) {
+  return everyObject(type, (m) => names.every((name) => m.properties.has(name)));
+}
+function returnsTuple(receiver, method) {
+  return everyObject(receiver, (m) => {
+    const found = m.properties.get(method)?.type;
+    const signatures = !found ? [] : found.kind === "intersection" ? found.types : [found];
+    return signatures.length > 0 && signatures.every((f) => f.kind === "function" && f.returns.kind === "tuple");
+  });
+}
+
 // src/index.ts
 var tilua = {
   tokenize,
@@ -11769,6 +12099,7 @@ var index_default = tilua;
   CONFIG_FILE_NAMES,
   Keywords,
   LANGUAGE_GLOBALS,
+  LUAU_KEYWORDS,
   LexError,
   Operators,
   PRELUDE_SOURCE,
@@ -11789,20 +12120,27 @@ var index_default = tilua;
   difference,
   directivesOf,
   equalTypes,
+  escapeLuauString,
   falsyType,
   findConfig,
   fn,
   formatType,
   getBinding,
+  hasMembers,
   intersection,
   isAssignable,
   isClassType,
+  isFunctionType,
   isGlobal,
+  isIdentifier,
+  isInstanceOf,
+  isLuauName,
   isPossiblyFalsy,
   isPossiblyTruthy,
   isUnassignedGlobal,
   literal,
   loadConfig,
+  luauString,
   matchInfer,
   moduleCandidates,
   moduleExports,
@@ -11825,6 +12163,7 @@ var index_default = tilua;
   readDirectives,
   resolveModulePath,
   resolveTypeLibraries,
+  returnsTuple,
   setAliasExpander,
   setDeferredBound,
   sourceMapTypes,
@@ -11843,5 +12182,6 @@ var index_default = tilua;
   unknownType,
   widen,
   withAliasName,
-  withoutAliasName
+  withoutAliasName,
+  withoutNil
 });