my-code-style 1.2.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

@@ -1,33 +1,67 @@
 # my-code-style
 
-Lint/Format/Git 配置工程化 npm 包。适用于 Vue 3 + TypeScript + uni-app 项目。
+Lint/Format/Git 配置工程化 npm 包。适用于 Vue 3 + TypeScript + uni-app 项目及纯 Node/TS 基础工程。
 
 支持 ESLint v8 (.eslintrc.cjs) 和 ESLint v9 (Flat Config) 双格式，支持 SCSS 和 Less 样式检查。
 
-## 快速开始
+## 项目文档
+
+- [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 脚本会自动检测项目的 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 内嵌样式             |
+| 规则同步   | 每个项目各抄一份             | 升级一个依赖版本，全项目生效                      |
 
 ## 生成的文件
 
-| 文件 | 说明 |
-|------|------|
-| `.eslintrc.cjs` | ESLint 配置（v8 项目，TypeScript + Vue 3 + uni-app） |
-| `eslint.config.ts` | ESLint Flat Config（v9 项目，TypeScript + Vue 3 + uni-app） |
-| `.prettierrc.cjs` | Prettier 格式化配置 |
-| `.prettierignore` | Prettier 忽略文件（跳过二进制文件） |
-| `.stylelintrc.cjs` | Stylelint CSS/SCSS/Less 配置 |
-| `.commitlintrc.cjs` | Git commit 信息规范 |
-| `.versionrc.js` | 自动版本号 + CHANGELOG 生成 |
-| `.editorconfig` | 编辑器基础配置 |
-| `.gitattributes` | Git 文件类型处理（统一 EOL=LF，标记二进制文件） |
-| `.husky/commit-msg` | Git hook: commitlint |
-| `.husky/pre-commit` | Git hook: lint-staged |
+| 文件                               | 说明                                                                          |
+| ---------------------------------- | ----------------------------------------------------------------------------- |
+| `.eslintrc.cjs`                    | ESLint 配置（v8 项目，TypeScript + Vue 3 / uni-app）                          |
+| `eslint.config.mjs`                | ESLint Flat Config（v9 项目，默认优先推荐）                                   |
+| `.prettierrc.cjs`                  | Prettier 格式化配置                                                           |
+| `.prettierignore`                  | Prettier 忽略文件（跳过二进制文件与产物）                                     |
+| `.stylelintrc.cjs`                 | Stylelint CSS/SCSS/Less 配置（非样式项目自动跳过）                            |
+| `.commitlintrc.cjs`                | Git commit 信息规范（支持智能 scope 猜测）                                    |
+| `.versionrc.js` / `.versionrc.cjs` | 自动版本号 + CHANGELOG（ESM 生成 `.versionrc.cjs`，CJS 生成 `.versionrc.js`） |
+| `.editorconfig`                    | 编辑器基础配置                                                                |
+| `.gitattributes`                   | Git 文件类型处理（统一 EOL=LF，标记二进制文件）                               |
+| `.gitignore`                       | Git 忽略文件（自动忽略 node_modules/、dist/、*.tgz 等）                       |
+| `.husky/commit-msg`                | Git hook: commitlint（Husky 9 格式）                                          |
+| `.husky/pre-commit`                | Git hook: lint-staged（Husky 9 格式）                                         |
 
 ## 手动使用（不通过 init）
 
@@ -38,18 +72,18 @@ init 脚本会自动检测项目的 ESLint 版本和 CSS 预处理器，生成
 module.exports = require("my-code-style/eslint/uniapp")
 
 // 或按需引入中间层
-const base = require("my-code-style/eslint")        // 基础 TypeScript
-const vue3 = require("my-code-style/eslint/vue3")   // + Vue 3 规则
+const base = require("my-code-style/eslint") // 基础 TypeScript
+const vue3 = require("my-code-style/eslint/vue3") // + Vue 3 规则
 ```
 
-### ESLint v9 (Flat Config / eslint.config.ts)
+### ESLint v9 (Flat Config / eslint.config.mjs)
 
-```ts
-// eslint.config.ts
+```js
+// eslint.config.mjs
 import uniappConfig from "my-code-style/eslint/flat/uniapp"
 
 // 或按需引入中间层
-import baseConfig from "my-code-style/eslint/flat/base"
+import baseConfig from "my-code-style/eslint/flat"
 import vue3Config from "my-code-style/eslint/flat/vue3"
 ```
 
@@ -65,7 +99,16 @@ module.exports = require("my-code-style/stylelint")
 // .commitlintrc.cjs
 const base = require("my-code-style/commitlint")
 const { generateScopes, guessCurrentScope } = require("my-code-style/commitlint/scopes")
-module.exports = { ...base, prompt: { ...base.prompt, scopes: generateScopes("src") } }
+const scopeComplete = guessCurrentScope()
+module.exports = {
+    ...base,
+    prompt: {
+        ...base.prompt,
+        customScopesAlign: !scopeComplete ? "top" : "bottom",
+        defaultScope: scopeComplete,
+        scopes: [...generateScopes("src"), "mock"],
+    },
+}
 
 // .versionrc.js
 module.exports = require("my-code-style/versionrc")
@@ -87,32 +130,74 @@ module.exports = {
 
 ## 导出入口
 
-| 入口 | 说明 |
-|------|------|
-| `my-code-style` | 默认：ESLint v8 uni-app 配置 |
-| `my-code-style/eslint` | 基础 ESLint v8（TypeScript） |
-| `my-code-style/eslint/vue3` | + Vue 3 规则 |
-| `my-code-style/eslint/uniapp` | + uni-app globals |
-| `my-code-style/eslint/flat` | ESLint v9 Flat Config 基础 |
-| `my-code-style/eslint/flat/vue3` | + Vue 3 规则 |
-| `my-code-style/eslint/flat/uniapp` | + uni-app globals |
-| `my-code-style/prettier` | Prettier 配置 |
-| `my-code-style/stylelint` | Stylelint 配置（SCSS + Less） |
-| `my-code-style/stylelint/less-override` | Less 专用覆写配置 |
-| `my-code-style/commitlint` | Commitlint 基础配置 |
-| `my-code-style/commitlint/scopes` | 动态 scope 工具函数 |
-| `my-code-style/versionrc` | standard-version 配置 |
+| 入口                                    | 说明                          |
+| --------------------------------------- | ----------------------------- |
+| `my-code-style`                         | 默认：ESLint v8 uni-app 配置  |
+| `my-code-style/eslint`                  | 基础 ESLint v8（TypeScript）  |
+| `my-code-style/eslint/vue3`             | + Vue 3 规则                  |
+| `my-code-style/eslint/uniapp`           | + uni-app globals             |
+| `my-code-style/eslint/flat`             | ESLint v9 Flat Config 基础    |
+| `my-code-style/eslint/flat/vue3`        | + Vue 3 规则                  |
+| `my-code-style/eslint/flat/uniapp`      | + uni-app globals             |
+| `my-code-style/prettier`                | Prettier 配置                 |
+| `my-code-style/stylelint`               | Stylelint 配置（SCSS / 默认） |
+| `my-code-style/stylelint/less`          | Less 专用 Stylelint 配置      |
+| `my-code-style/stylelint/less-override` | Less 专用覆写配置             |
+| `my-code-style/commitlint`              | Commitlint 基础配置           |
+| `my-code-style/commitlint/scopes`       | 动态 scope 工具函数           |
+| `my-code-style/versionrc`               | standard-version 配置         |
+
+## CLI 初始化参数
+
+```bash
+npx my-code-style-init [--dry-run] [--backup] [--version|-v] [--help|-h]
+```
+
+- `--dry-run`：试运行模式，仅输出将执行的变更，不修改任何文件。
+- `--backup`：在覆盖已有配置文件之前，将其备份到 `.my-code-style-backup/` 目录。
+- 具备**事务回滚保护**：若在写入过程中遭遇文件权限或磁盘异常，自动回滚所有修改，恢复工作区原始状态。
 
 ## 特性
 
-- **双引号**：`quotes: ["error", "double", { avoidEscape: false, allowTemplateLiterals: true }]`
-- **4 空格缩进**：`tabWidth: 4`
+- **双引号**：`quotes: ["error", "double", { avoidEscape: true, allowTemplateLiterals: true }]`（`avoidEscape` 必须为 `true`，否则与 Prettier 的转义策略冲突，`--fix` 无法消除报错）
+- **4 空格缩进**：`tabWidth: 4`（由 Prettier 全权统一格式化）
 - **无分号**：`semi: false`（`.nvue` 文件除外）
 - **行宽 100**：`printWidth: 100`
-- **小程序适配**：允许 `rpx` 单位、`page` 标签、`::v-deep` 伪类
-- **uni-app globals**：`uni`、`UniApp`、`wx`、`getCurrentPages` 等
-- **Less 支持**：`postcss-less` 解析、`@` 变量放行、`::v-deep` 伪元素
-- **双 ESLint 格式**：v8 (.eslintrc.cjs) 和 v9 (Flat Config) 自动检测
+- **JSX / TSX 全面支持**：Flat Config 与传统配置均支持 `.jsx` 和 `.tsx` 语法解析、Prettier 格式化、规则修复与目录扫描
+- **多工程形态适配**：智能识别 uni-app / Vue 3 / 纯 Node-TS 基础工程，无样式的纯代码项目自动跳过 Stylelint
+- **双 ESLint 格式**：ESLint v9 (Flat Config，未配置项目默认优先) 与 v8 (.eslintrc.cjs) 全自动检测，强化支持 npm 别名、workspace 协议与复杂 semver 范围
+- **现代化 Git Hooks**：采用 Husky 9 原生极简 hook + lint-staged 互斥文件分组，串行运行、消除并发写入缓存冲突
+- **Stylelint SCSS、Less 及混合工程双支持**：支持纯 SCSS、纯 Less 以及两者共存的混合工程，放行 `@` 变量、小程序 `rpx`/`page`、深度选择器 `::v-deep` 及现代 CSS 伪类，组件内嵌多预处理器样式全面检查
+- **严格暂存区 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 与配置矩阵测试（59 项）
+npm run test:integration:setup # 安装现代化隔离依赖运行环境
+npm run test:integration       # 运行 Flat Config、真实 Husky 及提交链路测试（47 项）
+npm run test:legacy:setup      # 安装 ESLint 8 隔离运行环境
+npm run test:legacy            # 运行 ESLint 8.57.0 兼容性回归测试（27 项）
+npm run test:all               # 全量运行全部 133 项测试
+```
 
 ## License