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

package/src/adapters/type-ast-bridge/ir-to-typescript.ts

@@ -1,5 +1,6 @@
 import type ts from "typescript";
 import { assertNever } from "../../domain/assert-never.js";
+import { DEFAULT_STRING_ENCODING } from "../../domain/ir/constructors.js";
 import type {
   IrComment,
   IrKeyword,
@@ -74,6 +75,9 @@ function toStringLiteralType(
 
 function toTupleElement(ts: TypeScriptModule, element: IrTupleElement): ts.TypeNode {
   const type = toTypeNode(ts, element.type);
+  if (element.isOptional) {
+    return ts.factory.createOptionalTypeNode(type);
+  }
   return element.isRest ? ts.factory.createRestTypeNode(type) : type;
 }
 
@@ -87,7 +91,7 @@ function toLeafTypeNode(ts: TypeScriptModule, type: LeafType): ts.TypeNode {
     case "keyword":
       return toKeywordType(ts, type.keyword);
     case "stringLiteral":
-      return toStringLiteralType(ts, type.value, type.encoding);
+      return toStringLiteralType(ts, type.value, type.encoding ?? DEFAULT_STRING_ENCODING);
     case "numberLiteral":
       return ts.factory.createLiteralTypeNode(toNumberExpression(ts, type.value));
     case "booleanLiteral":

package/src/adapters/type-ast-bridge/print-typescript.ts

@@ -1,11 +1,13 @@
 import type ts from "typescript";
 import type { TypeScriptModule } from "./load-typescript.js";
+import type { ts as CompilerTypes } from "./typescript-types.js";
 
 /** Options of `astToString` for the TypeScript printer, as in the original. */
 export interface AstToStringOptions {
   fileName?: string;
   sourceText?: string;
-  formatOptions?: ts.PrinterOptions;
+  /** The installed compiler's printer options (ADR-032: named without `ts.PrinterOptions`). */
+  formatOptions?: CompilerTypes.PrinterOptions;
 }
 
 /** Print TypeScript nodes as the original `astToString` did. */

package/src/adapters/type-ast-bridge/typescript-to-ir.ts

@@ -6,6 +6,7 @@ import type {
   IrMember,
   IrPropertyName,
   IrPropertySignature,
+  IrTupleElement,
   IrType,
 } from "../../domain/ir/nodes.js";
 import type { TypeScriptModule } from "./load-typescript.js";
@@ -83,20 +84,31 @@ function fromReference(ts: TypeScriptModule, node: ts.TypeReferenceNode): IrType
   return { kind: "reference", name: ts.idText(node.typeName), typeArguments };
 }
 
+function fromTupleElement(
+  ts: TypeScriptModule,
+  element: ts.TypeNode,
+  convert: (node: ts.TypeNode) => IrType,
+): IrTupleElement {
+  if (ts.isRestTypeNode(element)) {
+    return { type: convert(element.type), isRest: true, isOptional: false };
+  }
+  if (ts.isOptionalTypeNode(element)) {
+    // The `?` is the parent of the type: it decides which parentheses the factory put in.
+    return { type: fromTypeNode(ts, element.type, element), isRest: false, isOptional: true };
+  }
+  return { type: convert(element), isRest: false, isOptional: false };
+}
+
+/** A tuple of plain, rest and optional elements; one with named members stays text. */
 function fromTuple(ts: TypeScriptModule, node: ts.TupleTypeNode): IrType | null {
-  const isPlain = node.elements.every(
-    (element) => !ts.isNamedTupleMember(element) && !ts.isOptionalTypeNode(element),
-  );
-  if (!isPlain) {
+  if (node.elements.some((element) => ts.isNamedTupleMember(element))) {
     return null;
   }
   const convert = childrenOf(ts, node);
-  const elements = node.elements.map((element) =>
-    ts.isRestTypeNode(element)
-      ? { type: convert(element.type), isRest: true }
-      : { type: convert(element), isRest: false },
-  );
-  return { kind: "tuple", elements };
+  return {
+    kind: "tuple",
+    elements: node.elements.map((element) => fromTupleElement(ts, element, convert)),
+  };
 }
 
 /**
@@ -237,8 +249,9 @@ function fromStructure(ts: TypeScriptModule, node: ts.TypeNode): IrType | null {
 
 /**
  * Whether the factory's parenthesizer put these parentheses in (same rules as the IR printer):
- * unions, intersections and `readonly` types as array elements, indexed objects and `readonly`
- * operands; unions and intersections as members of other unions or intersections.
+ * unions, intersections and `readonly` types as array elements, indexed objects, optional tuple
+ * elements and `readonly` operands; unions and intersections as members of other unions or
+ * intersections.
  */
 function isFactoryParenthesis(
   ts: TypeScriptModule,
@@ -252,6 +265,7 @@ function isFactoryParenthesis(
   const isPostfixOrReadonlyParent =
     ts.isArrayTypeNode(parent) ||
     ts.isIndexedAccessTypeNode(parent) ||
+    ts.isOptionalTypeNode(parent) ||
     ts.isTypeOperatorNode(parent);
   if (isPostfixOrReadonlyParent) {
     return isComposite || ts.isTypeOperatorNode(inner);

package/src/adapters/type-ast-bridge/typescript-types.ts

@@ -1,8 +1,60 @@
-import type ts from "typescript";
+import type * as TypeScript from "typescript";
 
 /**
- * The TypeScript compiler's types for code outside the bridge (ADR-004, decision 4). Type-only:
- * it is erased at build time, so importing it never loads TypeScript. Only the bridge imports
- * `typescript` itself (enforced by dependency-cruiser).
+ * The TypeScript compiler's node types for code outside the bridge and for the public
+ * declarations (ADR-004, decision 4; ADR-032). Type-only: importing it never loads TypeScript.
+ *
+ * Each type is read from the compiler API of the `typescript` package the consumer has installed
+ * (`factory`, `createPrinter`), not named as `ts.Node`. TypeScript 5.x and 6.x have that API, so
+ * the types are the compiler's own. TypeScript 7's `typescript` package exports only `version`;
+ * `ts.Node` there is error TS2694 in a consumer that checks declarations (`skipLibCheck: false`).
  */
-export type { ts };
+
+type Api = typeof TypeScript;
+type Factory = Api extends { readonly factory: infer F } ? F : undefined;
+
+/**
+ * A compiler type when the installed `typescript` has no compiler API (TypeScript 7). It is `any`
+ * because that is what these types already were for such a consumer with `skipLibCheck: true`
+ * (an unresolved type in a declaration file is `any`), so callbacks that build or read nodes of
+ * `@typescript/typescript6` keep compiling (ADR-032). The cost, as before: a union with a node
+ * type, such as the result of `transform`, accepts any value there.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: unresolved compiler types were `any` (ADR-032)
+type WithoutCompilerApi = any;
+
+/** The node type that `factory[Name]` returns, or `WithoutCompilerApi`. */
+type Created<Name extends string> = Factory extends {
+  readonly [Key in Name]: (...args: never[]) => infer Result;
+}
+  ? Result
+  : WithoutCompilerApi;
+
+type ModifierList = Created<"createModifiersFromModifierFlags">;
+
+/** The compiler node types the package names; see the module comment. */
+export declare namespace ts {
+  type Node = Api extends { isTypeNode(node: infer N): boolean } ? N : WithoutCompilerApi;
+  type TypeNode = Factory extends { createArrayTypeNode(elementType: infer T): unknown }
+    ? T
+    : WithoutCompilerApi;
+  type QuestionToken = Factory extends {
+    createPropertySignature(modifiers: never, name: never, token: infer Q, type: never): unknown;
+  }
+    ? NonNullable<Q>
+    : WithoutCompilerApi;
+  type Modifier = ModifierList extends readonly (infer M)[] | undefined ? M : WithoutCompilerApi;
+  type PrinterOptions = Api extends { createPrinter(options?: infer O, ...rest: never[]): unknown }
+    ? NonNullable<O>
+    : WithoutCompilerApi;
+  type PropertySignature = Created<"createPropertySignature">;
+  type LiteralTypeNode = Created<"createLiteralTypeNode">;
+  type TypeLiteralNode = Created<"createTypeLiteralNode">;
+  type InterfaceDeclaration = Created<"createInterfaceDeclaration">;
+  type EnumDeclaration = Created<"createEnumDeclaration">;
+  type EnumMember = Created<"createEnumMember">;
+  type VariableStatement = Created<"createVariableStatement">;
+  type Identifier = Created<"createIdentifier">;
+  type NumericLiteral = Created<"createNumericLiteral">;
+  type StringLiteral = Created<"createStringLiteral">;
+}

package/src/api/default-ports.ts

@@ -1,6 +1,7 @@
 import { performance } from "node:perf_hooks";
 import { createConfig, type Config as RedoclyConfig } from "@redocly/openapi-core";
 import supportsColor from "supports-color";
+import type { RemoteDocumentLimits } from "../adapters/redocly-loader/remote-fetch.js";
 import { createTerminalLogger } from "../adapters/terminal-logger/terminal-logger.js";
 import type { Logger } from "../application/ports/logger.js";
 
@@ -32,6 +33,21 @@ export function defaultLogger(silent: boolean): Logger {
  */
 export const REMOTE_REF_TIMEOUT_MS = 60_000;
 
+/**
+ * Bounds on the remote documents of one run (ADR-033). Large split documents have a few thousand
+ * files, so 10,000 leaves room and still ends an endless fan-out. 16 parallel fetches keep a
+ * multi-file document fast without exhausting local ports.
+ */
+export const DEFAULT_REMOTE_DOCUMENT_LIMITS: RemoteDocumentLimits = {
+  maxDocuments: 10_000,
+  maxParallelFetches: 16,
+};
+
+/** The working directory of the process: the default `cwd` of an inline source. */
+export function processCwd(): string {
+  return process.cwd();
+}
+
 /** A monotonic clock in milliseconds, for debug durations. */
 export function monotonicNow(): number {
   return performance.now();

package/src/api/discriminator-conflict-warnings.ts

@@ -0,0 +1,43 @@
+import type { Logger } from "../application/ports/logger.js";
+import {
+  type DiscriminatorValueConflict,
+  findDiscriminatorValueConflicts,
+} from "../domain/openapi/discriminator-conflicts.js";
+import { OutputFix } from "../domain/output-fixes.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+
+const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
+const DOCS_URL = `${DOCS_BASE_URL}/advanced.md#discriminator-values`;
+
+function listed(values: readonly unknown[]): string {
+  return values.map((value) => JSON.stringify(value)).join(", ");
+}
+
+function warningOf(conflict: DiscriminatorValueConflict): string {
+  const { member, owner, propertyName, values, allowed, isImplicit } = conflict;
+  const rule = isImplicit
+    ? "A Discriminator Object without a mapping entry for a schema gives it its schema name as " +
+      `the value; add a mapping entry such as ${JSON.stringify(allowed[0])}: "${member}".`
+    : "The Discriminator Object maps these values to the schema; map the values it allows.";
+  return (
+    `${member}: the discriminator "${propertyName}" of ${owner} gives this schema the value ` +
+    `${listed(values)}, which its "${propertyName}" property does not allow ` +
+    `(${listed(allowed)}), so no value of the schema matches the discriminator. ${rule} ` +
+    `See ${DOCS_URL}`
+  );
+}
+
+/**
+ * Warn once per discriminator member whose value its own property does not allow. The members
+ * depend on the run's fixes (`allof-discriminated-union`).
+ */
+export function warnDiscriminatorValueConflicts(
+  document: unknown,
+  fixes: readonly OutputFix[],
+  logger: Logger,
+): void {
+  const isUnionReused = fixes.includes(OutputFix.ALLOF_DISCRIMINATED_UNION);
+  for (const conflict of findDiscriminatorValueConflicts(document, { isUnionReused })) {
+    logger.warn(warningText(warningOf(conflict), WARNING_CODES.DISCRIMINATOR_VALUE_NOT_ALLOWED));
+  }
+}

package/src/api/discriminator-enum-names.ts

@@ -0,0 +1,26 @@
+import type { SharedEnumNames } from "../application/transform/footer/shared-enum-names.js";
+import type { EnumDeclarationRequest } from "../application/transform/schema/schema-context.js";
+
+/**
+ * `--dedupe-enums` names a shared enum after the first schema that declares it. With
+ * `discriminator-values` and `--enum`, a member's value refers to the owner's enum, which is then
+ * declared when the member is typed, maybe before that first schema; the shared enum would take
+ * the owner's name. A first pass records the names of the declaring schemas only, so the second
+ * pass names each shared enum as the document order does (`OtherKind`, not `PetPetType`).
+ */
+export class FirstSchemaNameRecorder implements SharedEnumNames {
+  private readonly names = new Map<string, string>();
+
+  nameOf(key: string, name: string, request: EnumDeclarationRequest): string {
+    if (!request.isOwnerReference && !this.names.has(key)) {
+      this.names.set(key, name);
+    }
+    return name;
+  }
+
+  /** The recorded name of each shared enum, for the second pass. */
+  chosenNames(): SharedEnumNames {
+    const chosen = new Map(this.names);
+    return { nameOf: (key, name) => chosen.get(key) ?? name };
+  }
+}

package/src/api/discriminator-enum-parent.ts

@@ -0,0 +1,129 @@
+import { createRef, parseRefPointer } from "../domain/openapi/json-pointer.js";
+import type { SchemaObject } from "../types.js";
+import type { EnumPatch } from "./discriminator-enum.js";
+
+/**
+ * The `discriminator-values` fix (#1700). With `--enum`, the enum the scan adds to a member
+ * (`petType: "Cat"`) is declared as an enum of its own (`CatPetType`), which is not assignable to
+ * the parent's enum (`PetType`). The parent's enum is found here, so the member's property can be
+ * typed with its members (`PetType.Cat`).
+ */
+
+/** The parent's enum schema and the location it is typed at, which gives the enum its name. */
+export interface EnumParent {
+  readonly schema: SchemaObject;
+  readonly path: string;
+}
+
+type ResolveSchemaRef = (ref: string) => unknown;
+
+/** A declared property schema and the location the transformer types it at. */
+interface DeclaredProperty {
+  readonly property: unknown;
+  readonly path: string;
+}
+
+const PROPERTIES_KEYWORD = "properties";
+/** `components`, `schemas` and the schema name: the segments before the schema's own keywords. */
+const ROOT_SEGMENTS = 3;
+
+/** The location a `$ref` is typed at: object properties are nested without `properties`. */
+function typedAt(ref: string): string {
+  const segments = parseRefPointer(ref);
+  const nested = segments.slice(ROOT_SEGMENTS).filter((segment) => segment !== PROPERTIES_KEYWORD);
+  return createRef([...segments.slice(0, ROOT_SEGMENTS), ...nested]);
+}
+
+function isSchemaObject(value: unknown): value is SchemaObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The property `name` of a schema object typed at `ref`. */
+function ownProperty(item: SchemaObject, ref: string, name: string): DeclaredProperty | undefined {
+  const property = ("properties" in item ? item.properties : undefined)?.[name];
+  return property === undefined ? undefined : { property, path: createRef([ref, name]) };
+}
+
+/** The property `name` of the schema at `ref`, its own or from an `allOf` item, depth first. */
+function declaredProperty(
+  ref: string,
+  name: string,
+  resolve: ResolveSchemaRef,
+  visited: Set<string>,
+): DeclaredProperty | undefined {
+  const schema = resolve(ref);
+  if (visited.has(ref) || !isSchemaObject(schema)) {
+    return undefined;
+  }
+  visited.add(ref);
+  // An inline `allOf` item is typed at its parent's location, so both share the path.
+  for (const item of [schema, ...(schema.allOf ?? [])]) {
+    if (!isSchemaObject(item)) {
+      continue;
+    }
+    const found =
+      "$ref" in item
+        ? declaredProperty(item.$ref as string, name, resolve, visited)
+        : ownProperty(item, ref, name);
+    if (found !== undefined) {
+      return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A discriminator and the `$ref` of the schema that declares its property; `ref` is the member
+ * whose value the discriminator gives, where there is one.
+ */
+export type DiscriminatorOwner = Pick<EnumPatch, "discriminator" | "discriminatorRef"> &
+  Partial<Pick<EnumPatch, "ref">>;
+
+/**
+ * The property `name` that the member at `ref` inherits through its `allOf` `$ref`s. Its own
+ * keywords and inline items are left out: the scan writes the added value there.
+ */
+function inheritedProperty(
+  ref: string,
+  name: string,
+  resolve: ResolveSchemaRef,
+): DeclaredProperty | undefined {
+  const schema = resolve(ref);
+  const visited = new Set([ref]);
+  for (const item of isSchemaObject(schema) ? (schema.allOf ?? []) : []) {
+    const found =
+      isSchemaObject(item) && "$ref" in item
+        ? declaredProperty(item.$ref as string, name, resolve, visited)
+        : undefined;
+    if (found !== undefined) {
+      return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The enum of the property that the discriminator owner declares, if it is one. An owner that
+ * declares no such property (a `oneOf` with a mapping) leaves the member's type to the property
+ * the member inherits, so that property's enum is the one.
+ */
+export function enumParentOf(
+  patch: DiscriminatorOwner,
+  resolve: ResolveSchemaRef,
+): EnumParent | undefined {
+  const name = patch.discriminator.propertyName;
+  const declared =
+    declaredProperty(patch.discriminatorRef, name, resolve, new Set()) ??
+    (patch.ref === undefined ? undefined : inheritedProperty(patch.ref, name, resolve));
+  if (declared === undefined || !isSchemaObject(declared.property)) {
+    return undefined;
+  }
+  const ref = (declared.property as { readonly $ref?: unknown }).$ref;
+  const parent =
+    typeof ref === "string"
+      ? { schema: resolve(ref), path: typedAt(ref) }
+      : { schema: declared.property, path: declared.path };
+  return isSchemaObject(parent.schema) && Array.isArray(parent.schema.enum)
+    ? { schema: parent.schema, path: parent.path }
+    : undefined;
+}

package/src/api/discriminator-enum.ts

@@ -61,6 +61,45 @@ function isObjectSchema(schema: unknown): schema is SchemaObject & ObjectSubtype
   );
 }
 
+/** The values a property schema allows, from `const` or `enum`; null when it lists none. */
+function listedValues(property: unknown): readonly unknown[] | null {
+  if (typeof property !== "object" || property === null) {
+    return null;
+  }
+  const { const: constant, enum: values } = property as SchemaObject;
+  if (constant !== undefined) {
+    return [constant];
+  }
+  return Array.isArray(values) ? values : null;
+}
+
+/** Whether one schema object requires the property and allows exactly the values. */
+function requiresValues(schema: unknown, name: string, values: readonly string[]): boolean {
+  if (typeof schema !== "object" || schema === null || "$ref" in schema) {
+    return false;
+  }
+  const { required, properties } = schema as SchemaObject & ObjectSubtype;
+  const listed = listedValues(properties?.[name]);
+  return (
+    Boolean(required?.includes(name)) &&
+    listed !== null &&
+    listed.length === values.length &&
+    values.every((value) => listed.includes(value))
+  );
+}
+
+/**
+ * Whether `schema`, or an inline `allOf` item of it, already requires the discriminator property
+ * with exactly the patch's values (the `discriminator-values` fix). Then a patch would
+ * only repeat it (#2124).
+ */
+export function declaresValues(schema: SchemaObject | undefined, patch: EnumPatch): boolean {
+  const name = patch.discriminator.propertyName;
+  return [schema, ...(schema?.allOf ?? [])].some((item) =>
+    requiresValues(item, name, patch.values),
+  );
+}
+
 /**
  * Add or replace the enum property in `schema`, an `allOf` or object schema. Returns the added
  * enum schema, or null for another kind of schema, which is left as it is.

package/src/api/discriminator-other-owners.ts

@@ -0,0 +1,97 @@
+import type { DiscriminatorObject, ReferenceObject, SchemaObject } from "../types.js";
+import type { EnumPatch } from "./discriminator-enum.js";
+import { enumKey, patchDiscriminatorEnum, type ScanState } from "./discriminator-patch.js";
+import { resolveDocumentRef } from "./document-refs.js";
+
+/**
+ * The `discriminator-values` fix: a schema inherits one discriminator per property. A schema that
+ * owns a discriminator keeps its own (#2200), so the scan does not record the one it inherits for
+ * another property (`Content` owns `subtype` and `allOf`s `Element`, which owns `contentType`).
+ * Its members (`Video`) still get a value of that property, found here from the owners above.
+ */
+
+/** A discriminator and the schema that defines it. */
+interface OtherOwner {
+  readonly discriminator: DiscriminatorObject;
+  readonly ownerRef: string;
+}
+
+/** The `$ref`s of a schema's `allOf` items. */
+function allOfRefs(state: ScanState, ref: string): string[] {
+  const { silent, logger } = state;
+  const schema = resolveDocumentRef<SchemaObject>(state.schema, ref, { silent, logger });
+  const items = (schema?.allOf ?? []) as (SchemaObject | ReferenceObject)[];
+  return items.flatMap((item) =>
+    "$ref" in item && typeof item.$ref === "string" ? [item.$ref] : [],
+  );
+}
+
+/**
+ * The owners' discriminators that the schema at `parentRef` and its `allOf` parents define, the
+ * nearest one per property, except the property of `parentRef`'s own discriminator.
+ */
+function otherOwners(state: ScanState, parentRef: string): OtherOwner[] {
+  const own = state.objects[parentRef]?.propertyName;
+  const found = new Map<string, OtherOwner>();
+  const visited = new Set<string>();
+  const queue = [parentRef];
+  for (let ref = queue.shift(); ref !== undefined; ref = queue.shift()) {
+    if (visited.has(ref)) {
+      continue;
+    }
+    visited.add(ref);
+    const discriminator = state.owners.has(ref) ? state.objects[ref] : undefined;
+    const name = discriminator?.propertyName;
+    if (discriminator && name !== undefined && name !== own && !found.has(name)) {
+      found.set(name, { discriminator, ownerRef: ref });
+    }
+    queue.push(...allOfRefs(state, ref));
+  }
+  return [...found.values()];
+}
+
+/**
+ * The child redefines this property, so its `allOf` items omit it: a parent may have a value of
+ * its own, as `Content` has when `Element`'s mapping names it.
+ */
+function recordOtherProperty(state: ScanState, ref: string, propertyName: string): void {
+  const names = state.otherProperties[ref] ?? [];
+  if (!names.includes(propertyName)) {
+    names.push(propertyName);
+  }
+  state.otherProperties[ref] = names;
+}
+
+/**
+ * The child at `ref` of the schema at `parentRef` gets a value of each other property: a mapped
+ * one at once, else its schema name after both passes, where no mapping gives one. The schema's
+ * own discriminator property is still added, so these patches do not mark it handled.
+ */
+export function inheritOtherOwners(state: ScanState, parentRef: string, ref: string): void {
+  const childProperty = state.objects[ref]?.propertyName;
+  for (const { discriminator, ownerRef } of otherOwners(state, parentRef)) {
+    if (discriminator.propertyName === childProperty) {
+      continue;
+    }
+    recordOtherProperty(state, ref, discriminator.propertyName);
+    const mapped = Object.entries(discriminator.mapping ?? {})
+      .filter(([, target]) => target === ref)
+      .map(([value]) => value);
+    const name = ref.slice(ref.lastIndexOf("/") + 1);
+    const patch: EnumPatch = { ref, values: mapped, discriminator, discriminatorRef: ownerRef };
+    if (mapped.length > 0) {
+      patchDiscriminatorEnum(state, patch);
+    } else {
+      state.otherInferredPatches.push({ ...patch, values: [name] });
+    }
+  }
+}
+
+/** The deferred schema-name values of other properties; see `inheritOtherOwners`. */
+export function applyOtherInferredPatches(state: ScanState, mapped: ReadonlySet<string>): void {
+  for (const patch of state.otherInferredPatches) {
+    if (!mapped.has(enumKey(patch))) {
+      patchDiscriminatorEnum(state, patch);
+    }
+  }
+}