@goflag/cli 0.2.5 → 0.2.8

package/dist/cli.js

@@ -4,12 +4,15 @@ import {
   Logger,
   PROFILES,
   PROFILE_NAMES,
+  PROSE_RULES,
+  RULES,
+  SITE_RULES,
   exitCode,
   renderSummaryTerminal,
   renderTerminal,
   runAudit,
   summarize
-} from "./chunk-5FO2Q3II.js";
+} from "./chunk-SKX7UCGC.js";
 
 // src/report/diff.ts
 function collectFindings(report) {
@@ -284,83 +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]
-
-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>            Crawl depth (0 = entry page only). Default: 2.
-  --max-pages <n>        Hard cap on pages crawled. 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". Authoritative: overrides what the
-                         sitemap and crawl suggest, and makes a locale the
-                         site does not serve yet show up as missing.
-  --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. Default: 8000.
-  --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,
@@ -382,145 +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];
-        i++;
-        break;
-      }
-      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);
+    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;
-      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;
+      } else {
+        spec.apply({ parsed, value: "", flag: arg });
       }
-      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 && !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");
@@ -535,10 +835,503 @@ 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 = [
+  {
+    id: "whatwg-html-title",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 the title element",
+    url: "https://html.spec.whatwg.org/multipage/semantics.html",
+    anchor: "the-title-element",
+    retrievedAt: "2026-08-06",
+    note: "Documents must have exactly one title element in the head, and its text should identify the document even out of context (e.g. in history or bookmarks)."
+  },
+  {
+    id: "whatwg-html-meta",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 the meta element",
+    url: "https://html.spec.whatwg.org/multipage/semantics.html",
+    anchor: "the-meta-element",
+    retrievedAt: "2026-08-06",
+    note: "Defines the syntax of meta: exactly one of name, http-equiv, charset or itemprop must be present, and name/http-equiv variants require a content attribute."
+  },
+  {
+    id: "whatwg-html-standard-metadata-names",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 standard metadata names",
+    url: "https://html.spec.whatwg.org/multipage/semantics.html",
+    anchor: "standard-metadata-names",
+    retrievedAt: "2026-08-06",
+    note: "The registry of standard meta names \u2014 description, viewport, theme-color, robots, generator, \u2026 \u2014 and the conformance requirements for each (e.g. at most one meta description per document)."
+  },
+  {
+    id: "whatwg-html-link",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 the link element",
+    url: "https://html.spec.whatwg.org/multipage/semantics.html",
+    anchor: "the-link-element",
+    retrievedAt: "2026-08-06",
+    note: "Defines the syntax of link: a rel attribute (or itemprop) is required, and href must be a valid non-empty URL potentially surrounded by spaces."
+  },
+  {
+    id: "whatwg-html-link-types",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 link types",
+    url: "https://html.spec.whatwg.org/multipage/links.html",
+    anchor: "linkTypes",
+    retrievedAt: "2026-08-06",
+    note: "The registry of rel keywords \u2014 canonical, alternate, icon, manifest, \u2026 \u2014 including which are allowed on link vs a/area, and the semantics of each (e.g. alternate + hreflang designates a translation)."
+  },
+  {
+    id: "whatwg-html-lang",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 the lang and xml:lang attributes",
+    url: "https://html.spec.whatwg.org/multipage/dom.html",
+    anchor: "the-lang-and-xml:lang-attributes",
+    retrievedAt: "2026-08-06",
+    note: "lang gives the language of the element's contents and must be a valid BCP 47 language tag or the empty string; authors are encouraged to set it on the root html element."
+  },
+  {
+    id: "whatwg-html-dir",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "HTML Living Standard \u2014 the dir attribute",
+    url: "https://html.spec.whatwg.org/multipage/dom.html",
+    anchor: "the-dir-attribute",
+    retrievedAt: "2026-08-06",
+    note: "dir declares text directionality: ltr, rtl, or auto. Governs whether an rtl-language page declares its direction explicitly."
+  },
+  {
+    id: "whatwg-url",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "URL Standard",
+    url: "https://url.spec.whatwg.org/",
+    retrievedAt: "2026-08-06",
+    note: "How browsers actually parse URLs \u2014 the parsing/validity contract goflag applies when it checks that a canonical or alternate href is a valid, absolute URL."
+  },
+  {
+    id: "whatwg-encoding",
+    publisher: "WHATWG",
+    rigor: "normative",
+    title: "Encoding Standard",
+    url: "https://encoding.spec.whatwg.org/",
+    retrievedAt: "2026-08-06",
+    note: "Defines character encodings for the web; UTF-8 is the mandatory encoding for new content, which is what a meta charset declaration should say."
+  },
+  {
+    id: "ietf-rfc3986",
+    publisher: "IETF",
+    rigor: "normative",
+    title: "RFC 3986 \u2014 URI Generic Syntax",
+    url: "https://www.rfc-editor.org/rfc/rfc3986",
+    retrievedAt: "2026-08-06",
+    note: "The generic URI grammar: scheme, authority, path, query, fragment. The formal definition of what an absolute URL is."
+  },
+  {
+    id: "ietf-rfc3987",
+    publisher: "IETF",
+    rigor: "normative",
+    title: "RFC 3987 \u2014 Internationalized Resource Identifiers (IRIs)",
+    url: "https://www.rfc-editor.org/rfc/rfc3987",
+    retrievedAt: "2026-08-06",
+    note: "Extends URIs to non-ASCII characters and defines the IRI-to-URI mapping \u2014 relevant when localized sites use non-ASCII paths."
+  },
+  {
+    id: "ietf-bcp47",
+    publisher: "IETF",
+    rigor: "normative",
+    title: "RFC 5646 / BCP 47 \u2014 Tags for Identifying Languages",
+    url: "https://www.rfc-editor.org/rfc/rfc5646",
+    retrievedAt: "2026-08-06",
+    note: "The grammar of language tags used by lang and hreflang (language[-script][-region]\u2026). Tags are case-insensitive; the familiar en-US casing is only a convention."
+  },
+  {
+    id: "ietf-rfc6596",
+    publisher: "IETF",
+    rigor: "normative",
+    title: "RFC 6596 \u2014 The Canonical Link Relation",
+    url: "https://www.rfc-editor.org/rfc/rfc6596",
+    retrievedAt: "2026-08-06",
+    note: 'Defines rel="canonical": the preferred IRI for duplicative content. The target must not be a 404 and should not vary per duplicate (no self-referencing loops through redirects).'
+  },
+  {
+    id: "ietf-rfc9309",
+    publisher: "IETF",
+    rigor: "normative",
+    title: "RFC 9309 \u2014 Robots Exclusion Protocol",
+    url: "https://www.rfc-editor.org/rfc/rfc9309",
+    retrievedAt: "2026-08-06",
+    note: "The robots.txt file format and matching rules: group selection by user-agent, longest-match precedence, allow wins ties, and how errors/unavailability must be treated."
+  },
+  {
+    id: "sitemaps-protocol",
+    publisher: "sitemaps.org",
+    rigor: "normative",
+    title: "Sitemaps XML protocol",
+    url: "https://www.sitemaps.org/protocol.html",
+    retrievedAt: "2026-08-06",
+    note: "The sitemap.xml schema: urlset/url/loc structure, optional lastmod/changefreq/priority, the 50,000-URL / 50 MB limits, and sitemap index files."
+  },
+  {
+    id: "w3c-appmanifest",
+    publisher: "W3C",
+    rigor: "normative",
+    title: "Web Application Manifest",
+    url: "https://www.w3.org/TR/appmanifest/",
+    retrievedAt: "2026-08-06",
+    note: 'The manifest.json format linked via link rel="manifest": members like name, icons, start_url, display, and how user agents process them.'
+  },
+  {
+    id: "w3c-wcag22",
+    publisher: "W3C",
+    rigor: "normative",
+    title: "WCAG 2.2",
+    url: "https://www.w3.org/TR/WCAG22/",
+    retrievedAt: "2026-08-06",
+    note: "Accessibility success criteria \u2014 language of page (3.1.1), non-text content / alt (1.1.1), contrast, \u2026 Reserved for the future a11y vertical."
+  },
+  {
+    id: "w3c-wai-aria12",
+    publisher: "W3C",
+    rigor: "normative",
+    title: "WAI-ARIA 1.2",
+    url: "https://www.w3.org/TR/wai-aria-1.2/",
+    retrievedAt: "2026-08-06",
+    note: "ARIA roles, states and properties. Reserved for the future a11y vertical."
+  },
+  {
+    id: "w3c-i18n-language-tags",
+    publisher: "W3C",
+    rigor: "guideline",
+    title: "W3C i18n \u2014 Language tags in HTML and XML",
+    url: "https://www.w3.org/International/articles/language-tags/",
+    retrievedAt: "2026-08-06",
+    note: "W3C i18n guidance on applying BCP 47 in practice: keep tags as short as possible, subtag order and casing conventions, when to include script or region."
+  }
+];
+var VENDOR = [
+  {
+    id: "ogp",
+    publisher: "ogp.me",
+    rigor: "vendor-spec",
+    title: "The Open Graph protocol",
+    url: "https://ogp.me/",
+    retrievedAt: "2026-08-06",
+    note: "The og:* vocabulary. og:title, og:type, og:image and og:url are required for every page that wants to be a rich object in the social graph; og:description and others are optional."
+  },
+  {
+    id: "x-cards",
+    publisher: "X (Twitter)",
+    rigor: "vendor-spec",
+    title: "X Cards \u2014 about cards markup",
+    url: "https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards",
+    retrievedAt: "2026-08-06",
+    note: "The twitter:* card vocabulary (twitter:card, twitter:title, \u2026) and the fallback behavior: X's crawler falls back to og:* tags when twitter:* equivalents are absent. X has since removed most of this documentation (the URL now redirects to docs.x.com/overview) but the crawler behavior and tag names are unchanged \u2014 the tags stayed twitter:*, not x:*."
+  },
+  {
+    id: "google-canonicalization",
+    publisher: "Google",
+    rigor: "vendor-spec",
+    title: "Consolidate duplicate URLs (canonicalization)",
+    url: "https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls",
+    retrievedAt: "2026-08-06",
+    note: `How Google treats rel="canonical": a strong hint (not a directive), absolute URLs recommended, don't point to redirecting or 404 targets, one canonical per page.`
+  },
+  {
+    id: "google-robots-meta",
+    publisher: "Google",
+    rigor: "vendor-spec",
+    title: "Robots meta tag and X-Robots-Tag",
+    url: "https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag",
+    retrievedAt: "2026-08-06",
+    note: "The robots meta / X-Robots-Tag directives (noindex, nofollow, \u2026), how meta and header directives combine, and that the most restrictive directive wins on conflict."
+  },
+  {
+    id: "google-robots-intro",
+    publisher: "Google",
+    rigor: "vendor-spec",
+    title: "Introduction to robots.txt",
+    url: "https://developers.google.com/search/docs/crawling-indexing/robots/intro",
+    retrievedAt: "2026-08-06",
+    note: "Google's robots.txt behavior on top of RFC 9309 \u2014 notably that robots.txt controls crawling, not indexing: a blocked URL can still be indexed from links, so noindex needs the page to be crawlable."
+  },
+  {
+    id: "google-hreflang",
+    publisher: "Google",
+    rigor: "vendor-spec",
+    title: "Localized versions of your pages (hreflang)",
+    url: "https://developers.google.com/search/docs/specialty/international/localized-versions",
+    retrievedAt: "2026-08-06",
+    note: "hreflang via link annotations, headers or sitemaps: every language version must list itself and all others (reciprocity), use absolute URLs, and x-default marks the unmatched-language fallback."
+  },
+  {
+    id: "google-title-link",
+    publisher: "Google",
+    rigor: "guideline",
+    title: "Influence your title links in search results",
+    url: "https://developers.google.com/search/docs/appearance/title-link",
+    retrievedAt: "2026-08-06",
+    note: "Write descriptive, concise, non-boilerplate titles unique to each page. Google may rewrite titles it considers poor; length itself is not a ranking factor."
+  },
+  {
+    id: "google-snippet",
+    publisher: "Google",
+    rigor: "guideline",
+    title: "Control your snippets in search results",
+    url: "https://developers.google.com/search/docs/appearance/snippet",
+    retrievedAt: "2026-08-06",
+    note: "Meta descriptions feed the search snippet but Google may substitute on-page text; write a unique, accurate summary per page rather than keyword stuffing."
+  },
+  {
+    id: "google-structured-data",
+    publisher: "Google",
+    rigor: "vendor-spec",
+    title: "Introduction to structured data markup",
+    url: "https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data",
+    retrievedAt: "2026-08-06",
+    note: "How Google consumes structured data (JSON-LD recommended) and what rich-result eligibility requires; the vocabulary itself is schema.org's."
+  },
+  {
+    id: "google-sitemaps",
+    publisher: "Google",
+    rigor: "guideline",
+    title: "Build and submit a sitemap",
+    url: "https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview",
+    retrievedAt: "2026-08-06",
+    note: "Google's sitemap practice on top of the sitemaps.org protocol: when a sitemap helps, supported formats, and submission via robots.txt or Search Console."
+  },
+  {
+    id: "schema-org",
+    publisher: "schema.org",
+    rigor: "vendor-spec",
+    title: "schema.org vocabulary",
+    url: "https://schema.org/",
+    retrievedAt: "2026-08-06",
+    note: "The shared vocabulary (types and properties) that structured data \u2014 JSON-LD in particular \u2014 is written in."
+  },
+  {
+    id: "apple-web-apps",
+    publisher: "Apple",
+    rigor: "vendor-spec",
+    title: "Configuring web applications (Safari Web Content Guide)",
+    url: "https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html",
+    retrievedAt: "2026-08-06",
+    note: "apple-touch-icon and the apple-mobile-web-app-* meta tags: how iOS picks home-screen icons and startup images. Archived but still the reference Apple points to."
+  },
+  {
+    id: "meta-og-sharing",
+    publisher: "Meta",
+    rigor: "vendor-spec",
+    title: "Sharing \u2014 webmasters (Open Graph usage)",
+    url: "https://developers.facebook.com/docs/sharing/webmasters/",
+    retrievedAt: "2026-08-06",
+    note: "How Meta's crawler builds link previews from og:* tags \u2014 including image size expectations (1200\xD7630 recommended, 200\xD7200 minimum) beyond what ogp.me specifies."
+  },
+  {
+    id: "bing-webmaster-guidelines",
+    publisher: "Microsoft",
+    rigor: "guideline",
+    title: "Bing Webmaster Guidelines",
+    url: "https://www.bing.com/webmasters/help/webmasters-guidelines-30fba23a",
+    retrievedAt: "2026-08-06",
+    note: "Bing's crawlability and content guidance \u2014 a cross-check that the catalog is not Google-only."
+  }
+];
+var PRACTICAL = [
+  {
+    id: "mdn-meta-name",
+    publisher: "MDN / Mozilla",
+    rigor: "guideline",
+    title: "MDN \u2014 <meta> name attribute values",
+    url: "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name",
+    retrievedAt: "2026-08-06",
+    note: "Practical reference for standard and de-facto meta names, browser support included."
+  },
+  {
+    id: "mdn-viewport",
+    publisher: "MDN / Mozilla",
+    rigor: "guideline",
+    title: "MDN \u2014 Viewport meta tag",
+    url: "https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag",
+    retrievedAt: "2026-08-06",
+    note: "width=device-width, initial-scale=1 and friends: what the viewport meta controls and the accessibility pitfalls (never disable user scaling)."
+  },
+  {
+    id: "mdn-link-rel",
+    publisher: "MDN / Mozilla",
+    rigor: "guideline",
+    title: "MDN \u2014 rel attribute values",
+    url: "https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel",
+    retrievedAt: "2026-08-06",
+    note: "Practical reference for rel values across link, a and form, with support notes."
+  },
+  {
+    id: "lighthouse-seo",
+    publisher: "Google",
+    rigor: "guideline",
+    title: "Lighthouse \u2014 SEO audits",
+    url: "https://developer.chrome.com/docs/lighthouse/seo/",
+    retrievedAt: "2026-08-06",
+    note: "The audit definitions Lighthouse ships (document has a title, has a meta description, valid hreflang, valid canonical, \u2026) \u2014 the closest thing to an industry-standard checklist to mirror."
+  },
+  {
+    id: "axe-core-rules",
+    publisher: "Deque",
+    rigor: "guideline",
+    title: "axe-core \u2014 rule descriptions",
+    url: "https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md",
+    retrievedAt: "2026-08-06",
+    note: "The a11y rule catalog to cross-check against when the a11y vertical lands (html-has-lang, valid-lang, image-alt, \u2026)."
+  },
+  {
+    id: "w3c-nu-checker",
+    publisher: "W3C",
+    rigor: "guideline",
+    title: "Nu HTML Checker",
+    url: "https://validator.w3.org/nu/",
+    retrievedAt: "2026-08-06",
+    note: "The reference HTML validator \u2014 the cross-check for goflag's document-level syntax rules."
+  },
+  {
+    id: "moz-title-tag",
+    publisher: "Moz",
+    rigor: "heuristic",
+    title: "Title tag best practices",
+    url: "https://moz.com/learn/seo/title-tag",
+    retrievedAt: "2026-08-06",
+    note: "The ~50\u201360 character title window is display folklore, not spec: it approximates SERP truncation width. Ships as heuristic so agents weight it accordingly."
+  },
+  {
+    id: "moz-meta-description",
+    publisher: "Moz",
+    rigor: "heuristic",
+    title: "Meta description best practices",
+    url: "https://moz.com/learn/seo/meta-description",
+    retrievedAt: "2026-08-06",
+    note: "The ~50\u2013160 character description window is display folklore, not spec: it approximates snippet truncation. Ships as heuristic so agents weight it accordingly."
+  }
+];
+var SOURCES = [...NORMATIVE, ...VENDOR, ...PRACTICAL];
+function getSource(id) {
+  return SOURCES.find((source) => source.id === id);
+}
+
+// src/lib/rules/catalog.ts
+function fixOf(fix) {
+  if (!fix) return void 0;
+  return { title: fix.title, snippet: fix.snippet, language: fix.language ?? "ts" };
+}
+function buildRuleCatalog(version) {
+  const rules = [];
+  for (const rule of RULES) {
+    rules.push({
+      id: rule.id,
+      scope: "page",
+      category: rule.category,
+      severity: rule.kind === "boolean" ? rule.severity : rule.severityByBand.acceptable,
+      kind: rule.kind,
+      summary: rule.title,
+      why: rule.why,
+      rigor: rule.rigor,
+      sources: [...rule.sources],
+      reads: [...rule.reads],
+      ...rule.relates ? { relates: [...rule.relates] } : {},
+      ...rule.expected ? { expected: rule.expected } : {},
+      ...fixOf(rule.fix) ? { fix: fixOf(rule.fix) } : {},
+      ...rule.kind === "scored" ? { bands: { ...rule.bands }, severityByBand: { ...rule.severityByBand } } : {}
+    });
+  }
+  for (const rule of SITE_RULES) {
+    rules.push({
+      id: rule.id,
+      scope: "site",
+      severity: rule.severity,
+      kind: "boolean",
+      summary: rule.summary,
+      rigor: null,
+      sources: []
+    });
+  }
+  for (const rule of PROSE_RULES) {
+    rules.push({
+      id: rule.id,
+      scope: "prose",
+      category: rule.category,
+      severity: null,
+      kind: "prose",
+      summary: rule.title,
+      why: rule.why,
+      rigor: rule.rigor,
+      sources: [...rule.sources],
+      reads: [...rule.reads],
+      prose: rule.prose
+    });
+  }
+  rules.sort((a, b) => a.id.localeCompare(b.id));
+  const cited = new Set(rules.flatMap((r) => r.sources));
+  const sources = {};
+  for (const id of [...cited].sort()) {
+    const doc = getSource(id);
+    if (doc) {
+      sources[id] = {
+        id: doc.id,
+        publisher: doc.publisher,
+        title: doc.title,
+        rigor: doc.rigor,
+        url: doc.url
+      };
+    }
+  }
+  return {
+    ...version ? { version } : {},
+    counts: {
+      page: RULES.length,
+      site: SITE_RULES.length,
+      prose: PROSE_RULES.length
+    },
+    sources,
+    rules
+  };
+}
+function serialiseCatalog(catalog) {
+  return `${JSON.stringify(catalog, null, 2)}
+`;
+}
+
+// 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
@@ -582,6 +1375,14 @@ ${HELP}
 `);
     return 0;
   }
+  if (args.command === "rules") {
+    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>