lwc-linter/README.md

A comprehensive CLI tool for linting Lightning Web Components v8.0.0+ with modern LWC patterns, decorators, lifecycle hooks, and Salesforce platform integration

# 🔍 LWC Linter

A comprehensive CLI tool for linting Lightning Web Components with **code quality**, **accessibility (ADA)**, **performance**, **security**, **ESLint**, and **Prettier** integration.

## ✨ Features

- 🧹 **25+ Custom Rules** across 4 categories plus ESLint/Prettier integration
- 🔧 **Auto-fix** functionality for fixable issues
- 📊 **Multiple Output Formats** (CLI, JSON, HTML)
- ⚙️ **Configurable** via `.lwclintrc.json`
- 🎯 **Severity Filtering** (info, warn, error)
- 🚫 **Rule Disabling** (disable specific rules)
- 🚀 **CI/CD Ready** with proper exit codes
- 📐 **ESLint Integration** for comprehensive code analysis
- 💅 **Prettier Integration** for consistent formatting
- 🌐 **Interactive HTML Reports** with filtering and Excel export
- 🚀 **Quick Scan Mode** with auto-browser opening

## 📦 Installation

```bash
npm install lwc-linter
```

## 🚀 Quick Start

### 🚀 One-Command Scan (Recommended)
```bash
# Scan current directory, generate report, and open in browser
npx lwc-linter scan

# Scan specific directory
npx lwc-linter scan ./src

# Scan with auto-fix suggestions
npx lwc-linter scan ./src --fix
```

### 📋 Traditional Usage
```bash
# Basic scan
npx lwc-linter ./src

# Generate and auto-open HTML report
npx lwc-linter ./src --report html --open

# Auto-fix issues
npx lwc-linter ./src --fix

# Show only errors
npx lwc-linter ./src --severity error
```

## 🌟 Interactive Features

The HTML report includes:
- **📂 Expandable/Collapsible** file sections
- **💡 Code fix examples** for every issue
- **🔍 Advanced filtering** by severity and category
- **📊 Excel export** functionality
- **📱 Responsive design** for all devices
- **🎨 Modern UI** with smooth animations

## 📋 Available Rules

### 🧩 Code Quality (10 rules)
- `no-unused-vars` - Disallow unused variables [fixable]
- `no-console` - Disallow console statements [fixable]
- `prefer-const` - Prefer const over let [fixable]
- `no-var` - Disallow var declarations [fixable]
- `camelcase-naming` - Enforce camelCase naming
- `max-nesting-depth` - Limit nesting depth
- `no-magic-numbers` - Disallow magic numbers
- `eslint-integration` - ESLint-style code analysis [fixable]
- `prettier-formatting` - Prettier formatting standards [fixable]
- `import-organization` - Proper import organization [fixable]

### ♿ Accessibility (6 rules)
- `aria-required` - Ensure ARIA attributes [fixable]
- `alt-text-required` - Ensure alt text [fixable]
- `color-contrast` - Check color contrast
- `keyboard-navigation` - Ensure keyboard support
- `focus-management` - Proper focus management
- `semantic-html` - Encourage semantic HTML

### ⚡ Performance (5 rules)
- `dom-query-optimization` - Optimize DOM queries
- `reactive-property-usage` - Proper @track/@api usage
- `large-dom-check` - Warn about large DOM
- `bundle-size-check` - Check bundle size
- `async-operation-check` - Proper async handling

### 🔒 Security (5 rules)
- `no-innerhtml` - Prevent XSS via innerHTML
- `input-validation` - Ensure input validation
- `xss-prevention` - Prevent XSS vulnerabilities
- `no-eval` - Prohibit eval() usage
- `secure-communication` - Ensure secure practices

## ⚙️ Configuration

Create a `.lwclintrc.json` file in your project root:

```json
{
  "rules": {
    "no-console": "warn",
    "aria-required": "error",
    "prettier-formatting": "warn",
    "eslint-integration": "warn"
  },
  "severity": "warn",
  "fix": false,
  "exclude": ["node_modules/**", "**/*.test.js"],
  "accessibility": {
    "enabled": true,
    "level": "AA"
  },
  "performance": {
    "enabled": true,
    "maxBundleSize": 500000
  },
  "security": {
    "enabled": true,
    "allowInnerHTML": false
  },
  "eslintIntegration": {
    "enabled": true,
    "configPath": ".eslintrc.js",
    "ignorePatterns": ["node_modules/**", "lib/**"]
  },
  "prettierIntegration": {
    "enabled": true,
    "configPath": ".prettierrc.js",
    "printWidth": 100,
    "tabWidth": 2,
    "useTabs": false
  }
}
```

## 🛠️ Command Reference

### Quick Scan Commands
```bash
# 🚀 Quick scan with browser opening (recommended)
npx lwc-linter scan                    # Scan current directory
npx lwc-linter scan ./src             # Scan specific directory  
npx lwc-linter scan --fix             # Show auto-fix suggestions
npx lwc-linter scan --no-open         # Don't open browser

# 🔧 Auto-fix command (use after scan)
npx lwc-linter ./src --fix            # Fix all fixable issues
```

### Advanced Commands
```bash
# List all available rules
npx lwc-linter --rules

# Custom configuration
npx lwc-linter ./src --config .lwclintrc.json

# Disable specific rules
npx lwc-linter ./src --disable no-console,prettier-formatting

# Generate specific report formats
npx lwc-linter ./src --report json --output report.json
npx lwc-linter ./src --report html --output report.html --open

# Filter by severity
npx lwc-linter ./src --severity error  # Show only errors
npx lwc-linter ./src --severity warn   # Show warnings and errors
```

## 🛠️ ESLint Integration

The linter includes a comprehensive ESLint configuration:

```javascript
// .eslintrc.js (included)
module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint', 'prettier'],
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    'prettier/prettier': 'error',
    '@typescript-eslint/no-unused-vars': 'error',
    'no-console': 'warn',
    'no-eval': 'error',
    'eqeqeq': 'error',
    // ... and many more
  }
};
```

## 💅 Prettier Integration

Consistent code formatting with Prettier:

```javascript
// .prettierrc.js (included)
module.exports = {
  printWidth: 100,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  singleQuote: true,
  trailingComma: 'es5',
  bracketSpacing: true,
  arrowParens: 'avoid'
};
```

## 📊 Report Features

### CLI Output (default)
Beautiful colored terminal output with icons and summary.

### JSON Output
```bash
npx lwc-linter ./src --report json --output report.json
```

### Interactive HTML Report
```bash
npx lwc-linter ./src --report html --open
```

**HTML Report Features:**
- 📂 **Expandable file sections** with click-to-toggle
- 💡 **Code fix examples** showing before/after
- 🔍 **Real-time filtering** by severity and category
- 📊 **Excel export** with comprehensive data
- 📱 **Responsive design** for all screen sizes
- 🎨 **Modern UI** with smooth animations
- 📈 **Statistical summaries** with color-coded metrics

## 🛠️ Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Run ESLint
npm run lint

# Auto-fix ESLint issues
npm run lint:fix

# Format with Prettier
npm run format

# Check Prettier formatting
npm run format:check

# Run tests
npm test
```

## 🎯 Example Workflow

```bash
# 1. Quick scan your project
npx lwc-linter scan ./src

# 2. Review issues in the auto-opened HTML report
#    - Filter by severity/category
#    - View code fix examples
#    - Export to Excel if needed

# 3. Auto-fix what you can
npx lwc-linter ./src --fix

# 4. Re-scan to see improvements
npx lwc-linter scan ./src
```

## 📁 Project Structure

```
lwc-linter/
├── bin/cli.js                 # CLI entry point
├── src/
│   ├── cli.ts                 # Enhanced CLI with scan command
│   ├── core/                  # Core functionality
│   │   ├── linter.ts          # Main linter class
│   │   ├── file-processor.ts
│   │   ├── rule-manager.ts
│   │   └── output-formatter.ts # Enhanced HTML formatter
│   ├── rules/                 # Rule definitions
│   │   ├── code-quality.ts
│   │   ├── accessibility.ts
│   │   ├── performance.ts
│   │   ├── security.ts
│   │   └── eslint-prettier.ts # ESLint/Prettier integration
│   └── types/
│       └── config.ts          # TypeScript types
├── lib/                       # Compiled JavaScript
├── .eslintrc.js              # ESLint configuration
├── .prettierrc.js            # Prettier configuration
└── test-lwc/                 # Example test files
```

## 🎯 Example Output

```
🚀 LWC Quick Scan Starting...
📁 Scanning: /path/to/your/project

✔ Scan completed! Processed 15 files.
📊 Interactive report generated: lwc-scan-report-2024-01-15.html

📈 Quick Summary:
   ● 12 errors
   ● 28 warnings
   ● 25 fixable issues

🌐 Opening interactive report in browser...
✅ Report opened successfully!

🎯 In the report you can:
   • Filter by severity (errors, warnings, info)
   • Filter by category (code quality, accessibility, etc.)
   • Expand/collapse file sections
   • View code fix examples
   • Export data to Excel

🔧 Auto-fix Command:
   npx lwc-linter "./src" --fix
   This will automatically fix 25 issues!
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Follow ESLint and Prettier standards
4. Add tests for new rules
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🆘 Support

- 📖 Documentation: See this README
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions

---

Built with ❤️ for the Lightning Web Components community