name	pdlc-lint
description	代码质量检查与自动修复
argument-hint	["目录 \| 文件"]
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
layer	3
stage	quality
produces	[]
requires	[]
next_step	null
terminal_state	null

代码质量检查与自动修复

对项目代码执行静态分析、风格检查和质量度量，自动修复可安全修复的问题，输出结构化报告。

子命令解析

从 $ARGUMENTS 中解析子命令和参数：

子命令	格式	说明
`check [目标]`	运行全量检查，输出报告（默认子命令）
`fix [目标]`	自动修复可安全修复的问题
`setup`	为项目配置 lint 工具链（检测技术栈，生成配置文件）

目标 可选，支持：服务名、应用名、目录路径、文件路径。不传则检查整个项目。
如果未提供子命令，默认执行 check。

工具链自动探测

扫描项目目录，按以下优先级检测已有的 lint 工具：

前端 / Node.js 项目

按优先级检测（找到第一个可用的即停止）：

工具	检测方式	运行命令
ESLint（flat config）	`eslint.config.*` 存在	`npx eslint .`
ESLint（legacy）	`.eslintrc*` 存在	`npx eslint .`
Biome	`biome.json` 或 `biome.jsonc` 存在	`npx biome check .`
oxlint	`package.json` 含 `oxlint` 依赖	`npx oxlint .`

样式检查（与上述并行）：

工具	检测方式	运行命令
Stylelint	`.stylelintrc` 或 `stylelint.config.` 存在	`npx stylelint "*/.{css,scss,less}"`
Prettier	`.prettierrc` 或 `prettier.config.` 存在	`npx prettier --check .`

TypeScript 类型检查（如存在 tsconfig.json）：

npx tsc --noEmit

后端 Java 项目

工具	检测方式	运行命令
Checkstyle	`checkstyle*.xml` 或 pom.xml 含 checkstyle plugin	`mvn checkstyle:check`
SpotBugs	pom.xml 含 spotbugs plugin	`mvn spotbugs:check`
PMD	pom.xml 含 pmd plugin	`mvn pmd:check`
SonarQube	`sonar-project.properties` 或 pom.xml 含 sonar plugin	`mvn sonar:sonar`（需配置连接）
Spotless	pom.xml 含 spotless plugin	`mvn spotless:check`

Gradle 项目检测 build.gradle / build.gradle.kts 并使用对应 gradle 命令。

后端 Go 项目

工具	检测方式	运行命令
golangci-lint	`.golangci.yml` 或 `go.mod` 存在	`golangci-lint run ./...`
go vet	`go.mod` 存在	`go vet ./...`
staticcheck	`go.mod` 存在	`staticcheck ./...`

后端 Python 项目

工具	检测方式	运行命令
Ruff	`ruff.toml` 或 `pyproject.toml` 含 `[tool.ruff]`	`ruff check .`
Flake8	`.flake8` 或 `setup.cfg` 含 `[flake8]`	`flake8 .`
Pylint	`.pylintrc` 或 `pyproject.toml` 含 `[tool.pylint]`	`pylint */.py`
MyPy	`mypy.ini` 或 `pyproject.toml` 含 `[tool.mypy]`	`mypy .`
Black	`pyproject.toml` 含 `[tool.black]`	`black --check .`

子命令执行流程

check [目标]

探测工具链：按上述规则检测项目使用的 lint 工具
未检测到任何工具 → 输出提示后自动执行 setup 子命令：
```
⚠️ 未检测到 lint 工具配置，正在为项目自动配置...
```
检测到工具 → 按以下顺序运行： a. 代码风格检查（ESLint / Biome / Checkstyle / golangci-lint / Ruff 等） b. 类型检查（TypeScript tsc / MyPy / go vet 等） c. 安全扫描（如有 npm audit / mvn dependency:analyze / safety check） d. 代码复杂度分析（从 lint 输出中提取，或使用工具内置规则）

收集结果，按严重程度分类：

级别	含义	示例
🔴 Error	必须修复	语法错误、类型错误、安全漏洞
🟠 Warning	应该修复	未使用变量、复杂度过高、潜在 Bug
🟡 Info	建议修复	命名不规范、缺少 JSDoc、import 排序
🔵 Style	可自动修复	格式化、尾逗号、引号风格

输出报告：

## 代码质量报告

### 工具链
| 工具 | 版本 | 状态 |
|------|------|------|
| ESLint | 9.x | ✅ 已运行 |
| TypeScript | 5.x | ✅ 已运行 |
| Prettier | 3.x | ✅ 已运行 |

### 问题汇总
| 级别 | 数量 | 可自动修复 |
|------|------|-----------|
| 🔴 Error | N | N |
| 🟠 Warning | N | N |
| 🟡 Info | N | N |
| 🔵 Style | N | N |

### 问题详情（按文件分组）

#### `src/services/userService.ts`
| 行 | 级别 | 规则 | 描述 | 可修复 |
|----|------|------|------|--------|
| 23 | 🔴 | @typescript-eslint/no-explicit-any | 避免使用 any 类型 | ❌ |
| 45 | 🔵 | prettier/prettier | 格式化不一致 | ✅ |

### 质量指标
- 问题密度：X 个/千行代码
- 可自动修复比例：XX%

### 建议
👉 运行 `/pdlc-lint fix` 自动修复 N 个问题

fix [目标]

探测工具链（同 check）
先运行 check 收集所有问题，统计可自动修复数量

执行自动修复（按工具分别运行）：

技术栈	修复命令
ESLint	`npx eslint --fix .`
Biome	`npx biome check --write .`
Prettier	`npx prettier --write .`
Stylelint	`npx stylelint --fix "*/.{css,scss,less}"`
Spotless (Java)	`mvn spotless:apply`
golangci-lint	`golangci-lint run --fix ./...`
Ruff	`ruff check --fix .`
Black	`black .`

修复后再次运行 check，对比修复前后数量
输出报告：

## 自动修复报告

### 修复结果
| 指标 | 修复前 | 修复后 | 变化 |
|------|--------|--------|------|
| 🔴 Error | N | N | -N |
| 🟠 Warning | N | N | -N |
| 🟡 Info | N | N | -N |
| 🔵 Style | N | 0 | -N |
| **总计** | N | N | **-N** |

### 修改的文件
| 文件 | 修复数 |
|------|--------|
| src/xxx.ts | N |

### 剩余需手动修复的问题
（列出无法自动修复的 Error 和 Warning）

### 建议
- 🔴 Error 需要手动修复，建议逐一处理
- 考虑将 lint 检查加入 CI：`/pdlc-ship`（发布流水线含 CI/CD 配置管理）

不自动提交：修复后的文件保留为未暂存状态，由用户决定是否提交

setup

探测技术栈：扫描 package.json、pom.xml、build.gradle、go.mod、pyproject.toml、requirements.txt 等
按技术栈生成配置文件：

Node.js / 前端项目：
- 生成 eslint.config.mjs（flat config，ESLint 9+）
- 生成 .prettierrc（格式化配置）
- 若有 TypeScript，确保 tsconfig.json 含 strict: true
- 在 package.json 的 scripts 中追加：
```
"lint": "eslint .",
"lint:fix": "eslint --fix . && prettier --write .",
"type-check": "tsc --noEmit"
```
Java/Maven 项目：
- 在 pom.xml 中追加 Checkstyle + Spotless plugin（若不存在）
- 生成 checkstyle.xml（基于 Google Java Style 或项目已有规范）
Go 项目：
- 生成 .golangci.yml（含常用 linter 配置）
Python 项目：
- 生成 ruff.toml（推荐 Ruff 作为默认 linter）
- 配置 line-length、target-version 等

检查 Git Hooks：

若未配置 pre-commit hook，建议配置：

💡 建议配置 Git pre-commit hook 自动运行 lint：
   npx husky init          # Node.js 项目
   pre-commit install      # Python 项目（需 pip install pre-commit）

输出配置报告：

✅ Lint 工具链配置完成

已生成/更新的配置文件：
  📄 eslint.config.mjs
  📄 .prettierrc
  📄 package.json (scripts)

已检测的技术栈：
  - TypeScript 5.x + React 18
  - Tailwind CSS 3.x

建议下一步：
  /pdlc-lint check     ← 运行首次全量检查
  /pdlc-lint fix       ← 自动修复可修复的问题
  /pdlc-ship           ← 将 lint 加入 CI 流水线（发布时自动配置）

与其他 PDLC 命令的联动

/pdlc-feature：可在阶段五（自查评审）中自动触发 lint check 验证代码质量
/pdlc-review：评审时参考 lint 报告
/pdlc-ship：在发布流水线的 CI/CD 配置中增加 lint 阶段

要求

不修改 lint 工具本身的配置（除 setup 子命令外）
fix 子命令只修复工具标记为"可自动修复"的问题，不做额外改动
遇到工具未安装的情况，优先使用 npx / mvn 等包管理器临时调用

检查目标: $ARGUMENTS

本命令的 handoff 输出：

✅ 代码质量检查 完成
📦 产出：（lint 报告输出到控制台）
👉 下一步：（本次流程结束，无后续）