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

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

@@ -7,7 +7,7 @@ import {
 } from "../../../domain/ir/constructors.js";
 import type { IrTupleElement, IrType } from "../../../domain/ir/nodes.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { unionOf } from "../type-combinators.js";
 import type { SchemaRequest } from "./schema-rule.js";
@@ -79,9 +79,7 @@ function prefixItemsTupleType(
 }
 
 function isPrefixItemsFixed(schema: SchemaObject, request: SchemaRequest): boolean {
-  return (
-    schema.prefixItems !== undefined && request.context.options.fixes.has(OutputFix.PREFIX_ITEMS)
-  );
+  return schema.prefixItems !== undefined && request.context.options.fixes.has(FIX.PREFIX_ITEMS);
 }
 
 /** The type of one item; `unknown` without `items`. */
@@ -193,7 +191,7 @@ function fixedArrayType(schema: SchemaObject, request: SchemaRequest): IrType {
 
 function isArrayLengthFixed(request: SchemaRequest): boolean {
   const { arrayLength, fixes } = request.context.options;
-  return arrayLength && fixes.has(OutputFix.ARRAY_LENGTH_TUPLES);
+  return arrayLength && fixes.has(FIX.ARRAY_LENGTH_TUPLES);
 }
 
 /** `type: array`, including tuples (`prefixItems`, array `items`) and `--array-length`. */

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

@@ -1,8 +1,8 @@
 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 { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { requirableRefType } from "../ref-pointer/pointer-type.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import {
@@ -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]),
     }),
   );
 }
@@ -58,7 +58,7 @@ function keysToRequire(
   if (!request.context.discriminators.isHandled(ref)) {
     return defined;
   }
-  if (!request.context.options.fixes.has(OutputFix.DISCRIMINATOR_MEMBER_REQUIRED)) {
+  if (!request.context.options.fixes.has(FIX.DISCRIMINATOR_MEMBER_REQUIRED)) {
     return [];
   }
   return defined.filter((key) => !target.required?.includes(key));
@@ -131,7 +131,7 @@ function allOfItemType(
   const isUnion =
     unionItem !== undefined &&
     !unionItem.isMapped &&
-    request.context.options.fixes.has(OutputFix.ALLOF_DISCRIMINATED_UNION);
+    request.context.options.fixes.has(FIX.ALLOF_DISCRIMINATED_UNION);
   if (!propertyName || isUnion) {
     return type;
   }
@@ -173,7 +173,7 @@ function anyOfType(
   if (variants.length === 0 || previous === null) {
     return variants.length === 0 ? previous : unionOf(variants);
   }
-  if (!request.context.options.fixes.has(OutputFix.ANYOF_PROPERTIES)) {
+  if (!request.context.options.fixes.has(FIX.ANYOF_PROPERTIES)) {
     return unionOf([previous, ...variants]);
   }
   return Array.isArray(schema.type) ? previous : intersectionOf([previous, unionOf(variants)]);

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

@@ -6,9 +6,13 @@ 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 { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { literalType } from "../literal-type.js";
 import { refType } from "../ref-type.js";
 import { intersectionOf, unionOf } from "../type-combinators.js";
@@ -55,7 +59,7 @@ function hasEnumMetadata(schema: SchemaObject): boolean {
  */
 function tsEnumEntries(schema: SchemaObject, options: SchemaOptions): [unknown, number][] {
   const entries = (schema.enum ?? []).map((value, index): [unknown, number] => [value, index]);
-  return options.fixes.has(OutputFix.NULLABLE_ENUMS)
+  return options.fixes.has(FIX.NULLABLE_ENUMS)
     ? entries.filter(([value]) => value !== null)
     : entries;
 }
@@ -147,9 +151,7 @@ export function ownerEnumMembersType(
   request: SchemaRequest,
 ): IrType | null {
   const { options, discriminators, footer } = request.context;
-  const parent: DiscriminatorEnumParent | undefined = options.fixes.has(
-    OutputFix.DISCRIMINATOR_VALUES,
-  )
+  const parent: DiscriminatorEnumParent | undefined = options.fixes.has(FIX.DISCRIMINATOR_VALUES)
     ? discriminators.enumParentOf(key)
     : undefined;
   if (parent === undefined || !isTsEnum(parent.schema, options)) {
@@ -175,7 +177,7 @@ function tsEnumType(schema: SchemaObject, request: SchemaRequest): IrType {
       irReference(footer.addEnum(enumRequest(schema, request.location.path, options))),
       schema,
     );
-  return options.fixes.has(OutputFix.NULLABLE_ENUMS) && isNullAllowed(schema)
+  return options.fixes.has(FIX.NULLABLE_ENUMS) && isNullAllowed(schema)
     ? unionOf([type, irKeyword("null")])
     : type;
 }
@@ -230,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/presence-members.ts

@@ -1,5 +1,5 @@
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import type { SchemaRequest } from "./schema-rule.js";
 
 /**
@@ -81,7 +81,7 @@ export interface AllOfMembers {
  */
 export function allOfMembers(members: readonly Schema[], request: SchemaRequest): AllOfMembers {
   const unchanged = { members, required: [] };
-  if (!request.context.options.fixes.has(OutputFix.ALLOF_REQUIRED)) {
+  if (!request.context.options.fixes.has(FIX.ALLOF_REQUIRED)) {
     return unchanged;
   }
   const schemas = members.map((member) => memberSchema(member, request));

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/required-variants.ts

@@ -1,6 +1,6 @@
 import type { IrType } from "../../../domain/ir/nodes.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { unionOf, withRequiredKeys } from "../type-combinators.js";
 import { isKeptProperty } from "./object-type.js";
 import type { SchemaRequest } from "./schema-rule.js";
@@ -55,7 +55,7 @@ export function hasRequiredVariants(
   request: SchemaRequest,
 ): boolean {
   return (
-    request.context.options.fixes.has(OutputFix.ANYOF_ONEOF_REQUIRED) &&
+    request.context.options.fixes.has(FIX.ANYOF_ONEOF_REQUIRED) &&
     isObjectTyped(schema) &&
     requiredKeyLists(schema, variants, request) !== null
   );
@@ -73,7 +73,7 @@ export function requiredVariantsType(
   variants: readonly Schema[],
   request: SchemaRequest,
 ): IrType | null {
-  if (!request.context.options.fixes.has(OutputFix.ANYOF_ONEOF_REQUIRED) || previous === null) {
+  if (!request.context.options.fixes.has(FIX.ANYOF_ONEOF_REQUIRED) || previous === null) {
     return null;
   }
   const keyLists = isObjectTyped(schema) ? requiredKeyLists(schema, variants, request) : null;

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/unevaluated-properties.ts

@@ -6,7 +6,7 @@ import {
 } from "../../../domain/ir/constructors.js";
 import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { HELPER_TYPES } from "../helper-types.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { unionOf } from "../type-combinators.js";
@@ -32,7 +32,7 @@ import type { SchemaRequest } from "./schema-rule.js";
 function unevaluatedSchemaOf(schema: SchemaObject, request: SchemaRequest): Schema | null {
   const { unevaluatedProperties } = schema;
   if (
-    !request.context.options.fixes.has(OutputFix.UNEVALUATED_PROPERTIES) ||
+    !request.context.options.fixes.has(FIX.UNEVALUATED_PROPERTIES) ||
     unevaluatedProperties === undefined ||
     unevaluatedProperties === false ||
     schema.additionalProperties !== undefined

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

@@ -1,5 +1,6 @@
+import { appendAll } from "../../domain/append-all.js";
 import type { IrComment, IrPropertySignature } from "../../domain/ir/nodes.js";
-import { OutputFix } from "../../domain/output-fixes.js";
+import { FIX, type OutputFix } from "../../domain/output-fixes.js";
 
 /** Schema fields that produce JSDoc lines (the original `AnnotatedSchemaObject`). */
 export interface AnnotatedSchema {
@@ -44,7 +45,7 @@ export const ORIGINAL_SCHEMA_COMMENT: SchemaCommentOptions = { hasMemberDescript
 
 /** How the fixes turned on write a schema's JSDoc. */
 export function schemaCommentOptionsOf(fixes: ReadonlySet<OutputFix>): SchemaCommentOptions {
-  return { hasMemberDescriptions: fixes.has(OutputFix.ANYOF_ONEOF_DESCRIPTIONS) };
+  return { hasMemberDescriptions: fixes.has(FIX.ANYOF_ONEOF_DESCRIPTIONS) };
 }
 
 function formatValue(value: unknown): string {
@@ -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) ?? [] };
 }

package/src/cli/api-writes.ts

@@ -0,0 +1,117 @@
+import type { ClaimedFile } from "../application/ports/file-system.js";
+import type { GeneratedTypes } from "./cli-dependencies.js";
+import {
+  type CliRun,
+  duplicateOutputError,
+  emitOutput,
+  ensureOutputIsNotSchema,
+  type NamedFile,
+  type OutputFile,
+} from "./cli-output.js";
+
+/**
+ * Writing the generated APIs of a Redocly config. Before the first byte is written, every output
+ * is claimed: a missing one is created empty, so the file system gives it its own identity. Two
+ * APIs whose files then have one identity fail with `CLI_OUTPUT_DUPLICATE` and write nothing,
+ * also when their names looked different (ADR-043, decision 1).
+ */
+
+/** An API whose types are generated and not written yet. */
+export interface GeneratedApi {
+  readonly name: string;
+  readonly outputFile: OutputFile;
+  readonly types: GeneratedTypes;
+}
+
+/** An API whose output is claimed; `claim` is undefined with `--check`, which writes nothing. */
+interface ClaimedApi {
+  readonly api: GeneratedApi;
+  readonly claim: ClaimedFile | undefined;
+}
+
+/** The failures of the API an API name maps to; an API without failures was written. */
+type ApiFailures = Map<string, unknown[]>;
+
+/** The failure of a step, as a list: empty when it succeeded. */
+export function failuresOf(step: () => void): unknown[] {
+  try {
+    step();
+    return [];
+  } catch (failure) {
+    return [failure];
+  }
+}
+
+/** Claim the output of each API; an API whose claim fails gets that failure instead. */
+function claimOutputs(run: CliRun, apis: readonly GeneratedApi[], failures: ApiFailures) {
+  const claimed: ClaimedApi[] = [];
+  for (const api of apis) {
+    try {
+      const claim = run.args.isCheck ? undefined : run.deps.files.claimFile(api.outputFile.file);
+      claimed.push({ api, claim });
+    } catch (failure) {
+      failures.set(api.name, [failure]);
+    }
+  }
+  return claimed;
+}
+
+/** The APIs that share their claimed file with another, by API name, with the other names. */
+function sharedOutputs(claimed: readonly ClaimedApi[]): Map<string, string[]> {
+  const byIdentity = new Map<string, string[]>();
+  for (const { api, claim } of claimed) {
+    if (claim) {
+      byIdentity.set(claim.identity, [...(byIdentity.get(claim.identity) ?? []), api.name]);
+    }
+  }
+  const shared = new Map<string, string[]>();
+  for (const names of byIdentity.values()) {
+    for (const name of names.length > 1 ? names : []) {
+      shared.set(
+        name,
+        names.filter((other) => other !== name).map((other) => `API ${other}`),
+      );
+    }
+  }
+  return shared;
+}
+
+/** Write one claimed API; a failed write releases the claim, so no empty file is left. */
+function writeClaimed(run: CliRun, { api, claim }: ClaimedApi): unknown[] {
+  const failures = failuresOf(() => emitOutput(run, api.outputFile, api.types.contents));
+  return failures.length > 0 && claim
+    ? [...failures, ...failuresOf(() => claim.release())]
+    : failures;
+}
+
+/**
+ * Write (or `--check`) every API unless its output is a file the run read or the file of another
+ * API. Returns the failures by API name. Claims are released in reverse order, so a directory
+ * one claim created is empty by the time it is removed.
+ */
+export function writeGeneratedApis(
+  run: CliRun,
+  apis: readonly GeneratedApi[],
+  readFiles: readonly NamedFile[],
+): ApiFailures {
+  const failures: ApiFailures = new Map();
+  const ownOutputs = apis.filter((api) => {
+    const failure = failuresOf(() => ensureOutputIsNotSchema(run, api.outputFile, readFiles));
+    failures.set(api.name, failure);
+    return failure.length === 0;
+  });
+  const claimed = claimOutputs(run, ownOutputs, failures);
+  const shared = sharedOutputs(claimed);
+  for (const entry of [...claimed].reverse()) {
+    const { api, claim } = entry;
+    const others = shared.get(api.name);
+    if (others) {
+      const release = claim ? failuresOf(() => claim.release()) : [];
+      failures.set(api.name, [duplicateOutputError(api.outputFile, others), ...release]);
+    }
+  }
+  for (const entry of claimed.filter(({ api }) => !shared.has(api.name))) {
+    failures.set(entry.api.name, writeClaimed(run, entry));
+  }
+  return failures;
+}