Liking cljdoc? Tell your friends :D

The Mantine anchor is single-sourced from the package.json pins

The wrapped Mantine version, the Mantine anchor (see GLOSSARY.md), appears as a literal in at least six machine-consumed places: the exact @mantine/* pins in package.json, the ^-prefixed consumer ranges in src/main/deps.cljs, the mantine-version def in codegen/plan.clj (which flows into every generated banner and docstring), the 9.4.1.N prefix of build.clj's version, and the hardcoded (Mantine 9.4.1) banners in codegen/extract.clj. Nothing enforced their agreement, so a Mantine bump meant synchronizing each by hand, and a half-applied bump drifted silently: the generated banner could claim a version the enumerated surface didn't match.

Decision. Treat the exact @mantine/* pins in package.json as the one canonical anchor. read-sources already slurps package.json, and the pins are what npm installs, so no competing source of truth is introduced. Every other appearance is a rendering of the anchor and is either derived or validated:

  • Derive the codegen/plan.clj generator constant: delete the def and read the agreed pin. It is codegen-internal and already in the pipeline.
  • Validate deps.cljs ranges and build.clj's version prefix. These are hand-authored, shipped artifacts (and build.clj's string is the sole home of the wrapper revision N). A bb release-check task reads them as data and asserts agreement; they are never regenerated.
  • extract stamps its banners from the anchor (not a second hardcoded literal), asserts the <clone-dir> version equals the anchor, and writes a machine-readable provenance witness, codegen/input/mantine-version.edn: the version the committed inputs were captured at. The witness is authoritative about provenance, not a second anchor; it is validated against the real anchor.

Three reality-checks guard the layers the anchor is a declaration about:

  • generate: the installed versions in node_modules/@mantine/* must equal the anchor (checked where the surface is enumerated, catching a stray local npm install).
  • extract: the fed clone must equal the anchor (catching "extracted the wrong clone / forgot to bump package.json").
  • release-check: the committed provenance witness must equal the anchor. extract writes the witness only when clone == anchor, and a bump moves the anchor while a skipped re-extract leaves the witness stale. This check therefore fires exactly on "bumped the anchor but forgot bb extract", the one bump-time slip the other checks miss (the committed docgen.json carries no version of its own to read).

The release-identity logic lives entirely on the codegen/bb classpath. build.clj (under the deps.edn :build alias, which cannot see codegen/) is a read target, never a consumer. There is no bridge into the deploy build and no release logic in the shipped src/main jar. bb release-check runs the standalone checks and is wired into bb ci.

This preserves ADR 0001: the artifact stays source-only and Mantine-anchored as 9.4.1.N. Only the mechanics of keeping the anchor consistent change.

Considered options

  • A dedicated release.edn as the anchor: rejected. It would compete with the pins npm already enforces; package.json is both already read and operationally true.
  • Derive everything (regenerate deps.cljs and build.clj from the anchor): rejected. It turns two hand-curated, shipped files into opaque generated output for no safety the validation doesn't already give.
  • Bridge the module into build.clj (add codegen to the :build alias): rejected. Validation reads the literal fine; a bridge couples the deploy build to the codegen tree for zero gain.

Out of scope

The provenance witness proves the committed inputs were extracted at the anchor version; it does not prove docgen.json was not hand-edited afterward. Content integrity would need a fingerprint (hash at extract, assert at check). That is not worth it, since hand-editing 1.5 MB of generated JSON is not a realistic failure mode.

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close