Initial Commit

openspec/changes/diff-stringify/tasks.md

@@ -0,0 +1,85 @@
+# Tasks — Diff `stringifyPatch` human-readable patch formatter
+
+> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened.
+
+## 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.
+
+## Audit Note (2026-05-02)
+
+**Minimal progress** — DEFERRED, do not archive.
+
+- No `packages/data/diff/src/utils/stringify-patch/` directory exists.
+- `grep -rln "stringifyPatch\|stringify-patch" packages/data/diff/src/` returns zero hits.
+- `bunx turbo lint typecheck test --filter=@suaveplan/diff` is GREEN — but the new `stringifyPatch` surface is not implemented.
+- All 40 tasks remain to be done: error code `DIFF.INVALID_PATCH_OP`, `stringify-patch.ts` feature module, `StringifyPatchOptions`, OTel span event, subpath export, sibling `.md`, conformance + property tests.
+
+## 1. Spec authoring
+
+- [ ] 1.1 Read `../suaveplan/packages/universal/diff/src/utils/utils.ts` (legacy `stringify` at L237-L240)
+- [ ] 1.2 Read RFC 6902 §4 for op grammar reference
+- [ ] 1.3 Read `openspec/specs/diff/spec.md` and `src/operations/` to confirm the canonical `JsonPatch` type
+- [ ] 1.4 Read `openspec/AGENTS.md` Sections 13 and 14
+- [ ] 1.5 Draft `proposal.md` from `openspec/templates/proposal.md`
+- [ ] 1.6 Fill in `## Source mapping` table — every requirement cites a line range OR appears in the "no source line" table with justification
+- [ ] 1.7 Draft `specs/diff/spec.md` from `openspec/templates/spec-delta.md`
+- [ ] 1.8 Every requirement in the spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles
+
+## 2. Implementation
+
+- [ ] 2.1 Register error code `DIFF.INVALID_PATCH_OP` in `src/errors/diff-error.ts`
+- [ ] 2.2 Create `src/utils/stringify-patch/` feature module with `stringify-patch.ts`, `stringify-patch.types.ts`, `stringify-patch.schemas.ts`, `stringify-patch.md`, `index.ts`
+- [ ] 2.3 Define `StringifyPatchOptions` in `stringify-patch.types.ts`
+- [ ] 2.4 Implement `stringifyPatch(patch, options?)` rendering one line per op:
+  - `add /path -> <value>` — value via `valueFormatter`
+  - `remove /path`
+  - `replace /path -> <value>`
+  - `move /from -> /path`
+  - `copy /from -> /path`
+  - `test /path -> <value>`
+- [ ] 2.5 Apply `options.indent` prefix per line and `options.uppercaseOps` casing transform
+- [ ] 2.6 Throw `DiffError(DIFF.INVALID_PATCH_OP)` on unknown op (defensive)
+- [ ] 2.7 Wire OTel span event `diff.stringify-patch` with `opCount` attribute
+- [ ] 2.8 Add subpath export `./utils/stringify-patch` to `package.json::exports`
+- [ ] 2.9 Re-export `stringifyPatch` from the root barrel `src/index.ts`
+
+## 3. Tests
+
+- [ ] 3.1 Unit tests at `src/utils/stringify-patch/stringify-patch.test.ts` — every operation type rendered; multi-op join with `\n`; empty patch returns empty string; default formatter uses `JSON.stringify`
+- [ ] 3.2 Spec-conformance tests at `src/utils/stringify-patch/stringify-patch.spec-conformance.test.ts` — `valueFormatter` invoked once per value-bearing op; `uppercaseOps` flips case; `indent` prefix prepended per line; `DIFF.INVALID_PATCH_OP` thrown on unknown op; OTel span event emitted with correct `opCount`; subpath import resolves
+- [ ] 3.3 Property test (fast-check): for any well-formed `JsonPatch`, `stringifyPatch(patch).split('\n').length === patch.length`
+- [ ] 3.4 Every `it(...)` carries `{ timeout: 5000 }`
+
+## 4. Documentation
+
+- [ ] 4.1 `src/utils/stringify-patch/stringify-patch.md` — sibling doc (≥200 words, basic + advanced examples including `valueFormatter` redaction usage, full API reference)
+- [ ] 4.2 README links `./utils/stringify-patch/stringify-patch.md` under `## Modules`
+- [ ] 4.3 Update `CLAUDE.md` `@suaveplan/diff` entry to mention `stringifyPatch`
+
+## 5. Pre-archive verification (the 5-gate triple)
+
+- [ ] 5.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
+- [ ] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/diff` — green
+- [ ] 5.3 `bunx turbo test:coverage --filter=@suaveplan/diff` — 100/100/100/100
+- [ ] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/diff` — exit 0, no `error` findings
+- [ ] 5.5 `bunx turbo build --filter=@suaveplan/diff` — green
+- [ ] 5.6 `bunx turbo test --filter=...@suaveplan/diff` — every dependent (undo, event-sourcing, crdt) passes
+
+## 6. Pre-archive 7-row checklist (AGENTS.md Section 13)
+
+- [ ] 6.1 Generics threaded; `expectTypeOf` confirms `stringifyPatch` returns `string` (not `string | undefined`)
+- [ ] 6.2 Zod schema wired at `StringifyPatchOptions` boundary
+- [ ] 6.3 `DIFF.INVALID_PATCH_OP` thrown by at least one production path
+- [ ] 6.4 Strict-mode behaviors tested (`uppercaseOps: false` vs `true`; default vs custom `valueFormatter`)
+- [ ] 6.5 OTel span event emitted from production paths and asserted with a real in-memory `TracerProvider`
+- [ ] 6.6 Lifecycle dedup — N/A (stateless function)
+- [ ] 6.7 No retroactive tick — every box above reflects work done in this change
+
+## 7. Archive
+
+- [ ] 7.1 Fold spec delta into `openspec/specs/diff/spec.md`
+- [ ] 7.2 Move `openspec/changes/diff-stringify/` → `openspec/archive/<yyyy-mm-dd>-diff-stringify/`
+- [ ] 7.3 Refresh `MANIFEST.md` if dep set changed (no expected change)