diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3176bdb..72b0042 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,10 +21,12 @@ cd toolkit # Install dependencies pnpm install -# Verify everything works +# Verify everything works (same checks CI runs, in the same order) pnpm lint -pnpm test +pnpm format:check +pnpm typecheck pnpm build +pnpm test ``` ## Monorepo Structure @@ -80,12 +82,12 @@ compose these functions to provide the full analysis pipeline. | Parser | `src/core/parser.ts` | `parseTrace()` — JSON, JSONL, bare array | | Normalizer | `src/core/normalizer.ts` | Event normalization (timestamps, directions) | | Timeline | `src/core/timeline.ts` | `buildSessionTimeline()` — session correlation | -| Detection | `src/core/detection.ts` | `detectFailures()` — 15 failure rules | +| Detection | `src/core/detection.ts` | `detectFailures()` — failure detection rules | | Diff | `src/core/diff.ts` | `diffTraces()` — compare two traces | | Assertions | `src/core/assertions.ts` | `evaluateScenario()` — scenario assertions | | Summarizer | `src/core/summarizer.ts` | Session summary statistics | | Validator | `src/core/validator.ts` | OCPP 1.6 structural validation | -| Scenarios | `src/scenarios/` | 15 predefined scenarios + registry | +| Scenarios | `src/scenarios/` | Predefined scenarios + registry | | Reporter | `src/reporter/` | Markdown + HTML report generators | | Replay | `src/replay/` | Deterministic replay engine | | React | `src/react/` | Reusable UI components | @@ -120,11 +122,17 @@ git checkout -b feat/- ```bash pnpm lint +pnpm format:check pnpm typecheck -pnpm test pnpm build +pnpm test ``` +These are the checks CI runs, in the same order, so a green run here means a +green run there. CI stops at the first failure, which means a formatting problem +masks every result after it. `pnpm format:check` only reports; run `pnpm format` +to apply the fixes. + ### 5. Add a Changeset If your PR changes publishable package behavior, add a changeset: @@ -217,17 +225,26 @@ trace with expected failure outcomes and optional assertions. 2. Import and register it in `packages/toolkit/src/scenarios/index.ts`. -3. Update the scenario count in: +3. Update the scenario count in every place that states it: - `packages/toolkit/src/scenarios/index.test.ts` - `tests/external-fixture/test.mjs` + - `README.md` + - `packages/toolkit/README.md` + + The first two fail the test suite when they drift. The two READMEs do not, so + they are easy to miss. -4. Run `ocpp-debugkit ci` to verify all scenarios pass. +4. Run `ocpp-debugkit ci` to verify all scenarios pass, then run the full local + check from [Verify Locally](#4-verify-locally). `ocpp-debugkit ci` does not + cover formatting, lint, or types. ### Guidelines - All data must be **synthetic** — no real station IDs, transaction IDs, idTags, or personal data. - Use `SYNTHETIC-TAG-NNN` for idTags, `CS-SYNTHETIC-NNN` for station IDs. +- Each scenario takes its own station ID. Check the existing files in + `__scenarios__/` for the next free number rather than reusing one. - `expectedFailures` must align with detection rules available in the current version. - Test your scenario with `ocpp-debugkit scenario run my-scenario`. @@ -278,6 +295,16 @@ new contributors. They should: If you're a new contributor, look for issues with the `good-first-issue` label on the [issues page](https://github.com/ocpp-debugkit/toolkit/issues). +### Claiming One + +Comment on the issue saying you would like to work on it and it will be assigned +to you. + +Please hold one open claim at a time. Once your pull request for it is merged, +say which issue you want next and it will be assigned. This keeps issues from +sitting claimed while another is still in review, so other newcomers can see what +is genuinely free. + ## Security Guidelines OCPP DebugKit processes untrusted input (trace files, pasted content). When diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index 3f951b0..5f70138 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -4,21 +4,21 @@ ## Current Version -`0.4.1`, METER_VALUE_ANOMALY fix (published 2026-07-22). A `0.4.2` patch is in -progress (STATUS_TRANSITION_VIOLATION per-connector fix, #128). +`0.4.2`, STATUS_TRANSITION_VIOLATION per-connector fix (published 2026-07-22). +The v0.4.x line is complete. ## Active Milestone -**v0.4.x - detection correctness patches, then v0.5.0 (OCPP 2.0.1)** +**v0.5.0 (OCPP 2.0.1), after a complete v0.4.x** v0.4.0 shipped the Open OCPP Trace interop: the toolkit reads and writes the shared v1.1 interchange format (input adapter #121, exporter + `convert` CLI -#122), checked against the specification's conformance fixtures. Two -false-positive bugs shiv3 found from the simulator integration are being -fixed: `METER_VALUE_ANOMALY` measurand/connector flattening (#127, shipped in -0.4.1) and `STATUS_TRANSITION_VIOLATION` global status tracking (#128, in -0.4.2). Next milestone is **v0.5.0 (OCPP 2.0.1)**, where the per-connector / -EVSE model these fixes introduce is required across detection. +#122), checked against the specification's conformance fixtures. Both +false-positive bugs shiv3 found from the simulator integration are fixed and +released: `METER_VALUE_ANOMALY` measurand/connector flattening (#127, in 0.4.1) +and `STATUS_TRANSITION_VIOLATION` global status tracking (#128, in 0.4.2). Next +milestone is **v0.5.0 (OCPP 2.0.1)**, where the per-connector / EVSE model +these fixes introduce is required across detection. ## What's Done @@ -272,15 +272,36 @@ EVSE model these fixes introduce is required across detection. (vendored) in CI; round-trip tests prove export-then-reparse preserves the consumer view and the events +### v0.4.x Releases + +- ✅ `@ocpp-debugkit/toolkit@0.4.0` published 2026-07-17, Open OCPP Trace + interop (#121, #122) +- ✅ `@ocpp-debugkit/toolkit@0.4.1` published 2026-07-22, `METER_VALUE_ANOMALY` + scoped to cumulative energy registers per connector (Issue #127, PR #129) +- ✅ `@ocpp-debugkit/toolkit@0.4.2` published 2026-07-22, + `STATUS_TRANSITION_VIOLATION` tracked per connector (Issue #128, PR #131) +- ✅ Git tags + GitHub releases `v0.4.0`, `v0.4.1`, `v0.4.2` created + +### Contributor Onboarding Fixes (Issue #134) + +- ✅ First external contribution to a `good-first-issue` arrived (#133, + firmware-update-success scenario for #104). Second external contributor after + #114. +- ✅ `CONTRIBUTING.md` now documents `pnpm format:check`, which CI enforced and + the guide never named, with both command lists ordered to match the CI job +- ✅ Hard-coded rule and scenario counts dropped from the architecture table + after drifting twice; the READMEs stay authoritative and the suite asserts them +- ✅ "Adding a Scenario" names all four files carrying the count, and station + IDs are documented as unique per scenario +- ✅ Good-first-issues carry a one-open-claim-at-a-time policy + ## What's Next -1. **v0.4.0 release** - both interop halves (#121, #122) are in; cut and - publish `v0.4.0` -2. **v0.5.0 - OCPP 2.0.1 Support** - extend the engine beyond 1.6J: message +1. **v0.5.0 - OCPP 2.0.1 Support** - extend the engine beyond 1.6J: message set, device model, scenarios, and detection -3. **v1.0.0 - Stable FOSS Ecosystem** - API stabilization, 20+ scenarios, docs +2. **v1.0.0 - Stable FOSS Ecosystem** - API stabilization, 20+ scenarios, docs overhaul, contributor onboarding -4. **Future** - active scenario runner (live endpoint testing), playground, +3. **Future** - active scenario runner (live endpoint testing), playground, YAML trace format support ## Known Blockers / Decisions Pending