Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (68 loc) · 3.89 KB

CLAUDE.md

File metadata and controls

95 lines (68 loc) · 3.89 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Prism is an open-source API mocking and contract testing platform supporting OpenAPI v2/v3.0/v3.1 and Postman Collections. It provides a mock server and validation proxy.

Common Commands

# Install dependencies
npm ci

# Build (clean + compile TypeScript)
npm run build

# Run all tests
npm test

# Run tests for a specific package or file
npm test -- --testPathPattern="core"
npm test -- packages/http/src/__tests__/client.spec.ts

# Lint
npm run lint
npm run lint.fix

# Run CLI directly during development (from packages/cli)
cd packages/cli && npm run cli -- mock openapi.yaml

# Debug CLI (attaches Node inspector)
cd packages/cli && npm run cli:debug -- mock file.oas.yml

# Build binary
npm run build.binary

# Integration/harness tests (requires build.binary first)
npm run test.harness

Architecture

This is a Lerna monorepo with npm workspaces. Packages have a strict layering:

packages/
├── core/         # Base abstractions: routing, validation, mocking contracts
├── http/         # HTTP-specific: mocker, validator, forwarder, router, negotiator
├── http-server/  # HTTP server using Micri; wires http/ into a running server
└── cli/          # CLI entry point using Yargs; commands: mock, proxy

Data flow: CLI → HTTP-Server → HTTP (mocker/validator/forwarder/router) → Core

Key Design Patterns

  • fp-ts throughout: The codebase uses Either, TaskEither, Reader, and Option from fp-ts for error handling and dependency injection. Expect functional-style pipelines via pipe().
  • IPrismConfig / IHttpConfig: Central config objects passed as dependencies control behavior (dynamic mocking, validation strictness, proxy mode).
  • Pino structured logging: A logger instance is passed as a context through nearly all operations.
  • Mocker pipeline (packages/http/src/mocker/): Negotiates content type → selects example or generates with json-schema-faker → applies callbacks.
  • Validator pipeline (packages/http/src/validator/): AJV-based validation for request/response bodies, headers, path/query params.

Important Files

File Purpose
packages/core/src/factory.ts Creates Prism instances
packages/http/src/client.ts HTTP client factory
packages/http/src/mocker/index.ts Mock response generation entrypoint
packages/http/src/validator/index.ts Validation entrypoint
packages/http/src/router/index.ts Matches requests to OpenAPI operations
packages/http/src/forwarder/index.ts Upstream proxy forwarding
packages/cli/src/commands/ mock and proxy CLI command implementations
packages/http-server/src/index.ts HTTP server setup

Testing

  • Tests live in __tests__/ directories alongside source files, named *.spec.ts or *.test.ts
  • Jest projects are scoped per package: HTTP-SERVER, HTTP, CORE, CLI
  • nock is used for HTTP mocking in tests
  • Harness tests (packages/cli/src/__tests__/harness/) test the compiled binary end-to-end

Code Style

  • Prettier: 120-char line width, single quotes, trailing commas (es5)
  • ESLint with @typescript-eslint — lint-staged auto-fixes on commit via Husky
  • Arrow functions: omit parens for single parameter
  • TypeScript strict mode; ttypescript (ttsc) is used for compilation with custom transformers

Branch & Release

  • Feature branches: feature/*, chore/*, fix/*
  • Releases managed via Lerna (npm run release)
  • Node.js minimum: 18.20.1