+
# cubit
-Continuous benchmarking and performance-regression tracking — runs benchmarks, records baselines in a git branch, renders trend dashboards, and posts non-blocking baseline-vs-PR comparisons.
+
+Continuous benchmarking and performance-regression tracking.
+
+`cubit` runs your benchmarks, records baselines in a git branch, and reports how
+a change moves performance — locally for a developer, or as a **non-blocking PR
+comment** in CI. It is a *light gate*: the numbers and the trend dashboard inform
+a human go/no-go, nothing hard-fails.
+
+Sibling to [bulwark](https://github.com/wardnet/bulwark) (code-quality scanning),
+built for the [wardnet](https://github.com/wardnet) daemon's benchmarks.
+
+## How it works
+
+1. Your CI runs the benchmarks (today: Rust [criterion](https://github.com/bheisler/criterion.rs)).
+2. `cubit compare` ingests the output, diffs it against the baseline recorded on
+ the `cubit-state` branch, and posts a Markdown table (baseline vs current, Δ%)
+ plus a link to a trend dashboard.
+3. On the default branch, `cubit record` updates the baseline — keyed by commit
+ SHA — for the next PR to compare against.
+
+Baselines and history live in an orphan git branch (no database, no hosted
+service). The dashboard renders from that branch as a CI artifact and via a local
+`cubit serve`, so it works on private repos and repos whose GitHub Pages slot is
+already taken.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `cubit compare` | Ingest a run, diff against a baseline, render the report |
+| `cubit record` | Ingest a run and write it as a baseline record (SHA-keyed) |
+| `cubit update` | Self-update to the latest release |
+| `cubit version` | Print the version |
+
+## Install
+
+```sh
+curl -fsSL https://github.com/wardnet/cubit/releases/latest/download/install.sh | sh
+```
+
+`cubit update` self-updates the CLI in place.
+
+## Status
+
+Early. The ingest → compare → report spine works; baseline persistence
+(`cubit-state` branch), the release/action plumbing, and the React trend
+dashboard are in progress.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
diff --git a/action.yml b/action.yml
new file mode 100644
index 0000000..1f2f419
--- /dev/null
+++ b/action.yml
@@ -0,0 +1,170 @@
+name: cubit
+description: >
+ Run benchmarks through cubit — compare a PR against the recorded baseline and
+ post a non-blocking summary comment, or record a new baseline on the default
+ branch. Never fails the build; the comment + dashboard inform a human.
+
+inputs:
+ version:
+ description: cubit version to install (omit or "latest" for the latest release)
+ default: latest
+ criterion-dir:
+ description: criterion output directory to ingest (relative to the repo root)
+ default: target/criterion
+ bench-command:
+ description: >
+ optional shell command that produces the criterion output (e.g.
+ "cargo bench --bench dns_components"). Omit if an earlier step already ran
+ the benchmarks.
+ default: ""
+ state-branch:
+ description: orphan branch cubit stores baselines on
+ default: cubit-state
+ threshold:
+ description: flag benchmarks slower than baseline by more than this percent
+ default: "15"
+ dashboard-url:
+ description: trend-dashboard URL to link from the PR comment
+ default: ""
+ mode:
+ description: >
+ "auto" (default) compares on pull_request and records on a push to the
+ default branch. Force with "compare" or "record".
+ default: auto
+ github-token:
+ description: token used to post the PR comment and push the state branch
+ default: ${{ github.token }}
+
+runs:
+ using: composite
+ steps:
+ - name: Install cubit
+ shell: bash
+ env:
+ VERSION: ${{ inputs.version }}
+ run: |
+ # install.sh is fetched from the latest release; CUBIT_VERSION pins the
+ # binary it installs and install.sh verifies its SHA-256 before use.
+ if [[ "${VERSION}" != "latest" ]]; then
+ export CUBIT_VERSION="${VERSION}"
+ fi
+ export CUBIT_INSTALL_DIR="${RUNNER_TEMP}/cubit-bin"
+ curl -fsSL -o "${RUNNER_TEMP}/cubit-install.sh" https://github.com/wardnet/cubit/releases/latest/download/install.sh
+ sh "${RUNNER_TEMP}/cubit-install.sh"
+ echo "${CUBIT_INSTALL_DIR}" >> "$GITHUB_PATH"
+
+ - name: Run benchmarks
+ if: inputs.bench-command != ''
+ shell: bash
+ env:
+ BENCH_COMMAND: ${{ inputs.bench-command }}
+ run: |
+ eval "$BENCH_COMMAND"
+
+ - name: Fetch state branch
+ shell: bash
+ env:
+ STATE: ${{ inputs.state-branch }}
+ run: |
+ # Best-effort: the branch may not exist yet (first ever run). A present
+ # remote-tracking ref is what cubit reads baselines from, and what a
+ # record run bases its append on.
+ git fetch origin "+refs/heads/${STATE}:refs/remotes/origin/${STATE}" 2>/dev/null || true
+
+ - name: cubit
+ id: cubit
+ shell: bash
+ env:
+ MODE: ${{ inputs.mode }}
+ DIR: ${{ inputs.criterion-dir }}
+ STATE: ${{ inputs.state-branch }}
+ THRESHOLD: ${{ inputs.threshold }}
+ DASH: ${{ inputs.dashboard-url }}
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+ EVENT: ${{ github.event_name }}
+ PR_BASE: ${{ github.event.pull_request.base.ref }}
+ PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+ run: |
+ set -euo pipefail
+ report="${RUNNER_TEMP}/cubit-report.md"
+ dashboard="${RUNNER_TEMP}/cubit-dashboard.html"
+ echo "report=${report}" >> "$GITHUB_OUTPUT"
+ echo "dashboard=${dashboard}" >> "$GITHUB_OUTPUT"
+
+ # Resolve auto mode from the triggering event.
+ mode="$MODE"
+ if [[ "$mode" == "auto" ]]; then
+ if [[ "$EVENT" == "pull_request" ]]; then
+ mode="compare"
+ elif [[ "$GITHUB_REF_NAME" == "$DEFAULT_BRANCH" ]]; then
+ mode="record"
+ else
+ echo "cubit: nothing to do (push to non-default branch $GITHUB_REF_NAME)"
+ echo "did-run=false" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ fi
+ echo "did-run=true" >> "$GITHUB_OUTPUT"
+ echo "mode=${mode}" >> "$GITHUB_OUTPUT"
+
+ dash_arg=()
+ [[ -n "$DASH" ]] && dash_arg=(--dashboard-url "$DASH")
+
+ if [[ "$mode" == "compare" ]]; then
+ # latest:![\"\"](\"https://raw.githubusercontent.com/wardnet/cubit/main/assets/cubit-logo.png\"){kind=logo}
cubit — performance\n\n")
+ if cur.Commit != "" {
+ fmt.Fprintf(&b, "Commit `%s`", shortSHA(cur.Commit))
+ if cur.Branch != "" {
+ fmt.Fprintf(&b, " on `%s`", cur.Branch)
+ }
+ b.WriteString(" · ")
+ }
+ fmt.Fprintf(&b, "%d benchmarks · flagging Δ > %.0f%% slower\n\n", len(deltas), thresholdPct)
+
+ regressed := countRegressed(deltas)
+ newCount := countNew(deltas)
+ switch {
+ case regressed > 0:
+ fmt.Fprintf(&b, "⚠️ **%d benchmark(s) slower than baseline by more than %.0f%%** — review before merge.\n\n", regressed, thresholdPct)
+ default:
+ b.WriteString("✅ No benchmark exceeded the regression threshold.\n\n")
+ }
+
+ b.WriteString("| Benchmark | Baseline | Current | Δ | |\n")
+ b.WriteString("|---|--:|--:|--:|:-:|\n")
+ for _, d := range deltas {
+ b.WriteString(row(d))
+ }
+ b.WriteString("\n")
+
+ if newCount > 0 {
+ fmt.Fprintf(&b, "_%d benchmark(s) are new (no baseline to compare)._\n\n", newCount)
+ }
+ if dashboardURL != "" {
+ fmt.Fprintf(&b, "📈 [Trend dashboard](%s) — history and variance band.\n", dashboardURL)
+ }
+
+ return b.String()
+}
+
+func row(d model.Delta) string {
+ if !d.HasBase {
+ return fmt.Sprintf("| `%s` | — | %s | _new_ | 🆕 |\n", d.ID, formatNs(d.Current))
+ }
+ return fmt.Sprintf("| `%s` | %s | %s | %s | %s |\n",
+ d.ID, formatNs(d.Baseline), formatNs(d.Current), formatPct(d.PctChange), marker(d))
+}
+
+func marker(d model.Delta) string {
+ switch {
+ case d.Regressed:
+ return "⚠️"
+ case d.PctChange < -5:
+ return "🚀" // meaningfully faster
+ default:
+ return ""
+ }
+}
+
+func countRegressed(deltas []model.Delta) int {
+ n := 0
+ for _, d := range deltas {
+ if d.Regressed {
+ n++
+ }
+ }
+ return n
+}
+
+func countNew(deltas []model.Delta) int {
+ n := 0
+ for _, d := range deltas {
+ if !d.HasBase {
+ n++
+ }
+ }
+ return n
+}
+
+// formatNs renders a nanosecond value with an adaptive unit, so a table mixing
+// sub-microsecond cache lookups and millisecond pipeline runs stays readable.
+func formatNs(ns float64) string {
+ switch {
+ case ns >= 1e9:
+ return fmt.Sprintf("%.2f s", ns/1e9)
+ case ns >= 1e6:
+ return fmt.Sprintf("%.2f ms", ns/1e6)
+ case ns >= 1e3:
+ return fmt.Sprintf("%.2f µs", ns/1e3)
+ default:
+ return fmt.Sprintf("%.1f ns", ns)
+ }
+}
+
+func formatPct(p float64) string {
+ sign := "+"
+ if p < 0 {
+ sign = ""
+ }
+ return fmt.Sprintf("%s%.1f%%", sign, p)
+}
+
+func shortSHA(s string) string {
+ if len(s) > 8 {
+ return s[:8]
+ }
+ return s
+}
diff --git a/scripts/install.sh b/scripts/install.sh
new file mode 100755
index 0000000..06b2342
--- /dev/null
+++ b/scripts/install.sh
@@ -0,0 +1,71 @@
+#!/bin/sh
+# install.sh — download and install the cubit CLI from GitHub releases.
+#
+# Usage:
+# curl -fsSL https://github.com/wardnet/cubit/releases/latest/download/install.sh | sh
+#
+# Environment:
+# CUBIT_VERSION version to install, e.g. 1.2.0 or v1.2.0 (default: latest)
+# CUBIT_INSTALL_DIR install directory (default: $HOME/.local/bin)
+set -eu
+
+REPO_URL="https://github.com/wardnet/cubit"
+INSTALL_DIR="${CUBIT_INSTALL_DIR:-$HOME/.local/bin}"
+VERSION="${CUBIT_VERSION:-latest}"
+
+if [ "$VERSION" = "latest" ]; then
+ # The releases/latest URL redirects to .../releases/tag/vcubit
++ No benchmark history yet. Record a run on the default branch to start + the trend. +
+
+ 
cubit — performance
+
+
+ {data.benchmarks.length} benchmarks · branch {data.branch} ·
+ generated {new Date(data.generatedAt).toISOString().replace("T", " ").slice(0, 16)}
+
+ {data.benchmarks.map((b) => (
+
+ no data
;
+ }
+
+ const lows = pts.map((p) => p.lower);
+ const highs = pts.map((p) => p.upper);
+ let yMin = Math.min(...lows);
+ let yMax = Math.max(...highs);
+ if (yMin === yMax) {
+ yMin *= 0.95;
+ yMax *= 1.05;
+ }
+ const span = yMax - yMin || 1;
+
+ const x = (i: number) =>
+ PAD.left + (pts.length === 1 ? plotW / 2 : (i / (pts.length - 1)) * plotW);
+ const y = (v: number) => PAD.top + plotH - ((v - yMin) / span) * plotH;
+
+ const line = pts.map((p, i) => `${x(i)},${y(p.value)}`).join(" ");
+ const band =
+ pts.map((p, i) => `${x(i)},${y(p.upper)}`).join(" ") +
+ " " +
+ pts
+ .map((p, i) => `${x(pts.length - 1 - i)},${y(pts[pts.length - 1 - i].lower)}`)
+ .join(" ");
+
+ const last = pts[pts.length - 1];
+
+ return (
+