openapi-typesafe 0.0.0 → 1.0.0-rc.1

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,47 @@
+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 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,294 @@
+import type { IrDeclaration, IrMember, IrType } from "../../../domain/ir/nodes.js";
+import {
+  absorbed,
+  type Evaluated,
+  type Evaluation,
+  MISSING,
+  NEVER,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+import {
+  declaredFirst,
+  extracted,
+  isNeverIntersection,
+  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;
+const NULLISH: ReadonlySet<string> = new Set(["null", "undefined"]);
+
+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 {
+    const owner = this.expand(value);
+    if (owner.kind !== "type") {
+      return owner;
+    }
+    if (this.membersOf(owner).length > 1) {
+      return this.unionIndex(owner, index);
+    }
+    const { type } = owner;
+    switch (type.kind) {
+      case "object":
+        return this.memberType(owner, type.members, index);
+      case "intersection":
+        return this.partsIndex(owner, type.types, index);
+      case "union":
+        return this.unionIndex(owner, index);
+      case "array":
+        return isNumberIndex(index) ? this.flattened(owner, type.element) : builtInIndex(index);
+      case "keyword":
+        return type.keyword === "never" ? owner : builtInIndex(index);
+      default:
+        return builtInIndex(index);
+    }
+  }
+
+  private memberType(owner: Evaluated, members: readonly IrMember[], index: IrType): Evaluation {
+    const key = indexKey(index);
+    const property = members.find(
+      (member) => member.kind === "property" && key !== null && propertyKey(member.name) === key,
+    );
+    if (property !== undefined) {
+      return this.flattened(owner, property.type);
+    }
+    const signature = members.find((member) => member.kind === "indexSignature");
+    if (signature !== undefined) {
+      return this.flattened(owner, signature.type);
+    }
+    return key === null || isObjectBuiltIn(key) ? OPAQUE : MISSING;
+  }
+
+  private partsIndex(owner: Evaluated, parts: readonly IrType[], index: IrType): Evaluation {
+    if (isNeverIntersection(this, owner, parts)) {
+      return { ...owner, type: NEVER };
+    }
+    const found = parts.map((type) => this.index({ ...owner, type }, index));
+    if (found.some((part) => part.kind === "opaque")) {
+      return OPAQUE;
+    }
+    const read = parts.map((type, at) => ({ type, found: found[at] as Evaluation }));
+    const types = declaredFirst(this, owner, indexKey(index), read).flatMap((part) =>
+      part.kind === "type" ? [part.type] : [],
+    );
+    return types.length === 0 ? MISSING : { ...owner, type: intersectionType(types) };
+  }
+
+  private unionIndex(owner: Evaluated, index: IrType): Evaluation {
+    const found = this.membersOf(owner).map((member) =>
+      member.kind === "type" ? this.index(member, index) : member,
+    );
+    if (found.some((member) => member.kind === "missing")) {
+      return MISSING;
+    }
+    if (found.some((member) => member.kind === "opaque")) {
+      return OPAQUE;
+    }
+    return { ...owner, type: unionType((found as Evaluated[]).map((member) => member.type)) };
+  }
+
+  /**
+   * A member read through `FlattenedDeepRequired`: a value that is only arrays (and `undefined` or
+   * `null`) is replaced by its elements, anything else loses `undefined` and `null`.
+   */
+  private flattened(owner: Evaluated, type: IrType): Evaluation {
+    const member: Evaluated = { ...owner, type };
+    if (!owner.deep) {
+      return this.expand(member);
+    }
+    const members = this.membersOf(member);
+    if (members.some((candidate) => candidate.kind !== "type")) {
+      return OPAQUE;
+    }
+    const present = (members as Evaluated[]).filter((candidate) => !isNullish(candidate.type));
+    const elements = present.map((candidate) => arrayElement(candidate.type));
+    if (present.length > 0 && elements.every((element) => element !== null)) {
+      return this.expand({ ...owner, type: unionType(elements as IrType[]) });
+    }
+    return { ...owner, type: unionType(present.map((candidate) => candidate.type)) };
+  }
+}
+
+function isNullish(type: IrType): boolean {
+  return type.kind === "keyword" && NULLISH.has(type.keyword);
+}
+
+/** The element of an expanded member; expanding already dropped `readonly`. */
+function arrayElement(type: IrType): IrType | null {
+  return type.kind === "array" ? type.element : null;
+}
+
+function intersectionType(types: readonly IrType[]): IrType {
+  return types.length === 1 ? (types[0] as IrType) : { kind: "intersection", types };
+}
+
+function indexKey(index: IrType): string | null {
+  if (index.kind === "stringLiteral") {
+    return index.value;
+  }
+  return index.kind === "numberLiteral" ? String(index.value) : null;
+}
+
+function isNumberIndex(index: IrType): boolean {
+  const key = indexKey(index);
+  return (index.kind === "keyword" && index.keyword === "number") || /^\d+$/.test(key ?? "");
+}
+
+function isObjectBuiltIn(key: string): boolean {
+  return key in {};
+}
+
+/** A key of a primitive or an array: a built-in member is opaque, any other key is missing. */
+function builtInIndex(index: IrType): Evaluation {
+  const key = indexKey(index);
+  const isBuiltIn = key === null || key in String.prototype || key in Array.prototype;
+  return isBuiltIn || key in Number.prototype ? OPAQUE : MISSING;
+}