opencons 0.1.0

package/src/core/index.js

@@ -0,0 +1,198 @@
+'use strict';
+
+const { runWithContext, getCurrentContext } = require('./context');
+const { TraceTracer } = require('./tracer');
+const { createTraceStore } = require('../store/trace-store');
+const { createWebSocketServer } = require('../server/ws');
+const { createStaticServer } = require('../server/static');
+const { installRequireHook } = require('../interceptors/require-hook');
+const { installDrivers } = require('../drivers');
+const { resolveOptions, isProductionDisabled } = require('../lib/config');
+const { logger } = require('../lib/logger');
+const { safeClone } = require('../lib/serialize');
+
+/** @typedef {import('../lib/config').OpenconsOptions} OpenconsOptions */
+
+/** @type {ReturnType<import('../store/trace-store').createTraceStore> | null} */
+let traceStore = null;
+
+/** @type {boolean} */
+let initialised = false;
+
+/** @type {OpenconsOptions | null} */
+let activeOptions = null;
+
+/**
+ * @param {Partial<OpenconsOptions>} [userOptions]
+ * @returns {import('express').RequestHandler}
+ */
+function createOpencons(userOptions = {}) {
+  let options;
+
+  try {
+    options = resolveOptions(userOptions);
+  } catch (err) {
+    logger.error(`Invalid configuration: ${err.message}`);
+    throw err;
+  }
+
+  if (isProductionDisabled(options)) {
+    logger.warn('Disabled in production. Opencons is intended for development only.');
+    return (_req, _res, next) => next();
+  }
+
+  if (initialised) {
+    if (activeOptions && JSON.stringify(activeOptions) !== JSON.stringify(options)) {
+      logger.warn('Already initialised — additional options are ignored. Call opencons() once.');
+    }
+
+    return buildMiddleware(options);
+  }
+
+  initialised = true;
+  activeOptions = options;
+  traceStore = createTraceStore(options.maxTraces);
+
+  if (options.transform?.enabled) {
+    installRequireHook({
+      projectRoot: options.transform.projectRoot || process.cwd(),
+      exclude: options.transform.exclude || [],
+    });
+  }
+
+  installDrivers(options.drivers);
+
+  if (options.enableWidget) {
+    createStaticServer(options.port)
+      .then(({ port }) => {
+        options.widgetPort = port;
+        createWebSocketServer(traceStore);
+      })
+      .catch((err) => {
+        logger.error(`Widget server failed to start: ${err.message}`, err);
+      });
+  }
+
+  return buildMiddleware(options);
+}
+
+/**
+ * @param {OpenconsOptions} options
+ * @returns {import('express').RequestHandler}
+ */
+function buildMiddleware(options) {
+  let loggedFirstRequest = false;
+
+  /**
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {import('express').NextFunction} next
+   */
+  function middleware(req, res, next) {
+    if (!traceStore) {
+      return next();
+    }
+
+    // Nest hook + prepend can both invoke this — trace once per request.
+    if (getCurrentContext()) {
+      return next();
+    }
+
+    if (shouldExclude(req, options.exclude)) {
+      return next();
+    }
+
+    if (!loggedFirstRequest) {
+      loggedFirstRequest = true;
+      logger.info(`Tracing ${req.method} ${req.originalUrl || req.url}`);
+    }
+
+    /** @type {unknown} */
+    let capturedResponse;
+
+    if (options.captureResponse) {
+      attachResponseCapture(res, (body) => {
+        capturedResponse = safeClone(body);
+      });
+    }
+
+    const tracer = new TraceTracer({
+      method: req.method,
+      url: req.originalUrl || req.url,
+      params: req.params,
+      body: options.captureBody ? safeClone(req.body) : undefined,
+    });
+
+    tracer.onChange = () => {
+      traceStore.update(tracer.snapshot());
+    };
+
+    traceStore.start(tracer.snapshot());
+
+    const context = {
+      id: tracer.id,
+      startTime: tracer.startTime,
+      tracer,
+    };
+
+    let finished = false;
+
+    const onFinish = () => {
+      if (finished) return;
+      finished = true;
+      tracer.onChange = null;
+      traceStore.complete(tracer.finish(res.statusCode, capturedResponse));
+    };
+
+    res.on('finish', onFinish);
+    res.on('close', onFinish);
+
+    runWithContext(context, () => next());
+  }
+
+  middleware.getTraces = () => (traceStore ? traceStore.getAll() : []);
+  middleware.options = options;
+  middleware.__openconsEntry = true;
+
+  return middleware;
+}
+
+/**
+ * @param {import('express').Response} res
+ * @param {(body: unknown) => void} onCapture
+ */
+function attachResponseCapture(res, onCapture) {
+  const originalJson = res.json.bind(res);
+  res.json = function patchedJson(body) {
+    onCapture(body);
+    return originalJson(body);
+  };
+
+  const originalSend = res.send.bind(res);
+  res.send = function patchedSend(body) {
+    onCapture(body);
+    return originalSend(body);
+  };
+}
+
+/**
+ * @param {import('express').Request} req
+ * @param {string[]} excludePatterns
+ */
+function shouldExclude(req, excludePatterns) {
+  const path = req.originalUrl || req.url;
+
+  return excludePatterns.some((pattern) => {
+    if (pattern.includes('*')) {
+      const regex = new RegExp(
+        `^${pattern.replace(/\*/g, '.*').replace(/\//g, '\\/')}$`
+      );
+      return regex.test(path.split('?')[0]);
+    }
+    return path.startsWith(pattern);
+  });
+}
+
+module.exports = {
+  createOpencons,
+};

package/src/core/tracer.js

@@ -0,0 +1,252 @@
+'use strict';
+
+const { randomBytes } = require('crypto');
+const { getCurrentContext } = require('./context');
+
+/**
+ * @typedef {'request' | 'middleware' | 'controller' | 'branch' | 'loop' | 'db' | 'response' | 'error'} NodeType
+ */
+
+/**
+ * @typedef {Object} TraceNode
+ * @property {string} id
+ * @property {NodeType} type
+ * @property {string} label
+ * @property {string} [summary]
+ * @property {string} [condition]
+ * @property {boolean} [has_else]
+ * @property {{ key: string, label: string, taken: boolean }[]} [outcomes]
+ * @property {string | null} [taken_outcome]
+ * @property {number | null} duration_ms
+ * @property {boolean} [called_next]
+ * @property {string} [exit_reason]
+ * @property {*} [value]
+ * @property {number} [rows]
+ * @property {string} [query]
+ * @property {unknown} [params]
+ * @property {string} [driver]
+ * @property {string} [operation]
+ * @property {string} [collection]
+ * @property {'select' | 'insert' | 'update' | 'delete' | 'count' | 'transaction' | 'query'} [db_action]
+ * @property {string} [db_intent]
+ * @property {string} [db_result]
+ * @property {{ file: string, line: number | null, kind?: string }} [source]
+ */
+
+/**
+ * @typedef {Object} TraceEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {boolean} [parallel]
+ */
+
+/**
+ * @typedef {Object} TraceGraph
+ * @property {string} id
+ * @property {number} timestamp
+ * @property {string} method
+ * @property {string} url
+ * @property {Record<string, string>} params
+ * @property {unknown} [body]
+ * @property {unknown} [response]
+ * @property {number | null} status
+ * @property {number} duration_ms
+ * @property {'active' | 'complete'} [state]
+ * @property {TraceNode[]} nodes
+ * @property {TraceEdge[]} edges
+ */
+
+class TraceTracer {
+  /**
+   * @param {Object} meta
+   * @param {string} meta.method
+   * @param {string} meta.url
+   * @param {Record<string, string>} [meta.params]
+   * @param {unknown} [meta.body]
+   */
+  constructor(meta) {
+    this.id = `req_${randomBytes(4).toString('hex')}`;
+    this.timestamp = Date.now();
+    this.method = meta.method;
+    this.url = meta.url;
+    this.params = meta.params || {};
+    this.body = meta.body;
+    this.status = null;
+    this.startTime = performance.now();
+    this._nodeCounter = 0;
+    this._lastNodeId = null;
+
+    const requestNode = this._createNode({
+      type: 'request',
+      label: `${meta.method} ${meta.url}`,
+      duration_ms: null,
+    });
+
+    this.nodes = [requestNode];
+    this.edges = [];
+    this._lastNodeId = requestNode.id;
+    this._finished = false;
+
+    /** @type {(() => void) | null} */
+    this.onChange = null;
+  }
+
+  _nextNodeId() {
+    this._nodeCounter += 1;
+    return `n${this._nodeCounter}`;
+  }
+
+  /**
+   * @param {Omit<TraceNode, 'id'>} nodeData
+   * @returns {TraceNode}
+   */
+  _createNode(nodeData) {
+    return {
+      id: this._nextNodeId(),
+      ...nodeData,
+    };
+  }
+
+  /**
+   * @param {Omit<TraceNode, 'id'>} nodeData
+   * @returns {TraceNode}
+   */
+  addNode(nodeData) {
+    const node = this._createNode(nodeData);
+    this.nodes.push(node);
+
+    if (this._lastNodeId) {
+      this.edges.push({ from: this._lastNodeId, to: node.id });
+    }
+
+    this._lastNodeId = node.id;
+    this._setScopeNode(node);
+    this._notifyChange();
+    return node;
+  }
+
+  /**
+   * Record a concurrent branch (e.g. database query) from the active handler scope.
+   * @param {string | null | undefined} parentId
+   * @param {Omit<TraceNode, 'id'>} nodeData
+   * @returns {TraceNode}
+   */
+  addForkNode(parentId, nodeData) {
+    const node = this._createNode(nodeData);
+    const from = parentId || this._lastNodeId;
+
+    this.nodes.push(node);
+
+    if (from) {
+      this.edges.push({ from, to: node.id, parallel: true });
+    }
+
+    this._notifyChange();
+    return node;
+  }
+
+  /**
+   * @param {string} nodeId
+   * @param {Partial<TraceNode>} patch
+   */
+  updateNode(nodeId, patch) {
+    const node = this.nodes.find((entry) => entry.id === nodeId);
+    if (!node) return;
+    Object.assign(node, patch);
+    this._notifyChange();
+  }
+
+  /**
+   * @returns {string | null}
+   */
+  getLastSequentialNodeId() {
+    return this._lastNodeId;
+  }
+
+  /**
+   * @param {TraceNode} node
+   */
+  _setScopeNode(node) {
+    if (node.type === 'db') return;
+
+    const ctx = getCurrentContext();
+    if (ctx) {
+      ctx.scopeNodeId = node.id;
+    }
+  }
+
+  _notifyChange() {
+    if (this.onChange && !this._finished) {
+      this.onChange();
+    }
+  }
+
+  /**
+   * @returns {TraceGraph}
+   */
+  snapshot() {
+    return {
+      id: this.id,
+      timestamp: this.timestamp,
+      method: this.method,
+      url: this.url,
+      params: this.params,
+      body: this.body,
+      status: this.status,
+      state: 'active',
+      duration_ms: Math.round((performance.now() - this.startTime) * 10) / 10,
+      nodes: this.nodes,
+      edges: this.edges,
+    };
+  }
+
+  /**
+   * @param {string} from
+   * @param {string} to
+   */
+  addEdge(from, to) {
+    this.edges.push({ from, to });
+  }
+
+  /**
+   * @param {number} status
+   * @param {unknown} [response]
+   * @returns {TraceGraph}
+   */
+  finish(status, response) {
+    this._finished = true;
+    this.status = status;
+    const duration_ms = Math.round((performance.now() - this.startTime) * 10) / 10;
+
+    const responseNode = this._createNode({
+      type: 'response',
+      label: `${status}`,
+      duration_ms: null,
+    });
+
+    this.nodes.push(responseNode);
+
+    if (this._lastNodeId) {
+      this.edges.push({ from: this._lastNodeId, to: responseNode.id });
+    }
+
+    return {
+      id: this.id,
+      timestamp: this.timestamp,
+      method: this.method,
+      url: this.url,
+      params: this.params,
+      body: this.body,
+      response,
+      status: this.status,
+      state: 'complete',
+      duration_ms,
+      nodes: this.nodes,
+      edges: this.edges,
+    };
+  }
+}
+
+module.exports = {
+  TraceTracer,
+};

package/src/drivers/db-language.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * @param {string} sql
+ */
+function extractTableFromSql(sql) {
+  const text = String(sql || '').replace(/\s+/g, ' ').trim();
+
+  const patterns = [
+    /\bfrom\s+["'`]?([a-zA-Z_][\w$]*)/i,
+    /\binto\s+["'`]?([a-zA-Z_][\w$]*)/i,
+    /\bupdate\s+["'`]?([a-zA-Z_][\w$]*)/i,
+    /\bjoin\s+["'`]?([a-zA-Z_][\w$]*)/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match) return match[1];
+  }
+
+  return undefined;
+}
+
+/**
+ * @param {string | undefined} name
+ */
+function humanizeName(name) {
+  if (!name) return 'records';
+
+  return String(name)
+    .replace(/^["'`]|["'`]$/g, '')
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase();
+}
+
+/**
+ * @param {object} meta
+ * @param {string} [meta.driver]
+ * @param {string} [meta.operation]
+ * @param {string} [meta.query]
+ */
+function inferDbAction(meta) {
+  const operation = String(meta.operation || '').toLowerCase();
+  const query = String(meta.query || '').trim();
+  const sql = query.toUpperCase();
+
+  if (meta.driver === 'prisma') {
+    if (/^find|aggregate|groupby/i.test(operation)) return 'select';
+    if (/^create/i.test(operation)) return 'insert';
+    if (/^update|upsert/i.test(operation)) return 'update';
+    if (/^delete/i.test(operation)) return 'delete';
+    if (operation === 'count') return 'count';
+    if (operation === 'queryRaw' || operation === 'executeRaw') return 'query';
+    return 'query';
+  }
+
+  if (meta.driver === 'mongoose') {
+    if (/find|distinct|count/i.test(operation)) return operation.includes('count') ? 'count' : 'select';
+    if (/insert|save|create/i.test(operation)) return 'insert';
+    if (/update|replace/i.test(operation)) return 'update';
+    if (/delete|remove/i.test(operation)) return 'delete';
+    return 'query';
+  }
+
+  if (sql.startsWith('SELECT') || sql.startsWith('WITH')) return 'select';
+  if (sql.startsWith('INSERT')) return 'insert';
+  if (sql.startsWith('UPDATE')) return 'update';
+  if (sql.startsWith('DELETE')) return 'delete';
+  if (/\bCOUNT\s*\(/i.test(sql)) return 'count';
+  if (/^(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)/i.test(sql)) return 'transaction';
+
+  return 'query';
+}
+
+/**
+ * @param {'select' | 'insert' | 'update' | 'delete' | 'count' | 'transaction' | 'query'} action
+ * @param {string | undefined} table
+ */
+function describeDbIntent(action, table) {
+  const target = humanizeName(table);
+
+  switch (action) {
+    case 'select':
+      return `Fetching ${target}`;
+    case 'insert':
+      return `Saving to ${target}`;
+    case 'update':
+      return `Updating ${target}`;
+    case 'delete':
+      return `Removing from ${target}`;
+    case 'count':
+      return `Counting ${target}`;
+    case 'transaction':
+      return 'Running a database transaction';
+    default:
+      return table ? `Querying ${target}` : 'Running a database query';
+  }
+}
+
+/**
+ * @param {'select' | 'insert' | 'update' | 'delete' | 'count' | 'transaction' | 'query'} action
+ * @param {number | undefined} rows
+ * @param {string | undefined} error
+ */
+function describeDbResult(action, rows, error) {
+  if (error) {
+    const short = error.length > 72 ? `${error.slice(0, 72)}…` : error;
+    return `Failed — ${short}`;
+  }
+
+  switch (action) {
+    case 'select':
+      if (rows === 0) return 'Nothing found';
+      if (rows === 1) return 'Returned 1 record';
+      if (rows != null) return `Returned ${rows} records`;
+      return 'Lookup finished';
+    case 'insert':
+      if (rows === 1) return 'Submitted 1 new row';
+      if (rows != null && rows > 1) return `Submitted ${rows} new rows`;
+      return 'Save completed';
+    case 'update':
+      if (rows === 0) return 'No rows changed';
+      if (rows === 1) return 'Updated 1 row';
+      if (rows != null) return `Updated ${rows} rows`;
+      return 'Update completed';
+    case 'delete':
+      if (rows === 0) return 'Nothing removed';
+      if (rows === 1) return 'Removed 1 row';
+      if (rows != null) return `Removed ${rows} rows`;
+      return 'Delete completed';
+    case 'count':
+      if (rows != null) return `Count is ${rows}`;
+      return 'Count completed';
+    case 'transaction':
+      return 'Transaction step completed';
+    default:
+      if (rows === 0) return 'No rows affected';
+      if (rows === 1) return '1 row affected';
+      if (rows != null) return `${rows} rows affected`;
+      return 'Query completed';
+  }
+}
+
+/**
+ * @param {'select' | 'insert' | 'update' | 'delete' | 'count' | 'transaction' | 'query'} action
+ * @param {string | undefined} table
+ */
+function describeDbLabel(action, table) {
+  const target = humanizeName(table);
+
+  switch (action) {
+    case 'select':
+      return `Fetch ${target}`;
+    case 'insert':
+      return `Save ${target}`;
+    case 'update':
+      return `Update ${target}`;
+    case 'delete':
+      return `Delete ${target}`;
+    case 'count':
+      return `Count ${target}`;
+    case 'transaction':
+      return 'Transaction';
+    default:
+      return table ? `Query ${target}` : 'Database query';
+  }
+}
+
+/**
+ * @param {object} meta
+ * @param {string} [meta.driver]
+ * @param {string} [meta.operation]
+ * @param {string} [meta.query]
+ * @param {string} [meta.collection]
+ * @param {number} [meta.rows]
+ * @param {number} [meta.duration_ms]
+ * @param {string} [meta.error]
+ */
+function buildDbNodeLanguage(meta) {
+  const action = inferDbAction(meta);
+  const table = meta.collection || extractTableFromSql(meta.query);
+  const intent = describeDbIntent(action, table);
+  const result = describeDbResult(action, meta.rows, meta.error);
+  const label = describeDbLabel(action, table);
+  const summary = meta.error
+    ? result
+    : `${result}${meta.duration_ms != null ? ` · ${meta.duration_ms}ms` : ''}`;
+
+  return {
+    label,
+    summary,
+    db_action: action,
+    db_intent: intent,
+    db_result: result,
+  };
+}
+
+module.exports = {
+  extractTableFromSql,
+  humanizeName,
+  inferDbAction,
+  describeDbIntent,
+  describeDbResult,
+  describeDbLabel,
+  buildDbNodeLanguage,
+};

package/src/drivers/detect.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { createRequire } = require('module');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * @param {string} packageName
+ */
+function isPackageInstalled(packageName) {
+  const searchPaths = [
+    process.cwd(),
+    path.join(process.cwd(), 'node_modules'),
+    ...(require.main?.paths || []),
+  ];
+
+  const hostRequire = createRequire(path.join(process.cwd(), 'package.json'));
+
+  for (const base of searchPaths) {
+    try {
+      hostRequire.resolve(packageName, { paths: [base] });
+      return true;
+    } catch {
+      // try next
+    }
+  }
+
+  const localNodeModules = path.join(process.cwd(), 'node_modules', packageName);
+  return fs.existsSync(localNodeModules);
+}
+
+/**
+ * @param {Partial<Record<'mongoose' | 'pg' | 'prisma' | 'mysql2' | 'drizzle', boolean>>} [config]
+ */
+function resolveDriverConfig(config = {}) {
+  const detected = {
+    mongoose: isPackageInstalled('mongoose'),
+    pg: isPackageInstalled('pg'),
+    prisma: isPackageInstalled('@prisma/client'),
+    mysql2: isPackageInstalled('mysql2'),
+    drizzle: isPackageInstalled('drizzle-orm'),
+  };
+
+  const drizzle = config.drizzle !== false && detected.drizzle;
+
+  // Drizzle uses pg/mysql2 underneath — patch at the ORM layer to avoid duplicate nodes.
+  const pgExplicit = config.pg === true;
+  const mysql2Explicit = config.mysql2 === true;
+
+  return {
+    mongoose: config.mongoose !== false && detected.mongoose,
+    drizzle,
+    pg: config.pg !== false && detected.pg && (!drizzle || pgExplicit),
+    prisma: config.prisma !== false && detected.prisma,
+    mysql2: config.mysql2 !== false && detected.mysql2 && (!drizzle || mysql2Explicit),
+  };
+}
+
+module.exports = {
+  isPackageInstalled,
+  resolveDriverConfig,
+};