openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/application/transform/schema/unevaluated-properties.ts

@@ -0,0 +1,105 @@
+import {
+  irKeyword,
+  irObject,
+  irReference,
+  irStringIndexSignature,
+} from "../../../domain/ir/constructors.js";
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { HELPER_TYPES } from "../helper-types.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { unionOf } from "../type-combinators.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * The `unevaluated-properties` fix (ADR-021, roadmap R11; upstream #2839, #2880). Without it
+ * `unevaluatedProperties` is ignored, so its value type is lost and an object with only that
+ * keyword is `Record<string, never>`. With it the composed type is intersected with an index
+ * signature, as `additionalProperties` gives: every key that no other keyword declares has the
+ * `unevaluatedProperties` type. TypeScript checks that index signature against every key of a
+ * value, declared ones included, so its type also holds the types of the declared properties
+ * (of this schema and of its `allOf`, `anyOf` and `oneOf` members); otherwise a valid value would
+ * not be assignable. `false` adds nothing, like `additionalProperties: false`: TypeScript has no
+ * closed object type.
+ */
+
+/**
+ * Whether `unevaluatedProperties` applies. It types the keys left over at this level, so it
+ * does nothing next to `additionalProperties` (which already types them all), and only an object
+ * schema has keys. A `type` list is typed one listed type at a time, so its object gets it.
+ */
+function unevaluatedSchemaOf(schema: SchemaObject, request: SchemaRequest): Schema | null {
+  const { unevaluatedProperties } = schema;
+  if (
+    !request.context.options.fixes.has(OutputFix.UNEVALUATED_PROPERTIES) ||
+    unevaluatedProperties === undefined ||
+    unevaluatedProperties === false ||
+    schema.additionalProperties !== undefined
+  ) {
+    return null;
+  }
+  return schema.type === undefined || schema.type === "object" ? unevaluatedProperties : null;
+}
+
+function isAnySchema(schema: Schema): boolean {
+  return schema === true || (typeof schema === "object" && Object.keys(schema).length === 0);
+}
+
+function memberValueTypes(member: IrMember): IrType[] {
+  if (member.kind === "indexSignature") {
+    return [member.type];
+  }
+  return member.isOptional ? [member.type, irKeyword("undefined")] : [member.type];
+}
+
+/**
+ * The value types a key of the composed type can have, read from its IR: the members of object
+ * types, through unions and intersections. A reference (a `$ref`, `Omit`, `WithRequired`) or a raw
+ * type is read with `PropertyValues`. Primitives, literals and arrays declare no keys.
+ */
+function declaredValueTypes(type: IrType, request: SchemaRequest): IrType[] {
+  switch (type.kind) {
+    case "object":
+      return type.members.flatMap(memberValueTypes);
+    case "union":
+    case "intersection":
+      return type.types.flatMap((member) => declaredValueTypes(member, request));
+    case "reference":
+    case "indexedAccess":
+    case "raw":
+      request.context.footer.requirePropertyValues();
+      return [irReference(HELPER_TYPES.propertyValues.name, [type])];
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+    case "array":
+    case "tuple":
+    case "readonly":
+      return [];
+  }
+}
+
+/**
+ * The index signature object for `unevaluatedProperties`, given the composed type of the other
+ * keywords (null when there is none). Null when the fix is off or the keyword does not apply.
+ */
+export function unevaluatedPropertiesType(
+  schema: SchemaObject,
+  composed: IrType | null,
+  request: SchemaRequest,
+): IrType | null {
+  const unevaluated = unevaluatedSchemaOf(schema, request);
+  if (unevaluated === null) {
+    return null;
+  }
+  const valueTypes = isAnySchema(unevaluated)
+    ? [UNKNOWN_TYPE]
+    : [
+        request.transformNested(unevaluated, request.location, true),
+        ...(composed === null ? [] : declaredValueTypes(composed, request)),
+      ];
+  const { immutable } = request.context.options;
+  return irObject([irStringIndexSignature("key", unionOf(valueTypes), immutable)]);
+}

package/src/application/transform/schema-comment.ts

@@ -0,0 +1,116 @@
+import type { IrComment, IrPropertySignature } from "../../domain/ir/nodes.js";
+
+/** Schema fields that produce JSDoc lines (the original `AnnotatedSchemaObject`). */
+export interface AnnotatedSchema {
+  readonly const?: unknown;
+  readonly default?: unknown;
+  readonly deprecated?: boolean;
+  readonly description?: string;
+  readonly enum?: unknown[];
+  readonly example?: unknown;
+  readonly examples?: unknown;
+  readonly format?: string;
+  readonly nullable?: boolean;
+  readonly summary?: string;
+  readonly title?: string;
+  readonly type?: string | string[];
+}
+
+const LINE_BREAK_RE = /\r?\n/g;
+/** Continuation lines of a multi-line value are indented under the tag. */
+const CONTINUATION = "\n *     ";
+const COMMENT_END_RE = /\*\//g;
+/** Tags written as `@tag value`; an empty string is kept only where it is a meaningful value. */
+const VALUE_TAGS = ["description", "default", "example"] as const;
+const TAGS_KEEPING_EMPTY_STRING: ReadonlySet<string> = new Set(["default", "example"]);
+const JSON_INDENT = 2;
+
+function formatValue(value: unknown): string {
+  const text = typeof value === "object" ? JSON.stringify(value, null, JSON_INDENT) : value;
+  return String(text).trim().replace(LINE_BREAK_RE, CONTINUATION);
+}
+
+function plainLines(schema: AnnotatedSchema): string[] {
+  const lines: string[] = [];
+  for (const text of [schema.title, schema.summary]) {
+    // The document is not validated against the schema dialect: a property named `summary`
+    // written without `properties:` makes `summary` an object (upstream #2349).
+    if (typeof text === "string" && text) {
+      lines.push(text.trim().replace(LINE_BREAK_RE, CONTINUATION));
+    }
+  }
+  if (schema.format) {
+    lines.push(`Format: ${schema.format}`);
+  }
+  if (schema.deprecated) {
+    lines.push("@deprecated");
+  }
+  return lines;
+}
+
+function valueTagLines(schema: AnnotatedSchema): string[] {
+  const lines: string[] = [];
+  for (const tag of VALUE_TAGS) {
+    const value = schema[tag];
+    if (value === undefined || (value === "" && !TAGS_KEEPING_EMPTY_STRING.has(tag))) {
+      continue;
+    }
+    lines.push(`@${tag} ${formatValue(value)}`);
+  }
+  if (Array.isArray(schema.examples)) {
+    lines.push(...schema.examples.map((example: unknown) => `@example ${formatValue(example)}`));
+  }
+  return lines;
+}
+
+function enumTypeName(schema: AnnotatedSchema): string {
+  if (Array.isArray(schema.type)) {
+    return schema.type.join("|");
+  }
+  return typeof schema.type === "string" ? schema.type : "unknown";
+}
+
+function constantAndEnumLines(schema: AnnotatedSchema): string[] {
+  const lines: string[] = [];
+  if ("const" in schema) {
+    lines.push("@constant");
+  }
+  if (schema.enum) {
+    lines.push(`@enum {${enumTypeName(schema)}${schema.nullable ? "|null" : ""}}`);
+  }
+  return lines;
+}
+
+/**
+ * The JSDoc comment the original writes for a schema (`addJSDocComment`): title, summary and
+ * format, then `@deprecated`, `@description`, `@default`, `@example`, `@constant` and `@enum`
+ * tags. One short line stays on the `/**` line; anything else is a block. Returns null when there
+ * is nothing to say, or when the value is not a schema object.
+ */
+export function schemaComment(schema: unknown): IrComment | null {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return null;
+  }
+  const annotated = schema as AnnotatedSchema;
+  const lines = [
+    ...plainLines(annotated),
+    ...valueTagLines(annotated),
+    ...constantAndEnumLines(annotated),
+  ];
+  if (lines.length === 0) {
+    return null;
+  }
+  const isSingleLine = lines.length === 1 && !lines.some((line) => line.includes("\n"));
+  const text = isSingleLine ? `* ${lines.join("\n")} ` : `*\n * ${lines.join("\n * ")}\n `;
+  // A `*/` inside a value would end the comment early.
+  return { kind: "block", text: text.replace(COMMENT_END_RE, "*\\/") };
+}
+
+/** The property with the schema's JSDoc added after the comments it already has. */
+export function withSchemaComment(
+  property: IrPropertySignature,
+  schema: unknown,
+): IrPropertySignature {
+  const comment = schemaComment(schema);
+  return comment === null ? property : { ...property, comments: [...property.comments, comment] };
+}

package/src/application/transform/shared-types.ts

@@ -0,0 +1,9 @@
+import { irKeyword } from "../../domain/ir/constructors.js";
+import type { IrKeywordType } from "../../domain/ir/nodes.js";
+
+/**
+ * The shared `unknown` node. The original compares types with its shared `UNKNOWN` node by
+ * identity (a nullable schema whose type *is* that node stays `unknown`), so the transformers use
+ * one frozen node for the same cases, and the legacy adapter maps the original constant to it.
+ */
+export const UNKNOWN_TYPE: IrKeywordType = Object.freeze(irKeyword("unknown"));

package/src/application/transform/transform-context.ts

@@ -0,0 +1,51 @@
+import type { IrPropertySignature } from "../../domain/ir/nodes.js";
+import type { FooterDeclarations, SchemaContext, SchemaOptions } from "./schema/schema-context.js";
+
+/** Options of the transformers above schemas. They grow as parents are ported (Phase 5). */
+export interface TransformOptions extends SchemaOptions {
+  /** `--generate-path-params`: add path template parameters that the document does not define. */
+  readonly generatePathParams: boolean;
+  /** `--path-params-as-types`: key templated paths by a template literal type. */
+  readonly pathParamsAsTypes: boolean;
+  /** `--root-types`: export an alias per component, like `SchemaPet`. */
+  readonly rootTypes: boolean;
+  /** `--root-types-no-schema-prefix`: `Pet` instead of `SchemaPet` for schemas. */
+  readonly rootTypesNoSchemaPrefix: boolean;
+  /** `--root-types-keep-casing`: keep schema names as written instead of PascalCase. */
+  readonly rootTypesKeepCasing: boolean;
+  /** `--export-type`: root types are type aliases instead of interfaces. */
+  readonly exportType: boolean;
+  /** Code added as is after the helper types (Node API `inject`). */
+  readonly inject: string | undefined;
+  /** `--make-paths-enum`: add the `ApiPaths` enum of all operation URLs. */
+  readonly makePathsEnum: boolean;
+}
+
+/** Name casing for generated identifiers (the original uses the `change-case` package). */
+export interface NameCasing {
+  pascalCase(text: string): string;
+}
+
+/** Declarations after the main types, including the top-level `operations` interface. */
+export interface DocumentFooter extends FooterDeclarations {
+  /**
+   * Add a member to the `operations` interface. The interface is declared before `build` runs, so
+   * it comes before any declaration the operation adds, as in the original.
+   */
+  addOperation(build: () => IrPropertySignature): void;
+}
+
+/** Debug output for slow parts of a run (`DEBUG=openapi-ts:*`). */
+export interface TransformDiagnostics {
+  /** A monotonic time in milliseconds, used only to measure durations. */
+  now(): number;
+  debug(message: string, durationMs: number): void;
+}
+
+/** The context of the document transformers: the schema context with their options and ports. */
+export interface TransformContext extends SchemaContext {
+  readonly options: TransformOptions;
+  readonly footer: DocumentFooter;
+  readonly diagnostics: TransformDiagnostics;
+  readonly casing: NameCasing;
+}

package/src/application/transform/type-combinators.ts

@@ -0,0 +1,57 @@
+import { irIntersection, irKeyword, irReference, irUnion } from "../../domain/ir/constructors.js";
+import type { IrType } from "../../domain/ir/nodes.js";
+import { dedupeTypes } from "../../domain/ir/normalize.js";
+import { literalType } from "./literal-type.js";
+
+/**
+ * Type combinators with the original helper semantics (`tsUnion`, `tsIntersection`, `tsOmit`, …).
+ * They are the only places where the transformers normalize types.
+ */
+
+/** `never` for no types, the type itself for one, else a de-duplicated union (`tsUnion`). */
+export function unionOf(types: readonly IrType[]): IrType {
+  if (types.length <= 1) {
+    return types[0] ?? irKeyword("never");
+  }
+  return irUnion(dedupeTypes(types));
+}
+
+/** Like `unionOf`, for intersections (`tsIntersection`). */
+export function intersectionOf(types: readonly IrType[]): IrType {
+  if (types.length <= 1) {
+    return types[0] ?? irKeyword("never");
+  }
+  return irIntersection(dedupeTypes(types));
+}
+
+/** `T | null` without de-duplication (`tsNullable`). */
+export function nullableOf(types: readonly IrType[]): IrType {
+  return irUnion([...types, irKeyword("null")]);
+}
+
+/** `Omit<T, "a" | "b">`; the key union is never collapsed or de-duplicated (`tsOmit`). */
+export function omitKeys(type: IrType, keys: readonly string[]): IrType {
+  return irReference("Omit", [type, irUnion(keys.map(literalType))]);
+}
+
+/** `WithRequired<T, "a" | "b">`, or the type itself for no keys (`tsWithRequired`). */
+export function withRequiredKeys(type: IrType, keys: readonly string[]): IrType {
+  if (keys.length === 0) {
+    return type;
+  }
+  return irReference("WithRequired", [type, unionOf(keys.map(literalType))]);
+}
+
+/** Primitive keywords, as the original `tsIsPrimitive` defines them (the null literal included). */
+const PRIMITIVE_KEYWORDS: ReadonlySet<string> = new Set([
+  "boolean",
+  "never",
+  "null",
+  "number",
+  "string",
+  "undefined",
+]);
+
+export function isPrimitiveType(type: IrType): boolean {
+  return type.kind === "keyword" && PRIMITIVE_KEYWORDS.has(type.keyword);
+}

package/src/cli/cli-arguments.ts

@@ -0,0 +1,198 @@
+import { kebabCase } from "scule";
+import parser from "yargs-parser";
+import type { OutputFixName } from "../domain/output-fixes.js";
+import { cliError } from "./cli-errors.js";
+import { fixNamesOf } from "./fix-option.js";
+
+/** The CLI's arguments, parsed as the original CLI parsed them (yargs-parser). */
+
+/** Boolean flags that become generator options (camelCase; yargs also accepts kebab-case). */
+export const GENERATOR_FLAGS = [
+  "additionalProperties",
+  "alphabetize",
+  "arrayLength",
+  "binaryAsBlob",
+  "conditionalEnums",
+  "dedupeEnums",
+  "defaultNonNullable",
+  "emptyObjectsUnknown",
+  "enum",
+  "enumValues",
+  "excludeDeprecated",
+  "exportType",
+  "generatePathParams",
+  "immutable",
+  "lint",
+  "makePathsEnum",
+  "pathParamsAsTypes",
+  "propertiesRequiredByDefault",
+  "readWriteMarkers",
+  "rootTypes",
+  "rootTypesKeepCasing",
+  "rootTypesNoSchemaPrefix",
+] as const;
+
+export type GeneratorFlag = (typeof GENERATOR_FLAGS)[number];
+
+export type GeneratorFlags = Readonly<Partial<Record<GeneratorFlag, boolean>>>;
+
+// `contentNever` was a boolean flag of the original CLI that no code reads; it stays in the list
+// so that `--content-never <input>` keeps parsing as a flag and an input.
+const CAMEL_CASE_BOOLEAN_FLAGS = [...GENERATOR_FLAGS, "check", "contentNever", "help"];
+
+// yargs-parser matches the `boolean` list by the exact spelling of the flag: with camelCase names
+// only, `--root-types schema.yaml` took the path as the flag's value (upstream #2523). Both
+// spellings are listed.
+const BOOLEAN_FLAGS = [
+  ...CAMEL_CASE_BOOLEAN_FLAGS,
+  ...CAMEL_CASE_BOOLEAN_FLAGS.map((flag) => kebabCase(flag)),
+];
+
+/** The `$ref` limits as the user wrote them; unset flags are absent. */
+export interface CliRefLimits {
+  readonly localRefRoot?: string;
+  readonly remoteRefHosts?: readonly string[];
+}
+
+export interface CliArguments {
+  /** The schema path or URL; none means stdin, or the APIs of the Redocly config. */
+  readonly input: string | undefined;
+  readonly output: string | undefined;
+  readonly redocly: string | undefined;
+  readonly isCheck: boolean;
+  readonly isHelp: boolean;
+  readonly isVersion: boolean;
+  readonly generatorFlags: GeneratorFlags;
+  readonly refLimits: CliRefLimits;
+  /** `--fix`, comma-separated and repeatable (ADR-021); unset when the flag is not given. */
+  readonly fix: readonly OutputFixName[] | undefined;
+  /** Flags the CLI does not know, as written on the command line (`--bogus`, `-x`). */
+  readonly unknownFlags: readonly string[];
+}
+
+/** Flags of older versions that were removed or renamed, with the message for each. */
+const REMOVED_FLAGS: readonly (readonly [string, string])[] = [
+  ["-ap", `The -ap alias has been deprecated. Use "--additional-properties" instead.`],
+  ["--immutable-types", `The --immutable-types flag has been renamed to "--immutable".`],
+  [
+    "--support-array-length",
+    `The --support-array-length flag has been renamed to "--array-length".`,
+  ],
+  ["-it", `The -it alias has been deprecated. Use "--immutable" instead.`],
+  ["--redoc", `The --redoc config flag has been renamed to "--redocly" (or -c as shorthand).`],
+];
+
+/** Flags that only work together with `--root-types`. */
+const ROOT_TYPES_FLAGS = ["--root-types-no-schema-prefix", "--root-types-keep-casing"] as const;
+
+function rejectRemovedFlags(argv: readonly string[]): void {
+  for (const [flag, message] of REMOVED_FLAGS) {
+    if (argv.includes(flag)) {
+      throw cliError("CLI_FLAG_REMOVED", message);
+    }
+  }
+}
+
+/** Notices for flags that have no effect in this combination, printed before the run. */
+export function ineffectiveFlagNotices(argv: readonly string[]): string[] {
+  if (argv.includes("--root-types")) {
+    return [];
+  }
+  return ROOT_TYPES_FLAGS.filter((flag) => argv.includes(flag)).map(
+    (flag) => `${flag} has no effect without --root-types flag`,
+  );
+}
+
+function generatorFlagsOf(parsed: parser.Arguments): GeneratorFlags {
+  const flags: Partial<Record<GeneratorFlag, boolean>> = {};
+  for (const name of GENERATOR_FLAGS) {
+    if (typeof parsed[name] === "boolean") {
+      flags[name] = parsed[name];
+    }
+  }
+  return flags;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return value === undefined ? undefined : String(value);
+}
+
+/** The last value of a flag that may be given more than once. */
+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 {
+  if (value === undefined) {
+    return undefined;
+  }
+  return [value]
+    .flat()
+    .flatMap((entry) => String(entry).split(","))
+    .map((host) => host.trim())
+    .filter((host) => host !== "");
+}
+
+function refLimitsOf(parsed: parser.Arguments): CliRefLimits {
+  const localRefRoot = lastString(parsed.localRefRoot);
+  const remoteRefHosts = hostList(parsed.remoteRefHosts);
+  return {
+    ...(localRefRoot === undefined ? {} : { localRefRoot }),
+    ...(remoteRefHosts === undefined ? {} : { remoteRefHosts }),
+  };
+}
+
+/** String flags, in both spellings, so that a value such as `8080` is not read as a number. */
+const STRING_FLAGS = [
+  "output",
+  "redocly",
+  "fix",
+  ...["localRefRoot", "remoteRefHosts"].flatMap((flag) => [flag, kebabCase(flag)]),
+];
+
+const ALIASES = { redocly: ["c"], exportType: ["t"], output: ["o"] };
+
+/** Every name yargs-parser can return for a flag this CLI reads. */
+const KNOWN_FLAGS = new Set<string>([
+  ...BOOLEAN_FLAGS,
+  ...STRING_FLAGS,
+  ...Object.values(ALIASES).flat(),
+  "version",
+]);
+
+/**
+ * Flags that no code reads. The original CLI ignored them silently, so a typo such as
+ * `--alphabetise` gave other output with no hint; they still do not fail the run.
+ */
+function unknownFlagsOf(parsed: parser.Arguments): string[] {
+  const names = Object.keys(parsed)
+    .filter((key) => key !== "_" && key !== "--" && !KNOWN_FLAGS.has(key))
+    .map((key) => (key.length === 1 ? `-${key}` : `--${kebabCase(key)}`));
+  return [...new Set(names)];
+}
+
+/**
+ * Parse the arguments after `node cli.js`. Fails with `CLI_FLAG_REMOVED` for an old flag and with
+ * `OPTION_FIX_UNKNOWN` for an unknown `--fix` name.
+ */
+export function parseCliArguments(argv: readonly string[]): CliArguments {
+  rejectRemovedFlags(argv);
+  const parsed = parser([...argv], {
+    boolean: BOOLEAN_FLAGS,
+    string: STRING_FLAGS,
+    alias: ALIASES,
+  });
+  return {
+    input: optionalString(parsed._[0]),
+    output: optionalString(parsed.output),
+    redocly: optionalString(parsed.redocly),
+    isCheck: parsed.check === true,
+    isHelp: "help" in parsed,
+    isVersion: "version" in parsed,
+    generatorFlags: generatorFlagsOf(parsed),
+    refLimits: refLimitsOf(parsed),
+    fix: fixNamesOf(parsed.fix),
+    unknownFlags: unknownFlagsOf(parsed),
+  };
+}

package/src/cli/cli-dependencies.ts

@@ -0,0 +1,42 @@
+import type { Readable } from "node:stream";
+import type { FileReader, FileWriter } from "../application/ports/file-system.js";
+import type { Logger } from "../application/ports/logger.js";
+import type { RedoclyConfigSource } from "../application/ports/redocly-config-source.js";
+import type { GeneratorOptions, SchemaSource } from "../types.js";
+
+/** What the CLI needs from the outside world; `main.ts` wires the real adapters (ADR-012). */
+
+/** Plain output lines: `info` goes to stdout, `notice` to stderr, both without a prefix. */
+export interface CliConsole {
+  info(text: string): void;
+  notice(text: string): void;
+}
+
+/** The terminal styles of the CLI's own lines; they return the text unchanged without colors. */
+export interface TextStyle {
+  bold(text: string): string;
+  green(text: string): string;
+  dim(text: string): string;
+}
+
+/** Generate the printed declarations, with the comment header, for one schema. */
+export type GenerateTypes = (source: SchemaSource, options: GeneratorOptions) => Promise<string>;
+
+export interface CliDependencies {
+  /** The working directory, as a directory URL (with a trailing slash). */
+  readonly cwd: URL;
+  readonly version: string;
+  /** Warnings and the final error line; never silent. */
+  readonly logger: Logger;
+  readonly console: CliConsole;
+  /** The generated types when there is no `--output`. */
+  readonly writeStdout: (text: string) => void;
+  /** Read only when the schema comes from stdin: opening it early can keep the process alive. */
+  readonly stdin: () => Readable;
+  readonly files: FileReader & FileWriter;
+  readonly redoclyConfigs: RedoclyConfigSource;
+  readonly generate: GenerateTypes;
+  /** A monotonic time in milliseconds, for the time printed after each output. */
+  readonly now: () => number;
+  readonly style: TextStyle;
+}