Skip to content

Commit bac53fd

Browse files
codeaholicguycodeaholicguy
committed
Add zod migration plan
1 parent 53a68cd commit bac53fd

File tree

5 files changed

+303
-0
lines changed

5 files changed

+303
-0
lines changed

‎docs/ai/design/feature-validation-zod-migration.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
phase: design
3+
title: Validation Migration to Zod - Design
4+
description: Schema-first validation design for CLI and memory package inputs
5+
---
6+
7+
# Design: Validation Migration to Zod
8+
9+
## Architecture Overview
10+
11+
Validation moves from imperative functions to declarative Zod schemas across `packages/memory` and `packages/cli` while preserving existing entry points.
12+
13+
```mermaid
14+
graph TD
15+
CLI[CLI Commands] --> CLIVAL[CLI Validation Layer]
16+
CLIVAL --> API[Memory API Layer]
17+
MCP[MCP Tools] --> HANDLERS[Handlers]
18+
API --> HANDLERS
19+
HANDLERS --> SCHEMAS[Zod Schemas]
20+
CLIVAL --> SCHEMAS
21+
SCHEMAS --> NORMALIZE[Normalization Helpers]
22+
HANDLERS --> DB[(SQLite)]
23+
SCHEMAS --> ERR[Error Adapter]
24+
```
25+
26+
## Data Models
27+
28+
- Add schema module(s) for:
29+
- `StoreKnowledgeInput`
30+
- `UpdateKnowledgeInput` (partial fields + at least one update field)
31+
- `SearchKnowledgeInput`
32+
- Add schema module(s) for CLI validator inputs currently enforced manually (for example registry ID and skill name formats in `packages/cli/src/util/skill.ts`).
33+
- Reuse constants for min/max and regex patterns to avoid rule drift.
34+
- Infer types from schemas where practical, while keeping exported public types stable.
35+
36+
## API Design
37+
38+
- Handlers continue receiving the same input shapes.
39+
- Replace manual validator calls with `schema.parse` / `safeParse` wrappers.
40+
- Convert Zod issues into existing error surfaces:
41+
- `ValidationError` for memory package flows.
42+
- `Error` (or existing CLI error handling shape) for CLI utility validators.
43+
- Error text is allowed to differ as long as validation semantics stay equivalent.
44+
45+
## Component Breakdown
46+
47+
1. `packages/memory/src/services/validator.ts`
48+
- Refactor to define and export Zod schemas plus parse helpers.
49+
- Keep legacy exported function names (`validateStoreInput`, `validateUpdateInput`, etc.) as compatibility wrappers where needed.
50+
51+
2. `packages/memory/src/handlers/search.ts`
52+
- Move inline `validateSearchInput` logic to shared Zod schema-based validation.
53+
54+
3. `packages/cli/src/util/skill.ts` (and optional helper module)
55+
- Replace regex-based manual checks in `validateRegistryId` and `validateSkillName` with Zod schema parsing.
56+
- Keep existing exported function signatures to avoid caller churn.
57+
58+
4. `packages/memory/tests/unit/validator.test.ts`, memory integration tests, and CLI util tests
59+
- Update/add assertions for schema-driven validation behavior and error formatting.
60+
61+
## Design Decisions
62+
63+
- **Schema wrappers retained:** Keep current validator function surface to minimize downstream churn.
64+
- **Centralized constants:** Preserve existing numeric/string constraints to avoid behavior regressions.
65+
- **Error compatibility semantics:** Preserve pass/fail behavior and reasons; exact message strings may evolve.
66+
- **Package-local adapters:** Keep memory and CLI error adaptation local to each package to avoid cross-package coupling.
67+
68+
## Non-Functional Requirements
69+
70+
- **Performance:** Validation overhead should remain negligible for CLI payload sizes.
71+
- **Reliability:** Invalid payloads fail fast before DB calls.
72+
- **Maintainability:** New validation rules should be added through schema composition, not duplicated logic.
73+
- **Security:** Input constraints remain enforced before persistence/query execution.

‎docs/ai/implementation/feature-validation-zod-migration.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
phase: implementation
3+
title: Validation Migration to Zod
4+
description: Implementation notes for replacing custom validators with Zod
5+
---
6+
7+
# Implementation Guide: Validation Migration to Zod
8+
9+
## Development Setup
10+
11+
- Install dependencies in workspace after planning/design approval.
12+
- Validate that `packages/memory` builds and tests pass before and after migration.
13+
14+
## Code Structure
15+
16+
- Primary scope: `packages/memory/src/services/validator.ts` and `packages/memory/src/handlers/search.ts`.
17+
- Prefer schema + wrapper functions to keep external call sites stable.
18+
19+
## Implementation Notes
20+
21+
### Core Features
22+
- Implement shared Zod schema fragments for title/content/tags/scope/query/limit.
23+
- Keep `ValidationError` as output error type.
24+
- Preserve rule constants and validation boundaries.
25+
26+
### Patterns & Best Practices
27+
- Use `safeParse` where multi-error formatting is needed.
28+
- Avoid duplicating regex and min/max constants.
29+
30+
## Integration Points
31+
32+
- Memory handlers: store/update/search
33+
- CLI and MCP paths relying on memory handlers
34+
35+
## Error Handling
36+
37+
- Convert Zod errors to existing `ValidationError` message and `errors[]` metadata.
38+
39+
## Performance Considerations
40+
41+
- Keep validation synchronous and lightweight.
42+
43+
## Security Notes
44+
45+
- All external inputs must pass schema validation prior to DB access.

‎docs/ai/planning/feature-validation-zod-migration.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
phase: planning
3+
title: Validation Migration to Zod - Planning
4+
description: Task plan for migrating custom validators to Zod schemas
5+
---
6+
7+
# Planning: Validation Migration to Zod
8+
9+
## Milestones
10+
11+
- [ ] Milestone 1: Introduce Zod dependency and schema scaffolding
12+
- [ ] Milestone 2: Migrate memory validation paths to Zod
13+
- [ ] Milestone 3: Complete tests and regression verification
14+
15+
## Task Breakdown
16+
17+
### Phase 1: Foundation
18+
19+
- [ ] Task 1.1: Add `zod` dependency to `packages/memory/package.json`
20+
- [ ] Task 1.2: Create/extend validation schema module with shared constraints and helper formatters
21+
22+
### Phase 2: Core Migration
23+
24+
- [ ] Task 2.1: Refactor `validateTitle`, `validateContent`, `validateTags`, `validateScope` to schema-based parsing
25+
- [ ] Task 2.2: Refactor `validateStoreInput` and `validateUpdateInput` to use schema wrappers
26+
- [ ] Task 2.3: Replace inline search input validation in `packages/memory/src/handlers/search.ts` with schema-based validation
27+
28+
### Phase 3: Tests & Validation
29+
30+
- [ ] Task 3.1: Update unit tests for validator behavior parity
31+
- [ ] Task 3.2: Update integration tests for store/update/search invalid input scenarios
32+
- [ ] Task 3.3: Run package and workspace tests; fix regressions
33+
34+
## Dependencies
35+
36+
- Task 1.1 precedes all migration tasks.
37+
- Task 1.2 precedes Tasks 2.1-2.3.
38+
- Tasks 2.1-2.3 should complete before Tasks 3.1-3.3.
39+
40+
## Timeline & Estimates
41+
42+
- Phase 1: 0.5 day
43+
- Phase 2: 1-1.5 days
44+
- Phase 3: 0.5-1 day
45+
- Total estimate: 2-3 days including regression fixes
46+
47+
## Risks & Mitigation
48+
49+
- Risk: Error message text changes may break strict tests.
50+
- Mitigation: Add error adapter and update tests intentionally where text differences are acceptable.
51+
- Risk: Partial update validation semantics may shift.
52+
- Mitigation: Keep explicit tests for "at least one field" and optional field validation.
53+
- Risk: Scope creep to all validators in repo.
54+
- Mitigation: Lock this feature to memory package first; track CLI util migration separately if needed.
55+
56+
## Resources Needed
57+
58+
- Existing memory validation tests as baseline
59+
- Zod documentation for schema composition and custom refinements
60+
- Reviewer pass focused on behavioral parity

‎docs/ai/requirements/feature-validation-zod-migration.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
phase: requirements
3+
title: Validation Migration to Zod
4+
description: Replace hand-written validation logic with schema-based Zod validation
5+
---
6+
7+
# Requirements: Validation Migration to Zod
8+
9+
## Problem Statement
10+
11+
The codebase currently uses hand-written validation functions in multiple places (including `packages/memory` and `packages/cli`). This leads to duplicated patterns, inconsistent error handling shape, and higher maintenance overhead when validation rules evolve.
12+
13+
- **Who is affected?** Developers maintaining CLI and memory package input handling.
14+
- **Current workaround:** Add/modify custom validator functions per module.
15+
16+
## Goals & Objectives
17+
18+
**Primary goals:**
19+
- Standardize runtime validation using Zod schemas instead of ad-hoc functions.
20+
- Preserve current validation behavior and constraints (title/content lengths, tag/scope formats, query/limit boundaries).
21+
- Keep error outputs actionable and semantically compatible with existing CLI/MCP consumers.
22+
23+
**Secondary goals:**
24+
- Improve readability by co-locating schema and type intent.
25+
- Reduce duplication by reusing shared schema fragments.
26+
27+
**Non-goals:**
28+
- Changing business rules for what is considered valid input.
29+
- Rewriting unrelated non-validation logic.
30+
- Introducing a different validation library.
31+
32+
## User Stories & Use Cases
33+
34+
1. As a maintainer, I want validation rules defined in schemas so I can update constraints in one place.
35+
2. As a maintainer, I want consistent validation errors so CLI and MCP behavior remains predictable.
36+
3. As a contributor, I want tests around schema validation so refactors are safer.
37+
38+
**Key workflows:**
39+
- `memory store` validates input via Zod schema before persistence.
40+
- `memory update` validates partial updates via Zod schema before persistence.
41+
- `memory search` validates query/limit/scope via Zod schema before query execution.
42+
- CLI package validators validate registry/skill and related CLI input via Zod schema before command execution.
43+
44+
**Edge cases:**
45+
- Optional fields in update payloads should validate only when provided.
46+
- Multiple invalid fields should still produce clear aggregated error output.
47+
- Existing generic content checks should remain enforced (or be explicitly documented if removed).
48+
49+
## Success Criteria
50+
51+
1. Validation logic for custom validator paths in `packages/memory` and `packages/cli` is schema-based (Zod), not manually constructed field validators.
52+
2. Existing acceptance behavior remains stable for valid and invalid inputs.
53+
3. Test suite covers schema success paths and failure paths for all migrated inputs.
54+
4. No regression in CLI/MCP command contract for validation failures.
55+
5. Validation message text may change, but failure semantics remain equivalent.
56+
57+
## Constraints & Assumptions
58+
59+
- **Technical constraints:**
60+
- Existing error class patterns (`ValidationError`) should remain the public error type.
61+
- Current TypeScript and package structure must be preserved.
62+
- **Assumptions:**
63+
- User request "zoi" means **Zod**.
64+
- Migration scope includes both `packages/memory` and `packages/cli`.
65+
66+
## Questions & Open Items
67+
68+
- None at this stage.

‎docs/ai/testing/feature-validation-zod-migration.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
phase: testing
3+
title: Testing Strategy - Validation Migration to Zod
4+
description: Test plan for schema-based validation migration
5+
---
6+
7+
# Testing Strategy: Validation Migration to Zod
8+
9+
## Test Coverage Goals
10+
11+
- 100% coverage for new/changed validation code paths.
12+
- Regression coverage for existing invalid-input scenarios.
13+
14+
## Unit Tests
15+
16+
### `packages/memory/src/services/validator.ts`
17+
- [ ] Valid store payload passes
18+
- [ ] Invalid title/content/tags/scope fail with expected semantics
19+
- [ ] Update payload enforces id + at least one update field
20+
- [ ] Generic content phrase checks remain enforced (if retained)
21+
22+
### `packages/memory/src/handlers/search.ts`
23+
- [ ] Valid search payload passes
24+
- [ ] Invalid query length / invalid limit fail
25+
26+
## Integration Tests
27+
28+
- [ ] `memory store` rejects invalid inputs with `ValidationError`
29+
- [ ] `memory update` rejects invalid partial updates with `ValidationError`
30+
- [ ] `memory search` rejects invalid query payloads with `ValidationError`
31+
32+
## End-to-End Tests
33+
34+
- [ ] CLI flow: invalid input returns structured error output
35+
- [ ] CLI flow: valid input remains successful and unchanged
36+
37+
## Test Data
38+
39+
- Reuse current fixtures for title/content/tags/scope boundary values.
40+
41+
## Test Reporting & Coverage
42+
43+
- Run `npm run test --workspace=packages/memory`
44+
- Run workspace regression tests via root `npm run test`
45+
- Record any coverage gaps and rationale in this document
46+
47+
## Manual Testing
48+
49+
- Validate representative CLI commands for store/update/search error paths.
50+
51+
## Performance Testing
52+
53+
- Not expected to require dedicated load testing for this migration.
54+
55+
## Bug Tracking
56+
57+
- Track behavior mismatches (especially error text drift) as regressions.

0 commit comments

Comments
 (0)