@weapp-vite/eslint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ice breaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @weapp-vite/eslint
+
+`@weapp-vite/eslint` 提供 Wevu 项目的兼容性静态检查规则，帮助在源码阶段发现不能直接迁移到小程序运行时的 Vue、Pinia 和 Vue Router API。
+
+## 安装
+
+```bash
+pnpm add -D @weapp-vite/eslint eslint
+```
+
+## 配置
+
+```js
+import {
+  wevuCompatibilityPlugin,
+  wevuCompatibilityRecommended,
+} from '@weapp-vite/eslint'
+import { defineConfig } from 'eslint/config'
+
+export default defineConfig([
+  wevuCompatibilityRecommended,
+  {
+    plugins: {
+      wevu: wevuCompatibilityPlugin,
+    },
+  },
+])
+```
+
+推荐配置包含三条规则：
+
+- `wevu/no-unsupported-api`：禁止静态可确定的不支持导入，并给出替代 API。
+- `wevu/no-risky-api`：警告同名但参数、时序或宿主语义不同的 API。
+- `wevu/no-unsupported-template-feature`：只对能追溯到 `vue-router` 导入的 `RouterLink` 模板能力报错。
+
+规则只检查项目源码，不扫描 `node_modules`、构建产物或 `.weapp-vite` 生成文件。动态属性访问、第三方依赖内部代码和宿主运行时能力不在静态判定范围内。
+
+兼容矩阵也从根入口导出：
+
+```ts
+import {
+  findWevuCompatibilityEntry,
+  wevuCompatibilityCatalog,
+} from '@weapp-vite/eslint'
+```
+
+旧项目可以继续从 `weapp-vite/eslint` 和 `weapp-vite/compatibility` 导入兼容转出入口。

package/dist/index.d.mts

@@ -0,0 +1,44 @@
+import { Linter, Rule } from "eslint";
+//#region src/compatibility.d.ts
+type WevuCompatibilityLevel = 'supported' | 'supported-with-differences' | 'experimental' | 'unsupported';
+type WevuCompatibilityDiagnostic = 'off' | 'warn' | 'error';
+type WevuCompatibilitySurface = 'runtime' | 'template' | 'sfc-style' | 'type';
+type WevuCompatibilityUpstream = 'vue' | 'pinia' | 'vue-router';
+interface WevuCompatibilityEntry {
+  upstream: WevuCompatibilityUpstream;
+  api: string;
+  wevuEntry: 'wevu' | 'wevu/router' | 'wevu/store' | 'weapp-vite';
+  compatibility: WevuCompatibilityLevel;
+  diagnostic: WevuCompatibilityDiagnostic;
+  replacement?: string;
+  summary: string;
+  docs: string;
+  surfaces: WevuCompatibilitySurface[];
+  platforms?: {
+    weapp: 'stable' | 'experimental' | 'unsupported';
+    other: 'stable' | 'experimental' | 'unsupported';
+  };
+}
+/**
+ * Wevu 与 Vue 生态的公开兼容真值。
+ *
+ * Website、ESLint 规则和兼容审计应消费此清单，避免各自维护状态。
+ */
+declare const wevuCompatibilityCatalog: readonly WevuCompatibilityEntry[];
+declare function findWevuCompatibilityEntry(upstream: WevuCompatibilityUpstream, api: string, surface?: WevuCompatibilitySurface): WevuCompatibilityEntry | undefined;
+//#endregion
+//#region src/index.d.ts
+declare const wevuCompatibilityPlugin: {
+  meta: {
+    name: string;
+    version: string;
+  };
+  rules: {
+    'no-unsupported-api': Rule.RuleModule;
+    'no-risky-api': Rule.RuleModule;
+    'no-unsupported-template-feature': Rule.RuleModule;
+  };
+};
+declare const wevuCompatibilityRecommended: Linter.Config;
+//#endregion
+export { type WevuCompatibilityDiagnostic, type WevuCompatibilityEntry, type WevuCompatibilityLevel, type WevuCompatibilitySurface, type WevuCompatibilityUpstream, findWevuCompatibilityEntry, wevuCompatibilityCatalog, wevuCompatibilityPlugin, wevuCompatibilityRecommended };

package/dist/index.mjs

@@ -0,0 +1,382 @@
+//#region src/compatibility.ts
+const entry = (value) => value;
+/**
+* Wevu 与 Vue 生态的公开兼容真值。
+*
+* Website、ESLint 规则和兼容审计应消费此清单，避免各自维护状态。
+*/
+const wevuCompatibilityCatalog = [
+	...[
+		[
+			"vue",
+			"createSSRApp",
+			"createApp()"
+		],
+		[
+			"vue",
+			"defineAsyncComponent",
+			"静态组件导入或自动组件注册"
+		],
+		[
+			"vue",
+			"onWatcherCleanup",
+			"watch() 回调提供的清理函数"
+		],
+		[
+			"vue",
+			"useId",
+			"自行生成稳定的小程序实例 id"
+		],
+		[
+			"vue",
+			"h",
+			"Wevu JSX/TSX"
+		],
+		[
+			"vue",
+			"createRenderer",
+			"Wevu 小程序编译运行时"
+		],
+		[
+			"vue",
+			"render",
+			"Wevu 模板或 JSX/TSX"
+		],
+		[
+			"vue-router",
+			"RouterView",
+			"页面路由与 layout"
+		],
+		[
+			"vue-router",
+			"createWebHistory",
+			"createRouter()"
+		],
+		[
+			"vue-router",
+			"createWebHashHistory",
+			"createRouter()"
+		]
+	].map(([upstream, api, replacement]) => entry({
+		upstream,
+		api,
+		wevuEntry: upstream === "vue-router" ? "wevu/router" : "wevu",
+		compatibility: "unsupported",
+		diagnostic: "error",
+		replacement,
+		summary: "该 Web/renderer 能力不能在 Wevu 小程序运行时使用。",
+		docs: "/wevu/compatibility",
+		surfaces: ["runtime"]
+	})),
+	entry({
+		upstream: "vue",
+		api: "hasInjectionContext",
+		wevuEntry: "wevu",
+		compatibility: "supported",
+		diagnostic: "off",
+		summary: "与 Wevu 的同步 setup 注入上下文对齐。",
+		docs: "/wevu/api/setup-context#hasinjectioncontext",
+		surfaces: ["runtime"]
+	}),
+	entry({
+		upstream: "pinia",
+		api: "createPinia",
+		wevuEntry: "wevu/store",
+		compatibility: "unsupported",
+		diagnostic: "error",
+		replacement: "createStore()；单例场景也可直接 defineStore()",
+		summary: "Wevu Store 不创建 Pinia 根实例。",
+		docs: "/wevu/api/store#createpinia",
+		surfaces: ["runtime"]
+	}),
+	entry({
+		upstream: "vue-router",
+		api: "RouterLink",
+		wevuEntry: "wevu/router",
+		compatibility: "unsupported",
+		diagnostic: "error",
+		replacement: "router.push() 或原生 <navigator>",
+		summary: "小程序模板没有 Web RouterLink 组件。",
+		docs: "/wevu/api/router#routerlink",
+		surfaces: ["runtime", "template"]
+	}),
+	entry({
+		upstream: "vue-router",
+		api: "<router-link>",
+		wevuEntry: "wevu/router",
+		compatibility: "unsupported",
+		diagnostic: "error",
+		replacement: "router.push() 或原生 <navigator>",
+		summary: "仅禁止可追溯到 vue-router 的模板组件。",
+		docs: "/wevu/api/router#routerlink",
+		surfaces: ["template"]
+	}),
+	...[
+		["createRouter", "创建时必须处于同步 setup；默认实例按首次创建时序确定。"],
+		["useRouter", "读取 Wevu Router，而非 Web history router。"],
+		["useRoute", "只能在同步 setup 阶段读取。"],
+		["currentRoute", "是 readonly 响应式对象，不是 Ref。"],
+		["isReady", "小程序没有初始异步 history 导航，Promise 立即完成。"],
+		["install", "只建立默认实例，不注册 RouterView 或 RouterLink。"],
+		["push", "映射宿主导航；正向历史、hash、tabBar query 均受宿主限制。"],
+		["replace", "映射宿主 redirect/reLaunch/switchTab，而非 Web history replace。"],
+		["go", "仅支持负数回退；正数历史导航不可用。"],
+		["forward", "小程序没有正向历史栈。"]
+	].map(([api, summary]) => entry({
+		upstream: "vue-router",
+		api,
+		wevuEntry: "wevu/router",
+		compatibility: "supported-with-differences",
+		diagnostic: "warn",
+		summary,
+		docs: `/wevu/api/router#router-${api.toLowerCase()}`,
+		surfaces: ["runtime"]
+	})),
+	...[
+		["defineStore", "API 形状相近，但没有 Pinia SSR、HMR 和 devtools 生态。"],
+		["storeToRefs", "当前结果包含函数；Pinia 会过滤方法。"],
+		["$reset", "Options Store 与 Setup Store 均可重置。"],
+		["$subscribe", "订阅批次和错误传播遵循 Wevu 的同步 Store 契约。"],
+		["$onAction", "插件和 action 错误处理不提供完整 Pinia 上下文。"],
+		["install", "Store manager 的 install() 是 no-op。"],
+		["use", "插件上下文是 Wevu Store manager 契约，不等同 PiniaPluginContext。"]
+	].map(([api, summary]) => entry({
+		upstream: "pinia",
+		api,
+		wevuEntry: "wevu/store",
+		compatibility: "supported-with-differences",
+		diagnostic: "warn",
+		summary,
+		docs: `/wevu/api/store#${api.replace(/^\$/, "store-").toLowerCase()}`,
+		surfaces: ["runtime"]
+	})),
+	...[
+		["CSS v-bind()", "CSS 表达式经 compiler-sfc 重写并由 Wevu 响应式桥接到模板根节点。"],
+		["scoped CSS", "使用稳定 scope 属性隔离当前 SFC 拥有的节点。"],
+		[":deep()", "支持可映射到小程序选择器的常见 deep 形式。"],
+		[":global()", "支持显式移除局部 scope 的常见 global 形式。"],
+		[":slotted()", "为 slot 投影节点生成独立 slotted scope 属性。"],
+		["CSS Modules", "支持默认 $style 和命名 module。"],
+		["useCssModule()", "只能在同步 setup 中读取当前 SFC 的 module 映射。"]
+	].map(([api, summary]) => entry({
+		upstream: "vue",
+		api,
+		wevuEntry: api === "useCssModule()" ? "wevu" : "weapp-vite",
+		compatibility: "supported-with-differences",
+		diagnostic: "off",
+		summary,
+		docs: "/wevu/vue-sfc/class-style",
+		surfaces: api === "useCssModule()" ? ["runtime", "sfc-style"] : ["sfc-style"],
+		platforms: {
+			weapp: "stable",
+			other: "experimental"
+		}
+	})),
+	...[
+		["AppConfig", "Wevu 配置面向小程序 RuntimeApp，不含 Vue DOM renderer 配置。"],
+		["ComponentPublicInstance", "实例暴露宿主桥接与 Wevu setup 状态，不是 Vue DOM 组件代理。"],
+		["SetupContext", "attrs、slots、emit、expose 遵循小程序桥接约束。"],
+		["PropType", "用于小程序 properties 推导，运行时构造器能力受宿主限制。"],
+		["VNode", "仅描述 Wevu JSX island 节点，不等同 Vue renderer VNode。"],
+		["ObjectDirective", "只覆盖 Wevu 可编译或可桥接的指令钩子。"],
+		["ExtractPropTypes", "推导结果包含小程序 properties 归一化规则。"],
+		["ExtractPublicPropTypes", "公开 props 推导遵循 Wevu 组件构造类型。"]
+	].map(([api, summary]) => entry({
+		upstream: "vue",
+		api,
+		wevuEntry: "wevu",
+		compatibility: "supported-with-differences",
+		diagnostic: "warn",
+		summary,
+		docs: `/wevu/api/types#${api.toLowerCase()}`,
+		surfaces: ["type"]
+	})),
+	...[
+		"ComputedGetter",
+		"ComputedRef",
+		"ComputedSetter",
+		"CustomRefFactory",
+		"EffectScope",
+		"MaybeRef",
+		"MaybeRefOrGetter",
+		"Ref",
+		"ShallowRef",
+		"ToRefs",
+		"WritableComputedOptions",
+		"WritableComputedRef"
+	].map((api) => entry({
+		upstream: "vue",
+		api,
+		wevuEntry: "wevu",
+		compatibility: "supported",
+		diagnostic: "off",
+		summary: "类型形状与 Vue 响应式类型兼容，由 Wevu 响应式实现承载。",
+		docs: `/wevu/api/types#${api.toLowerCase()}`,
+		surfaces: ["type"]
+	})),
+	...[
+		"AllowedComponentProps",
+		"ComponentCustomProps",
+		"ComponentOptionsMixin",
+		"ComponentPropsOptions",
+		"ComponentTypeEmits",
+		"DefineComponent",
+		"EmitFn",
+		"EmitsOptions",
+		"ExtractDefaultPropTypes",
+		"GlobalComponents",
+		"GlobalDirectives",
+		"ModelRef",
+		"PublicProps",
+		"ShallowUnwrapRef",
+		"TemplateRef",
+		"VNodeProps"
+	].map((api) => entry({
+		upstream: "vue",
+		api,
+		wevuEntry: "wevu",
+		compatibility: "supported-with-differences",
+		diagnostic: "warn",
+		summary: "同名类型按 Wevu 小程序组件、事件、模板或宿主实例契约收窄。",
+		docs: `/wevu/api/types#${api.toLowerCase()}`,
+		surfaces: ["type"]
+	})),
+	...[
+		"MultiWatchSources",
+		"WatchCallback",
+		"WatchEffect",
+		"WatchEffectOptions",
+		"WatchOptions",
+		"WatchSource",
+		"WatchStopHandle"
+	].map((api) => entry({
+		upstream: "vue",
+		api,
+		wevuEntry: "wevu",
+		compatibility: "supported-with-differences",
+		diagnostic: "warn",
+		summary: "类型形状接近 Vue，但 flush 时序和渲染批次遵循 Wevu setData 调度。",
+		docs: `/wevu/api/types#${api.toLowerCase()}`,
+		surfaces: ["type"]
+	}))
+];
+function findWevuCompatibilityEntry(upstream, api, surface) {
+	return wevuCompatibilityCatalog.find((item) => item.upstream === upstream && item.api === api && (!surface || item.surfaces.includes(surface)));
+}
+//#endregion
+//#region src/index.ts
+const SOURCE_TO_UPSTREAM = {
+	"vue": "vue",
+	"pinia": "pinia",
+	"vue-router": "vue-router"
+};
+function findEntry(upstream, api, diagnostic) {
+	return wevuCompatibilityCatalog.find((item) => item.upstream === upstream && item.api === api && item.diagnostic === diagnostic);
+}
+function importedName(specifier) {
+	if (specifier.type !== "ImportSpecifier") return;
+	return specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value;
+}
+function reportCompatibility(context, node, entry) {
+	context.report({
+		node,
+		message: entry.replacement ? `{{api}} 不能在 Wevu 中使用；请改用 {{replacement}}。` : `{{api}} 在 Wevu 中的语义不同：{{summary}}`,
+		data: {
+			api: entry.api,
+			replacement: entry.replacement,
+			summary: entry.summary
+		}
+	});
+}
+function createImportCompatibilityRule(diagnostic) {
+	return {
+		meta: {
+			type: "problem",
+			docs: { description: diagnostic === "error" ? "禁止 Wevu 不支持的上游 API" : "提示 Wevu 同名 API 的语义差异" },
+			schema: [],
+			messages: {}
+		},
+		create(context) {
+			const namespaces = /* @__PURE__ */ new Map();
+			return {
+				ImportDeclaration(node) {
+					const upstream = SOURCE_TO_UPSTREAM[node.source.value];
+					if (!upstream || node.importKind === "type" && diagnostic === "error") return;
+					for (const specifier of node.specifiers) {
+						if (specifier.type === "ImportNamespaceSpecifier") {
+							namespaces.set(specifier.local.name, upstream);
+							continue;
+						}
+						if (specifier.importKind === "type" && diagnostic === "error") continue;
+						const name = importedName(specifier);
+						const compatibility = name && findEntry(upstream, name, diagnostic);
+						if (compatibility) reportCompatibility(context, specifier, compatibility);
+					}
+				},
+				MemberExpression(node) {
+					if (node.object.type !== "Identifier" || node.computed && node.property.type !== "Literal") return;
+					const upstream = namespaces.get(node.object.name);
+					const name = node.computed ? node.property.value : node.property.name;
+					const compatibility = upstream && typeof name === "string" && findEntry(upstream, name, diagnostic);
+					if (compatibility) reportCompatibility(context, node, compatibility);
+				},
+				TSQualifiedName(node) {
+					if (node.left.type !== "Identifier" || node.right.type !== "Identifier") return;
+					const upstream = namespaces.get(node.left.name);
+					const compatibility = upstream && findEntry(upstream, node.right.name, diagnostic);
+					if (compatibility) reportCompatibility(context, node, compatibility);
+				}
+			};
+		}
+	};
+}
+const wevuCompatibilityPlugin = {
+	meta: {
+		name: "weapp-vite-wevu-compatibility",
+		version: "1.0.0"
+	},
+	rules: {
+		"no-unsupported-api": createImportCompatibilityRule("error"),
+		"no-risky-api": createImportCompatibilityRule("warn"),
+		"no-unsupported-template-feature": {
+			meta: {
+				type: "problem",
+				docs: { description: "禁止可追溯到上游包的不支持模板能力" },
+				schema: [],
+				messages: {}
+			},
+			create(context) {
+				const routerLinkAliases = /* @__PURE__ */ new Set();
+				const scriptVisitor = { ImportDeclaration(node) {
+					if (node.source.value !== "vue-router" || node.importKind === "type") return;
+					for (const specifier of node.specifiers) if (importedName(specifier) === "RouterLink") routerLinkAliases.add(specifier.local.name);
+				} };
+				const parserServices = context.sourceCode.parserServices;
+				if (typeof parserServices?.defineTemplateBodyVisitor !== "function") return scriptVisitor;
+				return parserServices.defineTemplateBodyVisitor({ VElement(node) {
+					const rawName = node.rawName || node.name;
+					const normalized = String(rawName).replace(/-/g, "").toLowerCase();
+					if (![...routerLinkAliases].some((alias) => alias.toLowerCase() === normalized)) return;
+					const compatibility = findEntry("vue-router", "<router-link>", "error") ?? findEntry("vue-router", "RouterLink", "error");
+					if (compatibility) reportCompatibility(context, node, compatibility);
+				} }, scriptVisitor);
+			}
+		}
+	}
+};
+const wevuCompatibilityRecommended = {
+	files: ["**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"],
+	ignores: [
+		"**/node_modules/**",
+		"**/dist/**",
+		"**/.weapp-vite/**"
+	],
+	plugins: { wevu: wevuCompatibilityPlugin },
+	rules: {
+		"wevu/no-unsupported-api": "error",
+		"wevu/no-risky-api": "warn",
+		"wevu/no-unsupported-template-feature": "error"
+	}
+};
+//#endregion
+export { findWevuCompatibilityEntry, wevuCompatibilityCatalog, wevuCompatibilityPlugin, wevuCompatibilityRecommended };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@weapp-vite/eslint",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Wevu compatibility ESLint plugin and recommended configuration",
+  "author": "ice breaker <1324318532@qq.com>",
+  "license": "MIT",
+  "homepage": "https://vite.icebreaker.top/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weapp-vite/weapp-vite.git",
+    "directory": "packages/eslint"
+  },
+  "bugs": {
+    "url": "https://github.com/weapp-vite/weapp-vite/issues"
+  },
+  "keywords": [
+    "eslint",
+    "wevu",
+    "vue",
+    "pinia",
+    "vue-router",
+    "weapp-vite"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@typescript-eslint/parser": "^8.67.0",
+    "eslint": "^10.9.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11",
+    "vue-eslint-parser": "^10.4.1"
+  },
+  "scripts": {
+    "dev": "tsdown -w --sourcemap",
+    "build": "tsdown",
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:types": "cd test-d/compatibility-eslint-public-types && tsd",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "release": "pnpm publish",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}