dtourolle
95eb16d5ef
Three gaps in the frontend tooling, all in the package.json script surface.
1. No JS/TS linter or formatter existed at all for 274 TS/Svelte files.
Adds an ESLint flat config (typescript-eslint + eslint-plugin-svelte,
Svelte 5 + TS strict) and prettier + prettier-plugin-svelte, plus the
`lint`, `lint:fix`, `format`, `format:check` scripts.
The tree is error-clean (`npx eslint .` exits 0). Getting there needed
seven real one-line fixes (braced switch cases that leaked `const` across
arms, a useless regex escape, two `let`s that never change, a thrown Error
that dropped its `cause`, and two `// eslint-disable-next-line` comments
documenting the Svelte 5 bare-read-for-dependency idiom). Everything else
that fires is set to `warn` with the reason written next to it in
eslint.config.js — notably ~94 dead bindings and `any` at the IPC
boundary. Those are real findings to drive to zero, not noise to delete.
`no-console` is OFF for now: a parallel change is moving all ~468 console
calls onto a logger facade, and turning the rule on today would collide
with it. eslint.config.js says so, and says to flip it to `error` once
that lands.
`prettier --write` is deliberately NOT run here — it would rewrite ~200
files and swamp every other diff in flight. The gate is available; the
sweep is a separate commit. Markdown and CI YAML are in .prettierignore
because both are hand-laid-out (and docs/traceability.md is generated).
2. `bun run test` was bare `vitest`, i.e. watch mode — while CLAUDE.md's
"Before Committing" list tells people to run it. It is now `vitest run`,
with `test:watch` and `test:coverage` (also `--run`-ified) alongside.
scripts/test-all.sh drops the now-redundant `--run`, and
scripts/test-frontend.sh keeps `--watch`/`--ui`/`-w` working by routing
them to a long-running vitest instead of the single-pass one.
3. The webdriverio e2e suite is deleted. It was last touched in January
("First working POC"), has never run since, and is not in CI — five
devDependencies and two scripts of pure decoration. Removes e2e/,
wdio.conf.ts, the two `test:e2e*` scripts, the @wdio/* + webdriverio
devDeps, and the WebdriverIO block in .gitignore.
The package.json diff also carries `hooks:install` and `check:links`, wired
up by the following commits.
215 lines
7.4 KiB
Markdown
215 lines
7.4 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 # 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.
|
|
```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
|
|
|
|
## Linting & Formatting
|
|
|
|
There is no script wrapper for these — they are plain package.json entries:
|
|
|
|
```bash
|
|
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`).
|
|
```bash
|
|
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.sh`
|
|
- `cargo fmt --all -- --check`, **only when staged files touch `src-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`.
|
|
|
|
```bash
|
|
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.
|
|
```bash
|
|
./scripts/clean.sh
|
|
```
|
|
|
|
## NPM Script Aliases
|
|
|
|
You can also run these via npm/bun:
|
|
```bash
|
|
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
|
|
```
|