ice-lab/spec

:hatching_chick: easy to use eslint/stylelint/tslint/prettier/...

@iceworks/spec

Easy to use eslint(support TypeScript) / stylelint / prettier / commitlint in rax, ice and react project. And spec means specification.

Install

$ npm i --save-dev @iceworks/spec eslint stylelint prettier @commitlint/cli

PS: You don't need to install other eslint plugins and parsers.

Usage

ESLint

1. Create configuration file

First create a .eslintrc.js file. Then edit your config.

2. Update config

rules base on eslint-config-ali and @iceworks/eslint-plugin-best-practices.

// .eslintrc.js
const { getESLintConfig } = require('@iceworks/spec');

// getESLintConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?);
module.exports = getESLintConfig('react');

stylelint

1. Create configuration file

First create a .stylelintrc.js file. Then edit your config.

2. Update config

rules base on stylelint-config-ali

// .stylelintrc.js
const { getStylelintConfig } = require('@iceworks/spec');

// getStylelintConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?);
module.exports = getStylelintConfig('react');

prettier rules

1. Create configuration file

First create a .prettierrc.js file. Then edit your config.

2. Update config

// .prettierrc.js
const { getPrettierConfig } = require('@iceworks/spec');

// getPrettierConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?);
module.exports = getPrettierConfig('react');

commitlint

1. Create configuration file

First create a .commitlintrc.js file. Then edit your config.

2. Update config

rules base on commitlint-config-ali

// .commitlintrc.js
const { getCommitlintConfig } = require('@iceworks/spec');

// getCommitlintConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?);
module.exports = getCommitlintConfig('react');

FAQ

Custom config

// .eslintrc.js
const { getESLintConfig } = require('@iceworks/spec');

// getESLintConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?);
module.exports = getESLintConfig('rax', {
  // custom config it will merge into main config
  rules: {
    // ...
  },
});

package.json scripts

Add scripts in your package.json, example:

"scripts": {
  "lint": "npm run eslint && npm run stylelint",
  "eslint": "eslint --cache --ext .js,.jsx,.ts,.tsx ./",
  "stylelint": "stylelint ./**/*.scss",
  "prettier": "prettier **/* --write"
}

Then use npm run lint check your project, ues npm run prettier update your code.

Git hooks

To lint commits before they are created you can use Husky's Git hook.

Install in your project npm install husky --save-dev or yarn add -D husky.

After that, we recommend you to see husky docs, then create "commit-msg" and "pre-commit" config.

Update from @ice/spec

If you are using @ice/spec in your project, we recommend use @iceworks/spec to get better maintainability and faster response to lint rules support.

Based on @iceworks/spec's simple API you can quickly migrate your project, install and update your lint config file, the mission is completed 😁.

Develop

Run Test

npm run test

run test for specific component

npm run test -- packages/spec

Run Prettier

npm run prettier

Run Lint

npm run lint

spec's Issues

是否可以为spec提供d.ts

问题描述/Problem Description

是否可以为spec提供d.ts？getPrettierConfig之类的函数第二个参数都无法自动补全

建议的方案/Proposal

备选的方案/Alternatives

附加信息/Other Information

rule 规则讨论

在使用spec中 遇到了一些问题，有些规则想一起讨论下 是否要加到lint rule中。

我这边有一些自定义的

{
    // 数组空格风格
    'array-bracket-spacing': ['error', 'always', { 'objectsInArrays': false, 'arraysInArrays': false, 'singleValue': true }],
    // 对象空格风格
    'object-curly-spacing': ['error', 'always'],
    //  使用单引号，关闭转义
    quotes: ['error', 'single', { avoidEscape: true }],
    // jsx 使用双引号
    'jsx-quotes': ['error', 'prefer-double'],
    // 去除无用的constructor
    'no-useless-constructor': 'error',
    // 注释后有空格
    'spaced-comment': ['error', 'always', { 'markers': ['/'] }],
    //  逗号后有空格，前无空格
    'comma-spacing': ['error', { 'before': false, 'after': true }],
    // hook 依赖 提升到error级别，如果有特殊情况，可以 单独注释
    'react-hooks/exhaustive-deps': 'error',
    // 最后一行添加空行
    'eol-last': ['error', 'always'],
    // 函数空格风格
    'space-before-function-paren': ['error', {
      'anonymous': 'never',
      'named': 'never',
      'asyncArrow': 'always'
    }],
    'key-spacing': [ 'error', { afterColon: true }],
    // 去除无用的constructor
    '@typescript-eslint/no-useless-constructor': 'error',
    // react 支持tsx后缀
    'react/jsx-filename-extension': [
      'error',
      {
        extensions: ['.js', '.jsx', '.tsx'],
      },
    ]
}

peerDependencies 是否要加 stylelint

npm 关于 peerDependencies 的说明 https://docs.npmjs.com/cli/v7/configuring-npm/package-json#peerdependencies

当前的 spec 包的 peerDependencies：

 "peerDependencies": {
    "eslint": ">=6.8.0"
  }

问题

在 Iceworks VS Code 插件打包打包脚本中出现 peer dep missing stylelint 错误。

原因分析

VS Code 在构建插件时会运行 $npm list --production --parseable --depth=99999 --loglevel=error

npm 默认只检测 top level 的依赖，但指定 --depth=99999 时，会深层分析所有依赖，spec 子依赖 stylelint-config-ali 申明了
stylelint 的 peerDependencies，使用 spec 的 VS Code 插件依赖包未安装 stylelint 时会出现此错误。

现状

spec 包当前的使用场景：

• 脚手架新工程 （不会出错，依赖较全）
• 用户自己配置 spec 的配置，仅安装了 ESLint （不会出错，默认查 top level 的 peerDependencies，等级为 WARN）
• 普通使用依赖 spec npm 包（不会出错，同上）
• VS Code 使用依赖 spec npm 包（未安装 stylelint 时会出现上述错误）

解决方案

1. 维持现状

缺点：在 VS Code 插件使用依赖 spec npm 包需要注意依赖。
优点：除问题场景外其他用户无感

2. Iceworks 工程打包脚本指定使用 npm 7.x

根据 npm 文档自测 npm 会自行安装相关 peerDependencies
优点：所有上层设施均无感
缺点：需要回归测试下打包脚本

3. spec 包的 peerDependencies 加入 stylelint

优点：保证包的完善，符合直觉
缺点：对现状 2 ，只用了 ESLint 的用户造成影响，安装依赖会提示安装 stylelint

新增规则：样式单位写法

具体规则需要定下，比如不写单位的、用 rem 而不是 rpx 的

eslint 规则报错应该返回具体的错误位置

spec/packages/eslint-plugin-best-practices/src/rules/no-js-in-ts-project.js

Lines 36 to 51 in 7f8cb17

	context.report({
	loc: {
	start: {
	line: 0,
	column: 0,
	},
	end: {
	line: 0,
	column: 0,
	},
	},
	messageId: 'noJSInTSProject',
	data: {
	fileName,
	},
	});

[bug] deepmerge实现需要判断target是否有[key]属性

需要做下 target[key]的undefined判断， 没有的话，也走最后一个分支

stylelint 和 eslint 放在dependencies

stylelint-config-rational-order 的 stylelint的版本依赖偏低，导致stylelint报 Undefined rule unicode-bom

请教eslint和stylelint放在dependencies依赖中

@iceworks/eslint-plugin-best-practices 性能问题

包名: @iceworks/eslint-plugin-best-practices

您的本地环境信息/Your local environment information

• 操作系统及其版本/System and Version: MacOS
• Node version: v14.17.0
• 问题 npm 包 version: 0.2.7

您遇到的问题及复现步骤/What are your problems and how to reproduce them

这个包依赖了 @mdn/browser-compat-data@^2.0.3，这个版本的 @mdn/browser-compat-data 有比较严重的性能问题（包含了很多同步的 fs 调用），同时体积也比较大（22 MB），新版本 @mdn/[email protected] 发布前做了预打包处理，性能更好，而且体积只有 9.6MB

在 slow HDD 上的性能数据：

老版本：>4s
新版本：<1s

性能数据参考：Publish pre-build bundles to npm

您期待的正确结果/The right result you're looking forward to

升级至 @iceworks/eslint-plugin-best-practices 的依赖 @mdn/browser-compat-data 到 4.x 版本，解决性能问题，同时减少 npm install 时间

@fyangstudio

[RFC] 不再依赖各种最佳实践的插件

• 插件里的配置太黑盒，跟随升级有成本
• lint 规则应该是具体明确的

请升级项目依赖解决安装时警告产生

warning "@iceworks/spec > [email protected]" has incorrect peer dependency "stylelint@^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0".

现在安装时会导致以上警告产生，是否可以升级项目基础依赖至最新？

getESLintConfig 增加小程序类型的属性

目前 getESLintConfig 的入参仅跟框架语言有关，例如 rax, react, rax-ts 等。
当业务使用 rax 框架开发小程序时，需要检测小程序平台的 rule。
例如编译时语法需要满足 约束，对应的插件为：https://github.com/raxjs/miniapp/tree/master/packages/eslint-plugin-rax-compile-time-miniapp

目前有两个方案：

1. 在运行 spec 时，检测仓库中的 build.json，读取 targets 和 target 对应的 buildType，来自动加载对应插件；
2. 在初始化仓库时，根据类型，在仓库的 .eslintrc.js 中声明当前仓库的类型

方案一：与 rax 仓库的目录结构高耦合，若业务方的脚手架进行过封装可能会失效。
方案二：若仓库初始化完成后，用户修改了 targets 和 target 对应的 buildType，那么 .eslintrc.js 也需要修改配置。

Eslint默认的配置不考虑加入prettier的配置吗

$ yarn add eslint-plugin-prettier eslint-config-prettier -D

const { getESLintConfig } = require('@iceworks/spec');

module.exports = getESLintConfig('react-ts', {
  extends: ['plugin:prettier/recommended'],
});

这样可以检测到哪些代码的格式化是有问题的, 并在vsc报红, 并且可以通过eslint修复

脚手架去除 prettier ，统一使用 ESLint 进行格式化

背景

在最佳实践 spec 的 ESLint 配置中，我们已经集成了大量格式化规则。可以解决约 90% 的格式问题。

运行 ESLint 检测已成为 CI 及用户开发习惯中的一部分。

问题

脚手架工程同时集成 prettier 和 ESLint ，不但功能有重复，增加概念和配置，也会产生一定的使用和理解成本。

不断的迭代的 ESLint 和 prettier ，需要开发者不断解决 ESLint 和 prettier 的冲突问题，产生很大的维护成本。
（现阶段已解决，但存在隐患）

建议

秉承简单易用原则，建议脚手架工程主要推荐 ESLint 修复链路，淡化 prettier 。