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

package/src/domain/cause-secrets.ts

@@ -3,31 +3,55 @@ import { redactUrlSecrets } from "./url-secrets.js";
 /**
  * The `cause` of a typed error is shown wherever the error is: `console.error(error)` and
  * `util.inspect` print the whole chain, and error trackers send it. A lower-level error names the
- * URL it failed on (fetch refuses `https://user:token@host/…` and quotes it), so the chain must
- * hide the same secrets as the message (url-secrets.ts).
+ * URL it failed on (fetch refuses `https://user:token@host/…` and quotes it), and may keep it in
+ * nested objects too (Redocly's parse error holds `originalError.mark.name` and
+ * `source.absoluteRef`), so the chain must hide the same secrets as the message (url-secrets.ts)
+ * at every depth.
  */
 
-/** A string with its URL secrets hidden; any other value as it is. */
-function redactedValue(value: unknown): unknown {
-  return typeof value === "string" ? redactUrlSecrets(value) : value;
+/**
+ * How deep the walk copies a cause. The data of a cause is shallow (Redocly's deepest URL is three
+ * levels below the error); a value below this depth is dropped, so no secret is kept unread.
+ */
+const MAX_CAUSE_DEPTH = 8;
+
+interface Walk {
+  /** The objects on the way from the cause to the value, so a cycle is cut where it closes. */
+  readonly path: ReadonlySet<object>;
+  readonly depth: number;
+}
+
+function deeper(walk: Walk, value: object): Walk {
+  return { path: new Set([...walk.path, value]), depth: walk.depth + 1 };
+}
+
+/** An array with each item hidden, or the array itself when no item holds a secret. */
+function redactedArray(array: readonly unknown[], walk: Walk): readonly unknown[] {
+  const inner = deeper(walk, array);
+  const items = array.map((item) => redactedValue(item, inner));
+  return items.every((item, index) => item === array[index]) ? array : items;
 }
 
 /**
- * A copy of `error` of the same class, its own properties (`message`, `stack`, `code`, `input`, a
- * nested `cause`) with URL secrets hidden, or `error` itself when none of them holds one. Each
- * property is read through its getter (V8 keeps `stack` behind one) and copied as a value.
+ * A copy of `value` with the same prototype, its own properties (`message`, `stack`, `code`,
+ * `input`, a nested `cause` or object) with URL secrets hidden, or `value` itself when none of
+ * them holds one. Each property is read through its getter (V8 keeps `stack` behind one) and
+ * copied as a value.
  */
-function redactedError(error: Error, seen: ReadonlySet<Error>): Error {
-  const inner = new Set([...seen, error]);
-  // A real error with the class of `error`, so `util.inspect` and `util.types.isNativeError`
-  // treat it as one.
-  const copy = Object.setPrototypeOf(new Error(), Object.getPrototypeOf(error)) as Error;
+function redactedObject(value: object, walk: Walk): object {
+  const inner = deeper(walk, value);
+  // An error is copied as a real error, so `util.inspect` and `util.types.isNativeError` treat
+  // the copy as one.
+  const copy: object =
+    value instanceof Error
+      ? Object.setPrototypeOf(new Error(), Object.getPrototypeOf(value))
+      : Object.create(Object.getPrototypeOf(value) as object | null);
   let isChanged = false;
-  for (const key of Reflect.ownKeys(error)) {
-    const value: unknown = Reflect.get(error, key);
-    const shown = key === "cause" ? redactedCauseIn(value, inner) : redactedValue(value);
-    isChanged ||= shown !== value;
-    const enumerable = Object.getOwnPropertyDescriptor(error, key)?.enumerable === true;
+  for (const key of Reflect.ownKeys(value)) {
+    const property: unknown = Reflect.get(value, key);
+    const shown = redactedValue(property, inner);
+    isChanged ||= shown !== property;
+    const enumerable = Object.getOwnPropertyDescriptor(value, key)?.enumerable === true;
     Object.defineProperty(copy, key, {
       value: shown,
       enumerable,
@@ -35,18 +59,28 @@ function redactedError(error: Error, seen: ReadonlySet<Error>): Error {
       configurable: true,
     });
   }
-  return isChanged ? copy : error;
+  return isChanged ? copy : value;
+}
+
+/** Binary data and functions hold no text to hide, so they are kept as they are. */
+function isOpaque(value: object): boolean {
+  return typeof value === "function" || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
 }
 
-function redactedCauseIn(cause: unknown, seen: ReadonlySet<Error>): unknown {
-  if (!(cause instanceof Error)) {
-    return redactedValue(cause);
+function redactedValue(value: unknown, walk: Walk): unknown {
+  if (typeof value === "string") {
+    return redactUrlSecrets(value);
+  }
+  if (typeof value !== "object" || value === null || isOpaque(value)) {
+    return value;
+  }
+  if (walk.path.has(value) || walk.depth >= MAX_CAUSE_DEPTH) {
+    return undefined;
   }
-  // A chain that loops back is cut where it does, so the copy is finite.
-  return seen.has(cause) ? undefined : redactedError(cause, seen);
+  return Array.isArray(value) ? redactedArray(value, walk) : redactedObject(value, walk);
 }
 
 /** The cause of a typed error with the URL secrets of its whole chain hidden. */
 export function redactCauseSecrets(cause: unknown): unknown {
-  return redactedCauseIn(cause, new Set());
+  return redactedValue(cause, { path: new Set(), depth: 0 });
 }

package/src/domain/errors.ts

@@ -28,8 +28,10 @@ export const ERROR_CODES = {
   ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY",
   CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE",
   OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN",
+  OPTION_INVALID: "OPTION_INVALID",
   TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND",
   CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED",
+  CLI_FLAG_INVALID: "CLI_FLAG_INVALID",
   CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED",
   CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND",
   CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID",

package/src/domain/location-text.ts

@@ -0,0 +1,12 @@
+/** How a location the user writes, as a CLI argument or an option string, is read. */
+
+/**
+ * A scheme of two or more characters (`https:`, `file:`). One letter is a Windows drive (`C:`), so
+ * `C:\\specs\\api.yaml` stays a path.
+ */
+const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
+
+/** Whether the location is written as a URL, not as a file path. */
+export function hasUrlScheme(location: string): boolean {
+  return URL_SCHEME.test(location);
+}

package/src/domain/openapi/document-places.ts

@@ -0,0 +1,78 @@
+import { ADDITIONAL_OPERATIONS_KEY, HTTP_METHODS, QUERY_METHOD } from "./path-item-object.js";
+
+/**
+ * The places of an OpenAPI document that a JSON Pointer passes through, read from the document's
+ * structure rather than from the words of the pointer. `named*` places and `callback` are maps
+ * whose next segment is a name (a path, a component name, a callback expression). `outside` (a
+ * root key that is no document key), `input` (a parameter or a request body) and `other` end the
+ * walk.
+ */
+export type DocumentPlace =
+  | "root"
+  | "outside"
+  | "components"
+  | "namedPathItems"
+  | "namedCallbacks"
+  | "callback"
+  | "pathItem"
+  | "namedOperations"
+  | "operation"
+  | "input"
+  | "other";
+
+const OPERATION_KEYS: ReadonlySet<string> = new Set([...HTTP_METHODS, QUERY_METHOD]);
+
+/** The place each fixed field leads to; any other field leads to `other`. */
+const FIELDS: Readonly<Partial<Record<DocumentPlace, Readonly<Record<string, DocumentPlace>>>>> = {
+  root: {
+    paths: "namedPathItems",
+    webhooks: "namedPathItems",
+    components: "components",
+    $defs: "other",
+  },
+  components: {
+    parameters: "input",
+    requestBodies: "input",
+    pathItems: "namedPathItems",
+    callbacks: "namedCallbacks",
+  },
+  pathItem: { parameters: "input", [ADDITIONAL_OPERATIONS_KEY]: "namedOperations" },
+  operation: { parameters: "input", requestBody: "input", callbacks: "namedCallbacks" },
+};
+
+/** Maps whose every key leads to the same place. */
+const NAMED: Readonly<Partial<Record<DocumentPlace, DocumentPlace>>> = {
+  namedPathItems: "pathItem",
+  namedCallbacks: "callback",
+  callback: "pathItem",
+  namedOperations: "operation",
+};
+
+function nextPlace(place: DocumentPlace, segment: string): DocumentPlace {
+  const named = NAMED[place];
+  if (named !== undefined) {
+    return named;
+  }
+  if (place === "pathItem" && OPERATION_KEYS.has(segment)) {
+    return "operation";
+  }
+  const fields = FIELDS[place] ?? {};
+  if (Object.hasOwn(fields, segment)) {
+    return fields[segment] as DocumentPlace;
+  }
+  return place === "root" ? "outside" : "other";
+}
+
+const TERMINAL_PLACES: ReadonlySet<DocumentPlace> = new Set(["outside", "input", "other"]);
+
+/** The place the segments of a pointer (after `#`) lead to; the walk stops at a terminal place. */
+export function placeOf(segments: Iterable<string>): DocumentPlace {
+  let place: DocumentPlace = "root";
+  for (const segment of segments) {
+    place = nextPlace(place, segment);
+    if (TERMINAL_PLACES.has(place)) {
+      return place;
+    }
+  }
+  return place;
+}

package/src/domain/output-fixes.ts

@@ -21,6 +21,11 @@ export const FIX = {
   ARRAY_LENGTH_TUPLES: "array-length-tuples",
   /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
   DEDUPE_ENUM_NAMES: "dedupe-enum-names",
+  /**
+   * `--default-non-nullable` finds parameters and request bodies by the document's structure, not
+   * by the words `parameters` and `requestBody` anywhere in a schema's location.
+   */
+  DEFAULT_INPUT_LOCATIONS: "default-input-locations",
   /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
   DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required",
   /**
@@ -33,8 +38,8 @@ export const FIX = {
   EXPLODED_QUERY_OBJECTS: "exploded-query-objects",
   /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
   NULLABLE_ENUMS: "nullable-enums",
-  /** A parameter with `content` instead of `schema` is typed by the schema of its media type. */
-  PARAMETER_CONTENT: "parameter-content",
+  /** A parameter or header with `content`, not `schema`, is typed by its media type's schema. */
+  PARAMETER_HEADER_CONTENT: "parameter-header-content",
   /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
   PATH_PARAM_TYPE_NAMES: "path-param-type-names",
   /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
@@ -111,6 +116,7 @@ export interface OutputFixRequirement {
   readonly option:
     | "arrayLength"
     | "dedupeEnums"
+    | "defaultNonNullable"
     | "enum"
     | "pathParamsAsTypes"
     | "rootTypes"
@@ -129,6 +135,7 @@ const NO_SCHEMA_PREFIX = {
 const REQUIREMENTS: Readonly<Partial<Record<OutputFixName, readonly OutputFixRequirement[]>>> = {
   [FIX.ARRAY_LENGTH_TUPLES]: [{ option: "arrayLength", flag: "--array-length" }],
   [FIX.DEDUPE_ENUM_NAMES]: [ENUM, { option: "dedupeEnums", flag: "--dedupe-enums" }],
+  [FIX.DEFAULT_INPUT_LOCATIONS]: [{ option: "defaultNonNullable", flag: "--default-non-nullable" }],
   [FIX.NULLABLE_ENUMS]: [ENUM],
   [FIX.PATH_PARAM_TYPE_NAMES]: [{ option: "pathParamsAsTypes", flag: "--path-params-as-types" }],
   [FIX.ROOT_TYPE_NUMBERING]: [ROOT_TYPES, NO_SCHEMA_PREFIX],

package/src/domain/terminal-text.ts

@@ -0,0 +1,44 @@
+/**
+ * Text from a document or a project (a path key, an `operationId`, a file name) reaches the
+ * terminal and CI job logs. A line break in it starts a new line that CI reads as a command
+ * (`::error …` in GitHub Actions, `##vso[…]` in Azure Pipelines), and an escape sequence moves
+ * the cursor or erases lines, so it can forge or hide output. Each such character is shown as an
+ * escape instead (`\n`, `\u001b`), so one message stays one line and shows what the text holds.
+ */
+
+/**
+ * The code points shown as escapes: C0 controls but the tab, DEL and C1 controls, the Unicode
+ * line and paragraph separators, and the bidirectional controls, which reorder how a terminal
+ * shows the text around them.
+ */
+const CONTROL_RANGES: readonly (readonly [number, number])[] = [
+  [0x00, 0x08],
+  [0x0a, 0x1f],
+  [0x7f, 0x9f],
+  [0x2028, 0x2029],
+  [0x202a, 0x202e],
+  [0x2066, 0x2069],
+];
+
+const SHORT_ESCAPES: Readonly<Record<string, string>> = { "\n": "\\n", "\r": "\\r" };
+const HEX_DIGITS = 4;
+const HEX_RADIX = 16;
+
+function isControl(codePoint: number): boolean {
+  return CONTROL_RANGES.some(([first, last]) => codePoint >= first && codePoint <= last);
+}
+
+function escapeOf(character: string, codePoint: number): string {
+  const hex = codePoint.toString(HEX_RADIX).padStart(HEX_DIGITS, "0");
+  return SHORT_ESCAPES[character] ?? `\\u${hex}`;
+}
+
+/** The text with every control character shown as an escape, so it prints as one plain line. */
+export function terminalSafeText(text: string): string {
+  let shown = "";
+  for (const character of text) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    shown += isControl(codePoint) ? escapeOf(character, codePoint) : character;
+  }
+  return shown;
+}

package/src/domain/warnings.ts

@@ -7,6 +7,7 @@
 /** Every warning code. */
 export const WARNING_CODES = {
   CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED",
+  CLI_OUTPUT_IGNORED: "CLI_OUTPUT_IGNORED",
   CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN",
   DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID",
   DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED",