Development

• jolt check requires every project namespace headlessly and exits 0. It's the fastest way to catch a namespace that doesn't compile.
• jolt test runs the unit suite: 1270 tests, 7560 assertions on macOS, 7529 on Linux (some asserts are gated by OS, such as desktop-file-validate and plutil). Nothing outside the process runs; the attach evaluators use in-process fake servers. Pass namespaces for a subset: jolt test jonquil.edit-test.
• jolt verify is the pre-commit gate: clj-kondo in report mode, then jolt test and jolt test:nrepl, both of which must pass.

Five harnesses drive the real GTK front end.

jolt gtk:selftest opens ten real GTK windows in turn and runs the rows against them, calling the same button and key handlers a person would use. The full application window alone has over 400 rows. The windows run in the navy theme, easier on the eyes while they flash past; set JONQUIL_SELFTEST_THEME=light (or another theme name) for a run in a different one. Each row starts on that theme, and the theme rows set the themes they check themselves. JONQUIL_SELFTEST_MAXIMIZE=1 maximizes the window before every row, for a recording of a run.

jolt smoke:binary builds target/smoke/jonquil (skip with --no-build), launches it as a subprocess, and drives it with cgevent key --pid, so no keystroke goes to other windows or --global. It checks file bytes, window titles, and screen pixels (OCR through cgevent ocr-inspect, plus a colour check of the theme's text and prompt). Every process it starts is killed on every exit path.

jolt smoke:binary, smoke:cljd, smoke:cljs and jolt docs:shots drive the macOS cgevent tool, which is private for now, so they run only where it is installed. The unit suite, the self-tests and jolt linux:test never need it.

jolt smoke:cljd drives a built ./jonquil against a real, running ClojureDart app built on the nREPL fork (private for now). The gitignored dev/smoke/cljd_app.local.edn names it: :dir (absolute path), :main-ns (the namespace Run loads), and optionally :fork-sha (a prefix the app's deps.edn :git/sha must start with). Without the file the task prints how to create it and exits 1. If the app isn't up or the screen is locked, every step SKIPs and it exits 0.

jolt smoke:cljs drives a built ./jonquil against a real, running shadow-cljs app. Start the watch and a JS runtime first (npx shadow-cljs watch <build>, then the browser tab or node script); the task never starts or stops them. The gitignored dev/smoke/cljs_app.local.edn holds {:dir "..." :build :dev}, and without it the task prints how to create it. With several builds it writes a temporary untracked .jonquil.edn into the app directory to name one, removed on every exit path. 18 checks.

jolt docs:shots self-captures every docs/images/*.png and the GIFs the guide pages embed, launching a fresh jolt -M:shots <scene-id> per scene (32 scenes). Retake one image with that command directly. First runs can download dependencies (ClojureScript and shadow-cljs scenes, and the ClojureDocs export for clj-full-doc). A scene whose tools are missing prints a line and exits 0 without an image.

Every harness isolates your settings. The window self-tests and docs:shots pass a temp :settings-path to jonquil.main/start!, and the smokes point XDG_CONFIG_HOME at a fresh temp directory per process. Nothing touches ~/.config/jonquil/settings.edn.

Temp directories come from dev/temp_dirs.clj, which deletes them when the tests or driver finish. jolt clean:tmp removes what older runs left (only names these harnesses make); jolt clean:tmp --dry-run lists them first.

Traps

• Don't type while a self-test or smoke window has focus. A stray keystroke fails an unrelated row.
• A phantom second display at scale 1.0 breaks smoke:binary's OCR and makes docs:shots images 1x instead of Retina 2x. Check system_profiler SPDisplaysDataType.
• Never use cgevent type against this app: GTK's macOS backend reads the key code, not the Unicode string, so text arrives mangled.
• An interrupted jolt test:nrepl or jolt gtk:selftest can leave a Jolt child. Check pgrep -fl "jolt.nrepl/start 79" and kill only pids from your interrupted run.
• An interrupted jolt test:clj can leave a JVM. Check pgrep -fl clojure-cli.repl.server, and kill only a pid that run started.

The design is in Window parts. In short:

1. Add src/jonquil/parts/<name>.clj with spec (its commands, each with a :call data entry) and list it in jonquil.parts/specs.
2. Add src/jonquil/gtk/parts/<name>.clj with (part wctx) tagged ^{:part/id :<name>}, returning {:fns :ui :hooks :exports}, and list it in jonquil.gtk.parts/installs.
3. Take everything the part needs from wctx, never by requiring jonquil.gtk.window.
4. For a right-hand panel, declare it in the spec's :panels with a label, add a :panel/<id> command whose :call is [:panel-focus-fn :<id>], and answer it under :panels from the install: {:<id> {:root widget :focus! f :open! f}}. Don't use :review or :history, which are core ids.
5. For keys, a new feature's keys may go in the spec's :bindings ({:window [...] :editor [...]}, entries shaped like keymap.edn). Keys of existing features stay in keymap.edn. A binding with Alt needs :physical? true to fire on macOS. Spec bindings come after the shipped ones, so a shipped key wins, and the unreachable-bindings test fails if one is shadowed.
6. Test the spec in jolt test, and add a row to a window self-test for the install. specs-and-installs-name-the-same-parts fails if only one list has the part.
7. For per-tab state, add :on-tab-removed, :on-tab-wired and :on-switch hooks to :hooks; each is called (f ctx tab). Wire-time hooks run before the changed-form gutter's handler connects, and removal hooks run while the tab's buffer is still alive, and switch hooks run when a tab becomes the active one. A throwing hook is reported on the status line and the close or wiring goes on.
8. Run jolt verify.

• jolt app:bundle rebuilds ./jonquil and makes ./Jonquil.app, printing a check line for plutil -lint on the Info.plist, the executable bit, and codesign -dv showing the linker's ad-hoc signature. A failed check exits non-zero naming it.
• jolt app:install bundles, moves the result to ~/Applications/Jonquil.app (replacing an existing one only if its plist names net.b12n.jonquil), and runs lsregister -f. The checkout's copy is unregistered and removed, so Open With lists Jonquil once.
• jolt app:icon regenerates resources/Jonquil.icns and resources/icon/jonquil-256.png from resources/icon/icon.swift. It needs Swift, and you run it only after changing the icon.

The bundle is deliberately not re-signed: jolt build appends the program image after the launcher's Mach-O, so codesign --force fails strict validation. macOS checks the linker's ad-hoc signature, which the task verifies.

On Linux, jolt app:install runs jolt app:build and copies the binary, a launcher, the icon and the MIME types under ~/.local/share (dev/app_linux.clj); jolt app:uninstall removes them. On macOS it only says to drag the app to the Trash.

Every Linux check runs in a local Docker container, so a Mac can verify the Linux build. There is no CI for it: the workflows in .github/ stay manual. Docker is the only requirement beyond the usual tools.

Tasks take --arch arm64|amd64 (default: the host's), except linux:clean. The arm64 image compiles Jolt and Chez Scheme from source because Jolt publishes no Linux arm64 binary, so it's slow to build (about 11 minutes); amd64 uses the pinned release tarball but still takes about 6.5 minutes, its apt step emulated. Pulling the base image needs Docker Hub, so run the first jolt linux:image from a normal terminal.

The checkout is mounted read-only and copied to ~/jonquil in the container, skipping jonquil, jonquil.build, Jonquil.app, _site and target. Only target/linux/<arch>/ is written in your tree.

A non-host arch runs under emulation, several times slower. jolt linux:selftest then sets JONQUIL_SELFTEST_EMULATED=1, widening the paint-async row's budget from 150 to 750 ms. The 20 s wait for a Jolt nREPL child can still run out on a busy host.

The noVNC hand check

jolt linux:vnc starts a container with Xvfb, openbox, pcmanfm, x11vnc and noVNC, installs Jonquil with jolt app:install, and prints a URL such as http://localhost:6080/vnc.html?autoconnect=true&resize=scale. The port is the first free one from 6080; --port P asks for one and is refused when busy. In pcmanfm, open ~/smoke (hello.clj, hello.jank, nrepl-project) and check that right-clicking a file offers Jonquil, that it opens, and that selecting both hello files opens one window with two tabs. For anything else use docker exec jonquil-vnc-<P> ... (add -e DISPLAY=:1 for windows). Ctrl-C stops the container and frees the port.

• jolt lint runs clj-kondo over src, test and dev in report mode. jolt lint:strict exits non-zero on any finding (2 for warnings, 3 for errors); the lint workflow gates on it. The git hooks block only on clj-kondo errors.
• jolt metrics runs jolt-metrics over the repo and prints its Markdown report: a refactoring queue worst first, git hotspots, unusual commits and files, unused requires and functions nothing mentions, then per-file numbers and coupling. The queue weighs each function by its reach, how many functions depend on it at any distance (from jolt-lsp's call graph), so a complex function the rest of the code goes through ranks first; the EDN and JSON reports also carry each function's fan-in and fan-out. jolt metrics:edn gives every finding as data, jolt metrics:json a lean JSON report for tools, and jolt metrics:html one self-contained page (target/metrics.html unless a file comes first). Extra arguments go to its CLI (an output file, whose extension picks the format, --top N, --no-git, --exclude GLOB). Findings never fail it; only bad usage does. .jolt-metrics.edn at the root counts dev as test code (measured, never queued) and leaves out build output, clj-kondo's cache, the smoke fixtures and docs. Upstream-lifted code (src/jonquil/syntax.clj, src/jonquil/parinfer.clj, src/jonquil/inspect/view.clj and test/jonquil/upstream/) is left out too, since it follows DrClojure's source and is tracked in UPSTREAM.md. The :metrics alias pins the library's version, at the commit Jolt's own CI gate runs.
• jolt metrics:gate is the one metrics task that fails. It runs the report as EDN through ci/metrics-gate.clj, which checks ci/metrics-allow.edn, and fails on two things: - a critical finding under src/ or test/: a function past a complexity, length, nesting, parameter, coupling or maintainability limit, or a file past 1000 lines. Under test/, only helpers and the file itself are queued, not deftest bodies. A file jolt-metrics can't read there fails it too. There's no list of accepted criticals, so a function that crosses a limit gets split. - an unused require, private function or public function that the allowlist doesn't name with a :why, and an allowlist entry that's no longer reported, so the list stays true.

The gate also refuses to run against an allowlist with no :critical-free paths, or a report missing its sections, rather than pass having checked nothing. dev/ (the fake servers, demo shots and the self-test harness) isn't in the gate yet. Bringing it in takes two edits: add "dev/" to :critical-free, and take dev out of .jolt-metrics.edn's :test-paths. The metrics job in .github/workflows/lint.yml runs it on every push to main and every pull request. - jolt lsp:format / jolt lsp:format-check and jolt lsp:clean-ns / jolt lsp:clean-ns-check reformat (or dry-run) code and ns forms with clojure-lsp; jolt lsp:check runs both dry-run checks. - The LSP tasks cover src, test and dev, skipping dev/smoke/fixtures/*.clj (deliberately invalid Clojure that aborts clojure-lsp's parser), dev/smoke/PixelAt.java, and the two files lifted from DrClojure-Neo (src/jonquil/syntax.clj, test/jonquil/upstream/syntax_test.clj) so re-syncs diff cleanly. - jolt hooks:install writes a fast pre-commit hook (clj-kondo errors plus a format dry-run). jolt hooks:install:full adds the full test suite. jolt hooks:uninstall removes either. Installing runs the checks first and warns if the tree doesn't pass yet.

The lint workflow

.github/workflows/lint.yml runs jolt lint:strict and jolt lsp:format-check on ubuntu-latest, with Jolt installed to run the tasks, plus the metrics job (Jolt 0.8.27). It runs on every push to main and every pull request, and by hand from the Actions tab or with gh workflow run lint.yml.

jolt bench:edit [sizes...] times what typing costs in a large file. For each size (default 200, 2000, 8000 and 20000 lines of Jonquil's own source) it opens a real GTK window, so leave the keyboard alone. It prints bench <measure> lines=<n> ms=<x> lines:

• plan: the median paint-plan run (background thread, so not a stall).
• stall-edit, stall-quote: the longest main-loop iteration in the 2 s after typing a letter, or a double quote (which flips string parity), into the first defn name in the first 40 lines.
• settle-stall-edit, settle-stall-quote: time until the repaint has landed; VOID if it didn't settle.
• jump: the median jump-to-definition.

Each timed run gets a fresh copy of the text, because the tokenizer caches by string identity. What remains of the stall at 20,000 lines is the copy of the buffer text on the GTK thread, about 50 ms.

jolt upstream:diff lists upstream DrClojure-Neo commits since UPSTREAM_PIN that touch src or test. It needs no setup: it keeps its own clone under ~/.cache/jonquil/. See Porting and attribution.

jolt site:build, jolt site:serve [port] and jolt site:clean build and preview this documentation site (docs/guide/) using a sibling checkout of jlt-commons/docs-engine, looked up as $JLT_DOCS_ENGINE, then ~/dev/jlt-commons/docs-engine, then ../docs-engine (a sibling there can be an unrelated older fork). If none exists, the task prints where to git clone it. site:serve also needs babashka (bb) on PATH. The engine's preview server is http-kit, which Jolt doesn't bundle, so that one task runs the engine's bb serve. site:build and site:clean run under Jolt. There's no workflow or GitHub Pages site behind this: it's a local preview until the project is open-sourced.