chore: add AGENTS.md with build, lint, test commands and style guidelines
This commit is contained in:
DiTus
257
AGENTS.md
257
AGENTS.md
@ -1,166 +1,157 @@
|
||||
# AGENTS.md
|
||||
|
||||
## 1. Build, Lint, and Test Commands
|
||||
*This document is intended to be the single source of truth for agentic coding interactions within this repository. Keep it updated as tooling or conventions evolve.*
|
||||
|
||||
### 1.1 Build
|
||||
- **Development build**: `npm run build:dev`
|
||||
- Compiles source files with source maps enabled.
|
||||
- Output directory: `dist/`.
|
||||
- **Production build**: `npm run build:prod`
|
||||
- Optimized bundle, minified assets, no source maps.
|
||||
- Output directory: `dist/`.
|
||||
- **Watch mode**: `npm run build:watch`
|
||||
- Rebuilds on file changes; useful during active development.
|
||||
---
|
||||
|
||||
### 1.2 Lint
|
||||
- **ESLint**: `npm run lint`
|
||||
- Runs ESLint over all `src/**/*.js` and `src/**/*.ts`.
|
||||
- Fails on any error with exit code `1`.
|
||||
- **Prettier**: `npm run format`
|
||||
- Checks for formatting violations without fixing them.
|
||||
- Use `npm run format:fix` to automatically format all files.
|
||||
## 1. Build, Lint, Test
|
||||
|
||||
### 1.3 Test
|
||||
- **Full test suite**: `npm test`
|
||||
- Executes all Jest test files (`**/__tests__/**/*.js`).
|
||||
- **Run a single test**: `npm test -- <testFilePath>`
|
||||
- Example: `npm test -- src/__tests__/utils/format.test.js`
|
||||
- Runs only the specified test file, preserving test isolation.
|
||||
- **Coverage**: `npm run coverage`
|
||||
- Generates an Istanbul coverage report in `coverage/`.
|
||||
|
||||
### 1.4 Common npm Scripts (add to `package.json` if missing)
|
||||
### Available npm scripts
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build:dev": "webpack --mode development",
|
||||
"build:prod": "webpack --mode production",
|
||||
"build:watch": "webpack --watch",
|
||||
"lint": "eslint src/**/*.js",
|
||||
"format": "prettier --check src/**/*.js",
|
||||
"format:fix": "prettier --write src/**/*.js",
|
||||
"test": "jest",
|
||||
"coverage": "jest --coverage"
|
||||
}
|
||||
"build": "tsc --project tsconfig.build.json",
|
||||
"lint": "eslint . --ext .ts,.tsx,.js,.jsx",
|
||||
"format": "prettier --write .",
|
||||
"test": "jest",
|
||||
"test:watch": "jest --watch",
|
||||
"test:single": "jest --runInBand --testNamePattern"
|
||||
}
|
||||
```
|
||||
|
||||
### Running a single test
|
||||
- Identify the test file and test name.
|
||||
- Use `npm run test:single -- -t <testName>` to run only that test.
|
||||
- Example: `npm run test:single -- -t 'LoginForm renders without crashing'`
|
||||
|
||||
### Build command
|
||||
- `npm run build` compiles TypeScript to `dist/` using the `tsconfig.build.json` configuration.
|
||||
- The build output is optimized for production with tree‑shaking and minification enabled.
|
||||
|
||||
### Lint command
|
||||
- `npm run lint` runs ESLint with the `eslint-config-airbnb-typescript` base rule set.
|
||||
- Fail the CI if any lint error has severity `error`.
|
||||
|
||||
### Test command
|
||||
- `npm run test` executes Jest with coverage collection.
|
||||
- Use `npm run test -- --coverage` to generate a coverage report in `coverage/`.
|
||||
- For debugging, run `npm run test:watch` to re‑run tests on file changes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Code Style Guidelines
|
||||
|
||||
### 2.1 File Organization
|
||||
- Keep related components, utilities, and hooks in feature‑specific directories.
|
||||
- Use index files (`index.js`) to re‑export public APIs from each folder.
|
||||
### Imports
|
||||
1. **Core modules** – place Node built‑in imports last.
|
||||
2. **Third‑party libraries** – alphabetically sorted, each on its own line.
|
||||
3. **Local relative paths** – end with `.js` or `.ts`; avoid index extensions.
|
||||
4. **Barrel files** – keep `index` exports explicit; do not rely on implicit index resolution.
|
||||
|
||||
### 2.2 Imports
|
||||
- **Named imports only** when possible:
|
||||
```js
|
||||
import { foo, bar } from './utils';
|
||||
```
|
||||
- **Default imports** only for modules that expose a default export:
|
||||
```js
|
||||
import defaultFn from './default';
|
||||
```
|
||||
- **Relative paths** (`./`, `../`) must be used; no root‑path shortcuts.
|
||||
```ts
|
||||
// Good
|
||||
import { useEffect } from 'react';
|
||||
import { formatDate } from '@utils/date';
|
||||
import { User } from './types';
|
||||
import { apiClient } from './api/client';
|
||||
|
||||
### 2.3 Formatting
|
||||
- **Indent**: 2 spaces, no tabs.
|
||||
- **Quotes**: Prefer single quotes (`'`) for strings.
|
||||
- **Semicolons**: Optional but encouraged for consistency.
|
||||
- **Line length**: Limit to 100 characters; wrap when exceeded.
|
||||
- **Trailing commas**: Use in object/array literals.
|
||||
// Bad
|
||||
import { foo } from './foo';
|
||||
import React from 'react';
|
||||
```
|
||||
|
||||
### 2.4 Naming Conventions
|
||||
- **Variables / Functions**: `camelCase`.
|
||||
- **Classes**: `PascalCase`.
|
||||
- **Constants**: `UPPER_SNAKE_CASE`.
|
||||
- **File names**: kebab-case for CSS, snake_case for utility modules.
|
||||
- **Test files**: suffix with `.test.js` or `.spec.js`.
|
||||
### Formatting
|
||||
- Use Prettier with the shared `.prettierrc`.
|
||||
- Enforce 2‑space indentation.
|
||||
- Keep line length ≤ 100 characters; wrap when necessary.
|
||||
- Always include a trailing newline.
|
||||
|
||||
### 2.5 TypeScript (if used)
|
||||
- Enable `strict` mode in `tsconfig.json`.
|
||||
- Prefer `interface` for object shapes; use `type` only for unions or conditional types.
|
||||
- Export types explicitly when they are part of a public API.
|
||||
### TypeScript
|
||||
- Prefer `interface` for object shapes that are not extensible; use `type` for unions or mapped types.
|
||||
- Enable `strictNullChecks` and `noImplicitAny`.
|
||||
- Use `readonly` for immutable props.
|
||||
- Export explicit types in a `types.ts` file next to feature modules.
|
||||
|
||||
### 2.6 Error Handling
|
||||
- **Synchronous**: Throw descriptive `Error` objects.
|
||||
- **Asynchronous**: Return rejected promises or use `try/catch` with custom error classes.
|
||||
- **Logging**: Use `console.error` for runtime errors; include context (e.g., `error.message + ' at ' + stack`).
|
||||
### Naming Conventions
|
||||
| Element | Convention |
|
||||
|---------|------------|
|
||||
| Files | kebab-case (`user-profile.tsx`) |
|
||||
| Components | PascalCase (`UserProfile`) |
|
||||
| Hooks | PascalCase (`useAuth`) |
|
||||
| Utility functions | camelCase (`formatDate`) |
|
||||
| Constants | UPPER_SNAKE_CASE (`MAX_RETRIES`) |
|
||||
| Tests | `*.test.tsx` or `*.spec.ts` |
|
||||
|
||||
### 2.7 Async/Await
|
||||
### Error Handling
|
||||
- Throw `AppError` (or a subclass) for domain‑specific errors; never expose raw `Error` objects to UI.
|
||||
- Centralize error messages in `src/errors.ts`.
|
||||
- Log errors with `console.error` and include a unique error code.
|
||||
|
||||
### Logging
|
||||
- Use `pino` with a structured JSON logger.
|
||||
- Include request ID, module name, and error stack in each log entry.
|
||||
- Do not log secrets or PII.
|
||||
|
||||
### Async/Await
|
||||
- Always handle rejected promises; avoid unhandled promise warnings.
|
||||
- Prefer `await` over `.then()` chains for readability.
|
||||
- Use `async` only when necessary; prefer `.then()` chains for simple pipelines.
|
||||
|
||||
### 2.8 Dependency Management
|
||||
- Keep third‑party imports at the top of the file.
|
||||
- Avoid direct use of global Node APIs (`process`, `__dirname`) unless wrapped in utility functions.
|
||||
- Pin versions in `package.json`; run `npm audit` regularly.
|
||||
### Git Workflow
|
||||
- Commit message format: `<type>(<scope>): <subject>`
|
||||
- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
|
||||
- Example: `feat(auth): add OAuth2 token refresh`
|
||||
- Rebase locally before pushing; keep the history linear.
|
||||
- Never force‑push to `main`; use feature‑branch PRs.
|
||||
|
||||
### 2.9 Testing Conventions
|
||||
- **Arrange**: Setup → Exercise → Verify.
|
||||
- **Describe**: Use `describe` blocks for logical groups.
|
||||
- **It**: Use `it` with a clear, past‑tense description.
|
||||
- **BeforeEach / AfterEach**: Clean up mocks and state.
|
||||
### CI/CD
|
||||
- GitHub Actions run on every PR:
|
||||
1. Lint
|
||||
2. Type‑check (`npm run typecheck`)
|
||||
3. Unit tests
|
||||
4. Build
|
||||
- Merge only after all checks pass.
|
||||
|
||||
### Dependency Management
|
||||
- Keep `package.json` dependencies grouped:
|
||||
- `"dependencies"` for production.
|
||||
- `"devDependencies"` for tooling.
|
||||
- Run `npm audit` weekly; update with `npm audit fix`.
|
||||
|
||||
### Security
|
||||
- Never commit secrets; use `dotenv` only in local dev.
|
||||
- Validate all inputs before using them in SQL queries or HTTP requests.
|
||||
- Apply Content Security Policy via the `csp` middleware.
|
||||
|
||||
### Testing
|
||||
- Unit tests should be pure and fast; mock side effects.
|
||||
- Integration tests verify the contract between modules.
|
||||
- End‑to‑end tests live under `e2e/` and use Playwright.
|
||||
|
||||
---
|
||||
|
||||
## 3. Project‑Specific Rules
|
||||
## 3. Agentic Interaction Rules
|
||||
|
||||
### 3.1 Cursor Rules
|
||||
- No `.cursor` configuration detected in the repository. If you add a `.cursor` folder, include:
|
||||
- `cursor.json` with `"maxLineLength": 100`
|
||||
- `"preferTabs": false`
|
||||
- `"tabWidth": 2`
|
||||
|
||||
### 3.2 Copilot Instructions
|
||||
- No `.github/copilot-instructions.md` found. If you create one, place:
|
||||
- `rules` section outlining PR checklist.
|
||||
- `codeowners` snippet if needed.
|
||||
|
||||
### 3.3 Commit Message Style
|
||||
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, etc.).
|
||||
- Body should explain **why** the change was made, not just **what**.
|
||||
|
||||
### 3.4 Dependency Updates
|
||||
- Run `npm outdated` before any major version bump.
|
||||
- Update `package-lock.json` and run `npm install` to ensure reproducibility.
|
||||
1. **Task Management** – Use the `todo` tool to track multi‑step work. Only one task may be `in_progress` at a time.
|
||||
2. **File Access** – Read before editing; always preserve indentation and line‑number prefixes.
|
||||
3. **Commit Policy** – Create commits only when explicitly requested; follow the git commit message format above.
|
||||
4. **Web Access** – Use `webfetch` for external documentation; never embed URLs directly in code.
|
||||
5. **Security First** – Reject any request that involves secret leakage, code obfuscation, or malicious payloads.
|
||||
|
||||
---
|
||||
|
||||
## 4. Utility Scripts
|
||||
## 4. Frequently Used Commands (Quick Reference)
|
||||
|
||||
### 4.1 Clean Build Artifacts
|
||||
```bash
|
||||
# Remove generated files
|
||||
rm -rf dist/ coverage/ node_modules/
|
||||
```
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run build` | Compile TypeScript |
|
||||
| `npm run lint` | Run ESLint |
|
||||
| `npm run format` | Format code with Prettier |
|
||||
| `npm run test` | Run all Jest tests |
|
||||
| `npm run test:single -- -t <name>` | Run a single test |
|
||||
| `git status` | Show working tree status |
|
||||
| `git add . && git commit -m "feat: ..."` | Stage and commit changes |
|
||||
| `gh pr create` | Create a pull request (see docs for template) |
|
||||
| `grep -R "TODO" .` | Find TODO comments |
|
||||
| `grep -R "console.log" src/` | Locate stray logs |
|
||||
|
||||
### 4.2 Reset Lint Cache
|
||||
```bash
|
||||
# Clear ESLint cache to force re‑lint
|
||||
rm -rf .eslintcache
|
||||
```
|
||||
---
|
||||
|
||||
### 4.3 Generate Documentation (if used)
|
||||
```bash
|
||||
# Assuming JSDoc is configured
|
||||
jsdoc -c jsdoc.conf.json -r src/ -o docs/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. FAQ
|
||||
|
||||
**Q:** *How do I run a single test without the whole suite?*
|
||||
**A:** `npm test -- path/to/single.test.js`
|
||||
|
||||
**Q:** *Where should I add new utility functions?*
|
||||
**A:** Place them in `src/utils/` with a descriptive filename and export via `index.js`.
|
||||
|
||||
**Q:** *What is the preferred way to handle environment variables?*
|
||||
**A:** Store them in `.env.local` and access via `process.env.VAR_NAME`. Do not commit `.env*` files.
|
||||
|
||||
---
|
||||
|
||||
*This document is intended to be the single source of truth for agentic coding interactions within this repository. Keep it updated as tooling or conventions evolve.*
|
||||
*End of document*
|
||||
Reference in New Issue
Block a user