@polyv/eslint-config 0.8.0 → 1.0.0

package/package.json

@@ -1,35 +1,67 @@
 {
   "name": "@polyv/eslint-config",
-  "version": "0.8.0",
-  "description": "Standard ESLint configuration for Polyv projects.",
-  "keywords": [
-    "polyv",
-    "eslint",
-    "config"
-  ],
-  "homepage": "https://www.polyv.net/",
+  "version": "1.0.0",
+  "description": "ESLint 10 flat config for Polyv Mini Program import checks.",
+  "type": "module",
   "license": "MIT",
   "engines": {
-    "node": "^20.10.0"
+    "node": ">=20.10.0"
   },
-  "dependencies": {
-    "@babel/core": "^7.24.9",
-    "@babel/eslint-parser": "^7.24.8",
-    "@typescript-eslint/eslint-plugin": "^7.16.1",
-    "@typescript-eslint/parser": "^7.16.1",
-    "@vue/eslint-config-standard": "^8.0.1",
-    "eslint": "^8.57.0",
-    "eslint-config-standard": "^17.1.0",
-    "eslint-import-resolver-typescript": "^3.6.1",
-    "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-n": "^16.6.2",
-    "eslint-plugin-promise": "^6.6.0",
-    "eslint-plugin-sonarjs": "^0.25.1",
-    "eslint-plugin-vue": "^9.27.0",
-    "typescript": "^5.5.3",
-    "vue-eslint-parser": "^9.4.3"
+  "exports": {
+    ".": "./index.mjs",
+    "./plugin": "./plugin.mjs",
+    "./prettier-config": "./prettier-config.mjs",
+    "./configs/common": "./configs/common/index.mjs",
+    "./configs/importx": "./configs/importx/index.mjs",
+    "./configs/js": "./configs/js/index.mjs",
+    "./configs/miniprogram": "./configs/miniprogram/index.mjs",
+    "./configs/prettier": "./configs/prettier/index.mjs",
+    "./configs/sonarjs": "./configs/sonarjs/index.mjs",
+    "./configs/ts": "./configs/ts/index.mjs",
+    "./configs/vue2": "./configs/vue2/index.mjs",
+    "./rules/explicit-module-boundary-types": "./rules/explicit-module-boundary-types/index.mjs",
+    "./rules/no-relative-directory-index-imports": "./rules/no-relative-directory-index-imports/index.mjs",
+    "./rules/no-vue-component-variable-name-conflict": "./rules/no-vue-component-variable-name-conflict/index.mjs"
   },
+  "files": [
+    "configs",
+    "rules",
+    "index.mjs",
+    "plugin.mjs",
+    "prettier-config.mjs",
+    "utils.mjs",
+    "README.md"
+  ],
   "scripts": {
-    "print-config": "eslint --print-config ./lib/for-vue.js > config.txt"
+    "lint": "eslint .",
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "eslint": "^10.0.0",
+    "typescript": ">=4.8.4 <6.1.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-node": "^0.3.9",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-sonarjs": "^4.0.3",
+    "eslint-plugin-vue": "^10.9.2",
+    "globals": "^17.6.0",
+    "typescript-eslint": "^8.61.0",
+    "vue-eslint-parser": "^10.4.1"
+  },
+  "devDependencies": {
+    "eslint": "^10.5.0",
+    "typescript": "^5.8.3"
   }
 }

package/plugin.mjs

@@ -0,0 +1,17 @@
+import explicitModuleBoundaryTypes from './rules/explicit-module-boundary-types/index.mjs';
+import noRelativeDirectoryIndexImports from './rules/no-relative-directory-index-imports/index.mjs';
+import noVueComponentVariableNameConflict from './rules/no-vue-component-variable-name-conflict/index.mjs';
+
+const plugin = {
+  meta: {
+    name: '@polyv/eslint-config'
+  },
+  rules: {
+    'explicit-module-boundary-types': explicitModuleBoundaryTypes,
+    'no-relative-directory-index-imports': noRelativeDirectoryIndexImports,
+    'no-vue-component-variable-name-conflict': noVueComponentVariableNameConflict
+  }
+};
+
+export const rules = plugin.rules;
+export default plugin;

package/prettier-config.mjs

@@ -0,0 +1,15 @@
+/** @type {import('prettier').Config} */
+const prettierConfig = {
+  useTabs: false,
+  printWidth: 120,
+  tabWidth: 2,
+  singleQuote: true,
+  semi: true,
+  trailingComma: 'all',
+  bracketSameLine: false,
+  arrowParens: 'avoid',
+  quoteProps: 'as-needed',
+  singleAttributePerLine: true
+};
+
+export default prettierConfig;

package/rules/explicit-module-boundary-types/README.md

@@ -0,0 +1,126 @@
+# explicit-module-boundary-types
+
+`polyv/explicit-module-boundary-types` 基于 `@typescript-eslint/explicit-module-boundary-types` 封装，用于要求导出函数显式声明模块边界类型，同时允许指定函数或方法省略返回类型。
+
+## 适用场景
+
+Hook 函数经常返回组合对象、响应式引用或多个工具方法。强制写返回类型容易让声明变得冗长，并且可能削弱 TypeScript 对组合返回值的推导体验。
+
+该规则只放开匹配函数或方法的返回类型要求，不会放开参数类型要求，也不会放开未匹配函数的返回类型要求。
+
+## 使用方式
+
+如果已经组合 `polyv.configs.common`，`polyv` plugin 会自动注册：
+
+```javascript
+// eslint.config.mjs
+import polyv from '@polyv/eslint-config';
+
+export default [
+  ...polyv.configs.common,
+  {
+    rules: {
+      'polyv/explicit-module-boundary-types': ['error', {
+        allowHookReturnTypeInference: true,
+        allowedReturnTypeInferencePatterns: [
+          '^[A-Za-z_$][\\w$]*(?:Props?|Emits?)$'
+        ]
+      }]
+    }
+  }
+];
+```
+
+TypeScript 项目通常直接使用 `polyv.configs.ts`：
+
+```javascript
+// eslint.config.mjs
+import polyv from '@polyv/eslint-config';
+
+export default [
+  ...polyv.configs.common,
+  ...polyv.configs.ts
+];
+```
+
+## 错误示例
+
+```typescript
+// bad.ts
+export function createService() {
+  return { value: 1 };
+}
+```
+
+## 正确示例
+
+```typescript
+// good.ts
+export function createService(): { value: number } {
+  return { value: 1 };
+}
+
+export function useDemo() {
+  return { value: 1 };
+}
+```
+
+## 返回类型推导
+
+当 `allowHookReturnTypeInference` 为 `true` 时，函数名符合 `useXxx` 会被视为 hook 函数并允许省略返回类型，例如：
+
+- `useDemo`
+- `useUserInfo`
+- `use2dCanvas`
+
+也可以通过 `allowedReturnTypeInferencePatterns` 配置允许省略返回类型的函数或方法名正则，例如：
+
+```javascript
+// eslint.config.mjs
+{
+  rules: {
+    'polyv/explicit-module-boundary-types': ['error', {
+      allowedReturnTypeInferencePatterns: [
+        '^[A-Za-z_$][\\w$]*(?:Props?|Emits?)$'
+      ]
+    }]
+  }
+}
+```
+
+场景配置也可以通过 settings 注入同名配置；settings 会和规则 options 合并：
+
+```javascript
+// eslint.config.mjs
+{
+  settings: {
+    'polyv/explicit-module-boundary-types': {
+      allowedReturnTypeInferencePatterns: [
+        '^[A-Za-z_$][\\w$]*(?:Props?|Emits?)$'
+      ]
+    }
+  }
+}
+```
+
+该规则不会根据文件路径放开整个文件，因此 `hooks/` 目录里的普通导出函数仍然需要声明返回类型。
+
+## 规则选项
+
+该规则继承 `@typescript-eslint/explicit-module-boundary-types` 的原有选项，并额外支持：
+
+- `allowHookReturnTypeInference`：是否允许 `useXxx` hook 函数省略模块边界返回类型，默认值为 `false`。
+- `allowedReturnTypeInferencePatterns`：允许省略模块边界返回类型的函数或方法名正则列表，默认值为 `[]`。
+
+## Settings
+
+该规则会读取 `settings['polyv/explicit-module-boundary-types']`，目前支持：
+
+- `allowHookReturnTypeInference`
+- `allowedReturnTypeInferencePatterns`
+
+当 settings 和规则 options 都配置了 `allowedReturnTypeInferencePatterns` 时，两者会合并生效。
+
+## 自动修复
+
+该规则不提供自动修复。返回类型需要根据实际 API 边界手动补充。

package/rules/explicit-module-boundary-types/index.mjs

@@ -0,0 +1,171 @@
+import tseslint from 'typescript-eslint';
+
+const baseRule = tseslint.plugin.rules['explicit-module-boundary-types'];
+const baseOptionsSchema = baseRule.meta.schema[0];
+const settingsKey = 'polyv/explicit-module-boundary-types';
+
+function getKeyName(key) {
+  if (!key) {
+    return null;
+  }
+
+  if (key.type === 'Identifier') {
+    return key.name;
+  }
+
+  if (key.type === 'Literal' && typeof key.value === 'string') {
+    return key.value;
+  }
+
+  return null;
+}
+
+function getFunctionName(node) {
+  if (node.id?.type === 'Identifier') {
+    return node.id.name;
+  }
+
+  const parent = node.parent;
+  if (!parent) {
+    return null;
+  }
+
+  if (parent.type === 'VariableDeclarator' && parent.id.type === 'Identifier') {
+    return parent.id.name;
+  }
+
+  if (
+    parent.type === 'MethodDefinition' ||
+    parent.type === 'Property' ||
+    parent.type === 'PropertyDefinition' ||
+    parent.type === 'AccessorProperty' ||
+    parent.type === 'TSAbstractMethodDefinition'
+  ) {
+    return getKeyName(parent.key);
+  }
+
+  return null;
+}
+
+function isHookName(name) {
+  return /^use[A-Z0-9]/.test(name);
+}
+
+function createAllowedReturnTypeInferencePatterns(patterns = []) {
+  return patterns.map((pattern) => new RegExp(pattern));
+}
+
+function getAllowedReturnTypeInferencePatterns(...patternGroups) {
+  return patternGroups.flatMap((patterns) => (
+    Array.isArray(patterns)
+      ? patterns.filter((pattern) => typeof pattern === 'string')
+      : []
+  ));
+}
+
+function getRuleSettings(context) {
+  const settings = context.settings?.[settingsKey];
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    return {};
+  }
+
+  return settings;
+}
+
+function isAllowedReturnTypeInferenceName(name, patterns) {
+  return patterns.some((pattern) => pattern.test(name));
+}
+
+function shouldIgnoreMissingReturnType(descriptor, options) {
+  if (descriptor?.messageId !== 'missingReturnType') {
+    return false;
+  }
+
+  const functionName = getFunctionName(descriptor.node);
+  if (!functionName) {
+    return false;
+  }
+
+  return (
+    (options.allowHookReturnTypeInference && isHookName(functionName)) ||
+    isAllowedReturnTypeInferenceName(functionName, options.allowedReturnTypeInferencePatterns)
+  );
+}
+
+function createBaseContext(context, baseOptions, options) {
+  const baseContext = Object.create(context);
+
+  Object.defineProperties(baseContext, {
+    options: {
+      value: [baseOptions]
+    },
+    report: {
+      value(descriptor, ...args) {
+        if (args.length === 0 && shouldIgnoreMissingReturnType(descriptor, options)) {
+          return;
+        }
+
+        return context.report(descriptor, ...args);
+      }
+    }
+  });
+
+  return baseContext;
+}
+
+export default {
+  ...baseRule,
+  meta: {
+    ...baseRule.meta,
+    docs: {
+      ...baseRule.meta.docs,
+      description: '要求导出函数显式声明模块边界类型，并允许指定函数或方法省略返回类型'
+    },
+    schema: [{
+      ...baseOptionsSchema,
+      properties: {
+        ...baseOptionsSchema.properties,
+        allowHookReturnTypeInference: {
+          type: 'boolean',
+          description: '是否允许 useXxx hook 函数省略模块边界返回类型。'
+        },
+        allowedReturnTypeInferencePatterns: {
+          type: 'array',
+          description: '允许省略模块边界返回类型的函数或方法名正则列表。',
+          items: {
+            type: 'string'
+          }
+        }
+      }
+    }]
+  },
+  defaultOptions: [{
+    ...baseRule.defaultOptions[0],
+    allowHookReturnTypeInference: false,
+    allowedReturnTypeInferencePatterns: []
+  }],
+  create(context) {
+    const settings = getRuleSettings(context);
+    const ruleOptions = context.options[0] ?? {};
+    const options = {
+      ...baseRule.defaultOptions[0],
+      allowHookReturnTypeInference: false,
+      ...settings,
+      ...ruleOptions,
+      allowedReturnTypeInferencePatterns: getAllowedReturnTypeInferencePatterns(
+        settings.allowedReturnTypeInferencePatterns,
+        ruleOptions.allowedReturnTypeInferencePatterns
+      )
+    };
+    const {
+      allowHookReturnTypeInference,
+      allowedReturnTypeInferencePatterns,
+      ...baseOptions
+    } = options;
+
+    return baseRule.create(createBaseContext(context, baseOptions, {
+      allowHookReturnTypeInference,
+      allowedReturnTypeInferencePatterns: createAllowedReturnTypeInferencePatterns(allowedReturnTypeInferencePatterns)
+    }));
+  }
+};

package/rules/no-relative-directory-index-imports/README.md

@@ -0,0 +1,87 @@
+# no-relative-directory-index-imports
+
+`polyv/no-relative-directory-index-imports` 用于禁止依赖相对目录的 `index` 文件兜底解析。
+
+## 适用场景
+
+微信小程序 npm 构建后，不保证把相对目录路径自动解析到该目录下的 `index` 文件。业务代码如果写成 `./helper`、`.`、`..` 这类目录入口，构建后可能出现运行时路径解析失败。
+
+## 使用方式
+
+如果已经组合 `polyv.configs.common`，`polyv` plugin 会自动注册：
+
+```javascript
+// eslint.config.mjs
+import polyv from '@polyv/eslint-config';
+
+export default [
+  ...polyv.configs.common,
+  {
+    rules: {
+      'polyv/no-relative-directory-index-imports': 'error'
+    }
+  }
+];
+```
+
+小程序项目通常直接使用 `polyv.configs.miniprogram`：
+
+```javascript
+// eslint.config.mjs
+import polyv from '@polyv/eslint-config';
+
+export default [
+  ...polyv.configs.common,
+  ...polyv.configs.miniprogram
+];
+```
+
+## 错误示例
+
+```javascript
+// bad.js
+import helper from './helper';
+import current from '.';
+import parent from '..';
+const utils = require('./utils');
+```
+
+## 正确示例
+
+```javascript
+// good.js
+import helper from './helper/index';
+import current from './index';
+import parent from '../index';
+const utils = require('./utils/index');
+```
+
+## 自动修复
+
+该规则支持自动修复，会把相对目录入口补成显式 `index` 路径。
+
+例如：
+
+```javascript
+// bad.js
+import helper from './helper';
+```
+
+会修复为：
+
+```javascript
+// good.js
+import helper from './helper/index';
+```
+
+## 检查范围
+
+该规则会检查：
+
+- `import ... from '...'`
+- `export ... from '...'`
+- `export * from '...'`
+- `import('...')`
+- `require('...')`
+
+该规则不会处理已经带扩展名的路径，也不会处理已经显式写出 `index` 的路径。

package/rules/no-relative-directory-index-imports/index.mjs

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const fileExtensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json'];
+const indexExtensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+
+function isRelativeSpecifier(specifier) {
+  return specifier === '.' || specifier === '..' || specifier.startsWith('./') || specifier.startsWith('../');
+}
+
+function hasExplicitIndex(specifier) {
+  return /(?:^|\/)index$/.test(specifier);
+}
+
+function hasExplicitExtension(specifier) {
+  return Boolean(path.posix.extname(specifier));
+}
+
+function hasMatchingFile(resolvedPath) {
+  return fileExtensions.some((extension) => fs.existsSync(`${resolvedPath}${extension}`));
+}
+
+function hasDirectoryIndex(resolvedPath) {
+  if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isDirectory()) {
+    return false;
+  }
+
+  return indexExtensions.some((extension) => fs.existsSync(path.join(resolvedPath, `index${extension}`)));
+}
+
+function getFilename(context) {
+  return context.filename || context.getFilename?.();
+}
+
+function toExplicitIndexSpecifier(specifier) {
+  if (specifier === '.') {
+    return './index';
+  }
+
+  if (specifier === '..') {
+    return '../index';
+  }
+
+  return specifier.endsWith('/') ? `${specifier}index` : `${specifier}/index`;
+}
+
+function shouldReport(context, specifier) {
+  if (!isRelativeSpecifier(specifier) || hasExplicitIndex(specifier) || hasExplicitExtension(specifier)) {
+    return false;
+  }
+
+  const filename = getFilename(context);
+  if (!filename || filename === '<input>') {
+    return false;
+  }
+
+  const resolvedPath = path.resolve(path.dirname(filename), specifier);
+  return !hasMatchingFile(resolvedPath) && hasDirectoryIndex(resolvedPath);
+}
+
+function reportSpecifier(context, node, specifier) {
+  if (!shouldReport(context, specifier)) {
+    return;
+  }
+
+  context.report({
+    node,
+    messageId: 'noRelativeDirectoryIndexImports',
+    data: {
+      specifier,
+      indexSpecifier: toExplicitIndexSpecifier(specifier)
+    },
+    fix(fixer) {
+      if (!node.range || typeof node.value !== 'string') {
+        return null;
+      }
+
+      const sourceCode = context.sourceCode || context.getSourceCode();
+      const raw = sourceCode.getText(node);
+      const quote = raw[0] === '"' ? '"' : "'";
+      return fixer.replaceText(node, `${quote}${toExplicitIndexSpecifier(specifier)}${quote}`);
+    }
+  });
+}
+
+function checkLiteralSource(context, sourceNode) {
+  if (sourceNode && sourceNode.type === 'Literal' && typeof sourceNode.value === 'string') {
+    reportSpecifier(context, sourceNode, sourceNode.value);
+  }
+}
+
+function checkCallExpression(context, node) {
+  if (
+    node.arguments.length !== 1 ||
+    !node.arguments[0] ||
+    node.arguments[0].type !== 'Literal' ||
+    typeof node.arguments[0].value !== 'string'
+  ) {
+    return;
+  }
+
+  const isRequireCall = node.callee.type === 'Identifier' && node.callee.name === 'require';
+  const isLegacyDynamicImport = node.callee.type === 'Import';
+  if (!isRequireCall && !isLegacyDynamicImport) {
+    return;
+  }
+
+  reportSpecifier(context, node.arguments[0], node.arguments[0].value);
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '禁止依赖相对目录的 index 文件兜底解析，避免微信小程序 npm 构建后的运行时解析失败'
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      noRelativeDirectoryIndexImports: '微信小程序 npm 构建后不保证把目录路径 "{{specifier}}" 解析到 "{{indexSpecifier}}"，请显式引入 "{{indexSpecifier}}"。'
+    }
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        checkLiteralSource(context, node.source);
+      },
+      ExportAllDeclaration(node) {
+        checkLiteralSource(context, node.source);
+      },
+      ExportNamedDeclaration(node) {
+        checkLiteralSource(context, node.source);
+      },
+      ImportExpression(node) {
+        checkLiteralSource(context, node.source);
+      },
+      CallExpression(node) {
+        checkCallExpression(context, node);
+      }
+    };
+  }
+};