dtourolle
5d02628689
Two defects found while preparing v0.9.2, both of which had been shipping for months without anything to notice them by. **Every release note was the same 1,050 bytes.** All 35 releases from v0.0.1 to v0.9.1 published identical generic install instructions whose "What's New" section read "See CHANGELOG.md" -- a link that does not resolve from a release page. A reader learned nothing about what changed in any release the project has ever made. The body now comes from the `## <version>` section of CHANGELOG.md, and a missing section fails the release: notes that say nothing are worse than a build that waits for a maintainer to write two sentences. The 35 published bodies have been backfilled from the changelog via the tea CLI. This also corrects something introduced two commits ago. That change generated the body from `bun run release:notes`, which CLAUDE.md is explicit about -- its output is "a reviewed draft, not a final changelog". Publishing it unreviewed proved the point immediately: the v0.9.1..HEAD range contains a repo-wide prettier sweep, so every file in src/ counted as changed, their TRACES resolved to nearly the whole matrix, and the draft claimed the release had added the entire application. The script now skips cosmetic commits (chore(format), chore(deps), style) and reports how many rather than silently returning a smaller set, but it stays a local drafting tool. **Every release from v0.1.0 to v0.8.2 shipped every Windows installer ever built.** src-tauri/target/*/release/bundle/ is not versioned, cargo never cleans it, and the runner reuses the target directory -- so the copy step's bundle/**/*-setup.exe glob collected the lot. v0.8.2 carried sixteen installers, thirteen of them stale; v0.5.0 offered users a download list going back to 0.1.0. Eight months, and nothing to notice it by: the upload loop reported success, the files were real, and the page looked busy rather than wrong. It stopped only because an unrelated cargo cache change wiped the runner's target dir, so it was dormant, not fixed. Both desktop builds now remove the bundle directory before building, so a stale file cannot exist to be copied. Filtering the copy by version would have hidden it instead. The Linux job gets the same treatment: it was never hit only because Linux packaging is newer, and the glob is identical. scripts/check-release-artifacts.sh is the backstop for whatever reintroduces one by a route nobody predicted. It runs before the SBOM, the checksums and the upload -- all of which describe the file set, so a stale artifact has to be caught before it is hashed and published as part of the release. Verified against a reconstruction of the real v0.8.2 accumulation. DR-219, DR-220, UT-210.
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