# Yy Enable Lint

> 为项目添加可通过 npm run lint 执行的 lint 支持。用于需要为前端、Node.js 或 Python 项目接入格式化、代码检查、Markdown 检查、类型检测和测试流程时触发；不用于只运行已有 lint 命令或只修复 lint 报错。

- Skill: `bulls-cows/yy-enable-lint` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-enable-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-enable-lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-enable-lint

---


# yy-enable-lint

## 描述

为项目补齐 `npm run lint` 入口，使 lint 流程覆盖格式化、代码文件检查、Markdown 文件检查、类型检测和测试用例执行。支持前端项目、Node.js 项目和 Python 项目；没有 `package.json` 的项目也要创建最小化 `package.json` 作为统一命令入口。

## 使用场景

- 用户要求给项目添加 lint 支持
- 用户要求补齐 `npm run lint` 命令
- 用户要求统一格式化、代码检查、Markdown 检查、类型检测和测试流程
- 用户要求为前端、Node.js 或 Python 项目接入基础质量检查

不应触发：

- 用户只是要求运行已有 lint 命令
- 用户只是要求修复 lint 报错
- 用户只是要求新增业务测试用例
- 用户要求接入非 `npm run lint` 的质量检查入口

## 指令

### 步骤 1. 确认目标项目

确定需要接入 lint 的项目根目录，并读取项目说明、依赖清单和现有配置。

**必须检查的文件或目录**：

- `package.json`
- `.editorconfig`
- `pyproject.toml`、`requirements.txt`、`setup.cfg`、`tox.ini`
- `tsconfig.json`、`tsconfig.*.json`、`jsconfig.json`
- `src/`、`test/`、`tests/`、`__tests__/`
- 已存在的 ESLint、Prettier、markdownlint、Ruff、pytest、unittest、Vitest、Jest、Node.js test runner、`tsc`、`vue-tsc`、mypy 或 pyright 配置

**决策分支**：

- **存在项目规范文件**：先读取并遵守项目规范，再继续后续步骤
- **不存在 `.editorconfig`**：新增 `.editorconfig`，使用通用 UTF-8、两个空格缩进、LF 换行、文件末尾换行和清理行尾空白配置
- **不存在 `package.json`**：创建最小化 `package.json`，用于承载 `npm run lint` 统一入口
- **项目类型无法判断**：只创建通用 Markdown 检查和格式化入口，并明确标记代码检查、类型检测和测试流程需要用户补充技术栈信息

### 步骤 2. 识别项目类型

根据文件结构和依赖判断项目类型，允许同时命中多个类型。

**决策分支**：

- **前端项目**：存在 Vite、Vue、React、Next.js、Nuxt、Svelte、Astro 或浏览器端构建配置时，按前端项目处理
- **Node.js 项目**：存在 Node.js 入口、脚本、库代码或 `package.json` 依赖，但不属于纯前端项目时，按 Node.js 项目处理
- **Python 项目**：存在 Python 源码、`pyproject.toml`、`requirements.txt` 或 `tests/` 中的 Python 测试时，按 Python 项目处理
- **混合项目**：同时保留各语言的检查与测试入口，并由 `npm run lint` 统一串联

### 步骤 3. 设计 lint 脚本

在 `package.json` 中补齐脚本，保证 `npm run lint` 同时覆盖格式化、代码检查、Markdown 检查、类型检测和测试流程。

脚本片段可参考 `templates/lint-script-patterns.md`，但必须按目标项目已有脚本、依赖和配置裁剪，不得无差别复制模板。

**推荐脚本结构**：

- `lint`：串联执行 `lint:format`、`lint:code`、`lint:markdown`、`lint:typecheck`、`test`
- `lint:format`：格式化代码、配置文件和 Markdown 文件
- `lint:code`：检查项目代码文件
- `lint:markdown`：检查 Markdown 文件
- `lint:typecheck`：执行 TypeScript、Vue 或 Python 类型检测
- `test`：执行项目测试用例

**脚本组织规则**：

- **已有 `node --run` 风格**：优先沿用 `node --run <script>` 串联脚本
- **已有 `npm run` 风格**：优先沿用 `npm run <script>` 串联脚本
- **已有 `run-s`、`npm-run-all2` 或通配脚本**：可复用并保持原有并行或串行策略
- **Python 项目只有 npm 包装入口**：保持 `package.json` 轻量，只把 Python 工具命令包装到 npm 脚本中
- **混合项目**：将各语言检查拆成清晰子脚本，再由 `lint` 串联，避免单个长命令难以维护

**配置优先级**：

- 能由配置文件表达的文件范围、忽略项和规则，必须优先写入工具配置，不在 npm 脚本中堆叠 glob、文件列表、忽略项或规则参数
- Prettier 优先使用项目根目录 `.prettierignore` 管理依赖目录、构建产物、环境文件和不应格式化的目录；`lint:format` 脚本优先保持为 `prettier --write .`
- ESLint 优先使用现有 ESLint 配置管理规则和忽略范围；仅在工具配置无法表达时，才在脚本中保留少量必要参数，并说明原因
- Markdown 检查优先使用 `.markdownlint-cli2.jsonc` 管理 `globs`、`ignores`、`fix` 和规则配置
- 类型检查优先使用 `tsconfig.json`、`pyproject.toml`、mypy 或 pyright 配置管理包含范围和排除项

**决策分支**：

- **已有同名脚本且语义一致**：优先复用原脚本，只补齐缺失的子脚本或串联关系
- **已有同名脚本但语义冲突**：保留原脚本，新增更具体的子脚本名称，并将 `lint` 调整为统一入口
- **缺少 Markdown 检查**：新增 `markdownlint-cli2` 依赖、配置文件和轻量脚本入口
- **缺少格式化**：新增 Prettier、Ruff 或项目已有格式化工具入口
- **缺少类型检测**：按项目类型新增 `lint:typecheck` 脚本和必要配置
- **缺少测试脚本**：按步骤 5 创建最小化测试用例和测试入口

### 步骤 4. 接入检查工具

优先复用项目已有工具；缺失时按项目类型补齐最小依赖和配置。

**依赖安装版本策略**：

- 新装依赖时优先安装较新的稳定版本，避免固定到已过时的旧版本
- 不清楚依赖最新版本时，通过包管理器指定 `@latest` 安装最新版本，例如 `npm install -D packagename@latest`
- 依赖版本以实际安装结果为准写入清单，不手工猜测版本号

**前端与 Node.js 项目**：

- 代码检查优先使用已有 ESLint 配置
- 缺少 ESLint 时，按项目语言和框架补齐最小 ESLint 配置
- 使用 ESLint 时，`lint:code` 脚本中必须添加 `--fix` 参数以启用自动修复；不加 `--fix` 时 ESLint 仅报告错误而不自动修复
- 格式化优先使用 Prettier
- 使用 Prettier 时，先读取已有 `.prettierignore`；缺失时新建该文件并将依赖目录、构建产物、环境文件和项目特有的生成目录写入其中
- 使用 Prettier 时，`format` 脚本中必须添加 `--write` 参数以启用原地格式化；不加 `--write` 时 Prettier 仅输出差异而不修改文件
- `package.json` 中的 `lint:format` 脚本优先保持为 `prettier --write .`，不内联维护文件列表、glob 或 `--ignore-path`；仅当项目工具限制导致无法使用 `.prettierignore` 时，才保留必要参数并说明原因
- TypeScript 项目使用 `tsc -p tsconfig.json --noEmit`；Vue 项目优先使用 `vue-tsc --build`
- JavaScript 项目只有在已有 `jsconfig.json`、`tsconfig.json` 或 `checkJs` 约定时接入类型检测
- 测试优先复用已有 Vitest、Jest、Playwright 或 Node.js test runner

**Python 项目**：

- 代码检查优先使用 Ruff
- 使用 Ruff 进行代码检查时，`lint:code` 脚本中必须添加 `--fix` 参数以启用自动修复；不加 `--fix` 时 Ruff 仅报告错误而不自动修复
- 格式化优先使用 Ruff format；存在 Black 配置时可复用 Black。使用 Ruff format 时无需额外参数，`ruff format` 默认原地格式化文件
- 类型检测优先复用已有 mypy 或 pyright 配置；缺失时根据项目依赖和类型标注规模补齐最小 `lint:typecheck` 入口
- Python 项目中只要存在 `package.json` 文件，pyright 配置就必须排除 `node_modules`，不以目录是否已存在作为判断条件
- 测试优先复用已有 pytest 或 unittest
- 通过 `package.json` 脚本调用 Python 工具，保持 `npm run lint` 作为统一入口

**Markdown 文件**：

- 优先使用 `markdownlint-cli2`
- 优先使用 `.markdownlint-cli2.jsonc` 配置 `globs`、`ignores`、`fix` 和 `config`，把可配置参数写入配置文件。将 `fix` 设置为 `true`，使 markdownlint-cli2 在检查时自动修复可修复的 Markdown 问题
- 在配置中设置 `"gitignore": true`，自动排除 `.gitignore` 中的文件，无需手动维护两套忽略列表
- `ignores` 字段仅保留 `.gitignore` 未覆盖的额外忽略项（如项目特有的非 git 忽略文件）
- `package.json` 中的 `lint:markdown` 脚本优先保持为 `markdownlint-cli2`，避免在命令中传递 glob、忽略项或 `--fix` 等参数
- 格式化可由 Prettier 覆盖 Markdown 文件

**EditorConfig 文件**：

- 如果项目根目录不存在 `.editorconfig`，新增 `.editorconfig`，为后续格式化工具提供基础编辑器约定
- 新增 `.editorconfig` 时，优先使用以下配置：
  - 顶部：`root = true`
  - `[*]` 段：`charset = utf-8`、`indent_style = space`、`indent_size = 2`、`end_of_line = lf`、`insert_final_newline = true`、`trim_trailing_whitespace = true`
- 如果项目根目录已存在 `.editorconfig`，只读取并遵守，不为统一风格而重写已有配置
- 如果目标项目已有明确缩进、换行或字符集约定，新增 `.editorconfig` 时按项目约定调整对应字段，并在输出中说明依据

### 步骤 5. 补齐最小测试

检查项目是否已有可由命令执行的测试用例。

**决策分支**：

- **已有测试用例和测试命令**：复用现有测试命令，不新增测试文件
- **前端或 Node.js 项目无测试**：创建最小化 smoke test，验证项目基础文件或公开入口可访问
- **Python 项目无测试**：在 `tests/` 下创建最小化 pytest 测试，验证项目基础导入或项目根目录存在
- **混合项目无测试**：分别为命中的技术栈创建最小测试，并由 `npm run test` 串联执行

最小测试只用于跑通测试流程，不应引入业务断言或改变业务代码。

### 步骤 6. 修改项目文件

按最小必要改动落地配置和脚本。

**允许修改的文件类型**：

- `package.json` 和必要的锁文件
- `.editorconfig`
- ESLint、Prettier、markdownlint、Ruff、pytest 或测试框架配置文件
- TypeScript、Vue、mypy、pyright 或其他类型检测配置文件
- 最小化测试文件
- 必要的开发依赖清单文件

**修改原则**：

- 不删除已有脚本、配置和测试
- 不重写无关配置项
- 不把 lint 接入扩散成项目重构
- 不手动修改自动生成文件，除非依赖安装命令生成或更新
- 新增配置优先使用项目已采用的文件格式和命名风格

### 步骤 7. 输出结果

输出内容必须包含：

1. 修改原因和影响范围
2. 新增或更新的文件列表
3. `.editorconfig` 处理方式，必须说明是新增、复用还是按项目约定调整
4. `npm run lint` 覆盖的流程，必须说明类型检测入口
5. 测试用例处理方式
6. 后续验证建议和注意事项

## 安全边界

- 不主动执行发布、部署、清理缓存或删除文件命令
- 不在接入完成后主动执行 `npm run lint`，避免格式化产生大量额外改动
- 不为通过 lint 而删除业务代码、跳过测试或降低规则强度
- 不在未确认的情况下引入大型框架迁移或替换项目既有工具链
- 不把最小测试写成依赖外部网络、真实账号或生产数据的测试

## 相关资源

- `templates/lint-script-patterns.md`：不同类型项目的 `npm run lint` 脚本模式参考