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

package/src/application/transform/ref-pointer/property-shape.ts

@@ -0,0 +1,97 @@
+import type { Schema } from "../../../domain/openapi/schema-object.js";
+import { propertyAccessFlags } from "../schema/access-flags.js";
+import { isInputLocation } from "../schema/input-location.js";
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import {
+  followLocated,
+  followRefs,
+  isJsonObject,
+  type JsonObject,
+  type LocatedNode,
+} from "./located-node.js";
+
+/**
+ * What the generated type of an object schema makes of one of its properties: optional, left
+ * out, wrapped in a read or write marker, or a value that may be `undefined` or `null`.
+ */
+
+/** `nullable: true` or a `type` list with `null`: the generated type includes `null`. */
+export function isNullableSchema(node: unknown): boolean {
+  if (!isJsonObject(node)) {
+    return false;
+  }
+  return node.nullable === true || (Array.isArray(node.type) && node.type.includes("null"));
+}
+
+/**
+ * Whether the generated type has the property as optional, as `objectType` decides: a `default`
+ * makes a property required except in an input location, where the client may leave it out.
+ */
+export function isOptionalProperty(
+  owner: LocatedNode & { node: JsonObject },
+  key: string,
+  options: SchemaOptions,
+): boolean {
+  const { node } = owner;
+  const required = Array.isArray(node.required) ? node.required : undefined;
+  const property = (node.properties as JsonObject)[key];
+  const hasDefault = isJsonObject(property) && property.default !== undefined;
+  const isDefaultRequired =
+    hasDefault && options.defaultNonNullable && !isInputLocation(owner.location, options.fixes);
+  const isRequired =
+    required?.includes(key) === true ||
+    (required === undefined && options.propertiesRequiredByDefault) ||
+    isDefaultRequired;
+  return !isRequired;
+}
+
+/**
+ * Whether `--exclude-deprecated` leaves the property out: its object, or the one its `$ref`
+ * names, is deprecated (`objectType`). The key is then not in the generated type at all.
+ */
+export function isExcludedProperty(
+  property: unknown,
+  options: SchemaOptions,
+  refs: RefResolver,
+): boolean {
+  const resolved = followRefs(property, refs);
+  return options.excludeDeprecated && isJsonObject(resolved) && Boolean(resolved.deprecated);
+}
+
+/**
+ * Whether `--read-write-markers` wraps the type of a property or `$defs` member: one that is only
+ * `readOnly` or only `writeOnly` is `$Read<T>` or `$Write<T>` (object-type.ts).
+ */
+export function isMarkedProperty(value: unknown, options: SchemaOptions, refs: RefResolver) {
+  if (!options.readWriteMarkers || !isJsonObject(value)) {
+    return false;
+  }
+  const flags = propertyAccessFlags(value as Schema, { options, refs });
+  return flags.isReadOnly !== flags.isWriteOnly;
+}
+
+/** Whether a value is there: `present`, `absent` (may be `undefined` or `null`) or `unknown`. */
+export type Presence = "present" | "absent" | "unknown";
+
+/** The presence of a value of `schema` itself: `absent` when its type includes `null`. */
+export function schemaPresence(schema: unknown, refs: RefResolver): Presence {
+  return isNullableSchema(followRefs(schema, refs)) ? "absent" : "present";
+}
+
+/** The presence of property `key` of `schema`: optional or nullable is `absent`. */
+export function propertyPresence(
+  schema: LocatedNode,
+  key: string,
+  options: SchemaOptions,
+  refs: RefResolver,
+): Presence {
+  const owner = followLocated(schema, refs);
+  const { node } = owner;
+  const properties = isJsonObject(node) && isJsonObject(node.properties) ? node.properties : {};
+  if (!isJsonObject(node) || !Object.hasOwn(properties, key)) {
+    return "unknown";
+  }
+  return isOptionalProperty({ ...owner, node }, key, options)
+    ? "absent"
+    : schemaPresence(properties[key], refs);
+}

package/src/application/transform/ref-pointer/typed-walk.ts

@@ -2,25 +2,34 @@ import { irIndexedAccess, irKeyword, irReference } from "../../../domain/ir/cons
 import type { IrKeyword, IrType } from "../../../domain/ir/nodes.js";
 import { indexBy, indexKeyword, rootType } from "../ref-type.js";
 import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import { isArrayShape, isObjectShape } from "./generated-shape.js";
 import {
+  childLocation,
+  followLocated,
   followRefs,
-  isArrayShape,
   isJsonObject,
-  isObjectShape,
-  type Presence,
-  propertyPresence,
-  schemaPresence,
-} from "./generated-shape.js";
+  type LocatedNode,
+} from "./located-node.js";
 import {
+  type ContentForm,
+  headerParameterContentForm,
+  isExcludedOperation,
   isOptionalHeader,
   isOptionalRequestBody,
   isParameterList,
   isTypedAsSchema,
-  leadingNode,
+  leadingLocated,
   leadingSegmentsOf,
   type RefPointer,
   startsInSchema,
 } from "./pointer-walk.js";
+import {
+  isExcludedProperty,
+  isMarkedProperty,
+  type Presence,
+  propertyPresence,
+  schemaPresence,
+} from "./property-shape.js";
 
 /**
  * The type of a `$ref` pointer as the generated types have it: the `schema` of a media type,
@@ -36,9 +45,18 @@ export interface TypedWalk {
   readonly type: IrType;
   /** The document node the type stands for (not followed through a `$ref`). */
   readonly node: unknown;
+  /** The node's JSON Pointer, where the generator writes its type (`LocatedNode`). */
+  readonly location: string | undefined;
   readonly isSchema: boolean;
   /** The segment is a property or `$defs` name, not a keyword. */
   readonly isName: boolean;
+  /** The location of the map of names (`properties` or `$defs`) when `isName`. */
+  readonly namesLocation?: string | undefined;
+  /**
+   * The node is the `content` of a header or parameter typed as its first media type, so the
+   * next segment must name that media type and adds no member.
+   */
+  readonly isFirstMediaType?: boolean;
   readonly presence: Presence;
 }
 
@@ -58,19 +76,32 @@ function present(walk: TypedWalk): IrType {
 }
 
 function indexEntries(walk: TypedWalk, key: IrKeyword, keyword: string, refs: RefResolver) {
-  const owner = followRefs(walk.node, refs);
-  const child = isJsonObject(owner) ? owner[keyword] : undefined;
+  const owner = followLocated(walk, refs);
+  const child = isJsonObject(owner.node) ? owner.node[keyword] : undefined;
   return {
     ...walk,
     type: irIndexedAccess(present(walk), irKeyword(key)),
     node: child,
+    location: childLocation(owner.location, keyword),
     presence: schemaPresence(child, refs),
   };
 }
 
+/**
+ * A property `--exclude-deprecated` left out has no member to index, and the `$Read<T>` or
+ * `$Write<T>` of a marked property has no member but the marker's: such a pointer is typed in
+ * place.
+ */
 function nameStep(walk: TypedWalk, name: string, isLast: boolean, input: TypedWalkInput) {
-  const owner = followRefs(walk.node, input.refs);
-  const properties = isJsonObject(owner) && isJsonObject(owner.properties) ? owner.properties : {};
+  const owner = followLocated(walk, input.refs);
+  const { node } = owner;
+  const properties = isJsonObject(node) && isJsonObject(node.properties) ? node.properties : {};
+  const value = properties[name];
+  const { options, refs } = input;
+  const isMarkedOnTheWay = !isLast && isMarkedProperty(value, options, refs);
+  if (isExcludedProperty(value, options, refs) || isMarkedOnTheWay) {
+    return null;
+  }
   const type =
     walk.presence === "present"
       ? indexKeyword(walk.type, name, isLast)
@@ -78,19 +109,25 @@ function nameStep(walk: TypedWalk, name: string, isLast: boolean, input: TypedWa
   return {
     ...walk,
     type,
-    node: properties[name],
+    node: value,
+    location: childLocation(walk.namesLocation, name),
     isName: false,
-    presence: propertyPresence(walk.node, name, input.options, input.refs),
+    presence: propertyPresence(walk, name, input.options, input.refs),
   };
 }
 
 /** `$defs` is optional (`NonNullable` when more follows); its members are present. */
-function defsStep(walk: TypedWalk, owner: unknown, isLast: boolean): TypedWalk {
-  const defs = isJsonObject(owner) && isJsonObject(owner[DEFS_KEYWORD]) ? owner[DEFS_KEYWORD] : {};
+function defsStep(walk: TypedWalk, owner: LocatedNode, isLast: boolean): TypedWalk {
+  const { node } = owner;
+  const defs = isJsonObject(node) && isJsonObject(node[DEFS_KEYWORD]) ? node[DEFS_KEYWORD] : {};
+  const namesLocation = childLocation(owner.location, DEFS_KEYWORD);
   return {
     ...walk,
     type: indexKeyword(present(walk), DEFS_KEYWORD, isLast),
+    // A node of its own, not in the document: its properties are the definitions.
     node: { properties: defs, required: Object.keys(defs) },
+    location: namesLocation,
+    namesLocation,
     isName: true,
     presence: "present",
   };
@@ -115,13 +152,13 @@ function hasKeywordMember(owner: unknown, segment: string): boolean {
 }
 
 function keywordStep(walk: TypedWalk, segment: string, isLast: boolean, input: TypedWalkInput) {
-  const owner = followRefs(walk.node, input.refs);
-  if (!hasKeywordMember(owner, segment)) {
+  const owner = followLocated(walk, input.refs);
+  if (!hasKeywordMember(owner.node, segment)) {
     return null;
   }
   switch (segment) {
     case "properties":
-      return { ...walk, isName: true };
+      return { ...walk, isName: true, namesLocation: childLocation(owner.location, segment) };
     case "items":
       return indexEntries(walk, "number", "items", input.refs);
     case "additionalProperties":
@@ -143,10 +180,65 @@ function containerStep(walk: TypedWalk, index: number, input: TypedWalkInput): T
     ...walk,
     type: indexBy(present(walk), segment),
     node: isJsonObject(owner) ? owner[segment] : undefined,
+    location: childLocation(followLocated(walk, input.refs).location, segment),
     presence: isOptional ? "absent" : "present",
   };
 }
 
+/**
+ * The `content` of a header or parameter: no member of its own, since the type holds its media
+ * types (or the first one's type). Untyped where the type is `string` or a `schema`'s, and as the
+ * last segment of the first media type form, whose type is not the map's.
+ */
+function contentStep(walk: TypedWalk, form: ContentForm, isLast: boolean, refs: RefResolver) {
+  const isMapTyped = form === "media-type-members" || (form === "first-media-type" && !isLast);
+  if (!isMapTyped) {
+    return null;
+  }
+  const owner = followLocated(walk, refs);
+  return {
+    ...walk,
+    node: isJsonObject(owner.node) ? owner.node.content : undefined,
+    location: childLocation(owner.location, "content"),
+    isFirstMediaType: form === "first-media-type",
+  };
+}
+
+/** The first media type of such a `content` is the type itself; another one has no type. */
+function firstMediaTypeStep(walk: TypedWalk, segment: string): TypedWalk | null {
+  const content = isJsonObject(walk.node) ? walk.node : {};
+  if (Object.keys(content)[0] !== segment) {
+    return null;
+  }
+  const location = childLocation(walk.location, segment);
+  return { ...walk, node: content[segment], location, isFirstMediaType: false };
+}
+
+function schemaStep(walk: TypedWalk, refs: RefResolver): TypedWalk {
+  const owner = followLocated(walk, refs);
+  const schema = isJsonObject(owner.node) ? owner.node.schema : undefined;
+  const location = childLocation(owner.location, "schema");
+  // The container's type is its schema's type: an optional header stays optional.
+  const presence = walk.presence === "absent" ? "absent" : schemaPresence(schema, refs);
+  return { ...walk, node: schema, location, isSchema: true, presence };
+}
+
+function documentStep(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk | null {
+  const owner = followRefs(walk.node, input.refs);
+  const form = headerParameterContentForm(input.pointer, index, owner, input.options);
+  if (form !== null) {
+    const isLast = index === input.pointer.segments.length - 1;
+    return contentStep(walk, form, isLast, input.refs);
+  }
+  if (
+    isParameterList(input.pointer, index) ||
+    isExcludedOperation(input.pointer, index, owner, input)
+  ) {
+    return null;
+  }
+  return containerStep(walk, index, input);
+}
+
 function step(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk | null {
   const { segments } = input.pointer;
   const segment = segments[index] as string;
@@ -156,20 +248,19 @@ function step(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk
       ? nameStep(walk, segment, isLast, input)
       : keywordStep(walk, segment, isLast, input);
   }
+  if (walk.isFirstMediaType) {
+    return firstMediaTypeStep(walk, segment);
+  }
   if (segment === "schema" && isTypedAsSchema(input.pointer, index)) {
-    const owner = followRefs(walk.node, input.refs);
-    const schema = isJsonObject(owner) ? owner.schema : undefined;
-    // The container's type is its schema's type: an optional header stays optional.
-    const presence = walk.presence === "absent" ? "absent" : schemaPresence(schema, input.refs);
-    return { ...walk, node: schema, isSchema: true, presence };
+    return schemaStep(walk, input.refs);
   }
-  return isParameterList(input.pointer, index) ? null : containerStep(walk, index, input);
+  return documentStep(walk, index, input);
 }
 
 /** Walk the whole pointer; see the module comment. */
 export function typedWalk(input: TypedWalkInput): TypedWalkResult {
   const { pointer } = input;
-  const node = leadingNode(pointer, input.refs);
+  const { node, location } = leadingLocated(pointer, input.refs);
   const isSchema = startsInSchema(pointer);
   let walk: TypedWalk = {
     type: indexBy(
@@ -177,6 +268,7 @@ export function typedWalk(input: TypedWalkInput): TypedWalkResult {
       ...pointer.segments.slice(0, leadingSegmentsOf(pointer)),
     ),
     node,
+    location,
     isSchema,
     isName: false,
     presence: isSchema ? schemaPresence(node, input.refs) : "present",

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

@@ -30,7 +30,7 @@ function merged(left: AccessFlags, right: AccessFlags): AccessFlags {
  */
 function appliedFlags(
   schema: Schema | undefined,
-  context: SchemaContext,
+  context: Pick<SchemaContext, "refs">,
   seen: ReadonlySet<Schema>,
 ): AccessFlags {
   if (typeof schema !== "object" || schema === null || seen.has(schema)) {
@@ -52,7 +52,10 @@ function appliedFlags(
  * it count, as in openapi-typescript; with it, also those of the schemas its `$ref` and `allOf`
  * apply (upstream #1938).
  */
-export function propertyAccessFlags(value: Schema, context: SchemaContext): AccessFlags {
+export function propertyAccessFlags(
+  value: Schema,
+  context: Pick<SchemaContext, "options" | "refs">,
+): AccessFlags {
   if (typeof value !== "object") {
     return NO_FLAGS;
   }

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

@@ -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,6 +110,12 @@ 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,
@@ -118,8 +123,9 @@ function propertyType(
   request: SchemaRequest,
 ): CustomResult {
   const path = appendPointer(request.location.path, [key]);
-  const type = facts.ref
-    ? schemaRefType(facts.ref, request)
+  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
@@ -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/schema-transform.ts

@@ -32,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,

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/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,12 +1,10 @@
 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, type GeneratorFlags, hostList } from "./cli-arguments.js";
-import { cliError } from "./cli-errors.js";
-import { resolveLocationUrl } from "./cli-output.js";
+import { ApiFailure, cliError } from "./cli-errors.js";
 import { fixNamesOf } from "./fix-option.js";
-import type { RefLimitOptions } from "./ref-limits.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
@@ -23,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. */
@@ -127,31 +126,24 @@ export function apiFixNames(
   try {
     return fixNamesOf(entries);
   } catch (error) {
-    throw isOpenAPITypesafeError(error) ? withApiName(apiName, error) : error;
+    throw new ApiFailure(apiName, 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. */
+/**
+ * `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, settings, 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. */