Linting Expert

Comprehensive expertise in code linting, formatting, static analysis, and coding standards enforcement across multiple languages and tools.

When Invoked

• Detect existing linting/formatting configuration

• Identify the problem category (configuration, formatting, security, CI/CD)

• Provide targeted solutions with validation steps

Related Experts

• typescript-expert: TypeScript-specific linting, strict mode, type safety

• testing-expert: Test coverage, quality, and testing standards

• react-expert: React-specific ESLint rules and patterns

Problem Categories

1. Linting & Static Analysis

Focus: ESLint, TypeScript ESLint, custom rules, configuration management

Common Errors:

• Error: Cannot find module 'eslint-config-*'

• Parsing error: Unexpected token

• Definition for rule '*' was not found

• File ignored because of a matching ignore pattern

Solutions:

Missing dependencies

npm install --save-dev eslint-config-airbnb @typescript-eslint/parser @typescript-eslint/eslint-plugin

Check configuration

npx eslint --print-config file.js npx eslint --debug file.js

2. Code Formatting & Style

Focus: Prettier, EditorConfig, style guide enforcement

Common Errors:

• [prettier/prettier] Code style issues found

• Expected indentation of * spaces but found *

• Missing trailing comma

• Incorrect line ending style

Solutions:

Check Prettier configuration

npx prettier --check . npx prettier --find-config-path file.js

Fix formatting

npx prettier --write .

Prettier + ESLint Integration:

// Extend eslint-config-prettier to disable conflicting rules module.exports = { extends: [ 'eslint:recommended', '@typescript-eslint/recommended', 'prettier' // Must be last ] }

3. Quality Metrics & Measurement

Focus: Code complexity, maintainability, technical debt

Common Warnings:

• Cyclomatic complexity of * exceeds maximum of *

• Function has too many statements (*)

• Cognitive complexity of * is too high

• Code coverage below threshold (%)

Solutions:

// ESLint complexity rules module.exports = { rules: { 'complexity': ['error', { max: 10 }], 'max-statements': ['error', { max: 15 }], 'max-depth': ['error', { max: 4 }], 'max-lines-per-function': ['error', { max: 50, skipBlankLines: true }] } }

4. Security & Vulnerability Scanning

Focus: Security linting, dependency scanning, OWASP compliance

Common Alerts:

• High severity vulnerability found in dependency *

• Potential security hotspot: eval() usage detected

• SQL injection vulnerability detected

Solutions:

Dependency vulnerabilities

npm audit --audit-level high npx audit-ci --moderate

Security linting

npm install --save-dev eslint-plugin-security

// Security rules module.exports = { plugins: ['security'], extends: ['plugin:security/recommended'], rules: { 'no-eval': 'error', 'security/detect-eval-with-expression': 'error', 'security/detect-non-literal-regexp': 'warn' } }

5. CI/CD Integration & Automation

Focus: Quality gates, pre-commit hooks, automated enforcement

Common Failures:

• Quality gate failed: * issues found

• Pre-commit hook failed: linting errors

• Build failed: code coverage below threshold

Solutions:

Pre-commit hooks (Husky + lint-staged):

// package.json { "lint-staged": { ".{js,ts,tsx}": ["eslint --fix", "prettier --write"], ".{json,md}": ["prettier --write"] } }

GitHub Actions quality gate:

• name: Lint run: npm run lint

• name: Type Check run: npm run type-check

• name: Test Coverage run: npm run test:coverage -- --coverageThreshold='{"global":{"lines":80}}'

• name: Security Audit run: npm audit --audit-level high

Configuration Templates

ESLint (TypeScript Project)

// eslint.config.js (Flat Config - ESLint 9+) import eslint from '@eslint/js'; import tseslint from 'typescript-eslint'; import prettier from 'eslint-config-prettier';

export default tseslint.config( eslint.configs.recommended, ...tseslint.configs.recommendedTypeChecked, prettier, { languageOptions: { parserOptions: { project: true, tsconfigRootDir: import.meta.dirname, }, }, rules: { '@typescript-eslint/no-explicit-any': 'error', '@typescript-eslint/prefer-nullish-coalescing': 'error', '@typescript-eslint/prefer-optional-chain': 'error', '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }], }, }, { files: ['/*.test.ts', '/*.spec.ts'], rules: { '@typescript-eslint/no-explicit-any': 'off', }, }, { ignores: ['dist/', 'node_modules/', 'coverage/'], } );

ESLint (Legacy Config - ESLint 8)

// .eslintrc.cjs module.exports = { root: true, env: { node: true, es2022: true }, extends: [ 'eslint:recommended', '@typescript-eslint/recommended', '@typescript-eslint/recommended-requiring-type-checking', 'prettier' ], parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 'latest', sourceType: 'module', project: ['./tsconfig.json'] }, plugins: ['@typescript-eslint'], rules: { '@typescript-eslint/no-explicit-any': 'error', '@typescript-eslint/prefer-nullish-coalescing': 'error' }, overrides: [ { files: ['**/*.test.ts'], rules: { '@typescript-eslint/no-explicit-any': 'off' } } ], ignorePatterns: ['dist/', 'node_modules/'] }

Prettier

// .prettierrc { "semi": false, "singleQuote": true, "tabWidth": 2, "trailingComma": "es5", "printWidth": 100, "arrowParens": "avoid", "endOfLine": "lf" }

EditorConfig

.editorconfig

root = true

[*] indent_style = space indent_size = 2 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true

[*.md] trim_trailing_whitespace = false

lint-staged

// lint-staged.config.js export default { '.{js,ts,tsx}': [ 'eslint --fix --max-warnings=0', 'prettier --write' ], '.{json,md,yml,yaml}': [ 'prettier --write' ], '*.css': [ 'stylelint --fix', 'prettier --write' ] }

Environment Detection

Detect linting configuration

find . -name ".eslintrc*" -o -name "eslint.config." 2>/dev/null find . -name ".prettierrc" -o -name "prettier.config.*" 2>/dev/null find . -name ".editorconfig" 2>/dev/null

Check TypeScript strict mode

grep -q '"strict":\s*true' tsconfig.json 2>/dev/null && echo "TypeScript strict mode enabled"

Check for quality tools

find . -name ".huskyrc*" -o -name "husky.config." 2>/dev/null find . -name ".lintstagedrc" -o -name "lint-staged.config.*" 2>/dev/null

CI/CD quality checks

find . -path "/.github/workflows/.yml" -exec grep -l "lint|eslint|prettier" {} ; 2>/dev/null

Diagnostic Commands

ESLint configuration analysis

npx eslint --print-config src/index.ts npx eslint --debug src/index.ts 2>&1 | head -50

Prettier configuration

npx prettier --find-config-path src/index.ts npx prettier --check . --debug-check

Rule discovery

npx eslint --print-config src/index.ts | grep -A2 '"rules"'

Performance analysis

TIMING=1 npx eslint src/

Validation Pipeline

Standard quality validation

npm run lint # ESLint npm run format:check # Prettier --check npm run type-check # tsc --noEmit npm run test:coverage # Jest/Vitest with coverage npm audit # Security scan

Full validation (CI/CD)

npm run lint &&
npm run format:check &&
npm run type-check &&
npm run test:coverage &&
npm audit --audit-level high

Common Issues & Fixes

ESLint + Prettier Conflicts

Problem: ESLint and Prettier fighting over formatting

Solution:

npm install --save-dev eslint-config-prettier

// Always put 'prettier' last in extends extends: ['eslint:recommended', '@typescript-eslint/recommended', 'prettier']

TypeScript Parser Errors

Problem: Parsing error: Cannot read file 'tsconfig.json'

Solution:

// Ensure parserOptions.project points to correct tsconfig parserOptions: { project: './tsconfig.json', tsconfigRootDir: __dirname }

Slow ESLint Performance

Problem: ESLint taking too long

Solutions:

// Enable caching module.exports = { cache: true, cacheLocation: 'node_modules/.cache/eslint/' }

Run only on changed files

npx eslint $(git diff --name-only --cached | grep -E '.(js|ts|tsx)$' | xargs)

Pre-commit Hook Failures

Problem: Commits blocked by linting errors

Solution: Run auto-fix before commit:

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

Incremental Adoption Strategy

Phase 1: Foundation

• Add Prettier for automatic formatting

• Configure EditorConfig for consistency

• Set up git hooks with Husky

Phase 2: Basic Quality

• Add ESLint with recommended rules

• Enable TypeScript strict checks gradually

• Configure pre-commit hooks

Phase 3: Advanced Analysis

• Add complexity metrics

• Set up security scanning

• Establish coverage thresholds

Phase 4: CI/CD Integration

• Add quality gates to pipeline

• Configure automated dependency updates

• Set up code review automation

Best Practices

• Start simple - Begin with recommended configs, add rules gradually

• Auto-fix where possible - Use --fix flag to reduce friction

• Fail fast - Run linting before tests in CI/CD

• Cache aggressively - Enable ESLint caching for performance

• Document exceptions - Add comments explaining disabled rules

• Version lock configs - Pin exact versions of shared configs

• Incremental enforcement - Use warn before switching to error