opencons 0.1.0

package/src/transform/natural-language.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * @param {string | null | undefined} expr
+ */
+function phraseCondition(expr) {
+  if (!expr) return null;
+
+  return expr
+    .replace(/\s+/g, ' ')
+    .replace(/===/g, ' equals ')
+    .replace(/!==/g, ' does not equal ')
+    .replace(/==/g, ' equals ')
+    .replace(/!=/g, ' does not equal ')
+    .replace(/<=/g, ' is at most ')
+    .replace(/>=/g, ' is at least ')
+    .replace(/</g, ' is less than ')
+    .replace(/>/g, ' is greater than ')
+    .replace(/&&/g, ' and ')
+    .replace(/\|\|/g, ' or ')
+    .replace(/\b!/g, 'not ')
+    .trim();
+}
+
+/**
+ * @param {string} kind
+ * @param {string | null} condition
+ */
+function decisionTitle(kind, condition) {
+  const phrase = phraseCondition(condition);
+
+  if (kind === 'if' || kind === 'ternary') {
+    return phrase ? `Checked whether ${phrase}` : 'Checked an if condition';
+  }
+
+  if (kind === 'switch') {
+    return phrase ? `Switched on ${phrase}` : 'Evaluated a switch';
+  }
+
+  if (kind === 'while' || kind === 'for') {
+    return phrase ? `Loop condition: ${phrase}` : 'Evaluated a loop condition';
+  }
+
+  if (kind === 'catch') {
+    return 'Entered a catch block';
+  }
+
+  return phrase ? `Evaluated ${phrase}` : 'Evaluated a condition';
+}
+
+/**
+ * @param {string} kind
+ * @param {unknown} value
+ * @param {boolean} hasElse
+ */
+function buildIfOutcomes(value, hasElse) {
+  const truthy = Boolean(value);
+
+  const outcomes = [
+    {
+      key: 'then',
+      label: truthy ? 'Then block — ran' : 'Then block — skipped',
+      taken: truthy,
+    },
+  ];
+
+  if (hasElse) {
+    outcomes.push({
+      key: 'else',
+      label: truthy ? 'Else block — skipped' : 'Else block — pending',
+      taken: false,
+    });
+  }
+
+  return outcomes;
+}
+
+/**
+ * @param {string} kind
+ * @param {unknown} value
+ * @param {boolean} [hasElse]
+ */
+function decisionSummary(kind, value, hasElse = false) {
+  const truthy = Boolean(value);
+
+  if (kind === 'if' || kind === 'ternary') {
+    if (truthy) return 'Yes — code inside the then branch ran';
+    if (hasElse) return 'No — then branch skipped (else may run next)';
+    return 'No — then branch skipped';
+  }
+
+  if (kind === 'switch') {
+    return `Matched value ${formatValue(value)}`;
+  }
+
+  if (kind === 'while' || kind === 'for') {
+    return truthy ? 'Yes — loop body will run' : 'No — loop finished';
+  }
+
+  return truthy ? 'Condition was true' : 'Condition was false';
+}
+
+/**
+ * @param {unknown} value
+ */
+function formatValue(value) {
+  if (value === true) return 'true';
+  if (value === false) return 'false';
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') return `"${value}"`;
+  return String(value);
+}
+
+/**
+ * @param {object} node
+ */
+function applyElseTaken(node) {
+  const outcomes = (node.outcomes || []).map((outcome) => {
+    if (outcome.key === 'else') {
+      return { ...outcome, label: 'Else block — ran', taken: true };
+    }
+
+    if (outcome.key === 'then') {
+      return { ...outcome, label: 'Then block — skipped', taken: false };
+    }
+
+    return outcome;
+  });
+
+  return {
+    ...node,
+    outcomes,
+    taken_outcome: 'else',
+    summary: 'No — ran the else branch instead',
+  };
+}
+
+module.exports = {
+  phraseCondition,
+  decisionTitle,
+  buildIfOutcomes,
+  decisionSummary,
+  formatValue,
+  applyElseTaken,
+};

package/src/transform/probe.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const { getCurrentTracer } = require('../core/context');
+const {
+  decisionTitle,
+  buildIfOutcomes,
+  decisionSummary,
+  applyElseTaken,
+} = require('./natural-language');
+
+/**
+ * @param {string} label
+ */
+function parseProbeLabel(label) {
+  const parts = String(label).split(':');
+  const kind = parts[0] || 'branch';
+  const file = parts[1] || '';
+  const line = Number(parts[2]) || null;
+
+  return { kind, file, line };
+}
+
+/**
+ * Runtime probe injected into transformed application modules.
+ *
+ * @param {string} label
+ * @param {unknown} value
+ * @param {string} [conditionText]
+ * @param {boolean} [hasElse]
+ * @returns {unknown}
+ */
+function __rg_probe(label, value, conditionText, hasElse = false) {
+  const tracer = getCurrentTracer();
+
+  if (!tracer) {
+    return value;
+  }
+
+  const meta = parseProbeLabel(label);
+  const nodeType = meta.kind === 'while' || meta.kind === 'for' ? 'loop' : 'branch';
+  const title = decisionTitle(meta.kind, conditionText || null);
+  const summary = decisionSummary(meta.kind, value, hasElse);
+
+  const node = {
+    type: nodeType,
+    label: title,
+    summary,
+    value,
+    condition: conditionText || undefined,
+    has_else: hasElse || undefined,
+    duration_ms: null,
+    source: meta.file
+      ? {
+          file: meta.file,
+          line: meta.line,
+          kind: meta.kind,
+        }
+      : undefined,
+  };
+
+  if (meta.kind === 'if' || meta.kind === 'ternary') {
+    node.outcomes = buildIfOutcomes(value, hasElse);
+    node.taken_outcome = Boolean(value) ? 'then' : null;
+  }
+
+  tracer.addNode(node);
+
+  return value;
+}
+
+/**
+ * @param {string} label
+ */
+function __rg_else_probe(label) {
+  const tracer = getCurrentTracer();
+
+  if (!tracer) {
+    return;
+  }
+
+  const meta = parseProbeLabel(label.replace(/^else/, 'if'));
+  const lastIf = [...tracer.nodes]
+    .reverse()
+    .find(
+      (node) =>
+        node.source?.kind === 'if' &&
+        node.source.file === meta.file &&
+        node.source.line === meta.line
+    );
+
+  if (lastIf) {
+    Object.assign(lastIf, applyElseTaken(lastIf));
+    if (typeof tracer._notifyChange === 'function') {
+      tracer._notifyChange();
+    }
+    return;
+  }
+
+  tracer.addNode({
+    type: 'branch',
+    label: decisionTitle('if', null),
+    summary: 'Ran the else branch',
+    value: false,
+    has_else: true,
+    outcomes: [
+      { key: 'then', label: 'Then block — skipped', taken: false },
+      { key: 'else', label: 'Else block — ran', taken: true },
+    ],
+    taken_outcome: 'else',
+    duration_ms: null,
+    source: meta.file
+      ? {
+          file: meta.file,
+          line: meta.line,
+          kind: 'else',
+        }
+      : undefined,
+  });
+}
+
+/**
+ * @param {string} label
+ * @param {unknown} error
+ */
+function __rg_catch_probe(label, error) {
+  const tracer = getCurrentTracer();
+
+  if (!tracer) {
+    return error;
+  }
+
+  const meta = parseProbeLabel(label);
+  const message =
+    error && typeof error === 'object' && 'message' in error
+      ? String(error.message)
+      : String(error);
+
+  tracer.addNode({
+    type: 'error',
+    label: 'An error was caught',
+    summary: message ? `Caught: ${message}` : 'Entered catch block',
+    value: message,
+    duration_ms: null,
+    source: meta.file
+      ? {
+          file: meta.file,
+          line: meta.line,
+          kind: 'catch',
+        }
+      : undefined,
+  });
+
+  return error;
+}
+
+module.exports = {
+  __rg_probe,
+  __rg_else_probe,
+  __rg_catch_probe,
+  parseProbeLabel,
+};

package/src/transform/register.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const path = require('path');
+const { installRequireHook } = require('../interceptors/require-hook');
+
+/**
+ * Install the require hook immediately. Import this module BEFORE your
+ * application modules load:
+ *
+ *   require('opencons/register-transform');
+ *
+ * @param {object} [options]
+ * @param {string} [options.projectRoot]
+ * @param {string[]} [options.exclude]
+ */
+function registerTransform(options = {}) {
+  installRequireHook({
+    projectRoot:
+      options.projectRoot ||
+      process.env.OPENCONS_ROOT ||
+      process.env.ROUTEGRAPHER_ROOT ||
+      process.cwd(),
+    exclude:
+      options.exclude ||
+      splitEnvList(process.env.OPENCONS_TRANSFORM_EXCLUDE || process.env.ROUTEGRAPHER_TRANSFORM_EXCLUDE),
+  });
+}
+
+/**
+ * @param {string | undefined} value
+ */
+function splitEnvList(value) {
+  if (!value) return [];
+  return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+const transformEnabled =
+  process.env.OPENCONS_TRANSFORM || process.env.ROUTEGRAPHER_TRANSFORM;
+
+if (transformEnabled === '1' || transformEnabled === 'true') {
+  registerTransform();
+}
+
+module.exports = registerTransform;

package/src/utils/label.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Assign a display name to a middleware/handler for Opencons traces.
+ *
+ * @example
+ * app.use(Opencons.label('cors', corsFn));
+ * app.use(Opencons.label('bullAuth', bullAuth));
+ *
+ * @param {string} name
+ * @param {T} handler
+ * @returns {T}
+ * @template {Function} T
+ */
+function label(name, handler) {
+  if (typeof handler !== 'function') {
+    return handler;
+  }
+
+  handler.__openconsName = name;
+  return handler;
+}
+
+module.exports = {
+  label,
+};

package/src/utils/observable.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const { createRequire } = require('module');
+const path = require('path');
+const { runWithContext } = require('../core/context');
+
+/** @type {{ rxjs: typeof import('rxjs') } | null} */
+let cachedRxjs = null;
+
+/**
+ * Load rxjs from the host application (Nest consumer), not from Opencons.
+ */
+function loadRxjs() {
+  if (cachedRxjs) return cachedRxjs;
+
+  const searchPaths = [
+    process.cwd(),
+    ...(require.main?.paths || []),
+    path.join(process.cwd(), 'node_modules'),
+  ];
+
+  const hostRequire = createRequire(path.join(process.cwd(), 'package.json'));
+
+  for (const base of searchPaths) {
+    try {
+      const rxjsPath = hostRequire.resolve('rxjs', { paths: [base] });
+      cachedRxjs = { rxjs: hostRequire(rxjsPath) };
+      return cachedRxjs;
+    } catch {
+      // try next base
+    }
+  }
+
+  try {
+    cachedRxjs = { rxjs: require('rxjs') };
+    return cachedRxjs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wrap a Nest/RxJS observable and record when the stream completes.
+ *
+ * @param {unknown} source
+ * @param {(exitReason?: string) => void} onFinish
+ * @param {import('../core/context').TraceContext} [alsContext]
+ * @returns {unknown}
+ */
+function traceObservable(source, onFinish, alsContext) {
+  const finish = (reason) => {
+    if (alsContext) {
+      runWithContext(alsContext, () => onFinish(reason));
+      return;
+    }
+    onFinish(reason);
+  };
+
+  if (!source || typeof source.subscribe !== 'function') {
+    finish();
+    return source;
+  }
+
+  const loaded = loadRxjs();
+
+  if (!loaded?.rxjs?.Observable) {
+    return source;
+  }
+
+  const { Observable } = loaded.rxjs;
+
+  return new Observable((subscriber) => {
+    let innerSub;
+
+    try {
+      innerSub = source.subscribe({
+        next: (value) => subscriber.next(value),
+        error: (err) => {
+          finish(`error: ${err.message}`);
+          subscriber.error(err);
+        },
+        complete: () => {
+          finish();
+          subscriber.complete();
+        },
+      });
+    } catch (err) {
+      finish(`error: ${err.message}`);
+      subscriber.error(err);
+    }
+
+    return () => {
+      if (innerSub && typeof innerSub.unsubscribe === 'function') {
+        innerSub.unsubscribe();
+      }
+    };
+  });
+}
+
+module.exports = {
+  traceObservable,
+  loadRxjs,
+};