robert/ttrpg-initiative-tracker
1
0
Fork 0
Code Issues Pull Requests Releases 4 Wiki Activity

chore: move audit tools tests/audit, add scratch/ gitignored

Browse Source 
Audit tools are test code (bug-finders), not scripts. Move to tests/audit/.
scripts/ now only replay-combat (live demo tool).

scratch/ = gitignored throwaway. Repro scripts, exploration, debug.

Update DEVELOPMENT.md + scripts/README to match new layout.
This commit is contained in:
david raistrick
2026-06-29 17:11:46 -04:00
parent a8e88cf0f0
commit c314d1975e
5 changed files with 41 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEVELOPMENT.md
+31 -18
View File
@@ -24,10 +24,13 @@ TTRPG Initiative Tracker — fork with self-hosted backend. Monorepo via npm wor
shared/ # Pure logic, no I/O (client + server + tests import)
turn.js # turn-order state machine
tests/ # turn logic tests
scripts/ # manual demo/audit tools (NOT unit tests)
scripts/ # manual demo tool (NOT test)
replay-combat.js # live backend demo
audit-rotation.js # exploratory rotation bug-finder
audit-state.js # exploratory invariant bug-finder (9 classes)
tests/
audit/ # exploratory bug-finders (manual, Math.random)
audit-rotation.js # rotation invariant
audit-state.js # 9 invariant classes
scratch/ # gitignored: throwaway repro/exploration
docs/
REWORK_PLAN.md
DEVELOPMENT.md # this file
@@ -119,33 +122,38 @@ CI=true npx react-scripts test --watchAll=false src/tests/App.characterization.t
CI=true npx react-scripts test --watchAll=false --testPathIgnorePatterns="Combat.scenario"
```
## Manual tools (NOT tests)
## Demo tool (NOT test)
`scripts/` = exploratory. Math.random, non-deterministic. Used to find bugs, unit tests lock them.
### replay-combat.js — live demo
Drives full combat through real backend via ws adapter (same contract as App). Player display live-updates.
`scripts/replay-combat.js` = live backend demo. Watch UI react to state changes.
```bash
# start backend + frontend first (see Run)
# start backend + frontend first
node scripts/replay-combat.js [rounds] [delayMs]
# defaults: 100 rounds, 200ms/step
```
Coverage per round: damage, heal, all 22 conditions, toggleActive (mark inactive/reactivate), removeParticipant, addParticipant (reinforcements), updateParticipant (edit), pause/resume, reorderParticipants, endEncounter. Revives dead each round to sustain 100 rounds.
Coverage per round: damage, heal, all 22 conditions, toggleActive,
removeParticipant, addParticipant (reinforcements), updateParticipant,
pause/resume, reorderParticipants, endEncounter. Revives dead each round
to sustain full round count.
### audit-rotation.js — rotation bug-finder
## Audit tools (NOT unit tests)
Pure turn.js simulation of replay op sequence. Detects rotation violations (skip/dupe per round). Pinpointed BUG-1 (addParticipant + pause corrupts rotation).
`tests/audit/` = exploratory, Math.random, non-deterministic. Manual run.
Unit tests (`{shared,server,src}/tests/`) lock known bugs deterministically.
### audit-rotation.js
Pure turn.js simulation of replay op sequence. Detects rotation violations
(skip/dupe per round). Found BUG-1 (addParticipant + pause corrupts rotation).
```bash
node scripts/audit-rotation.js
node tests/audit/audit-rotation.js
```
Bisect mode: comment/uncomment op blocks to isolate which combo triggers.
Bisect: comment/uncomment op blocks to isolate triggering combo.
### audit-state.js — expanded invariant bug-finder
### audit-state.js
Runs pure turn.js combat, audits 9 invariant classes per round:
@@ -160,13 +168,18 @@ Runs pure turn.js combat, audits 9 invariant classes per round:
9. undo support
```bash
node scripts/audit-state.js [rounds]
node tests/audit/audit-state.js [rounds] # default 100
```
100-round run: 128 violations, all BUG-1/BUG-2 family (4 symptom faces). Clean: HP, isActive, deathSave, conditions, removal.
Current state (post BUG-1/2 fix): 0 violations / 100 rounds.
See `TODO.md` for known bugs.
## Scratch
`scratch/` = gitignored throwaway. Repro scripts, exploration, debug.
Not committed. Use freely, delete anytime.
## Build
```bash