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

package/src/cli/cli-arguments.ts

@@ -2,51 +2,28 @@ import { kebabCase } from "scule";
 import parser from "yargs-parser";
 import type { OutputFixName } from "../domain/output-fixes.js";
 import { cliError } from "./cli-errors.js";
+import {
+  ALIASES,
+  BOOLEAN_FLAGS,
+  GENERATOR_FLAGS,
+  type GeneratorFlag,
+  type GeneratorFlags,
+  KNOWN_FLAGS,
+  STRING_FLAGS,
+} from "./cli-flag-names.js";
+import { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
 import { fixNamesOf } from "./fix-option.js";
+import {
+  rejectInvalidBooleans,
+  rejectNegatedValueFlags,
+  rejectRemovedFlags,
+  unknownFlagNames,
+  writtenFlags,
+} from "./written-flags.js";
 
-/** The CLI's arguments, parsed as the original CLI parsed them (yargs-parser). */
-
-/** Boolean flags that become generator options (camelCase; yargs also accepts kebab-case). */
-export const GENERATOR_FLAGS = [
-  "additionalProperties",
-  "alphabetize",
-  "arrayLength",
-  "binaryAsBlob",
-  "conditionalEnums",
-  "dedupeEnums",
-  "defaultNonNullable",
-  "emptyObjectsUnknown",
-  "enum",
-  "enumValues",
-  "excludeDeprecated",
-  "exportType",
-  "generatePathParams",
-  "immutable",
-  "lint",
-  "makePathsEnum",
-  "pathParamsAsTypes",
-  "propertiesRequiredByDefault",
-  "readWriteMarkers",
-  "rootTypes",
-  "rootTypesKeepCasing",
-  "rootTypesNoSchemaPrefix",
-] as const;
-
-export type GeneratorFlag = (typeof GENERATOR_FLAGS)[number];
-
-export type GeneratorFlags = Readonly<Partial<Record<GeneratorFlag, boolean>>>;
-
-// `contentNever` was a boolean flag of the original CLI that no code reads; it stays in the list
-// so that `--content-never <input>` keeps parsing as a flag and an input.
-const CAMEL_CASE_BOOLEAN_FLAGS = [...GENERATOR_FLAGS, "check", "contentNever", "help"];
+export { GENERATOR_FLAGS, type GeneratorFlag, type GeneratorFlags } from "./cli-flag-names.js";
 
-// yargs-parser matches the `boolean` list by the exact spelling of the flag: with camelCase names
-// only, `--root-types schema.yaml` took the path as the flag's value (upstream #2523). Both
-// spellings are listed.
-const BOOLEAN_FLAGS = [
-  ...CAMEL_CASE_BOOLEAN_FLAGS,
-  ...CAMEL_CASE_BOOLEAN_FLAGS.map((flag) => kebabCase(flag)),
-];
+/** The CLI's arguments, parsed as the original CLI parsed them (yargs-parser). */
 
 /** The `$ref` limits as the user wrote them; unset flags are absent. */
 export interface CliRefLimits {
@@ -70,101 +47,9 @@ export interface CliArguments {
   readonly unknownFlags: readonly string[];
 }
 
-/** 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).`],
-];
-
 /** Flags that only work together with `--root-types`. */
 const ROOT_TYPES_FLAGS = ["rootTypesNoSchemaPrefix", "rootTypesKeepCasing"] as const;
 
-const OPTIONS_END = "--";
-const LONG_PREFIX = "--";
-const NEGATION_PREFIX = "--no-";
-const VALUE_SEPARATOR = "=";
-const BOOLEAN_VALUES: ReadonlySet<string> = new Set(["true", "false"]);
-
-/** A flag as written before `--`: its name (`--redoc`, `-o`) and the text after `=`, if any. */
-interface WrittenFlag {
-  readonly name: string;
-  readonly value: string | undefined;
-}
-
-function writtenFlags(argv: readonly string[]): WrittenFlag[] {
-  const end = argv.indexOf(OPTIONS_END);
-  return (end === -1 ? argv : argv.slice(0, end))
-    .filter((arg) => arg.startsWith("-") && arg !== "-")
-    .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`). */
-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);
-    }
-  }
-}
-
-const ALIASES = { redocly: ["c"], exportType: ["t"], output: ["o"] };
-
-/** The short aliases of boolean flags (`-t`), which take a value the same way (`-t=true`). */
-const BOOLEAN_ALIASES = Object.entries(ALIASES)
-  .filter(([flag]) => CAMEL_CASE_BOOLEAN_FLAGS.includes(flag))
-  .flatMap(([, aliases]) => aliases.map((alias) => `-${alias}`));
-
-const BOOLEAN_FLAG_NAMES: ReadonlySet<string> = new Set([
-  ...BOOLEAN_FLAGS.map((flag) => `${LONG_PREFIX}${flag}`),
-  ...BOOLEAN_ALIASES,
-]);
-
-/**
- * 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.
- */
-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.`,
-      );
-    }
-  }
-}
-
 /** Notices for flags that have no effect in this combination, printed before the run. */
 export function ineffectiveFlagNotices(flags: GeneratorFlags): string[] {
   if (flags.rootTypes === true) {
@@ -221,22 +106,6 @@ function refLimitsOf(parsed: parser.Arguments): CliRefLimits {
   };
 }
 
-/** String flags, in both spellings, so that a value such as `8080` is not read as a number. */
-const STRING_FLAGS = [
-  "output",
-  "redocly",
-  "fix",
-  ...["localRefRoot", "remoteRefHosts"].flatMap((flag) => [flag, kebabCase(flag)]),
-];
-
-/** Every name yargs-parser can return for a flag this CLI reads. */
-const KNOWN_FLAGS = new Set<string>([
-  ...BOOLEAN_FLAGS,
-  ...STRING_FLAGS,
-  ...Object.values(ALIASES).flat(),
-  "version",
-]);
-
 /**
  * Flags that no code reads. The original CLI ignored them silently, so a typo such as
  * `--alphabetise` gave other output with no hint; they still do not fail the run.
@@ -258,22 +127,42 @@ function writtenFlagName(key: string, argv: readonly string[]): string {
   return isNegated ? negated : `--${kebabCase(key)}`;
 }
 
+/**
+ * The one schema argument. More than one fails with `CLI_INPUT_EXTRA`: the original CLI read the
+ * first and dropped the rest, so a glob the shell expanded (`g/*.yaml`) generated one schema.
+ */
+function inputOf(positionals: readonly (string | number)[]): string | undefined {
+  if (positionals.length > 1) {
+    throw cliError(
+      "CLI_INPUT_EXTRA",
+      `Only one schema argument is allowed, but ${positionals.length} were given: ` +
+        `${positionals.join(" ")}. A shell expands an unquoted *; to generate several ` +
+        `schemas, list them under \`apis\` in redocly.yaml. See ${MULTIPLE_SCHEMAS_DOCS_URL}`,
+    );
+  }
+  return optionalString(positionals[0]);
+}
+
 /**
  * Parse the arguments after `node cli.js`. Fails with `CLI_FLAG_REMOVED` for an old flag, with
- * `CLI_FLAG_INVALID` for a boolean flag with another value than true or false, and with
+ * `CLI_FLAG_INVALID` for a boolean flag with another value than true or false or a `--no-` form
+ * of a flag that takes a value, with `CLI_INPUT_EXTRA` for a second schema argument, and with
  * `OPTION_FIX_UNKNOWN` for an unknown `--fix` name.
  */
 export function parseCliArguments(argv: readonly string[]): CliArguments {
   const flags = writtenFlags(argv);
   rejectRemovedFlags(flags);
   rejectInvalidBooleans(flags);
+  rejectNegatedValueFlags(flags);
   const parsed = parser([...argv], {
-    boolean: BOOLEAN_FLAGS,
+    boolean: [...BOOLEAN_FLAGS, ...unknownFlagNames(flags)],
     string: STRING_FLAGS,
     alias: ALIASES,
+    // A schema path is a file name: `1.10` is not the number 1.1.
+    configuration: { "parse-positional-numbers": false },
   });
   return {
-    input: optionalString(parsed._[0]),
+    input: inputOf(parsed._),
     output: lastString(parsed.output),
     redocly: lastString(parsed.redocly),
     isCheck: parsed.check === true,

package/src/cli/cli-errors.ts

@@ -109,6 +109,7 @@ const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   CLI_CONFIG_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
   CLI_CHECK_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
   CLI_INPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
+  CLI_INPUT_EXTRA: { exitCode: EXIT_CODES.USAGE },
   CLI_OUTPUT_IS_INPUT: { exitCode: EXIT_CODES.USAGE },
   CLI_OUTPUT_DUPLICATE: { exitCode: EXIT_CODES.USAGE },
   CLI_OUTPUT_INVALID: { exitCode: EXIT_CODES.USAGE },

package/src/cli/cli-flag-names.ts

@@ -0,0 +1,99 @@
+import { kebabCase } from "scule";
+
+/** The names of the CLI's flags, in the spellings yargs-parser is told about. */
+
+/** Boolean flags that become generator options (camelCase; yargs also accepts kebab-case). */
+export const GENERATOR_FLAGS = [
+  "additionalProperties",
+  "alphabetize",
+  "arrayLength",
+  "binaryAsBlob",
+  "conditionalEnums",
+  "dedupeEnums",
+  "defaultNonNullable",
+  "emptyObjectsUnknown",
+  "enum",
+  "enumValues",
+  "excludeDeprecated",
+  "exportType",
+  "generatePathParams",
+  "immutable",
+  "lint",
+  "makePathsEnum",
+  "pathParamsAsTypes",
+  "propertiesRequiredByDefault",
+  "readWriteMarkers",
+  "rootTypes",
+  "rootTypesKeepCasing",
+  "rootTypesNoSchemaPrefix",
+] as const;
+
+export type GeneratorFlag = (typeof GENERATOR_FLAGS)[number];
+
+export type GeneratorFlags = Readonly<Partial<Record<GeneratorFlag, boolean>>>;
+
+// `contentNever` was a boolean flag of the original CLI that no code reads; it stays in the list
+// so that `--content-never <input>` keeps parsing as a flag and an input.
+const CAMEL_CASE_BOOLEAN_FLAGS = [...GENERATOR_FLAGS, "check", "contentNever", "help"];
+
+// yargs-parser matches the `boolean` list by the exact spelling of the flag: with camelCase names
+// only, `--root-types schema.yaml` took the path as the flag's value (upstream #2523). Both
+// spellings are listed.
+export const BOOLEAN_FLAGS = [
+  ...CAMEL_CASE_BOOLEAN_FLAGS,
+  ...CAMEL_CASE_BOOLEAN_FLAGS.map((flag) => kebabCase(flag)),
+];
+
+export const ALIASES = { redocly: ["c"], exportType: ["t"], output: ["o"] };
+
+const CAMEL_CASE_STRING_FLAGS = ["output", "redocly", "fix", "localRefRoot", "remoteRefHosts"];
+
+/** String flags, in both spellings, so that a value such as `8080` is not read as a number. */
+export const STRING_FLAGS = [
+  ...CAMEL_CASE_STRING_FLAGS,
+  ...CAMEL_CASE_STRING_FLAGS.map((flag) => kebabCase(flag)),
+];
+
+/** Every name yargs-parser can return for a flag this CLI reads. */
+export const KNOWN_FLAGS: ReadonlySet<string> = new Set<string>([
+  ...BOOLEAN_FLAGS,
+  ...STRING_FLAGS,
+  ...Object.values(ALIASES).flat(),
+  "version",
+]);
+
+export const LONG_PREFIX = "--";
+export const SHORT_PREFIX = "-";
+export const NEGATION_PREFIX = "--no-";
+
+/** The short aliases of `flags`, as written on the command line (`-t`). */
+function aliasesOf(flags: readonly string[]): string[] {
+  return Object.entries(ALIASES)
+    .filter(([flag]) => flags.includes(flag))
+    .flatMap(([, aliases]) => aliases.map((alias) => `${SHORT_PREFIX}${alias}`));
+}
+
+/** The boolean flags as written, `--` and `-` included; they take `=true` or `=false`. */
+export const BOOLEAN_FLAG_NAMES: ReadonlySet<string> = new Set([
+  ...BOOLEAN_FLAGS.map((flag) => `${LONG_PREFIX}${flag}`),
+  ...aliasesOf(CAMEL_CASE_BOOLEAN_FLAGS),
+]);
+
+/**
+ * The flags that take a value, as `canonicalFlagName` gives them: kebab-case, and the short
+ * aliases with `--`, since yargs-parser reads `--no-o` as the negation of `-o`.
+ */
+export const VALUE_FLAG_NAMES: ReadonlySet<string> = new Set([
+  ...CAMEL_CASE_STRING_FLAGS.map((flag) => `${LONG_PREFIX}${kebabCase(flag)}`),
+  ...aliasesOf(CAMEL_CASE_STRING_FLAGS).map((alias) => `${SHORT_PREFIX}${alias}`),
+]);
+
+/** The long flags this CLI reads, as `canonicalFlagName` gives them. */
+export const KNOWN_LONG_FLAG_NAMES: ReadonlySet<string> = new Set(
+  [...KNOWN_FLAGS]
+    .filter((flag) => flag.length > 1)
+    .map((flag) => `${LONG_PREFIX}${kebabCase(flag)}`),
+);
+
+/** The short flags this CLI reads, without the `-`. */
+export const KNOWN_SHORT_FLAGS: ReadonlySet<string> = new Set(Object.values(ALIASES).flat());

package/src/cli/cli-output.ts

@@ -187,12 +187,15 @@ export function ensureOutputIsOwn(
   }
 }
 
-/** `CLI_OUTPUT_DUPLICATE` for `output`, which is also the output of the `others` (named). */
+/**
+ * `CLI_OUTPUT_DUPLICATE` for `output`, which is also the output of the `others` (named). Only
+ * APIs share outputs, and the CLI names the API before the message (`ApiFailure`).
+ */
 export function duplicateOutputError(output: NamedOutput, others: readonly string[]): Error {
   return cliError(
     "CLI_OUTPUT_DUPLICATE",
-    `The output ${output.output} of API ${output.source} is also the output of ` +
-      `${others.join(", ")}: they would overwrite each other. Give each API its own output file.`,
+    `The output ${output.output} is also the output of ${others.join(", ")}: they would ` +
+      "overwrite each other. Give each API its own output file.",
   );
 }
 
@@ -216,13 +219,24 @@ function printDone(run: CliRun, output: OutputFile): void {
   run.deps.console.info(`🚀 ${target} ${duration}`);
 }
 
+const CRLF = /\r\n/g;
+const LF = "\n";
+
+/**
+ * The text with LF line ends. Git with `core.autocrlf` checks a committed file out with CRLF on
+ * Windows, so `--check` compares lines, not line ends.
+ */
+function withLfLineEnds(text: string): string {
+  return text.replace(CRLF, LF);
+}
+
 /**
- * With `--check`, fail with `OUTPUT_STALE` when the file differs from `contents` and leave it
- * alone otherwise. Without it, write the file and print where it went.
+ * With `--check`, fail with `OUTPUT_STALE` when the file differs from `contents` (line ends
+ * aside) and leave it alone otherwise. Without it, write the file and print where it went.
  */
 export function emitOutput(run: CliRun, output: OutputFile, contents: string): void {
   if (run.args.isCheck) {
-    if (run.deps.files.readText(output.file) !== contents) {
+    if (withLfLineEnds(run.deps.files.readText(output.file)) !== withLfLineEnds(contents)) {
       // The original message, then the file: with several APIs it tells which one is stale.
       throw cliError(
         "OUTPUT_STALE",

package/src/cli/main.ts

@@ -27,9 +27,10 @@ function readVersion(): string {
   return packageJson.version;
 }
 
+/** The style of the CLI's own lines, which go to stdout. */
 function terminalStyle(): TextStyle {
   const palette = colors.create();
-  palette.enabled = terminalSupportsColor();
+  palette.enabled = terminalSupportsColor("stdout");
   return {
     bold: (text) => palette.bold(text),
     green: (text) => palette.green(text),

package/src/cli/redocly-apis.ts

@@ -104,7 +104,8 @@ interface ApiRun {
 }
 
 /**
- * The generator options of one API: its own settings win over the CLI's flags. A flag that has
+ * 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.
  */
@@ -119,7 +120,7 @@ function apiOptions(run: CliRun, apiRun: ApiRun, target: ApiTarget): GeneratorOp
     ...apiRun.refLimits,
     ...apiRefLimitOptions(name, settings, configRoot),
     ...fixOption(apiFixNames(name, settings) ?? run.args.fix),
-    redocly: apiRun.redocly,
+    redocly: run.deps.redoclyConfigs.forApi(apiRun.redocly, name),
   };
 }
 
@@ -146,9 +147,12 @@ async function generateApi(run: CliRun, apiRun: ApiRun, target: ApiTarget): Prom
     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 options = apiOptions(run, apiRun, target);
   try {
@@ -159,6 +163,18 @@ async function generateApi(run: CliRun, apiRun: ApiRun, target: ApiTarget): Prom
   }
 }
 
+/**
+ * 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);
+  }
+}
+
 /**
  * The schema and the output of every API, and the config file itself. A location that is no
  * text or no valid URL is left out: it is no file that an output could be, and its own API fails

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/errors.ts

@@ -38,6 +38,7 @@ export const ERROR_CODES = {
   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

@@ -6,7 +6,22 @@
  */
 const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
 
-/** Whether the location is written as a URL, not as a file path. */
+/** 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 {
-  return URL_SCHEME.test(location);
+  const scheme = URL_SCHEME.exec(location)?.[0];
+  if (scheme === undefined) {
+    return false;
+  }
+  return (
+    READ_SCHEMES.has(scheme.toLowerCase()) || location.startsWith(AUTHORITY_START, scheme.length)
+  );
 }