@contrast/core 1.31.1 → 1.32.0

package/lib/capture-stacktrace.js

@@ -12,12 +12,15 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-
+// @ts-check
 'use strict';
 
 const process = require('process');
 const fnInspect = require('@contrast/fn-inspect');
 
+/** @typedef {import('.').Frame} Frame */
+/** @typedef {import('.').CreateSnapshotOpts} CreateSnapshotOpts */
+
 const EVAL_ORIGIN_REGEX = /\((.*?):(\d+):\d+\)/;
 
 module.exports = function(core) {
@@ -28,28 +31,38 @@ module.exports = function(core) {
     isAgentPath
   });
 
-  core.captureStacktrace = function(...args) {
-    return stacktraceFactory.captureStacktrace(...args);
+  /** @type {StacktraceFactory['captureStacktrace']} */
+  core.captureStacktrace = function (obj, opts, key) {
+    return stacktraceFactory.captureStacktrace(obj, opts, key);
   };
 
-  core.createSnapshot = function(...args) {
-    return stacktraceFactory.createSnapshot(...args);
+  /** @type {StacktraceFactory['createSnapshot']} */
+  core.createSnapshot = function (opts) {
+    return stacktraceFactory.createSnapshot(opts);
   };
 
   return core.captureStacktrace;
 };
 
-/**
- * The factory will set stacktrace limit for stackframe lists created by it.
- * @param {number} stackTraceLimit set the stack trace limit
- * @param {function} isAgentPath function indicating if path is agent code
- */
 class StacktraceFactory {
+  /**
+   * The factory will set stacktrace limit for stackframe lists created by it.
+   * @param {Object} opts
+   * @param {number} opts.stackTraceLimit set the stack trace limit
+   * @param {(path: string) => boolean} opts.isAgentPath function indicating if path is agent code
+   */
   constructor({ stackTraceLimit, isAgentPath }) {
     this.stackTraceLimit = stackTraceLimit;
     this.isAgentPath = isAgentPath;
   }
 
+  /**
+   * @template T
+   * @param {T} obj
+   * @param {CreateSnapshotOpts} opts
+   * @param {string} key
+   * @returns {T}
+   */
   captureStacktrace(obj, opts, key = 'stack') {
     let stack;
     const snapshot = this.createSnapshot(opts);
@@ -71,91 +84,117 @@ class StacktraceFactory {
     return obj;
   }
 
+  /**
+   * @param {Frame} frame
+   * @returns {boolean}
+   */
+  shouldAppendFrame(frame) {
+    return (
+      !!frame.file &&
+      !this.isAgentPath(frame.file) &&
+      !`${frame.type}${frame.method}`.includes('ContrastMethods')
+    );
+  }
+
   /**
    * Creates a function that will build a stacktrace when invoked. It will keep
    * an error in a closure whose stack will be generated and processed when the
    * returned function executes. The result will be cached.
-   * @param {object} params
-   * @param {function} params.limitFn The constructorOpt param used when creating stack
-   * @returns {function}
+   * @param {CreateSnapshotOpts} params
+   * @returns {() => Frame[]}
    */
   createSnapshot({ constructorOpt, prependFrames } = {}) {
-    const { isAgentPath } = this;
     const target = {};
-
     this.appendStackGetter(target, constructorOpt);
 
-    let ret;
+    let frames;
 
     /**
      * Generates array of frames from `target`'s `stack` getter
-     * @returns {array}
+     * @returns {Frame[]}
      */
-    function snapshot() {
-      if (!ret) {
-        const callsites = StacktraceFactory.generateCallsites(target);
-        /* eslint-disable complexity */
-        ret = (callsites || []).reduce((acc, callsite) => {
-          if (StacktraceFactory.isCallsiteValid(callsite)) {
-            const frame = StacktraceFactory.makeFrame(callsite);
-
-            if (
-              frame.file &&
-              !`${frame.type}${frame.method}`.includes('ContrastMethods')
-            ) {
-              if (!isAgentPath(frame.file)) {
+    const snapshot = () => {
+      if (!frames) {
+        // @ts-expect-error target has had a stack getter appended above.
+        const callsites = StacktraceFactory.generateCallsites(target) ?? [];
+        frames = callsites.reduce(
+          /**
+           * @param {Frame[]} acc
+           * @param {NodeJS.CallSite} callsite
+           */
+          (acc, callsite) => {
+            if (StacktraceFactory.isCallsiteValid(callsite)) {
+              const frame = StacktraceFactory.makeFrame(callsite);
+              if (this.shouldAppendFrame(frame)) {
                 acc.push(frame);
               }
             }
-          }
 
-          return acc;
-        }, []);
+            return acc;
+          },
+          [],
+        );
       }
 
-      if (!prependFrames) return ret;
+      if (!prependFrames) return frames;
 
       return [
         ...prependFrames.map((f) => (typeof f == 'function' ? fnInspect.funcInfo(f) : f)),
-        ...ret
+        ...frames,
       ];
-    }
+    };
 
     return snapshot;
   }
 
   /**
    * Based on stacktrace limit and constructor opt, will append a stack getter
-   * @param {} error
-   * @param {} limitFn
+   * @param {any} obj
+   * @param {Function=} constructorOpt
    */
-  appendStackGetter(error, constructorOpt) {
+  appendStackGetter(obj, constructorOpt) {
     const { stackTraceLimit } = Error;
     Error.stackTraceLimit = this.stackTraceLimit;
-    Error.captureStackTrace(error, constructorOpt);
+    Error.captureStackTrace(obj, constructorOpt);
     Error.stackTraceLimit = stackTraceLimit;
   }
 
+  /**
+   * @param {any} callsite
+   * @returns {boolean}
+   */
   static isCallsiteValid(callsite) {
     return callsite instanceof Callsite;
   }
 
   /**
    * Creates an array frame objects from an array of Callsite instances
-   * @param {} callsite
-   * @returns {}
+   * @param {NodeJS.CallSite} callsite
+   * @returns {Frame}
    */
   static makeFrame(callsite) {
-    let evalOrigin, file, lineNumber, method, type;
+    /** @type {string | undefined} */
+    let evalOrigin;
+    /** @type {string | undefined} */
+    let file;
+    /** @type {number | null} */
+    let lineNumber = null;
+    /** @type {string | null} */
+    let method = null;
+    /** @type {string | null} */
+    let type;
 
     if (callsite.isEval()) {
       evalOrigin = StacktraceFactory.formatFileName(callsite.getEvalOrigin());
-      [, file, lineNumber] = evalOrigin.match(EVAL_ORIGIN_REGEX) || evalOrigin.endsWith('.ejs');
+      const matches = EVAL_ORIGIN_REGEX.exec(evalOrigin);
+      if (matches) {
+        file = matches[1];
+        lineNumber = parseInt(matches[2]);
+      }
     }
 
-    file = file || callsite.getFileName();
-    lineNumber = lineNumber || callsite.getLineNumber();
-
+    file = file ?? callsite.getFileName();
+    lineNumber = lineNumber ?? callsite.getLineNumber();
     method = callsite.getFunctionName();
     type = callsite.getTypeName();
 
@@ -167,6 +206,10 @@ class StacktraceFactory {
     return { eval: evalOrigin, file, lineNumber, method, type };
   }
 
+  /**
+   * @param {string} fileName
+   * @returns {string}
+   */
   static formatFileName(fileName = '') {
     const cwd = `${process.cwd()}/`;
     const idx = fileName.indexOf(cwd);
@@ -181,15 +224,15 @@ class StacktraceFactory {
    * Will access `stack` getter propery on the provided error to generate
    * a stacktrace. We capture the callsite instances passed to `prepareStacktrace`
    * using an ephemeral monkey patch.
-   * @param {object} error object with a `stack` getter property
-   * @returns {}
+   * @param {Error} error object with a `stack` getter property
+   * @returns {NodeJS.CallSite[]}
    */
   static generateCallsites(error) {
-    let callsites;
+    let callsites = [];
 
     const { prepareStackTrace } = Error;
 
-    Error.prepareStackTrace = function(_, _callsites) {
+    Error.prepareStackTrace = function contrastPrepareStackTrace(_, _callsites) {
       callsites = _callsites;
       return _callsites;
     };

package/lib/index.d.ts

@@ -15,14 +15,28 @@
 
 import { AppInfo, Messages } from '@contrast/common';
 
+interface Frame {
+  eval: string | undefined;
+  file: string | undefined;
+  lineNumber: number | null;
+  method: string | null;
+  type: string | null;
+}
+
+/* eslint-disable @typescript-eslint/ban-types */
+interface CreateSnapshotOpts {
+  constructorOpt?: Function;
+  prependFrames?: (Function | Frame)[];
+}
+
 export interface Core {
   agentName: string;
   agentVersion: string;
 
   appInfo: AppInfo;
 
-  captureStackTrace(...args: any[]): any;
-  captureSnapshot(...args: any[]): any;
+  captureStackTrace<T>(obj: T, opts: CreateSnapshotOpts, key: string): T;
+  createSnapshot(opts?: CreateSnapshotOpts): () => Frame[];
 
   isAgentPath(path: string): boolean;
 

package/lib/is-agent-path.js

@@ -12,15 +12,15 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-
 'use strict';
 
-/**
- */
 module.exports = function(core) {
   const { config } = core;
 
   /**
+   * Returns true if the provided path matches any of the configured filters.
+   * @param {string} path
+   * @returns {boolean}
    */
   function isAgentPath(path) {
     for (const seg of config.agent.stack_trace_filters) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/core",
-  "version": "1.31.1",
+  "version": "1.32.0",
   "description": "Preconfigured Contrast agent core services and models",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -16,7 +16,7 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.20.1",
+    "@contrast/common": "1.21.0",
     "@contrast/find-package-json": "^1.0.0",
     "@contrast/fn-inspect": "^4.0.0"
   }