代码质量工具包

项目概述

质量助手(Quality Helper)是一个集代码规范、版本管理和开发流程优化于一体的现代化前端脚手架工具。提供一站式代码质量解决方案，支持快速集成到现代前端项目开发流程中，具备智能依赖管理、配置文件更新、版本信息生成等核心功能。

🚀 快速开始

安装

# 全局安装（推荐）
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分钟上手指南

①创建新项目

# 交互式创建项目（推荐新手）
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

②为现有项目添加质量工具

# 进入现有项目目录
cd existing-project

# 一键添加代码规范配置
npx quality-helper update-config
# or
npx qh update-config

# 更新依赖到最新稳定版本
npx quality-helper update-deps
# or
npx qh update-deps

③ 验证配置效果

# 检查代码规范
npm run lint

# 格式化代码
npm run format

# 提交代码（会自动触发质量检查）
git add .
git commit -m "feat: add quality tools"

④Vite插件集成示例

// 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',
    }),
  ],
})

// 在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)

# 基础用法
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)

# 交互式依赖更新
npx quality-helper update-deps

依赖管理特性：

• 🔍 智能检测 - 自动识别包管理器（npm/pnpm/yarn）
• 📊 状态分析 - 显示过时依赖和安全漏洞
• 🎯 精准分类 - 区分生产依赖和开发依赖
• 🚀 批量操作 - 支持一键更新所有依赖
• 🛠️ 自动修复 - 自动处理pnpm锁文件损坏问题
• 🔄 版本智能获取 - 自动获取npm最新稳定版本号

配置文件更新功能

• 智能合并：自动合并现有配置与模板配置
• 一步式选择：支持分组全选或单文件选择
• 模板优先：新配置项优先，保留用户自定义配置
• 格式保持：保持原有文件格式和注释结构
• 依赖自动安装：配置更新后自动检测并提示安装所需依赖
• 智能依赖分类：自动区分生产依赖和开发依赖进行安装

依赖管理功能

• 智能检测：自动检测项目中缺失的依赖包
• 分类安装：区分生产依赖和开发依赖，精准安装
• 多包管理器支持：自动检测并使用项目的包管理器（npm/yarn/pnpm）
• 版本管理：支持更新到推荐版本或最新版本
• 依赖清理：支持清理缓存和重新安装
• 状态检查：提供详细的依赖状态报告
• 锁文件修复：自动检测并修复pnpm锁文件损坏问题（ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY）
• 版本号智能解析：当依赖版本为'latest'时，自动获取npm仓库最新稳定版本
• 错误恢复：遇到依赖冲突时自动使用--no-frozen-lockfile参数重试安装

版本信息说明

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：新项目快速启动

# 创建企业级Vue3项目
npx quality-helper create my-admin-system --single
cd my-admin-system

# 项目自动包含：
# ✅ TypeScript + Vite 构建配置
# ✅ ESLint + Prettier 代码规范
# ✅ Git Hooks + Commitlint 提交规范
# ✅ 环境变量配置
# ✅ 依赖管理脚本

# 开始开发
npm run dev

场景2：现有项目规范化

# 进入现有混乱项目
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项目管理

# 创建组件库项目
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：团队协作规范

# 团队成员克隆项目后
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): 添加新按钮组件"