levnikolaevich/ln-741-linter-configurator

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-741-linter-configurator

Type: L3 Worker Category: 7XX Project Bootstrap

Configures code linting, formatting, and type checking tools for TypeScript, Python, and .NET projects.

---

Purpose & Scope

Does:

• Detects which linter stack to configure based on project type
• Checks for existing linter configurations
• Generates appropriate config files from templates
• Installs required dependencies (always latest versions, no pinning)
• Generates unified lint script (scripts/lint.sh)
• Verifies all linters run without errors

Does NOT:

• Configure pre-commit hooks (separate worker)
• Set up test infrastructure (separate worker)
• Modify source code

---

Supported Stacks

| Technology | Linter | Type Checker | Formatter | Config Files | |------------|--------|-------------|-----------|--------------| | TypeScript | ESLint 9+ (flat config) | TypeScript (tsc) | Prettier | eslint.config.ts, .prettierrc | | .NET | Roslyn Analyzers | Roslyn | dotnet format | .editorconfig, Directory.Build.props | | Python | Ruff | mypy | Ruff (built-in) | ruff.toml, mypy.toml (or pyproject.toml) |

---

Phase 1: Check Existing Configuration

Before generating configs, check what already exists.

Files to Check:

| Stack | Config Files | Glob Pattern | |-------|--------------|--------------| | TypeScript | ESLint config | eslint.config.*, .eslintrc* | | TypeScript | Prettier config | .prettierrc*, prettier.config.* | | .NET | Editor config | .editorconfig | | .NET | Build props | Directory.Build.props | | Python | Ruff config | ruff.toml, pyproject.toml | | Python | mypy config | mypy.toml, mypy.ini, pyproject.toml [tool.mypy] |

Decision Logic:

1. If no config exists: CREATE from template
2. If config exists but incomplete (fewer rules/tools than template): EXTEND to match template
3. If config matches template: SKIP (inform user)

Completeness Check (Python):

| Aspect | Check | Template Standard | |--------|-------|-------------------| | Ruff rules | Count select entries | 23+ categories (see ruff_template.toml) | | Ruff per-file-ignores | Tests section exists | tests/**/*.py with S101,S105,S106,T201 | | Ruff advanced | mccabe, flake8-bugbear, isort | All present | | MyPy | strict = true | Enabled | | Advanced tools | import-linter, deptry, vulture in dev deps | All installed | | Lint script | scripts/lint.sh with 7 checks | All 7 active | | .editorconfig | File exists | Present |

---

Phase 2: Generate Configuration

Use templates from references/ folder. Customize placeholders based on project.

TypeScript:

1. Copy eslint_template.ts to project root as eslint.config.ts
2. Copy prettier_template.json as .prettierrc
3. Add scripts to package.json:
   • "lint": "eslint ."
   • "lint:fix": "eslint . --fix"
   • "format": "prettier --write ."
   • "format:check": "prettier --check ."
   • "typecheck": "tsc --noEmit"
   • "lint:all": "npm run typecheck && npm run lint && npm run format:check"
4. For React projects: uncomment React sections in template

.NET:

1. Copy editorconfig_template.ini as .editorconfig
2. Copy directory_build_props_template.xml as Directory.Build.props
3. Ensure analyzers are included (SDK 5+ includes them by default)

Python:

1. Copy ruff_template.toml as ruff.toml
   • OR merge into existing pyproject.toml under [tool.ruff]
2. Copy mypy_template.toml as mypy.toml
   • OR merge into existing pyproject.toml under [tool.mypy]
3. Update known-first-party in isort config to match project package name
4. Update files in mypy config to match project source directories
5. Generate advanced tool configs in pyproject.toml:
   • [tool.importlinter] from importlinter_template.toml -- adapt root_packages and contracts to project layer structure
   • [tool.vulture] from vulture_template.toml -- adapt paths to project source directory
   • [tool.deptry] from deptry_template.toml -- adapt extend_exclude
6. Generate .editorconfig from editorconfig_template.ini -- adapt max_line_length to match ruff line-length

---

Phase 3: Install Dependencies

Install required packages. Always install latest versions — no version pinning.

TypeScript:

npm install -D eslint @eslint/js typescript-eslint eslint-config-prettier prettier eslint-plugin-unicorn jiti

For React projects, also install: npm install -D eslint-plugin-react eslint-plugin-react-hooks

Note on jiti: Required for eslint.config.ts on Node.js < 22.10. On Node.js 22.10+ TypeScript configs are supported natively.

.NET:

• Analyzers included in SDK 5+ — no separate install needed

Python:

uv add --dev ruff mypy import-linter deptry vulture pip-audit

# OR without uv:
pip install ruff mypy import-linter deptry vulture pip-audit

---

Phase 4: Generate Lint Script

Generate scripts/lint.sh from lint_script_template.sh with ALL checks for the detected stack.

1. Copy lint_script_template.sh to scripts/lint.sh
2. Uncomment ALL check lines matching detected stack -- both basic AND advanced tools:

| Stack | Checks | TOTAL | |-------|--------|-------| | Python | ruff check, ruff format, mypy, lint-imports, deptry, vulture, pip-audit | 7 | | TypeScript | typecheck, eslint, prettier, knip, depcruise | 5 | | .NET | dotnet build, dotnet format | 2 |

3. Set TOTAL to match active checks count
4. Uncomment matching auto-fix commands in --fix block
5. Make executable: chmod +x scripts/lint.sh
6. For TypeScript: ensure "lint:all" script exists in package.json

---

Phase 5: Verify Setup

After configuration, verify everything works.

TypeScript:

npx tsc --noEmit
npx eslint .
npx prettier --check .

.NET:

dotnet format --verify-no-changes

Python:

ruff check .
ruff format --check .
mypy

Unified verification:

bash scripts/lint.sh

Expected: Exit code 0 for all checks.

On Failure: Check error output, adjust config, re-verify.

---

Phase 6: Fix Lint Errors

After generating all configs and installing tools, run bash scripts/lint.sh --all to see all violations.

1. Run bash scripts/lint.sh --fix to auto-fix what ruff can
2. Fix remaining errors manually (file by file)
3. For C901 (complexity) on functions that cannot be refactored now: add # noqa: C901
4. For deptry false positives: add [tool.deptry.per_rule_ignores] entries
5. Repeat until bash scripts/lint.sh passes with 0 failures

---

Critical Rules

RULE 1: Always include eslint-config-prettier (last in config) when using ESLint + Prettier together.

RULE 2: Use ESLint flat config format (eslint.config.ts), NOT legacy .eslintrc.

RULE 3: Ruff replaces Black, isort, flake8, and many other Python tools. Do NOT install them separately.

RULE 4: Never disable strict TypeScript rules without documented reason.

RULE 5: Always run mypy alongside Ruff for Python projects. Ruff handles style/bugs, mypy handles type safety.

RULE 6: Use recommendedTypeChecked as ESLint default, not just recommended. Downgrade individual rules if needed.

RULE 7: Never pin dependency versions in install commands -- always install latest.

RULE 8: Advanced static analysis tools (import-linter, deptry, vulture, pip-audit) are MANDATORY for Python projects, not optional.

---

Monitor (2.1.98+): When lint/typecheck verification commands expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

• [ ] Appropriate config files created for detected stack
• [ ] Dependencies installed (latest versions)
• [ ] scripts/lint.sh generated with correct checks for stack
• [ ] Lint command runs without errors on project source
• [ ] Format command runs without errors
• [ ] Type checker runs without errors (mypy for Python, tsc for TypeScript)
• [ ] No ESLint/Prettier conflicts (eslint-config-prettier installed)
• [ ] Advanced tools installed and configured (import-linter, deptry, vulture, pip-audit)
• [ ] scripts/lint.sh runs ALL checks (7 for Python) with exit code 0
• [ ] .editorconfig created with settings matching ruff config
• [ ] User informed of available lint/format commands

---

Reference Files

| File | Purpose | |------|---------| | eslint_template.ts | ESLint flat config template (TypeScript) | | prettier_template.json | Prettier config template | | ruff_template.toml | Python Ruff config template | | mypy_template.toml | Python mypy config template | | lint_script_template.sh | Unified lint script template | | editorconfig_template.ini | .NET editorconfig template | | directory_build_props_template.xml | .NET analyzers template | | importlinter_template.toml | Python import-linter config template | | vulture_template.toml | Python vulture config template | | deptry_template.toml | Python deptry config template | | linter_guide.md | Detailed configuration guide |

---

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | ESLint/Prettier conflict | Missing eslint-config-prettier | Install and add as last config | | ESLint projectService error | Config file not in tsconfig | Add to allowDefaultProject list | | ESLint .ts config fails | Missing jiti | npm install -D jiti | | TypeScript parse errors | Parser version mismatch | Align typescript-eslint with TS version | | mypy missing stubs | Third-party library without types | Add [[mypy.overrides]] with ignore_missing_imports | | mypy strict too strict | Hundreds of errors on first run | Start with relaxed config, enable strict gradually | | Ruff not found | Not installed | pip install ruff or uv add ruff | | dotnet format fails | Missing SDK | Install .NET SDK |

---

Version: 4.0.0 Last Updated: 2026-03-18