my-code-style 1.8.6 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## 变更日志
 
+## [1.9.0](https://github.com/myvn/codeStyle/compare/v1.8.6...v1.9.0) (2026-09-23)
+
+### ✨ Features | 新功能
+
+- **cli:** 新增 my-code-style-doctor 独立体检命令 ([fd3ac0d](https://github.com/myvn/codeStyle/commit/fd3ac0da3ac123f1bf69e755da1de288bdf5eeb4)), closes [#6](https://github.com/myvn/codeStyle/issues/6)
+- **init:** --merge 合并模式 + 收尾 hook 自检 ([f6f6fa7](https://github.com/myvn/codeStyle/commit/f6f6fa7f391f4371a9cd76ff8e436c7061b25335)), closes [#7](https://github.com/myvn/codeStyle/issues/7) [#8](https://github.com/myvn/codeStyle/issues/8)
+
+### 🐛 Bug Fixes | Bug 修复
+
+- **prettier:** 默认 prettierignore 纳入各包管理器 lockfile（BUG-034） ([ece6d03](https://github.com/myvn/codeStyle/commit/ece6d035d3d71e64e1aca541dd49efaab615da48)), closes [#9](https://github.com/myvn/codeStyle/issues/9)
+
 ## [1.8.6](https://github.com/myvn/codeStyle/compare/v1.8.5...v1.8.6) (2026-09-22)
 
 ### 🐛 Bug Fixes | Bug 修复

package/README.md

@@ -25,7 +25,7 @@ pnpm add -D my-code-style            # npm: npm i -D my-code-style
 npx my-code-style-init --dry-run
 npx my-code-style-init                # 需保留旧文件时加 --backup
 
-# 3. 按 CLI 输出的缺失依赖清单安装 peerDependencies（会按包管理器生成命令，别漏 typescript）
+# 3. 按 CLI 输出的缺失依赖清单安装 peerDependencies（会按包管理器生成命令，别漏 typescript 和 stylelint-order——后者是 recess-order 7 的 peer，Vue/SCSS 项目缺了它 stylelint 直接崩）
 pnpm add -D my-code-style eslint@^9.0.0 typescript@^5.0.0 prettier@^3.0.0 ...   # 以 CLI 实际输出为准
 
 # 4. 初始化 hooks 并首次检查
@@ -195,13 +195,30 @@ module.exports = {
 ## CLI 初始化参数
 
 ```bash
-npx my-code-style-init [--dry-run] [--backup] [--version|-v] [--help|-h]
+npx my-code-style-init [--dry-run] [--backup] [--merge] [--version|-v] [--help|-h]
 ```
 
 - `--dry-run`：试运行模式，仅输出将执行的变更，不修改任何文件。
 - `--backup`：在覆盖已有配置文件之前，将其备份到 `.my-code-style-backup/` 目录。
+- `--merge`（别名 `--no-overwrite`）：合并模式——已存在的配置与 hooks 一律保留，只补缺失文件；`package.json` 只新增缺失的 scripts，已有 `lint-staged` 分组原样保留。适合升级场景先合并、再人工比对。
+- 初始化结束时**自动自检 hooks**（存在 / 非空 / 可执行位 / `lint-staged`、`commitlint` 是否可解析），只提示不阻断——把"hook 存在但不生效"消灭在当场。
 - 具备**事务回滚保护**：若在写入过程中遭遇文件权限或磁盘异常，自动回滚所有修改，恢复工作区原始状态。
 
+## 项目体检：my-code-style-doctor
+
+```bash
+npx my-code-style-doctor
+```
+
+对既有项目随时复验（init 的依赖体检只在新装/重装时打印一次）：
+
+- **peer 依赖**：按项目类型裁剪核对（与 init 同口径——ESLint 8 才查 classic import、无预处理器不查 stylelint 族），缺失/版本越界逐项报红，并输出可整段粘贴的补齐命令；
+- **husky hooks**：存在 / 非空 / 可执行位 / 引用命令可解析 / `core.hooksPath` 指向；
+- **lockfile**：是否被 `.gitignore` 排除（排除 = 不同机器版本组合不可复现）；
+- **配置文件**：四件套是否就位。
+
+退出码 `0` 健康 / `1` 有问题，可直接当 CI 门禁用。
+
 ## 特性
 
 - **双引号**：`quotes: ["error", "double", { avoidEscape: true, allowTemplateLiterals: true }]`（`avoidEscape` 必须为 `true`，否则与 Prettier 的转义策略冲突，`--fix` 无法消除报错）
@@ -218,32 +235,33 @@ npx my-code-style-init [--dry-run] [--backup] [--version|-v] [--help|-h]
 
 ## 常见问题（使用中遇到的问题）
 
-| 现象                                                                 | 原因                                                                           | 处理                                                                                                                                                                                                                                                    |
-| -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 只装了 `my-code-style`，`pnpm lint` 报找不到 eslint                  | peerDependencies 全部是 optional，不会自动安装                                 | 按 CLI 结尾输出的清单装全，**别漏 `typescript`**（`@typescript-eslint/parser` / `typescript-eslint` 的必需 peer）                                                                                                                                       |
-| `pnpm prepare` 输出 `.git can't be found`，hooks 不生效              | husky 必须在 git 仓库内执行                                                    | 先 `git init`、再 `pnpm prepare`；验证 `git config core.hooksPath` 输出 `.husky/_`                                                                                                                                                                      |
-| 安装依赖报 `ERR_PNPM_IGNORED_BUILDS`（如 `unrs-resolver`）           | pnpm 10+ 默认拦截依赖的构建脚本                                                | 执行 `pnpm approve-builds` 后重新安装，不是初始化失败                                                                                                                                                                                                   |
-| `eslint` 声明 `>=8.0.0` 却生成了 Flat Config                         | 无上界范围 npm 实际会装 9，CLI 按 9 生成                                       | 确定留在 8 就把范围收紧到 `<9`（如 `~8.57.0`）后重跑 init                                                                                                                                                                                               |
-| 重复 init 后，改过的 `.prettierrc.cjs` / hooks 被覆盖                | 除 ESLint 入口与已存在的 `.gitignore` 外，目标文件一律覆盖                     | 先用 `--dry-run` 看清单、用 `--backup` 留档（备份含 `package.json`，目录会自动写入 `.gitignore`）                                                                                                                                                       |
-| 自定义 `lint-staged` 分组消失                                        | `lint-staged` 为整体替换，避免残留失效分组                                     | 从 `.my-code-style-backup/package.json` 恢复后手动合并                                                                                                                                                                                                  |
-| 提交时 lint 报错、提交失败                                           | 修不了的错误（语法错误、非法 CSS 属性）会阻止提交                              | 按提示修复；紧急情况可用 `git commit --no-verify`，但请在 **CI 用 `pnpm lint` 兜底**                                                                                                                                                                    |
-| 提交信息被拒（`type may not be empty` / `subject may not be empty`） | 提交信息需符合 conventional commits，`类型(范围): 描述` 的**冒号后必须有空格** | 先看冒号后面有没有空格（`fix:(修复)…` 会被判成 type 与 subject 双空）；用 `pnpm cz` 交互式生成；header 上限 108 字符                                                                                                                                    |
-| `pnpm cz` 报 `No files added to staging!`                            | czg 由暂存区驱动：没有暂存文件就不启动（`--all` / `-a` 也不绕过）              | 先 `git add -A` 再 `pnpm cz`；scope 候选与默认值也是按暂存区推断的                                                                                                                                                                                      |
-| 想让 `pnpm cz` 的提示换成英文/自己的措辞                             | 提示语来自 `prompt.messages`，本包默认中文                                     | 在项目的 `.commitlintrc.cjs` 里覆盖 `prompt.messages`（标题）与 `prompt.types`（类型描述）；scope 列表里的「自定义 / 不填」对应 `customScopesAlias` / `emptyScopesAlias`                                                                                |
-| 老项目已有 `.eslintrc.*`，init 只读退出                              | ESLint 版本与配置格式冲突时 CLI 拒绝写入                                       | 先确认/迁移版本，再重跑 init                                                                                                                                                                                                                            |
-| `pnpm release` 之后如何发布                                          | `release` 只生成版本、CHANGELOG、提交与 tag                                    | 另行执行 `npm publish`                                                                                                                                                                                                                                  |
-| 装完看到一片 `unmet peer` 警告，要不要管                             | npm 遇到不满足的 peer 会直接 ERESOLVE 拒装，pnpm 只打印 WARN 就装完            | 先看警告来自谁：`unmet peer … from my-code-style` 说明版本声明没跟上，先升级本包；来自别的包（如 `postcss-html@1.8.1` 却要 `^2`）按提示对齐。重跑 `init` 会主动体检（范围精确到 minor，例如 `vue-eslint-parser 10.2.0` 不满足 `^10.3.0`）并打印对齐命令 |
-| `stylelint` 该用 16 还是 17                                          | 两条线都支持：`stylelint ^16.24.0 \|\| ^17.0.0`                                | 16 线（`stylelint-config-recommended@17`）兼容面最广；17 线要 stylelint 17 + `config-recommended@18` + `recommended-scss@17` + `stylelint-order@7/8`，且 Node ≥ 22.12。两条线都有真实运行回归（集成套件跑 16 线，Stylelint 17 套件跑 17 线）            |
+| 现象                                                                 | 原因                                                                                             | 处理                                                                                                                                                                                                                                                    |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 只装了 `my-code-style`，`pnpm lint` 报找不到 eslint                  | peerDependencies 全部是 optional，不会自动安装                                                   | 按 CLI 结尾输出的清单装全，**别漏 `typescript`**（`@typescript-eslint/parser` / `typescript-eslint` 的必需 peer）                                                                                                                                       |
+| stylelint 报 `Could not find plugin "stylelint-order"`               | recess-order 7 把 stylelint-order 声明为 peer（非依赖），pnpm 10+ 严格模式 / npm / yarn 不自动装 | 显式安装 `stylelint-order`（对齐 peer 范围 `^6 \|\| ^7 \|\| ^8`；Vue/SCSS 项目必装）                                                                                                                                                                    |
+| `pnpm prepare` 输出 `.git can't be found`，hooks 不生效              | husky 必须在 git 仓库内执行                                                                      | 先 `git init`、再 `pnpm prepare`；验证 `git config core.hooksPath` 输出 `.husky/_`                                                                                                                                                                      |
+| 安装依赖报 `ERR_PNPM_IGNORED_BUILDS`（如 `unrs-resolver`）           | pnpm 10+ 默认拦截依赖的构建脚本                                                                  | 执行 `pnpm approve-builds` 后重新安装，不是初始化失败                                                                                                                                                                                                   |
+| `eslint` 声明 `>=8.0.0` 却生成了 Flat Config                         | 无上界范围 npm 实际会装 9，CLI 按 9 生成                                                         | 确定留在 8 就把范围收紧到 `<9`（如 `~8.57.0`）后重跑 init                                                                                                                                                                                               |
+| 重复 init 后，改过的 `.prettierrc.cjs` / hooks 被覆盖                | 除 ESLint 入口与已存在的 `.gitignore` 外，目标文件一律覆盖                                       | 先用 `--dry-run` 看清单、用 `--backup` 留档（备份含 `package.json`，目录会自动写入 `.gitignore`）                                                                                                                                                       |
+| 自定义 `lint-staged` 分组消失                                        | `lint-staged` 为整体替换，避免残留失效分组                                                       | 从 `.my-code-style-backup/package.json` 恢复后手动合并                                                                                                                                                                                                  |
+| 提交时 lint 报错、提交失败                                           | 修不了的错误（语法错误、非法 CSS 属性）会阻止提交                                                | 按提示修复；紧急情况可用 `git commit --no-verify`，但请在 **CI 用 `pnpm lint` 兜底**                                                                                                                                                                    |
+| 提交信息被拒（`type may not be empty` / `subject may not be empty`） | 提交信息需符合 conventional commits，`类型(范围): 描述` 的**冒号后必须有空格**                   | 先看冒号后面有没有空格（`fix:(修复)…` 会被判成 type 与 subject 双空）；用 `pnpm cz` 交互式生成；header 上限 108 字符                                                                                                                                    |
+| `pnpm cz` 报 `No files added to staging!`                            | czg 由暂存区驱动：没有暂存文件就不启动（`--all` / `-a` 也不绕过）                                | 先 `git add -A` 再 `pnpm cz`；scope 候选与默认值也是按暂存区推断的                                                                                                                                                                                      |
+| 想让 `pnpm cz` 的提示换成英文/自己的措辞                             | 提示语来自 `prompt.messages`，本包默认中文                                                       | 在项目的 `.commitlintrc.cjs` 里覆盖 `prompt.messages`（标题）与 `prompt.types`（类型描述）；scope 列表里的「自定义 / 不填」对应 `customScopesAlias` / `emptyScopesAlias`                                                                                |
+| 老项目已有 `.eslintrc.*`，init 只读退出                              | ESLint 版本与配置格式冲突时 CLI 拒绝写入                                                         | 先确认/迁移版本，再重跑 init                                                                                                                                                                                                                            |
+| `pnpm release` 之后如何发布                                          | `release` 只生成版本、CHANGELOG、提交与 tag                                                      | 另行执行 `npm publish`                                                                                                                                                                                                                                  |
+| 装完看到一片 `unmet peer` 警告，要不要管                             | npm 遇到不满足的 peer 会直接 ERESOLVE 拒装，pnpm 只打印 WARN 就装完                              | 先看警告来自谁：`unmet peer … from my-code-style` 说明版本声明没跟上，先升级本包；来自别的包（如 `postcss-html@1.8.1` 却要 `^2`）按提示对齐。重跑 `init` 会主动体检（范围精确到 minor，例如 `vue-eslint-parser 10.2.0` 不满足 `^10.3.0`）并打印对齐命令 |
+| `stylelint` 该用 16 还是 17                                          | 两条线都支持：`stylelint ^16.24.0 \|\| ^17.0.0`                                                  | 16 线（`stylelint-config-recommended@17`）兼容面最广；17 线要 stylelint 17 + `config-recommended@18` + `recommended-scss@17` + `stylelint-order@7/8`，且 Node ≥ 22.12。两条线都有真实运行回归（集成套件跑 16 线，Stylelint 17 套件跑 17 线）            |
 
 完整 FAQ（含更多场景与解释）见 [docs/manual.md](docs/manual.md#五使用中遇到的问题faq)。
 
 ## 测试套件
 
 ```bash
-npm run test:all               # 全量运行 189 项：用例明细 + 分类统计 + 最慢文件定位
+npm run test:all               # 全量运行 194 项：用例明细 + 分类统计 + 最慢文件定位
 npm run diagnose               # 换机器后先跑它：进程 / git / 文件系统 / hooks 各占多少
 npm run sweep                  # 给本机找最佳文件级并发（扫 integration 套件）
-npm test                       # 只跑基础 CLI 与配置矩阵（88 项）
+npm test                       # 只跑基础 CLI 与配置矩阵（93 项）
 npm run test:integration:setup # 安装现代化隔离依赖运行环境
 npm run test:integration       # Flat Config、真实 Husky 及提交链路测试（65 项）
 npm run test:legacy:setup      # 安装 ESLint 8 隔离运行环境
@@ -258,47 +276,47 @@ npm run test:stylelint17       # Stylelint 17 生态兼容性回归（8 项）
 ```text
   my-code-style 测试套件
 
-  ▶ [1/4] 基础 CLI 与配置矩阵  （共 88 项，5 文件 · 3 文件并发（自动：2 核 / 内存 4G））
+  ▶ [1/4] 基础 CLI 与配置矩阵  （共 93 项，5 文件 · 3 文件并发（自动：2 核 / 内存 4G））
       ✓ 运行器 TAP 解析：统计通过与失败、SKIP 与每用例耗时 · 7ms
       ✓ cz 交互提示为中文，且可选类型与 type-enum 一一对应 · 1ms
       ✓ peer 范围覆盖我们声明支持的上游大版本（校准防回退，BUG-027） · 0ms
       ✓ 一键安装命令对含 || 的版本范围加引号，可整段粘贴执行 · 40ms
       ✓ 初始化结尾指引把 cz 用法说清楚（先 git add + 指到 README 手册） · 80ms
       …
-     ✓ 通过 88  ·  3.6s   · 最慢文件 init-matrix.test.cjs 3.4s
+     ✓ 通过 93  ·  4.9s   · 最慢文件 init-matrix.test.cjs 4.6s
 
   ▶ [2/4] 现代工具链与提交链  （共 65 项，24 文件 · 3 文件并发（自动：2 核 / 内存 4G））
       ✓ 完整提交链：JS/TS/Vue/nvue/CSS/less 自动修复及二次复检 · 10.4s
       ✓ 发布防呆：HEAD 已有 v* tag 时拦截（此时 release 工具会静默抬版并写出空 CHANGELOG） · 609ms
       …
-     ✓ 通过 65  ·  45.3s   · 最慢文件 commit-chain-both.test.cjs 12.4s
+     ✓ 通过 65  ·  50.7s   · 最慢文件 commit-chain-both.test.cjs 16.1s
 
   ▶ [3/4] ESLint 8 兼容性  （共 27 项，1 文件 · 3 文件并发（自动：2 核 / 内存 4G））
       ✓ 独立运行 ESLint 8 支持下限而非 ESLint 9 · 1ms
       ✓ ESLint 8 base：实际 CLI 加载生成配置并接受正常文件 · 1.3s
       …
-     ✓ 通过 27  ·  18.3s
+     ✓ 通过 27  ·  19.4s
 
   ▶ [4/4] Stylelint 17 兼容性  （共 9 项，1 文件 · 3 文件并发（自动：2 核 / 内存 4G））
       ✓ 隔离环境装的是 stylelint 17（不是 16） · 2ms
       ✓ 生成的 .stylelintrc.cjs 在 stylelint 17 下可加载并放过正常 SCSS · 700ms
       …
-     ✓ 通过 9  ·  8.2s
+     ✓ 通过 9  ·  9.6s
 
   ──────────────────────────────────────────────────────
   套件                      通过    失败    跳过    用时
   ──────────────────────────────────────────────────────
-  基础 CLI 与配置矩阵         88       0       -    3.6s
-  现代工具链与提交链          65       0       -   45.3s
-  ESLint 8 兼容性             27       0       -   18.7s
-  Stylelint 17 兼容性          9       0       -    8.2s
+  基础 CLI 与配置矩阵         93       0       -    4.9s
+  现代工具链与提交链          65       0       -   50.7s
+  ESLint 8 兼容性             27       0       -   19.4s
+  Stylelint 17 兼容性          9       0       -    9.6s
   ──────────────────────────────────────────────────────
-  合计                       189       0       -   76.9s
+  合计                       194       0       -   84.6s
   ──────────────────────────────────────────────────────
 
   ⏱ 最慢文件：eslint8.test.cjs 18.0s · commit-chain-less.test.cjs 11.4s · commit-chain-both.test.cjs 11.3s
 
-  ✅ 全部通过：189/189 项，用时 76.9s
+  ✅ 全部通过：194/194 项，用时 84.6s
 ```
 
 终端里每个套件下方还有一条实时进度条（`██████░░░░ 38/66  失败 0  4.0s`）。附加参数：
@@ -376,7 +394,7 @@ npm run test:all -- --profile     # 看每个测试文件耗时，定位瓶颈
 | `npm run test:integration`（运行器调度，自动并发 3）                        | 30.6s（只看集成套件那一段）                 |
 | 串行套件 + 文件级并发 23（全部一波）                                        | ✗ 3.8G 内存沙箱被 OOM 压垮（19 项 SIGKILL） |
 
-同机复测（189 项，同一台 2 核沙箱连续跑；绝对秒数随机器负载波动，相对关系稳定）：串行套件 + 文件级并发 1 = 84.4s、默认自动并发 3 = 76.9s、`npm run test:integration` = 45.3s（其余口径为早前基线实测，相对关系稳定）。
+同机复测（194 项，同一台 2 核沙箱连续跑；绝对秒数随机器负载波动，相对关系稳定）：默认自动并发 3 = 84.6s、`npm run test:integration` = 50.7s（本轮实跑；串行与 parallel 口径为早前基线实测，相对关系稳定）。
 
 （2 核沙箱里并行收益被 CPU 争抢吃掉大半，`--concurrency=1` 时单个文件只要 0.7–4.2s；
 16 核机器上集成套件那段 ≈ 最慢子文件，即"一次真实提交"的量级。）

package/bin/doctor

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// my-code-style-doctor — 项目体检：peer 是否装齐且版本达标、hooks 是否真的能跑、
+// lockfile 是否被 gitignore 排除、配置文件是否就位。一次性报红，供 CI 与人工复验。
+//
+// 背景：peerDependencies 全部 optional（包管理器零警告），"看起来配了、实际全死"
+// 可以长期潜伏（下游 1.2 → 1.8 升级实测 20 个 peer 一个没装、hook 命令被注释）。
+// init 的依赖体检只在新装/重装时打印一次；doctor 让既有项目随时可查（issue #6）。
+
+const fs = require("fs")
+const path = require("path")
+const { spawnSync } = require("child_process")
+
+const PROJECT_ROOT = process.cwd()
+let problems = 0
+
+const ok = (msg) => console.log(`  ✓ ${msg}`)
+const bad = (msg) => {
+    problems++
+    console.log(`  ✗ ${msg}`)
+}
+const info = (msg) => console.log(`  · ${msg}`)
+
+const args = process.argv.slice(2)
+const supported = new Set(["--help", "-h", "--version", "-v"])
+const unknown = args.filter((arg) => !supported.has(arg))
+if (unknown.length) {
+    console.error(`未知参数: ${unknown.join(", ")}；使用 --help 查看帮助`)
+    process.exit(1)
+}
+if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: my-code-style-doctor [--version|-v] [--help|-h]")
+    console.log("在项目根目录运行：体检 peer 依赖、husky hooks、lockfile 入库与配置文件。")
+    console.log("退出码：0 = 全部健康；1 = 存在需要处理的问题（可用于 CI 门禁）。")
+    process.exit(0)
+}
+if (args.includes("--version") || args.includes("-v")) {
+    console.log(require("../package.json").version)
+    process.exit(0)
+}
+
+// ---- 环境解析 ----
+const projectRequire = (() => {
+    try {
+        return require("node:module").createRequire(path.join(PROJECT_ROOT, "package.json"))
+    } catch {
+        return require
+    }
+})()
+
+function readManifest() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, "package.json"), "utf8"))
+    } catch {
+        return null
+    }
+}
+
+// 读取依赖包版本：优先裸包名/package.json（可能被 exports 挡，如 less），
+// 回退到 resolve(裸包名) 后读相邻 package.json
+function installedVersion(projectRequire, name) {
+    try {
+        return require(`${name}/package.json`).version
+    } catch {}
+    try {
+        const entry = projectRequire.resolve(name)
+        // 截掉入口文件取包目录（用 path.dirname；别用正则截第一个分隔符——会得到空串）
+        const dir = path.dirname(entry)
+        return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).version
+    } catch {
+        return null
+    }
+}
+
+// 迷你 semver：覆盖本包 peer 的全部形态（^x.y.z 的 || 组合、*）
+function satisfies(version, range) {
+    const [major, minor = 0, patch = 0] = String(version)
+        .split(".")
+        .map((n) => parseInt(n, 10))
+    if ([major, minor, patch].some(Number.isNaN)) return false
+    return range
+        .split("||")
+        .map((alt) => alt.trim())
+        .some((alt) => {
+            if (!alt || alt === "*") return true
+            const caret = alt.match(/^\^(\d+)\.(\d+)\.(\d+)$/)
+            if (!caret) return false
+            const [M, m, p] = caret.slice(1).map(Number)
+            if (M > 0) return major === M
+            if (m > 0) return major === 0 && minor === m
+            return major === 0 && minor === 0 && patch === p
+        })
+}
+
+console.log(`my-code-style-doctor · 项目 ${path.basename(PROJECT_ROOT)}`)
+
+// ---- ① package.json 与 my-code-style ----
+const manifest = readManifest()
+if (!manifest) {
+    bad("package.json 不存在或不是合法 JSON（在项目根目录运行）")
+    console.log(`\n体检完成：${problems} 个问题`)
+    process.exit(1)
+}
+ok("package.json 可解析")
+
+let selfPkg = null
+try {
+    selfPkg = projectRequire("my-code-style/package.json")
+} catch {}
+if (!selfPkg) {
+    bad("my-code-style 未安装（npm i -D my-code-style）")
+    console.log(`\n体检完成：${problems} 个问题`)
+    process.exit(1)
+}
+ok(`my-code-style ${selfPkg.version}`)
+
+// ---- ② peer 依赖：装了吗？版本对吗？ ----
+// 与 init 的依赖体检（checkPeerDeps）同口径裁剪：classic import 仅 ESLint 8 legacy
+// 线需要；无预处理器且非 Vue 项目不查 stylelint 族；Vue 项目才查 vue 全家。
+// 改动需与 bin/init 两侧同步（init-matrix 回归守底）。
+function requiredPeers(manifest) {
+    const deps = {
+        ...manifest.dependencies,
+        ...manifest.devDependencies,
+        ...manifest.peerDependencies,
+    }
+    const eslintSpec = String(deps.eslint ?? "")
+    const eslintMajor = Number((eslintSpec.match(/(\d+)\./) || [])[1] ?? 0)
+    const hasLegacyEntry = [".eslintrc.cjs", ".eslintrc.js", ".eslintrc.json"].some((f) =>
+        fs.existsSync(path.join(PROJECT_ROOT, f)),
+    )
+    const hasFlatEntry = [
+        "eslint.config.mjs",
+        "eslint.config.js",
+        "eslint.config.ts",
+        "eslint.config.cjs",
+    ].some((f) => fs.existsSync(path.join(PROJECT_ROOT, f)))
+    const useFlat = hasFlatEntry || (!hasLegacyEntry && eslintMajor >= 9)
+    const isVue = !!(deps.vue || deps["@dcloudio/uni-app"] || deps["uni-app"])
+    const cssPre =
+        deps.less && (deps.sass || isVue)
+            ? "both"
+            : deps.less
+              ? "less"
+              : deps.sass || isVue
+                ? "scss"
+                : null
+
+    const list = [
+        "eslint",
+        "typescript",
+        "prettier",
+        ...(isVue ? ["eslint-plugin-vue"] : []),
+        "@commitlint/cli",
+        "@commitlint/config-conventional",
+        "husky",
+        "lint-staged",
+        "czg",
+        "commit-and-tag-version",
+    ]
+    if (useFlat) {
+        list.push(
+            "typescript-eslint",
+            "eslint-import-resolver-typescript",
+            ...(isVue ? ["vue-eslint-parser"] : []),
+            "globals",
+            "eslint-plugin-import-x",
+            "@eslint/js",
+            "eslint-plugin-prettier",
+            "eslint-config-prettier",
+        )
+    } else {
+        list.push(
+            "@typescript-eslint/parser",
+            "@typescript-eslint/eslint-plugin",
+            ...(isVue ? ["vue-eslint-parser"] : []),
+            "eslint-plugin-import",
+            "eslint-import-resolver-typescript",
+            "eslint-plugin-prettier",
+            "eslint-config-prettier",
+        )
+    }
+    if (cssPre === "scss" || cssPre === "both") {
+        list.push(
+            "stylelint",
+            "postcss-scss",
+            "postcss-html",
+            "stylelint-config-recommended",
+            "stylelint-config-recommended-scss",
+            "stylelint-config-recommended-vue",
+            "stylelint-config-html",
+            "stylelint-config-recess-order",
+            "stylelint-prettier",
+        )
+    }
+    if (cssPre === "less" || cssPre === "both") {
+        list.push(
+            "stylelint",
+            "postcss-less",
+            "postcss-html",
+            "stylelint-config-recommended",
+            "stylelint-config-recommended-vue",
+            "stylelint-config-html",
+            "stylelint-config-recess-order",
+            "stylelint-prettier",
+        )
+    }
+    return [...new Set(list)]
+}
+
+const peers = selfPkg.peerDependencies || {}
+const scopedPeers = manifest.name === "my-code-style" ? [] : requiredPeers(manifest)
+const declared = {
+    ...manifest.dependencies,
+    ...manifest.devDependencies,
+    ...manifest.peerDependencies,
+}
+const missing = []
+const mismatched = []
+const peerRanges = selfPkg.peerDependencies || {}
+for (const name of scopedPeers) {
+    const range = peerRanges[name] ?? "*"
+    const version = installedVersion(projectRequire, name)
+    if (!version) {
+        missing.push([name, range])
+        continue
+    }
+    if (!satisfies(version, range)) {
+        mismatched.push([name, version, range])
+    }
+}
+if (manifest.name === "my-code-style") {
+    info("my-code-style 仓库自身：跳过 peer 体检（狗粮环境按需自装）")
+} else if (scopedPeers.length === 0) {
+    info("未检出需要体检的 peer（项目类型判定为空）")
+} else if (missing.length === 0 && mismatched.length === 0) {
+    ok(`peer 依赖 ${scopedPeers.length} 个全部安装且版本达标`)
+} else {
+    for (const [name, range] of missing) bad(`peer ${name} 未安装（要求 ${range}）`)
+    for (const [name, version, range] of mismatched) bad(`peer ${name}@${version} 不满足 ${range}`)
+    const spec = [...missing, ...mismatched.map(([n, , r]) => [n, r])]
+        .map(([name, range]) => (range.includes("||") ? `"${name}@${range}"` : `${name}@${range}`))
+        .join(" ")
+    info(`一键补齐（按包管理器换命令）：npm i -D ${spec}`)
+}
+
+// ---- ③ husky hooks：存在 / 非空 / 可执行 / 命令可解析 ----
+const hooksDir = path.join(PROJECT_ROOT, ".husky")
+const hookNames = ["pre-commit", "commit-msg"]
+if (!fs.existsSync(hooksDir)) {
+    bad(".husky/ 不存在：先跑 init 生成 hooks，再 npm i 触发 prepare")
+} else {
+    const gitHooksPath = spawnSync("git", ["config", "core.hooksPath"], {
+        cwd: PROJECT_ROOT,
+        encoding: "utf8",
+    })
+    if (gitHooksPath.status !== 0) {
+        info("非 git 仓库或 core.hooksPath 未设置：git init + npm run prepare 后 hooks 生效")
+    } else if (gitHooksPath.stdout.trim() !== ".husky/_") {
+        bad(`core.hooksPath=${gitHooksPath.stdout.trim()}，预期 .husky/_`)
+    } else {
+        ok("core.hooksPath 指向 .husky/_")
+    }
+    for (const name of hookNames) {
+        const hookPath = path.join(hooksDir, name)
+        if (!fs.existsSync(hookPath)) {
+            bad(`.husky/${name} 缺失`)
+            continue
+        }
+        const content = fs.readFileSync(hookPath, "utf8")
+        if (!content.trim()) {
+            bad(`.husky/${name} 内容为空（曾出现注释掉命令导致门禁静默失效的案例）`)
+            continue
+        }
+        if ((fs.statSync(hookPath).mode & 0o111) === 0) {
+            bad(`.husky/${name} 缺少可执行位，git 会静默忽略（chmod +x 修复）`)
+            continue
+        }
+        let cmdOk = true
+        for (const cmd of ["lint-staged", "commitlint"]) {
+            if (!content.includes(cmd)) continue
+            const localBin = fs.existsSync(path.join(PROJECT_ROOT, "node_modules", ".bin", cmd))
+            const installed = Boolean(declared[name]) || Boolean(declared[cmd])
+            if (!localBin && !installedVersion(projectRequire, cmd) && !installed) {
+                bad(`.husky/${name} 引用的 ${cmd} 未安装：提交时会因 npx --no-install 失败`)
+                cmdOk = false
+            }
+        }
+        if (cmdOk) ok(`.husky/${name} 存在、可执行、引用命令可解析`)
+    }
+}
+
+// ---- ④ lockfile 入库（F3）：被 gitignore 的 lockfile 让版本不可复现 ----
+const lockfiles = ["pnpm-lock.yaml", "yarn.lock", "package-lock.json", "bun.lockb", "bun.lock"]
+const presentLock = lockfiles.find((f) => fs.existsSync(path.join(PROJECT_ROOT, f)))
+if (!presentLock) {
+    info("未发现 lockfile（可复现安装建议入库一份）")
+} else {
+    const check = spawnSync("git", ["check-ignore", presentLock], {
+        cwd: PROJECT_ROOT,
+        encoding: "utf8",
+    })
+    if (check.status === 0) {
+        bad(`${presentLock} 被 .gitignore 排除：不同机器/CI 的版本组合将不可复现`)
+    } else {
+        ok(`lockfile ${presentLock} 已入库`)
+    }
+}
+
+// ---- ⑤ 配置文件就位 ----
+const flatEntry = [
+    "eslint.config.mjs",
+    "eslint.config.js",
+    "eslint.config.ts",
+    "eslint.config.cjs",
+].find((f) => fs.existsSync(path.join(PROJECT_ROOT, f)))
+const configs = [
+    [".prettierrc.cjs", "prettier"],
+    [".stylelintrc.cjs", "stylelint（有 CSS 预处理器的项目）"],
+    [flatEntry || null, "eslint 入口"],
+    [".commitlintrc.cjs", "commitlint"],
+]
+let configCount = 0
+for (const [file, label] of configs) {
+    if (!file) continue
+    if (fs.existsSync(path.join(PROJECT_ROOT, file))) {
+        configCount++
+    } else {
+        info(`缺 ${file}（${label}）——需要时用 my-code-style-init 生成`)
+    }
+}
+if (configCount > 0) ok(`配置文件 ${configCount} 个就位`)
+
+console.log(`\n体检完成：${problems === 0 ? "全部健康 ✓" : `${problems} 个问题需要处理`}`)
+process.exit(problems === 0 ? 0 : 1)

package/bin/init

@@ -682,7 +682,16 @@ function getLintStagedConfig(cssPreprocessor) {
 
 function main() {
     const args = process.argv.slice(2)
-    const supported = new Set(["--dry-run", "--backup", "--version", "-v", "--help", "-h"])
+    const supported = new Set([
+        "--dry-run",
+        "--backup",
+        "--merge",
+        "--no-overwrite",
+        "--version",
+        "-v",
+        "--help",
+        "-h",
+    ])
     const unknown = args.filter((arg) => !supported.has(arg))
     if (unknown.length) {
         console.error(`未知参数: ${unknown.join(", ")}；使用 --help 查看帮助`)
@@ -690,9 +699,15 @@ function main() {
         return
     }
     if (args.includes("--help") || args.includes("-h")) {
-        console.log("Usage: my-code-style-init [--dry-run] [--backup] [--version|-v] [--help|-h]")
+        console.log(
+            "Usage: my-code-style-init [--dry-run] [--backup] [--merge] [--version|-v] [--help|-h]",
+        )
         console.log("  --backup   覆盖已有配置前将其备份到 .my-code-style-backup/ 目录")
         console.log("  --dry-run  试运行，仅输出将执行的变更，不写入任何文件")
+        console.log(
+            "  --merge    合并模式：已存在的配置一律保留，只补缺失文件（别名 --no-overwrite）",
+        )
+        console.log("  结束时自动自检 hooks（存在 / 可执行 / 命令可解析），仅提示不阻断")
         console.log("初始化会覆盖部分配置和 hooks；请先备份并运行 --dry-run。")
         return
     }
@@ -907,6 +922,7 @@ function main() {
     }
 
     const backup = args.includes("--backup")
+    const mergeMode = args.includes("--merge") || args.includes("--no-overwrite")
     stepHeader(3, 6, "配置文件与 Git hooks")
     let overwriteTotal = 0
     let createTotal = 0
@@ -1023,6 +1039,8 @@ function main() {
         // package.json is rewritten (scripts + lint-staged), so it must be backed
         // up as well — users lose custom lint-staged groups otherwise.
         for (const item of [...files, ...hooks, { path: "package.json" }]) {
+            // --merge 不覆盖已有文件，无需为其备份（package.json 例外：scripts 仍会补齐）
+            if (mergeMode && item.path !== "package.json") continue
             if (fileExists(item.path)) {
                 const srcPath = path.resolve(PROJECT_ROOT, item.path)
                 const targetPath = path.resolve(backupDir, item.path)
@@ -1034,10 +1052,10 @@ function main() {
         // 与本次生成的 .versionrc.cjs 抢生效顺序的同名旧配置（.versionrc /
         // .versionrc.json 会直接压过生成物，ESM 项目的 .versionrc.js 徒增歧义）：
         // 备份后移除，不留"哪份在生效"的悬案（下游升级实测 D2）
-        const staleVersionrcFiles = [
-            ...staleVersionrcTop,
-            ...(staleVersionrc ? [".versionrc.js"] : []),
-        ]
+        // --merge 不动用户已有配置：stale 文件保持原样（前面已给出告警）
+        const staleVersionrcFiles = mergeMode
+            ? []
+            : [...staleVersionrcTop, ...(staleVersionrc ? [".versionrc.js"] : [])]
         for (const relPath of staleVersionrcFiles) {
             if (!fileExists(relPath)) continue
             const staleSrc = path.resolve(PROJECT_ROOT, relPath)
@@ -1106,6 +1124,10 @@ function main() {
     try {
         // Actually write files
         for (const f of files) {
+            if (mergeMode && snapshot.get(f.path)?.existed) {
+                console.log(`      · 保留 ${f.path}（--merge 不覆盖）`)
+                continue
+            }
             writeFile(f.path, f.content)
         }
 
@@ -1114,23 +1136,33 @@ function main() {
             ensureDir(huskyDir)
         }
         for (const h of hooks) {
+            if (mergeMode && snapshot.get(h.path)?.existed) {
+                console.log(`      · 保留 ${h.path}（--merge 不覆盖）`)
+                continue
+            }
             writeFile(h.path, h.content)
             fs.chmodSync(path.resolve(PROJECT_ROOT, h.path), 0o755)
         }
 
         // package.json scripts + lint-staged
-        modifyPackageJson({
-            scripts: {
-                lint: lintCommand,
-                "lint:fix": `${lintCommand} --fix`,
-                format: "prettier --write .",
-                prepare: "husky",
-                release: "commit-and-tag-version",
-                cz: "czg",
+        modifyPackageJson(
+            {
+                scripts: {
+                    lint: lintCommand,
+                    "lint:fix": `${lintCommand} --fix`,
+                    format: "prettier --write .",
+                    prepare: "husky",
+                    release: "commit-and-tag-version",
+                    cz: "czg",
+                },
+                "lint-staged": getLintStagedConfig(cssPreprocessor),
             },
-            "lint-staged": getLintStagedConfig(cssPreprocessor),
-        })
+            { merge: mergeMode },
+        )
         printPackageJsonStep()
+        if (!dryRun) {
+            verifyGeneratedHooks(hooks)
+        }
 
         // The backup directory is ours, not the user's source — keep it out of git
         if (backup) {
@@ -1177,7 +1209,43 @@ function main() {
     printFooter()
 }
 
-function modifyPackageJson(updates) {
+// init 收尾 hook 自检（issue #8）：存在 / 非空 / 可执行位 / 引用命令可解析。
+// 只报告不阻断——真实提交链路才是最终裁判，这里负责把"装了但没用"提前亮出来。
+function verifyGeneratedHooks(hooks) {
+    console.log("      · hook 自检")
+    let pkg = {}
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.resolve(PROJECT_ROOT, "package.json"), "utf8"))
+    } catch {}
+    for (const h of hooks) {
+        const abs = path.resolve(PROJECT_ROOT, h.path)
+        if (!fileExists(abs)) {
+            warn(`${h.path} 缺失`)
+            continue
+        }
+        const content = fs.readFileSync(abs, "utf8")
+        if (!content.trim()) {
+            warn(`${h.path} 内容为空，git 将静默跳过`)
+            continue
+        }
+        if ((fs.statSync(abs).mode & 0o111) === 0) {
+            warn(`${h.path} 缺少可执行位，git 会静默忽略（chmod +x 修复）`)
+        }
+        for (const cmd of ["lint-staged", "commitlint"]) {
+            if (!content.includes(cmd)) continue
+            const localBin = fs.existsSync(path.join(PROJECT_ROOT, "node_modules", ".bin", cmd))
+            const declared = Boolean(pkg.devDependencies?.[cmd] ?? pkg.dependencies?.[cmd])
+            if (!localBin && !declared) {
+                warn(`${h.path} 引用的 ${cmd} 未安装：安装依赖前提交会因 npx --no-install 失败`)
+            }
+        }
+    }
+    if (!fs.existsSync(path.join(PROJECT_ROOT, ".husky", "_"))) {
+        console.log("      · 提示：.husky/_ 未生成，安装依赖（触发 prepare）后 hooks 才生效")
+    }
+}
+
+function modifyPackageJson(updates, { merge = false } = {}) {
     const pkgPath = path.resolve(PROJECT_ROOT, "package.json")
     let pkg = {}
     if (fileExists("package.json")) {
@@ -1214,7 +1282,8 @@ function modifyPackageJson(updates) {
     }
 
     // Set lint-staged (replace existing lint-staged to avoid stale/duplicate patterns)
-    if (updates["lint-staged"]) {
+    // --merge 例外：用户已有分组原样保留，只补缺失
+    if (updates["lint-staged"] && !(merge && pkg["lint-staged"])) {
         pkg["lint-staged"] = updates["lint-staged"]
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-code-style",
-  "version": "1.8.6",
+  "version": "1.9.0",
   "description": "Lint/Format/Git 配置工程化 npm 包（ESLint + Prettier + Stylelint + Commitlint + Husky + standard-version）",
   "type": "commonjs",
   "main": "src/eslint/uniapp.cjs",
@@ -13,7 +13,8 @@
     "url": "https://github.com/myvn/codeStyle/issues"
   },
   "bin": {
-    "my-code-style-init": "./bin/init"
+    "my-code-style-init": "./bin/init",
+    "my-code-style-doctor": "./bin/doctor"
   },
   "exports": {
     ".": "./src/eslint/uniapp.cjs",

package/src/prettierignore

@@ -14,3 +14,13 @@
 *.woff2
 *.apk
 *.plist
+
+# 各包管理器 lockfile：格式所有权归包管理器——pnpm 9 的单引号紧凑风格
+# 与 prettier 的 YAML 风格互搏，lint-staged 每次提交都会改写、下次 install
+# 又被包管理器写回（下游实测单次 diff 7664 行，BUG-034 / issue #5）
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+npm-shrinkwrap.json
+bun.lockb
+bun.lock