chore: add CI/publish workflows and improve README

- Add GitHub Actions CI workflow (Node 20.x, 22.x, 24.x)
- Add publish workflow (triggered by GitHub releases, supports beta tags)
- Rewrite README with proper markdown, full API docs, warnings table
- Add lcov coverage reporter for CI tools
- Add files field to package.json for clean npm publishes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kevinccbsg

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x, 24.x]
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Vitest
+        run: npm run test:ci

.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            npm publish --access public --tag beta
+          else
+            npm publish --access public
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -2,52 +2,159 @@
 
 Validate JSON payloads against OpenAPI 3.0/3.1 specs. Catch mock drift before it hits production.
 
-## Purpose
+## Why
 
 Frontend teams write mock responses in tests that drift from reality over time. Fields get renamed, removed, or added in the API but mocks stay frozen. Tests pass, code ships, and the app breaks in production.
 
 This package validates mock payloads against the OpenAPI spec — the source of truth. No YAML parsing, no URL fetching — consumers handle I/O, this package handles validation.
 
 ## Install
 
+```bash
 npm install openapi-mock-validator
+```
 
-## Usage
+## Quick Start
 
+```typescript
 import { OpenAPIMockValidator } from 'openapi-mock-validator';
+import fs from 'node:fs';
 
-// Consumers load the spec themselves (fetch, readFile, etc.)
+// Load the spec yourself (fetch, readFile, etc.)
 const spec = JSON.parse(fs.readFileSync('./openapi.json', 'utf-8'));
 
 const validator = new OpenAPIMockValidator(spec);
 await validator.init();
 
 // Match a mock URL to a spec path
 const match = validator.matchPath('/v1/orders/abc-123/status', 'GET');
-// { path: '/v1/orders/{id}/status', params: { id: 'abc-123' } }
+// → { path: '/v1/orders/{id}/status', params: { id: 'abc-123' } }
 
-// Validate mock response against the spec
-const result = validator.validateResponse(match.path, 'GET', 200, mockPayload);
-// { valid: false, errors: [...], warnings: [...] }
+if (match) {
+  // Validate the mock response against the spec
+  const result = validator.validateResponse(match.path, 'GET', 200, mockPayload);
+  // → { valid: false, errors: [...], warnings: [...] }
+}
+```
 
-// Validate request body
-const reqResult = validator.validateRequest('/v1/orders', 'POST', requestBody);
+## API
 
-## Options
+### `new OpenAPIMockValidator(spec, options?)`
 
-const validator = new OpenAPIMockValidator(spec, { strict: false });
-// strict (default: true) — reject additional properties not in spec
+Creates a validator instance. The spec must be a parsed OpenAPI 3.x JSON object.
 
-// Can also override per call:
+```typescript
+const validator = new OpenAPIMockValidator(spec, {
+  strict: true, // default: true — reject additional properties not in spec
+});
+```
+
+### `validator.init()`
+
+Dereferences all `$ref`s, normalizes OpenAPI 3.0 schemas to 3.1 format, and compiles path matchers. Must be called before any validation.
+
+```typescript
+await validator.init();
+```
+
+### `validator.matchPath(url, method)`
+
+Matches a URL against the spec's paths. Returns the matched spec path and extracted parameters, or `null`.
+
+```typescript
+const match = validator.matchPath('/v1/pets/abc-123', 'GET');
+// → { path: '/v1/pets/{petId}', params: { petId: 'abc-123' } }
+// → null if no match
+```
+
+- Strips trailing slashes and query strings automatically
+- Prefers literal path segments over parameterized ones (`/orders/pending` beats `/orders/{id}`)
+
+### `validator.validateResponse(path, method, status, payload, options?)`
+
+Validates a response payload against the schema defined in the spec.
+
+```typescript
+const result = validator.validateResponse('/v1/pets/{petId}', 'GET', 200, {
+  id: 1,
+  name: 'Fido',
+});
+```
+
+Returns:
+
+```typescript
+{
+  valid: boolean;
+  errors: ValidationError[];   // field-level mismatches
+  warnings: ValidationWarning[]; // undocumented status codes, missing schemas
+}
+```
+
+### `validator.validateRequest(path, method, payload, options?)`
+
+Validates a request body payload against the spec's `requestBody` schema.
+
+```typescript
+const result = validator.validateRequest('/v1/pets', 'POST', {
+  name: 'Fido',
+  tag: 'dog',
+});
+```
+
+### Per-call options
+
+Override the constructor's `strict` option per call:
+
+```typescript
 validator.validateResponse(path, method, status, payload, { strict: false });
+```
+
+## Errors and Warnings
+
+### Errors
+
+Returned when the payload doesn't match the schema:
+
+```typescript
+{
+  path: '/id',                    // JSON pointer to the field
+  message: 'must be integer',     // human-readable
+  keyword: 'type',                // AJV keyword
+  expected: 'integer',            // what the spec says
+  received: 'string',             // what the payload has
+}
+```
+
+### Warnings
+
+Returned when the validator can't fully validate — the payload isn't wrong, but it's not contract-tested either:
+
+| Type | When |
+|------|------|
+| `UNMATCHED_STATUS` | Status code not documented in the spec |
+| `MISSING_SCHEMA` | No schema defined for this path/method/status |
+| `EMPTY_SPEC_RESPONSE` | Response exists but has no `content` (e.g., 204) |
 
 ## OpenAPI Support
 
-- OpenAPI 3.0 — nullable fields normalized automatically
-- OpenAPI 3.1 — native JSON Schema Draft 2020-12
-- Full $ref resolution (nested, circular)
-- oneOf / anyOf / allOf composition
-- discriminator support
+- **OpenAPI 3.0** — `nullable` fields normalized to 3.1 format automatically
+- **OpenAPI 3.1** — native JSON Schema Draft 2020-12
+- **$ref resolution** — nested, deeply nested, components referencing components
+- **Composition** — `oneOf`, `anyOf`, `allOf` with full validation
+- **Discriminator** — `discriminator.propertyName` support
+- **Strict mode** — `additionalProperties: false` enforced by default
+
+### Known Limitation
+
+Strict mode (`additionalProperties: false`) can conflict with `allOf` schemas. When `allOf` branches define different properties, each branch rejects the other's properties as "additional." Use `{ strict: false }` for endpoints that use `allOf` composition, or define `additionalProperties` explicitly in your spec.
+
+## Design Decisions
+
+- **JSON only** — no YAML parsing, no URL fetching. Consumers handle I/O.
+- **Strict by default** — if the spec is the source of truth, mocks should match it exactly.
+- **Warnings, not silence** — undocumented status codes and missing schemas are surfaced, never silently skipped.
+- **Parse once, validate many** — the `init()` step is expensive (dereferencing, normalization, path compilation). Validation calls are fast.
 
 ## License
 

package.json

@@ -11,6 +11,9 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest",

vitest.config.ts

@@ -6,7 +6,7 @@ export default defineConfig({
     coverage: {
       provider: 'v8',
       include: ['src/**/*.ts'],
-      reporter: ['text', 'json', 'html'],
+      reporter: ['text', 'json', 'html', 'lcov'],
     },
   },
 });