JavaScript

<!-- JAVASCRIPT:START -->
# JavaScript Project Rules

## Agent Automation Commands

**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).

```bash
# Complete quality check sequence:
npm run lint              # Linting (0 warnings required)
npm run format            # Code formatting
npm test                  # All tests (100% pass required)
npm run test:coverage     # Coverage check (95%+ required)
npm run build             # Build verification (if applicable)

# Security audit:
npm audit --production    # Vulnerability scan
npm outdated              # Check outdated deps
```

## JavaScript Configuration

**CRITICAL**: Use modern JavaScript (ES2022+) with strict linting and testing.

- **Version**: Node.js 18+
- **Recommended**: Node.js 22 LTS
- **Standard**: ES2022 or later
- **Module System**: ESM (ES Modules)
- **Type**: Set `"type": "module"` in package.json

### package.json Requirements

```json
{
  "name": "your-package",
  "version": "1.0.0",
  "description": "Package description",
  "type": "module",
  "main": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js"
    }
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "esbuild src/index.js --bundle --platform=node --outfile=dist/index.js",
    "test": "vitest --run",
    "test:watch": "vitest",
    "test:coverage": "vitest --coverage",
    "lint": "eslint src/**/*.js tests/**/*.js",
    "lint:fix": "eslint src/**/*.js tests/**/*.js --fix",
    "format": "prettier --write 'src/**/*.js' 'tests/**/*.js'",
    "format:check": "prettier --check 'src/**/*.js' 'tests/**/*.js'"
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "devDependencies": {
    "eslint": "^9.19.0",
    "prettier": "^3.4.0",
    "vitest": "^2.1.0",
    "@vitest/coverage-v8": "^2.1.0",
    "esbuild": "^0.24.0"
  }
}
```

## Code Quality Standards

### Mandatory Quality Checks

**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.

**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!

```bash
# Pre-Commit Checklist (MUST match .github/workflows/*.yml)

# 1. Lint (MUST pass with no warnings - matches workflow)
npm run lint

# 2. Format check (matches workflow - use check, not write!)
npm run format:check
# or: npx prettier --check 'src/**/*.js' 'tests/**/*.js'

# 3. Run all tests (MUST pass 100% - matches workflow)
npm test

# 4. Build (if applicable - matches workflow)
npm run build

# 5. Check coverage (MUST meet threshold)
npm run test:coverage

# If ANY fails: ❌ DO NOT COMMIT - Fix first!
```

**If ANY of these fail, you MUST fix the issues before committing.**

**Why This Matters:**
- Running different commands locally than in CI causes "works on my machine" failures
- CI/CD workflows will fail if commands don't match
- Example: Using `prettier --write` locally but `prettier --check` in CI = failure
- Example: Skipping lint locally = CI ESLint failures catch errors you missed

### Linting

- Use ESLint 9+ with flat config
- Configuration in `eslint.config.js`
- Must pass with no warnings
- Use recommended rule sets

Example `eslint.config.js`:
```javascript
import js from '@eslint/js';

export default [
  js.configs.recommended,
  {
    files: ['src/**/*.js', 'tests/**/*.js'],
    languageOptions: {
      ecmaVersion: 2022,
      sourceType: 'module',
      globals: {
        console: 'readonly',
        process: 'readonly',
      },
    },
    rules: {
      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      'no-console': 'off', // Allow console in Node.js
      'prefer-const': 'error',
      'no-var': 'error',
    },
  },
];
```

### Formatting

- Use Prettier for code formatting
- Configuration in `.prettierrc.json`
- Integrate with ESLint for consistency
- Format before committing

Example `.prettierrc.json`:
```json
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always"
}
```

### Testing

- **Framework**: Vitest (recommended), Jest, or Mocha
- **Location**: `/tests` directory
- **Coverage**: Must meet project threshold (default 80%)
- **Watch Mode**: Use `vitest` or `vitest --watch` for development
- **CI Mode**: **CRITICAL** - Default `npm test` command MUST include `--run` flag
  - This prevents Vitest from entering watch mode, which never terminates
  - In `package.json`: `"test": "vitest --run"`
  - For manual development, use `npm run test:watch`

Example test structure:
```javascript
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { myFunction } from '../src/module.js';

describe('myFunction', () => {
  let testData;

  beforeEach(() => {
    testData = { value: 'test' };
  });

  afterEach(() => {
    // Cleanup
  });

  it('should return expected value', () => {
    const result = myFunction(testData);
    expect(result).toBe('expected');
  });

  it('should throw on invalid input', () => {
    expect(() => myFunction(null)).toThrow('Invalid input');
  });
});
```

### S2S (Server-to-Server) and Slow Tests

**CRITICAL**: Separate fast tests from slow/S2S tests.

**Problem**: Mixing fast unit tests with slow integration tests or tests requiring external servers causes:
- ❌ Slow CI/CD pipelines (10+ minutes instead of < 2 minutes)
- ❌ Flaky tests (external services unreliable)
- ❌ Developer frustration (slow test feedback)
- ❌ Blocked commits (waiting for slow tests)

**Solution**: Isolate S2S and slow tests using environment variables and tags.

#### What are S2S/Slow Tests?

**S2S (Server-to-Server) Tests**:
- Require external running servers (databases, APIs, message queues)
- Network I/O heavy
- Typically 5-30 seconds per test
- Examples: Database integration tests, API endpoint tests, message queue tests

**Slow Tests**:
- Long-running operations (processing large files, complex calculations)
- Typically > 5 seconds per test
- Examples: File processing tests, image manipulation, encryption tests

**Fast Tests** (Regular Unit Tests):
- No external dependencies
- In-memory only
- < 100ms per test
- Should be 95%+ of your test suite

#### Implementation Pattern

**1. Mark S2S/slow tests with conditional execution**:

```javascript
// tests/integration/database.test.js
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { setupDatabase, teardownDatabase } from './test-helpers.js';

// Only run if RUN_S2S_TESTS environment variable is set
const runS2STests = process.env.RUN_S2S_TESTS === '1';
const describeS2S = runS2STests ? describe : describe.skip;

describeS2S('Database Integration', () => {
  beforeAll(async () => {
    await setupDatabase();
  });

  afterAll(async () => {
    await teardownDatabase();
  });

  it('should connect to database', async () => {
    const result = await query('SELECT 1');
    expect(result).toBeDefined();
  }, { timeout: 30000 }); // 30 second timeout for S2S tests
});
```

**2. Mark slow tests similarly**:

```javascript
// tests/slow/file-processing.test.js
const runSlowTests = process.env.RUN_SLOW_TESTS === '1';
const describeSlow = runSlowTests ? describe : describe.skip;

describeSlow('Large File Processing', () => {
  it('should process 1GB file', async () => {
    const result = await processLargeFile('large-file.dat');
    expect(result).toBeDefined();
  }, { timeout: 60000 }); // 60 second timeout
});
```

**3. Organize tests by speed**:

```
tests/
├── unit/           # Fast tests (< 100ms) - DEFAULT
│   ├── parser.test.js
│   └── validator.test.js
├── integration/    # S2S tests (require servers)
│   ├── database.test.js
│   └── api.test.js
└── slow/           # Slow tests (> 5 seconds)
    └── file-processing.test.js
```

**4. Add npm scripts in `package.json`**:

```json
{
  "scripts": {
    "test": "vitest --run",
    "test:watch": "vitest",
    "test:s2s": "RUN_S2S_TESTS=1 vitest --run",
    "test:slow": "RUN_SLOW_TESTS=1 vitest --run",
    "test:all": "RUN_S2S_TESTS=1 RUN_SLOW_TESTS=1 vitest --run"
  }
}
```

**Windows users**: Use `cross-env` for environment variables:

```bash
npm install --save-dev cross-env
```

```json
{
  "scripts": {
    "test:s2s": "cross-env RUN_S2S_TESTS=1 vitest --run",
    "test:slow": "cross-env RUN_SLOW_TESTS=1 vitest --run"
  }
}
```

#### Best Practices

- ✅ **Always run fast tests** in CI/CD by default
- ✅ **Isolate S2S tests** - never run them in standard test suite
- ✅ **Mark slow tests** - prevent CI/CD timeouts
- ✅ **Document requirements** - specify which servers/services are needed for S2S tests
- ✅ **Use timeouts** - Set appropriate timeouts: `{ timeout: 30000 }` for S2S tests
- ✅ **Use environment variables** - Control test execution with `RUN_S2S_TESTS` and `RUN_SLOW_TESTS`
- ❌ **Never mix** fast and slow/S2S tests in same test run
- ❌ **Never require** external services for standard test suite
- ❌ **Never exceed** 10-20 seconds for regular tests

#### Example: Complete Test Setup

**Fast test** (runs by default):
```javascript
// tests/unit/calculator.test.js
import { describe, it, expect } from 'vitest';
import { add, multiply } from '../src/calculator.js';

describe('Calculator', () => {
  it('should add numbers', () => {
    expect(add(2, 3)).toBe(5);
  });

  it('should multiply numbers', () => {
    expect(multiply(2, 3)).toBe(6);
  });
});
```

**S2S test** (skipped by default):
```javascript
// tests/integration/api.test.js
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

const runS2STests = process.env.RUN_S2S_TESTS === '1';
const describeS2S = runS2STests ? describe : describe.skip;

describeS2S('API Integration', () => {
  let server;

  beforeAll(async () => {
    // Start server on port 3001
    server = await startTestServer(3001);
  });

  afterAll(async () => {
    await server.close();
  });

  it('should fetch users from API', async () => {
    const response = await fetch('http://localhost:3001/users');
    expect(response.status).toBe(200);
    const data = await response.json();
    expect(Array.isArray(data)).toBe(true);
  }, { timeout: 30000 });
});
```

**Running tests**:
```bash
# Fast tests only (default - for development and CI)
npm test

# Include S2S tests (manual or scheduled CI)
npm run test:s2s

# Include slow tests
npm run test:slow

# All tests (nightly builds)
npm run test:all
```

## Module System

- Use ES modules (`import`/`export`)
- Set `"type": "module"` in `package.json`
- Use `.js` extensions in imports for Node.js compatibility
- No CommonJS (`require`/`module.exports`) in new code

Example:
```javascript
// Good: ES modules with .js extension
import { myFunction } from './my-module.js';
import fs from 'node:fs';

export { myFunction };
export default class MyClass {}
```

```javascript
// Bad: CommonJS
const { myFunction } = require('./my-module');
module.exports = { myFunction };
```

## Error Handling

- Always handle errors explicitly
- Use try/catch for async operations
- Create custom error classes for domain errors
- Never swallow errors silently

Example:
```javascript
export class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
  }
}

export async function fetchData(url) {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    return await response.json();
  } catch (error) {
    if (error instanceof TypeError) {
      throw new ValidationError('Invalid URL', 'url');
    }
    throw error;
  }
}
```

## Documentation

- Use JSDoc for documentation
- Document all public APIs
- Include examples
- Export types for consumers (if using TypeScript types via JSDoc)

Example:
```javascript
/**
 * Processes the input data and returns a formatted result.
 *
 * @param {string} input - The input string to process
 * @param {Object} [options] - Optional processing options
 * @param {boolean} [options.trim=false] - Whether to trim whitespace
 * @returns {string} The processed string in uppercase
 * @throws {ValidationError} If input is empty
 *
 * @example
 * ```javascript
 * const result = process('hello', { trim: true });
 * console.log(result); // 'HELLO'
 * ```
 */
export function process(input, options = {}) {
  if (!input) {
    throw new ValidationError('Input cannot be empty', 'input');
  }
  const processed = options.trim ? input.trim() : input;
  return processed.toUpperCase();
}
```

## Async/Await Patterns

- Always use async/await (not callbacks or raw promises)
- Handle promise rejections
- Use Promise.all for concurrent operations
- Avoid blocking operations

Example:
```javascript
// Good: Async/await with error handling
export async function processMultiple(urls) {
  try {
    const results = await Promise.all(
      urls.map(url => fetchData(url))
    );
    return results;
  } catch (error) {
    console.error('Failed to process URLs:', error);
    throw error;
  }
}

// Bad: Callback hell
function processMultipleCallback(urls, callback) {
  let results = [];
  urls.forEach((url, i) => {
    fetchDataCallback(url, (err, data) => {
      if (err) return callback(err);
      results.push(data);
      if (i === urls.length - 1) callback(null, results);
    });
  });
}
```

## Package Management

**CRITICAL**: Use consistent package manager across team.

- **Default**: npm (most compatible, built-in)
- **Alternative**: pnpm (fast, disk-efficient) or yarn
- **Lockfile**: Always commit lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`)
  - **IMPORTANT**: GitHub Actions `setup-node` with `cache: 'npm'` requires lockfile to be committed
  - Without lockfile: CI/CD fails with "Dependencies lock file is not found"
  - Solution: Commit `package-lock.json` and use `npm ci` in workflows

### Dependencies

1. **Check for latest versions**:
   - Use Context7 MCP tool if available
   - Check npm registry: `npm view <package> versions`
   - Review changelog for breaking changes

2. **Dependency Guidelines**:
   - ✅ Use exact versions for applications (`"1.2.3"`)
   - ✅ Use semver for libraries (`"^1.2.3"`)
   - ✅ Keep dependencies updated regularly
   - ✅ Use `npm audit` for security
   - ❌ Don't use deprecated packages
   - ❌ Don't add unnecessary dependencies

## CI/CD Requirements

**CRITICAL**: GitHub Actions `cache: 'npm'` requires `package-lock.json` to be committed.

Must include GitHub Actions workflows for:

1. **Testing** (`javascript-test.yml`):
   - Test on ubuntu-latest, windows-latest, macos-latest
   - Node.js versions: 18.x, 20.x, 22.x
   - Use Vitest for fast execution
   - Upload coverage reports
   - **MUST**: Commit package-lock.json for caching

2. **Linting** (`javascript-lint.yml`):
   - ESLint: `npm run lint`
   - Prettier: `npm run format:check`
   - **MUST**: Commit package-lock.json for caching

3. **Build** (`javascript-build.yml`):
   - Build: `npm run build`
   - Verify output artifacts
   - **MUST**: Commit package-lock.json for caching

## Project Structure

```
project/
├── package.json        # Package manifest
├── package-lock.json   # Lockfile (MUST commit for CI cache)
├── eslint.config.js    # ESLint configuration
├── .prettierrc.json    # Prettier configuration
├── vitest.config.js    # Test configuration
├── README.md           # Project overview
├── LICENSE             # Project license
├── src/
│   ├── index.js        # Main entry point
│   └── ...
├── tests/              # Test files
├── dist/               # Build output (gitignored)
└── docs/               # Documentation
```

## Best Practices

### DO's ✅

- **USE** modern ES2022+ features
- **USE** async/await for asynchronous code
- **USE** strict equality (`===`) over loose equality (`==`)
- **VALIDATE** all inputs
- **HANDLE** errors explicitly
- **DOCUMENT** public APIs with JSDoc
- **TEST** all code paths
- **KEEP** dependencies minimal and updated

### DON'Ts ❌

- **NEVER** use `var` (use `const` or `let`)
- **NEVER** use `==` (use `===`)
- **NEVER** swallow errors silently
- **NEVER** commit `node_modules/`
- **NEVER** commit `.env` files
- **NEVER** use deprecated packages
- **NEVER** skip tests
- **NEVER** commit console.log debugging code

## Security

- Never commit secrets or API keys
- Use environment variables for sensitive data
- Run `npm audit` regularly
- Keep dependencies updated
- Use `.env` files (add to `.gitignore`)

Example `.env`:
```bash
API_KEY=your-secret-key
DATABASE_URL=postgres://localhost/db
```

Load with:
```javascript
import 'dotenv/config';

const apiKey = process.env.API_KEY;
```

<!-- JAVASCRIPT:END -->