Liking cljdoc? Tell your friends :D

hive-build.promote.api-surface

A namespace's PUBLIC surface as data, and the difference between two of them.

Pure: takes already-read top-level forms, returns values.

Surface shape: {"ns/name" {:kind :def|:defn|:defmacro|:defprotocol|:defrecord :arities #{0 1 :variadic} :methods {"method" #{1 2}}}}

What counts as public: anything a downstream repo can compile against — defn/def/defmacro without ^:private (and not defn-), plus every protocol and its method arities. Private vars are excluded on purpose: they are not part of the contract and freezing them would freeze refactoring.

A namespace's PUBLIC surface as data, and the difference between two of them.

Pure: takes already-read top-level forms, returns values.

Surface shape:
  {"ns/name" {:kind :def|:defn|:defmacro|:defprotocol|:defrecord
               :arities #{0 1 :variadic}
               :methods {"method" #{1 2}}}}

What counts as public: anything a downstream repo can compile against —
`defn`/`def`/`defmacro` without ^:private (and not `defn-`), plus every
protocol and its method arities. Private vars are excluded on purpose: they
are not part of the contract and freezing them would freeze refactoring.
raw docstring

hive-build.promote.classes

Compiled classes as values: which classes a .class file links against, and which of those links the jar does not satisfy. Pure.

An AOT jar that hardcodes implements hive_addon.protocol.IAddon builds and publishes in silence, then fails to mount because the host loaded that protocol from source under a different class identity. The link is visible in the constant pool long before anyone tries to mount it.

Compiled classes as values: which classes a .class file links against, and
which of those links the jar does not satisfy. Pure.

An AOT jar that hardcodes `implements hive_addon.protocol.IAddon` builds and
publishes in silence, then fails to mount because the host loaded that
protocol from source under a different class identity. The link is visible
in the constant pool long before anyone tries to mount it.
raw docstring

hive-build.promote.elide

Source-level metadata elision, applied to a staged copy of the sources before AOT. Pure: text in, text out.

The compiler's :elide-meta reaches def metadata only. An ns form's docstring is part of a constant map the ns macro emits, so it survives into the generated __init class verbatim.

Source-level metadata elision, applied to a staged copy of the sources
before AOT. Pure: text in, text out.

The compiler's :elide-meta reaches `def` metadata only. An `ns` form's
docstring is part of a constant map the ns macro emits, so it survives into
the generated __init class verbatim.
raw docstring

hive-build.promote.freeze

The freeze policy, evaluated. Pure.

A contract library's whole value is that consumers can pin it and forget it. Two things destroy that: a change they cannot survive, and a cadence that makes them re-pin constantly. This namespace decides both from data.

Policy shape (./freeze-policy.edn in the repo being released):

{:policy/version 1 :cadence {:mode :scheduled | :on-merge :min-days-between-releases 90 :exception-marker "release-exception:"} :compatibility {:additive-only? true :break-marker "BREAKING-CHANGE:"}}

Contract: evaluate never throws and never consults the world — every observation (the diff, the age, the commit message) is passed in.

The freeze policy, evaluated. Pure.

A contract library's whole value is that consumers can pin it and forget it.
Two things destroy that: a change they cannot survive, and a cadence that
makes them re-pin constantly. This namespace decides both from data.

Policy shape (./freeze-policy.edn in the repo being released):

  {:policy/version 1
   :cadence {:mode :scheduled | :on-merge
             :min-days-between-releases 90
             :exception-marker "release-exception:"}
   :compatibility {:additive-only? true
                   :break-marker "BREAKING-CHANGE:"}}

Contract: `evaluate` never throws and never consults the world — every
observation (the diff, the age, the commit message) is passed in.
raw docstring

hive-build.promote.license

Licence agreement between ./LICENSE, version.edn :license and the SPDX headers in the source tree, as an open rule chain. Pure.

A rule returns nil when satisfied, else a message. Unlike an access decision, every rule runs: a licence report that stopped at the first problem would hide the rest, and a published pom can never be retracted.

Licence agreement between ./LICENSE, version.edn :license and the SPDX
headers in the source tree, as an open rule chain. Pure.

A rule returns nil when satisfied, else a message. Unlike an access
decision, every rule runs: a licence report that stopped at the first
problem would hide the rest, and a published pom can never be retracted.
raw docstring

hive-build.promote.lint

clj-kondo invocations as values. Pure.

Constructing the argument vector is where a lint task silently stops failing, so it is stated here and asserted rather than inlined at the process call.

clj-kondo invocations as values. Pure.

Constructing the argument vector is where a lint task silently stops
failing, so it is stated here and asserted rather than inlined at the
process call.
raw docstring

hive-build.promote.manifest

Addon manifests as values. Pure.

A hive addon ships resources/META-INF/hive-addons/<id>.edn describing itself. The version in that file is the one an addon store reads, so it is derived from the coordinate being built rather than hand-maintained.

Addon manifests as values. Pure.

A hive addon ships resources/META-INF/hive-addons/<id>.edn describing
itself. The version in that file is the one an addon store reads, so it is
derived from the coordinate being built rather than hand-maintained.
raw docstring

hive-build.promote.naming

Names derived from a coordinate: the Maven symbol, artifact paths, the registry URL a publish check probes, and the namespace/path correspondence AOT compilation depends on. Pure.

Names derived from a coordinate: the Maven symbol, artifact paths, the
registry URL a publish check probes, and the namespace/path correspondence
AOT compilation depends on. Pure.
raw docstring

hive-build.promote.opacity

Does the built artifact still carry the vendor's words? Pure: the strings the sources declare secret go in, the strings the artifact carries go in, and the ones present in both come out.

An AOT jar is audited today for what it LINKS against (promote/classes). Nothing audited what it SAYS. :elide-meta removes def metadata and the staging pass removes the ns docstring, but neither is observed after the fact, so an elision that silently stops running publishes a readable jar and reports success.

The check is set intersection rather than a heuristic on purpose. A detector that scored strings for prose would have to guess whether "Resolve user-facing cartography intent into stable indexed-world data." is a leaked docstring or a :summary the program prints, and it is the second one. Only the source knows which strings were meant to be private, so the source is what supplies them.

Does the built artifact still carry the vendor's words? Pure: the strings the
sources declare secret go in, the strings the artifact carries go in, and the
ones present in both come out.

An AOT jar is audited today for what it LINKS against (`promote/classes`).
Nothing audited what it SAYS. `:elide-meta` removes `def` metadata and the
staging pass removes the ns docstring, but neither is observed after the
fact, so an elision that silently stops running publishes a readable jar and
reports success.

The check is set intersection rather than a heuristic on purpose. A detector
that scored strings for prose would have to guess whether
"Resolve user-facing cartography intent into stable indexed-world data." is
a leaked docstring or a `:summary` the program prints, and it is the second
one. Only the source knows which strings were meant to be private, so the
source is what supplies them.
raw docstring

hive-build.promote.pom

The parts of a pom hive-build decides rather than delegates: the declared licence, the dependency set, the source roots, the SCM tag and the repository set. Pure.

The parts of a pom hive-build decides rather than delegates: the declared
licence, the dependency set, the source roots, the SCM tag and the
repository set. Pure.
raw docstring

hive-build.promote.project

The Project value object: raw version.edn data plus a resolved version, with every default applied. Pure.

Nothing downstream reads version.edn again, so a default lives here exactly once.

The Project value object: raw version.edn data plus a resolved version, with
every default applied. Pure.

Nothing downstream reads version.edn again, so a default lives here exactly
once.
raw docstring

hive-build.promote.publish

Publish destinations as data, behind a registry. Pure.

The registry is the dependency-inversion point: plan and the boundary depend on the Target schema, never on a particular registry. A new destination is a register! and no edit anywhere else.

Publish destinations as data, behind a registry. Pure.

The registry is the dependency-inversion point: `plan` and the boundary
depend on the Target schema, never on a particular registry. A new
destination is a `register!` and no edit anywhere else.
raw docstring

hive-build.promote.reproducible

What must be rewritten INSIDE a jar for two builds of identical inputs to be byte-identical. Pure.

Fixing ZIP entry timestamps is not enough: build tooling also writes wall clock time and host details into entry content, where a timestamp rewrite cannot reach them. Each such source is a rule, so a newly discovered one is an addition rather than an edit.

What must be rewritten INSIDE a jar for two builds of identical inputs to be
byte-identical. Pure.

Fixing ZIP entry timestamps is not enough: build tooling also writes wall
clock time and host details into entry content, where a timestamp rewrite
cannot reach them. Each such source is a rule, so a newly discovered one is
an addition rather than an edit.
raw docstring

hive-build.promote.version

Semantic versions as values: parse, render, order, bump. Pure.

Semantic versions as values: parse, render, order, bump. Pure.
raw docstring

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