@goflag/cli 0.2.9 → 0.2.11

package/dist/index.d.ts

@@ -48,6 +48,16 @@ type TagOrigin = {
     kind: "computed";
 };
 type Severity = "error" | "warning" | "info";
+/**
+ * How authoritative the requirement behind a finding is.
+ *
+ * Lives here rather than in the rule layer for the same reason `Issue` does:
+ * it crosses the engine → report → CLI `--json` boundary. An agent reading a
+ * report has to be able to tell a `spec-required` from a `heuristic` before it
+ * decides what to change, and a type that stopped at the rule registry could
+ * not tell it — `../rules/types` re-exports this one.
+ */
+type Rigor = "spec-required" | "spec-recommended" | "vendor-spec" | "guideline" | "heuristic";
 
 /**
  * Hreflang reciprocity + matrix derivation (Phase 7.4 / 7.5).
@@ -424,8 +434,6 @@ interface Extraction {
  * findings into issues at that boundary.
  */
 
-/** How authoritative the requirement behind a rule is. */
-type Rigor = "spec-required" | "spec-recommended" | "vendor-spec" | "guideline" | "heuristic";
 /** A band a scored measurement can land in. */
 type Band = "ideal" | "acceptable" | "poor";
 /** Everything a rule declares about itself, before any evaluation. */
@@ -509,7 +517,17 @@ interface AdvisoryFinding {
     ruleId: string;
     kind: "prose";
     prose: string;
-    rigor: Rigor;
+    /**
+     * `null` where no document supports the question.
+     *
+     * Every page prose rule carries one. The cross-page ones (`./site-prose.ts`)
+     * may not: `hreflang.sitemap-mismatch` asks about a disagreement no
+     * specification addresses, and inventing a rigor for it would put back the
+     * dishonesty that moving it out of the verdict-bearing registry removed.
+     * An agent reads this to weight the question; `null` says "weight it on the
+     * evidence alone".
+     */
+    rigor: Rigor | null;
     sources: string[];
     /**
      * Extraction path → the observed value there, one entry per declared
@@ -742,6 +760,13 @@ interface SiteIssue {
     why?: string;
     /** A copy-pasteable fix snippet, when the rule offers one. */
     fix?: string;
+    /**
+     * Same two fields as `SeoIssue`, and absent for a different reason: a
+     * `SiteRule` may simply not declare a rigor yet. Three of the four do not,
+     * and the catalogue reports that gap rather than inventing an authority.
+     */
+    rigor?: Rigor;
+    sources?: string[];
 }
 /** How the audit established which locales the site serves. */
 interface LocaleAxisReport {
@@ -774,6 +799,20 @@ interface SeoIssue {
     why?: string;
     /** A copy-pasteable fix snippet, when the rule offers one. */
     fix?: string;
+    /**
+     * How authoritative the requirement is, and the documents that back it.
+     *
+     * Carried on the finding because a report is read where the rule registry is
+     * not — a JSON file in CI, a PR comment, an agent's context. Without it a
+     * consumer cannot tell a `spec-required` from a `heuristic`, which is the one
+     * distinction the rigor axis exists to make.
+     */
+    rigor?: Rigor;
+    sources?: string[];
+    /** What the page actually said, as the rule saw it. */
+    observed?: unknown;
+    /** One sentence stating what a passing page looks like. */
+    expected?: string;
 }
 /**
  * One prose rule's evidence bundle, attributed to a page. The `id` is a
@@ -1104,6 +1143,12 @@ interface RollupLink {
 interface RollupSeo {
     ruleId: string;
     severity: Severity;
+    /**
+     * How authoritative the rule is. Constant within a group — a rollup is one
+     * rule — which is what makes the summary the right place to show it: one tag
+     * per line instead of one per finding.
+     */
+    rigor?: Rigor;
     why?: string;
     fix?: string;
     /** A representative message (from the first occurrence). */

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goflag/cli",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "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": [

package/rules.json

@@ -1,8 +1,8 @@
 {
   "counts": {
     "page": 23,
-    "site": 4,
-    "prose": 4
+    "site": 28,
+    "prose": 5
   },
   "sources": {
     "apple-web-apps": {
@@ -33,6 +33,13 @@
       "rigor": "vendor-spec",
       "url": "https://developers.google.com/search/docs/specialty/international/localized-versions"
     },
+    "google-robots-intro": {
+      "id": "google-robots-intro",
+      "publisher": "Google",
+      "title": "Introduction to robots.txt",
+      "rigor": "vendor-spec",
+      "url": "https://developers.google.com/search/docs/crawling-indexing/robots/intro"
+    },
     "google-robots-meta": {
       "id": "google-robots-meta",
       "publisher": "Google",
@@ -40,6 +47,13 @@
       "rigor": "vendor-spec",
       "url": "https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag"
     },
+    "google-sitemaps": {
+      "id": "google-sitemaps",
+      "publisher": "Google",
+      "title": "Build and submit a sitemap",
+      "rigor": "guideline",
+      "url": "https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview"
+    },
     "google-snippet": {
       "id": "google-snippet",
       "publisher": "Google",
@@ -61,6 +75,13 @@
       "rigor": "normative",
       "url": "https://www.rfc-editor.org/rfc/rfc6596"
     },
+    "ietf-rfc9309": {
+      "id": "ietf-rfc9309",
+      "publisher": "IETF",
+      "title": "RFC 9309 — Robots Exclusion Protocol",
+      "rigor": "normative",
+      "url": "https://www.rfc-editor.org/rfc/rfc9309"
+    },
     "mdn-link-rel": {
       "id": "mdn-link-rel",
       "publisher": "MDN / Mozilla",
@@ -103,6 +124,13 @@
       "rigor": "vendor-spec",
       "url": "https://ogp.me/"
     },
+    "sitemaps-protocol": {
+      "id": "sitemaps-protocol",
+      "publisher": "sitemaps.org",
+      "title": "Sitemaps XML protocol",
+      "rigor": "normative",
+      "url": "https://www.sitemaps.org/protocol.html"
+    },
     "w3c-appmanifest": {
       "id": "w3c-appmanifest",
       "publisher": "W3C",
@@ -291,23 +319,39 @@
         "language": "tsx"
       }
     },
+    {
+      "id": "hreflang.cluster-incomplete",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "Every locale the sitemap publishes must appear in the route's `hreflang` cluster",
+      "rigor": "vendor-spec",
+      "sources": [
+        "google-hreflang"
+      ]
+    },
     {
       "id": "hreflang.missing",
       "scope": "site",
       "severity": "error",
       "kind": "boolean",
       "summary": "Pages on a multilingual site must advertise their locale alternates",
-      "rigor": null,
-      "sources": []
+      "rigor": "vendor-spec",
+      "sources": [
+        "google-hreflang",
+        "whatwg-html-link-types"
+      ]
     },
     {
       "id": "hreflang.sitemap-mismatch",
-      "scope": "site",
-      "severity": "warning",
-      "kind": "boolean",
-      "summary": "`<head>` alternates and sitemap locale coverage must agree",
+      "scope": "prose",
+      "severity": null,
+      "kind": "prose",
+      "summary": "`<head>` alternates advertise a locale the sitemap does not list",
+      "why": "The two are derived from one intent by different code paths, so a disagreement means one of them is wrong. No specification says which: the declaration methods are equivalent, and a page can legitimately be cross-linked and kept out of the sitemap.",
       "rigor": null,
-      "sources": []
+      "sources": [],
+      "prose": "Your `<head>` advertises a translation your sitemap does not list. Is the sitemap missing an entry, or is the alternate pointing at a page you did not mean to publish?"
     },
     {
       "id": "icons.apple-touch.missing",
@@ -744,14 +788,29 @@
       ],
       "expected": "an explicit `og:title`"
     },
+    {
+      "id": "robots.blocks-page",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A page asking to be indexed must not be disallowed by robots.txt",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ietf-rfc9309",
+        "google-robots-intro"
+      ]
+    },
     {
       "id": "robots.blocks-site",
       "scope": "site",
       "severity": "error",
       "kind": "boolean",
       "summary": "`robots.txt` must not forbid crawling a site that asks to be indexed",
-      "rigor": null,
-      "sources": []
+      "rigor": "vendor-spec",
+      "sources": [
+        "ietf-rfc9309",
+        "google-robots-intro"
+      ]
     },
     {
       "id": "robots.conflict",
@@ -772,6 +831,270 @@
       ],
       "expected": "consistent indexing directives across meta tags and headers"
     },
+    {
+      "id": "robotstxt.cross-origin",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "`/robots.txt` should not redirect to another origin",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ietf-rfc9309"
+      ]
+    },
+    {
+      "id": "robotstxt.invalid-line",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "Every line of robots.txt should parse as something",
+      "rigor": "spec-required",
+      "sources": [
+        "ietf-rfc9309"
+      ]
+    },
+    {
+      "id": "robotstxt.oversized",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "Rules past 500 KiB of robots.txt are not guaranteed to be read",
+      "rigor": "spec-required",
+      "sources": [
+        "ietf-rfc9309"
+      ]
+    },
+    {
+      "id": "robotstxt.sitemap.relative",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A `Sitemap:` declaration must be an absolute URL",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol",
+        "ietf-rfc9309"
+      ]
+    },
+    {
+      "id": "robotstxt.unknown-directive",
+      "scope": "site",
+      "severity": "info",
+      "kind": "boolean",
+      "summary": "Non-standard robots.txt directives are read by some crawlers and ignored by others",
+      "rigor": "guideline",
+      "sources": [
+        "ietf-rfc9309",
+        "google-robots-intro"
+      ]
+    },
+    {
+      "id": "robotstxt.unreachable",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A robots.txt that errors is read as forbidding the whole site",
+      "rigor": "spec-required",
+      "sources": [
+        "ietf-rfc9309"
+      ]
+    },
+    {
+      "id": "sitemap.empty",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A sitemap that parses should list something",
+      "rigor": "guideline",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.entry.blocked-by-robots",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A sitemap must not list URLs that robots.txt forbids fetching",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ietf-rfc9309",
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.entry.cross-host",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A sitemap should only list URLs on its own host",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.entry.invalid-url",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "Every `<loc>` must be an absolute, parseable URL",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.entry.noindex",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A sitemap must not list URLs that ask not to be indexed",
+      "rigor": "vendor-spec",
+      "sources": [
+        "sitemaps-protocol",
+        "google-robots-meta"
+      ]
+    },
+    {
+      "id": "sitemap.entry.non-canonical",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A sitemap should list canonical URLs",
+      "rigor": "vendor-spec",
+      "sources": [
+        "sitemaps-protocol",
+        "google-canonicalization"
+      ]
+    },
+    {
+      "id": "sitemap.entry.out-of-scope",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A sitemap may only list URLs under its own directory",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.entry.protocol-mismatch",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A sitemap should not mix `http` and `https` entries",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.entry.redirects",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A sitemap should list final URLs, not URLs that redirect",
+      "rigor": "guideline",
+      "sources": [
+        "sitemaps-protocol",
+        "google-sitemaps"
+      ]
+    },
+    {
+      "id": "sitemap.entry.unreachable",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "Every URL a sitemap lists must answer",
+      "rigor": "vendor-spec",
+      "sources": [
+        "sitemaps-protocol",
+        "google-sitemaps"
+      ]
+    },
+    {
+      "id": "sitemap.field.invalid",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "`<changefreq>` and `<priority>` must hold the values the protocol defines",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol",
+        "google-sitemaps"
+      ]
+    },
+    {
+      "id": "sitemap.index.child-error",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "Every child of a sitemap index must be reachable and parseable",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.lastmod.invalid",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "`<lastmod>` must be a W3C Datetime, and must not be in the future",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol",
+        "google-sitemaps"
+      ]
+    },
+    {
+      "id": "sitemap.limits.exceeded",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "No single sitemap document may exceed 50,000 entries or 50 MB",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
+    {
+      "id": "sitemap.missing",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A site should publish a sitemap",
+      "rigor": "guideline",
+      "sources": [
+        "sitemaps-protocol",
+        "google-sitemaps"
+      ]
+    },
+    {
+      "id": "sitemap.orphans",
+      "scope": "site",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "Indexable pages the crawl found should be listed in the sitemap",
+      "rigor": "guideline",
+      "sources": [
+        "sitemaps-protocol",
+        "google-sitemaps"
+      ]
+    },
+    {
+      "id": "sitemap.unparsable",
+      "scope": "site",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "A located sitemap must be a well-formed `<urlset>` or `<sitemapindex>`",
+      "rigor": "spec-required",
+      "sources": [
+        "sitemaps-protocol"
+      ]
+    },
     {
       "id": "title.descriptive",
       "scope": "prose",