feat(schemas): add Zod contract package

[amirbahador-hub]

Shared, validated contract for CV Builder surfaces: Resume, JobDescription,
Archetype, Issue, Claim, and EvalResult (with required rubric/archetype
versions).

Closes #47

What does this PR do?

surface (CLI/skills now, web + telegram later) speaks. Schemas are the source of truth; TypeScript types are inferred from them, so the runtime check and the compile-time type can't drift.

Exports: Resume / ResumeSource, JobDescription, Archetype,
EvaluationWeights, EvaluationDimension, Issue, Claim, EvalResult
(each with its *Schema).

Related issue

Closes #47

Type of change

• New feature

Checklist

• I've read CONTRIBUTING.md
• My code follows the project's style
• I've added/updated tests (if applicable)
• I've tested locally and it works
• New archetypes include 15+ keywords and source references

Screenshots (if UI change)

Before	After

Summary by CodeRabbit

• New Features

  • Added a shared schemas package exposing validated types for resumes, job descriptions, evaluations (dimensions/claims/issues/results), and archetypes.

• Documentation

  • Added README explaining schema usage, Phase 1 validation requirements, required fields, and a short validation example.

• Tests

  • Added unit tests covering schema parsing, required fields, value bounds, and defaulting behavior.

• Chores

  • Added package config, TypeScript build, and test tooling (Vitest) setup.

[Copilot]

Pull request overview

Adds a new @cv-builder/schemas workspace package that defines a shared runtime-validated contract (via Zod) for CV Builder surfaces (CLI now; web/telegram later), with TypeScript types inferred from schemas to prevent drift between runtime validation and compile-time types.

Changes:

• Introduces packages/schemas with Zod schemas for Resume, JobDescription, Archetype, and evaluation result types (Issue/Claim/EvalResult, etc.).
• Adds Vitest-based schema tests for parsing/validation behavior and required version fields.
• Updates pnpm-lock.yaml to include the new workspace package and its zod dependency.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds lockfile entries for the new packages/schemas importer and zod.
packages/schemas/vitest.config.ts	Adds Vitest config for the schemas package.
packages/schemas/tsconfig.json	Adds TS build config for emitting dist/* and excluding tests.
packages/schemas/src/resume.ts	Adds Resume-related Zod schemas and inferred types.
packages/schemas/src/job-description.ts	Adds JobDescription Zod schema and inferred type.
packages/schemas/src/index.ts	Adds public exports for schemas and inferred types.
packages/schemas/src/evaluation.ts	Adds evaluation-related Zod schemas and inferred types (dimension/issue/claim/result).
packages/schemas/src/archetype.ts	Adds Archetype + EvaluationWeights Zod schemas and inferred types.
packages/schemas/src/tests/schemas.test.ts	Adds Vitest tests to validate schema behavior.
packages/schemas/README.md	Documents package purpose and usage example.
packages/schemas/package.json	Declares the new @cv-builder/schemas package, scripts, and dependencies.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[amirbahador-hub]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 270d5b64-7e20-497a-942d-59248784cee1

📥 Commits

Reviewing files that changed from the base of the PR and between 6748d7e and ab36770.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml, !**/pnpm-lock.yaml

📒 Files selected for processing (3)

• packages/schemas/src/__tests__/schemas.test.ts
• packages/schemas/src/evaluation.ts
• packages/schemas/src/index.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/schemas/src/tests/schemas.test.ts
• packages/schemas/src/evaluation.ts

---

📝 Walkthrough

Walkthrough

Adds a new @cv-builder/schemas package: Zod schemas and inferred TypeScript types for evaluation, archetype, resume, and job-description domains; package tooling (package.json, tsconfig, Vitest); a central re-export index; schema validation tests; and a README documenting Phase 1 usage and exported types.

Changes

Zod Schemas Foundation

Layer / File(s)	Summary
Package configuration & tooling packages/schemas/package.json, packages/schemas/tsconfig.json, packages/schemas/vitest.config.ts	Adds package metadata, ESM exports, build/test scripts, TypeScript project config targeting dist/, and Vitest config using the Node environment.
Evaluation & Archetype Schemas packages/schemas/src/evaluation.ts, packages/schemas/src/archetype.ts	Introduces EvaluationDimensionSchema, IssueSchema, ClaimSchema, EvalResultSchema with bounded numeric fields and required rubricVersion/archetypeVersion, plus EvaluationWeightsSchema and ArchetypeSchema with keyword and weight constraints.
Resume & Job Description Schemas packages/schemas/src/resume.ts, packages/schemas/src/job-description.ts	Adds nested resume schemas (ResumeSourceSchema, ResumeLinkSchema, ResumeContactSchema, ResumeExperienceSchema, ResumeEducationSchema, ResumeSchema) with defaults and JobDescriptionSchema.
Central export module packages/schemas/src/index.ts	Creates a unified public API by re-exporting all schemas and inferred types from the submodules.
Schema validation tests packages/schemas/src/__tests__/schemas.test.ts	Adds tests verifying parsing of valid EvalResult, enforcement of required version fields, numeric/range constraints, default application for resume fields, and archetype keyword constraints.
Package documentation packages/schemas/README.md	Documents that Zod schemas are the source of truth, Phase 1 validation requirements for LLM outputs, lists exported schemas/types, and shows an EvalResultSchema.parse(...) example.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• alexNJF
• rfatideh

"🐰
I stitched each schema, neat and small,
Types inferred straight from Zod's call,
Tests to guard the shapes tonight,
Docs to show the schema light,
Hoppity hops — the package stands tall!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR partially addresses issue #47 by creating shared Zod schemas for Resume, JobDescription, Archetype, and EvaluationWeights types, but does not convert the core/types.ts file itself or implement all 15 required types.	Convert packages/core/src/types.ts to use Zod schemas instead of plain interfaces, and implement all 15 types specified in issue #47 (EvaluationDimension, Issue, Rewrite, EvaluationResult, TailoredCV, CVChange, Suggestion, RoleArchetype, EvaluationWeights, CVInput, JobDescription, EvaluateOptions, TailorOptions, LLMProvider, ProviderConfig).

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: introducing a new Zod-based schemas package for CV Builder with defined validation contracts.
Out of Scope Changes check	✅ Passed	All changes are scope-aligned: creating a shared schemas package with Zod validation, README documentation, tests, and TypeScript configuration are all foundational work toward the referenced issue #47 objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/schemas-zod-contract

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/schemas/src/evaluation.ts`:
- Around line 3-9: The EvaluationDimensionSchema currently validates score and
maxScore independently, allowing score > maxScore; update
EvaluationDimensionSchema to add a schema-level refinement (e.g., .refine or
.superRefine on the z.object) that checks score <= maxScore and returns a clear
path-specific error (attach to "score" or use ctx.addIssue) when violated; keep
existing field validators (name, weight, maxScore default) but remove any
hard-coded static .max on score if it conflicts with dynamic maxScore validation
and ensure the refinement runs after parsing to enforce the invariant.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8c88bb06-b5c7-4b69-810b-6f0b1b6b4e92

📥 Commits

Reviewing files that changed from the base of the PR and between 1e258e6 and f16790b.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (10)

• packages/schemas/README.md
• packages/schemas/package.json
• packages/schemas/src/__tests__/schemas.test.ts
• packages/schemas/src/archetype.ts
• packages/schemas/src/evaluation.ts
• packages/schemas/src/index.ts
• packages/schemas/src/job-description.ts
• packages/schemas/src/resume.ts
• packages/schemas/tsconfig.json
• packages/schemas/vitest.config.ts

[rfatideh]

The types look good now. I think at this stage, we can’t be much more confident in them. We can always extend them later if we discover new use cases.

[SaharPak]

Thanks for the Zod schemas contract package! This is now in the MVP integration branch. It's the foundation everything else builds on — types are now derived from Zod schemas. Solid work!