@goflag/cli 0.2.7 → 0.2.9

package/README.md

@@ -16,9 +16,11 @@ on the site. A human cannot check those on 400 pages. That is the whole job.
 ## What it checks
 
 - **Broken links** — scrapes every crawled page, dedupes targets globally (a footer link on 500 pages is probed once), and checks each with `HEAD`→`GET` fallback, redirect-chain/loop detection, soft-404 and anti-bot (403/429) triage. Broken links are mapped back to the pages that reference them.
-- **Missing translation pages** — builds a `route × locale` matrix and flags every route that exists in one locale but is missing in another, plus hreflang reciprocity gaps (`A → B` with no `B → A`), missing `x-default`, and locale tags naming a language, script or region that does not exist. Rows are keyed by pathname, unless your sitemap declares its translation clusters with `xhtml:link` — then those declarations decide which URLs are one page, whatever their slugs, and the run reports `diagnostics.declaredClusters`.
+- **Missing translation pages** — builds a `route × locale` matrix and flags every route that exists in one locale but is missing in another, plus hreflang reciprocity gaps (`A → B` with no `B → A`), missing `x-default`, and locale tags naming a language, script or region that does not exist. Rows are keyed by pathname, unless the site declares its translation clusters — either with `xhtml:link` in the sitemap, or with reciprocal `hreflang` between two crawled pages' `<head>`. Then those declarations decide which URLs are one page, whatever their slugs, and the run reports `diagnostics.declaredClusters`. The sitemap source survives `--coverage structural`, where the two locales of a slug-translating family are rarely both sampled; the `<head>` source needs both pages in hand and is what fixes the common site that declares properly there and nothing in its sitemap.
 - **robots.txt policy** — flags a site that forbids crawling while its pages ask to be indexed. The two declarations cannot both hold, and robots.txt wins, so the meta tag is never even read.
 - **SEO metadata** — lints each page's `<head>` for the handful of mistakes that actually hurt in search and social and are invisible in a browser: missing/oversized `<title>` and description, missing/relative canonical, missing `og:title`/`og:description`/`og:image`, missing viewport, and contradictory `robots`/`googlebot`/`X-Robots-Tag` directives.
+- **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.
 - **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.
@@ -138,14 +140,27 @@ npx @goflag/cli rules > rules.json
 
 `rules` answers a question about goflag rather than about a site: no URL, no
 crawl, no network. Every entry carries its scope, severity and summary; the
-eleven page rules and four prose rules also carry a rigor, the documents they
-cite and — where a remedy is a line of code — a fix snippet. The three site
-rules carry none of those three: `SiteRule` has no rigor field yet, and the
-catalogue emits `rigor: null` with an empty `sources` rather than inventing an
-authority nobody assigned. Write your consumer against that. The same document
+twenty-three page rules and four prose rules also carry a rigor, the documents they
+cite and — where a remedy is a line of code — a fix snippet. Cross-page rules
+may carry them too, and one does; the three that predate the field still emit
+`rigor: null` with an empty `sources`, because choosing their citations is work
+nobody has done and inventing an authority is worse than admitting the gap.
+Write your consumer against that. The same document
 ships inside the package as `rules.json`, if you would rather read it than run
 anything.
 
+The flag list below is data too:
+
+```sh
+npx @goflag/cli flags > flags.json
+```
+
+Same idea, one step further: `flags` prints the very table `goflag --help` is
+rendered from and the argument parser dispatches on, so a flag cannot exist in
+one and not the other. Each entry carries its long and short forms, its argument
+placeholder, its default, the group it belongs to and any flag it requires. It
+ships inside the package as `flags.json` as well.
+
 It deliberately omits the message a finding prints — that is built at audit time
 from what the page actually says, so a static copy would be a sample rather than
 a fact, and a sample presented as the truth is how this project's own
@@ -424,6 +439,17 @@ goflag https://example.com --ignore-holes /legal --ignore-holes "/blog/**"
 Suppressed gaps are counted in `diagnostics.ignoredHoles`, so a quiet report
 never means "nothing was wrong" by accident.
 
+The opposite failure is quieter still. A cell in the matrix can be filled by an
+`hreflang` on another page and by nothing else — not crawled, not listed in your
+sitemap — and a filled cell reads as a translation that exists. A page
+advertising a translation the site does not serve therefore plugs the very gap
+it should reveal. Those cells are counted in
+`diagnostics.unverifiedAlternates`, and goflag deliberately does **not** act on
+them: refusing to believe an alternate the sitemap omits would invent holes on
+every site using `@goflag/next`'s `sitemap: false` on purpose. Read that number
+next to `missingTranslations` — a `0` beside a non-zero count is the one place
+this report can be quietly wrong.
+
 ## In CI
 
 Two moments are worth auditing, and they answer different questions.
@@ -455,7 +481,7 @@ Three rules, whichever you use:
 stages: [build, deploy, audit]
 
 variables:
-  GOFLAG_VERSION: "0.2.7"
+  GOFLAG_VERSION: "0.2.9"
 
 # Before the merge: build the branch, let goflag boot it, audit that.
 seo:mr:
@@ -507,7 +533,7 @@ jobs:
       - run: corepack enable && pnpm install --frozen-lockfile
       - run: pnpm build
       - run: |
-          npx --yes @goflag/cli@0.2.7 http://localhost:3000 \
+          npx --yes @goflag/cli@0.2.9 http://localhost:3000 \
             --start "pnpm start" --static --no-external \
             --baseline .goflag/baseline.json --regressions-only --max-debt 41 \
             --report goflag-report.json