AGENTS.md · web-infra-dev/rsdoctor

Sections

1. Stack
2. Commands
3. Project structure
4. Code style
5. Testing
6. CI
7. Pull request conventions
8. Conventions for AI agents

First lines (shown under the repo's MIT license)

# 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.