Merge PR #68: add Zod schema contract package

Author: Cleanup Bot

packages/schemas/README.md

@@ -0,0 +1,17 @@
+# @cv-builder/schemas
+
+[Zod](https://zod.dev) schemas shared across CV Builder surfaces. Schemas are
+the source of truth; TypeScript types are inferred from them.
+
+Phase 1 requires that no LLM response is used without passing Zod validation,
+and that every `EvalResult` carries a `rubricVersion` and `archetypeVersion`.
+
+```ts
+import { EvalResultSchema, type EvalResult } from "@cv-builder/schemas";
+
+const result: EvalResult = EvalResultSchema.parse(rawModelOutput);
+```
+
+Exports: `Resume` / `ResumeSource`, `JobDescription`, `Archetype`,
+`EvaluationWeights`, `EvaluationDimension`, `Issue`, `Claim`, `EvalResult`
+(each with its `*Schema`). Evaluation types only — tailoring is Phase 2.

packages/schemas/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@cv-builder/schemas",
+  "version": "0.1.0",
+  "description": "Zod schemas and inferred types — the validated contract shared across CV Builder",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "cv",
+    "resume",
+    "zod",
+    "schema",
+    "types"
+  ],
+  "license": "MIT"
+}

packages/schemas/src/__tests__/schemas.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { ArchetypeSchema, EvalResultSchema, ResumeSchema } from "../index.js";
+
+const validEvalResult = {
+  rubricVersion: "1.0.0",
+  archetypeVersion: "1.0.0",
+  archetypeId: "software-engineer",
+  archetypeName: "Software Engineer",
+  score: 3.4,
+  dimensions: [
+    {
+      name: "Shipped Evidence",
+      weight: 0.3,
+      score: 4,
+      feedback: "Strong production work with named outcomes.",
+    },
+  ],
+  strengths: ["Clear quantified impact"],
+  issues: [
+    {
+      element: "Summary",
+      quote: "Passionate team player",
+      why: "Generic phrasing with no evidence.",
+      fix: "Replace with a concrete, measurable achievement.",
+      severity: "major",
+    },
+  ],
+  claims: [
+    {
+      text: "Scaled system to 1M users",
+      category: "metric",
+      supported: false,
+      reason: "No corroborating detail elsewhere in the resume.",
+    },
+  ],
+  atsCompatible: true,
+};
+
+describe("EvalResultSchema", () => {
+  it("parses a well-formed result", () => {
+    expect(() => EvalResultSchema.parse(validEvalResult)).not.toThrow();
+  });
+
+  it("rejects a malformed result", () => {
+    const bad = { ...validEvalResult, score: "high" };
+    expect(EvalResultSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("requires rubricVersion and archetypeVersion", () => {
+    for (const field of ["rubricVersion", "archetypeVersion"]) {
+      const partial = { ...validEvalResult };
+      delete (partial as Record<string, unknown>)[field];
+      const result = EvalResultSchema.safeParse(partial);
+      expect(result.success, `${field} should be required`).toBe(false);
+    }
+  });
+
+  it("rejects an out-of-range dimension score", () => {
+    const bad = {
+      ...validEvalResult,
+      dimensions: [{ ...validEvalResult.dimensions[0], score: 7 }],
+    };
+    expect(EvalResultSchema.safeParse(bad).success).toBe(false);
+  });
+});
+
+describe("ResumeSchema", () => {
+  it("applies array/object defaults from rawText alone", () => {
+    const resume = ResumeSchema.parse({ rawText: "Jane Doe — Engineer" });
+    expect(resume.links).toEqual([]);
+    expect(resume.skills).toEqual([]);
+    expect(resume.contact).toEqual({});
+  });
+});
+
+describe("ArchetypeSchema", () => {
+  it("requires at least one keyword", () => {
+    const archetype = {
+      id: "software-engineer",
+      name: "Software Engineer",
+      description: "Builds and ships software",
+      keywords: [],
+      evaluationWeights: {
+        shippedEvidence: 0.3,
+        quantifiedImpact: 0.2,
+        toolingVisibility: 0.2,
+        atsCompatibility: 0.1,
+        keywordMatch: 0.1,
+        publicProof: 0.1,
+      },
+      actionVerbs: ["Built"],
+      antiPatterns: ["familiar with"],
+      version: "1.0.0",
+    };
+    expect(ArchetypeSchema.safeParse(archetype).success).toBe(false);
+  });
+});

packages/schemas/src/archetype.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+export const EvaluationWeightsSchema = z.object({
+  shippedEvidence: z.number().min(0).max(1),
+  quantifiedImpact: z.number().min(0).max(1),
+  toolingVisibility: z.number().min(0).max(1),
+  atsCompatibility: z.number().min(0).max(1),
+  keywordMatch: z.number().min(0).max(1),
+  publicProof: z.number().min(0).max(1),
+});
+export type EvaluationWeights = z.infer<typeof EvaluationWeightsSchema>;
+
+// Weights are expected to sum to ~1.0, but that's enforced in the intelligence
+// layer so a half-edited archetype still parses here.
+export const ArchetypeSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string(),
+  keywords: z.array(z.string()).min(1),
+  evaluationWeights: EvaluationWeightsSchema,
+  actionVerbs: z.array(z.string()),
+  antiPatterns: z.array(z.string()),
+  version: z.string(),
+});
+export type Archetype = z.infer<typeof ArchetypeSchema>;

packages/schemas/src/evaluation.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+export const EvaluationDimensionSchema = z.object({
+  name: z.string(),
+  weight: z.number().min(0).max(1),
+  score: z.number().int().min(0).max(5),
+  feedback: z.string(),
+});
+export type EvaluationDimension = z.infer<typeof EvaluationDimensionSchema>;
+
+export const IssueSchema = z.object({
+  element: z.string(),
+  quote: z.string().optional(),
+  why: z.string(),
+  fix: z.string(),
+  severity: z.enum(["critical", "major", "minor"]),
+});
+export type Issue = z.infer<typeof IssueSchema>;
+
+export const ClaimSchema = z.object({
+  text: z.string(),
+  category: z.enum(["tool", "technology", "metric", "experience", "education", "other"]),
+  supported: z.boolean(),
+  reason: z.string(),
+});
+export type Claim = z.infer<typeof ClaimSchema>;
+
+// Versions are required so old results stay reproducible when the rubric or an
+// archetype changes later.
+export const EvalResultSchema = z.object({
+  rubricVersion: z.string(),
+  archetypeVersion: z.string(),
+  archetypeId: z.string(),
+  archetypeName: z.string(),
+  score: z.number().min(0).max(5),
+  dimensions: z.array(EvaluationDimensionSchema),
+  strengths: z.array(z.string()).default([]),
+  issues: z.array(IssueSchema).default([]),
+  claims: z.array(ClaimSchema).default([]),
+  atsCompatible: z.boolean(),
+  locale: z.string().optional(),
+});
+export type EvalResult = z.infer<typeof EvalResultSchema>;

packages/schemas/src/index.ts

@@ -0,0 +1,35 @@
+// Zod schemas are the source of truth; types are inferred from them.
+// Phase 1 ships evaluation types only — tailoring/rewrite is Phase 2.
+
+export {
+  type Archetype,
+  ArchetypeSchema,
+  type EvaluationWeights,
+  EvaluationWeightsSchema,
+} from "./archetype.js";
+export {
+  type Claim,
+  ClaimSchema,
+  type EvalResult,
+  EvalResultSchema,
+  type EvaluationDimension,
+  EvaluationDimensionSchema,
+  type Issue,
+  IssueSchema,
+} from "./evaluation.js";
+
+export { type JobDescription, JobDescriptionSchema } from "./job-description.js";
+export {
+  type Resume,
+  type ResumeContact,
+  ResumeContactSchema,
+  type ResumeEducation,
+  ResumeEducationSchema,
+  type ResumeExperience,
+  ResumeExperienceSchema,
+  type ResumeLink,
+  ResumeLinkSchema,
+  ResumeSchema,
+  type ResumeSource,
+  ResumeSourceSchema,
+} from "./resume.js";

packages/schemas/src/job-description.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+// Phase 1 uses the JD only as keyword-match context; fit-scoring is Phase 2.
+export const JobDescriptionSchema = z.object({
+  content: z.string(),
+  url: z.string().optional(),
+  company: z.string().optional(),
+  title: z.string().optional(),
+  keywords: z.array(z.string()).default([]),
+});
+export type JobDescription = z.infer<typeof JobDescriptionSchema>;

packages/schemas/src/resume.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+// Raw input as it arrives from a surface, before extraction.
+export const ResumeSourceSchema = z.object({
+  content: z.string(),
+  format: z.enum(["pdf", "markdown", "plaintext", "html"]),
+});
+export type ResumeSource = z.infer<typeof ResumeSourceSchema>;
+
+export const ResumeLinkSchema = z.object({
+  type: z.enum(["github", "linkedin", "portfolio", "blog", "website", "other"]),
+  url: z.string(),
+});
+export type ResumeLink = z.infer<typeof ResumeLinkSchema>;
+
+export const ResumeContactSchema = z.object({
+  email: z.string().optional(),
+  phone: z.string().optional(),
+  location: z.string().optional(),
+});
+export type ResumeContact = z.infer<typeof ResumeContactSchema>;
+
+export const ResumeExperienceSchema = z.object({
+  company: z.string(),
+  role: z.string(),
+  startDate: z.string().optional(),
+  endDate: z.string().optional(),
+  bullets: z.array(z.string()).default([]),
+});
+export type ResumeExperience = z.infer<typeof ResumeExperienceSchema>;
+
+export const ResumeEducationSchema = z.object({
+  institution: z.string(),
+  degree: z.string().optional(),
+  field: z.string().optional(),
+  year: z.string().optional(),
+});
+export type ResumeEducation = z.infer<typeof ResumeEducationSchema>;
+
+export const ResumeSchema = z.object({
+  name: z.string().optional(),
+  headline: z.string().optional(),
+  summary: z.string().optional(),
+  contact: ResumeContactSchema.default({}),
+  links: z.array(ResumeLinkSchema).default([]),
+  experience: z.array(ResumeExperienceSchema).default([]),
+  education: z.array(ResumeEducationSchema).default([]),
+  skills: z.array(z.string()).default([]),
+  // Original document, kept so downstream steps can quote exact source text.
+  rawText: z.string(),
+});
+export type Resume = z.infer<typeof ResumeSchema>;

packages/schemas/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/__tests__/**"]
+}

packages/schemas/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: "node",
+  },
+});