winterfail/AGENTS.md

AGENTS.md

1. Build, Lint, and Test Commands

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.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)

{
  "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"
  }
}

---

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.

2.2 Imports

• Named imports only when possible:

  import { foo, bar } from './utils';
  

• Default imports only for modules that expose a default export:

  import defaultFn from './default';
  

• Relative paths (./, ../) must be used; no root‑path shortcuts.

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.

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.

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.

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).

2.7 Async/Await

• Always handle rejected promises; avoid unhandled promise warnings.
• Prefer await over .then() chains for readability.

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.

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.

---

3. Project‑Specific 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.

---

4. Utility Scripts

4.1 Clean Build Artifacts

# Remove generated files
rm -rf dist/ coverage/ node_modules/

4.2 Reset Lint Cache

# Clear ESLint cache to force re‑lint
rm -rf .eslintcache

4.3 Generate Documentation (if used)

# 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.