# 代码质量工具包

## 项目概述

质量助手(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): 添加新按钮组件"
```