hive-build.api — io.github.hive-agi/hive-build 0.1.14

The canonical hive release tasks, delivered as a library.

Point a repository's :build alias here and it inherits the whole release path — no build.clj to copy, and no build.clj to drift:

:build {:deps {io.github.hive-agi/hive-build {:mvn/version "0.1.0"}} :ns-default hive-build.api}

Coordinates come from ./version.edn, the version from ./VERSION:

{:lib io.github.hive-agi/hive-thing :minor 1 :license {:name "MIT" :url "https://opensource.org/licenses/MIT"} :scm-url "https://github.com/hive-agi/hive-thing" :src-dirs ["src"] :publish :clojars ; :clojars | :gitea | :gitea-source | :none :aot/java-opts [] ; optional, AOT compile only :aot/elide-meta [] ; optional, [] disables metadata elision :aot/publishable-sources [] ; optional, entry prefixes whose sources ship :aot/strict-opacity false ; optional, overrides the target's default: ; a PRIVATE target (:gitea) fails a leak, ; a public one only reports it :jar-excludes [] ; optional, entry paths (file or directory) ; pruned before the jar is written and ; refused if the jar still carries them :pom-exclude-deps []} ; optional, dropped from the published pom

An untracked ./local.deps.edn may supply a :provided alias (host sources that must be on the AOT compile classpath but must NOT enter the pom) and an :aot/preload namespace vector compiled ahead of this lib's own namespaces.

:publish is the ONLY thing that differs between packages — the task names are identical everywhere, so one CI workflow drives the whole fleet:

:clojars public source jar -> repo.clojars.org :gitea AOT no-source jar -> private Gitea Maven registry :gitea-source source jar -> private Gitea Maven registry :none builds, never ships

Tasks (invoke with clojure -T:build <task>): clean delete target/ jar source jar + pom jar-aot AOT no-source jar (own .class + resources only) install build + install to ~/.m2 (offline) kondo sync dependency-exported lint configs, then lint bump rewrite ./VERSION (:level :patch|:minor|:major) verify-license report LICENSE / version.edn / SPDX agreement (warns) audit-opacity report private strings a built jar still carries (warns) freeze-check refuse a release that breaks ./freeze-policy.edn (fails) readme-examples run README.md's clojure blocks in a new JVM (fails) changelog regenerate ./CHANGELOG.md from the release tags deploy build + publish per :publish (no-op when :none)

Release flow (what CI runs on a push to main that touches src/deps): clojure -T:build bump :level :patch clojure -T:build deploy

audit-opacity clj

(audit-opacity {:keys [jar strict]})

Report which strings this repository's sources declared private that the built jar still carries.

Reads an artifact that already exists: run jar-aot first, or pass :jar to audit any jar on disk. The audit is the same one jar-aot runs, so a jar built before the elision pass existed can be measured without rebuilding it.

:jar path to the jar (default: the coordinate under target/) :strict true to throw on a leak (default: report and return)

A clean verdict says the audited strings are absent. It says nothing about the call graph, the numeric constants, or any name.

bump clj

(bump {:keys [level] :or {level :patch}})

Rewrite ./VERSION to the next semantic version and print it.

:level :patch (default) | :minor | :major VERSION is the single source of truth for both the git tag (v{VERSION}) and the Maven coordinate. Does not commit, tag, or deploy.

changelog clj

(changelog {:keys [depth out fragments pending]
            :or {out "CHANGELOG.md" fragments "changelog.d"}})

Regenerate ./CHANGELOG.md from the commits between release tags.

:depth releases rendered in full (default 25; older ones are named in the footer, not dropped) :out output path (default CHANGELOG.md) :fragments directory of authored prose (default changelog.d), where <version>.md is spliced under that release's heading and preamble.md replaces the generated header :pending version being cut but not yet tagged; defaults to ./VERSION when no tag names it yet, so a release regenerates the file BEFORE tagging and still describes itself. Pass an empty string to suppress it.

The file is a projection of git, so it is rewritten in full every time and nothing authored in it survives. Returns the counts it wrote.

clean clj

(clean _)

Delete target/.

deploy clj

(deploy opts)

Build + publish according to version.edn :publish.

A coordinate already present in the registry is a no-op, not an error: both registries are immutable, so releasing again means bumping VERSION.

freeze-check clj

(freeze-check _)

Refuse a release that breaks the repository's freeze policy.

Reads ./freeze-policy.edn (absent = nothing enforced), compares the public API surface on disk against the surface at the last v* tag, and checks the age of that tag. Prints the verdict; THROWS on a violation so the release workflow stops before bump mints a version that can never be retracted.

Escape hatches are per-commit and must be written down: the cadence marker and the break marker named by the policy, in the HEAD commit message.

Returns the verdict map on success.

install clj

(install _)

Build + install to the local ~/.m2 repository (offline).

jar clj

(jar _)

Build the source jar (pom + copied sources) under target/.

jar-aot clj

(jar-aot _)

Build the AOT no-source jar: this lib's own .class files + resources only.

kondo clj

(kondo {:keys [aliases paths fail-level]
        :or {aliases [:test] fail-level :error}})

Sync clj-kondo configs exported by dependencies, then lint.

Any deps.edn or bb.edn dependency shipping resources/clj-kondo.exports/<group>/<artifact>/ has its config + hooks copied into ./.clj-kondo/imports/, which clj-kondo loads automatically. Macro awareness therefore arrives with the dependency instead of being re-authored per repo.

:aliases deps aliases whose classpath is scanned (default [:test]) :paths lint targets (default src + test) :fail-level :error (default) | :warning | nil to report only

readme-examples clj

(readme-examples
  {:keys [readme aliases out]
   :or {readme "README.md" aliases [] out "target/readme-examples.clj"}})

Run every fenced clojure block of ./README.md in a new JVM, as the gate it is.

A code block claims that its example runs against this library, and a ;; => value line after a form claims what that form answers. The blocks are rendered into one program under target/ and run with clojure -M in a NEW process on the project's own classpath, so nothing passes because the session that wrote the README happened to have it loaded. Add no-run to a fence's info string (```clojure no-run) to keep a block out.

:readme markdown path (default README.md) :aliases deps aliases for the run (default [], the project's own :deps) :out generated program path (default target/readme-examples.clj)

Prints the program's own output; THROWS when it exits non-zero, so a release workflow stops on a README that lies. Returns the counts on success. A README with no runnable block returns counts of zero and does not throw: nothing was claimed, so nothing was refuted.

verify-license clj

(verify-license _)

Report whether ./LICENSE, version.edn :license and the src SPDX headers agree. Advisory: prints and returns the report, never fails the build.