miaoda-expo-devkit 0.1.1-beta.1

package/README.md

@@ -0,0 +1,267 @@
+# miaoda-expo-devkit
+
+Expo / React Native 开发环境工具集，通过 Metro 构建层注入以下能力：
+
+- **Sentry DSN 替换** — 拦截 `@sentry/react-native`，将真实 DSN 替换为无害 stub，防止开发期错误事件发送到 Sentry 服务器
+- **错误 / 网络捕获** — 内置 `SentryCapture`，自动调用 Metro `/symbolicate` 还原源码位置并输出到 `console.warn`
+- **Bundle 首部注入** — 在 expo-router 初始化之前执行自定义脚本
+- **HMR postMessage 控制** — 通过 `window.postMessage` 在运行时启动或停止 Fast Refresh
+- **LogBox 屏蔽** — web 平台禁用 Expo 全屏错误遮罩
+
+## 安装
+
+在 pnpm workspace 中，将包添加到应用的依赖：
+
+```json
+// your-app/package.json
+{
+  "dependencies": {
+    "miaoda-expo-devkit": "workspace:*"
+  }
+}
+```
+
+```sh
+pnpm install
+```
+
+## 使用
+
+### Metro 配置
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+const { withDevStubs, withEntryInjection } = require('miaoda-expo-devkit/metro');
+
+const config = getDefaultConfig(__dirname);
+module.exports = withEntryInjection(withDevStubs(config));
+```
+
+支持与其他 Metro wrapper 链式组合：
+
+```js
+module.exports = withNativeWind(withEntryInjection(withDevStubs(config)), { input: './global.css' });
+```
+
+### Sentry 初始化
+
+照常调用 `Sentry.init`，stub 自动注入内置捕获器，无需额外配置：
+
+```ts
+// app/_layout.tsx
+import * as Sentry from '@sentry/react-native';
+
+Sentry.init({
+  dsn: 'https://your-key@sentry.io/your-project',
+  // stub 自动拦截 beforeSend / beforeBreadcrumb，错误摘要输出到 console.warn
+});
+```
+
+#### 自定义回调（可选）
+
+传入自己的 `beforeSend` / `beforeBreadcrumb`，会在内置捕获器之后串联执行：
+
+```ts
+import * as Sentry from '@sentry/react-native';
+import { SentryCapture } from 'miaoda-expo-devkit';
+import type { ErrorCaptureInfo, NetworkCaptureInfo } from 'miaoda-expo-devkit';
+
+const capture = new SentryCapture({
+  onError(info: ErrorCaptureInfo) {
+    console.log('Error at:', info.symbolicatedFrames?.[0]);
+  },
+  onNetwork(info: NetworkCaptureInfo) {
+    console.log('Network:', info.method, info.url, info.statusCode);
+  },
+});
+
+Sentry.init({
+  dsn: 'https://your-key@sentry.io/your-project',
+  beforeSend: capture.beforeSend,
+  beforeBreadcrumb: capture.beforeBreadcrumb,
+});
+```
+
+### HMR postMessage 控制
+
+`withEntryInjection` 会在 bundle 首部注入脚本，该脚本安装一个 `window.postMessage` 监听器，可在运行时控制 Fast Refresh：
+
+```ts
+// 停止 HMR（暂停 Fast Refresh，WebSocket 连接保持）
+window.postMessage({ type: 'devkit:hmr', action: 'disable' }, '*');
+
+// 恢复 HMR（flush 期间积压的所有更新）
+window.postMessage({ type: 'devkit:hmr', action: 'enable' }, '*');
+```
+
+当前 HMR 状态可通过全局标记读取：
+
+```ts
+window.__DEVKIT_HMR_ENABLED__  // true | false
+```
+
+> HMR 客户端调用仅在 `__DEV__` 模式下生效。全局标记在静态导出（生产构建）下同样存在，可用于测试验证。
+
+## API
+
+### `withDevStubs(config)`
+
+从 `miaoda-expo-devkit/metro` 引入。
+
+将 Sentry DSN 替换 stub 和 LogBox 屏蔽注入到 Metro config：
+
+- **所有平台**：将 `@sentry/react-native` 重定向到内置 stub
+- **web 平台**：将 `@expo/log-box` 和 `ErrorOverlayWebControls` 重定向到 no-op stub
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `config` | `MetroConfig` | 来自 `getDefaultConfig` 或 `getSentryExpoConfig` 的 Metro config |
+
+---
+
+### `withEntryInjection(config, options?)`
+
+从 `miaoda-expo-devkit/metro` 引入。
+
+在 expo-router 启动前注入脚本，注入内容（`dist/stubs/entry-inject.js`）：
+
+1. 设置 `globalThis.__DEVKIT_INJECTED__ = true`
+2. 安装 HMR postMessage 控制器（`window.addEventListener('message', ...)`）
+3. 打印 `[DevKit] Hello World`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `config` | `MetroConfig` | Metro config 对象 |
+| `options` | `InjectOptions?` | 预留选项（当前无字段） |
+
+---
+
+### `new SentryCapture(options)`
+
+从 `miaoda-expo-devkit` 引入。
+
+用于自定义捕获行为。stub 内置了一个默认实例（输出到 `console.warn`），此类用于叠加自定义处理逻辑。
+
+| 选项 | 类型 | 说明 |
+|---|---|---|
+| `onError` | `(info: ErrorCaptureInfo) => void` | 捕获到错误时触发，携带符号化后的调用栈 |
+| `onNetwork` | `(info: NetworkCaptureInfo) => void` | 捕获到 HTTP 请求时触发 |
+| `symbolicator` | `MetroSymbolicator` | 可选，单测时注入 mock 以隔离网络依赖 |
+
+构造完成后，将绑定方法传给 `Sentry.init`：
+
+```ts
+Sentry.init({
+  beforeSend: capture.beforeSend,
+  beforeBreadcrumb: capture.beforeBreadcrumb,
+});
+```
+
+#### `ErrorCaptureInfo`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `message` | `string` | 错误信息 |
+| `symbolicatedFrames` | `MetroFrame[] \| null` | 经 Metro 符号化后还原到源码位置的调用栈帧 |
+| `componentStack` | `string \| null` | React 组件调用栈（ErrorBoundary 捕获的错误才有值） |
+| `mechanismType` | `string \| null` | Sentry 捕获方式：`'onerror'`、`'generic'`、`'auto.function.react.error_boundary'` 等 |
+
+#### `NetworkCaptureInfo`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `method` | `string \| null` | HTTP 方法 |
+| `url` | `string \| null` | 请求 URL |
+| `statusCode` | `number \| null` | HTTP 状态码（连接级失败为 `null`） |
+
+---
+
+### `new MetroSymbolicator(options?)`
+
+从 `miaoda-expo-devkit` 引入。
+
+通过 Metro `/symbolicate` 接口将 bundle 行列号还原为源码位置。`SentryCapture` 内部已默认使用，主要用途是单测时注入 mock。
+
+| 选项 | 类型 | 说明 |
+|---|---|---|
+| `baseUrl` | `string` | Metro server 地址。不传则从 `NativeModules.SourceCode.scriptURL` 自动推断，fallback 到 `localhost:8081`。 |
+
+**单测示例：**
+
+```ts
+const mockSym = {
+  parseErrorStack: jest.fn(() => []),
+  symbolicate: jest.fn(async () => null),
+};
+const onError = jest.fn();
+const capture = new SentryCapture({ onError, symbolicator: mockSym });
+
+await capture.beforeSend(fakeEvent, { originalException: new Error('oops') });
+
+expect(onError).toHaveBeenCalledWith(
+  expect.objectContaining({ message: 'oops' }),
+);
+```
+
+---
+
+## 全局标记
+
+注入脚本在 bundle 执行时（早于任何 React 代码）写入以下全局变量，可用于 E2E 测试断言：
+
+| 变量 | 类型 | 说明 |
+|---|---|---|
+| `window.__DEVKIT_INJECTED__` | `true` | 注入脚本已执行（由 `withEntryInjection` 保证） |
+| `window.__DEVKIT_HMR_ENABLED__` | `boolean` | 当前 HMR 状态，随 postMessage 消息实时更新 |
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `SENTRY_OVERRIDE_DSN` | `https://stubPublicKey@o0.ingest.sentry.io/0` | 覆盖 Sentry DSN，可指向本地 relay 等自定义端点 |
+
+## 工作原理
+
+```
+metro.config.js
+  └─ withEntryInjection(withDevStubs(config))
+       │
+       ├─ withDevStubs → resolver.resolveRequest
+       │    ├─ @sentry/react-native        →  dist/stubs/sentry-react-native-stub.js  （全平台）
+       │    └─ @expo/log-box               →  dist/stubs/no-op-logbox.js              （仅 web）
+       │
+       └─ withEntryInjection → resolver.resolveRequest
+            └─ expo-router/entry-classic   →  dist/stubs/expo-router-entry-stub.js
+                 ├─ require('./entry-inject')           ← 注入脚本（bundle 首部执行）
+                 │    ├─ globalThis.__DEVKIT_INJECTED__ = true
+                 │    ├─ setupHMRMessageControl()       ← 安装 postMessage 监听器
+                 │    └─ console.log('[DevKit] Hello World')
+                 └─ require('expo-router/entry-classic') ← 原 expo-router 入口
+
+setupHMRMessageControl()
+  └─ window.addEventListener('message', handler)
+       ├─ { type: 'devkit:hmr', action: 'disable' }
+       │    ├─ globalThis.__DEVKIT_HMR_ENABLED__ = false
+       │    └─ hmrClient.disable()   （仅 __DEV__）
+       └─ { type: 'devkit:hmr', action: 'enable' }
+            ├─ globalThis.__DEVKIT_HMR_ENABLED__ = true
+            └─ hmrClient.enable()    （仅 __DEV__）
+
+sentry-react-native-stub.js
+  └─ init(options)
+       └─ RealSentry.init({ ...options, dsn: OVERRIDE_DSN, beforeSend, beforeBreadcrumb })
+            ├─ _capture.beforeSend(event, hint)         ← 内置 SentryCapture（自动注入）
+            │    ├─ MetroSymbolicator.symbolicate()     →  POST /symbolicate
+            │    └─ onError({ message, frames, ... })   →  console.warn（默认）
+            └─ options.beforeSend?(event, hint)         ← 调用方自定义（可选，串联执行）
+```
+
+## Package Exports
+
+| 子路径 | 文件 | 内容 |
+|---|---|---|
+| `.` | `dist/index.js` | `SentryCapture`、`MetroSymbolicator`、全部类型 |
+| `./metro` | `dist/metro.js` | `withDevStubs`、`withEntryInjection` |
+| `./sentry-react-native-stub` | `dist/stubs/sentry-react-native-stub.js` | `@sentry/react-native` 模块替换 stub |
+| `./no-op-logbox` | `dist/stubs/no-op-logbox.js` | LogBox no-op stub |

package/dist/babel/plugin-jsx-source.js

@@ -0,0 +1,91 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/babel/plugin-jsx-source.ts
+var plugin_jsx_source_exports = {};
+__export(plugin_jsx_source_exports, {
+  default: () => babelPluginJsxSource
+});
+module.exports = __toCommonJS(plugin_jsx_source_exports);
+function createSourceObject(t, fileName, lineNumber, columnNumber) {
+  return t.objectExpression([
+    t.objectProperty(t.identifier("fileName"), t.stringLiteral(fileName)),
+    t.objectProperty(t.identifier("lineNumber"), t.numericLiteral(lineNumber)),
+    t.objectProperty(t.identifier("columnNumber"), t.numericLiteral(columnNumber))
+  ]);
+}
+function hasSourceAttribute(t, attributes) {
+  return attributes.some(
+    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: SOURCE_PROP_NAME })
+  );
+}
+var SOURCE_PROP_NAME = "__jsxsource";
+var REACT_SPECIAL_COMPONENTS = /* @__PURE__ */ new Set(["Fragment", "Suspense", "StrictMode", "Profiler"]);
+function shouldSkipElement(t, name) {
+  if (t.isJSXIdentifier(name)) {
+    return REACT_SPECIAL_COMPONENTS.has(name.name);
+  }
+  if (t.isJSXMemberExpression(name)) {
+    const propertyName = name.property.name;
+    if (t.isJSXIdentifier(name.object) && name.object.name === "React") {
+      return REACT_SPECIAL_COMPONENTS.has(propertyName);
+    }
+    if (propertyName === "Provider" || propertyName === "Consumer") {
+      return true;
+    }
+  }
+  if (t.isJSXNamespacedName(name)) {
+    return true;
+  }
+  return false;
+}
+function babelPluginJsxSource({
+  types: t
+}) {
+  return {
+    name: "babel-plugin-jsx-source",
+    visitor: {
+      JSXOpeningElement(path, state) {
+        const { opts, filename } = state;
+        if (!filename) return;
+        if (filename.includes("node_modules")) return;
+        if (opts.excludePaths?.some((p) => filename.includes(p))) return;
+        if (shouldSkipElement(t, path.node.name)) return;
+        if (hasSourceAttribute(t, path.node.attributes)) return;
+        const loc = path.node.loc;
+        if (!loc) return;
+        let filePath = filename;
+        if (opts.rootDir && filename.startsWith(opts.rootDir)) {
+          filePath = filename.slice(opts.rootDir.length);
+          if (filePath.startsWith("/")) {
+            filePath = filePath.slice(1);
+          }
+        }
+        const sourceAttribute = t.jsxAttribute(
+          t.jsxIdentifier(SOURCE_PROP_NAME),
+          t.jsxExpressionContainer(
+            createSourceObject(t, filePath, loc.start.line, loc.start.column)
+          )
+        );
+        path.node.attributes.push(sourceAttribute);
+      }
+    }
+  };
+}
+//# sourceMappingURL=plugin-jsx-source.js.map

package/dist/babel/plugin-jsx-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/babel/plugin-jsx-source.ts"],"sourcesContent":["/**\n * babel-plugin-jsx-source\n *\n * 为 JSX 元素注入 __jsxsource 属性，包含文件路径和行列号信息，用于开发调试。\n *\n * 转换前：\n *   <View style={styles.container} />\n *\n * 转换后：\n *   <View style={styles.container} __jsxsource={{ fileName: \"/path/to/file.tsx\", lineNumber: 10, columnNumber: 4 }} />\n *\n * 用法（babel.config.js）：\n *\n *   module.exports = {\n *     plugins: [\n *       ['miaoda-expo-devkit/babel-plugin-jsx-source', { rootDir: __dirname }]\n *     ]\n *   };\n *\n * 选项：\n *   - rootDir: 项目根目录，用于计算相对路径（可选，默认使用绝对路径）\n */\n\nimport type { PluginObj, NodePath, types as BabelTypes } from '@babel/core';\n\n/** 插件选项 */\nexport interface JsxSourcePluginOptions {\n  /** 项目根目录，用于计算相对路径。若不提供则使用绝对路径 */\n  rootDir?: string;\n  /** 需要跳过注入的路径模式列表（相对于 rootDir 的路径片段） */\n  excludePaths?: string[];\n}\n\n/** 创建 __jsxsource 对象的属性值 */\nfunction createSourceObject(\n  t: typeof BabelTypes,\n  fileName: string,\n  lineNumber: number,\n  columnNumber: number\n): BabelTypes.ObjectExpression {\n  return t.objectExpression([\n    t.objectProperty(t.identifier('fileName'), t.stringLiteral(fileName)),\n    t.objectProperty(t.identifier('lineNumber'), t.numericLiteral(lineNumber)),\n    t.objectProperty(t.identifier('columnNumber'), t.numericLiteral(columnNumber)),\n  ]);\n}\n\n/** 检查 JSX 元素是否已有 __jsxsource 属性 */\nfunction hasSourceAttribute(\n  t: typeof BabelTypes,\n  attributes: (BabelTypes.JSXAttribute | BabelTypes.JSXSpreadAttribute)[]\n): boolean {\n  return attributes.some(\n    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: SOURCE_PROP_NAME })\n  );\n}\n\n/**\n * React 内置特殊组件，不接受任意 props\n */\n/** 注入的 prop 名称 */\nconst SOURCE_PROP_NAME = '__jsxsource';\n\nconst REACT_SPECIAL_COMPONENTS = new Set(['Fragment', 'Suspense', 'StrictMode', 'Profiler']);\n\n/**\n * 检查是否为需要跳过的特殊组件\n *\n * 跳过的情况：\n * 1. React 特殊组件: Fragment, Suspense, StrictMode, Profiler\n * 2. React 命名空间组件: React.Fragment, React.Suspense 等\n * 3. Context Provider/Consumer: *.Provider, *.Consumer\n * 4. JSXNamespacedName: <svg:rect> 等\n */\nfunction shouldSkipElement(\n  t: typeof BabelTypes,\n  name: BabelTypes.JSXOpeningElement['name']\n): boolean {\n  // 简单标识符: <Fragment>, <Suspense> 等\n  if (t.isJSXIdentifier(name)) {\n    return REACT_SPECIAL_COMPONENTS.has(name.name);\n  }\n\n  // 成员表达式: <React.Fragment>, <Context.Provider> 等\n  if (t.isJSXMemberExpression(name)) {\n    const propertyName = name.property.name;\n\n    // React.* 特殊组件\n    if (t.isJSXIdentifier(name.object) && name.object.name === 'React') {\n      return REACT_SPECIAL_COMPONENTS.has(propertyName);\n    }\n\n    // *.Provider 和 *.Consumer (Context 组件)\n    if (propertyName === 'Provider' || propertyName === 'Consumer') {\n      return true;\n    }\n  }\n\n  // JSXNamespacedName (如 <svg:rect>) - XML 命名空间元素，跳过\n  if (t.isJSXNamespacedName(name)) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Babel 插件：为 JSX 元素注入 __jsxsource 属性\n */\nexport default function babelPluginJsxSource({\n  types: t,\n}: {\n  types: typeof BabelTypes;\n}): PluginObj {\n  return {\n    name: 'babel-plugin-jsx-source',\n    visitor: {\n      JSXOpeningElement(\n        path: NodePath<BabelTypes.JSXOpeningElement>,\n        state: { opts: JsxSourcePluginOptions; filename?: string }\n      ) {\n        const { opts, filename } = state;\n\n        // 没有文件名信息则跳过\n        if (!filename) return;\n\n        // 忽略 node_modules\n        if (filename.includes('node_modules')) return;\n\n        // 忽略用户配置的排除路径\n        if (opts.excludePaths?.some((p) => filename.includes(p))) return;\n\n        // 特殊组件不能有自定义属性，跳过\n        if (shouldSkipElement(t, path.node.name)) return;\n\n        // 已有 __jsxsource 属性则跳过\n        if (hasSourceAttribute(t, path.node.attributes)) return;\n\n        // 获取位置信息\n        const loc = path.node.loc;\n        if (!loc) return;\n\n        // 计算文件路径（相对路径或绝对路径）\n        let filePath = filename;\n        if (opts.rootDir && filename.startsWith(opts.rootDir)) {\n          filePath = filename.slice(opts.rootDir.length);\n          // 移除开头的 /\n          if (filePath.startsWith('/')) {\n            filePath = filePath.slice(1);\n          }\n        }\n\n        // 创建 __jsxsource 属性\n        const sourceAttribute = t.jsxAttribute(\n          t.jsxIdentifier(SOURCE_PROP_NAME),\n          t.jsxExpressionContainer(\n            createSourceObject(t, filePath, loc.start.line, loc.start.column)\n          )\n        );\n\n        // 添加到属性列表末尾\n        path.node.attributes.push(sourceAttribute);\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAkCA,SAAS,mBACP,GACA,UACA,YACA,cAC6B;AAC7B,SAAO,EAAE,iBAAiB;AAAA,IACxB,EAAE,eAAe,EAAE,WAAW,UAAU,GAAG,EAAE,cAAc,QAAQ,CAAC;AAAA,IACpE,EAAE,eAAe,EAAE,WAAW,YAAY,GAAG,EAAE,eAAe,UAAU,CAAC;AAAA,IACzE,EAAE,eAAe,EAAE,WAAW,cAAc,GAAG,EAAE,eAAe,YAAY,CAAC;AAAA,EAC/E,CAAC;AACH;AAGA,SAAS,mBACP,GACA,YACS;AACT,SAAO,WAAW;AAAA,IAChB,CAAC,SAAS,EAAE,eAAe,IAAI,KAAK,EAAE,gBAAgB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAAA,EAC7F;AACF;AAMA,IAAM,mBAAmB;AAEzB,IAAM,2BAA2B,oBAAI,IAAI,CAAC,YAAY,YAAY,cAAc,UAAU,CAAC;AAW3F,SAAS,kBACP,GACA,MACS;AAET,MAAI,EAAE,gBAAgB,IAAI,GAAG;AAC3B,WAAO,yBAAyB,IAAI,KAAK,IAAI;AAAA,EAC/C;AAGA,MAAI,EAAE,sBAAsB,IAAI,GAAG;AACjC,UAAM,eAAe,KAAK,SAAS;AAGnC,QAAI,EAAE,gBAAgB,KAAK,MAAM,KAAK,KAAK,OAAO,SAAS,SAAS;AAClE,aAAO,yBAAyB,IAAI,YAAY;AAAA,IAClD;AAGA,QAAI,iBAAiB,cAAc,iBAAiB,YAAY;AAC9D,aAAO;AAAA,IACT;AAAA,EACF;AAGA,MAAI,EAAE,oBAAoB,IAAI,GAAG;AAC/B,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAKe,SAAR,qBAAsC;AAAA,EAC3C,OAAO;AACT,GAEc;AACZ,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,MACP,kBACE,MACA,OACA;AACA,cAAM,EAAE,MAAM,SAAS,IAAI;AAG3B,YAAI,CAAC,SAAU;AAGf,YAAI,SAAS,SAAS,cAAc,EAAG;AAGvC,YAAI,KAAK,cAAc,KAAK,CAAC,MAAM,SAAS,SAAS,CAAC,CAAC,EAAG;AAG1D,YAAI,kBAAkB,GAAG,KAAK,KAAK,IAAI,EAAG;AAG1C,YAAI,mBAAmB,GAAG,KAAK,KAAK,UAAU,EAAG;AAGjD,cAAM,MAAM,KAAK,KAAK;AACtB,YAAI,CAAC,IAAK;AAGV,YAAI,WAAW;AACf,YAAI,KAAK,WAAW,SAAS,WAAW,KAAK,OAAO,GAAG;AACrD,qBAAW,SAAS,MAAM,KAAK,QAAQ,MAAM;AAE7C,cAAI,SAAS,WAAW,GAAG,GAAG;AAC5B,uBAAW,SAAS,MAAM,CAAC;AAAA,UAC7B;AAAA,QACF;AAGA,cAAM,kBAAkB,EAAE;AAAA,UACxB,EAAE,cAAc,gBAAgB;AAAA,UAChC,EAAE;AAAA,YACA,mBAAmB,GAAG,UAAU,IAAI,MAAM,MAAM,IAAI,MAAM,MAAM;AAAA,UAClE;AAAA,QACF;AAGA,aAAK,KAAK,WAAW,KAAK,eAAe;AAAA,MAC3C;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+import { ErrorEvent, EventHint, Breadcrumb, BreadcrumbHint } from '@sentry/core';
+
+/**
+ * Sentry Capture 模块
+ *
+ * 提供 Metro 符号化（MetroSymbolicator）和 Sentry 事件捕获（SentryCapture）。
+ */
+
+/** Metro /symbolicate 接口的帧格式（请求与响应共用）。 */
+interface MetroFrame {
+    file: string;
+    lineNumber: number;
+    column: number;
+    methodName: string;
+}
+/** SentryCapture.onError 回调参数 */
+interface ErrorCaptureInfo {
+    message: string;
+    symbolicatedFrames: MetroFrame[] | null;
+    componentStack: string | null;
+    /** Sentry Mechanism.type，如 'onerror' / 'generic' / 'auto.function.react.error_boundary' */
+    mechanismType: string | null;
+}
+/** SentryCapture.onNetwork 回调参数 */
+interface NetworkCaptureInfo {
+    method: string | null;
+    url: string | null;
+    statusCode: number | null;
+}
+interface SentryCaptureOptions {
+    onError?: (info: ErrorCaptureInfo) => void;
+    onNetwork?: (info: NetworkCaptureInfo) => void;
+    /** 可注入 mock 实例以在单元测试中隔离网络依赖 */
+    symbolicator?: MetroSymbolicator;
+}
+/**
+ * Metro 符号化器。
+ * 将 bundle 行列号还原为源码位置（通过 Metro /symbolicate 接口）。
+ *
+ * @example
+ * const sym = new MetroSymbolicator();
+ *
+ * @example
+ * // 单测：注入 baseUrl 并 mock fetch
+ * const sym = new MetroSymbolicator({ baseUrl: 'http://localhost:8081' });
+ * global.fetch = jest.fn().mockResolvedValue({ ok: true, json: async () => ({ stack: [...] }) });
+ */
+declare class MetroSymbolicator {
+    readonly baseUrl: string;
+    constructor({ baseUrl }?: {
+        baseUrl?: string;
+    });
+    /**
+     * 从 NativeModules.SourceCode.scriptURL 推断 Metro server base URL。
+     * web 平台使用相对路径；native 回退到 localhost:8081。
+     */
+    private static _getDefaultBaseUrl;
+    /**
+     * 解析 Error.stack 字符串为 Metro 所需的帧数组。
+     *
+     * 使用 stacktrace-parser 覆盖各 JS 引擎的格式：
+     *   V8/Node.js/Hermes(新)：at methodName (url:line:col)
+     *   Gecko/Firefox/Hermes(旧)：methodName@url:line:col
+     *   JavaScriptCore(iOS)：methodName@url:line:col
+     *
+     * 无法符号化的帧（file 或 lineNumber 为 null）会被过滤掉。
+     */
+    parseErrorStack(stack: string): MetroFrame[];
+    /**
+     * 将帧列表发送到 Metro /symbolicate，返回符号化后的帧数组。
+     */
+    symbolicate(stack: MetroFrame[]): Promise<MetroFrame[] | null>;
+}
+/**
+ * Sentry 事件捕获器。
+ * 封装 beforeSend / beforeBreadcrumb 逻辑，通过注入的回调将事件数据交给调用方处理。
+ *
+ * @example
+ * const capture = new SentryCapture({
+ *   onError(info) { console.log(info.message, info.symbolicatedFrames); },
+ *   onNetwork(info) { console.log(info.method, info.url, info.statusCode); },
+ * });
+ * Sentry.init({ dsn: '...', beforeSend: capture.beforeSend, beforeBreadcrumb: capture.beforeBreadcrumb });
+ *
+ * @example
+ * // 单测：注入 mock symbolicator
+ * const mockSym = { parseErrorStack: jest.fn(() => []), symbolicate: jest.fn(async () => null) };
+ * const onError = jest.fn();
+ * const capture = new SentryCapture({ onError, symbolicator: mockSym });
+ * await capture.beforeSend(fakeEvent, { originalException: new Error('oops') });
+ * expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: 'oops' }));
+ */
+declare class SentryCapture {
+    private readonly onError;
+    private readonly onNetwork;
+    private readonly symbolicator;
+    constructor({ onError, onNetwork, symbolicator }?: SentryCaptureOptions);
+    /**
+     * Sentry beforeSend hook。
+     * 优先使用原始 Error.stack 进行符号化；若无法获取则回退到 Sentry 事件帧。
+     * 符号化完成后触发 onError 回调，原样返回 event。
+     */
+    beforeSend(event: ErrorEvent, hint: EventHint): Promise<ErrorEvent>;
+    /**
+     * Sentry beforeBreadcrumb hook。
+     * 识别 HTTP 类型的 breadcrumb，触发 onNetwork 回调，原样返回 breadcrumb。
+     */
+    beforeBreadcrumb(breadcrumb: Breadcrumb, _hint?: BreadcrumbHint): Breadcrumb;
+}
+
+export { type ErrorCaptureInfo, type MetroFrame, MetroSymbolicator, type NetworkCaptureInfo, SentryCapture, type SentryCaptureOptions };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { ErrorEvent, EventHint, Breadcrumb, BreadcrumbHint } from '@sentry/core';
+
+/**
+ * Sentry Capture 模块
+ *
+ * 提供 Metro 符号化（MetroSymbolicator）和 Sentry 事件捕获（SentryCapture）。
+ */
+
+/** Metro /symbolicate 接口的帧格式（请求与响应共用）。 */
+interface MetroFrame {
+    file: string;
+    lineNumber: number;
+    column: number;
+    methodName: string;
+}
+/** SentryCapture.onError 回调参数 */
+interface ErrorCaptureInfo {
+    message: string;
+    symbolicatedFrames: MetroFrame[] | null;
+    componentStack: string | null;
+    /** Sentry Mechanism.type，如 'onerror' / 'generic' / 'auto.function.react.error_boundary' */
+    mechanismType: string | null;
+}
+/** SentryCapture.onNetwork 回调参数 */
+interface NetworkCaptureInfo {
+    method: string | null;
+    url: string | null;
+    statusCode: number | null;
+}
+interface SentryCaptureOptions {
+    onError?: (info: ErrorCaptureInfo) => void;
+    onNetwork?: (info: NetworkCaptureInfo) => void;
+    /** 可注入 mock 实例以在单元测试中隔离网络依赖 */
+    symbolicator?: MetroSymbolicator;
+}
+/**
+ * Metro 符号化器。
+ * 将 bundle 行列号还原为源码位置（通过 Metro /symbolicate 接口）。
+ *
+ * @example
+ * const sym = new MetroSymbolicator();
+ *
+ * @example
+ * // 单测：注入 baseUrl 并 mock fetch
+ * const sym = new MetroSymbolicator({ baseUrl: 'http://localhost:8081' });
+ * global.fetch = jest.fn().mockResolvedValue({ ok: true, json: async () => ({ stack: [...] }) });
+ */
+declare class MetroSymbolicator {
+    readonly baseUrl: string;
+    constructor({ baseUrl }?: {
+        baseUrl?: string;
+    });
+    /**
+     * 从 NativeModules.SourceCode.scriptURL 推断 Metro server base URL。
+     * web 平台使用相对路径；native 回退到 localhost:8081。
+     */
+    private static _getDefaultBaseUrl;
+    /**
+     * 解析 Error.stack 字符串为 Metro 所需的帧数组。
+     *
+     * 使用 stacktrace-parser 覆盖各 JS 引擎的格式：
+     *   V8/Node.js/Hermes(新)：at methodName (url:line:col)
+     *   Gecko/Firefox/Hermes(旧)：methodName@url:line:col
+     *   JavaScriptCore(iOS)：methodName@url:line:col
+     *
+     * 无法符号化的帧（file 或 lineNumber 为 null）会被过滤掉。
+     */
+    parseErrorStack(stack: string): MetroFrame[];
+    /**
+     * 将帧列表发送到 Metro /symbolicate，返回符号化后的帧数组。
+     */
+    symbolicate(stack: MetroFrame[]): Promise<MetroFrame[] | null>;
+}
+/**
+ * Sentry 事件捕获器。
+ * 封装 beforeSend / beforeBreadcrumb 逻辑，通过注入的回调将事件数据交给调用方处理。
+ *
+ * @example
+ * const capture = new SentryCapture({
+ *   onError(info) { console.log(info.message, info.symbolicatedFrames); },
+ *   onNetwork(info) { console.log(info.method, info.url, info.statusCode); },
+ * });
+ * Sentry.init({ dsn: '...', beforeSend: capture.beforeSend, beforeBreadcrumb: capture.beforeBreadcrumb });
+ *
+ * @example
+ * // 单测：注入 mock symbolicator
+ * const mockSym = { parseErrorStack: jest.fn(() => []), symbolicate: jest.fn(async () => null) };
+ * const onError = jest.fn();
+ * const capture = new SentryCapture({ onError, symbolicator: mockSym });
+ * await capture.beforeSend(fakeEvent, { originalException: new Error('oops') });
+ * expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: 'oops' }));
+ */
+declare class SentryCapture {
+    private readonly onError;
+    private readonly onNetwork;
+    private readonly symbolicator;
+    constructor({ onError, onNetwork, symbolicator }?: SentryCaptureOptions);
+    /**
+     * Sentry beforeSend hook。
+     * 优先使用原始 Error.stack 进行符号化；若无法获取则回退到 Sentry 事件帧。
+     * 符号化完成后触发 onError 回调，原样返回 event。
+     */
+    beforeSend(event: ErrorEvent, hint: EventHint): Promise<ErrorEvent>;
+    /**
+     * Sentry beforeBreadcrumb hook。
+     * 识别 HTTP 类型的 breadcrumb，触发 onNetwork 回调，原样返回 breadcrumb。
+     */
+    beforeBreadcrumb(breadcrumb: Breadcrumb, _hint?: BreadcrumbHint): Breadcrumb;
+}
+
+export { type ErrorCaptureInfo, type MetroFrame, MetroSymbolicator, type NetworkCaptureInfo, SentryCapture, type SentryCaptureOptions };