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>
90 lines
4.7 KiB
Markdown
90 lines
4.7 KiB
Markdown
# 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.
|