puaros/LINTING.md

Linting & Code Style Guide

Overview

This project uses ESLint + Prettier with strict TypeScript rules and 4-space indentation.

Quick Start

# Format all code
pnpm format

# Lint and auto-fix
pnpm lint

# Check only (no fix)
pnpm eslint "packages/**/*.ts"

Configuration Files

• .prettierrc - Prettier code formatting (4 spaces, single quotes, etc.)
• eslint.config.mjs - ESLint rules (TypeScript strict mode + best practices)
• .editorconfig - Editor settings (consistent across IDEs)

Key Rules

TypeScript Strictness

Rule	Level	Description
@typescript-eslint/no-explicit-any	warn	Avoid any type - use proper typing
@typescript-eslint/explicit-function-return-type	warn	Functions must declare return types
@typescript-eslint/no-floating-promises	error	Always handle promises
@typescript-eslint/no-unsafe-*	warn	Strict type safety checks

Code Quality

Rule	Level	Description
no-console	warn	Use logger instead (except console.warn/error)
prefer-const	error	Use const for non-reassigned variables
eqeqeq	error	Always use === instead of ==
curly	error	Always use curly braces for if/for/while
complexity	warn	Max cyclomatic complexity: 15
max-params	warn	Max function parameters: 5
max-lines-per-function	warn	Max 100 lines per function

Code Style

• Indentation: 4 spaces (not tabs)
• Line Length: 100 characters max
• Quotes: Single quotes 'string'
• Semicolons: Always required ;
• Trailing Commas: Always in multiline
• Arrow Functions: Always use parentheses (x) => x

Handling Warnings

any Type Usage

Before:

function process(data: any) {
    return data.value;
}

After:

interface ProcessData {
    value: string;
}

function process(data: ProcessData): string {
    return data.value;
}

Missing Return Types

Before:

async function fetchData() {
    return await api.get('/data');
}

After:

async function fetchData(): Promise<DataResponse> {
    return await api.get('/data');
}

Floating Promises

Before:

async function init() {
    startServer(); // ❌ Promise not handled
}

After:

async function init(): Promise<void> {
    await startServer(); // ✅ Promise awaited
}

Ignoring Rules (Use Sparingly)

// Disable specific rule for next line
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const legacyData: any = getLegacyApi();

// Disable for entire file (add at top)
/* eslint-disable @typescript-eslint/no-explicit-any */

Note: Only use eslint-disable for legacy code or when type safety is genuinely impossible.

Pre-commit Hooks (Optional)

To automatically format on commit, install Husky:

pnpm add -D husky lint-staged
npx husky init

# Add to .husky/pre-commit:
pnpm lint-staged

Create lint-staged config in package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "prettier --write",
      "eslint --fix"
    ]
  }
}

IDE Setup

VS Code

Install extensions:

• ESLint (dbaeumer.vscode-eslint)
• Prettier (esbenp.prettier-vscode)

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": ["typescript", "javascript"]
}

WebStorm / IntelliJ IDEA

1. Settings → Languages & Frameworks → JavaScript → Prettier

   • Enable "On save"
   • Set "Run for files": {**/*,*}.{ts,js,tsx,jsx}

2. Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint

   • Enable "Automatic ESLint configuration"
   • Enable "Run eslint --fix on save"

Common Issues

"Parsing error: ESLint was configured to run..."

Solution: Make sure tsconfig.json exists in the project root.

"Rule 'indent' conflicts with Prettier"

Solution: Already handled - ESLint indent rule is disabled in favor of Prettier.

Too many warnings after upgrade

Solution: Run auto-fix first, then address remaining issues:

pnpm lint
# Review warnings, fix manually

Best Practices

1. Run pnpm format before committing - ensures consistent formatting
2. Fix warnings incrementally - don't disable rules without reason
3. Add types instead of any - improves code quality and IDE support
4. Use ESLint ignore comments sparingly - only for edge cases

Resources

• TypeScript ESLint Rules
• Prettier Options
• ESLint Rules
• Airbnb JavaScript Style Guide

---

Last Updated: 2025-01-19