suaveplan/openspec/archive/2026-04-19-enterprise-diff/tasks.md

Tasks: enterprise-diff

1. Scaffold

• 1.1 Create universal/primitives/diff/ with package.json, tsconfig.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md skeleton.
• 1.2 Register 100/100/100/100 coverage thresholds in vitest.config.ts; provider: 'istanbul'.
• 1.3 Cross-cutting guard tests in tests/: dep-graph, no-disallowed, tree-shake, file-size budget.
• 1.4 Add package to root CLAUDE.md listing, README.md table, FOLDERS.yml.

2. Errors + schemas

• 2.1 src/errors/diff-error.ts — DiffError extends SuaveplanError; defineCodes for DIFF.INVALID_PATCH, DIFF.TEST_FAILED, DIFF.PATH_INVALID, DIFF.APPLY_FAILED, DIFF.INVERT_FAILED.
• 2.2 Auto-register codes via side-effect import in src/index.ts.
• 2.3 Zod schemas: OperationSchema, PatchSchema, PatchOptionsSchema, DiffOptionsSchema, HistoryStateSchema, SyncDeltaSchema in *.schemas.ts siblings.
• 2.4 Tests: error construction, code narrowing, { path?, operation?, reason? } context fields.

3. Path module

• 3.1 src/path/path.ts — parsePath, formatPath, appendPath, concatPaths, comparePaths, pathEquals, isPrefix, parentPath, lastSegment, escapeSegment, unescapeSegment.
• 3.2 Co-located src/path/path.md.
• 3.3 Unit tests + property tests: parsePath(formatPath(p)) === p; escape round-trip.

4. Utils module

• 4.1 src/utils/utils.ts — deepClone, deepEqual, hashValue, stringify, isObject, isPrimitive, getValueAtPath, setValueAtPath, setValueAtPathMut, insertValueAtPath, insertValueAtPathMut, deleteValueAtPath, deleteValueAtPathMut.
• 4.2 Co-located src/utils/utils.md.
• 4.3 Unit tests covering edge cases: root path, array index beyond length, circular refs.

5. Operations

• 5.1 src/operations/operations.ts — createAdd, createCopy, createMove, createRemove, createReplace, createTest, invertOperation, invertPatch, operationsConflict, validateOperation, validatePatch.
• 5.2 Co-located src/operations/operations.md.
• 5.3 Unit tests for each factory + invert round-trip + conflict detection.

6. Diff algorithm

• 6.1 src/diff/diff.ts — structural diff with configurable ArrayStrategy ('index' | 'lcs').
• 6.2 Co-located src/diff/diff.md.
• 6.3 Property tests: applyPatch(doc, diff(a, b)) === b.

7. Patch apply/revert

• 7.1 src/patch/patch.ts — applyPatch, revertPatch; OTel counters + histogram.
• 7.2 Co-located src/patch/patch.md.
• 7.3 Unit tests: each operation type, failure modes, test op semantics; PatchResult shape.

8. History

• 8.1 src/history/history.ts — History class with push, undo, redo, branch truncation; createHistory factory.
• 8.2 Co-located src/history/history.md.
• 8.3 Unit tests: linear undo/redo, branch-truncation on push, bounded size, listener notifications.

9. Sync manager

• 9.1 src/sync/sync.ts — SyncManager class; createSync factory; delta push/pull; optimistic rebasing.
• 9.2 Co-located src/sync/sync.md.
• 9.3 Unit tests: concurrent deltas, conflict resolution, listener notifications.

10. Documentation + index

• 10.1 Public src/index.ts — re-exports only; no side effects besides code-registry import.
• 10.2 Subpath exports in package.json per feature module.
• 10.3 Root README.md with Install / Quick-start / Modules links.

11. Benchmarks

• 11.1 src/__benchmarks__/diff.bench.ts, apply.bench.ts, revert.bench.ts, sync-push.bench.ts.
• 11.2 Publish baseline throughput numbers in README.

12. Ship gate

• 12.1 bunx turbo lint typecheck test --filter=@suaveplan/diff — green.
• 12.2 bunx turbo test:coverage --filter=@suaveplan/diff — 100/100/100/100.
• 12.3 bunx turbo build --filter=@suaveplan/diff — green.
• 12.4 Banned-pattern scan + missing-.md scan return zero output.
• 12.5 Fold spec delta into openspec/specs/diff/spec.md; archive change folder.