@tilua/parser 1.0.0 → 1.0.2

package/dist/index.cjs

@@ -4498,7 +4498,12 @@ function substitute(t, subst) {
       return t.name && r.kind === "intersection" && !r.name ? { ...r, name: t.name } : r;
     }
     case "genericRef":
-      return { kind: "genericRef", name: t.name, typeArguments: t.typeArguments.map((a) => substitute(a, subst)) };
+      return {
+        kind: "genericRef",
+        name: t.name,
+        typeArguments: t.typeArguments.map((a) => substitute(a, subst)),
+        ...t.origin ? { origin: t.origin } : {}
+      };
     case "keyof":
       return { kind: "keyof", target: substitute(t.target, subst) };
     case "templateLiteral":
@@ -4658,6 +4663,7 @@ function optional(t) {
   return union([t, nilType]);
 }
 function widen(t) {
+  if (isAliasNamed(t)) return t;
   switch (t.kind) {
     case "literal":
       return primitive(t.base);
@@ -4697,7 +4703,7 @@ function isAssignable(rawA, rawB) {
   if (expandAlias) {
     if (a.kind === "genericRef" && b.kind !== "genericRef") a = expandAlias(a);
     else if (b.kind === "genericRef" && a.kind !== "genericRef") b = expandAlias(b);
-    else if (a.kind === "genericRef" && b.kind === "genericRef" && a.name !== b.name) {
+    else if (a.kind === "genericRef" && b.kind === "genericRef" && !sameRefTarget(a, b)) {
       a = expandAlias(a);
       b = expandAlias(b);
     }
@@ -4807,10 +4813,17 @@ function isAssignableInner(a, b) {
   }
   if (b.kind === "typeParam") return false;
   if (a.kind === "genericRef" || b.kind === "genericRef") {
-    return a.kind === "genericRef" && b.kind === "genericRef" && a.name === b.name && a.typeArguments.length === b.typeArguments.length && a.typeArguments.every((x, i) => equalTypes(x, b.typeArguments[i]));
+    return a.kind === "genericRef" && b.kind === "genericRef" && sameRefTarget(a, b) && a.typeArguments.length === b.typeArguments.length && a.typeArguments.every((x, i) => equalTypes(x, b.typeArguments[i]));
   }
   return false;
 }
+function isAliasNamed(t) {
+  if (t.kind === "object" || t.kind === "intersection") return t.name !== void 0;
+  return t.alias !== void 0;
+}
+function sameRefTarget(a, b) {
+  return a.name === b.name && (!a.origin || !b.origin || a.origin === b.origin);
+}
 function isNoValue(t) {
   return t.kind === "tuple" && t.elements.length === 0;
 }
@@ -5211,6 +5224,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,11 +5603,15 @@ 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();
   /** Uninstantiated alias definitions, for `Name<Args>` instantiation. */
   aliasDefs = /* @__PURE__ */ new Map();
+  /** Put on every ref to one of `aliasDefs`, so a module that imports the
+   *  type expands the ref here rather than by its name there. */
+  origin = { expand: (t) => this.expand(t) };
   /** See `resolveClass`. */
   classTypes = /* @__PURE__ */ new WeakMap();
   /** See `instanceType` — one instance type per `class ... end`. */
@@ -5669,6 +5687,7 @@ var TypeAnalyzer = class {
       typeOfTypeNode: this.typeOfTypeNode,
       expectedTypeOf: this.expectedTypeOf,
       aliases: this.resolveDeferredAliases(),
+      iteratesValues: this.iteratesValues,
       diagnostics: this.diagnostics
     };
   }
@@ -6001,7 +6020,8 @@ var TypeAnalyzer = class {
     return {
       kind: "genericRef",
       name: stmt.name.name,
-      typeArguments: params.map((p) => typeParam(p.name, p.constraint ? this.resolveType(p.constraint) : void 0))
+      typeArguments: params.map((p) => typeParam(p.name, p.constraint ? this.resolveType(p.constraint) : void 0)),
+      origin: this.origin
     };
   }
   /** The class table: the statics, what it inherits from the class it
@@ -6162,7 +6182,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 +6369,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
@@ -6566,7 +6586,8 @@ var TypeAnalyzer = class {
             return this.expand({
               kind: "genericRef",
               name: node.base,
-              typeArguments: node.typeArguments.map((a) => this.resolveType(a))
+              typeArguments: node.typeArguments.map((a) => this.resolveType(a)),
+              origin: this.origin
             });
           }
           const imported = this.importedTypes.get(node.base);
@@ -6579,7 +6600,8 @@ var TypeAnalyzer = class {
           return this.expand({
             kind: "genericRef",
             name,
-            typeArguments: node.typeArguments.map((a) => this.resolveType(a))
+            typeArguments: node.typeArguments.map((a) => this.resolveType(a)),
+            origin: this.origin
           });
         }
         return {
@@ -7009,7 +7031,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 +7125,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 +7210,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 +7455,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 +7488,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 +7535,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 +7598,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 +8246,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 +8273,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 = [];
@@ -8378,6 +8427,7 @@ var TypeAnalyzer = class {
    *  resolving, which is what breaks re-entry on a recursive alias. */
   expand(t) {
     if (t.kind !== "genericRef") return t;
+    if (t.origin && t.origin !== this.origin) return t.origin.expand(t);
     const def = this.aliasDefs.get(t.name);
     if (!def) {
       const imported = this.importedTypes.get(t.name);
@@ -8681,7 +8731,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 +9110,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 +9828,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 +9855,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 +9929,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

@@ -1223,6 +1223,15 @@ interface GenericRefType {
     kind: "genericRef";
     name: string;
     typeArguments: Type[];
+    /** The module whose alias this names. A recursive alias is left as a ref
+     *  inside its own structure, and that ref travels with the type into every
+     *  module that imports it — where `name` may mean nothing, or a different
+     *  type. Expanding through `origin` reads the name where it was written. */
+    origin?: TypeOrigin;
+}
+/** A module's own alias resolution, handed out on the refs it creates. */
+interface TypeOrigin {
+    expand(t: GenericRefType): Type;
 }
 /** `keyof T`. */
 interface KeyofType {
@@ -1405,6 +1414,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
@@ -1672,4 +1688,4 @@ declare const tilua: {
     readonly analyzeTypes: typeof analyzeTypes;
 };
 
-export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, type BuildTarget, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassAccessor, type ClassConstructor, type ClassDeclaration, type ClassExpression, type ClassField, type ClassInfo, type ClassLike, type ClassMember, type ClassMethod, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type ExpressionStatement, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NewExpression, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type SuperExpression, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type TiluaConfig, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, aliasNameOf, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, declaredUnknownType, tilua as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, setDeferredBound, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tilua, tokenize, tuple, typeParam, unify, union, unknownType, widen, withAliasName, withoutAliasName };
+export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, type BuildTarget, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassAccessor, type ClassConstructor, type ClassDeclaration, type ClassExpression, type ClassField, type ClassInfo, type ClassLike, type ClassMember, type ClassMethod, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type ExpressionStatement, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NewExpression, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type SuperExpression, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type TiluaConfig, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypeOrigin, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, aliasNameOf, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, declaredUnknownType, tilua as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, setDeferredBound, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tilua, tokenize, tuple, typeParam, unify, union, unknownType, widen, withAliasName, withoutAliasName };

package/dist/index.d.ts

@@ -1223,6 +1223,15 @@ interface GenericRefType {
     kind: "genericRef";
     name: string;
     typeArguments: Type[];
+    /** The module whose alias this names. A recursive alias is left as a ref
+     *  inside its own structure, and that ref travels with the type into every
+     *  module that imports it — where `name` may mean nothing, or a different
+     *  type. Expanding through `origin` reads the name where it was written. */
+    origin?: TypeOrigin;
+}
+/** A module's own alias resolution, handed out on the refs it creates. */
+interface TypeOrigin {
+    expand(t: GenericRefType): Type;
 }
 /** `keyof T`. */
 interface KeyofType {
@@ -1405,6 +1414,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
@@ -1672,4 +1688,4 @@ declare const tilua: {
     readonly analyzeTypes: typeof analyzeTypes;
 };
 
-export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, type BuildTarget, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassAccessor, type ClassConstructor, type ClassDeclaration, type ClassExpression, type ClassField, type ClassInfo, type ClassLike, type ClassMember, type ClassMethod, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type ExpressionStatement, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NewExpression, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type SuperExpression, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type TiluaConfig, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, aliasNameOf, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, declaredUnknownType, tilua as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, setDeferredBound, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tilua, tokenize, tuple, typeParam, unify, union, unknownType, widen, withAliasName, withoutAliasName };
+export { type AnalyzeTypesOptions, type AnyType, type ArrayExpression, type ArrayPattern, type ArrayPatternElement, type ArrayType, type ArrayTypeNode, type AsConstExpression, type AssignmentStatement, type BaseNode, type BaseToken, type BinaryExpression, BinaryOperators, type Binding, type BindingId, type BindingKind, type BindingTarget, type Block, type BooleanLiteral, type BreakStatement, type BuildTarget, CONFIG_FILE_NAMES, type CallExpression, type CallStatement, type ClassAccessor, type ClassConstructor, type ClassDeclaration, type ClassExpression, type ClassField, type ClassInfo, type ClassLike, type ClassMember, type ClassMethod, type CompoundAssignmentStatement, type ConditionalType, type ConditionalTypeNode, type ConfigLookup, type ConfigProblem, type ContinueStatement, type DeclareClassStatement, type DeclareStatement, type DifferenceType, type DifferenceTypeNode, type Directive, type DirectiveKind, type DirectiveOutcome, type Directives, type DoStatement, type EOFToken, type ErrorExpression, type ErrorStatement, type ExportAllStatement, type ExportDefaultStatement, type ExportNamedStatement, type ExportSpecifier, type ExportStatement, type ExportTypeAliasStatement, type ExportedType, type Expression, type ExpressionStatement, type FunctionBody, type FunctionDeclaration, type FunctionDeclarationStatement, type FunctionExpression, type FunctionName, type FunctionParam, type FunctionParameter, type FunctionSignature, type FunctionType, type FunctionTypeNode, type FunctionTypeParameter, type GenericForStatement, type GenericRefType, type GenericTypeParameter, type Identifier, type IdentifierPattern, type IdentifierToken, type IfClause, type IfElseExpression, type IfStatement, type ImportSpecifier, type ImportStatement, type IndexExpression, type IndexedAccessType, type IndexedAccessTypeNode, type InferType, type InferTypeNode, type InterpolatedStringExpression, type InterpolatedStringPart, type InterpolatedStringPart_Expression, type InterpolatedStringPart_String, type InterpolatedStringToken, type IntersectionType, type IntersectionTypeNode, type KeyofType, type KeyofTypeNode, type KeywordToken, Keywords, LexError, type LiteralToken, type LiteralType, type LoweringModule, type LoweringPlugin, type MappedType, type MappedTypeNode, type MemberExpression, type MethodCall, type MethodCallExpression, type MethodLowering, type ModuleExports, type NeverType, type NewExpression, type NilLiteral, type Node, type NumberLiteral, type NumericForStatement, type ObjectPattern, type ObjectPatternProperty, type ObjectProperty, type ObjectType, type OperatorToken, Operators, PRELUDE_SOURCE, type ParenthesizedExpression, type ParenthesizedTypeNode, ParseError, type ParserOptions, type PrimitiveName, type PrimitiveType, type Program, type ProjectHost, type PunctuatorToken, Punctuators, type RecoverResult, type RepeatStatement, type ReturnStatement, type SatisfiesExpression, type ScopeAnalysis, type ScopeDiagnostic, type SourceComment, type SourceMapNode, type SourceMapOptions, type SourceMapTypes, type SpreadElement, type Statement, type StringLiteral, type SuperExpression, type TableExpression, type TableField, type TableTypeNode, type TableTypeProperty, type TemplateLiteralType, type TemplateLiteralTypeNode, type TiluaConfig, type Token, type TokenizeOptions, type TupleType, type TupleTypeNode, type Type, type TypeAliasStatement, type TypeAnalysis, type TypeAssertionExpression, type TypeDiagnostic, type TypeLibraries, type TypeLiteralBoolean, type TypeLiteralNumber, type TypeLiteralString, type TypeNode, type TypeOrigin, type TypePackNode, type TypeParamType, type TypePredicate, type TypePredicateNode, type TypeReference, type TypedIdentifier, type TypeofTypeNode, UNUSED_EXPECT_ERROR, type UnaryExpression, UnaryOperators, type UnionType, type UnionTypeNode, type UnknownType, type VarargExpression, type VariableDeclaration, type VariadicTypeNode, type WhileStatement, aliasNameOf, analyzeScopes, analyzeTypes, anyType, applyDirectives, arrayOf, booleanType, bufferType, containsTypeParam, declaredUnknownType, tilua as default, difference, directivesOf, equalTypes, falsyType, findConfig, fn, formatType, getBinding, intersection, isAssignable, isClassType, isGlobal, isPossiblyFalsy, isPossiblyTruthy, isUnassignedGlobal, literal, loadConfig, matchInfer, moduleCandidates, moduleExports, narrowExclude, narrowFalsy, narrowTo, narrowTruthy, neverType, nilType, nodeHost, numberType, objectType, optional, overlaps, parse, parseExpressionFromSource, parseTokens, parseWithRecovery, primitive, readDirectives, resolveModulePath, resolveTypeLibraries, setAliasExpander, setDeferredBound, sourceMapTypes, stringType, stripJsonComments, substitute, templateMatches, threadType, tilua, tokenize, tuple, typeParam, unify, union, unknownType, widen, withAliasName, withoutAliasName };