xbintsc 0.5.23 → 0.5.32

package/src/binder/types.ts

@@ -43,6 +43,24 @@ export interface SymbolInfo {
   boxed: boolean;
 }
 
+/**
+ * A same-scope declaration that cannot legally merge with the symbol already
+ * bound to that name (`let x` twice, `function f` then `const f`, ...).
+ *
+ * The binder records the conflict instead of reporting it: whether it is an
+ * error is checker policy (`--no-check` keeps the old, permissive behaviour),
+ * while the fact itself is cheap to capture during the one declaration pass.
+ */
+export interface DeclarationConflict {
+  readonly name: string;
+  /** The symbol the name was already bound to. */
+  readonly existing: SymbolInfo;
+  /** The kind of the offending declaration. */
+  readonly kind: SymbolKind;
+  /** The offending declaration node (the second one to use the name). */
+  readonly node: Node;
+}
+
 export type FunctionNode = SourceFileNode | FunctionDeclaration | FunctionExpression | ArrowFunction;
 
 export interface FunctionInfo {
@@ -88,10 +106,20 @@ export interface ClassInfo {
   readonly fields: ClassFieldInfo[];
   readonly methods: FunctionInfo[];
   readonly statics: FunctionInfo[];
+  /** `static { ... }` blocks, in declaration order. */
+  readonly staticBlocks: FunctionInfo[];
+  /** Static fields and static blocks, interleaved in declaration order: they
+   *  run in source order, while static methods are installed before both. */
+  readonly staticInit: ClassStaticInit[];
   ctor?: FunctionInfo;
   /** The symbol the class name binds to, when there is one. */
 }
 
+/** One static element evaluated at class-definition time, in source order. */
+export type ClassStaticInit =
+  | { readonly kind: "field"; readonly field: ClassFieldInfo }
+  | { readonly kind: "block"; readonly fn: FunctionInfo };
+
 export interface ClassFieldInfo {
   readonly name: string;
   readonly initializer: Expression | undefined;
@@ -129,6 +157,8 @@ export interface BindResult {
   readonly scopes: Map<Node, Scope>;
   /** Identifier references that could not be resolved in user code. */
   readonly unresolved: Identifier[];
+  /** Same-scope declarations that cannot merge (see {@link DeclarationConflict}). */
+  readonly conflicts: readonly DeclarationConflict[];
 }
 
 export interface MutableFunction extends FunctionInfo {

package/src/canonical.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical bytes for compiler-emitted artifacts.
+ *
+ * The compiler runs on Windows, macOS and Linux, and can be compiled by
+ * itself. Anything it writes into a byte-compared artifact — LLVM IR, debug
+ * metadata, the compiler fingerprint, the bundled module text and the `path`
+ * module's results — has to use the same representation on every host. These
+ * constants are that representation: do not spell `"/"` or `"\n"` in code that
+ * emits an artifact.
+ *
+ * Native paths are deliberately different. Diagnostics, `import.meta.filename`
+ * and `process.cwd()` keep the host separator, exactly like Node. Convert a
+ * native path with {@link artifactPath} only when it enters an artifact.
+ */
+
+/** Separator between path segments in a compiler artifact. Deliberately not
+ *  selected by `process.platform`: every host writes `/`, so the same source
+ *  produces the same bytes (and Windows accepts `/` in every API). */
+export const ARTIFACT_PATH_SEPARATOR = "/";
+
+/** Line ending between records in a compiler artifact. Deliberately not
+ *  `os.EOL`/`"\r\n"` on Windows: the runtime opens stdout/stderr in binary
+ *  mode, and CRLF would make IR, fingerprints and documentation differ per
+ *  host. */
+export const ARTIFACT_LINE_ENDING = "\n";
+
+/**
+ * Rewrite a native path for an artifact: `C:\dir\file.ts` becomes
+ * `C:/dir/file.ts`. A backslash is always a separator here, matching how the
+ * runtime and Node treat Windows paths.
+ */
+export function artifactPath(path: string): string {
+  // `split`/`join` is measurably faster than a regex or `replaceAll` for the
+  // short paths this sees (it runs once per emitted stack frame), and it is the
+  // exact transform the compiler used before it was centralised.
+  return path.split("\\").join(ARTIFACT_PATH_SEPARATOR);
+}

package/src/checker/assignability.ts

@@ -0,0 +1,134 @@
+/**
+ * Structural assignability for the small type model.
+ *
+ * This is intentionally lenient: every case the model cannot decide returns
+ * `true`. A `false` is reserved for a definite mismatch (a string where a
+ * number is required, a required property that is absent from a closed shape),
+ * because a false negative only hides a bug while a false positive rejects
+ * working code.
+ */
+
+import { isAny, unionMembers, type Type } from "./type-model.js";
+
+const MAX_DEPTH = 8;
+
+export function isAssignable(source: Type, target: Type, depth = 0): boolean {
+  if (depth > MAX_DEPTH) return true;
+  if (isAny(source) || isAny(target)) return true;
+
+  // Every member of a source union must fit; a target union accepts if any
+  // member fits. Source first, so `("a" | "b")` fits `("a" | "b")`.
+  if (source.kind === "union") {
+    return source.members.every((member) => isAssignable(member, target, depth + 1));
+  }
+  if (target.kind === "union") {
+    return target.members.some((member) => isAssignable(source, member, depth + 1));
+  }
+
+  if (target.kind === "literal") {
+    if (source.kind === "literal") return source.value === target.value;
+    if (source.kind === "primitive") return source.name === target.primitive;
+    return false;
+  }
+
+  if (target.kind === "primitive") {
+    return assignableToPrimitive(source, target.name);
+  }
+
+  if (source.kind === "literal") {
+    if (target.kind === "object") return false;
+    if (target.kind === "array" || target.kind === "tuple" || target.kind === "function") return false;
+    return true;
+  }
+
+  if (source.kind === "primitive") {
+    // `null` / `undefined` are accepted everywhere: the compiler does not
+    // enable strict-null checking, so rejecting them would break working code.
+    if (source.name === "null" || source.name === "undefined" || source.name === "void") return true;
+    if (target.kind === "object") return false;
+    if (target.kind === "array" || target.kind === "tuple" || target.kind === "function") return false;
+    return true;
+  }
+
+  if (target.kind === "array") {
+    if (source.kind === "array") return isAssignable(source.element, target.element, depth + 1);
+    if (source.kind === "tuple") return source.elements.every((element) => isAssignable(element, target.element, depth + 1));
+    return false;
+  }
+
+  if (target.kind === "tuple") {
+    if (source.kind === "tuple") {
+      if (source.elements.length !== target.elements.length) return false;
+      return source.elements.every((element, index) => isAssignable(element, target.elements[index]!, depth + 1));
+    }
+    // Array-to-tuple is not generally safe, but the model cannot prove it is
+    // wrong, so stay silent.
+    return source.kind === "array";
+  }
+
+  if (target.kind === "object") {
+    if (source.kind === "array" || source.kind === "tuple") {
+      // Arrays have prototype members this model does not enumerate; only a
+      // target with no required properties can be judged.
+      return [...target.properties.values()].every((property) => property.optional);
+    }
+    if (source.kind !== "object") return false;
+    for (const [name, targetProperty] of target.properties) {
+      const sourceProperty = source.properties.get(name);
+      if (!sourceProperty) {
+        if (targetProperty.optional) continue;
+        if (source.index && isAssignable(source.index, targetProperty.type, depth + 1)) continue;
+        if (!target.closed) continue;
+        return false;
+      }
+      if (!isAssignable(sourceProperty.type, targetProperty.type, depth + 1)) return false;
+    }
+    if (target.index) {
+      if (source.index && !isAssignable(source.index, target.index, depth + 1)) return false;
+      for (const property of source.properties.values()) {
+        if (!isAssignable(property.type, target.index, depth + 1)) return false;
+      }
+    }
+    return true;
+  }
+
+  if (target.kind === "function") {
+    if (source.kind !== "function") {
+      // A function-typed value can also wear object members; do not guess.
+      return source.kind === "object";
+    }
+    const required = target.parameters.filter((parameter) => !parameter.optional && !parameter.rest).length;
+    if (source.parameters.length < required) return false;
+    for (let index = 0; index < target.parameters.length; index++) {
+      const sourceParameter = source.parameters[index];
+      const targetParameter = target.parameters[index];
+      if (!sourceParameter || !targetParameter) break;
+      if (!isAssignable(targetParameter.type, sourceParameter.type, depth + 1)) return false;
+    }
+    return isAssignable(source.returnType, target.returnType, depth + 1);
+  }
+
+  return true;
+}
+
+function assignableToPrimitive(source: Type, name: string): boolean {
+  if (name === "null" || name === "undefined" || name === "void") return true;
+  if (source.kind === "literal") return source.primitive === name;
+  if (source.kind === "primitive") {
+    if (source.name === "null" || source.name === "undefined" || source.name === "void") return true;
+    return source.name === name;
+  }
+  if (name === "object") return source.kind === "object" || source.kind === "array" || source.kind === "tuple" || source.kind === "function";
+  return false;
+}
+
+/** True only when the value is definitely not callable (not merely unknown). */
+export function isDefinitelyNotCallable(type: Type): boolean {
+  const members = unionMembers(type);
+  return members.every((member) => {
+    if (member.kind === "primitive") {
+      return member.name === "number" || member.name === "string" || member.name === "boolean" || member.name === "bigint" || member.name === "symbol" || member.name === "null" || member.name === "undefined";
+    }
+    return member.kind === "literal";
+  });
+}

package/src/checker/calls.ts

@@ -0,0 +1,135 @@
+/**
+ * Call arity: `f(1)` where `f` declares two required parameters.
+ *
+ * Only calls whose callee the checker can resolve without inference are
+ * checked: a direct identifier bound to a function declaration, or to a
+ * `const` initialised with a function expression / arrow. Methods, imports,
+ * first-class re-exports and reassigned bindings are left alone — guessing
+ * there is how a checker produces false positives.
+ */
+
+import {
+  SyntaxKind,
+  type BinaryExpression,
+  type CallExpression,
+  type Expression,
+  type Identifier,
+  type Parameter,
+  type SourceFileNode,
+} from "../ast/nodes.js";
+import { SymbolKind, type BindResult, type FunctionInfo } from "../binder/binder.js";
+import { DiagnosticCode, type DiagnosticBag } from "../diagnostics/diagnostic.js";
+import { ASSIGNMENT_OPERATORS } from "../codegen/generator/tables.js";
+import { fileNameOf, isUntypedNode } from "./source.js";
+import { walk } from "./walk.js";
+
+interface Arity {
+  /** Leading parameters that must be supplied. */
+  readonly required: number;
+  /** Total parameters, or `Infinity` for a rest parameter. */
+  readonly max: number;
+}
+
+function arityOf(fn: FunctionInfo): Arity | undefined {
+  const parameters = (fn.node as unknown as { parameters?: readonly Parameter[] }).parameters;
+  if (!parameters) return undefined;
+  let required = 0;
+  let max = 0;
+  for (const parameter of parameters) {
+    if (parameter.dotDotDotToken) return { required, max: Number.POSITIVE_INFINITY };
+    max++;
+    // A `this:` parameter is a type-only declaration: it is erased and never
+    // occupies an argument slot.
+    if (parameter.name.kind === SyntaxKind.Identifier && (parameter.name as Identifier).text === "this") {
+      max--;
+      continue;
+    }
+    if (!parameter.questionToken && !parameter.initializer) required = max;
+  }
+  return { required, max };
+}
+
+/** Symbols written after their declaration (so their signature can change). */
+function collectAssignedSymbols(sourceFile: SourceFileNode, binding: BindResult): Set<number> {
+  const assigned = new Set<number>();
+  walk(sourceFile, (node) => {
+    if (node.kind !== SyntaxKind.BinaryExpression) return;
+    const binary = node as BinaryExpression;
+    if (!ASSIGNMENT_OPERATORS.has(binary.operator)) return;
+    if (binary.left.kind !== SyntaxKind.Identifier) return;
+    const symbol = binding.symbolOfIdentifier.get(binary.left as Identifier);
+    if (symbol) assigned.add(symbol.id);
+  });
+  return assigned;
+}
+
+function resolveCallee(binding: BindResult, assigned: ReadonlySet<number>, callee: Expression): FunctionInfo | undefined {
+  if (callee.kind !== SyntaxKind.Identifier) return undefined;
+  const symbol = binding.symbolOfIdentifier.get(callee as Identifier);
+  if (!symbol || symbol.declarations.length !== 1 || assigned.has(symbol.id)) return undefined;
+  if (symbol.kind === SymbolKind.Function) {
+    return binding.functionOfNode.get(symbol.declarations[0]!);
+  }
+  if (symbol.kind === SymbolKind.Const) {
+    const declaration = symbol.declarations[0]!;
+    if (declaration.kind !== SyntaxKind.VariableDeclaration) return undefined;
+    const initializer = (declaration as unknown as { initializer?: Expression }).initializer;
+    if (!initializer) return undefined;
+    if (initializer.kind !== SyntaxKind.ArrowFunction && initializer.kind !== SyntaxKind.FunctionExpression) {
+      return undefined;
+    }
+    return binding.functionOfNode.get(initializer);
+  }
+  return undefined;
+}
+
+function plural(count: number): string {
+  return count === 1 ? "argument" : "arguments";
+}
+
+function expected(arity: Arity): string {
+  if (arity.max === Number.POSITIVE_INFINITY) return `at least ${arity.required} ${plural(arity.required)}`;
+  if (arity.required === arity.max) return `${arity.required} ${plural(arity.required)}`;
+  return `${arity.required}-${arity.max} ${plural(arity.max)}`;
+}
+
+export function checkCallArity(
+  sourceFile: SourceFileNode,
+  binding: BindResult,
+  diagnostics: DiagnosticBag,
+): void {
+  const assigned = collectAssignedSymbols(sourceFile, binding);
+  /* `function f() { return arguments.length; }` is a declared-zero-parameter
+   * function that legitimately accepts any number of arguments; its parameter
+   * list is not the whole signature. */
+  const argumentsUsers = new Map<number, boolean>();
+  const usesArguments = (fn: FunctionInfo): boolean => {
+    const cached = argumentsUsers.get(fn.id);
+    if (cached !== undefined) return cached;
+    let found = false;
+    walk(fn.node, (node) => {
+      if (node.kind === SyntaxKind.Identifier && (node as Identifier).text === "arguments") found = true;
+    });
+    argumentsUsers.set(fn.id, found);
+    return found;
+  };
+  walk(sourceFile, (node) => {
+    if (node.kind !== SyntaxKind.CallExpression) return;
+    if (isUntypedNode(sourceFile, node)) return;
+    const call = node as CallExpression;
+    if (call.optional) return;
+    if (call.arguments.some((argument) => argument.kind === SyntaxKind.SpreadElement)) return;
+    const fn = resolveCallee(binding, assigned, call.expression);
+    if (!fn || fn.isModule || usesArguments(fn)) return;
+    const arity = arityOf(fn);
+    if (!arity) return;
+    const argc = call.arguments.length;
+    if (argc >= arity.required && argc <= arity.max) return;
+    diagnostics.error(
+      DiagnosticCode.ArgumentCountMismatch,
+      `Expected ${expected(arity)}, but got ${argc}.`,
+      call,
+      fileNameOf(sourceFile, call),
+    );
+  });
+}

package/src/checker/checker.ts

@@ -0,0 +1,47 @@
+/**
+ * The opt-out semantic checker (`--check` / `--no-check`).
+ *
+ * It runs after binding and before code generation. The first three passes are
+ * inference-free:
+ *
+ *   1. identifier references with no declaration and no runtime global,
+ *   2. same-scope declarations that cannot merge (`let x` twice, ...),
+ *   3. calls whose argument count cannot match a locally-visible signature.
+ *
+ * The fourth pass uses a deliberately small structural type model to check
+ * assignability, property existence and simple flow narrowing. It understands
+ * annotations, interfaces, classes, arrays, functions, unions and simple
+ * generics; anything else is `any`, so unsupported syntax can hide a bug but
+ * never reject working code.
+ */
+
+import type { SourceFileNode } from "../ast/nodes.js";
+import type { BindResult } from "../binder/binder.js";
+import type { DiagnosticBag } from "../diagnostics/diagnostic.js";
+import { checkCallArity } from "./calls.js";
+import { reportDeclarationConflicts } from "./declarations.js";
+import { checkTypes } from "./typecheck.js";
+import { checkUnresolvedNames } from "./undefined.js";
+
+export interface CheckOptions {
+  /** Globals supplied by the registered extensions (`print`, `__registerScript`, ...). */
+  readonly builtins?: Readonly<Record<string, unknown>>;
+  /** Global values supplied by the registered extensions (`window`, `document`). */
+  readonly globalValues?: Readonly<Record<string, unknown>>;
+}
+
+export function checkProgram(
+  sourceFile: SourceFileNode,
+  binding: BindResult,
+  diagnostics: DiagnosticBag,
+  options: CheckOptions = {},
+): void {
+  const builtinNames = new Set<string>([
+    ...Object.keys(options.builtins ?? {}),
+    ...Object.keys(options.globalValues ?? {}),
+  ]);
+  checkUnresolvedNames(sourceFile, binding, diagnostics, builtinNames);
+  reportDeclarationConflicts(sourceFile, binding, diagnostics);
+  checkCallArity(sourceFile, binding, diagnostics);
+  checkTypes(sourceFile, binding, diagnostics);
+}

package/src/checker/declarations.ts

@@ -0,0 +1,26 @@
+/**
+ * Redeclarations: the binder records same-scope declarations that cannot merge
+ * (`let x` twice, `function f` followed by `const f`, ...). This pass turns
+ * those facts into diagnostics.
+ */
+
+import type { SourceFileNode } from "../ast/nodes.js";
+import type { BindResult } from "../binder/binder.js";
+import { DiagnosticCode, type DiagnosticBag } from "../diagnostics/diagnostic.js";
+import { fileNameOf, isDependencyNode } from "./source.js";
+
+export function reportDeclarationConflicts(
+  sourceFile: SourceFileNode,
+  binding: BindResult,
+  diagnostics: DiagnosticBag,
+): void {
+  for (const conflict of binding.conflicts) {
+    if (isDependencyNode(sourceFile, conflict.node)) continue;
+    diagnostics.error(
+      DiagnosticCode.DuplicateIdentifier,
+      `Duplicate identifier '${conflict.name}'.`,
+      conflict.node,
+      fileNameOf(sourceFile, conflict.node),
+    );
+  }
+}

package/src/checker/flow.ts

@@ -0,0 +1,236 @@
+/**
+ * Lightweight control-flow narrowing.
+ *
+ * Only the predicates whose refinement is unambiguous are handled:
+ * `typeof x === "..."`, comparisons with `null`/`undefined`, `instanceof`,
+ * truthiness and the `&&` / `||` / `??` forms that combine them. Everything
+ * else leaves the flow untouched, so a missed narrowing can only hide an
+ * error, never invent one.
+ */
+
+import {
+  SyntaxKind,
+  type BinaryExpression,
+  type Expression,
+  type Identifier,
+  type PrefixUnaryExpression,
+  type TypeOfExpression,
+} from "../ast/nodes.js";
+import { primitive, unionMembers, unwrap, type Type } from "./type-model.js";
+import type { TypeResolver } from "./type-system.js";
+
+export class Flow {
+  constructor(
+    readonly parent?: Flow,
+    readonly overrides: ReadonlyMap<number, Type> = new Map(),
+  ) {}
+
+  typeOf(symbolId: number): Type | undefined {
+    return this.overrides.get(symbolId) ?? this.parent?.typeOf(symbolId);
+  }
+
+  with(overrides: ReadonlyMap<number, Type>): Flow {
+    return new Flow(this, overrides);
+  }
+}
+
+function merge(...maps: ReadonlyMap<number, Type>[]): Map<number, Type> {
+  const result = new Map<number, Type>();
+  for (const map of maps) for (const [key, value] of map) result.set(key, value);
+  return result;
+}
+
+function symbolIdOf(expression: Expression, resolver: TypeResolver): number | undefined {
+  const unwrapped = unwrap(expression);
+  if (unwrapped.kind !== SyntaxKind.Identifier) return undefined;
+  return resolver.binding.symbolOfIdentifier.get(unwrapped as Identifier)?.id;
+}
+
+function nullishKind(expression: Expression): "null" | "undefined" | "nullish" | undefined {
+  const unwrapped = unwrap(expression);
+  if (unwrapped.kind === SyntaxKind.NullKeyword) return "null";
+  if (unwrapped.kind === SyntaxKind.UndefinedKeyword) return "undefined";
+  if (unwrapped.kind === SyntaxKind.Identifier && (unwrapped as Identifier).text === "undefined") return "undefined";
+  return undefined;
+}
+
+function literalType(expression: Expression): Type | undefined {
+  const unwrapped = unwrap(expression);
+  switch (unwrapped.kind) {
+    case SyntaxKind.StringLiteral:
+    case SyntaxKind.NoSubstitutionTemplateLiteral:
+      return { kind: "literal", value: (unwrapped as { value: string }).value, primitive: "string" };
+    case SyntaxKind.NumericLiteral:
+      return { kind: "literal", value: (unwrapped as { value: number }).value, primitive: "number" };
+    case SyntaxKind.TrueKeyword:
+      return { kind: "literal", value: true, primitive: "boolean" };
+    case SyntaxKind.FalseKeyword:
+      return { kind: "literal", value: false, primitive: "boolean" };
+    default:
+      return undefined;
+  }
+}
+
+const TYPEOF_NAMES: Readonly<Record<string, "string" | "number" | "boolean" | "bigint" | "symbol" | "undefined">> = {
+  string: "string",
+  number: "number",
+  boolean: "boolean",
+  bigint: "bigint",
+  symbol: "symbol",
+  undefined: "undefined",
+};
+
+function filterType(type: Type, predicate: (member: Type) => boolean): Type | undefined {
+  const kept = unionMembers(type).filter(predicate);
+  if (kept.length === 0) return undefined;
+  if (kept.length === 1) return kept[0]!;
+  return { kind: "union", members: kept };
+}
+
+export function withoutNullish(type: Type): Type {
+  return filterType(type, (member) => !(member.kind === "primitive" && (member.name === "null" || member.name === "undefined"))) ?? type;
+}
+
+function refine(type: Type, predicate: (member: Type) => boolean): Type | undefined {
+  return filterType(type, predicate);
+}
+
+function positiveRefinement(expression: Expression, flow: Flow, resolver: TypeResolver): Map<number, Type> {
+  const result = new Map<number, Type>();
+  const unwrapped = unwrap(expression);
+
+  if (unwrapped.kind === SyntaxKind.Identifier) {
+    const id = symbolIdOf(unwrapped, resolver);
+    if (id !== undefined) {
+      const type = flow.typeOf(id) ?? resolver.typeOfSymbolId(id);
+      if (type) result.set(id, withoutNullish(type));
+    }
+    return result;
+  }
+
+  if (unwrapped.kind === SyntaxKind.PrefixUnaryExpression) {
+    const unary = unwrapped as PrefixUnaryExpression;
+    if (unary.operator === "!") return negativeRefinement(unary.operand, flow, resolver);
+    return result;
+  }
+
+  if (unwrapped.kind !== SyntaxKind.BinaryExpression) return result;
+  const binary = unwrapped as BinaryExpression;
+  const operator = binary.operator;
+
+  if (operator === "&&") return merge(positiveRefinement(binary.left, flow, resolver), positiveRefinement(binary.right, flow, resolver));
+  if (operator === "||") {
+    // `a || b` is truthy when either side is; no single refinement to apply.
+    return result;
+  }
+  if (operator === "??") return positiveRefinement(binary.left, flow, resolver);
+
+  const equality = operator === "===" || operator === "==";
+  const inequality = operator === "!==" || operator === "!=";
+  if (equality || inequality) {
+    const leftNullish = nullishKind(binary.left);
+    const rightNullish = nullishKind(binary.right);
+    const nullish = leftNullish ?? rightNullish;
+    const other = leftNullish ? binary.right : binary.left;
+    const id = symbolIdOf(other, resolver);
+    if (id !== undefined && nullish) {
+      if (equality) {
+        const target = nullish === "nullish" ? [primitive("null"), primitive("undefined")] : [primitive(nullish)];
+        for (const type of target) result.set(id, type);
+      } else {
+        const base = flow.typeOf(id) ?? resolver.typeOfSymbolId(id);
+        if (base) {
+          const narrowed = refine(base, (member) => !(member.kind === "primitive" && (member.name === "null" || member.name === "undefined")));
+          if (narrowed) result.set(id, narrowed);
+        }
+      }
+      return result;
+    }
+    // `typeof x === "string"` and friends.
+    const typeofSide = unwrap(binary.left).kind === SyntaxKind.TypeOfExpression ? binary.left : unwrap(binary.right).kind === SyntaxKind.TypeOfExpression ? binary.right : undefined;
+    const literalSide = literalType(typeofSide === binary.left ? binary.right : binary.left);
+    if (typeofSide && literalSide?.kind === "literal" && typeof literalSide.value === "string") {
+      const name = TYPEOF_NAMES[literalSide.value];
+      const operand = (unwrap(typeofSide) as TypeOfExpression).expression;
+      const operandId = symbolIdOf(operand, resolver);
+      if (name && operandId !== undefined) {
+        const base = flow.typeOf(operandId) ?? resolver.typeOfSymbolId(operandId);
+        if (base) {
+          const narrowed = refine(base, (member) => matchesTypeof(member, name));
+          if (narrowed) result.set(operandId, narrowed);
+        }
+      }
+      return result;
+    }
+    // `x === "literal"` narrows to that literal.
+    const leftLiteral = literalType(binary.left);
+    const rightLiteral = literalType(binary.right);
+    if (leftLiteral && !rightLiteral) {
+      const id = symbolIdOf(binary.right, resolver);
+      if (id !== undefined) result.set(id, leftLiteral);
+    } else if (rightLiteral && !leftLiteral) {
+      const id = symbolIdOf(binary.left, resolver);
+      if (id !== undefined) result.set(id, rightLiteral);
+    }
+    return result;
+  }
+
+  if (operator === "instanceof") {
+    const id = symbolIdOf(binary.left, resolver);
+    if (id === undefined) return result;
+    const instance = resolver.classInstanceFromIdentifier(binary.right);
+    if (instance) result.set(id, instance);
+  }
+  return result;
+}
+
+function negativeRefinement(expression: Expression, flow: Flow, resolver: TypeResolver): Map<number, Type> {
+  const result = new Map<number, Type>();
+  const unwrapped = unwrap(expression);
+  if (unwrapped.kind === SyntaxKind.PrefixUnaryExpression) {
+    const unary = unwrapped as PrefixUnaryExpression;
+    if (unary.operator === "!") return positiveRefinement(unary.operand, flow, resolver);
+    return result;
+  }
+  if (unwrapped.kind !== SyntaxKind.BinaryExpression) return result;
+  const binary = unwrapped as BinaryExpression;
+  if (binary.operator === "&&") {
+    // `!(a && b)` does not refine either side on its own.
+    return result;
+  }
+  if (binary.operator === "||") {
+    return merge(negativeRefinement(binary.left, flow, resolver), negativeRefinement(binary.right, flow, resolver));
+  }
+  const equality = binary.operator === "===" || binary.operator === "==";
+  const inequality = binary.operator === "!==" || binary.operator === "!=";
+  if (!equality && !inequality) return result;
+  const leftNullish = nullishKind(binary.left);
+  const rightNullish = nullishKind(binary.right);
+  const nullish = leftNullish ?? rightNullish;
+  const other = leftNullish ? binary.right : binary.left;
+  const id = symbolIdOf(other, resolver);
+  if (id === undefined || !nullish) return result;
+  if (equality) {
+    // `!(x === null)` means x is non-null.
+    const base = flow.typeOf(id) ?? resolver.typeOfSymbolId(id);
+    if (!base) return result;
+    const narrowed = refine(base, (member) => !(member.kind === "primitive" && (member.name === "null" || member.name === "undefined")));
+    if (narrowed) result.set(id, narrowed);
+  } else {
+    // `!(x !== null)` means x is null (or nullish for `!= null`).
+    const target = nullish === "nullish" ? [primitive("null"), primitive("undefined")] : [primitive(nullish)];
+    for (const type of target) result.set(id, type);
+  }
+  return result;
+}
+
+function matchesTypeof(type: Type, name: string): boolean {
+  if (type.kind === "literal") return type.primitive === name;
+  if (type.kind !== "primitive") return false;
+  return type.name === name;
+}
+
+export function narrow(condition: Expression, truthy: boolean, flow: Flow, resolver: TypeResolver): Flow {
+  const overrides = truthy ? positiveRefinement(condition, flow, resolver) : negativeRefinement(condition, flow, resolver);
+  return overrides.size > 0 ? flow.with(overrides) : flow;
+}