From 9b135665b44d7158a0b999ab40bdcd8624d73309 Mon Sep 17 00:00:00 2001 From: sepehr-safari Date: Wed, 8 Jul 2026 11:32:11 +0300 Subject: [PATCH] docs: add package READMEs for npm discoverability Add README.md for all 4 published packages: - @ocpp-debugkit/core: parse, timeline, detection, summarizer, validator - @ocpp-debugkit/scenarios: 5 scenarios, getScenario() API - @ocpp-debugkit/reporter: generateMarkdownReport(), AnalysisResult type - @ocpp-debugkit/cli: inspect, report, scenario commands --- .changeset/package-readmes.md | 8 ++++ packages/cli/README.md | 69 +++++++++++++++++++++++++++++++++++ packages/core/README.md | 69 +++++++++++++++++++++++++++++++++++ packages/reporter/README.md | 50 +++++++++++++++++++++++++ packages/scenarios/README.md | 44 ++++++++++++++++++++++ 5 files changed, 240 insertions(+) create mode 100644 .changeset/package-readmes.md create mode 100644 packages/cli/README.md create mode 100644 packages/core/README.md create mode 100644 packages/reporter/README.md create mode 100644 packages/scenarios/README.md diff --git a/.changeset/package-readmes.md b/.changeset/package-readmes.md new file mode 100644 index 0000000..87f9fe3 --- /dev/null +++ b/.changeset/package-readmes.md @@ -0,0 +1,8 @@ +--- +'@ocpp-debugkit/core': patch +'@ocpp-debugkit/scenarios': patch +'@ocpp-debugkit/reporter': patch +'@ocpp-debugkit/cli': patch +--- + +Add package READMEs for npm discoverability. diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000..c0814e5 --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,69 @@ +# @ocpp-debugkit/cli + +> Command-line interface for OCPP DebugKit — inspect traces, generate reports, run scenarios. + +## Installation + +```bash +npm install -g @ocpp-debugkit/cli +``` + +## Commands + +### inspect + +Parse and analyze an OCPP trace file: + +```bash +ocpp-debugkit inspect trace.json +``` + +Outputs event count, sessions, detected failures, and parse warnings. + +### report + +Generate a Markdown report: + +```bash +# To stdout +ocpp-debugkit report trace.json + +# To a file +ocpp-debugkit report trace.json --output report.md + +# Specify format +ocpp-debugkit report trace.json --format markdown +``` + +### scenario list + +List all available built-in scenarios: + +```bash +ocpp-debugkit scenario list +``` + +### scenario run + +Run a scenario through the analysis engine and compare detected vs expected failures: + +```bash +ocpp-debugkit scenario run failed-auth +``` + +**Note:** `scenario run` runs static fixtures through the local analysis engine only. It is not active endpoint testing, WebSocket simulation, or live station/CSMS testing. + +## Accepted Trace Formats + +- **JSON Object** — `{ "metadata": {...}, "events": [...] }` +- **JSONL** — one event per line +- **Bare array** — `[[2, "id", "Action", {}], ...]` + +## Limits + +- Maximum input size: 10 MB +- Maximum event count: 10,000 + +## License + +Apache 2.0 diff --git a/packages/core/README.md b/packages/core/README.md new file mode 100644 index 0000000..69a55b2 --- /dev/null +++ b/packages/core/README.md @@ -0,0 +1,69 @@ +# @ocpp-debugkit/core + +> Core data model, parser, normalizer, timeline, and failure detection for OCPP DebugKit. + +## Installation + +```bash +npm install @ocpp-debugkit/core +``` + +## Usage + +### Parse a trace + +```typescript +import { parseTrace } from '@ocpp-debugkit/core'; + +const result = parseTrace(traceString); +// result.events — normalized Event[] +// result.warnings — ParseWarning[] for malformed entries +``` + +Accepts JSON Object, JSONL, and bare array formats. + +### Build session timeline + +```typescript +import { buildSessionTimeline } from '@ocpp-debugkit/core'; + +const sessions = buildSessionTimeline(result.events); +``` + +### Detect failures + +```typescript +import { detectFailures } from '@ocpp-debugkit/core'; + +const failures = detectFailures(result.events, sessions); +// Three detection rules: FAILED_AUTHORIZATION, CONNECTOR_FAULT, +// STATION_OFFLINE_DURING_SESSION +``` + +### Generate summaries + +```typescript +import { summarizeSessions } from '@ocpp-debugkit/core'; + +const summaries = summarizeSessions(sessions, failures); +``` + +### Validate messages + +```typescript +import { validateMessage } from '@ocpp-debugkit/core'; + +const result = validateMessage(event); +// result.valid, result.errors +``` + +## Key Types + +- `Event` — canonical normalized OCPP message +- `Session` — logical charging session +- `Failure` — detected failure with severity and suggested steps +- `Scenario` — predefined trace fixture with expected failures + +## License + +Apache 2.0 diff --git a/packages/reporter/README.md b/packages/reporter/README.md new file mode 100644 index 0000000..253a0e1 --- /dev/null +++ b/packages/reporter/README.md @@ -0,0 +1,50 @@ +# @ocpp-debugkit/reporter + +> Report generators for OCPP DebugKit analysis results. + +## Installation + +```bash +npm install @ocpp-debugkit/reporter +``` + +## Usage + +### Generate a Markdown report + +```typescript +import { generateMarkdownReport } from '@ocpp-debugkit/reporter'; +import type { AnalysisResult } from '@ocpp-debugkit/reporter'; + +const report = generateMarkdownReport({ + events, + sessions, + failures, + summaries, + warnings, +}); + +// report is a Markdown string with: +// - Session overview table +// - Timeline summary (action sequences) +// - Failures (severity, description, suggested steps) +// - Suggested next steps +// - Raw event appendix +``` + +## Input Type + +```typescript +interface AnalysisResult { + events: Event[]; + sessions: Session[]; + failures: Failure[]; + summaries: SessionSummary[]; + warnings: ParseWarning[]; + metadata?: TraceMetadata; +} +``` + +## License + +Apache 2.0 diff --git a/packages/scenarios/README.md b/packages/scenarios/README.md new file mode 100644 index 0000000..e37b07f --- /dev/null +++ b/packages/scenarios/README.md @@ -0,0 +1,44 @@ +# @ocpp-debugkit/scenarios + +> Predefined OCPP trace scenarios for testing the DebugKit analysis engine. + +## Installation + +```bash +npm install @ocpp-debugkit/scenarios +``` + +## Usage + +```typescript +import { scenarios, getScenario } from '@ocpp-debugkit/scenarios'; + +// List all scenario names +scenarios.forEach(s => console.log(s.name, s.expectedFailures)); + +// Get a specific scenario +const scenario = getScenario('failed-auth'); + +// Run through the analysis engine +import { parseTrace, buildSessionTimeline, detectFailures } from '@ocpp-debugkit/core'; + +const result = parseTrace(JSON.stringify(scenario.trace)); +const sessions = buildSessionTimeline(result.events); +const failures = detectFailures(result.events, sessions); +``` + +## Available Scenarios + +| Name | Expected Failures | +|------|-------------------| +| `normal-session` | none | +| `failed-auth` | `FAILED_AUTHORIZATION` | +| `connector-fault` | `CONNECTOR_FAULT` | +| `station-offline` | `STATION_OFFLINE_DURING_SESSION` | +| `unexpected-stop-reason` | none (parser/timeline-only fixture) | + +All scenario data is fully synthetic — no real station identifiers or personal data. + +## License + +Apache 2.0