eslint-config-hcl 0.0.3-alpha.0

package/LICENSE

@@ -0,0 +1 @@
+MIT

package/README.md

@@ -0,0 +1,219 @@
+# eslint-config-hcl
+
+> 基于 ESLint 9 扁平配置的基础通用 JavaScript、TypeScript、Vue 编码规范
+
+支持配套的 [eslint 可共享配置](https://www.npmjs.com/package/markdownlint#optionsconfig)。
+
+提供了多套配置文件以支持 `JavaScript`、`TypeScript`、`Vue` 等多种项目类型。
+
+## JavaScript 项目 - eslint-config-hcl
+
+针对未使用 `Vue` 的原生 `JavaScript` 项目，使用 `ESLint` 原生规则和 [eslint-plugin-import](https://www.npmjs.com/package/eslint-plugin-import) 规则，使用 [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) 作为 `parser`，是本包的默认配置。
+
+### 依赖
+
+- [@babel/core](https://www.npmjs.com/package/@babel/core)@^7.24.0
+- [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser)@^7.24.5
+- [eslint-plugin-import](https://www.npmjs.com/package/eslint-plugin-import)@^2.31.0
+
+### 安装
+
+```bash
+npm install @babel/core @babel/eslint-parser eslint-plugin-import --save-dev
+```
+
+安装本包：
+
+```bash
+npm install eslint-config-hcl --save-dev
+```
+
+### 配置
+
+配置文件 `eslint.config.js`，内容如下：
+
+```javascript
+// eslint.config.js
+import eslintConfigHcl from 'eslint-config-hcl';
+
+export default [
+  ...eslintConfigHcl,
+  // 你的自定义配置
+];
+```
+
+## JavaScript + Vue 项目 - eslint-config-hcl/vue
+
+针对 `JS Vue` 的项目，继承了默认配置，并启用了 [eslint-plugin-vue](https://www.npmjs.com/package/eslint-plugin-vue) 插件的规则，使用 [vue-eslint-parser](https://www.npmjs.com/package/vue-eslint-parser) 作为 parser。
+
+### 依赖
+
+- [@babel/core](https://www.npmjs.com/package/@babel/core)@^7.24.0
+- [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser)@^7.24.5
+- [eslint-plugin-import](https://www.npmjs.com/package/eslint-plugin-import)@^2.31.0
+- [vue-eslint-parser](https://www.npmjs.com/package/vue-eslint-parser)@^9.4.3
+- [eslint-plugin-vue](https://www.npmjs.com/package/eslint-plugin-vue)@^9.33.0
+
+### 安装
+
+```bash
+npm install @babel/core @babel/eslint-parser eslint-plugin-import vue-eslint-parser eslint-plugin-vue --save-dev
+```
+
+安装本包：
+
+```bash
+npm install eslint-config-hcl --save-dev
+```
+
+### 配置
+
+配置文件 `eslint.config.js`，内容如下：
+
+```javascript
+// eslint.config.js
+import eslintConfigHclVue from 'eslint-config-hcl/vue';
+
+export default [
+  ...eslintConfigHclVue,
+  // 你的自定义配置
+];
+```
+
+## TypeScript 项目 - eslint-config-hcl/typescript
+
+针对未使用 `Vue` 的 `TypeScript` 项目，继承了默认配置，并启用了 [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin) 插件的规则，使用 [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser) 作为 parser。
+
+### 依赖
+
+- [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser)@^8.5.0
+- [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin)@^8.5.0
+- [eslint-plugin-import](https://www.npmjs.com/package/eslint-plugin-import)@^2.31.0
+- [eslint-import-resolver-typescript](https://www.npmjs.com/package/eslint-import-resolver-typescript)@^4.0.0
+
+### 安装
+
+```bash
+npm install @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-import eslint-import-resolver-typescript --save-dev
+```
+
+安装本包：
+
+```bash
+npm install eslint-config-hcl --save-dev
+```
+
+### 配置
+
+配置文件 `eslint.config.js`，内容如下：
+
+```javascript
+// eslint.config.js
+import eslintConfigHclTS from 'eslint-config-hcl/typescript';
+
+export default [
+  ...eslintConfigHclTS,
+  // 你的自定义配置
+];
+```
+
+需保证项目已安装 `typescript` 依赖，另外如果项目的 `TS` 配置文件不是 `./tsconfig.json`，则需要设置 `languageOptions.parserOptions.project` 字段 ，例如：
+
+```javascript
+// eslint.config.js
+import eslintConfigHclTS from 'eslint-config-hcl/typescript';
+
+export default [
+  ...eslintConfigHclTS,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.eslint.json',
+      },
+    },
+  },
+];
+```
+
+## TypeScript + Vue 项目 - eslint-config-hcl/typescript/vue
+
+针对 `TS Vue` 项目，继承了 `JS Vue` 的配置，并启用了 [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin) 插件的规则，使用 [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser) 作为 `parser`。
+
+### 依赖
+
+- [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser)@^8.5.0
+- [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin)@^8.5.0
+- [eslint-plugin-import](https://www.npmjs.com/package/eslint-plugin-import)@^2.31.0
+- [eslint-import-resolver-typescript](https://www.npmjs.com/package/eslint-import-resolver-typescript)@^4.0.0
+- [vue-eslint-parser](https://www.npmjs.com/package/vue-eslint-parser)@^9.4.3
+- [eslint-plugin-vue](https://www.npmjs.com/package/eslint-plugin-vue)@^9.33.0
+
+### 安装
+
+```bash
+npm install @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-import eslint-import-resolver-typescript vue-eslint-parser eslint-plugin-vue --save-dev
+```
+
+安装本包：
+
+```bash
+npm install eslint-config-hcl --save-dev
+```
+
+### 配置
+
+配置文件 `eslint.config.js`，内容如下：
+
+```javascript
+// eslint.config.js
+import eslintConfigHclTSVue from 'eslint-config-hcl/typescript/vue';
+
+export default [
+  ...eslintConfigHclTSVue,
+  // 你的自定义配置
+];
+```
+
+## 配合 Prettier 使用
+
+如果你的项目使用 [Prettier](https://prettier.io/) 进行代码格式化，本包的一些规则可能会跟 Prettier 格式化结果有冲突，[例如这条规则](https://github.com/typescript-eslint/typescript-eslint/issues/372)。为了避免冲突，你需要手动安装 [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier)：
+
+### 安装
+
+```bash
+npm install eslint-config-prettier --save-dev
+```
+
+### 配置
+
+并修改 `eslint.config.js`，在配置数组中增加 `prettier` 配置（需放在最后，以覆盖冲突规则）：
+
+```javascript
+// eslint.config.js
+import eslintConfigHclTSVue from 'eslint-config-hcl/typescript/vue';
+
+export default [
+  ...eslintConfigHclTSVue,
+  // 放在最后，以覆盖冲突规则
+  'prettier',
+  // 你的自定义配置
+];
+```
+
+了解更多请阅读 [Prettier - Integrating with Linters](https://prettier.io/docs/en/integrating-with-linters.html)。
+
+## 将风格问题降级
+
+为了保证一致的编码风格，本包中大量风格相关的规则被设为了 `error` 级别，以引起开发者的足够重视。如果你觉得风格问题不足以是 `error` 级别（有些用户根据 ESLint error 进行流程卡点），本包还提供了一套名为 'essential' 的配置文件，这套配置将所有风格问题降级为 `warn` 级别，仅将必要问题报告为 `error`，引用方式为在相应配置的 `eslint-config` 后面加上 `/essential`，如对 `JS Vue` 项目为 `eslint-config/essential/Vue`、对 `TS Vue` 项目为 `eslint-config/essential/typescript/vue`
+
+## 了解更多
+
+- 如果你对 ESLint 还不熟悉，可以阅读官网的 [Getting Started](https://eslint.org/docs/user-guide/getting-started) 快速入门。
+- 了解如何为 IDE 配置 ESLint，可以参考官网的 [Integrations](http://eslint.org/docs/user-guide/integrations)。
+- 了解如何在继承本包的基础上对项目 ESLint 进行个性化配置，可参考官网的 [Configuring ESLint](https://eslint.org/docs/user-guide/configuring)。下面简介下 ESLint 配置中的几个常用字段：
+  - `extends`: 继承一组规则集。`"extends": "eslint-config",` 表示继承本包定义的规则配置。
+  - `rules`: 配置规则，这里定义的规则会覆盖 `extends` 的规则。如果觉得本包开启的某条规则过于严格，你可以暂时在这里将其关闭。
+  - `parser`: 设置 ESLint 的解析器。ESLint 使用 Espree 作为默认的解析器，可以通过这个参数指定其他的解析器。比如指定为 [@babel/eslint-parser](https://npmjs.com/package/@babel/eslint-parser)，以解析 Babel 支持但 ESLint 默认解析器不支持的语法（本包不同配置文件使用的解析器可在简介表格中的「依赖 parser」一列查看）。
+  - `globals`: 指定代码中可能用到的全局变量，以免全局变量被 [no-undef](http://eslint.org/docs/rules/no-undef) 规则报错。
+  - `env`: 指定代码的运行环境，每个环境预定义了一组对应的全局变量，本包已开启的环境有 browser、node、jquery、es6 及几个测试框架的环境。
+- 了解常用的 ESLint 命令，如 `--fix`、`--ext`，可参考官网的 [Command Line Interface](http://eslint.org/docs/user-guide/command-line-interface)。

package/essential/es5.js

@@ -0,0 +1,15 @@
+import es5Config from '../es5.js';
+import setStyleToWarn from './rules/set-style-to-warn.js';
+import blacklist from './rules/blacklist.js';
+
+export default [
+  ...es5Config,
+  setStyleToWarn,
+  blacklist,
+  {
+    files: ['**/*.js'],
+    rules: {
+      'comma-dangle': ['warn', 'never'],
+    },
+  },
+];

package/essential/index.js

@@ -0,0 +1,11 @@
+import baseConfig from '../index.js';
+import setStyleToWarn from './rules/set-style-to-warn.js';
+import blacklist from './rules/blacklist.js';
+import es6Blacklist from './rules/es6-blacklist.js';
+
+export default [
+  ...baseConfig,
+  setStyleToWarn,
+  blacklist,
+  es6Blacklist,
+];

package/essential/rules/blacklist.js

@@ -0,0 +1,48 @@
+export default {
+  rules: {
+    // 统一在点号之前换行
+    // @unessential
+    'dot-location': ['warn', 'property'],
+
+    // 禁止使用 eval
+    // @unessential 部分场景必须使用 eval
+    'no-eval': 'warn',
+
+    // 禁止使用类 eval 的方法，如 setTimeout 传入字符串
+    // @unessential
+    'no-implied-eval': 'warn',
+
+    // 禁止使用 javascript:url，如 location.href = 'javascript:void(0)';
+    // @unessential
+    'no-script-url': 'warn',
+
+    // 禁止变量与外层作用域已存在的变量同名
+    // @unessential
+    'no-shadow': 'warn',
+
+    // 禁止出现多个连续空格
+    // @unessential
+    'no-multi-spaces': [
+      'warn',
+      {
+        ignoreEOLComments: false,
+      },
+    ],
+
+    // 使用 2 个空格缩进
+    // @unessential
+    indent: 'off',
+
+    // 使用分号
+    // @unessential
+    semi: 'off',
+
+    // 分号必须写在行尾
+    // @unessential
+    'semi-style': 'off',
+
+    // 不要直接在对象上调用 Object.prototypes 上的方法
+    // @unessential
+    'no-prototype-builtins': 'warn',
+  },
+};

package/essential/rules/es6-blacklist.js

@@ -0,0 +1,62 @@
+export default {
+  rules: {
+    // 箭头函数的箭头前后各留一个空格
+    // @unessential
+    'arrow-spacing': ['warn', { before: true, after: true }],
+
+    // generator 函数的 * 号前面无空格，后面有一个空格
+    // @unessential
+    'generator-star-spacing': ['warn', { before: false, after: true }],
+
+    // 避免箭头函数与比较操作符产生混淆
+    // @unessential
+    'no-confusing-arrow': 'warn',
+
+    // 回调函数使用箭头函数而不是匿名函数
+    // @unessential
+    'prefer-arrow-callback': [
+      'warn',
+      {
+        allowNamedFunctions: false,
+        allowUnboundThis: true,
+      },
+    ],
+
+    // 优先使用 const，只有当变量会被重新赋值时才使用 let
+    // @unessential
+    'prefer-const': [
+      'warn',
+      {
+        destructuring: 'any',
+        ignoreReadBeforeAssign: true,
+      },
+    ],
+
+    // 模板字符串中的大括号内部两侧无空格
+    // @unessential
+    'template-curly-spacing': 'warn',
+
+    // yield* 表达式的 * 号前面无空格，后面有一个空格
+    // @unessential
+    'yield-star-spacing': ['warn', 'after'],
+
+    // import 语句需要放到模块的最上方
+    // @unessential
+    'import/first': 'warn',
+
+    // 使用对象属性和方法的简写语法
+    // @unessential
+    'object-shorthand': [
+      'warn',
+      'always',
+      {
+        ignoreConstructors: false,
+        avoidQuotes: true,
+      },
+    ],
+
+    // 使用 const 或 let 声明变量，不要使用 var
+    // @unessential
+    'no-var': 'warn',
+  },
+};

package/essential/rules/set-style-to-warn.js

@@ -0,0 +1,26 @@
+/**
+ * 将 error 级别的 style 规则降级为 warn
+ */
+import styleRules from '../../rules/base/style.js';
+
+// 将传入 config 中 error 级别规则都改为 warn 级别
+function setErrorRulesToWarn(config) {
+  const rules = { ...config.rules };
+
+  for (const ruleName in rules) {
+    if (Object.prototype.hasOwnProperty.call(rules, ruleName)) {
+      const ruleValue = rules[ruleName];
+      if (Array.isArray(ruleValue)) {
+        if (ruleValue[0] === 'error') {
+          rules[ruleName] = ['warn', ...ruleValue.slice(1)];
+        }
+      } else if (ruleValue === 'error') {
+        rules[ruleName] = 'warn';
+      }
+    }
+  }
+
+  return { rules };
+}
+
+export default setErrorRulesToWarn(styleRules);

package/essential/rules/ts-blacklist.js

@@ -0,0 +1,15 @@
+export default {
+  rules: {
+    // 使用 2 个空格缩进
+    // @unessential
+    '@typescript-eslint/indent': 'off',
+
+    // 使用分号
+    // @unessential
+    '@typescript-eslint/semi': 'off',
+
+    '@typescript-eslint/adjacent-overload-signatures': 'warn',
+
+    '@typescript-eslint/parameter-properties': 'warn',
+  },
+};

package/essential/typescript/index.js

@@ -0,0 +1,28 @@
+import essentialConfig from '../index.js';
+import tsRules from '../../rules/typescript.js';
+import tsBlacklist from '../rules/ts-blacklist.js';
+// // 显式导入并注册 @typescript-eslint
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import importPlugin from 'eslint-plugin-import';
+
+export default [
+  ...essentialConfig,
+  {
+    files: ['**/*.{ts}'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: './tsconfig.json',
+        createDefaultProgram: true,
+        extraFileExtensions: ['.vue'],
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      import: importPlugin,
+    },
+    ...tsRules,
+  },
+  tsBlacklist,
+];

package/essential/typescript/vue.js

@@ -0,0 +1,28 @@
+import tsEssentialConfig from './index.js';
+import vueRules from '../../rules/vue.js';
+
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import vuePlugin from 'eslint-plugin-vue';
+
+export default [
+  ...tsEssentialConfig,
+  {
+    files: ['**/*.vue'],
+    languageOptions: {
+      parser: vuePlugin.parser,
+      parserOptions: {
+        parser: tsParser,
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        project: './tsconfig.json',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'vue': vuePlugin,
+    },
+    // vue 要置于最后，因为里面用了 vue-parser 插件，需要在 ts 规则之后执行
+    ...vueRules,
+  },
+];

package/essential/vue.js

@@ -0,0 +1,11 @@
+import vueConfig from '../vue.js';
+import setStyleToWarn from './rules/set-style-to-warn.js';
+import blacklist from './rules/blacklist.js';
+import es6Blacklist from './rules/es6-blacklist.js';
+
+export default [
+  ...vueConfig,
+  setStyleToWarn,
+  blacklist,
+  es6Blacklist,
+];

package/index.js

@@ -0,0 +1,58 @@
+import babelParser from '@babel/eslint-parser';
+import importPlugin from 'eslint-plugin-import';
+
+import bestPracticesRules from './rules/base/best-practices.js';
+import possibleErrorsRules from './rules/base/possible-errors.js';
+import styleRules from './rules/base/style.js';
+import variablesRules from './rules/base/variables.js';
+import es6Rules from './rules/base/es6.js';
+import strictRules from './rules/base/strict.js';
+import importsRules from './rules/imports.js';
+
+export default [
+  {
+    languageOptions: {
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        ecmaFeatures: {
+          globalReturn: false,
+          impliedStrict: true,
+        },
+      },
+    },
+    plugins: {
+      import: importPlugin,
+    },
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...bestPracticesRules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...possibleErrorsRules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...styleRules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...variablesRules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...es6Rules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...strictRules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    ...importsRules,
+  },
+];

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "eslint-config-hcl",
+  "version": "0.0.3-alpha.0",
+  "type": "module",
+  "description": "基于 ESLint 9 扁平配置的基础通用 JavaScript、TypeScript、Vue 编码规范",
+  "license": "ISC",
+  "author": "hechenglong <1104907547@qq.com>",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./typescript": "./typescript/index.js",
+    "./typescript/vue": "./typescript/vue.js",
+    "./vue": "./vue.js",
+    "./es5": "./essential/es5.js",
+    "./essential": "./essential/index.js",
+    "./essential/vue": "./essential/vue.js",
+    "./essential/typescript": "./essential/typescript/index.js",
+    "./essential/typescript/vue": "./essential/typescript/vue.js"
+  },
+  "files": [
+    "index.js",
+    "typescript/",
+    "vue.js",
+    "essential/",
+    "rules/"
+  ],
+  "keywords": [
+    "eslint",
+    "javascript",
+    "typescript",
+    "vue",
+    "lint"
+  ],
+  "scripts": {
+    "lint": "eslint ./",
+    "test": "mocha ./__tests__/*.test.js --timeout 5000",
+    "print-config": "eslint --print-config ./index.js > ./print-config.json"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "homepage": "https://github.com/15272410401/front-end-coding-specification#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/15272410401/front-end-coding-specification.git"
+  },
+  "bugs": {
+    "url": "https://github.com/15272410401/front-end-coding-specification/issues"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/eslint-parser": "^7.24.5",
+    "@typescript-eslint/eslint-plugin": "^8.5.0",
+    "@typescript-eslint/parser": "^8.5.0",
+    "eslint": "^9.39.5",
+    "eslint-import-resolver-typescript": "^4.0.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-vue": "^9.33.0",
+    "mocha": "^11.7.6",
+    "typescript": "^6.0.3",
+    "vue-eslint-parser": "^9.4.3"
+  },
+  "gitHead": "2cf5f56362c04886dc8f937985cabd5794615f4d"
+}