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

package/src/domain/output-fixes.ts

@@ -3,9 +3,10 @@ import { ERROR_CODES, OpenAPITypesafeError } from "./errors.js";
 /**
  * Opt-in fixes of the output of valid schemas (ADR-021). Each one changes only the cases it names;
  * without any, the output is the same as openapi-typescript 7.13 gives. In 2.0 they become the
- * default.
+ * default. The object names the fixes for this package's code; the public API is the `OutputFix`
+ * union and the `OUTPUT_FIXES` list (ADR-021, amendment 1).
  */
-export const OutputFix = {
+export const FIX = {
   /** An `allOf` `$ref` to a discriminated union is the union, without `Omit` or a schema name. */
   ALLOF_DISCRIMINATED_UNION: "allof-discriminated-union",
   /** An `allOf` member with only `required` makes those properties of the others required. */
@@ -32,6 +33,8 @@ export const OutputFix = {
   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). */
@@ -43,30 +46,48 @@ export const OutputFix = {
    * 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). */
   UNEVALUATED_PROPERTIES: "unevaluated-properties",
 } as const;
-export type OutputFix = (typeof OutputFix)[keyof typeof OutputFix];
+/** The name of one opt-in output fix. */
+export type OutputFix = (typeof FIX)[keyof typeof FIX];
 
 /** Every fix of this version, in the order the docs list them. */
-export const OUTPUT_FIXES: readonly OutputFix[] = Object.values(OutputFix);
+export const OUTPUT_FIXES: readonly OutputFix[] = Object.values(FIX);
 
 /** The name that turns on every fix of the installed version. */
-export const ALL_OUTPUT_FIXES = "all";
+const ALL_FIXES = "all";
 
-/** A name the `fix` option accepts: one fix, or `all`. */
-export type OutputFixName = OutputFix | typeof ALL_OUTPUT_FIXES;
+/** A name the `fix` option accepts: one fix, or `"all"`. */
+export type OutputFixName = OutputFix | typeof ALL_FIXES;
 
-const KNOWN_NAMES: ReadonlySet<string> = new Set<string>([...OUTPUT_FIXES, ALL_OUTPUT_FIXES]);
+const KNOWN_NAMES: ReadonlySet<string> = new Set<string>([...OUTPUT_FIXES, ALL_FIXES]);
 
 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(", ");
@@ -82,7 +103,7 @@ export function outputFixNamesOf(values: readonly unknown[]): readonly OutputFix
 
 /** The fixes the names turn on; `all` stands for every fix of this version. */
 export function resolveOutputFixes(names: readonly OutputFixName[]): ReadonlySet<OutputFix> {
-  return new Set(names.flatMap((name) => (name === ALL_OUTPUT_FIXES ? OUTPUT_FIXES : [name])));
+  return new Set(names.flatMap((name) => (name === ALL_FIXES ? OUTPUT_FIXES : [name])));
 }
 
 /** A generator option that a fix works with; without it, the fix changes nothing (ADR-021). */
@@ -106,13 +127,11 @@ const NO_SCHEMA_PREFIX = {
 
 /** The options each fix needs, by fix name; `all` has none. */
 const REQUIREMENTS: Readonly<Partial<Record<OutputFixName, readonly OutputFixRequirement[]>>> = {
-  [OutputFix.ARRAY_LENGTH_TUPLES]: [{ option: "arrayLength", flag: "--array-length" }],
-  [OutputFix.DEDUPE_ENUM_NAMES]: [ENUM, { option: "dedupeEnums", flag: "--dedupe-enums" }],
-  [OutputFix.NULLABLE_ENUMS]: [ENUM],
-  [OutputFix.PATH_PARAM_TYPE_NAMES]: [
-    { option: "pathParamsAsTypes", flag: "--path-params-as-types" },
-  ],
-  [OutputFix.ROOT_TYPE_NUMBERING]: [ROOT_TYPES, NO_SCHEMA_PREFIX],
+  [FIX.ARRAY_LENGTH_TUPLES]: [{ option: "arrayLength", flag: "--array-length" }],
+  [FIX.DEDUPE_ENUM_NAMES]: [ENUM, { option: "dedupeEnums", flag: "--dedupe-enums" }],
+  [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],
 };
 
 function describeRequirement(requirement: OutputFixRequirement): string {

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/domain/warnings.ts

@@ -12,7 +12,6 @@ export const WARNING_CODES = {
   DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED",
   ENUM_VALUES_EXCLUDED: "ENUM_VALUES_EXCLUDED",
   FIX_NEEDS_OPTION: "FIX_NEEDS_OPTION",
-  LEGACY_CALLBACK_DEPRECATED: "LEGACY_CALLBACK_DEPRECATED",
   LINT_PROBLEM: "LINT_PROBLEM",
   PATH_TEMPLATES_IDENTICAL: "PATH_TEMPLATES_IDENTICAL",
   QUERYSTRING_NEXT_TO_QUERY: "QUERYSTRING_NEXT_TO_QUERY",

package/src/index.ts

@@ -34,6 +34,7 @@ export {
   UNDEFINED,
   UNKNOWN,
 } from "./api/type-helpers.js";
+export { DEPRECATION_CODES, type DeprecationCode } from "./domain/deprecations.js";
 export {
   ERROR_CODES,
   type ErrorCode,
@@ -42,12 +43,7 @@ export {
   OpenAPITypesafeError,
 } from "./domain/errors.js";
 export type * from "./domain/ir/nodes.js";
-export {
-  ALL_OUTPUT_FIXES,
-  OUTPUT_FIXES,
-  OutputFix,
-  type OutputFixName,
-} from "./domain/output-fixes.js";
+export { OUTPUT_FIXES, type OutputFix, type OutputFixName } from "./domain/output-fixes.js";
 export { WARNING_CODES, type WarningCode } from "./domain/warnings.js";
 export { default as transformComponentsObject } from "./transform/components-object.js";
 export { default as transformHeaderObject } from "./transform/header-object.js";

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);
-}