132 lines
6.9 KiB
Markdown
132 lines
6.9 KiB
Markdown
# Tasks: enterprise-profiler
|
|
|
|
**Change ID**: enterprise-profiler
|
|
**Package**: `@suaveplan/profiler`
|
|
**Target path**: `universal/platform/profiler`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`
|
|
|
|
---
|
|
|
|
## 0. Pre-flight (non-negotiable)
|
|
|
|
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
|
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
|
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] Create `universal/platform/profiler/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
|
- [ ] Write `package.json` at version `0.1.0`:
|
|
- `"type": "module"`, `"sideEffects": false`
|
|
- `exports` map: `"."` barrel + `"./core/profiler/profiler"`, `"./core/session/session"`, `"./sinks/console-sink/console-sink"`, `"./sinks/json-sink/json-sink"`, `"./utils/aggregate"`, `"./utils/flamegraph"`, `"./types/common"`
|
|
- `dependencies`: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/logger workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
|
|
- `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `mitata catalog:testing`, `@suaveplan/testing workspace:^`
|
|
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
|
- [ ] Write `vitest.config.ts` using `createTestConfig()`.
|
|
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`, `bench` scripts.
|
|
|
|
---
|
|
|
|
## 2. Types and error codes
|
|
|
|
- [ ] Define all public types in `src/types/common.ts`: `ProfileSample`, `StackFrame`, `ProfileSession`, `FlamegraphNode`, `ProfileAggregate`, `ProfilerOptions`, `SessionOptions`, `ProfilerSink`, `ConsoleSinkOptions`, `JsonSinkOptions`.
|
|
- [ ] Write `src/types/common.md` (≥200 words, simple + advanced examples).
|
|
- [ ] Define error codes in `src/error-codes.ts`: `ProfilerErrorCode` union, metadata, `registerProfilerErrorCodes()`.
|
|
- [ ] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
|
|
|
|
---
|
|
|
|
## 3. Aggregate utilities (`src/utils/aggregate.ts`)
|
|
|
|
- [ ] Implement `aggregateSamples(samples)`: compute count, totalCpuMs, avgCpuMs, p50/p95/p99 (insertion-sort on the cpu array), peakHeapMb, avgHeapMb.
|
|
- [ ] Implement `formatDuration(ms)`: format as `Xms`, `Xs`, `Xm Xs`.
|
|
- [ ] Write `aggregate.test.ts` (≤500 lines): empty array, single sample, percentile correctness for known data.
|
|
- [ ] Write `aggregate.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 4. Flamegraph utilities (`src/utils/flamegraph.ts`)
|
|
|
|
- [ ] Implement `buildFlamegraph(session)`: group samples by stack frame path, build tree by folding frames into children.
|
|
- [ ] Each node's `value` = number of samples that include this frame.
|
|
- [ ] Produce sorted children (descending by value).
|
|
- [ ] Write `flamegraph.test.ts` (≤500 lines): empty session, single frame, multi-frame stacks, shared frames merge correctly.
|
|
- [ ] Write `flamegraph.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 5. Profiler session (`src/core/session/`)
|
|
|
|
- [ ] Implement `ProfilerSession` (internal class):
|
|
- `sample()` — captures `clock.now()` + heap stats via `process.memoryUsage()` (guarded for non-Node runtimes); returns `ProfileSample`.
|
|
- `stop()` — sets `endTime`, returns immutable `ProfileSession` snapshot.
|
|
- `export('json', signal?)` — JSON-serialises session.
|
|
- `export('flamegraph', signal?)` — calls `buildFlamegraph`, JSON-serialises.
|
|
- `toFlamegraph()` — synchronous `buildFlamegraph` call.
|
|
- [ ] Write `session.test.ts` (≤500 lines): sample, stop, export json, export flamegraph, abort on export.
|
|
- [ ] Write `session.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 6. Profiler (`src/core/profiler/`)
|
|
|
|
- [ ] Implement `createProfiler(options?)`: validates options with Zod; stores sessions in `Map<string, ProfilerSession>`.
|
|
- [ ] Implement `profiler.startSession(name, options?)` — generates UUID id, stores session, emits OTel span `profiler.session.start`.
|
|
- [ ] Implement `profiler.getSession(id)`, `listSessions()`, `clearSessions()`.
|
|
- [ ] Implement `profiler.use(sink)` — registers sink; on session stop, calls `sink.onSessionEnd(session)` asynchronously.
|
|
- [ ] On session stop, emit OTel span `profiler.session.stop`, histogram `profiler.session_duration_ms`.
|
|
- [ ] Write `profiler.test.ts` (≤500 lines): session lifecycle, sink called on stop, multiple sessions.
|
|
- [ ] Write `profiler.md` (≥200 words).
|
|
|
|
---
|
|
|
|
## 7. Sinks (`src/sinks/`)
|
|
|
|
### 7a. Console sink
|
|
|
|
- [ ] Implement `createConsoleSink(options?)` — on session end, prints a summary table via `console.log` with aggregate stats.
|
|
- [ ] Write `console-sink.test.ts`: output contains session name and p95 duration.
|
|
- [ ] Write `console-sink.md`.
|
|
|
|
### 7b. JSON sink
|
|
|
|
- [ ] Implement `createJsonSink(options: { path: string })` — on session end, appends JSON line to file via `Bun.write` (or `fs.appendFile` fallback).
|
|
- [ ] Write `json-sink.test.ts`: file written, valid JSON, append-safe.
|
|
- [ ] Write `json-sink.md`.
|
|
|
|
---
|
|
|
|
## 8. Property-based tests (`tests/property.test.ts`)
|
|
|
|
- [ ] `aggregateSamples` invariants: avg ≤ max, p50 ≤ p95 ≤ p99, count equals input length.
|
|
- [ ] `buildFlamegraph` node value sum: root node value ≤ total samples.
|
|
- [ ] Session stop idempotency: calling `stop()` twice on a session should be a no-op after the first call (endTime does not change).
|
|
|
|
---
|
|
|
|
## 9. Benchmarks (`src/__benchmarks__/profiler.bench.ts`)
|
|
|
|
- [ ] `sample_hot`: 1000 `session.sample()` calls.
|
|
- [ ] `buildFlamegraph_1k`, `buildFlamegraph_10k`: flamegraph on 1k and 10k sample sessions.
|
|
- [ ] `aggregateSamples_1k`, `aggregateSamples_10k`: aggregate on 1k and 10k samples.
|
|
|
|
---
|
|
|
|
## 10. Docs
|
|
|
|
- [ ] All per-file `.md` files per layout in `proposal.md`.
|
|
- [ ] `universal/platform/profiler/README.md`: purpose, installation, quick-start, API section, dependency table, benchmarks table.
|
|
|
|
---
|
|
|
|
## 11. Verify and publish
|
|
|
|
- [ ] `bunx turbo lint --filter=@suaveplan/profiler` — zero errors.
|
|
- [ ] `bunx turbo typecheck --filter=@suaveplan/profiler` — zero errors.
|
|
- [ ] `bunx turbo test --filter=@suaveplan/profiler` — all tests pass.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/profiler` — 100% on all touched modules.
|
|
- [ ] `bun run docs:check --filter=@suaveplan/profiler` — zero errors.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/profiler`.
|
|
- [ ] Update `CLAUDE.md` package listing.
|
|
- [ ] Archive: move `openspec/changes/enterprise-profiler/` to `openspec/archive/2026-04-24-enterprise-profiler/`.
|