mirror of
https://github.com/jakejarvis/rdapper.git
synced 2025-10-18 20:14:27 -04:00
40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- Source: `src/` (entry: `src/index.ts`).
|
||
- Protocol modules: `src/rdap/` and `src/whois/` (clients, normalize, helpers).
|
||
- Utilities: `src/lib/`, shared types: `src/types.ts`.
|
||
- Tests live beside code in `__tests__/` and use `*.test.ts`.
|
||
- Built output: `dist/` (ESM + types). Quick CLI: `cli.mjs` for manual checks.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `npm run build` — clean and compile TypeScript to `dist/`.
|
||
- `npm test` — type-check, build, and run Node’s test runner on `dist/**/*.test.js`.
|
||
- `npm run lint` — format and lint with Biome (auto-fixes).
|
||
- Manual smoke: `node cli.mjs example.com` (after `npm run build`).
|
||
- Network smoke tests (opt‑in): `SMOKE=1 npm test`.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- TypeScript strict, ESM (`module`/`moduleResolution: NodeNext`).
|
||
- Formatting via Biome: spaces, 2‑space indent, double quotes.
|
||
- Naming: functions/vars `camelCase`, types/interfaces `PascalCase`, constants `UPPER_SNAKE_CASE`.
|
||
- Files: lowercase; tests in `__tests__/` with `*.test.ts`.
|
||
- Prefer named exports; avoid default exports unless ergonomic.
|
||
|
||
## Testing Guidelines
|
||
- Framework: Node `node:test` + `assert/strict`.
|
||
- Unit tests must be deterministic and offline. Gate network tests behind `SMOKE=1`.
|
||
- Place tests near the code (e.g., `src/whois/__tests__/normalize.test.ts`).
|
||
- Run locally: `npm test`; for smoke: `SMOKE=1 npm test`.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Commits: concise imperative subject (e.g., “Add WHOIS referral fallback”), with a brief “what/why” body.
|
||
- Scope changes narrowly; keep diffs readable.
|
||
- PRs: clear description, linked issues, test plan (commands + expected output), and any CLI screenshots/logs when relevant.
|
||
- Required checks before PR: `npm run lint && npm test`.
|
||
|
||
## Security & Configuration Tips
|
||
- Node `>= 18.17`. No external HTTP client; uses global `fetch` and TCP 43 for WHOIS.
|
||
- Avoid hardcoding endpoints. Respect options: `timeoutMs`, `followWhoisReferral`, `rdapOnly`, `whoisOnly`.
|
||
- Do not run network tests in CI by default; use `SMOKE=1` only when appropriate.
|