@proteus-vue/compat-miniprogram 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @proteus-vue/compat-miniprogram
+
+> **G-31 B6 Layer 1 兼容层**（`docs/proteus-component-semantics-plan/migration.md`）
+
+## 一句话
+
+**旧小程序不用重写就能渐进迁移到 Proteus**（三步走）：compat 运行时桥让 `wx.*` 旧代码跑通 → codemod 批量转语义（标签/存储自动 + 复杂项标注 manual）→ 人工收尾语义还原。
+
+## 三位一体（migration.md §4 三步对应）
+
+| 能力 | 对应 Step | 说明 |
+|------|----------|------|
+| `createWxCompat(platform, cap)` | Step 1 | 运行时桥：`wx.request/navigateTo/setStorageSync/showModal/...` 委托 Proteus PlatformAPI + CapabilityHooks——旧代码原样跑通 |
+| `migrateMpSource(source)` | Step 2 | codemod 纯函数（幂等）：① 标签自动（view→p-box/text→p-text/button→p-button/input→p-input...）② 同步存储直改（`wx.setStorageSync` → `useStorage().set`）③ 回调式 API 标注（`wx.request({success})` → `[proteus-migrate:manual]` 注释）④ 语义识别标签标注（scroll-view/swiper → manual） |
+| `useStorage()` + `bindCompatPlatform()` | Step 2 目标 | codemod 输出 `useStorage().set(...)` 的运行时绑定（委托 platform.storage） |
+
+## 用法
+
+```ts
+import { createPlatformAPI, createCapabilityHooks } from '@proteus-vue/api'
+import { installCompat, migrateMpSource } from '@proteus-vue/compat-miniprogram'
+
+// Step 1：旧代码兜底（wx.* 可用）
+const platform = createPlatformAPI()
+installCompat(platform, createCapabilityHooks())
+
+// Step 2：codemod 迁移
+const migrated = migrateMpSource(`
+  <view><text>标题</text></view>
+  wx.setStorageSync('k', v)
+  wx.request({ url: '/x', success: (r) => {} })
+`)
+// → <p-box><p-text>标题</p-text></p-box>
+//   useStorage().set('k', v)
+//   // [proteus-migrate:manual] wx.request → await useFetch(url)
+//   wx.request({ url: '/x', success: (r) => {} })
+```
+
+## CLI
+
+```bash
+proteus migrate:mp <file|dir> [--dry-run]   # 批量迁移（幂等；--dry-run 只报告不写回）
+```
+
+## 严格规则
+
+- **G-31.1**：compat 层只做「兜底」，新代码必须 Layer 0 语义（p-* / useXxx）——不反向污染
+- **幂等**：codemod 跑两次结果一致（migrate-types 同款文本级规则集）
+- **包名**：`@proteus-vue/compat-miniprogram`（组织 scope 收口，决策 #215a；plan 文档写 `@proteus/compat-miniprogram`）
+
+## 路线
+
+B6 ✅ 兼容桥 + codemod（标签/存储自动 70-90% + manual 标注）→ B6 续（路由名表 + scroll-view/swiper AI 语义还原 + codemod 完善）

package/dist/codemod.d.ts

@@ -0,0 +1,17 @@
+export declare const MANUAL_MARK = "[proteus-migrate:manual]";
+/**
+ * 迁移单个文件文本（幂等——跑两次结果一致）：
+ * 1) 标签自动替换（view/button/input 等 1:1 → p-*）
+ * 2) 同步存储 → useStorage()
+ * 3) 回调式 API（wx.request({success}) 等）→ manual 标注（原代码保留，compat 层兜底可跑）
+ * 4) 语义识别标签（scroll-view/swiper）→ manual 标注（AI 辅助还原布局语义）
+ */
+export declare function migrateMpSource(source: string): string;
+/** 迁移统计（报告用） */
+export interface MigrationStats {
+    tagsReplaced: number;
+    storageReplaced: number;
+    manualAnnotations: number;
+}
+/** 统计迁移量（在 migrateMpSource 后调用——基于前后差异计数） */
+export declare function countMigration(source: string, migrated: string): MigrationStats;

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { CapabilityHooks, PlatformAPI } from '@proteus-vue/api';
+import type { WxCompat } from './wx-compat';
+export { AUTO_CODEMOD_TAGS, MANUAL_TAGS, isAutoCodeable, isManualTag } from './tags';
+export { migrateMpSource, countMigration, MANUAL_MARK } from './codemod';
+export type { MigrationStats } from './codemod';
+export { collectRouteTargets, routeNameFromPath, buildRouteTable, NAVIGATION_APIS } from './route-table';
+export type { RouteTarget } from './route-table';
+export { createWxCompat } from './wx-compat';
+export type { WxCompat } from './wx-compat';
+/** 绑定平台实例（迁移期入口：bindCompatPlatform(createPlatformAPI())——旧代码 useStorage/wx 可用） */
+export declare function bindCompatPlatform(platform: PlatformAPI): void;
+export interface CompatStorage {
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/** ★G-32 C15 目标 Hook（codemod 输出形态）：useStorage() → 平台 storage（绑定后可用） */
+export declare function useStorage(): CompatStorage;
+/** 一键绑定（迁移入口常用形态） */
+export declare function installCompat(platform: PlatformAPI, cap: CapabilityHooks): WxCompatLegacy;
+/** 兼容桥（类型包装——installCompat 返回值） */
+export type WxCompatLegacy = WxCompat;

package/dist/index.js

@@ -0,0 +1,233 @@
+// src/wx-compat.ts
+function createWxCompat(platform, cap) {
+  return {
+    // request：回调式 → platform.request Promise 桥（async 成功后调 success）
+    request(options) {
+      void platform.request({ url: options.url, method: options.method ?? "GET" }).then(
+        (res) => options.success?.({ statusCode: res.status ?? 200, data: res.data }),
+        (err) => options.fail?.(err)
+      );
+    },
+    navigateTo(options) {
+      platform.router.push(options.url ?? "");
+      options.success?.();
+    },
+    redirectTo(options) {
+      platform.router.replace(options.url ?? "");
+    },
+    navigateBack(options) {
+      platform.router.back(options.delta ?? 1);
+    },
+    switchTab(options) {
+      platform.router.switchTab(options.url ?? "");
+    },
+    setStorageSync(key, value) {
+      platform.storage.set(key, value);
+    },
+    getStorageSync(key) {
+      return platform.storage.get(key);
+    },
+    removeStorageSync(key) {
+      platform.storage.remove(key);
+    },
+    clearStorageSync() {
+      platform.storage.clear();
+    },
+    showToast(options) {
+      platform.ui.showToast(options.title ?? "", options.duration);
+    },
+    showModal(options) {
+      void platform.ui.showModal({ title: options.title, content: options.content }).then((r) => {
+        options.success?.({ confirm: r.confirm });
+      });
+    },
+    vibrateShort() {
+      void cap.useVibrate(15);
+    },
+    getSystemInfoSync() {
+      return { platform: "web", screenWidth: 390, screenHeight: 844 };
+    }
+  };
+}
+
+// src/tags.ts
+var AUTO_CODEMOD_TAGS = {
+  view: "p-box",
+  text: "p-text",
+  button: "p-button",
+  image: "p-image",
+  input: "p-input",
+  textarea: "p-textarea",
+  switch: "p-switch",
+  slider: "p-slider",
+  checkbox: "p-checkbox",
+  radio: "p-radio",
+  form: "p-form",
+  picker: "p-picker"
+};
+var MANUAL_TAGS = {
+  "scroll-view": "p-scroll\uFF08\u6216 p-stack direction\u2014\u2014\u8BED\u4E49\u8BC6\u522B\uFF09",
+  swiper: 'p-stack snap="mandatory" loop\uFF08\u8F6E\u64AD\u8BED\u4E49\uFF09',
+  "swiper-item": "p-stack \u5B50\u9879",
+  "movable-area": "gesture.scrollable \u5BB9\u5668",
+  "movable-view": "gesture.draggable",
+  navigator: "router-link\uFF08url \u2192 to \u6620\u5C04\uFF09",
+  label: "p-label\uFF08L2\uFF09",
+  progress: "p-progress\uFF08L2\uFF09",
+  "rich-text": "p-rich-text",
+  icon: "p-icon",
+  canvas: "p-canvas",
+  video: 'p-media kind="video"\uFF08\u6D88\u706D\u4E3A\u5C5E\u6027\uFF09',
+  audio: 'p-media kind="audio"\uFF08\u6D88\u706D\u4E3A\u5C5E\u6027\uFF09',
+  camera: "p-camera + useCamera\uFF08L2\uFF09",
+  map: "p-map + useMap\uFF08L2\uFF09",
+  "web-view": "p-webview\uFF08L2\uFF09"
+};
+function isManualTag(tag) {
+  return tag in MANUAL_TAGS;
+}
+function isAutoCodeable(tag) {
+  return tag in AUTO_CODEMOD_TAGS;
+}
+
+// src/codemod.ts
+var MANUAL_MARK = "[proteus-migrate:manual]";
+var COMMENT_MARK = "[proteus-migrate:manual]";
+var CALLBACK_APIS = [
+  { re: /\bwx\.request\s*\(/, target: () => "wx.request \u2192 await useFetch(url)" },
+  { re: /\bwx\.navigateTo\s*\(/, target: () => "wx.navigateTo \u2192 router.push({ name, params })\uFF08\u8DEF\u7531\u540D\u9700\u5EFA\u8868\uFF09" },
+  { re: /\bwx\.scanCode\s*\(/, target: () => "wx.scanCode \u2192 native.scanQR()\uFF08awaitify\uFF09" },
+  { re: /\bwx\.login\s*\(/, target: () => "wx.login \u2192 auth.login()\uFF08\u94FE\u8DEF\u5408\u5E76\uFF09" },
+  { re: /\bwx\.getLocation\s*\(/, target: () => "wx.getLocation \u2192 useLocation()" },
+  { re: /\bwx\.showModal\s*\(/, target: () => "wx.showModal \u2192 platform.ui.showModal\uFF08Promise\uFF09" },
+  { re: /\bwx\.showActionSheet\s*\(/, target: () => "wx.showActionSheet \u2192 platform.ui.showActionSheet\uFF08Promise\uFF09" }
+];
+function findManualTag(line) {
+  const m = line.match(/<([a-zA-Z][\w-]*)[\s/>]/);
+  if (!m) return null;
+  return isManualTag(m[1]) ? m[1] : null;
+}
+function migrateMpSource(source) {
+  let out = source;
+  for (const [mpTag, proteusTag] of Object.entries(AUTO_CODEMOD_TAGS)) {
+    out = out.replace(new RegExp(`<${mpTag}(?=[\\s>/])`, "g"), `<${proteusTag}`);
+    out = out.replace(new RegExp(`</${mpTag}\\s*>`, "g"), `</${proteusTag}>`);
+  }
+  out = out.replace(/\bwx\.setStorageSync\s*\(([^;]+)\)/g, "useStorage().set($1)");
+  out = out.replace(/\bwx\.getStorageSync\s*\(([^;]+)\)/g, "useStorage().get($1)");
+  out = out.replace(/\bwx\.removeStorageSync\s*\(([^;]+)\)/g, "useStorage().remove($1)");
+  out = out.replace(/\bwx\.clearStorageSync\s*\(/g, "useStorage().clear()");
+  const lines = out.split("\n");
+  const result = [];
+  for (const line of lines) {
+    if (line.includes(COMMENT_MARK)) {
+      result.push(line);
+      continue;
+    }
+    const prevIsMark = result.length > 0 && result[result.length - 1].includes(COMMENT_MARK);
+    const indent = line.match(/^\s*/)?.[0] ?? "";
+    let annotated = false;
+    for (const { re, target } of CALLBACK_APIS) {
+      if (re.test(line) && /success\s*[:=]/.test(line)) {
+        if (!prevIsMark) result.push(`${indent}// ${COMMENT_MARK} ${target(line)}`);
+        annotated = true;
+        break;
+      }
+    }
+    if (annotated) {
+      result.push(line);
+      continue;
+    }
+    const manualTag = findManualTag(line);
+    if (manualTag && !prevIsMark) {
+      result.push(`${indent}<!-- ${COMMENT_MARK} <${manualTag}> \u2192 ${MANUAL_TAGS[manualTag]}\uFF08\u8BED\u4E49\u8BC6\u522B\uFF0CAI \u8F85\u52A9\uFF09 -->`);
+    }
+    result.push(line);
+  }
+  return result.join("\n");
+}
+function countMigration(source, migrated) {
+  const manualAnnotations = migrated.split(COMMENT_MARK).length - 1;
+  let tagsReplaced = 0;
+  for (const mpTag of Object.keys(AUTO_CODEMOD_TAGS)) {
+    const before = (source.match(new RegExp(`<${mpTag}(?=[\\s>/])`, "g")) ?? []).length;
+    const after = (migrated.match(new RegExp(`<${mpTag}(?=[\\s>/])`, "g")) ?? []).length;
+    tagsReplaced += before - after;
+  }
+  const storageReplaced = (migrated.match(/useStorage\(\)\.(set|get|remove|clear)\(/g) ?? []).length;
+  return { tagsReplaced, storageReplaced, manualAnnotations };
+}
+
+// src/route-table.ts
+var NAVIGATION_APIS = ["navigateTo", "switchTab", "reLaunch", "redirectTo"];
+function routeNameFromPath(path) {
+  const clean = path.replace(/^\/+/, "").replace(/\.vue$/, "").split("?")[0];
+  let segs = clean.split("/").filter(Boolean);
+  if (segs[0] === "pages" || segs[0] === "subpackages") segs = segs.slice(1);
+  if (segs.length === 0) return "index";
+  if (segs[segs.length - 1] === "index") segs = segs.slice(0, -1);
+  if (segs.length === 0) return "index";
+  const kebab = segs.join("-");
+  return kebab.split("-").filter(Boolean).map((s, i) => i === 0 ? s.toLowerCase() : s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()).join("");
+}
+function collectRouteTargets(source) {
+  const out = [];
+  const re = /\bwx\.(navigateTo|switchTab|reLaunch|redirectTo)\s*\(\s*\{[^}]*?\burl\s*:\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const url = m[2];
+    const path = url.split("?")[0].replace(/^\/+/, "");
+    out.push({ api: m[1], url, path });
+  }
+  return out;
+}
+function buildRouteTable(sources) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const src of sources) {
+    for (const t of collectRouteTargets(src)) {
+      const entry = byPath.get(t.path);
+      if (entry) entry.apis.add(t.api);
+      else byPath.set(t.path, { path: t.path, name: routeNameFromPath(t.path), apis: /* @__PURE__ */ new Set([t.api]) });
+    }
+  }
+  return [...byPath.values()].map((e) => ({ path: e.path, name: e.name, apis: [...e.apis].sort() })).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+
+// src/index.ts
+var boundPlatform = null;
+function bindCompatPlatform(platform) {
+  boundPlatform = platform;
+}
+function useStorage() {
+  if (!boundPlatform) {
+    throw new Error("[compat-miniprogram] useStorage \u672A\u7ED1\u5B9A\u5E73\u53F0\u2014\u2014\u8BF7\u5148 bindCompatPlatform(createPlatformAPI())");
+  }
+  return boundPlatform.storage;
+}
+function installCompat(platform, cap) {
+  bindCompatPlatform(platform);
+  const wx = createWxCompat(platform, cap);
+  const g = globalThis;
+  if (!g.wx) g.wx = wx;
+  return wxCompatLegacy(wx);
+}
+function wxCompatLegacy(wx) {
+  return wx;
+}
+export {
+  AUTO_CODEMOD_TAGS,
+  MANUAL_MARK,
+  MANUAL_TAGS,
+  NAVIGATION_APIS,
+  bindCompatPlatform,
+  buildRouteTable,
+  collectRouteTargets,
+  countMigration,
+  createWxCompat,
+  installCompat,
+  isAutoCodeable,
+  isManualTag,
+  migrateMpSource,
+  routeNameFromPath,
+  useStorage
+};

package/dist/route-table.d.ts

@@ -0,0 +1,20 @@
+/** wx 导航 API（目标收集面） */
+export declare const NAVIGATION_APIS: readonly ["navigateTo", "switchTab", "reLaunch", "redirectTo"];
+export interface RouteTarget {
+    /** 导航 API 名（wx.navigateTo 等） */
+    api: string;
+    /** 原始 url（可能带 query） */
+    url: string;
+    /** 路径（去 query / 去 .vue / 去前导斜杠） */
+    path: string;
+}
+/** 路径 → 路由名候选（小驼峰；index 归并目录名——对齐 deriveNameFromFile + NAME_RE） */
+export declare function routeNameFromPath(path: string): string;
+/** 从单份源码收集导航目标（纯函数） */
+export declare function collectRouteTargets(source: string): RouteTarget[];
+/** 批量源码 → 去重排序路由名表（按 path） */
+export declare function buildRouteTable(sources: string[]): Array<{
+    path: string;
+    name: string;
+    apis: string[];
+}>;

package/dist/tags.d.ts

@@ -0,0 +1,8 @@
+/** codemod 自动替换：小程序标签 → p-* 语义组件（1:1；migration.md §2 自动集） */
+export declare const AUTO_CODEMOD_TAGS: Record<string, string>;
+/** 需语义识别（manual 标注——scroll-view→p-stack 等语义还原；AI Agent G-23 辅助） */
+export declare const MANUAL_TAGS: Record<string, string>;
+/** 判定一个标签是否需要 manual 标注（有效小程序组件标签） */
+export declare function isManualTag(tag: string): boolean;
+/** 判定一个标签是否自动可替换 */
+export declare function isAutoCodeable(tag: string): boolean;

package/dist/wx-compat.d.ts

@@ -0,0 +1,53 @@
+import type { CapabilityHooks } from '@proteus-vue/api';
+import type { PlatformAPI } from '@proteus-vue/api';
+/** wx 兼容面（旧代码可用子集——委托 Proteus） */
+export interface WxCompat {
+    request(options: {
+        url: string;
+        method?: string;
+        success?: (res: {
+            statusCode: number;
+            data: unknown;
+        }) => void;
+        fail?: (err: unknown) => void;
+    }): void;
+    navigateTo(options: {
+        url: string;
+        success?: () => void;
+    }): void;
+    redirectTo(options: {
+        url: string;
+    }): void;
+    navigateBack(options: {
+        delta?: number;
+    }): void;
+    switchTab(options: {
+        url: string;
+    }): void;
+    setStorageSync(key: string, value: unknown): void;
+    getStorageSync(key: string): unknown;
+    removeStorageSync(key: string): void;
+    clearStorageSync(): void;
+    showToast(options: {
+        title: string;
+        duration?: number;
+    }): void;
+    showModal(options: {
+        title?: string;
+        content?: string;
+        success?: (res: {
+            confirm: boolean;
+        }) => void;
+    }): void;
+    vibrateShort(): void;
+    getSystemInfoSync(): {
+        platform: string;
+        screenWidth: number;
+        screenHeight: number;
+    };
+}
+/**
+ * 创建 wx 兼容桥（平台无关——委托 Proteus PlatformAPI + CapabilityHooks）
+ * 用法（迁移期入口）：globalThis.wx = createWxCompat(platform, cap)
+ */
+export declare function createWxCompat(platform: PlatformAPI, cap: CapabilityHooks): WxCompat;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@proteus-vue/compat-miniprogram",
+  "version": "0.1.0",
+  "description": "G-31 B6 Layer 1 兼容层（proteus-component-semantics-plan migration.md）：旧小程序迁移三步走——createWxCompat 运行时桥（wx.* 委托 Proteus）+ migrateMpSource codemod（标签自动/存储直改/manual 标注）+ useStorage 迁移目标",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --platform=neutral --outfile=dist/index.js --external:@proteus-vue/api"
+  },
+  "dependencies": {
+    "@proteus-vue/api": "0.1.0"
+  }
+}