babel-plugin-transform-taroapi 4.1.12-beta.23 → 4.1.12-beta.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-plugin-transform-taroapi",
-  "version": "4.1.12-beta.23",
+  "version": "4.1.12-beta.26",
   "author": "O2Team",
   "license": "MIT",
   "main": "dist/index.js",

package/docs/h5-compile-flow-analysis.md

@@ -1,94 +0,0 @@
-# H5 端编译流程与 transform-taroapi 执行顺序分析
-
-## 1. 相关插件与调用顺序
-
-### 1.1 modifyWebpackChain 注册顺序
-
-| 插件 | 注册时机 | 作用 |
-|-----|---------|-----|
-| **taro-framework-react** | 框架插件 | `modifyH5WebpackChain`：设置 alias、process-import-taro-h5 loader（仅匹配 `taro-h5/dist/`）、fast-refresh |
-| **taro-platform-h5** | 平台插件，`setupTransaction.addWrapper` | 追加 `transform-taroapi` 到 babel-loader 的 `plugins` |
-| **plugin-inject-jdapi** | 业务插件，`onSetupClose` | 修改 transform-taroapi 配置（apis）、可将其移到 preset |
-
-### 1.2 taro-platform-h5 的 Babel 修改
-
-```ts
-// taro-platform-h5/src/program.ts:98-111
-const options = babelLoader.get('options')
-babelLoader.set('options', {
-  ...options,
-  plugins: [
-    ...(options.plugins || []),
-    [require('babel-plugin-transform-taroapi'), { packageName, definition }],
-  ],
-})
-```
-
-**关键**：`transform-taroapi` 被 **追加** 到 `options.plugins` 末尾。
-
-### 1.3 初始 Babel 配置来源
-
-- **script rule**：`WebpackModule.getScriptRule()` 仅设置 `babel-loader` 且 `options: { compact: false }`
-- **完整配置**：babel-loader 运行时从项目根目录加载 `babel.config.js`
-- **babel.config.js** 典型内容：`presets: ['babel-preset-taro']`
-
-## 2. babel-preset-taro 的配置结构
-
-```js
-// babel-preset-taro/index.js
-return {
-  sourceType: 'unambiguous',
-  overrides: [{
-    exclude: [/@babel[/|\\\\]runtime/, /core-js/, /\bwebpack\/buildin\b/],
-    presets: [preset-env, preset-ts, preset-react, ...],
-    plugins: [decorators, class-props, transform-runtime, dynamic-import-node, ...],
-  }],
-}
-```
-
-- 对 **未** 命中 `exclude` 的文件（如 `list/index.tsx`），使用 override 的 `presets` 和 `plugins`
-- `preset-env` 内含 `@babel/plugin-transform-optional-chaining`
-- `transform-runtime` 会注入 `_slicedToArray` 等 helper
-
-## 3. 最终 Babel 配置的合并方式
-
-loader 传入的 `options` 会与 `babel.config.js` 合并，大致为：
-
-```
-babel.config.js:  presets: [babel-preset-taro]
-loader options:   plugins: [..., transform-taroapi]  // taro-platform-h5 追加
-```
-
-Babel 对 **overrides** 的处理：
-
-- 命中 override 时，会应用 override 的 `presets` 和 `plugins`
-- 顶层 `plugins`（含 `transform-taroapi`）与 override 的合并顺序依赖 Babel 内部实现
-- 若 override 的 plugins 先于顶层 plugins 执行，则 `optional-chaining`、`transform-runtime` 会先跑，预扫描时 AST 已被改写
-
-## 4. order10 日志的结论
-
-预扫描时 AST 已包含：
-
-- 第一个 import：`_slicedToArray`（来自 transform-runtime）
-- `Taro.JDMTA.isTrafficMapEnable?.()` 已被展开为三元表达式
-
-说明在 `transform-taroapi` 的 `Program.enter` 执行前，`optional-chaining` 和 `transform-runtime` 已经处理过该文件。
-
-## 5. 可选修复方案
-
-### 方案 A：在 plugin-inject-jdapi 中移到 preset（已实现）
-
-将 `transform-taroapi` 从 `plugins` 中移除，放入独立 preset，并 `presets.push()`，利用 presets 倒序执行，使其在 preset-env 之前运行。
-
-### 方案 B：在 taro-platform-h5 中调整注入方式
-
-在 `taro-platform-h5` 中不再简单追加到 `plugins`，而是：
-
-- 使用 `presets.unshift({ plugins: [transform-taroapi] })`，或
-- 通过其他方式保证其在 preset-env 之前执行
-
-这样不依赖 plugin-inject-jdapi，所有 H5 项目都能受益。
-
-### 方案 C：在 babel-preset-taro 中内置
-
-在 `babel-preset-taro` 的 override 中，将 `transform-taroapi` 放在 `plugins` 数组最前面，确保先于 `optional-chaining` 执行。

package/docs/optional-chaining-fix.md

@@ -1,212 +0,0 @@
-# H5 端命名空间 API 可选链问题修复方案
-
-## 问题描述
-
-在 Taro H5 端，使用可选链语法调用命名空间 API 时，编译产物中会保留对 `Taro.JDMTA` 等不存在对象的引用，导致运行时报错：
-
-```
-TypeError: Cannot read properties of undefined (reading 'isTrafficMapEnable')
-```
-
-受影响的写法包括：
-
-```ts
-// 以下可选链写法在 H5 端均会出错
-Taro?.JDMTA.isTrafficMapEnable()
-Taro.JDMTA?.isTrafficMapEnable()
-Taro.JDMTA.isTrafficMapEnable?.()           // 最常见
-Taro?.JDMTA?.isTrafficMapEnable()
-Taro?.JDMTA.isTrafficMapEnable?.()
-Taro.JDMTA?.isTrafficMapEnable?.()
-Taro?.JDMTA?.isTrafficMapEnable?.()
-```
-
-而不带可选链的写法 `Taro.JDMTA.isTrafficMapEnable()` 一直是正常的。
-
-## 根因分析
-
-### Babel 的遍历模型
-
-Babel 将所有插件的 visitor **合并到一次遍历**中，逐节点推进，对同一节点按插件顺序依次触发 visitor。这意味着：
-
-- `transform-taroapi` 和 `@babel/plugin-transform-optional-chaining`（来自 `preset-env`）共享同一次遍历
-- "插件 A 先于插件 B"只意味着**同一节点**上 A 的 visitor 先触发，而非 A 完整跑完再轮到 B
-
-### 具体失败场景
-
-以 `Taro.JDMTA.isTrafficMapEnable?.().then(res => {...})` 为例，AST 结构如下：
-
-```
-CallExpression (.then)                              ← 主遍历先访问这里
-  └─ MemberExpression (.then)
-       └─ OptionalCallExpression { optional: true }  ← 我们想处理的节点
-            └─ MemberExpression (Taro.JDMTA.isTrafficMapEnable)
-```
-
-主遍历是自顶向下（enter）的：
-
-1. **进入 `.then()` CallExpression** — `transform-taroapi` 先触发，callee 是 `.then`，不匹配，跳过
-2. **紧接着** `@babel/plugin-transform-optional-chaining` 触发 — 检测到 callee 链中存在 `?.()` 可选链，**一次性展开整条链**，生成：
-   ```js
-   (_Taro$JDMTA = Taro.JDMTA) === null || _Taro$JDMTA === void 0
-     ? void 0
-     : _Taro$JDMTA.isTrafficMapEnable().then(res => {...})
-   ```
-3. 内层 `OptionalCallExpression` 节点**已经被替换**，`transform-taroapi` 永远无法访问到它
-
-关键在于：外层节点先被访问，`optional-chaining` 在外层就把整棵子树改写了，内层节点在被任何插件处理前就已消失。
-
-## 解决方案
-
-### 核心思路：`Program.enter` 预扫描
-
-在 `transform-taroapi` 的 `Program.enter` 中，通过 `ast.traverse()` 发起一次**独立的子遍历**。这次子遍历：
-
-- 只有 `transform-taroapi` 自己的逻辑参与，没有其他插件
-- **同步执行完毕**后，主遍历才继续
-- 在所有插件开始处理具体节点之前，就把可选链降级完成
-
-### 执行流程
-
-```
-┌─────────────────────────────────────────────────────┐
-│ Program.enter 触发                                   │
-│                                                     │
-│ 子遍历 1：找到 import，确定 taroName                  │
-│   import Taro from '@tarojs/taro'                   │
-│   → preScanTaroName = 'Taro'                        │
-│                                                     │
-│ 子遍历 2：遍历所有 OptionalCallExpression             │
-│   Taro.JDMTA.isTrafficMapEnable?.()                 │
-│   → 匹配 namespace API（JDMTA_isTrafficMapEnable）   │
-│   → replaceWith(CallExpression)                     │
-│   → 变成 Taro.JDMTA.isTrafficMapEnable()            │
-│                                                     │
-│ ─── 子遍历完成，AST 已修改 ───                        │
-└─────────────────────────────────────────────────────┘
-                    │
-                    ▼
-┌─────────────────────────────────────────────────────┐
-│ 主遍历继续（所有插件共享）                              │
-│                                                     │
-│ @babel/plugin-transform-optional-chaining            │
-│   → 已经没有 Taro API 的可选链了，不会介入              │
-│                                                     │
-│ transform-taroapi 的 CallExpression visitor           │
-│   → 匹配 Taro.JDMTA.isTrafficMapEnable()            │
-│   → 替换为 _JDMTA_isTrafficMapEnable()              │
-│                                                     │
-│ Program.exit                                        │
-│   → 生成 import { JDMTA_isTrafficMapEnable as       │
-│     _JDMTA_isTrafficMapEnable } from '@tarojs/taro' │
-└─────────────────────────────────────────────────────┘
-```
-
-### 代码改动说明
-
-#### 1. `getTaroNamespaceCall` 辅助函数
-
-统一识别各种可选链和 TS 包裹形态下的命名空间 API 调用：
-
-```ts
-function getTaroNamespaceCall(t, callee, taroName, file)
-  : { namespaceName: string, methodName: string } | null
-```
-
-处理的 callee 形态包括：
-- `MemberExpression`：`Taro.JDMTA.isTrafficMapEnable`
-- `OptionalMemberExpression`：`Taro?.JDMTA?.isTrafficMapEnable`
-- `OptionalCallExpression` 包裹：`Taro.JDMTA.isTrafficMapEnable?.()`
-- `AssignmentExpression` 包裹：`(_tmp = Taro.JDMTA).isTrafficMapEnable`
-- `TSAsExpression` / `TSNonNullExpression` 等 TS 类型包裹
-
-#### 2. `Program.enter` 预扫描（核心）
-
-```ts
-Program: {
-  enter(ast) {
-    // ... 状态重置 ...
-
-    // 子遍历 1：找到 taroName
-    ast.traverse({
-      ImportDeclaration(importPath) { /* 从 import 中提取 taroName */ }
-    })
-
-    // 子遍历 2：降级可选链
-    if (preScanTaroName) {
-      ast.traverse({
-        OptionalCallExpression(optPath) {
-          const nsInfo = getTaroNamespaceCall(...)
-          if (nsInfo && apis.has(flatName)) {
-            optPath.replaceWith(t.callExpression(
-              optPath.node.callee,
-              optPath.node.arguments
-            ))
-          }
-        }
-      })
-    }
-  }
-}
-```
-
-#### 3. `CallExpression|OptionalCallExpression` visitor
-
-主遍历中的兜底处理，使用 `getTaroNamespaceCall` 识别命名空间 API 调用并替换为扁平标识符：
-
-```ts
-'CallExpression|OptionalCallExpression'(ast) {
-  const nsInfo = getTaroNamespaceCall(t, callee, taroName, this.file)
-  if (nsInfo && this.apis.has(flatName)) {
-    // 替换为扁平标识符，如 _JDMTA_isTrafficMapEnable
-    if (t.isOptionalCallExpression(ast.node)) {
-      ast.replaceWith(t.callExpression(identifier, ast.node.arguments))
-    } else {
-      ast.node.callee = identifier
-    }
-  }
-}
-```
-
-#### 4. `MemberExpression|OptionalMemberExpression` visitor
-
-处理非调用场景下的命名空间属性访问（如 `const fn = Taro.JDMTA.isTrafficMapEnable`）。
-
-### 编译结果
-
-```ts
-// 编译前（任意可选链组合）
-import Taro from '@tarojs/taro'
-Taro.JDMTA.isTrafficMapEnable?.()
-  .then(res => console.log(res))
-  .catch(err => console.log(err))
-
-// 编译后
-import { JDMTA_isTrafficMapEnable as _JDMTA_isTrafficMapEnable } from '@tarojs/taro-h5'
-_JDMTA_isTrafficMapEnable()
-  .then(res => console.log(res))
-  .catch(err => console.log(err))
-```
-
-## 为什么不能靠调整插件执行顺序解决
-
-`transform-taroapi` 本身就在 `@babel/plugin-transform-optional-chaining` 之前执行（plugins 在 presets 之前）。但由于 Babel 的合并遍历模型：
-
-- **同节点竞争**：插件顺序靠前的先触发 → `transform-taroapi` 赢
-- **父子节点竞争**：父节点先被访问 → `optional-chaining` 在父节点上改写整棵子树 → `transform-taroapi` 输
-
-可选链的链式调用（`.then()/.catch()`）恰好触发了"父子节点竞争"场景。`Program.enter` 中的独立子遍历绕过了这个问题——在主遍历开始前就完成了可选链降级，无需和其他插件竞争。
-
-## 调试方法
-
-设置环境变量 `JDAPI_DEBUG_TAROAPI=true` 可以开启调试日志，观察预扫描和命名空间 API 匹配的情况：
-
-```bash
-JDAPI_DEBUG_TAROAPI=true npm run dev:h5
-```
-
-输出示例：
-```
-[jdapi-core-taroapi] pre-transform: strip optional call for JDMTA_isTrafficMapEnable in file: /src/pages/index.tsx
-[jdapi-core-taroapi] getTaroNamespaceCall hit: JDMTA_isTrafficMapEnable file = /src/pages/index.tsx
-```