From 871b66e0314be016b66f6fc200191205a5b7a78e Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Thu, 9 Jul 2026 10:21:56 +0300 Subject: [PATCH] docs: contribution guide + 5 good-first-issues Closes #90 --- CONTRIBUTING.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++ CURRENT_STATE.md | 1 + 2 files changed, 143 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37cc623..1b4615b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,6 +53,49 @@ subpath exports (`@ocpp-debugkit/toolkit/core`, `/scenarios`, `/reporter`, See [`AGENTS.md`](./AGENTS.md) for a detailed overview of the architecture, build commands, and package dependency graph. +## Architecture Overview + +OCPP DebugKit is a pnpm monorepo with a single published package +(`@ocpp-debugkit/toolkit`) and a single Next.js web app. + +### Core Data Flow + +``` +Trace Input (JSON/JSONL) + → parseTrace() → Events[] + → buildSessionTimeline() → Sessions[] + → detectFailures() → Failures[] + → summarizeSessions() → SessionSummary[] +``` + +Each step is a pure function — no side effects, no I/O. The CLI and web app +compose these functions to provide the full analysis pipeline. + +### Key Modules + +| Module | Location | Description | +|--------|----------|-------------| +| Types | `src/core/types.ts` | All TypeScript interfaces and type definitions | +| Schemas | `src/core/schemas.ts` | Zod validation schemas for input | +| 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 | +| 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 | +| Reporter | `src/reporter/` | Markdown + HTML report generators | +| Replay | `src/replay/` | Deterministic replay engine | +| React | `src/react/` | Reusable UI components | +| CLI | `src/cli/` | Command-line interface | + +### Browser-Safe vs Node-Only + +- `core`, `scenarios`, `reporter`, `replay`, `react`: browser-safe (no Node built-ins) +- `cli`: Node-only (uses `fs`, `path`, `process`). Never imported by browser code. + ## Development Workflow ### 1. Find or Create an Issue @@ -137,6 +180,105 @@ test/ # e.g. test/core-coverage - Tests live next to the code they test. - Coverage target: 70%+ for core package. +#### Running Tests + +```bash +pnpm test # Run all unit tests +pnpm test:external-fixture # External fixture test (installs from tarball) +pnpm test:e2e # Playwright E2E tests (in apps/web) +``` + +#### Writing Tests + +- Test the **behavior**, not the implementation. +- Cover both positive (expected result) and negative (error/edge case) paths. +- Use the `makeEvent()` helper pattern from `detection.test.ts` for creating + test events. +- For CLI tests, use the `execa`-based pattern from `cli.test.ts`. + +## Contributing Scenarios + +Scenarios are the most common first contribution. A scenario is a synthetic +trace with expected failure outcomes and optional assertions. + +### How to Add a Scenario + +1. Create a file in `packages/toolkit/src/scenarios/__scenarios__/`: + ```typescript + export default { + name: 'my-scenario', + description: 'Description of what the scenario tests.', + trace: { /* synthetic trace data */ }, + expectedFailures: ['FAILED_AUTHORIZATION'], + assertions: [ + { type: 'event_order', params: { actions: ['BootNotification', 'Authorize'] } } + ], + }; + ``` + +2. Import and register it in `packages/toolkit/src/scenarios/index.ts`. + +3. Update the scenario count in: + - `packages/toolkit/src/scenarios/index.test.ts` + - `tests/external-fixture/test.mjs` + +4. Run `ocpp-debugkit ci` to verify all scenarios pass. + +### 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. +- `expectedFailures` must align with detection rules available in the current + version. +- Test your scenario with `ocpp-debugkit scenario run my-scenario`. + +## Contributing Detection Rules + +Detection rules identify failure patterns in traces. + +### How to Add a Detection Rule + +1. Add the failure code to `FailureCode` in `packages/toolkit/src/core/types.ts`. + +2. Add suggested steps and severity in `packages/toolkit/src/core/detection.ts`: + ```typescript + SUGGESTED_STEPS.MY_NEW_RULE = [ + 'Step 1 to resolve the issue', + 'Step 2 to resolve the issue', + ]; + SEVERITY.MY_NEW_RULE = 'warning'; + ``` + +3. Implement the detection function: + ```typescript + function detectMyNewRule(events: Event[]): Failure[] { + const failures: Failure[] = []; + // Detection logic + return failures; + } + ``` + +4. Wire it into `detectFailures()`. + +5. Add unit tests in `detection.test.ts` (positive + negative cases). + +6. **Audit all existing scenarios** — new rules may trigger on existing fixtures. + Fix false positives or add the new code to `expectedFailures`. + +## Contributing Good-First-Issues + +Good-first-issues are labeled with `good-first-issue` and are designed for +new contributors. They should: + +- Have clear instructions and acceptance criteria +- Point to the relevant files and code +- Be scoped to a single concern +- Not require deep knowledge of the codebase + +If you're a new contributor, look for issues with the `good-first-issue` label +on the [issues page](https://github.com/ocpp-debugkit/ocpp-debugkit/issues). + ## Security Guidelines OCPP DebugKit processes untrusted input (trace files, pasted content). When diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md index ae72155..2682551 100644 --- a/CURRENT_STATE.md +++ b/CURRENT_STATE.md @@ -205,6 +205,7 @@ integration examples, and contributor onboarding. - ✅ Assert-based scenarios — 5 new scenarios (15 total) + `compareScenarioReports()` (Issue #87) - ✅ CLI: ci + anonymize + diff commands (Issue #88) - ✅ Integration examples — 4 example projects (Issue #89) +- ✅ Contribution guide + 5 good-first-issues (Issue #90) ## What's Next