openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/domain/openapi/unsupported-features.ts

@@ -0,0 +1,139 @@
+import { createRef, parseRefPointer } from "./json-pointer.js";
+import { QUERYSTRING_LOCATION } from "./parameter-object.js";
+import { type PathItemObject, pathItemOperations } from "./path-item-object.js";
+
+/**
+ * OpenAPI 3.2 uses that the generated types leave out, so each one gets a warning. The 3.2
+ * features are typed (ADR-020); what is left is an `in: querystring` parameter next to
+ * `in: query` parameters of the same operation, which 3.2 does not allow: the `query`
+ * parameters keep their types and the `querystring` parameter is not in the output.
+ */
+export const UnsupportedFeature = {
+  QUERYSTRING_NEXT_TO_QUERY: "querystring",
+} as const;
+export type UnsupportedFeature = (typeof UnsupportedFeature)[keyof typeof UnsupportedFeature];
+
+/** One place in the document that uses a feature the output leaves out. */
+export interface UnsupportedFeatureUse {
+  readonly feature: UnsupportedFeature;
+  /** A JSON Pointer to the object that has the feature's key, such as `#/paths/~1items`. */
+  readonly pointer: string;
+}
+
+const QUERY_LOCATION = "query";
+const LOCAL_REF_PREFIX = "#/";
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The value at a local `$ref` (`#/...`) of the document; null for other or broken `$ref`s. */
+function resolveLocal(document: JsonObject, value: unknown): unknown {
+  if (!isObject(value) || typeof value.$ref !== "string") {
+    return value;
+  }
+  if (!value.$ref.startsWith(LOCAL_REF_PREFIX)) {
+    return null;
+  }
+  let node: unknown = document;
+  for (const segment of parseRefPointer(value.$ref)) {
+    node = isObject(node) || Array.isArray(node) ? (node as JsonObject)[segment] : undefined;
+  }
+  return node ?? null;
+}
+
+/** A parameter where it is written, with the object its `$ref` points to. */
+interface LocatedParameter {
+  readonly pointer: string;
+  readonly parameter: JsonObject;
+}
+
+function locatedParameters(
+  document: JsonObject,
+  parameters: unknown,
+  segments: readonly string[],
+): LocatedParameter[] {
+  if (!Array.isArray(parameters)) {
+    return [];
+  }
+  return parameters.flatMap((entry, index) => {
+    const parameter = resolveLocal(document, entry);
+    const pointer = createRef([...segments, String(index)]);
+    return isObject(parameter) ? [{ pointer, parameter }] : [];
+  });
+}
+
+/** Path item parameters, then the operation's, which replace those of the same `in` and name. */
+function mergedParameters(
+  shared: readonly LocatedParameter[],
+  own: readonly LocatedParameter[],
+): LocatedParameter[] {
+  const byKey = new Map<string, LocatedParameter>();
+  for (const located of [...shared, ...own]) {
+    byKey.set(`${String(located.parameter.in)}-${String(located.parameter.name)}`, located);
+  }
+  return [...byKey.values()];
+}
+
+/** The `querystring` parameters of one operation that has `in: query` parameters as well. */
+function querystringPointers(parameters: readonly LocatedParameter[]): string[] {
+  const hasQuery = parameters.some(({ parameter }) => parameter.in === QUERY_LOCATION);
+  return hasQuery
+    ? parameters
+        .filter(({ parameter }) => parameter.in === QUERYSTRING_LOCATION)
+        .map(({ pointer }) => pointer)
+    : [];
+}
+
+/** Pointers of `querystring` parameters next to `query` ones in the operations of a path item. */
+function pathItemPointers(
+  document: JsonObject,
+  pathItem: JsonObject,
+  segments: readonly string[],
+): string[] {
+  const shared = locatedParameters(document, pathItem.parameters, [...segments, "parameters"]);
+  return pathItemOperations(pathItem as PathItemObject).flatMap((entry) => {
+    const operation = resolveLocal(document, entry.operation);
+    if (!isObject(operation)) {
+      return [];
+    }
+    const operationSegments = [...segments, ...entry.segments, "parameters"];
+    const own = locatedParameters(document, operation.parameters, operationSegments);
+    return querystringPointers(mergedParameters(shared, own));
+  });
+}
+
+function pathItemsPointers(
+  document: JsonObject,
+  pathItems: unknown,
+  root: readonly string[],
+): string[] {
+  if (!isObject(pathItems)) {
+    return [];
+  }
+  return Object.entries(pathItems).flatMap(([key, pathItem]) =>
+    isObject(pathItem) ? pathItemPointers(document, pathItem, [...root, key]) : [],
+  );
+}
+
+/**
+ * Every use of a feature in `UnsupportedFeature`, once per pointer, in document order: `paths`,
+ * then `webhooks`, then `components.pathItems`.
+ */
+export function findUnsupportedFeatures(document: unknown): UnsupportedFeatureUse[] {
+  if (!isObject(document)) {
+    return [];
+  }
+  const components = isObject(document.components) ? document.components : {};
+  const pointers = [
+    ...pathItemsPointers(document, document.paths, ["paths"]),
+    ...pathItemsPointers(document, document.webhooks, ["webhooks"]),
+    ...pathItemsPointers(document, components.pathItems, ["components", "pathItems"]),
+  ];
+  return [...new Set(pointers)].map((pointer) => ({
+    feature: UnsupportedFeature.QUERYSTRING_NEXT_TO_QUERY,
+    pointer,
+  }));
+}

package/src/domain/output-fixes.ts

@@ -0,0 +1,136 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "./errors.js";
+
+/**
+ * Opt-in fixes of the output of valid schemas (ADR-021). Each one changes only the cases it names;
+ * without any, the output is the same as openapi-typescript 7.13 gives. In 2.0 they become the
+ * default.
+ */
+export const OutputFix = {
+  /** An `allOf` `$ref` to a discriminated union is the union, without `Omit` or a schema name. */
+  ALLOF_DISCRIMINATED_UNION: "allof-discriminated-union",
+  /** An `allOf` member with only `required` makes those properties of the others required. */
+  ALLOF_REQUIRED: "allof-required",
+  /** The JSDoc of a schema lists the descriptions of its `anyOf` and `oneOf` members. */
+  ANYOF_ONEOF_DESCRIPTIONS: "anyof-oneof-descriptions",
+  /** `anyOf` / `oneOf` variants with only `required` make those keys of the parent required. */
+  ANYOF_ONEOF_REQUIRED: "anyof-oneof-required",
+  /** `anyOf` next to object keywords or `allOf` is intersected with them, not added to a union. */
+  ANYOF_PROPERTIES: "anyof-properties",
+  /** `--array-length` tuples have `min` to `max` items, nest right and follow `--immutable`. */
+  ARRAY_LENGTH_TUPLES: "array-length-tuples",
+  /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
+  DEDUPE_ENUM_NAMES: "dedupe-enum-names",
+  /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
+  DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required",
+  /**
+   * The value a discriminator member gets: one enum of every discriminator's values, a mapping
+   * before the schema name, a schema's own mapping before an inherited one, none where the member
+   * declares it, and with `--enum` a member of the owner's enum.
+   */
+  DISCRIMINATOR_VALUES: "discriminator-values",
+  /** An exploded object query parameter's properties are keys of `query`, as they are sent. */
+  EXPLODED_QUERY_OBJECTS: "exploded-query-objects",
+  /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
+  NULLABLE_ENUMS: "nullable-enums",
+  /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
+  PATH_PARAM_TYPE_NAMES: "path-param-type-names",
+  /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
+  PREFIX_ITEMS: "prefix-items",
+  /** `readOnly` and `writeOnly` of the schema a `$ref` names, or of `allOf` members, count. */
+  READ_WRITE_REFS: "read-write-refs",
+  /**
+   * A `$ref` into schema keywords (`content/<type>/schema`, `items`, `allOf/0`) gets the type it
+   * points at, also where the original type compiles through an index signature.
+   */
+  REF_POINTERS: "ref-pointers",
+  /** Schemas of one root type name without the prefix each get an alias, the earlier numbered. */
+  ROOT_TYPE_NUMBERING: "root-type-numbering",
+  /** `unevaluatedProperties` types the keys no other keyword declares (an index signature). */
+  UNEVALUATED_PROPERTIES: "unevaluated-properties",
+} as const;
+export type OutputFix = (typeof OutputFix)[keyof typeof OutputFix];
+
+/** Every fix of this version, in the order the docs list them. */
+export const OUTPUT_FIXES: readonly OutputFix[] = Object.values(OutputFix);
+
+/** The name that turns on every fix of the installed version. */
+export const ALL_OUTPUT_FIXES = "all";
+
+/** A name the `fix` option accepts: one fix, or `all`. */
+export type OutputFixName = OutputFix | typeof ALL_OUTPUT_FIXES;
+
+const KNOWN_NAMES: ReadonlySet<string> = new Set<string>([...OUTPUT_FIXES, ALL_OUTPUT_FIXES]);
+
+function isOutputFixName(value: unknown): value is OutputFixName {
+  return typeof value === "string" && KNOWN_NAMES.has(value);
+}
+
+/** The fix names as given; fails with `OPTION_FIX_UNKNOWN` for any other value. */
+export function outputFixNamesOf(values: readonly unknown[]): readonly OutputFixName[] {
+  const unknown = values.filter((value) => !isOutputFixName(value));
+  if (unknown.length > 0) {
+    const names = unknown.map((value) => JSON.stringify(value)).join(", ");
+    const known = [...KNOWN_NAMES].join(", ");
+    throw new OpenAPITypesafeError({
+      code: ERROR_CODES.OPTION_FIX_UNKNOWN,
+      message: `Unknown fix ${names}. Known fixes: ${known}.`,
+      details: { unknown, known: [...KNOWN_NAMES] },
+    });
+  }
+  return values as readonly OutputFixName[];
+}
+
+/** The fixes the names turn on; `all` stands for every fix of this version. */
+export function resolveOutputFixes(names: readonly OutputFixName[]): ReadonlySet<OutputFix> {
+  return new Set(names.flatMap((name) => (name === ALL_OUTPUT_FIXES ? OUTPUT_FIXES : [name])));
+}
+
+/** A generator option that a fix works with; without it, the fix changes nothing (ADR-021). */
+export interface OutputFixRequirement {
+  readonly option:
+    | "arrayLength"
+    | "dedupeEnums"
+    | "enum"
+    | "pathParamsAsTypes"
+    | "rootTypes"
+    | "rootTypesNoSchemaPrefix";
+  readonly flag: string;
+}
+
+const ROOT_TYPES = { option: "rootTypes", flag: "--root-types" } as const;
+const ENUM = { option: "enum", flag: "--enum" } as const;
+const NO_SCHEMA_PREFIX = {
+  option: "rootTypesNoSchemaPrefix",
+  flag: "--root-types-no-schema-prefix",
+} as const;
+
+/** The options each fix needs, by fix name; `all` has none. */
+const REQUIREMENTS: Readonly<Partial<Record<OutputFixName, readonly OutputFixRequirement[]>>> = {
+  [OutputFix.ARRAY_LENGTH_TUPLES]: [{ option: "arrayLength", flag: "--array-length" }],
+  [OutputFix.DEDUPE_ENUM_NAMES]: [ENUM, { option: "dedupeEnums", flag: "--dedupe-enums" }],
+  [OutputFix.NULLABLE_ENUMS]: [ENUM],
+  [OutputFix.PATH_PARAM_TYPE_NAMES]: [
+    { option: "pathParamsAsTypes", flag: "--path-params-as-types" },
+  ],
+  [OutputFix.ROOT_TYPE_NUMBERING]: [ROOT_TYPES, NO_SCHEMA_PREFIX],
+};
+
+function describeRequirement(requirement: OutputFixRequirement): string {
+  return `${requirement.option} (${requirement.flag})`;
+}
+
+/**
+ * A notice for each fix given by name with an option it needs off; it names the options that are
+ * off. `all` adds none: it means every fix that applies, so one that does not apply is expected.
+ */
+export function ineffectiveFixNotices(
+  names: readonly OutputFixName[],
+  isOptionOn: (option: OutputFixRequirement["option"]) => boolean,
+): string[] {
+  return [...new Set(names)].flatMap((name) => {
+    const missing = (REQUIREMENTS[name] ?? []).filter(({ option }) => !isOptionOn(option));
+    return missing.length === 0
+      ? []
+      : [`Fix "${name}" has no effect without ${missing.map(describeRequirement).join(" and ")}`];
+  });
+}

package/src/domain/warnings.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed warnings. A warning does not stop the run: the output is written and the CLI exits with 0.
+ * Each one ends with a stable machine-readable code in parentheses, as the CLI prints errors
+ * (`message (CODE)`), so a script or a person can search for it.
+ */
+
+/** Every warning code. */
+export const WARNING_CODES = {
+  DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED",
+  ENUM_VALUES_EXCLUDED: "ENUM_VALUES_EXCLUDED",
+  PATH_TEMPLATES_IDENTICAL: "PATH_TEMPLATES_IDENTICAL",
+  QUERYSTRING_NEXT_TO_QUERY: "QUERYSTRING_NEXT_TO_QUERY",
+} as const;
+
+export type WarningCode = (typeof WARNING_CODES)[keyof typeof WARNING_CODES];
+
+/** The warning line for people, with its code at the end. */
+export function warningText(message: string, code: WarningCode): string {
+  return `${message} (${code})`;
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+import openapiTS from "./api/openapi-ts.js";
+
+/**
+ * The package entry: the public Node API (ENGINEERING_PLAN 4.1, `api/`). `openapiTS` is the default
+ * export, as in the original.
+ */
+
+export * from "./api/ast-to-string.js";
+export { COMMENT_HEADER } from "./api/comment-header.js";
+export { scanDiscriminators } from "./api/discriminator-scan.js";
+export type { FooterEntry } from "./api/footer-entry.js";
+export * from "./api/legacy-ts-helpers.js";
+export * from "./api/legacy-utils.js";
+export * from "./api/string-to-ast.js";
+export { default as transformSchema } from "./api/transform-schema.js";
+export {
+  BOOLEAN,
+  FALSE,
+  NEVER,
+  NULL,
+  NUMBER,
+  type OapiRefOptions,
+  oapiRef,
+  STRING,
+  TRUE,
+  type TypeInput,
+  tsIntersection,
+  tsLiteral,
+  tsNullable,
+  tsOmit,
+  tsRecord,
+  tsUnion,
+  tsWithRequired,
+  UNDEFINED,
+  UNKNOWN,
+} from "./api/type-helpers.js";
+export {
+  ERROR_CODES,
+  type ErrorCode,
+  type ErrorDetails,
+  isOpenAPITypesafeError,
+  OpenAPITypesafeError,
+} from "./domain/errors.js";
+export type * from "./domain/ir/nodes.js";
+export {
+  ALL_OUTPUT_FIXES,
+  OUTPUT_FIXES,
+  OutputFix,
+  type OutputFixName,
+} from "./domain/output-fixes.js";
+export { default as transformComponentsObject } from "./transform/components-object.js";
+export { default as transformHeaderObject } from "./transform/header-object.js";
+export { default as transformMediaTypeObject } from "./transform/media-type-object.js";
+export * from "./transform/operation-object.js";
+export { default as transformOperationObject } from "./transform/operation-object.js";
+export { default as transformParameterObject } from "./transform/parameter-object.js";
+export * from "./transform/path-item-object.js";
+export { default as transformPathItemObject } from "./transform/path-item-object.js";
+export { default as transformPathsObject } from "./transform/paths-object.js";
+export { default as transformRequestBodyObject } from "./transform/request-body-object.js";
+export { default as transformResponseObject } from "./transform/response-object.js";
+export { default as transformResponsesObject } from "./transform/responses-object.js";
+export * from "./transform/schema-object.js";
+export { default as transformSchemaObject } from "./transform/schema-object.js";
+export * from "./types.js";
+
+export default openapiTS;

package/src/transform/components-object.ts

@@ -0,0 +1,27 @@
+import { createTransformContext } from "../api/transform-context.js";
+import { componentsType } from "../application/transform/document/components.js";
+import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
+import type { IrType, IrTypeAliasDeclaration } from "../domain/ir/nodes.js";
+import { isEnumSchema, singularizeComponentKind } from "../domain/openapi/components-object.js";
+import type { ComponentsObject, GlobalContext } from "../types.js";
+
+export { isEnumSchema };
+
+/** `requestBodies` → `requestBody`; other keys drop the final `s`. */
+export const singularizeComponentKey = singularizeComponentKind;
+
+/**
+ * Transform the ComponentsObject (4.8.7)
+ * @see https://spec.openapis.org/oas/latest.html#components-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 6). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API: the `components` type, then the root type aliases.
+ */
+export default function transformComponentsObject(
+  componentsObject: ComponentsObject,
+  ctx: GlobalContext,
+): (IrType | IrTypeAliasDeclaration)[] {
+  const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));
+  // No footer here: only the aliases the `root-type-numbering` fix keeps get numbers.
+  return [type, ...renameTakenAliases(rootTypes, [])];
+}

package/src/transform/header-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { headerType } from "../application/transform/document/header.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { HeaderObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform HeaderObject nodes (4.8.21)
+ * @see https://spec.openapis.org/oas/v3.1.0#header-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformHeaderObject(
+  headerObject: HeaderObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return headerType(headerObject, schemaLocation(options), context);
+}

package/src/transform/media-type-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { mediaTypeType } from "../application/transform/document/media-type.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { MediaTypeObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform MediaTypeObject nodes (4.8.14)
+ * @see https://spec.openapis.org/oas/v3.1.0#media-type-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformMediaTypeObject(
+  mediaTypeObject: MediaTypeObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return mediaTypeType(mediaTypeObject, schemaLocation(options), context);
+}

package/src/transform/operation-object.ts

@@ -0,0 +1,36 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { operationMembers } from "../application/transform/document/operation.js";
+import { irObject, irProperty } from "../domain/ir/constructors.js";
+import type { IrMember } from "../domain/ir/nodes.js";
+import { toPropertyName } from "../domain/ir/property-name.js";
+import type { OperationObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform OperationObject nodes (4.8.10)
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformOperationObject(
+  operationObject: OperationObject,
+  options: TransformNodeOptions,
+): IrMember[] {
+  const context = createTransformContext(options.ctx);
+  return operationMembers(operationObject, schemaLocation(options), context);
+}
+
+/** inject an operation at the top level */
+export function injectOperationObject(
+  operationId: string,
+  operationObject: OperationObject,
+  options: TransformNodeOptions,
+): void {
+  const context = createTransformContext(options.ctx);
+  context.footer.addOperation(() => {
+    const members = operationMembers(operationObject, schemaLocation(options), context);
+    return irProperty(toPropertyName(operationId), irObject(members), {
+      isReadonly: options.ctx.immutable,
+    });
+  });
+}

package/src/transform/parameter-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { parameterType } from "../application/transform/document/parameter.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ParameterObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform ParameterObject nodes (4.8.12)
+ * @see https://spec.openapis.org/oas/v3.1.0#parameter-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformParameterObject(
+  parameterObject: ParameterObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return parameterType(parameterObject, schemaLocation(options), context);
+}

package/src/transform/parameters-array.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { parametersMember } from "../application/transform/document/parameters.js";
+import type { IrMember } from "../domain/ir/nodes.js";
+import type { ParameterObject, ReferenceObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Synthetic type. Array of (ParameterObject | ReferenceObject)s found in OperationObject and
+ * PathItemObject.
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the deep imports of this module.
+ */
+export function transformParametersArray(
+  parametersArray: (ParameterObject | ReferenceObject)[],
+  options: TransformNodeOptions,
+): IrMember[] {
+  const context = createTransformContext(options.ctx);
+  return [parametersMember(parametersArray, schemaLocation(options), context)];
+}

package/src/transform/path-item-object.ts

@@ -0,0 +1,22 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { pathItemType } from "../application/transform/document/path-item.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { HttpMethod } from "../domain/openapi/path-item-object.js";
+import type { PathItemObject, TransformNodeOptions } from "../types.js";
+
+export type Method = HttpMethod;
+
+/**
+ * Transform PathItem nodes (4.8.9)
+ * @see https://spec.openapis.org/oas/v3.1.0#path-item-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformPathItemObject(
+  pathItem: PathItemObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return pathItemType(pathItem, schemaLocation(options), context);
+}

package/src/transform/paths-enum.ts

@@ -0,0 +1,8 @@
+import { apiPathsEnumDeclaration } from "../application/transform/document/paths-enum.js";
+import type { IrEnumDeclaration } from "../domain/ir/nodes.js";
+import type { PathsObject } from "../types.js";
+
+/** The `ApiPaths` enum (`--make-paths-enum`), built in IR (ENGINEERING_PLAN Phase 5, step 6). */
+export default function makeApiPathsEnum(pathsObject: PathsObject): IrEnumDeclaration {
+  return apiPathsEnumDeclaration(pathsObject);
+}

package/src/transform/paths-object.ts

@@ -0,0 +1,15 @@
+import { createTransformContext } from "../api/transform-context.js";
+import { pathsType } from "../application/transform/document/paths.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { GlobalContext, PathsObject } from "../types.js";
+
+/**
+ * Transform the PathsObject node (4.8.8)
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformPathsObject(pathsObject: PathsObject, ctx: GlobalContext): IrType {
+  return pathsType(pathsObject, createTransformContext(ctx));
+}

package/src/transform/request-body-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { requestBodyType } from "../application/transform/document/request-body.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { RequestBodyObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform RequestBodyObject nodes (4.8.13)
+ * @see https://spec.openapis.org/oas/v3.1.0#request-body-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 4). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformRequestBodyObject(
+  requestBodyObject: RequestBodyObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return requestBodyType(requestBodyObject, schemaLocation(options), context);
+}

package/src/transform/response-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { responseType } from "../application/transform/document/response.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ResponseObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform ResponseObject nodes (4.8.17)
+ * @see https://spec.openapis.org/oas/v3.1.0#response-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 4). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformResponseObject(
+  responseObject: ResponseObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return responseType(responseObject, schemaLocation(options), context);
+}

package/src/transform/responses-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { responsesType } from "../application/transform/document/responses.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ResponsesObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform ResponsesObject nodes (4.8.16)
+ * @see https://spec.openapis.org/oas/v3.1.0#responses-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 4). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformResponsesObject(
+  responsesObject: ResponsesObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return responsesType(responsesObject, schemaLocation(options), context);
+}

package/src/transform/schema-object.ts

@@ -0,0 +1,36 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import {
+  transformSchema,
+  transformSchemaShape,
+} from "../application/transform/schema/schema-transform.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ReferenceObject, SchemaObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform SchemaObject nodes (4.8.24)
+ * @see https://spec.openapis.org/oas/v3.1.0#schema-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 2): the work happens in
+ * `application/transform/schema`; this keeps the original name and parameters, returning IR
+ * (task 6.2), for the public API and for users who call it from callbacks.
+ */
+export default function transformSchemaObject(
+  schemaObject: SchemaObject | ReferenceObject,
+  options: TransformNodeOptions,
+  fromAdditionalProperties = false,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  const location = schemaLocation(options);
+  return transformSchema(schemaObject, location, context, fromAdditionalProperties);
+}
+
+/** Transform SchemaObjects without the `postTransform` callback at the top level. */
+export function transformSchemaObjectWithComposition(
+  schemaObject: SchemaObject | ReferenceObject,
+  options: TransformNodeOptions,
+  fromAdditionalProperties = false,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  const location = schemaLocation(options);
+  return transformSchemaShape(schemaObject, location, context, fromAdditionalProperties);
+}