README
本包已迁移至 f2elint,欢迎使用 :)
xima 是《集团前端规约》的配套工具,可以为工程一键接入规约、一键扫描和修复规约问题,保障工程的编码规范和代码质量。
背景
为了《集团前端规约》的落地,我们引入多个开源工具和规则包来实现不同的规约,包括:
规约 | 工具 | 规则包 |
---|---|---|
《JavaScript 编码规约》 《TypeScript 编码规约》 《React 编码规约》 《Vue 编码规约》 |
ESLint | eslint-config-ali |
《CSS 编码规约》 | stylelint | stylelint-config-ali |
《Git commit message 规约》 | commitlint | commitlint-config-ali |
可以看到这些工具和规则包比较零散,工程的接入和后续升级都需要一定成本。
xima
屏蔽收敛了这些依赖和配置细节,提供简单的 CLI 和 Node.js API,让工程能够一键接入、一键扫描、一键修复、一键升级,并为工程配置 git commit 卡点,降低工程实施规约的成本。
CLI 使用
安装
在终端执行:
npm install xima -g
安装完成后,可执行 xima -h
以验证安装成功
功能
:一键接入 xima init
在工程根目录执行 xima init
,即可将工程一键接入规约体系,为工程安装开发阶段进行规约问题检查所需的依赖和配置,具体会做以下事情:
- 安装各种依赖:如工具依赖,包括 ESLint、stylelint、commitlint 等;配置依赖,包括 eslint-config-ali、stylelint-config-ali、@commitlint/config-ali 等
- 写入各种配置文件(到工程根目录):包括 .eslintrc.js、.eslintignore、.stylelintrc.js、.stylelintignore、commitlint.config.js、.prettierrc.js、.editorconfig、.vscode/settings.json 等;此外还会写入一个 xima.config.js 文件,包含 xima 工具的一些配置,如启用的功能、黑名单等
- 配置 git commit 卡点:使用 husky + lint-staged 设置代码提交卡点,在 git commit 时会运行
xima scan
,若有规约问题则阻止提交
注 1. 如果项目已经安装和配置过 ESLint、stylelint,执行
xima init
将会提示存在冲突的依赖和配置,并在你确认后进行覆盖
注 2. 如果项目里 .vscode/ 目录被 .gitignore 忽略,可以在拉取项目后单独执行
xima init --vscode
命令写入 .vscode/settings.json 配置文件(若存在原配置,将进行合并)
:一键扫描 xima scan
在工程的根目录执行命令,即可扫描工程的代码规约问题:
支持下列参数:
-q
--quiet
仅报告 error 级别的问题-o
--output-report
输出扫描出的规约问题日志-i
--include <dirpath>
指定要进行规约扫描的目录
:一键修复 xima fix
在工程的根目录执行命令,即可自动修复工程的代码规约问题:
注意请 review 下修复前后的代码,以免工具误修的情况。
Node.js API 使用
安装
npm install xima --save
API
init:初始化
- xima.init(config):将工程一键接入规约体系,效果等同于 xima init
示例:
await xima.init({
eslintType: 'react',
enableStylelint: true,
});
config参数如下:
参数 | 说明 | 可选值 | 备注 |
---|---|---|---|
eslintType | 初始的语言和框架类型 | ESLintType | 如果不配置,等同于xima init,控制台会出现选择器,如果配置,控制台就不会出现选择器 |
enableStylelint | 是否启用 stylelint | boolean | 同上 |
ESLintType
- default: JavaScript 项目(未使用 React 和 Vue 的 JS 项目)
- react: JavaScript + React 项目
- vue: JavaScript + Vue 项目
- typescript/default: TypeScript 项目(未使用 React 和 Vue 的 TS 项目)
- typescript/react: TypeScript + React 项目
- typescript/vue: TypeScript + Vue 项目
- es5: ES5 及之前版本的 JavaScript 老项目
scan:扫描
- xima.scan(config): 扫描当前工程代码,效果等同 xima scan
示例:
await xima.scan({
cwd: path.resolve(__dirname, '../fe'),
include: '.',
quiet: false,
outputReport: false,
});
参数 | 说明 | 可选值 | 备注 |
---|---|---|---|
cwd | 工程绝对路径 | string | - |
include | 指定要进行规约扫描的目录 | string | - |
quiet | 仅报告错误信息 | boolean | 默认: false |
outputReport | 输出扫描出的规约问题日志 | boolean | 默认: false |
配置
xima 基于一份配置进行扫描,包括仓库类型、忽略目录等。但你也可以零配置使用,无配置时 xima 会嗅探仓库的情况使用一份默认配置。
使用 CLI 时,xima 会读取执行目录下的 xima.config.js
文件作为配置,执行 xima init
会在工程根目录下新增如下的 xima.config.js
文件:
module.exports = {
enableStylelint: true
};