@goflag/cli 0.2.7 → 0.2.9

package/dist/index.d.ts

@@ -95,12 +95,29 @@ interface ReciprocityIssue {
     peerUrl?: string;
     message: string;
 }
+/**
+ * What the audit actually knows about the URL in a cell.
+ *
+ *   - `crawled` — fetched and inspected. The only one that is a fact.
+ *   - `sitemap` — the site's own `<loc>` list names it, but the crawl did not
+ *     reach it. Under structural coverage this is most of the grid.
+ *   - `alternate` — **no list names it**: the only evidence is a
+ *     `<link rel="alternate">` on some page. It still fills the cell, so it
+ *     still hides a hole, and nothing has checked that the page is there.
+ *
+ * Derived from the winning URL rather than from which writer got there first,
+ * so `record`'s ordering — and every fingerprint that depends on it — is
+ * untouched (`docs/i18n-cluster-plan.md` §10).
+ */
+type I18nCellSource = "crawled" | "sitemap" | "alternate";
 interface I18nCell {
     /** Absolute URL serving this (route, locale) cell. `null` when
      *  no page in the crawl filled this cell. */
     url: string | null;
     /** True when the page was actually inspected (vs. discovered only). */
     inspected: boolean;
+    /** How the URL got here. Absent when `url` is null — nothing to source. */
+    source?: I18nCellSource;
 }
 interface I18nMatrix {
     /** Stable locale axis, `x-default` first when present, then BCP 47
@@ -272,6 +289,34 @@ interface ExtractionIcon {
         height: number;
     } | "any">;
 }
+/** One entry of a Web App Manifest's `icons` member. */
+interface ExtractionManifestIcon {
+    src: string;
+    sizes?: string;
+    type?: string;
+    purpose?: string;
+    /** Parsed `sizes` entries; empty for absent or unparseable values. */
+    parsedSizes: Array<{
+        width: number;
+        height: number;
+    } | "any">;
+}
+/**
+ * The `<link rel="manifest">`, and what the manifest said when goflag fetched
+ * it.
+ *
+ * `parsed` is deliberately three-valued. `undefined` means no probe ran — the
+ * manifest was never looked at — while `false` means it was fetched and could
+ * not be read. A rule must be able to tell those apart from a manifest that
+ * parsed and declares no icons, because only the last of the three is evidence
+ * about the site.
+ */
+interface ExtractionManifest {
+    href: string;
+    parsed?: boolean;
+    /** Present only when `parsed` is true. */
+    icons?: ExtractionManifestIcon[];
+}
 /** One feed advertisement (`rel="alternate"` with a feed content type). */
 interface ExtractionFeed {
     type: string;
@@ -286,9 +331,7 @@ interface ExtractionFeed {
 interface ExtractionLinks {
     hreflang: ExtractionHreflang[];
     icons: ExtractionIcon[];
-    manifest?: {
-        href: string;
-    };
+    manifest?: ExtractionManifest;
     feeds: ExtractionFeed[];
 }
 /** One `<script type="application/ld+json">` block. */
@@ -303,6 +346,29 @@ interface ExtractionJsonLd {
     /** Verbatim script content — the evidence, especially on parse errors. */
     raw: string;
 }
+/** One intrinsic size a file declares about itself. */
+interface ExtractionAssetSize {
+    width: number;
+    height: number;
+}
+/**
+ * What was served at one asset URL the page declared.
+ *
+ * The rules stay pure functions of this model: the network happened in a
+ * dedicated pass (`docs/og-plan.md` D8) and its answers arrive here as data,
+ * exactly like the manifest's.
+ */
+interface ExtractionAsset {
+    status: number;
+    /** 2xx *and* an image content type. */
+    ok: boolean;
+    contentType?: string;
+    /**
+     * Sizes decoded from the file's header — several for an ICO. Absent for a
+     * format goflag does not decode, which means *unknown*, never *none*.
+     */
+    sizes?: ExtractionAssetSize[];
+}
 /**
  * The per-page observation. Everything a page rule (or an agent judging a
  * prose rule) may read; nothing else.
@@ -319,6 +385,13 @@ interface Extraction {
     twitter: ExtractionTwitter;
     links: ExtractionLinks;
     jsonLd: ExtractionJsonLd[];
+    /**
+     * What was served at each asset URL this page declared, keyed by resolved
+     * URL. **Absent when no probe pass ran** — a rule must read that as "not
+     * looked at" rather than "nothing there", the same three-valued care the
+     * manifest gets.
+     */
+    assets?: Record<string, ExtractionAsset>;
 }
 
 /**
@@ -778,6 +851,13 @@ interface GoflagReport {
          * are duplicates. Reported so a shrinking finding count is explicable.
          */
         duplicatePages?: number;
+        /**
+         * Matrix cells filled by an `hreflang` on another page and by nothing
+         * else: not crawled, and not listed in the sitemap. They count as a
+         * present translation, so each one may be hiding the hole it claims to
+         * fill. Reported, never judged — see `docs/i18n-cluster-plan.md` §10.
+         */
+        unverifiedAlternates?: number;
         /**
          * Translation clusters the sitemap declared with `xhtml:link`, when it
          * declared any.
@@ -792,6 +872,16 @@ interface GoflagReport {
         declaredClusters?: {
             count: number;
             conflicts?: number;
+            /**
+             * Of `count`, the clusters that exist only because a page's `<head>`
+             * declared them — rows the sitemap never mentioned.
+             */
+            fromHead?: number;
+            /**
+             * Clusters the site declared that goflag declined to use, because no
+             * `x-default` named the row (or the members disagreed about it).
+             */
+            refused?: number;
         };
         /** Sitemap discovery outcome, when discovery ran. */
         /** Which pages the run chose to audit, and what it therefore cannot promise. */

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   runAudit,
   summarize,
   targetKey
-} from "./chunk-UOKYUKHQ.js";
+} from "./chunk-TAZEAIFI.js";
 export {
   Logger,
   SAMPLE_LIMIT,

package/flags.json

@@ -0,0 +1,302 @@
+{
+  "flags": [
+    {
+      "name": "--advisories",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "output",
+      "description": "Attach the prose rules — the judgment calls goflag refuses to fake — each with the observed facts an agent needs to judge it. Never affects the gate."
+    },
+    {
+      "name": "--allow-insecure-tls",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "fetch",
+      "description": "Accept self-signed / invalid TLS (localhost, tunnels)."
+    },
+    {
+      "name": "--baseline",
+      "short": null,
+      "arg": "<file>",
+      "default": null,
+      "requires": null,
+      "group": "gate",
+      "description": "Stored report to compare against. Use with --regressions-only."
+    },
+    {
+      "name": "--conformance",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "output",
+      "description": "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."
+    },
+    {
+      "name": "--coverage",
+      "short": null,
+      "arg": "<mode>",
+      "default": "structural when a sitemap is found, all otherwise",
+      "requires": null,
+      "group": "crawl",
+      "description": "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."
+    },
+    {
+      "name": "--depth",
+      "short": null,
+      "arg": "<n>",
+      "default": "2",
+      "requires": null,
+      "group": "crawl",
+      "description": "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\" — add --no-sitemap for that. Default: 2."
+    },
+    {
+      "name": "--exclude",
+      "short": null,
+      "arg": "<glob>",
+      "default": null,
+      "requires": null,
+      "group": "crawl",
+      "description": "Skip paths matching <glob> (repeatable)."
+    },
+    {
+      "name": "--fail-on",
+      "short": null,
+      "arg": "<level>",
+      "default": "warning",
+      "requires": null,
+      "group": "gate",
+      "description": "Exit 1 at or above this severity: warning (default), error, or never."
+    },
+    {
+      "name": "--help",
+      "short": "-h",
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "terminal",
+      "description": "Show this help."
+    },
+    {
+      "name": "--ignore-holes",
+      "short": null,
+      "arg": "<glob>",
+      "default": null,
+      "requires": null,
+      "group": "i18n",
+      "description": "Route (locale-free) that is deliberately not translated everywhere, so its gaps are not reported as missing translations (repeatable)."
+    },
+    {
+      "name": "--include",
+      "short": null,
+      "arg": "<glob>",
+      "default": null,
+      "requires": null,
+      "group": "crawl",
+      "description": "Only crawl paths matching <glob> (repeatable)."
+    },
+    {
+      "name": "--json",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "output",
+      "description": "Print the JSON report to stdout (nothing else)."
+    },
+    {
+      "name": "--locales",
+      "short": null,
+      "arg": "<list>",
+      "default": null,
+      "requires": null,
+      "group": "i18n",
+      "description": "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/… and /fr/… into one route family for structural coverage, so pass it on any locale-prefixed site."
+    },
+    {
+      "name": "--max-debt",
+      "short": null,
+      "arg": "<n>",
+      "default": null,
+      "requires": null,
+      "group": "gate",
+      "description": "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."
+    },
+    {
+      "name": "--max-pages",
+      "short": null,
+      "arg": "<n>",
+      "default": "200",
+      "requires": null,
+      "group": "crawl",
+      "description": "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."
+    },
+    {
+      "name": "--no-color",
+      "short": null,
+      "arg": null,
+      "default": "colour when stdout is a TTY and NO_COLOR is unset",
+      "requires": null,
+      "group": "terminal",
+      "description": "Disable coloured output."
+    },
+    {
+      "name": "--no-external",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "fetch",
+      "description": "Do not probe off-origin (external) links."
+    },
+    {
+      "name": "--no-sitemap",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "crawl",
+      "description": "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."
+    },
+    {
+      "name": "--profile",
+      "short": null,
+      "arg": "<name>",
+      "default": "default",
+      "requires": null,
+      "group": "gate",
+      "description": "Policy overlay on the rule set — it changes how loudly a rule fires, never what it observes: default — rule severities exactly as authored strict — every spec-backed rule fails the build spec-only — heuristic rules switched off entirely marketing — snippet and unfurl metadata gaps are errors"
+    },
+    {
+      "name": "--quiet",
+      "short": "-q",
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "terminal",
+      "description": "Suppress the live progress output."
+    },
+    {
+      "name": "--regressions-only",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": "--baseline",
+      "group": "gate",
+      "description": "Weaken the gate: fail only on findings that are NEW relative to --baseline. Known findings stop blocking the build — a green run no longer means a clean site. Requires --baseline."
+    },
+    {
+      "name": "--report",
+      "short": null,
+      "arg": "<file>",
+      "default": null,
+      "requires": null,
+      "group": "output",
+      "description": "Write the (full) JSON report to <file>."
+    },
+    {
+      "name": "--start",
+      "short": null,
+      "arg": "<cmd>",
+      "default": null,
+      "requires": null,
+      "group": "boot",
+      "description": "Boot <cmd>, wait for <url> to answer, audit, then stop it. Use to gate a merge on the built app before it ships."
+    },
+    {
+      "name": "--start-cwd",
+      "short": null,
+      "arg": "<dir>",
+      "default": "the current directory",
+      "requires": null,
+      "group": "boot",
+      "description": "Directory to run --start in. Defaults to the current one; set it when auditing a monorepo package from the repository root."
+    },
+    {
+      "name": "--start-timeout",
+      "short": null,
+      "arg": "<ms>",
+      "default": "60000",
+      "requires": null,
+      "group": "boot",
+      "description": "How long to wait for --start to answer. Default: 60000."
+    },
+    {
+      "name": "--static",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "fetch",
+      "description": "Static HTML only; never launch headless Chromium."
+    },
+    {
+      "name": "--summary",
+      "short": "-s",
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "output",
+      "description": "Roll findings up (dedup by link/rule/code). Pairs with --json for a compact, agent-friendly payload."
+    },
+    {
+      "name": "--timeout",
+      "short": null,
+      "arg": "<ms>",
+      "default": "8000 for link probes, 15000 for page fetches",
+      "requires": null,
+      "group": "fetch",
+      "description": "Per-request timeout in ms, for page fetches and link probes alike. Unset, the defaults differ: 8000 for link probes, 15000 for page fetches."
+    },
+    {
+      "name": "--update-baseline",
+      "short": null,
+      "arg": null,
+      "default": null,
+      "requires": "--baseline",
+      "group": "gate",
+      "description": "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 — it says what it accepted."
+    },
+    {
+      "name": "--verbose",
+      "short": "-V",
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "terminal",
+      "description": "Log every page as it is analyzed."
+    },
+    {
+      "name": "--version",
+      "short": "-v",
+      "arg": null,
+      "default": null,
+      "requires": null,
+      "group": "terminal",
+      "description": "Show the version."
+    }
+  ],
+  "exitCodes": [
+    {
+      "code": 0,
+      "label": "clean"
+    },
+    {
+      "code": 1,
+      "label": "findings found"
+    },
+    {
+      "code": 2,
+      "label": "fatal error"
+    }
+  ],
+  "counts": {
+    "flags": 31,
+    "withShortForm": 5,
+    "takingValue": 16
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goflag/cli",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "type": "module",
   "description": "Audits a site for broken links, missing translation pages, a robots.txt that contradicts your pages, and missing or misconfigured SEO metadata. JSON-first.",
   "keywords": [
@@ -43,7 +43,8 @@
   },
   "files": [
     "dist",
-    "rules.json"
+    "rules.json",
+    "flags.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -61,6 +62,8 @@
     "test:coverage": "vitest run --coverage",
     "validate:sources": "tsx scripts/validate-sources.ts",
     "generate:catalog": "tsx scripts/generate-catalog.ts",
+    "generate:flags": "tsx scripts/generate-flags.ts",
+    "generate:help-fixture": "tsx scripts/generate-help-fixture.ts",
     "prepack": "node ../../scripts/stage-package-docs.mjs",
     "prepublishOnly": "pnpm build",
     "release": "commit-and-tag-version --path . --skip.tag"