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

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/index-signature-type.ts

@@ -0,0 +1,31 @@
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { NO_DECLARED_TYPES } from "../document/declared-types.js";
+import { assignabilityProof } from "../document/type-assignability.js";
+import { unionOf } from "../type-combinators.js";
+
+/**
+ * The index signature type with the property types it does not admit. TypeScript checks an index
+ * signature against every key of a value, declared ones too, so `{ total: number } & { [key:
+ * string]: string }` admits no value with `total` (with a required `total`, none at all). The
+ * signature takes those property types too, as `unevaluated-properties` does. A property type
+ * proven assignable adds nothing, so output that admitted its values stays; one the proof cannot
+ * decide (a `$ref`) is added, member by member, so the union stays flat. `$defs` is a keyword, not
+ * data, so it is not read.
+ */
+export function withPropertyTypes(indexType: IrType, propertyTypes: readonly IrType[]): IrType {
+  const relate = assignabilityProof(NO_DECLARED_TYPES);
+  const members = unionMembers(indexType);
+  const added: IrType[] = [];
+  // Each member of a property type joins the union on its own, unless the union admits it
+  // already: `(string | null) | (string | null)` is written `string | null`.
+  for (const member of propertyTypes.flatMap(unionMembers)) {
+    if (relate(member, unionOf([...members, ...added])) !== "assignable") {
+      added.push(member);
+    }
+  }
+  // Without an added member the index type stays as printed before, repeats and all.
+  return added.length === 0 ? indexType : unionOf([...members, ...added]);
+}
+
+const unionMembers = (type: IrType): readonly IrType[] =>
+  type.kind === "union" ? type.types : [type];

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

@@ -0,0 +1,35 @@
+import { placeOf } from "../../../domain/openapi/document-places.js";
+import { parseRefPointer } from "../../../domain/openapi/json-pointer.js";
+import { FIX, type OutputFix } from "../../../domain/output-fixes.js";
+
+/** The words that mark an input anywhere in a location, as the original reads them. */
+const ORIGINAL_INPUT_WORDS = ["parameters", "requestBody", "requestBodies"] as const;
+
+/**
+ * Whether a schema location describes an input: a parameter or a request body. A client may
+ * leave out an input property that has a `default`, so the default makes no such property
+ * required. The original tests the location text for a word, so a schema or path that is only
+ * named so (`#/components/schemas/Job/properties/parameters`, `/system-parameters`) counts as an
+ * input too. The `default-input-locations` fix reads a pointer into the document by the
+ * document's structure instead (ADR-021).
+ */
+export function isInputLocation(path: string | undefined, fixes: ReadonlySet<OutputFix>): boolean {
+  if (path === undefined) {
+    return false;
+  }
+  return fixes.has(FIX.DEFAULT_INPUT_LOCATIONS) ? isStructuralInput(path) : namesInput(path);
+}
+
+function namesInput(path: string): boolean {
+  return ORIGINAL_INPUT_WORDS.some((word) => path.includes(word));
+}
+
+/**
+ * Whether the document's structure makes the pointer an input. A path an exported transformer was
+ * given that is no pointer into the document (`/items/{id}`) has no known structure, so the
+ * original's words still mark an input there.
+ */
+function isStructuralInput(path: string): boolean {
+  const place = placeOf(parseRefPointer(path));
+  return place === "outside" ? namesInput(path) : place === "input";
+}

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";
@@ -15,13 +15,13 @@ import { schemaCommentOptionsOf, withSchemaComment } from "../schema-comment.js"
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { intersectionOf, unionOf } from "../type-combinators.js";
 import { type AccessFlags, propertyAccessFlags } from "./access-flags.js";
+import { withPropertyTypes } from "./index-signature-type.js";
 import { discriminatorMember, inheritedDiscriminator } from "./inherited-discriminator.js";
+import { isInputLocation } from "./input-location.js";
+import { refWithSiblingsAsAllOf } from "./ref-siblings.js";
 import type { SchemaOptions } from "./schema-context.js";
 import type { SchemaRequest } from "./schema-rule.js";
 
-/** Path parts where a default value cannot make a property required (inputs may omit it). */
-const INPUT_PATH_PARTS = ["parameters", "requestBody", "requestBodies"] as const;
-
 export class InvalidPropertyError extends OpenAPITypesafeError {
   constructor(path: string | undefined, key: string, value: unknown) {
     const received = Array.isArray(value) ? "Array" : typeof value;
@@ -85,11 +85,10 @@ function isOptionalProperty(
   request: SchemaRequest,
 ): boolean {
   const { options } = request.context;
-  const path = request.location.path;
   const isDefaultRequired =
     facts.hasDefault &&
     options.defaultNonNullable &&
-    !INPUT_PATH_PARTS.some((part) => path?.includes(part));
+    !isInputLocation(request.location.path, options.fixes);
   const isRequired =
     schema.required?.includes(key) ||
     (schema.required === undefined && options.propertiesRequiredByDefault) ||
@@ -111,15 +110,22 @@ interface CustomResult {
   readonly isOptional: true | null;
 }
 
+/** A `$ref` with siblings that `ref-siblings` types as an `allOf` is typed as a schema. */
+function plainRef({ ref }: PropertyFacts, value: Schema, request: SchemaRequest) {
+  const isAllOf = ref && refWithSiblingsAsAllOf(value as SchemaObject, request.context.options);
+  return isAllOf ? undefined : ref;
+}
+
 function propertyType(
   key: string,
   value: Schema,
   facts: PropertyFacts,
   request: SchemaRequest,
 ): CustomResult {
-  const path = createRef([request.location.path, key]);
-  const type = facts.ref
-    ? schemaRefType(facts.ref, request)
+  const path = appendPointer(request.location.path, [key]);
+  const ref = plainRef(facts, value, request);
+  const type = ref
+    ? schemaRefType(ref, request)
     : request.transformNested(value, { ...request.location, path });
   const custom = request.context.callbacks.transform(value, request.location);
   return custom === null
@@ -151,7 +157,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 +182,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 }),
@@ -270,6 +276,9 @@ export function objectType(schema: SchemaObject, request: SchemaRequest): IrType
     return inherited ? irObject([discriminatorMember(inherited, request)]) : null;
   }
   const members = discriminatorAndPropertyMembers(schema, request);
+  const propertyTypes = members.flatMap((member) =>
+    member.kind === "property" ? [member.type] : [],
+  );
   // As in the original, a null `$defs` throws here (Object.keys) instead of being skipped.
   if (
     "$defs" in schema &&
@@ -282,8 +291,9 @@ export function objectType(schema: SchemaObject, request: SchemaRequest): IrType
   if (valueTypes.length === 0) {
     return members.length > 0 ? irObject(members) : null;
   }
+  const indexType = withPropertyTypes(unionOf(valueTypes), propertyTypes);
   const index = irObject([
-    irStringIndexSignature("key", unionOf(valueTypes), request.context.options.immutable),
+    irStringIndexSignature("key", indexType, request.context.options.immutable),
   ]);
   return intersectionOf([...(members.length > 0 ? [irObject(members)] : []), index]);
 }

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";
 
@@ -31,7 +32,8 @@ const SHAPE_RULES: readonly SchemaRule[] = [
   },
   {
     name: "const",
-    matches: (schema) => schema.const !== null && schema.const !== undefined,
+    // `const: null` is the value null (JSON Schema §6.1.3); the original read it as no `const`.
+    matches: (schema) => schema.const !== undefined,
     transform: (schema) => literalType(schema.const),
   },
   enumRule,
@@ -83,8 +85,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

@@ -1,13 +1,8 @@
-import {
-  irKeyword,
-  irObject,
-  irReference,
-  irStringIndexSignature,
-} from "../../../domain/ir/constructors.js";
-import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import { irObject, irStringIndexSignature } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { FIX } from "../../../domain/output-fixes.js";
-import { HELPER_TYPES } from "../helper-types.js";
+import { declaredValueTypes } from "../declared-value-types.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { unionOf } from "../type-combinators.js";
 import type { SchemaRequest } from "./schema-rule.js";
@@ -46,41 +41,6 @@ function isAnySchema(schema: Schema): boolean {
   return schema === true || (typeof schema === "object" && Object.keys(schema).length === 0);
 }
 
-function memberValueTypes(member: IrMember): IrType[] {
-  if (member.kind === "indexSignature") {
-    return [member.type];
-  }
-  return member.isOptional ? [member.type, irKeyword("undefined")] : [member.type];
-}
-
-/**
- * The value types a key of the composed type can have, read from its IR: the members of object
- * types, through unions and intersections. A reference (a `$ref`, `Omit`, `WithRequired`) or a raw
- * type is read with `PropertyValues`. Primitives, literals and arrays declare no keys.
- */
-function declaredValueTypes(type: IrType, request: SchemaRequest): IrType[] {
-  switch (type.kind) {
-    case "object":
-      return type.members.flatMap(memberValueTypes);
-    case "union":
-    case "intersection":
-      return type.types.flatMap((member) => declaredValueTypes(member, request));
-    case "reference":
-    case "indexedAccess":
-    case "raw":
-      request.context.footer.requirePropertyValues();
-      return [irReference(HELPER_TYPES.propertyValues.name, [type])];
-    case "keyword":
-    case "stringLiteral":
-    case "numberLiteral":
-    case "booleanLiteral":
-    case "array":
-    case "tuple":
-    case "readonly":
-      return [];
-  }
-}
-
 /**
  * The index signature object for `unevaluatedProperties`, given the composed type of the other
  * keywords (null when there is none). Null when the fix is off or the keyword does not apply.
@@ -98,7 +58,7 @@ export function unevaluatedPropertiesType(
     ? [UNKNOWN_TYPE]
     : [
         request.transformNested(unevaluated, request.location, true),
-        ...(composed === null ? [] : declaredValueTypes(composed, request)),
+        ...(composed === null ? [] : declaredValueTypes(composed, request.context.footer)),
       ];
   const { immutable } = request.context.options;
   return irObject([irStringIndexSignature("key", unionOf(valueTypes), immutable)]);

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-logger.ts

@@ -0,0 +1,17 @@
+import type { DebugGroup, Logger } from "../application/ports/logger.js";
+
+/**
+ * A logger whose lines name the API they are about. With several APIs in `redocly.yaml`, each is
+ * loaded and linted in turn, and a problem line such as "Can't resolve $ref" is the same for
+ * each, so without the name the user cannot tell which API it belongs to. The summary of a
+ * failed API names it the same way (`API a: …`).
+ */
+export function apiLogger(logger: Logger, apiName: string): Logger {
+  const prefix = `API ${apiName}: `;
+  return {
+    debug: (message: string, group?: DebugGroup, durationMs?: number) =>
+      logger.debug(`${prefix}${message}`, group, durationMs),
+    warn: (message: string) => logger.warn(`${prefix}${message}`),
+    error: (message: string) => logger.error(`${prefix}${message}`),
+  };
+}

package/src/cli/api-settings.ts

@@ -1,9 +1,10 @@
 import { kebabCase } from "scule";
+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 { cliError } from "./cli-errors.js";
-import { resolveLocationUrl } from "./cli-output.js";
-import type { RefLimitOptions } from "./ref-limits.js";
+import { GENERATOR_FLAGS, type GeneratorFlags, hostList } from "./cli-arguments.js";
+import { ApiFailure, cliError } from "./cli-errors.js";
+import { fixNamesOf } from "./fix-option.js";
+import { localRootUrl, type RefLimitOptions } from "./ref-limits.js";
 
 /**
  * The settings of one API in `redocly.yaml` (`apis.<name>.x-openapi-ts`). A setting has the name
@@ -20,6 +21,7 @@ export const OUTPUT_SETTING = "output";
 export const FIX_SETTING = "fix";
 
 const LOCAL_REF_ROOT_SETTING = "localRefRoot";
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
 const REMOTE_REF_HOSTS_SETTING = "remoteRefHosts";
 
 /** `--content-never` is accepted and has no effect, as on the command line. */
@@ -51,32 +53,97 @@ 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}`,
   );
 }
 
-/** `local-ref-root: dir`, relative to the config file; empty means the config file's directory. */
+/**
+ * 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 new ApiFailure(apiName, error);
+  }
+}
+
+/**
+ * `local-ref-root: dir`, relative to the config file; empty means the config file's directory. A
+ * value that is no text or a URL of another protocol fails with `CLI_CONFIG_INVALID`.
+ */
 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");
+  const localRoot = typeof value === "string" ? localRootUrl(value, configRoot) : undefined;
+  if (localRoot === undefined) {
+    throw invalidSetting(apiName, settings, LOCAL_REF_ROOT_SETTING, LOCAL_ROOT_EXPECTED);
   }
-  return { localRefRoot: resolveLocationUrl(value === "" ? "." : value, configRoot) };
+  return { localRefRoot: localRoot };
 }
 
 /** `remote-ref-hosts: [a, b]` or `a,b`; an empty list or value allows no host. */
@@ -87,7 +154,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) ?? [] };
 }