# @humand-packages/linter

A explicit ESLint configuration package for the Humand monorepo. **NO DEFAULTS** - you must explicitly configure what you want.

## Installation

This package is already configured in the pnpm workspace. If you need to add it to a new package:

```bash
pnpm add @humand-packages/linter --dev
```

## Usage

### ⚠️ Important: No Magic Defaults

This linter package has **NO defaults**. You must explicitly specify:
- Global ignore patterns (required)
- File patterns for each enabled rule type (required when enabled)

This makes configurations explicit and prevents unexpected behavior.

### Basic Configuration

You MUST provide at least `globalIgnores`:

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    // REQUIRED: Global ignore patterns
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
        'coverage',
    ],
    
    // All other rules are disabled by default
    // To enable, you must provide both enabled: true AND files: [...]
});
```

### Enabling Rule Sets

To enable any rule set, you MUST provide both `enabled: true` and a `files` array:

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
    ],
    
    // TypeScript rules - EXPLICIT configuration required
    typescript: {
        enabled: true,
        files: ['**/*.ts', '**/*.tsx'] // REQUIRED when enabled: true
    },
    
    // Test rules - EXPLICIT configuration required
    tests: {
        enabled: true,
        files: ['**/*.test.ts', '**/*.spec.ts', 'tests/**/*.ts'] // REQUIRED when enabled: true
    },
    
    // YAML rules
    yaml: {
        enabled: true,
        files: ['*.yml', '*.yaml', 'config/**/*.yml'] // REQUIRED when enabled: true
    },
    
    // Route files with custom patterns
    routeFiles: {
        enabled: true,
        files: [
            'src/routes/**/*.ts',
            'src/api/**/*.ts',
            'src/controllers/**/*.ts'
        ] // REQUIRED when enabled: true
    },
    
    // Integration tests
    integrationTests: {
        enabled: true,
        files: ['e2e/**/*.ts', 'integration/**/*.ts'] // REQUIRED when enabled: true
    },
});
```

### Disabling Rules

To disable a rule set, use `false` or omit it entirely:

```javascript
module.exports = createLinterConfig({
    globalIgnores: ['node_modules', '*.md', 'build'],
    
    typescript: {
        enabled: true,
        files: ['**/*.ts']
    },
    
    // These are all equivalent ways to disable:
    tests: false,           // Explicit false
    yaml: { enabled: false }, // Explicit object with enabled: false
    // routeFiles: undefined,  // Omitted entirely
    // integrationTests: undefined, // Omitted entirely
});
```

### Error Cases

These configurations will throw errors:

```javascript
// ❌ WRONG: Missing globalIgnores
module.exports = createLinterConfig({
    typescript: { enabled: true, files: ['**/*.ts'] }
});
// Error: globalIgnores array is required

// ❌ WRONG: enabled: true without files
module.exports = createLinterConfig({
    globalIgnores: ['node_modules'],
    typescript: { enabled: true } // Missing files!
});
// Error: When enabled is true, files array must be provided

// ❌ WRONG: Boolean true (legacy syntax not supported)
module.exports = createLinterConfig({
    globalIgnores: ['node_modules'],
    typescript: true // Should be object with enabled + files
});
// Error: Boolean true not allowed. Use object with enabled: true and files: [...] instead
```

## Configuration Options

### `createLinterConfig(options)`

Creates a complete ESLint configuration array.

**Required Parameters:**

- `options.globalIgnores` (Array<string>, **REQUIRED**): Global ignore patterns. Must contain at least one pattern.

**Optional Parameters:**

- `options.typescript` (object|false, default: disabled): TypeScript configuration
  - `typescript.enabled` (boolean, **REQUIRED if object**): Enable TypeScript rules
  - `typescript.files` (Array<string>, **REQUIRED when enabled: true**): File patterns

- `options.tests` (object|false, default: disabled): Test configuration
  - `tests.enabled` (boolean, **REQUIRED if object**): Enable test rules
  - `tests.files` (Array<string>, **REQUIRED when enabled: true**): File patterns

- `options.yaml` (object|false, default: disabled): YAML configuration
  - `yaml.enabled` (boolean, **REQUIRED if object**): Enable YAML rules
  - `yaml.files` (Array<string>, **REQUIRED when enabled: true**): File patterns

- `options.routeFiles` (object|false, default: disabled): Route files configuration
  - `routeFiles.enabled` (boolean, **REQUIRED if object**): Enable route-specific rules
  - `routeFiles.files` (Array<string>, **REQUIRED when enabled: true**): File patterns

- `options.integrationTests` (object|false, default: disabled): Integration test configuration
  - `integrationTests.enabled` (boolean, **REQUIRED if object**): Enable integration test rules
  - `integrationTests.files` (Array<string>, **REQUIRED when enabled: true**): File patterns

## Examples by Project Type

### TypeScript Library

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
        'dist',
        'lib',
    ],
    
    typescript: {
        enabled: true,
        files: ['src/**/*.ts', 'types/**/*.ts']
    },
    
    // All others disabled (tests: false, yaml: false, etc.)
});
```

### Backend API (Monolith)

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
        'coverage',
        'protos',
        'postman/**',
        'src/api/modules/*/presentation/i18n/*.json',
    ],
    
    typescript: {
        enabled: true,
        files: ['src/**/*.ts']
    },
    
    tests: {
        enabled: true,
        files: ['**/*.test.ts', '**/jest.*.ts']
    },
    
    yaml: {
        enabled: true,
        files: ['**/*.yaml', '**/*.yml']
    },
    
    routeFiles: {
        enabled: true,
        files: [
            'src/api/services/eventEmitter.ts',
            'src/api/routes/*.ts',
            'src/api/modules/auth/presentation/routers/sso/*.ts',
            'src/api/routes/publicApi/*.ts',
            'src/api/modules/*/presentation/routers/*.ts',
            'src/api/kernels/*/presentation/routers/*.ts',
            'src/api/common/presentation/routers/*.ts',
        ]
    },
    
    integrationTests: {
        enabled: true,
        files: ['test-integration/**/*.ts']
    },
});
```

### Migrations Package

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
        'coverage',
        'dist',
    ],
    
    typescript: {
        enabled: true,
        files: ['src/**/*.ts', 'migrations/**/*.ts']
    },
    
    // Everything else disabled by default
});
```

### Frontend Package

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
        'dist',
        'public',
    ],
    
    typescript: {
        enabled: true,
        files: ['src/**/*.ts', 'src/**/*.tsx']
    },
    
    tests: {
        enabled: true,
        files: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts']
    },
    
    yaml: {
        enabled: true,
        files: ['*.yml', '.github/**/*.yml']
    },
    
    integrationTests: {
        enabled: true,
        files: ['e2e/**/*.ts', 'cypress/**/*.ts']
    },
});
```

### Common Package

```javascript
// eslint.config.js
const { createLinterConfig } = require('@humand-packages/linter');

module.exports = createLinterConfig({
    globalIgnores: [
        'node_modules',
        '*.md',
        'build',
        'src/presentation/i18n/*.json',
    ],
    
    typescript: {
        enabled: true,
        files: ['**/*.ts', '**/*.tsx']
    },
    
    tests: {
        enabled: true,
        files: ['**/*.test.ts', '**/*.spec.ts']
    },
    
    // No YAML, routes, or integration tests for common library
});
```

## Rules Overview

The linter includes the following rule sets:

- **Base Rules**: General JavaScript/Node.js rules, Prettier integration, import ordering
- **TypeScript Rules**: Type checking, unused imports, member ordering, floating promises
- **Test Rules**: Jest rules, consistent test structure, formatting
- **YAML Rules**: YAML syntax and structure validation
- **Route Files Rules**: Special promise handling for Express route handlers
- **Integration Test Rules**: Relaxed console rules for test output

## Prettier Integration

All configurations include Prettier integration with these settings:
- Semi: true
- Tab Width: 4
- Print Width: 150
- Single Quote: true
- Trailing Comma: all
- End of Line: auto

## Key Principles

1. **No Magic**: Everything must be explicitly configured
2. **Required Patterns**: If you enable something, you must specify what files
3. **No Defaults**: No hidden file patterns or ignore rules
4. **Explicit Errors**: Clear error messages when configuration is incomplete
5. **Predictable**: What you see in the config is exactly what you get