icarys-code-quality

Icarys 前端项目共享代码质量包，内置 Lefthook、ESLint、Prettier 和 commitlint 配置。

目标是让业务项目只安装一个 npm 包，再运行一次初始化命令即可接入本地提交检查。

安装

只需安装，无需任何额外命令：

npm i -D icarys-code-quality

安装完成后会通过 postinstall 自动初始化，生成或更新：

• eslint.config.js
• .commitlintrc.cjs
• prettier.config.cjs
• sonar-project.properties
• lefthook.yml
• package.json scripts
• .gitignore 中的 eslint-report.json、coverage/
• vite/plugins/auto-import.js 中的 .eslintrc-auto-import.json 生成配置
• 自动执行 lefthook install 安装 Git 钩子（存在 .git 时）

如果项目已有同名配置文件，默认不会覆盖，安装过程也不会失败。

需要强制覆盖，或想手动重新初始化时，可运行：

npx icarys-code-quality init --force

如需在某些环境（例如 CI）跳过自动初始化，设置环境变量：

ICARYS_CODE_QUALITY_SKIP_POSTINSTALL=1 npm i

业务项目 scripts

初始化后业务项目会得到这些脚本：

{
    "lint": "icarys-eslint . --max-warnings 0",
    "lint:fix": "icarys-eslint . --fix",
    "lint:report": "icarys-eslint . -f json -o eslint-report.json || true",
    "format": "icarys-prettier --write \"src/**/*.{js,vue,css,scss}\"",
    "format:check": "icarys-prettier --check \"src/**/*.{js,vue,css,scss}\"",
    "prepare": "icarys-lefthook install"
}

提交检查

业务项目根目录的 lefthook.yml 只需要继承包内配置：

extends:
  - ./node_modules/icarys-code-quality/lefthook.yml

包内默认规则：

• pre-commit：只处理 staged 的 js/vue/css/scss/json/md 文件。
• pre-commit：ESLint 和 Prettier 自动修复后重新 stage。
• commit-msg：使用 Conventional Commits 校验提交信息。

合法提交示例：

feat: 新增门禁刷卡记录
fix: 修复工单详情加载异常

SonarQube / Jenkins 流水线

初始化会在业务项目根目录生成 sonar-project.properties，预置了源码目录、排除项，并通过 sonar.eslint.reportPaths 把 ESLint 报告并入 Sonar。

使用前需改一处：把 sonar.projectKey、sonar.projectName 的 CHANGE_ME 换成项目实际名称。

Sonar 服务器地址与 token 属于环境敏感信息，不写在文件里，由流水线传参。Jenkins 示例：

npm ci
npm run lint:report        # 生成 eslint-report.json 供 Sonar 读取
# npm run test -- --coverage   # 如有单测，生成 coverage/lcov.info
sonar-scanner \
  -Dsonar.host.url=http://your-sonar-server \
  -Dsonar.login=$SONAR_TOKEN

前提：流水线机器上已安装 sonar-scanner，且能访问到 SonarQube 服务器。建议在 SonarQube 侧配置 Quality Gate，由流水线依据门禁结果决定是否放行。

自定义规则

规则都集中在本包的 config/ 目录，改这里对所有业务项目生效：

• ESLint 规则：config/eslint.config.cjs（rules 字段）。
• Prettier 规则：config/prettier.config.cjs。
• commitlint 规则：config/commitlint.config.cjs。

业务项目里生成的 eslint.config.js、prettier.config.cjs、.commitlintrc.cjs 只是 require 上述共享文件，无需在业务项目里逐个配置。

Vite auto-import

Icarys 项目通常使用 unplugin-auto-import 自动导入 Vue API。初始化命令会尽量给 vite/plugins/auto-import.js 增加：

eslintrc: { enabled: true, filepath: './.eslintrc-auto-import.json' },

然后运行一次：

npm run build:prod

或者：

npm run dev

生成 .eslintrc-auto-import.json 后，ESLint 就不会把 ref、computed、useRouter 等自动导入变量误报为 no-undef。

发布到私有 npm 源

确认包内容：

npm pack --dry-run

发布：

npm publish --access restricted

如果公司私有源需要指定 registry，在项目 .npmrc 或命令中配置即可。