openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/api/legacy-ts-helpers.ts

@@ -0,0 +1,311 @@
+import { toTypeNode, toValueExpression } from "../adapters/type-ast-bridge/ir-to-typescript.js";
+import { lazyNode } from "../adapters/type-ast-bridge/lazy-node.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import {
+  enumMemberDescription,
+  quotedMemberName,
+} from "../application/transform/footer/enum-naming.js";
+import { HELPER_TYPES } from "../application/transform/helper-types.js";
+import { schemaComment } from "../application/transform/schema-comment.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import { declaresTypeAlias, type FooterEntry } from "./footer-entry.js";
+import type { TypeInput } from "./type-helpers.js";
+
+/**
+ * The original's helpers that build TypeScript compiler nodes, kept for 1.x and deprecated
+ * (ADR-004, decision 9). They load TypeScript on first use through the bridge; the generator
+ * itself does not use them.
+ */
+
+export const JS_PROPERTY_INDEX_RE = /^[A-Za-z_$][A-Za-z_$0-9]*$/;
+export const JS_ENUM_INVALID_CHARS_RE = /[^A-Za-z_$0-9]+(.)?/g;
+export const JS_PROPERTY_INDEX_INVALID_CHARS_RE = /[^A-Za-z_$0-9]+/g;
+export const SPECIAL_CHARACTER_MAP: Record<string, string> = {
+  "+": "Plus",
+  // Add more mappings as needed
+};
+
+/**
+ * The `?` token. Created on first use, so importing the package needs no TypeScript.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export const QUESTION_TOKEN: ts.QuestionToken = lazyNode(() => {
+  const ts = loadTypeScript();
+  return ts.factory.createToken(ts.SyntaxKind.QuestionToken);
+});
+
+export interface AnnotatedSchemaObject {
+  const?: unknown; // jsdoc without value
+  default?: unknown; // jsdoc with value
+  deprecated?: boolean; // jsdoc without value
+  description?: string; // jsdoc with value
+  enum?: unknown[]; // jsdoc without value
+  example?: string; // jsdoc with value
+  examples?: unknown;
+  format?: string; // not jsdoc
+  nullable?: boolean; // Node information
+  summary?: string; // not jsdoc
+  title?: string; // not jsdoc
+  type?: string | string[]; // Type of node
+}
+
+/**
+ * Add the schema's JSDoc comment to a TypeScript property signature.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function addJSDocComment(
+  schemaObject: AnnotatedSchemaObject,
+  node: ts.PropertySignature,
+): void {
+  const ts = loadTypeScript();
+  const comment = schemaComment(schemaObject);
+  if (comment) {
+    ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, comment.text, true);
+  }
+}
+
+/** A type argument of the deprecated helpers as TypeScript; IR from type helpers is converted. */
+function legacyTypeNode(type: TypeInput): ts.TypeNode {
+  const ts = loadTypeScript();
+  return typeof type.kind === "string" ? toTypeNode(ts, type as IrType) : (type as ts.TypeNode);
+}
+
+/** Add a helper type alias to the footer once, as a named raw declaration (like the generator). */
+function requireHelper(injectFooter: FooterEntry[], helper: { name: string; text: string }): void {
+  if (!injectFooter.some((entry) => declaresTypeAlias(entry, helper.name))) {
+    injectFooter.push({ kind: "rawDeclaration", name: helper.name, text: helper.text });
+  }
+}
+
+/**
+ * Deduplicate simple primitive types from an array of nodes
+ * Note: won’t deduplicate complex types like objects
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsDedupe(types: TypeInput[]): ts.TypeNode[] {
+  const encounteredTypes = new Set<number>();
+  const filteredTypes: ts.TypeNode[] = [];
+  for (const t of types.map(legacyTypeNode)) {
+    // only mark for deduplication if this is not a const ("text" means it is a const)
+    if (!("text" in ((t as ts.LiteralTypeNode).literal ?? t))) {
+      const { kind } = (t as ts.LiteralTypeNode).literal ?? t;
+      if (encounteredTypes.has(kind)) {
+        continue;
+      }
+      if (tsIsPrimitive(t)) {
+        encounteredTypes.add(kind);
+      }
+    }
+    filteredTypes.push(t);
+  }
+  return filteredTypes;
+}
+
+/** @deprecated The generator keeps its own enum registry per run; kept for 1.x (ADR-004). */
+export const enumCache = new Map<string, ts.EnumDeclaration>();
+
+/**
+ * Create a TS enum (with sanitized name and members)
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsEnum(
+  name: string,
+  members: (string | number)[],
+  metadata?: { name?: string; description?: string | null }[],
+  options?: { export?: boolean; shouldCache?: boolean },
+) {
+  const ts = loadTypeScript();
+  let enumName = sanitizeMemberName(name);
+  enumName = `${enumName.charAt(0).toUpperCase()}${enumName.substring(1)}`;
+  let key = "";
+  if (options?.shouldCache) {
+    key = `${members
+      .slice(0)
+      .sort()
+      .map((v, i) => {
+        return `${metadata?.[i]?.name ?? String(v)}:${metadata?.[i]?.description || ""}`;
+      })
+      .join(",")}`;
+    if (enumCache.has(key)) {
+      return enumCache.get(key) as ts.EnumDeclaration;
+    }
+  }
+  const enumDeclaration = ts.factory.createEnumDeclaration(
+    /* modifiers */ options ? tsModifiers({ export: options.export ?? false }) : undefined,
+    /* name      */ enumName,
+    /* members   */ members.map((value, i) => tsEnumMember(value, metadata?.[i])),
+  );
+  options?.shouldCache && enumCache.set(key, enumDeclaration);
+  return enumDeclaration;
+}
+
+/**
+ * Create an exported TS array literal expression
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsArrayLiteralExpression(
+  name: string,
+  elementType: TypeInput,
+  values: (string | number)[],
+  options?: { export?: boolean; readonly?: boolean; injectFooter?: FooterEntry[] },
+) {
+  const ts = loadTypeScript();
+  let variableName = sanitizeMemberName(name);
+  variableName = `${variableName.charAt(0).toLowerCase()}${variableName.substring(1)}`;
+
+  if (options?.injectFooter) {
+    requireHelper(options.injectFooter, HELPER_TYPES.flattenedDeepRequired);
+  }
+
+  const arrayType = options?.readonly
+    ? tsReadonlyArray(elementType, options.injectFooter)
+    : ts.factory.createArrayTypeNode(legacyTypeNode(elementType));
+
+  return ts.factory.createVariableStatement(
+    options ? tsModifiers({ export: options.export ?? false }) : undefined,
+    ts.factory.createVariableDeclarationList(
+      [
+        ts.factory.createVariableDeclaration(
+          variableName,
+          undefined,
+          arrayType,
+          ts.factory.createArrayLiteralExpression(
+            values.map((value) => toValueExpression(ts, value)),
+          ),
+        ),
+      ],
+      ts.NodeFlags.Const,
+    ),
+  );
+}
+
+function sanitizeMemberName(name: string) {
+  let sanitizedName = name.replace(JS_ENUM_INVALID_CHARS_RE, (c) => {
+    // The pattern matches at least one character, so `last` is always a character.
+    const last = c.at(-1) ?? "";
+    return JS_PROPERTY_INDEX_INVALID_CHARS_RE.test(last) ? "" : last.toUpperCase();
+  });
+  if (Number(name[0]) >= 0) {
+    sanitizedName = `Value${name}`;
+  }
+  return sanitizedName;
+}
+
+/** An enum member name: a valid identifier as is; anything else prefixed, replaced or quoted. */
+function enumMemberName(value: string | number, explicitName: string | undefined): string {
+  let name = explicitName ?? String(value);
+  if (JS_PROPERTY_INDEX_RE.test(name)) {
+    return name;
+  }
+  if (Number(name[0]) >= 0) {
+    // A decimal point is not valid in a name; keep the digits readable.
+    name = `Value${name}`.replace(".", "_");
+  } else if (name[0] === "-") {
+    name = `ValueMinus${name.slice(1)}`;
+  }
+  const invalidCharMatch = name.match(JS_PROPERTY_INDEX_INVALID_CHARS_RE);
+  if (!invalidCharMatch) {
+    return name === "" ? quotedMemberName(name) : name;
+  }
+  if (invalidCharMatch[0] === name) {
+    return quotedMemberName(name);
+  }
+  return name.replace(JS_PROPERTY_INDEX_INVALID_CHARS_RE, (s) =>
+    s in SPECIAL_CHARACTER_MAP ? (SPECIAL_CHARACTER_MAP[s] as string) : "_",
+  );
+}
+
+/**
+ * Sanitize TS enum member expression
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsEnumMember(
+  value: string | number,
+  metadata: { name?: string; description?: string | null } = {},
+) {
+  const ts = loadTypeScript();
+  const name = enumMemberName(value, metadata.name);
+  const member = ts.factory.createEnumMember(name, toValueExpression(ts, value));
+  const trimmedDescription = enumMemberDescription(metadata.description);
+  if (trimmedDescription === "") {
+    return member;
+  }
+
+  return ts.addSyntheticLeadingComment(
+    member,
+    ts.SyntaxKind.SingleLineCommentTrivia,
+    ` ${trimmedDescription}`,
+    true,
+  );
+}
+
+/**
+ * Is this a primitive type (string, number, boolean, null, undefined)?
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsIsPrimitive(input: TypeInput): boolean {
+  const ts = loadTypeScript();
+  if (!input) {
+    return true;
+  }
+  const type = legacyTypeNode(input);
+  return (
+    ts.SyntaxKind[type.kind] === "BooleanKeyword" ||
+    ts.SyntaxKind[type.kind] === "NeverKeyword" ||
+    ts.SyntaxKind[type.kind] === "NullKeyword" ||
+    ts.SyntaxKind[type.kind] === "NumberKeyword" ||
+    ts.SyntaxKind[type.kind] === "StringKeyword" ||
+    ts.SyntaxKind[type.kind] === "UndefinedKeyword" ||
+    ("literal" in type && tsIsPrimitive(type.literal as ts.TypeLiteralNode))
+  );
+}
+
+/**
+ * Modifiers (readonly)
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsModifiers(modifiers: { readonly?: boolean; export?: boolean }): ts.Modifier[] {
+  const ts = loadTypeScript();
+  const typeMods: ts.Modifier[] = [];
+  if (modifiers.export) {
+    typeMods.push(ts.factory.createModifier(ts.SyntaxKind.ExportKeyword));
+  }
+  if (modifiers.readonly) {
+    typeMods.push(ts.factory.createModifier(ts.SyntaxKind.ReadonlyKeyword));
+  }
+  return typeMods;
+}
+
+/**
+ * Create a valid property index
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsPropertyIndex(index: string | number) {
+  const ts = loadTypeScript();
+  if (
+    (typeof index === "number" && !(index < 0)) ||
+    (typeof index === "string" && String(Number(index)) === index && index[0] !== "-")
+  ) {
+    return ts.factory.createNumericLiteral(index);
+  }
+  return typeof index === "string" && JS_PROPERTY_INDEX_RE.test(index)
+    ? ts.factory.createIdentifier(index)
+    : ts.factory.createStringLiteral(String(index));
+}
+
+/**
+ * Enhanced ReadonlyArray.
+ * eg: type Foo = ReadonlyArray<T>; type Bar = ReadonlyArray<T[]>
+ * Foo and Bar are both of type `readonly T[]`
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function tsReadonlyArray(type: TypeInput, injectFooter?: FooterEntry[]): ts.TypeNode {
+  const ts = loadTypeScript();
+  if (injectFooter) {
+    requireHelper(injectFooter, HELPER_TYPES.readonlyArray);
+  }
+  return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("ReadonlyArray"), [
+    legacyTypeNode(type),
+  ]);
+}

package/src/api/legacy-utils.ts

@@ -0,0 +1,118 @@
+import colors from "ansi-colors";
+import { formatDuration } from "../adapters/terminal-logger/terminal-logger.js";
+import type { DebugGroup } from "../application/ports/logger.js";
+import { discriminatorProperty } from "../application/transform/schema/discriminator-property.js";
+import type { IrPropertySignature } from "../domain/ir/nodes.js";
+import { createRef as createDomainRef } from "../domain/openapi/json-pointer.js";
+import type { DiscriminatorObject } from "../types.js";
+import { defaultLogger, terminalSupportsColor } from "./default-ports.js";
+import { type ResolveRefOptions, resolveDocumentRef, walkDocument } from "./document-refs.js";
+
+/**
+ * The original's exported utilities, kept for 1.x (ADR-004, decision 9). The generator itself
+ * logs through the Logger port; `debug`, `warn` and `error` here write through the default one.
+ */
+
+// The exported `c` is the shared ansi-colors instance, switched off at import when the terminal has
+// no colors, as the original did. The generator's own logger uses a separate instance.
+if (!terminalSupportsColor()) {
+  colors.enabled = false;
+}
+
+/**
+ * The shared ansi-colors instance.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9). Use a color library directly.
+ */
+export const c = colors;
+
+/**
+ * The discriminator property of a schema at `path`, typed as its discriminator value. Returns IR
+ * (task 6.2), like the exported transformers.
+ */
+export function createDiscriminatorProperty(
+  discriminator: DiscriminatorObject,
+  { path, readonly = false }: { path: string; readonly?: boolean },
+): IrPropertySignature {
+  return discriminatorProperty(discriminator, path, readonly);
+}
+
+/** Create a $ref pointer (even from other $refs) */
+export function createRef(parts: (number | string | undefined | null)[]): string {
+  return createDomainRef(parts);
+}
+
+/**
+ * Print debug message (cribbed from the `debug` package, but without all the bells & whistles
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function debug(msg: string, group?: string, time?: number) {
+  // Any group name was accepted; one the logger does not know prints in white, as before.
+  defaultLogger(false).debug(msg, group as DebugGroup | undefined, time);
+}
+
+/**
+ * Print error message
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function error(msg: string) {
+  defaultLogger(false).error(msg);
+}
+
+/** Format a performance log in a friendly format */
+export function formatTime(t: number) {
+  return typeof t === "number" ? formatDuration(t) : t;
+}
+
+/** Call Object.entries() and optionally sort */
+export function getEntries<T>(
+  obj: ArrayLike<T> | Record<string, T>,
+  options?: {
+    alphabetize?: boolean;
+    excludeDeprecated?: boolean;
+  },
+) {
+  let entries = Object.entries(obj);
+  if (options?.alphabetize) {
+    entries.sort(([a], [b]) => a.localeCompare(b, "en-us", { numeric: true }));
+  }
+  if (options?.excludeDeprecated) {
+    entries = entries.filter(
+      ([, v]) => !(v && typeof v === "object" && "deprecated" in v && v.deprecated),
+    );
+  }
+  return entries;
+}
+
+export type { ResolveRefOptions } from "./document-refs.js";
+
+/**
+ * resolve a $ref in a schema
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function resolveRef<T>(
+  schema: any,
+  $ref: string,
+  options: ResolveRefOptions,
+): T | undefined {
+  return resolveDocumentRef<T>(schema, $ref, options);
+}
+
+/**
+ * Walk through any JSON-serializable (i.e. non-circular) object
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function walk(
+  obj: unknown,
+  cb: (value: Record<string, unknown>, path: (string | number)[]) => void,
+  path: (string | number)[] = [],
+): void {
+  walkDocument(obj, cb, path);
+}
+
+/**
+ * Print warning message
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function warn(msg: string, silent = false) {
+  defaultLogger(silent).warn(msg);
+}

package/src/api/openapi-ts.ts

@@ -0,0 +1,62 @@
+import { createRedoclySchemaLoader } from "../adapters/redocly-loader/redocly-schema-loader.js";
+import { withStackOverflowReported } from "../application/stack-overflow.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+import type { GeneratorOptions, SchemaSource } from "../types.js";
+import {
+  defaultLogger,
+  defaultRedoclyConfig,
+  monotonicNow,
+  REMOTE_REF_TIMEOUT_MS,
+} from "./default-ports.js";
+import { createDocumentRun, type GeneratorPorts } from "./document-run.js";
+import transformSchema from "./transform-schema.js";
+
+/**
+ * The Node API's composition root (ENGINEERING_PLAN 4.5): `openapiTS` wires the default adapters;
+ * `generateDeclarations` runs with any ports, which is how the CLI calls it.
+ */
+
+/** Load, validate and bundle the source, then transform it into IR declarations. */
+export async function generateDeclarations(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<IrDeclaration[]> {
+  const { schema, ctx } = await createDocumentRun(source, options, ports);
+  const startedAt = ports.now();
+  const result = withStackOverflowReported("transform", () => transformSchema(schema, ctx));
+  ports.logger.debug(
+    "Completed AST transformation for entire document",
+    "ts",
+    ports.now() - startedAt,
+  );
+  return result;
+}
+
+/** The default ports: the terminal logger, the given or default Redocly config, Redocly loading. */
+export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<GeneratorPorts> {
+  const logger = defaultLogger(options.silent ?? false);
+  const redoc = options.redocly ?? (await defaultRedoclyConfig());
+  const loader = createRedoclySchemaLoader({
+    redoc,
+    logger,
+    now: monotonicNow,
+    remoteRefTimeoutMs: REMOTE_REF_TIMEOUT_MS,
+  });
+  return { loader, logger, redoc, now: monotonicNow };
+}
+
+/**
+ * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
+ * @param {string|URL|object|Readable} source OpenAPI schema source:
+ *   - YAML: string
+ *   - JSON: parsed object
+ *   - URL: URL to a YAML or JSON file (local or remote)
+ *   - Readable: Readable stream of YAML or JSON
+ */
+export default async function openapiTS(
+  source: SchemaSource,
+  options: GeneratorOptions = {},
+): Promise<IrDeclaration[]> {
+  return generateDeclarations(source, options, await defaultGeneratorPorts(options));
+}

package/src/api/path-template-warnings.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "../application/ports/logger.js";
+import { findIdenticalPathTemplates } from "../domain/openapi/path-templates.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+
+const DOCS_URL =
+  "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/cli.md#pathparamsastypes";
+const SPEC_RULE =
+  "OpenAPI does not allow this (Paths Object): templated paths with the same hierarchy but " +
+  "different templated names MUST NOT exist as they are identical";
+
+/** `"/a"`, `"/a" and "/b"`, `"/a", "/b" and "/c"`. */
+function quotedList(urls: readonly string[]): string {
+  const quoted = urls.map((url) => `"${url}"`);
+  const last = quoted.pop();
+  return quoted.length === 0 ? (last ?? "") : `${quoted.join(", ")} and ${last}`;
+}
+
+/**
+ * Warn once per group of paths that differ only in parameter names, which the spec forbids: a URL
+ * cannot tell them apart, and `--path-params-as-types` gives them the same key type.
+ */
+export function warnIdenticalPathTemplates(document: unknown, logger: Logger): void {
+  for (const urls of findIdenticalPathTemplates(document)) {
+    const message = `Paths ${quotedList(urls)} differ only in their parameter names. ${SPEC_RULE}`;
+    logger.warn(warningText(`${message}. See ${DOCS_URL}`, WARNING_CODES.PATH_TEMPLATES_IDENTICAL));
+  }
+}