openapi-typesafe 1.0.0-rc.1 → 1.0.0-rc.2

package/src/application/transform/footer/type-indexing.ts

@@ -0,0 +1,152 @@
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import {
+  type Evaluated,
+  type Evaluation,
+  intersectionType,
+  isNullish,
+  MISSING,
+  NEVER,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+import { declaredFirst, isNeverIntersection, type TypeExpansion } from "./type-rules.js";
+
+/**
+ * Indexed access (`T["key"]`, `T[number]`) on the generated types, as TypeScript reads it, for
+ * the evaluator of the `--enum-values` check (ADR-027).
+ */
+
+/** The part of the evaluator that indexed access uses. */
+export interface IndexedTypes extends TypeExpansion {
+  expand(value: Evaluated): Evaluation;
+  index(value: Evaluated, index: IrType): Evaluation;
+}
+
+/** `value[index]` for a string literal, `string` or `number` index. */
+export function indexType(types: IndexedTypes, value: Evaluated, index: IrType): Evaluation {
+  const owner = types.expand(value);
+  if (owner.kind !== "type") {
+    return owner;
+  }
+  if (types.membersOf(owner).length > 1) {
+    return unionIndex(types, owner, index);
+  }
+  const { type } = owner;
+  switch (type.kind) {
+    case "object":
+      return memberType(types, owner, type.members, index);
+    case "intersection":
+      return partsIndex(types, owner, type.types, index);
+    case "union":
+      return unionIndex(types, owner, index);
+    case "array":
+      return isNumberIndex(index) ? flattened(types, owner, type.element) : builtInIndex(index);
+    case "keyword":
+      return type.keyword === "never" ? owner : builtInIndex(index);
+    default:
+      return builtInIndex(index);
+  }
+}
+
+function memberType(
+  types: IndexedTypes,
+  owner: Evaluated,
+  members: readonly IrMember[],
+  index: IrType,
+): Evaluation {
+  const key = indexKey(index);
+  const property = members.find(
+    (member) => member.kind === "property" && key !== null && propertyKey(member.name) === key,
+  );
+  if (property !== undefined) {
+    return flattened(types, owner, property.type);
+  }
+  const signature = members.find((member) => member.kind === "indexSignature");
+  if (signature !== undefined) {
+    return flattened(types, owner, signature.type);
+  }
+  return key === null || isObjectBuiltIn(key) ? OPAQUE : MISSING;
+}
+
+function partsIndex(
+  types: IndexedTypes,
+  owner: Evaluated,
+  parts: readonly IrType[],
+  index: IrType,
+): Evaluation {
+  if (isNeverIntersection(types, owner, parts)) {
+    return { ...owner, type: NEVER };
+  }
+  const found = parts.map((type) => types.index({ ...owner, type }, index));
+  if (found.some((part) => part.kind === "opaque")) {
+    return OPAQUE;
+  }
+  const read = parts.map((type, at) => ({ type, found: found[at] as Evaluation }));
+  const kept = declaredFirst(types, owner, indexKey(index), read).flatMap((part) =>
+    part.kind === "type" ? [part.type] : [],
+  );
+  return kept.length === 0 ? MISSING : { ...owner, type: intersectionType(kept) };
+}
+
+function unionIndex(types: IndexedTypes, owner: Evaluated, index: IrType): Evaluation {
+  const found = types
+    .membersOf(owner)
+    .map((member) => (member.kind === "type" ? types.index(member, index) : member));
+  if (found.some((member) => member.kind === "missing")) {
+    return MISSING;
+  }
+  if (found.some((member) => member.kind === "opaque")) {
+    return OPAQUE;
+  }
+  return { ...owner, type: unionType((found as Evaluated[]).map((member) => member.type)) };
+}
+
+/**
+ * A member read through `FlattenedDeepRequired`: a value that is only arrays (and `undefined` or
+ * `null`) is replaced by its elements, anything else loses `undefined` and `null`.
+ */
+function flattened(types: IndexedTypes, owner: Evaluated, type: IrType): Evaluation {
+  const member: Evaluated = { ...owner, type };
+  if (!owner.deep) {
+    return types.expand(member);
+  }
+  const members = types.membersOf(member);
+  if (members.some((candidate) => candidate.kind !== "type")) {
+    return OPAQUE;
+  }
+  const present = (members as Evaluated[]).filter((candidate) => !isNullish(candidate.type));
+  const elements = present.map((candidate) => arrayElement(candidate.type));
+  if (present.length > 0 && elements.every((element) => element !== null)) {
+    return types.expand({ ...owner, type: unionType(elements as IrType[]) });
+  }
+  return { ...owner, type: unionType(present.map((candidate) => candidate.type)) };
+}
+
+/** The element of an expanded member; expanding already dropped `readonly`. */
+function arrayElement(type: IrType): IrType | null {
+  return type.kind === "array" ? type.element : null;
+}
+
+function indexKey(index: IrType): string | null {
+  if (index.kind === "stringLiteral") {
+    return index.value;
+  }
+  return index.kind === "numberLiteral" ? String(index.value) : null;
+}
+
+function isNumberIndex(index: IrType): boolean {
+  const key = indexKey(index);
+  return (index.kind === "keyword" && index.keyword === "number") || /^\d+$/.test(key ?? "");
+}
+
+function isObjectBuiltIn(key: string): boolean {
+  return key in {};
+}
+
+/** A key of a primitive or an array: a built-in member is opaque, any other key is missing. */
+function builtInIndex(index: IrType): Evaluation {
+  const key = indexKey(index);
+  const isBuiltIn = key === null || key in String.prototype || key in Array.prototype;
+  return isBuiltIn || key in Number.prototype ? OPAQUE : MISSING;
+}

package/src/cli/api-settings.ts

@@ -0,0 +1,109 @@
+import { kebabCase } from "scule";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import { GENERATOR_FLAGS, hostList } from "./cli-arguments.js";
+import { cliError } from "./cli-errors.js";
+import { resolveLocationUrl } from "./cli-output.js";
+import type { RefLimitOptions } from "./ref-limits.js";
+
+/**
+ * The settings of one API in `redocly.yaml` (`apis.<name>.x-openapi-ts`). A setting has the name
+ * of its CLI flag, in kebab-case or camelCase (ADR-021, decision 1); a setting the CLI does not
+ * read gets a warning, as an unknown flag gets a notice.
+ */
+
+export type ApiSettings = Readonly<Record<string, unknown>>;
+
+/** The setting that names the output file. */
+export const OUTPUT_SETTING = "output";
+
+/** The setting that lists the API's output fixes. */
+export const FIX_SETTING = "fix";
+
+const LOCAL_REF_ROOT_SETTING = "localRefRoot";
+const REMOTE_REF_HOSTS_SETTING = "remoteRefHosts";
+
+/** `--content-never` is accepted and has no effect, as on the command line. */
+const IGNORED_SETTINGS = ["contentNever"] as const;
+
+const CAMEL_CASE_SETTINGS = [
+  OUTPUT_SETTING,
+  FIX_SETTING,
+  LOCAL_REF_ROOT_SETTING,
+  REMOTE_REF_HOSTS_SETTING,
+  ...GENERATOR_FLAGS,
+  ...IGNORED_SETTINGS,
+];
+
+const KNOWN_SETTINGS = new Set<string>([
+  ...CAMEL_CASE_SETTINGS,
+  ...CAMEL_CASE_SETTINGS.map((name) => kebabCase(name)),
+]);
+
+/** The warning for each setting of an API that no code reads. */
+export function unknownSettingWarnings(apiName: string, settings: ApiSettings): string[] {
+  return Object.keys(settings)
+    .filter((key) => !KNOWN_SETTINGS.has(key))
+    .map((key) =>
+      warningText(
+        `API ${apiName}: the setting \`${key}\` is not an openapi-typesafe option and is ignored`,
+        WARNING_CODES.CONFIG_SETTING_UNKNOWN,
+      ),
+    );
+}
+
+/** The value of a setting in camelCase, else in kebab-case; `undefined` when it is absent. */
+function settingValue(settings: ApiSettings, name: string): unknown {
+  return name in settings ? settings[name] : settings[kebabCase(name)];
+}
+
+function hasSetting(settings: ApiSettings, name: string): boolean {
+  return name in settings || kebabCase(name) in settings;
+}
+
+function invalidSetting(apiName: string, name: string, expected: string): Error {
+  return cliError(
+    "CLI_CONFIG_INVALID",
+    `API ${apiName}: \`${kebabCase(name)}\` in x-openapi-ts must be ${expected}`,
+  );
+}
+
+/** `local-ref-root: dir`, relative to the config file; empty means the config file's directory. */
+function localRefRootOf(apiName: string, settings: ApiSettings, configRoot: URL): RefLimitOptions {
+  if (!hasSetting(settings, LOCAL_REF_ROOT_SETTING)) {
+    return {};
+  }
+  const value = settingValue(settings, LOCAL_REF_ROOT_SETTING) ?? "";
+  if (typeof value !== "string") {
+    throw invalidSetting(apiName, LOCAL_REF_ROOT_SETTING, "a directory path");
+  }
+  return { localRefRoot: resolveLocationUrl(value === "" ? "." : value, configRoot) };
+}
+
+/** `remote-ref-hosts: [a, b]` or `a,b`; an empty list or value allows no host. */
+function remoteRefHostsOf(apiName: string, settings: ApiSettings): RefLimitOptions {
+  if (!hasSetting(settings, REMOTE_REF_HOSTS_SETTING)) {
+    return {};
+  }
+  const value = settingValue(settings, REMOTE_REF_HOSTS_SETTING) ?? [];
+  const entries = [value].flat();
+  if (entries.some((entry) => typeof entry !== "string")) {
+    throw invalidSetting(apiName, REMOTE_REF_HOSTS_SETTING, "a host list");
+  }
+  return { remoteRefHosts: hostList(entries) ?? [] };
+}
+
+/**
+ * The `$ref` limits an API sets (threat model R1, R2). Each one replaces the CLI flag of the same
+ * name for this API, as its boolean settings and `fix` do; fails with `CLI_CONFIG_INVALID` for a
+ * value of another type.
+ */
+export function apiRefLimitOptions(
+  apiName: string,
+  settings: ApiSettings,
+  configRoot: URL,
+): RefLimitOptions {
+  return {
+    ...localRefRootOf(apiName, settings, configRoot),
+    ...remoteRefHostsOf(apiName, settings),
+  };
+}

package/src/cli/cli-arguments.ts

@@ -122,8 +122,11 @@ function lastString(value: unknown): string | undefined {
   return optionalString(Array.isArray(value) ? value.at(-1) : value);
 }
 
-/** `--remote-ref-hosts a.example,b.example`, repeatable; an empty value allows no host. */
-function hostList(value: unknown): string[] | undefined {
+/**
+ * `--remote-ref-hosts a.example,b.example`, repeatable; an empty value allows no host. The
+ * `remote-ref-hosts` setting of a `redocly.yaml` API is read the same way.
+ */
+export function hostList(value: unknown): string[] | undefined {
   if (value === undefined) {
     return undefined;
   }

package/src/cli/help-text.ts

@@ -4,7 +4,7 @@ export const HELP_TEXT = [
   "  $ openapi-typesafe [input] [options]",
   "",
   "Options",
-  "  --help                     Display this",
+  "  --help                     Show this help",
   "  --version                  Display the version",
   "  --redocly [path], -c       Specify path to Redocly config (default: redocly.yaml)",
   "  --output, -o               Specify output file (if not specified in redocly.yaml)",
@@ -20,8 +20,8 @@ export const HELP_TEXT = [
   "  --additional-properties    Treat schema objects as if `additionalProperties: true` is set",
   "  --empty-objects-unknown    Generate `unknown` instead of" +
     " `Record<string, never>` for empty objects",
-  "  --default-non-nullable     Set to `false` to ignore default values" +
-    " when generating non-nullable types",
+  "  --default-non-nullable     A property with a `default` is required" +
+    " (default: true; =false makes it optional)",
   "  --properties-required-by-default",
   "                             Treat schema objects as if `required` is" +
     " set to all properties by default",
@@ -35,7 +35,7 @@ export const HELP_TEXT = [
     " undefined by schema",
   "  --alphabetize              Sort object keys alphabetically",
   "  --exclude-deprecated       Exclude deprecated types",
-  "  --root-types               Export schemas types at root level",
+  "  --root-types               Export `components` types as root-level aliases",
   "  --root-types-no-schema-prefix",
   '                             Do not add "Schema" prefix to types at' +
     " the root level (should only be used with --root-types)",

package/src/cli/redocly-apis.ts

@@ -2,6 +2,13 @@ import { kebabCase } from "scule";
 import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
 import type { OutputFixName } from "../domain/output-fixes.js";
 import type { GeneratorOptions } from "../types.js";
+import {
+  type ApiSettings,
+  apiRefLimitOptions,
+  FIX_SETTING,
+  OUTPUT_SETTING,
+  unknownSettingWarnings,
+} from "./api-settings.js";
 import { GENERATOR_FLAGS, type GeneratorFlags } from "./cli-arguments.js";
 import { cliError } from "./cli-errors.js";
 import { type CliRun, emitOutput, resolveLocationUrl } from "./cli-output.js";
@@ -14,11 +21,6 @@ import { refLimitOptions } from "./ref-limits.js";
 /** The key of an API's openapi-typesafe settings in `redocly.yaml`. */
 const REDOCLY_CONFIG_KEY = "x-openapi-ts";
 
-/** The setting of an API that lists its output fixes. */
-const FIX_SETTING = "fix";
-
-type ApiSettings = Readonly<Record<string, unknown>>;
-
 interface RedoclyApi {
   readonly name: string;
   readonly root: string;
@@ -59,19 +61,23 @@ function configRootOf(redocly: RedoclyConfig, cwd: URL): URL {
 }
 
 async function generateApi(run: CliRun, redocly: RedoclyConfig, api: RedoclyApi): Promise<void> {
-  if (!api.settings?.output) {
+  if (!api.settings?.[OUTPUT_SETTING]) {
     throw cliError(
       "CLI_CONFIG_OUTPUT_MISSING",
       `API ${api.name} is missing an \`${REDOCLY_CONFIG_KEY}.output\` key. ` +
         `See ${MULTIPLE_SCHEMAS_DOCS_URL}`,
     );
   }
-  const output = String(api.settings.output);
+  for (const warning of unknownSettingWarnings(api.name, api.settings)) {
+    run.deps.logger.warn(warning);
+  }
+  const output = String(api.settings[OUTPUT_SETTING]);
   const configRoot = configRootOf(redocly, run.deps.cwd);
   const options: GeneratorOptions = {
     ...run.args.generatorFlags,
     ...apiFlags(api.settings),
     ...refLimitOptions(run.args, run.deps.cwd),
+    ...apiRefLimitOptions(api.name, api.settings, configRoot),
     ...fixOption(apiFixNames(api.settings) ?? run.args.fix),
     redocly,
   };

package/src/cli/run-cli.ts

@@ -1,5 +1,6 @@
 import type { Logger } from "../application/ports/logger.js";
 import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import type { SchemaSource } from "../types.js";
 import { ineffectiveFlagNotices, parseCliArguments } from "./cli-arguments.js";
 import type { CliDependencies } from "./cli-dependencies.js";
@@ -84,7 +85,10 @@ async function generate(run: CliRun): Promise<unknown[]> {
   }
   if (run.args.input) {
     run.deps.logger.warn(
-      "APIs are specified both in Redocly Config and CLI argument. Only using Redocly config.",
+      warningText(
+        "APIs are specified both in Redocly Config and CLI argument. Only using Redocly config.",
+        WARNING_CODES.CLI_INPUT_IGNORED,
+      ),
     );
   }
   return generateRedoclyApis(run, redocly);

package/src/domain/errors.ts

@@ -1,3 +1,5 @@
+import { redactUrlCredentials } from "./url-credentials.js";
+
 /**
  * Typed errors (ENGINEERING_PLAN 4.6, ADR-011). Every expected failure of the generator and the CLI
  * is an `OpenAPITypesafeError` with a stable machine-readable `code` and structured `details`. The
@@ -48,13 +50,17 @@ export interface OpenAPITypesafeErrorInit {
   readonly cause?: unknown;
 }
 
-/** The base of every expected failure; check `code`, not the class or the message. */
+/**
+ * The base of every expected failure; check `code`, not the class or the message. The message
+ * never shows the user info of a URL (`url-credentials.ts`).
+ */
 export class OpenAPITypesafeError extends Error {
   readonly code: ErrorCode;
   readonly details: ErrorDetails;
 
   constructor(init: OpenAPITypesafeErrorInit) {
-    super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+    const message = redactUrlCredentials(init.message);
+    super(message, init.cause === undefined ? undefined : { cause: init.cause });
     this.name = "OpenAPITypesafeError";
     this.code = init.code;
     this.details = init.details ?? {};

package/src/domain/ir/constructors.ts

@@ -33,6 +33,9 @@ export function irKeyword(keyword: IrKeyword): IrKeywordType {
   return { kind: "keyword", keyword };
 }
 
+/** The encoding of a string literal that does not name one. */
+export const DEFAULT_STRING_ENCODING: IrStringEncoding = "json";
+
 export function irString(value: string, encoding: IrStringEncoding): IrStringLiteralType {
   return { kind: "stringLiteral", value, encoding };
 }

package/src/domain/ir/nodes.ts

@@ -1,8 +1,10 @@
 /**
  * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
  * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
- * discriminator; every consumer dispatches with an exhaustive `switch`, so a new kind breaks the
- * build wherever it must be handled.
+ * discriminator; every consumer in this package dispatches with an exhaustive `switch`, so a new
+ * kind breaks the build wherever it must be handled. For users the set is open: a minor release
+ * may add a kind (ADR-034), so code outside the package must keep a node of an unknown kind as it
+ * is, and a `switch` over `kind` needs a `default` branch.
  *
  * Utility types (`Omit`, `Record`, `WithRequired`, `Extract`) are `reference` nodes with type
  * arguments, built by named constructors: the printer has nothing special to do for them.
@@ -35,7 +37,8 @@ export interface IrKeywordType {
 export interface IrStringLiteralType {
   readonly kind: "stringLiteral";
   readonly value: string;
-  readonly encoding: IrStringEncoding;
+  /** How the printer writes the value; unset is `json`. A detail of the printer. */
+  readonly encoding?: IrStringEncoding;
 }
 
 /** Finite number; a negative value prints with a leading minus sign. */
@@ -112,9 +115,9 @@ export interface IrRawType {
   readonly kind: "raw";
   readonly text: string;
   /**
-   * The outside node the text was printed from, opaque to the IR. While the Node API still
-   * returns `ts.Node`s (until Phase 6), the bridge hands this node back unchanged, exactly as the
-   * original did. Removed with the reverse bridge in Phase 6.
+   * @internal The TypeScript node the bridge printed the text from. The reverse bridge (the
+   * deprecated `ts.Node` callbacks, ADR-004) hands it back unchanged. Set by the generator only:
+   * read it as opaque, never set it, and expect it to go away in 2.0.
    */
   readonly origin?: unknown;
 }

package/src/domain/openapi/path-templates.ts

@@ -4,7 +4,8 @@
  * `/a/{name}`, match the same URLs, so a client cannot tell which one a request is for.
  */
 
-const PATH_PARAMETER_RE = /\{[^}]+\}/g;
+/** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
+const PATH_PARAMETER_RE = /\{[^{}]+\}/g;
 const PATH_PREFIX = "/";
 const UNNAMED_PARAMETER = "{}";
 

package/src/domain/url-credentials.ts

@@ -0,0 +1,18 @@
+/**
+ * URLs with user info (`https://user:token@host/…`) can reach a message: the CLI input, a `$ref`,
+ * a redirect. Messages end up in CI job logs, so the user info is hidden in every one (audit B2,
+ * F12). Fetch refuses such URLs anyway, so a message never needs the credentials.
+ */
+
+/**
+ * The user info after a scheme: everything up to an `@` that comes before the end of the
+ * authority. The class stops at `/`, so a scan never runs past the next `://`; it stays linear.
+ */
+const URL_USER_INFO = /:\/\/[^\s/?#@]*@/g;
+
+const REDACTED_USER_INFO = "://***@";
+
+/** The text with the user info of every URL in it replaced by `***`. */
+export function redactUrlCredentials(text: string): string {
+  return text.replace(URL_USER_INFO, () => REDACTED_USER_INFO);
+}

package/src/domain/warnings.ts

@@ -6,10 +6,18 @@
 
 /** Every warning code. */
 export const WARNING_CODES = {
+  CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED",
+  CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN",
+  DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID",
   DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED",
   ENUM_VALUES_EXCLUDED: "ENUM_VALUES_EXCLUDED",
+  FIX_NEEDS_OPTION: "FIX_NEEDS_OPTION",
+  LEGACY_CALLBACK_DEPRECATED: "LEGACY_CALLBACK_DEPRECATED",
+  LINT_PROBLEM: "LINT_PROBLEM",
   PATH_TEMPLATES_IDENTICAL: "PATH_TEMPLATES_IDENTICAL",
   QUERYSTRING_NEXT_TO_QUERY: "QUERYSTRING_NEXT_TO_QUERY",
+  REF_CIRCULAR: "REF_CIRCULAR",
+  REF_NOT_FOUND: "REF_NOT_FOUND",
 } as const;
 
 export type WarningCode = (typeof WARNING_CODES)[keyof typeof WARNING_CODES];

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   OutputFix,
   type OutputFixName,
 } from "./domain/output-fixes.js";
+export { WARNING_CODES, type WarningCode } from "./domain/warnings.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";

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

@@ -1,10 +1,14 @@
 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 { PathItemMethod } from "../domain/openapi/path-item-object.js";
 import type { PathItemObject, TransformNodeOptions } from "../types.js";
 
-export type Method = HttpMethod;
+/**
+ * The operation methods of a path item: openapi-typescript's eight, plus the OpenAPI 3.2 `query`
+ * (ADR-020), as `HttpMethod` of openapi-typesafe-helpers lists them.
+ */
+export type Method = PathItemMethod;
 
 /**
  * Transform PathItem nodes (4.8.9)

package/src/types/generator-options.ts

@@ -3,8 +3,6 @@ import type { Readable } from "node:stream";
 import type { Config as RedoclyConfig } from "@redocly/openapi-core";
 import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
 import type { FooterEntry } from "../api/footer-entry.js";
-import type { Logger } from "../application/ports/logger.js";
-import type { DocumentFooter } from "../application/transform/transform-context.js";
 import type { IrPropertySignature, IrType } from "../domain/ir/nodes.js";
 import type { OutputFix, OutputFixName } from "../domain/output-fixes.js";
 import type { ReferenceObject } from "./openapi-common.js";
@@ -74,7 +72,7 @@ export interface OpenAPITSBaseOptions {
   lint?: boolean;
   /** (optional) Should logging be suppressed? (necessary for STDOUT) */
   silent?: boolean;
-  /** (optional) OpenAPI version. Must be present if parsing raw schema */
+  /** Accepted for compatibility with openapi-typescript; not read. */
   version?: number;
   /** (optional) Export type instead of interface */
   exportType?: boolean;
@@ -197,28 +195,22 @@ export interface OpenAPITSIrOptions extends OpenAPITSBaseOptions, IrCallbackOpti
 /** Either form of the generator options. */
 export type GeneratorOptions = OpenAPITSOptions | OpenAPITSIrOptions;
 
-/** Context passed to all submodules */
+/**
+ * Context passed to all submodules, and to the callbacks as `options.ctx`. To call an exported
+ * transformer outside a run, build one with the fields of openapi-typescript's context; the
+ * fields openapi-typesafe added are optional.
+ */
 export interface GlobalContext {
   // user options
   additionalProperties: boolean;
   alphabetize: boolean;
   arrayLength: boolean;
-  binaryAsBlob: boolean;
+  /** `format: binary` and `contentMediaType` strings become `Blob` (default: false). */
+  binaryAsBlob?: boolean;
   defaultNonNullable: boolean;
   discriminators: {
     objects: Record<string, DiscriminatorObject>;
     refsHandled: string[];
-    /**
-     * @internal With the `discriminator-values` fix: for each enum the scan added to a
-     * member and each inherited discriminator object, the enum of the owner's property and the
-     * location it is typed at.
-     */
-    enumParents?: ReadonlyMap<object, { readonly schema: SchemaObject; readonly path: string }>;
-    /**
-     * @internal With the `discriminator-values` fix: for each schema, the properties of the
-     * discriminators it inherits besides `objects[ref]`, which it redefines too.
-     */
-    otherProperties?: Readonly<Record<string, readonly string[]>>;
   };
   emptyObjectsUnknown: boolean;
   enum: boolean;
@@ -235,24 +227,12 @@ export interface GlobalContext {
    * callbacks may add IR declarations or TypeScript nodes.
    */
   injectFooter: FooterEntry[];
+  pathParamsAsTypes: boolean;
   /**
-   * @internal Footer state of this run (enum registry and enum naming), created on first use by
-   * the transform context adapter. Not an option; do not set it.
-   */
-  runFooter?: DocumentFooter;
-  /**
-   * @internal The deprecated callback forms this run has warned about (once each). Not an
-   * option; do not set it.
-   */
-  legacyCallbackWarnings?: Set<LegacyCallbackName>;
-  /**
-   * @internal Where this run reports warnings and debug output. Not an option; a context without
-   * it logs to the terminal.
+   * Whether the callbacks below take IR (`OpenAPITSIrOptions`) or TypeScript nodes
+   * (default: false, TypeScript nodes).
    */
-  logger?: Logger;
-  pathParamsAsTypes: boolean;
-  /** Whether the callbacks below take IR (`OpenAPITSIrOptions`) or TypeScript nodes. */
-  irCallbacks: boolean;
+  irCallbacks?: boolean;
   postTransform: GeneratorOptions["postTransform"];
   propertiesRequiredByDefault: boolean;
   rootTypes: boolean;

package/src/types/openapi-common.ts

@@ -7,6 +7,7 @@
 // for ways schemas _can_ be written, not necessarily how they _should_ be.
 
 export interface Extensable {
+  // biome-ignore lint/suspicious/noExplicitAny: public type under semver (ADR-034)
   [key: `x-${string}`]: any;
 }
 

package/src/types/openapi-request.ts

@@ -67,6 +67,7 @@ export interface ParameterObject extends Extensable {
   /** The schema defining the type used for the parameter. */
   schema?: SchemaObject;
   /** Example of the parameter’s potential value. */
+  // biome-ignore lint/suspicious/noExplicitAny: public type under semver (ADR-034)
   example?: any;
   /** Examples of the parameter’s potential value. */
   examples?: { [name: string]: ExampleObject | ReferenceObject };
@@ -111,6 +112,7 @@ export interface MediaTypeObject extends Extensable {
    * referencing a schema which contains an example, the example value SHALL override the example
    * provided by the schema.
    */
+  // biome-ignore lint/suspicious/noExplicitAny: public type under semver (ADR-034)
   example?: any;
   /**
    * Examples of the media type. Each example object SHOULD match the media type and specified
@@ -188,6 +190,7 @@ export interface ExampleObject extends Extensable {
    * represent examples of media types that cannot naturally represented in JSON or YAML, use a
    * string value to contain the example, escaping where necessary.
    */
+  // biome-ignore lint/suspicious/noExplicitAny: public type under semver (ADR-034)
   value?: any;
   /**
    * A URI that points to the literal example. This provides the capability to reference examples

package/src/types/openapi-schema.ts

@@ -21,6 +21,7 @@ export type SchemaObject = {
   /** Additional external documentation for this schema. */
   externalDocs?: ExternalDocumentationObject;
   /** @deprecated */
+  // biome-ignore lint/suspicious/noExplicitAny: public type under semver (ADR-034)
   example?: any;
   title?: string;
   description?: string;
@@ -47,6 +48,7 @@ export type SchemaObject = {
   allOf?: (SchemaObject | ReferenceObject)[];
   anyOf?: (SchemaObject | ReferenceObject)[];
   required?: string[];
+  // biome-ignore lint/suspicious/noExplicitAny: public type under semver (ADR-034)
   [key: `x-${string}`]: any;
 } & (
   | StringSubtype