@goflag/cli 0.1.3 → 0.2.0

package/README.md

@@ -1,12 +1,17 @@
 # Goflag
 
 > **A lean CLI that flags the site problems humans can't catch at scale.**
-> Point it at a URL and get three things: broken links, missing translation pages, and missing/misconfigured SEO metadata. JSON-first.
+> Point it at a URL and get four things: broken links, missing translation pages, a robots.txt that contradicts your pages, and missing or misconfigured SEO metadata. JSON-first.
 
-[![node](https://img.shields.io/badge/node-%3E%3D20.11-339933?logo=nodedotjs&logoColor=white)](./.nvmrc)
+[![node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](./package.json)
 [![license: MIT](https://img.shields.io/badge/license-MIT-green)](#license)
 
-Goflag crawls a site once and runs three focused static checks over it. 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.
+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
+search: a `hreflang` that points at a 404, a canonical that silently
+de-indexes a page, a `robots.txt` that contradicts every `<meta name="robots">`
+on the site. A human cannot check those on 400 pages. That is the whole job.
 
 ## What it checks
 
@@ -17,30 +22,88 @@ Goflag crawls a site once and runs three focused static checks over it. It is de
 
 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`.
 
-SPA support is built in: pages that look client-rendered are re-rendered in headless Chromium automatically (pass `--static` to skip it).
+**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
+headless Chromium before being judged, so a SPA is not reported as missing
+everything. `--static` turns that off, including the detection: with it, a
+client-rendered page is judged on its unhydrated shell.
 
-## Repository layout
+That direction is deliberate. Static mode over-reports rather than under-reports
+— the metadata is genuinely absent from the HTML a crawler receives — so it
+fails loudly rather than passing quietly. It is also why `--static` is the right
+default in CI: it needs no browser, and it cannot mistake a broken page for a
+fine one.
+
+## Install
 
+Requires Node `>=22`.
+
+```sh
+npx @goflag/cli https://example.com          # one-off, nothing installed
+pnpm add -D @goflag/cli                      # then: pnpm goflag https://example.com
 ```
-packages/cli/      @goflag/cli — the CLI (installs the `goflag` command)
-packages/next/     @goflag/next — the Next.js library (not built yet)
-apps/website/      documentation and marketing site (not built yet)
+
+Install it as a dev dependency once you run it more than once — in a script, in
+CI, in a git hook. `npx` is for trying it.
+
+The package is `@goflag/cli`; the command it installs is `goflag`. Everything
+under the brand lives in the `@goflag` scope; the bare `goflag` name on npm is a
+deprecated signpost pointing here and carries no code.
+
+Headless rendering needs Chromium, which is **not** installed with goflag —
+`playwright` is an optional peer dependency. Add it only if you audit
+client-rendered pages without `--static`:
+
+```sh
+pnpm add -D playwright && pnpm exec playwright install chromium
 ```
 
-The library and the apps must not import from the CLI: the two products stay
-independently useful, and a lint rule enforces it rather than trusting memory.
+## Getting started
 
-## Quick start
+Five steps, in this order. Each one is explained in full further down; this is
+the sequence.
 
-Requires Node `>=20.11`.
+**1. Look at your site.** No flags, no gate — find out what is there.
 
 ```sh
 npx @goflag/cli https://example.com
 ```
 
-The package is `@goflag/cli`; the command it installs is `goflag`. The bare
-`goflag` name on npm is not claimed yet — see the note in
-[docs/spec-and-lib-plan.md](docs/spec-and-lib-plan.md#une-marque-des-outils-nommés).
+Expect it to be red. Almost every site that has never been audited has a
+backlog, and that is not a reason to fix everything before continuing.
+
+**2. Decide what is real.** Some findings are deliberate — a legal page that
+exists in one jurisdiction, a route you chose not to translate. Tell goflag,
+rather than living with noise:
+
+```sh
+npx @goflag/cli https://example.com --ignore-holes /legal
+```
+
+**3. Capture a baseline.** This freezes today's findings as "known", so the gate
+can ask _did this change make it worse?_ instead of _is this site perfect?_
+
+```sh
+npx @goflag/cli https://example.com --static --no-external \
+  --baseline .goflag/baseline.json --update-baseline
+```
+
+It prints how many findings it grandfathered and the `--max-debt` to set next.
+Commit `.goflag/baseline.json`.
+
+**4. Gate CI on regressions.** See [In CI](#in-ci) for a job you can copy.
+
+```sh
+goflag https://example.com --static --no-external \
+  --baseline .goflag/baseline.json --regressions-only --max-debt 41
+```
+
+**5. Lower the ratchet.** Fix a finding, drop `--max-debt` by one, commit both.
+This is the only part that makes the backlog shrink; without it a baseline
+fossilises behind a passing build.
+
+Steps 3 to 5 are the whole method. The rest of this README is why each flag
+behaves the way it does.
 
 You get a coloured terminal report and an exit code:
 
@@ -48,6 +111,11 @@ You get a coloured terminal report and an exit code:
 - `1` — findings present (yellow/red flag) — use this as a CI gate
 - `2` — fatal error (bad URL, unexpected failure)
 
+## Using it
+
+Everything below is reference: what each flag does and why it behaves that way.
+The five steps above are the path; this is the map.
+
 ### JSON is the source of truth
 
 ```sh
@@ -70,11 +138,19 @@ The terminal view is just a render of that JSON.
 --ignore-holes <glob>  Route deliberately not translated everywhere
                        (repeatable).
 --no-sitemap           Do not discover the sitemap; crawl from <url> only.
+--profile <name>       Policy overlay on the rule set: default, strict,
+                       spec-only, marketing.
+--conformance          Report every rule's status on every page, not just
+                       the violations.
+--advisories           Attach the prose rules — the judgment calls goflag
+                       refuses to fake — with the facts to judge them by.
 --fail-on <level>      Exit 1 at or above this severity: warning (default),
                        error, or never.
 --regressions-only     Weaken the gate: fail only on NEW findings relative
                        to --baseline. Requires --baseline.
 --baseline <file>      Stored report to compare against.
+--update-baseline      Write this run to --baseline and exit 0, instead of
+                       judging against it.
 --max-debt <n>         Fail when the site carries more than <n> findings in
                        total, new or known.
 --start <cmd>          Boot <cmd>, wait for <url>, audit, then stop it.
@@ -90,7 +166,101 @@ The terminal view is just a render of that JSON.
 -v, --version          Show the version.
 ```
 
-Headless mode needs Chromium. It ships as an optional dependency; if it's missing, install it with `npx playwright install chromium` (or just run with `--static`).
+Headless mode needs Chromium. `playwright` is an optional peer dependency; if it's missing, install it with `npx playwright install chromium` (or just run with `--static`).
+
+### Profiles: how much each rule matters to you
+
+Every rule records how authoritative it is — whether a published spec requires
+it, a vendor documents it, or it is widely-repeated folklore. That is a fact
+about the rule, and goflag never fudges it. What your build should _do_ about
+each one is a separate question, and that is what `--profile` answers:
+
+```sh
+goflag https://example.com --profile spec-only    # only what a spec backs
+goflag https://example.com --profile strict       # spec-backed rules fail the build
+goflag https://example.com --profile marketing    # metadata gaps are errors
+```
+
+| Profile     | What it does                                                                   |
+| ----------- | ------------------------------------------------------------------------------ |
+| `default`   | Each rule's own severity. No overlay.                                          |
+| `strict`    | Every spec-backed rule becomes an `error`. Heuristics stay warnings.           |
+| `spec-only` | Heuristic rules (title/description length) are switched off entirely.          |
+| `marketing` | The snippet and unfurl metadata — description, `og:title`, `og:image` — error. |
+
+A profile only changes how loudly a rule fires and whether it runs at all. It
+never changes what a rule observes, and it never rewrites a rule's stated
+authority — so `strict` can make a finding fail your build, but it cannot turn
+folklore into a spec requirement.
+
+The report records which profile produced it (`"profile": "strict"`), and the
+terminal output names any non-default one. A run under `spec-only` reporting
+zero issues means "nothing a spec backs is wrong here", not "nothing is wrong".
+
+That record is load-bearing: comparing a run against a baseline captured under
+a different profile still works, but "0 new findings" no longer means what it
+appears to, so goflag says so rather than letting the number speak for itself:
+
+```
+REGRESSION GATE  0 new · 19 known findings NOT gating this build
+baseline https://example.com — taken 2026-08-06 (today)
+note: baseline was captured under profile `strict`, this run used `spec-only` — the two are not like-for-like.
+```
+
+It is a warning, never a gate — a `--profile spec-only` investigation against a
+`strict` baseline is a legitimate thing to do.
+
+### Where do we stand? (`--conformance`)
+
+A list of violations cannot tell you the difference between a rule that
+passes everywhere and a rule that never applied to a single page. Both look
+like silence. `--conformance` reports every rule's status on every page:
+
+```sh
+goflag https://example.com --conformance
+```
+
+```
+Conformance
+  6 pages × every rule
+  canonical.absolute       6 fail  [vendor-spec]
+  canonical.missing        6 pass  [vendor-spec]
+  description.length       6 n/a   [heuristic]
+  title.missing            6 pass  [spec-required]
+```
+
+The terminal shows the tally; `--json` carries the full rule × page grid,
+with each rule's rigor and sources in a legend rather than repeated per
+cell. `pass + fail + warn + n/a + crashed` always equals the page count, so
+the coverage claim is checkable.
+
+### The questions goflag will not answer for you (`--advisories`)
+
+Whether a title _describes_ the page is not a thing a linter can decide.
+goflag could fake it — count words, match boilerplate, emit a confident
+verdict — and the result would be unfalsifiable noise. So it states the
+question, cites what makes it a real requirement, attaches the observed
+facts, and stops:
+
+```sh
+goflag https://example.com --advisories --json
+```
+
+```json
+{
+  "ruleId": "description.accurate",
+  "prose": "Does the description accurately summarize this page's content, and is it written for this page rather than copied across the site?",
+  "rigor": "guideline",
+  "sources": ["google-snippet", "moz-meta-description"],
+  "evidence": { "meta.description": { "value": "…", "origin": { "kind": "meta" } } },
+  "verdict": "needs-judgment"
+}
+```
+
+Advisories are asked only where the subject exists — no question about a
+description on a page that has none, because `description.missing` already
+says that. They never count toward the summary, the verdict, or the exit
+code: nobody has judged them yet.
 
 ### Gate on regressions, not on perfection
 
@@ -99,7 +269,7 @@ yet — so it gets switched off, or ignored. Capture a baseline once and gate on
 "did this change make it worse?" instead:
 
 ```sh
-goflag https://example.com --report baseline.json --json          # once
+goflag https://example.com --baseline baseline.json --update-baseline   # once
 goflag https://example.com --regressions-only --baseline baseline.json
 ```
 
@@ -129,6 +299,28 @@ goflag https://example.com --regressions-only --baseline baseline.json --max-deb
 Keeping `baseline.json` in the repository helps for the same reason: adding a
 finding to it then shows up in a diff someone reviews.
 
+Capture it with the run that will later judge it, minus one flag:
+
+```sh
+goflag https://example.com --baseline baseline.json --update-baseline
+```
+
+That matters more than it looks. A baseline captured with different options than
+the gate — a forgotten `--static`, another `--max-pages` — does not compare
+cleanly, and the mismatch surfaces as findings that appear from nowhere. Using
+the same command for both makes that impossible.
+
+The same flag accepts findings you have decided to live with, and it says what
+it accepted:
+
+```
+goflag: baseline updated — 3 newly accepted, 0 resolved, 44 findings now
+grandfathered in baseline.json
+```
+
+Refreshing a baseline is taking on debt. It prints the number so the commit that
+does it can be read as what it is.
+
 ### Gate a merge before it ships
 
 `--start` boots your app, waits for it to answer, audits it, and stops it — so
@@ -175,10 +367,121 @@ 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.
 
+## In CI
+
+Two moments are worth auditing, and they answer different questions.
+
+| When                 | Against                                     | Answers                                  |
+| -------------------- | ------------------------------------------- | ---------------------------------------- |
+| On the merge request | the branch's own build, booted by `--start` | does **this change** regress?            |
+| After deploying      | the running environment                     | is what is **actually serving** correct? |
+
+Neither replaces the other. Only the deployed run sees what the environment
+injects — the real base URL, whatever the proxy serves for `robots.txt`,
+redirects. A canonical broken by a misconfigured environment variable is
+invisible in a local build.
+
+Three rules, whichever you use:
+
+- **Pin the version.** A floating one turns someone else's release into a red
+  pipeline on a commit that touched nothing, and the job is only worth having if
+  red means "you broke something".
+- **Commit the baseline.** Grandfathering a finding then shows up in a diff
+  somebody reviews, instead of vanishing into a cache.
+- **Build the same site the baseline was captured against.** Frameworks bake
+  build-time environment into the output; a build that differs produces
+  differences that are real in the report and meaningless as findings.
+
+### GitLab CI
+
+```yaml
+stages: [build, deploy, audit]
+
+variables:
+  GOFLAG_VERSION: "0.1.4"
+
+# Before the merge: build the branch, let goflag boot it, audit that.
+seo:mr:
+  stage: audit
+  image: node:24-alpine
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+  script:
+    - corepack enable && pnpm install --frozen-lockfile
+    - pnpm build
+    - npx --yes "@goflag/cli@$GOFLAG_VERSION" http://localhost:3000
+      --start "pnpm start" --static --no-external
+      --baseline .goflag/baseline.json --regressions-only --max-debt 41
+  artifacts:
+    when: always
+    paths: [goflag-report.json]
+
+# After the deploy: audit what is serving.
+seo:
+  stage: audit
+  image: node:24-alpine
+  needs: [{ job: deploy, artifacts: false }]
+  rules:
+    - if: $CI_COMMIT_BRANCH == "develop"
+  script:
+    - npx --yes "@goflag/cli@$GOFLAG_VERSION" https://develop.example.com
+      --static --no-external
+      --baseline .goflag/baseline.json --regressions-only --max-debt 41
+      --report goflag-report.json
+  artifacts:
+    when: always
+    paths: [goflag-report.json]
+```
+
+### GitHub Actions
+
+```yaml
+name: seo
+on: [pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 24 }
+      - run: corepack enable && pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: |
+          npx --yes @goflag/cli@0.1.4 http://localhost:3000 \
+            --start "pnpm start" --static --no-external \
+            --baseline .goflag/baseline.json --regressions-only --max-debt 41
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: goflag-report
+          path: goflag-report.json
+```
+
+### Why `--static --no-external` in CI
+
+`--static` needs no browser, so the job runs on a plain Node image and cannot
+be slowed by a Chromium download. `--no-external` skips off-origin links, which
+are the ones you cannot fix and whose failures are somebody else's outage — a
+gate that goes red because a third party is down teaches people to ignore it.
+
+Audit external links on a schedule instead, where nobody is waiting.
+
+### Reading a red build
+
+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.
+
+If the finding is one you have decided to accept, refresh the baseline with the
+same command minus `--regressions-only`, plus `--update-baseline`. It will tell
+you what it accepted, and that number belongs in the commit message.
+
 ## Programmatic API
 
 ```ts
-import { runAudit } from "goflag";
+import { runAudit } from "@goflag/cli";
 
 const report = await runAudit("https://example.com", { depth: 2 });
 console.log(report.summary); // { brokenLinks, missingTranslations, seoIssues, verdict }
@@ -186,8 +489,27 @@ console.log(report.summary); // { brokenLinks, missingTranslations, seoIssues, v
 
 `runAudit` returns the same `GoflagReport` object the CLI emits.
 
+## Repository layout
+
+```
+packages/cli/      @goflag/cli — the CLI (installs the `goflag` command)
+tools/name-holder/ the bare `goflag` name on npm, a signpost to @goflag/cli
+```
+
+That is the whole tree. `@goflag/next` (the Next.js library) and the
+documentation site are planned but deliberately absent: the workspace globs
+(`packages/*`, `apps/*`) are ready for them, and empty stubs for things that do
+not exist are how a repository accumulates code nobody calls.
+
+When they land, they must not import from the CLI: the two products stay
+independently useful, and an ESLint rule enforces it rather than trusting
+memory.
+
 ## Develop locally
 
+Requires pnpm `11.18.0` (pinned via `packageManager` — `corepack enable` picks
+it up). Run these from the repository root:
+
 ```sh
 pnpm install
 pnpm dev https://example.com   # run the CLI from source (tsx)
@@ -200,7 +522,11 @@ pnpm typecheck                 # tsc --noEmit
 pnpm format                    # prettier
 ```
 
-The engine is framework-agnostic and lives in [`src/lib/core/`](src/lib/core) (crawl, fetch/extract, link audit, i18n) and [`src/lib/rules/`](src/lib/rules) (SEO checks). The CLI shell — orchestration, the `GoflagReport` schema, and rendering — lives in [`src/report/`](src/report) and [`src/cli.ts`](src/cli.ts).
+`lint`, `format` and `format:check` run once over the whole repository; the
+rest fan out across workspace packages with `pnpm -r`. To work on one package,
+filter: `pnpm --filter @goflag/cli test`.
+
+The engine is framework-agnostic and lives in [`packages/cli/src/lib/core/`](packages/cli/src/lib/core) (crawl, fetch/extract, link audit, i18n) and [`packages/cli/src/lib/rules/`](packages/cli/src/lib/rules) (SEO checks). The CLI shell — orchestration, the `GoflagReport` schema, and rendering — lives in [`packages/cli/src/report/`](packages/cli/src/report) and [`packages/cli/src/cli.ts`](packages/cli/src/cli.ts).
 
 ## License