npm package: @ibew-eslint/eslint-config-angular
Description: Shared ESLint configuration for Angular projects
Author: IBEW Dev Ops
Latest version: 1.0.1

# @ibew-eslint/eslint-config-angular

Shared ESLint configuration for Angular projects at IBEW.

## Installation

```bash
npm install --save-dev @ibew-eslint/eslint-config-angular
```

**Note**: This package requires peer dependencies. Install them if not already present:

```bash
npm install --save-dev @eslint/js @typescript-eslint/eslint-plugin @typescript-eslint/parser typescript-eslint angular-eslint eslint
```

## Usage

Create `eslint.config.js` in your project root:

```javascript
module.exports = require('@ibew-eslint/eslint-config-angular');
```

Add scripts to your `package.json`:

```json
{
  "scripts": {
    "lint": "eslint \"src/**/*.{ts,html}\"",
    "lint:fix": "eslint \"src/**/*.{ts,html}\" --fix",
    "lint:check": "eslint \"src/**/*.{ts,html}\" --max-warnings 0"
  }
}
```

## What's Included

This configuration includes:

### TypeScript Rules
- **Component selectors**: Must use `app-` prefix with kebab-case
- **Directive selectors**: Must use `app` prefix with camelCase  
- **No console statements**: Prevents console.log in production code
- **Unused variables**: Variables starting with `_` are allowed to be unused
- **Comment standards**: Enforces consistent comment formatting

### HTML Template Rules
- **Angular template best practices**: Component and directive usage
- **Accessibility**: WCAG compliance helpers
- **Template syntax**: Consistent Angular template patterns

### Code Quality Rules
- **Commented code detection**: Warns about TODO, FIXME, etc.
- **Comment formatting**: Enforces spaced comments with proper markers
- **Inline comment warnings**: Discourages inline comments

### Detailed Rule List

| Rule | Level | Description |
|------|-------|-------------|
| `@angular-eslint/component-selector` | error | Components must use `app-` prefix with kebab-case |
| `@angular-eslint/directive-selector` | error | Directives must use `app` prefix with camelCase |
| `no-console` | error | No console.log statements allowed |
| `@typescript-eslint/no-unused-vars` | error | Unused vars not allowed (except those starting with `_`) |
| `no-warning-comments` | warn | Warns on TODO, FIXME, HACK, BUG, XXX, TEMP, TEMPORARY |
| `spaced-comment` | error | Comments must have proper spacing |
| `no-inline-comments` | warn | Discourages inline comments |
| `multiline-comment-style` | error | Enforces starred-block style for multiline comments |

## Customizing for Your Project

To add project-specific rules, extend the configuration:

```javascript
const baseConfig = require('@ibew-eslint/eslint-config-angular');

module.exports = [
  ...baseConfig,
  {
    rules: {
      // Your project-specific overrides
      'no-console': 'warn', // Relax console rule
      '@angular-eslint/component-selector': [
        'error',
        {
          type: 'element',
          prefix: 'custom', // Different prefix for this project
          style: 'kebab-case',
        },
      ],
    }
  },
  {
    // Ignore specific files
    ignores: [
      'src/legacy/**/*',
      'src/generated/**/*'
    ]
  }
];
```

### Environment-Specific Configuration

```javascript
const baseConfig = require('@ibew-eslint/eslint-config-angular');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = [
  ...baseConfig,
  {
    rules: {
      // Allow console in development
      'no-console': isDevelopment ? 'warn' : 'error',
    }
  }
];
```

## IDE Setup

### VS Code
1. Install the ESLint extension
2. Add to your workspace `.vscode/settings.json`:

```json
{
  "eslint.validate": ["javascript", "typescript", "html"],
  "eslint.format.enable": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.formatOnSave": true
}
```

3. Recommended extensions (`.vscode/extensions.json`):
```json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "angular.ng-template"
  ]
}
```

### Basic Project Structure
```
my-angular-app/
├── .vscode/
│   └── settings.json        ← IDE configuration
├── src/
│   ├── app/
│   │   ├── components/
│   │   └── services/
│   └── ...
├── eslint.config.js         ← Your ESLint config
├── package.json
└── ...
```

### Npm Scripts
Add these to your `package.json`:

```json
{
  "scripts": {
    "lint": "eslint \"src/**/*.{ts,html}\"",
    "lint:fix": "eslint \"src/**/*.{ts,html}\" --fix",
    "lint:check": "eslint \"src/**/*.{ts,html}\" --max-warnings 0",
    "lint:report": "eslint \"src/**/*.{ts,html}\" --format html --output-file eslint-report.html"
  }
}
```

## Troubleshooting

### "Cannot resolve configuration" Error
```bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

### VS Code Not Showing Errors
```bash
# Press Ctrl+Shift+P (Cmd+Shift+P on Mac) and run:
# "ESLint: Restart ESLint Server"
```

### Peer Dependency Warnings
```bash
# Install exact versions
npm install --save-dev @eslint/js@^9.0.0 typescript-eslint@^8.0.0 angular-eslint@^18.0.0
```

### Too Many Errors After Installation
```bash
# Run auto-fix multiple times
npm run lint:fix
npm run lint:fix
npm run lint:fix
```

### Configuration Not Being Applied
```bash
# Check if ESLint can find your config
npx eslint --print-config src/app/app.component.ts
```

## Git Integration

### Pre-commit Hooks
```bash
# Install husky and lint-staged
npm install --save-dev husky lint-staged

# Setup
npm pkg set scripts.prepare="husky install"
npm run prepare
npx husky add .husky/pre-commit "npx lint-staged"
```

Add to `package.json`:
```json
{
  "lint-staged": {
    "src/**/*.{ts,html}": [
      "eslint --fix",
      "git add"
    ]
  }
}
```

## Contributing

To suggest rule changes:
1. **Open an issue** describing the problem with examples
2. **Provide context** on why the change is needed  
3. **Show examples** of current vs desired behavior
4. **Consider impact** on existing codebases
5. **Test locally** with the proposed changes

### Rule Change Process
1. Discuss in team meeting or Slack
2. Create feature branch in shared config repo
3. Test with existing projects
4. Update documentation and changelog
5. Create pull request for review

## Support

- **Documentation**: [ESLint Docs](https://eslint.org/docs/) | [Angular ESLint](https://github.com/angular-eslint/angular-eslint)
- **Team Support**: Ask in #development-tools Slack channel
- **Issues**: Open an issue in the shared config repository
- **Quick Help**: Check this README's troubleshooting section