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

package/src/api/openapi-ts.ts

@@ -2,7 +2,7 @@ import { createRedoclySchemaLoader } from "../adapters/redocly-loader/redocly-sc
 import type { Logger } from "../application/ports/logger.js";
 import { withStackOverflowReported } from "../application/stack-overflow.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
-import type { GeneratorOptions, SchemaSource } from "../types.js";
+import type { GeneratorOptions, OpenAPITSOptions, SchemaSource } from "../types.js";
 import {
   DEFAULT_REMOTE_DOCUMENT_LIMITS,
   defaultDeprecationReporter,
@@ -78,6 +78,19 @@ export async function defaultGeneratorPorts(
  *   - URL: URL to a YAML or JSON file (local or remote)
  *   - Readable: Readable stream of YAML or JSON
  */
+export default function openapiTS(
+  source: SchemaSource,
+  options?: OpenAPITSOptions,
+): Promise<IrDeclaration[]>;
+// The options without `irCallbacks` get their own signature: TypeScript does not pick a member of
+// `GeneratorOptions | undefined` (an optional parameter) by a key that the object leaves out, so
+// inline callbacks had implicit `any` parameters (TS7006). `irCallbacks: true` picks the member
+// here. This signature is last, so `Parameters<typeof openapiTS>` reads it.
+/** Convert an OpenAPI schema to IR declarations, with either form of the options. */
+export default function openapiTS(
+  source: SchemaSource,
+  options?: GeneratorOptions,
+): Promise<IrDeclaration[]>;
 export default async function openapiTS(
   source: SchemaSource,
   options: GeneratorOptions = {},

package/src/api/option-errors.ts

@@ -0,0 +1,22 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+
+/** The `OPTION_INVALID` errors of the Node API's options, checked before anything loads. */
+
+/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */
+export function kindOf(value: unknown): string {
+  if (value instanceof URL) {
+    return `a ${value.protocol} URL`;
+  }
+  if (Array.isArray(value)) {
+    return "a list";
+  }
+  return value === null ? "null" : `a ${typeof value}`;
+}
+
+export function optionInvalid(option: string, expected: string, got: string): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.OPTION_INVALID,
+    message: `The ${option} option must be ${expected}; got ${got}.`,
+    details: { option },
+  });
+}

package/src/api/ref-limit-options.ts

@@ -1,9 +1,9 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import type { RefAccess } from "../application/ports/schema-loader.js";
-import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
 import { hasUrlScheme } from "../domain/location-text.js";
 import type { GeneratorOptions } from "../types.js";
+import { kindOf, optionInvalid } from "./option-errors.js";
 
 /**
  * The `$ref` limits of the options (threat model R1, R2, ADR-017), checked before anything loads.
@@ -13,36 +13,29 @@ import type { GeneratorOptions } from "../types.js";
 
 const FILE_PROTOCOL = "file:";
 
-/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */
-function kindOf(value: unknown): string {
-  if (value instanceof URL) {
-    return `a ${value.protocol} URL`;
-  }
-  if (Array.isArray(value)) {
-    return "a list";
-  }
-  return value === null ? "null" : `a ${typeof value}`;
-}
-
-function optionInvalid(option: string, expected: string, got: string): OpenAPITypesafeError {
-  return new OpenAPITypesafeError({
-    code: ERROR_CODES.OPTION_INVALID,
-    message: `The ${option} option must be ${expected}; got ${got}.`,
-    details: { option },
-  });
-}
-
 const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
+const RELATIVE_ROOT_EXPECTED = "an absolute path or a file: URL when cwd is no file: URL";
 
 /**
  * A string as the CLI reads `--local-ref-root`: a URL when it has a scheme (`file:///specs/`),
- * else a path that resolves against the cwd. Undefined when it does not parse as a URL.
+ * else a path that resolves against the cwd. Undefined when it does not parse as a URL. A
+ * relative path needs a local cwd: with an `http:` cwd it names no local directory.
  */
 function localRootUrlOf(value: string, cwd: URL): URL | undefined {
-  if (!hasUrlScheme(value)) {
-    return pathToFileURL(path.resolve(fileURLToPath(cwd), value));
+  if (hasUrlScheme(value)) {
+    return URL.parse(value, cwd.href) ?? undefined;
+  }
+  if (path.isAbsolute(value)) {
+    return pathToFileURL(value);
+  }
+  if (cwd.protocol !== FILE_PROTOCOL) {
+    throw optionInvalid(
+      "localRefRoot",
+      RELATIVE_ROOT_EXPECTED,
+      `a relative path, and cwd is ${kindOf(cwd)}`,
+    );
   }
-  return URL.parse(value, cwd.href) ?? undefined;
+  return pathToFileURL(path.resolve(fileURLToPath(cwd), value));
 }
 
 /** The local root as a `file:` URL; the option is set, so it is not undefined. */

package/src/application/ports/redocly-config-source.ts

@@ -17,4 +17,9 @@ export interface RedoclyConfigSource {
    * when the ignore file of the working directory is bad.
    */
   createDefault(): Promise<RedoclyConfig>;
+  /**
+   * The config one API of `config` is linted with: the API's own `rules` (and other lint
+   * settings) under `apis.<name>` in place of the root's, as `redocly lint <name>` reads them.
+   */
+  forApi(config: RedoclyConfig, apiName: string): RedoclyConfig;
 }

package/src/application/transform/document/path-template-refs.ts

@@ -2,6 +2,7 @@ import { irRaw } from "../../../domain/ir/constructors.js";
 import type { IrDeclaration } from "../../../domain/ir/nodes.js";
 import type { PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { documentEntries } from "../document-entries.js";
+import { HELPER_TYPES } from "../helper-types.js";
 import type { TransformContext } from "../transform-context.js";
 import type { PathKeyPart } from "./path-key-overlaps.js";
 import { booleanExpandedKeys, pathTemplateParts, templateText } from "./path-template-key.js";
@@ -11,7 +12,8 @@ import { isUntakenKey, pathKeyOf } from "./paths.js";
  * `--path-params-as-types` and `$ref`s into a templated path. Such a path is an index signature
  * of `paths` (`` [path: `/pets/${number}`] ``), so `paths["/pets/{id}"]`, the type of a `$ref`
  * to it, names no key: `{id}` is no number (TS2339). The reference indexes `paths` by the
- * template instead, which reaches the signature. With only `${string}` placeholders the URL
+ * template instead, which reaches the signature; so does the type of an `--enum-values` array,
+ * which indexes `FlattenedDeepRequired<paths>`. With only `${string}` placeholders the URL
  * itself matches the template and the output compiles, so it stays as it is.
  */
 
@@ -64,16 +66,35 @@ function isNode(value: unknown): value is Readonly<Record<string, unknown>> {
   return typeof value === "object" && value !== null;
 }
 
+function isBarePathsReference(node: unknown): boolean {
+  const reference = node as Readonly<Record<string, unknown>> | undefined;
+  return (
+    reference?.kind === "reference" &&
+    reference.name === PATHS_TYPE_NAME &&
+    (reference.typeArguments as readonly unknown[] | undefined)?.length === 0
+  );
+}
+
+/**
+ * The `paths` root as a `$ref` or an `--enum-values` array indexes it: `paths`, or
+ * `FlattenedDeepRequired<paths>` (`rootType`), whose mapped keys are those of `paths`.
+ */
+function isPathsRoot(node: unknown): boolean {
+  const reference = node as Readonly<Record<string, unknown>> | undefined;
+  const typeArguments = reference?.typeArguments as readonly unknown[] | undefined;
+  const isDeepRoot =
+    reference?.kind === "reference" &&
+    reference.name === HELPER_TYPES.flattenedDeepRequired.name &&
+    typeArguments?.length === 1 &&
+    isBarePathsReference(typeArguments[0]);
+  return isDeepRoot || isBarePathsReference(node);
+}
+
 /** `paths["<url>"]`: an index of the `paths` root by a string literal. */
 function pathsIndexUrl(node: Readonly<Record<string, unknown>>): string | undefined {
-  const object = node.object as Readonly<Record<string, unknown>> | undefined;
   const index = node.index as Readonly<Record<string, unknown>> | undefined;
   const isPathsIndex =
-    node.kind === "indexedAccess" &&
-    object?.kind === "reference" &&
-    object.name === PATHS_TYPE_NAME &&
-    (object.typeArguments as readonly unknown[] | undefined)?.length === 0 &&
-    index?.kind === "stringLiteral";
+    node.kind === "indexedAccess" && isPathsRoot(node.object) && index?.kind === "stringLiteral";
   return isPathsIndex ? (index.value as string) : undefined;
 }
 

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

@@ -8,6 +8,7 @@ import {
   type LocatedNode,
 } from "./located-node.js";
 import {
+  hasKeptProperties,
   isExcludedProperty,
   isMarkedProperty,
   isNullableSchema,
@@ -29,8 +30,16 @@ export type GeneratedMember =
       /** `$Read<T>` or `$Write<T>` (`isMarkedProperty`): no member but the marker's own. */
       readonly isMarked: boolean;
     }
-  /** An index signature; `node` is undefined when its value type is `unknown`. */
-  | { readonly kind: "index"; readonly node: unknown; readonly location: string | undefined }
+  /**
+   * An index signature; `node` is undefined when its value type is `unknown`. `isOtherType`: the
+   * type read is not the type of the node the key names (`indexMember`).
+   */
+  | {
+      readonly kind: "index";
+      readonly node: unknown;
+      readonly location: string | undefined;
+      readonly isOtherType: boolean;
+    }
   | { readonly kind: "missing" }
   | { readonly kind: "opaque" };
 
@@ -91,19 +100,51 @@ function isBuiltInMember(key: string, prototype: object): boolean {
   return key in prototype;
 }
 
-function indexMember(owner: LocatedNode & { node: JsonObject }, options: SchemaOptions) {
+/** `additionalProperties: true` or `{}` (also as a pattern's schema): a value of `unknown`. */
+function isUnknownValue(value: unknown): boolean {
+  return value === true || (isJsonObject(value) && Object.keys(value).length === 0);
+}
+
+/** The value schemas of an index signature none of whose values is `unknown`, located. */
+function typedIndexValues(owner: LocatedNode & { node: JsonObject }): LocatedNode[] {
   const { additionalProperties: values, patternProperties: patterns } = owner.node;
-  if (isJsonObject(patterns) && Object.keys(patterns).length > 0) {
-    return OPAQUE;
+  const located: LocatedNode[] = [];
+  if (isJsonObject(values)) {
+    located.push({ node: values, location: childLocation(owner.location, "additionalProperties") });
   }
-  if (isJsonObject(values) && Object.keys(values).length > 0) {
-    const location = childLocation(owner.location, "additionalProperties");
-    return { kind: "index", node: values, location } satisfies GeneratedMember;
+  for (const [pattern, node] of isJsonObject(patterns) ? Object.entries(patterns) : []) {
+    located.push({ node, location: childLocation(owner.location, "patternProperties", pattern) });
+  }
+  return located;
+}
+
+/**
+ * The index signature of an object schema, or null without one. Its type is the union of its
+ * value schemas' types (`unknown` if one is `unknown`); a union of several counts as opaque. It
+ * also holds the kept property types (`withPropertyTypes`), and a key that names a property
+ * `--exclude-deprecated` left out reads it instead of that property: both are `isOtherType`.
+ */
+function indexMember(
+  owner: LocatedNode & { node: JsonObject },
+  isExcludedKey: boolean,
+  input: MemberInput,
+): GeneratedMember | null {
+  const { additionalProperties: values, patternProperties: patterns } = owner.node;
+  const patternValues = isJsonObject(patterns) ? Object.values(patterns) : [];
+  const isUnknown =
+    isUnknownValue(values) ||
+    patternValues.some(isUnknownValue) ||
+    (!values && input.options.additionalProperties);
+  if (isUnknown) {
+    return { kind: "index", node: undefined, location: undefined, isOtherType: isExcludedKey };
+  }
+  const typed = typedIndexValues(owner);
+  const [only] = typed;
+  if (only === undefined || typed.length > 1) {
+    return only === undefined ? null : OPAQUE;
   }
-  const isImplicit = values === true || (isJsonObject(values) && Object.keys(values).length === 0);
-  return isImplicit || (!values && options.additionalProperties)
-    ? ({ kind: "index", node: undefined, location: undefined } satisfies GeneratedMember)
-    : null;
+  const isOtherType = isExcludedKey || hasKeptProperties(owner.node, input.options, input.refs);
+  return { kind: "index", ...only, isOtherType };
 }
 
 function objectMember(
@@ -114,7 +155,9 @@ function objectMember(
   const { options } = input;
   const { node } = owner;
   const properties = isJsonObject(node.properties) ? node.properties : {};
-  if (Object.hasOwn(properties, key) && !isExcludedProperty(properties[key], options, input.refs)) {
+  const isExcludedKey =
+    Object.hasOwn(properties, key) && isExcludedProperty(properties[key], options, input.refs);
+  if (Object.hasOwn(properties, key) && !isExcludedKey) {
     if (isJsonObject(node.discriminator)) {
       return OPAQUE;
     }
@@ -130,7 +173,7 @@ function objectMember(
     return OPAQUE;
   }
   return hasObjectKeywords(node)
-    ? (indexMember(owner, options) ?? MISSING)
+    ? (indexMember(owner, isExcludedKey, input) ?? MISSING)
     : emptyObjectMember(node, options);
 }
 

package/src/application/transform/ref-pointer/original-index.ts

@@ -18,8 +18,10 @@ import {
 /**
  * Whether the type the original wrote for a `$ref` (`refType`: every segment indexed by name,
  * `properties` skipped) surely fails to compile. It walks the document as TypeScript walks the
- * generated types and answers true only where TypeScript reports an error for sure; where the
- * answer depends on a shape it does not model, it answers false, so that output stays as it was.
+ * generated types and answers true only where TypeScript reports an error for sure, or where the
+ * type compiles but is read through an index signature that is not the target's type alone
+ * (`isOtherType`); where the answer depends on a shape it does not model, it answers false, so
+ * that output stays as it was.
  */
 
 type Step = "fails" | "compiles" | "continue";
@@ -42,7 +44,8 @@ function schemaStep(walk: OriginalWalk, segment: string, isLast: boolean, input:
     return { step: "continue" as Step, walk };
   }
   const member = generatedMember(walk, segment, input.options, input.refs);
-  if (member.kind === "missing") {
+  // Such an index signature compiles, but its type is not the target's alone.
+  if (member.kind === "missing" || (member.kind === "index" && member.isOtherType)) {
     return { step: "fails" as Step, walk };
   }
   if (member.kind === "opaque") {

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

@@ -58,6 +58,15 @@ export function isExcludedProperty(
   return options.excludeDeprecated && isJsonObject(resolved) && Boolean(resolved.deprecated);
 }
 
+/**
+ * Whether the generated type keeps one of the schema's properties. The index signature next to
+ * them then holds their types too (`withPropertyTypes`), so it is not its value schema's type.
+ */
+export function hasKeptProperties(node: JsonObject, options: SchemaOptions, refs: RefResolver) {
+  const properties = isJsonObject(node.properties) ? node.properties : {};
+  return Object.values(properties).some((value) => !isExcludedProperty(value, options, refs));
+}
+
 /**
  * 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).

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

@@ -24,6 +24,7 @@ import {
   startsInSchema,
 } from "./pointer-walk.js";
 import {
+  hasKeptProperties,
   isExcludedProperty,
   isMarkedProperty,
   type Presence,
@@ -34,9 +35,10 @@ import {
 /**
  * The type of a `$ref` pointer as the generated types have it: the `schema` of a media type,
  * header or component parameter is its type, `items` is indexed by `number`,
- * `additionalProperties` by `string`, and a value that may be `undefined` or `null` is wrapped in
- * `NonNullable` before it is indexed. The walk stops at a segment with no type of its own
- * (`allOf/0`, `definitions/A`, operation `parameters/0`): the caller types the target itself.
+ * `additionalProperties` by `string` where the index signature is its type alone, and a value
+ * that may be `undefined` or `null` is wrapped in `NonNullable` before it is indexed. The walk
+ * stops at a segment with no type of its own (`allOf/0`, `definitions/A`, operation
+ * `parameters/0`): the caller types the target itself.
  */
 
 const DEFS_KEYWORD = "$defs";
@@ -133,6 +135,8 @@ function defsStep(walk: TypedWalk, owner: LocatedNode, isLast: boolean): TypedWa
   };
 }
 
+const COMPOSITION_KEYWORDS = ["allOf", "anyOf", "oneOf"] as const;
+
 const SHAPED_KEYWORDS: ReadonlySet<string> = new Set([
   "properties",
   "items",
@@ -151,6 +155,21 @@ function hasKeywordMember(owner: unknown, segment: string): boolean {
   return segment === "items" ? isArrayShape(owner) : isObjectShape(owner);
 }
 
+/**
+ * Whether `[string]` of the owner's type is its `additionalProperties` type. Not where the index
+ * signature also holds pattern or property types (`withPropertyTypes`), nor next to `allOf` /
+ * `anyOf` / `oneOf`, whose members may add an index signature or an inherited discriminator.
+ */
+function isIndexedByValue(owner: unknown, input: TypedWalkInput): boolean {
+  if (!isJsonObject(owner)) {
+    return true;
+  }
+  const patterns = owner.patternProperties;
+  const hasPatterns = isJsonObject(patterns) && Object.keys(patterns).length > 0;
+  const isComposed = COMPOSITION_KEYWORDS.some((keyword) => keyword in owner);
+  return !hasPatterns && !isComposed && !hasKeptProperties(owner, input.options, input.refs);
+}
+
 function keywordStep(walk: TypedWalk, segment: string, isLast: boolean, input: TypedWalkInput) {
   const owner = followLocated(walk, input.refs);
   if (!hasKeywordMember(owner.node, segment)) {
@@ -162,7 +181,10 @@ function keywordStep(walk: TypedWalk, segment: string, isLast: boolean, input: T
     case "items":
       return indexEntries(walk, "number", "items", input.refs);
     case "additionalProperties":
-      return indexEntries(walk, "string", "additionalProperties", input.refs);
+      // Otherwise the walk stops, and the target is typed in place.
+      return isIndexedByValue(owner.node, input)
+        ? indexEntries(walk, "string", "additionalProperties", input.refs)
+        : null;
     case DEFS_KEYWORD:
       return defsStep(walk, owner, isLast);
     default:

package/src/cli/api-writes.ts

@@ -1,5 +1,6 @@
 import type { ClaimedFile } from "../application/ports/file-system.js";
 import type { GeneratedTypes } from "./cli-dependencies.js";
+import { ApiFailure } from "./cli-errors.js";
 import {
   type CliRun,
   duplicateOutputError,
@@ -84,10 +85,17 @@ function writeClaimed(run: CliRun, { api, claim }: ClaimedApi): unknown[] {
     : failures;
 }
 
+/** The failures with the name of their API, which the CLI prints before each message. */
+function namedFailures(failures: ApiFailures): ApiFailures {
+  return new Map(
+    [...failures].map(([name, list]) => [name, list.map((cause) => new ApiFailure(name, cause))]),
+  );
+}
+
 /**
  * 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.
+ * API. Returns the failures by API name, each an `ApiFailure`. 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,
@@ -113,5 +121,5 @@ export function writeGeneratedApis(
   for (const entry of claimed.filter(({ api }) => !shared.has(api.name))) {
     failures.set(entry.api.name, writeClaimed(run, entry));
   }
-  return failures;
+  return namedFailures(failures);
 }