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

package/src/cli/redocly-apis.ts

@@ -10,7 +10,8 @@ import {
   unknownSettingWarnings,
 } from "./api-settings.js";
 import { type GeneratedApi, writeGeneratedApis } from "./api-writes.js";
-import { cliError } from "./cli-errors.js";
+import { ineffectiveFlagNotices } from "./cli-arguments.js";
+import { ApiFailure, cliError } from "./cli-errors.js";
 import {
   type CliRun,
   ensureOutputIsNotSchema,
@@ -24,7 +25,7 @@ import {
 } from "./cli-output.js";
 import { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
 import { fixOption } from "./fix-option.js";
-import { refLimitOptions } from "./ref-limits.js";
+import { type RefLimitOptions, refLimitOptions } from "./ref-limits.js";
 
 /** The `apis` of a Redocly config: each API is generated into its `x-openapi-ts.output`. */
 
@@ -92,16 +93,34 @@ function apiTarget(api: RedoclyApi, configRoot: URL): ApiTarget {
   return { name, root, settings, configRoot };
 }
 
-/** The generator options of one API: its own settings win over the CLI's flags. */
-function apiOptions(run: CliRun, redocly: RedoclyConfig, target: ApiTarget): GeneratorOptions {
+/**
+ * What every API of a run shares: the config, the files of all APIs, and the reference limits of
+ * the command line, which are checked once before any API, so an invalid flag fails the run once.
+ */
+interface ApiRun {
+  readonly redocly: RedoclyConfig;
+  readonly files: ConfigFiles;
+  readonly refLimits: RefLimitOptions;
+}
+
+/**
+ * The generator options of one API: its own settings win over the CLI's flags, and its own lint
+ * rules in `redocly.yaml` over the root's (upstream used the root's only). A flag that has
+ * no effect with the merged flags is named for this API, since its settings may turn on the flag
+ * that the command line lacks, or set one that has no effect themselves.
+ */
+function apiOptions(run: CliRun, apiRun: ApiRun, target: ApiTarget): GeneratorOptions {
   const { name, settings, configRoot } = target;
+  const flags = { ...run.args.generatorFlags, ...apiFlags(name, settings) };
+  for (const notice of ineffectiveFlagNotices(flags)) {
+    run.deps.console.notice(`API ${name}: ${notice}`);
+  }
   return {
-    ...run.args.generatorFlags,
-    ...apiFlags(name, settings),
-    ...refLimitOptions(run.args, run.deps.cwd),
+    ...flags,
+    ...apiRun.refLimits,
     ...apiRefLimitOptions(name, settings, configRoot),
     ...fixOption(apiFixNames(name, settings) ?? run.args.fix),
-    redocly,
+    redocly: run.deps.redoclyConfigs.forApi(apiRun.redocly, name),
   };
 }
 
@@ -122,22 +141,38 @@ function otherOutputs(files: ConfigFiles, apiName: string): NamedFile[] {
  * Generate the types of one API. Its output must not be a file the run reads before any API is
  * loaded (the root of any API, the Redocly config) nor another API's output.
  */
-async function generateApi(
-  run: CliRun,
-  redocly: RedoclyConfig,
-  target: ApiTarget,
-  files: ConfigFiles,
-): Promise<GeneratedApi> {
+async function generateApi(run: CliRun, apiRun: ApiRun, target: ApiTarget): Promise<GeneratedApi> {
+  const { files } = apiRun;
   for (const warning of unknownSettingWarnings(target.name, target.settings)) {
     run.deps.logger.warn(warning);
   }
   const output = apiOutputOf(target.name, target.settings);
-  const outputFile = outputFileOf(run, { source: target.name, output }, target.configRoot);
-  ensureOutputIsNotSchema(run, outputFile, files.schemas);
-  ensureOutputIsOwn(run, outputFile, otherOutputs(files, target.name));
+  const outputFile = failingAsApi(target.name, () => {
+    const file = outputFileOf(run, { source: target.name, output }, target.configRoot);
+    ensureOutputIsNotSchema(run, file, files.schemas);
+    ensureOutputIsOwn(run, file, otherOutputs(files, target.name));
+    return file;
+  });
   const source = resolveLocationUrl(target.root, target.configRoot);
-  const types = await run.deps.generate(source, apiOptions(run, redocly, target));
-  return { name: target.name, outputFile, types };
+  const options = apiOptions(run, apiRun, target);
+  try {
+    const types = await run.deps.generate(source, options, target.name);
+    return { name: target.name, outputFile, types };
+  } catch (error) {
+    throw new ApiFailure(target.name, error);
+  }
+}
+
+/**
+ * The result of a step of one API, whose failure is reported with the API's name. Errors of an
+ * API's settings name the API in their own message and are not wrapped.
+ */
+function failingAsApi<T>(apiName: string, step: () => T): T {
+  try {
+    return step();
+  } catch (error) {
+    throw new ApiFailure(apiName, error);
+  }
 }
 
 /**
@@ -192,8 +227,9 @@ async function settledInTurn<T, R>(
 export async function generateRedoclyApis(run: CliRun, redocly: RedoclyConfig): Promise<unknown[]> {
   const apis = redoclyApisOf(redocly);
   const { configRoot, files } = configFilesOf(run, redocly, apis);
+  const apiRun = { redocly, files, refLimits: refLimitOptions(run.args, run.deps.cwd) };
   const results = await settledInTurn(apis, (api) =>
-    generateApi(run, redocly, apiTarget(api, configRoot), files),
+    generateApi(run, apiRun, apiTarget(api, configRoot)),
   );
   const generated = results.flatMap((result) =>
     result.status === "fulfilled" ? [result.value] : [],

package/src/cli/ref-limits.ts

@@ -1,16 +1,35 @@
 import type { GeneratorOptions } from "../types.js";
 import type { CliArguments } from "./cli-arguments.js";
+import { cliError } from "./cli-errors.js";
 import { resolveLocationUrl } from "./cli-output.js";
 
 /** The `$ref` limits of the CLI flags as generator options (threat model R1, R2, ADR-017). */
 
 export type RefLimitOptions = Pick<GeneratorOptions, "localRefRoot" | "remoteRefHosts">;
 
-/** `--local-ref-root` resolves against the working directory, like every other CLI path. */
+const FILE_PROTOCOL = "file:";
+
+/** A local `$ref` root as a URL; undefined for a URL of another protocol, which names no folder. */
+export function localRootUrl(location: string, base: URL): URL | undefined {
+  const url = resolveLocationUrl(location, base);
+  return url.protocol === FILE_PROTOCOL ? url : undefined;
+}
+
+/**
+ * `--local-ref-root` resolves against the working directory, like every other CLI path. A URL of
+ * another protocol (`https://…`) fails with `CLI_FLAG_INVALID`.
+ */
 export function refLimitOptions(args: CliArguments, cwd: URL): RefLimitOptions {
   const { localRefRoot, remoteRefHosts } = args.refLimits;
+  const localRoot = localRefRoot === undefined ? undefined : localRootUrl(localRefRoot, cwd);
+  if (localRefRoot !== undefined && localRoot === undefined) {
+    throw cliError(
+      "CLI_FLAG_INVALID",
+      `--local-ref-root ${localRefRoot}: a directory path or a file: URL.`,
+    );
+  }
   return {
-    ...(localRefRoot === undefined ? {} : { localRefRoot: resolveLocationUrl(localRefRoot, cwd) }),
+    ...(localRoot === undefined ? {} : { localRefRoot: localRoot }),
     ...(remoteRefHosts === undefined ? {} : { remoteRefHosts }),
   };
 }

package/src/cli/run-cli.ts

@@ -1,5 +1,6 @@
 import type { Logger } from "../application/ports/logger.js";
 import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
+import { hasUrlScheme } from "../domain/location-text.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import type { SchemaSource } from "../types.js";
 import { ineffectiveFlagNotices, parseCliArguments } from "./cli-arguments.js";
@@ -52,13 +53,29 @@ function schemaSource(run: CliRun): SchemaSource {
   return run.deps.stdin();
 }
 
+/** The character that made the original CLI read a schema argument as a glob pattern. */
+const GLOB_WILDCARD = "*";
+
+/**
+ * Whether the schema argument is a glob pattern, which the CLI no longer expands: a path with a
+ * `*` that names no file. A URL is no pattern (`?fields=*` is its query), nor a file whose name
+ * has a `*`, which the CLI reads as any other file.
+ */
+function isGlobPattern(run: CliRun, input: string): boolean {
+  return (
+    input.includes(GLOB_WILDCARD) &&
+    !hasUrlScheme(input) &&
+    !run.deps.files.isFile(resolveLocationUrl(input, run.deps.cwd))
+  );
+}
+
 /**
  * One schema from a path, a URL or stdin; without `--output`, the types go to stdout. Warnings and
  * errors go to stderr either way, so they never mix with the types (upstream dropped warnings).
  */
 async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promise<void> {
   const { input, output } = run.args;
-  if (input?.includes("*")) {
+  if (input !== undefined && isGlobPattern(run, input)) {
     throw cliError(
       "CLI_GLOB_UNSUPPORTED",
       "Globbing has been deprecated in favor of redocly.yaml’s `apis` keys. " +
@@ -72,6 +89,9 @@ async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promis
       "--check needs the generated file to compare with: add --output <file>.",
     );
   }
+  for (const notice of ineffectiveFlagNotices(run.args.generatorFlags)) {
+    run.deps.console.notice(notice);
+  }
   const source = schemaSource(run);
   const outputFile = output ? singleOutputFile(run, output, source, redocly) : undefined;
   const options = {
@@ -112,23 +132,35 @@ async function generate(run: CliRun): Promise<unknown[]> {
     await generateSingleSchema(run, redocly);
     return [];
   }
-  if (run.args.input) {
-    run.deps.logger.warn(
+  warnAboutIgnoredArguments(run);
+  return generateRedoclyApis(run, redocly);
+}
+
+/** With the APIs of a Redocly config, the input and the output of the command line are unused. */
+function warnAboutIgnoredArguments(run: CliRun): void {
+  const { args, deps } = run;
+  if (args.input) {
+    deps.logger.warn(
       warningText(
         "APIs are specified both in Redocly Config and CLI argument. Only using Redocly config.",
         WARNING_CODES.CLI_INPUT_IGNORED,
       ),
     );
   }
-  return generateRedoclyApis(run, redocly);
+  if (args.output) {
+    deps.logger.warn(
+      warningText(
+        `APIs are specified in Redocly Config, so --output ${args.output} is ignored: ` +
+          "each API is written to its x-openapi-ts.output.",
+        WARNING_CODES.CLI_OUTPUT_IGNORED,
+      ),
+    );
+  }
 }
 
 /** Run the command; the failures it returns did not stop the other outputs. */
 async function runCommand(argv: readonly string[], deps: CliDependencies): Promise<unknown[]> {
   const startedAt = deps.now();
-  for (const notice of ineffectiveFlagNotices(argv)) {
-    deps.console.notice(notice);
-  }
   const args = parseCliArguments(argv);
   for (const flag of args.unknownFlags) {
     deps.console.notice(`Unknown flag ${flag} is ignored (see --help)`);

package/src/cli/written-flags.ts

@@ -0,0 +1,131 @@
+import { kebabCase } from "scule";
+import { cliError } from "./cli-errors.js";
+import {
+  BOOLEAN_FLAG_NAMES,
+  KNOWN_LONG_FLAG_NAMES,
+  KNOWN_SHORT_FLAGS,
+  LONG_PREFIX,
+  NEGATION_PREFIX,
+  SHORT_PREFIX,
+  VALUE_FLAG_NAMES,
+} from "./cli-flag-names.js";
+
+/**
+ * Checks of the flags as the user wrote them, before yargs-parser reads them: yargs-parser accepts
+ * any spelling and value, so what it cannot tell apart is checked here.
+ */
+
+/** Flags of older versions that were removed or renamed, with the message for each. */
+const REMOVED_FLAGS: readonly (readonly [string, string])[] = [
+  ["-ap", `The -ap alias has been deprecated. Use "--additional-properties" instead.`],
+  ["--immutable-types", `The --immutable-types flag has been renamed to "--immutable".`],
+  [
+    "--support-array-length",
+    `The --support-array-length flag has been renamed to "--array-length".`,
+  ],
+  ["-it", `The -it alias has been deprecated. Use "--immutable" instead.`],
+  ["--redoc", `The --redoc config flag has been renamed to "--redocly" (or -c as shorthand).`],
+];
+
+const OPTIONS_END = "--";
+const VALUE_SEPARATOR = "=";
+const BOOLEAN_VALUES: ReadonlySet<string> = new Set(["true", "false"]);
+const LETTER = /^[a-z]$/i;
+
+/** A flag as written before `--`: its name (`--redoc`, `-o`) and the text after `=`, if any. */
+export interface WrittenFlag {
+  readonly name: string;
+  readonly value: string | undefined;
+}
+
+export function writtenFlags(argv: readonly string[]): WrittenFlag[] {
+  const end = argv.indexOf(OPTIONS_END);
+  return (end === -1 ? argv : argv.slice(0, end))
+    .filter((arg) => arg.startsWith(SHORT_PREFIX) && arg !== SHORT_PREFIX)
+    .map((arg) => {
+      const at = arg.indexOf(VALUE_SEPARATOR);
+      return at === -1
+        ? { name: arg, value: undefined }
+        : { name: arg.slice(0, at), value: arg.slice(at + 1) };
+    });
+}
+
+/**
+ * A long flag as yargs-parser reads it: in kebab-case and without `--no-`, so `--immutableTypes`
+ * and `--no-immutable-types` are `--immutable-types`. A short flag stays as written.
+ */
+function canonicalFlagName(name: string): string {
+  if (!name.startsWith(LONG_PREFIX)) {
+    return name;
+  }
+  const bare = name.startsWith(NEGATION_PREFIX)
+    ? name.slice(NEGATION_PREFIX.length)
+    : name.slice(LONG_PREFIX.length);
+  return `${LONG_PREFIX}${kebabCase(bare)}`;
+}
+
+/** An old flag fails by its name in any spelling, also with a value (`--redoc=redocly.yaml`). */
+export function rejectRemovedFlags(flags: readonly WrittenFlag[]): void {
+  const names = new Set(flags.map(({ name }) => canonicalFlagName(name)));
+  for (const [flag, message] of REMOVED_FLAGS) {
+    if (names.has(flag)) {
+      throw cliError("CLI_FLAG_REMOVED", message);
+    }
+  }
+}
+
+/**
+ * A boolean flag takes `=true` or `=false`, and its `--no-` form takes no value. yargs-parser read
+ * any other value as false (`--enum=1`, `--alphabetize=yes`), which turned the option off.
+ */
+export function rejectInvalidBooleans(flags: readonly WrittenFlag[]): void {
+  for (const { name, value } of flags) {
+    const negated = name.startsWith(NEGATION_PREFIX)
+      ? `${LONG_PREFIX}${name.slice(NEGATION_PREFIX.length)}`
+      : undefined;
+    const isNegatedWithValue = negated !== undefined && BOOLEAN_FLAG_NAMES.has(negated);
+    const isInvalid = BOOLEAN_FLAG_NAMES.has(name) && !BOOLEAN_VALUES.has(value ?? "true");
+    if (value !== undefined && (isNegatedWithValue || isInvalid)) {
+      throw cliError(
+        "CLI_FLAG_INVALID",
+        `${name}=${value}: a boolean flag takes no value, or =true or =false.`,
+      );
+    }
+  }
+}
+
+/**
+ * A flag that takes a value has no `--no-` form: yargs-parser gave it the value false, which the
+ * CLI read as the text "false" (`--no-output` wrote a file named `false`).
+ */
+export function rejectNegatedValueFlags(flags: readonly WrittenFlag[]): void {
+  for (const { name } of flags) {
+    if (name.startsWith(NEGATION_PREFIX) && VALUE_FLAG_NAMES.has(canonicalFlagName(name))) {
+      throw cliError(
+        "CLI_FLAG_INVALID",
+        `${name}: a flag that takes a value has no --no- form. Leave the flag out instead.`,
+      );
+    }
+  }
+}
+
+/** The bare names of the unknown flags in a written long flag or a group of short flags. */
+function unknownNamesOf({ name }: WrittenFlag): string[] {
+  if (name.startsWith(LONG_PREFIX)) {
+    return KNOWN_LONG_FLAG_NAMES.has(canonicalFlagName(name))
+      ? []
+      : [name.slice(LONG_PREFIX.length)];
+  }
+  return [...name.slice(SHORT_PREFIX.length)].filter(
+    (letter) => LETTER.test(letter) && !KNOWN_SHORT_FLAGS.has(letter),
+  );
+}
+
+/**
+ * The unknown flags, to declare as boolean: yargs-parser gives an undeclared flag the next
+ * argument as its value, so `--alphabetise api.yaml` took the schema path and read stdin. An
+ * unknown flag is ignored, so it takes a value only as `--flag=value`.
+ */
+export function unknownFlagNames(flags: readonly WrittenFlag[]): string[] {
+  return [...new Set(flags.flatMap(unknownNamesOf))];
+}

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,14 +28,17 @@ 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",
   CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING",
   CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING",
   CLI_INPUT_MISSING: "CLI_INPUT_MISSING",
+  CLI_INPUT_EXTRA: "CLI_INPUT_EXTRA",
   CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT",
   CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE",
   CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID",

package/src/domain/location-text.ts

@@ -0,0 +1,27 @@
+/** 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;
+
+/** The schemes the generator reads, which mark a URL also without `//` (`file:api.yaml`). */
+const READ_SCHEMES: ReadonlySet<string> = new Set(["file:", "http:", "https:"]);
+
+const AUTHORITY_START = "//";
+
+/**
+ * Whether the location is written as a URL, not as a file path: a scheme the generator reads, or
+ * any scheme followed by `//` (`s3://bucket/api.yaml`). Another text before a colon is part of a
+ * file name, as it is on POSIX file systems (`out:v2.ts`, `spec:v2.yaml`).
+ */
+export function hasUrlScheme(location: string): boolean {
+  const scheme = URL_SCHEME.exec(location)?.[0];
+  if (scheme === undefined) {
+    return false;
+  }
+  return (
+    READ_SCHEMES.has(scheme.toLowerCase()) || location.startsWith(AUTHORITY_START, scheme.length)
+  );
+}

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],