feat(rewriteframes): Introduce RewriteFrames package

package.json

@@ -35,6 +35,7 @@
     "packages/eslint-plugin-sdk",
     "packages/gatsby",
     "packages/hub",
+    "packages/integration-common-rewriteframes",
     "packages/integration-tests",
     "packages/integrations",
     "packages/minimal",

packages/integration-common-rewriteframes/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['../../.eslintrc.js'],
+};

packages/integration-common-rewriteframes/.npmignore

@@ -0,0 +1,4 @@
+*
+!/dist/**/*
+!/esm/**/*
+*.tsbuildinfo

packages/integration-common-rewriteframes/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Sentry
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/integration-common-rewriteframes/README.md

@@ -0,0 +1,57 @@
+<p align="center">
+  <a href="https://sentry.io" target="_blank" align="center">
+    <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280">
+  </a>
+  <br />
+</p>
+
+# Sentry JavaScript RewriteFrames integration
+
+[![npm version](https://img.shields.io/npm/v/@sentry/integration-common-rewriteframes.svg)](https://www.npmjs.com/package/@sentry/wasm)
+[![npm dm](https://img.shields.io/npm/dm/@sentry/integration-common-rewriteframes.svg)](https://www.npmjs.com/package/@sentry/wasm)
+[![npm dt](https://img.shields.io/npm/dt/@sentry/integration-common-rewriteframes.svg)](https://www.npmjs.com/package/@sentry/wasm)
+[![typedoc](https://img.shields.io/badge/docs-typedoc-blue.svg)](http://getsentry.github.io/sentry-javascript/)
+
+## Links
+
+- [Official SDK Docs](https://docs.sentry.io/quickstart/)
+- [TypeDoc](http://getsentry.github.io/sentry-javascript/)
+
+## General
+
+This integration allows you to apply a transformation to each frame of the stack trace. In the streamlined scenario, it can be used to change the name of the file frame it originates from, or it can be fed with an iterated function to apply any arbitrary transformation.
+
+On Windows machines, you have to use Unix paths and skip the volume letter in root option to enable. For example `C:\\Program Files\\Apache\\www` won’t work, however, `/Program Files/Apache/www` will.
+
+Available options:
+
+```js
+import * as Sentry from "@sentry/browser";
+import { RewriteFrames } from "@sentry/integration-common-rewriteframes";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new RewriteFrames(
+    {
+      // root path that will be stripped from the current frame's filename by the default iteratee if the filename is an absolute path
+      root: string;
+
+      // a custom prefix that will be used by the default iteratee (default: `app://`)
+      prefix: string;
+
+      // function that takes the frame, applies a transformation, and returns it
+      iteratee: (frame) => frame;
+    }
+  )],
+});
+```
+
+#### Usage Examples
+
+For example, if the full path to your file is `/www/src/app/file.js`:
+
+| Usage                             | Path in Stack Trace      | Description                                                                                                                   |
+| --------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `RewriteFrames()`                 | `app:///file.js`         | The default behavior is to replace the absolute path, except the filename, and prefix it with the default prefix (`app:///`). |
+| `RewriteFrames({prefix: 'foo/'})` | `foo/file.js`            | Prefix `foo/` is used instead of the default prefix `app:///`.                                                                |
+| `RewriteFrames({root: '/www'})`   | `app:///src/app/file.js` | `root` is defined as `/www`, so only that part is trimmed from beginning of the path.                                         |

packages/integration-common-rewriteframes/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@sentry/integration-common-rewriteframes",
+  "version": "6.17.0-beta.0",
+  "description": "Integration that allows users to apply a transformation to each frame of the stack trace",
+  "repository": "git://github.com/getsentry/sentry-javascript.git",
+  "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/integration-common-rewriteframes",
+  "author": "Sentry",
+  "license": "BSD-3-Clause",
+  "engines": {
+    "node": ">=6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "esm/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@sentry/types": "6.17.0-beta.0",
+    "@sentry/utils": "6.17.0-beta.0",
+    "tslib": "^1.9.3"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build": "run-p build:cjs build:esm",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:dev": "run-s build",
+    "build:es5": "yarn build:cjs # *** backwards compatibility - remove in v7 ***",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:watch": "run-p build:cjs:watch build:esm:watch",
+    "build:cjs:watch": "tsc -p tsconfig.cjs.json -w --preserveWatchOutput",
+    "build:dev:watch": "run-s build:watch",
+    "build:es5:watch": "yarn build:cjs:watch # *** backwards compatibility - remove in v7 ***",
+    "build:esm:watch": "tsc -p tsconfig.esm.json -w --preserveWatchOutput",
+    "circularDepCheck": "madge --circular src/index.ts",
+    "clean": "rimraf dist esm coverage",
+    "fix": "run-s fix:eslint fix:prettier",
+    "fix:eslint": "eslint . --format stylish --fix",
+    "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"",
+    "link:yarn": "yarn link",
+    "lint": "run-s lint:prettier lint:eslint",
+    "lint:eslint": "eslint . --cache --cache-location '../../eslintcache/' --format stylish",
+    "lint:prettier": "prettier --check \"{src,test}/**/*.ts\"",
+    "pack": "npm pack",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "moduleFileExtensions": [
+      "js",
+      "ts"
+    ],
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "globals": {
+      "ts-jest": {
+        "tsConfig": "./tsconfig.json",
+        "diagnostics": false
+      }
+    }
+  },
+  "sideEffects": false
+}

packages/integration-common-rewriteframes/src/index.ts

@@ -0,0 +1,132 @@
+import { Event, EventProcessor, Hub, Integration, StackFrame, Stacktrace } from '@sentry/types';
+import { basename, relative } from '@sentry/utils';
+
+type StackFrameIteratee = (frame: StackFrame) => StackFrame;
+
+/** Rewrite event frames paths */
+export class RewriteFrames implements Integration {
+  /**
+   * @inheritDoc
+   */
+  public static id: string = 'RewriteFrames';
+
+  /**
+   * @inheritDoc
+   */
+  public name: string = RewriteFrames.id;
+
+  /**
+   * @inheritDoc
+   */
+  private readonly _root?: string;
+
+  /**
+   * @inheritDoc
+   */
+  private readonly _prefix: string = 'app:///';
+
+  /**
+   * @inheritDoc
+   */
+  public constructor(options: { root?: string; prefix?: string; iteratee?: StackFrameIteratee } = {}) {
+    if (options.root) {
+      this._root = options.root;
+    }
+    if (options.prefix) {
+      this._prefix = options.prefix;
+    }
+    if (options.iteratee) {
+      this._iteratee = options.iteratee;
+    }
+  }
+
+  /**
+   * @inheritDoc
+   */
+  public setupOnce(addGlobalEventProcessor: (callback: EventProcessor) => void, getCurrentHub: () => Hub): void {
+    addGlobalEventProcessor(event => {
+      const self = getCurrentHub().getIntegration(RewriteFrames);
+      if (self) {
+        return self.process(event);
+      }
+      return event;
+    });
+  }
+
+  /** JSDoc */
+  public process(originalEvent: Event): Event {
+    let processedEvent = originalEvent;
+
+    if (originalEvent.exception && Array.isArray(originalEvent.exception.values)) {
+      processedEvent = this._processExceptionsEvent(processedEvent);
+    }
+
+    if (originalEvent.stacktrace) {
+      processedEvent = this._processStacktraceEvent(processedEvent);
+    }
+
+    return processedEvent;
+  }
+
+  /**
+   * @inheritDoc
+   */
+  private readonly _iteratee: StackFrameIteratee = (frame: StackFrame) => {
+    if (!frame.filename) {
+      return frame;
+    }
+    // Check if the frame filename begins with `/` or a Windows-style prefix such as `C:\`
+    const isWindowsFrame = /^[A-Z]:\\/.test(frame.filename);
+    const startsWithSlash = /^\//.test(frame.filename);
+    if (isWindowsFrame || startsWithSlash) {
+      const filename = isWindowsFrame
+        ? frame.filename
+            .replace(/^[A-Z]:/, '') // remove Windows-style prefix
+            .replace(/\\/g, '/') // replace all `\\` instances with `/`
+        : frame.filename;
+      const base = this._root ? relative(this._root, filename) : basename(filename);
+      frame.filename = `${this._prefix}${base}`;
+    }
+    return frame;
+  };
+
+  /** JSDoc */
+  private _processExceptionsEvent(event: Event): Event {
+    try {
+      return {
+        ...event,
+        exception: {
+          ...event.exception,
+          // The check for this is performed inside `process` call itself, safe to skip here
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          values: event.exception!.values!.map(value => ({
+            ...value,
+            stacktrace: this._processStacktrace(value.stacktrace),
+          })),
+        },
+      };
+    } catch (_oO) {
+      return event;
+    }
+  }
+
+  /** JSDoc */
+  private _processStacktraceEvent(event: Event): Event {
+    try {
+      return {
+        ...event,
+        stacktrace: this._processStacktrace(event.stacktrace),
+      };
+    } catch (_oO) {
+      return event;
+    }
+  }
+
+  /** JSDoc */
+  private _processStacktrace(stacktrace?: Stacktrace): Stacktrace {
+    return {
+      ...stacktrace,
+      frames: stacktrace && stacktrace.frames && stacktrace.frames.map(f => this._iteratee(f)),
+    };
+  }
+}

packages/integrations/test/rewriteframes.test.ts → packages/integration-common-rewriteframes/test/index.test.ts

@@ -1,6 +1,6 @@
 import { Event, StackFrame } from '@sentry/types';
 
-import { RewriteFrames } from '../src/rewriteframes';
+import { RewriteFrames } from '../src';
 
 let rewriteFrames: RewriteFrames;
 let messageEvent: Event;

packages/integration-common-rewriteframes/tsconfig.cjs.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+
+  "compilerOptions": {
+    "module": "commonjs",
+    "outDir": "dist"
+  }
+}

packages/integration-common-rewriteframes/tsconfig.esm.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+
+  "compilerOptions": {
+    "module": "es6",
+    "outDir": "esm"
+  }
+}

packages/integration-common-rewriteframes/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+
+  "include": ["src/**/*"],
+
+  "compilerOptions": {
+    // package-specific options
+  }
+}

packages/integration-common-rewriteframes/tsconfig.test.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+
+  "include": ["test/**/*"],
+
+  "compilerOptions": {
+    // should include all types from `./tsconfig.json` plus types for all test frameworks used
+    "types": ["node", "jest"]
+
+    // other package-specific, test-specific options
+  }
+}