openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,196 @@
+import type { IrComment, IrPropertySignature } from "../../domain/ir/nodes.js";
+import { OutputFix } from "../../domain/output-fixes.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;
+/** The member lists whose descriptions `anyof-oneof-descriptions` adds, with their headings. */
+const MEMBER_LISTS = [
+  ["anyOf", "Any of:"],
+  ["oneOf", "One of:"],
+] as const;
+/** The later lines of a member's description are indented under its bullet. */
+const BULLET_CONTINUATION = "\n  ";
+
+/** How a schema's JSDoc is written. */
+export interface SchemaCommentOptions {
+  /** `anyof-oneof-descriptions`: the descriptions of `anyOf` and `oneOf` members are listed. */
+  readonly hasMemberDescriptions: boolean;
+}
+
+/** The JSDoc the original writes. */
+export const ORIGINAL_SCHEMA_COMMENT: SchemaCommentOptions = { hasMemberDescriptions: false };
+
+/** How the fixes turned on write a schema's JSDoc. */
+export function schemaCommentOptionsOf(fixes: ReadonlySet<OutputFix>): SchemaCommentOptions {
+  return { hasMemberDescriptions: fixes.has(OutputFix.ANYOF_ONEOF_DESCRIPTIONS) };
+}
+
+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 own, non-blank `description` of each member; a member without one is left out. */
+function memberDescriptions(members: unknown): string[] {
+  if (!Array.isArray(members)) {
+    return [];
+  }
+  return members.flatMap((member: unknown) => {
+    const description = isSchemaObject(member) ? member.description : undefined;
+    return typeof description === "string" && description.trim() !== "" ? [description.trim()] : [];
+  });
+}
+
+/** Each member list with a described member, as a heading and one bullet per description. */
+function memberDescriptionLists(schema: SchemaRecord): string[] {
+  return MEMBER_LISTS.flatMap(([keyword, heading]) => {
+    const descriptions = memberDescriptions(schema[keyword]);
+    if (descriptions.length === 0) {
+      return [];
+    }
+    const bullets = descriptions.map(
+      (description) => `- ${description.replace(LINE_BREAK_RE, BULLET_CONTINUATION)}`,
+    );
+    return [[heading, ...bullets].join("\n")];
+  });
+}
+
+/**
+ * The schema with the descriptions of its `anyOf` and `oneOf` members after its own description
+ * (upstream #2142). A member's description holds only where that member applies, so each one is
+ * listed under its keyword rather than merged into one sentence. A `description` that is not a
+ * string is kept as it is.
+ */
+function withMemberDescriptions(schema: SchemaRecord): AnnotatedSchema {
+  const lists = memberDescriptionLists(schema);
+  const own = schema.description;
+  if (lists.length === 0 || (own !== undefined && typeof own !== "string")) {
+    // As the original, the keywords are read as they are, without validating them.
+    return schema as AnnotatedSchema;
+  }
+  const ownLines = typeof own === "string" && own.trim() !== "" ? [own.trim()] : [];
+  return { ...(schema as AnnotatedSchema), description: [...ownLines, ...lists].join("\n") };
+}
+
+/** A schema object read without knowing its keywords. */
+interface SchemaRecord {
+  readonly description?: unknown;
+  readonly [keyword: string]: unknown;
+}
+
+function isSchemaObject(value: unknown): value is SchemaRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 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,
+  options: SchemaCommentOptions = ORIGINAL_SCHEMA_COMMENT,
+): IrComment | null {
+  if (!isSchemaObject(schema)) {
+    return null;
+  }
+  const annotated = options.hasMemberDescriptions
+    ? withMemberDescriptions(schema)
+    : (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,
+  options: SchemaCommentOptions = ORIGINAL_SCHEMA_COMMENT,
+): IrPropertySignature {
+  const comment = schemaComment(schema, options);
+  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,208 @@
+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, argv: readonly string[]): string[] {
+  const names = Object.keys(parsed)
+    .filter((key) => key !== "_" && key !== "--" && !KNOWN_FLAGS.has(key))
+    .map((key) => writtenFlagName(key, argv));
+  return [...new Set(names)];
+}
+
+/** The flag as the user wrote it: yargs-parser reads `--no-x` as `x: false`. */
+function writtenFlagName(key: string, argv: readonly string[]): string {
+  if (key.length === 1) {
+    return `-${key}`;
+  }
+  const negated = `--no-${kebabCase(key)}`;
+  const isNegated = argv.some((arg) => arg === negated || arg.startsWith(`${negated}=`));
+  return isNegated ? negated : `--${kebabCase(key)}`;
+}
+
+/**
+ * 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, argv),
+  };
+}

package/src/cli/cli-dependencies.ts

@@ -0,0 +1,47 @@
+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;
+  /**
+   * Whether stdin is a terminal. Then nothing is piped in, and reading it would wait for typed
+   * input with no prompt, which looks like a hang (upstream #1905).
+   */
+  readonly isStdinTerminal: () => boolean;
+  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;
+}