LA2NodeJS/AGENTS.md

Agent Guidelines for LA2NodeJS

Build/Lint/Test Commands

Development

npm run dev              # Start development server
npm run build            # Build production bundle

Linting & Formatting

npm run lint             # Run linter (ESLint)
npm run format           # Format code (Prettier)
npm run format:write     # Format code in place

Testing

npm test                 # Run all tests
npm test -- --watch      # Run tests in watch mode
npm test -- <pattern>    # Run single test file or pattern
npm test <test>          # Run specific test (e.g., npm test -- src/__tests__/api.test.ts)

Single Test Execution

To run a single test file:

npm test -- src/__tests__/utils.test.ts

To run specific test cases with test.only:

npm run test:watch -- -t "describe name"

To run individual test case using V8 flags (if Jest doesn't support -t):

npx jest src/__tests__/utils.test.ts -t "test description"

---

Code Style Guidelines

Imports

• Sort imports in this order: Node built-ins, third-party, relative
• Group same-type imports together
• Limit each import statement to a single type
• Use import type for type-only imports
• Maximum 8-10 imports per file
• Use barrel exports only when reducing exports from a directory

Formatting

• Use Prettier with the configured .prettierrc
• Line width: 100 characters
• Tab indentation preferred
• Single quotes for strings (if configured)
• Semicolons included
• Trailing commas in multi-line objects/arrays
• No unnecessary parentheses (only for arrow functions and template literals)

Type Safety

• Enable strict TypeScript mode
• Type all function parameters and return values
• Use explicit types for async functions (Promise<void> or Promise<T>)
• Avoid any type; use unknown for untrusted input
• Use generic types in function signatures
• Type union/literal types as narrow as possible
• Avoid @ts-ignore / @ts-expect-error without comments

Naming Conventions

• Files: kebab-case (example-file.ts)
• Components: PascalCase or kebab-case based on framework
• Variables: camelCase for JS, snake_case if required by framework
• Constants: UPPER_SNAKE_CASE
• Classes: PascalCase
• Functions: camelCase
• Private members: _private prefix
• Public methods with prefix get|set|add|remove for clarity
• Event names: camelCase or kebab-case
• Types/Interfaces: PascalCase

Error Handling

• Use Error subclassing for domain-specific errors
• Throw errors when invariants are violated
• Catch specific error types, not bare catch
• Never swallow errors without logging or rethrowing
• Use custom error types: class NotFoundError extends Error { }
• Include context in error messages (path, id, etc.)
• Avoid process.env.NODE_ENV checks; use runtime error detection
• Use .catch() with async functions to handle Promise rejections

Async/Await

• Prefer async/await over .then() chains
• Handle errors immediately after async calls
• Return early from async functions on failure
• Use Promise.reject() explicitly over throw new Error()
• Avoid .catch(() => void 0); instead, log or handle errors

Code Organization

• Place types declarations in types/ directory
• Utility functions in utils/
• API/service modules in services/ or controllers/
• Tests in matching __tests__/ or .specs/ directories
• Keep files under 400 lines
• Maximum 10 files in any directory
• Barrel files for logical grouping, not lazy imports

Security

• Never commit secrets to git
• Validate all external inputs (URLs, IPs, email)
• Use environment-specific config (not committed)
• Sanitize data before logging
• Validate API request payloads with Zod/schema validation
• Avoid deprecated crypto functions (use Web Crypto API)
• Use secure HTTP headers (CORS, Helmet if applicable)

File Conventions

• Use .ts over .tsx when possible
• Export only named exports when multiple items exported
• Index exports only for submodules/microservices
• Use .d.ts for public type definitions
• Keep test files alongside source files
• Use .env.local for local overrides only

Linting Rules

• Disable ESLint rule only when necessary
• Provide comment explaining why
• Use eslint-disable-next-line // reason for single-line
• Use /* eslint-disable rule */ for blocks (max 5 lines)
• Always re-enable rules after disabling

Documentation

• Document non-obvious code with JSDoc
• Include @param and @returns for public APIs
• Document complex algorithms with comments
• Add TODO/FIXME comments for known issues
• Link related issues in commit messages and PRs
• Document breaking changes prominently

Performance

• Avoid unnecessary array method calls
• Prefer Object.entries() over Object.keys() for iteration
• Defer non-critical initializations
• Cache expensive computations
• Use Set for uniqueness checks
• Batch DOM operations when applicable

Testing Rules

• Test one scenario per file
• Arrange-Act-Assert pattern for tests
• Mock external dependencies
• Use describe/it for BDD-style tests
• Order tests: Setup -> Happy Path -> Edge Cases -> Error Cases
• Include coverage reports when debugging tests

---

Migration Notes

• Replace .jsx with .tsx where component doesn't use DOM APIs
• Use React.FC only for strict component props (avoid for simplicity)
• Use useState, useReducer for state with reset patterns
• Use useContext for global state needs
• Avoid useEffect for non-reactive state; keep side effects minimal

---

Common Workflows

Adding a new feature

1. Create implementation file in appropriate directory
2. Add types if needed in types/
3. Add tests in matching __tests__/ directory
4. Run npm run lint and fix issues
5. Create PR with descriptive title

Debugging

1. Add console.log with context
2. Use node -e to run isolated snippets
3. Check browser DevTools for React errors
4. Use breakpointMode: 'inspect-brk' in package.json for debugging