validate-lint

Purpose

Execute ESLint and Prettier to validate code style, formatting standards, and linting rules across the project.

When to Use

• Quality gate validation (before commit/PR)
• During conductor Phase 3 (Quality Assurance)
• Pre-refactor validation
• Real-time validation during development
• As part of quality-gate skill

Supported Linters

• ESLint: JavaScript/TypeScript linting
• Prettier: Code formatting
• Detects via:
  • npm scripts (npm run lint)
  • Direct commands (eslint .)
  • npx execution (npx eslint .)

Instructions

Step 1: Detect Lint Command

# Check package.json for lint script
if grep -q '"lint"' package.json; then
  LINT_CMD="npm run lint"
  echo "Using npm script: npm run lint"

# Check for eslint in node_modules
elif [ -f node_modules/.bin/eslint ]; then
  LINT_CMD="npx eslint ."
  echo "Using npx eslint"

# Use global eslint
elif command -v eslint &>/dev/null; then
  LINT_CMD="eslint ."
  echo "Using global eslint"

else
  echo "❌ Error: ESLint not available"
  echo "Install: npm install --save-dev eslint"
  exit 1
fi

Step 2: Run Lint Check

echo "→ Running lint validation..."

# Run linter and capture output
if $LINT_CMD 2>&1 | tee .claude/validation/lint-output.txt; then
  LINT_STATUS="passing"
  LINT_EXIT_CODE=0
  echo "✅ Lint validation passed"
else
  LINT_STATUS="failing"
  LINT_EXIT_CODE=$?
  echo "❌ Lint validation failed"
fi

Step 3: Parse Errors and Warnings

if [ "$LINT_STATUS" = "failing" ]; then
  # Count errors and warnings
  ERROR_COUNT=$(grep -c 'error  ' .claude/validation/lint-output.txt || echo "0")
  WARNING_COUNT=$(grep -c 'warning  ' .claude/validation/lint-output.txt || echo "0")

  echo "   Errors: $ERROR_COUNT"
  echo "   Warnings: $WARNING_COUNT"

  # Extract affected files
  AFFECTED_FILES=$(grep -oP '^/.+\.tsx?(?=\s)' .claude/validation/lint-output.txt | \
    sort -u | \
    jq -R -s -c 'split("\n") | map(select(length > 0))')

  # Parse rule violations (top offenders)
  RULE_VIOLATIONS=$(grep -oP '\w+/[\w-]+(?=\s+)' .claude/validation/lint-output.txt | \
    sort | uniq -c | sort -rn | head -5 | \
    awk '{print "{\"rule\": \"" $2 "\", \"count\": " $1 "}"}' | \
    jq -s -c '.')

else
  ERROR_COUNT=0
  WARNING_COUNT=0
  AFFECTED_FILES="[]"
  RULE_VIOLATIONS="[]"
fi

Step 4: Return Structured Output

{
  "status": "$([ "$LINT_STATUS" = "passing" ] && echo 'success' || echo 'error')",
  "lint": {
    "status": "$LINT_STATUS",
    "errors": $ERROR_COUNT,
    "warnings": $WARNING_COUNT,
    "files": $AFFECTED_FILES,
    "ruleViolations": $RULE_VIOLATIONS
  },
  "canProceed": $([ "$LINT_STATUS" = "passing" ] && echo 'true' || echo 'false')
}

Output Format

All Checks Pass

{
  "status": "success",
  "lint": {
    "status": "passing",
    "errors": 0,
    "warnings": 0,
    "files": [],
    "ruleViolations": []
  },
  "canProceed": true
}

Lint Errors Found

{
  "status": "error",
  "lint": {
    "status": "failing",
    "errors": 15,
    "warnings": 8,
    "files": [
      "src/components/Settings.tsx",
      "src/utils/helpers.ts"
    ],
    "ruleViolations": [
      {"rule": "react/prop-types", "count": 5},
      {"rule": "@typescript-eslint/no-explicit-any", "count": 4},
      {"rule": "prettier/prettier", "count": 3}
    ]
  },
  "canProceed": false,
  "details": "15 lint errors must be fixed before proceeding"
}

Integration with Quality Gate

Used in quality-gate skill:

### Step 2: Lint Validation

Use `validate-lint` skill:

Expected result:
- Status: passing
- Errors: 0
- Warnings: acceptable (configurable)

If lint errors found:
  ❌ BLOCK - Quality gate fails
  → Fix linting errors
  → Re-run quality gate

If lint passes:
  ✅ Continue to next check

Common Rule Violations

React/TypeScript Rules

react/prop-types          - Missing prop type validation
@typescript-eslint/no-explicit-any - Using 'any' type
react-hooks/exhaustive-deps - Missing hook dependencies

Action: Fix according to project style guide

Prettier Formatting

prettier/prettier - Formatting inconsistencies

Action: Run npm run format or prettier --write .

Import/Export Rules

import/no-unresolved - Cannot resolve import
import/order - Incorrect import ordering

Action: Fix import paths and organize imports

Auto-Fix Support

Many linting issues can be auto-fixed:

# Auto-fix ESLint issues
eslint --fix .

# Auto-format with Prettier
prettier --write .

# Combined (if configured)
npm run lint:fix

Related Skills

• quality-gate - Uses this for lint validation
• validate-typescript - Type checking (separate from linting)

Error Handling

ESLint Not Installed

{
  "status": "error",
  "error": "ESLint not available",
  "suggestion": "Install ESLint: npm install --save-dev eslint"
}

No ESLint Config

if [ ! -f .eslintrc.json ] && [ ! -f .eslintrc.js ] && [ ! -f eslint.config.js ]; then
  echo "⚠️ Warning: No ESLint config found - using default rules"
fi

Best Practices

1. Fix errors before committing - Don't accumulate lint debt
2. Warnings are acceptable - Configure thresholds in quality-gate
3. Use auto-fix when safe - Speeds up fixing formatting issues
4. Consistent config - Share ESLint config across team
5. Save output - Keep logs for debugging

Notes

• Warnings don't block quality gate by default (configurable)
• Errors always block
• Output saved to .claude/validation/lint-output.txt
• Respects .eslintignore and .prettierignore