@tilua/parser 1.0.0 → 1.0.1

package/dist/index.cjs

@@ -5211,6 +5211,7 @@ function mergeObjectMembers(types) {
 var INTERNAL_MEMBERS = /* @__PURE__ */ new Set(["ClassObject", "ParentClass"]);
 var MAX_MISSING = 3;
 var MAX_EXPLANATION = 90;
+var MAX_TYPE = 120;
 function analyzeTypes(program, scopes, options = {}) {
   return new TypeAnalyzer(program, scopes, options).run();
 }
@@ -5589,6 +5590,7 @@ var TypeAnalyzer = class {
   narrowedTypeOf = /* @__PURE__ */ new Map();
   typeOfTypeNode = /* @__PURE__ */ new Map();
   expectedTypeOf = /* @__PURE__ */ new Map();
+  iteratesValues = /* @__PURE__ */ new Set();
   /** Public: each alias resolved once (generic aliases keep their params as
    *  `typeParam` nodes in the body). */
   aliases = new AliasMap();
@@ -5669,6 +5671,7 @@ var TypeAnalyzer = class {
       typeOfTypeNode: this.typeOfTypeNode,
       expectedTypeOf: this.expectedTypeOf,
       aliases: this.resolveDeferredAliases(),
+      iteratesValues: this.iteratesValues,
       diagnostics: this.diagnostics
     };
   }
@@ -6162,7 +6165,7 @@ var TypeAnalyzer = class {
             if (declared && this.emitDiagnostics && !isAssignable(actual, declared)) {
               this.diagnostics.push({
                 node: member.init,
-                message: `Type '${formatType(actual)}' is not assignable to type '${formatType(declared)}'` + this.explainMismatch(actual, declared)
+                message: `Type '${briefType(actual)}' is not assignable to type '${briefType(declared)}'` + this.explainMismatch(actual, declared)
               });
             }
             continue;
@@ -6349,7 +6352,7 @@ var TypeAnalyzer = class {
     if (fits) return;
     this.diagnostics.push({
       node: stmt,
-      message: `Type '${formatType(actual)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(actual, declared)
+      message: `Type '${briefType(actual)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(actual, declared)
     });
   }
   /** A function that declared what it returns but never does. Only a body
@@ -7009,7 +7012,7 @@ var TypeAnalyzer = class {
             if (declared.kind !== "any" && !this.namesNothing(declared) && !this.fitsAnnotation(source, declared, inferred, env)) {
               this.diagnostics.push({
                 node: stmt,
-                message: `Type '${formatType(inferred)}' is not assignable to '${formatType(declared)}'` + this.explainMismatch(inferred, declared)
+                message: `Type '${briefType(inferred)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(inferred, declared)
               });
             } else if (declared.kind !== "any") {
               this.reportExcessProperties(source, declared);
@@ -7103,7 +7106,7 @@ var TypeAnalyzer = class {
                 if (this.emitDiagnostics && !isAssignable(next, declared) && declared.kind !== "any") {
                   this.diagnostics.push({
                     node: stmt,
-                    message: `Type '${formatType(next)}' is not assignable to '${formatType(declared)}'` + this.explainMismatch(next, declared)
+                    message: `Type '${briefType(next)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(next, declared)
                   });
                 }
                 this.setBinding(env, id, narrowTo(declared, next));
@@ -7188,21 +7191,23 @@ var TypeAnalyzer = class {
           const valueId = value.type === "IdentifierPattern" ? this.bindingIdByName(value.name, value) : void 0;
           if (keyId !== void 0 && valueId !== void 0) this.correlateBindings(bodyEnv, [keyId, valueId], rows);
         } else {
-          const [keyT, valT] = this.iterationTypes(stmt.iterators[0], iterTypes[0], stmt.variables.length);
+          const [keyT, valT, iteratesValues] = this.iterationTypes(stmt.iterators[0], iterTypes[0], stmt.variables.length);
           stmt.variables.forEach((v, i) => {
             this.bindPattern(v, i === 0 ? keyT : i === 1 ? valT : unknownType, bodyEnv, "widen");
           });
+          if (iteratesValues && stmt.iterators.length === 1) this.iteratesValues.add(stmt);
         }
         this.visitBlock(stmt.body, bodyEnv);
         return;
       }
       case "ReturnStatement": {
         const declared = this.declaredReturns[this.declaredReturns.length - 1];
-        if (declared) {
+        const wanted = declared ?? this.contextualReturns[this.contextualReturns.length - 1];
+        if (wanted) {
           if (stmt.arguments.length === 1) {
-            this.applyContext(stmt.arguments[0], declared);
-          } else if (declared.kind === "tuple" && declared.isPack) {
-            stmt.arguments.forEach((a, i) => this.applyContext(a, declared.elements[i]));
+            this.applyContext(stmt.arguments[0], wanted);
+          } else if (wanted.kind === "tuple" && wanted.isPack) {
+            stmt.arguments.forEach((a, i) => this.applyContext(a, wanted.elements[i]));
           }
         }
         const want = declared?.kind === "tuple" && declared.isPack ? declared.elements.length : 0;
@@ -7431,6 +7436,17 @@ var TypeAnalyzer = class {
   /** What a function expression's unannotated parameters are, from where
    *  it is written — see `applyContext`. */
   contextualParams = /* @__PURE__ */ new WeakMap();
+  /** What a function expression written in a typed position returns, from
+   *  that position — see `applyContext`. A body with no `return` annotation
+   *  would otherwise infer its `return` expressions with nothing wanted of
+   *  them, and widen the literals in them: `() => S = function() { return
+   *  { Status: true } }` inferred `Status: boolean` and then failed against
+   *  `S`. It is a hint, not a contract: only `applyContext` reads it, so a
+   *  body that does not match still reports at the assignment, not here. */
+  contextualReturnOf = /* @__PURE__ */ new WeakMap();
+  /** `contextualReturnOf` for each function body being walked, alongside
+   *  `declaredReturns`. */
+  contextualReturns = [];
   /** `expected` is the type the surroundings want for `expr`. A function
    *  expression written there takes its unannotated parameters' types from
    *  it, as in TypeScript: `signal:Connect(function(player) ... end)` knows
@@ -7453,6 +7469,10 @@ var TypeAnalyzer = class {
     const members = expected.kind === "union" ? expected.types : [expected];
     const signatures = members.flatMap((m) => this.overloadsOf(this.expand(m)));
     if (!signatures.length) return;
+    if (!e.func.returnType && !e.func.predicate) {
+      const returns = signatures.map((s) => s.returns).filter((t) => !containsTypeParam(t));
+      if (returns.length) this.contextualReturnOf.set(e.func, union(returns));
+    }
     e.func.params.forEach((p, k) => {
       if (p.typeAnnotation || p.pattern || p.default) return;
       const candidates = [];
@@ -7496,7 +7516,9 @@ var TypeAnalyzer = class {
         return property ? [property.type] : o.indexer ? [o.indexer.value] : [];
       });
       if (types.length) {
-        this.applyContext(field.type === "TableFieldShorthand" ? field.name : field.value, union(types));
+        const target = field.type === "TableFieldShorthand" ? field.name : field.value;
+        this.contextArms.set(target, types);
+        this.applyContext(target, union(types));
       }
     }
   }
@@ -7557,11 +7579,13 @@ var TypeAnalyzer = class {
   withVarargs(func, body) {
     this.varargs.push(this.varargElement(func));
     this.declaredReturns.push(func.predicate ? booleanType : func.returnType ? this.resolveType(func.returnType) : void 0);
+    this.contextualReturns.push(this.contextualReturnOf.get(func));
     try {
       return body();
     } finally {
       this.varargs.pop();
       this.declaredReturns.pop();
+      this.contextualReturns.pop();
     }
   }
   visitFunctionBodyInner(func, outerEnv) {
@@ -8203,22 +8227,26 @@ var TypeAnalyzer = class {
     if (ids.length < 2) return;
     this.correlateBindings(env, ids, objects.map((member) => names.map((name) => this.propertyType(member, name))));
   }
-  /** `(keyType, valueType)` yielded by a generic-for iterator. Handles
-   *  `ipairs`/`pairs`/`next(t)` and Luau generalized iteration (`for … in t`).
-   *  `varCount` is how many loop variables were written. */
+  /** `(keyType, valueType, iteratesValues)` yielded by a generic-for
+   *  iterator. Handles `ipairs`/`pairs`/`next(t)` and Luau generalized
+   *  iteration (`for … in t`). `varCount` is how many loop variables were
+   *  written. `iteratesValues` reports the one case where the first variable
+   *  is bound to the value rather than the key, which is what lowering has
+   *  to know to emit the loop; see `TypeAnalysis.iteratesValues`. */
   iterationTypes(iterNode, iterType, varCount) {
     if (iterNode?.type === "CallExpression" && iterNode.callee.type === "Identifier" && iterNode.arguments[0]) {
       const name = iterNode.callee.name;
       const src = this.expand(this.typeOf.get(iterNode.arguments[0]) ?? unknownType);
-      if (name === "ipairs") return [numberType, this.elementType(src, 0)];
+      if (name === "ipairs") return [numberType, this.elementType(src, 0), false];
       if (name === "pairs" || name === "next") {
         if (src.kind === "object") {
           return [
             src.indexer?.key ?? stringType,
-            src.indexer?.value ?? union([...src.properties.values()].map((p) => p.type))
+            src.indexer?.value ?? union([...src.properties.values()].map((p) => p.type)),
+            false
           ];
         }
-        if (src.kind === "array") return [numberType, src.element];
+        if (src.kind === "array") return [numberType, src.element, false];
       }
     }
     const iterator = this.expand(iterType);
@@ -8226,16 +8254,18 @@ var TypeAnalyzer = class {
       const returns = this.expand(iterator.returns);
       const parts = returns.kind === "tuple" ? returns.elements.map((m) => this.expand(m)) : [returns];
       const at = (i) => parts[i] ?? (parts.length === 1 ? parts[0] : unknownType);
-      return [at(0), at(1)];
+      return [at(0), at(1), false];
     }
     const t = this.expand(iterType);
-    if (t.kind === "array") return varCount >= 2 ? [numberType, t.element] : [t.element, unknownType];
+    if (t.kind === "array") {
+      return varCount >= 2 ? [numberType, t.element, false] : [t.element, unknownType, true];
+    }
     if (t.kind === "object") {
       const k = t.indexer?.key ?? stringType;
       const v = t.indexer?.value ?? union([...t.properties.values()].map((p) => p.type));
-      return varCount >= 2 ? [k, v] : [v, unknownType];
+      return varCount >= 2 ? [k, v, false] : [v, unknownType, true];
     }
-    return [unknownType, unknownType];
+    return [unknownType, unknownType, false];
   }
   inferReturnType(body, env) {
     const returns = [];
@@ -8681,7 +8711,7 @@ var TypeAnalyzer = class {
         if (!isAssignable(narrow, declared) && !isAssignable(actual, declared)) {
           this.diagnostics.push({
             node: expr,
-            message: `Type '${formatType(actual)}' does not satisfy the expected type '${formatType(declared)}'`
+            message: `Type '${briefType(actual)}' does not satisfy the expected type '${briefType(declared)}'` + this.explainMismatch(actual, declared)
           });
         } else {
           this.reportExcessProperties(expr.expression, declared);
@@ -9060,8 +9090,16 @@ var TypeAnalyzer = class {
    *  inferred, so this is a lookup rather than a second pass. */
   widenUnlessAsked(value, at) {
     const wanted = this.expectedTypeOf.get(at);
+    if (value.kind === "literal") {
+      const arms = this.contextArms.get(at);
+      if (arms?.some((arm) => this.admitsLiteral(arm, value.base))) return value;
+    }
     return wanted === void 0 ? widen(value) : this.keepContextualLiterals(value, wanted);
   }
+  /** What each arm of the contract wanted of an expression, unmerged — see
+   *  `widenUnlessAsked`. Recorded by `applyTableContext` beside the merged
+   *  type it hands to `applyContext`. */
+  contextArms = /* @__PURE__ */ new WeakMap();
   inferObject(expr, env, asConst) {
     const entries = [];
     let indexer;
@@ -9770,8 +9808,9 @@ var TypeAnalyzer = class {
    *  themselves are then the whole story. */
   explainMismatch(actual, expected) {
     const from = this.expand(actual);
-    const to = this.expand(expected);
-    if (from.kind !== "object" || to.kind !== "object") return "";
+    if (from.kind !== "object") return "";
+    const to = this.likeliestArm(from, this.expand(expected));
+    if (to === void 0) return "";
     const missing = [];
     for (const [name, property] of to.properties) {
       if (property.optional || from.properties.has(name) || INTERNAL_MEMBERS.has(name)) continue;
@@ -9796,6 +9835,34 @@ var TypeAnalyzer = class {
     }
     return "";
   }
+  /** Which object of a contract the value was reaching for. One object is
+   *  itself; among several, a discriminant decides — the arm whose literal
+   *  properties the value already agrees with (`Status: true` picks
+   *  `StatSuccess` over `StatError`). Failing that, the arm it is closest to
+   *  fitting, so the explanation is about the shortest gap rather than an
+   *  arbitrary one. `undefined` when there is no object to explain against. */
+  likeliestArm(from, expected) {
+    const arms = this.membersOf(expected).filter((m) => m.kind === "object");
+    if (arms.length <= 1) return arms[0];
+    const gapOf = (arm) => {
+      let gap = 0;
+      for (const [name, property] of arm.properties) {
+        if (INTERNAL_MEMBERS.has(name)) continue;
+        const own = from.properties.get(name);
+        if (!own) {
+          if (!property.optional) gap += 1;
+          continue;
+        }
+        if (isAssignable(own.type, property.type)) continue;
+        gap += this.expand(property.type).kind === "literal" ? 100 : 1;
+      }
+      for (const name of from.properties.keys()) {
+        if (!INTERNAL_MEMBERS.has(name) && !arm.properties.has(name) && !arm.indexer) gap += 1;
+      }
+      return gap;
+    };
+    return arms.reduce((best, arm) => gapOf(arm) < gapOf(best) ? arm : best);
+  }
   bindingIdOf(id) {
     return this.scopes.bindingOf.get(id);
   }
@@ -9842,7 +9909,15 @@ function briefType(t) {
     const shown = t.types.slice(0, 6).map(formatType).join(" | ");
     return `${shown} | ... ${t.types.length - 6} more`;
   }
-  return formatType(t);
+  const full = formatType(t);
+  if (full.length <= MAX_TYPE) return full;
+  if (t.kind === "object" && t.properties.size) {
+    const names = [...t.properties.keys()].filter((n) => !INTERNAL_MEMBERS.has(n));
+    const shown = names.slice(0, MAX_MISSING);
+    const rest = names.length - shown.length;
+    return `{ ${shown.join(", ")}${rest > 0 ? `, ... ${rest} more` : ""} }`;
+  }
+  return `${full.slice(0, MAX_TYPE)}...`;
 }
 
 // src/project/host.ts

package/dist/index.d.cts

@@ -1405,6 +1405,13 @@ interface TypeAnalysis {
     /** Top-level type aliases, resolved — and the type names this module
      *  imports, so tooling treats both alike. */
     readonly aliases: Map<string, Type>;
+    /** The `for x in t` loops that walk a table directly, where tilua's one
+     *  variable takes the *value* — not an iterator such as `pairs(t)` or
+     *  `string.gmatch(s, p)`, whose variables are bound as written. Luau hands
+     *  the key over first, so lowering these needs a key variable in front.
+     *  Deciding that here keeps it next to the types the same choice produces:
+     *  the variable's type and the code bound to it cannot drift apart. */
+    readonly iteratesValues: ReadonlySet<GenericForStatement>;
     readonly diagnostics: TypeDiagnostic[];
 }
 /** A type a module exports: the resolved type, plus the parameter names of a

package/dist/index.d.ts

@@ -1405,6 +1405,13 @@ interface TypeAnalysis {
     /** Top-level type aliases, resolved — and the type names this module
      *  imports, so tooling treats both alike. */
     readonly aliases: Map<string, Type>;
+    /** The `for x in t` loops that walk a table directly, where tilua's one
+     *  variable takes the *value* — not an iterator such as `pairs(t)` or
+     *  `string.gmatch(s, p)`, whose variables are bound as written. Luau hands
+     *  the key over first, so lowering these needs a key variable in front.
+     *  Deciding that here keeps it next to the types the same choice produces:
+     *  the variable's type and the code bound to it cannot drift apart. */
+    readonly iteratesValues: ReadonlySet<GenericForStatement>;
     readonly diagnostics: TypeDiagnostic[];
 }
 /** A type a module exports: the resolved type, plus the parameter names of a

package/dist/index.js

@@ -5108,6 +5108,7 @@ function mergeObjectMembers(types) {
 var INTERNAL_MEMBERS = /* @__PURE__ */ new Set(["ClassObject", "ParentClass"]);
 var MAX_MISSING = 3;
 var MAX_EXPLANATION = 90;
+var MAX_TYPE = 120;
 function analyzeTypes(program, scopes, options = {}) {
   return new TypeAnalyzer(program, scopes, options).run();
 }
@@ -5486,6 +5487,7 @@ var TypeAnalyzer = class {
   narrowedTypeOf = /* @__PURE__ */ new Map();
   typeOfTypeNode = /* @__PURE__ */ new Map();
   expectedTypeOf = /* @__PURE__ */ new Map();
+  iteratesValues = /* @__PURE__ */ new Set();
   /** Public: each alias resolved once (generic aliases keep their params as
    *  `typeParam` nodes in the body). */
   aliases = new AliasMap();
@@ -5566,6 +5568,7 @@ var TypeAnalyzer = class {
       typeOfTypeNode: this.typeOfTypeNode,
       expectedTypeOf: this.expectedTypeOf,
       aliases: this.resolveDeferredAliases(),
+      iteratesValues: this.iteratesValues,
       diagnostics: this.diagnostics
     };
   }
@@ -6059,7 +6062,7 @@ var TypeAnalyzer = class {
             if (declared && this.emitDiagnostics && !isAssignable(actual, declared)) {
               this.diagnostics.push({
                 node: member.init,
-                message: `Type '${formatType(actual)}' is not assignable to type '${formatType(declared)}'` + this.explainMismatch(actual, declared)
+                message: `Type '${briefType(actual)}' is not assignable to type '${briefType(declared)}'` + this.explainMismatch(actual, declared)
               });
             }
             continue;
@@ -6246,7 +6249,7 @@ var TypeAnalyzer = class {
     if (fits) return;
     this.diagnostics.push({
       node: stmt,
-      message: `Type '${formatType(actual)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(actual, declared)
+      message: `Type '${briefType(actual)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(actual, declared)
     });
   }
   /** A function that declared what it returns but never does. Only a body
@@ -6906,7 +6909,7 @@ var TypeAnalyzer = class {
             if (declared.kind !== "any" && !this.namesNothing(declared) && !this.fitsAnnotation(source, declared, inferred, env)) {
               this.diagnostics.push({
                 node: stmt,
-                message: `Type '${formatType(inferred)}' is not assignable to '${formatType(declared)}'` + this.explainMismatch(inferred, declared)
+                message: `Type '${briefType(inferred)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(inferred, declared)
               });
             } else if (declared.kind !== "any") {
               this.reportExcessProperties(source, declared);
@@ -7000,7 +7003,7 @@ var TypeAnalyzer = class {
                 if (this.emitDiagnostics && !isAssignable(next, declared) && declared.kind !== "any") {
                   this.diagnostics.push({
                     node: stmt,
-                    message: `Type '${formatType(next)}' is not assignable to '${formatType(declared)}'` + this.explainMismatch(next, declared)
+                    message: `Type '${briefType(next)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(next, declared)
                   });
                 }
                 this.setBinding(env, id, narrowTo(declared, next));
@@ -7085,21 +7088,23 @@ var TypeAnalyzer = class {
           const valueId = value.type === "IdentifierPattern" ? this.bindingIdByName(value.name, value) : void 0;
           if (keyId !== void 0 && valueId !== void 0) this.correlateBindings(bodyEnv, [keyId, valueId], rows);
         } else {
-          const [keyT, valT] = this.iterationTypes(stmt.iterators[0], iterTypes[0], stmt.variables.length);
+          const [keyT, valT, iteratesValues] = this.iterationTypes(stmt.iterators[0], iterTypes[0], stmt.variables.length);
           stmt.variables.forEach((v, i) => {
             this.bindPattern(v, i === 0 ? keyT : i === 1 ? valT : unknownType, bodyEnv, "widen");
           });
+          if (iteratesValues && stmt.iterators.length === 1) this.iteratesValues.add(stmt);
         }
         this.visitBlock(stmt.body, bodyEnv);
         return;
       }
       case "ReturnStatement": {
         const declared = this.declaredReturns[this.declaredReturns.length - 1];
-        if (declared) {
+        const wanted = declared ?? this.contextualReturns[this.contextualReturns.length - 1];
+        if (wanted) {
           if (stmt.arguments.length === 1) {
-            this.applyContext(stmt.arguments[0], declared);
-          } else if (declared.kind === "tuple" && declared.isPack) {
-            stmt.arguments.forEach((a, i) => this.applyContext(a, declared.elements[i]));
+            this.applyContext(stmt.arguments[0], wanted);
+          } else if (wanted.kind === "tuple" && wanted.isPack) {
+            stmt.arguments.forEach((a, i) => this.applyContext(a, wanted.elements[i]));
           }
         }
         const want = declared?.kind === "tuple" && declared.isPack ? declared.elements.length : 0;
@@ -7328,6 +7333,17 @@ var TypeAnalyzer = class {
   /** What a function expression's unannotated parameters are, from where
    *  it is written — see `applyContext`. */
   contextualParams = /* @__PURE__ */ new WeakMap();
+  /** What a function expression written in a typed position returns, from
+   *  that position — see `applyContext`. A body with no `return` annotation
+   *  would otherwise infer its `return` expressions with nothing wanted of
+   *  them, and widen the literals in them: `() => S = function() { return
+   *  { Status: true } }` inferred `Status: boolean` and then failed against
+   *  `S`. It is a hint, not a contract: only `applyContext` reads it, so a
+   *  body that does not match still reports at the assignment, not here. */
+  contextualReturnOf = /* @__PURE__ */ new WeakMap();
+  /** `contextualReturnOf` for each function body being walked, alongside
+   *  `declaredReturns`. */
+  contextualReturns = [];
   /** `expected` is the type the surroundings want for `expr`. A function
    *  expression written there takes its unannotated parameters' types from
    *  it, as in TypeScript: `signal:Connect(function(player) ... end)` knows
@@ -7350,6 +7366,10 @@ var TypeAnalyzer = class {
     const members = expected.kind === "union" ? expected.types : [expected];
     const signatures = members.flatMap((m) => this.overloadsOf(this.expand(m)));
     if (!signatures.length) return;
+    if (!e.func.returnType && !e.func.predicate) {
+      const returns = signatures.map((s) => s.returns).filter((t) => !containsTypeParam(t));
+      if (returns.length) this.contextualReturnOf.set(e.func, union(returns));
+    }
     e.func.params.forEach((p, k) => {
       if (p.typeAnnotation || p.pattern || p.default) return;
       const candidates = [];
@@ -7393,7 +7413,9 @@ var TypeAnalyzer = class {
         return property ? [property.type] : o.indexer ? [o.indexer.value] : [];
       });
       if (types.length) {
-        this.applyContext(field.type === "TableFieldShorthand" ? field.name : field.value, union(types));
+        const target = field.type === "TableFieldShorthand" ? field.name : field.value;
+        this.contextArms.set(target, types);
+        this.applyContext(target, union(types));
       }
     }
   }
@@ -7454,11 +7476,13 @@ var TypeAnalyzer = class {
   withVarargs(func, body) {
     this.varargs.push(this.varargElement(func));
     this.declaredReturns.push(func.predicate ? booleanType : func.returnType ? this.resolveType(func.returnType) : void 0);
+    this.contextualReturns.push(this.contextualReturnOf.get(func));
     try {
       return body();
     } finally {
       this.varargs.pop();
       this.declaredReturns.pop();
+      this.contextualReturns.pop();
     }
   }
   visitFunctionBodyInner(func, outerEnv) {
@@ -8100,22 +8124,26 @@ var TypeAnalyzer = class {
     if (ids.length < 2) return;
     this.correlateBindings(env, ids, objects.map((member) => names.map((name) => this.propertyType(member, name))));
   }
-  /** `(keyType, valueType)` yielded by a generic-for iterator. Handles
-   *  `ipairs`/`pairs`/`next(t)` and Luau generalized iteration (`for … in t`).
-   *  `varCount` is how many loop variables were written. */
+  /** `(keyType, valueType, iteratesValues)` yielded by a generic-for
+   *  iterator. Handles `ipairs`/`pairs`/`next(t)` and Luau generalized
+   *  iteration (`for … in t`). `varCount` is how many loop variables were
+   *  written. `iteratesValues` reports the one case where the first variable
+   *  is bound to the value rather than the key, which is what lowering has
+   *  to know to emit the loop; see `TypeAnalysis.iteratesValues`. */
   iterationTypes(iterNode, iterType, varCount) {
     if (iterNode?.type === "CallExpression" && iterNode.callee.type === "Identifier" && iterNode.arguments[0]) {
       const name = iterNode.callee.name;
       const src = this.expand(this.typeOf.get(iterNode.arguments[0]) ?? unknownType);
-      if (name === "ipairs") return [numberType, this.elementType(src, 0)];
+      if (name === "ipairs") return [numberType, this.elementType(src, 0), false];
       if (name === "pairs" || name === "next") {
         if (src.kind === "object") {
           return [
             src.indexer?.key ?? stringType,
-            src.indexer?.value ?? union([...src.properties.values()].map((p) => p.type))
+            src.indexer?.value ?? union([...src.properties.values()].map((p) => p.type)),
+            false
           ];
         }
-        if (src.kind === "array") return [numberType, src.element];
+        if (src.kind === "array") return [numberType, src.element, false];
       }
     }
     const iterator = this.expand(iterType);
@@ -8123,16 +8151,18 @@ var TypeAnalyzer = class {
       const returns = this.expand(iterator.returns);
       const parts = returns.kind === "tuple" ? returns.elements.map((m) => this.expand(m)) : [returns];
       const at = (i) => parts[i] ?? (parts.length === 1 ? parts[0] : unknownType);
-      return [at(0), at(1)];
+      return [at(0), at(1), false];
     }
     const t = this.expand(iterType);
-    if (t.kind === "array") return varCount >= 2 ? [numberType, t.element] : [t.element, unknownType];
+    if (t.kind === "array") {
+      return varCount >= 2 ? [numberType, t.element, false] : [t.element, unknownType, true];
+    }
     if (t.kind === "object") {
       const k = t.indexer?.key ?? stringType;
       const v = t.indexer?.value ?? union([...t.properties.values()].map((p) => p.type));
-      return varCount >= 2 ? [k, v] : [v, unknownType];
+      return varCount >= 2 ? [k, v, false] : [v, unknownType, true];
     }
-    return [unknownType, unknownType];
+    return [unknownType, unknownType, false];
   }
   inferReturnType(body, env) {
     const returns = [];
@@ -8578,7 +8608,7 @@ var TypeAnalyzer = class {
         if (!isAssignable(narrow, declared) && !isAssignable(actual, declared)) {
           this.diagnostics.push({
             node: expr,
-            message: `Type '${formatType(actual)}' does not satisfy the expected type '${formatType(declared)}'`
+            message: `Type '${briefType(actual)}' does not satisfy the expected type '${briefType(declared)}'` + this.explainMismatch(actual, declared)
           });
         } else {
           this.reportExcessProperties(expr.expression, declared);
@@ -8957,8 +8987,16 @@ var TypeAnalyzer = class {
    *  inferred, so this is a lookup rather than a second pass. */
   widenUnlessAsked(value, at) {
     const wanted = this.expectedTypeOf.get(at);
+    if (value.kind === "literal") {
+      const arms = this.contextArms.get(at);
+      if (arms?.some((arm) => this.admitsLiteral(arm, value.base))) return value;
+    }
     return wanted === void 0 ? widen(value) : this.keepContextualLiterals(value, wanted);
   }
+  /** What each arm of the contract wanted of an expression, unmerged — see
+   *  `widenUnlessAsked`. Recorded by `applyTableContext` beside the merged
+   *  type it hands to `applyContext`. */
+  contextArms = /* @__PURE__ */ new WeakMap();
   inferObject(expr, env, asConst) {
     const entries = [];
     let indexer;
@@ -9667,8 +9705,9 @@ var TypeAnalyzer = class {
    *  themselves are then the whole story. */
   explainMismatch(actual, expected) {
     const from = this.expand(actual);
-    const to = this.expand(expected);
-    if (from.kind !== "object" || to.kind !== "object") return "";
+    if (from.kind !== "object") return "";
+    const to = this.likeliestArm(from, this.expand(expected));
+    if (to === void 0) return "";
     const missing = [];
     for (const [name, property] of to.properties) {
       if (property.optional || from.properties.has(name) || INTERNAL_MEMBERS.has(name)) continue;
@@ -9693,6 +9732,34 @@ var TypeAnalyzer = class {
     }
     return "";
   }
+  /** Which object of a contract the value was reaching for. One object is
+   *  itself; among several, a discriminant decides — the arm whose literal
+   *  properties the value already agrees with (`Status: true` picks
+   *  `StatSuccess` over `StatError`). Failing that, the arm it is closest to
+   *  fitting, so the explanation is about the shortest gap rather than an
+   *  arbitrary one. `undefined` when there is no object to explain against. */
+  likeliestArm(from, expected) {
+    const arms = this.membersOf(expected).filter((m) => m.kind === "object");
+    if (arms.length <= 1) return arms[0];
+    const gapOf = (arm) => {
+      let gap = 0;
+      for (const [name, property] of arm.properties) {
+        if (INTERNAL_MEMBERS.has(name)) continue;
+        const own = from.properties.get(name);
+        if (!own) {
+          if (!property.optional) gap += 1;
+          continue;
+        }
+        if (isAssignable(own.type, property.type)) continue;
+        gap += this.expand(property.type).kind === "literal" ? 100 : 1;
+      }
+      for (const name of from.properties.keys()) {
+        if (!INTERNAL_MEMBERS.has(name) && !arm.properties.has(name) && !arm.indexer) gap += 1;
+      }
+      return gap;
+    };
+    return arms.reduce((best, arm) => gapOf(arm) < gapOf(best) ? arm : best);
+  }
   bindingIdOf(id) {
     return this.scopes.bindingOf.get(id);
   }
@@ -9739,7 +9806,15 @@ function briefType(t) {
     const shown = t.types.slice(0, 6).map(formatType).join(" | ");
     return `${shown} | ... ${t.types.length - 6} more`;
   }
-  return formatType(t);
+  const full = formatType(t);
+  if (full.length <= MAX_TYPE) return full;
+  if (t.kind === "object" && t.properties.size) {
+    const names = [...t.properties.keys()].filter((n) => !INTERNAL_MEMBERS.has(n));
+    const shown = names.slice(0, MAX_MISSING);
+    const rest = names.length - shown.length;
+    return `{ ${shown.join(", ")}${rest > 0 ? `, ... ${rest} more` : ""} }`;
+  }
+  return `${full.slice(0, MAX_TYPE)}...`;
 }
 
 // src/project/host.ts

package/package.json

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