@tilua/parser 2.0.0 → 2.1.0

package/README.md

@@ -341,9 +341,11 @@ name: T | nil   -- must be written, but may be nil
 Omitting an argument requires `?` (or a default), as in TypeScript — a
 parameter typed `T | nil` still has to be passed something.
 
-**Optional chaining** — `a?.b` and `a?:m(x)` are nil when `a` is, and then
-nothing further along the chain runs, arguments included: `folder?:FindFirstChild("A")?.Name`
-is a `string | nil`. The `?` must touch the `.` or `:`; `c ? a : b` stays a
+**Optional chaining** — `a?.b`, `a?.[k]`, `a?.(x)` and `a?:m(x)` are nil when
+`a` is, and then nothing further along the chain runs, arguments and the key
+included: `folder?:FindFirstChild("A")?.Name` is a `string | nil`, and
+`maps?.[key]?.label` reads the key only when `maps` is there. The `?` must
+touch the `.` or `:`; `c ? a : b` stays a
 ternary. Parentheses end a chain. A chain cannot be assigned to (`a?.b = 1` is
 an error). A chain that got through narrows what it tested: inside
 `if (part?.Parent)`, and `if (part?.Name == "Door")`, `part` is not nil.
@@ -743,6 +745,17 @@ non-nil part.
 
 Only `nil` and `false` are falsy — `0` and `""` are truthy, unlike JavaScript.
 
+**What Luau raises on is said first.** An operator no metamethod answers takes
+numbers — `..` a string or a number, `#` a string or a table — so `n * 2` with
+`n` a `number | nil` is an error where it is written rather than where it runs.
+A comparison two types can never settle (`s == "c"` with `s` a `"a" | "b"`) is
+one too; a test against `nil` never is, since a map's value and an array's
+element are read as what they hold. A name holds nothing until its line has
+run, a list is indexed by position (`xs["a"]` is not a read), `readonly T[]`
+rules out writing to the list as well as passing it where a `number[]` is
+wanted, a key written twice in one table is reported, and a parameter with no
+type says so — it is `any`, and `any` turns off every check made of it.
+
 **Types** — unions, intersections, tuples `[A, B]` (with a rest, `[A,
 ...B[]]`), `keyof`, `T[K]`, conditional types with
 `infer`, mapped types with `as` remapping, template literal types

package/dist/index.cjs

@@ -2503,6 +2503,21 @@ var Parser = class {
           base = { type: "MemberExpression", object: base, property: prop, optional: true, ...spanFrom(base, prop) };
           continue;
         }
+        if (punct === "." && this.punctuatorAt(2, "[")) {
+          this.advance();
+          this.advance();
+          this.expectPunctuator("[");
+          const index = this.inBrackets(() => this.parseExpression());
+          this.expectPunctuator("]");
+          base = {
+            type: "IndexExpression",
+            object: base,
+            index,
+            optional: true,
+            ...spanFrom(base, this.previous())
+          };
+          continue;
+        }
         if (punct === "." && this.punctuatorAt(2, "(")) {
           this.advance();
           this.advance();
@@ -3256,8 +3271,12 @@ var Parser = class {
    *  `name?: T` for an optional property or parameter. */
   parseSuffixType() {
     if (this.checkIdentifierValue("readonly")) {
+      const start = this.current();
       this.advance();
-      return this.parseSuffixType();
+      const t2 = this.parseSuffixType();
+      if (t2.type === "ArrayTypeNode" || t2.type === "TupleTypeNode") return { ...t2, isReadonly: true };
+      this.problemAt(start, "'readonly' belongs on an array or a tuple: a property is marked where it is written");
+      return t2;
     }
     let t = this.parsePrimaryType();
     while (true) {
@@ -3808,31 +3827,34 @@ var Analyzer = class {
    *  can call it, but a call straight in the block before the declaration
    *  finds nothing there yet. At a module's top level the whole function is
    *  hoisted, and this does not apply. */
-  checkUseBeforeDefine(identifier, id) {
+  checkUseBeforeDefine(identifier, id, at = this.functionDepth) {
     const binding = this.bindings.get(id);
-    if (binding.declaredBy !== "function" && binding.declaredBy !== "class" || this.typeQueryDepth > 0) return;
+    if (this.typeQueryDepth > 0) return;
     const declaration = binding.declarationNode;
-    const depth = declaration && this.hoisted.get(declaration);
-    if (depth === void 0 || depth !== this.functionDepth) return;
+    if (!declaration) return;
+    const hoisted = binding.declaredBy === "function" || binding.declaredBy === "class";
+    const depth = hoisted ? this.hoisted.get(declaration) : this.declaredDepth.get(id);
+    const readable = hoisted || binding.kind === "local";
+    if (!readable || depth === void 0 || depth !== at) return;
     const before = identifier.line.start < declaration.line.start || identifier.line.start === declaration.line.start && identifier.column.start < declaration.column.start;
     if (!before) return;
     this.diagnostics.push({
       node: identifier,
-      message: `'${binding.name}' is used before its definition: inside a function, a function declared further down is only there once its declaration has run`,
+      message: hoisted ? `'${binding.name}' is used before its definition: inside a function, a function declared further down is only there once its declaration has run` : `'${binding.name}' is used before its declaration, and holds nothing until that line has run`,
       kind: "use-before-define"
     });
   }
   noteDeferred(identifier, scope, id, assignment) {
     if (this.functionDepth === 0 && this.typeQueryDepth === 0) return;
     if (this.bindings.get(id).kind !== "global") return;
-    this.deferredGlobals.push({ node: identifier, scope, assignment });
+    this.deferredGlobals.push({ node: identifier, scope, assignment, depth: this.functionDepth });
   }
   /** Point each deferred read of a global at the declaration of that name
    *  that turned up later — in the module, or in any block around the code
    *  that reads it. Such code runs after the declaration has: a closure
    *  written inside a value reads the name the value is bound to. */
   resolveForwardReferences() {
-    for (const { node, scope, assignment } of this.deferredGlobals) {
+    for (const { node, scope, assignment, depth } of this.deferredGlobals) {
       const localId = this.lookup(scope, node.name);
       const globalId = this.bindingOf.get(node);
       if (localId === void 0 || globalId === void 0 || localId === globalId) continue;
@@ -3847,7 +3869,10 @@ var Analyzer = class {
       this.bindingOf.set(node, localId);
       this.bindings.get(localId).references.push(node);
       if (assignment) this.checkConstAssign(localId, node);
-      else if (this.typeQueryDepth === 0) this.checkTypeOnly(localId, node);
+      else if (this.typeQueryDepth === 0) {
+        this.checkTypeOnly(localId, node);
+        this.checkUseBeforeDefine(node, localId, depth);
+      }
     }
   }
   /** Every read of a global nothing declares. A global assigned somewhere
@@ -3878,9 +3903,13 @@ var Analyzer = class {
     }
     const id = this.nextId++;
     this.bindings.set(id, { id, name, kind, declarationNode: node, references: [], isConst, declaredBy });
+    this.declaredDepth.set(id, this.functionDepth);
     scope.declarations.set(name, id);
     return id;
   }
+  /** Which function body each name was declared in. A read of a `const` from
+   *  the same body, but above it, is a read of nothing. */
+  declaredDepth = /* @__PURE__ */ new Map();
   resolve(scope, name) {
     for (let s = scope; s; s = s.parent) {
       const id = s.declarations.get(name);
@@ -4533,9 +4562,9 @@ function substitute(t, subst) {
     case "typeParam":
       return subst.get(t.name) ?? t;
     case "array":
-      return arrayOf(substitute(t.element, subst));
+      return { ...arrayOf(substitute(t.element, subst)), readonly: t.readonly };
     case "tuple":
-      return tuple(t.elements.map((e) => substitute(e, subst)), t.rest && substitute(t.rest, subst));
+      return { ...tuple(t.elements.map((e) => substitute(e, subst)), t.rest && substitute(t.rest, subst)), readonly: t.readonly };
     case "object": {
       const entries = [];
       for (const [k, v] of t.properties) entries.push([k, { ...v, type: substitute(v.type, subst) }]);
@@ -4700,6 +4729,20 @@ function unify(param, arg, vars, out) {
       return;
   }
 }
+function memberKey(t) {
+  switch (t.kind) {
+    case "literal":
+      return `l${t.base}:${String(t.value)}`;
+    case "primitive":
+      return `p${t.name}`;
+    case "any":
+    case "unknown":
+    case "never":
+      return t.kind;
+    default:
+      return formatType(t);
+  }
+}
 function union(types) {
   const flat = [];
   for (const t of types) {
@@ -4711,7 +4754,7 @@ function union(types) {
   const seen = /* @__PURE__ */ new Map();
   for (const t of flat) {
     if (t.kind === "never") continue;
-    const key = formatType(t);
+    const key = memberKey(t);
     if (!seen.has(key)) seen.set(key, t);
   }
   let members = reduceSubtypes([...seen.values()]);
@@ -4740,7 +4783,7 @@ function intersection(types) {
   const seen = /* @__PURE__ */ new Map();
   for (const t of flat) {
     if (t.kind === "unknown") continue;
-    seen.set(formatType(t), t);
+    seen.set(memberKey(t), t);
   }
   const members = [...seen.values()];
   if (members.length === 0) return unknownType;
@@ -4767,9 +4810,9 @@ function widen(t) {
     case "literal":
       return primitive(t.base);
     case "array":
-      return arrayOf(widen(t.element));
+      return { ...arrayOf(widen(t.element)), readonly: t.readonly };
     case "tuple":
-      return tuple(t.elements.map(widen), t.rest && widen(t.rest));
+      return { ...tuple(t.elements.map(widen), t.rest && widen(t.rest)), readonly: t.readonly };
     case "object": {
       if (t.frozen || t.class) return t;
       const entries = [];
@@ -4867,6 +4910,7 @@ function isAssignableInner(a, b) {
     return b.kind === "primitive" && b.name === "string";
   }
   if (a.kind === "primitive") return b.kind === "primitive" && b.name === a.name;
+  if ((a.kind === "array" || a.kind === "tuple") && a.readonly && (b.kind === "array" || b.kind === "tuple") && !b.readonly) return false;
   if (a.kind === "array") {
     if (b.kind === "array") return isAssignable(a.element, b.element);
     if (b.kind === "tuple") return b.elements.length === 0 && !!b.rest && isAssignable(a.element, b.rest);
@@ -5212,10 +5256,10 @@ function formatTypeUncached(t) {
     case "literal":
       return t.base === "string" ? JSON.stringify(t.value) : String(t.value);
     case "array":
-      return `${formatAtom(t.element)}[]`;
+      return `${t.readonly ? "readonly " : ""}${formatAtom(t.element)}[]`;
     case "tuple": {
       const inner = [...t.elements.map(formatType), ...t.rest ? [`...${formatAtom(t.rest)}[]`] : []];
-      return `[${inner.join(", ")}]`;
+      return `${t.readonly ? "readonly " : ""}[${inner.join(", ")}]`;
     }
     case "object": {
       if (t.name) {
@@ -5738,7 +5782,7 @@ function expressionLabel(e, depth = 0) {
     case "IndexExpression": {
       const o = expressionLabel(e.object, depth + 1);
       const i = e.index.type === "StringLiteral" ? JSON.stringify(e.index.value) : e.index.type === "NumberLiteral" ? e.index.raw : e.index.type === "Identifier" ? e.index.name : "...";
-      return o === void 0 ? void 0 : `${o}[${i}]`;
+      return o === void 0 ? void 0 : `${o}${e.optional ? "?." : ""}[${i}]`;
     }
     case "ParenthesizedExpression": {
       const inner = expressionLabel(e.expression, depth + 1);
@@ -5789,7 +5833,8 @@ var TypeAnalyzer = class {
   /** 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`. */
+  /** See `resolveClass`. Shared with other analyses over the same libraries
+   *  when none of their names is redefined here; see `shareableClasses`. */
   classTypes = /* @__PURE__ */ new WeakMap();
   /** See `instanceType` — one instance type per `class ... end`. */
   instanceTypes = /* @__PURE__ */ new WeakMap();
@@ -5835,6 +5880,11 @@ var TypeAnalyzer = class {
   /** Recursion guard for `preVisitBody`. */
   preVisitDepth = 0;
   run() {
+    const shared = shareableClasses(this.options.libs ?? [], this.program);
+    if (shared) {
+      this.classTypes = shared.classTypes;
+      this.classMembers = shared.classMembers;
+    }
     this.registerAliasDefs(preludeProgram().body, true);
     for (const lib of this.options.libs ?? []) this.registerAliasDefs(lib.body, true);
     this.registerAliasDefs(this.program.body);
@@ -7000,14 +7050,17 @@ var TypeAnalyzer = class {
         return literal(node.value);
       case "TypeLiteralNumber":
         return literal(node.value);
-      case "ArrayTypeNode":
-        return arrayOf(this.resolveType(node.element));
+      case "ArrayTypeNode": {
+        const made = arrayOf(this.resolveType(node.element));
+        return node.isReadonly ? { ...made, readonly: true } : made;
+      }
       case "TupleTypeNode": {
         const rest = node.rest && this.expand(this.resolveType(node.rest));
-        return tuple(
+        const made = tuple(
           node.elements.map((e) => this.resolveType(e)),
           rest ? rest.kind === "array" ? rest.element : rest.kind === "any" ? anyType : unknownType : void 0
         );
+        return node.isReadonly && made.kind === "tuple" ? { ...made, readonly: true } : made;
       }
       case "UnionTypeNode":
         return union(node.types.map((t) => this.resolveType(t)));
@@ -7827,8 +7880,19 @@ var TypeAnalyzer = class {
     if (p.rest) return arrayOf(unknownType);
     if (p.pattern) return this.patternToType(p.pattern, env);
     if (p.default) return widen(this.infer(p.default, env));
-    return this.contextualParams.get(p) ?? anyType;
+    const contextual = this.contextualParams.get(p);
+    if (contextual) return contextual;
+    if (this.emitDiagnostics && !receiver && p.name && p.line && !this.untypedParamReported.has(p)) {
+      this.untypedParamReported.add(p);
+      this.diagnostics.push({
+        node: p,
+        message: `Parameter '${p.name}' has no type, so it is 'any': give it one, or a default to read it from`
+      });
+    }
+    return anyType;
   }
+  /** Parameters already spoken about: a body is visited more than once. */
+  untypedParamReported = /* @__PURE__ */ new WeakSet();
   /** What a function expression's unannotated parameters are, from where
    *  it is written — see `applyContext`. */
   contextualParams = /* @__PURE__ */ new WeakMap();
@@ -8123,6 +8187,11 @@ var TypeAnalyzer = class {
    *  this returns `undefined` and the ordinary pick stands. */
   distributedReturn(fns, argTypes, picked, argsFor) {
     if (fns.length < 2) return void 0;
+    if (argTypes.some((t) => this.expand(t).kind === "any")) {
+      const taken = fns.filter((f) => this.overloadAccepts(f, argsFor(f, argTypes)));
+      if (taken.length < 2) return void 0;
+      return union(taken.map((f) => this.callReturn(f, argsFor(f, argTypes))));
+    }
     const position = argTypes.findIndex((t) => this.expand(t).kind === "union");
     if (position < 0) return void 0;
     const members = this.expand(argTypes[position]).types;
@@ -8171,6 +8240,8 @@ var TypeAnalyzer = class {
    *  lone argument cannot be checked against without false errors. */
   boundParams(f) {
     if (!f.typeParams?.length) return f.params.map((p) => p.type);
+    const known = this.boundParamsCache.get(f);
+    if (known) return known;
     const bounds = new Map(f.typeParams.map((name) => [name, anyType]));
     const seen = /* @__PURE__ */ new WeakSet();
     const walk = (value) => {
@@ -8188,8 +8259,11 @@ var TypeAnalyzer = class {
       for (const child of Object.values(value)) walk(child);
     };
     for (const p of f.params) if (containsTypeParam(p.type)) walk(p.type);
-    return f.params.map((p) => this.reduceType(substitute(p.type, bounds)));
+    const bound = f.params.map((p) => this.reduceType(substitute(p.type, bounds)));
+    this.boundParamsCache.set(f, bound);
+    return bound;
   }
+  boundParamsCache = /* @__PURE__ */ new WeakMap();
   /** Record what each written argument is expected to be — see
    *  `TypeAnalysis.expectedTypeOf`. */
   recordExpected(written, fns, selfOf, argsOf = () => []) {
@@ -8653,7 +8727,7 @@ var TypeAnalyzer = class {
   /** What one `for (const item in source)` hands over each time, and how it
    *  walks the source. `pairs`/`ipairs` are read from the table they are
    *  given, so a record's keys stay the literals they are. */
-  iterationOf(source, sourceType) {
+  iterationOf(source, sourceType, report = true) {
     if (source.type === "CallExpression" && source.callee.type === "Identifier" && source.arguments[0]) {
       const name = source.callee.name;
       const src = this.expand(this.typeOf.get(source.arguments[0]) ?? unknownType);
@@ -8691,7 +8765,14 @@ var TypeAnalyzer = class {
     if (t.kind === "object") {
       return [t.indexer?.value ?? union([...t.properties.values()].map((p) => p.type)), values];
     }
-    if (t.kind !== "never" && this.emitDiagnostics) {
+    if (t.kind === "union") {
+      const each = t.types.map((member) => this.iterationOf(source, member, false));
+      const [first] = each;
+      if (first && each.every(([, form]) => form.walks === first[1].walks && form.viaIter === first[1].viaIter)) {
+        return [union(each.map(([item]) => item)), first[1]];
+      }
+    }
+    if (t.kind !== "never" && report && this.emitDiagnostics) {
       this.diagnostics.push({
         node: source,
         message: `Cannot loop over '${formatType(sourceType)}': a loop walks an array, a table, an iterator function or an iteration such as 'pairs(t)'`
@@ -9060,7 +9141,14 @@ var TypeAnalyzer = class {
     const names = keys.map(nameOf);
     const others = keys.filter((_, i) => names[i] === void 0);
     let message;
-    if (others.length && this.cannotIndex(object, others)) {
+    const listOnly = (t) => {
+      const x = this.expand(t);
+      if (x.kind === "union") return x.types.every(listOnly);
+      return x.kind === "array" || x.kind === "tuple";
+    };
+    if (names.some((name) => name !== void 0) && listOnly(withoutNil(this.expand(object)))) {
+      message = `Type '${briefType(index)}' cannot be used to index type '${shown}'`;
+    } else if (others.length && this.cannotIndex(object, others)) {
       message = `Type '${briefType(index)}' cannot be used to index type '${shown}'`;
     } else if (!others.length && names.every((name) => this.memberMissing(object, name))) {
       message = keys.length === 1 ? `Property '${names[0]}' does not exist on type '${shown}'` : `None of ${briefType(index)} is a property of type '${shown}'`;
@@ -9332,10 +9420,18 @@ var TypeAnalyzer = class {
         switch (expr.operator) {
           case "not":
             return booleanType;
-          case "-":
-            return this.operatorResult(expr, "-", arg, void 0) ?? this.arithmeticOn([arg]);
-          case "#":
-            return this.operatorResult(expr, "#", arg, void 0) ?? numberType;
+          case "-": {
+            const answered = this.operatorResult(expr, "-", arg, void 0);
+            if (answered) return answered;
+            this.checkOperands(expr, "-", arg);
+            return this.arithmeticOn([arg]);
+          }
+          case "#": {
+            const answered = this.operatorResult(expr, "#", arg, void 0);
+            if (answered) return answered;
+            this.checkOperands(expr, "#", arg);
+            return numberType;
+          }
         }
         return arg;
       }
@@ -9364,16 +9460,21 @@ var TypeAnalyzer = class {
           if (unwrapParens(expr.left).type === "StringLiteral") this.expectedTypeOf.set(unwrapParens(expr.left), r);
         }
         switch (op) {
-          case "..":
-            return this.operatorResult(expr, op, l, r) ?? stringType;
+          case "..": {
+            const answered = this.operatorResult(expr, op, l, r);
+            if (answered) return answered;
+            this.checkOperands(expr, op, l, r);
+            return stringType;
+          }
           case "<":
           case ">":
           case "<=":
           case ">=":
-            this.checkComparison(expr, op, l, r);
+            if (!this.checkComparison(expr, op, l, r)) this.checkOperands(expr, op, l, r);
             return booleanType;
           case "==":
           case "~=":
+            this.checkOverlap(expr, op, l, r);
             return booleanType;
           case "+":
           case "-":
@@ -9381,8 +9482,12 @@ var TypeAnalyzer = class {
           case "/":
           case "//":
           case "%":
-          case "^":
-            return this.operatorResult(expr, op, l, r) ?? this.arithmeticOn([l, r]);
+          case "^": {
+            const answered = this.operatorResult(expr, op, l, r);
+            if (answered) return answered;
+            this.checkOperands(expr, op, l, r);
+            return this.arithmeticOn([l, r]);
+          }
         }
         return union([l, r]);
       }
@@ -9630,6 +9735,14 @@ var TypeAnalyzer = class {
       name = target.property.name;
       object = target.object;
     } else if (target.type === "IndexExpression") {
+      const list = this.expand(this.infer(target.object, env));
+      if ((list.kind === "array" || list.kind === "tuple") && list.readonly) {
+        this.diagnostics.push({
+          node: target,
+          message: `Cannot assign to an element of '${formatType(list)}': it is read-only`
+        });
+        return;
+      }
       const index = this.expand(this.infer(target.index, env));
       if (index.kind !== "literal" || typeof index.value !== "string") return;
       name = index.value;
@@ -9802,9 +9915,27 @@ var TypeAnalyzer = class {
           if (s.indexer) indexer = mergeIndexer(indexer, s.indexer);
         }
       }
+      this.checkDuplicateKey(expr, field, entries);
     }
     return objectType(entries, indexer, asConst || void 0);
   }
+  /** `{ a: 1, a: 2 }` — the second wins and the first was written for
+   *  nothing, which is a typo far more often than a decision. A spread is
+   *  not one: overriding what it brought is exactly what it is for. */
+  checkDuplicateKey(expr, field, entries) {
+    if (!this.emitDiagnostics || this.duplicateKeyReported.has(field)) return;
+    const written = field.type === "TableFieldNamed" ? field.key.type === "Identifier" ? field.key.name : field.key.value : field.type === "TableFieldShorthand" ? field.name.name : void 0;
+    if (written === void 0) return;
+    const spreadBefore = expr.fields.slice(0, expr.fields.indexOf(field)).some((f) => f.type === "TableFieldSpread");
+    if (spreadBefore) return;
+    if (entries.filter(([k]) => k === written).length < 2) return;
+    this.duplicateKeyReported.add(field);
+    this.diagnostics.push({
+      node: field.type === "TableFieldNamed" ? field.key : field.name,
+      message: `'${written}' is given twice in this table; only the last one is kept`
+    });
+  }
+  duplicateKeyReported = /* @__PURE__ */ new WeakSet();
   /** A value inferred `as const`, widened back wherever `context` does not
    *  ask for a literal: `satisfies`' result type. A property keeps `"circle"`
    *  when the contract's property admits string literals, and becomes
@@ -10297,27 +10428,84 @@ var TypeAnalyzer = class {
   arithmeticOn(operands) {
     return operands.some((t) => this.expand(t).kind === "any") ? anyType : numberType;
   }
+  /** `a == b` where nothing `a` can hold is anything `b` can: the answer is
+   *  always the same, so the comparison was not the one meant. Only types
+   *  that say what they hold take part — `any`, `unknown` and a type
+   *  parameter say nothing, and a table compares by identity, so two of them
+   *  may well be the same table. */
+  checkOverlap(node, op, l, r) {
+    if (!this.emitDiagnostics) return;
+    const left = this.expand(l);
+    const right = this.expand(r);
+    const judged = (t) => {
+      const parts = t.kind === "union" ? t.types.map((m) => this.expand(m)) : [t];
+      return parts.every((p) => p.kind === "literal" || p.kind === "primitive");
+    };
+    const isNil = (t) => t.kind === "primitive" && t.name === "nil";
+    if (isNil(left) || isNil(right)) return;
+    if (!judged(left) || !judged(right)) return;
+    if (isAssignable(left, right) || isAssignable(right, left)) return;
+    this.diagnostics.push({
+      node,
+      message: `This comparison is always ${op === "==" ? "false" : "true"}: '${formatType(l)}' and '${formatType(r)}' have no value in common`
+    });
+  }
+  /** What an operator takes, where no metamethod answered for it. Luau
+   *  raises on the rest — `n * 2` with `n` nil is an error at the line it
+   *  runs, and a nil `n` is exactly what `number | nil` says may happen — so
+   *  it is said here instead. `any` passes: nothing is known about it. */
+  checkOperands(node, op, left, right) {
+    if (!this.emitDiagnostics) return;
+    const fits = (t) => {
+      const x = this.expand(t);
+      if (x.kind === "any" || x.kind === "never") return true;
+      switch (op) {
+        // `..` joins strings, and Luau writes a number into one.
+        case "..":
+          return isAssignable(x, stringType) || isAssignable(x, numberType);
+        // `#` counts a string's bytes or a table's entries.
+        case "#":
+          return x.kind === "array" || x.kind === "tuple" || x.kind === "object" || isAssignable(x, stringType);
+        default:
+          return isAssignable(x, numberType);
+      }
+    };
+    if (op === "<" || op === ">" || op === "<=" || op === ">=") {
+      const both = (t) => this.expand(t);
+      const [l, r] = [both(left), both(right)];
+      const loose = (t) => t.kind === "any" || t.kind === "never";
+      const alike = (as) => isAssignable(l, as) && isAssignable(r, as);
+      if (loose(l) || loose(r) || alike(numberType) || alike(stringType)) return;
+    } else if (fits(left) && (right === void 0 || fits(right))) {
+      return;
+    }
+    this.diagnostics.push({
+      node,
+      message: right === void 0 ? `Operator '${op}' cannot be applied to type '${formatType(left)}'` : `Operator '${op}' cannot be applied to types '${formatType(left)}' and '${formatType(right)}'`
+    });
+  }
   /** `a < b` between class instances: Luau asks `__lt` (`__le` for `<=`),
    *  with the operands swapped for `>` and `>=`, and an instance without
    *  one cannot be compared at all. */
   checkComparison(node, op, l, r) {
-    if (!this.emitDiagnostics) return;
+    if (!this.emitDiagnostics) return false;
     const left = this.expand(l);
     const right = this.expand(r);
     const instance = (t) => t.kind === "object" && t.class !== void 0;
-    if (!instance(left) && !instance(right)) return;
+    if (!instance(left) && !instance(right)) return false;
     const name = op === "<" || op === ">" ? "__lt" : "__le";
     const operands = op === ">" || op === ">=" ? [right, left] : [left, right];
     for (const receiver of operands) {
       const method = receiver.kind === "object" ? receiver.properties.get(name) : void 0;
       if (!method) continue;
-      if (this.pickOverload(this.overloadsOf(method.type), operands)) return;
+      if (this.pickOverload(this.overloadsOf(method.type), operands)) return true;
       break;
     }
     this.diagnostics.push({
       node,
       message: `Operator '${op}' cannot be applied to types '${formatType(l)}' and '${formatType(r)}'`
     });
+    return true;
   }
   /** What an operator on a value with metamethods gives: `a + b` calls
    *  `__add` on `a`, or failing that on `b` with the operands swapped — the
@@ -10604,7 +10792,56 @@ var TypeAnalyzer = class {
     return this.bindingByDecl.get(node) ?? this.bindingByPos.get(posKey(name, node.line.start, node.column.start));
   }
 };
-function referencedTypeNames(node, out = []) {
+var libraryNames = /* @__PURE__ */ new WeakMap();
+function namesDeclaredIn(program) {
+  const known = libraryNames.get(program);
+  if (known) return known;
+  const names = /* @__PURE__ */ new Set();
+  for (const stmt of program.body.statements) {
+    const declaration = stmt.type === "ExportStatement" || stmt.type === "ExportDefaultStatement" ? stmt.declaration : stmt;
+    if (declaration.type === "TypeAliasStatement") names.add(declaration.name.name);
+    else if (declaration.type === "ExportTypeAliasStatement") names.add(declaration.alias.name.name);
+    else if (declaration.type === "DeclareClassStatement") names.add(declaration.name.name);
+    else if (declaration.type === "ClassDeclaration" && declaration.name) names.add(declaration.name.name);
+    else if (stmt.type === "ImportStatement") {
+      for (const s of stmt.specifiers) names.add(s.local.name);
+      if (stmt.defaultImport) names.add(stmt.defaultImport.name);
+      if (stmt.namespaceImport) names.add(stmt.namespaceImport.name);
+    }
+  }
+  libraryNames.set(program, names);
+  return names;
+}
+var sharedClassesByLib = /* @__PURE__ */ new WeakMap();
+function shareableClasses(libs, program) {
+  if (!libs.length) return void 0;
+  const mine = namesDeclaredIn(program);
+  if (mine.size) {
+    for (const lib of libs) {
+      for (const name of namesDeclaredIn(lib)) if (mine.has(name)) return void 0;
+    }
+  }
+  const existing = sharedClassesByLib.get(libs[0]);
+  if (existing) {
+    const same = existing.libs.length === libs.length && existing.libs.every((lib, i) => lib === libs[i]);
+    if (same) return existing;
+    return void 0;
+  }
+  const store = { libs: [...libs], classTypes: /* @__PURE__ */ new WeakMap(), classMembers: /* @__PURE__ */ new WeakMap() };
+  sharedClassesByLib.set(libs[0], store);
+  return store;
+}
+var referencedNamesOf = /* @__PURE__ */ new WeakMap();
+var typeQueryIn = /* @__PURE__ */ new WeakMap();
+function referencedTypeNames(node, out) {
+  if (out === void 0 && node && typeof node === "object") {
+    const known = referencedNamesOf.get(node);
+    if (known) return known;
+    const found = referencedTypeNames(node, []);
+    referencedNamesOf.set(node, found);
+    return found;
+  }
+  out = out ?? [];
   if (!node || typeof node !== "object") return out;
   if (Array.isArray(node)) {
     for (const item of node) referencedTypeNames(item, out);
@@ -10621,9 +10858,11 @@ function referencedTypeNames(node, out = []) {
 }
 function containsTypeQuery(node) {
   if (!node || typeof node !== "object") return false;
-  if (Array.isArray(node)) return node.some(containsTypeQuery);
-  if (node.type === "TypeofTypeNode") return true;
-  return Object.values(node).some(containsTypeQuery);
+  const known = typeQueryIn.get(node);
+  if (known !== void 0) return known;
+  const found = Array.isArray(node) ? node.some(containsTypeQuery) : node.type === "TypeofTypeNode" || Object.values(node).some(containsTypeQuery);
+  typeQueryIn.set(node, found);
+  return found;
 }
 var STRING_INTRINSICS = /* @__PURE__ */ new Set(["Uppercase", "Lowercase", "Capitalize", "Uncapitalize"]);
 function briefType(t) {

package/dist/index.d.cts

@@ -704,6 +704,9 @@ interface IndexExpression extends BaseNode {
     type: "IndexExpression";
     object: Expression;
     index: Expression;
+    /** `object?.[key]` — when `object` is nil, the whole chain this link
+     *  belongs to is nil and the key is not evaluated. */
+    optional?: boolean;
 }
 interface CallExpression extends BaseNode {
     type: "CallExpression";
@@ -902,6 +905,8 @@ interface TableTypeNode extends BaseNode {
 interface ArrayTypeNode extends BaseNode {
     type: "ArrayTypeNode";
     element: TypeNode;
+    /** `readonly T[]` — the list may be read, not written to. */
+    isReadonly?: boolean;
 }
 /** `[number, string]` — a tuple type; `[string, ...number[]]` ends in a rest
  *  of as many more as there are. */
@@ -910,6 +915,8 @@ interface TupleTypeNode extends BaseNode {
     elements: TypeNode[];
     /** `...number[]` at the end: the array type the rest of it is. */
     rest?: TypeNode;
+    /** `readonly [A, B]` — see `ArrayTypeNode.isReadonly`. */
+    isReadonly?: boolean;
 }
 interface FunctionTypeParameter extends BaseNode {
     type: "FunctionTypeParameter";
@@ -1119,6 +1126,7 @@ interface ArrayType {
     kind: "array";
     element: Type;
     alias?: string;
+    readonly?: boolean;
 }
 /** `[A, B, C]` — fixed length; `[A, ...B[]]` — at least that, then any
  *  number of `B`. `rest` is the element type of that tail. A tuple is an
@@ -1128,6 +1136,7 @@ interface TupleType {
     elements: Type[];
     rest?: Type;
     alias?: string;
+    readonly?: boolean;
 }
 interface ObjectProperty {
     type: Type;

package/dist/index.d.ts

@@ -704,6 +704,9 @@ interface IndexExpression extends BaseNode {
     type: "IndexExpression";
     object: Expression;
     index: Expression;
+    /** `object?.[key]` — when `object` is nil, the whole chain this link
+     *  belongs to is nil and the key is not evaluated. */
+    optional?: boolean;
 }
 interface CallExpression extends BaseNode {
     type: "CallExpression";
@@ -902,6 +905,8 @@ interface TableTypeNode extends BaseNode {
 interface ArrayTypeNode extends BaseNode {
     type: "ArrayTypeNode";
     element: TypeNode;
+    /** `readonly T[]` — the list may be read, not written to. */
+    isReadonly?: boolean;
 }
 /** `[number, string]` — a tuple type; `[string, ...number[]]` ends in a rest
  *  of as many more as there are. */
@@ -910,6 +915,8 @@ interface TupleTypeNode extends BaseNode {
     elements: TypeNode[];
     /** `...number[]` at the end: the array type the rest of it is. */
     rest?: TypeNode;
+    /** `readonly [A, B]` — see `ArrayTypeNode.isReadonly`. */
+    isReadonly?: boolean;
 }
 interface FunctionTypeParameter extends BaseNode {
     type: "FunctionTypeParameter";
@@ -1119,6 +1126,7 @@ interface ArrayType {
     kind: "array";
     element: Type;
     alias?: string;
+    readonly?: boolean;
 }
 /** `[A, B, C]` — fixed length; `[A, ...B[]]` — at least that, then any
  *  number of `B`. `rest` is the element type of that tail. A tuple is an
@@ -1128,6 +1136,7 @@ interface TupleType {
     elements: Type[];
     rest?: Type;
     alias?: string;
+    readonly?: boolean;
 }
 interface ObjectProperty {
     type: Type;

package/dist/index.js

@@ -2398,6 +2398,21 @@ var Parser = class {
           base = { type: "MemberExpression", object: base, property: prop, optional: true, ...spanFrom(base, prop) };
           continue;
         }
+        if (punct === "." && this.punctuatorAt(2, "[")) {
+          this.advance();
+          this.advance();
+          this.expectPunctuator("[");
+          const index = this.inBrackets(() => this.parseExpression());
+          this.expectPunctuator("]");
+          base = {
+            type: "IndexExpression",
+            object: base,
+            index,
+            optional: true,
+            ...spanFrom(base, this.previous())
+          };
+          continue;
+        }
         if (punct === "." && this.punctuatorAt(2, "(")) {
           this.advance();
           this.advance();
@@ -3151,8 +3166,12 @@ var Parser = class {
    *  `name?: T` for an optional property or parameter. */
   parseSuffixType() {
     if (this.checkIdentifierValue("readonly")) {
+      const start = this.current();
       this.advance();
-      return this.parseSuffixType();
+      const t2 = this.parseSuffixType();
+      if (t2.type === "ArrayTypeNode" || t2.type === "TupleTypeNode") return { ...t2, isReadonly: true };
+      this.problemAt(start, "'readonly' belongs on an array or a tuple: a property is marked where it is written");
+      return t2;
     }
     let t = this.parsePrimaryType();
     while (true) {
@@ -3703,31 +3722,34 @@ var Analyzer = class {
    *  can call it, but a call straight in the block before the declaration
    *  finds nothing there yet. At a module's top level the whole function is
    *  hoisted, and this does not apply. */
-  checkUseBeforeDefine(identifier, id) {
+  checkUseBeforeDefine(identifier, id, at = this.functionDepth) {
     const binding = this.bindings.get(id);
-    if (binding.declaredBy !== "function" && binding.declaredBy !== "class" || this.typeQueryDepth > 0) return;
+    if (this.typeQueryDepth > 0) return;
     const declaration = binding.declarationNode;
-    const depth = declaration && this.hoisted.get(declaration);
-    if (depth === void 0 || depth !== this.functionDepth) return;
+    if (!declaration) return;
+    const hoisted = binding.declaredBy === "function" || binding.declaredBy === "class";
+    const depth = hoisted ? this.hoisted.get(declaration) : this.declaredDepth.get(id);
+    const readable = hoisted || binding.kind === "local";
+    if (!readable || depth === void 0 || depth !== at) return;
     const before = identifier.line.start < declaration.line.start || identifier.line.start === declaration.line.start && identifier.column.start < declaration.column.start;
     if (!before) return;
     this.diagnostics.push({
       node: identifier,
-      message: `'${binding.name}' is used before its definition: inside a function, a function declared further down is only there once its declaration has run`,
+      message: hoisted ? `'${binding.name}' is used before its definition: inside a function, a function declared further down is only there once its declaration has run` : `'${binding.name}' is used before its declaration, and holds nothing until that line has run`,
       kind: "use-before-define"
     });
   }
   noteDeferred(identifier, scope, id, assignment) {
     if (this.functionDepth === 0 && this.typeQueryDepth === 0) return;
     if (this.bindings.get(id).kind !== "global") return;
-    this.deferredGlobals.push({ node: identifier, scope, assignment });
+    this.deferredGlobals.push({ node: identifier, scope, assignment, depth: this.functionDepth });
   }
   /** Point each deferred read of a global at the declaration of that name
    *  that turned up later — in the module, or in any block around the code
    *  that reads it. Such code runs after the declaration has: a closure
    *  written inside a value reads the name the value is bound to. */
   resolveForwardReferences() {
-    for (const { node, scope, assignment } of this.deferredGlobals) {
+    for (const { node, scope, assignment, depth } of this.deferredGlobals) {
       const localId = this.lookup(scope, node.name);
       const globalId = this.bindingOf.get(node);
       if (localId === void 0 || globalId === void 0 || localId === globalId) continue;
@@ -3742,7 +3764,10 @@ var Analyzer = class {
       this.bindingOf.set(node, localId);
       this.bindings.get(localId).references.push(node);
       if (assignment) this.checkConstAssign(localId, node);
-      else if (this.typeQueryDepth === 0) this.checkTypeOnly(localId, node);
+      else if (this.typeQueryDepth === 0) {
+        this.checkTypeOnly(localId, node);
+        this.checkUseBeforeDefine(node, localId, depth);
+      }
     }
   }
   /** Every read of a global nothing declares. A global assigned somewhere
@@ -3773,9 +3798,13 @@ var Analyzer = class {
     }
     const id = this.nextId++;
     this.bindings.set(id, { id, name, kind, declarationNode: node, references: [], isConst, declaredBy });
+    this.declaredDepth.set(id, this.functionDepth);
     scope.declarations.set(name, id);
     return id;
   }
+  /** Which function body each name was declared in. A read of a `const` from
+   *  the same body, but above it, is a read of nothing. */
+  declaredDepth = /* @__PURE__ */ new Map();
   resolve(scope, name) {
     for (let s = scope; s; s = s.parent) {
       const id = s.declarations.get(name);
@@ -4428,9 +4457,9 @@ function substitute(t, subst) {
     case "typeParam":
       return subst.get(t.name) ?? t;
     case "array":
-      return arrayOf(substitute(t.element, subst));
+      return { ...arrayOf(substitute(t.element, subst)), readonly: t.readonly };
     case "tuple":
-      return tuple(t.elements.map((e) => substitute(e, subst)), t.rest && substitute(t.rest, subst));
+      return { ...tuple(t.elements.map((e) => substitute(e, subst)), t.rest && substitute(t.rest, subst)), readonly: t.readonly };
     case "object": {
       const entries = [];
       for (const [k, v] of t.properties) entries.push([k, { ...v, type: substitute(v.type, subst) }]);
@@ -4595,6 +4624,20 @@ function unify(param, arg, vars, out) {
       return;
   }
 }
+function memberKey(t) {
+  switch (t.kind) {
+    case "literal":
+      return `l${t.base}:${String(t.value)}`;
+    case "primitive":
+      return `p${t.name}`;
+    case "any":
+    case "unknown":
+    case "never":
+      return t.kind;
+    default:
+      return formatType(t);
+  }
+}
 function union(types) {
   const flat = [];
   for (const t of types) {
@@ -4606,7 +4649,7 @@ function union(types) {
   const seen = /* @__PURE__ */ new Map();
   for (const t of flat) {
     if (t.kind === "never") continue;
-    const key = formatType(t);
+    const key = memberKey(t);
     if (!seen.has(key)) seen.set(key, t);
   }
   let members = reduceSubtypes([...seen.values()]);
@@ -4635,7 +4678,7 @@ function intersection(types) {
   const seen = /* @__PURE__ */ new Map();
   for (const t of flat) {
     if (t.kind === "unknown") continue;
-    seen.set(formatType(t), t);
+    seen.set(memberKey(t), t);
   }
   const members = [...seen.values()];
   if (members.length === 0) return unknownType;
@@ -4662,9 +4705,9 @@ function widen(t) {
     case "literal":
       return primitive(t.base);
     case "array":
-      return arrayOf(widen(t.element));
+      return { ...arrayOf(widen(t.element)), readonly: t.readonly };
     case "tuple":
-      return tuple(t.elements.map(widen), t.rest && widen(t.rest));
+      return { ...tuple(t.elements.map(widen), t.rest && widen(t.rest)), readonly: t.readonly };
     case "object": {
       if (t.frozen || t.class) return t;
       const entries = [];
@@ -4762,6 +4805,7 @@ function isAssignableInner(a, b) {
     return b.kind === "primitive" && b.name === "string";
   }
   if (a.kind === "primitive") return b.kind === "primitive" && b.name === a.name;
+  if ((a.kind === "array" || a.kind === "tuple") && a.readonly && (b.kind === "array" || b.kind === "tuple") && !b.readonly) return false;
   if (a.kind === "array") {
     if (b.kind === "array") return isAssignable(a.element, b.element);
     if (b.kind === "tuple") return b.elements.length === 0 && !!b.rest && isAssignable(a.element, b.rest);
@@ -5107,10 +5151,10 @@ function formatTypeUncached(t) {
     case "literal":
       return t.base === "string" ? JSON.stringify(t.value) : String(t.value);
     case "array":
-      return `${formatAtom(t.element)}[]`;
+      return `${t.readonly ? "readonly " : ""}${formatAtom(t.element)}[]`;
     case "tuple": {
       const inner = [...t.elements.map(formatType), ...t.rest ? [`...${formatAtom(t.rest)}[]`] : []];
-      return `[${inner.join(", ")}]`;
+      return `${t.readonly ? "readonly " : ""}[${inner.join(", ")}]`;
     }
     case "object": {
       if (t.name) {
@@ -5633,7 +5677,7 @@ function expressionLabel(e, depth = 0) {
     case "IndexExpression": {
       const o = expressionLabel(e.object, depth + 1);
       const i = e.index.type === "StringLiteral" ? JSON.stringify(e.index.value) : e.index.type === "NumberLiteral" ? e.index.raw : e.index.type === "Identifier" ? e.index.name : "...";
-      return o === void 0 ? void 0 : `${o}[${i}]`;
+      return o === void 0 ? void 0 : `${o}${e.optional ? "?." : ""}[${i}]`;
     }
     case "ParenthesizedExpression": {
       const inner = expressionLabel(e.expression, depth + 1);
@@ -5684,7 +5728,8 @@ var TypeAnalyzer = class {
   /** 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`. */
+  /** See `resolveClass`. Shared with other analyses over the same libraries
+   *  when none of their names is redefined here; see `shareableClasses`. */
   classTypes = /* @__PURE__ */ new WeakMap();
   /** See `instanceType` — one instance type per `class ... end`. */
   instanceTypes = /* @__PURE__ */ new WeakMap();
@@ -5730,6 +5775,11 @@ var TypeAnalyzer = class {
   /** Recursion guard for `preVisitBody`. */
   preVisitDepth = 0;
   run() {
+    const shared = shareableClasses(this.options.libs ?? [], this.program);
+    if (shared) {
+      this.classTypes = shared.classTypes;
+      this.classMembers = shared.classMembers;
+    }
     this.registerAliasDefs(preludeProgram().body, true);
     for (const lib of this.options.libs ?? []) this.registerAliasDefs(lib.body, true);
     this.registerAliasDefs(this.program.body);
@@ -6895,14 +6945,17 @@ var TypeAnalyzer = class {
         return literal(node.value);
       case "TypeLiteralNumber":
         return literal(node.value);
-      case "ArrayTypeNode":
-        return arrayOf(this.resolveType(node.element));
+      case "ArrayTypeNode": {
+        const made = arrayOf(this.resolveType(node.element));
+        return node.isReadonly ? { ...made, readonly: true } : made;
+      }
       case "TupleTypeNode": {
         const rest = node.rest && this.expand(this.resolveType(node.rest));
-        return tuple(
+        const made = tuple(
           node.elements.map((e) => this.resolveType(e)),
           rest ? rest.kind === "array" ? rest.element : rest.kind === "any" ? anyType : unknownType : void 0
         );
+        return node.isReadonly && made.kind === "tuple" ? { ...made, readonly: true } : made;
       }
       case "UnionTypeNode":
         return union(node.types.map((t) => this.resolveType(t)));
@@ -7722,8 +7775,19 @@ var TypeAnalyzer = class {
     if (p.rest) return arrayOf(unknownType);
     if (p.pattern) return this.patternToType(p.pattern, env);
     if (p.default) return widen(this.infer(p.default, env));
-    return this.contextualParams.get(p) ?? anyType;
+    const contextual = this.contextualParams.get(p);
+    if (contextual) return contextual;
+    if (this.emitDiagnostics && !receiver && p.name && p.line && !this.untypedParamReported.has(p)) {
+      this.untypedParamReported.add(p);
+      this.diagnostics.push({
+        node: p,
+        message: `Parameter '${p.name}' has no type, so it is 'any': give it one, or a default to read it from`
+      });
+    }
+    return anyType;
   }
+  /** Parameters already spoken about: a body is visited more than once. */
+  untypedParamReported = /* @__PURE__ */ new WeakSet();
   /** What a function expression's unannotated parameters are, from where
    *  it is written — see `applyContext`. */
   contextualParams = /* @__PURE__ */ new WeakMap();
@@ -8018,6 +8082,11 @@ var TypeAnalyzer = class {
    *  this returns `undefined` and the ordinary pick stands. */
   distributedReturn(fns, argTypes, picked, argsFor) {
     if (fns.length < 2) return void 0;
+    if (argTypes.some((t) => this.expand(t).kind === "any")) {
+      const taken = fns.filter((f) => this.overloadAccepts(f, argsFor(f, argTypes)));
+      if (taken.length < 2) return void 0;
+      return union(taken.map((f) => this.callReturn(f, argsFor(f, argTypes))));
+    }
     const position = argTypes.findIndex((t) => this.expand(t).kind === "union");
     if (position < 0) return void 0;
     const members = this.expand(argTypes[position]).types;
@@ -8066,6 +8135,8 @@ var TypeAnalyzer = class {
    *  lone argument cannot be checked against without false errors. */
   boundParams(f) {
     if (!f.typeParams?.length) return f.params.map((p) => p.type);
+    const known = this.boundParamsCache.get(f);
+    if (known) return known;
     const bounds = new Map(f.typeParams.map((name) => [name, anyType]));
     const seen = /* @__PURE__ */ new WeakSet();
     const walk = (value) => {
@@ -8083,8 +8154,11 @@ var TypeAnalyzer = class {
       for (const child of Object.values(value)) walk(child);
     };
     for (const p of f.params) if (containsTypeParam(p.type)) walk(p.type);
-    return f.params.map((p) => this.reduceType(substitute(p.type, bounds)));
+    const bound = f.params.map((p) => this.reduceType(substitute(p.type, bounds)));
+    this.boundParamsCache.set(f, bound);
+    return bound;
   }
+  boundParamsCache = /* @__PURE__ */ new WeakMap();
   /** Record what each written argument is expected to be — see
    *  `TypeAnalysis.expectedTypeOf`. */
   recordExpected(written, fns, selfOf, argsOf = () => []) {
@@ -8548,7 +8622,7 @@ var TypeAnalyzer = class {
   /** What one `for (const item in source)` hands over each time, and how it
    *  walks the source. `pairs`/`ipairs` are read from the table they are
    *  given, so a record's keys stay the literals they are. */
-  iterationOf(source, sourceType) {
+  iterationOf(source, sourceType, report = true) {
     if (source.type === "CallExpression" && source.callee.type === "Identifier" && source.arguments[0]) {
       const name = source.callee.name;
       const src = this.expand(this.typeOf.get(source.arguments[0]) ?? unknownType);
@@ -8586,7 +8660,14 @@ var TypeAnalyzer = class {
     if (t.kind === "object") {
       return [t.indexer?.value ?? union([...t.properties.values()].map((p) => p.type)), values];
     }
-    if (t.kind !== "never" && this.emitDiagnostics) {
+    if (t.kind === "union") {
+      const each = t.types.map((member) => this.iterationOf(source, member, false));
+      const [first] = each;
+      if (first && each.every(([, form]) => form.walks === first[1].walks && form.viaIter === first[1].viaIter)) {
+        return [union(each.map(([item]) => item)), first[1]];
+      }
+    }
+    if (t.kind !== "never" && report && this.emitDiagnostics) {
       this.diagnostics.push({
         node: source,
         message: `Cannot loop over '${formatType(sourceType)}': a loop walks an array, a table, an iterator function or an iteration such as 'pairs(t)'`
@@ -8955,7 +9036,14 @@ var TypeAnalyzer = class {
     const names = keys.map(nameOf);
     const others = keys.filter((_, i) => names[i] === void 0);
     let message;
-    if (others.length && this.cannotIndex(object, others)) {
+    const listOnly = (t) => {
+      const x = this.expand(t);
+      if (x.kind === "union") return x.types.every(listOnly);
+      return x.kind === "array" || x.kind === "tuple";
+    };
+    if (names.some((name) => name !== void 0) && listOnly(withoutNil(this.expand(object)))) {
+      message = `Type '${briefType(index)}' cannot be used to index type '${shown}'`;
+    } else if (others.length && this.cannotIndex(object, others)) {
       message = `Type '${briefType(index)}' cannot be used to index type '${shown}'`;
     } else if (!others.length && names.every((name) => this.memberMissing(object, name))) {
       message = keys.length === 1 ? `Property '${names[0]}' does not exist on type '${shown}'` : `None of ${briefType(index)} is a property of type '${shown}'`;
@@ -9227,10 +9315,18 @@ var TypeAnalyzer = class {
         switch (expr.operator) {
           case "not":
             return booleanType;
-          case "-":
-            return this.operatorResult(expr, "-", arg, void 0) ?? this.arithmeticOn([arg]);
-          case "#":
-            return this.operatorResult(expr, "#", arg, void 0) ?? numberType;
+          case "-": {
+            const answered = this.operatorResult(expr, "-", arg, void 0);
+            if (answered) return answered;
+            this.checkOperands(expr, "-", arg);
+            return this.arithmeticOn([arg]);
+          }
+          case "#": {
+            const answered = this.operatorResult(expr, "#", arg, void 0);
+            if (answered) return answered;
+            this.checkOperands(expr, "#", arg);
+            return numberType;
+          }
         }
         return arg;
       }
@@ -9259,16 +9355,21 @@ var TypeAnalyzer = class {
           if (unwrapParens(expr.left).type === "StringLiteral") this.expectedTypeOf.set(unwrapParens(expr.left), r);
         }
         switch (op) {
-          case "..":
-            return this.operatorResult(expr, op, l, r) ?? stringType;
+          case "..": {
+            const answered = this.operatorResult(expr, op, l, r);
+            if (answered) return answered;
+            this.checkOperands(expr, op, l, r);
+            return stringType;
+          }
           case "<":
           case ">":
           case "<=":
           case ">=":
-            this.checkComparison(expr, op, l, r);
+            if (!this.checkComparison(expr, op, l, r)) this.checkOperands(expr, op, l, r);
             return booleanType;
           case "==":
           case "~=":
+            this.checkOverlap(expr, op, l, r);
             return booleanType;
           case "+":
           case "-":
@@ -9276,8 +9377,12 @@ var TypeAnalyzer = class {
           case "/":
           case "//":
           case "%":
-          case "^":
-            return this.operatorResult(expr, op, l, r) ?? this.arithmeticOn([l, r]);
+          case "^": {
+            const answered = this.operatorResult(expr, op, l, r);
+            if (answered) return answered;
+            this.checkOperands(expr, op, l, r);
+            return this.arithmeticOn([l, r]);
+          }
         }
         return union([l, r]);
       }
@@ -9525,6 +9630,14 @@ var TypeAnalyzer = class {
       name = target.property.name;
       object = target.object;
     } else if (target.type === "IndexExpression") {
+      const list = this.expand(this.infer(target.object, env));
+      if ((list.kind === "array" || list.kind === "tuple") && list.readonly) {
+        this.diagnostics.push({
+          node: target,
+          message: `Cannot assign to an element of '${formatType(list)}': it is read-only`
+        });
+        return;
+      }
       const index = this.expand(this.infer(target.index, env));
       if (index.kind !== "literal" || typeof index.value !== "string") return;
       name = index.value;
@@ -9697,9 +9810,27 @@ var TypeAnalyzer = class {
           if (s.indexer) indexer = mergeIndexer(indexer, s.indexer);
         }
       }
+      this.checkDuplicateKey(expr, field, entries);
     }
     return objectType(entries, indexer, asConst || void 0);
   }
+  /** `{ a: 1, a: 2 }` — the second wins and the first was written for
+   *  nothing, which is a typo far more often than a decision. A spread is
+   *  not one: overriding what it brought is exactly what it is for. */
+  checkDuplicateKey(expr, field, entries) {
+    if (!this.emitDiagnostics || this.duplicateKeyReported.has(field)) return;
+    const written = field.type === "TableFieldNamed" ? field.key.type === "Identifier" ? field.key.name : field.key.value : field.type === "TableFieldShorthand" ? field.name.name : void 0;
+    if (written === void 0) return;
+    const spreadBefore = expr.fields.slice(0, expr.fields.indexOf(field)).some((f) => f.type === "TableFieldSpread");
+    if (spreadBefore) return;
+    if (entries.filter(([k]) => k === written).length < 2) return;
+    this.duplicateKeyReported.add(field);
+    this.diagnostics.push({
+      node: field.type === "TableFieldNamed" ? field.key : field.name,
+      message: `'${written}' is given twice in this table; only the last one is kept`
+    });
+  }
+  duplicateKeyReported = /* @__PURE__ */ new WeakSet();
   /** A value inferred `as const`, widened back wherever `context` does not
    *  ask for a literal: `satisfies`' result type. A property keeps `"circle"`
    *  when the contract's property admits string literals, and becomes
@@ -10192,27 +10323,84 @@ var TypeAnalyzer = class {
   arithmeticOn(operands) {
     return operands.some((t) => this.expand(t).kind === "any") ? anyType : numberType;
   }
+  /** `a == b` where nothing `a` can hold is anything `b` can: the answer is
+   *  always the same, so the comparison was not the one meant. Only types
+   *  that say what they hold take part — `any`, `unknown` and a type
+   *  parameter say nothing, and a table compares by identity, so two of them
+   *  may well be the same table. */
+  checkOverlap(node, op, l, r) {
+    if (!this.emitDiagnostics) return;
+    const left = this.expand(l);
+    const right = this.expand(r);
+    const judged = (t) => {
+      const parts = t.kind === "union" ? t.types.map((m) => this.expand(m)) : [t];
+      return parts.every((p) => p.kind === "literal" || p.kind === "primitive");
+    };
+    const isNil = (t) => t.kind === "primitive" && t.name === "nil";
+    if (isNil(left) || isNil(right)) return;
+    if (!judged(left) || !judged(right)) return;
+    if (isAssignable(left, right) || isAssignable(right, left)) return;
+    this.diagnostics.push({
+      node,
+      message: `This comparison is always ${op === "==" ? "false" : "true"}: '${formatType(l)}' and '${formatType(r)}' have no value in common`
+    });
+  }
+  /** What an operator takes, where no metamethod answered for it. Luau
+   *  raises on the rest — `n * 2` with `n` nil is an error at the line it
+   *  runs, and a nil `n` is exactly what `number | nil` says may happen — so
+   *  it is said here instead. `any` passes: nothing is known about it. */
+  checkOperands(node, op, left, right) {
+    if (!this.emitDiagnostics) return;
+    const fits = (t) => {
+      const x = this.expand(t);
+      if (x.kind === "any" || x.kind === "never") return true;
+      switch (op) {
+        // `..` joins strings, and Luau writes a number into one.
+        case "..":
+          return isAssignable(x, stringType) || isAssignable(x, numberType);
+        // `#` counts a string's bytes or a table's entries.
+        case "#":
+          return x.kind === "array" || x.kind === "tuple" || x.kind === "object" || isAssignable(x, stringType);
+        default:
+          return isAssignable(x, numberType);
+      }
+    };
+    if (op === "<" || op === ">" || op === "<=" || op === ">=") {
+      const both = (t) => this.expand(t);
+      const [l, r] = [both(left), both(right)];
+      const loose = (t) => t.kind === "any" || t.kind === "never";
+      const alike = (as) => isAssignable(l, as) && isAssignable(r, as);
+      if (loose(l) || loose(r) || alike(numberType) || alike(stringType)) return;
+    } else if (fits(left) && (right === void 0 || fits(right))) {
+      return;
+    }
+    this.diagnostics.push({
+      node,
+      message: right === void 0 ? `Operator '${op}' cannot be applied to type '${formatType(left)}'` : `Operator '${op}' cannot be applied to types '${formatType(left)}' and '${formatType(right)}'`
+    });
+  }
   /** `a < b` between class instances: Luau asks `__lt` (`__le` for `<=`),
    *  with the operands swapped for `>` and `>=`, and an instance without
    *  one cannot be compared at all. */
   checkComparison(node, op, l, r) {
-    if (!this.emitDiagnostics) return;
+    if (!this.emitDiagnostics) return false;
     const left = this.expand(l);
     const right = this.expand(r);
     const instance = (t) => t.kind === "object" && t.class !== void 0;
-    if (!instance(left) && !instance(right)) return;
+    if (!instance(left) && !instance(right)) return false;
     const name = op === "<" || op === ">" ? "__lt" : "__le";
     const operands = op === ">" || op === ">=" ? [right, left] : [left, right];
     for (const receiver of operands) {
       const method = receiver.kind === "object" ? receiver.properties.get(name) : void 0;
       if (!method) continue;
-      if (this.pickOverload(this.overloadsOf(method.type), operands)) return;
+      if (this.pickOverload(this.overloadsOf(method.type), operands)) return true;
       break;
     }
     this.diagnostics.push({
       node,
       message: `Operator '${op}' cannot be applied to types '${formatType(l)}' and '${formatType(r)}'`
     });
+    return true;
   }
   /** What an operator on a value with metamethods gives: `a + b` calls
    *  `__add` on `a`, or failing that on `b` with the operands swapped — the
@@ -10499,7 +10687,56 @@ var TypeAnalyzer = class {
     return this.bindingByDecl.get(node) ?? this.bindingByPos.get(posKey(name, node.line.start, node.column.start));
   }
 };
-function referencedTypeNames(node, out = []) {
+var libraryNames = /* @__PURE__ */ new WeakMap();
+function namesDeclaredIn(program) {
+  const known = libraryNames.get(program);
+  if (known) return known;
+  const names = /* @__PURE__ */ new Set();
+  for (const stmt of program.body.statements) {
+    const declaration = stmt.type === "ExportStatement" || stmt.type === "ExportDefaultStatement" ? stmt.declaration : stmt;
+    if (declaration.type === "TypeAliasStatement") names.add(declaration.name.name);
+    else if (declaration.type === "ExportTypeAliasStatement") names.add(declaration.alias.name.name);
+    else if (declaration.type === "DeclareClassStatement") names.add(declaration.name.name);
+    else if (declaration.type === "ClassDeclaration" && declaration.name) names.add(declaration.name.name);
+    else if (stmt.type === "ImportStatement") {
+      for (const s of stmt.specifiers) names.add(s.local.name);
+      if (stmt.defaultImport) names.add(stmt.defaultImport.name);
+      if (stmt.namespaceImport) names.add(stmt.namespaceImport.name);
+    }
+  }
+  libraryNames.set(program, names);
+  return names;
+}
+var sharedClassesByLib = /* @__PURE__ */ new WeakMap();
+function shareableClasses(libs, program) {
+  if (!libs.length) return void 0;
+  const mine = namesDeclaredIn(program);
+  if (mine.size) {
+    for (const lib of libs) {
+      for (const name of namesDeclaredIn(lib)) if (mine.has(name)) return void 0;
+    }
+  }
+  const existing = sharedClassesByLib.get(libs[0]);
+  if (existing) {
+    const same = existing.libs.length === libs.length && existing.libs.every((lib, i) => lib === libs[i]);
+    if (same) return existing;
+    return void 0;
+  }
+  const store = { libs: [...libs], classTypes: /* @__PURE__ */ new WeakMap(), classMembers: /* @__PURE__ */ new WeakMap() };
+  sharedClassesByLib.set(libs[0], store);
+  return store;
+}
+var referencedNamesOf = /* @__PURE__ */ new WeakMap();
+var typeQueryIn = /* @__PURE__ */ new WeakMap();
+function referencedTypeNames(node, out) {
+  if (out === void 0 && node && typeof node === "object") {
+    const known = referencedNamesOf.get(node);
+    if (known) return known;
+    const found = referencedTypeNames(node, []);
+    referencedNamesOf.set(node, found);
+    return found;
+  }
+  out = out ?? [];
   if (!node || typeof node !== "object") return out;
   if (Array.isArray(node)) {
     for (const item of node) referencedTypeNames(item, out);
@@ -10516,9 +10753,11 @@ function referencedTypeNames(node, out = []) {
 }
 function containsTypeQuery(node) {
   if (!node || typeof node !== "object") return false;
-  if (Array.isArray(node)) return node.some(containsTypeQuery);
-  if (node.type === "TypeofTypeNode") return true;
-  return Object.values(node).some(containsTypeQuery);
+  const known = typeQueryIn.get(node);
+  if (known !== void 0) return known;
+  const found = Array.isArray(node) ? node.some(containsTypeQuery) : node.type === "TypeofTypeNode" || Object.values(node).some(containsTypeQuery);
+  typeQueryIn.set(node, found);
+  return found;
 }
 var STRING_INTRINSICS = /* @__PURE__ */ new Set(["Uppercase", "Lowercase", "Capitalize", "Uncapitalize"]);
 function briefType(t) {

package/package.json

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