sjg
bcde03de38
Record the three-tier improvement backlog (infrastructure, robustness, product) with a per-item progress status column, so the work discovered in the July 2026 repo scan is tracked. Register aidocs/** in REUSE.toml alongside docs/**. Assisted-By: Claude Code (claude-opus-4) Claude-Session: https://claude.ai/code/session_01NFpGtGTWUEYXLwZeZs2RAV Signed-off-by: Stan Grams <sjg@haxx.space>
4.7 KiB
Work In Progress — Project Improvement Areas
Living tracker for engineering-infrastructure and hardening work identified
during a July 2026 repo scan. The architecture-level backlog
(docs/Improvement-Areas.md, P0–P3) is closed; these items focus on the
tooling, robustness, and product concerns around the code.
Status legend: Done · In progress · Not started
| # | Tier | Area | Status |
|---|---|---|---|
| 1 | 1 — Infrastructure | Gitea Actions CI (fmt, clippy, test, REUSE) | In progress |
| 2 | 1 — Infrastructure | Supply-chain & lint governance (cargo-deny/audit, MSRV, [workspace.lints]) |
Not started |
| 3 | 1 — Infrastructure | Release & deployment (container image, systemd units, binary releases) | Not started |
| 4 | 2 — Robustness | Panic-resilience audit (harden ~495 unwrap/expect/panic sites) | Not started |
| 5 | 2 — Robustness | unsafe SIMD safety scaffolding (# Safety docs, scalar↔SIMD equivalence tests) |
Not started |
| 6 | 2 — Robustness | DSP performance benchmarks (criterion, guard optimization gains) | Not started |
| 7 | 2 — Robustness | Test-coverage measurement & gap-filling (llvm-cov; CAT backends, server tasks) | Not started |
| 8 | 3 — Product | Frontend modularization & tooling (split app.js into ES modules, ESLint, JS tests) |
Not started |
| 9 | 3 — Product | Runtime observability (/health, Prometheus metrics) |
Not started |
| 10 | 3 — Product | Documentation freshness & consolidation (reconcile docs/ with code) |
Not started |
Tier 1 — Infrastructure gaps
1. Gitea Actions CI
No .gitea/ / .github/ / Woodpecker workflows exist, despite 768 tests.
Add a workflow running cargo fmt --check, cargo clippy -D warnings,
cargo build/cargo test, and REUSE lint on push + pull_request.
System deps: pkg-config cmake libopus-dev libasound2-dev libsoapysdr-dev
(the soapysdr backend is a default feature).
Notes for the runner: assumes an act_runner registered with an
ubuntu-latest label and GitHub-action proxying enabled (used by
actions/checkout, actions/cache, fsfe/reuse-action). clippy runs
with -D warnings; core crates are already clean, but if the first full
--all-features run surfaces warnings in a less-travelled crate, fix them
(preferred) or temporarily soften that step.
2. Supply-chain & lint governance
No deny.toml, cargo audit, rustfmt.toml/clippy.toml, declared MSRV,
or [workspace.lints]. Add dependency auditing to CI, pin an MSRV
(rust-version), and centralize lint policy in the workspace manifest.
3. Release & deployment
No Dockerfile, systemd units, packaging, or release automation (only
script/dummy-server.sh). Add a container image, example systemd units for
trx-server/trx-client, and a tag-triggered static-binary release job.
Tier 2 — Robustness & correctness
4. Panic-resilience audit
495 unwrap()/expect()/panic! sites, 11 in the hottest server files
(audio.rs, rig_task.rs). A panic there can drop a rig task or the
process. Convert hot-path panics to error propagation / graceful
degradation; reserve expect for documented invariants.
5. unsafe SIMD safety scaffolding
13 unsafe blocks (AVX2 DSP). Add # Safety docs stating invariants,
confirm runtime feature detection is tested, and add property tests
asserting SIMD output matches the scalar fallback across random inputs.
6. DSP performance benchmarks
docs/Optimization-Guidelines.md documents NCO/polyphase/AVX2 gains, but no
criterion benches guard them. Add benches for the demod/resample/FFT hot
paths so regressions surface as numbers.
7. Test-coverage measurement & gap-filling
67 of 146 Rust files have no test module. Protocol is well covered; backends
(CAT BCD/ASCII encoding), listener.rs, and config.rs look thin. Wire up
cargo-llvm-cov and target the CAT backends and server tasks first.
Tier 3 — Product & maintainability
8. Frontend modularization & tooling
app.js is 8,760 lines and map-core.js 3,515, with no modules, linter, or
tests. Keeping vanilla HTML+JS (no framework), split into native ES modules
by concern, add ESLint + Prettier, and add node:test unit tests for pure
logic (frequency formatting, unit math, decode parsing).
9. Runtime observability
tracing is set up, but there is no /health endpoint or metrics
instrumentation. Add health/readiness endpoints and Prometheus-format
metrics (decode rates, reconnects, audio underruns, per-rig state).
10. Documentation freshness & consolidation
docs/ (13 files) is mostly dated 2026-03-29 while code moved into July, and
mixes planning artifacts with reference docs. Reconcile against current code,
separate "plans" from "reference," and fold still-true content into the
canonical docs.