styleproof 3.20.0 → 4.0.0

package/CHANGELOG.md

@@ -7,6 +7,198 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-07-07
+
+The first major since v3. Three breaking defaults make StyleProof strict out of
+the box — an unapproved change **blocks**, a silently-failing data endpoint
+**gates**, and a manifest-less map bundle is **refused** rather than compared on
+faith. Pin `BenSheridanEdwards/StyleProof@v4` to adopt; `@v3` stays on 3.x. Each
+breaking entry below carries its one-line migration.
+
+### Removed
+
+- **BREAKING: a manifest-less map bundle is no longer compared — it fails with exit
+  `2`.** Before, a two-directory `styleproof-diff`/`styleproof-report` where a side
+  shipped captured maps but no `styleproof-manifest.json` (the legacy committed-map
+  workflow) printed a one-line stderr notice and **compared anyway** (the tolerance
+  added in #200). The same-environment guard can't be enforced without a manifest, so
+  captures from different browser builds or platforms could diff as false changes. For
+  **v4** that tolerance is removed: a side that ships maps with no manifest now fails
+  loudly with exit `2` (usage/capture error), naming the bare side(s) and the remedy —
+  re-capture with current StyleProof; maps without a manifest are unsupported. A dir
+  with _no maps at all_ is unchanged: it is "no baseline yet", still the first-adoption
+  review path (exit `3`), not a bare bundle. **Migration:** re-capture both sides —
+  `styleproof-map` for spec-driven surfaces, or `styleproof-capture` for a one-shot
+  design diff; both now write a `styleproof-manifest.json` into their output dir
+  (`styleproof-capture` previously wrote none, which would have made the design-match
+  flow fail under this change — it now stamps one, degrading the git SHA/dirty fields
+  gracefully when run outside a git repo).
+
+### Changed
+
+- **BREAKING: `dataResidue` now defaults to `'gate'` instead of `'warn'`.** A
+  data-boundary request (`replayUrl`, default `**/api/**`) that fails during a
+  spec-driven capture means the endpoint's _fallback_ branch shipped as the certified
+  state — its response-driven states were never captured. Warn-only was the
+  backwards-compatible launch choice, not the correct one; the default is now to BLOCK.
+  `'warn'` remains fully supported as the explicit opt-out (record + warn without
+  gating); the acknowledgement ledger and stale-acknowledgement rot protection are
+  unchanged. **Migration:** if a capture now fails on a data endpoint you expect to be
+  down, either acknowledge the intentional failures in `styleproof.data-residue.json`
+  (`{"<surface·endpoint>": "why"}`), or set `dataResidue: 'warn'` in the capture spec to
+  restore the previous non-gating behaviour. A capture with no failing data request is
+  unaffected. (#205)
+
+- **BREAKING: `blocking` now defaults to `true`.** In review-gate mode
+  (`require-approval: true`), an **unapproved** visual change now **fails the
+  report job** (red ✗) out of the box, so the check blocks a merge even on a repo
+  without a branch-protection rule requiring the `StyleProof` status (which needs
+  GitHub Pro or a public repo). Previously the default was `false` — advisory-only,
+  where only the commit status went red. The approve→re-run flow is unchanged: tick
+  **Approve all changes**, re-run the job, and the re-run sees the sign-off and
+  passes. Certify mode (`fail-on-diff: true`) is unaffected. **Migration:** to keep
+  the old advisory-only behaviour, set `"blocking": false` in
+  `styleproof.config.json` at your repo root.
+- **Pre-push guidance no longer commits maps to the PR branch** (docs and repo
+  hygiene only; no change to the published package, CLI, or Action). The
+  pre-push recipe previously ended with `git add stylemaps` + a map commit on
+  the branch — so maps appeared as changed files in every PR, and because all
+  PRs wrote the same `stylemaps/` paths, each merge forced every other open PR
+  to rebase. The recipe now captures and publishes to the SHA-keyed
+  `styleproof-maps` store branch (what `styleproof-map` already does outside
+  CI) and never touches the PR branch; `stylemaps/` is gitignored as a
+  guardrail, and the README states the maps-never-in-PR rule explicitly.
+
+### Added
+
+- **Data-residue guard — a capture that embeds an unprovoked data-fault state now
+  says so.** During a spec-driven capture, any request matching the data boundary
+  (`replayUrl`, default `**/api/**`) that FAILS — a network error, or a 4xx/5xx —
+  means the captured state rendered that endpoint's _fallback_ branch, so the states
+  its real responses would drive are uncaptured and unproven (the failure mode
+  documented in #202). StyleProof now names each such failure on stderr at capture
+  time (what failed, what it means, what to do: fixture it via `page.route`/
+  `liveStates`, or acknowledge it), records it on the capture (`StyleMap.dataResidue`),
+  and surfaces it in `styleproof-diff` and the report's certification block. **Gate by
+  default:** an _unacknowledged_ failing endpoint blocks the diff (exit 1); acknowledge
+  intentional ones in `styleproof.data-residue.json` (`key → reason`), and a stale
+  acknowledgement (the endpoint no longer fails) also fails so the ledger can't rot — the
+  same discipline as `exclude` and the inventory guard. Set `dataResidue: 'warn'` to opt
+  down to record-and-warn without gating. A 2xx endpoint that merely wasn't fixtured is
+  **never** flagged (recording mode legitimately records live responses). `--json` gains
+  an additive optional `dataResidue` field. A capture with no failing data request is
+  byte-identical whichever mode you run. Fixes #205.
+- **`styleproof-init` now installs the pre-push publish hook by default.** The
+  capture-locally/publish-to-store flow is the out-of-the-box path, not an
+  opt-in recipe: init scaffolds a `pre-push` hook (into `.husky/` when present,
+  else `.githooks/` with a one-line activation hint) that runs `styleproof-map`
+  — capture this commit, publish the bundle to the SHA-keyed `styleproof-maps`
+  branch — plus an advisory `styleproof-diff`, so CI restores by SHA and stays
+  report-only. `STYLEPROOF_SKIP_CAPTURE=1 git push` skips a push that can't
+  affect render. Never overwrites an existing hook; maps never get committed
+  to the PR branch.
+- **`styleproof-init` now installs the approval workflow.** The generated report
+  workflow runs with `require-approval: true`, but the `issue_comment` handler
+  that flips the `StyleProof` status when a reviewer ticks **Approve all changes**
+  previously had to be copied from `example/` by hand — leaving the review gate
+  inert until someone did. `styleproof-init` now scaffolds
+  `.github/workflows/styleproof-approve.yml` alongside the report workflow
+  (copied verbatim from the packaged example, never overwriting an existing file),
+  so the gate is complete out of the box. It activates once the init PR merges,
+  since GitHub runs `issue_comment` workflows only from the default branch.
+- **Enforced quality gates and an agent context layer** (repository tooling only;
+  no change to the published package, CLI, or Action). A `commit-msg` commitlint
+  hook and PR-title/body validation enforce Conventional Commits; gitleaks
+  (staged-diff hook + full-history CI, fail-closed), CodeQL, and
+  `npm audit --audit-level=high` add secret/SAST/dependency scanning; a machine
+  `pull_request` check validates the PR template shape. `AGENTS.md` is now the
+  tool-agnostic source of truth (previously a symlink to `CLAUDE.md`, now a thin
+  vendor adapter), with `.agents/project/` documenting architecture, conventions,
+  tech stack, glossary, the gate matrix, PR quality, and the Definition of Done
+  (moved from `.agents/DEFINITION_OF_DONE.md`). Adds `.agents/decisions/` ADRs, a
+  root `TODO.md`, and a `.claude/` PreToolUse hook that blocks `--no-verify`.
+
+### Docs
+
+- **README catches up with the shipped gates.** A new _What a green certifies_
+  section surfaces the coverage, determinism, and inventory verdicts (3.9–3.14)
+  that previously lived only in the CLI reference bullet, linking
+  `docs/what-it-catches.md` and `docs/inventory-guard.md`; `styleproof-capture`
+  joins the CLI reference (with `--until-covered`); the policy table gains
+  `gateInventoryRemovals`; and the layout-equivalent-margin wording reflects the
+  one-sided-imbalance fix below. The repo's Claude Code skills
+  (`.claude/skills/styleproof*`) are fact-checked against the current CLI/API
+  surface: dead cross-references removed; the gate-contract exit codes, crawl
+  `expected` guard, browser-build compatibility key, and ledger verdicts added.
+
+### Fixed
+
+- **A two-directory `styleproof-diff`/`styleproof-report` no longer skips the
+  same-environment guard in silence.** The guard (`assertCompatibleMapDirs`) compares
+  platform/arch/node/Playwright/browser-build across both maps, but no-ops when either
+  side carries no `styleproof-manifest.json` — so a committed-map workflow that ships
+  maps but no manifest (exactly the flow most likely to compare captures across
+  machines) got zero protection with nothing said. Both CLIs now print a one-line
+  notice to stderr naming the bare side(s) — `before`, `after`, or `both` — pointing
+  at `styleproof-map` to record a manifest, then compare anyway. It is a notice, not a
+  failure: **exit codes are byte-identical** (plenty of legitimate manifest-less flows
+  exist, e.g. `styleproof-capture` one-shots), and a pair where both sides carry a
+  manifest behaves exactly as before, silently. `--json` is unchanged.
+
+## [3.21.0] - 2026-07-07
+
+### Added
+
+- **Shared-chrome tier in the report and the `styleproof-diff` CLI.** When one
+  change rides the frame every view draws — a persistent nav rail, header, or
+  footer that moved on every surface that renders it — it is promoted to a single
+  "🧱 Global chrome change" callout at the top, with the detail folded beneath,
+  instead of repeating across a long surface list on several entries. The reviewer
+  reads "the nav changed everywhere" once. The threshold is **structural, not a
+  tunable knob**: an element path is chrome only when it is hosted on more than one
+  surface base and changed on _every_ base that hosts it (full coverage of its
+  hosting surfaces). A change on merely some surfaces, or a view's own content
+  change entangled with the frame change, is never promoted — the view-specific
+  detail always stays visible. Purely presentational: grouping keys, findings,
+  counts, exit codes, and `--json` are unchanged.
+
+### Changed
+
+- **`styleproof-diff` human output now reuses the report's grouping.** One real
+  change no longer prints once per surface with its derived-longhand echo: the CLI
+  groups surfaces that changed identically into one finding (with the per-surface
+  count on the header line), summarises longhands into shorthands, and folds the
+  size/position-derived longhands (`transform-origin`, `width`/`height`, cascaded
+  ancestor heights…) behind a `(+N derived longhands)` count. A one-view button
+  restyle at one width that used to fill dozens of raw lines now reads as a single
+  grouped finding. `--json` stays the complete, byte-stable machine contract (every
+  surface, every raw longhand); exit codes are unchanged.
+
+### Fixed
+
+- **The report's certification block no longer contradicts the diff on inventory
+  additions.** For the same capture pair, `styleproof-diff` correctly prints a
+  navigable addition (additive, non-gating), but `styleproof-report`'s certification
+  block still read `Inventory — ✓ navigable set unchanged` — telling a reviewer the
+  navigable set didn't change when it did. The inventory line now echoes additions as
+  an informational, still-✓-class clause (`✓ N navigable affordance(s) added: <keys>
+(additions don't gate)`), with the same truncation and key-escaping discipline as
+  the removals line. Removals still drive the ⚠/✗ gate semantics; additions are
+  appended. The diff and the report can no longer disagree about the navigable delta.
+- **The unit suite no longer flakes on spawned-CLI tests (test-infra only, no
+  consumer-visible change).** The package-smoke test packed the live checkout with
+  `npm pack`, which runs the `prepare` lifecycle (`tsc`) even under `--ignore-scripts`.
+  `tsc` truncates each `dist/*.js` to zero bytes before rewriting it, so a CLI spawned
+  by a _different_ test running concurrently under `node --test` could read a
+  half-written `dist` module and die with a static ESM link error
+  (`does not provide an export named …`) — surfacing as an "impossible" exit code (a
+  flag-rejection test that pins exit `2` seeing exit `1`, or a spawned bin printing a
+  missing-export `SyntaxError`). The smoke test now packs a staged copy of the package
+  whose manifest carries no lifecycle scripts, so pack can never rebuild — the shared
+  `dist` is never mutated mid-suite. Same coverage (the packed tarball is still
+  installed and its API + every bin's `--help` exercised); the packed artifact is
+  identical.
+
 ## [3.20.0] - 2026-07-07
 
 ### Fixed