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

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

@@ -23,6 +23,16 @@ export function unionType(types: readonly IrType[]): IrType {
   return types.length === 0 ? NEVER : { kind: "union", types };
 }
 
+export function intersectionType(types: readonly IrType[]): IrType {
+  return types.length === 1 ? (types[0] as IrType) : { kind: "intersection", types };
+}
+
+const NULLISH: ReadonlySet<string> = new Set(["null", "undefined"]);
+
+export function isNullish(type: IrType): boolean {
+  return type.kind === "keyword" && NULLISH.has(type.keyword);
+}
+
 export function propertyKey(name: IrPropertyName): string {
   return name.kind === "string" ? name.value : name.text;
 }

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

@@ -1,21 +1,16 @@
-import type { IrDeclaration, IrMember, IrType } from "../../../domain/ir/nodes.js";
+import type { IrDeclaration, IrType } from "../../../domain/ir/nodes.js";
 import {
   absorbed,
   type Evaluated,
   type Evaluation,
-  MISSING,
-  NEVER,
+  intersectionType,
+  isNullish,
   OPAQUE,
   propertyKey,
   unionType,
 } from "./evaluation.js";
-import {
-  declaredFirst,
-  extracted,
-  isNeverIntersection,
-  markerObject,
-  omitted,
-} from "./type-rules.js";
+import { indexType } from "./type-indexing.js";
+import { extracted, markerObject, omitted } from "./type-rules.js";
 
 /**
  * A small evaluator of the generated types, as TypeScript reads them, for the `--enum-values`
@@ -30,7 +25,6 @@ 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>();
@@ -168,127 +162,6 @@ export class TypeEvaluator {
 
   /** `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) };
+    return indexType(this, value, index);
   }
-
-  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;
 }

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

@@ -0,0 +1,152 @@
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import {
+  type Evaluated,
+  type Evaluation,
+  intersectionType,
+  isNullish,
+  MISSING,
+  NEVER,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+import { declaredFirst, isNeverIntersection, type TypeExpansion } from "./type-rules.js";
+
+/**
+ * Indexed access (`T["key"]`, `T[number]`) on the generated types, as TypeScript reads it, for
+ * the evaluator of the `--enum-values` check (ADR-027).
+ */
+
+/** The part of the evaluator that indexed access uses. */
+export interface IndexedTypes extends TypeExpansion {
+  expand(value: Evaluated): Evaluation;
+  index(value: Evaluated, index: IrType): Evaluation;
+}
+
+/** `value[index]` for a string literal, `string` or `number` index. */
+export function indexType(types: IndexedTypes, value: Evaluated, index: IrType): Evaluation {
+  const owner = types.expand(value);
+  if (owner.kind !== "type") {
+    return owner;
+  }
+  if (types.membersOf(owner).length > 1) {
+    return unionIndex(types, owner, index);
+  }
+  const { type } = owner;
+  switch (type.kind) {
+    case "object":
+      return memberType(types, owner, type.members, index);
+    case "intersection":
+      return partsIndex(types, owner, type.types, index);
+    case "union":
+      return unionIndex(types, owner, index);
+    case "array":
+      return isNumberIndex(index) ? flattened(types, owner, type.element) : builtInIndex(index);
+    case "keyword":
+      return type.keyword === "never" ? owner : builtInIndex(index);
+    default:
+      return builtInIndex(index);
+  }
+}
+
+function memberType(
+  types: IndexedTypes,
+  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 flattened(types, owner, property.type);
+  }
+  const signature = members.find((member) => member.kind === "indexSignature");
+  if (signature !== undefined) {
+    return flattened(types, owner, signature.type);
+  }
+  return key === null || isObjectBuiltIn(key) ? OPAQUE : MISSING;
+}
+
+function partsIndex(
+  types: IndexedTypes,
+  owner: Evaluated,
+  parts: readonly IrType[],
+  index: IrType,
+): Evaluation {
+  if (isNeverIntersection(types, owner, parts)) {
+    return { ...owner, type: NEVER };
+  }
+  const found = parts.map((type) => types.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 kept = declaredFirst(types, owner, indexKey(index), read).flatMap((part) =>
+    part.kind === "type" ? [part.type] : [],
+  );
+  return kept.length === 0 ? MISSING : { ...owner, type: intersectionType(kept) };
+}
+
+function unionIndex(types: IndexedTypes, owner: Evaluated, index: IrType): Evaluation {
+  const found = types
+    .membersOf(owner)
+    .map((member) => (member.kind === "type" ? types.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`.
+ */
+function flattened(types: IndexedTypes, owner: Evaluated, type: IrType): Evaluation {
+  const member: Evaluated = { ...owner, type };
+  if (!owner.deep) {
+    return types.expand(member);
+  }
+  const members = types.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 types.expand({ ...owner, type: unionType(elements as IrType[]) });
+  }
+  return { ...owner, type: unionType(present.map((candidate) => candidate.type)) };
+}
+
+/** The element of an expanded member; expanding already dropped `readonly`. */
+function arrayElement(type: IrType): IrType | null {
+  return type.kind === "array" ? type.element : null;
+}
+
+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;
+}

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

@@ -1,6 +1,6 @@
 import { irReference } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { InvalidRefError, refType } from "../ref-type.js";
 import type { SchemaRequest } from "../schema/schema-rule.js";
 import { generatedLocationOf } from "./generated-location.js";
@@ -62,9 +62,7 @@ function correctedType(
 
 function isCorrected(pointer: RefPointer, request: SchemaRequest): boolean {
   const { options, refs } = request.context;
-  return (
-    options.fixes.has(OutputFix.REF_POINTERS) || originalIndexFails({ pointer, options, refs })
-  );
+  return options.fixes.has(FIX.REF_POINTERS) || originalIndexFails({ pointer, options, refs });
 }
 
 /** The type of a schema `$ref`. Throws InvalidRefError when the `$ref` has no pointer. */

package/src/application/transform/schema/access-flags.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 { SchemaContext } from "./schema-context.js";
 
 /** Whether a property is `readOnly` or `writeOnly` (JSON Schema 2020-12 Validation §9.4). */
@@ -56,7 +56,7 @@ export function propertyAccessFlags(value: Schema, context: SchemaContext): Acce
   if (typeof value !== "object") {
     return NO_FLAGS;
   }
-  if (!context.options.fixes.has(OutputFix.READ_WRITE_REFS)) {
+  if (!context.options.fixes.has(FIX.READ_WRITE_REFS)) {
     return ownFlags(value as SchemaObject);
   }
   return appliedFlags(value, context, new Set());

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

@@ -2,7 +2,7 @@ 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 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 {
@@ -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

@@ -8,7 +8,7 @@ import {
 import type { IrType } from "../../../domain/ir/nodes.js";
 import { createRef, parseRefPointer } 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 +55,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 +147,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 +173,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;
 }

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/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/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,5 @@
 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 +44,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 {

package/src/cli/api-settings.ts

@@ -0,0 +1,109 @@
+import { kebabCase } from "scule";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import { GENERATOR_FLAGS, hostList } from "./cli-arguments.js";
+import { cliError } from "./cli-errors.js";
+import { resolveLocationUrl } from "./cli-output.js";
+import type { RefLimitOptions } from "./ref-limits.js";
+
+/**
+ * The settings of one API in `redocly.yaml` (`apis.<name>.x-openapi-ts`). A setting has the name
+ * of its CLI flag, in kebab-case or camelCase (ADR-021, decision 1); a setting the CLI does not
+ * read gets a warning, as an unknown flag gets a notice.
+ */
+
+export type ApiSettings = Readonly<Record<string, unknown>>;
+
+/** The setting that names the output file. */
+export const OUTPUT_SETTING = "output";
+
+/** The setting that lists the API's output fixes. */
+export const FIX_SETTING = "fix";
+
+const LOCAL_REF_ROOT_SETTING = "localRefRoot";
+const REMOTE_REF_HOSTS_SETTING = "remoteRefHosts";
+
+/** `--content-never` is accepted and has no effect, as on the command line. */
+const IGNORED_SETTINGS = ["contentNever"] as const;
+
+const CAMEL_CASE_SETTINGS = [
+  OUTPUT_SETTING,
+  FIX_SETTING,
+  LOCAL_REF_ROOT_SETTING,
+  REMOTE_REF_HOSTS_SETTING,
+  ...GENERATOR_FLAGS,
+  ...IGNORED_SETTINGS,
+];
+
+const KNOWN_SETTINGS = new Set<string>([
+  ...CAMEL_CASE_SETTINGS,
+  ...CAMEL_CASE_SETTINGS.map((name) => kebabCase(name)),
+]);
+
+/** The warning for each setting of an API that no code reads. */
+export function unknownSettingWarnings(apiName: string, settings: ApiSettings): string[] {
+  return Object.keys(settings)
+    .filter((key) => !KNOWN_SETTINGS.has(key))
+    .map((key) =>
+      warningText(
+        `API ${apiName}: the setting \`${key}\` is not an openapi-typesafe option and is ignored`,
+        WARNING_CODES.CONFIG_SETTING_UNKNOWN,
+      ),
+    );
+}
+
+/** 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)];
+}
+
+function hasSetting(settings: ApiSettings, name: string): boolean {
+  return name in settings || kebabCase(name) in settings;
+}
+
+function invalidSetting(apiName: string, name: string, expected: string): Error {
+  return cliError(
+    "CLI_CONFIG_INVALID",
+    `API ${apiName}: \`${kebabCase(name)}\` in x-openapi-ts must be ${expected}`,
+  );
+}
+
+/** `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)) {
+    return {};
+  }
+  const value = settingValue(settings, LOCAL_REF_ROOT_SETTING) ?? "";
+  if (typeof value !== "string") {
+    throw invalidSetting(apiName, LOCAL_REF_ROOT_SETTING, "a directory path");
+  }
+  return { localRefRoot: resolveLocationUrl(value === "" ? "." : value, configRoot) };
+}
+
+/** `remote-ref-hosts: [a, b]` or `a,b`; an empty list or value allows no host. */
+function remoteRefHostsOf(apiName: string, settings: ApiSettings): RefLimitOptions {
+  if (!hasSetting(settings, REMOTE_REF_HOSTS_SETTING)) {
+    return {};
+  }
+  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");
+  }
+  return { remoteRefHosts: hostList(entries) ?? [] };
+}
+
+/**
+ * The `$ref` limits an API sets (threat model R1, R2). Each one replaces the CLI flag of the same
+ * name for this API, as its boolean settings and `fix` do; fails with `CLI_CONFIG_INVALID` for a
+ * value of another type.
+ */
+export function apiRefLimitOptions(
+  apiName: string,
+  settings: ApiSettings,
+  configRoot: URL,
+): RefLimitOptions {
+  return {
+    ...localRefRootOf(apiName, settings, configRoot),
+    ...remoteRefHostsOf(apiName, settings),
+  };
+}

package/src/cli/cli-arguments.ts

@@ -122,8 +122,11 @@ function lastString(value: unknown): string | undefined {
   return optionalString(Array.isArray(value) ? value.at(-1) : value);
 }
 
-/** `--remote-ref-hosts a.example,b.example`, repeatable; an empty value allows no host. */
-function hostList(value: unknown): string[] | undefined {
+/**
+ * `--remote-ref-hosts a.example,b.example`, repeatable; an empty value allows no host. The
+ * `remote-ref-hosts` setting of a `redocly.yaml` API is read the same way.
+ */
+export function hostList(value: unknown): string[] | undefined {
   if (value === undefined) {
     return undefined;
   }