Detecting design drift between two repos with a hash
Two sites share a design system by copying two files. Nothing enforced that, so a check hashes both against the original and fails when they diverge. It also reports when it cannot see the original, which is the part most checks get wrong.
The documentation moved into its own repository and its own deployment. It should look identical to
the product it documents, and the way it achieves that is by containing copies of two files. Nothing
made those copies stay in step, so a check does.
Two sites, two repositories, one visual identity. The shared surface is small: a Tailwind config
carrying the colour, spacing and type scales, and a stylesheet carrying the token definitions and
base layer. Everything else differs.
The correct answer is to publish those as a versioned package and depend on it from both. That is
also a package to build, version, release and consume, for two files and one consumer, before
anyone knows how often they will actually change. Doing it too early is its own cost.
So they are copies, which is a decision with a known failure mode. Somebody adjusts a colour ramp
on the product, ships it, and the documentation quietly stops matching. Nobody notices, because
nobody has both sites open beside each other, and the drift accumulates in small steps that each
look fine alone.
The gap between "we should share this properly" and "we have shared it properly" is where the
project actually lives. The question is what to do during it.
At build time, hash both local files, fetch their counterparts from the other repository's default
branch, hash those, and compare:
javascript
const digest = text =>
createHash('sha256').update(text.replace(/\r\n/g, '\n').trimEnd()).digest('hex');
Line endings are normalised and trailing whitespace trimmed before hashing, so a checkout on a
different platform is not reported as a design change.
A hash rather than a diff, for one reason: the answer required is binary. Either these files are
the same or they are not, and if they are not, a human has to decide which version is correct,
which is not a decision a build step can make. Computing a diff would mean rendering it in CI
output nobody reads, and inviting an argument about which hunks are acceptable drift. There is no
acceptable drift. They match or the build fails.
The failure message tries to be useful rather than merely correct:
text
[design] tailwind.config.js DIFFERS from eight-west/fred
Either copy the upstream version over, or land the same change in both
repositories. To see what differs:
curl -s https://raw.githubusercontent.com/.../tailwind.config.js | diff tailwind.config.js -
It names both remedies, and hands over the command that produces the diff it deliberately did not
compute. A failing check that leaves you to work out what to do next has done half its job.
The product repository is private. An unauthenticated fetch of its raw files returns 404, so
without a token the check cannot see anything to compare against.
The naive handling is to treat unreachable as fine and pass. The check then reports success on
every build, forever, having verified nothing, and the first person to see green concludes the
design is in sync.
Instead, when every file is unreachable it warns and says exactly that:
text
[design] could not reach any upstream file
This check is INERT until eight-west/fred is reachable
Passing here proves nothing about whether the design has drifted.
That last line is the whole point. A check has three outcomes rather than two: it passed, it
failed, or it did not run. Collapsing the third into the first is how a suite accumulates checks
that everyone trusts and none of which are doing anything. It is worth writing that sentence into
the output, where somebody reads it, rather than into a comment nobody opens.
The distinction generalises past design tokens. Any check that depends on a resource it might not
reach, an external API, a service that might be down, a credential that might be absent, has this
third state, and the default handling of it is usually silence.
It detects, it does not fix. The script's own header comment says so: the real fix is publishing
the tokens as a package, worth doing once the two get edited often enough that this check starts
firing. The check is explicitly a placeholder that reports when its own replacement has become
worth building.
It compares against a moving target. The upstream fetch is the default branch, so an
unmerged change to the tokens does not exist yet and a merged one is immediately authoritative.
A docs build can start passing or failing because of a commit in another repository, with nothing
in this one having changed.
Two files is a guess. The shared surface was decided by inspection, not derivation. A third
file that matters and is not on the list drifts unobserved, and nothing would reveal that.
It is inert today. The token was never set, so it has warned on every build since it was
written and compared nothing. Being loud about that is the difference between a known gap and a
false sense of coverage, but it is still a gap, and the fix is one repository secret.
Byte equality is stricter than visual equality. A reordered key or a reformatted comment fails
the check without changing a single rendered pixel. That is the right trade for two rarely-edited
files, since the alternative is parsing and comparing semantically, which is a much larger thing to
maintain. It does mean the check will occasionally cry wolf, and a check that cries wolf gets
disabled.
A shared token is not a shared component. Identical configs mean the two sites can express the
same design. They do not mean they do. Every component in the documentation is a separate
implementation, and nothing compares those at all.
Standard RAG retrieves passages. Some questions need numbers that do not exist until you compute them. CS-RAG retrieves from three model surfaces over 11.9M spatial records, then computes before the model writes anything.
Asking "where in Northern California" means aggregating millions of spatial records with no filter to narrow them. Pre-aggregating into three hexagon resolutions turns that into three lookups under 2 ms each, and the coarse answer constrains the fine one.
A seven-step geometric binary search search sizes a spatial radius query in 1 to 3 seconds, against 8 to 25 seconds for running the pipeline to find out.