docs: rebuild the social preview from the package, and fail CI when it drifts - #77
Merged
Conversation
…t drifts
chock's social preview was a static image. It is now derived: the agent list
comes from config.SURFACE_AGENTS, the surfaces from the Surface enum, the
commands from cli.EVERYDAY, and the version, dependency count and Python range
from pyproject.toml. Every count printed beside a list is len() of that list.
Nothing on the card is hand-typed, so nothing on it can be typed wrong.
It can still be stale, which is the real risk: add an agent, skip the
regenerate, and the committed image quietly claims the old number. The image is
what a link preview shows to someone who has not read the repo yet, so being
quietly wrong there is worse than in prose nobody has opened. So the card is now
held to the same drift discipline as the other compiled artifacts -- a
`--check` mode plus a CI job that re-derives it and fails with what moved:
social-preview.svg is out of date
now present: 15, some-new-agent
no longer: 14
Regenerate it: python docs/assets/gen_brand_assets.py
The comparison is on the SVG, never the PNG. The SVG is text produced only from
repository data, so it is byte-identical on any machine; a PNG additionally
depends on the font installed on the renderer, which CI does not have. Facts
reach the SVG first, so checking it catches everything that matters without
making CI's font a dependency of the build passing.
Two guards live in the renderer itself, because both caught real defects while
this was being built: a row longer than its panel raises rather than running
silently into the next column, and the left column asserts it clears the footer
rule.
The hand-drawn wheel-and-wedge logo is untouched; the header reuses its shape
without the spokes, which turn to mud at 38px.
Signed-off-by: Claude <noreply@anthropic.com>
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (4)
📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe CI workflow adds a Linux-based ChangesBrand asset validation
Estimated code review effort: 2 (Simple) | ~10 minutes ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
test_repo_standards.py::test_no_file_exceeds_line_budget failed on the previous commit: docs/assets/gen_brand_assets.py was 333 lines against a 300-line budget whose stated remedy is "split by activity". The other 851 tests passed. Split exactly as the rule asks, along the seam that was already there: - brandkit.py (225 lines) is the drawing language -- palette, text, panels, the card layout, the write/check pair. It knows nothing about chock; it takes lists and labels and returns SVG. - gen_brand_assets.py (124 lines) is what this repository has to say: the mark, the facts read from SURFACE_AGENTS, the Surface enum, cli.EVERYDAY and pyproject.toml, and the card built from them. Two activities, two files, both well inside the budget. The rule was worth following rather than exempting the file from: the halves genuinely belong apart, and the drawing half is the part a sibling repo can be read against. Verified: test_repo_standards.py passes, ruff check and format clean across the repo, and `gen_brand_assets.py --check` still reports the committed card current -- the split changed no output, only where the code lives. Signed-off-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
chock's social preview was a static image. It is now derived, and checked in CI.
The card shows real content in three columns — the 14 agents by name, the 8 enforcement
surfaces, the 8 everyday commands — plus the everyday loop as real commands and a footer of
counts. Every one of those facts is read at render time:
chock.config.SURFACE_AGENTSSurfaceenum (andINSTALLED_SURFACESfor the alt text)chock.cli.EVERYDAYpyproject.tomlEach count printed beside a list is
len()of that list. Nothing on the card is hand-typed, sonothing on it can be typed wrong.
The problem this actually solves
Derivation stops the card being wrong. It does not stop it being stale: add an agent, skip
the regenerate, and the committed PNG quietly claims the old number. The image is what a link
preview shows to someone who has not read the repo yet, so being quietly wrong there is worse
than in prose nobody has opened.
So the card is held to the same drift discipline as the other compiled artifacts.
--checkre-derives it, compares, and fails naming what moved:
The comparison is on the SVG, never the PNG. The SVG is text produced only from repository
data, so it is byte-identical on any machine; a PNG additionally depends on the font installed on
the renderer, which CI does not have. Any drift in the facts reaches the SVG first, so checking
the SVG catches everything that matters without making CI's font a dependency of the build
passing.
This also removes the need to remember anything at release time.
mainis correct continuously,so a release just picks up a card that is already right.
Definition of done
ruff check .→ All checks passed;ruff format --check .→ cleanchock sync --check,chock check --only verify, the registry scan and the acceptance suite have nothing to re-verify — no manifest,pack, lockfile, compiled artifact or matrix input is touched
pytest -qnot re-run: nothing undersrc/ortests/is touchedVerified directly:
python gen_brand_assets.pythen--check→ "social-preview.svg is current"brand-assetsCI job pinsactions/checkoutandactions/setup-pythonto the sameSHAs the rest of this workflow uses, and pins
cairosvg==2.9.0— the repo's ownpin-github-actionsdiscipline applies to the job that checks the artwork tooClaims
name from the
Surfaceenum without grading them, and the alt text distinguishes all 8surfaces from the 3 that
chock syncinstalls.INSTALLED_SURFACES, the coverage tableand
docs/enforcement-surfaces.mdare untouched.Two guards live in the renderer itself, because both caught real defects while this was being
built:
cairosvgis asset tooling a maintainer runs by hand; it is not a dependency anddependenciesinpyproject.tomlis unchanged.Notes for the reviewer
upload
docs/assets/social-preview.pngunder Settings → General → Social preview. The CIcheck is also the signal for when a re-upload is due.
logo.svgis untouched. The card's header reuses its shapewithout the spokes, which turn to mud at 38px.
Generated by Claude Code
Summary by CodeRabbit
Tests
Chores