openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.4

package/src/application/transform/document/webhooks.ts

@@ -1,7 +1,7 @@
 import { irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { PathItemObject, PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { documentEntries } from "../document-entries.js";
 import type { TransformContext } from "../transform-context.js";
@@ -14,7 +14,7 @@ import { pathItemType } from "./path-item.js";
  */
 export function webhooksType(webhooks: PathsObject, context: TransformContext): IrType {
   const members = documentEntries(webhooks, context.options).map(([name, pathItem]) => {
-    const location = { path: createRef(["webhooks", name]) };
+    const location = { path: appendPointer(ROOT_POINTER, ["webhooks", name]) };
     const type = pathItemType(pathItem as PathItemObject, location, context);
     return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
   });

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

@@ -12,12 +12,14 @@ import type {
   EnumValuesRequest,
 } from "../schema/schema-context.js";
 import type { DocumentFooter } from "../transform-context.js";
+import { EnumNameClaims } from "./enum-name-claims.js";
 import {
   type DeclaredMembers,
   EnumNaming,
   enumDeclaration,
   withoutDeclaredMembers,
 } from "./enum-naming.js";
+import { OperationKeys } from "./operation-keys.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. */
@@ -62,6 +64,12 @@ function declarationKey(name: string, request: EnumDeclarationRequest): string {
   return JSON.stringify([name, request.values, request.metadata]);
 }
 
+/** The naming state a run's footer shares with the rest of the run. */
+export interface RunFooterNames {
+  readonly enums: EnumNameClaims;
+  readonly operations: OperationKeys;
+}
+
 /**
  * The footer of one run: enums (deduplicated with `--dedupe-enums`), `--enum-values` arrays, the
  * helper types they need, and the `operations` interface. Replaces the original's module-level
@@ -83,15 +91,18 @@ export class RunFooter implements DocumentFooter {
   private readonly sink: FooterSink;
   private readonly isDedupingEnums: boolean;
   private readonly sharedNames: SharedEnumNames;
+  private readonly names: RunFooterNames;
 
   constructor(
     sink: FooterSink,
     isDedupingEnums: boolean,
     sharedNames: SharedEnumNames = FIRST_SCHEMA_NAMES,
+    names: RunFooterNames = { enums: new EnumNameClaims(), operations: new OperationKeys() },
   ) {
     this.sink = sink;
     this.isDedupingEnums = isDedupingEnums;
     this.sharedNames = sharedNames;
+    this.names = names;
   }
 
   addEnum(request: EnumDeclarationRequest): string {
@@ -99,11 +110,13 @@ export class RunFooter implements DocumentFooter {
     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 sharedName = key === null ? ownName : this.sharedNames.nameOf(key, ownName, request);
     const known = key === null ? undefined : this.enumNamesByKey.get(key);
     if (known !== undefined) {
       return known;
     }
+    // The owner is the schema location: its requests share one enum, with `--dedupe-enums` too.
+    const name = this.names.enums.nameFor(sharedName, request.name);
     // Only a repeated member fails to compile; two empty declarations merge, so they stay.
     const declared = request.values.length > 0 ? declarationKey(name, request) : null;
     if (declared !== null && this.declaredEnums.has(declared)) {
@@ -200,6 +213,10 @@ export class RunFooter implements DocumentFooter {
     this.sink.addOperation(build);
   }
 
+  operationKey(operationId: string): string {
+    return this.names.operations.keyFor(operationId);
+  }
+
   private require(helper: HelperType): void {
     if (!this.sink.hasTypeAlias(helper.name)) {
       this.sink.add({ kind: "rawDeclaration", name: helper.name, text: helper.text });

package/src/application/transform/footer/enum-name-claims.ts

@@ -0,0 +1,62 @@
+import { freeNumberedName } from "../numbered-names.js";
+
+/**
+ * The names of the `--enum` declarations of one run, unique across the enums and apart from the
+ * names the rest of the output may need.
+ *
+ * Every enum has an owner: the schema location it is named after, or with `--dedupe-enums` its
+ * members. Two owners whose names come out the same (`status` and `Status`) merged into one enum
+ * before, so each accepted the values of the other (upstream behavior). Now the first owner keeps
+ * the name and each later one gets the next free `Name_2`, `Name_3`, …; requests of one owner (a
+ * property and an inline `allOf` item of one schema) still share one enum.
+ *
+ * An enum also gives way to a name the output may need, which is only known at the end: a global
+ * type the output refers to (the `Blob` of `--binary-as-blob`, the `Record` of
+ * `Record<string, never>`), a helper type, or `ApiPaths`. Until then it takes the numbered name;
+ * `givenBack` lists the ones whose own name the output turned out not to need, so output that
+ * compiled before keeps its names (ADR-021).
+ */
+export class EnumNameClaims {
+  private readonly mayBeNeeded: ReadonlySet<string>;
+  /** The first owner of each name an enum asked for. */
+  private readonly owners = new Map<string, string>();
+  /** The name given to each owner, by name asked for and owner. */
+  private readonly given = new Map<string, string>();
+  /** Every name given, and every name the output may need. */
+  private readonly taken: Set<string>;
+  /** A numbered name given only because the output may need the name asked for: that name. */
+  private readonly standIns = new Map<string, string>();
+
+  /** `mayBeNeeded`: the names an enum avoids until the end of the run; empty outside a run. */
+  constructor(mayBeNeeded: ReadonlySet<string> = new Set()) {
+    this.mayBeNeeded = mayBeNeeded;
+    this.taken = new Set(mayBeNeeded);
+  }
+
+  /** The declaration name of the enum `owner` asks to name `name`; the same for every request. */
+  nameFor(name: string, owner: string): string {
+    const key = JSON.stringify([name, owner]);
+    const known = this.given.get(key);
+    if (known !== undefined) {
+      return known;
+    }
+    const isFirstOwner = (this.owners.get(name) ?? owner) === owner;
+    this.owners.set(name, this.owners.get(name) ?? owner);
+    const isFree = isFirstOwner && !this.taken.has(name);
+    const declared = isFree ? name : freeNumberedName(name, this.taken);
+    if (isFirstOwner && this.mayBeNeeded.has(name)) {
+      this.standIns.set(declared, name);
+    }
+    this.taken.add(declared);
+    this.given.set(key, declared);
+    return declared;
+  }
+
+  /**
+   * The numbered names to rename back to the name asked for, because `needed` (the names the
+   * finished output declares or refers to) does not hold that name.
+   */
+  givenBack(needed: ReadonlySet<string>): ReadonlyMap<string, string> {
+    return new Map([...this.standIns].filter(([, name]) => !needed.has(name)));
+  }
+}

package/src/application/transform/footer/operation-keys.ts

@@ -0,0 +1,28 @@
+/**
+ * The keys of the `operations` interface in one run. A repeated `operationId` (Redocly warns
+ * about it) gave the interface two members of one name, which did not compile (TS2300). Now the
+ * first operation with an ID keeps it, and each later one gets the lowest number from 2 whose key
+ * no operation of the document has: the second `listItems` is `listItems2`, the name
+ * `--make-paths-enum` gives it in `ApiPaths` too. Keys follow the order the operations are
+ * transformed in, which is the document order (or the `--alphabetize` order).
+ */
+export class OperationKeys {
+  private readonly written: ReadonlySet<string>;
+  private readonly taken = new Set<string>();
+
+  /** `written`: every operation key of the document; empty outside a document run. */
+  constructor(written: ReadonlySet<string> = new Set()) {
+    this.written = written;
+  }
+
+  /** The key of the next operation with this key, written or numbered. */
+  keyFor(key: string): string {
+    let unique = key;
+    for (let count = 2; this.taken.has(unique); count += 1) {
+      const candidate = `${key}${count}`;
+      unique = this.written.has(candidate) ? unique : candidate;
+    }
+    this.taken.add(unique);
+    return unique;
+  }
+}

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

@@ -22,7 +22,7 @@ import { extracted, markerObject, omitted } from "./type-rules.js";
 
 /** How many references one evaluation expands; a deeper one is opaque. */
 const MAX_EXPANSIONS = 200;
-const DEEP_PREFIX = "FlattenedDeepRequired<";
+const DEEP_HELPER = "FlattenedDeepRequired";
 /** How many members distributing an intersection may give; more is opaque. */
 const MAX_DISTRIBUTED = 64;
 
@@ -75,15 +75,15 @@ export class TypeEvaluator {
     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));
+    const [first, second] = args;
+    if (name === DEEP_HELPER && first?.kind === "reference" && first.typeArguments.length === 0) {
+      const root = this.declared.get(first.name);
       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;
     }

package/src/application/transform/helper-types.ts

@@ -51,9 +51,10 @@ export const HELPER_TYPES = {
 /**
  * The `--read-write-markers` helper types, written before the root types. Task 7.6 replaces the
  * original text on purpose (ADR-014): primitives (also branded), readonly arrays, tuples,
- * intersected arrays and null-only properties keep their types (upstream #2615, #2620, #2632,
- * #2717, #2765). The declarations equal `Readable` / `Writable` of openapi-typesafe-helpers
- * (`test/api/read-write-marker-types.test.ts`); the text is what the TypeScript printer prints.
+ * intersected arrays, null-only and `any` properties keep their types (upstream #2615, #2620,
+ * #2632, #2717, #2765). The declarations equal the `Readable` / `Writable` that
+ * openapi-typesafe-fetch declares (`test/api/read-write-marker-types.test.ts`); the text is what
+ * the TypeScript printer prints.
  */
 export const READ_WRITE_MARKER_TYPES = lines(
   "export type $Read<T> = {",
@@ -65,8 +66,8 @@ export const READ_WRITE_MARKER_TYPES = lines(
   "type ReadWritePrimitive = string | number | boolean | bigint | symbol | null | undefined;",
   "type ReadWriteLeaf = ReadWritePrimitive | ((...args: never) => unknown);",
   "type ReadWriteMarkedKeys<T, Marker> = {",
-  "    [K in keyof T]-?: NonNullable<T[K]> extends never ? never : NonNullable<T[K]> " +
-    "extends Marker ? K : never;",
+  "    [K in keyof T]-?: 0 extends 1 & T[K] ? never : NonNullable<T[K]> extends never ? never : " +
+    "NonNullable<T[K]> extends Marker ? K : never;",
   "}[keyof T];",
   'type ReadWriteResolveArray<T extends readonly unknown[], Resolved extends "read" | ' +
     '"write"> = T[number][] extends T ? T extends unknown[] ? ReadWriteResolve<T[number], ' +

package/src/application/transform/numbered-names.ts

@@ -18,3 +18,18 @@ export function withNumberedRepeats(names: readonly string[], numbered: Numbered
     return unique;
   });
 }
+
+/** Separates a repeated declaration name from its number: `Status` → `Status_2`. */
+const DECLARATION_NUMBER_SEPARATOR = "_";
+
+/**
+ * The first of `Name_2`, `Name_3`, … that `taken` does not hold: the suffix `--root-types` uses for
+ * its own conflicts, and every other declaration that must give way to another name.
+ */
+export function freeNumberedName(name: string, taken: ReadonlySet<string>): string {
+  let count = 2;
+  while (taken.has(`${name}${DECLARATION_NUMBER_SEPARATOR}${count}`)) {
+    count += 1;
+  }
+  return `${name}${DECLARATION_NUMBER_SEPARATOR}${count}`;
+}

package/src/application/transform/ref-pointer/generated-location.ts

@@ -1,4 +1,4 @@
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { RefResolver } from "../schema/schema-context.js";
 import { isJsonObject } from "./generated-shape.js";
 import {
@@ -205,7 +205,7 @@ function walkTo(ref: string, refs: RefResolver, seen: readonly string[]): Locati
 export function generatedLocationOf(ref: string, refs: RefResolver): GeneratedLocation {
   const walk = walkTo(ref, refs, []);
   return {
-    path: walk === null ? ref : createRef(walk.path),
+    path: walk === null ? ref : appendPointer(ROOT_POINTER, walk.path),
     isFromAdditionalProperties: walk?.isFromAdditionalProperties ?? false,
   };
 }

package/src/application/transform/ref-type.ts

@@ -68,7 +68,8 @@ export function indexKeyword(type: IrType, segment: string, isLast: boolean): Ir
 }
 
 export function rootType(rootSegment: string, isDeep: boolean): IrType {
-  return irReference(isDeep ? `FlattenedDeepRequired<${rootSegment}>` : rootSegment);
+  const root = irReference(rootSegment);
+  return isDeep ? irReference("FlattenedDeepRequired", [root]) : root;
 }
 
 /**

package/src/application/transform/schema/composition-type.ts

@@ -1,6 +1,6 @@
 import { irKeyword, irRecord } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { FIX } from "../../../domain/output-fixes.js";
 import { requirableRefType } from "../ref-pointer/pointer-type.js";
@@ -29,7 +29,7 @@ function variantTypes(
   return variants.map((variant, index) =>
     request.transformNested(variant, {
       ...request.location,
-      path: createRef([request.location.path, keyword, String(index)]),
+      path: appendPointer(request.location.path, [keyword, index]),
     }),
   );
 }

package/src/application/transform/schema/enum-rule.ts

@@ -6,7 +6,11 @@ import {
   irString,
 } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
-import { createRef, parseRefPointer } from "../../../domain/openapi/json-pointer.js";
+import {
+  appendPointer,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "../../../domain/openapi/json-pointer.js";
 import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { FIX } from "../../../domain/output-fixes.js";
 import { literalType } from "../literal-type.js";
@@ -228,7 +232,7 @@ function enumValuesPointer(path: string | undefined): { ref: string; extract: st
       : pointer
           .slice(firstVariantStart)
           .filter((segment) => !UNION_KEYWORDS.has(segment) && !INDEX_RE.test(segment));
-  return { ref: createRef(kept), extract };
+  return { ref: appendPointer(ROOT_POINTER, kept), extract };
 }
 
 function addEnumValues(schema: SchemaObject, request: SchemaRequest): void {

package/src/application/transform/schema/object-type.ts

@@ -7,7 +7,7 @@ import {
 } from "../../../domain/ir/constructors.js";
 import type { IrMember, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { documentEntries } from "../document-entries.js";
 import { schemaRefType } from "../ref-pointer/pointer-type.js";
@@ -117,7 +117,7 @@ function propertyType(
   facts: PropertyFacts,
   request: SchemaRequest,
 ): CustomResult {
-  const path = createRef([request.location.path, key]);
+  const path = appendPointer(request.location.path, [key]);
   const type = facts.ref
     ? schemaRefType(facts.ref, request)
     : request.transformNested(value, { ...request.location, path });
@@ -151,7 +151,7 @@ function propertyMember(
       isReadonly: options.immutable || (!options.readWriteMarkers && facts.flags.isReadOnly),
     },
   );
-  return finishProperty(property, value, createRef([request.location.path, key]), request);
+  return finishProperty(property, value, appendPointer(request.location.path, [key]), request);
 }
 
 function propertyMembers(schema: SchemaObject, request: SchemaRequest): IrMember[] {
@@ -176,7 +176,7 @@ function defsMember(
 ): IrMember {
   const { options } = request.context;
   const members = Object.entries(defs).map(([key, value]) => {
-    const path = createRef([request.location.path, "$defs", key]);
+    const path = appendPointer(request.location.path, ["$defs", key]);
     const flags = propertyAccessFlags(value, request.context);
     const type = withReadWriteMarker(
       request.transformNested(value, { ...request.location, path }),

package/src/application/transform/schema/ref-siblings.ts

@@ -0,0 +1,76 @@
+import { SCHEMA_DIALECTS } from "../../../domain/openapi/schema-dialect.js";
+import type {
+  ReferenceSchema,
+  Schema,
+  SchemaObject,
+} from "../../../domain/openapi/schema-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
+import type { SchemaOptions } from "./schema-context.js";
+
+/**
+ * The `ref-siblings` fix (ADR-021 amendment 2, RC4 G16): in JSON Schema 2020-12 (OpenAPI 3.1 and
+ * 3.2) the keywords next to a `$ref` apply too, so `{ $ref: Base, required: [extra], properties:
+ * { extra } }` is a `Base` that also has a required `extra`. That is what `allOf: [{ $ref: Base }]`
+ * next to the same keywords means, so the schema is typed as that `allOf`, with every rule the
+ * generator has for `allOf` and its siblings (`WithRequired`, intersections).
+ */
+
+/**
+ * Keywords that only annotate (JSON Schema 2020-12 meta-data, format-annotation and content
+ * vocabularies, OpenAPI fixed fields), or that change no type on their own (`discriminator`
+ * without `oneOf`). Next to a `$ref` they stay where they were, so the output keeps the plain
+ * reference with its comment. Extension keywords (`x-…`) count as annotations too.
+ */
+const ANNOTATION_KEYWORDS: ReadonlySet<string> = new Set([
+  "$anchor",
+  "$comment",
+  "$defs",
+  "$dynamicAnchor",
+  "$id",
+  "$ref",
+  "$schema",
+  "contentEncoding",
+  "contentMediaType",
+  "default",
+  "deprecated",
+  "description",
+  "discriminator",
+  "example",
+  "examples",
+  "externalDocs",
+  "format",
+  "readOnly",
+  "title",
+  "writeOnly",
+  "xml",
+]);
+
+const EXTENSION_PREFIX = "x-";
+
+function hasRef(schema: SchemaObject): schema is SchemaObject & ReferenceSchema {
+  return typeof (schema as Partial<ReferenceSchema>).$ref === "string";
+}
+
+function isTypeKeyword(keyword: string): boolean {
+  return !ANNOTATION_KEYWORDS.has(keyword) && !keyword.startsWith(EXTENSION_PREFIX);
+}
+
+/**
+ * A `$ref` schema as the `allOf` it means, or null where nothing changes: a schema without `$ref`,
+ * no fix, an OpenAPI 3.0 document, or no sibling that changes the type. The result has no
+ * `$ref`, so the shape rules type it as `enum`, `const` or a composition.
+ */
+export function refWithSiblingsAsAllOf(
+  schema: SchemaObject,
+  options: SchemaOptions,
+): SchemaObject | null {
+  const isApplied =
+    options.fixes.has(FIX.REF_SIBLINGS) &&
+    options.schemaDialect === SCHEMA_DIALECTS.JSON_SCHEMA_2020_12;
+  if (!isApplied || !hasRef(schema) || !Object.keys(schema).some(isTypeKeyword)) {
+    return null;
+  }
+  const { $ref, allOf = [], ...siblings } = schema;
+  const members: readonly Schema[] = [{ $ref }, ...allOf];
+  return { ...siblings, allOf: members };
+}

package/src/application/transform/schema/schema-context.ts

@@ -1,4 +1,5 @@
 import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import type { SchemaDialect } from "../../../domain/openapi/schema-dialect.js";
 import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
 import type { OutputFix } from "../../../domain/output-fixes.js";
 
@@ -27,6 +28,8 @@ export interface SchemaOptions {
   readonly immutable: boolean;
   readonly propertiesRequiredByDefault: boolean;
   readonly readWriteMarkers: boolean;
+  /** Whether keywords next to a `$ref` apply (OpenAPI 3.1 and 3.2) or not (3.0). */
+  readonly schemaDialect: SchemaDialect;
 }
 
 /**

package/src/application/transform/schema/schema-transform.ts

@@ -7,6 +7,7 @@ import { schemaRefType } from "../ref-pointer/pointer-type.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { compositionType } from "./composition-type.js";
 import { enumRule } from "./enum-rule.js";
+import { refWithSiblingsAsAllOf } from "./ref-siblings.js";
 import type { SchemaContext, SchemaLocation } from "./schema-context.js";
 import type { SchemaRequest, SchemaRule } from "./schema-rule.js";
 
@@ -83,8 +84,9 @@ export function transformSchemaShape(
     return checked.type;
   }
   const current = request(location, context, isFromAdditionalProperties);
-  const rule = SHAPE_RULES.find((candidate) => candidate.matches(checked.schema));
-  return rule ? rule.transform(checked.schema, current) : compositionType(checked.schema, current);
+  const shaped = refWithSiblingsAsAllOf(checked.schema, context.options) ?? checked.schema;
+  const rule = SHAPE_RULES.find((candidate) => candidate.matches(shaped));
+  return rule ? rule.transform(shaped, current) : compositionType(shaped, current);
 }
 
 /** Transform a schema to IR, then apply `postTransform` (the original `transformSchemaObject`). */

package/src/application/transform/schema-comment.ts

@@ -1,3 +1,4 @@
+import { appendAll } from "../../domain/append-all.js";
 import type { IrComment, IrPropertySignature } from "../../domain/ir/nodes.js";
 import { FIX, type OutputFix } from "../../domain/output-fixes.js";
 
@@ -80,7 +81,10 @@ function valueTagLines(schema: AnnotatedSchema): string[] {
     lines.push(`@${tag} ${formatValue(value)}`);
   }
   if (Array.isArray(schema.examples)) {
-    lines.push(...schema.examples.map((example: unknown) => `@example ${formatValue(example)}`));
+    appendAll(
+      lines,
+      schema.examples.map((example: unknown) => `@example ${formatValue(example)}`),
+    );
   }
   return lines;
 }

package/src/application/transform/transform-context.ts

@@ -33,6 +33,11 @@ export interface DocumentFooter extends FooterDeclarations {
    * it comes before any declaration the operation adds, as in the original.
    */
   addOperation(build: () => IrPropertySignature): void;
+  /**
+   * The key in `operations` of the next operation with this (normalized) `operationId`: the ID,
+   * or for a repeated ID a numbered one (`OperationKeys`).
+   */
+  operationKey(operationId: string): string;
 }
 
 /** Debug output for slow parts of a run (`DEBUG=openapi-ts:*`). */

package/src/cli/api-settings.ts

@@ -1,8 +1,11 @@
 import { kebabCase } from "scule";
+import { isOpenAPITypesafeError, OpenAPITypesafeError } from "../domain/errors.js";
+import type { OutputFixName } from "../domain/output-fixes.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
-import { GENERATOR_FLAGS, hostList } from "./cli-arguments.js";
+import { GENERATOR_FLAGS, type GeneratorFlags, hostList } from "./cli-arguments.js";
 import { cliError } from "./cli-errors.js";
 import { resolveLocationUrl } from "./cli-output.js";
+import { fixNamesOf } from "./fix-option.js";
 import type { RefLimitOptions } from "./ref-limits.js";
 
 /**
@@ -51,22 +54,94 @@ export function unknownSettingWarnings(apiName: string, settings: ApiSettings):
     );
 }
 
+/** The key a setting is written with: camelCase, else kebab-case; undefined when it is absent. */
+function settingKey(settings: ApiSettings, name: string): string | undefined {
+  if (name in settings) {
+    return name;
+  }
+  const kebabName = kebabCase(name);
+  return kebabName in settings ? kebabName : undefined;
+}
+
 /** The value of a setting in camelCase, else in kebab-case; `undefined` when it is absent. */
 function settingValue(settings: ApiSettings, name: string): unknown {
-  return name in settings ? settings[name] : settings[kebabCase(name)];
+  const key = settingKey(settings, name);
+  return key === undefined ? undefined : settings[key];
 }
 
 function hasSetting(settings: ApiSettings, name: string): boolean {
-  return name in settings || kebabCase(name) in settings;
+  return settingKey(settings, name) !== undefined;
 }
 
-function invalidSetting(apiName: string, name: string, expected: string): Error {
+/** `CLI_CONFIG_INVALID` for the setting `name` of an API, named as the user wrote it. */
+function invalidSetting(apiName: string, settings: ApiSettings, name: string, expected: string) {
+  const key = settingKey(settings, name) ?? kebabCase(name);
   return cliError(
     "CLI_CONFIG_INVALID",
-    `API ${apiName}: \`${kebabCase(name)}\` in x-openapi-ts must be ${expected}`,
+    `API ${apiName}: \`${key}\` in x-openapi-ts must be ${expected}`,
   );
 }
 
+/**
+ * The boolean flags an API sets, in camelCase or kebab-case; they win over the CLI's flags. A
+ * value of another type (`root-types: "true"`) fails with `CLI_CONFIG_INVALID`: ignoring it
+ * would generate other types than the config asks for, without a word.
+ */
+export function apiFlags(apiName: string, settings: ApiSettings): GeneratorFlags {
+  const flags: Partial<Record<(typeof GENERATOR_FLAGS)[number], boolean>> = {};
+  for (const name of GENERATOR_FLAGS) {
+    const value = settingValue(settings, name);
+    if (typeof value === "boolean") {
+      flags[name] = value;
+    } else if (hasSetting(settings, name)) {
+      throw invalidSetting(apiName, settings, name, "true or false");
+    }
+  }
+  return flags;
+}
+
+/** The API's `output` file as written; fails with `CLI_CONFIG_INVALID` when it is not text. */
+export function apiOutputOf(apiName: string, settings: ApiSettings): string {
+  const output = settings[OUTPUT_SETTING];
+  if (typeof output !== "string") {
+    throw invalidSetting(apiName, settings, OUTPUT_SETTING, "a file path");
+  }
+  return output;
+}
+
+/**
+ * The API's `fix` names, which replace the CLI's `--fix` (ADR-021). An entry that is not text
+ * fails with `CLI_CONFIG_INVALID`; an unknown name with `OPTION_FIX_UNKNOWN`, naming the API.
+ */
+export function apiFixNames(
+  apiName: string,
+  settings: ApiSettings,
+): readonly OutputFixName[] | undefined {
+  if (!hasSetting(settings, FIX_SETTING)) {
+    return undefined;
+  }
+  const entries = [settingValue(settings, FIX_SETTING)].flat();
+  if (entries.some((entry) => typeof entry !== "string")) {
+    throw invalidSetting(apiName, settings, FIX_SETTING, "a list of fix names or a comma list");
+  }
+  try {
+    return fixNamesOf(entries);
+  } catch (error) {
+    throw isOpenAPITypesafeError(error) ? withApiName(apiName, error) : error;
+  }
+}
+
+/** The same error, with the API named first in its message. */
+function withApiName(apiName: string, error: OpenAPITypesafeError): OpenAPITypesafeError {
+  const { code, details, cause } = error;
+  return new OpenAPITypesafeError({
+    code,
+    message: `API ${apiName}: ${error.message}`,
+    details,
+    cause,
+  });
+}
+
 /** `local-ref-root: dir`, relative to the config file; empty means the config file's directory. */
 function localRefRootOf(apiName: string, settings: ApiSettings, configRoot: URL): RefLimitOptions {
   if (!hasSetting(settings, LOCAL_REF_ROOT_SETTING)) {
@@ -74,7 +149,7 @@ function localRefRootOf(apiName: string, settings: ApiSettings, configRoot: URL)
   }
   const value = settingValue(settings, LOCAL_REF_ROOT_SETTING) ?? "";
   if (typeof value !== "string") {
-    throw invalidSetting(apiName, LOCAL_REF_ROOT_SETTING, "a directory path");
+    throw invalidSetting(apiName, settings, LOCAL_REF_ROOT_SETTING, "a directory path");
   }
   return { localRefRoot: resolveLocationUrl(value === "" ? "." : value, configRoot) };
 }
@@ -87,7 +162,7 @@ function remoteRefHostsOf(apiName: string, settings: ApiSettings): RefLimitOptio
   const value = settingValue(settings, REMOTE_REF_HOSTS_SETTING) ?? [];
   const entries = [value].flat();
   if (entries.some((entry) => typeof entry !== "string")) {
-    throw invalidSetting(apiName, REMOTE_REF_HOSTS_SETTING, "a host list");
+    throw invalidSetting(apiName, settings, REMOTE_REF_HOSTS_SETTING, "a host list");
   }
   return { remoteRefHosts: hostList(entries) ?? [] };
 }