@weapp-vite/eslint 0.2.2 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # @weapp-vite/eslint
 
-`@weapp-vite/eslint` 提供 Wevu 项目的兼容性静态检查规则，帮助在源码阶段发现不能直接迁移到小程序运行时的 Vue、Pinia 和 Vue Router API。
+`@weapp-vite/eslint` 提供 Wevu 兼容性和小程序 AppService 宿主 API 静态检查规则。
 
 ## 安装
 
@@ -12,12 +12,14 @@ pnpm add -D @weapp-vite/eslint eslint
 
 ```js
 import {
+  miniProgramRuntimeRecommended,
   wevuCompatibilityPlugin,
   wevuCompatibilityRecommended,
 } from '@weapp-vite/eslint'
 import { defineConfig } from 'eslint/config'
 
 export default defineConfig([
+  miniProgramRuntimeRecommended,
   wevuCompatibilityRecommended,
   {
     plugins: {
@@ -33,6 +35,23 @@ export default defineConfig([
 - `wevu/no-risky-api`：警告同名但参数、时序或宿主语义不同的 API。
 - `wevu/no-unsupported-template-feature`：只对能追溯到 `vue-router` 导入的 `RouterLink` 模板能力报错。
 
+`miniProgramRuntimeRecommended` 另外提供：
+
+- `mini-program/no-unsupported-runtime-api`：禁止 DOM/Node 全局和超出 ES2018 小程序兼容基线的现代内建。
+- `mini-program/no-implicit-runtime-polyfill`：警告 `queueMicrotask`、`fetch`、`URL`、`AbortController` 等不能依赖宿主隐式提供的能力，并指向 `weapp.appPrelude.webRuntime` 或显式兼容层。
+
+默认只匹配 `src/**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}`，排除 config、测试、脚本、Web-only、`dist` 和生成目录。需要自定义源码范围时使用：
+
+```js
+import { createMiniProgramRuntimeConfig } from '@weapp-vite/eslint'
+
+export default defineConfig([
+  createMiniProgramRuntimeConfig({ files: ['app/**/*.ts'] }),
+])
+```
+
+局部变量、参数、import、类型位置和单纯的 `typeof` 能力探测不会报错。静态规则不能代替目标真机/IDE 验证；尤其不能假定所有微信基础库都提供 `queueMicrotask`。
+
 规则只检查项目源码，不扫描 `node_modules`、构建产物或 `.weapp-vite` 生成文件。动态属性访问、第三方依赖内部代码和宿主运行时能力不在静态判定范围内。
 
 兼容矩阵也从根入口导出：

package/dist/index.d.mts

@@ -27,6 +27,45 @@ interface WevuCompatibilityEntry {
 declare const wevuCompatibilityCatalog: readonly WevuCompatibilityEntry[];
 declare function findWevuCompatibilityEntry(upstream: WevuCompatibilityUpstream, api: string, surface?: WevuCompatibilitySurface): WevuCompatibilityEntry | undefined;
 //#endregion
+//#region src/miniProgramRuntime.d.ts
+type MiniProgramRuntimeApiDiagnostic = 'off' | 'warn' | 'error';
+type MiniProgramRuntimeApiKind = 'global' | 'static-method' | 'instance-method';
+type MiniProgramRuntimeApiSupport = 'baseline' | 'polyfill-required' | 'unsupported';
+interface MiniProgramRuntimeApiEntry {
+  api: string;
+  kind: MiniProgramRuntimeApiKind;
+  support: MiniProgramRuntimeApiSupport;
+  diagnostic: MiniProgramRuntimeApiDiagnostic;
+  platform: 'wechat';
+  replacement?: string;
+  summary: string;
+}
+/**
+ * 微信小程序 AppService 运行时能力清单。
+ *
+ * baseline 表示兼容基线可直接使用；polyfill-required 表示必须显式启用或调用
+ * weapp-vite 兼容层；unsupported 表示业务运行时代码不应依赖该能力。
+ */
+declare const miniProgramRuntimeApiCatalog: readonly MiniProgramRuntimeApiEntry[];
+declare const miniProgramRuntimePlugin: {
+  meta: {
+    name: string;
+    version: string;
+  };
+  rules: {
+    'no-unsupported-runtime-api': Rule.RuleModule;
+    'no-implicit-runtime-polyfill': Rule.RuleModule;
+  };
+};
+interface MiniProgramRuntimeConfigOptions {
+  files?: string[];
+  ignores?: string[];
+}
+declare const MINI_PROGRAM_RUNTIME_DEFAULT_FILES: string[];
+declare const MINI_PROGRAM_RUNTIME_DEFAULT_IGNORES: string[];
+declare function createMiniProgramRuntimeConfig(options?: MiniProgramRuntimeConfigOptions): Linter.Config;
+declare const miniProgramRuntimeRecommended: Linter.Config;
+//#endregion
 //#region src/index.d.ts
 declare const wevuCompatibilityPlugin: {
   meta: {
@@ -41,4 +80,4 @@ declare const wevuCompatibilityPlugin: {
 };
 declare const wevuCompatibilityRecommended: Linter.Config;
 //#endregion
-export { type WevuCompatibilityDiagnostic, type WevuCompatibilityEntry, type WevuCompatibilityLevel, type WevuCompatibilitySurface, type WevuCompatibilityUpstream, findWevuCompatibilityEntry, wevuCompatibilityCatalog, wevuCompatibilityPlugin, wevuCompatibilityRecommended };
+export { MINI_PROGRAM_RUNTIME_DEFAULT_FILES, MINI_PROGRAM_RUNTIME_DEFAULT_IGNORES, type MiniProgramRuntimeApiDiagnostic, type MiniProgramRuntimeApiEntry, type MiniProgramRuntimeApiKind, type MiniProgramRuntimeApiSupport, type MiniProgramRuntimeConfigOptions, type WevuCompatibilityDiagnostic, type WevuCompatibilityEntry, type WevuCompatibilityLevel, type WevuCompatibilitySurface, type WevuCompatibilityUpstream, createMiniProgramRuntimeConfig, findWevuCompatibilityEntry, miniProgramRuntimeApiCatalog, miniProgramRuntimePlugin, miniProgramRuntimeRecommended, wevuCompatibilityCatalog, wevuCompatibilityPlugin, wevuCompatibilityRecommended };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 //#region src/compatibility.ts
-const entry = (value) => value;
+const entry$1 = (value) => value;
 /**
 * Wevu 与 Vue 生态的公开兼容真值。
 *
@@ -57,7 +57,7 @@ const wevuCompatibilityCatalog = [
 			"createWebHashHistory",
 			"createRouter()"
 		]
-	].map(([upstream, api, replacement]) => entry({
+	].map(([upstream, api, replacement]) => entry$1({
 		upstream,
 		api,
 		wevuEntry: upstream === "vue-router" ? "wevu/router" : "wevu",
@@ -68,7 +68,7 @@ const wevuCompatibilityCatalog = [
 		docs: "/wevu/compatibility",
 		surfaces: ["runtime"]
 	})),
-	entry({
+	entry$1({
 		upstream: "vue",
 		api: "hasInjectionContext",
 		wevuEntry: "wevu",
@@ -78,7 +78,7 @@ const wevuCompatibilityCatalog = [
 		docs: "/wevu/api/setup-context#hasinjectioncontext",
 		surfaces: ["runtime"]
 	}),
-	entry({
+	entry$1({
 		upstream: "pinia",
 		api: "createPinia",
 		wevuEntry: "wevu/store",
@@ -89,7 +89,7 @@ const wevuCompatibilityCatalog = [
 		docs: "/wevu/api/store#createpinia",
 		surfaces: ["runtime"]
 	}),
-	entry({
+	entry$1({
 		upstream: "vue-router",
 		api: "RouterLink",
 		wevuEntry: "wevu/router",
@@ -100,7 +100,7 @@ const wevuCompatibilityCatalog = [
 		docs: "/wevu/api/router#routerlink",
 		surfaces: ["runtime", "template"]
 	}),
-	entry({
+	entry$1({
 		upstream: "vue-router",
 		api: "<router-link>",
 		wevuEntry: "wevu/router",
@@ -122,7 +122,7 @@ const wevuCompatibilityCatalog = [
 		["replace", "映射宿主 redirect/reLaunch/switchTab，而非 Web history replace。"],
 		["go", "仅支持负数回退；正数历史导航不可用。"],
 		["forward", "小程序没有正向历史栈。"]
-	].map(([api, summary]) => entry({
+	].map(([api, summary]) => entry$1({
 		upstream: "vue-router",
 		api,
 		wevuEntry: "wevu/router",
@@ -140,7 +140,7 @@ const wevuCompatibilityCatalog = [
 		["$onAction", "插件和 action 错误处理不提供完整 Pinia 上下文。"],
 		["install", "Store manager 的 install() 是 no-op。"],
 		["use", "插件上下文是 Wevu Store manager 契约，不等同 PiniaPluginContext。"]
-	].map(([api, summary]) => entry({
+	].map(([api, summary]) => entry$1({
 		upstream: "pinia",
 		api,
 		wevuEntry: "wevu/store",
@@ -158,7 +158,7 @@ const wevuCompatibilityCatalog = [
 		[":slotted()", "为 slot 投影节点生成独立 slotted scope 属性。"],
 		["CSS Modules", "支持默认 $style 和命名 module。"],
 		["useCssModule()", "只能在同步 setup 中读取当前 SFC 的 module 映射。"]
-	].map(([api, summary]) => entry({
+	].map(([api, summary]) => entry$1({
 		upstream: "vue",
 		api,
 		wevuEntry: api === "useCssModule()" ? "wevu" : "weapp-vite",
@@ -181,7 +181,7 @@ const wevuCompatibilityCatalog = [
 		["ObjectDirective", "只覆盖 Wevu 可编译或可桥接的指令钩子。"],
 		["ExtractPropTypes", "推导结果包含小程序 properties 归一化规则。"],
 		["ExtractPublicPropTypes", "公开 props 推导遵循 Wevu 组件构造类型。"]
-	].map(([api, summary]) => entry({
+	].map(([api, summary]) => entry$1({
 		upstream: "vue",
 		api,
 		wevuEntry: "wevu",
@@ -204,7 +204,7 @@ const wevuCompatibilityCatalog = [
 		"ToRefs",
 		"WritableComputedOptions",
 		"WritableComputedRef"
-	].map((api) => entry({
+	].map((api) => entry$1({
 		upstream: "vue",
 		api,
 		wevuEntry: "wevu",
@@ -231,7 +231,7 @@ const wevuCompatibilityCatalog = [
 		"ShallowUnwrapRef",
 		"TemplateRef",
 		"VNodeProps"
-	].map((api) => entry({
+	].map((api) => entry$1({
 		upstream: "vue",
 		api,
 		wevuEntry: "wevu",
@@ -249,7 +249,7 @@ const wevuCompatibilityCatalog = [
 		"WatchOptions",
 		"WatchSource",
 		"WatchStopHandle"
-	].map((api) => entry({
+	].map((api) => entry$1({
 		upstream: "vue",
 		api,
 		wevuEntry: "wevu",
@@ -264,6 +264,229 @@ function findWevuCompatibilityEntry(upstream, api, surface) {
 	return wevuCompatibilityCatalog.find((item) => item.upstream === upstream && item.api === api && (!surface || item.surfaces.includes(surface)));
 }
 //#endregion
+//#region src/miniProgramRuntime.ts
+const entry = (value) => value;
+/**
+* 微信小程序 AppService 运行时能力清单。
+*
+* baseline 表示兼容基线可直接使用；polyfill-required 表示必须显式启用或调用
+* weapp-vite 兼容层；unsupported 表示业务运行时代码不应依赖该能力。
+*/
+const miniProgramRuntimeApiCatalog = [
+	...[
+		"fetch",
+		"Headers",
+		"Request",
+		"Response",
+		"AbortController",
+		"AbortSignal",
+		"XMLHttpRequest",
+		"WebSocket",
+		"URL",
+		"URLSearchParams",
+		"Blob",
+		"File",
+		"FormData",
+		"TextEncoder",
+		"TextDecoder",
+		"atob",
+		"btoa",
+		"performance",
+		"crypto",
+		"Event",
+		"CustomEvent",
+		"queueMicrotask"
+	].map((api) => entry({
+		api,
+		kind: "global",
+		support: "polyfill-required",
+		diagnostic: "warn",
+		platform: "wechat",
+		replacement: "启用 weapp.appPrelude.webRuntime，或从 @wevu/web-apis 使用显式兼容实现",
+		summary: "不同基础库、真机和 DevTools 版本的宿主能力不一致，不能依赖隐式全局。"
+	})),
+	...[
+		"window",
+		"document",
+		"navigator",
+		"self",
+		"global",
+		"location",
+		"process",
+		"Buffer",
+		"localStorage",
+		"sessionStorage",
+		"setImmediate",
+		"structuredClone"
+	].map((api) => entry({
+		api,
+		kind: "global",
+		support: "unsupported",
+		diagnostic: "error",
+		platform: "wechat",
+		summary: "微信小程序 AppService 不提供可移植的浏览器或 Node.js 全局能力。"
+	})),
+	...[
+		["Object.fromEntries", "使用 for...of 构造对象"],
+		["Object.hasOwn", "使用 Object.prototype.hasOwnProperty.call(...)"],
+		["Promise.any", "使用兼容实现或调整并发策略"],
+		["Promise.allSettled", "使用 Promise.all 包装每个任务结果"]
+	].map(([api, replacement]) => entry({
+		api,
+		kind: "static-method",
+		support: "unsupported",
+		diagnostic: "error",
+		platform: "wechat",
+		replacement,
+		summary: "该现代内建超出项目的小程序 ES2018 运行时兼容基线。"
+	})),
+	...[
+		["Array.prototype.at", "使用下标访问"],
+		["String.prototype.at", "使用 charAt() 或下标访问"],
+		["Array.prototype.flat", "使用循环展开数组"],
+		["Array.prototype.flatMap", "使用循环或 reduce 展开数组"],
+		["String.prototype.replaceAll", "使用带全局标志的正则 replace()"]
+	].map(([api, replacement]) => entry({
+		api,
+		kind: "instance-method",
+		support: "unsupported",
+		diagnostic: "error",
+		platform: "wechat",
+		replacement,
+		summary: "该现代内建超出项目的小程序 ES2018 运行时兼容基线。"
+	}))
+];
+const unsupportedEntries = miniProgramRuntimeApiCatalog.filter((item) => item.support === "unsupported");
+const polyfillEntries = miniProgramRuntimeApiCatalog.filter((item) => item.support === "polyfill-required");
+function staticPropertyName(node) {
+	if (!node.computed && node.property?.type === "Identifier") return node.property.name;
+	if (node.computed && node.property?.type === "Literal" && typeof node.property.value === "string") return node.property.value;
+}
+function isTypePosition(node) {
+	let current = node.parent;
+	while (current) {
+		if (String(current.type).startsWith("TS")) return true;
+		if (/Expression$|Statement$|Declaration$/.test(current.type)) return false;
+		current = current.parent;
+	}
+	return false;
+}
+function isLocallyBound(context, node, name) {
+	let scope = context.sourceCode.getScope(node);
+	while (scope) {
+		if ((scope.set?.get(name))?.defs?.length) return true;
+		scope = scope.upper;
+	}
+	return false;
+}
+function isScopeReference(context, node) {
+	let scope = context.sourceCode.getScope(node);
+	while (scope) {
+		if (scope.references?.some((reference) => reference.identifier === node) || scope.through?.some((reference) => reference.identifier === node)) return true;
+		scope = scope.upper;
+	}
+	return false;
+}
+function isInspectionOnlyReference(node) {
+	return isTypePosition(node) || node.parent?.type === "UnaryExpression" && node.parent.operator === "typeof";
+}
+function isRuntimeReference(context, node) {
+	if (isInspectionOnlyReference(node)) return false;
+	return isScopeReference(context, node) && !isLocallyBound(context, node, node.name);
+}
+function staticRuntimeObjectName(context, node) {
+	if (node?.type === "Identifier" && !isLocallyBound(context, node, node.name)) return node.name;
+	if (node?.type === "MemberExpression" && node.object?.type === "Identifier" && node.object.name === "globalThis" && !isLocallyBound(context, node.object, "globalThis")) return staticPropertyName(node);
+}
+function report(context, node, entry) {
+	context.report({
+		node,
+		message: entry.replacement ? `{{api}} 不能作为隐式小程序运行时能力使用；{{replacement}}。` : `{{api}} 不是受支持的小程序运行时能力。`,
+		data: {
+			api: entry.api,
+			replacement: entry.replacement
+		}
+	});
+}
+function createRuntimeApiRule(entries) {
+	const globals = new Map(entries.filter((item) => item.kind === "global").map((item) => [item.api, item]));
+	const staticMethods = new Map(entries.filter((item) => item.kind === "static-method").map((item) => [item.api, item]));
+	const instanceMethods = /* @__PURE__ */ new Map();
+	for (const item of entries.filter((item) => item.kind === "instance-method")) instanceMethods.set(item.api.slice(item.api.lastIndexOf(".") + 1), item);
+	return {
+		meta: {
+			type: "problem",
+			docs: { description: "限制小程序 AppService 不可移植的运行时 API" },
+			schema: [],
+			messages: {}
+		},
+		create(context) {
+			return {
+				Identifier(node) {
+					const entry = globals.get(node.name);
+					if (!entry || !isRuntimeReference(context, node)) return;
+					if (node.parent?.type === "MemberExpression" && node.parent.property === node && !node.parent.computed) return;
+					report(context, node, entry);
+				},
+				MemberExpression(node) {
+					if (isInspectionOnlyReference(node)) return;
+					const property = staticPropertyName(node);
+					if (!property) return;
+					if (node.object?.type === "Identifier" && node.object.name === "globalThis" && !isLocallyBound(context, node.object, "globalThis")) {
+						const globalEntry = globals.get(property);
+						if (globalEntry) report(context, node, globalEntry);
+						return;
+					}
+					const runtimeObjectName = staticRuntimeObjectName(context, node.object);
+					if (runtimeObjectName) {
+						const staticEntry = staticMethods.get(`${runtimeObjectName}.${property}`);
+						if (staticEntry) {
+							report(context, node, staticEntry);
+							return;
+						}
+					}
+					const instanceEntry = instanceMethods.get(property);
+					if (instanceEntry && node.parent?.type === "CallExpression" && node.parent.callee === node) report(context, node, instanceEntry);
+				}
+			};
+		}
+	};
+}
+const miniProgramRuntimePlugin = {
+	meta: {
+		name: "weapp-vite-mini-program-runtime",
+		version: "1.0.0"
+	},
+	rules: {
+		"no-unsupported-runtime-api": createRuntimeApiRule(unsupportedEntries),
+		"no-implicit-runtime-polyfill": createRuntimeApiRule(polyfillEntries)
+	}
+};
+const MINI_PROGRAM_RUNTIME_DEFAULT_FILES = ["src/**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"];
+const MINI_PROGRAM_RUNTIME_DEFAULT_IGNORES = [
+	"**/node_modules/**",
+	"**/dist/**",
+	"**/dist-*/**",
+	"**/.weapp-vite/**",
+	"**/generated/**",
+	"**/scripts/**",
+	"**/src/**/node.{js,mjs,cjs,jsx,ts,mts,cts,tsx}",
+	"**/src/**/*.web.*",
+	"**/*.{test,spec}.{js,mjs,cjs,jsx,ts,mts,cts,tsx}"
+];
+function createMiniProgramRuntimeConfig(options = {}) {
+	return {
+		files: options.files ?? MINI_PROGRAM_RUNTIME_DEFAULT_FILES,
+		ignores: options.ignores ?? MINI_PROGRAM_RUNTIME_DEFAULT_IGNORES,
+		plugins: { "mini-program": miniProgramRuntimePlugin },
+		rules: {
+			"mini-program/no-unsupported-runtime-api": "error",
+			"mini-program/no-implicit-runtime-polyfill": "warn"
+		}
+	};
+}
+const miniProgramRuntimeRecommended = createMiniProgramRuntimeConfig();
+//#endregion
 //#region src/index.ts
 const SOURCE_TO_UPSTREAM = {
 	"vue": "vue",
@@ -379,4 +602,4 @@ const wevuCompatibilityRecommended = {
 	}
 };
 //#endregion
-export { findWevuCompatibilityEntry, wevuCompatibilityCatalog, wevuCompatibilityPlugin, wevuCompatibilityRecommended };
+export { MINI_PROGRAM_RUNTIME_DEFAULT_FILES, MINI_PROGRAM_RUNTIME_DEFAULT_IGNORES, createMiniProgramRuntimeConfig, findWevuCompatibilityEntry, miniProgramRuntimeApiCatalog, miniProgramRuntimePlugin, miniProgramRuntimeRecommended, wevuCompatibilityCatalog, wevuCompatibilityPlugin, wevuCompatibilityRecommended };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weapp-vite/eslint",
   "type": "module",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Wevu compatibility ESLint plugin and recommended configuration",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -52,7 +52,7 @@
     }
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "^8.68.0",
+    "@typescript-eslint/parser": "^8.69.0",
     "eslint": "^10.9.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",