@goflag/cli 0.2.12 → 0.2.14

package/README.md

@@ -5,6 +5,12 @@ A CLI that audits a site for broken links, missing translation pages, a robots.t
 [![node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://github.com/tancredesimonin/goflag/blob/main/package.json)
 [![license: MIT](https://img.shields.io/badge/license-MIT-green)](#license)
 
+[![A goflag run against a site with findings: a red verdict over the crawl counts, a COVERAGE line saying how many pages of the sitemap were audited, the tally of broken links, missing translations and SEO issues, then the broken links listed under the page that references them.](https://goflag.tech/assets/hero.png)](https://goflag.tech/docs/report)
+
+<sub>The first eleven lines of a real run. Rendered from the same transcript the
+documentation site paints, which is compared to the renderers byte for byte —
+so this picture cannot drift from what the command prints.</sub>
+
 Goflag crawls a site once and judges what it found. It is deliberately small: no dashboard, no config system, no social-preview gallery. Just the findings, as a machine-readable report you can pipe, diff, or gate CI on.
 
 It is built for the mistakes that are invisible while browsing and expensive in
@@ -38,14 +44,14 @@ here and carries no code.
 - **Open Graph, past its presence** — a declared `og:image` is judged as well as counted: relative URLs no crawler can resolve, an undeclared size (so the first share of a URL renders without the image), a shape far from the 1.91:1 the card is cropped to, a missing `og:image:alt`, and — the one no tag check can reach — whether the URL actually serves an image at all. On a translated page, `og:locale` and `og:locale:alternate` are checked against the hreflang cluster — two vocabularies for one fact, which nothing in a build keeps in step.
 - **Icons** — whether anything declares one at all (nothing in a spec requires it, which is why nothing complains), whether iOS has an `apple-touch-icon` to use instead of screenshotting the page, whether the Web App Manifest and the `<head>` contradict each other about the same file, whether every declared icon answers with an image, whether a `sizes` attribute describes the file it points at (a `.ico` carrying 16, 32 and 48 declared as `48x48` advertises a third of itself), and whether the origin actually serves `/favicon.ico` — a 200 of HTML from a catch-all route does not count. Two icon lists that merely differ are the normal case and are not reported.
 - **Sitemap** — whether there is one, whether it parses (an HTML error page served with a 200 reads as healthy to anything that only checks the status), whether it lists anything, and whether an index can reach its children. Each entry is judged too: a `<loc>` that is not absolute, entries on another host or another protocol, a `<lastmod>` that is not a W3C Datetime or is dated in the future, a `changefreq` or `priority` outside the values the protocol defines.
-- **Where the two files meet the crawl** — the contradictions no single artefact shows. A sitemap entry that `robots.txt` forbids fetching, one whose page declares `noindex`, one whose canonical points elsewhere, one that 404s or redirects, and the indexable pages the crawl found that the sitemap never lists. Entry probing answers from the crawl and the link audit before it fetches anything, so a well-built site costs almost no extra requests — and when the caps stop it short, the finding says how many went unchecked rather than implying the rest are fine. Nothing is broken when you look at either half alone, which is why nobody finds these by reading.
+- **Where the two files meet the crawl** — the contradictions no single artefact shows. A sitemap entry that `robots.txt` forbids fetching, one whose page declares `noindex`, one whose canonical points elsewhere, one that 404s or redirects, and the indexable pages the crawl found that the sitemap never lists — judged only once every sitemap the site declares has been read, since a page listed where goflag could not read looks exactly like one the site forgot. Entry probing answers from the crawl and the link audit before it fetches anything, so a well-built site costs almost no extra requests — and when the caps stop it short, the finding says how many went unchecked rather than implying the rest are fine. Nothing is broken when you look at either half alone, which is why nobody finds these by reading.
 - **Unreachable pages** — a page the crawl reached that answered non-2xx, or that never answered at all (timeout, reset, DNS failure — recorded as `status: 0`), is reported in `unreachablePages`. goflag asks a second time, from the back of the queue, before calling a page unreachable. Each one is an `error`-severity finding: it turns the verdict red, counts toward `--max-debt`, and fails the build even under `--fail-on error`. A page that silently dropped out of the audited set is what poisons a baseline, so it is reported rather than warned about.
 
 **Which pages get audited.** When goflag finds a sitemap it does not audit every URL in it. It groups URLs that share a path shape — and therefore a template — into families, audits every page that stands alone, and samples three pages per family. A cap answers "how many" and never "which": on a site of thousands of pages built from thirty templates, the first 200 pages a crawl reaches are four templates out of thirty.
 
 The trade is stated in every report rather than hidden. Template rules (`canonical.*`, `hreflang.*`, `og.image.missing`) are conclusive on a sampled family; copy rules (`title.length`, `description.length`), broken links and the translation matrix are only conclusive on the pages that were drawn. The terminal prints a `COVERAGE` line, and `diagnostics.coverage` carries `mode`, `considered`, `selected` and every sampled family with its ratio. Pass `--coverage all` to audit what the sitemap lists in order, up to `--max-pages`, which is the pre-0.2.3 behaviour.
 
-Pages that declare a `<link rel="canonical">` pointing at another crawled page are excluded from the checks — the site has said they are duplicates, so linting them would multiply every finding by the number of filtered variants. The count is reported as `diagnostics.duplicatePages`.
+Pages that declare a `<link rel="canonical">` pointing at another crawled page are excluded from the page checks — the site has said they are duplicates, so linting them would multiply every finding by the number of filtered variants. The count is reported as `diagnostics.duplicatePages`. They still count for what the sitemap lists: a variant the sitemap names is the defect `sitemap.entry.non-canonical` reports.
 
 **Client-rendered pages.** By default, a page whose `<head>` looks empty — no
 title, no description, no canonical, no OG, no JSON-LD — is re-rendered in
@@ -61,7 +67,7 @@ fine one.
 
 ## Where it runs
 
-Two packages ship to npm from a tag, published by GitLab CI over OIDC with no stored credential: `@goflag/cli` (`v*`) and `@goflag/next` (`next-v*`). The documentation site `apps/website` runs at [goflag.tech](https://goflag.tech), with `develop.goflag.tech` alongside it, both deployed with Kamal onto the shared OVH host described in the `infrastructure` repository.
+Three packages ship to npm from a tag, published by GitLab CI over OIDC with no stored credential: `@goflag/cli` (`v*`), `@goflag/next` (`next-v*`) and `@goflag/og` (`og-v*`). The documentation site `apps/website` runs at [goflag.tech](https://goflag.tech), with `develop.goflag.tech` alongside it, both deployed with Kamal onto the shared OVH host described in the `infrastructure` repository.
 
 ## Your first audit
 
@@ -150,8 +156,8 @@ npx @goflag/cli rules > rules.json
 ```
 
 `rules` answers a question about goflag rather than about a site: no URL, no
-crawl, no network. It ships fifty-eight rules — twenty-five page rules,
-twenty-eight site rules and five prose rules — and every entry carries its
+crawl, no network. It ships sixty-four rules — twenty-five page rules,
+thirty-four site rules and five prose rules — and every entry carries its
 scope, severity and summary. All but one also carry a rigor, the documents they
 cite and, where a remedy is a line of code, a fix snippet. The exception is
 `hreflang.sitemap-mismatch`, which emits `rigor: null` with an empty `sources`
@@ -469,6 +475,11 @@ same confidence would be six unearned claims, so the file says which is which.
 It never gates — it exits 0 unless the run itself failed — and it prints the
 path it wrote, so `open "$(goflag preview http://localhost:3000)"` opens it.
 
+An example of what it writes — a real audit, frozen, so its footer names the date it was
+taken — is served at <https://goflag.tech/assets/example-preview.html>. The URL is absolute
+because `prepack` copies this file into the package and npm renders it, where a relative link
+is dead.
+
 ### Multilingual sites
 
 Discovery is seeded from the sitemap, not just from links. That matters because
@@ -547,7 +558,7 @@ Three rules, whichever you use:
 stages: [build, deploy, audit]
 
 variables:
-  GOFLAG_VERSION: "0.2.12"
+  GOFLAG_VERSION: "0.2.14"
 
 # Before the merge: build the branch, let goflag boot it, audit that.
 seo:mr:
@@ -599,7 +610,7 @@ jobs:
       - run: corepack enable && pnpm install --frozen-lockfile
       - run: pnpm build
       - run: |
-          npx --yes @goflag/cli@0.2.12 http://localhost:3000 \
+          npx --yes @goflag/cli@0.2.14 http://localhost:3000 \
             --start "pnpm start" --static --no-external \
             --baseline .goflag/baseline.json --regressions-only --max-debt 41 \
             --report goflag-report.json
@@ -621,6 +632,25 @@ Audit external links on a schedule instead, where nobody is waiting.
 
 ### Reading a red build
 
+A red build says what moved, not what is wrong. The diff lists rule ids and
+absolute page URLs; the messages and the fixes are in the report:
+
+<!-- goflag:transcript gate -->
+
+```plaintext
+goflag --regressions-only
+REGRESSION  1 new · 13 known findings NOT gating this build · 1 resolved
+baseline https://example.com/ — taken 2026-07-21T09:14:02.881Z (14 days ago)
+
+New findings
+  + error seo  canonical.absolute on https://example.com/pricing
+
+Resolved
+  - warn  seo  og.image.missing on https://example.com/about
+```
+
+<!-- /goflag:transcript -->
+
 The report artefact is the thing to open. It is the same JSON as `--json`, and
 it is kept whether the job passed or failed, because it is most wanted when it
 is red.
@@ -683,7 +713,7 @@ finding unrepresentable. Full documentation at
 Two of this catalogue's rules had no remedy to point at. `og.image.missing`
 fired 24 times on one site and `og.image.alt` 46 times on another, and the fix
 for both is "either an asset or a route you have to write" — which is how a rule
-becomes permanent debt. [`@goflag/og`](packages/og) is that route, written once.
+becomes permanent debt. [`@goflag/og`](https://github.com/tancredesimonin/goflag/tree/main/packages/og) is that route, written once.
 
 ```tsx
 // app/[locale]/opengraph-image.tsx
@@ -701,7 +731,7 @@ embeds satori — turns into a PNG at build time, so nothing installs a second
 renderer and a card can be unit-tested with no framework build. It also packs
 the `favicon.ico` **no Next convention emits**, guarded so that a generated file
 living in git is not dirtied by every commit. API reference in
-[`packages/og/README.md`](packages/og/README.md).
+[`packages/og/README.md`](https://github.com/tancredesimonin/goflag/blob/main/packages/og/README.md).
 
 ## Develop locally