openapi-typesafe 1.0.0-rc.0 → 1.0.0-rc.2

package/src/application/transform/footer/document-footer.ts

@@ -1,5 +1,10 @@
 import { irReference } from "../../../domain/ir/constructors.js";
-import type { IrDeclaration, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import type {
+  IrDeclaration,
+  IrEnumDeclaration,
+  IrPropertySignature,
+  IrType,
+} from "../../../domain/ir/nodes.js";
 import { HELPER_TYPES, type HelperType } from "../helper-types.js";
 import type {
   EnumDeclarationRequest,
@@ -7,7 +12,13 @@ import type {
   EnumValuesRequest,
 } from "../schema/schema-context.js";
 import type { DocumentFooter } from "../transform-context.js";
-import { EnumNaming, enumDeclaration } from "./enum-naming.js";
+import {
+  type DeclaredMembers,
+  EnumNaming,
+  enumDeclaration,
+  withoutDeclaredMembers,
+} from "./enum-naming.js";
+import { FIRST_SCHEMA_NAMES, type SharedEnumNames } from "./shared-enum-names.js";
 
 /** Where footer declarations go, in order: the run's `ctx.injectFooter`, open to user code. */
 export interface FooterSink {
@@ -43,6 +54,9 @@ function metadataKey(value: string, metadata: EnumMemberMetadata | undefined): s
   return `${metadata?.name ?? value}:${metadata?.description || ""}`;
 }
 
+/** Separates a repeated `--enum-values` array name from its number, as root type aliases do. */
+const ENUM_VALUES_NUMBER_SEPARATOR = "_";
+
 /** The whole declaration: an equal key means the same enum, member for member. */
 function declarationKey(name: string, request: EnumDeclarationRequest): string {
   return JSON.stringify([name, request.values, request.metadata]);
@@ -58,18 +72,34 @@ export class RunFooter implements DocumentFooter {
   private readonly enumNamesByKey = new Map<string, string>();
   /** Declarations added already: the same one twice fails with "Duplicate identifier". */
   private readonly declaredEnums = new Set<string>();
+  /** The member names of each declared enum, by value. */
+  private readonly membersByEnum = new Map<string, Map<string | number, string>>();
+  /** The members of each declared enum name, by member name. */
+  private readonly declaredMembers = new Map<string, Map<string, string | number>>();
+  /** `--enum-values` arrays added already: their declared name by name, type and values. */
+  private readonly declaredEnumValues = new Map<string, string>();
+  /** The declared `--enum-values` array names. */
+  private readonly enumValuesNames = new Set<string>();
   private readonly sink: FooterSink;
   private readonly isDedupingEnums: boolean;
+  private readonly sharedNames: SharedEnumNames;
 
-  constructor(sink: FooterSink, isDedupingEnums: boolean) {
+  constructor(
+    sink: FooterSink,
+    isDedupingEnums: boolean,
+    sharedNames: SharedEnumNames = FIRST_SCHEMA_NAMES,
+  ) {
     this.sink = sink;
     this.isDedupingEnums = isDedupingEnums;
+    this.sharedNames = sharedNames;
   }
 
   addEnum(request: EnumDeclarationRequest): string {
     // The name is built before the cache lookup: it advances the naming state either way.
-    const name = this.naming.enumName(request.name);
+    const ownName = this.naming.enumName(request.name);
     const key = this.isDedupingEnums ? dedupeKey(request) : null;
+    // Every schema of a shared enum goes to `sharedNames`, the later ones too.
+    const name = key === null ? ownName : this.sharedNames.nameOf(key, ownName, request);
     const known = key === null ? undefined : this.enumNamesByKey.get(key);
     if (known !== undefined) {
       return known;
@@ -82,15 +112,56 @@ export class RunFooter implements DocumentFooter {
     if (declared !== null) {
       this.declaredEnums.add(declared);
     }
-    this.sink.add(enumDeclaration(name, request, this.naming));
+    const declaration = this.withoutRepeats(enumDeclaration(name, request, this.naming));
+    if (declaration !== null) {
+      this.record(declaration);
+      this.sink.add(declaration);
+    }
     if (key !== null) {
       this.enumNamesByKey.set(key, name);
     }
     return name;
   }
 
+  /** The declaration without members an earlier one of the name has; null when none is left. */
+  private withoutRepeats(declaration: IrEnumDeclaration): IrEnumDeclaration | null {
+    const earlier: DeclaredMembers | undefined = this.declaredMembers.get(declaration.name);
+    if (earlier === undefined) {
+      return declaration;
+    }
+    const merged = withoutDeclaredMembers(declaration, earlier);
+    // Two empty declarations merge into one empty enum, which compiles, so the second stays.
+    return merged.members.length === 0 && declaration.members.length > 0 ? null : merged;
+  }
+
+  /** The members of a declaration; the first member of a value names it. */
+  private record(declaration: IrEnumDeclaration): void {
+    const byName = this.declaredMembers.get(declaration.name) ?? new Map();
+    const byValue = this.membersByEnum.get(declaration.name) ?? new Map();
+    for (const member of declaration.members) {
+      byName.set(member.name, member.value);
+      if (!byValue.has(member.value)) {
+        byValue.set(member.value, member.name);
+      }
+    }
+    this.declaredMembers.set(declaration.name, byName);
+    this.membersByEnum.set(declaration.name, byValue);
+  }
+
+  enumMembers(name: string): ReadonlyMap<string | number, string> {
+    return this.membersByEnum.get(name) ?? new Map();
+  }
+
   addEnumValues(request: EnumValuesRequest): void {
-    const name = this.naming.arrayName(request.name);
+    const baseName = this.naming.arrayName(request.name);
+    // The same array twice fails with "Cannot redeclare"; a schema typed twice adds it twice.
+    const declared = JSON.stringify([baseName, request.type, request.values]);
+    if (this.declaredEnumValues.has(declared)) {
+      return;
+    }
+    const name = this.freeEnumValuesName(baseName);
+    this.declaredEnumValues.set(declared, name);
+    this.enumValuesNames.add(name);
     this.require(HELPER_TYPES.flattenedDeepRequired);
     this.require(HELPER_TYPES.readonlyArray);
     this.sink.add({
@@ -103,6 +174,20 @@ export class RunFooter implements DocumentFooter {
     });
   }
 
+  /**
+   * Another array may have the name: `Discount/type` and `discount/type`, or a property and an
+   * inline `allOf` item of one schema, typed at one location. A redeclared `const` does not
+   * compile, so a later one gets the next number (`discountTypeValues_2`). Every unnumbered name
+   * ends with `Values`, so a number never takes a name that a later array needs.
+   */
+  private freeEnumValuesName(name: string): string {
+    let candidate = name;
+    for (let count = 2; this.enumValuesNames.has(candidate); count++) {
+      candidate = `${name}${ENUM_VALUES_NUMBER_SEPARATOR}${count}`;
+    }
+    return candidate;
+  }
+
   requireWithRequired(): void {
     this.require(HELPER_TYPES.withRequired);
   }

package/src/application/transform/footer/enum-naming.ts

@@ -179,3 +179,32 @@ export function enumDeclaration(
     comments: [],
   };
 }
+
+/** The member names an enum name has so far, with their values. */
+export type DeclaredMembers = ReadonlyMap<string, string | number>;
+
+/**
+ * A later declaration of an enum name merges with the earlier ones, and a member name declared
+ * twice does not compile (TS2300): a property and an inline `allOf` item of one schema give one
+ * name. A member that repeats one by name and value is left out; one whose name another value has
+ * gets the next free number (`a_b_2`).
+ */
+export function withoutDeclaredMembers(
+  declaration: IrEnumDeclaration,
+  declared: DeclaredMembers,
+): IrEnumDeclaration {
+  const taken = new Set(declared.keys());
+  const members: IrEnumDeclaration["members"][number][] = [];
+  for (const member of declaration.members) {
+    if (declared.get(member.name) === member.value) {
+      continue;
+    }
+    let name = member.name;
+    for (let count = 2; taken.has(name); count++) {
+      name = numberedMemberName(member.name, count);
+    }
+    taken.add(name);
+    members.push(name === member.name ? member : { ...member, name });
+  }
+  return { ...declaration, members };
+}

package/src/application/transform/footer/enum-values-check.ts

@@ -0,0 +1,171 @@
+import { irArray, irReadonly, irReference } from "../../../domain/ir/constructors.js";
+import type { IrConstArrayDeclaration, IrDeclaration, IrType } from "../../../domain/ir/nodes.js";
+import { HELPER_TYPES } from "../helper-types.js";
+import { literalType } from "../literal-type.js";
+import { unionOf } from "../type-combinators.js";
+import { type Evaluated, type Evaluation, NEVER } from "./evaluation.js";
+import { TypeEvaluator } from "./type-evaluation.js";
+
+/**
+ * `--enum-values` arrays are typed by the location of their schema in the generated types
+ * (`FlattenedDeepRequired<components>["schemas"]["A"]["status"]`). Where that type surely does not
+ * hold the values (ADR-027), the array is typed by its own values instead, so it compiles:
+ * - the location indexes a key the generated type does not have (`definitions`, `allOf`, a
+ *   property of `unknown`), or
+ * - the type there does not admit a listed value (an `allOf` of different enums, a discriminator
+ *   value the property enum does not list, an array next to other `anyOf` members).
+ * Everything else stays as it was.
+ */
+
+/** Why an array got its own values as its type. */
+export type EnumValuesRetype =
+  /** The location's type admits only other values, or none: the document contradicts itself. */
+  | { readonly kind: "excluded"; readonly name: string; readonly excluded: readonly unknown[] }
+  /** The location could not be typed; nothing to report, the array is right now. */
+  | { readonly kind: "untyped"; readonly name: string };
+
+type Admission = "yes" | "no" | "opaque";
+
+function literalAdmission(type: IrType, value: string | number): Admission {
+  switch (type.kind) {
+    case "stringLiteral":
+    case "numberLiteral":
+      return type.value === value ? "yes" : "no";
+    case "booleanLiteral":
+      return "no";
+    case "keyword":
+      if (type.keyword === "unknown") {
+        return "yes";
+      }
+      return type.keyword === typeof value ? "yes" : "no";
+    case "object":
+      // `{}` (as in `string & {}`) admits every value but `null` and `undefined`.
+      return type.members.length === 0 ? "yes" : "no";
+    case "array":
+      return "no";
+    default:
+      return "opaque";
+  }
+}
+
+function admission(evaluator: TypeEvaluator, value: Evaluated, item: string | number): Admission {
+  const { type } = value;
+  if (type.kind === "union" || type.kind === "intersection") {
+    const parts = type.types.map((part) => {
+      const expanded = evaluator.expand({ ...value, type: part });
+      return expanded.kind === "type" ? admission(evaluator, expanded, item) : "opaque";
+    });
+    // A union admits a value one member admits; an intersection excludes one a part excludes.
+    const decisive: Admission = type.kind === "union" ? "yes" : "no";
+    if (parts.includes(decisive)) {
+      return decisive;
+    }
+    return parts.includes("opaque") ? "opaque" : decisive === "yes" ? "no" : "yes";
+  }
+  return literalAdmission(type, item);
+}
+
+/** `ReadonlyArray<T>`: an array type `T` is the array itself, so its elements are checked. */
+function elementOf(evaluator: TypeEvaluator, value: Evaluated): Evaluation {
+  const members = evaluator.membersOf(value);
+  const elements = members.map((member) =>
+    member.kind === "type" && member.type.kind === "array" ? member.type.element : null,
+  );
+  if (members.length === 0 || elements.some((element) => element === null)) {
+    return value;
+  }
+  return evaluator.expand({ ...value, type: unionOf(elements as IrType[]) });
+}
+
+const LITERAL_KINDS: ReadonlySet<string> = new Set([
+  "stringLiteral",
+  "numberLiteral",
+  "booleanLiteral",
+]);
+
+/** Whether a type is made of literals only (or `never`): a finite set of values. */
+function isFiniteType(evaluator: TypeEvaluator, value: Evaluated): boolean {
+  const { type } = value;
+  if (type.kind === "union" || type.kind === "intersection") {
+    return type.types.every((part) => {
+      const expanded = evaluator.expand({ ...value, type: part });
+      return expanded.kind === "type" && isFiniteType(evaluator, expanded);
+    });
+  }
+  return LITERAL_KINDS.has(type.kind) || (type.kind === "keyword" && type.keyword === "never");
+}
+
+function locationType(declaration: IrConstArrayDeclaration): IrType | null {
+  const { type } = declaration;
+  const isTyped = type.kind === "reference" && type.name === HELPER_TYPES.readonlyArray.name;
+  return isTyped ? (type.typeArguments[0] ?? null) : null;
+}
+
+function retypeOf(
+  evaluator: TypeEvaluator,
+  declaration: IrConstArrayDeclaration,
+): EnumValuesRetype | null {
+  const location = locationType(declaration);
+  const evaluated = location === null ? null : evaluator.evaluate(location);
+  if (evaluated === null || evaluated.kind === "opaque") {
+    return null;
+  }
+  if (evaluated.kind === "missing") {
+    return { kind: "untyped", name: declaration.name };
+  }
+  const element = elementOf(evaluator, evaluated);
+  if (element.kind !== "type") {
+    return element.kind === "missing" ? { kind: "untyped", name: declaration.name } : null;
+  }
+  if (declaration.values.length === 0 && isNever(element.type)) {
+    // The `ReadonlyArray` helper of `never` is `never` (`never` extends an array): not even `[]`.
+    return { kind: "untyped", name: declaration.name };
+  }
+  const results = declaration.values.map((value) => admission(evaluator, element, value));
+  if (!results.includes("no")) {
+    return null;
+  }
+  if (!isFiniteType(evaluator, element)) {
+    return { kind: "untyped", name: declaration.name };
+  }
+  const excluded = declaration.values.filter((_, index) => results[index] === "no");
+  return { kind: "excluded", name: declaration.name, excluded };
+}
+
+function isNever(type: IrType): boolean {
+  return type.kind === "keyword" && type.keyword === "never";
+}
+
+/** The values' own type; with no values `readonly never[]` (`ReadonlyArray<never>` is never). */
+function ownValuesType(declaration: IrConstArrayDeclaration): IrType {
+  if (declaration.values.length === 0) {
+    return irReadonly(irArray(NEVER));
+  }
+  const values = unionOf(declaration.values.map((value) => literalType(value)));
+  return irReference(HELPER_TYPES.readonlyArray.name, [values]);
+}
+
+/**
+ * The footer with each `--enum-values` array whose location type does not hold its values typed
+ * by its own values, and why each one changed. `declarations` are the document's types.
+ */
+export function checkedEnumValues<T>(
+  footer: readonly (T | IrDeclaration)[],
+  declarations: readonly IrDeclaration[],
+  isDeclaration: (entry: T | IrDeclaration) => entry is IrDeclaration,
+): { footer: (T | IrDeclaration)[]; retyped: EnumValuesRetype[] } {
+  const evaluator = new TypeEvaluator([...declarations, ...footer.filter(isDeclaration)]);
+  const retyped: EnumValuesRetype[] = [];
+  const checked = footer.map((entry) => {
+    if (!isDeclaration(entry) || entry.kind !== "constArray") {
+      return entry;
+    }
+    const retype = retypeOf(evaluator, entry);
+    if (retype === null) {
+      return entry;
+    }
+    retyped.push(retype);
+    return { ...entry, type: ownValuesType(entry) };
+  });
+  return { footer: checked, retyped };
+}

package/src/application/transform/footer/evaluation.ts

@@ -0,0 +1,57 @@
+import type { IrPropertyName, IrType } from "../../../domain/ir/nodes.js";
+
+/** The values the evaluator of the `--enum-values` check works with (ADR-027). */
+
+/** A type as evaluated: `deep` is set inside `FlattenedDeepRequired`. */
+export interface Evaluated {
+  readonly kind: "type";
+  readonly type: IrType;
+  readonly deep: boolean;
+}
+
+export type Evaluation = Evaluated | { readonly kind: "missing" } | { readonly kind: "opaque" };
+
+export const MISSING: Evaluation = { kind: "missing" };
+export const OPAQUE: Evaluation = { kind: "opaque" };
+
+export const NEVER: IrType = { kind: "keyword", keyword: "never" };
+
+export function unionType(types: readonly IrType[]): IrType {
+  if (types.length === 1) {
+    return types[0] as IrType;
+  }
+  return types.length === 0 ? NEVER : { kind: "union", types };
+}
+
+export function intersectionType(types: readonly IrType[]): IrType {
+  return types.length === 1 ? (types[0] as IrType) : { kind: "intersection", types };
+}
+
+const NULLISH: ReadonlySet<string> = new Set(["null", "undefined"]);
+
+export function isNullish(type: IrType): boolean {
+  return type.kind === "keyword" && NULLISH.has(type.keyword);
+}
+
+export function propertyKey(name: IrPropertyName): string {
+  return name.kind === "string" ? name.value : name.text;
+}
+
+function isKeyword(member: Evaluation, keyword: string): boolean {
+  return (
+    member.kind === "type" && member.type.kind === "keyword" && member.type.keyword === keyword
+  );
+}
+
+/**
+ * Union members as TypeScript reduces them: `any` absorbs every member, `unknown` every member
+ * but `any`, so `{ a: X } | unknown` is `unknown`. An opaque member may be `any`.
+ */
+export function absorbed(members: readonly Evaluation[]): readonly Evaluation[] {
+  const any = members.find((member) => isKeyword(member, "any"));
+  const unknown = members.find((member) => isKeyword(member, "unknown"));
+  if (any !== undefined || unknown === undefined) {
+    return any === undefined ? members : [any];
+  }
+  return members.some((member) => member.kind !== "type") ? [OPAQUE] : [unknown];
+}

package/src/application/transform/footer/shared-enum-names.ts

@@ -0,0 +1,86 @@
+import type { EnumDeclarationRequest } from "../schema/schema-context.js";
+import { EnumNaming } from "./enum-naming.js";
+
+/**
+ * How `--dedupe-enums` names the one enum that schemas with the same members share. `key` is the
+ * dedupe key of the members; `name` is the name the schema gives with the run's naming state.
+ */
+export interface SharedEnumNames {
+  /** Called for every schema of the enum, in document order; returns the name to declare. */
+  nameOf(key: string, name: string, request: EnumDeclarationRequest): string;
+}
+
+/** The original: the enum takes the name of the first schema in the document. */
+export const FIRST_SCHEMA_NAMES: SharedEnumNames = { nameOf: (_key, name) => name };
+
+interface NameCandidate {
+  readonly name: string;
+  readonly isComponentSchema: boolean;
+}
+
+/**
+ * Whether `candidate` names the enum better than `other`: a component schema that is the enum
+ * itself, then the shorter name, then the earlier one in code-unit order. No part depends on the
+ * document order, so adding or moving a schema changes the name only when the new one ranks first.
+ */
+function isBetterName(candidate: NameCandidate, other: NameCandidate): boolean {
+  if (candidate.isComponentSchema !== other.isComponentSchema) {
+    return candidate.isComponentSchema;
+  }
+  if (candidate.name.length !== other.name.length) {
+    return candidate.name.length < other.name.length;
+  }
+  return candidate.name < other.name;
+}
+
+/** The candidates from best to worst. */
+function ranked(candidates: readonly NameCandidate[]): NameCandidate[] {
+  return [...candidates].sort((left, right) => {
+    if (left.name === right.name && left.isComponentSchema === right.isComponentSchema) {
+      return 0;
+    }
+    return isBetterName(left, right) ? -1 : 1;
+  });
+}
+
+/**
+ * The `dedupe-enum-names` fix (ADR-021, upstream #1683), first pass: records every schema of each
+ * shared enum and keeps the run's own names. `chosenNames` gives the names for the second pass.
+ */
+export class SharedEnumNameRecorder implements SharedEnumNames {
+  private readonly candidatesByKey = new Map<string, NameCandidate[]>();
+
+  nameOf(key: string, name: string, request: EnumDeclarationRequest): string {
+    // A fresh naming state: the run's state depends on the names built before (EnumNaming).
+    const candidate = {
+      name: new EnumNaming().enumName(request.name),
+      isComponentSchema: request.isComponentSchema,
+    };
+    const candidates = this.candidatesByKey.get(key);
+    if (candidates === undefined) {
+      this.candidatesByKey.set(key, [candidate]);
+    } else {
+      candidates.push(candidate);
+    }
+    return name;
+  }
+
+  /**
+   * The best name of each enum. Two enums whose best names are the same (two schemas that give
+   * one name) are resolved in key order: the later one takes its next name that is free.
+   */
+  chosenNames(): SharedEnumNames {
+    const chosen = new Map<string, string>();
+    const taken = new Set<string>();
+    const keys = [...this.candidatesByKey.keys()].sort();
+    for (const key of keys) {
+      const names = ranked(this.candidatesByKey.get(key) ?? []).map(({ name }) => name);
+      const name = names.find((candidate) => !taken.has(candidate)) ?? names[0];
+      if (name !== undefined) {
+        chosen.set(key, name);
+        taken.add(name);
+      }
+    }
+    return { nameOf: (key, name) => chosen.get(key) ?? name };
+  }
+}

package/src/application/transform/footer/type-evaluation.ts

@@ -0,0 +1,167 @@
+import type { IrDeclaration, IrType } from "../../../domain/ir/nodes.js";
+import {
+  absorbed,
+  type Evaluated,
+  type Evaluation,
+  intersectionType,
+  isNullish,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+import { indexType } from "./type-indexing.js";
+import { extracted, markerObject, omitted } from "./type-rules.js";
+
+/**
+ * A small evaluator of the generated types, as TypeScript reads them, for the `--enum-values`
+ * check (ADR-027). It follows the declarations of the document and the helper types the generator
+ * writes (`NonNullable`, `Extract`, `WithRequired`, `Omit`, `Record`, `FlattenedDeepRequired`). Its
+ * answers are sure: a key is `missing` only where TypeScript reports it, and every type it does
+ * not model is `opaque`, which never counts as an error.
+ */
+
+/** How many references one evaluation expands; a deeper one is opaque. */
+const MAX_EXPANSIONS = 200;
+const DEEP_PREFIX = "FlattenedDeepRequired<";
+/** How many members distributing an intersection may give; more is opaque. */
+const MAX_DISTRIBUTED = 64;
+
+export class TypeEvaluator {
+  private readonly declared = new Map<string, IrType>();
+  private expansions = 0;
+
+  constructor(declarations: readonly IrDeclaration[]) {
+    for (const declaration of declarations) {
+      if (declaration.kind === "interface") {
+        this.declared.set(declaration.name, { kind: "object", members: declaration.members });
+      } else if (declaration.kind === "typeAlias") {
+        this.declared.set(declaration.name, declaration.type);
+      }
+    }
+  }
+
+  /** Evaluate a type written in the footer; the expansion budget starts again. */
+  evaluate(type: IrType): Evaluation {
+    this.expansions = 0;
+    return this.expand({ kind: "type", type, deep: false });
+  }
+
+  /** The type with references, `readonly` and indexed access resolved at the top. */
+  expand(value: Evaluated): Evaluation {
+    const { type } = value;
+    switch (type.kind) {
+      case "readonly":
+        return this.expand({ ...value, type: type.type });
+      case "indexedAccess":
+        return this.indexedAccess(value, type.object, type.index);
+      case "reference":
+        return this.reference(value, type.name, type.typeArguments);
+      case "raw":
+      case "tuple":
+        return OPAQUE;
+      default:
+        return value;
+    }
+  }
+
+  private indexedAccess(value: Evaluated, object: IrType, index: IrType): Evaluation {
+    const owner = this.expand({ ...value, type: object });
+    return owner.kind === "type" ? this.index(owner, index) : owner;
+  }
+
+  private reference(value: Evaluated, name: string, args: readonly IrType[]): Evaluation {
+    // Only references cost budget: re-expanding an already expanded value (as the checks after
+    // `evaluate` do) is free, so a large evaluation does not leave its checks opaque.
+    if (this.expansions++ > MAX_EXPANSIONS) {
+      return OPAQUE;
+    }
+    if (name.startsWith(DEEP_PREFIX) && name.endsWith(">")) {
+      const root = this.declared.get(name.slice(DEEP_PREFIX.length, -1));
+      return root === undefined ? OPAQUE : this.expand({ kind: "type", type: root, deep: true });
+    }
+    const declared = args.length === 0 ? this.declared.get(name) : undefined;
+    if (declared !== undefined) {
+      return this.expand({ ...value, type: declared });
+    }
+    const [first, second] = args;
+    if (first === undefined) {
+      return OPAQUE;
+    }
+    const argument = this.expand({ ...value, type: first });
+    if (argument.kind !== "type") {
+      return argument;
+    }
+    return this.helper(name, argument, second);
+  }
+
+  private helper(name: string, argument: Evaluated, second: IrType | undefined): Evaluation {
+    switch (name) {
+      case "NonNullable":
+        return this.withoutNullish(argument);
+      case "WithRequired":
+      case "Readonly":
+        return argument;
+      case "Extract":
+        return second === undefined ? OPAQUE : this.extract(argument, second);
+      case "Omit":
+        return second === undefined ? OPAQUE : omitted(this, argument, second);
+      default:
+        return markerObject(name, argument) ?? OPAQUE;
+    }
+  }
+
+  /**
+   * The members of a union, each expanded; an intersection with unions in it is distributed over
+   * them (`A & (B | C)` is `(A & B) | (A & C)`), as TypeScript normalizes it. A type that is not a
+   * union is its only member. A union with an `any` or `unknown` member is that keyword alone.
+   */
+  membersOf(value: Evaluated): readonly Evaluation[] {
+    const expanded = this.expand(value);
+    if (expanded.kind !== "type") {
+      return [expanded];
+    }
+    const { type } = expanded;
+    if (type.kind === "union") {
+      return absorbed(
+        type.types.flatMap((member) => this.membersOf({ ...expanded, type: member })),
+      );
+    }
+    return type.kind === "intersection" ? this.distributed(expanded, type.types) : [expanded];
+  }
+
+  private distributed(value: Evaluated, parts: readonly IrType[]): readonly Evaluation[] {
+    const memberLists = parts.map((part) => this.membersOf({ ...value, type: part }));
+    const size = memberLists.reduce((product, list) => product * list.length, 1);
+    if (size > MAX_DISTRIBUTED || memberLists.some((list) => list.some((m) => m.kind !== "type"))) {
+      return [OPAQUE];
+    }
+    let combinations: IrType[][] = [[]];
+    for (const list of memberLists as Evaluated[][]) {
+      combinations = combinations.flatMap((done) => list.map((member) => [...done, member.type]));
+    }
+    return combinations.map((types) => ({ ...value, type: intersectionType(types) }));
+  }
+
+  private withoutNullish(value: Evaluated): Evaluation {
+    const members = this.membersOf(value);
+    if (members.some((member) => member.kind !== "type")) {
+      return OPAQUE;
+    }
+    const kept = (members as Evaluated[]).filter((member) => !isNullish(member.type));
+    return { ...value, type: unionType(kept.map((member) => member.type)) };
+  }
+
+  /** `Extract<T, { key: unknown }>` keeps the members that have `key`; other probes are opaque. */
+  private extract(value: Evaluated, probe: IrType): Evaluation {
+    const [member] = probe.kind === "object" ? probe.members : [];
+    if (probe.kind !== "object" || probe.members.length !== 1 || member?.kind !== "property") {
+      return OPAQUE;
+    }
+    return extracted(this, value, propertyKey(member.name));
+  }
+
+  /** `value[index]` for a string literal, `string` or `number` index. */
+  index(value: Evaluated, index: IrType): Evaluation {
+    return indexType(this, value, index);
+  }
+}