82 lines
6.0 KiB
Markdown
82 lines
6.0 KiB
Markdown
# Tasks — network-plugin-devtools
|
|
|
|
> Blocked on: `network-core`, `network-plugin-monitor`, `network-plugin-simulation`.
|
|
>
|
|
> **Status (2026-05-11):** SHIPPED. All 4 subsystems implemented at enterprise grade with 100/100/100/100 coverage and full spec-conformance suite. Capability spec `openspec/specs/network-plugin-devtools/spec.md` published with seven `### Requirement: NET_DEV-NN —` clauses, each carrying a `**Verified by:**` line.
|
|
|
|
## 1. Scaffold
|
|
|
|
- [x] 1.1 `packages/network/network-plugin-devtools/` with `package.json` (`@suaveplan/network-plugin-devtools@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
|
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/diff` (added for inspector RFC-6902 diff), `@suaveplan/opentelemetry`/`@opentelemetry/api`, `zod`.
|
|
- [x] 1.3 `sideEffects: false`.
|
|
- [x] 1.4 Marked as `devOnly: true` in workspace config — implemented via `package.json` `"suaveplan": { "tier": "devtools" }` block (no monorepo-wide convention exists yet for this; the dev-only contract is enforced at runtime via the `tierGate` callback on `DevToolsPlugin`).
|
|
|
|
## 2. Types
|
|
|
|
- [x] 2.1 `src/types/visualizer.types.ts` — `VisualizerConfig`, `VisualizerMode`, `NodeLayout`, plus `EdgeLayout`, `HeatCell`, `VisualizerFilter`, `TopologyAdapter`, `MessageStreamAdapter`, `Renderer`, `RendererOutput`, `VisualizerScene`.
|
|
- [x] 2.2 `src/types/inspector.types.ts` — `InspectorConfig`, `StateView`, `DiffView`, plus `StateSnapshot`, `DiffSummary`, `SearchFilter`.
|
|
- [x] 2.3 `src/types/profiler.types.ts` — `ProfilerConfig`, `PerformanceReport`, `Baseline`, plus `LatencySample`, `ThroughputSample`, `PluginOverheadSample`, `MemorySample`, `LatencyDistribution`, `Regression`, `RegressionSeverity`, `OptimizationSuggestion`.
|
|
- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_DEV", [...])` registry of 20 codes spanning all four subsystems plus the plugin facade.
|
|
|
|
## 3. Network visualizer
|
|
|
|
- [x] 3.1 `src/visualizer/network-visualizer.ts` — `NetworkVisualizer`.
|
|
- [x] 3.2 Hierarchy view: tier structure, edges, labels (via `TopologyAdapter`).
|
|
- [x] 3.3 Message flow view: animated paths, throughput, drops (via `MessageStreamAdapter`).
|
|
- [x] 3.4 Performance heat map: latency colour-coding, saturation (via `HeatCell` IR + bundled `SvgRenderer`).
|
|
- [x] 3.5 Filtering by tier, latency group, session, transport (Zod `VisualizerFilter`).
|
|
- [x] 3.6 Export to PNG/SVG (`Renderer` injection — bundled `SvgRenderer`; PNG via caller-supplied encoder).
|
|
|
|
## 4. State inspector
|
|
|
|
- [x] 4.1 `src/inspector/state-inspector.ts` — `StateInspector`.
|
|
- [x] 4.2 Tree view of synchronised state paths (`list()` + `inspect(path)`).
|
|
- [x] 4.3 Historical state viewing with timeline scrubber (`scrub(path, atVersion)`).
|
|
- [x] 4.4 Diff visualisation between two versions (`diff(path, fromVersion, toVersion)` over `@suaveplan/diff`).
|
|
- [x] 4.5 Search and filter by path, peer, session (`search(SearchFilter)`).
|
|
|
|
## 5. Simulation config tool
|
|
|
|
- [x] 5.1 `src/simulator/simulation-config-tool.ts` — `SimulationConfigTool` (+ `simulation-config-tool.schemas.ts` Zod boundary split).
|
|
- [x] 5.2 Topology editor (programmatic API: `addPeer`, `removePeer`, `listPeers`).
|
|
- [x] 5.3 Network condition editor (latency/loss/bandwidth curves: `setCondition`, `clearCondition`, `listConditions`).
|
|
- [x] 5.4 Event timeline editor (`addEvent`, `listEvents`).
|
|
- [x] 5.5 Recording and playback (`startRecording`/`stopRecording`/`loadPlayback`/`playback`).
|
|
- [x] 5.6 Export/import scenarios as JSON (`exportJson`/`importJson` with full Zod validation).
|
|
|
|
## 6. Performance profiler
|
|
|
|
- [x] 6.1 `src/profiler/performance-profiler.ts` — `PerformanceProfiler` (+ `performance-profiler.suggestions.ts` heuristic split).
|
|
- [x] 6.2 Message latency distribution (p50, p95, p99; min/max/mean/count).
|
|
- [x] 6.3 Transport throughput per path (`recordThroughput`).
|
|
- [x] 6.4 Plugin overhead measurement (`recordPluginOverhead` with windowed averaging).
|
|
- [x] 6.5 Memory usage tracking (`recordMemory`).
|
|
- [x] 6.6 Regression detection against baseline (`captureBaseline` + `compare` with two-window EMA + Z-score severity ladder).
|
|
- [x] 6.7 Optimization suggestions (`suggestions()` covering tail latency, overhead, heap pressure, zero throughput).
|
|
|
|
## 7. Plugin wrapper
|
|
|
|
- [x] 7.1 `src/plugin/devtools-plugin.ts` — `DevToolsPlugin implements NetworkPlugin`.
|
|
- [x] 7.2 No-op in production (tier gate short-circuits `start()`; `requireActive()` raises `PLUGIN_DEV_DISABLED`).
|
|
- [x] 7.3 Exposes visualizer, inspector, simulator, profiler on plugin API as public fields.
|
|
|
|
## 8. Spec
|
|
|
|
- [x] 8.1 Capability spec `openspec/specs/network-plugin-devtools/spec.md` published with seven `### Requirement: NET_DEV-NN —` clauses, each carrying a `**Verified by:**` line referencing the matching `*.spec-conformance.test.ts`. (Originally scoped out as "no spec required (dev-only tool)"; promoted during the un-deferral sweep so the conformance gate runs against the same contract every other network plugin is held to.)
|
|
|
|
## 9. Conformance tests
|
|
|
|
- [x] 9.1 `src/visualizer/visualizer.spec-conformance.test.ts` — hierarchy, flow, heat map, export (26 tests).
|
|
- [x] 9.2 `src/inspector/inspector.spec-conformance.test.ts` — tree, history, diff, search (14 tests).
|
|
- [x] 9.3 `src/simulator/simulator.spec-conformance.test.ts` — editor, playback, export/import (25 tests).
|
|
- [x] 9.4 `src/profiler/profiler.spec-conformance.test.ts` — latency, throughput, regression, suggestions (33 tests).
|
|
- [x] 9.5 `src/error-codes.spec-conformance.test.ts` — frozen registry (6 tests).
|
|
|
|
Plus `src/plugin/devtools-plugin.spec-conformance.test.ts` (7 tests) covering the facade per NET_DEV-06.
|
|
|
|
## 10. Verify
|
|
|
|
- [x] 10.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-devtools` GREEN — 10 tasks successful, 111 tests passed.
|
|
- [x] 10.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-devtools` 100/100/100/100 (statements 502/502, branches 253/253, functions 108/108, lines 445/445).
|
|
- [x] 10.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-devtools` PASS (0 error, 0 warn, 0 info).
|