rsdoctor

# AGENTS.md

## Stack

- Node.js `22.18+`, package manager **pnpm `12.6.0+`** (enable via `corepack enable`)
- `pnpm` workspace monorepo (topological build ordering)
- TypeScript strict mode
- Lint/format: **Rstack CLI** (`rs lint` backed by Rslint, `rs fmt` based on Prettier)
- Test runner: **Rstack CLI / Rstest** (`pnpm test`), E2E: **Playwright** (`pnpm e2e`)

## Commands

```bash
# ── bootstrap ────────────────────────────────────────────────
pnpm install                # install all deps + build all packages (prepare hook)

# ── quality checks ───────────────────────────────────────────
pnpm lint                   # rs lint (error-level only)
pnpm format                 # rs fmt
pnpm test                   # package tests via rs test (single worker, NODE_OPTIONS=--max-old-space-size=8192)
pnpm e2e                    # playwright e2e (requires chromium: cd e2e && npx playwright install chromium)

# ── build ────────────────────────────────────────────────────
pnpm run build                                # build all package targets in topological order
pnpm --filter '@rsdoctor/core...' run build   # build one package and its workspace dependencies

# ── focused dev ──────────────────────────────────────────────
pnpm --filter @rsdoctor/core run build     # build one package
pnpm --filter @rsdoctor/core run test      # test one package
pnpm -C packages/client build              # alternative: use directory path
```

## Project structure

```text
packages/
  shared/             # shared types, utilities, and module / chunk / package graphs
  core/               # Rspack plugin, analysis engine, rules, and server SDK
  cli/                # `rsdoctor` CLI binary
  agent-cli/          # `rsdoctor-agent` CLI for agent-facing report queries
  client/             # web client (Rsbuild SPA, serves analysis report and report UI)
  document/           # documentation site (Rspress)
scripts/
  config/             # shared Rslib, Rstest, and TypeScript configuration
  test-helper/        # test utilities shared across packages
e2e/                  # Rstest + Playwright E2E tests
examples/             # runnable Rspack / Rsbuild / Rspress projects
```

## Code style

- **Quotes**: single quotes everywhere; Prettier enforces formatting.
- **Naming**: `camelCase` for functions, variables, and file names; `PascalCase` for types, classes, interfaces, and enums.
- **Imports**: Rslint auto-organizes imports; use `import type` for type-only imports.
- **No default exports** in library packages unless re-exporting a config.
- Keep files focused; split large modules into sub-directories.

## Testing

- Unit tests live in `<package>/tests/` (file pattern: `*.test.ts`).
- Each tested package registers the shared `@scripts/config/test` options through `define.test()` in its Rstack config. Tests run with `maxWorkers: 1` (build-heavy tests are flaky in parallel).
- Snapshot serializer normalizes workspace paths (see `scripts/config/rstest.setup.ts`).
- E2E tests use Playwright; cases are organized per bundler under `e2e/cases/`.

## CI

- **Test (Ubuntu)**: Node 22.x on ubuntu-22.04, runs `pnpm run test:all` (unit + e2e).
- **Test (Windows)**: same matrix on windows.
- **Lint**: separate workflow runs `rs lint`.
- PRs targeting `main`, `release_*`, `release-*` trigger CI.
- Paths `packages/document/**` and `*.md` are excluded from test CI triggers.

## Pull request conventions

- Branch off `main`; never commit directly to `main`.
- PR title must follow **Conventional Commits**: `type(scope): description`.
- Common scopes: `core`, `rspack-plugin`, `shared`, `sdk`, `cli`, `agent-cli`, `ai`, `graph`, `utils`, `components`, `client`, `deps`.
- Read `.github/PULL_REQUEST_TEMPLATE.md` and follow its current headings and guidance.

## Conventions for AI agents

- Always run `pnpm install` first if `node_modules/` is missing.
- Before editing, build the target package to ensure the baseline is green.
- After making changes, run `pnpm --filter <pkg> run test` to validate.
- When fixing a bug, add or update a test case in `<package>/tests/`.
- Do not modify generated files under `dist/`, `compiled/`, or `node_modules/`.
- Do not modify `pnpm-lock.yaml` manually — run `pnpm install` to regenerate.
- Respect existing file structure; do not flatten sub-directories without reason.
- When creating new exports, update the `exports` field in `package.json` and ensure both CJS and ESM entries exist.

More agent context in web-infra-dev/rsdoctor

9 other files this repository gives its agents.