dtourolle
20e683d705
DR-247. The desktop suite cannot reach ExoPlayer: it needs an Android Context and a Looper, so it exists only inside an app process. These are the same behaviours, asserted against the engine itself. Writing them forced the same gap open that mpv had. JellyTauPlayer.load(url, mediaId) had no way to express a start position, so every caller loaded and then seeked — the test could not even be written against the old signature, which is a stronger statement than a failing assertion. The position now goes to ExoPlayer with the media item via setMediaItem(item, startPositionMs), and the two-argument form delegates to it, so nothing else had to change. Running one suite against both engines settled something guesswork could not: seekWhileOpeningIsHonoured passes on ExoPlayer with no fix ExoPlayer already queues a seek issued before prepare() completes. So the lost-seek half of DR-241 was mpv-specific, and only the missing vocabulary for a start position was shared. That is the difference between "both engines have this bug" and knowing which one does. All seven cases pass on device (ROD2-W09, arm64). The fixture is a silent WAV synthesised in the cache directory at setup rather than committed or pushed: no binary in the repo, no adb step, and an exact duration, which the seek assertions depend on. Also adds the instrumentation runner to defaultConfig and teaches sync-android-sources.sh to mirror src/androidTest, the way it already mirrors src/test — so the canonical tree stays the only place tests are edited. Run: ./gradlew :app:connectedUniversalDebugAndroidTest -x :app:rustBuildUniversalDebug
Development Scripts
Collection of utility scripts for building, testing, and deploying JellyTau.
Testing Scripts
test-all.sh
Run all tests (frontend + Rust backend).
./scripts/test-all.sh
test-frontend.sh
Run frontend tests only.
./scripts/test-frontend.sh # Single pass (same as `bun run test`)
./scripts/test-frontend.sh --watch # Watch mode
./scripts/test-frontend.sh --ui # Open UI
bun run test is vitest run — one pass, exit code, done. It used to be bare
vitest, which parked in watch mode; CLAUDE.md's "Before Committing" list tells
people to run it, so it had to terminate. The interactive modes moved to their
own entry points:
| Command | Runs |
|---|---|
bun run test |
vitest run — single pass |
bun run test:watch |
vitest — watch mode |
bun run test:ui |
vitest --ui |
bun run test:coverage |
vitest run --coverage |
test-frontend.sh forwards any extra arguments to vitest and switches to the
long-running form automatically when it sees --watch, -w, or --ui.
test-rust.sh
Run Rust tests only.
./scripts/test-rust.sh # Run all tests
./scripts/test-rust.sh -- --nocapture # Show println! output
Android Scripts
build-android.sh
Build the Android APK.
./scripts/build-android.sh # Debug build
./scripts/build-android.sh release # Release build
deploy-android.sh
Install APK on connected Android device.
./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.
./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.
./scripts/check-android.sh
logcat.sh
View Android logcat filtered for the app.
./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.
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, andfind-req-implementations.shwere deleted in July 2026. They read an undocumented@req:tag convention parallel toTRACES:, greppedsrc-tauri/unscoped (hanging on ~40 GB oftarget/artifacts), and in one case reported "all requirements implemented" from an empty result set.extract-traces.tsis the single source of truth for requirement coverage. See it reportedTotal Requirements: 1and then "All requirements have implementations!". Nothing referenced it. Usebun run traces:coverage.
Example TRACES comment in code:
// TRACES: UR-005, UR-026 | DR-029
function handlePlayback() { ... }
See 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 - Full CI/CD documentation
- TRACES Quick Reference - Quick guide for adding TRACES
Linting & Formatting
There is no script wrapper for these — they are plain package.json entries:
bun run lint # eslint .
bun run lint:fix # eslint . --fix
bun run format # prettier --write .
bun run format:check # prettier --check .
Config lives in eslint.config.js (flat config: typescript-eslint +
eslint-plugin-svelte, tuned for Svelte 5 and TS strict), .prettierrc, and
.prettierignore. src/lib/api/bindings.ts is excluded from both — it is
generated by tauri-specta on every Rust build.
bun run lint is currently error-clean but not warning-clean: several rules
are deliberately set to warn because the existing tree has more hits than a
tooling change should touch (unused bindings, any at the IPC boundary, unkeyed
{#each}). Each one is annotated in eslint.config.js with why, and the
intended end state is error. Drive them down; do not delete them.
no-console is switched off for now — see the note in eslint.config.js.
Git Hooks
install-hooks.sh
Point git at the repo's tracked hooks directory (core.hooksPath).
bun run hooks:install # or: ./scripts/install-hooks.sh
hooks/pre-commit
Runs the fast half of CLAUDE.md's "Before Committing" list so it is enforced rather than remembered:
bun run check(svelte-check)bun run test(vitest, single pass)scripts/check-frontend-boundary.shcargo fmt --all -- --check, only when staged files touchsrc-tauri/
cargo clippy and cargo test are deliberately not in the hook — minutes per
commit is how you teach people to reach for --no-verify. They run in CI, and
locally via bun run test:all.
git commit --no-verify # skip the hook for one commit
git config --unset core.hooksPath # uninstall
The hook skips itself during a merge, rebase, or cherry-pick, and when nothing is staged.
Utility Scripts
clean.sh
Clean all build artifacts.
./scripts/clean.sh
NPM Script Aliases
You can also run these via npm/bun:
bun run test # Frontend tests (single pass)
bun run test:all # All tests
bun run test:rust # Rust tests
bun run lint # ESLint
bun run format:check # Prettier (check only)
bun run hooks:install # Install the git hooks
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