lint-checker

# Lint Checker

Verifies code adheres to project linting and formatting standards. Identifies code quality issues, style violations, and potential bugs early in the development process.

## Invocation Context

Called by the Dev agent during development workflow:
- After implementation, before running tests
- Before committing code changes
- When checking code quality gates
- On request for specific files or changed files

## Input Expected

Accept the following parameters from the Dev agent:

- `story_path` (optional): Path to story file for context about what was implemented
- `files` (optional): Array of specific file paths to lint. If not provided, defaults to changed files (git status)
- `fix` (boolean, optional): Whether to attempt auto-fixing issues. Default: false

## Process Steps

Execute the following workflow:

1. **Identify Linting Tools**: Check project configuration files to determine available linters:
   - `.eslintrc.*`, `eslint.config.js` - ESLint for JavaScript/TypeScript
   - `.prettierrc.*` - Prettier for formatting
   - `pylintrc`, `.pylintrc`, `setup.cfg` - Pylint for Python
   - `.flake8` - Flake8 for Python
   - `.rubocop.yml` - RuboCop for Ruby
   - Check `package.json` scripts for lint commands
   - Check `pyproject.toml` for Python tool configs

2. **Determine Lint Command**: Based on project type and available tools:
   - Check for npm/yarn scripts first (`npm run lint`, `npm run format`)
   - Fall back to direct tool invocation if scripts not found

3. **Get Files to Check**: If `files` parameter not provided:
   - Run `git status --porcelain` to get changed files
   - Filter to relevant file types based on available linters
   - If no changes, check all project files (may be time-consuming, warn first)

4. **Execute Linter**: Run appropriate linting command:
   - If `fix` is true, use auto-fix flags
   - Capture stdout and stderr
   - Note exit codes (non-zero typically indicates violations)

5. **Capture Violations**: Parse linter output:
   - Extract file paths, line numbers, columns
   - Identify violation severity (error, warning, info)
   - Record rule names/codes
   - Extract violation messages

6. **Categorize by Severity**: Group violations:
   - Errors: Must be fixed (blocking)
   - Warnings: Should be fixed (non-blocking but important)
   - Info: Nice to fix (stylistic suggestions)

## Lint Commands

Common linting commands by ecosystem:

**JavaScript/TypeScript**:
```bash
# Check only
npm run lint
eslint src/
npx eslint --ext .js,.jsx,.ts,.tsx src/

# With auto-fix
npm run lint -- --fix
eslint src/ --fix
```

**Formatting (Prettier)**:
```bash
# Check only
npm run format:check
prettier --check "src/**/*.{js,jsx,ts,tsx,json,css,md}"

# With auto-fix
npm run format
prettier --write "src/**/*.{js,jsx,ts,tsx,json,css,md}"
```

**Python**:
```bash
# Check only
pylint src/
flake8 src/
black --check src/

# With auto-fix
black src/
autopep8 --in-place --recursive src/
```

**Ruby**:
```bash
# Check only
rubocop

# With auto-fix
rubocop --auto-correct-all
```

**Multiple Tools**: Run all configured linters and aggregate results.

## Output Format

Return results as JSON to the Dev agent:

```json
{
  "status": "CLEAN | VIOLATIONS",
  "total_files_checked": 12,
  "violations": {
    "error": 3,
    "warning": 7,
    "info": 2
  },
  "issues": [
    {
      "file": "/absolute/path/to/file.ts",
      "line": 42,
      "column": 15,
      "severity": "error",
      "rule": "no-unused-vars",
      "message": "'userData' is defined but never used"
    },
    {
      "file": "/absolute/path/to/file.ts",
      "line": 58,
      "column": 1,
      "severity": "warning",
      "rule": "max-line-length",
      "message": "Line exceeds maximum length of 100 characters"
    }
  ],
  "fixable_count": 5,
  "tools_used": ["eslint", "prettier"],
  "recommendation": "FIX_REQUIRED | AUTO_FIX_AVAILABLE | ACCEPTABLE"
}
```

**Status Values**:
- `CLEAN`: No violations found, code meets standards
- `VIOLATIONS`: Issues detected, see details in issues array

**Recommendation Values**:
- `FIX_REQUIRED`: Errors present, must fix before proceeding
- `AUTO_FIX_AVAILABLE`: Violations can be auto-fixed, suggest running with fix=true
- `ACCEPTABLE`: Only warnings/info, may proceed but should review

## Completion

1. Return JSON result to Dev agent through standard output
2. If `fix` was true, report what was auto-fixed
3. Provide actionable summary:
   - "Code is clean, no linting violations"
   - "Found 3 errors and 7 warnings across 12 files. 5 issues are auto-fixable."
   - "Auto-fixed 5 issues. 2 errors remain and require manual intervention."

Dev agent uses this output to determine next steps in development workflow.