openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/api/schema-callbacks.ts

@@ -0,0 +1,211 @@
+import { toPropertySignature, toTypeNode } from "../adapters/type-ast-bridge/ir-to-typescript.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { fromPropertySignature } from "../adapters/type-ast-bridge/typescript-to-ir.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type {
+  CustomType,
+  SchemaCallbacks,
+  SchemaLocation,
+} from "../application/transform/schema/schema-context.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+import { irRaw } from "../domain/ir/constructors.js";
+import type { IrPropertySignature, IrType } from "../domain/ir/nodes.js";
+import type {
+  GlobalContext,
+  IrCallbackType,
+  IrPostTransform,
+  IrTransform,
+  IrTransformProperty,
+  LegacyCallbackOptions,
+  SchemaObject,
+  TransformNodeOptions,
+} from "../types.js";
+import { warnLegacyCallback } from "./legacy-callback-warning.js";
+import { toIrType } from "./type-helpers.js";
+
+/**
+ * The user's schema callbacks as the transformers call them (ENGINEERING_PLAN 6.3, ADR-004).
+ * With `irCallbacks: true` they receive and return IR; otherwise they receive TypeScript nodes and
+ * their results are read by the bridge.
+ */
+
+export class UnreadablePropertyError extends OpenAPITypesafeError {
+  constructor(path: string | undefined) {
+    super({
+      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
+      message:
+        `transformProperty at ${path} returned a property ` +
+        "with syntax the generator cannot read",
+      details: { callback: "transformProperty", path },
+    });
+    this.name = "UnreadablePropertyError";
+  }
+}
+
+/** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */
+export class UnreadableTypeError extends OpenAPITypesafeError {
+  constructor(callback: "transform" | "postTransform", path: string | undefined) {
+    super({
+      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
+      message: `${callback} at ${path} returned a value that is not a TypeScript node`,
+      details: { callback, path },
+    });
+    this.name = "UnreadableTypeError";
+  }
+}
+
+function nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {
+  return { ...location, ctx } as TransformNodeOptions;
+}
+
+/** The callbacks of the run: IR callbacks when the run asks for them, legacy ones otherwise. */
+export function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
+  return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);
+}
+
+/** An IR callback type; text is a raw type, printed as written. */
+function fromCallbackType(type: IrCallbackType): IrType {
+  return typeof type === "string" ? irRaw(type) : type;
+}
+
+function irCustomType(result: ReturnType<IrTransform>): CustomType | null {
+  if (result === undefined || result === null) {
+    return null;
+  }
+  if (typeof result === "object" && "schema" in result) {
+    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };
+  }
+  return { type: fromCallbackType(result), isOptional: false };
+}
+
+/**
+ * The context fields hold either callback form; `irCallbacks` says which one, so the casts below
+ * only name the form the user declared with `OpenAPITSIrOptions`.
+ */
+function irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
+  const transform = ctx.transform as IrTransform | undefined;
+  const postTransform = ctx.postTransform as IrPostTransform | undefined;
+  const transformProperty = ctx.transformProperty as IrTransformProperty | undefined;
+  return {
+    transform: (schema, location) =>
+      transform
+        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)))
+        : null,
+    postTransform(type, location) {
+      const result = postTransform?.(type, nodeOptions(ctx, location));
+      return result === undefined ? null : fromCallbackType(result);
+    },
+    transformProperty: (property, schema, location) =>
+      transformProperty?.(property, schema as SchemaObject, nodeOptions(ctx, location)) ?? null,
+  };
+}
+
+type LegacyTransform = NonNullable<LegacyCallbackOptions["transform"]>;
+type LegacyPostTransform = NonNullable<LegacyCallbackOptions["postTransform"]>;
+type LegacyTransformProperty = NonNullable<LegacyCallbackOptions["transformProperty"]>;
+
+/** A legacy result type: IR from the helpers as it is; a TypeScript node through the bridge. */
+/**
+ * IR nodes have a string `kind`, TypeScript nodes a number. JavaScript callers can return any
+ * value, and anything else would crash the TypeScript printer later.
+ */
+function readResultType(
+  callback: "transform" | "postTransform",
+  result: unknown,
+  location: SchemaLocation,
+): IrType {
+  const kind = (result as { kind?: unknown }).kind;
+  if (typeof kind !== "string" && typeof kind !== "number") {
+    throw new UnreadableTypeError(callback, location.path);
+  }
+  return toIrType(result as IrType | ts.TypeNode);
+}
+
+function legacyResultType(ctx: GlobalContext, type: unknown, location: SchemaLocation): IrType {
+  const result = readResultType("transform", type, location);
+  if (typeof (type as { kind: unknown }).kind !== "string") {
+    warnLegacyCallback(ctx, "transform");
+  }
+  return result;
+}
+
+function legacyCustomType(
+  ctx: GlobalContext,
+  result: ReturnType<LegacyTransform>,
+  location: SchemaLocation,
+): CustomType | null {
+  if (!result || typeof result !== "object") {
+    return null;
+  }
+  if ("schema" in result) {
+    return {
+      type: legacyResultType(ctx, result.schema, location),
+      isOptional: Boolean(result.questionToken),
+    };
+  }
+  return { type: legacyResultType(ctx, result, location), isOptional: false };
+}
+
+/** See `irSchemaCallbacks` for the casts; `typeof` checks keep the original's tolerance. */
+function legacySchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
+  const transform = ctx.transform as LegacyTransform | undefined;
+  const postTransform = ctx.postTransform as LegacyPostTransform | undefined;
+  return {
+    transform: (schema, location) =>
+      typeof transform === "function"
+        ? legacyCustomType(
+            ctx,
+            transform(schema as SchemaObject, nodeOptions(ctx, location)),
+            location,
+          )
+        : null,
+    postTransform(type, location) {
+      if (typeof postTransform !== "function") {
+        return null;
+      }
+      warnLegacyCallback(ctx, "postTransform");
+      const result = postTransform(toTypeNode(loadTypeScript(), type), nodeOptions(ctx, location));
+      return result ? readResultType("postTransform", result, location) : null;
+    },
+    transformProperty: (property, schema, location) =>
+      legacyTransformProperty(ctx, property, schema, location),
+  };
+}
+
+function isIrProperty(
+  property: IrPropertySignature | ts.PropertySignature,
+): property is IrPropertySignature {
+  return typeof property.kind === "string";
+}
+
+function legacyTransformProperty(
+  ctx: GlobalContext,
+  property: IrPropertySignature,
+  schema: unknown,
+  location: SchemaLocation,
+): IrPropertySignature | null {
+  const transformProperty = ctx.transformProperty as LegacyTransformProperty | undefined;
+  if (typeof transformProperty !== "function") {
+    return null;
+  }
+  warnLegacyCallback(ctx, "transformProperty");
+  const ts = loadTypeScript();
+  const options = nodeOptions(ctx, location);
+  const result = transformProperty(
+    toPropertySignature(ts, property),
+    schema as SchemaObject,
+    options,
+  );
+  if (!result) {
+    return null;
+  }
+  if (isIrProperty(result)) {
+    return result;
+  }
+  // JavaScript callers can return any value, so check the node kind before reading it.
+  const converted = ts.isPropertySignature(result) ? fromPropertySignature(ts, result) : null;
+  if (converted === null) {
+    throw new UnreadablePropertyError(location.path);
+  }
+  return converted;
+}

package/src/api/string-to-ast.ts

@@ -0,0 +1,27 @@
+import { deprecate } from "node:util";
+import { parseStatements } from "../adapters/type-ast-bridge/ir-declarations-to-typescript.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { IR_CALLBACKS_GUIDE_URL } from "./legacy-callback-warning.js";
+
+const STRING_TO_AST_DEPRECATION =
+  "stringToAST() is deprecated and removed in 2.0. Return TypeScript type text from an IR " +
+  `callback (irCallbacks: true) instead: ${IR_CALLBACKS_GUIDE_URL}`;
+
+/** Node's deprecation code for `stringToAST`, so users can filter or trace the warning. */
+export const STRING_TO_AST_DEPRECATION_CODE = "OPENAPI_TYPESAFE_DEP_STRING_TO_AST";
+
+function parseSource(source: string): unknown[] {
+  return [...parseStatements(loadTypeScript(), source)];
+}
+
+/**
+ * Convert an arbitrary string to TS (assuming it’s valid). Parses with the TypeScript bridge, so
+ * it needs TypeScript 6 or earlier (or `@typescript/typescript6`). Node's `util.deprecate` warns
+ * on the first call only.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 7). Use type text in IR callbacks.
+ */
+export const stringToAST: (source: string) => unknown[] = deprecate(
+  parseSource,
+  STRING_TO_AST_DEPRECATION,
+  STRING_TO_AST_DEPRECATION_CODE,
+);

package/src/api/transform-context.ts

@@ -0,0 +1,93 @@
+import * as changeCase from "change-case";
+import { RunFooter } from "../application/transform/footer/document-footer.js";
+import type {
+  DiscriminatorEnumParent,
+  SchemaLocation,
+} from "../application/transform/schema/schema-context.js";
+import type {
+  DocumentFooter,
+  NameCasing,
+  TransformContext,
+  TransformDiagnostics,
+  TransformOptions,
+} from "../application/transform/transform-context.js";
+import type { GlobalContext, TransformNodeOptions } from "../types.js";
+import { defaultLogger, monotonicNow } from "./default-ports.js";
+import { ContextFooterSink } from "./footer-sink.js";
+import { schemaCallbacks } from "./schema-callbacks.js";
+
+/**
+ * Builds the ported transformers' context from the original `GlobalContext`: options, refs,
+ * discriminators, the run footer and the user callbacks (see `schema-callbacks.ts`).
+ */
+
+function transformOptions(ctx: GlobalContext): TransformOptions {
+  return {
+    additionalProperties: ctx.additionalProperties,
+    alphabetize: ctx.alphabetize,
+    arrayLength: ctx.arrayLength,
+    binaryAsBlob: ctx.binaryAsBlob,
+    conditionalEnums: ctx.conditionalEnums,
+    dedupeEnums: ctx.dedupeEnums,
+    defaultNonNullable: ctx.defaultNonNullable,
+    emptyObjectsUnknown: ctx.emptyObjectsUnknown,
+    enum: ctx.enum,
+    enumValues: ctx.enumValues,
+    excludeDeprecated: ctx.excludeDeprecated,
+    fixes: new Set(ctx.fix ?? []),
+    immutable: ctx.immutable,
+    propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,
+    readWriteMarkers: ctx.readWriteMarkers,
+    generatePathParams: ctx.generatePathParams,
+    pathParamsAsTypes: ctx.pathParamsAsTypes,
+    rootTypes: ctx.rootTypes,
+    rootTypesNoSchemaPrefix: ctx.rootTypesNoSchemaPrefix,
+    rootTypesKeepCasing: ctx.rootTypesKeepCasing,
+    exportType: ctx.exportType,
+    inject: ctx.inject,
+    makePathsEnum: ctx.makePathsEnum,
+  };
+}
+
+/** One footer per run: it holds the enum registry, so it lives on the run's context. */
+function runFooter(ctx: GlobalContext): DocumentFooter {
+  ctx.runFooter ??= new RunFooter(new ContextFooterSink(ctx.injectFooter), ctx.dedupeEnums);
+  return ctx.runFooter;
+}
+
+const CASING: NameCasing = { pascalCase: (text) => changeCase.pascalCase(text) };
+
+/**
+ * A monotonic clock and the run's logger (the default one for a user's own context), "ts" group.
+ */
+function diagnostics(ctx: GlobalContext): TransformDiagnostics {
+  const logger = ctx.logger ?? defaultLogger(ctx.silent);
+  return {
+    now: monotonicNow,
+    debug: (message, durationMs) => logger.debug(message, "ts", durationMs),
+  };
+}
+
+/** The ported transformers' context for one call from a legacy transformer. */
+export function createTransformContext(ctx: GlobalContext): TransformContext {
+  return {
+    options: transformOptions(ctx),
+    refs: { resolve: (ref) => ctx.resolve(ref) },
+    discriminators: {
+      objectAt: (ref) => ctx.discriminators.objects[ref],
+      isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
+      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],
+      enumParentOf: (schema) =>
+        ctx.discriminators.enumParents?.get(schema) as DiscriminatorEnumParent | undefined,
+    },
+    footer: runFooter(ctx),
+    callbacks: schemaCallbacks(ctx),
+    diagnostics: diagnostics(ctx),
+    casing: CASING,
+  };
+}
+
+/** The transformer's location for the original options object. */
+export function schemaLocation(options: TransformNodeOptions): SchemaLocation {
+  return { path: options.path, schema: options.schema };
+}

package/src/api/transform-schema.ts

@@ -0,0 +1,123 @@
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import { documentBody, documentClosing } from "../application/transform/document/document.js";
+import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
+import { RunFooter } from "../application/transform/footer/document-footer.js";
+import { checkedEnumValues } from "../application/transform/footer/enum-values-check.js";
+import {
+  SharedEnumNameRecorder,
+  type SharedEnumNames,
+} from "../application/transform/footer/shared-enum-names.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+import type { DocumentObject } from "../domain/openapi/document-object.js";
+import { OutputFix } from "../domain/output-fixes.js";
+import type { GlobalContext, OpenAPI3 } from "../types.js";
+import { FirstSchemaNameRecorder } from "./discriminator-enum-names.js";
+import { documentDeclarations, type TransformedDocument } from "./document-declarations.js";
+import { excludedValuesWarning } from "./enum-values-warnings.js";
+import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+import { ContextFooterSink } from "./footer-sink.js";
+import { createTransformContext } from "./transform-context.js";
+
+const OPERATIONS_NAME = "operations";
+
+/** Whether a footer entry is named `operations` (any declaration kind, as in the original). */
+function isOperations(entry: FooterEntry): boolean {
+  const name = isIrDeclaration(entry)
+    ? (entry as { name?: string }).name
+    : (entry as Partial<ts.InterfaceDeclaration>).name?.escapedText;
+  return name === OPERATIONS_NAME;
+}
+
+/** Drops a message: the first pass must not repeat the run's warnings or debug lines. */
+const dropMessage = (): void => undefined;
+const DROPPED_MESSAGES = { debug: dropMessage, warn: dropMessage, error: dropMessage };
+
+/** A shared enum name recorder of a first pass, and the names it gives the second. */
+interface EnumNameRecorder extends SharedEnumNames {
+  chosenNames(): SharedEnumNames;
+}
+
+/**
+ * The names of shared enums, known only at the end: a first pass transforms the document into a
+ * scratch footer that `recorder` watches; its output is dropped. User callbacks run in both
+ * passes. The `dedupe-enum-names` fix (ADR-021, upstream #1683) names an enum by all of its
+ * schemas; `discriminator-values` keeps the first declaring schema's name
+ * (`FirstSchemaNameRecorder`).
+ */
+function sharedEnumNamesOf(
+  document: DocumentObject,
+  ctx: GlobalContext,
+  recorder: EnumNameRecorder,
+): SharedEnumNames {
+  const injectFooter: FooterEntry[] = [];
+  const scratch: GlobalContext = {
+    ...ctx,
+    injectFooter,
+    runFooter: new RunFooter(new ContextFooterSink(injectFooter), true, recorder),
+    logger: DROPPED_MESSAGES,
+    legacyCallbackWarnings: new Set(),
+  };
+  const scratchContext = createTransformContext(scratch);
+  documentBody(document, scratchContext, () => injectFooter.filter(isIrDeclaration));
+  return recorder.chosenNames();
+}
+
+/** The recorder of the run's fixes, or null where the first schema's name needs no first pass. */
+function enumNameRecorderOf(ctx: GlobalContext): EnumNameRecorder | null {
+  if (ctx.fix?.includes(OutputFix.DEDUPE_ENUM_NAMES)) {
+    return new SharedEnumNameRecorder();
+  }
+  return ctx.fix?.includes(OutputFix.DISCRIMINATOR_VALUES) ? new FirstSchemaNameRecorder() : null;
+}
+
+/** With a naming fix, `--enum` and `--dedupe-enums`, the run's footer names shared enums. */
+function withSharedEnumNames(document: DocumentObject, ctx: GlobalContext): void {
+  const recorder = ctx.runFooter === undefined ? enumNameRecorderOf(ctx) : null;
+  if (recorder === null || !ctx.enum || !ctx.dedupeEnums) {
+    return;
+  }
+  const names = sharedEnumNamesOf(document, ctx, recorder);
+  ctx.runFooter = new RunFooter(new ContextFooterSink(ctx.injectFooter), true, names);
+}
+
+/**
+ * With `--enum-values`, arrays whose location type does not hold their values are typed by their
+ * values (ADR-027); a location that excludes listed values is a contradiction of the document.
+ */
+function enumValuesChecked(
+  body: readonly IrDeclaration[],
+  footer: FooterEntry[],
+  ctx: GlobalContext,
+): FooterEntry[] {
+  if (!ctx.enumValues) {
+    return footer;
+  }
+  const checked = checkedEnumValues(footer, body, isIrDeclaration);
+  for (const retype of checked.retyped) {
+    if (retype.kind === "excluded") {
+      ctx.logger?.warn(excludedValuesWarning(retype.name, retype.excluded));
+    }
+  }
+  return checked.footer;
+}
+
+/** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
+export function transformDocument(schema: OpenAPI3, ctx: GlobalContext): TransformedDocument {
+  const document = schema as DocumentObject;
+  withSharedEnumNames(document, ctx);
+  const context = createTransformContext(ctx);
+  // documentBody registers the enums in the footer, so the footer is read after it.
+  const rawBody = documentBody(document, context, () => ctx.injectFooter.filter(isIrDeclaration));
+  const footer = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
+  const closing = documentClosing(document, context, footer.some(isOperations));
+  const body = renameTakenAliases(rawBody, footer.filter(isIrDeclaration), closing);
+  return { body, footer, closing };
+}
+
+/**
+ * The whole document as IR declarations (ENGINEERING_PLAN 6.1–6.2); `openapiTS` returns the same
+ * for a loaded document.
+ */
+export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclaration[] {
+  return documentDeclarations(transformDocument(schema, ctx));
+}

package/src/api/type-helpers.ts

@@ -0,0 +1,130 @@
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { fromTypeNode } from "../adapters/type-ast-bridge/typescript-to-ir.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import { HELPER_TYPES } from "../application/transform/helper-types.js";
+import { literalType } from "../application/transform/literal-type.js";
+import { refType } from "../application/transform/ref-type.js";
+import { UNKNOWN_TYPE } from "../application/transform/shared-types.js";
+import {
+  intersectionOf,
+  nullableOf,
+  omitKeys,
+  unionOf,
+  withRequiredKeys,
+} from "../application/transform/type-combinators.js";
+import { irBoolean, irKeyword, irRecord } from "../domain/ir/constructors.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ParameterObject, ReferenceObject } from "../types.js";
+import { declaresTypeAlias, type FooterEntry } from "./footer-entry.js";
+
+/**
+ * The public type helpers (ENGINEERING_PLAN 6.2, ADR-004 decision 2). Same names and call
+ * signatures as the original helpers; they return IR types. A `ts.TypeNode` argument (from user
+ * code built with `ts.factory`) is read into IR by the bridge.
+ */
+
+/** A helper argument: an IR type, or a TypeScript type node from user code. */
+export type TypeInput = IrType | ts.TypeNode;
+
+export const BOOLEAN: IrType = Object.freeze(irKeyword("boolean"));
+export const FALSE: IrType = Object.freeze(irBoolean(false));
+export const NEVER: IrType = Object.freeze(irKeyword("never"));
+export const NULL: IrType = Object.freeze(irKeyword("null"));
+export const NUMBER: IrType = Object.freeze(irKeyword("number"));
+export const STRING: IrType = Object.freeze(irKeyword("string"));
+export const TRUE: IrType = Object.freeze(irBoolean(true));
+export const UNDEFINED: IrType = Object.freeze(irKeyword("undefined"));
+/** The shared `unknown` type; the transformers compare with it by identity, as the original did. */
+export const UNKNOWN: IrType = UNKNOWN_TYPE;
+
+/** IR nodes have a string `kind`; TypeScript nodes have a numeric `SyntaxKind`. */
+function isIrType(type: TypeInput): type is IrType {
+  return typeof type.kind === "string";
+}
+
+/** @internal Read a helper argument into IR. */
+export function toIrType(type: TypeInput): IrType {
+  return isIrType(type) ? type : fromTypeNode(loadTypeScript(), type);
+}
+
+/** `A | B`: `never` for no types, the type itself for one; repeated primitives are removed. */
+export function tsUnion(types: readonly TypeInput[]): IrType {
+  return unionOf(types.map(toIrType));
+}
+
+/** `A & B`, with the same rules as `tsUnion`. */
+export function tsIntersection(types: readonly TypeInput[]): IrType {
+  return intersectionOf(types.map(toIrType));
+}
+
+/** `A | null`, without removing repeated types. */
+export function tsNullable(types: readonly TypeInput[]): IrType {
+  return nullableOf(types.map(toIrType));
+}
+
+/** `Omit<T, "a" | "b">`. */
+export function tsOmit(type: TypeInput, keys: readonly string[]): IrType {
+  return omitKeys(toIrType(type), keys);
+}
+
+/** `Record<K, V>`. */
+export function tsRecord(key: TypeInput, value: TypeInput): IrType {
+  return irRecord(toIrType(key), toIrType(value));
+}
+
+/**
+ * The literal type of a JSON value: strings, numbers, booleans and `null` as literals, arrays as
+ * tuples (an empty one as `never[]`), objects as object types; anything else is `unknown`.
+ */
+export function tsLiteral(value: unknown): IrType {
+  return literalType(value);
+}
+
+/**
+ * `WithRequired<T, "a" | "b">`, or the type itself for no keys. Adds the `WithRequired` helper
+ * type to the footer once.
+ */
+export function tsWithRequired(
+  type: TypeInput,
+  keys: readonly string[],
+  injectFooter: FooterEntry[],
+): IrType {
+  if (keys.length === 0) {
+    return toIrType(type);
+  }
+  const { name, text } = HELPER_TYPES.withRequired;
+  if (!injectFooter.some((entry) => declaresTypeAlias(entry, name))) {
+    injectFooter.push({ kind: "rawDeclaration", name, text });
+  }
+  return withRequiredKeys(toIrType(type), keys);
+}
+
+export interface OapiRefOptions {
+  /** Whether to wrap with FlattenedDeepRequired<> (default: false) */
+  deep?: boolean;
+  /** Array of property names to wrap with Extract<> when accessing */
+  extractProperties?: string[];
+}
+
+function isParameterObject(
+  value: ParameterObject | ReferenceObject | undefined,
+): value is ParameterObject {
+  return Boolean(value && !("$ref" in value && value.$ref) && (value as ParameterObject).in);
+}
+
+/**
+ * The generated type a JSON Pointer refers to, as an indexed access: `#/components/schemas/Foo`
+ * → `components["schemas"]["Foo"]`. Object `properties` are skipped, and a referenced parameter
+ * is indexed by its location (`resolved`).
+ */
+export function oapiRef(
+  path: string,
+  resolved?: ParameterObject | ReferenceObject,
+  options: OapiRefOptions = {},
+): IrType {
+  return refType(path, {
+    isDeep: options.deep ?? false,
+    extractProperties: options.extractProperties ?? [],
+    parameter: isParameterObject(resolved) ? { in: resolved.in, name: resolved.name } : null,
+  });
+}

package/src/api/unsupported-feature-warnings.ts

@@ -0,0 +1,33 @@
+import type { Logger } from "../application/ports/logger.js";
+import {
+  findUnsupportedFeatures,
+  UnsupportedFeature,
+} from "../domain/openapi/unsupported-features.js";
+import { WARNING_CODES, type WarningCode, warningText } from "../domain/warnings.js";
+
+const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
+const SUPPORT_DOCS_URL = `${DOCS_BASE_URL}/introduction.md#openapi-3-2-support`;
+
+/** Why each feature is not in the generated types. */
+const REASONS: Readonly<Record<UnsupportedFeature, string>> = {
+  [UnsupportedFeature.QUERYSTRING_NEXT_TO_QUERY]:
+    'is an "in: querystring" parameter next to "in: query" parameters, which OpenAPI 3.2 does ' +
+    "not allow; the query parameters keep their types and this parameter is not in the " +
+    "generated types",
+};
+
+/** The warning code of each feature. */
+const CODES: Readonly<Record<UnsupportedFeature, WarningCode>> = {
+  [UnsupportedFeature.QUERYSTRING_NEXT_TO_QUERY]: WARNING_CODES.QUERYSTRING_NEXT_TO_QUERY,
+};
+
+/**
+ * Warn once per use of an OpenAPI 3.2 feature that the generated types leave out, so a missing
+ * parameter is never silent (CODING_PRINCIPLES §8.7).
+ */
+export function warnUnsupportedFeatures(document: unknown, logger: Logger): void {
+  for (const { feature, pointer } of findUnsupportedFeatures(document)) {
+    const message = `${pointer} ${REASONS[feature]}. See ${SUPPORT_DOCS_URL}`;
+    logger.warn(warningText(message, CODES[feature]));
+  }
+}

package/src/application/ports/file-system.ts

@@ -0,0 +1,12 @@
+/** Read a generated file, for `--check` (ENGINEERING_PLAN 4.5). Fails with `OUTPUT_READ_FAILED`. */
+export interface FileReader {
+  readText(file: URL): string;
+}
+
+/**
+ * Write a generated file, creating its directory first (ENGINEERING_PLAN 4.5). Fails with
+ * `OUTPUT_WRITE_FAILED`.
+ */
+export interface FileWriter {
+  writeText(file: URL, contents: string): void;
+}

package/src/application/ports/logger.ts

@@ -0,0 +1,16 @@
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+export type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+export interface Logger {
+  /**
+   * A debug line, with how long the step took when it was measured. A line without a group is
+   * written whenever debug output is on.
+   */
+  debug(message: string, group?: DebugGroup, durationMs?: number): void;
+  warn(message: string): void;
+  error(message: string): void;
+}

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

@@ -0,0 +1,20 @@
+import type { GeneratorOptions } from "../../types.js";
+
+/** The loaded Redocly config, as the generator options take it. */
+export type RedoclyConfig = NonNullable<GeneratorOptions["redocly"]>;
+
+/** Where the CLI finds and loads `redocly.yaml` (ENGINEERING_PLAN 4.5). */
+export interface RedoclyConfigSource {
+  /**
+   * The config file to use: `explicitPath` (a file, or a directory to search), or the one found
+   * from the working directory. Undefined when there is none.
+   */
+  find(explicitPath: string | undefined): string | undefined;
+  /** The config of a file; fails with `CLI_CONFIG_INVALID` when it or its ignore file is bad. */
+  load(configPath: string): Promise<RedoclyConfig>;
+  /**
+   * The config used when there is no file: the minimal rules. Fails with `CLI_CONFIG_INVALID`
+   * when the ignore file of the working directory is bad.
+   */
+  createDefault(): Promise<RedoclyConfig>;
+}