my-code-style 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+## 变更日志
+
+## [1.5.0](https://github.com/myvn/codeStyle/compare/v1.4.0...v1.5.0) (2026-09-18)
+
+### 🐛 Bug Fixes | Bug 修复
+
+- 修复 ESLint 版本/样式检测误判、规则冲突与 scope 生成缺陷 ([033967b](https://github.com/myvn/codeStyle/commit/033967b0efadbb705bdafe5d4dfc34dbc90578c2))
+
+### ✨ Features | 新功能
+
+- **init:** 补全 peer 体检并按包管理器输出命令，新增初始化链路文档 ([0396198](https://github.com/myvn/codeStyle/commit/03961983be3a6f8cda96d4047450e7595ffefb97))
+
+## [1.4.0](https://github.com/myvn/codeStyle/compare/v1.2.0...v1.4.0) (2026-09-17)
+
+### 🐛 Bug Fixes | Bug 修复
+
+- **commitlint:** guessCurrentScope 仅基于暂存区推断并补充频次投票与全场景回归 ([3f5f8ea](https://github.com/myvn/codeStyle/commit/3f5f8ea1a4526621006025ce2d86608dd53e9b2d))
+- harden initialization and lint workflows with integration tests ([7079998](https://github.com/myvn/codeStyle/commit/707999895ac4d80d311537bd833584694c7a8510))
+- **stylelint:** 支持混合 SCSS 与 Less 工程并在组件内嵌/独立样式中全量检查与修复 ([e5a1b7e](https://github.com/myvn/codeStyle/commit/e5a1b7e4992f40cf6b4f97fa75e3c755b57fb257))
+
+### ✨ Features | 新功能
+
+- **core:** upgrade cli init, relax stylelint/eslint rules and bump v1.3.1 ([285c49b](https://github.com/myvn/codeStyle/commit/285c49b1f07707f7f998308d37f718e8d0af0d19))
+- **init:** 支持 ESM versionrc、JSX/TSX 检查、版本识别强化与初始化事务回滚 ([89e8eb6](https://github.com/myvn/codeStyle/commit/89e8eb6677db00802636201148119d1fe208abe3))
+
+## 1.3.1 (2026-09-16)
+
+### Bug Fixes
+
+- **stylelint:** 放行 SCSS `@extend` 类继承语法（`scss/at-extend-no-missing-placeholder: null`），放行空样式块（`block-no-empty: null`）
+- **stylelint:** 内置 `ignoreFiles`，自动忽略 `**/assets/iconfont/**`、`**/public/**` 及压缩文件
+- **eslint:** 允许 `// @ts-ignore` 注释（`@typescript-eslint/ban-ts-comment: off`）及 `{}` 类型（`@typescript-eslint/no-empty-object-type: off`）
+- **eslint:** 放行无用表达式报错（`no-unused-expressions: off`），Flat Config 默认忽略 `**/assets/iconfont/**` 与 `**/public/**`，避免历史或第三方资源阻断提交
+
+## 1.3.0 (2026-09-16)
+
+### Features
+
+- **init:** 智能识别工程类型（uni-app / Vue 3 / Node TS 基础库），按需分层生成配置
+- **init:** ESLint 检测支持 peerDependencies，未配置项目默认优先采用现代 Flat Config (ESLint 9+)
+- **init:** 无样式依赖的纯代码项目自动跳过 Stylelint 配置与任务挂载
+- **init:** 内置 `.gitignore` 模板，项目缺失时自动生成，杜绝误暂存 `node_modules`
+- **init:** 补齐 Stylelint 配套全量预设包及 `@commitlint/config-conventional` 到一键安装提示
+- **init:** `lint-staged` 写入改为整块规范化覆盖，彻底消除规则重复执行
+- **core:** 工具项目自身全面规范化，接入 ESLint 9 Flat Config 与 Husky 9 提交拦截
+
+### Bug Fixes
+
+- **eslint:** 修复 `eslintConfigPrettier` 顺序问题，置于配置末尾消除引号冲突
+- **eslint:** 放行 CommonJS 配置文件（`*.config.js`、`.*rc.js`、`*.cjs`）中的 `require()` 语法
+- **eslint:** 关闭 `indent` 与 `vue/html-indent`，缩进格式全权交由 Prettier 处理
+- **eslint:** 关闭 `import-x/extensions` 强制扩展名规则，补齐 `**/*.vue` 文件匹配
+- **stylelint:** 补齐宽松规则，放行现代伪类语法、选择器嵌套及层叠特异性限制
+- **husky:** 移除已废弃的 `husky.sh` 引用，升级全面兼容 Husky 9
+- **commitlint:** 重构 `guessCurrentScope`，提升跨平台路径及多文件暂存匹配精准度
+- **pkg:** 全部 31 项 `peerDependencies` 补充 `peerDependenciesMeta` 为 `optional`
+
+## 1.2.0 (2026-08-28)
+
+### Features
+
+- 一键安装命令带上版本号 a58ddf7
+- 一键安装提示，输出包含 my-code-style 的完整安装命令 3916ddd
+- 安装命令分行展示，避免终端截断 3d4ab9c
+- 添加 --version / -v 查看版本命令 14d6605
+- 添加 Less 专用 stylelint 配置，init 脚本自动选择 be34547
+
+### Bug Fixes
+
+- **eslint:** 修复 ESLint v8/v9 规则覆盖、解析器配置及脚手架生成逻辑 5b4e357
+- peerDependencies 改用 ^ 范围，限制次版本号 b8deccd
+- 修复 init 输出步骤号跳跃（1→3→4） 5248766
+- 修复项目自身 ESLint 配置，添加 eslint.config.mjs 83f79a7
+- 关闭 standard 带来的 style/quotes 冲突 0a21a6b
+- 清理项目自身 init 脚本污染 c1b3b59
+
+## [1.1.0] - 2026-07-29
+
+### Breaking
+
+- ESLint >= 9.0.0、@typescript-eslint >= 8.0.0
+- eslint-config-prettier >= 10.1.8（修复 CVE-2025-54313）
+- eslint-plugin-vue >= 10.0.0、husky >= 9.0.0、commitlint >= 19.0.0
+- stylelint-config-recommended >= 16.0.0、lint-staged >= 16.0.0
+
+### Fixes
+
+- `eslint-config-standard` 移入 peerDependenciesMeta optional（仅支持 ESLint 8）
+
+## [1.0.2] - 2026-07-29
+
+### Fixes
+
+- bin 文件名去 `.cjs` 扩展名（修复 npm 警告）
+- gitattributes 补充 `.ps1` 和 `.cmd/.bat` CRLF 支持
+- `style/quotes` 和 `style/semi` 关闭（与 @stylistic 兼容）
+
+## [1.0.1] - 2026-07-28
+
+### Fixes
+
+- 清理 init 脚本污染，.prettierrc.cjs 改为相对路径
+
+## [1.0.0] - 2026-07-28
+
+### Features
+
+- Less 专用 stylelint 配置（`src/stylelint/less.cjs`）
+- Flat Config 支持（ESLint 9+）

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 myvn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,15 +8,43 @@ Lint/Format/Git 配置工程化 npm 包。适用于 Vue 3 + TypeScript + uni-app
 
 - [HTML 项目技术全景](docs/project-overview.html)：下载或克隆仓库后，用浏览器直接打开，查看项目结构、配置架构、接入流程与维护注意事项；支持离线阅读和打印。
 - [Markdown 技术文档](TECHNICAL_DOC.md)
+- [使用说明书](docs/manual.md)：使用后的优点、带来的福利与解决的问题、完整使用步骤与常见问题 FAQ
+- [初始化链路说明](docs/init-flow.md)：`pnpm add -D my-code-style` + `npx my-code-style-init` 逐步做了什么、生成哪些文件、常见坑
 
-## 快速开始
+## 怎么使用
+
+前置条件：Node ≥ 18、项目有合法 `package.json`、**已 `git init`**（husky 需要 git 仓库）。
 
 ```bash
-pnpm add -D my-code-style
-npx my-code-style-init
+# 1. 安装配置包
+pnpm add -D my-code-style            # npm: npm i -D my-code-style
+
+# 2. 先预览，再初始化（init 会覆盖已存在的 .prettierrc.cjs / hooks 等）
+npx my-code-style-init --dry-run
+npx my-code-style-init                # 需保留旧文件时加 --backup
+
+# 3. 按 CLI 输出的缺失依赖清单安装 peerDependencies（会按包管理器生成命令，别漏 typescript）
+pnpm add -D my-code-style eslint@^9.0.0 typescript@^5.0.0 prettier@^3.0.0 ...   # 以 CLI 实际输出为准
+
+# 4. 初始化 hooks 并首次检查
+pnpm prepare                          # npm: npm run prepare
+pnpm lint
 ```
 
-init 脚本会自动检测项目技术栈类型（uni-app / Vue 3 / Node 基础库）、ESLint 版本和 CSS 预处理器，自动按需生成对应的配置文件。
+init 脚本会自动检测技术栈类型（uni-app / Vue 3 / Node 基础库）、ESLint 版本、CSS 预处理器和包管理器，按需生成配置文件，并在结尾列出尚未安装的 peerDependencies 与对应安装命令。
+
+初始化后：`lint-staged` 会在 `git commit` 时自动修复暂存文件，`commitlint` 校验提交信息，`pnpm release` 生成版本与 CHANGELOG。全过程细节见 [docs/init-flow.md](docs/init-flow.md)，收益与代价评估见 [docs/manual.md](docs/manual.md)。
+
+### 使用后的变化（速览）
+
+| 维度       | 使用前                       | 使用后                                            |
+| ---------- | ---------------------------- | ------------------------------------------------- |
+| 代码格式   | 各自编辑器配置               | 全仓库统一（4 空格 / 无分号 / 双引号 / 行宽 100） |
+| 提交       | 靠自觉，问题留到评审         | pre-commit 自动修复，修不好的挡下提交             |
+| 提交信息   | 自由文本                     | conventional commits 强校验 + `pnpm cz` 引导      |
+| 版本与日志 | 手工改版本、手工写 CHANGELOG | `pnpm release` 自动递增并生成 CHANGELOG           |
+| 样式代码   | 基本无人检查                 | stylelint 覆盖 SCSS/Less/Vue 内嵌样式             |
+| 规则同步   | 每个项目各抄一份             | 升级一个依赖版本，全项目生效                      |
 
 ## 生成的文件
 
@@ -131,7 +159,7 @@ npx my-code-style-init [--dry-run] [--backup] [--version|-v] [--help|-h]
 
 ## 特性
 
-- **双引号**：`quotes: ["error", "double", { avoidEscape: false, allowTemplateLiterals: true }]`
+- **双引号**：`quotes: ["error", "double", { avoidEscape: true, allowTemplateLiterals: true }]`（`avoidEscape` 必须为 `true`，否则与 Prettier 的转义策略冲突，`--fix` 无法消除报错）
 - **4 空格缩进**：`tabWidth: 4`（由 Prettier 全权统一格式化）
 - **无分号**：`semi: false`（`.nvue` 文件除外）
 - **行宽 100**：`printWidth: 100`
@@ -143,15 +171,32 @@ npx my-code-style-init [--dry-run] [--backup] [--version|-v] [--help|-h]
 - **严格暂存区 Scope 猜测**：`guessCurrentScope()` 严格只依据 Git 暂存区推断 scope，支持多目录频次投票、重命名、物理删除、中文路径与空格路径
 - **ESM 兼容的自动版本发布**：支持 CommonJS（`.versionrc.js`）与 ESM（`.versionrc.cjs`）工程无缝对接 standard-version，一键版本递增与 CHANGELOG 生成
 
+## 常见问题（使用中遇到的问题）
+
+| 现象                                                                 | 原因                                                       | 处理                                                                                                              |
+| -------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| 只装了 `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                        | 用 `pnpm cz` 交互式生成；header 上限 108 字符                                                                     |
+| 老项目已有 `.eslintrc.*`，init 只读退出                              | ESLint 版本与配置格式冲突时 CLI 拒绝写入                   | 先确认/迁移版本，再重跑 init                                                                                      |
+| `pnpm release` 之后如何发布                                          | `release` 只生成版本、CHANGELOG、提交与 tag                | 另行执行 `npm publish`                                                                                            |
+
+完整 FAQ（含更多场景与解释）见 [docs/manual.md](docs/manual.md#五使用中遇到的问题faq)。
+
 ## 测试套件
 
 ```bash
-npm test                       # 运行基础 CLI 与配置矩阵测试（52 项）
+npm test                       # 运行基础 CLI 与配置矩阵测试（59 项）
 npm run test:integration:setup # 安装现代化隔离依赖运行环境
-npm run test:integration       # 运行 Flat Config、真实 Husky 及提交链路测试（44 项）
+npm run test:integration       # 运行 Flat Config、真实 Husky 及提交链路测试（47 项）
 npm run test:legacy:setup      # 安装 ESLint 8 隔离运行环境
-npm run test:legacy            # 运行 ESLint 8.57.0 兼容性回归测试（25 项）
-npm run test:all               # 全量运行全部 121 项测试
+npm run test:legacy            # 运行 ESLint 8.57.0 兼容性回归测试（27 项）
+npm run test:all               # 全量运行全部 133 项测试
 ```
 
 ## License

package/bin/init

@@ -12,7 +12,6 @@
 
 const fs = require("fs")
 const path = require("path")
-const { execSync } = require("child_process")
 
 const PROJECT_ROOT = process.cwd()
 const PACKAGE_DIR = path.resolve(__dirname, "..")
@@ -51,6 +50,24 @@ function readTemplate(relativePath) {
     return fs.readFileSync(path.resolve(PACKAGE_DIR, relativePath), "utf8")
 }
 
+/**
+ * Append an entry to the project .gitignore (idempotent, keeps existing lines).
+ */
+function ensureGitignoreEntry(entry) {
+    const gitignorePath = path.resolve(PROJECT_ROOT, ".gitignore")
+    if (!fs.existsSync(gitignorePath)) return
+    const content = fs.readFileSync(gitignorePath, "utf8")
+    const hasEntry = content.split("\n").some((line) => line.trim() === entry)
+    if (hasEntry) return
+    const separator = content.length === 0 || content.endsWith("\n") ? "" : "\n"
+    fs.writeFileSync(
+        gitignorePath,
+        `${content}${separator}\n# my-code-style 初始化备份目录\n${entry}\n`,
+        "utf8",
+    )
+    log(`已将 ${entry} 追加到 .gitignore`)
+}
+
 function getProjectPkg() {
     const pkgPath = path.resolve(PROJECT_ROOT, "package.json")
     if (!fs.existsSync(pkgPath)) return null
@@ -79,6 +96,142 @@ function isEsmProject(pkg = getProjectPkg()) {
     return pkg?.type === "module"
 }
 
+// --- Semver range helpers (dependency-free) ---
+// Detection only needs to know which major versions a declared range can
+// install. Regex guessing on the raw string misreads "<9.0.0" (8 only) and
+// ">=8.0.0" (8 or 9), so ranges are parsed into half-open [lower, upper)
+// intervals with the subset of npm range syntax that appears in practice.
+
+const MAX_VERSION = [Number.POSITIVE_INFINITY, 0, 0]
+
+function compareVersion(a, b) {
+    for (let i = 0; i < 3; i += 1) {
+        if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1
+    }
+    return 0
+}
+
+function isWildcardField(field) {
+    return field === undefined || field === "" || /^[xX*]$/.test(field)
+}
+
+function parseVersionFields(text) {
+    const [release] = String(text).trim().replace(/^v/, "").split("-")
+    const fields = release.split(".")
+    if (fields.length > 3) return null
+    const parts = [0, 1, 2].map((index) => {
+        const field = fields[index]
+        if (isWildcardField(field)) return null
+        return /^\d+$/.test(field) ? parseInt(field, 10) : NaN
+    })
+    return parts.some((part) => Number.isNaN(part)) ? null : parts
+}
+
+function lowerBound(parts) {
+    return [parts[0] || 0, parts[1] || 0, parts[2] || 0]
+}
+
+function partialInterval(parts) {
+    const lower = lowerBound(parts)
+    const missing = parts.findIndex((part) => part === null)
+    if (missing === -1) return [lower, [lower[0], lower[1], lower[2] + 1]]
+    if (missing === 0) return [[0, 0, 0], MAX_VERSION]
+    const upper = [0, 0, 0]
+    for (let i = 0; i < missing; i += 1) upper[i] = parts[i]
+    upper[missing - 1] += 1
+    return [lower, upper]
+}
+
+function caretInterval(parts) {
+    const lower = lowerBound(parts)
+    if (parts[0] === null) return [[0, 0, 0], MAX_VERSION]
+    if (parts[0] > 0 || parts[1] === null) return [lower, [parts[0] + 1, 0, 0]]
+    if (parts[1] > 0 || parts[2] === null) return [lower, [0, parts[1] + 1, 0]]
+    return [lower, [0, 0, parts[2] + 1]]
+}
+
+function tildeInterval(parts) {
+    const lower = lowerBound(parts)
+    if (parts[0] === null) return [[0, 0, 0], MAX_VERSION]
+    if (parts[1] === null) return [lower, [parts[0] + 1, 0, 0]]
+    return [lower, [parts[0], parts[1] + 1, 0]]
+}
+
+function tokenInterval(token) {
+    const match = /^(>=|<=|>|<|\^|~|=)?\s*(.*)$/.exec(token.trim())
+    if (!match || !match[2]) return null
+    const [, operator = "", text] = match
+    if (/^[xX*]$/.test(text.trim())) return [[0, 0, 0], MAX_VERSION]
+    const parts = parseVersionFields(text)
+    if (!parts) return null
+    const lower = lowerBound(parts)
+    switch (operator) {
+        case ">=":
+            return [lower, MAX_VERSION]
+        case ">":
+            return [[lower[0], lower[1], lower[2] + 1], MAX_VERSION]
+        case "<":
+            return [[0, 0, 0], lower]
+        case "<=":
+            return [
+                [0, 0, 0],
+                [lower[0], lower[1], lower[2] + 1],
+            ]
+        case "^":
+            return caretInterval(parts)
+        case "~":
+            return tildeInterval(parts)
+        default:
+            return partialInterval(parts)
+    }
+}
+
+function rangeIntervals(range) {
+    const intervals = []
+    for (const clause of range.split("||")) {
+        const text = clause.trim()
+        if (!text) continue
+        const hyphen = text.split(/\s+-\s+/)
+        const tokens =
+            hyphen.length === 2 ? [`>=${hyphen[0]}`, `<=${hyphen[1]}`] : text.split(/\s+/)
+        let lower = [0, 0, 0]
+        let upper = MAX_VERSION
+        let valid = true
+        for (const token of tokens) {
+            const interval = tokenInterval(token)
+            if (!interval) {
+                valid = false
+                break
+            }
+            if (compareVersion(interval[0], lower) > 0) lower = interval[0]
+            if (compareVersion(interval[1], upper) < 0) upper = interval[1]
+        }
+        if (valid && compareVersion(lower, upper) < 0) intervals.push([lower, upper])
+    }
+    return intervals
+}
+
+/**
+ * List every major version a declared range can install (0-12), or null when
+ * the range cannot be parsed.
+ */
+function majorsForRange(range) {
+    const intervals = rangeIntervals(range)
+    if (!intervals.length) return null
+    const majors = []
+    for (let major = 0; major <= 12; major += 1) {
+        const lower = [major, 0, 0]
+        const upper = [major + 1, 0, 0]
+        const intersects = intervals.some(
+            ([intervalLower, intervalUpper]) =>
+                compareVersion(intervalLower, upper) < 0 &&
+                compareVersion(intervalUpper, lower) > 0,
+        )
+        if (intersects) majors.push(major)
+    }
+    return majors.length ? majors : null
+}
+
 /**
  * Detect ESLint major version from package.json or installed node_modules
  * Returns 8, 9, or null (not installed or ambiguous)
@@ -138,31 +291,22 @@ function detectEslintVersion(pkg = getProjectPkg(), rootDir = PROJECT_ROOT) {
         return 9
     }
 
-    // Range spanning both 8 and 9 (e.g. "^8.57.0 || ^9.0.0")
-    if (version.includes("||")) {
-        const parts = version.split("||").map((s) => s.trim())
-        const has8 = parts.some((p) => /\b8(?:\.\d+)?/.test(p))
-        const has9 = parts.some((p) => /\b9(?:\.\d+)?/.test(p))
-        if (has8 && has9) {
-            log("ESLint 依赖同时支持 8 与 9 且未安装本地副本，默认采用 ESLint 9 Flat Config")
-            return 9
-        }
+    const majors = majorsForRange(version)
+    if (!majors) {
+        // Fallback: check leading digit if available
+        const match = version.match(/(\d+)/)
+        return match ? parseInt(match[1], 10) : null
     }
 
-    // Explicit major 8 vs 9
-    const isMajor8 = /\b8(?:\.|\.x|\b)/.test(version) && !/^\s*(?:>=|\^)\s*9/.test(version)
-    const isMajor9 = /\b9(?:\.|\.x|\b)/.test(version) && !/<\s*9/.test(version)
-
-    if (isMajor8 && !isMajor9) return 8
-    if (isMajor9 && !isMajor8) return 9
-
-    // Fallback: check leading digit if available
-    const match = version.match(/(\d+)/)
-    if (match) {
-        return parseInt(match[1], 10)
+    // Ranges such as ">=8.0.0" or "^8.57.0 || ^9.0.0" can install either
+    // major; without a local install npm resolves the newest one (9).
+    if (majors.includes(8) && majors.includes(9)) {
+        log("ESLint 依赖同时支持 8 与 9 且未安装本地副本，默认采用 ESLint 9 Flat Config")
+        return 9
     }
-
-    return null
+    if (majors.includes(9)) return 9
+    if (majors.includes(8)) return 8
+    return majors[0]
 }
 
 /**
@@ -193,6 +337,52 @@ function isVueProject() {
     return !!(allDeps["vue"] || allDeps["@dcloudio/uni-app"] || allDeps["uni-app"])
 }
 
+/**
+ * Detect the package manager in use ("pnpm" | "npm" | "yarn" | "bun" | null).
+ * The lockfile is the project's own truth, so it wins over the user agent of
+ * whatever launched this CLI (e.g. `npx` inside a pnpm project).
+ */
+function detectPackageManager() {
+    if (fileExists("pnpm-lock.yaml")) return "pnpm"
+    if (fileExists("yarn.lock")) return "yarn"
+    if (fileExists("bun.lockb") || fileExists("bun.lock")) return "bun"
+    if (fileExists("package-lock.json")) return "npm"
+
+    const agent = process.env.npm_config_user_agent || ""
+    if (agent.startsWith("pnpm/")) return "pnpm"
+    if (agent.startsWith("yarn/")) return "yarn"
+    if (agent.startsWith("bun/")) return "bun"
+    if (agent.startsWith("npm/")) return "npm"
+    return null
+}
+
+function addDevCommand(packageManager) {
+    switch (packageManager) {
+        case "npm":
+            return "npm i -D"
+        case "yarn":
+            return "yarn add -D"
+        case "bun":
+            return "bun add -d"
+        default:
+            return "pnpm add -D"
+    }
+}
+
+/**
+ * `pnpm prepare` / `yarn prepare` run the script directly, but npm needs an
+ * explicit `npm run prepare` (plain `npm prepare` is not a command).
+ */
+function runScriptCommand(packageManager, script) {
+    switch (packageManager) {
+        case "npm":
+        case "bun":
+            return `${packageManager} run ${script}`
+        default:
+            return `${packageManager} ${script}`
+    }
+}
+
 /**
  * Detect project type: "uniapp", "vue", or "base"
  */
@@ -224,17 +414,26 @@ function detectCssPreprocessor() {
 
     // Fallback: check for existing stylelint config
     if (fileExists(".stylelintrc.cjs") || fileExists(".stylelintrc.js")) {
+        const stylelintFile = fileExists(".stylelintrc.cjs")
+            ? ".stylelintrc.cjs"
+            : ".stylelintrc.js"
+        let content = ""
         try {
-            const stylelintFile = fileExists(".stylelintrc.cjs")
-                ? ".stylelintrc.cjs"
-                : ".stylelintrc.js"
-            const content = fs.readFileSync(path.resolve(PROJECT_ROOT, stylelintFile), "utf8")
-            const hasPostcssLess = content.includes("postcss-less")
-            const hasPostcssScss =
-                content.includes("postcss-scss") || content.includes("my-code-style/stylelint")
-            if (hasPostcssLess && hasPostcssScss) return "both"
-            if (hasPostcssLess) return "less"
+            content = fs.readFileSync(path.resolve(PROJECT_ROOT, stylelintFile), "utf8")
         } catch {}
+        // "my-code-style/stylelint" is a prefix of "my-code-style/stylelint/less",
+        // so the Less entry must be matched before the SCSS one.
+        const usesLess =
+            /my-code-style\/stylelint\/less(?:-override)?/.test(content) ||
+            content.includes("postcss-less") ||
+            content.includes("stylelint-config-recommended-less")
+        const usesScss =
+            /my-code-style\/stylelint(?![-\w/])/.test(content) ||
+            content.includes("postcss-scss") ||
+            content.includes("stylelint-config-recommended-scss")
+        if (usesLess && usesScss) return "both"
+        if (usesLess) return "less"
+        if (usesScss) return "scss"
         return "scss"
     }
 
@@ -306,6 +505,11 @@ module.exports = require("${importPath}")
 }
 
 function commitlintrcContent() {
+    const mockScope = ["mock", "mocks", "src/mock", "src/mocks"].some((dir) =>
+        fs.existsSync(path.resolve(PROJECT_ROOT, dir)),
+    )
+        ? `, "mock"`
+        : ""
     return `// Commitlint config — powered by my-code-style
 const base = require("my-code-style/commitlint")
 const { generateScopes, guessCurrentScope } = require("my-code-style/commitlint/scopes")
@@ -319,7 +523,7 @@ module.exports = {
         ...base.prompt,
         customScopesAlign: !scopeComplete ? "top" : "bottom",
         defaultScope: scopeComplete,
-        scopes: [...scopes, "mock"],
+        scopes: [...scopes${mockScope}],
         allowEmptyIssuePrefixs: false,
         allowCustomIssuePrefixs: false,
     },
@@ -333,12 +537,14 @@ module.exports = require("my-code-style/versionrc")
 `
 }
 
+// Hook bodies live in src/husky/* so the shipped templates cannot drift from
+// what the CLI writes. Normalise the trailing newline.
 function huskyCommitMsg() {
-    return `npx --no-install commitlint --edit "\${1}"\n`
+    return readTemplate("src/husky/commit-msg").replace(/\s*$/, "\n")
 }
 
 function huskyPreCommit() {
-    return `npx --no-install -- lint-staged\n`
+    return readTemplate("src/husky/pre-commit").replace(/\s*$/, "\n")
 }
 
 function editorconfigContent() {
@@ -450,6 +656,7 @@ function main() {
     }
 
     // --- Detection phase ---
+    const pm = detectPackageManager() || "pnpm"
     const eslintVersion = detectEslintVersion()
     const cssPreprocessor = detectCssPreprocessor()
     const projectType = detectProjectType()
@@ -470,11 +677,19 @@ function main() {
         fileExists("eslint.config.cjs")
 
     if (eslintVersion !== null && eslintVersion < 8) {
-        console.error(`不支持 ESLint ${eslintVersion} 版本；本配置包仅支持 ESLint 8 或 9，未修改任何文件`)
+        console.error(
+            `不支持 ESLint ${eslintVersion} 版本；本配置包仅支持 ESLint 8 或 9，未修改任何文件`,
+        )
         process.exitCode = 1
         return
     }
 
+    if (eslintVersion !== null && eslintVersion >= 10) {
+        warn(
+            `ESLint ${eslintVersion} 尚未在 peerDependencies 声明支持（^8.57.0 || ^9.0.0），将按 Flat Config 生成`,
+        )
+    }
+
     // Do not silently mix an installed major version with an incompatible format.
     if (
         (eslintVersion >= 9 && hasLegacyConfigFile && !hasFlatConfigFile) ||
@@ -562,7 +777,9 @@ function main() {
     }
 
     if (isEsm && fileExists(".versionrc.js") && !fileExists(".versionrc.cjs")) {
-        warn("检测到 ESM 项目 (type: module) 存在旧的 .versionrc.js，standard-version 需使用 .versionrc.cjs")
+        warn(
+            "检测到 ESM 项目 (type: module) 存在旧的 .versionrc.js，standard-version 需使用 .versionrc.cjs",
+        )
     }
 
     files.push({
@@ -632,7 +849,9 @@ function main() {
     if (backup) {
         const backupDir = path.resolve(PROJECT_ROOT, ".my-code-style-backup")
         ensureDir(backupDir)
-        for (const item of [...files, ...hooks]) {
+        // 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" }]) {
             if (fileExists(item.path)) {
                 const srcPath = path.resolve(PROJECT_ROOT, item.path)
                 const targetPath = path.resolve(backupDir, item.path)
@@ -722,6 +941,11 @@ function main() {
             "lint-staged": getLintStagedConfig(cssPreprocessor),
         })
         success("更新 package.json (scripts + lint-staged)")
+
+        // The backup directory is ours, not the user's source — keep it out of git
+        if (backup) {
+            ensureGitignoreEntry(".my-code-style-backup/")
+        }
     } catch (err) {
         console.error(`\n  ✖ 初始化写入失败: ${err.message}；正在回滚...`)
         for (const [relPath, info] of snapshot.entries()) {
@@ -764,19 +988,28 @@ function main() {
     console.log("")
     console.log("  下一步：")
     console.log("  1. 确保已安装 peerDependencies：")
-    console.log("     pnpm add -D my-code-style")
+    console.log(`     ${addDevCommand(pm)} my-code-style`)
     if (useFlatConfig) {
         console.log("  2. Flat Config 需要的额外依赖：")
-        console.log("     pnpm add -D typescript-eslint globals eslint-plugin-import-x @eslint/js")
+        console.log(
+            `     ${addDevCommand(pm)} typescript-eslint globals eslint-plugin-import-x @eslint/js`,
+        )
         console.log("  3. 初始化 husky：")
-        console.log("     pnpm prepare")
+        console.log(`     ${runScriptCommand(pm, "prepare")}`)
         console.log("  4. 使用 czg 提交 commit：")
     } else {
         console.log("  2. 初始化 husky：")
-        console.log("     pnpm prepare")
+        console.log(`     ${runScriptCommand(pm, "prepare")}`)
         console.log("  3. 使用 czg 提交 commit：")
     }
-    console.log("     pnpm cz")
+    console.log(`     ${runScriptCommand(pm, "cz")}`)
+    if (pm === "pnpm") {
+        console.log("")
+        console.log("  提示：pnpm 10+ 默认拦截依赖的构建脚本，若安装时提示")
+        console.log(
+            "  ERR_PNPM_IGNORED_BUILDS（如 unrs-resolver），执行 pnpm approve-builds 后重试。",
+        )
+    }
     console.log("")
 }
 
@@ -787,6 +1020,20 @@ function modifyPackageJson(updates) {
         pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
     }
 
+    // A generated manifest must be installable on its own: npm requires
+    // name/version (e.g. running init in an empty directory).
+    if (typeof pkg.name !== "string" || !pkg.name.trim()) {
+        pkg.name =
+            path
+                .basename(PROJECT_ROOT)
+                .toLowerCase()
+                .replace(/[^a-z0-9._-]+/g, "-")
+                .replace(/^[._-]+|[._-]+$/g, "") || "my-project"
+    }
+    if (typeof pkg.version !== "string" || !pkg.version.trim()) {
+        pkg.version = "1.0.0"
+    }
+
     // Merge scripts: updates won't overwrite existing scripts with the same key
     if (updates.scripts) {
         pkg.scripts = { ...updates.scripts, ...(pkg.scripts || {}) }
@@ -797,7 +1044,14 @@ function modifyPackageJson(updates) {
         pkg["lint-staged"] = updates["lint-staged"]
     }
 
-    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 4) + "\n", "utf8")
+    // Keep the project's own indentation (a 2-space repo should not be reflowed)
+    const previous = fileExists("package.json") ? fs.readFileSync(pkgPath, "utf8") : ""
+    const indentMatch = previous.match(/^[ \t]+(?=")/m)
+    fs.writeFileSync(
+        pkgPath,
+        JSON.stringify(pkg, null, indentMatch ? indentMatch[0] : 4) + "\n",
+        "utf8",
+    )
 }
 
 function checkPeerDeps({
@@ -815,6 +1069,8 @@ function checkPeerDeps({
 
     const baseDeps = [
         "eslint",
+        // Required by @typescript-eslint/parser and typescript-eslint at runtime
+        "typescript",
         "prettier",
         ...(projectType !== "base" ? ["eslint-plugin-vue"] : []),
         "@commitlint/cli",
@@ -904,7 +1160,7 @@ function checkPeerDeps({
         warn(`以下依赖未安装：${missing.join(", ")}`)
         console.log("")
         warn("一键安装命令：")
-        console.log(`  pnpm add -D my-code-style \\`)
+        console.log(`  ${addDevCommand(detectPackageManager())} my-code-style \\`)
         missing.forEach((dep, i) => {
             const version =
                 dep === "eslint" ? (useFlatConfig ? "^9.0.0" : "^8.57.0") : peerDeps[dep] || ""
@@ -915,4 +1171,7 @@ function checkPeerDeps({
     }
 }
 
-main()
+// Only run when executed directly; requiring this file must be side-effect free.
+if (require.main === module) {
+    main()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-code-style",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Lint/Format/Git 配置工程化 npm 包（ESLint + Prettier + Stylelint + Commitlint + Husky + standard-version）",
   "type": "commonjs",
   "main": "src/eslint/uniapp.cjs",
@@ -34,7 +34,8 @@
   "files": [
     "src",
     "bin",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -93,6 +94,7 @@
     "stylelint-config-recommended-scss": "^16.0.0",
     "stylelint-config-recommended-vue": "^2.0.0",
     "stylelint-prettier": "^5.0.0",
+    "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",
     "vue-eslint-parser": "^10.3.0"
   },
@@ -184,6 +186,9 @@
     "stylelint-prettier": {
       "optional": true
     },
+    "typescript": {
+      "optional": true
+    },
     "typescript-eslint": {
       "optional": true
     },

package/src/commitlint/scopes.cjs

@@ -25,34 +25,88 @@ const PLURAL_MAP = {
     assets: "asset",
 }
 
+// Plurals whose singular cannot be derived by rule: uncountables, irregulars,
+// and the "-e" + "s" words that would otherwise lose their stem ("caches" →
+// "cach"). Everything else is handled by the suffix rules below.
+const EXACT_SINGULAR = {
+    news: "news",
+    series: "series",
+    movies: "movie",
+    cookies: "cookie",
+    caches: "cache",
+    chases: "chase",
+    niches: "niche",
+}
+
+// Directory names that already read as singular (or are conventional as-is)
+const NON_PLURAL = [
+    "status",
+    "canvas",
+    "bus",
+    "pass",
+    "process",
+    "css",
+    "less",
+    "scss",
+    "js",
+    "ts",
+    "types",
+]
+
+// Singulars that legitimately end in "s"/"z" and therefore take "-es":
+// bus → buses, status → statuses. Without this list "buses" would follow the
+// "-se + s" reading and become "buse".
+const SIBILANT_SINGULARS = [
+    "bus",
+    "gas",
+    "canvas",
+    "alias",
+    "atlas",
+    "bias",
+    "virus",
+    "status",
+    "process",
+    "lens",
+    "plus",
+    "focus",
+    "campus",
+    "analysis",
+    "axis",
+    "basis",
+    "crisis",
+    "thesis",
+    "quiz",
+]
+
+// Unambiguous "-es" plurals: the stem ends in a doubled sibilant or a digraph
+// (classes, boxes, churches, dishes, buzzes, batches, fixes).
+const ES_PLURAL = /(?:ss|zz|ch|sh|x)es$/i
+// "-ses"/"-zes" are ambiguous: "cases" is case + s, "buses" is bus + es.
+const S_OR_Z_ES_PLURAL = /[sz]es$/i
+
 function toSingular(name) {
     if (!name) {
         return name
     }
-    if (PLURAL_MAP[name]) {
-        return PLURAL_MAP[name]
+    const lower = name.toLowerCase()
+    if (PLURAL_MAP[lower]) {
+        return PLURAL_MAP[lower]
+    }
+    if (EXACT_SINGULAR[lower]) {
+        return EXACT_SINGULAR[lower]
     }
-    if (name.endsWith("ies") && name.length > 4) {
+    if (NON_PLURAL.includes(lower)) {
+        return name
+    }
+    if (/ies$/i.test(name) && name.length > 4) {
         return name.slice(0, -3) + "y"
     }
-    if (/(?:[sxz]|[ch|sh])es$/.test(name)) {
+    if (ES_PLURAL.test(name)) {
         return name.slice(0, -2)
     }
-    const nonPluralEndingInS = [
-        "status",
-        "canvas",
-        "bus",
-        "pass",
-        "process",
-        "css",
-        "less",
-        "scss",
-        "js",
-        "ts",
-        "types",
-    ]
-    if (nonPluralEndingInS.includes(name.toLowerCase())) {
-        return name
+    if (S_OR_Z_ES_PLURAL.test(name)) {
+        const esStem = name.slice(0, -2).toLowerCase()
+        return SIBILANT_SINGULARS.includes(esStem) ? name.slice(0, -2) : name.slice(0, -1)
     }
     if (name.endsWith("s") && !name.endsWith("ss") && name.length > 3) {
         return name.slice(0, -1)
@@ -71,11 +125,15 @@ function generateScopes(srcDirs = "src") {
 
     for (const srcDir of dirs) {
         const resolved = path.resolve(process.cwd(), srcDir)
-        if (!fs.existsSync(resolved)) {
+        let entries
+        try {
+            // A missing path, a plain file, or an unreadable directory must not
+            // break the commitlint config load — just yield no scopes.
+            entries = fs.readdirSync(resolved, { withFileTypes: true })
+        } catch {
             continue
         }
-        const scopes = fs
-            .readdirSync(resolved, { withFileTypes: true })
+        const scopes = entries
             .filter((dirent) => dirent.isDirectory())
             .map((dirent) => toSingular(dirent.name))
         allScopes.push(...scopes)

package/src/eslint/base.cjs

@@ -20,6 +20,17 @@ module.exports = {
             jsx: true,
         },
     },
+    // Mirrors the ignores of src/eslint/flat/base.mjs: without them `eslint .`
+    // lints build output (dist/, coverage/) and fails on generated code.
+    ignorePatterns: [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/coverage/**",
+        "**/public/**",
+        "**/assets/iconfont/**",
+        "**/*.min.js",
+        "**/*.min.css",
+    ],
     plugins: ["@typescript-eslint", "prettier", "import"],
     overrides: [
         {
@@ -42,7 +53,10 @@ module.exports = {
         // 格式化与风格
         indent: "off",
         semi: ["error", "never"],
-        quotes: ["error", "double", { avoidEscape: false, allowTemplateLiterals: true }],
+        // avoidEscape must stay true: Prettier keeps the cheaper quote when a
+        // string contains double quotes ('say "hi"'), so requiring an escape
+        // here produces an error that --fix can never resolve.
+        quotes: ["error", "double", { avoidEscape: true, allowTemplateLiterals: true }],
         curly: ["error", "all"],
         "comma-dangle": ["error", "always-multiline"],
         "object-curly-spacing": ["error", "always"],

package/src/eslint/flat/_shared.mjs

@@ -23,7 +23,10 @@ export const commonRules = {
     // 缩进由 Prettier 统一负责，关闭 ESLint 缩进避免打架
     indent: "off",
     semi: ["error", "never"],
-    quotes: ["error", "double", { avoidEscape: false, allowTemplateLiterals: true }],
+    // avoidEscape must stay true: Prettier keeps the cheaper quote when a
+    // string contains double quotes ('say "hi"'), so requiring an escape here
+    // produces an error that --fix can never resolve.
+    quotes: ["error", "double", { avoidEscape: true, allowTemplateLiterals: true }],
     curly: ["error", "all"],
     "comma-dangle": ["error", "always-multiline"],
     "object-curly-spacing": ["error", "always"],

package/src/eslint/flat/base.mjs

@@ -27,7 +27,7 @@ export default [
     ...tseslint.configs.recommended,
 
     // eslint-plugin-import-x configuration
-    // Replaces: plugin:import/recommended + eslint-config-standard (via FlatCompat)
+    // Replaces: plugin:import/recommended (ESLint 8 equivalent in src/eslint/base.cjs)
     {
         files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx,vue,nvue}"],
         plugins: {
@@ -66,7 +66,16 @@ export default [
         },
     },
 
-    // Shared rules for all JS, TS, JSX, TSX and Vue files
+    // Prettier integration (replaces: extends: ["plugin:prettier/recommended"])
+    eslintPluginPrettierRecommended,
+
+    // eslint-config-prettier disables rules that conflict with Prettier —
+    // including `curly`, which Prettier never rewrites.
+    eslintConfigPrettier,
+
+    // Shared rules for all JS, TS, JSX, TSX and Vue files.
+    // MUST come after eslint-config-prettier: in flat config a later entry wins,
+    // so explicit rules such as `curly` would otherwise be silently switched off.
     {
         files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx,vue,nvue}"],
         rules: {
@@ -83,19 +92,14 @@ export default [
         },
     },
 
-    // .nvue file handling (uni-app)
+    // .nvue file handling (uni-app) — mirrors the legacy config, which parses
+    // nvue script blocks as modules so `import` works.
     {
         files: ["**/*.nvue"],
         languageOptions: {
             parserOptions: {
-                sourceType: "script",
+                sourceType: "module",
             },
         },
     },
-
-    // Prettier integration (replaces: extends: ["plugin:prettier/recommended"])
-    eslintPluginPrettierRecommended,
-
-    // eslint-config-prettier MUST be last — disables conflicting ESLint rules
-    eslintConfigPrettier,
 ]

package/src/eslint/flat/vue3.mjs

@@ -49,6 +49,10 @@ export default [
         },
         rules: {
             "vue/comment-directive": "off",
+            // .nvue uses semicolons (see src/prettier/index.cjs), so the base
+            // `semi: ["error", "never"]` rule must be disabled here — mirrors
+            // the legacy config in src/eslint/vue3.cjs.
+            semi: "off",
             // Prettier cannot infer a parser from the custom .nvue extension.
             "prettier/prettier": ["error", { parser: "vue", semi: true }],
         },

package/src/gitignore

@@ -1,5 +1,6 @@
 node_modules/
 dist/
+unpackage/
 coverage/
 *.local
 *.log