@tianyio/quality-helper

# 代码质量工具包 ## 项目概述质量助手(Quality Helper)是一个集代码规范、版本管理和开发流程优化于一体的现代化前端脚手架工具。提供一站式代码质量解决方案，支持快速集成到现代前端项目开发流程中，具备智能依赖管理、配置文件更新、版本信息生成等核心功能。 ## 🚀 快速开始 ### 安装 ```bash # 全局安装（推荐） npm install -g @tianyio/quality-helper # 或 pnpm add -g @tianyio/quality-helper # 或 yarn global add @tianyio/quality-helper # 项目依赖安装 npm install @tianyio/quality-helper # 或使用npx直接运行 npx @tianyio/quality-helper <command> ``` ### 5分钟上手指南 #### ①创建新项目 ```bash # 交互式创建项目（推荐新手） npx quality-helper create # or npx qh create # 快速创建 Vue3 项目 npx quality-helper create my-vue-app --single #or npx qh create my-vue-app --single # 创建企业级 Monorepo 项目 npx quality-helper create my-workspace --monorepo # or npx qh create my-workspace --monorepo ``` #### ②为现有项目添加质量工具 ```bash # 进入现有项目目录 cd existing-project # 一键添加代码规范配置 npx quality-helper update-config # or npx qh update-config # 更新依赖到最新稳定版本 npx quality-helper update-deps # or npx qh update-deps ``` #### ③ 验证配置效果 ```bash # 检查代码规范 npm run lint # 格式化代码 npm run format # 提交代码（会自动触发质量检查） git add . git commit -m "feat: add quality tools" ``` #### ④Vite插件集成示例 ```typescript // vite.config.ts import { defineConfig } from 'vite' import { versionInfoPlugin } from '@tianyio/quality-helper/version-plugin' export default defineConfig({ plugins: [ versionInfoPlugin({ // 开发模式下提供API接口 injectGitInfo: true, injectBuildTime: true, // 生产构建时生成版本文件 generateFile: true, outputPath: 'dist/version.json', }), ], }) ``` ```typescript // 在Vue组件中使用 <template> <div class="version-info"> <p>版本: {{ versionInfo.version }}</p> <p>构建时间: {{ versionInfo.buildTime }}</p> <p>Git提交: {{ versionInfo.gitCommitShort }}</p> </div> </template> <script setup lang="ts"> import { ref, onMounted } from 'vue' import versionInfo from 'virtual:version-info' </script> ``` ## 📖 详细使用指南 ### CLI 命令详解 #### 🏗️ 项目创建 (`create`) ```bash # 基础用法 npx quality-helper create [项目名称] [选项] # or npx qh create [项目名称] [选项] # 交互式创建（推荐） npx quality-helper create # or npx qh create npx quality-helper create my-awesome-project # or npx qh create my-awesome-project # 指定架构类型 npx quality-helper create my-project --single # 单体仓库 npx qh create my-workspace --monorepo # Monorepo架构 # 组合使用 npx quality-helper create vue-admin --single # Vue3单体项目 npx qh create react-components --monorepo # React组件库 ``` **创建流程说明：** 1. 选择项目架构（单体/Monorepo） 2. 选择前端框架（Vue3/React/Vanilla） 3. 配置项目基础信息 4. 自动安装依赖和配置工具 5. 初始化 Git 仓库和提交规范 #### 📦 依赖管理 (`update-deps`) ```bash # 交互式依赖更新 npx quality-helper update-deps ``` **依赖管理特性：** - 🔍 **智能检测** - 自动识别包管理器（npm/pnpm/yarn） - 📊 **状态分析** - 显示过时依赖和安全漏洞 - 🎯 **精准分类** - 区分生产依赖和开发依赖 - 🚀 **批量操作** - 支持一键更新所有依赖 - 🛠️ **自动修复** - 自动处理pnpm锁文件损坏问题 - 🔄 **版本智能获取** - 自动获取npm最新稳定版本号 ### 配置文件更新功能 - **智能合并**：自动合并现有配置与模板配置 - **一步式选择**：支持分组全选或单文件选择 - **模板优先**：新配置项优先，保留用户自定义配置 - **格式保持**：保持原有文件格式和注释结构 - **依赖自动安装**：配置更新后自动检测并提示安装所需依赖 - **智能依赖分类**：自动区分生产依赖和开发依赖进行安装 ### 依赖管理功能 - **智能检测**：自动检测项目中缺失的依赖包 - **分类安装**：区分生产依赖和开发依赖，精准安装 - **多包管理器支持**：自动检测并使用项目的包管理器（npm/yarn/pnpm） - **版本管理**：支持更新到推荐版本或最新版本 - **依赖清理**：支持清理缓存和重新安装 - **状态检查**：提供详细的依赖状态报告 - **锁文件修复**：自动检测并修复pnpm锁文件损坏问题（ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY） - **版本号智能解析**：当依赖版本为'latest'时，自动获取npm仓库最新稳定版本 - **错误恢复**：遇到依赖冲突时自动使用--no-frozen-lockfile参数重试安装 ### 版本信息说明 ```ts interface VersionInfo { // 基本信息 name: string // 项目名称 version: string // 项目版本 description: string // 项目描述 author: string // 项目作者 homepage: string // 项目主页 repository: string // 仓库地址 license: string // 许可证 // 构建信息 buildTime: string // 构建时间（ISO格式） buildTimestamp: number // 构建时间戳 // Git信息 gitCommitHash: string // 完整提交哈希 gitCommitShort: string // 短提交哈希 gitBranch: string // 当前分支 gitCommitDate: string // 提交日期 gitCommitMessage: string // 提交信息 gitAuthor: string // 提交作者 gitEmail: string // 作者邮箱 gitDirty: boolean // 是否有未提交更改 // 环境信息 nodeVersion: string // Node.js版本 platform: string // 操作系统平台 arch: string // 系统架构 } ``` ## 配置文件支持 ### EditorConfig 分组 | 配置文件 | 描述 | | ------------- | -------------- | | .editorconfig | 编辑器配置文件 | ### ESLint 分组 | 配置文件 | 描述 | | ------------- | --------------- | | .eslintrc.js | ESLint 配置文件 | | .eslintignore | ESLint 忽略文件 | ### Prettier 分组 | 配置文件 | 描述 | | --------------- | ----------------- | | .prettierrc | Prettier 配置文件 | | .prettierignore | Prettier 忽略文件 | ### Git 相关分组 | 配置文件 | 描述 | | -------------------- | -------------------- | | .gitignore | Git 忽略文件 | | .gitattributes | Git 属性文件 | | .lintstagedrc.js | Lint-staged 配置文件 | | commitlint.config.js | Commitlint 配置文件 | | .husky/pre-commit | Git pre-commit 钩子 | | .husky/commit-msg | Git commit-msg 钩子 | ### NPM 分组 | 配置文件 | 描述 | | -------- | ------------- | | .npmrc | NPM 配置文件 | | .pnpmrc | PNPM 配置文件 | ### 环境变量分组 | 配置文件 | 描述 | | ------------ | ------------ | | .env | 环境变量文件 | | .env.local | 本地环境变量 | | .env.develop | 开发环境变量 | | .env.prod | 生产环境变量 | ## 🎯 实际使用场景 ### 场景1：新项目快速启动 ```bash # 创建企业级Vue3项目 npx quality-helper create my-admin-system --single cd my-admin-system # 项目自动包含： # ✅ TypeScript + Vite 构建配置 # ✅ ESLint + Prettier 代码规范 # ✅ Git Hooks + Commitlint 提交规范 # ✅ 环境变量配置 # ✅ 依赖管理脚本 # 开始开发 npm run dev ``` ### 场景2：现有项目规范化 ```bash # 进入现有混乱项目 cd legacy-project # 一键添加质量工具 npx quality-helper update-config # 更新依赖到稳定版本 npx quality-helper update-deps # 验证效果 npm run lint # 检查代码规范 npm run format # 格式化代码 git add . && git commit -m "feat: 添加代码质量工具" ``` ### 场景3：Monorepo项目管理 ```bash # 创建组件库项目 npx quality-helper create ui-components --monorepo cd ui-components # 生成的结构： # ├── apps/ # 应用目录 # │ └── docs/ # 文档站点 # ├── packages/ # 包目录 # │ ├── components/ # 组件包 # │ └── utils/ # 工具包 # ├── package.json # 根配置 # └── pnpm-workspace.yaml # workspace配置 # 统一管理所有子包的依赖 npx quality-helper update-deps ``` ### 场景4：团队协作规范 ```bash # 团队成员克隆项目后 git clone <project-url> cd project # 检查并更新开发环境 npx quality-helper update-deps # 如果有新的配置更新 npx quality-helper update-config # 提交代码时自动触发： # 1. pre-commit: 代码格式检查和修复 # 2. commit-msg: 提交信息格式验证 git commit -m "feat(components): 添加新按钮组件" ```