Statecraft 🧭
Statecraft is a local-first CLI for auditing Redux-style state recipes before they calcify into folklore. It scans project fixtures for predictable slices, async flow hygiene, coverage gaps, and migration checklist risks without mutating app code by default.
Think of it as a pantry labeler for state management: it will not cook dinner for you, but it will tell you which jars are mystery powder.
Install
Statecraft is currently distributed through GitHub Releases, not the npm registry. Install the release tarball directly:
npm install --global https://github.com/rogerchappel/statecraft/releases/download/v0.1.0/statecraft-0.1.0.tgzThe package artifact is named @rogerchappel/statecraft; the installed CLI command is statecraft. A future npm-registry publication will be announced separately.
To install from a source checkout instead, clone the repository, run npm ci && npm run build, then run npm install --global . from the repository root.
Use
statecraft scan examples/fixtures/redux-clean
statecraft scan examples/fixtures/redux-messy --format json --min-score 75
statecraft --help--min-score accepts a number from 0 through 100. A completed audit below that threshold exits with status 2, while invalid CLI arguments exit with status 1.
What it checks
- explicit initialState and discoverable reducer recipes
- reducer predictability issues such as clocks, random values, storage, or common mutation outside Immer-style wrappers (property and computed assignments, update operators, and mutating array/collection methods)
- async thunk lifecycle coverage for pending, fulfilled, and rejected
- cancellation/idempotency hints for async flows
- nearby or mirrored test coverage signals
- migration checklist items to attach to state-library upgrade PRs
State-specific findings are evaluated only in detected Redux recipe files: files whose path names slice, reducer, or store at a filename or directory boundary (such as cart.slice.ts, root-store.ts, or store/index.ts), or whose source uses createSlice, createReducer, or combineReducers. Substrings inside ordinary names such as bookstore.ts and slicer.ts do not count. Test and spec files are excluded from that inventory. This keeps ordinary clocks, random values, loose fixture types, and test setup mutations from affecting the audit score. Because detection is intentionally heuristic, unusually named vanilla reducer files may need a conventional .reducer filename to enter the inventory.
Source collection supports JavaScript and TypeScript module files with .js, .jsx, .ts, .tsx, .mts, and .cts extensions.
Rule matching ignores comments, regular-expression literal bodies (including expression statements after if, while, for, and with heads), and literal string text, including the text portions of template literals. Division expressions remain executable code, and executable ${...} template interpolations are still evaluated, including nested templates, so detector vocabulary cannot be hidden from the audit in real expressions.
Safety model
Statecraft is read-only. The MVP scans source text and emits a report; it does not rewrite reducers, install packages in target apps, or phone home. Use reports as review evidence, not as an automatic merge gate until your team calibrates the score thresholds.