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

package/src/domain/openapi/discriminator-conflicts.ts

@@ -1,6 +1,13 @@
+import { appendAll } from "../append-all.js";
 import { admittedPropertyValues, resolveLocalRef } from "./admitted-values.js";
 import { isUnionMember, unionAt } from "./discriminated-union.js";
-import { createRef, escapePointerSegment, parseRefPointer } from "./json-pointer.js";
+import {
+  appendPointer,
+  canonicalRef,
+  escapePointerSegment,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "./json-pointer.js";
 
 /**
  * Discriminator members whose discriminator value their own property does not allow. By the
@@ -45,8 +52,11 @@ function refsOf(list: unknown): string[] {
   );
 }
 
+/** A mapping value as a canonical `$ref`: Redocly writes it percent-decoded (`canonicalRef`). */
 function mappingTarget(target: string): string {
-  return target.startsWith("#") ? target : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
+  return target.startsWith("#")
+    ? canonicalRef(target)
+    : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
 }
 
 function ownerAt(node: JsonObject, pointer: () => string): Owner | null {
@@ -76,7 +86,7 @@ function pointerOf(visit: Visit): string {
   for (let current: Visit | null = visit; current?.key != null; current = current.parent) {
     segments.unshift(current.key);
   }
-  return createRef(segments);
+  return appendPointer(ROOT_POINTER, segments);
 }
 
 function childrenOf(visit: Visit): Visit[] {
@@ -101,7 +111,7 @@ function ownersIn(document: unknown): Owner[] {
     if (owner !== null) {
       found.push(owner);
     }
-    stack.push(...childrenOf(visit).reverse());
+    appendAll(stack, childrenOf(visit).reverse());
   }
   return found;
 }
@@ -200,8 +210,10 @@ function membersOf(owner: Owner, search: ConflictSearch): Member[] {
   const listed = owner.memberRefs.map((ref) => ({ ref, skipped: new Set([owner.pointer]) }));
   const members = new Map<string, Member>();
   for (const member of [...listed, ...inheritingMembers(owner, search)]) {
-    if (!members.has(member.ref)) {
-      members.set(member.ref, member);
+    // A member may be listed by a `$ref` and found by its pointer: both name it canonically.
+    const key = canonicalRef(member.ref);
+    if (!members.has(key)) {
+      members.set(key, member);
     }
   }
   return [...members.values()];
@@ -209,7 +221,9 @@ function membersOf(owner: Owner, search: ConflictSearch): Member[] {
 
 function memberValues(owner: Owner, member: string): { values: string[]; isImplicit: boolean } {
   const values = Object.entries(owner.mapping)
-    .filter(([, target]) => typeof target === "string" && mappingTarget(target) === member)
+    .filter(
+      ([, target]) => typeof target === "string" && mappingTarget(target) === canonicalRef(member),
+    )
     .map(([key]) => key);
   const name = parseRefPointer(member).pop() ?? "";
   return values.length > 0 ? { values, isImplicit: false } : { values: [name], isImplicit: true };

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

@@ -4,6 +4,8 @@ import type { Schema } from "./schema-object.js";
 
 /** The parts of an OpenAPI document that get a root type (OpenAPI 3.1 §4.8.1). */
 export interface DocumentObject {
+  /** The OpenAPI version: `3.0.x`, `3.1.x` or `3.2.x`. */
+  readonly openapi?: string;
   readonly paths?: PathsObject;
   readonly webhooks?: PathsObject;
   readonly components?: ComponentsObject;

package/src/domain/openapi/json-pointer.ts

@@ -18,19 +18,108 @@ function unescapePointerSegment(segment: string): string {
 }
 
 /**
- * Escape one segment for a JSON Pointer in a `$ref` fragment: `~` → `~0`, `/` → `~1`, and `%` →
- * `%25`, because reading a pointer back percent-decodes it. The original did not escape `%`, so a
- * name like `50%` threw URIError and `a%2Fb` read back as `a/b` (upstream #2251, #2828).
+ * Escape one segment for a JSON Pointer in a `$ref` fragment: `~` → `~0` and `/` → `~1` (RFC 6901),
+ * then `%` → `%25` and `#` → `%23`, the two characters of a key that a URI fragment cannot hold as
+ * written (RFC 6901 §6, RFC 3986). Reading a pointer back percent-decodes it, so the original's
+ * unescaped `%` threw URIError for `50%` and read `a%2Fb` as `a/b` (upstream #2251, #2828), and
+ * reading starts at the first `#/`, so an unescaped key `a#` cut the pointer short.
  */
 export function escapePointerSegment(segment: string): string {
-  return segment.replaceAll("~", "~0").replaceAll("/", "~1").replaceAll("%", "%25");
+  return segment
+    .replaceAll("~", "~0")
+    .replaceAll("/", "~1")
+    .replaceAll("%", "%25")
+    .replaceAll("#", "%23");
+}
+
+/** The pointer of the document root. */
+export const ROOT_POINTER = "#";
+
+/** A raw pointer segment; a missing one (`undefined`, `null` or empty) is skipped. */
+export type PointerSegment = string | number | null | undefined;
+
+/**
+ * Extend the pointer `base` with raw segments: document keys, such as a path, a property name or a
+ * media type, and array indexes. Each segment is escaped and never read as a `$ref`, so a key like
+ * `#/%41` stays one segment and reads back unchanged with {@link parseRefPointer}. A missing
+ * segment, such as the absent `name` of a parameter, is skipped, as the original `createRef` did,
+ * and an empty one too, because `parseRefPointer` drops it.
+ */
+export function appendPointer(
+  base: string | undefined,
+  segments: readonly PointerSegment[],
+): string {
+  let pointer = pointerBase(base);
+  for (const segment of segments) {
+    if (segment !== undefined && segment !== null && segment !== "") {
+      pointer = childPointer(pointer, String(segment));
+    }
+  }
+  return pointer;
+}
+
+/**
+ * The pointer of the child `key` of the node at `pointer`, with `key` escaped. Unlike
+ * {@link appendPointer}, an empty key is a child too: a document walk names every key it visits.
+ */
+export function childPointer(pointer: string, key: string): string {
+  return `${pointer}/${escapePointerSegment(key)}`;
+}
+
+/**
+ * A local `$ref` or `mapping` value in the form {@link appendPointer} builds, so that pointers
+ * compare as text whatever escapes the document chose: `.../a#b` and `.../a%23b` are both
+ * `.../a%23b`. Redocly writes a bundled `mapping` value percent-decoded, which is no pointer for a
+ * key with `%` (`.../50%`), so such a text is read as written. Any other text, such as an
+ * external `$ref` or a bare schema name, is returned unchanged.
+ */
+export function canonicalRef(ref: string): string {
+  if (!ref.startsWith(`${ROOT_POINTER}/`)) {
+    return ref;
+  }
+  return appendPointer(ROOT_POINTER, refSegments(ref));
+}
+
+function refSegments(ref: string): string[] {
+  try {
+    return parseRefPointer(ref);
+  } catch (error) {
+    if (!(error instanceof URIError)) {
+      throw error;
+    }
+    return writtenSegments(ref);
+  }
+}
+
+/** The segments of a pointer that is not percent-encoded: only `~1` and `~0` are escapes. */
+function writtenSegments(ref: string): string[] {
+  return ref
+    .slice(ROOT_POINTER.length + 1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+
+/**
+ * A pointer (`#` or `#/...`) is kept as written; a missing base is the root. Any other text is a
+ * `path` given to the exported transformers, such as `/items/{id}` or `other.yaml#/a`, which the
+ * original read as a `createRef` part, so it is read the same way here.
+ */
+function pointerBase(base: string | undefined): string {
+  if (base === undefined || base === "") {
+    return ROOT_POINTER;
+  }
+  return base === ROOT_POINTER || base.startsWith(`${ROOT_POINTER}/`) ? base : createRef([base]);
 }
 
 /**
- * Join parts into a local `$ref` (the original `createRef`). Empty parts are skipped. A part that
- * is itself a `$ref` contributes its segments; any other part is one segment.
+ * Join parts into a local `$ref` (the original `createRef`, exported for 1.x by ADR-034). Empty
+ * parts are skipped. A part that contains `#/` is parsed as a `$ref` and contributes its decoded
+ * segments, so it throws URIError for a malformed percent escape; any other part is one segment.
+ * Because of that parsing, the generator does not pass document keys here: it builds pointers
+ * with {@link appendPointer}, which never parses a segment.
  */
-export function createRef(parts: readonly (string | number | null | undefined)[]): string {
+export function createRef(parts: readonly PointerSegment[]): string {
   let ref = "#";
   for (const part of parts) {
     if (part === undefined || part === null || part === "") {

package/src/domain/openapi/schema-dialect.ts

@@ -0,0 +1,22 @@
+/**
+ * The schema dialect of a document. OpenAPI 3.0 Schema Objects ignore every keyword next to a
+ * `$ref` (OpenAPI 3.0.3, Reference Object). OpenAPI 3.1 and 3.2 use JSON Schema 2020-12, where a
+ * `$ref` is one keyword among the others, and all of them apply (JSON Schema Core §8.2.3.1).
+ */
+export const SCHEMA_DIALECTS = {
+  OPENAPI_3_0: "openapi-3.0",
+  JSON_SCHEMA_2020_12: "json-schema-2020-12",
+} as const;
+
+export type SchemaDialect = (typeof SCHEMA_DIALECTS)[keyof typeof SCHEMA_DIALECTS];
+
+const OPENAPI_3_0_RE = /^3\.0(?:\.|$)/;
+
+/**
+ * The dialect of a document's `openapi` version. Without a version (a schema passed to a
+ * transformer on its own) it is OpenAPI 3.0, which keeps the output the original gives.
+ */
+export function schemaDialectOf(openapiVersion: unknown): SchemaDialect {
+  const isOpenApi30 = typeof openapiVersion !== "string" || OPENAPI_3_0_RE.test(openapiVersion);
+  return isOpenApi30 ? SCHEMA_DIALECTS.OPENAPI_3_0 : SCHEMA_DIALECTS.JSON_SCHEMA_2020_12;
+}

package/src/domain/openapi/unsupported-features.ts

@@ -1,4 +1,4 @@
-import { createRef, parseRefPointer } from "./json-pointer.js";
+import { appendPointer, parseRefPointer, ROOT_POINTER } from "./json-pointer.js";
 import { QUERYSTRING_LOCATION } from "./parameter-object.js";
 import { type PathItemObject, pathItemOperations } from "./path-item-object.js";
 
@@ -60,7 +60,7 @@ function locatedParameters(
   }
   return parameters.flatMap((entry, index) => {
     const parameter = resolveLocal(document, entry);
-    const pointer = createRef([...segments, String(index)]);
+    const pointer = appendPointer(ROOT_POINTER, [...segments, index]);
     return isObject(parameter) ? [{ pointer, parameter }] : [];
   });
 }

package/src/domain/output-fixes.ts

@@ -33,6 +33,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",
   /** `--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). */
@@ -44,6 +46,11 @@ export const FIX = {
    * points at, also where the original type compiles through an index signature.
    */
   REF_POINTERS: "ref-pointers",
+  /**
+   * OpenAPI 3.1 and 3.2: keywords next to a `$ref` (`required`, `properties`) apply too, so the
+   * type is the reference intersected with them. OpenAPI 3.0 ignores them, as its spec says.
+   */
+  REF_SIBLINGS: "ref-siblings",
   /** Schemas of one root type name without the prefix each get an alias, the earlier numbered. */
   ROOT_TYPE_NUMBERING: "root-type-numbering",
   /** `unevaluatedProperties` types the keys no other keyword declares (an index signature). */
@@ -67,8 +74,20 @@ function isOutputFixName(value: unknown): value is OutputFixName {
   return typeof value === "string" && KNOWN_NAMES.has(value);
 }
 
-/** The fix names as given; fails with `OPTION_FIX_UNKNOWN` for any other value. */
-export function outputFixNamesOf(values: readonly unknown[]): readonly OutputFixName[] {
+/**
+ * The fix names as given; fails with `OPTION_FIX_UNKNOWN` for any other value, and for a `fix`
+ * option that is no list (`fix: "all"` from JavaScript), which must not be read letter by letter.
+ */
+export function outputFixNamesOf(values: unknown): readonly OutputFixName[] {
+  if (!Array.isArray(values)) {
+    throw new OpenAPITypesafeError({
+      code: ERROR_CODES.OPTION_FIX_UNKNOWN,
+      message:
+        'The fix option must be a list of fix names, such as ["all"]. ' +
+        `Got ${JSON.stringify(values)}.`,
+      details: { unknown: [values], known: [...KNOWN_NAMES] },
+    });
+  }
   const unknown = values.filter((value) => !isOutputFixName(value));
   if (unknown.length > 0) {
     const names = unknown.map((value) => JSON.stringify(value)).join(", ");

package/src/domain/url-secrets.ts

@@ -0,0 +1,72 @@
+/**
+ * URLs can reach a message: the CLI input, a `$ref`, a redirect. Messages end up in CI job logs, so
+ * the parts of a URL that carry secrets are hidden in every one (audit B2, F12): the user info
+ * (`https://user:token@host/…`), which fetch refuses anyway, and the query, which holds API keys
+ * and signatures (`?api_key=…`, `?X-Amz-Signature=…`). Which query parameters are secret cannot be
+ * told by their names, so the whole query is hidden; the path and the fragment (a JSON pointer)
+ * stay, so the message still names the document and the place in it.
+ */
+
+/**
+ * A URL in a message, from its `://` to the first space, quote or angle bracket: a serialized URL
+ * percent-encodes these, and messages put them around a URL. A match takes the rest of the URL,
+ * also a later `://` in it, so the scan never starts again inside a URL; it stays linear. It ends
+ * before punctuation that closes a sentence or a parenthesis (`… x.yaml?key=1: 404`, `(… ?key=1)`),
+ * which the message puts after the URL; a hidden query would hide it too.
+ */
+const URL_AFTER_SCHEME = /:\/\/[^\s"'<>]*[^\s"'<>.,:;!?)]/g;
+
+const SCHEME_SEPARATOR = "://";
+const AUTHORITY_END = /[/?#]/;
+const QUERY_OR_FRAGMENT = /[?#]/;
+const QUERY_START = "?";
+const FRAGMENT_START = "#";
+const USER_INFO_END = "@";
+const HIDDEN = "***";
+
+/** The part after `://` with the user info of its authority hidden: `***@host`. */
+function withoutUserInfo(rest: string): string {
+  const authorityEnd = rest.search(AUTHORITY_END);
+  const authority = authorityEnd === -1 ? rest : rest.slice(0, authorityEnd);
+  const userInfoEnd = authority.lastIndexOf(USER_INFO_END);
+  return userInfoEnd === -1 ? rest : `${HIDDEN}${rest.slice(userInfoEnd)}`;
+}
+
+/** The part after `://` with its query hidden: `/x.yaml?***#/a`. */
+function withoutQuery(rest: string): string {
+  const fragmentStart = rest.indexOf(FRAGMENT_START);
+  const beforeFragment = fragmentStart === -1 ? rest : rest.slice(0, fragmentStart);
+  const queryStart = beforeFragment.indexOf(QUERY_START);
+  if (queryStart === -1) {
+    return rest;
+  }
+  const fragment = fragmentStart === -1 ? "" : rest.slice(fragmentStart);
+  return `${rest.slice(0, queryStart + 1)}${HIDDEN}${fragment}`;
+}
+
+/** The text with the user info and the query of every URL in it replaced by `***`. */
+export function redactUrlSecrets(text: string): string {
+  return text.replace(URL_AFTER_SCHEME, (url) => {
+    const rest = url.slice(SCHEME_SEPARATOR.length);
+    return `${SCHEME_SEPARATOR}${withoutQuery(withoutUserInfo(rest))}`;
+  });
+}
+
+/**
+ * Text that starts like a URL but does not parse as one (`http://user:a/b@host/x`), with what may
+ * be secret hidden. Without a parse there is no telling where the authority ends, so everything
+ * from the `://` to the last `@` before the query counts as user info; the query is hidden as in
+ * `redactUrlSecrets`.
+ */
+export function redactUnparsedUrl(text: string): string {
+  const separator = text.indexOf(SCHEME_SEPARATOR);
+  if (separator === -1) {
+    return text;
+  }
+  const rest = text.slice(separator + SCHEME_SEPARATOR.length);
+  const queryOrFragment = rest.search(QUERY_OR_FRAGMENT);
+  const beforeQuery = queryOrFragment === -1 ? rest : rest.slice(0, queryOrFragment);
+  const userInfoEnd = beforeQuery.lastIndexOf(USER_INFO_END);
+  const shown = userInfoEnd === -1 ? rest : `${HIDDEN}${rest.slice(userInfoEnd)}`;
+  return `${text.slice(0, separator)}${SCHEME_SEPARATOR}${withoutQuery(shown)}`;
+}

package/src/types/generator-options.ts

@@ -70,7 +70,7 @@ export interface OpenAPITSBaseOptions {
    * still fail the run.
    */
   lint?: boolean;
-  /** (optional) Should logging be suppressed? (necessary for STDOUT) */
+  /** Hide warnings (default: false). Every line of the logger goes to stderr, never to stdout. */
   silent?: boolean;
   /** Accepted for compatibility with openapi-typescript; not read. */
   version?: number;

package/dist/cli/main.d.cts

@@ -1,2 +0,0 @@
-
-export { };

package/dist/cli/main.d.mts

@@ -1,2 +0,0 @@
-
-export { };

package/dist/cli/main.d.ts

@@ -1,2 +0,0 @@
-
-export { };

package/dist/domain/url-credentials.cjs

@@ -1,10 +0,0 @@
-'use strict';
-
-const URL_USER_INFO = /:\/\/[^\s/?#@]*@/g;
-const REDACTED_USER_INFO = "://***@";
-function redactUrlCredentials(text) {
-  return text.replace(URL_USER_INFO, () => REDACTED_USER_INFO);
-}
-
-exports.redactUrlCredentials = redactUrlCredentials;
-//# sourceMappingURL=url-credentials.cjs.map

package/dist/domain/url-credentials.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"url-credentials.cjs","sources":["../../src/domain/url-credentials.ts"],"sourcesContent":["/**\n * URLs with user info (`https://user:token@host/…`) can reach a message: the CLI input, a `$ref`,\n * a redirect. Messages end up in CI job logs, so the user info is hidden in every one (audit B2,\n * F12). Fetch refuses such URLs anyway, so a message never needs the credentials.\n */\n\n/**\n * The user info after a scheme: everything up to an `@` that comes before the end of the\n * authority. The class stops at `/`, so a scan never runs past the next `://`; it stays linear.\n */\nconst URL_USER_INFO = /:\\/\\/[^\\s/?#@]*@/g;\n\nconst REDACTED_USER_INFO = \"://***@\";\n\n/** The text with the user info of every URL in it replaced by `***`. */\nexport function redactUrlCredentials(text: string): string {\n  return text.replace(URL_USER_INFO, () => REDACTED_USER_INFO);\n}\n"],"names":[],"mappings":";;AAUA,MAAM,aAAA,GAAgB,mBAAA;AAEtB,MAAM,kBAAA,GAAqB,SAAA;AAGpB,SAAS,qBAAqB,IAAA,EAAsB;AACzD,EAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,aAAA,EAAe,MAAM,kBAAkB,CAAA;AAC7D;;"}

package/dist/domain/url-credentials.mjs

@@ -1,8 +0,0 @@
-const URL_USER_INFO = /:\/\/[^\s/?#@]*@/g;
-const REDACTED_USER_INFO = "://***@";
-function redactUrlCredentials(text) {
-  return text.replace(URL_USER_INFO, () => REDACTED_USER_INFO);
-}
-
-export { redactUrlCredentials };
-//# sourceMappingURL=url-credentials.mjs.map

package/dist/domain/url-credentials.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"url-credentials.mjs","sources":["../../src/domain/url-credentials.ts"],"sourcesContent":["/**\n * URLs with user info (`https://user:token@host/…`) can reach a message: the CLI input, a `$ref`,\n * a redirect. Messages end up in CI job logs, so the user info is hidden in every one (audit B2,\n * F12). Fetch refuses such URLs anyway, so a message never needs the credentials.\n */\n\n/**\n * The user info after a scheme: everything up to an `@` that comes before the end of the\n * authority. The class stops at `/`, so a scan never runs past the next `://`; it stays linear.\n */\nconst URL_USER_INFO = /:\\/\\/[^\\s/?#@]*@/g;\n\nconst REDACTED_USER_INFO = \"://***@\";\n\n/** The text with the user info of every URL in it replaced by `***`. */\nexport function redactUrlCredentials(text: string): string {\n  return text.replace(URL_USER_INFO, () => REDACTED_USER_INFO);\n}\n"],"names":[],"mappings":"AAUA,MAAM,aAAA,GAAgB,mBAAA;AAEtB,MAAM,kBAAA,GAAqB,SAAA;AAGpB,SAAS,qBAAqB,IAAA,EAAsB;AACzD,EAAA,OAAO,IAAA,CAAK,OAAA,CAAQ,aAAA,EAAe,MAAM,kBAAkB,CAAA;AAC7D;;"}

package/src/domain/url-credentials.ts

@@ -1,18 +0,0 @@
-/**
- * URLs with user info (`https://user:token@host/…`) can reach a message: the CLI input, a `$ref`,
- * a redirect. Messages end up in CI job logs, so the user info is hidden in every one (audit B2,
- * F12). Fetch refuses such URLs anyway, so a message never needs the credentials.
- */
-
-/**
- * The user info after a scheme: everything up to an `@` that comes before the end of the
- * authority. The class stops at `/`, so a scan never runs past the next `://`; it stays linear.
- */
-const URL_USER_INFO = /:\/\/[^\s/?#@]*@/g;
-
-const REDACTED_USER_INFO = "://***@";
-
-/** The text with the user info of every URL in it replaced by `***`. */
-export function redactUrlCredentials(text: string): string {
-  return text.replace(URL_USER_INFO, () => REDACTED_USER_INFO);
-}