diff --git a/REUSE.toml b/REUSE.toml index 725ec1a7..f46d1a72 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -11,6 +11,7 @@ path = [ "README.md", "trx-rs.toml.example", "docs/**", + "aidocs/**", "src/decoders/trx-ftx/README.md", "src/decoders/trx-wxsat/README.md", "assets/trx-logo.png", diff --git a/aidocs/wip.md b/aidocs/wip.md new file mode 100644 index 00000000..9dd10733 --- /dev/null +++ b/aidocs/wip.md @@ -0,0 +1,89 @@ +# 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.