openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.4

package/src/cli/api-writes.ts

@@ -0,0 +1,117 @@
+import type { ClaimedFile } from "../application/ports/file-system.js";
+import type { GeneratedTypes } from "./cli-dependencies.js";
+import {
+  type CliRun,
+  duplicateOutputError,
+  emitOutput,
+  ensureOutputIsNotSchema,
+  type NamedFile,
+  type OutputFile,
+} from "./cli-output.js";
+
+/**
+ * Writing the generated APIs of a Redocly config. Before the first byte is written, every output
+ * is claimed: a missing one is created empty, so the file system gives it its own identity. Two
+ * APIs whose files then have one identity fail with `CLI_OUTPUT_DUPLICATE` and write nothing,
+ * also when their names looked different (ADR-043, decision 1).
+ */
+
+/** An API whose types are generated and not written yet. */
+export interface GeneratedApi {
+  readonly name: string;
+  readonly outputFile: OutputFile;
+  readonly types: GeneratedTypes;
+}
+
+/** An API whose output is claimed; `claim` is undefined with `--check`, which writes nothing. */
+interface ClaimedApi {
+  readonly api: GeneratedApi;
+  readonly claim: ClaimedFile | undefined;
+}
+
+/** The failures of the API an API name maps to; an API without failures was written. */
+type ApiFailures = Map<string, unknown[]>;
+
+/** The failure of a step, as a list: empty when it succeeded. */
+export function failuresOf(step: () => void): unknown[] {
+  try {
+    step();
+    return [];
+  } catch (failure) {
+    return [failure];
+  }
+}
+
+/** Claim the output of each API; an API whose claim fails gets that failure instead. */
+function claimOutputs(run: CliRun, apis: readonly GeneratedApi[], failures: ApiFailures) {
+  const claimed: ClaimedApi[] = [];
+  for (const api of apis) {
+    try {
+      const claim = run.args.isCheck ? undefined : run.deps.files.claimFile(api.outputFile.file);
+      claimed.push({ api, claim });
+    } catch (failure) {
+      failures.set(api.name, [failure]);
+    }
+  }
+  return claimed;
+}
+
+/** The APIs that share their claimed file with another, by API name, with the other names. */
+function sharedOutputs(claimed: readonly ClaimedApi[]): Map<string, string[]> {
+  const byIdentity = new Map<string, string[]>();
+  for (const { api, claim } of claimed) {
+    if (claim) {
+      byIdentity.set(claim.identity, [...(byIdentity.get(claim.identity) ?? []), api.name]);
+    }
+  }
+  const shared = new Map<string, string[]>();
+  for (const names of byIdentity.values()) {
+    for (const name of names.length > 1 ? names : []) {
+      shared.set(
+        name,
+        names.filter((other) => other !== name).map((other) => `API ${other}`),
+      );
+    }
+  }
+  return shared;
+}
+
+/** Write one claimed API; a failed write releases the claim, so no empty file is left. */
+function writeClaimed(run: CliRun, { api, claim }: ClaimedApi): unknown[] {
+  const failures = failuresOf(() => emitOutput(run, api.outputFile, api.types.contents));
+  return failures.length > 0 && claim
+    ? [...failures, ...failuresOf(() => claim.release())]
+    : failures;
+}
+
+/**
+ * Write (or `--check`) every API unless its output is a file the run read or the file of another
+ * API. Returns the failures by API name. Claims are released in reverse order, so a directory
+ * one claim created is empty by the time it is removed.
+ */
+export function writeGeneratedApis(
+  run: CliRun,
+  apis: readonly GeneratedApi[],
+  readFiles: readonly NamedFile[],
+): ApiFailures {
+  const failures: ApiFailures = new Map();
+  const ownOutputs = apis.filter((api) => {
+    const failure = failuresOf(() => ensureOutputIsNotSchema(run, api.outputFile, readFiles));
+    failures.set(api.name, failure);
+    return failure.length === 0;
+  });
+  const claimed = claimOutputs(run, ownOutputs, failures);
+  const shared = sharedOutputs(claimed);
+  for (const entry of [...claimed].reverse()) {
+    const { api, claim } = entry;
+    const others = shared.get(api.name);
+    if (others) {
+      const release = claim ? failuresOf(() => claim.release()) : [];
+      failures.set(api.name, [duplicateOutputError(api.outputFile, others), ...release]);
+    }
+  }
+  for (const entry of claimed.filter(({ api }) => !shared.has(api.name))) {
+    failures.set(entry.api.name, writeClaimed(run, entry));
+  }
+  return failures;
+}

package/src/cli/cli-dependencies.ts

@@ -1,5 +1,11 @@
 import type { Readable } from "node:stream";
-import type { FileReader, FileWriter } from "../application/ports/file-system.js";
+import type {
+  DirectoryCheck,
+  FileClaims,
+  FileIdentity,
+  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";
@@ -19,8 +25,19 @@ export interface TextStyle {
   dim(text: string): string;
 }
 
-/** Generate the printed declarations, with the comment header, for one schema. */
-export type GenerateTypes = (source: SchemaSource, options: GeneratorOptions) => Promise<string>;
+/** The printed declarations of one schema, and the local files they were generated from. */
+export interface GeneratedTypes {
+  /** The declarations, with the comment header. */
+  readonly contents: string;
+  /** The schema, when it is a local file, and every local file its `$ref`s loaded. */
+  readonly localFiles: readonly URL[];
+}
+
+/** Generate the types of one schema. */
+export type GenerateTypes = (
+  source: SchemaSource,
+  options: GeneratorOptions,
+) => Promise<GeneratedTypes>;
 
 export interface CliDependencies {
   /** The working directory, as a directory URL (with a trailing slash). */
@@ -38,7 +55,7 @@ export interface CliDependencies {
    * input with no prompt, which looks like a hang (upstream #1905).
    */
   readonly isStdinTerminal: () => boolean;
-  readonly files: FileReader & FileWriter;
+  readonly files: FileReader & FileWriter & FileIdentity & DirectoryCheck & FileClaims;
   readonly redoclyConfigs: RedoclyConfigSource;
   readonly generate: GenerateTypes;
   /** A monotonic time in milliseconds, for the time printed after each output. */

package/src/cli/cli-errors.ts

@@ -68,9 +68,24 @@ function parseFailedMessage(error: OpenAPITypesafeError): string {
   );
 }
 
+/**
+ * Text piped into stdin that is only a YAML string (`echo api.yaml | openapi-typesafe`) gets the
+ * CLI's advice, not the Node API's (`openapiTS(pathToFileURL(path))`).
+ */
+function sourceInvalidMessage(error: OpenAPITypesafeError): string {
+  const { received, text } = error.details;
+  if (received !== "stream" || typeof text !== "string") {
+    return error.message;
+  }
+  return (
+    `stdin held only the YAML string "${text}", not an OpenAPI document. To read a file, pass ` +
+    "its path or URL as the first argument: openapi-typesafe ./openapi.yaml -o ./schema.ts"
+  );
+}
+
 const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   SCHEMA_SOURCE_EMPTY: { exitCode: EXIT_CODES.SCHEMA },
-  SCHEMA_SOURCE_INVALID: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_SOURCE_INVALID: { exitCode: EXIT_CODES.SCHEMA, message: sourceInvalidMessage },
   SCHEMA_LOAD_FAILED: { exitCode: EXIT_CODES.SCHEMA, message: loadFailedMessage },
   SCHEMA_PARSE_FAILED: { exitCode: EXIT_CODES.SCHEMA, message: parseFailedMessage },
   SCHEMA_VERSION_UNSUPPORTED: { exitCode: EXIT_CODES.SCHEMA },
@@ -92,6 +107,10 @@ const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   CLI_CONFIG_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
   CLI_CHECK_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
   CLI_INPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
+  CLI_OUTPUT_IS_INPUT: { exitCode: EXIT_CODES.USAGE },
+  CLI_OUTPUT_DUPLICATE: { exitCode: EXIT_CODES.USAGE },
+  CLI_OUTPUT_INVALID: { exitCode: EXIT_CODES.USAGE },
+  CLI_LOCATION_INVALID: { exitCode: EXIT_CODES.USAGE },
   OUTPUT_STALE: { exitCode: EXIT_CODES.OUTPUT_STALE },
   OUTPUT_READ_FAILED: { exitCode: EXIT_CODES.OUTPUT },
   OUTPUT_WRITE_FAILED: { exitCode: EXIT_CODES.OUTPUT },

package/src/cli/cli-output.ts

@@ -1,8 +1,10 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { formatDuration } from "../adapters/terminal-logger/terminal-logger.js";
+import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
+import { redactUnparsedUrl } from "../domain/url-secrets.js";
 import type { CliArguments } from "./cli-arguments.js";
-import type { CliDependencies } from "./cli-dependencies.js";
+import type { CliDependencies, GeneratedTypes } from "./cli-dependencies.js";
 import { cliError } from "./cli-errors.js";
 
 /** Writing one generated file, or checking it with `--check`, and the line printed for it. */
@@ -14,10 +16,14 @@ export interface CliRun {
   readonly startedAt: number;
 }
 
-/** A generated file: `source` names the schema and `output` is the path as the user wrote it. */
-export interface OutputFile {
+/** An output as the user wrote it: `source` names the schema, `output` is the path or URL. */
+export interface NamedOutput {
   readonly source: string;
   readonly output: string;
+}
+
+/** A generated file: an output with the location of its local file. */
+export interface OutputFile extends NamedOutput {
   readonly file: URL;
 }
 
@@ -28,18 +34,180 @@ export interface OutputFile {
 const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
 
 /**
- * The URL of a location the user wrote: a URL as it is, else a file path, absolute or relative to
- * the directory of `base` (a directory or file URL). A path is not parsed as a URL, so `#`, `?` and
- * `%` are part of the file name.
+ * The URL of a location the user wrote: a URL, else a file path, absolute or relative to the
+ * directory of `base` (a directory or file URL). A relative `file:` URL (`file:api.yaml`) resolves
+ * against `base` too, as in openapi-typescript. A path is not parsed as a URL, so `#`, `?` and `%`
+ * are part of the file name. A location with a scheme that does not parse as a URL
+ * (`http://[::1/x`) fails with `CLI_LOCATION_INVALID`.
  */
 export function resolveLocationUrl(location: string, base: URL): URL {
   if (URL_SCHEME.test(location)) {
-    return new URL(location);
+    const url = URL.parse(location, base.href);
+    if (url === null) {
+      const shown = redactUnparsedUrl(location);
+      throw cliError("CLI_LOCATION_INVALID", `The location ${shown} is not a valid URL`);
+    }
+    return url;
   }
   const baseDirectory = fileURLToPath(new URL(".", base));
   return pathToFileURL(path.resolve(baseDirectory, location));
 }
 
+const FILE_PROTOCOL = "file:";
+
+/** Segments that name a directory: the directory itself and its parent. */
+const DIRECTORY_SEGMENTS: ReadonlySet<string> = new Set([".", ".."]);
+
+/**
+ * Whether the location names a directory as written, before resolving drops the sign: a trailing
+ * `/` (or `\\` on Windows), or a last segment `.` or `..` (`-o gen/.`, `-o a/b/..`). For a URL
+ * the parsed path tells it too, since the URL parser drops `.`, `..` and their `%2E` forms.
+ */
+function namesDirectory(location: string, file: URL): boolean {
+  const lastSegment = location
+    .split(path.sep)
+    .flatMap((part) => part.split("/"))
+    .at(-1);
+  return (
+    lastSegment === "" || DIRECTORY_SEGMENTS.has(lastSegment ?? "") || file.pathname.endsWith("/")
+  );
+}
+
+function invalidOutput(output: string, reason: string): Error {
+  return cliError("CLI_OUTPUT_INVALID", `The output ${output} ${reason}`);
+}
+
+/** The URL of the output, if it is a local file that can be written; it may not exist yet. */
+function outputUrlOf(run: CliRun, output: string, base: URL): URL {
+  const file = parseLocationUrl(output, base);
+  if (file?.protocol !== FILE_PROTOCOL) {
+    throw invalidOutput(
+      output,
+      "is not a local file. Write the types to a file path or a file: URL.",
+    );
+  }
+  if (!isLocalFile(file)) {
+    throw invalidOutput(output, "names no file on this computer. Use a file path instead.");
+  }
+  if (namesDirectory(output, file) || run.deps.files.isDirectory(file)) {
+    throw invalidOutput(output, "is a directory. Name the file to write the types to in it.");
+  }
+  return file;
+}
+
+/** A `file:` URL with a host, or with an encoded slash, names no path on this platform. */
+function isLocalFile(file: URL): boolean {
+  try {
+    fileURLToPath(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The output file of `source`, as the user wrote it in `output`, relative to `base`. Fails with
+ * `CLI_OUTPUT_INVALID` before anything is generated when it is not a local file (a URL of
+ * another scheme) or is a directory (a trailing separator, a last segment `.` or `..`, or a
+ * directory on disk). Without this check, `-o dir/` and `-o dir/.` wrote a file named `dir`.
+ */
+export function outputFileOf(run: CliRun, named: NamedOutput, base: URL): OutputFile {
+  return { ...named, file: outputUrlOf(run, named.output, base) };
+}
+
+/** A file the CLI reads or writes: `name` is how an error names it, `location` where it is. */
+export interface NamedFile {
+  readonly name: string;
+  readonly location: URL;
+}
+
+/** The `files` that are the local file `output`, also through a link or in another letter case. */
+function filesAtOutput(run: CliRun, output: OutputFile, files: readonly NamedFile[]): NamedFile[] {
+  return files.filter(
+    ({ location }) =>
+      location.protocol === FILE_PROTOCOL && run.deps.files.isSameFile(location, output.file),
+  );
+}
+
+/** A location as a path relative to the working directory, as error messages name files. */
+function displayPathOf(run: CliRun, location: URL): string {
+  return path.relative(fileURLToPath(run.deps.cwd), fileURLToPath(location)) || ".";
+}
+
+/** The Redocly config file the run read, if any: no output may replace it. */
+export function redoclyConfigFiles(run: CliRun, redocly: RedoclyConfig): NamedFile[] {
+  if (!redocly.configFile) {
+    return [];
+  }
+  const location = resolveLocationUrl(redocly.configFile, run.deps.cwd);
+  return [{ name: `Redocly config ${displayPathOf(run, location)}`, location }];
+}
+
+/** The local files that `owner` (a schema or an API) was generated from, `$ref`'d ones too. */
+export function filesReadBy(run: CliRun, types: GeneratedTypes, owner: string): NamedFile[] {
+  return types.localFiles.map((location) => ({
+    name: `schema ${displayPathOf(run, location)} that ${owner} reads`,
+    location,
+  }));
+}
+
+/**
+ * Fail with `CLI_OUTPUT_IS_INPUT` when `output` is one of the `schemas` (or the Redocly config).
+ * Writing it would replace that file with the types, which upstream did without a word. The CLI
+ * checks the files it knows before generating, so nothing is loaded or written, and the files
+ * that `$ref`s loaded after generating, before anything is written.
+ */
+export function ensureOutputIsNotSchema(
+  run: CliRun,
+  output: OutputFile,
+  schemas: readonly NamedFile[],
+): void {
+  const [schema] = filesAtOutput(run, output, schemas);
+  if (schema) {
+    throw cliError(
+      "CLI_OUTPUT_IS_INPUT",
+      `The output ${output.output} is the ${schema.name}: writing the types would ` +
+        "overwrite it. Choose another output file.",
+    );
+  }
+}
+
+/**
+ * Fail with `CLI_OUTPUT_DUPLICATE` when the output of an API is also one of `otherOutputs`.
+ * Whichever write came last would win, so every API with that output fails, before anything is
+ * generated.
+ */
+export function ensureOutputIsOwn(
+  run: CliRun,
+  output: OutputFile,
+  otherOutputs: readonly NamedFile[],
+): void {
+  const clashes = filesAtOutput(run, output, otherOutputs);
+  if (clashes.length > 0) {
+    throw duplicateOutputError(
+      output,
+      clashes.map(({ name }) => name),
+    );
+  }
+}
+
+/** `CLI_OUTPUT_DUPLICATE` for `output`, which is also the output of the `others` (named). */
+export function duplicateOutputError(output: NamedOutput, others: readonly string[]): Error {
+  return cliError(
+    "CLI_OUTPUT_DUPLICATE",
+    `The output ${output.output} of API ${output.source} is also the output of ` +
+      `${others.join(", ")}: they would overwrite each other. Give each API its own output file.`,
+  );
+}
+
+/** As `resolveLocationUrl`, but undefined for a URL that does not parse instead of a throw. */
+export function parseLocationUrl(location: string, base: URL): URL | undefined {
+  if (URL_SCHEME.test(location)) {
+    return URL.parse(location, base.href) ?? undefined;
+  }
+  return resolveLocationUrl(location, base);
+}
+
 function printDone(run: CliRun, output: OutputFile): void {
   const { style, now } = run.deps;
   const target = style.green(`${output.source} → ${style.bold(output.output)}`);
@@ -65,3 +233,14 @@ export function emitOutput(run: CliRun, output: OutputFile, contents: string): v
   run.deps.files.writeText(output.file, contents);
   printDone(run, output);
 }
+
+/** Write (or `--check`) the types, unless the output is one of the files the run read. */
+export function writeOutput(
+  run: CliRun,
+  output: OutputFile,
+  types: GeneratedTypes,
+  readFiles: readonly NamedFile[],
+): void {
+  ensureOutputIsNotSchema(run, output, readFiles);
+  emitOutput(run, output, types.contents);
+}

package/src/cli/main.ts

@@ -7,7 +7,7 @@ import { createRedoclyConfigSource } from "../adapters/redocly-loader/redocly-co
 import { astToString } from "../api/ast-to-string.js";
 import { COMMENT_HEADER } from "../api/comment-header.js";
 import { defaultLogger, monotonicNow, terminalSupportsColor } from "../api/default-ports.js";
-import openapiTS from "../api/openapi-ts.js";
+import { defaultGeneratorPorts, generateDocument } from "../api/openapi-ts.js";
 import type { CliConsole, CliDependencies, GenerateTypes, TextStyle } from "./cli-dependencies.js";
 import { runCli } from "./run-cli.js";
 
@@ -36,8 +36,11 @@ function terminalStyle(): TextStyle {
 
 const STDIN_DESCRIPTOR = 0;
 
-const generateTypes: GenerateTypes = async (source, options) =>
-  `${COMMENT_HEADER}${astToString(await openapiTS(source, options))}`;
+const generateTypes: GenerateTypes = async (source, options) => {
+  const ports = await defaultGeneratorPorts(options);
+  const { declarations, localFiles } = await generateDocument(source, options, ports);
+  return { contents: `${COMMENT_HEADER}${astToString(declarations)}`, localFiles };
+};
 
 function terminalConsole(): CliConsole {
   return {