fix(design-system): let the visual baseline binding accept a refresh, not only the first adoption

[BigSimmo]

Summary

• validateCandidateSourceBinding required candidateSourceHead to name a commit whose AWAITING_BASELINE still declared the canonical six, and the current tree to declare none. That models the first adoption and nothing else. After test(visual): adopt the six linux visual baselines and satisfy their provenance contract #1729 landed, no commit on main declares the six again, so no future capture head can satisfy it — the binding was satisfiable exactly once, and that once has passed.
• The binding now accepts either shape: first adoption (candidate declares six, current declares none) or refresh (both ends empty, suite byte-identical).

Stated plainly: the consequence is latent today, not live. validateLinuxVisualBaselineSet short-circuits on declaredPaths.length === 0 and no surface declares baseline.status: "committed", so the contract is dormant and refreshing a golden is currently ungated. This is insurance, not a rescue. The defect bites the moment those surfaces are declared (#242) — at which point the first intentional design change would leave the goldens red with no supported way to re-adopt them, which is precisely backwards for a gate meant to make design changes provable.

A refresh is the ordinary case once baselines exist: a surface is deliberately re-shot and its goldens replaced while the suite itself does not change. Normalisation already blanks the AWAITING_BASELINE values on both sides, so the "suite changed beyond the AWAITING declaration" check stays exact for both shapes.

Nothing is loosened beyond that. A candidate head with five ids, seven ids, a dynamic set, a spread or a duplicate still fails, as do a non-empty current list, a non-ancestor head, a SHA-256 mismatch, a wrong platform and an unreviewed set. The one previously-untested shape — a refresh — now has its own case, which is why the gap was invisible: nothing exercised it.

Verification

• tests/design-system-adoption.test.ts — Tests 51 passed (51), including the new refresh case.
• npm run check:design-system-adoption — exit 0, design-system adoption checked: 53 components, 55 roots.
• npm run check:design-system-contract — exit 0.
• npm run format:check — All matched files use Prettier code style!

Risk and rollout

• Risk: Low, and currently inert — the validator it changes is dormant while zero surfaces declare baseline files.
• Rollback: git revert.
• Provider or production effects: None.

Refs #242, #118.

Summary by CodeRabbit

• Bug Fixes

  • Improved visual baseline adoption validation to support both initial adoption and unchanged baseline refreshes.
  • Refreshes now remain valid when no pending baseline items are present.
  • Updated validation feedback for invalid baseline states.

• Tests

  • Expanded coverage for initial adoption, refreshes, and invalid-state scenarios.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 68d182d2-5b3c-413c-9c95-145859207340

📥 Commits

Reviewing files that changed from the base of the PR and between fc399e2 and 6e71d69.

📒 Files selected for processing (2)

• scripts/generate-design-system-adoption.mjs
• tests/design-system-adoption.test.ts

---

📝 Walkthrough

Walkthrough

The visual baseline adoption script now accepts canonical six-ID states for first adoption and empty states for refreshes. Tests cover empty-to-empty refreshes and updated invalid-state messages.

Changes

Visual baseline adoption

Layer / File(s)	Summary
Candidate baseline state validation scripts/generate-design-system-adoption.mjs	Validation accepts canonical or empty AWAITING_BASELINE sets. Suite comparison normalizes both states.
First adoption and refresh coverage tests/design-system-adoption.test.ts	Tests cover first adoption, empty-to-empty refreshes, and invalid candidate states.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: allowing visual baseline binding during refreshes.
Description check	✅ Passed	The description covers the change, verification results, risk, rollback, and production effects; the relevant template sections are substantially complete.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/ds-baseline-refresh-binding

---

_{Comment @coderabbitai help to get the list of available commands.}