From 95dbb5abdbb746cf5da9f7926740d17205ac8d55 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sat, 6 Jun 2026 10:31:30 -0500
Subject: build: add Eask, test harness, and dev tooling

I brought the skeleton up to a working package baseline (Phase 0 in the design spec). Eask defines the package and its dev deps. A root Makefile delegates test targets to tests/Makefile and adds compile, coverage, lint, doctor, and clean, matching the layout the other packages use.

deps installs both halves DUET needs: the Emacs Lisp deps via eask, and the transport CLIs (rsync, rclone, lftp, unison) via the system package manager, so a contributor's environment is ready before the code that shells out to them.

make complexity runs a small homegrown McCabe branch counter (scripts/duet-complexity.el). No off-the-shelf tool measures Emacs Lisp: lizard doesn't support it and codemetrics is an interactive overlay, so DUET owns one. The counting is pure and covered by Normal/Boundary/Error tests. The budget is soft and the target is advisory.

The ERT harness (bootstrap, check-deps, per-file undercover coverage) and a smoke test prove the loop works end to end.
---
 docs/developer-guide.org | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/developer-guide.org

(limited to 'docs/developer-guide.org')

diff --git a/docs/developer-guide.org b/docs/developer-guide.org
new file mode 100644
index 0000000..df3199f
--- /dev/null
+++ b/docs/developer-guide.org
@@ -0,0 +1,52 @@
+#+TITLE: DUET Developer Guide
+#+AUTHOR: Craig Jennings
+
+* Status
+
+Stub. Fills out across the implementation phases; the backend API and
+transfer-spec contract land with Phase 2/3, the full release checklist with
+Phase 10. The authoritative design is [[file:design/duet-spec.org][docs/design/duet-spec.org]].
+
+* Repository layout
+
+- =duet.el= — the package. Public =duet-= commands and pure =duet--= helpers.
+  The only file that ships (Eask =package-file=).
+- =tests/= — ERT suites, one =test-duet-<area>.el= per source area, plus the
+  shared harness (=test-bootstrap.el=, =check-deps.el=, =run-coverage-file.el=).
+- =scripts/= — developer tooling, not part of the package: =coverage-summary.el=
+  (terminal coverage report) and =duet-complexity.el= (the McCabe gate).
+- =docs/= — this guide and the design spec.
+
+* Building and testing
+
+DUET uses [[https://emacs-eask.github.io/][Eask]] for dependency management and a Makefile for the common
+loops. From the project root:
+
+#+begin_src shell
+make deps          # Emacs Lisp deps (eask) + transport CLIs (rsync/rclone/lftp/unison)
+make setup         # Emacs Lisp deps only
+make test          # full ERT suite (excludes :slow)
+make test-file FILE=complexity   # one file
+make test-name TEST=pattern      # ERT name selector
+make compile       # byte-compile, warnings-as-errors
+make lint          # elisp-lint
+make coverage      # undercover + simplecov JSON, then a terminal summary
+make complexity    # cyclomatic-complexity report, gated on the soft budget
+make doctor        # transport executables present + duet loads
+make test-live     # env-gated live remote tests (DUET_LIVE_TESTS)
+#+end_src
+
+* Complexity budget
+
+=make complexity= runs =scripts/duet-complexity.el=, a homegrown McCabe branch
+counter (no off-the-shelf tool measures Emacs Lisp). The budget is soft: a
+function above the threshold (default 10) is split or carries a written
+justification. The target is advisory — run it on demand; it is not part of
+=make test=.
+
+* Backend API
+
+To be written with Phase 2. The published seam is =duet-register-backend=; the
+stable surface is the classified-endpoint plist, the =duet-backend= struct, the
+=duet-transfer-spec= plist, and the transfer-event payload. See the spec's
+"Backend extension API and developer contract".
-- 
cgit v1.2.3