@goflag/cli 0.2.7 → 0.2.9

package/dist/cli.js

@@ -12,7 +12,7 @@ import {
   renderTerminal,
   runAudit,
   summarize
-} from "./chunk-UOKYUKHQ.js";
+} from "./chunk-TAZEAIFI.js";
 
 // src/report/diff.ts
 function collectFindings(report) {
@@ -287,97 +287,505 @@ Raise --start-timeout, check the command listens on that URL, or point --start-c
   }
 }
 
-// src/cli-args.ts
-var PROFILE_HELP = PROFILE_NAMES.map(
-  (name) => `                         ${name} \u2014 ${PROFILES[name].description}`
-).join("\n");
-var HELP = `goflag \u2014 audit a site for broken links, missing translations, and SEO metadata
-
-Usage:
-  goflag <url> [options]
-  goflag rules              Print the rule catalogue as JSON and exit. No crawl
-                            and no network: every rule with its severity, its
-                            rigor and the documents it cites.
-
-Options:
-  --json                 Print the JSON report to stdout (nothing else).
-  --summary, -s          Roll findings up (dedup by link/rule/code). Pairs
-                         with --json for a compact, agent-friendly payload.
-  --report <file>        Write the (full) JSON report to <file>.
-  --depth <n>            How far to follow links out of each page (0 = follow
-                         none). Sitemap URLs are seeded regardless, so --depth 0
-                         alone is not "entry page only" \u2014 add --no-sitemap for
-                         that. Default: 2.
-  --max-pages <n>        Page budget for the crawl. A hard cap under
-                         --coverage all; under structural coverage the selection
-                         wins and the budget is max(<n>, selected + 5).
-                         Default: 200.
-  --coverage <mode>      How to choose which pages to audit.
-                         "structural" (default when a sitemap is found) keeps
-                         every standalone page and samples families of pages
-                         built from one template. "all" audits everything the
-                         sitemap lists, up to --max-pages.
-  --include <glob>       Only crawl paths matching <glob> (repeatable).
-  --exclude <glob>       Skip paths matching <glob> (repeatable).
-  --locales <list>       Comma-separated locales the site serves, e.g.
-                         "fr,en,pt-br". Unioned with what the sitemap shows,
-                         never substituted for it, and the only way to make a
-                         locale the site does not serve yet show up as missing.
-                         Also folds /en/\u2026 and /fr/\u2026 into one route family for
-                         structural coverage, so pass it on any locale-prefixed
-                         site.
-  --ignore-holes <glob>  Route (locale-free) that is deliberately not
-                         translated everywhere, so its gaps are not reported
-                         as missing translations (repeatable).
-  --no-sitemap           Do not discover the sitemap; crawl from <url> only.
-                         Discovery is on by default because link-only crawling
-                         cannot find locales a site never links to.
-  --profile <name>       Policy overlay on the rule set \u2014 it changes how
-                         loudly a rule fires, never what it observes:
-${PROFILE_HELP}
-  --conformance          Report EVERY rule's status on every page (pass /
-                         fail / warn / na), not just the violations. Answers
-                         "where do we stand against the catalog?"; pairs with
-                         --json.
-  --advisories           Attach the prose rules \u2014 the judgment calls goflag
-                         refuses to fake \u2014 each with the observed facts an
-                         agent needs to judge it. Never affects the gate.
-  --fail-on <level>      Exit 1 at or above this severity: warning (default),
-                         error, or never.
-  --regressions-only     Weaken the gate: fail only on findings that are NEW
-                         relative to --baseline. Known findings stop blocking
-                         the build \u2014 a green run no longer means a clean site.
-                         Requires --baseline.
-  --baseline <file>      Stored report to compare against. Use with
-                         --regressions-only.
-  --update-baseline      Write this run to --baseline and exit 0, instead of
-                         judging against it. Use it to capture a baseline, or
-                         to accept findings you have decided to live with \u2014
-                         it says what it accepted.
-  --max-debt <n>         Fail when the site carries more than <n> findings in
-                         total, whether new or known. Lower it as you fix, to
-                         stop a baseline from fossilising.
-  --start <cmd>          Boot <cmd>, wait for <url> to answer, audit, then
-                         stop it. Use to gate a merge on the built app before
-                         it ships.
-  --start-cwd <dir>      Directory to run --start in. Defaults to the current
-                         one; set it when auditing a monorepo package from the
-                         repository root.
-  --start-timeout <ms>   How long to wait for --start to answer. Default: 60000.
-  --no-external          Do not probe off-origin (external) links.
-  --static               Static HTML only; never launch headless Chromium.
-  --allow-insecure-tls   Accept self-signed / invalid TLS (localhost, tunnels).
-  --timeout <ms>         Per-request timeout in ms, for page fetches and link
-                         probes alike. Unset, the defaults differ: 8000 for link
-                         probes, 15000 for page fetches.
-  --verbose, -V          Log every page as it is analyzed.
-  --quiet, -q            Suppress the live progress output.
-  --no-color             Disable coloured output.
-  -h, --help             Show this help.
-  -v, --version          Show the version.
-
-Exit codes: 0 clean, 1 findings found, 2 fatal error.`;
+// src/lib/flags/registry.ts
 var FAIL_ON_LEVELS = ["warning", "error", "never"];
+function toInt(value, flag) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`${flag} expects a non-negative integer`);
+  return n;
+}
+var FLAGS = [
+  {
+    name: "--json",
+    label: "--json",
+    group: "output",
+    help: ["Print the JSON report to stdout (nothing else)."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.json = true;
+    }
+  },
+  {
+    name: "--summary",
+    short: "-s",
+    label: "--summary, -s",
+    group: "output",
+    help: [
+      "Roll findings up (dedup by link/rule/code). Pairs",
+      "with --json for a compact, agent-friendly payload."
+    ],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.summary = true;
+    }
+  },
+  {
+    name: "--report",
+    arg: "<file>",
+    label: "--report <file>",
+    group: "output",
+    help: ["Write the (full) JSON report to <file>."],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.report = value;
+    }
+  },
+  {
+    name: "--depth",
+    arg: "<n>",
+    label: "--depth <n>",
+    group: "crawl",
+    default: "2",
+    help: [
+      "How far to follow links out of each page (0 = follow",
+      "none). Sitemap URLs are seeded regardless, so --depth 0",
+      'alone is not "entry page only" \u2014 add --no-sitemap for',
+      "that. Default: 2."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      parsed.options.depth = toInt(value, flag);
+    }
+  },
+  {
+    name: "--max-pages",
+    arg: "<n>",
+    label: "--max-pages <n>",
+    group: "crawl",
+    default: "200",
+    help: [
+      "Page budget for the crawl. A hard cap under",
+      "--coverage all; under structural coverage the selection",
+      "wins and the budget is max(<n>, selected + 5).",
+      "Default: 200."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      parsed.options.maxPages = toInt(value, flag);
+    }
+  },
+  {
+    name: "--coverage",
+    arg: "<mode>",
+    label: "--coverage <mode>",
+    group: "crawl",
+    default: "structural when a sitemap is found, all otherwise",
+    help: [
+      "How to choose which pages to audit.",
+      '"structural" (default when a sitemap is found) keeps',
+      "every standalone page and samples families of pages",
+      'built from one template. "all" audits everything the',
+      "sitemap lists, up to --max-pages."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      if (value !== "structural" && value !== "all") {
+        throw new Error(`${flag} takes "structural" or "all", not ${JSON.stringify(value)}`);
+      }
+      parsed.options.coverage = value;
+    }
+  },
+  {
+    name: "--include",
+    arg: "<glob>",
+    label: "--include <glob>",
+    group: "crawl",
+    help: ["Only crawl paths matching <glob> (repeatable)."],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.options.include.push(value);
+    }
+  },
+  {
+    name: "--exclude",
+    arg: "<glob>",
+    label: "--exclude <glob>",
+    group: "crawl",
+    help: ["Skip paths matching <glob> (repeatable)."],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.options.exclude.push(value);
+    }
+  },
+  {
+    name: "--locales",
+    arg: "<list>",
+    label: "--locales <list>",
+    group: "i18n",
+    help: [
+      "Comma-separated locales the site serves, e.g.",
+      '"fr,en,pt-br". Unioned with what the sitemap shows,',
+      "never substituted for it, and the only way to make a",
+      "locale the site does not serve yet show up as missing.",
+      "Also folds /en/\u2026 and /fr/\u2026 into one route family for",
+      "structural coverage, so pass it on any locale-prefixed",
+      "site."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      const tags = value.split(",").map((t) => t.trim()).filter(Boolean);
+      if (tags.length === 0) throw new Error(`${flag} expects at least one locale`);
+      parsed.options.locales = [...parsed.options.locales ?? [], ...tags];
+    }
+  },
+  {
+    name: "--ignore-holes",
+    arg: "<glob>",
+    label: "--ignore-holes <glob>",
+    group: "i18n",
+    help: [
+      "Route (locale-free) that is deliberately not",
+      "translated everywhere, so its gaps are not reported",
+      "as missing translations (repeatable)."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.options.ignoreHoles = [...parsed.options.ignoreHoles ?? [], value];
+    }
+  },
+  {
+    name: "--no-sitemap",
+    label: "--no-sitemap",
+    group: "crawl",
+    help: [
+      "Do not discover the sitemap; crawl from <url> only.",
+      "Discovery is on by default because link-only crawling",
+      "cannot find locales a site never links to."
+    ],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.options.noSitemap = true;
+    }
+  },
+  {
+    name: "--profile",
+    arg: "<name>",
+    label: "--profile <name>",
+    group: "gate",
+    default: "default",
+    help: [
+      "Policy overlay on the rule set \u2014 it changes how",
+      "loudly a rule fires, never what it observes:"
+    ],
+    dynamicTail: () => PROFILE_NAMES.map((n) => `${n} \u2014 ${PROFILES[n].description}`),
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      if (!PROFILE_NAMES.includes(value)) {
+        throw new Error(`${flag} expects one of: ${PROFILE_NAMES.join(", ")}`);
+      }
+      parsed.options.profile = value;
+    }
+  },
+  {
+    name: "--conformance",
+    label: "--conformance",
+    group: "output",
+    help: [
+      "Report EVERY rule's status on every page (pass /",
+      "fail / warn / na), not just the violations. Answers",
+      '"where do we stand against the catalog?"; pairs with',
+      "--json."
+    ],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.options.conformance = true;
+    }
+  },
+  {
+    name: "--advisories",
+    label: "--advisories",
+    group: "output",
+    help: [
+      "Attach the prose rules \u2014 the judgment calls goflag",
+      "refuses to fake \u2014 each with the observed facts an",
+      "agent needs to judge it. Never affects the gate."
+    ],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.options.advisories = true;
+    }
+  },
+  {
+    name: "--fail-on",
+    arg: "<level>",
+    label: "--fail-on <level>",
+    group: "gate",
+    default: "warning",
+    help: ["Exit 1 at or above this severity: warning (default),", "error, or never."],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      const level = value;
+      if (!FAIL_ON_LEVELS.includes(level)) {
+        throw new Error(`${flag} expects one of: ${FAIL_ON_LEVELS.join(", ")}`);
+      }
+      parsed.failOn = level;
+    }
+  },
+  {
+    name: "--regressions-only",
+    label: "--regressions-only",
+    group: "gate",
+    requires: "--baseline",
+    help: [
+      "Weaken the gate: fail only on findings that are NEW",
+      "relative to --baseline. Known findings stop blocking",
+      "the build \u2014 a green run no longer means a clean site.",
+      "Requires --baseline."
+    ],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.regressionsOnly = true;
+    }
+  },
+  {
+    name: "--baseline",
+    arg: "<file>",
+    label: "--baseline <file>",
+    group: "gate",
+    help: ["Stored report to compare against. Use with", "--regressions-only."],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.baseline = value;
+    }
+  },
+  {
+    name: "--update-baseline",
+    label: "--update-baseline",
+    group: "gate",
+    requires: "--baseline",
+    help: [
+      "Write this run to --baseline and exit 0, instead of",
+      "judging against it. Use it to capture a baseline, or",
+      "to accept findings you have decided to live with \u2014",
+      "it says what it accepted."
+    ],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.updateBaseline = true;
+    }
+  },
+  {
+    name: "--max-debt",
+    arg: "<n>",
+    label: "--max-debt <n>",
+    group: "gate",
+    help: [
+      "Fail when the site carries more than <n> findings in",
+      "total, whether new or known. Lower it as you fix, to",
+      "stop a baseline from fossilising."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      parsed.maxDebt = toInt(value, flag);
+    }
+  },
+  {
+    name: "--start",
+    arg: "<cmd>",
+    label: "--start <cmd>",
+    group: "boot",
+    help: [
+      "Boot <cmd>, wait for <url> to answer, audit, then",
+      "stop it. Use to gate a merge on the built app before",
+      "it ships."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.start = value;
+    }
+  },
+  {
+    name: "--start-cwd",
+    arg: "<dir>",
+    label: "--start-cwd <dir>",
+    group: "boot",
+    default: "the current directory",
+    help: [
+      "Directory to run --start in. Defaults to the current",
+      "one; set it when auditing a monorepo package from the",
+      "repository root."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value }) => {
+      parsed.startCwd = value;
+    }
+  },
+  {
+    name: "--start-timeout",
+    arg: "<ms>",
+    label: "--start-timeout <ms>",
+    group: "boot",
+    default: "60000",
+    help: ["How long to wait for --start to answer. Default: 60000."],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      parsed.startTimeoutMs = toInt(value, flag);
+    }
+  },
+  {
+    name: "--no-external",
+    label: "--no-external",
+    group: "fetch",
+    help: ["Do not probe off-origin (external) links."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.options.checkExternal = false;
+    }
+  },
+  {
+    name: "--static",
+    label: "--static",
+    group: "fetch",
+    help: ["Static HTML only; never launch headless Chromium."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.options.static = true;
+    }
+  },
+  {
+    name: "--allow-insecure-tls",
+    label: "--allow-insecure-tls",
+    group: "fetch",
+    help: ["Accept self-signed / invalid TLS (localhost, tunnels)."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.options.allowInsecureTls = true;
+    }
+  },
+  {
+    name: "--timeout",
+    arg: "<ms>",
+    label: "--timeout <ms>",
+    group: "fetch",
+    default: "8000 for link probes, 15000 for page fetches",
+    help: [
+      "Per-request timeout in ms, for page fetches and link",
+      "probes alike. Unset, the defaults differ: 8000 for link",
+      "probes, 15000 for page fetches."
+    ],
+    takesValue: true,
+    apply: ({ parsed, value, flag }) => {
+      parsed.options.timeoutMs = toInt(value, flag);
+    }
+  },
+  {
+    name: "--verbose",
+    short: "-V",
+    label: "--verbose, -V",
+    group: "terminal",
+    help: ["Log every page as it is analyzed."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.logMode = "verbose";
+    }
+  },
+  {
+    name: "--quiet",
+    short: "-q",
+    label: "--quiet, -q",
+    group: "terminal",
+    help: ["Suppress the live progress output."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.logMode = "quiet";
+    }
+  },
+  {
+    name: "--no-color",
+    label: "--no-color",
+    group: "terminal",
+    default: "colour when stdout is a TTY and NO_COLOR is unset",
+    help: ["Disable coloured output."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.color = false;
+    }
+  },
+  {
+    name: "--help",
+    short: "-h",
+    label: "-h, --help",
+    group: "terminal",
+    help: ["Show this help."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.help = true;
+    }
+  },
+  {
+    name: "--version",
+    short: "-v",
+    label: "-v, --version",
+    group: "terminal",
+    help: ["Show the version."],
+    takesValue: false,
+    apply: ({ parsed }) => {
+      parsed.version = true;
+    }
+  }
+];
+var FLAGS_BY_TOKEN = new Map(
+  FLAGS.flatMap(
+    (spec) => spec.short ? [
+      [spec.name, spec],
+      [spec.short, spec]
+    ] : [[spec.name, spec]]
+  )
+);
+var EXIT_CODES = [
+  { code: 0, label: "clean" },
+  { code: 1, label: "findings found" },
+  { code: 2, label: "fatal error" }
+];
+var COMMANDS = [
+  {
+    name: "rules",
+    help: [
+      "Print the rule catalogue as JSON and exit. No crawl",
+      "and no network: every rule with its severity, its",
+      "rigor and the documents it cites."
+    ]
+  },
+  {
+    name: "flags",
+    help: [
+      "Print this flag reference as JSON and exit. The same",
+      "table this help is rendered from, so the two cannot",
+      "disagree."
+    ]
+  }
+];
+var DESCRIPTION_COLUMN = 25;
+function block(label, lines) {
+  const pad = " ".repeat(DESCRIPTION_COLUMN);
+  return lines.map(
+    (line, i) => i === 0 ? `  ${label.padEnd(DESCRIPTION_COLUMN - 2)}${line}` : `${pad}${line}`
+  );
+}
+function renderHelp() {
+  const lines = [
+    "goflag \u2014 audit a site for broken links, missing translations, and SEO metadata",
+    "",
+    "Usage:",
+    "  goflag <url> [options]"
+  ];
+  for (const command of COMMANDS) {
+    const pad = " ".repeat(28);
+    command.help.forEach((line, i) => {
+      lines.push(i === 0 ? `  goflag ${command.name.padEnd(19)}${line}` : `${pad}${line}`);
+    });
+  }
+  lines.push("", "Options:");
+  for (const spec of FLAGS) {
+    lines.push(...block(spec.label, [...spec.help, ...spec.dynamicTail?.() ?? []]));
+  }
+  lines.push("", `Exit codes: ${EXIT_CODES.map((e) => `${e.code} ${e.label}`).join(", ")}.`);
+  return lines.join("\n");
+}
+
+// src/cli-args.ts
+var HELP = renderHelp();
+var COMMAND_NAMES = COMMANDS.map((c) => c.name);
 function parseArgs(argv) {
   const parsed = {
     json: false,
@@ -399,146 +807,20 @@ function parseArgs(argv) {
   };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    switch (arg) {
-      case "-h":
-      case "--help":
-        parsed.help = true;
-        break;
-      case "-v":
-      case "--version":
-        parsed.version = true;
-        break;
-      case "--json":
-        parsed.json = true;
-        break;
-      case "-s":
-      case "--summary":
-        parsed.summary = true;
-        break;
-      case "--no-color":
-        parsed.color = false;
-        break;
-      case "-V":
-      case "--verbose":
-        parsed.logMode = "verbose";
-        break;
-      case "-q":
-      case "--quiet":
-        parsed.logMode = "quiet";
-        break;
-      case "--static":
-        parsed.options.static = true;
-        break;
-      case "--allow-insecure-tls":
-        parsed.options.allowInsecureTls = true;
-        break;
-      case "--no-external":
-        parsed.options.checkExternal = false;
-        break;
-      case "--no-sitemap":
-        parsed.options.noSitemap = true;
-        break;
-      case "--conformance":
-        parsed.options.conformance = true;
-        break;
-      case "--advisories":
-        parsed.options.advisories = true;
-        break;
-      case "--ignore-holes":
-        parsed.options.ignoreHoles = [...parsed.options.ignoreHoles ?? [], next(i, arg)];
-        i++;
-        break;
-      case "--locales": {
-        const value = next(i, arg);
-        const tags = value.split(",").map((t) => t.trim()).filter(Boolean);
-        if (tags.length === 0) throw new Error(`${arg} expects at least one locale`);
-        parsed.options.locales = [...parsed.options.locales ?? [], ...tags];
+    const spec = arg === void 0 ? void 0 : FLAGS_BY_TOKEN.get(arg);
+    if (spec && arg !== void 0) {
+      if (spec.takesValue) {
+        spec.apply({ parsed, value: next(i, arg), flag: arg });
         i++;
-        break;
+      } else {
+        spec.apply({ parsed, value: "", flag: arg });
       }
-      case "--profile": {
-        const value = next(i, arg);
-        if (!PROFILE_NAMES.includes(value)) {
-          throw new Error(`${arg} expects one of: ${PROFILE_NAMES.join(", ")}`);
-        }
-        parsed.options.profile = value;
-        i++;
-        break;
-      }
-      case "--fail-on": {
-        const value = next(i, arg);
-        if (!FAIL_ON_LEVELS.includes(value)) {
-          throw new Error(`${arg} expects one of: ${FAIL_ON_LEVELS.join(", ")}`);
-        }
-        parsed.failOn = value;
-        i++;
-        break;
-      }
-      case "--start":
-        parsed.start = next(i, arg);
-        i++;
-        break;
-      case "--start-timeout":
-        parsed.startTimeoutMs = toInt(next(i, arg), arg);
-        i++;
-        break;
-      case "--start-cwd":
-        parsed.startCwd = next(i, arg);
-        i++;
-        break;
-      case "--report":
-        parsed.report = next(i, arg);
-        i++;
-        break;
-      case "--baseline":
-        parsed.baseline = next(i, arg);
-        i++;
-        break;
-      case "--update-baseline":
-        parsed.updateBaseline = true;
-        break;
-      case "--regressions-only":
-        parsed.regressionsOnly = true;
-        break;
-      case "--max-debt":
-        parsed.maxDebt = toInt(next(i, arg), arg);
-        i++;
-        break;
-      case "--depth":
-        parsed.options.depth = toInt(next(i, arg), arg);
-        i++;
-        break;
-      case "--coverage": {
-        const mode = next(i, arg);
-        if (mode !== "structural" && mode !== "all") {
-          throw new Error(`--coverage takes "structural" or "all", not ${JSON.stringify(mode)}`);
-        }
-        parsed.options.coverage = mode;
-        i += 1;
-        break;
-      }
-      case "--max-pages":
-        parsed.options.maxPages = toInt(next(i, arg), arg);
-        i++;
-        break;
-      case "--timeout":
-        parsed.options.timeoutMs = toInt(next(i, arg), arg);
-        i++;
-        break;
-      case "--include":
-        parsed.options.include.push(next(i, arg));
-        i++;
-        break;
-      case "--exclude":
-        parsed.options.exclude.push(next(i, arg));
-        i++;
-        break;
-      default:
-        if (arg && arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
-        if (arg === "rules" && i === 0) parsed.command = "rules";
-        else if (arg && !parsed.url) parsed.url = arg;
-        else if (arg) throw new Error(`unexpected argument: ${arg}`);
+      continue;
     }
+    if (arg && arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+    if (arg && COMMAND_NAMES.includes(arg) && i === 0) parsed.command = arg;
+    else if (arg && !parsed.url) parsed.url = arg;
+    else if (arg) throw new Error(`unexpected argument: ${arg}`);
   }
   if (parsed.updateBaseline && !parsed.baseline) {
     throw new Error("--update-baseline needs a --baseline <file> to write to");
@@ -553,11 +835,6 @@ function parseArgs(argv) {
   }
   return parsed;
 }
-function toInt(value, flag) {
-  const n = Number(value);
-  if (!Number.isInteger(n) || n < 0) throw new Error(`${flag} expects a non-negative integer`);
-  return n;
-}
 
 // src/lib/rules/sources/index.ts
 var NORMATIVE = [
@@ -979,8 +1256,11 @@ function buildRuleCatalog(version) {
       severity: rule.severity,
       kind: "boolean",
       summary: rule.summary,
-      rigor: null,
-      sources: []
+      // `null` where a cross-page rule has not declared one yet — the three
+      // that predate the field still need their sources chosen rather than
+      // guessed, and emitting the gap is how it stays visible.
+      rigor: rule.rigor ?? null,
+      sources: rule.sources ?? []
     });
   }
   for (const rule of PROSE_RULES) {
@@ -1029,6 +1309,34 @@ function serialiseCatalog(catalog) {
 `;
 }
 
+// src/lib/flags/catalog.ts
+function buildFlagCatalog(version) {
+  const flags = FLAGS.map((spec) => ({
+    name: spec.name,
+    short: spec.short ?? null,
+    arg: spec.arg ?? null,
+    default: spec.default ?? null,
+    requires: spec.requires ?? null,
+    group: spec.group,
+    description: [...spec.help, ...spec.dynamicTail?.() ?? []].join(" ")
+  }));
+  flags.sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    ...version ? { version } : {},
+    flags,
+    exitCodes: EXIT_CODES.map((e) => ({ code: e.code, label: e.label })),
+    counts: {
+      flags: flags.length,
+      withShortForm: flags.filter((f) => f.short !== null).length,
+      takingValue: flags.filter((f) => f.arg !== null).length
+    }
+  };
+}
+function serialiseFlags(catalog) {
+  return `${JSON.stringify(catalog, null, 2)}
+`;
+}
+
 // src/cli.ts
 async function readVersion() {
   try {
@@ -1074,6 +1382,10 @@ ${HELP}
     process.stdout.write(serialiseCatalog(buildRuleCatalog(await readVersion())));
     return 0;
   }
+  if (args.command === "flags") {
+    process.stdout.write(serialiseFlags(buildFlagCatalog(await readVersion())));
+    return 0;
+  }
   if (!args.url) {
     process.stderr.write(`goflag: missing <url>