@goflag/cli 0.2.8 → 0.2.9

package/dist/index.d.ts

@@ -289,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;
@@ -303,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. */
@@ -320,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.
@@ -336,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>;
 }
 
 /**

package/dist/index.js

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

package/package.json

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

package/rules.json

@@ -1,10 +1,17 @@
 {
   "counts": {
-    "page": 11,
-    "site": 3,
+    "page": 23,
+    "site": 4,
     "prose": 4
   },
   "sources": {
+    "apple-web-apps": {
+      "id": "apple-web-apps",
+      "publisher": "Apple",
+      "title": "Configuring web applications (Safari Web Content Guide)",
+      "rigor": "vendor-spec",
+      "url": "https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html"
+    },
     "bing-webmaster-guidelines": {
       "id": "bing-webmaster-guidelines",
       "publisher": "Microsoft",
@@ -19,6 +26,13 @@
       "rigor": "vendor-spec",
       "url": "https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls"
     },
+    "google-hreflang": {
+      "id": "google-hreflang",
+      "publisher": "Google",
+      "title": "Localized versions of your pages (hreflang)",
+      "rigor": "vendor-spec",
+      "url": "https://developers.google.com/search/docs/specialty/international/localized-versions"
+    },
     "google-robots-meta": {
       "id": "google-robots-meta",
       "publisher": "Google",
@@ -47,6 +61,13 @@
       "rigor": "normative",
       "url": "https://www.rfc-editor.org/rfc/rfc6596"
     },
+    "mdn-link-rel": {
+      "id": "mdn-link-rel",
+      "publisher": "MDN / Mozilla",
+      "title": "MDN — rel attribute values",
+      "rigor": "guideline",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel"
+    },
     "mdn-viewport": {
       "id": "mdn-viewport",
       "publisher": "MDN / Mozilla",
@@ -82,6 +103,13 @@
       "rigor": "vendor-spec",
       "url": "https://ogp.me/"
     },
+    "w3c-appmanifest": {
+      "id": "w3c-appmanifest",
+      "publisher": "W3C",
+      "title": "Web Application Manifest",
+      "rigor": "normative",
+      "url": "https://www.w3.org/TR/appmanifest/"
+    },
     "w3c-i18n-language-tags": {
       "id": "w3c-i18n-language-tags",
       "publisher": "W3C",
@@ -96,6 +124,13 @@
       "rigor": "normative",
       "url": "https://html.spec.whatwg.org/multipage/dom.html"
     },
+    "whatwg-html-link-types": {
+      "id": "whatwg-html-link-types",
+      "publisher": "WHATWG",
+      "title": "HTML Living Standard — link types",
+      "rigor": "normative",
+      "url": "https://html.spec.whatwg.org/multipage/links.html"
+    },
     "whatwg-html-standard-metadata-names": {
       "id": "whatwg-html-standard-metadata-names",
       "publisher": "WHATWG",
@@ -116,6 +151,13 @@
       "title": "URL Standard",
       "rigor": "normative",
       "url": "https://url.spec.whatwg.org/"
+    },
+    "x-cards": {
+      "id": "x-cards",
+      "publisher": "X (Twitter)",
+      "title": "X Cards — about cards markup",
+      "rigor": "vendor-spec",
+      "url": "https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards"
     }
   },
   "rules": [
@@ -267,6 +309,135 @@
       "rigor": null,
       "sources": []
     },
+    {
+      "id": "icons.apple-touch.missing",
+      "scope": "page",
+      "category": "icons",
+      "severity": "info",
+      "kind": "boolean",
+      "summary": "Declare an `apple-touch-icon` for the iOS home screen",
+      "why": "iOS does not read `rel=\"icon\"` for a home-screen shortcut. With no `apple-touch-icon` it screenshots the page instead, so what someone saved is a thumbnail of whatever was on screen when they saved it.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "apple-web-apps",
+        "whatwg-html-link-types"
+      ],
+      "reads": [
+        "links.icons",
+        "links.manifest"
+      ],
+      "relates": [
+        "icons.missing"
+      ],
+      "expected": "a `<link rel=\"apple-touch-icon\">`"
+    },
+    {
+      "id": "icons.ico.missing",
+      "scope": "site",
+      "severity": "info",
+      "kind": "boolean",
+      "summary": "Serve a `/favicon.ico` at the root for the clients that ask blind",
+      "rigor": "guideline",
+      "sources": [
+        "whatwg-html-link-types",
+        "mdn-link-rel"
+      ]
+    },
+    {
+      "id": "icons.manifest-mismatch",
+      "scope": "page",
+      "category": "icons",
+      "severity": "info",
+      "kind": "boolean",
+      "summary": "The manifest and the `<head>` must not disagree about the same icon",
+      "why": "Two files declare the icons, maintained by different hands, and nothing compares them. The failure worth naming is not that the two lists differ — they legitimately do, since an apple-touch-icon is not a manifest icon — but that they describe the *same file* differently, or that the icons exist only in the manifest, where a browser tab never looks.",
+      "rigor": "guideline",
+      "sources": [
+        "w3c-appmanifest",
+        "whatwg-html-link-types"
+      ],
+      "reads": [
+        "links.icons",
+        "links.manifest"
+      ],
+      "relates": [
+        "icons.missing"
+      ],
+      "expected": "the same size and type wherever an icon is declared twice"
+    },
+    {
+      "id": "icons.missing",
+      "scope": "page",
+      "category": "icons",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "Declare an icon — the tab, the bookmark and the share sheet all read one",
+      "why": "No specification requires an icon, which is exactly why nothing complains and every consumer improvises. A browser falls back to `/favicon.ico` at the root, a feed reader or a link unfurler often falls back to nothing, and a bookmark to a site with no icon is a grey square among fifty.",
+      "rigor": "guideline",
+      "sources": [
+        "whatwg-html-link-types",
+        "mdn-link-rel"
+      ],
+      "reads": [
+        "links.icons",
+        "links.manifest"
+      ],
+      "relates": [
+        "icons.apple-touch.missing",
+        "icons.manifest-mismatch"
+      ],
+      "expected": "at least one `<link rel=\"icon\">`, or icons declared by a manifest",
+      "fix": {
+        "title": "Let the file convention declare it",
+        "snippet": "// app/icon.svg (or icon.png) — Next emits the <link rel=\"icon\"> itself.\n// app/apple-icon.png likewise emits rel=\"apple-touch-icon\".\n// A /favicon.ico at the root is a separate matter: see icons.ico.missing.",
+        "language": "tsx"
+      }
+    },
+    {
+      "id": "icons.sizes-mismatch",
+      "scope": "page",
+      "category": "icons",
+      "severity": "info",
+      "kind": "boolean",
+      "summary": "A `sizes` attribute must describe the file it points at",
+      "why": "`sizes` is how a client picks one icon out of several without fetching them all, so a wrong value costs exactly what the attribute was there to save: the client downloads the file it was told to prefer and gets the wrong resolution. A half-true declaration is the common shape — a `.ico` carrying 16, 32 and 48 declared as `48x48` advertises one third of itself.",
+      "rigor": "guideline",
+      "sources": [
+        "whatwg-html-link-types",
+        "mdn-link-rel"
+      ],
+      "reads": [
+        "links.icons",
+        "assets"
+      ],
+      "relates": [
+        "icons.unreachable"
+      ],
+      "expected": "`sizes` listing what the file actually contains"
+    },
+    {
+      "id": "icons.unreachable",
+      "scope": "page",
+      "category": "icons",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A declared icon has to answer with an image",
+      "why": "An icon that 404s is worse than one never declared: the client asks, gets nothing, and has already skipped the `/favicon.ico` it would have fallen back to. The declaration is what took the fallback away.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "whatwg-html-link-types",
+        "mdn-link-rel"
+      ],
+      "reads": [
+        "links.icons",
+        "assets"
+      ],
+      "relates": [
+        "icons.missing",
+        "icons.ico.missing"
+      ],
+      "expected": "a 2xx image at every declared icon URL"
+    },
     {
       "id": "lang.matches-content",
       "scope": "prose",
@@ -312,6 +483,85 @@
       ],
       "expected": "an `og:description` alongside the other `og:*` tags"
     },
+    {
+      "id": "og.image.absolute",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "`og:image` must be an absolute URL",
+      "why": "Unlike a browser, the crawler that builds the preview has no document to resolve a relative path against — it reads the tag, not the page. A relative `og:image` is therefore not a smaller mistake than a missing one: the unfurl is identical, and the tag makes it look handled.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ogp",
+        "meta-og-sharing"
+      ],
+      "reads": [
+        "openGraph.images"
+      ],
+      "relates": [
+        "og.image.missing",
+        "canonical.absolute"
+      ],
+      "expected": "every `og:image` URL absolute, scheme included",
+      "fix": {
+        "title": "Give Next a metadataBase, or write the origin in",
+        "snippet": "// app/layout.tsx — every relative metadata URL resolves against this.\nexport const metadata = {\n  metadataBase: new URL(process.env.SITE_ORIGIN!),\n  openGraph: { images: [\"/og.png\"] }, // emitted absolute\n};",
+        "language": "tsx"
+      }
+    },
+    {
+      "id": "og.image.alt",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "Describe the shared image with `og:image:alt`",
+      "why": "The protocol defines `og:image:alt` as a description of what is in the image, and a generated card usually carries the page's title as pixels. Omitting it leaves that text sighted-only, in the one place a link is seen before anybody has opened the page. Optional in the vocabulary, which is why this is a guideline and not a spec violation.",
+      "rigor": "guideline",
+      "sources": [
+        "ogp"
+      ],
+      "reads": [
+        "openGraph.images"
+      ],
+      "relates": [
+        "og.image.missing"
+      ],
+      "expected": "an `og:image:alt` beside every `og:image`",
+      "fix": {
+        "title": "Carry the alt per image, not as a constant",
+        "snippet": "// app/…/opengraph-image.tsx — `export const alt` is one fixed string, so a\n// translated or data-derived description has to go through the metadata fn.\nexport async function generateImageMetadata({ params }) {\n  const t = await getTranslations({ locale: params.locale });\n  return [{ id: \"og\", size, contentType, alt: t(\"og.alt\") }];\n}",
+        "language": "tsx"
+      }
+    },
+    {
+      "id": "og.image.dimensions",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "Declare `og:image:width` and `og:image:height`",
+      "why": "A crawler that does not know the size cannot lay the card out until it has fetched the image, so the first share of a URL renders without it — the one share that matters most. The dimensions are the fix, and they cost two tags.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ogp",
+        "meta-og-sharing"
+      ],
+      "reads": [
+        "openGraph.images"
+      ],
+      "relates": [
+        "og.image.missing",
+        "og.image.ratio"
+      ],
+      "expected": "both `og:image:width` and `og:image:height` on every image",
+      "fix": {
+        "title": "Declare the size alongside the URL",
+        "snippet": "// app/…/page.tsx\nexport const metadata = {\n  openGraph: { images: [{ url: \"/og.png\", width: 1200, height: 630 }] },\n};\n// The file convention emits both from `export const size` for free.",
+        "language": "tsx"
+      }
+    },
     {
       "id": "og.image.missing",
       "scope": "page",
@@ -338,6 +588,64 @@
         "language": "tsx"
       }
     },
+    {
+      "id": "og.image.ratio",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "info",
+      "kind": "scored",
+      "summary": "Keep the shared image near the 1.91:1 the card is laid out for",
+      "why": "Meta's recommended 1200×630 is a shape before it is a size. An image far from it is not rejected — it is cropped to fit, and the crop is chosen by the consumer rather than by you.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "meta-og-sharing",
+        "x-cards"
+      ],
+      "reads": [
+        "openGraph.images"
+      ],
+      "relates": [
+        "og.image.dimensions"
+      ],
+      "expected": "a width ÷ height between 1.7 and 2.1 (1.91:1 is 1.9)",
+      "bands": {
+        "ideal": [
+          1.7,
+          2.1
+        ],
+        "acceptable": [
+          1,
+          3
+        ]
+      },
+      "severityByBand": {
+        "acceptable": "info",
+        "poor": "warning"
+      }
+    },
+    {
+      "id": "og.image.reachable",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "error",
+      "kind": "boolean",
+      "summary": "The URL in `og:image` has to answer with an image",
+      "why": "Every other check on a preview image judges the tag. This one judges the file, and it is the only one that can catch the failure with no symptom: a URL that is present, well-formed, absolute — and dead. The card renders empty and nothing in the page says why. Found on this project's own documentation, where eleven pages pointed at a route a redirect had been swallowing since the day it was written.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ogp",
+        "meta-og-sharing"
+      ],
+      "reads": [
+        "openGraph.images",
+        "assets"
+      ],
+      "relates": [
+        "og.image.missing",
+        "og.image.absolute"
+      ],
+      "expected": "a 2xx image at every `og:image` URL"
+    },
     {
       "id": "og.image.representative",
       "scope": "prose",
@@ -359,6 +667,62 @@
       ],
       "prose": "Does the og:image represent what this page is about, rather than being a site-wide default, and does its subject survive being cropped to the 1.91:1 aspect ratio consumers render?"
     },
+    {
+      "id": "og.locale.alternates",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "`og:locale:alternate` and the hreflang cluster must name the same locales",
+      "why": "Two vocabularies describe the same fact — this page exists in these languages — and nothing in a build keeps them in step, so they drift silently. Whichever one is short is the one telling a consumer that a translation it could have linked to does not exist.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ogp",
+        "google-hreflang"
+      ],
+      "reads": [
+        "openGraph.locale",
+        "openGraph.localeAlternates",
+        "links.hreflang"
+      ],
+      "relates": [
+        "og.locale.missing",
+        "hreflang.missing"
+      ],
+      "expected": "one `og:locale:alternate` per hreflang locale other than this page's own",
+      "fix": {
+        "title": "Derive both lists from the same cluster",
+        "snippet": "// The hreflang map and the OG locales are one fact stated twice.\nopenGraph: {\n  locale: ogLocale(locale),\n  alternateLocale: cluster.filter((l) => l !== locale).map(ogLocale),\n},\nalternates: { languages: cluster },",
+        "language": "ts"
+      }
+    },
+    {
+      "id": "og.locale.missing",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "A translated page has to say which locale it is in",
+      "why": "`og:locale` defaults to `en_US` in the protocol itself — so a page that omits it does not decline to answer, it answers wrongly. On a site whose whole point is that the same page exists in several languages, every translation claims to be American English.",
+      "rigor": "vendor-spec",
+      "sources": [
+        "ogp"
+      ],
+      "reads": [
+        "openGraph.locale",
+        "links.hreflang"
+      ],
+      "relates": [
+        "og.locale.alternates",
+        "hreflang.missing"
+      ],
+      "expected": "an `og:locale` on any page that declares hreflang alternates",
+      "fix": {
+        "title": "Emit the locale in the page's own metadata",
+        "snippet": "// app/[locale]/…/page.tsx\nexport const metadata = {\n  openGraph: { locale: \"fr_FR\", alternateLocale: [\"en_US\", \"es_ES\"] },\n};",
+        "language": "tsx"
+      }
+    },
     {
       "id": "og.title.missing",
       "scope": "page",