@goflag/cli 0.2.11 → 0.2.12

package/dist/index.d.ts

@@ -379,6 +379,43 @@ interface ExtractionAsset {
      */
     sizes?: ExtractionAssetSize[];
 }
+/** One tag, named the way the page named it. */
+interface ExtractionHydratedMeta {
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+    content?: string;
+}
+/** One link, named the way the page named it. */
+interface ExtractionHydratedLink {
+    rel: string;
+    href?: string;
+    hreflang?: string;
+}
+/**
+ * What client JavaScript added to, or took from, the `<head>`.
+ *
+ * The gap between the two passes, at tag granularity — not per `Fact`, which
+ * carries which *tag* produced a value and never which *pass*. A value present
+ * here is a value the browser shows and a non-JS crawler never sees: the
+ * failure mode every `og.*` rule is blind to, because each of them judges the
+ * declaration it is given and this is about which declaration that was.
+ *
+ * **Absent on most runs, and that is not "nothing changed".** The delta only
+ * exists where both bodies do: the auto-escalation path, where a static fetch
+ * looked empty and a headless pass followed. A `--static` run never renders,
+ * and an explicit `--headless` run keeps no static body to compare against.
+ */
+interface ExtractionHydration {
+    titleChanged: boolean;
+    htmlLangChanged: boolean;
+    injectedMetas: ExtractionHydratedMeta[];
+    removedMetas: ExtractionHydratedMeta[];
+    injectedLinks: ExtractionHydratedLink[];
+    removedLinks: ExtractionHydratedLink[];
+    /** JSON-LD blocks that exist only after hydration. */
+    jsonLdBlocksAdded: number;
+}
 /**
  * The per-page observation. Everything a page rule (or an agent judging a
  * prose rule) may read; nothing else.
@@ -402,6 +439,11 @@ interface Extraction {
      * manifest gets.
      */
     assets?: Record<string, ExtractionAsset>;
+    /**
+     * What hydration changed in the `<head>`, when both passes ran and can be
+     * compared. Absent means "not established" — never "nothing moved".
+     */
+    hydration?: ExtractionHydration;
 }
 
 /**
@@ -874,6 +916,26 @@ interface GoflagReport {
      * touch the summary counts, the verdict, or the exit code.
      */
     advisories?: ReportAdvisory[];
+    /**
+     * What each page declared in its `<head>`, as the rules saw it. Present
+     * only when asked for (`AuditOptions.extractions`, which `goflag preview`
+     * sets).
+     *
+     * Every other section of this report is a *judgment*: a rule fired, or it
+     * did not. This one is the observation the judgments were made from, and it
+     * is here because a share card cannot be drawn from a violations list — a
+     * page that passes every `og.*` rule still has a title, an image and a
+     * description that somebody wants to look at, and none of them appear
+     * anywhere else in this file.
+     *
+     * Keyed by nothing: each entry carries its own `http.finalUrl`, which is the
+     * same string `ReportPage.url` and `SeoIssue.pageUrl` use.
+     *
+     * Covers fewer pages than `pages`, for the same reason `conformance` does:
+     * only healthy HTML documents reach the rule layer, so an unreachable page,
+     * a non-HTML resource and a canonical-declared duplicate have no entry here.
+     */
+    extractions?: Extraction[];
     /** Comparison against a stored baseline, when `--baseline` was given. */
     diff?: ReportDiff;
     diagnostics: {
@@ -1054,6 +1116,20 @@ interface AuditOptions {
      * carry no verdict and never affect the gate.
      */
     advisories?: boolean;
+    /**
+     * Emit each page's extraction — what its `<head>` declared, as the rules
+     * read it. Off by default: it is the observation, not a finding, and on a
+     * large crawl it is the biggest section of the report.
+     *
+     * `goflag preview` sets it, because a share card is drawn from the
+     * declarations and not from the verdicts about them.
+     *
+     * Unlike `conformance` and `advisories`, this section stops at the report:
+     * `summarize()` does not carry it — a summary of an observation is the
+     * observation with the useful parts removed — and no terminal renderer
+     * prints it. Its one reader is `renderPreview`.
+     */
+    extractions?: boolean;
 }
 /**
  * Routes present in some locales but absent in others. A "hole" is exactly
@@ -1225,6 +1301,50 @@ interface RenderOptions {
 }
 declare function renderSummaryTerminal(summary: GoflagSummary, options?: RenderOptions): string;
 
+/**
+ * The share-card preview — one self-contained HTML document.
+ *
+ * `renderPreview` is a pure function of a `GoflagReport`, exactly like the
+ * three terminal renderers beside it. It reads `report.extractions`, which is
+ * the only section that carries what a page *declared* rather than what a rule
+ * *decided*: a page can pass every `og.*` rule and still unfurl badly, and no
+ * violations list can show that.
+ *
+ * Two things this file refuses to do, and they are the point.
+ *
+ * **It draws no geometry it cannot source.** Every surface carries the same
+ * rigor scale the rule catalogue uses, because the surfaces are not equally
+ * documented: Facebook, LinkedIn and WhatsApp publish real numbers; Slack calls
+ * its own rendering a "micro-approximation"; Discord publishes nothing at all;
+ * X's card documentation is not reachable, and its shape changed twice since
+ * 2023. A preview that renders all seven identically states seven things with
+ * one confidence, and six of them are not earned.
+ *
+ * **It escapes everything.** The input is a site under audit, which is to say
+ * untrusted text, and the output is a file a human opens in a browser. Values
+ * go through `esc`; URLs that are not `http(s)` never become an `src`.
+ *
+ * Opening the document asks for the image URLs the pages declared, which is
+ * what makes it a preview rather than a table. Those URLs are the site's own
+ * choice and need not point at the audited origin, so the document ships a CSP
+ * that allows images and nothing else — no script, no frame, no fetch — and
+ * every image is `referrerpolicy="no-referrer"`. Rendering itself never touches
+ * the network.
+ */
+
+interface RenderPreviewOptions {
+    /** Document `<title>`. Defaults to the audited origin. */
+    title?: string;
+}
+/**
+ * Render the whole preview.
+ *
+ * A report without `extractions` renders a document that says so rather than an
+ * empty one: the caller asked for a preview and got a report that cannot make
+ * one, and that is a fact about the run, not an error to swallow.
+ */
+declare function renderPreview(report: GoflagReport, options?: RenderPreviewOptions): string;
+
 /**
  * Stable finding fingerprints.
  *
@@ -1328,4 +1448,4 @@ declare class Logger {
     private truncate;
 }
 
-export { type AuditOptions, type AuditPhase, type BrokenLink, type GoflagReport, type GoflagSummary, type LogMode, Logger, type LoggerOptions, type ProgressEvent, type ReportPage, type ReportReciprocityIssue, type RollupLink, type RollupReciprocity, type RollupSeo, SAMPLE_LIMIT, type SeoIssue, type TranslationHole, type UnreachablePage, type Verdict, deriveTranslationHoles, exitCode, fingerprint, renderSummaryTerminal, renderTerminal, routeKey, runAudit, summarize, targetKey };
+export { type AuditOptions, type AuditPhase, type BrokenLink, type GoflagReport, type GoflagSummary, type LogMode, Logger, type LoggerOptions, type ProgressEvent, type RenderPreviewOptions, type ReportPage, type ReportReciprocityIssue, type RollupLink, type RollupReciprocity, type RollupSeo, SAMPLE_LIMIT, type SeoIssue, type TranslationHole, type UnreachablePage, type Verdict, deriveTranslationHoles, exitCode, fingerprint, renderPreview, renderSummaryTerminal, renderTerminal, routeKey, runAudit, summarize, targetKey };

package/dist/index.js

@@ -5,19 +5,21 @@ import {
   deriveTranslationHoles,
   exitCode,
   fingerprint,
+  renderPreview,
   renderSummaryTerminal,
   renderTerminal,
   routeKey,
   runAudit,
   summarize,
   targetKey
-} from "./chunk-CWEJ6EXT.js";
+} from "./chunk-QKXUKHXB.js";
 export {
   Logger,
   SAMPLE_LIMIT,
   deriveTranslationHoles,
   exitCode,
   fingerprint,
+  renderPreview,
   renderSummaryTerminal,
   renderTerminal,
   routeKey,

package/flags.json

@@ -241,7 +241,7 @@
       "default": null,
       "requires": null,
       "group": "output",
-      "description": "Roll findings up (dedup by link/rule/code). Pairs with --json for a compact, agent-friendly payload."
+      "description": "Roll findings up (dedup by link/rule/code). Pairs with --json for a compact, agent-friendly payload. Not available with --baseline: there the diff is the answer, and --report writes the full report."
     },
     {
       "name": "--timeout",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goflag/cli",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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": [
@@ -66,7 +66,7 @@
     "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"
+    "release": "commit-and-tag-version --path . --skip.tag --tag-prefix v"
   },
   "dependencies": {
     "cheerio": "^1.2.0"

package/rules.json

@@ -1,6 +1,6 @@
 {
   "counts": {
-    "page": 23,
+    "page": 25,
     "site": 28,
     "prose": 5
   },
@@ -579,6 +579,34 @@
         "language": "tsx"
       }
     },
+    {
+      "id": "og.image.alt.caption",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "info",
+      "kind": "boolean",
+      "summary": "`og:image:alt` describes the image, it does not repeat the title",
+      "why": "The protocol asks for a description of what is in the image, and says in the same breath that it is not a caption. A copy of the title is the one value that is always available and never describes anything: a reader who cannot see the card is handed the same words twice and learns nothing about the picture. It also satisfies `og.image.alt` forever, which is why it needs an id of its own.",
+      "rigor": "guideline",
+      "sources": [
+        "ogp"
+      ],
+      "reads": [
+        "openGraph.images",
+        "openGraph.title",
+        "document.title"
+      ],
+      "relates": [
+        "og.image.alt",
+        "og.image.representative"
+      ],
+      "expected": "an `og:image:alt` that says something the title does not",
+      "fix": {
+        "title": "Say what the card shows, not what the page is called",
+        "snippet": "// The card is a title on a background. The alt says so — once, from a\n// template, so every page gets one and none of them is the title alone.\nconst ogAlt = (title: string) => `The title “${title}” on a dark preview card.`;",
+        "language": "ts"
+      }
+    },
     {
       "id": "og.image.dimensions",
       "scope": "page",
@@ -711,6 +739,35 @@
       ],
       "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.image.sizes-mismatch",
+      "scope": "page",
+      "category": "opengraph",
+      "severity": "warning",
+      "kind": "boolean",
+      "summary": "`og:image:width` and `og:image:height` must be the image's real size",
+      "why": "The declared size is what a crawler lays the card out with before it has the file, which is the whole reason `og.image.dimensions` asks for it. A wrong one is therefore worse than none: the crawler reserves a shape the image does not have, and the card is letterboxed or cropped on the first share — the one that matters most.\n\nIt is also the declaration that blinds every other check. `og.image.ratio` reads these two numbers and refuses to fetch, so an invented 1200×630 scores 1.9 and passes over an image that is square. Found on a site whose cover art is 1024×1024 and one of whose covers is a 337-byte 1×1 placeholder, all three declared 1200×630 by a library that had never looked at them.",
+      "rigor": "guideline",
+      "sources": [
+        "ogp",
+        "meta-og-sharing"
+      ],
+      "reads": [
+        "openGraph.images",
+        "assets"
+      ],
+      "relates": [
+        "og.image.dimensions",
+        "og.image.ratio",
+        "og.image.reachable"
+      ],
+      "expected": "declared dimensions equal to the file's own",
+      "fix": {
+        "title": "Measure the image, or let the file convention do it",
+        "snippet": "// app/…/opengraph-image.tsx — `size` is the truth and the declaration at once\nexport const size = { width: 1200, height: 630 };\n\n// Naming a file instead? Then the numbers are that file's, not a default.\nopenGraph: { images: [{ url: cover.url, width: cover.width, height: cover.height }] }",
+        "language": "tsx"
+      }
+    },
     {
       "id": "og.locale.alternates",
       "scope": "page",