Skip to content

Commit 8fe7386

Browse files
wrn14897wrn14897
committed
Add AGENTS.md with build, test, and code style guidelines for AI agents
1 parent 4697a88 commit 8fe7386

File tree

1 file changed

+199
-0
lines changed

1 file changed

+199
-0
lines changed

‎AGENTS.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# AGENTS.md — HyperDX JS SDK Monorepo
2+
3+
## Repository Overview
4+
5+
Monorepo for the HyperDX JavaScript/TypeScript SDKs built on OpenTelemetry.
6+
9 packages under `packages/` managed with **Yarn Classic** workspaces, **Nx** for
7+
task orchestration, and **Changesets** for versioning/publishing.
8+
9+
| Package | Name | Build Tool |
10+
| ----------------------------- | -------------------------------------- | ------------ |
11+
| `node-opentelemetry` | `@hyperdx/node-opentelemetry` | tsc |
12+
| `node-logger` | `@hyperdx/node-logger` | tsc |
13+
| `instrumentation-exception` | `@hyperdx/instrumentation-exception` | tsc |
14+
| `instrumentation-sentry-node` | `@hyperdx/instrumentation-sentry-node` | tsc |
15+
| `browser` | `@hyperdx/browser` | Rollup + TS |
16+
| `otel-web` | `@hyperdx/otel-web` | Rollup + tsc |
17+
| `session-recorder` | `@hyperdx/otel-web-session-recorder` | Rollup + tsc |
18+
| `cli` | `@hyperdx/cli` | tsup |
19+
| `deno` | `@hyperdx/deno` | Deno |
20+
21+
## Build Commands
22+
23+
```bash
24+
# Install dependencies (from repo root)
25+
yarn install
26+
27+
# Build all packages (respects dependency order via Nx)
28+
yarn ci:build # npx nx run-many --target=build
29+
30+
# Build a single package
31+
npx nx run @hyperdx/node-opentelemetry:build
32+
# Or from the package directory:
33+
cd packages/node-opentelemetry && yarn build
34+
35+
# Lint all packages
36+
yarn ci:lint # npx nx run-many --target=ci:lint
37+
38+
# Lint a single package (from its directory)
39+
cd packages/node-opentelemetry && yarn lint # ESLint only
40+
cd packages/node-opentelemetry && yarn ci:lint # ESLint + tsc --noEmit
41+
```
42+
43+
## Test Commands
44+
45+
Most packages use **Jest** with `ts-jest` (ESM preset). The `otel-web` package
46+
uses **Karma + Mocha** (browser) and **Mocha** (Node).
47+
48+
```bash
49+
# Run all unit tests across the monorepo
50+
yarn ci:unit # npx nx run-many --target=ci:unit
51+
52+
# Run tests in a single package
53+
cd packages/node-opentelemetry && npx jest
54+
cd packages/instrumentation-exception && yarn test
55+
cd packages/session-recorder && yarn test
56+
57+
# Run a single test file
58+
cd packages/node-opentelemetry && npx jest --testPathPattern="otel\\.test"
59+
60+
# Run tests matching a name pattern
61+
cd packages/node-opentelemetry && npx jest --testNamePattern="console"
62+
63+
# Watch mode
64+
cd packages/node-opentelemetry && yarn dev:unit # jest --watchAll
65+
cd packages/instrumentation-exception && yarn test:watch # jest --watch
66+
67+
# otel-web (Karma + Mocha, not Jest)
68+
cd packages/otel-web && yarn test:unit:ci-node # Mocha node tests
69+
cd packages/otel-web && yarn test:unit:ci # Karma browser tests (ChromeHeadless)
70+
```
71+
72+
### Smoke Tests (Docker + BATS)
73+
74+
```bash
75+
make build-smoke-images # docker compose build
76+
make smoke-sdk # run HTTP + gRPC smoke tests
77+
make smoke # run all BATS tests
78+
make resmoke # teardown + re-run
79+
```
80+
81+
## Code Style Guidelines
82+
83+
### Formatting — Prettier
84+
85+
- **Single quotes**, **trailing commas** everywhere, standard semicolons
86+
- Config in root `.prettierrc`
87+
- Enforced via pre-commit hook (`husky` + `lint-staged`)
88+
- Run manually: `yarn prettier` from any package directory
89+
90+
### Linting — ESLint
91+
92+
- Parser: `@typescript-eslint/parser`
93+
- Plugins: `@typescript-eslint`, `jest`, `prettier`, `simple-import-sort`
94+
- Key rules:
95+
- `simple-import-sort/imports`: **error** — imports must be sorted
96+
- `simple-import-sort/exports`: **error** — exports must be sorted
97+
- `@typescript-eslint/explicit-function-return-type`: **warn**
98+
- `prettier/prettier`: **error**
99+
100+
### Import Ordering
101+
102+
Imports are auto-sorted by `eslint-plugin-simple-import-sort`. The convention is:
103+
104+
```typescript
105+
// 1. External packages (alphabetical)
106+
import { diag, trace } from '@opentelemetry/api';
107+
import { InstrumentationBase } from '@opentelemetry/instrumentation';
108+
109+
// 2. Internal/relative imports (separated by blank line)
110+
import { name as PKG_NAME, version as PKG_VERSION } from '../package.json';
111+
import { parseHeaders } from './utils';
112+
```
113+
114+
### TypeScript
115+
116+
- **Strict mode** enabled (`strict: true`, `strictNullChecks: true`)
117+
- `noImplicitAny: false` — implicit `any` is tolerated
118+
- Target: `es2019`, Module: `commonjs`, ModuleResolution: `node`
119+
- Use `import type { ... }` for type-only imports
120+
- Browser packages produce dual CJS/ESM output
121+
122+
### Naming Conventions
123+
124+
| Element | Convention | Examples |
125+
| ----------------- | -------------------- | ------------------------------------- |
126+
| Files (classes) | PascalCase | `HyperDXBatchSpanProcessor.ts` |
127+
| Files (utils) | camelCase | `utils.ts`, `logger.ts` |
128+
| Classes | PascalCase | `Browser`, `ExceptionInstrumentation` |
129+
| Functions | camelCase | `initSDK`, `getWinstonTransport` |
130+
| Constants (env) | SCREAMING_SNAKE_CASE | `DEFAULT_HDX_API_KEY` |
131+
| Constants (other) | camelCase | `UI_LOG_PREFIX` |
132+
| Types/Interfaces | PascalCase | `SDKConfig`, `BrowserSDKConfig` |
133+
134+
### Exports
135+
136+
- Prefer **named exports**
137+
- The `@hyperdx/browser` package is the exception: it exports a singleton
138+
`new Browser()` as the default export
139+
140+
### Error Handling
141+
142+
- Use `try/catch` with `diag.error(...)` or `diag.debug(...)` for OpenTelemetry
143+
internal errors (from `@opentelemetry/api`)
144+
- Use `console.warn(...)` for user-facing warnings (e.g., missing API key)
145+
- Use `.catch(() => {})` for fire-and-forget optional integrations
146+
- Implement graceful shutdown: `SIGTERM`/`SIGINT` handlers with `forceFlush()`
147+
before process exit
148+
149+
### Testing Patterns
150+
151+
- Test files go in `src/__tests__/` or `__tests__/` directories
152+
- File naming: `*.test.ts` or `*.spec.ts`
153+
- Use `describe`/`it` blocks (Jest or Mocha)
154+
- Jest config uses `ts-jest` with ESM preset:
155+
```ts
156+
preset: 'ts-jest/presets/default-esm',
157+
transform: { '^.+\\.m?[tj]s?$': ['ts-jest', { useESM: true }] },
158+
```
159+
- Most tests are lightweight smoke tests; `node-opentelemetry` has the most
160+
comprehensive test suite (async context isolation, stream interception, etc.)
161+
162+
## Project Structure
163+
164+
```
165+
hyperdx-js/
166+
├── packages/
167+
│ ├── browser/ # Browser SDK (wraps otel-web + session-recorder)
168+
│ ├── cli/ # CLI for sourcemap uploads
169+
│ ├── deno/ # Deno SDK
170+
│ ├── instrumentation-exception/ # Exception capture instrumentation
171+
│ ├── instrumentation-sentry-node/ # Sentry integration for OTel
172+
│ ├── node-logger/ # Winston/Pino/NestJS logger transports
173+
│ ├── node-opentelemetry/ # Main Node.js OTel SDK
174+
│ ├── otel-web/ # Browser OTel RUM (forked from Splunk)
175+
│ └── session-recorder/ # Session recording (rrweb-based)
176+
├── smoke-tests/ # Docker + BATS integration tests
177+
├── nx.json # Nx workspace config (build caching, topological order)
178+
├── .prettierrc # Prettier config
179+
├── rollup.shared.js # Shared Rollup plugins for browser packages
180+
└── Makefile # Smoke test automation
181+
```
182+
183+
## CI/CD
184+
185+
- **Unit/lint** (`.github/workflows/unit.yaml`): Runs on push/PR to `main`.
186+
Uses Nx affected analysis. Steps: `yarn install` → `yarn ci:build` →
187+
`yarn ci:lint` → `yarn ci:unit`
188+
- **Smoke tests** (`.github/workflows/smoke.yaml`): Docker-based BATS tests
189+
- **Release** (`.github/workflows/release.yaml`): Changesets action creates
190+
release PRs or publishes. Supports `next` snapshot/canary releases.
191+
- **Pre-commit hook**: `lint-staged` runs `prettier --write` + `eslint --fix`
192+
on staged `.ts`/`.tsx` files
193+
194+
## Key Dependencies
195+
196+
- Node version: **v25** (specified in `.nvmrc`)
197+
- OpenTelemetry SDK packages (`@opentelemetry/*`) — core instrumentation layer
198+
- `rrweb` — session recording in the browser
199+
- `winston` / `pino` — logger transport targets in `node-logger`

0 commit comments

Comments
 (0)