Lint Tools SDK

一个用于在多个Git仓库中统一代码质量管理的前端代码规范工具SDK（npm包形式）。

核心功能

• ✅ ESLint集成：支持ESLint v9+ flat config格式，实现代码格式化校验
• ✅ commitlint集成：提交信息规范校验，确保提交信息格式统一
• ✅ Git Hooks自动触发：通过husky在提交代码时自动对暂存文件进行格式化校验
• ✅ lint-staged：仅对Git暂存文件执行ESLint校验与修复
• ✅ 配置覆盖机制：项目级配置自动合并覆盖SDK默认配置
• ✅ CLI命令支持：提供丰富的命令行工具，方便使用和集成

安装

# 全局安装（可选）
npm install -g lint-tools-sdk

# 局部安装
npm install --save-dev lint-tools-sdk

快速开始

1. 初始化项目

在项目根目录下执行：

npx lint-tools-sdk init

此命令会：

• 安装Git Hooks（pre-commit和commit-msg）
• 创建默认配置文件（eslint.config.js、.commitlintrc.js、.lintstagedrc.js）
• 更新package.json脚本

2. 基本使用

代码校验

# 全量代码校验
npx lint-tools-sdk lint

# 自动修复代码问题
npx lint-tools-sdk lint:fix

# 仅校验暂存文件
npx lint-tools-sdk lint:staged

提交信息校验

# 校验提交信息
npx lint-tools-sdk commitlint "feat: add new feature"

# 使用git commit时会自动触发校验

查看诊断信息

# 查看当前配置和服务状态
npx lint-tools-sdk status

配置说明

1. 项目级配置

可以通过以下方式覆盖SDK的默认配置：

a) package.json中的lintToolsConfig

{
  "lintToolsConfig": {
    "eslint": {
      "enabled": true,
      "fix": true
    },
    "commitlint": {
      "enabled": true
    },
    "githooks": {
      "enabled": true
    },
    "lintStaged": {
      "enabled": true
    }
  }
}

b) .linttoolsrc.js配置文件

module.exports = {
  eslint: {
    enabled: true,
    fix: true
  },
  commitlint: {
    enabled: true
  },
  githooks: {
    enabled: true
  },
  lintStaged: {
    enabled: true
  }
};

2. ESLint配置

SDK使用ESLint v9+的flat config格式，默认配置文件为eslint.config.js：

import globals from "globals";
import pluginJs from "@eslint/js";

export default [
  {
    files: ["**/*.js"],
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
      globals: {
        ...globals.node,
        ...globals.browser
      }
    },
    rules: {
      ...pluginJs.configs.recommended.rules,
      // 项目自定义规则
    }
  }
];

3. commitlint配置

默认配置文件为.commitlintrc.js：

module.exports = {
  extends: ['@commitlint/config-conventional']
};

4. lint-staged配置

默认配置文件为.lintstagedrc.js：

module.exports = {
  '*.js': ['eslint --fix', 'git add'],
  '*.jsx': ['eslint --fix', 'git add'],
  '*.ts': ['eslint --fix', 'git add'],
  '*.tsx': ['eslint --fix', 'git add']
};

CLI命令

| 命令 | 描述 | |------|------| | init | 初始化项目，安装Git Hooks并创建默认配置 | | lint | 全量代码校验 | | lint:fix | 自动修复代码问题 | | lint:staged | 仅校验暂存文件 | | commitlint <message> | 校验提交信息格式 | | status | 查看当前配置和服务状态 |

Git Hooks

pre-commit

执行lint-staged，对暂存文件进行ESLint校验与修复：

npx lint-staged

commit-msg

执行commitlint，校验提交信息格式：

npx commitlint --edit "$1"

项目结构

lint-tools-sdk/
├── src/
│   ├── index.js          # SDK主入口和CLI命令处理
│   ├── eslint.js         # ESLint服务实现
│   ├── commitlint.js     # commitlint服务实现
│   └── githooks.js       # Git Hooks服务实现
├── package.json
└── README.md

模块化架构

1. LintToolsSDK (主类)

整合所有服务，提供统一的API和CLI接口。

2. ESLintService

• 配置加载与管理
• 文件校验与修复
• 暂存文件处理

3. CommitLintService

• 提交信息校验
• 配置文件管理

4. GitHooksService

• husky钩子安装与管理
• 钩子脚本生成

技术栈

• Node.js：运行环境
• ESLint v9+：代码质量检查
• commitlint：提交信息规范
• husky：Git Hooks管理
• lint-staged：暂存文件处理

兼容性

• ESLint：^9.0.0
• husky：^8.0.0 || ^9.0.0
• lint-staged：^15.0.0 || ^16.0.0

项目构建与发布

1. 构建项目

# 安装依赖
npm install

# 验证代码（检查语法和类型错误）
npm run lint

# 运行测试（如有）
npm run test

2. 发布到npm

# 确保已登录npm
npm login

# 更新版本号（根据语义化版本规范）
npm version patch  # 修复bug，版本号第三位加1
npm version minor  # 新增功能，版本号第二位加1
npm version major  # 大版本更新，版本号第一位加1

# 发布到npm
npm publish

在其他项目中使用与验证

1. 安装SDK

# 从npm安装
npm install --save-dev lint-tools-sdk

# 或从本地开发版本安装
npm install --save-dev ../path/to/lint-tools-sdk

2. 初始化配置

npx lint-tools-sdk init

3. 验证功能

a) 代码校验

# 创建一个包含错误的测试文件
echo "const a = 1 console.log(a)" > test.js

# 执行代码校验，应该能检测到错误
npx lint-tools-sdk lint

# 尝试自动修复
npx lint-tools-sdk lint:fix

b) 提交信息校验

# 测试正确的提交信息（应该通过）
npx lint-tools-sdk commitlint "feat: add new feature"

# 测试错误的提交信息（应该失败）
npx lint-tools-sdk commitlint "add new feature"

c) Git Hooks验证

# 将测试文件添加到暂存区
git add test.js

# 尝试提交（应该触发pre-commit钩子）
git commit -m "fix: update test file"

贡献

欢迎提交Issue和Pull Request！

许可证

ISC

项目构建与发布

发布说明

该项目是一个Node.js SDK，主要包含JavaScript源代码，不需要使用webpack、rollup等工具进行打包。由于项目结构简单，直接发布源代码即可正常工作。

确保发布内容正确

通过以下配置确保只发布必要的文件：

1. .gitignore：排除node_modules、test-project等非必要文件
2. package.json的files字段：明确指定需要发布的文件和目录

发布步骤

1. 更新版本号：

   npm version patch  # 或 minor/major

2. 登录npm：

   npm login

3. 发布到npm：

   npm publish

4. （可选）发布前验证：

   # 查看将被发布的文件
   npm pack --dry-run
      
   # 或生成tgz包检查内容
   npm pack
   tar -tf lint-tools-sdk-*.tgz