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.

ln-741-linter-configurator

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-740-quality-setup

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 (ln-742 does this)
Set up test infrastructure (ln-743 does this)
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:

If config exists and is complete: SKIP (inform user)
If config exists but incomplete: ASK user to merge or replace
If no config exists: CREATE from template

Phase 2: Generate Configuration

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

TypeScript:

Copy eslint_template.ts to project root as eslint.config.ts
Copy prettier_template.json as .prettierrc
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"
For React projects: uncomment React sections in template

.NET:

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

Python:

Copy ruff_template.toml as ruff.toml
- OR merge into existing pyproject.toml under [tool.ruff]
Copy mypy_template.toml as mypy.toml
- OR merge into existing pyproject.toml under [tool.mypy]
Update known-first-party in isort config to match project package name
Update files in mypy config to match project source directories

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

# OR without uv:
pip install ruff mypy

Phase 4: Generate Lint Script

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

Copy lint_script_template.sh to scripts/lint.sh
Uncomment the check lines matching the detected stack (Python/TypeScript/.NET)
Set TOTAL variable to match the number of active checks
Make file executable: chmod +x scripts/lint.sh
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: Optional Advanced Tools

Suggest but do not auto-install. Inform user and add as commented lines in scripts/lint.sh.

| Stack | Tool | Purpose | Install | |-------|------|---------|---------| | TypeScript | dependency-cruiser | Architecture boundary validation | npm install -D dependency-cruiser | | TypeScript | knip | Unused code/dependency detection | npm install -D knip | | Python | vulture / deadcode | Dead code detection | uv add --dev vulture | | Python | import-linter | Circular import prevention | uv add --dev import-linter | | Python | deptry | Unused/missing dependency detection | uv add --dev deptry | | .NET | CSharpier | Opinionated formatter (Prettier for C#) | dotnet tool install csharpier |

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.

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)
[ ] User informed of available lint/format commands and optional advanced tools

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 | | 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: 3.0.0 Last Updated: 2026-02-26