@guomain/monitor-plugins 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @gm Monitor SDK
+
+前端错误监控：运行时错误、Promise、资源加载、接口异常、Vue/React、手动上报、catch 自动采集（需 Vite 插件）。
+
+## 安装
+
+```sh
+pnpm add @guomain/monitor-web
+pnpm add -D @guomain/monitor-plugins @guomain/monitor-types
+```
+
+## 快速开始
+
+```ts
+import { createWebMonitor } from '@guomain/monitor-web'
+
+const monitor = createWebMonitor({
+  appId: 'your-app',
+  dsn: '/api/monitor',
+  vue: { app }
+})
+
+globalThis.__GM_MONITOR__ = monitor
+monitor.start()
+```
+
+完整说明见仓库内 `SDK.md` 与 `PUBLISH.md`。

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from './react';
+export * from './vite';
+export * from './vue';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,OAAO,CAAA"}

package/index.js

@@ -0,0 +1,3 @@
+export * from './react';
+export * from './vite';
+export * from './vue';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+http://192.168.200.220/GomainFE/stamp.git",
+    "directory": "monitor/packages/monitor-plugins"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "name": "@guomain/monitor-plugins",
+  "description": "Build-time plugins for @gm monitor SDK (Vite catch injection, Vue/React helpers)",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./vite": {
+      "types": "./vite/index.d.ts",
+      "import": "./vite/index.js",
+      "default": "./vite/index.js"
+    },
+    "./vue": {
+      "types": "./vue/index.d.ts",
+      "import": "./vue/index.js",
+      "default": "./vue/index.js"
+    },
+    "./react": {
+      "types": "./react/index.d.ts",
+      "import": "./react/index.js",
+      "default": "./react/index.js"
+    }
+  },
+  "dependencies": {
+    "@guomain/monitor-core": "^0.1.0",
+    "@guomain/monitor-types": "^0.1.0",
+    "@babel/generator": "^7.28.3",
+    "@babel/parser": "^7.28.4",
+    "@babel/traverse": "^7.28.4",
+    "@babel/types": "^7.28.4"
+  },
+  "peerDependencies": {
+    "vite": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "files": [
+    "**/*"
+  ]
+}

package/react/index.d.ts

@@ -0,0 +1,9 @@
+import type { MonitorInstance, ReactElementLike, ReactRenderRoot } from '@guomain/monitor-types';
+/**
+ * 使用监控 ErrorBoundary 包装 React 渲染入口。
+ * @param monitor 当前监控实例。
+ * @param root React 渲染根节点。
+ * @param element 业务应用节点。
+ */
+export declare function renderReactWithMonitor(monitor: MonitorInstance, root: ReactRenderRoot, element: ReactElementLike): void;
+//# sourceMappingURL=index.d.ts.map

package/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAIhG;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,gBAAgB,QAG1B"}

package/react/index.js

@@ -0,0 +1,56 @@
+import { toErrorEvent } from '@guomain/monitor-core';
+const boundaryTypes = new WeakMap();
+/**
+ * 使用监控 ErrorBoundary 包装 React 渲染入口。
+ * @param monitor 当前监控实例。
+ * @param root React 渲染根节点。
+ * @param element 业务应用节点。
+ */
+export function renderReactWithMonitor(monitor, root, element) {
+    root.render(createReactBoundaryElement(getReactBoundaryType(monitor), element));
+}
+/**
+ * 获取当前监控实例对应的 React ErrorBoundary 类型。
+ * @param monitor 当前监控实例。
+ */
+function getReactBoundaryType(monitor) {
+    const cachedType = boundaryTypes.get(monitor);
+    if (cachedType) {
+        return cachedType;
+    }
+    class MonitorReactBoundary {
+        static getDerivedStateFromError() {
+            return { hasError: true };
+        }
+        constructor(props) {
+            this.state = { hasError: false };
+            this.props = props;
+        }
+        componentDidCatch(error, info) {
+            monitor.capture(toErrorEvent('react-error', error, { extra: { info } }));
+        }
+        render() {
+            return this.state.hasError ? null : this.props.children;
+        }
+    }
+    Object.defineProperty(MonitorReactBoundary.prototype, 'isReactComponent', {
+        value: {}
+    });
+    boundaryTypes.set(monitor, MonitorReactBoundary);
+    return MonitorReactBoundary;
+}
+/**
+ * 创建 React element 形态的边界节点。
+ * @param type React ErrorBoundary 类型。
+ * @param children 需要被边界包裹的业务节点。
+ */
+function createReactBoundaryElement(type, children) {
+    return {
+        $$typeof: Symbol.for('react.element'),
+        type,
+        key: null,
+        ref: null,
+        props: { children },
+        _owner: null
+    };
+}

package/vite/index.d.ts

@@ -0,0 +1,39 @@
+export interface MonitorCatchPluginOptions {
+    /** 是否启用 catch 注入，默认 false。 */
+    catch?: boolean;
+    /** 需要注入 catch 采集逻辑的文件路径。 */
+    include?: string[];
+    /** 需要排除的文件路径。 */
+    exclude?: string[];
+    /** 运行时挂载在 globalThis 上的监控实例变量名。 */
+    monitorVar?: string;
+}
+interface VitePluginLike {
+    name: string;
+    enforce?: 'pre' | 'post';
+    transform: (code: string, id: string) => {
+        code: string;
+        map: null;
+    } | null;
+}
+/**
+ * 创建 Vite 插件，基于 Babel AST 为 catch 代码注入监控采集。
+ * @param options 插件配置，catch 为 true 时才会按 include、exclude 和 monitorVar 注入。
+ */
+export declare function monitorCatchPlugin(options: MonitorCatchPluginOptions): VitePluginLike;
+/**
+ * 基于 Babel AST 为 catch 语句块注入 monitor.capture()。
+ *
+ * 注入逻辑：
+ * 1. 解析源码为 AST
+ * 2. 遍历所有 CatchClause 节点
+ * 3. 检查 catch 体内是否已包含上报调用，有则跳过
+ * 4. 在 catch 体首行插入 capture()，先于原有代码执行
+ *
+ * @param code 原始源码。
+ * @param monitorVar 运行时监控实例变量名。
+ * @param file 当前文件路径，用于上报排查。
+ */
+export declare function injectCatchCapture(code: string, monitorVar?: string, file?: string): string;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,yBAAyB;IACxC,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,iBAAiB;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACxB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;CAC5E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,cAAc,CAmCrF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,SAAmB,EAAE,IAAI,SAAK,GAAG,MAAM,CAkEjG"}

package/vite/index.js

@@ -0,0 +1,248 @@
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+import _generate from '@babel/generator';
+import * as t from '@babel/types';
+// @babel/traverse 和 @babel/generator 都是 CJS 包，解构导入
+const traverse = _traverse.default ?? _traverse;
+const generate = _generate.default ?? _generate;
+/**
+ * 创建 Vite 插件，基于 Babel AST 为 catch 代码注入监控采集。
+ * @param options 插件配置，catch 为 true 时才会按 include、exclude 和 monitorVar 注入。
+ */
+export function monitorCatchPlugin(options) {
+    const shouldInjectCatch = options.catch === true;
+    const monitorVar = options.monitorVar ?? '__GM_MONITOR__';
+    assertMonitorVar(monitorVar);
+    const include = (options.include ?? []).map(globToRegExp);
+    const exclude = (options.exclude ?? []).map(globToRegExp);
+    if (shouldInjectCatch && include.length === 0 && typeof console !== 'undefined') {
+        console.warn('[gm-monitor-catch] catch 注入已启用但未配置 include，不会注入任何文件');
+    }
+    return {
+        name: 'gm-monitor-catch',
+        enforce: 'post',
+        transform(code, id) {
+            if (!shouldInjectCatch) {
+                return null;
+            }
+            const normalizedId = normalizePath(id);
+            if (isSdkInternalPath(normalizedId)) {
+                return null;
+            }
+            if (!include.some(item => item.test(normalizedId))) {
+                return null;
+            }
+            if (exclude.some(item => item.test(normalizedId))) {
+                return null;
+            }
+            const nextCode = injectCatchCapture(code, monitorVar, normalizedId);
+            return nextCode === code ? null : { code: nextCode, map: null };
+        }
+    };
+}
+/**
+ * 基于 Babel AST 为 catch 语句块注入 monitor.capture()。
+ *
+ * 注入逻辑：
+ * 1. 解析源码为 AST
+ * 2. 遍历所有 CatchClause 节点
+ * 3. 检查 catch 体内是否已包含上报调用，有则跳过
+ * 4. 在 catch 体首行插入 capture()，先于原有代码执行
+ *
+ * @param code 原始源码。
+ * @param monitorVar 运行时监控实例变量名。
+ * @param file 当前文件路径，用于上报排查。
+ */
+export function injectCatchCapture(code, monitorVar = '__GM_MONITOR__', file = '') {
+    assertMonitorVar(monitorVar);
+    let ast;
+    try {
+        ast = parse(code, {
+            sourceType: 'unambiguous',
+            plugins: ['typescript', 'jsx', 'decorators-legacy'],
+            errorRecovery: true
+        });
+    }
+    catch {
+        return code;
+    }
+    let modified = false;
+    const visitor = {
+        CatchClause(path) {
+            const paramName = path.node.param
+                ? t.isIdentifier(path.node.param)
+                    ? path.node.param.name
+                    : t.isArrayPattern(path.node.param) || t.isObjectPattern(path.node.param)
+                        ? '__gmMonitorError'
+                        : null
+                : null;
+            const errorRef = paramName ?? '__gmMonitorError';
+            // 检查是否已有上报调用
+            if (hasMonitorCapture(path, monitorVar)) {
+                return;
+            }
+            // 如果没有参数，添加一个占位参数
+            if (!path.node.param) {
+                path.node.param = t.identifier('__gmMonitorError');
+            }
+            // 构造上报表达式
+            const captureCall = buildCaptureStatement(monitorVar, errorRef, file);
+            const body = path.node.body;
+            if (body.body.length > 0) {
+                body.body.unshift(captureCall);
+            }
+            else {
+                body.body.push(captureCall);
+            }
+            modified = true;
+        }
+    };
+    traverse(ast, visitor);
+    if (!modified) {
+        return code;
+    }
+    try {
+        const result = generate(ast, {
+            retainLines: true,
+            compact: false
+        });
+        return result.code;
+    }
+    catch {
+        return code;
+    }
+}
+/**
+ * 检查 catch 体内是否已包含指定监控变量的 capture 调用。
+ * 匹配模式：globalThis.{monitorVar}?.capture?.({ type: 'caught-error', ... })
+ */
+function hasMonitorCapture(path, monitorVar) {
+    let found = false;
+    path.node.body.body.forEach((stmt) => {
+        // 检查是否是表达式语句
+        if (t.isExpressionStatement(stmt)) {
+            if (matchCaptureCall(stmt.expression, monitorVar)) {
+                found = true;
+            }
+        }
+    });
+    return found;
+}
+/**
+ * 递归匹配表达式是否是 capture 调用链。
+ * 目标：globalThis.{monitorVar}?.capture?.({ type: 'caught-error', ... })
+ */
+function matchCaptureCall(expr, monitorVar) {
+    // 最外层：可选调用 (...)
+    if (t.isOptionalCallExpression(expr) || t.isCallExpression(expr)) {
+        const args = expr.arguments;
+        if (args.length === 0)
+            return false;
+        const firstArg = args[0];
+        // 检查是否是对象参数且包含 type: 'caught-error'
+        if (t.isObjectExpression(firstArg)) {
+            const hasTypeKey = firstArg.properties.some(p => {
+                if (t.isObjectProperty(p) && t.isIdentifier(p.key, { name: 'type' })) {
+                    return t.isStringLiteral(p.value) && p.value.value === 'caught-error';
+                }
+                return false;
+            });
+            // 确认调用链
+            if (hasTypeKey) {
+                return matchMemberChain(expr.callee, monitorVar);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * 匹配成员访问链：globalThis.{monitorVar}?.capture 或 {monitorVar}.capture
+ */
+function matchMemberChain(callee, monitorVar) {
+    // capture 属性访问
+    if (t.isOptionalMemberExpression(callee) &&
+        t.isIdentifier(callee.property, { name: 'capture' })) {
+        return matchMonitorVarRef(callee.object, monitorVar);
+    }
+    // 直接 capture（无可选链）
+    if (t.isMemberExpression(callee) && t.isIdentifier(callee.property, { name: 'capture' })) {
+        return matchMonitorVarRef(callee.object, monitorVar);
+    }
+    return false;
+}
+/**
+ * 匹配监控变量引用：globalThis.{monitorVar} 或直接标识符
+ */
+function matchMonitorVarRef(expr, monitorVar) {
+    // globalThis.{monitorVar}
+    if (t.isOptionalMemberExpression(expr) &&
+        t.isIdentifier(expr.object, { name: 'globalThis' }) &&
+        t.isIdentifier(expr.property, { name: monitorVar })) {
+        return true;
+    }
+    if (t.isMemberExpression(expr) &&
+        t.isIdentifier(expr.object, { name: 'globalThis' }) &&
+        t.isIdentifier(expr.property, { name: monitorVar })) {
+        return true;
+    }
+    // 直接 {monitorVar}
+    if (t.isIdentifier(expr, { name: monitorVar })) {
+        return true;
+    }
+    return false;
+}
+/**
+ * 构造上报语句：
+ * globalThis.__GM_MONITOR__?.capture?.({ type: 'caught-error', message: ..., stack: ..., timestamp: ..., extra: { file: '...' } })
+ */
+function buildCaptureStatement(monitorVar, errorRef, file) {
+    const captureFn = t.optionalCallExpression(t.optionalMemberExpression(t.memberExpression(t.identifier('globalThis'), t.identifier(monitorVar)), t.identifier('capture'), false, true), [
+        t.objectExpression([
+            t.objectProperty(t.identifier('type'), t.stringLiteral('caught-error')),
+            t.objectProperty(t.identifier('message'), t.conditionalExpression(t.binaryExpression('instanceof', t.identifier(errorRef), t.identifier('Error')), t.memberExpression(t.identifier(errorRef), t.identifier('message')), t.callExpression(t.identifier('String'), [t.identifier(errorRef)]))),
+            t.objectProperty(t.identifier('stack'), t.conditionalExpression(t.binaryExpression('instanceof', t.identifier(errorRef), t.identifier('Error')), t.memberExpression(t.identifier(errorRef), t.identifier('stack')), t.identifier('undefined'))),
+            t.objectProperty(t.identifier('timestamp'), t.callExpression(t.memberExpression(t.identifier('Date'), t.identifier('now')), [])),
+            t.objectProperty(t.identifier('extra'), t.objectExpression([t.objectProperty(t.identifier('file'), t.stringLiteral(file))]))
+        ])
+    ], true);
+    return t.expressionStatement(captureFn);
+}
+/**
+ * 校验监控实例变量名。
+ * @param monitorVar 用户配置的全局变量名。
+ */
+function assertMonitorVar(monitorVar) {
+    if (!/^[A-Za-z_$][\w$]*$/.test(monitorVar)) {
+        throw new Error(`Invalid monitorVar: ${monitorVar}`);
+    }
+}
+/**
+ * 把简单 glob 转成正则。
+ * @param glob include/exclude 配置项。
+ */
+function globToRegExp(glob) {
+    const normalized = normalizePath(glob);
+    const placeholder = '__GM_MONITOR_GLOB_STAR__';
+    const escaped = normalized
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, placeholder)
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]');
+    return new RegExp(escaped.replace(new RegExp(placeholder, 'g'), '.*'));
+}
+/**
+ * 统一路径分隔符。
+ * @param path 文件路径。
+ */
+function normalizePath(path) {
+    return path.replace(/\\/g, '/');
+}
+/**
+ * 判断是否是 SDK 内部路径
+ */
+function isSdkInternalPath(path) {
+    return (path.includes('/node_modules/@guomain/monitor-') ||
+        path.includes('/node_modules/@gm/monitor-') ||
+        path.includes('/monitor/packages/') ||
+        /(^|\/)packages\/monitor-(core|web|types|plugins)\//.test(path));
+}

package/vue/index.d.ts

@@ -0,0 +1,8 @@
+import type { MonitorInstance, VueMonitorOptions } from '@guomain/monitor-types';
+/**
+ * 接入 Vue 全局错误处理。
+ * @param options Vue 监控配置，包含 app 实例。
+ * @param monitor 当前监控实例。
+ */
+export declare function installVueMonitor(options: VueMonitorOptions, monitor: MonitorInstance): () => void;
+//# sourceMappingURL=index.d.ts.map

package/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vue/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAEhF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,cAUrF"}

package/vue/index.js

@@ -0,0 +1,16 @@
+import { toErrorEvent } from '@guomain/monitor-core';
+/**
+ * 接入 Vue 全局错误处理。
+ * @param options Vue 监控配置，包含 app 实例。
+ * @param monitor 当前监控实例。
+ */
+export function installVueMonitor(options, monitor) {
+    const previousHandler = options.app.config.errorHandler;
+    options.app.config.errorHandler = (err, instance, info) => {
+        monitor.capture(toErrorEvent('vue-error', err, { extra: { info } }));
+        previousHandler?.(err, instance, info);
+    };
+    return () => {
+        options.app.config.errorHandler = previousHandler;
+    };
+}