openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/api/document-refs.ts

@@ -0,0 +1,71 @@
+import { parseRef } from "@redocly/openapi-core/lib/ref-utils.js";
+import type { Logger } from "../application/ports/logger.js";
+import { defaultLogger } from "./default-ports.js";
+
+/** `$ref` resolution and the document walk that the generator's pre-pass uses. */
+
+export interface ResolveRefOptions {
+  silent: boolean;
+  visited?: string[];
+  /** @internal Where warnings go; the default terminal logger (respecting `silent`) if absent. */
+  logger?: Logger;
+}
+
+/** Resolve a `$ref` in a document; warns and returns undefined when it cannot. */
+export function resolveDocumentRef<T>(
+  schema: any,
+  $ref: string,
+  options: ResolveRefOptions,
+): T | undefined {
+  const { visited = [] } = options;
+  const logger = options.logger ?? defaultLogger(options.silent ?? false);
+  const { pointer } = parseRef($ref);
+  if (!pointer.length) {
+    return undefined;
+  }
+  let node = schema;
+  for (const key of pointer) {
+    if (node && typeof node === "object" && node[key]) {
+      node = node[key];
+    } else {
+      logger.warn(`Could not resolve $ref "${$ref}"`);
+      return undefined;
+    }
+  }
+
+  // if this is also a $ref, keep tracing
+  if (node && typeof node === "object" && node.$ref) {
+    if (visited.includes(node.$ref)) {
+      logger.warn(`Could not resolve circular $ref "${$ref}"`);
+      return undefined;
+    }
+    return resolveDocumentRef(schema, node.$ref, {
+      ...options,
+      logger,
+      visited: [...visited, node.$ref],
+    });
+  }
+
+  return node;
+}
+
+/** Call `cb` for every object in a JSON-serializable (non-circular) value, depth first. */
+export function walkDocument(
+  obj: unknown,
+  cb: (value: Record<string, unknown>, path: (string | number)[]) => void,
+  path: (string | number)[] = [],
+): void {
+  if (!obj || typeof obj !== "object") {
+    return;
+  }
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      walkDocument(obj[i], cb, path.concat(i));
+    }
+    return;
+  }
+  cb(obj as Record<string, unknown>, path);
+  for (const k of Object.keys(obj)) {
+    walkDocument((obj as Record<string, unknown>)[k], cb, path.concat(k));
+  }
+}

package/src/api/document-run.ts

@@ -0,0 +1,177 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { Config as RedoclyConfig } from "@redocly/openapi-core";
+import { sourceEmptyError } from "../adapters/redocly-loader/schema-load-errors.js";
+import type { Logger } from "../application/ports/logger.js";
+import type { RefAccess, SchemaLoader } from "../application/ports/schema-loader.js";
+import { withStackOverflowReported } from "../application/stack-overflow.js";
+import {
+  ineffectiveFixNotices,
+  type OutputFix,
+  outputFixNamesOf,
+  resolveOutputFixes,
+} from "../domain/output-fixes.js";
+import type { GeneratorOptions, GlobalContext, OpenAPI3, SchemaSource } from "../types.js";
+import { warnDiscriminatorValueConflicts } from "./discriminator-conflict-warnings.js";
+import { findDiscriminators } from "./discriminator-scan.js";
+import { resolveDocumentRef } from "./document-refs.js";
+import { warnIdenticalPathTemplates } from "./path-template-warnings.js";
+import { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
+
+/** The ports of one generator run, wired by the Node API or the CLI (ENGINEERING_PLAN 4.5). */
+export interface GeneratorPorts {
+  readonly loader: SchemaLoader;
+  readonly logger: Logger;
+  /** The Redocly config the loader uses; the run's context exposes it as `ctx.redoc`. */
+  readonly redoc: RedoclyConfig;
+  /** A monotonic time in milliseconds, for debug durations. */
+  readonly now: () => number;
+}
+
+/** A validated, bundled document and the context of one generator run. */
+export interface DocumentRun {
+  readonly schema: OpenAPI3;
+  readonly ctx: GlobalContext;
+}
+
+/** The context fields that are user flags, with the original defaults. */
+type ContextFlags = Omit<
+  GlobalContext,
+  | "discriminators"
+  | "injectFooter"
+  | "redoc"
+  | "resolve"
+  | "runFooter"
+  | "legacyCallbackWarnings"
+  | "logger"
+  | "fix"
+>;
+
+/**
+ * The directory that relative `$ref`s of an inline source resolve against, as a URL that ends in
+ * a slash. A path is resolved and encoded (`#`, `%`, spaces); a URL without the slash gets one.
+ */
+function sourceCwd(options: GeneratorOptions): URL {
+  const { cwd } = options;
+  if (cwd instanceof URL) {
+    return cwd.pathname.endsWith("/") ? cwd : new URL(`${cwd.pathname}/`, cwd);
+  }
+  const directory = path.resolve(cwd === undefined ? process.cwd() : cwd.toString());
+  return pathToFileURL(path.join(directory, path.sep));
+}
+
+/** The `$ref` limits of the options; a relative local root resolves against the cwd. */
+function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {
+  const { localRefRoot, remoteRefHosts } = options;
+  const localRoot =
+    typeof localRefRoot === "string"
+      ? pathToFileURL(path.resolve(fileURLToPath(cwd), localRefRoot))
+      : localRefRoot;
+  return {
+    ...(localRoot === undefined ? {} : { localRoot }),
+    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteRefHosts }),
+  };
+}
+
+function callbackOptions(options: GeneratorOptions) {
+  return {
+    irCallbacks: options.irCallbacks === true,
+    postTransform: typeof options.postTransform === "function" ? options.postTransform : undefined,
+    transform: typeof options.transform === "function" ? options.transform : undefined,
+    transformProperty:
+      typeof options.transformProperty === "function" ? options.transformProperty : undefined,
+  };
+}
+
+function contextFlags(options: GeneratorOptions): ContextFlags {
+  return {
+    additionalProperties: options.additionalProperties ?? false,
+    alphabetize: options.alphabetize ?? false,
+    arrayLength: options.arrayLength ?? false,
+    binaryAsBlob: options.binaryAsBlob ?? false,
+    defaultNonNullable: options.defaultNonNullable ?? true,
+    emptyObjectsUnknown: options.emptyObjectsUnknown ?? false,
+    enum: options.enum ?? false,
+    enumValues: options.enumValues ?? false,
+    conditionalEnums: options.conditionalEnums ?? false,
+    dedupeEnums: options.dedupeEnums ?? false,
+    excludeDeprecated: options.excludeDeprecated ?? false,
+    exportType: options.exportType ?? false,
+    immutable: options.immutable ?? false,
+    rootTypes: options.rootTypes ?? false,
+    rootTypesNoSchemaPrefix: options.rootTypesNoSchemaPrefix ?? false,
+    rootTypesKeepCasing: options.rootTypesKeepCasing ?? false,
+    pathParamsAsTypes: options.pathParamsAsTypes ?? false,
+    propertiesRequiredByDefault: options.propertiesRequiredByDefault ?? false,
+    silent: options.silent ?? false,
+    ...(options.inject === undefined ? {} : { inject: options.inject }),
+    makePathsEnum: options.makePathsEnum ?? false,
+    generatePathParams: options.generatePathParams ?? false,
+    readWriteMarkers: options.readWriteMarkers ?? false,
+    ...callbackOptions(options),
+  };
+}
+
+/**
+ * The fixes of the options, `all` expanded; fails with `OPTION_FIX_UNKNOWN` for another name.
+ * A fix named without the option it needs is reported, since it changes nothing.
+ */
+function outputFixesOf(options: GeneratorOptions, logger: Logger): readonly OutputFix[] {
+  const names = outputFixNamesOf(options.fix ?? []);
+  for (const notice of ineffectiveFixNotices(names, (option) => options[option] === true)) {
+    logger.warn(notice);
+  }
+  return [...resolveOutputFixes(names)];
+}
+
+/** The warnings about the loaded document itself, before it is transformed. */
+function warnAboutDocument(schema: OpenAPI3, fix: readonly OutputFix[], logger: Logger): void {
+  withStackOverflowReported("transform", () => warnUnsupportedFeatures(schema, logger));
+  withStackOverflowReported("transform", () =>
+    warnDiscriminatorValueConflicts(schema, fix, logger),
+  );
+  warnIdenticalPathTemplates(schema, logger);
+}
+
+/**
+ * Load the source through the ports, then build the run's context from the options. The fix names
+ * are checked first, so a typo fails before the document is read.
+ */
+export async function createDocumentRun(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<DocumentRun> {
+  if (!source) {
+    throw sourceEmptyError("Empty schema. Please specify a URL, file path, or Redocly Config");
+  }
+  const { logger } = ports;
+  const fix = outputFixesOf(options, logger);
+  const silent = options.silent ?? false;
+  const cwd = sourceCwd(options);
+  const schema = await ports.loader.load({
+    source,
+    cwd,
+    shouldLint: options.lint ?? true,
+    refAccess: refAccessOf(options, cwd),
+  });
+  warnAboutDocument(schema, fix, logger);
+  const ctx: GlobalContext = {
+    ...contextFlags(options),
+    fix,
+    // The scan walks every schema before the transform does, so on a larger stack, where loading
+    // passed, it is the first step to run out.
+    discriminators: withStackOverflowReported("transform", () =>
+      findDiscriminators(schema, {
+        silent,
+        logger,
+        fixes: new Set(fix),
+      }),
+    ),
+    injectFooter: [],
+    redoc: ports.redoc,
+    resolve: ($ref) => resolveDocumentRef(schema, $ref, { silent, logger }),
+    logger,
+  };
+  return { schema, ctx };
+}

package/src/api/enum-values-warnings.ts

@@ -0,0 +1,21 @@
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+
+const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
+const DOCS_URL = `${DOCS_BASE_URL}/advanced.md#enum-values-arrays`;
+
+/**
+ * The warning for an `--enum-values` array whose schema's location in the generated types admits
+ * none or only some of its values (ADR-027): the schema contradicts itself, for example an `allOf`
+ * of enums with different values or a discriminator value that the property enum does not list.
+ */
+export function excludedValuesWarning(name: string, excluded: readonly unknown[]): string {
+  const values = excluded.map((value) => JSON.stringify(value)).join(", ");
+  return warningText(
+    `${name}: the generated type at the location of this enum does not admit ${values}; ` +
+      "other keywords of the document exclude these values (an allOf of enums with other " +
+      "values, or a discriminator value the enum does not list). The array is typed by its own " +
+      "values. " +
+      `See ${DOCS_URL}`,
+    WARNING_CODES.ENUM_VALUES_EXCLUDED,
+  );
+}

package/src/api/footer-entry.ts

@@ -0,0 +1,23 @@
+import { isTypeAliasNamed } from "../adapters/type-ast-bridge/footer-nodes.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+
+/** A footer entry: a declaration in IR, or a TypeScript node added by user code. */
+export type FooterEntry = IrDeclaration | ts.Node;
+
+/** IR nodes have a string `kind`; TypeScript nodes have a numeric `SyntaxKind`. */
+export function isIrDeclaration(entry: FooterEntry): entry is IrDeclaration {
+  return typeof entry.kind === "string";
+}
+
+/**
+ * Whether the entry declares a type alias with this name: an IR type alias, a named raw
+ * declaration (the helper types), or a user's TypeScript type alias. Helpers are added once.
+ */
+export function declaresTypeAlias(entry: FooterEntry, name: string): boolean {
+  if (!isIrDeclaration(entry)) {
+    return isTypeAliasNamed(loadTypeScript(), entry, name);
+  }
+  return (entry.kind === "typeAlias" || entry.kind === "rawDeclaration") && entry.name === name;
+}

package/src/api/footer-sink.ts

@@ -0,0 +1,67 @@
+import { appendMember, asInterfaceNamed } from "../adapters/type-ast-bridge/footer-nodes.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import type { FooterSink } from "../application/transform/footer/document-footer.js";
+import type {
+  IrDeclaration,
+  IrInterfaceDeclaration,
+  IrPropertySignature,
+} from "../domain/ir/nodes.js";
+import { declaresTypeAlias, type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+
+const OPERATIONS_NAME = "operations";
+
+/**
+ * The footer of a run is its `ctx.injectFooter` list. The generator adds IR declarations; user
+ * code may add IR declarations or TypeScript nodes (ENGINEERING_PLAN 6.2).
+ */
+export class ContextFooterSink implements FooterSink {
+  private readonly footer: FooterEntry[];
+
+  constructor(footer: FooterEntry[]) {
+    this.footer = footer;
+  }
+
+  hasTypeAlias(name: string): boolean {
+    return this.footer.some((entry) => declaresTypeAlias(entry, name));
+  }
+
+  add(declaration: IrDeclaration): void {
+    this.footer.push(declaration);
+  }
+
+  /**
+   * Add a member to the `operations` interface, declared first (exported) when missing, so it
+   * comes before any declaration `build` adds. A user's TypeScript `operations` interface gets
+   * the member in place, as in the original.
+   */
+  addOperation(build: () => IrPropertySignature): void {
+    const existing = this.findOperations();
+    if (existing !== null && !isIrDeclaration(existing.entry)) {
+      const ts = loadTypeScript();
+      const node = asInterfaceNamed(ts, existing.entry, OPERATIONS_NAME);
+      if (node) {
+        appendMember(ts, node, build());
+      }
+      return;
+    }
+    const index = existing?.index ?? this.footer.push(emptyOperations()) - 1;
+    const member = build();
+    const operations = this.footer[index] as IrInterfaceDeclaration;
+    this.footer[index] = { ...operations, members: [...operations.members, member] };
+  }
+
+  /** The first `operations` interface: the generator's (IR) or a user's (TypeScript). */
+  private findOperations(): { entry: FooterEntry; index: number } | null {
+    const index = this.footer.findIndex((entry) =>
+      isIrDeclaration(entry)
+        ? entry.kind === "interface" && entry.name === OPERATIONS_NAME
+        : asInterfaceNamed(loadTypeScript(), entry, OPERATIONS_NAME) !== null,
+    );
+    const entry = this.footer[index];
+    return entry === undefined ? null : { entry, index };
+  }
+}
+
+function emptyOperations(): IrInterfaceDeclaration {
+  return { kind: "interface", name: OPERATIONS_NAME, isExported: true, members: [], comments: [] };
+}

package/src/api/legacy-callback-warning.ts

@@ -0,0 +1,29 @@
+import type { GlobalContext, LegacyCallbackName } from "../types.js";
+import { defaultLogger } from "./default-ports.js";
+
+/** Where the IR callbacks are documented; the warning points users there. */
+export const IR_CALLBACKS_GUIDE_URL =
+  "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/node.md#ir-callbacks";
+
+const USES: Readonly<Record<LegacyCallbackName, string>> = {
+  transform: "`transform` returned a TypeScript node",
+  postTransform: "`postTransform` receives TypeScript nodes",
+  transformProperty: "`transformProperty` receives TypeScript nodes",
+};
+
+function message(name: LegacyCallbackName): string {
+  return (
+    `${USES[name]}. This form works in 1.x through the TypeScript bridge and is removed in 2.0. ` +
+    `Use irCallbacks: true and return IR or type text instead: ${IR_CALLBACKS_GUIDE_URL}`
+  );
+}
+
+/** Warn once per run and callback; `silent` runs record the use but print nothing. */
+export function warnLegacyCallback(ctx: GlobalContext, name: LegacyCallbackName): void {
+  ctx.legacyCallbackWarnings ??= new Set();
+  if (ctx.legacyCallbackWarnings.has(name)) {
+    return;
+  }
+  ctx.legacyCallbackWarnings.add(name);
+  (ctx.logger ?? defaultLogger(ctx.silent)).warn(message(name));
+}