Contributing

Development setup

Fork and clone

git clone https://github.com/sqrcz/numerik-js.git
cd numerik-js

Install dependencies
Terminal window
```
pnpm install
```
Run the test suite
Terminal window
```
pnpm test
```

Local checks

Command	What it runs
`pnpm test`	Vitest test suite
`pnpm test:watch`	Vitest in watch mode
`pnpm test:cover`	Vitest with coverage
`pnpm typecheck`	`tsc --noEmit`
`pnpm lint`	Biome lint + format check
`pnpm lint:fix`	Biome lint + format — auto-fix
`pnpm build`	Compile to `dist/`
`pnpm check`	`typecheck` + `lint` + `test` in sequence

Run pnpm check before opening a PR to catch all issues locally.

Adding a new identifier

Adding a new identifier requires touching several files. PRs missing any item will not be merged:

Create src/value-objects/NewIdentifier.ts (implements IdentifierInterface)
Create src/identifiers/NewIdentifierIdentifier.ts (implements both ValidatorInterface and ParserInterface; accepts strict: boolean = true)
Add new ValidationFailureReason cases if the identifier introduces new failure types
Add an entry to src/Numerik.ts and export it from src/index.ts
Add Zod schemas to src/zod/index.ts
Add tests/new-identifier.test.ts
Add an identifier page under docs/src/content/docs/identifiers/
Update CHANGELOG.md

Branch naming

Type	Pattern	Example
Feature	`feat/<short-name>`	`feat/passport-identifier`
Fix	`fix/<short-name>`	`fix/pesel-century-calc`
Chore	`chore/<short-name>`	`chore/update-dependencies`

Commit style

Use Conventional Commits:

feat: add PassportIdentifier
fix: correct PESEL century calculation for 2000s
docs: update REGON algorithm description
test: add NIP fixtures for invalid tax office codes
chore: bump vitest to 4.x
refactor: extract checksum calculation to dedicated method

Pull request process

Fork the repository and create your branch from main.
Add tests for any new behaviour — all tests must pass.
Ensure pnpm check passes.
Open a PR against main and fill in the template completely.

Reporting a bug

Use the Bug Report template on GitHub.

Security vulnerabilities

Do not open a public issue. Report via GitHub’s private advisory system. See SECURITY.md.