peekinside 0.0.0-stage → 1.2.0

package/src/exceptions/exception-capture.js

@@ -0,0 +1,407 @@
+/**
+ * Records the exceptions of one PeekInside instance: from the framework integrations, from
+ * report(), and from the process-level hooks (see ProcessMonitor).
+ *
+ * Every path ends here, so the rules live in one place:
+ *
+ * - Nothing is recorded while the instance doesn't record (paused, stopped, no destination), and
+ *   nothing for requests that local mode refused to record because they reached a server.
+ * - An error object is recorded once per request, however many hooks see it.
+ * - At most 50 exceptions a second (bursts of 100) are recorded; crashes always are.
+ * - Framework errors with a 4xx status (`createError(404)`, `ctx.throw(400)`) are how apps answer
+ *   bad requests, not bugs, and aren't recorded automatically.
+ * - Whether an Express error was handled is only known later: an error middleware that receives
+ *   it may still pass it on to Express's final handler. Such records stay open on the request and
+ *   are settled when the error reaches the final handler (unhandled) or the request's record is
+ *   built (handled).
+ *
+ * Nothing here ever throws into the app: a failure to record is a lost exception, never a new one.
+ */
+
+import { ExceptionBuilder } from './exception-builder.js';
+import { TokenBucket } from './rate-limiter.js';
+import { RequestContext, RequestSnapshot } from './request-context.js';
+import { splitUrl } from '../capture/http-message.js';
+import { UserInfo } from '../user.js';
+
+// Open records of a request that already finished wait this long for Express's final handler.
+const LATE_SETTLE_MS = 50;
+
+// Every capture, oldest first. Weak, so an app that drops its PeekInside instance doesn't leak it.
+const registry = [];
+
+/**
+ * @typedef {Object} DeliverySink
+ * @property {(record: import('./exception-record.js').ExceptionRecord) => void} enqueueRecord -
+ *   Queues a record for the next batch
+ * @property {(batch: { exceptions: Object[], exchanges: Object[], fatal: boolean }) => void} deliverNow -
+ *   Delivers synchronously, for a process that may exit right away
+ * @property {string} environment
+ * @property {string|null} release
+ * @property {boolean} disabled
+ */
+
+/**
+ * Exception recording for one PeekInside instance.
+ */
+export class ExceptionCapture {
+  /**
+   * Adds a capture to the instances PeekInside.report() and the process hooks choose from.
+   *
+   * @param {ExceptionCapture} capture
+   * @returns {void}
+   */
+  static register(capture) {
+    registry.push(new WeakRef(capture));
+  }
+
+  /**
+   * @param {ExceptionCapture} capture
+   * @returns {void}
+   */
+  static unregister(capture) {
+    for (let i = registry.length - 1; i >= 0; i--) {
+      const current = registry[i].deref();
+      if (!current || current === capture) registry.splice(i, 1);
+    }
+  }
+
+  /**
+   * The most recently created capture that is recording.
+   *
+   * @param {Object} [options]
+   * @param {boolean} [options.automatic=false] - Only captures that record exceptions automatically
+   *   (captureExceptions)
+   * @returns {ExceptionCapture|null}
+   */
+  static latest({ automatic = false } = {}) {
+    for (let i = registry.length - 1; i >= 0; i--) {
+      const capture = registry[i].deref();
+      if (!capture) {
+        registry.splice(i, 1);
+        continue;
+      }
+      if (capture.recording && (!automatic || capture.automatic)) return capture;
+    }
+    return null;
+  }
+
+  /**
+   * Whether any registered capture records exceptions automatically, recording or not right now.
+   *
+   * @returns {boolean}
+   */
+  static anyAutomatic() {
+    return registry.some((ref) => {
+      const capture = ref.deref();
+      return Boolean(capture && capture.automatic);
+    });
+  }
+
+  /**
+   * @param {Object} options
+   * @param {string} options.root - The project folder: frames inside it are in-app
+   * @param {boolean} [options.automatic=true] - Record exceptions automatically (captureExceptions);
+   *   report() works either way
+   * @param {boolean} [options.sourceContext=true] - Read source lines around in-app frames
+   * @param {boolean} [options.sourceMaps=true] - Map frames of compiled code to their sources
+   * @param {() => boolean} options.isEnabled - Whether the instance records right now
+   * @param {() => DeliverySink|null} options.sink - Where records go (the instance's transport)
+   * @param {TokenBucket} [options.limiter] - Rate limit (default: 50 a second, bursts of 100)
+   * @param {Object} [options.owner] - The PeekInside instance it records for
+   */
+  constructor({ root, automatic = true, sourceContext = true, sourceMaps = true, isEnabled, sink, limiter = new TokenBucket(), owner = null }) {
+    /**
+     * The PeekInside instance it records for
+     * @type {Object|null}
+     */
+    this.owner = owner;
+    this.automatic = automatic;
+    this.builder = new ExceptionBuilder({ root, sourceContext, sourceMaps });
+    this.limiter = limiter;
+    this._isEnabled = isEnabled;
+    this._sink = sink;
+  }
+
+  /**
+   * Whether exceptions are recorded right now.
+   *
+   * @type {boolean}
+   */
+  get recording() {
+    const sink = this._sink();
+    return Boolean(sink && !sink.disabled && this._isEnabled());
+  }
+
+  /**
+   * An error reached a framework during a request: Express, Koa or Fastify.
+   *
+   * @param {RequestContext|null} context - The request's context
+   * @param {*} error
+   * @param {Object} options
+   * @param {'express'|'koa'|'fastify'} options.mechanism
+   * @param {boolean} options.handled - Whether the app handled it
+   * @param {boolean} [options.open=false] - The outcome isn't final yet (see the module comment)
+   * @returns {string|null} The exception's id, or null when nothing was recorded
+   */
+  frameworkError(context, error, { mechanism, handled, open = false }) {
+    try {
+      if (!this.automatic || !context || context.capture !== this || context.blocked) return null;
+      if (!this.recording || isClientError(error)) return null;
+
+      const existing = context.seen.get(error);
+      if (existing) {
+        // Handled on the way, but it still reached the final handler: unhandled after all.
+        if (!handled && context.pending.has(error)) {
+          context.pending.delete(error);
+          existing.handled = false;
+          this._emit(existing, context);
+        }
+        return existing.id;
+      }
+      if (!this.limiter.take()) return null;
+
+      const record = this._build(error, { mechanism, handled, fatal: false, context });
+      context.seen.set(error, record);
+      noteSpan(context, record);
+      if (open) {
+        context.pending.set(error, record);
+        if (context.finished) this._settleLater(context);
+      } else {
+        this._emit(record, context);
+      }
+      return record.id;
+    } catch (failure) {
+      return null;
+    }
+  }
+
+  /**
+   * Records an error the app reports (PeekInside#report()).
+   *
+   * @param {*} error
+   * @param {Object} [options]
+   * @param {import('http').IncomingMessage} [options.request] - The request it relates to (a
+   *   Fastify request or a Koa context work too); otherwise the request running now, if any
+   * @param {Object<string, string>} [options.tags]
+   * @param {*} [options.extra]
+   * @param {boolean} [options.handled=true]
+   * @param {*} [options.user] - Who it happened to (see UserInfo); by default, the request's user
+   * @returns {string|null} The exception's id, or null when nothing was recorded
+   */
+  report(error, { request, tags, extra, handled = true, user } = {}) {
+    try {
+      if (!this.recording) return null;
+      const explicit = nodeRequest(request);
+      let context = explicit ? RequestContext.of(explicit) : RequestContext.current();
+      if (context && context.capture !== this) context = null;
+      if (context && context.blocked) return null;
+
+      const dedupe = context && error !== null && typeof error === 'object';
+      if (dedupe && context.seen.has(error)) return context.seen.get(error).id;
+      if (!this.limiter.take()) return null;
+
+      const record = this._build(error, {
+        mechanism: 'report',
+        handled: handled !== false,
+        fatal: false,
+        context,
+        request: context ? null : explicit,
+        tags,
+        extra,
+        user: user === undefined ? undefined : UserInfo.normalize(user)
+      });
+      if (dedupe) context.seen.set(error, record);
+      noteSpan(context, record);
+      this._emit(record, context);
+      return record.id;
+    } catch (failure) {
+      return null;
+    }
+  }
+
+  /**
+   * Records the error a job run failed with (PeekInside.job(), a scheduled task, a queue worker's
+   * job): an exception like the others, with mechanism "job", linked to the run.
+   *
+   * @param {import('../jobs/job-context.js').JobContext} context
+   * @param {*} error
+   * @returns {string|null} The exception's id, or null when nothing was recorded
+   */
+  jobError(context, error) {
+    try {
+      if (!this.recording || !context) return null;
+      const dedupe = error !== null && typeof error === 'object';
+      if (dedupe && context.seen.has(error)) return context.seen.get(error).id;
+      if (!this.limiter.take()) return null;
+      const record = this._build(error, { mechanism: 'job', handled: false, fatal: false, context });
+      if (dedupe) context.seen.set(error, record);
+      noteSpan(context, record);
+      this._emit(record, context);
+      return record.id;
+    } catch (failure) {
+      return null;
+    }
+  }
+
+  /**
+   * Records an exception seen by the process-level hooks, and delivers it synchronously: the
+   * process may exit as soon as the hook returns. For a crash, the request it happened in is
+   * delivered too, as aborted, with the exceptions still open on it.
+   *
+   * @param {*} error
+   * @param {Object} options
+   * @param {'uncaught'|'unhandledRejection'|'http'} options.mechanism
+   * @param {boolean} options.fatal - The process is about to exit
+   * @param {boolean} options.handled
+   * @param {RequestContext|null} options.context - The request it happened in, if known
+   * @returns {string|null} The exception's id, or null when nothing was recorded
+   */
+  processError(error, { mechanism, fatal, handled, context }) {
+    try {
+      if (!this.recording || (context && context.blocked)) return null;
+      // A crash is recorded whatever the rate: it happens once.
+      if (!fatal && !this.limiter.take()) return null;
+
+      const own = context && context.capture === this ? context : null;
+      if (own) own.pending.delete(error);
+      const record = this._build(error, { mechanism, handled, fatal, context: own });
+
+      const exceptions = [];
+      const exchanges = [];
+      if (own && fatal) {
+        // The request's open records are settled as they stand: the process won't get further.
+        for (const open of own.pending.values()) {
+          own.noteRecorded(open);
+          exceptions.push(open);
+        }
+        own.pending.clear();
+      }
+      if (own) {
+        own.seen.set(error, record);
+        own.noteRecorded(record);
+        noteSpan(own, record);
+      }
+      exceptions.push(record);
+
+      if (own && fatal && own.recorder) {
+        const exchange = own.recorder.takeExchange();
+        if (exchange) {
+          exchange.exceptionCount = own.exceptionCount;
+          exchange.exceptions = own.links.slice();
+          own.completeTimeline(exchange);
+          if (own.user) exchange.user = own.user;
+          exchanges.push(exchange);
+        }
+      }
+
+      const sink = this._sink();
+      if (sink) sink.deliverNow({ exceptions, exchanges, fatal });
+      return record.id;
+    } catch (failure) {
+      return null;
+    }
+  }
+
+  /**
+   * Called when a request's record is built: settles its open records, and adds the exception
+   * count and links to the exchange.
+   *
+   * @param {RequestContext} context
+   * @param {import('../capture/exchange-recorder.js').Exchange} exchange - Changed in place
+   * @returns {void}
+   */
+  finish(context, exchange) {
+    try {
+      this.settle(context);
+      exchange.exceptionCount = context.exceptionCount;
+      exchange.exceptions = context.links.slice();
+    } catch (failure) {
+      // The request is still recorded, without its exceptions.
+    }
+  }
+
+  /**
+   * Queues a request's open records as handled: the error never reached the final handler.
+   *
+   * @param {RequestContext} context
+   * @returns {void}
+   */
+  settle(context) {
+    if (!context.pending.size) return;
+    const records = [...context.pending.values()];
+    context.pending.clear();
+    for (const record of records) this._emit(record, context);
+  }
+
+  // An error middleware received an error after the request's record was built (it answered,
+  // then passed an error on): settle shortly, unless the final handler gets the error first.
+  _settleLater(context) {
+    const timer = setTimeout(() => this.settle(context), LATE_SETTLE_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  _build(error, { mechanism, handled, fatal, context, request = null, tags, extra, user }) {
+    const sink = this._sink();
+    let snapshot = null;
+    let requestLine = null;
+    if (context) {
+      snapshot = context.snapshot();
+      requestLine = context.requestLine();
+    } else if (request) {
+      snapshot = RequestSnapshot.fromRequest(request);
+      requestLine = { method: snapshot.method, path: splitUrl(snapshot.url).pathname };
+    }
+    return this.builder.build(error, {
+      mechanism,
+      handled,
+      fatal,
+      environment: sink ? sink.environment : 'development',
+      release: sink ? sink.release || null : null,
+      requestId: context ? context.requestId : null,
+      request: snapshot,
+      requestLine,
+      user: user !== undefined ? user : context ? context.user : null,
+      jobRunId: context ? context.jobRunId || null : null,
+      job: context && context.jobName ? { name: context.jobName } : null,
+      tags,
+      extra
+    });
+  }
+
+  _emit(record, context) {
+    if (context) context.noteRecorded(record);
+    const sink = this._sink();
+    if (sink) sink.enqueueRecord(record);
+  }
+}
+
+// An exception recorded during a request is a span on its timeline too.
+function noteSpan(context, record) {
+  if (context && context.timeline) context.timeline.exception(record);
+}
+
+// The Node.js request behind what report() was given: the request itself (Express, http), a
+// Fastify request (`raw`) or a Koa context or request (`req`).
+function nodeRequest(request) {
+  if (!request || typeof request !== 'object') return null;
+  for (const candidate of [request, request.raw, request.req]) {
+    if (candidate && typeof candidate === 'object' && RequestContext.of(candidate)) return candidate;
+  }
+  for (const candidate of [request.raw, request.req]) {
+    if (candidate && typeof candidate === 'object' && candidate.headers && typeof candidate.method === 'string') return candidate;
+  }
+  return request;
+}
+
+// Status 4xx on the error: the app's answer to a bad request.
+function isClientError(error) {
+  if (error === null || typeof error !== 'object') return false;
+  let status;
+  try {
+    status = error.status !== undefined ? error.status : error.statusCode;
+  } catch (failure) {
+    return false;
+  }
+  return Number.isInteger(status) && status >= 400 && status < 500;
+}

package/src/exceptions/exception-record.js

@@ -0,0 +1,118 @@
+/**
+ * The stored form of an exception, shared by the local hub and PeekInside Cloud (see the data
+ * contract): a few plain fields for lists and filters, a summary for the exception list, and the
+ * detail (stack, frames, causes, request, process), loaded when someone opens the exception.
+ */
+
+import { LIMITS, truncate } from './limits.js';
+
+/**
+ * One recorded exception.
+ *
+ * The local hub receives the plain form (toJSON()). PeekInside Cloud receives the sealed form:
+ * the summary and the detail are encrypted to the project's public key, bound to the exception
+ * id, like the summary and detail of requests.
+ */
+export class ExceptionRecord {
+  /**
+   * @param {Object} fields
+   * @param {string} fields.id - UUID
+   * @param {number} fields.occurredAt - When it was recorded (ms since the epoch)
+   * @param {string} fields.environment - Normalized environment label
+   * @param {string|null} [fields.release=null] - The running release (see release.js)
+   * @param {boolean} fields.handled - Whether the app caught it (an error middleware, report())
+   * @param {boolean} fields.fatal - Whether it crashed the process
+   * @param {string|null} fields.requestId - The request it happened in
+   * @param {string|null} [fields.jobRunId=null] - The job run it happened in
+   * @param {Object} fields.summary - name, message, code, fingerprint, mechanism, location, request
+   * @param {Object} fields.detail - stack, frames, causes, request, process, tags, extra
+   */
+  constructor({ id, occurredAt, environment, release = null, handled, fatal, requestId, jobRunId = null, summary, detail }) {
+    this.id = id;
+    this.occurredAt = occurredAt;
+    this.environment = environment;
+    this.release = release;
+    this.handled = handled;
+    this.fatal = fatal;
+    this.requestId = requestId;
+    this.jobRunId = jobRunId;
+    this.summary = summary;
+    this.detail = detail;
+  }
+
+  /**
+   * The plain form, as the local hub stores it. Also used by JSON.stringify().
+   *
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      occurredAt: this.occurredAt,
+      environment: this.environment,
+      release: this.release,
+      handled: this.handled,
+      fatal: this.fatal,
+      requestId: this.requestId,
+      jobRunId: this.jobRunId,
+      summary: this.summary,
+      detail: this.detail
+    };
+  }
+
+  /**
+   * The sealed form, for PeekInside Cloud: the summary and the detail are encrypted, bound to this
+   * exception's id so they can't be swapped with another record's.
+   *
+   * @param {import('../crypto.js').Sealer} sealer - Sealer of the batch
+   * @returns {Promise<Object>}
+   */
+  async seal(sealer) {
+    const { summary, detail, ...meta } = this.toJSON();
+    return {
+      ...meta,
+      summary: await sealer.seal(JSON.stringify(summary), ExceptionRecord.summaryAad(this.id)),
+      detail: await sealer.seal(JSON.stringify(detail), ExceptionRecord.detailAad(this.id))
+    };
+  }
+
+  /**
+   * seal() for a process that is crashing, where nothing asynchronous runs anymore.
+   *
+   * @param {import('../crypto.js').SyncSealer} sealer
+   * @returns {Object}
+   */
+  sealSync(sealer) {
+    const { summary, detail, ...meta } = this.toJSON();
+    return {
+      ...meta,
+      summary: sealer.seal(JSON.stringify(summary), ExceptionRecord.summaryAad(this.id)),
+      detail: sealer.seal(JSON.stringify(detail), ExceptionRecord.detailAad(this.id))
+    };
+  }
+
+  /**
+   * How the record of the request it happened in lists it, so the request inspector can link to it.
+   *
+   * @returns {{ id: string, name: string, message: string }}
+   */
+  link() {
+    return { id: this.id, name: this.summary.name, message: truncate(this.summary.message, LIMITS.linkMessage) };
+  }
+
+  /**
+   * @param {string} id
+   * @returns {string} Additional authenticated data of a sealed summary
+   */
+  static summaryAad(id) {
+    return `exception:summary:${id}`;
+  }
+
+  /**
+   * @param {string} id
+   * @returns {string} Additional authenticated data of a sealed detail
+   */
+  static detailAad(id) {
+    return `exception:detail:${id}`;
+  }
+}

package/src/exceptions/fingerprint.js

@@ -0,0 +1,60 @@
+/**
+ * Groups exceptions into issues: exceptions with the same fingerprint are the same problem.
+ *
+ * The rule is part of the data contract with PeekInside Cloud, so both dashboards group the same
+ * way:
+ *
+ *   with in-app frames:  name + "\n" + the top three in-app frames as "relativeFile:function"
+ *   without:             name + "\n" + code + "\n" + the normalized message
+ *
+ * hashed with SHA-256 and cut to 16 hex characters. Line numbers are left out on purpose, so an
+ * edit above the throwing line keeps the issue together, and the message is normalized so that
+ * "User 42 not found" and "User 43 not found" are one issue.
+ */
+
+import { createHash } from 'crypto';
+
+const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+const HEX_RUN = /\b(?:0x)?[0-9a-f]{8,}\b/gi;
+const NUMBER = /\d+(?:\.\d+)?/g;
+// Double-quoted and backtick strings anywhere; single-quoted strings only where a quote opens a
+// string (start or after a non-word character), so the apostrophe in "can't" opens nothing.
+const QUOTED = /"[^"\n]*"|`[^`\n]*`|(^|[^\w])'[^'\n]*'/g;
+
+/**
+ * Computes fingerprints.
+ */
+export class Fingerprint {
+  /**
+   * @param {Object} exception
+   * @param {string} exception.name - Summary name
+   * @param {string|null} exception.code
+   * @param {string} exception.message - Summary message
+   * @param {import('./frame-classifier.js').Frame[]} exception.frames - Top frame first
+   * @returns {string} 16 lowercase hex characters
+   */
+  static of({ name, code, message, frames }) {
+    const inApp = frames.filter((frame) => frame.inApp).slice(0, 3);
+    const basis = inApp.length > 0
+      ? `${name}\n${inApp.map((frame) => `${frame.relativeFile}:${frame.function ?? '?'}`).join('\n')}`
+      : `${name}\n${code ?? ''}\n${Fingerprint.normalizeMessage(message)}`;
+    return createHash('sha256').update(basis).digest('hex').slice(0, 16);
+  }
+
+  /**
+   * Replaces the parts of a message that change from one occurrence to the next: quoted strings,
+   * UUIDs, runs of 8+ hex digits and numbers.
+   *
+   * @param {string} message
+   * @returns {string}
+   * @example
+   * Fingerprint.normalizeMessage('User 42 not found in "eu-west"') // 'User <num> not found in <str>'
+   */
+  static normalizeMessage(message) {
+    return String(message ?? '')
+      .replace(QUOTED, (match, before) => `${before ?? ''}<str>`)
+      .replace(UUID, '<uuid>')
+      .replace(HEX_RUN, '<hex>')
+      .replace(NUMBER, '<num>');
+  }
+}

package/src/exceptions/frame-classifier.js

@@ -0,0 +1,114 @@
+/**
+ * Tells the app's own code apart from its dependencies and Node.js itself, frame by frame.
+ *
+ * The dashboard highlights in-app frames, groups exceptions by them (see fingerprint.js) and shows
+ * their source lines, so "in app" has to mean the code people can change: files inside the
+ * project folder, except anything under node_modules.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * @typedef {Object} Frame
+ * @property {string|null} function
+ * @property {string|null} file - Absolute path, "node:..." for internals, null for built-ins
+ * @property {string|null} relativeFile - Relative to the project folder with forward slashes, when
+ *   the file is inside it
+ * @property {number|null} line
+ * @property {number|null} column
+ * @property {boolean} inApp - Inside the project folder and not under node_modules
+ * @property {string|null} module - npm package ("express", "@scope/pkg") of node_modules frames,
+ *   "node" for Node.js internals
+ * @property {boolean} native
+ * @property {boolean} async
+ * @property {{ start: number, lines: string[] }|null} context - Source lines, set by SourceContext
+ */
+
+/**
+ * Classifies parsed frames relative to one project folder.
+ */
+export class FrameClassifier {
+  /**
+   * @param {string} root - The project folder (ProjectIdentity#root)
+   */
+  constructor(root) {
+    this.root = path.resolve(root || process.cwd());
+    // Stack traces show where modules really are: a project reached through a symlink (macOS's
+    // /tmp and /var, linked workspaces, mounted volumes) appears under its real path there.
+    let real = this.root;
+    try {
+      real = fs.realpathSync(this.root);
+    } catch (error) {
+      real = this.root;
+    }
+    this.roots = real === this.root ? [this.root] : [this.root, real];
+  }
+
+  /**
+   * Completes a parsed frame with where it comes from.
+   *
+   * @param {import('./stack-parser.js').ParsedFrame} parsed
+   * @returns {Frame}
+   */
+  classify(parsed) {
+    const file = parsed.file;
+    let relativeFile = null;
+    let inApp = false;
+    let module = null;
+
+    if (file && file.startsWith('node:')) {
+      module = 'node';
+    } else if (file) {
+      module = FrameClassifier.moduleOf(file);
+      relativeFile = this.relativeFile(file);
+      inApp = relativeFile !== null && !relativeFile.split('/').includes('node_modules');
+    }
+
+    return {
+      function: parsed.function,
+      file,
+      relativeFile,
+      line: parsed.line,
+      column: parsed.column,
+      inApp,
+      module,
+      native: parsed.native,
+      async: parsed.async,
+      context: null
+    };
+  }
+
+  /**
+   * @param {string} file
+   * @returns {string|null} The path relative to the project folder, with forward slashes, or
+   *   null when the file is outside it (or isn't a path)
+   */
+  relativeFile(file) {
+    if (!path.isAbsolute(file)) return null;
+    for (const root of this.roots) {
+      const relative = path.relative(root, file);
+      if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue;
+      return relative.split(path.sep).join('/');
+    }
+    return null;
+  }
+
+  /**
+   * The npm package a file belongs to: the folder after the last node_modules segment, so
+   * nested installs and pnpm's .pnpm store name the package that actually runs.
+   *
+   * @param {string} file
+   * @returns {string|null}
+   */
+  static moduleOf(file) {
+    const segments = file.split(/[\\/]/);
+    const index = segments.lastIndexOf('node_modules');
+    if (index === -1 || index + 1 >= segments.length) return null;
+    const name = segments[index + 1];
+    if (name.startsWith('@')) {
+      return index + 2 < segments.length ? `${name}/${segments[index + 2]}` : null;
+    }
+    return name || null;
+  }
+}