dtourolle
b9dab56379
Four gates that were documented but unenforced, plus the flaky test that made a full-suite run untrustworthy. Rust lint/format: CLAUDE.md has required `cargo fmt` and `cargo clippy` before every commit for as long as the rule existed, yet neither ran anywhere in CI — the requirement rested on memory alone. Both now run in build-and-test.yml and build-release.yml. rustfmt and clippy are already baked into the builder image, so nothing is installed at job time. `cargo fmt --all -- --check` is strict immediately (the tree is clean). Clippy is advisory for now: ~51 pre-existing warnings mean `-D warnings` would fail on unrelated work, so the step carries a TODO to flip the flag once the backlog clears. A compile error still fails it, so it is not a no-op. Traceability threshold: MIN_THRESHOLD sat at 50 while real coverage was 86%, so nearly half the matrix could rot before the gate objected. Ratcheted to 82 with the policy written down — it only ever goes up, and is never lowered to make a red build pass. The same figure lives in MIN_COVERAGE_PERCENT so `traces:coverage` gates locally on the same bar, and a test fails if the two drift. Dangling IDs: a TRACES comment could name any well-formed ID and the extractor accepted it silently, so typos and renames that missed a call site passed unnoticed. `bun run traces:validate` cross-checks every traced ID against the table rows in requirements.md and fails with the referencing files listed. It spans UT/IT as well, which the coverage orphan list ignores by design. This currently reports DR-189 and UT-188, which are being defined separately. Flaky offlineCatalog test: the first dynamic import of the service paid ~1s to transform its dependency graph, charged to a test body against vitest's 5s default. Alone it passed; under suite-wide contention it timed out. The import is now warmed at collection time, so no test is timing the compiler — the timeout is deliberately unchanged. The store shim also drops subscribers from module instances discarded by resetModules, which previously leaked across tests.
143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
# Development Scripts
|
|
|
|
Collection of utility scripts for building, testing, and deploying JellyTau.
|
|
|
|
## Testing Scripts
|
|
|
|
### `test-all.sh`
|
|
Run all tests (frontend + Rust backend).
|
|
```bash
|
|
./scripts/test-all.sh
|
|
```
|
|
|
|
### `test-frontend.sh`
|
|
Run frontend tests only.
|
|
```bash
|
|
./scripts/test-frontend.sh # Run all tests
|
|
./scripts/test-frontend.sh --watch # Watch mode
|
|
./scripts/test-frontend.sh --ui # Open UI
|
|
```
|
|
|
|
### `test-rust.sh`
|
|
Run Rust tests only.
|
|
```bash
|
|
./scripts/test-rust.sh # Run all tests
|
|
./scripts/test-rust.sh -- --nocapture # Show println! output
|
|
```
|
|
|
|
## Android Scripts
|
|
|
|
### `build-android.sh`
|
|
Build the Android APK.
|
|
```bash
|
|
./scripts/build-android.sh # Debug build
|
|
./scripts/build-android.sh release # Release build
|
|
```
|
|
|
|
### `deploy-android.sh`
|
|
Install APK on connected Android device.
|
|
```bash
|
|
./scripts/deploy-android.sh # Deploy debug APK
|
|
./scripts/deploy-android.sh release # Deploy release APK
|
|
```
|
|
|
|
### `build-and-deploy.sh`
|
|
Build and deploy in one command.
|
|
```bash
|
|
./scripts/build-and-deploy.sh # Build + deploy debug
|
|
./scripts/build-and-deploy.sh release # Build + deploy release
|
|
```
|
|
|
|
### `check-android.sh`
|
|
Check Android development environment setup.
|
|
```bash
|
|
./scripts/check-android.sh
|
|
```
|
|
|
|
### `logcat.sh`
|
|
View Android logcat filtered for the app.
|
|
```bash
|
|
./scripts/logcat.sh
|
|
```
|
|
|
|
## Traceability & Documentation
|
|
|
|
### `extract-traces.ts`
|
|
Extract requirement IDs (TRACES) from source code and generate a traceability matrix mapping requirements to implementation locations.
|
|
|
|
```bash
|
|
bun run traces # Generate markdown report
|
|
bun run traces:json # Generate JSON report
|
|
bun run traces:markdown # Save to docs/traceability.md
|
|
bun run traces:coverage # Coverage gate — exits non-zero below the ratchet
|
|
bun run traces:validate # Dangling-ID gate — every traced ID must be defined
|
|
```
|
|
|
|
The script scans all TypeScript, Svelte, and Rust files (plus `scripts/`)
|
|
looking for `TRACES:` comments and generates a comprehensive mapping of:
|
|
- Which code files implement which requirements
|
|
- Line numbers and code context
|
|
- Coverage summary by requirement type (UR, IR, DR, JA)
|
|
|
|
**`bun run traces:coverage` is the supported way to check requirement coverage
|
|
locally** — it runs the same computation CI does. Coverage denominators are
|
|
derived from `docs/requirements.md` at run time; they are never hardcoded. An ID
|
|
that appears in a `TRACES:` comment but is not defined in `requirements.md` is
|
|
reported as *orphaned* and does not count toward coverage (see DR-093).
|
|
|
|
**`bun run traces:validate` is the dangling-ID gate.** It fails if any traced ID
|
|
— including `UT`/`IT`, which coverage deliberately ignores — is not defined as a
|
|
table row in `requirements.md`, printing each offender with the files that
|
|
reference it. Without it the extractor accepted any well-formed ID silently, so
|
|
typos and renames that missed a call site went unreported for months.
|
|
|
|
> **Removed:** `check-req-coverage.sh`, `check-test-coverage.sh`, and
|
|
> `find-req-implementations.sh` were deleted in July 2026. They read an
|
|
> undocumented `@req:` tag convention parallel to `TRACES:`, grepped `src-tauri/`
|
|
> unscoped (hanging on ~40 GB of `target/` artifacts), and in one case reported
|
|
> "all requirements implemented" from an empty result set. `extract-traces.ts` is
|
|
> the single source of truth for requirement coverage. See
|
|
> [docs/specs/req-coverage-script-removal.md](../docs/specs/req-coverage-script-removal.md).
|
|
|
|
Example TRACES comment in code:
|
|
```typescript
|
|
// TRACES: UR-005, UR-026 | DR-029
|
|
function handlePlayback() { ... }
|
|
```
|
|
|
|
See [docs/traceability.md](../docs/traceability.md) for the latest generated mapping.
|
|
|
|
### CI/CD Validation
|
|
|
|
The traceability system is integrated with Gitea Actions CI/CD:
|
|
- Automatically validates TRACES on every push and pull request
|
|
- Enforces a minimum coverage threshold (a ratchet: raise it, never lower it)
|
|
- Fails on dangling IDs — traced but undefined in `requirements.md`
|
|
- Warns if new code lacks TRACES comments
|
|
- Generates traceability reports automatically
|
|
|
|
For details, see:
|
|
- [Traceability CI Guide](../docs/traceability-ci.md) - Full CI/CD documentation
|
|
- [TRACES Quick Reference](../docs/traces-quick-ref.md) - Quick guide for adding TRACES
|
|
|
|
## Utility Scripts
|
|
|
|
### `clean.sh`
|
|
Clean all build artifacts.
|
|
```bash
|
|
./scripts/clean.sh
|
|
```
|
|
|
|
## NPM Script Aliases
|
|
|
|
You can also run these via npm/bun:
|
|
```bash
|
|
bun run test:all # All tests
|
|
bun run test:rust # Rust tests
|
|
bun run android:build # Build Android APK
|
|
bun run android:deploy # Deploy to device
|
|
bun run android:dev # Build + deploy debug
|
|
bun run android:check # Check environment
|
|
bun run clean # Clean artifacts
|
|
```
|