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

package/src/adapters/node-file-system/file-identity.ts

@@ -0,0 +1,137 @@
+import path from "node:path";
+
+/**
+ * The identity of a file path, also of one that does not exist yet (an output before the first
+ * run). Two paths are one file when their keys are equal: the real path of the nearest existing
+ * ancestor (links resolved, letter case as stored on disk) followed by the segments that do not
+ * exist yet, compared in the letter case rules of the file system that will hold them. Equal keys
+ * prove one file; different keys do not prove two (Unicode normalization, full case folding):
+ * the CLI claims every output before writing to decide those (ADR-043, decision 1).
+ */
+
+/** A device and a file number: one file, also through a hard link. */
+export interface FileNumber {
+  readonly device: bigint;
+  readonly file: bigint;
+}
+
+/** The file-system queries the identity needs; Node's `fs` in production, a fake in tests. */
+export interface PathQueries {
+  /** The file number of a path, following links; undefined when it cannot be read. */
+  status(filePath: string): FileNumber | undefined;
+  /** The path with every link resolved, in the letter case stored on disk. */
+  realPath(filePath: string): string;
+  /** The names in a directory; empty when it cannot be listed. */
+  entries(directory: string): readonly string[];
+  /** The target of a symbolic link as written in it; undefined for a path that is no link. */
+  linkTarget(filePath: string): string | undefined;
+}
+
+/**
+ * The most links followed for one path. Linux follows at most 40 (MAXSYMLINKS) and macOS 32
+ * before it fails with ELOOP; a longer chain is a loop, and the path is taken as missing.
+ */
+const MAX_LINK_HOPS = 40;
+
+/** Whether two file numbers name one file. */
+export function isSameFileNumber(left: FileNumber, right: FileNumber): boolean {
+  // Some file systems (FAT, some network shares) report no file number: 0 then proves nothing.
+  return left.file !== 0n && left.file === right.file && left.device === right.device;
+}
+
+function hasLetters(text: string): boolean {
+  return text.toLowerCase() !== text.toUpperCase();
+}
+
+function flipCase(text: string): string {
+  return [...text]
+    .map((character) => {
+      const upper = character.toUpperCase();
+      return character === upper ? character.toLowerCase() : upper;
+    })
+    .join("");
+}
+
+/** Whether a directory entry is also found under its name in the other letter case. */
+function isFoundInOtherCase(entryPath: string, queries: PathQueries): boolean | undefined {
+  const status = queries.status(entryPath);
+  if (!status) {
+    return undefined;
+  }
+  const flipped = path.join(path.dirname(entryPath), flipCase(path.basename(entryPath)));
+  const flippedStatus = queries.status(flipped);
+  return flippedStatus !== undefined && isSameFileNumber(status, flippedStatus);
+}
+
+/**
+ * Whether new names in `directory` ignore letter case. It is asked of the file system, not
+ * assumed from the OS: macOS and Windows volumes can be case-sensitive, and Linux mounts can
+ * ignore case. An entry of the directory is looked up in the other case; without one with
+ * letters, the directory itself is. With nothing to look up, names are taken as case-sensitive.
+ */
+function ignoresCase(directory: string, queries: PathQueries): boolean {
+  const candidates = [
+    ...queries
+      .entries(directory)
+      .filter(hasLetters)
+      .map((name) => path.join(directory, name)),
+    ...(hasLetters(path.basename(directory)) ? [directory] : []),
+  ];
+  for (const candidate of candidates) {
+    const answer = isFoundInOtherCase(candidate, queries);
+    if (answer !== undefined) {
+      return answer;
+    }
+  }
+  return false;
+}
+
+/**
+ * The nearest ancestor of `filePath` that exists (or the path itself), and the rest below it. A
+ * link to a missing file or directory is followed to its target, which a write would create: so
+ * `link/x.ts` with `link -> missing` is `missing/x.ts`. A relative target is read from the real
+ * directory of the link, as the system does: with `a -> real/sub` and
+ * `real/sub/link -> ../missing`, `a/link` is `real/missing`, not `missing`.
+ */
+function nearestExisting(filePath: string, queries: PathQueries): [string, string[]] {
+  const missing: string[] = [];
+  let current = path.resolve(filePath);
+  let hops = 0;
+  while (queries.status(current) === undefined) {
+    const target = hops < MAX_LINK_HOPS ? queries.linkTarget(current) : undefined;
+    if (target !== undefined) {
+      current = path.resolve(queries.realPath(path.dirname(current)), target);
+      hops += 1;
+      continue;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    missing.unshift(path.basename(current));
+    current = parent;
+  }
+  return [current, missing];
+}
+
+/**
+ * The path that a write to `filePath` creates, with links followed also where their target is
+ * missing: `link/x.ts` with `link -> missing` is the real path of `missing/x.ts`. `mkdir` does not
+ * follow a link to a missing directory on Linux and Windows, so the directories are created here.
+ */
+export function creationPath(filePath: string, queries: PathQueries): string {
+  const [existing, missing] = nearestExisting(filePath, queries);
+  return path.join(queries.realPath(existing), ...missing);
+}
+
+/** The key of a path: equal keys are one file, whether or not it exists yet. */
+export function fileIdentityKey(filePath: string, queries: PathQueries): string {
+  const [existing, missing] = nearestExisting(filePath, queries);
+  const realExisting = queries.realPath(existing);
+  if (missing.length === 0) {
+    return realExisting;
+  }
+  const isCaseIgnored = ignoresCase(realExisting, queries);
+  const rest = isCaseIgnored ? missing.map((segment) => segment.toLowerCase()) : missing;
+  return path.join(realExisting, ...rest);
+}

package/src/adapters/node-file-system/node-file-system.ts

@@ -1,7 +1,22 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-import type { FileReader, FileWriter } from "../../application/ports/file-system.js";
-import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import type {
+  ClaimedFile,
+  DirectoryCheck,
+  FileCheck,
+  FileClaims,
+  FileIdentity,
+  FileReader,
+  FileWriter,
+} from "../../application/ports/file-system.js";
+import { ERROR_CODES, type ErrorCode, OpenAPITypesafeError } from "../../domain/errors.js";
+import { claimFileAt, writeFileAt } from "./file-claims.js";
+import {
+  type FileNumber,
+  fileIdentityKey,
+  isSameFileNumber,
+  type PathQueries,
+} from "./file-identity.js";
 
 /** The file ports on Node's `fs`, with the failures as typed errors (ADR-011). */
 
@@ -9,36 +24,161 @@ function causeMessage(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }
 
-class NodeFileSystem implements FileReader, FileWriter {
+/**
+ * The file number of a path, or undefined when it cannot be read. A missing output is the common
+ * case; any other failure (no access, a file used as a directory) is reported by the read or write
+ * that follows, so the identity check does not report it a second time.
+ */
+function statusOf(filePath: string): FileNumber | undefined {
+  try {
+    const status = fs.statSync(filePath, { bigint: true });
+    return { device: status.dev, file: status.ino };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The native `realpath` resolves symbolic links and returns the letter case stored on disk, which
+ * the JavaScript one does not do on a case-insensitive file system. A path that vanished since its
+ * status was read keeps its own spelling.
+ */
+function realPathOf(filePath: string): string {
+  try {
+    return fs.realpathSync.native(filePath);
+  } catch {
+    return filePath;
+  }
+}
+
+/** A directory that cannot be listed has no entry to tell its letter case rules by. */
+function entriesOf(directory: string): readonly string[] {
+  try {
+    return fs.readdirSync(directory);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The target of a symbolic link, as written in it; undefined for a path that is no link or cannot
+ * be read. The key then treats the path as missing, and the claim at write time decides.
+ */
+function linkTargetOf(filePath: string): string | undefined {
+  try {
+    return fs.readlinkSync(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+const NODE_PATH_QUERIES: PathQueries = {
+  status: statusOf,
+  realPath: realPathOf,
+  entries: entriesOf,
+  linkTarget: linkTargetOf,
+};
+
+/** The path of a `file:` URL, or undefined for a URL that names no file on this platform. */
+function localPathOf(file: URL): string | undefined {
+  try {
+    return fileURLToPath(file);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A failed read or write as a typed error. The location is named by its path, or by the URL when
+ * it names no local file: computing the path must not throw a second, untyped error here.
+ */
+function fileError(code: ErrorCode, verb: string, file: URL, cause: unknown): OpenAPITypesafeError {
+  const name = localPathOf(file) ?? file.href;
+  return new OpenAPITypesafeError({
+    code,
+    message: `Cannot ${verb} ${name}: ${causeMessage(cause)}`,
+    details: { file: name },
+    cause,
+  });
+}
+
+/** Run a step that writes `file`, with its failure as `OUTPUT_WRITE_FAILED`. */
+function typedWrite<T>(file: URL, step: () => T): T {
+  try {
+    return step();
+  } catch (cause) {
+    throw fileError(ERROR_CODES.OUTPUT_WRITE_FAILED, "write", file, cause);
+  }
+}
+
+class NodeFileSystem
+  implements FileReader, FileWriter, FileIdentity, DirectoryCheck, FileCheck, FileClaims
+{
   readText(file: URL): string {
     try {
       return fs.readFileSync(file, "utf8");
     } catch (cause) {
-      throw new OpenAPITypesafeError({
-        code: ERROR_CODES.OUTPUT_READ_FAILED,
-        message: `Cannot read ${fileURLToPath(file)}: ${causeMessage(cause)}`,
-        details: { file: fileURLToPath(file) },
-        cause,
-      });
+      throw fileError(ERROR_CODES.OUTPUT_READ_FAILED, "read", file, cause);
     }
   }
 
   writeText(file: URL, contents: string): void {
     try {
-      fs.mkdirSync(new URL(".", file), { recursive: true });
-      fs.writeFileSync(file, contents, "utf8");
+      writeFileAt(fileURLToPath(file), contents, NODE_PATH_QUERIES);
     } catch (cause) {
-      throw new OpenAPITypesafeError({
-        code: ERROR_CODES.OUTPUT_WRITE_FAILED,
-        message: `Cannot write ${fileURLToPath(file)}: ${causeMessage(cause)}`,
-        details: { file: fileURLToPath(file) },
-        cause,
-      });
+      throw fileError(ERROR_CODES.OUTPUT_WRITE_FAILED, "write", file, cause);
+    }
+  }
+
+  claimFile(file: URL): ClaimedFile {
+    const claim = typedWrite(file, () => claimFileAt(fileURLToPath(file), NODE_PATH_QUERIES));
+    return {
+      identity: claim.identity,
+      release: () => typedWrite(file, () => claim.release()),
+    };
+  }
+
+  isDirectory(file: URL): boolean {
+    try {
+      return fs.statSync(file).isDirectory();
+    } catch {
+      // Missing or unreadable: not a directory; the write that follows reports a failure.
+      return false;
+    }
+  }
+
+  isFile(file: URL): boolean {
+    try {
+      return fs.statSync(file).isFile();
+    } catch {
+      // Missing or unreadable: no file; the read that follows reports a failure.
+      return false;
+    }
+  }
+
+  isSameFile(left: URL, right: URL): boolean {
+    const leftPath = fileURLToPath(left);
+    const rightPath = fileURLToPath(right);
+    if (leftPath === rightPath) {
+      return true;
+    }
+    const leftStatus = statusOf(leftPath);
+    const rightStatus = statusOf(rightPath);
+    if (leftStatus && rightStatus && isSameFileNumber(leftStatus, rightStatus)) {
+      return true;
     }
+    return (
+      fileIdentityKey(leftPath, NODE_PATH_QUERIES) === fileIdentityKey(rightPath, NODE_PATH_QUERIES)
+    );
   }
 }
 
 /** File access for the CLI. */
-export function createNodeFileSystem(): FileReader & FileWriter {
+export function createNodeFileSystem(): FileReader &
+  FileWriter &
+  FileIdentity &
+  DirectoryCheck &
+  FileCheck &
+  FileClaims {
   return new NodeFileSystem();
 }

package/src/adapters/pipe-safe-writer/pipe-safe-writer.ts

@@ -0,0 +1,29 @@
+import type { Writable } from "node:stream";
+
+/**
+ * A writer for the CLI's stdout that stops when the reader closes the pipe (`| head`): the write
+ * fails with `EPIPE`, which Node raises as an unhandled `error` event and a crash with exit code
+ * 1. The reader has all it wanted, so the rest is dropped and the run ends as it would have.
+ * Every other write error is thrown again, as before.
+ */
+
+const BROKEN_PIPE = "EPIPE";
+
+function isBrokenPipe(error: Error): boolean {
+  return (error as NodeJS.ErrnoException).code === BROKEN_PIPE;
+}
+
+/**
+ * The text writer of the stream. After `EPIPE` the stream is destroyed, so later writes are
+ * dropped by the stream itself and raise no second error.
+ */
+export function createPipeSafeWriter(stream: Writable): (text: string) => void {
+  stream.on("error", (error: Error) => {
+    if (!isBrokenPipe(error)) {
+      throw error;
+    }
+  });
+  return (text) => {
+    stream.write(text);
+  };
+}

package/src/adapters/redocly-loader/bundled-mapping-copies.ts

@@ -0,0 +1,60 @@
+import { childPointer } from "../../domain/openapi/json-pointer.js";
+import { type ComponentSchemas, componentSchemasOf, SCHEMAS_POINTER } from "./component-schemas.js";
+import { findMappings, findRefHolders } from "./ref-holders.js";
+
+/**
+ * Redocly 1.x bundles every discriminator `mapping` value as if it were an external `$ref`: it
+ * stores the target schema under the raw last segment of the pointer. For a local schema whose
+ * key needs an escape (`a~b`, written `a~0b`; `c/d`, written `c~1d`) that segment is no existing
+ * key, so the bundle added `a~0b` and `c~1d` to `components.schemas` as copies of `a~b` and
+ * `c/d`, and the generator wrote each type twice. A copy is the very object of the schema it
+ * copies, so a key the bundle added whose value is the value of a key the document had is removed,
+ * and the mapping values and `$ref`s that name it point at the original.
+ */
+
+/** The keys of `components.schemas` before bundling: the bundle edits the document in place. */
+export function schemaKeysOf(document: unknown): ReadonlySet<string> {
+  return new Set(Object.keys(componentSchemasOf(document) ?? {}));
+}
+
+/** Each key the bundle added as a copy, with the pointer of the schema it copies. */
+function copiesIn(schemas: ComponentSchemas, keysBefore: ReadonlySet<string>): Map<string, string> {
+  const originals = new Map<unknown, string>();
+  for (const key of keysBefore) {
+    if (Object.hasOwn(schemas, key) && !originals.has(schemas[key])) {
+      originals.set(schemas[key], key);
+    }
+  }
+  const copies = new Map<string, string>();
+  for (const [key, value] of Object.entries(schemas)) {
+    const original = keysBefore.has(key) ? undefined : originals.get(value);
+    if (original !== undefined) {
+      copies.set(`${SCHEMAS_POINTER}/${key}`, childPointer(SCHEMAS_POINTER, original));
+      delete schemas[key];
+    }
+  }
+  return copies;
+}
+
+/** Remove the bundle's copies of the document's own schemas, in place. */
+export function removeBundledMappingCopies(
+  bundled: unknown,
+  keysBefore: ReadonlySet<string>,
+): void {
+  const schemas = componentSchemasOf(bundled);
+  const copies = schemas === undefined ? new Map<string, string>() : copiesIn(schemas, keysBefore);
+  if (copies.size === 0) {
+    return;
+  }
+  for (const mapping of findMappings(bundled)) {
+    for (const [name, value] of Object.entries(mapping)) {
+      const original = typeof value === "string" ? copies.get(value) : undefined;
+      if (original !== undefined) {
+        mapping[name] = original;
+      }
+    }
+  }
+  for (const { node } of findRefHolders(bundled)) {
+    node.$ref = copies.get(node.$ref) ?? node.$ref;
+  }
+}

package/src/adapters/redocly-loader/bundled-ref-repair.ts

@@ -1,4 +1,4 @@
-import { escapePointerSegment, parseRefPointer } from "../../domain/openapi/json-pointer.js";
+import { childPointer, parseRefPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
 import { findRefHolders } from "./ref-holders.js";
 
 /**
@@ -48,7 +48,7 @@ function repairedRef(document: unknown, ref: string): string | null {
   if (!resolves(document, raw)) {
     return null;
   }
-  return `${LOCAL_REF_PREFIX}${raw.map(escapePointerSegment).join("/")}`;
+  return raw.reduce((pointer, key) => childPointer(pointer, key), ROOT_POINTER);
 }
 
 /** Repair the local `$ref`s of a bundled document in place, as Redocly's bundle edits it. */

package/src/adapters/redocly-loader/component-schemas.ts

@@ -0,0 +1,19 @@
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
+
+/** `components.schemas` of a parsed document, which the loader repairs in place. */
+
+export type ComponentSchemas = Record<string, unknown>;
+
+/** `#/components/schemas`. */
+export const SCHEMAS_POINTER = childPointer(childPointer(ROOT_POINTER, "components"), "schemas");
+
+function isContainer(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** The `components.schemas` object of a document, when it has one. */
+export function componentSchemasOf(document: unknown): ComponentSchemas | undefined {
+  const components = isContainer(document) ? document.components : undefined;
+  const schemas = isContainer(components) ? components.schemas : undefined;
+  return isContainer(schemas) ? schemas : undefined;
+}

package/src/adapters/redocly-loader/loaded-documents.ts

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { BaseResolver, Document } from "@redocly/openapi-core";
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/** The documents one load read, from the Redocly resolver's cache. */
+
+/**
+ * The root document and every other document the resolver loaded, as far as they parsed. A root
+ * read from a file or URL is in the resolver cache too, and is listed once. A `$ref` that failed
+ * to load leaves a rejected entry in the cache, also when bundling did not need it (an example's
+ * `$ref`): that entry is no document, and must not fail the listing.
+ */
+export async function loadedDocuments(
+  root: Document,
+  resolver: BaseResolver,
+): Promise<LoadedDocument[]> {
+  const settled = await Promise.allSettled(resolver.cache.values());
+  const cached = settled.flatMap((entry) => (entry.status === "fulfilled" ? [entry.value] : []));
+  const bySource = new Map<string, unknown>([[root.source.absoluteRef, root.parsed]]);
+  for (const document of cached) {
+    if ("parsed" in document && !bySource.has(document.source.absoluteRef)) {
+      bySource.set(document.source.absoluteRef, document.parsed);
+    }
+  }
+  return [...bySource].map(([source, parsed]) => ({ source, parsed }));
+}
+
+/**
+ * The local files the load read: the root, when it is a file, and every `$ref`'d file. Redocly
+ * names a local document by its absolute path and a remote one by its URL. An inline root (a
+ * string, object, buffer or stream) has a made-up path in the working directory, so it is left
+ * out unless it was read from a file.
+ */
+export async function localFilesRead(
+  root: Document,
+  resolver: BaseResolver,
+  isRootAFile: boolean,
+): Promise<URL[]> {
+  const documents = await loadedDocuments(root, resolver);
+  return documents
+    .map(({ source }) => source)
+    .filter((source) => path.isAbsolute(source))
+    .filter((source) => isRootAFile || source !== root.source.absoluteRef)
+    .map((source) => pathToFileURL(source));
+}

package/src/adapters/redocly-loader/mapping-schema-names.ts

@@ -0,0 +1,25 @@
+import { childPointer } from "../../domain/openapi/json-pointer.js";
+import { componentSchemasOf, SCHEMAS_POINTER } from "./component-schemas.js";
+import { findMappings } from "./ref-holders.js";
+
+/**
+ * A discriminator `mapping` value may be a schema name (`cat: Cat`) or a URI reference. Redocly
+ * reads every value as a `$ref`, so a name failed with "Can't resolve $ref". OpenAPI 3.1.1
+ * (§4.8.25) leaves a value that is both to the implementation and recommends the schema name; a
+ * relative URI is then written `./Cat`. So a value that is a key of the document's
+ * `components.schemas` becomes the pointer to that schema, in place, before the `$ref`s are
+ * resolved. Any other value stays a URI reference.
+ */
+export function pointMappingNamesAtSchemas(document: unknown): void {
+  const schemas = componentSchemasOf(document);
+  if (schemas === undefined) {
+    return;
+  }
+  for (const mapping of findMappings(document)) {
+    for (const [name, value] of Object.entries(mapping)) {
+      if (typeof value === "string" && Object.hasOwn(schemas, value)) {
+        mapping[name] = childPointer(SCHEMAS_POINTER, value);
+      }
+    }
+  }
+}