# Contributing to `express-rest-decorators`

Thanks for your interest in contributing! This document covers the dev loop, commands, and release flow.

## Prerequisites

- **Node.js** ≥ 20.0.0 (Node 22 LTS recommended; Node 24 also supported in CI).
- **pnpm 10** — enable via Corepack:

  ```bash
  corepack enable
  corepack prepare pnpm@10 --activate
  ```

- A POSIX shell (the build/test scripts assume bash/zsh on macOS or Linux). Windows users should use WSL2.

## Setup

```bash
git clone https://github.com/nirajk77777/express-rest-decorators.git
cd express-rest-decorators
pnpm install --frozen-lockfile
```

## Development Workflow

The project is a **single-package repo** — no `packages/`, no workspaces. Source lives in `src/`, tests live next to the code as `*.test.ts`, build output goes to `dist/{esm,commonjs}/` via [tshy](https://github.com/isaacs/tshy).

| Command | Purpose |
|---|---|
| `pnpm test:forks` | Run the full Vitest suite under the `forks` pool (process isolation; required green). |
| `pnpm test:threads` | Run the full Vitest suite under the `threads` pool (worker-thread isolation; required green). |
| `pnpm test:watch` | Re-run tests on file change. |
| `pnpm typecheck` | Run `tsc --noEmit` against the whole repo. |
| `pnpm lint` | Run Biome 2 (`biome check .`) — lint + format check, no writes. |
| `pnpm lint:fix` | Run Biome with `--write`; applies safe fixes. |
| `pnpm build` | Build dual ESM + CJS via tshy into `dist/`. |
| `pnpm test:build` | Verify the built artifacts (smoke imports, exports check). |
| `pnpm docs:build` | Generate TypeDoc HTML into `docs/` (configured in `typedoc.json`). |

**Both pool variants must pass** (`test:forks` AND `test:threads`). CI enforces this — local-only runs against one pool are not sufficient.

## Submitting Changes

1. Open a PR against `main`. Branch naming is up to you; concise prefixes like `fix/`, `feat/`, `docs/` are appreciated.
2. CI runs the matrix **Node 20 / 22 / 24 × forks + threads** on every PR. All cells must be green before review.
3. **Add a changeset** for any user-visible change (any change that ships in `dist/`):

   ```bash
   pnpm changeset add
   ```

   Pick `patch` / `minor` / `major` per [semver](https://semver.org/) and write a short summary. Internal-only changes (CI, docs, tests) can skip the changeset.

4. Keep PRs focused. Drive-by refactors of unrelated files inflate review burden.

## Code Style

- **Biome 2** is the single formatter + linter (`pnpm lint` / `pnpm lint:fix`). The config lives in `biome.json`.
- Legacy parameter decorators are enabled in Biome via `unsafeParameterDecoratorsEnabled: true` — required for the `experimentalDecorators` workflow this library is built on.
- Tab/space and import-ordering rules are all enforced by Biome; do not hand-format.

### ESLint 9 Fallback (BUILD-09 fallback)

Biome 2's decorator-aware lint coverage is intentionally narrow. If we hit a decorator-specific lint rule that Biome cannot express, the documented fallback is **ESLint 9 + `@typescript-eslint` 8 + Prettier 3**:

```bash
pnpm add -D \
  eslint@9 \
  @typescript-eslint/eslint-plugin@8 \
  @typescript-eslint/parser@8 \
  eslint-config-prettier \
  prettier@3
```

This recipe is documented but **not active** in v1 — the v1 release ships with Biome only. The fallback exists so the project can switch lanes without a research detour if a real decorator-rule gap appears.

## Repo Structure

This is a **single-package repo** by explicit project policy:

- One `package.json` at the root.
- One `src/` tree → one `dist/` tree.
- Optional features (`multer`, `cors`, `cookie`, `express-session`, `tinyglobby`) are **runtime peer dependencies**, not separate npm packages. Container integrations (TypeDI, tsyringe, Awilix, InversifyJS) are documented as **recipes** in the README, not published as `express-rest-decorators-typedi` style packages.
- `dist/esm/` and `dist/commonjs/` are generated by tshy from `src/`. Never edit `dist/` by hand.

The `.github/workflows/ci.yml` matrix exercises Node 20 / 22 / 24 × forks + threads. The `.github/workflows/release.yml` workflow (added in plan 05-06) handles npm publish + provenance + TypeDoc → GitHub Pages.

## Releases

Releases are **maintainer-only**. The flow:

1. PRs land on `main` with changesets attached.
2. The Changesets bot opens a "Version Packages" PR aggregating pending changesets, bumping `package.json`, and updating `CHANGELOG.md`.
3. Merging the Version Packages PR triggers `release.yml`, which runs `pnpm build`, `attw --pack`, `publint`, and `changeset publish --provenance`.
4. The same workflow rebuilds TypeDoc and publishes it to GitHub Pages.

The v1.0.0 release uses the `next` dist-tag for RCs (`pnpm install express-rest-decorators@next`). Once `1.0.0` ships, `next` is retired and the package promotes to `latest`.

## Reporting Bugs / Requesting Features

Open an issue at <https://github.com/nirajk77777/express-rest-decorators/issues>. Please include:

- Node version (`node -v`)
- Library version (`pnpm list express-rest-decorators`)
- Express version (`pnpm list express`)
- A minimal reproduction (a failing test case is ideal).

Thanks for helping make this library better!