ln-741-linter-configurator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ln-741-linter-configurator

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

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

类型： L3 Worker 分类： 7XX 项目初始化 父项： ln-740-质量设置

为TypeScript、.NET和Python项目配置代码检查与格式化工具。

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
Verifies linter runs without errors

Does NOT:

Configure pre-commit hooks (ln-742 does this)
Set up test infrastructure (ln-743 does this)
Modify source code

支持的操作：

根据项目类型检测需要配置的代码检查工具栈
检查是否存在现有代码检查配置
从模板生成对应的配置文件
安装所需依赖
验证代码检查工具可正常运行且无错误

不支持的操作：

配置提交前钩子（由ln-742负责）
搭建测试基础设施（由ln-743负责）
修改源代码

Supported Stacks

支持的技术栈

Technology	Linter	Formatter	Config Files
TypeScript/React	ESLint 9+ (flat config)	Prettier	`eslint.config.mjs` , `.prettierrc`
.NET	Roslyn Analyzers	dotnet format	`.editorconfig` , `Directory.Build.props`
Python	Ruff	Ruff (built-in)	`ruff.toml` or `pyproject.toml`

技术	代码检查器	格式化工具	配置文件
TypeScript/React	ESLint 9+（扁平化配置）	Prettier	`eslint.config.mjs` , `.prettierrc`
.NET	Roslyn Analyzers	dotnet format	`.editorconfig` , `Directory.Build.props`
Python	Ruff	Ruff（内置）	`ruff.toml` 或 `pyproject.toml`

Phase 1: Check Existing Configuration

阶段1：检查现有配置

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`

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

生成配置前，先检查已有的配置情况。

需要检查的文件：

技术栈	配置文件	通配符模式
TypeScript	ESLint配置	`eslint.config.` , `.eslintrc`
TypeScript	Prettier配置	`.prettierrc` , `prettier.config.`
.NET	Editor配置	`.editorconfig`
.NET	Build属性	`Directory.Build.props`
Python	Ruff配置	`ruff.toml` , `pyproject.toml`

决策逻辑：

若配置已存在且完整：跳过（告知用户）
若配置已存在但不完整：询问用户是合并还是替换
若不存在配置：从模板创建

Phase 2: Generate Configuration

阶段2：生成配置

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

TypeScript/React:

Copy
```
eslint_template.mjs
```
to project root as
```
eslint.config.mjs
```
Copy
```
prettier_template.json
```
as
```
.prettierrc
```

Add scripts to

package.json

```
"lint": "eslint ."
```
```
"lint:fix": "eslint . --fix"
```
```
"format": "prettier --write ."
```
```
"format:check": "prettier --check ."
```

.NET:

Copy
```
editorconfig_template.ini
```
as
```
.editorconfig
```

Copy

directory_build_props_template.xml

Directory.Build.props

Ensure analyzers package reference included

Python:

Copy

ruff_template.toml

ruff.toml

OR merge into existing
```
pyproject.toml
```
under
```
[tool.ruff]
```

Add scripts to
```
pyproject.toml
```
or document commands

使用references/文件夹中的模板，根据项目情况自定义占位符内容。

TypeScript/React：

将
```
eslint_template.mjs
```
复制到项目根目录并重命名为
```
eslint.config.mjs
```
将
```
prettier_template.json
```
复制为
```
.prettierrc
```

向

package.json

添加脚本：

```
"lint": "eslint ."
```
```
"lint:fix": "eslint . --fix"
```
```
"format": "prettier --write ."
```
```
"format:check": "prettier --check ."
```

.NET：

将
```
editorconfig_template.ini
```
复制为
```
.editorconfig
```

将

directory_build_props_template.xml

复制为

Directory.Build.props

确保已包含代码分析器包引用

Python：

将

ruff_template.toml

复制为

ruff.toml

或者合并到现有
```
pyproject.toml
```
的
```
[tool.ruff]
```
节点下

向
```
pyproject.toml
```
添加脚本或记录相关命令

Phase 3: Install Dependencies

阶段3：安装依赖

Install required packages for each stack.

TypeScript/React:

npm install -D eslint @eslint/js typescript-eslint eslint-plugin-react eslint-plugin-react-hooks eslint-config-prettier prettier

CRITICAL:
eslint-config-prettier
is REQUIRED to prevent ESLint/Prettier conflicts.

.NET:

Analyzers configured via Directory.Build.props
No separate install needed

Python:

pip install ruff

为每个技术栈安装所需的包。

TypeScript/React：

npm install -D eslint @eslint/js typescript-eslint eslint-plugin-react eslint-plugin-react-hooks eslint-config-prettier prettier

重要提示：
eslint-config-prettier
是防止ESLint与Prettier冲突的必需依赖。

.NET：

代码分析器通过Directory.Build.props配置
无需单独安装

Python：

pip install ruff

OR with uv:

或使用uv：

uv add --dev ruff

---

uv add --dev ruff

---

Phase 4: Verify Setup

阶段4：验证设置

After configuration, verify linter works.

TypeScript:

bash

npm run lint
npm run format:check

Expected: Exit code 0

.NET:

bash

dotnet format --verify-no-changes

Expected: Exit code 0

Python:

bash

ruff check .
ruff format --check .

Expected: Exit code 0

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

配置完成后，验证代码检查工具是否正常工作。

TypeScript：

bash

npm run lint
npm run format:check

预期结果： 退出码为0

.NET：

bash

dotnet format --verify-no-changes

预期结果： 退出码为0

Python：

bash

ruff check .
ruff format --check .

预期结果： 退出码为0

若验证失败： 检查错误输出，调整配置后重新验证。

Critical Rules

关键规则

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

RULE 2: Use ESLint flat config format (eslint.config.mjs), 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.

规则1： 当同时使用ESLint和Prettier时，必须包含
eslint-config-prettier
。

规则2： 使用ESLint扁平化配置格式（eslint.config.mjs），而非传统的.eslintrc。

规则3： Ruff可替代Black、isort、flake8等众多Python工具，请勿单独安装这些工具。

规则4： 禁止在无文档说明原因的情况下禁用严格的TypeScript规则。

Definition of Done

完成标准

Reference Files

参考文件

File	Purpose
eslint_template.mjs	ESLint flat config template
prettier_template.json	Prettier config template
editorconfig_template.ini	.NET editorconfig template
directory_build_props_template.xml	.NET analyzers template
ruff_template.toml	Python Ruff config template
linter_guide.md	Detailed configuration guide

文件	用途
eslint_template.mjs	ESLint扁平化配置模板
prettier_template.json	Prettier配置模板
editorconfig_template.ini	.NET editorconfig模板
directory_build_props_template.xml	.NET代码分析器模板
ruff_template.toml	Python Ruff配置模板
linter_guide.md	详细配置指南

Error Handling

错误处理

Error	Cause	Resolution
ESLint/Prettier conflict	Missing eslint-config-prettier	Install and add to config
TypeScript parse errors	Parser version mismatch	Align typescript-eslint with TS version
Ruff not found	Not installed	`pip install ruff` or `uv add ruff`
dotnet format fails	Missing SDK	Install .NET SDK

Version: 2.0.0 Last Updated: 2026-01-10

错误	原因	解决方法
ESLint/Prettier冲突	缺少eslint-config-prettier	安装该依赖并添加到配置中
TypeScript解析错误	解析器版本不匹配	使typescript-eslint与TS版本保持一致
找不到Ruff	未安装	执行 `pip install ruff` 或 `uv add ruff`
dotnet format执行失败	缺少SDK	安装.NET SDK

版本： 2.0.0 最后更新时间： 2026-01-10