@tilua/parser 3.1.0 → 4.0.0

package/README.md

@@ -124,14 +124,31 @@ Every problem comes back as `{ file, message, line, column }`, pointing into
 the config (or sourcemap) it is about. `host` reads files — pass your own to
 read unsaved editor buffers or to record what was read.
 
-`type` / `typeof` are **not** special-cased in the analyzer either: they are
-overload sets in `@tilua-types/lua` and `@tilua-types/roblox`, and narrowing is derived
-from them. Without a library that declares them, they narrow nothing.
+`typeof v` is the language's own, an operator like `not` and `#`: it needs no
+library, and Lua's `type()` and Luau's `typeof()` functions are declared by
+none. It answers Luau's names — `"nil"`, `"boolean"`, `"number"`, `"string"`,
+`"function"`, `"thread"`, `"buffer"`, `"userdata"` — except for a table, which
+is an `"array"` or an `"object"`. `typeof v == "array"` narrows `v`, and
+`== "table"` is an error: it is never the answer. There is no `typeof(v)`
+function: written that way it is an error, and a parenthesised operand stands
+apart from the operator — `typeof (a or b)`.
+
+What a runtime's own values answer is a library's to say, in one alias:
+
+```ts
+type TypeofNames = { Vector3: Vector3, Instance: Instance }
+```
+
+Each property is the name `typeof` gives a value of the property's type; a
+value several fit (a `Part` is an `Instance`) is the first one's.
+`TypeAnalysis.typeofTables` lists each `typeof v` whose `v` is, by its type,
+an array or an object wherever it is a table — what a compiler need not find
+out as the program runs.
 
 Libraries stack: a name declared again *adds* to what an earlier library gave
 it — overloads of a function accumulate, and the members of a declared table
-merge. That is how `@tilua-types/roblox` extends Lua's `table` and `type` without
-restating them.
+merge. That is how `@tilua-types/roblox` extends Lua's `table` without
+restating it.
 
 ## The language, in brief
 
@@ -340,7 +357,8 @@ such as `print(x)`, and `globalValue` for a global read as a value, such as
 `local p = print`. A local with the same name belongs to the author, and no
 hook is asked about it. A runtime can read `__LINES__`, the bundle's line map
 (`nil` outside a bundle), to turn a line Luau reports back into a place in the
-project. `console:log`, `print` and `error` in `@tilua-types/lua` are built on
+project. One that answers with a new array wraps it in `__ARRAY__(...)`, which
+writes it down as an array for `typeof`. `console:log`, `print` and `error` in `@tilua-types/lua` are built on
 these hooks.
 
 **A `(` that starts a line** continues the statement above it, as in Lua and
@@ -383,8 +401,8 @@ declare class Part extends BasePart { Shape: EnumItem }
 A `Part` is a `BasePart` and an `Instance` because it extends them. A
 `ReplicatedStorage` is not a `Part`, and no table literal is an `Instance`,
 however alike their members. A class still fits a shape that names members it
-has (`{ Name: string }`). It is not a table, though, so `typeof(part)` picks
-the `"Instance"` overload, not `"table"`. Members are inherited, and a subclass
+has (`{ Name: string }`). It is not a table, though, so `typeof part` is
+`"Instance"`, as the library's `TypeofNames` says, not `"object"`. Members are inherited, and a subclass
 may narrow one (`Parent: SomeFolder`).
 
 **`class ... { }`** — a class written in code, rather than declared in a
@@ -804,8 +822,9 @@ three operators: only a call after the `>` makes it type arguments.
 
 `typeof x` in a type is TypeScript's type query — the type of a value
 (`typeof config`, `typeof config.volume`, `ReturnType<typeof f>`). Luau's
-`typeof(expr)` spelling works too. It is compile-time only, unrelated to the
-`typeof(v)` function that returns a string at runtime.
+`typeof(expr)` spelling is an error here as well. It is compile-time only, unrelated to the
+`typeof v` operator in an expression, which answers a string as the program
+runs.
 
 **Modules** — `import` / `export`, export lists, re-exports and `export *`.
 

package/dist/index.cjs

@@ -711,6 +711,8 @@ var UNUSED_EXPECT_ERROR = "Unused '@tilua-expect-error' directive";
 
 // src/ast/builders.ts
 var NO_DOTS = "tilua has no bare '...': take a rest parameter, '...args: T[]', or 'scriptArgs' for the script's own";
+var NO_MEMBER_NAME = "Expected a name after '.'";
+var NO_TYPEOF_CALL = "'typeof' is an operator, not a function: write 'typeof v'";
 var ACCESSIBILITIES = /* @__PURE__ */ new Set(["public", "private", "protected"]);
 var CLASS_MODIFIERS = /* @__PURE__ */ new Set([...ACCESSIBILITIES, "static", "abstract", "override", "readonly"]);
 function bindThis(func, at) {
@@ -2248,6 +2250,7 @@ var Parser = class {
    *  `:` Identifier followed by one of Lua's call forms. */
   startsMethodCall(offset = 0) {
     if (this.peek(offset + 1).type !== "Identifier") return false;
+    if (this.startsOwnLine(this.peek(offset), this.peek(offset + 1))) return false;
     const after = this.peek(offset + 2);
     if (after.type === "Punctuator") {
       const v = String(after.value);
@@ -2273,6 +2276,23 @@ var Parser = class {
     const isString = t.type === "InterpolatedString" || t.type === "Literal" && t.kind === "string";
     return isString && this.punctuatorAt(1, ":") && this.startsMethodCall(1);
   }
+  /** Is there no member name at `offset`, after the `.` or `:` before it? */
+  namelessAfter(offset) {
+    const name = this.peek(offset);
+    if (name.type !== "Identifier") return true;
+    const before = offset === 0 ? this.previous() : this.peek(offset - 1);
+    return before !== void 0 && this.startsOwnLine(before, name);
+  }
+  /** Recovery only. `obj.` may go on to its name on a later line, as in
+   *  JavaScript — but while `obj.` is still being typed, the line below is
+   *  whatever statement was already there, and reading it as the name turns
+   *  one unfinished line into errors about the next. So, as a missing `}`
+   *  is placed, the indentation says which: a line that carries the access
+   *  on is indented deeper than the line it carries on from. */
+  startsOwnLine(before, name) {
+    if (!this.recover || name.line.start <= before.line.end) return false;
+    return this.indentOf(name) <= this.indentOf(before);
+  }
   /** Does the next token start right where the current one ends? */
   touchesNext() {
     const current = this.current();
@@ -2314,6 +2334,7 @@ var Parser = class {
     const t = this.current();
     if (t.type === "Keyword" && t.value === "not") return "not";
     if (t.type === "Operator" && (t.value === "-" || t.value === "#")) return t.value;
+    if (t.type === "Identifier" && t.value === "typeof") return "typeof";
     return null;
   }
   /** Runs `fn` inside a bracket, where a `:` can only ever be a method
@@ -2413,6 +2434,10 @@ var Parser = class {
     const op = this.isUnaryOperator();
     if (op) {
       const opTok = this.advance();
+      const next = this.current();
+      if (op === "typeof" && this.checkPunctuator("(") && next.line.start === opTok.line.end && next.column.start === opTok.column.end) {
+        this.problemAt(next, NO_TYPEOF_CALL);
+      }
       const argument = this.parseExpression(UNARY_PRECEDENCE);
       return {
         type: "UnaryExpression",
@@ -2582,6 +2607,13 @@ var Parser = class {
       if (this.checkPunctuator("?") && this.touchesNext()) {
         const next = this.peek(1);
         const punct = next.type === "Punctuator" ? String(next.value) : void 0;
+        if (punct === "." && this.recover && this.namelessAfter(2) && !this.punctuatorAt(2, "[") && !this.punctuatorAt(2, "(")) {
+          this.advance();
+          this.advance();
+          this.problemAt(this.previous(), NO_MEMBER_NAME);
+          base = { type: "ErrorExpression", expression: base, ...spanFrom(base, this.previous()) };
+          break;
+        }
         if (punct === "." && this.peek(2).type === "Identifier") {
           this.advance();
           this.advance();
@@ -2636,9 +2668,9 @@ var Parser = class {
         }
       }
       if (this.matchPunctuator(".")) {
-        if (this.recover && !this.checkType("Identifier")) {
-          this.softError("Expected identifier");
-          base = { type: "ErrorExpression", ...spanFrom(base, this.previous()) };
+        if (this.namelessAfter(0)) {
+          this.problemAt(this.previous(), NO_MEMBER_NAME);
+          base = { type: "ErrorExpression", expression: base, ...spanFrom(base, this.previous()) };
           break;
         }
         const prop = this.parseIdentifier();
@@ -2651,6 +2683,12 @@ var Parser = class {
         base = { type: "IndexExpression", object: base, index, ...spanFrom(base, this.previous()) };
         continue;
       }
+      if (this.recover && !this.ternaryColons && this.checkPunctuator(":") && this.peek(1).line.start > this.current().line.end && !this.startsMethodCall()) {
+        this.advance();
+        this.problemAt(this.previous(), "Expected a name after ':'");
+        base = { type: "ErrorExpression", expression: base, ...spanFrom(base, this.previous()) };
+        break;
+      }
       if (this.checkPunctuator(":") && this.startsMethodCall() && this.takeMethodColon()) {
         this.advance();
         const method = this.parseIdentifier();
@@ -3494,6 +3532,7 @@ var Parser = class {
       return { type: "TupleTypeNode", elements, ...rest ? { rest } : {}, ...spanFrom(t, this.previous()) };
     }
     if (t.type === "Identifier" && t.value === "typeof" && this.peek(1).type === "Punctuator" && this.peek(1).value === "(") {
+      this.problemAt(this.peek(1), NO_TYPEOF_CALL);
       this.advance();
       this.advance();
       const expression = this.parseExpression();
@@ -3874,7 +3913,7 @@ var BinaryOperators = [
   "and",
   "or"
 ];
-var UnaryOperators = ["-", "not", "#"];
+var UnaryOperators = ["-", "not", "#", "typeof"];
 
 // src/ast/analyzeScopes.ts
 function getBinding(analysis, id) {
@@ -4501,7 +4540,9 @@ var Analyzer = class {
       case "BooleanLiteral":
       case "NumberLiteral":
       case "StringLiteral":
+        return;
       case "ErrorExpression":
+        if (expr.expression) this.visitExpression(expr.expression, scope);
         return;
       case "InterpolatedStringExpression":
         for (const part of expr.parts) {
@@ -5807,6 +5848,13 @@ function mergeEnv(a, b, base) {
   }
   return out;
 }
+function joinNarrowings(into, a, aFrom, b, bFrom) {
+  for (const [key, left] of a) {
+    const right = b.get(key);
+    if (right === void 0 || left === aFrom.get(key) || right === bFrom.get(key)) continue;
+    into.set(key, union([left, right]));
+  }
+}
 function mergeIndexer(a, b) {
   return a ? { key: union([a.key, b.key]), value: union([a.value, b.value]) } : b;
 }
@@ -6086,6 +6134,10 @@ function unwrapParens(e) {
   while (e.type === "ParenthesizedExpression") e = e.expression;
   return e;
 }
+function memberLabel(label, key) {
+  if (label === void 0 || key === void 0) return void 0;
+  return typeof key === "number" ? `${label}[${key}]` : `${label}.${key}`;
+}
 function expressionLabel(e, depth = 0) {
   if (depth > 6) return void 0;
   const args = (list) => {
@@ -6157,6 +6209,7 @@ var TypeAnalyzer = class {
   metatables = [];
   metatableCache = /* @__PURE__ */ new WeakMap();
   methodSources = /* @__PURE__ */ new Map();
+  typeofTables = /* @__PURE__ */ new Map();
   /** Public: each alias resolved once (generic aliases keep their params as
    *  `typeParam` nodes in the body). */
   aliases = new LazyMap();
@@ -6235,7 +6288,7 @@ var TypeAnalyzer = class {
       const given = this.options.globalTypes?.[name];
       if (given) this.bindingType.set(id, given);
       else if (this.libGlobalTypes.has(name)) this.bindingType.defer(id, () => this.libGlobalTypes.get(name) ?? anyType);
-      else if (LANGUAGE_GLOBALS.includes(name)) this.bindingType.set(id, arrayOf(unknownType));
+      else if (LANGUAGE_GLOBALS.includes(name)) this.bindingType.set(id, arrayOf(declaredUnknownType));
       else this.bindingType.set(id, anyType);
     }
     setAliasExpander((t) => this.expand(t));
@@ -6258,6 +6311,7 @@ var TypeAnalyzer = class {
       aliases: this.resolveDeferredAliases(),
       loops: this.loops,
       methodSources: this.methodSources,
+      typeofTables: this.typeofTables,
       metatableMembers: (type) => this.metatableMembers(type),
       diagnostics: this.diagnostics
     };
@@ -7108,7 +7162,12 @@ var TypeAnalyzer = class {
         this.aliases.defer(name, () => this.classType(cls));
         continue;
       }
-      if (this.dependsOnTypeQuery(name)) continue;
+      if (this.dependsOnTypeQuery(name)) {
+        if (def.runtimeClass) {
+          this.aliases.defer(name, () => this.withTypeParams(def.params, () => this.resolveDef(def)));
+        }
+        continue;
+      }
       this.withTypeParams(def.params, () => {
         this.aliases.set(name, this.resolveDef(def));
       });
@@ -7116,14 +7175,16 @@ var TypeAnalyzer = class {
   }
   typeQueryDependents = /* @__PURE__ */ new Map();
   /** Does alias `name` contain a `typeof`, itself or through an alias it
-   *  names? */
+   *  names? Its parameters count: `class C<K extends Config["key"]>`
+   *  resolves the bound along with the class. */
   dependsOnTypeQuery(name, visiting = /* @__PURE__ */ new Set()) {
     const known = this.typeQueryDependents.get(name);
     if (known !== void 0) return known;
     const def = this.aliasDefs.get(name);
     if (!def || def.class || visiting.has(name)) return false;
     visiting.add(name);
-    const result = containsTypeQuery(def.node) || referencedTypeNames(def.node).some((other) => other !== name && this.dependsOnTypeQuery(other, visiting));
+    const nodes = [def.node, ...def.params.flatMap((p) => [p.constraint, p.default])];
+    const result = nodes.some(containsTypeQuery) || referencedTypeNames(nodes).some((other) => other !== name && this.dependsOnTypeQuery(other, visiting));
     visiting.delete(name);
     this.typeQueryDependents.set(name, result);
     return result;
@@ -7848,7 +7909,7 @@ var TypeAnalyzer = class {
           }
         }
         const mode = this.initIsAsConst(source) ? "asconst" : !isFreshLiteralExpr(source) ? "keep" : stmt.kind === "const" ? "const" : "widen";
-        this.bindPattern(target, inferred, env, mode);
+        this.bindPattern(target, inferred, env, mode, source && expressionLabel(source));
         if (stmt.kind === "const") {
           this.correlateDestructuring(target, inferred, env);
           this.correlateIndexed(target, source, env);
@@ -7941,9 +8002,10 @@ var TypeAnalyzer = class {
         } else if (target.type === "MemberExpression" || target.type === "IndexExpression") {
           this.infer(target, env);
           this.checkReadonlyAssign(target, env);
+          this.checkMemberAssign(stmt, target, vt, env);
           this.assignToRef(target, isFreshLiteralExpr(source) ? widen(vt) : vt, env);
         } else if (target.type === "ObjectPattern" || target.type === "ArrayPattern") {
-          this.reassignPattern(target, vt, env);
+          this.reassignPattern(target, vt, env, expressionLabel(source));
         }
         return;
       }
@@ -9309,7 +9371,8 @@ var TypeAnalyzer = class {
   }
   /** Like `bindPattern`, but the leaves are *existing* bindings (a `{a} = t`
    *  assignment). Updates their flow type; keeps a declared annotation. */
-  reassignPattern(target, valueType, env) {
+  reassignPattern(target, valueType, env, label) {
+    if (target.type === "ObjectPattern" || target.type === "ArrayPattern") valueType = this.destructured(target, valueType, label);
     switch (target.type) {
       case "IdentifierPattern": {
         const id = this.scopes.bindingOf.get(target);
@@ -9334,21 +9397,43 @@ var TypeAnalyzer = class {
         for (const p of target.properties) {
           const key = !p.computed && p.key.type === "Identifier" ? p.key.name : !p.computed && p.key.type === "StringLiteral" ? p.key.value : void 0;
           const pt = key !== void 0 ? this.propertyType(valueType, key) : unknownType;
-          this.reassignPattern(p.value, this.withDefault(pt, p.default, env), env);
+          this.reassignPattern(p.value, this.withDefault(pt, p.default, env), env, memberLabel(label, key));
         }
         if (target.rest) this.reassignPattern(target.rest, this.withoutKeys(valueType, target.properties), env);
         return;
       }
       case "ArrayPattern": {
         target.elements.forEach((el, i) => {
-          if (el) this.reassignPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env);
+          if (el) this.reassignPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env, memberLabel(label, i + 1));
         });
         if (target.rest) this.reassignPattern(target.rest, this.restAfter(valueType, target.elements.length), env);
         return;
       }
     }
   }
-  bindPattern(target, valueType, env, mode) {
+  destructuredReported = /* @__PURE__ */ new WeakSet();
+  /** What a pattern reads from. `const { a } = v` is `v.a`, and fails where
+   *  that would: on a `v` that may be nil, and on one that is `unknown`.
+   *  `label` is the value as it would be written — `args[1]` for the inner
+   *  pattern of `const [{ a }] = args`. */
+  destructured(pattern, raw, label) {
+    let type = raw;
+    const report = (message) => {
+      if (!this.emitDiagnostics || this.destructuredReported.has(pattern)) return;
+      this.destructuredReported.add(pattern);
+      this.diagnostics.push({ node: pattern, message: `${label === void 0 ? "Object" : `'${label}'`} ${message}` });
+    };
+    if (this.includesNil(type)) {
+      const t = this.expand(type);
+      report(t.kind === "primitive" ? "is nil" : "is possibly nil. Check it first, or give it a default");
+      type = withoutNil(t);
+    }
+    const read = this.expand(type);
+    if (read.kind === "unknown" && read.declared) report("is of type 'unknown'");
+    return type;
+  }
+  bindPattern(target, valueType, env, mode, label) {
+    if (target.type === "ObjectPattern" || target.type === "ArrayPattern") valueType = this.destructured(target, valueType, label);
     switch (target.type) {
       case "IdentifierPattern": {
         const id = this.bindingIdByName(target.name, target);
@@ -9369,7 +9454,7 @@ var TypeAnalyzer = class {
         for (const p of target.properties) {
           const key = !p.computed && p.key.type === "Identifier" ? p.key.name : !p.computed && p.key.type === "StringLiteral" ? p.key.value : void 0;
           const propType = key !== void 0 ? this.propertyType(valueType, key) : unknownType;
-          this.bindPattern(p.value, this.withDefault(propType, p.default, env), env, mode);
+          this.bindPattern(p.value, this.withDefault(propType, p.default, env), env, mode, memberLabel(label, key));
         }
         if (target.rest) this.bindPattern(target.rest, this.withoutKeys(valueType, target.properties), env, mode);
         return;
@@ -9377,7 +9462,7 @@ var TypeAnalyzer = class {
       case "ArrayPattern": {
         target.elements.forEach((el, i) => {
           if (!el) return;
-          this.bindPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env, mode);
+          this.bindPattern(el.value, this.withDefault(this.elementType(valueType, i), el.default, env), env, mode, memberLabel(label, i + 1));
         });
         if (target.rest) this.bindPattern(target.rest, this.restAfter(valueType, target.elements.length), env, mode);
         return;
@@ -9942,6 +10027,7 @@ var TypeAnalyzer = class {
       }
       // Broken syntax is reported by the parser; nothing more to say.
       case "ErrorExpression":
+        if (expr.expression) this.infer(expr.expression, env);
         return anyType;
       case "Identifier": {
         const id = this.bindingIdOf(expr);
@@ -10005,6 +10091,14 @@ var TypeAnalyzer = class {
             this.checkOperands(expr, "#", arg);
             return numberType;
           }
+          case "typeof": {
+            const names = this.typeofNamesOf(arg);
+            const tables = names && [...names].filter((name) => name === "array" || name === "object");
+            if (tables?.length === 1) this.typeofTables.set(expr, tables[0]);
+            else this.typeofTables.delete(expr);
+            const answers = names?.size ? [...names] : [...this.typeofTypes().keys()];
+            return union(answers.map((name) => literal(name)));
+          }
         }
         return arg;
       }
@@ -10047,7 +10141,9 @@ var TypeAnalyzer = class {
             return booleanType;
           case "==":
           case "~=":
-            this.checkOverlap(expr, op, l, r);
+            if (!this.checkTypeofName(expr, expr.left, expr.right) && !this.checkTypeofName(expr, expr.right, expr.left)) {
+              this.checkOverlap(expr, op, l, r);
+            }
             return booleanType;
           case "+":
           case "-":
@@ -10248,6 +10344,7 @@ var TypeAnalyzer = class {
     const fromMetatable = this.receiverMetatableMember(objType, expr.method.name);
     if (fromMetatable) this.methodSources.set(expr, fromMetatable.source);
     const method = fromMetatable?.type ?? this.propertyType(objType, expr.method.name);
+    this.typeOf.set(expr.method, method);
     const united = this.unionSignatures(method);
     const fns = united ?? this.overloadsOf(method);
     const explicit = this.explicitTypeArguments(expr, fns);
@@ -10388,6 +10485,43 @@ var TypeAnalyzer = class {
       message: `Cannot assign to '${name}' because it is a read-only property`
     });
   }
+  /** `t.x = v` against what `x` was declared as. Only a property the
+   *  table's type names is checked: a key it does not name is the Lua
+   *  table growing, which `checkMissingMember` is not about. */
+  checkMemberAssign(stmt, target, value, env) {
+    if (!this.emitDiagnostics) return;
+    let name;
+    if (target.type === "MemberExpression") {
+      name = target.property.name;
+    } else {
+      const index = this.expand(this.infer(target.index, env));
+      if (index.kind !== "literal" || typeof index.value !== "string") return;
+      name = index.value;
+    }
+    if (target.object.type === "Identifier") {
+      const id = this.bindingIdOf(target.object);
+      if (id !== void 0 && this.scopes.bindings.get(id)?.declaredBy === "namespace") return;
+    }
+    const declared = this.declaredProperty(this.expand(this.infer(target.object, env)), name);
+    if (!declared || declared.kind === "any" || declared.kind === "unknown") return;
+    if (this.fitsAnnotation(stmt.value, declared, value, env)) return;
+    this.diagnostics.push({
+      node: stmt,
+      message: `Type '${briefType(value)}' is not assignable to '${briefType(declared)}'` + this.explainMismatch(value, declared)
+    });
+  }
+  /** The type a property was declared with, where the type names it. */
+  declaredProperty(t, name) {
+    if (t.kind === "object") {
+      const p = t.properties.get(name);
+      return p && (p.optional ? optional(p.type) : p.type);
+    }
+    if (t.kind === "intersection") {
+      const parts = t.types.flatMap((m) => this.declaredProperty(this.expand(m), name) ?? []);
+      return parts.length ? intersection(parts) : void 0;
+    }
+    return void 0;
+  }
   isReadonlyProperty(t, name) {
     if (t.kind === "object") return t.properties.get(name)?.readonly === true;
     if (t.kind === "intersection" || t.kind === "union") {
@@ -10783,13 +10917,23 @@ var TypeAnalyzer = class {
     if (cond.type === "BinaryExpression") {
       const { operator: op, left, right } = cond;
       if (op === "and") {
-        this.applyNarrowing(left, env, t, forkEnv(env));
-        this.applyNarrowing(right, t, t, forkEnv(t));
+        const before = forkEnv(env);
+        const leftFailed = forkEnv(env);
+        this.applyNarrowing(left, env, t, leftFailed);
+        const between = forkEnv(t);
+        const rightFailed = forkEnv(t);
+        this.applyNarrowing(right, t, t, rightFailed);
+        joinNarrowings(f, leftFailed, before, rightFailed, between);
         return;
       }
       if (op === "or") {
-        this.applyNarrowing(left, env, forkEnv(env), f);
-        this.applyNarrowing(right, f, forkEnv(f), f);
+        const before = forkEnv(env);
+        const leftHeld = forkEnv(env);
+        this.applyNarrowing(left, env, leftHeld, f);
+        const between = forkEnv(f);
+        const rightHeld = forkEnv(f);
+        this.applyNarrowing(right, f, rightHeld, f);
+        joinNarrowings(t, leftHeld, before, rightHeld, between);
         return;
       }
       if (op === "==" || op === "~=") {
@@ -10808,11 +10952,13 @@ var TypeAnalyzer = class {
     this.narrowOptionalLinks(cond, env, t);
   }
   /** `a == b` / `a ~= b`. Handles, in order: a declaration-driven
-   *  `typeof(x) == "..."` test, a literal/`nil` comparison against a
+   *  `typeof x == "..."` test, a literal/`nil` comparison against a
    *  reference, and a reference-to-reference comparison. */
   narrowByComparison(left, right, eq, env, t, f) {
     const yes = eq ? t : f;
     const no = eq ? f : t;
+    if (this.narrowByTypeof(left, right, yes, no, env)) return;
+    if (this.narrowByTypeof(right, left, yes, no, env)) return;
     if (this.narrowByCallResult(left, right, yes, no, env)) return;
     if (this.narrowByCallResult(right, left, yes, no, env)) return;
     const litOf = (e) => {
@@ -10839,18 +10985,149 @@ var TypeAnalyzer = class {
       this.narrowRef(right, env, yes, no, (cur) => ({ yes: narrowTo(cur, lt), no: cur }));
     }
   }
-  /** Declaration-driven `typeof(x) == "number"`.
-   *
-   *  `typeof` is not special-cased: it is declared in the definitions as an
-   *  overload set whose members return *string-literal* types
-   *  (`(value: number) -> "number"`, ...). So for `f(x) == "lit"` we keep the
-   *  parameter types of the overloads that can return `"lit"`, and that union
-   *  is what `x` narrows to. Any user function declared the same way gets the
-   *  same treatment for free.
+  // --------------------------------------------------------
+  // typeof
+  // --------------------------------------------------------
+  //
+  // `typeof v` answers what Luau's `typeof` does, except for a table: that
+  // is an `"array"` or an `"object"`. The names of a runtime's own values —
+  // Roblox's `"Instance"`, `"Vector3"` — are a library's to give: it
+  // declares `type TypeofNames = { Vector3: Vector3, Instance: Instance }`,
+  // each property the name `typeof` answers for a value of that type. A
+  // value several of them fit is the first one's.
+  typeofTypesCache;
+  /** Every name `typeof` answers, and what a value it answered that for
+   *  is — `unknown` where nothing more is known. */
+  typeofTypes() {
+    if (this.typeofTypesCache) return this.typeofTypesCache;
+    const types = /* @__PURE__ */ new Map([
+      ["nil", nilType],
+      ["boolean", booleanType],
+      ["number", numberType],
+      ["string", stringType],
+      ["function", fn([], declaredUnknownType, declaredUnknownType)],
+      ["array", arrayOf(declaredUnknownType)],
+      ["object", objectType([], { key: declaredUnknownType, value: declaredUnknownType })],
+      ["thread", threadType],
+      ["buffer", bufferType],
+      ["userdata", unknownType]
+    ]);
+    for (const [name, type] of this.typeofLibraryNames()) if (!types.has(name)) types.set(name, type);
+    return this.typeofTypesCache = types;
+  }
+  typeofLibraryCache;
+  typeofLibraryNames() {
+    if (this.typeofLibraryCache) return this.typeofLibraryCache;
+    const declared = this.aliases.get("TypeofNames");
+    const names = declared && this.expand(declared);
+    return this.typeofLibraryCache = names?.kind === "object" ? [...names.properties].map(([name, property]) => [name, property.type]) : [];
+  }
+  /** The names `typeof` can answer for a value of type `raw`, or
+   *  `undefined` where the type does not say. */
+  typeofNamesOf(raw, depth = 0) {
+    if (depth > 8) return void 0;
+    const t = this.expand(raw);
+    switch (t.kind) {
+      case "never":
+        return /* @__PURE__ */ new Set();
+      case "primitive":
+        return /* @__PURE__ */ new Set([t.name]);
+      case "literal":
+        return /* @__PURE__ */ new Set([t.base]);
+      case "templateLiteral":
+        return /* @__PURE__ */ new Set(["string"]);
+      case "array":
+      case "tuple":
+        return /* @__PURE__ */ new Set(["array"]);
+      case "function":
+        return /* @__PURE__ */ new Set(["function"]);
+      case "object": {
+        const named = t.class && this.typeofLibraryNames().find(([, type]) => isAssignable(t, type));
+        return /* @__PURE__ */ new Set([named ? named[0] : "object"]);
+      }
+      case "union": {
+        const all = /* @__PURE__ */ new Set();
+        for (const member of t.types) {
+          const names = this.typeofNamesOf(member, depth + 1);
+          if (!names) return void 0;
+          for (const name of names) all.add(name);
+        }
+        return all;
+      }
+      case "intersection": {
+        const known = t.types.map((part) => this.typeofNamesOf(part, depth + 1)).filter((names) => names !== void 0);
+        if (!known.length) return void 0;
+        const common = [...known[0]].filter((name) => known.every((names) => names.has(name)));
+        return new Set(common.length ? common : known[0]);
+      }
+      case "typeParam":
+        return t.constraint ? this.typeofNamesOf(t.constraint, depth + 1) : void 0;
+      case "difference":
+        return this.typeofNamesOf(t.base, depth + 1);
+      default:
+        return void 0;
+    }
+  }
+  /** `typeof v == "table"`: a name `typeof` never answers. Returns true if
+   *  the comparison needs no further checking. */
+  checkTypeofName(node, typeofSide, nameSide) {
+    const test = unwrapParens(typeofSide);
+    if (test.type !== "UnaryExpression" || test.operator !== "typeof") return false;
+    const name = this.asLiteral(unwrapParens(nameSide));
+    if (typeof name !== "string") return false;
+    if (name === "nil") return true;
+    if (this.typeofTypes().has(name)) return false;
+    if (this.emitDiagnostics) {
+      this.diagnostics.push({
+        node,
+        message: name === "table" ? `'typeof' never answers "table": a table is an "array" or an "object"` : `'typeof' never answers "${name}"`
+      });
+    }
+    return true;
+  }
+  /** `typeof x == "number"`: `x` is what answers that name where the test
+   *  holds, and what does not where it fails. Returns true if `testSide` is
+   *  a `typeof` compared with a name. */
+  narrowByTypeof(testSide, nameSide, yes, no, env) {
+    const test = unwrapParens(testSide);
+    if (test.type !== "UnaryExpression" || test.operator !== "typeof") return false;
+    const name = this.asLiteral(unwrapParens(nameSide));
+    if (typeof name !== "string") return false;
+    const answered = this.typeofTypes().get(name);
+    if (!answered) return true;
+    const opaque = answered.kind !== "unknown";
+    const subtracts = opaque && name !== "array" && name !== "object";
+    const members = (cur) => {
+      const t = this.expand(cur);
+      return t.kind === "union" ? t.types.flatMap(members) : [t];
+    };
+    if (this.refKeyOf(test.argument) !== void 0) {
+      this.narrowRef(test.argument, env, yes, no, (cur) => {
+        const kept = [];
+        const dropped = [];
+        for (const member of members(cur)) {
+          const names = this.typeofNamesOf(member);
+          if (!names) {
+            kept.push(opaque ? narrowTo(member, answered) : member);
+            dropped.push(subtracts ? narrowExclude(member, answered) : member);
+            continue;
+          }
+          if (names.has(name)) kept.push(member);
+          if (!(names.size === 1 && names.has(name))) dropped.push(member);
+        }
+        return { yes: union(kept), no: union(dropped) };
+      });
+    }
+    this.narrowOptionalLinks(test.argument, env, name === "nil" ? no : yes);
+    return true;
+  }
+  /** Declaration-driven `kind(x) == "number"`.
    *
-   *  The analyzer knows nothing about the names `type` and `typeof`: with no
-   *  definitions loaded there are no literal-returning overloads and this
-   *  narrows nothing. Returns true if it handled the comparison. */
+   *  A function declared as an overload set whose members return
+   *  *string-literal* types (`(value: number) => "number"`, ...) says by its
+   *  answer what it was given. So for `f(x) == "lit"` we keep the parameter
+   *  types of the overloads that can return `"lit"`, and that union is what
+   *  `x` narrows to. Returns true if it handled the comparison. */
   narrowByCallResult(callSide, litSide, yes, no, env) {
     if (callSide.type !== "CallExpression" || callSide.arguments.length !== 1) return false;
     const name = this.asLiteral(litSide);