executable-stories-vitest 8.8.5 → 8.9.0

package/dist/otel.d.cts

@@ -0,0 +1,64 @@
+/**
+ * Collect the spans Vitest's OpenTelemetry instrumentation produces, so a
+ * story can claim the ones that belong to it.
+ *
+ * Vitest wraps every test in a span, which means `story.init()` already
+ * captures a trace id with no extra wiring. This is the other half: a
+ * SpanProcessor that keeps finished spans grouped by trace id, so the story
+ * can take its own at the end of the test.
+ */
+/** A finished span, in the shape an OTel SDK hands a SpanProcessor. */
+interface ReadableSpanLike {
+    name: string;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+    };
+    /** Current OTel SDKs. */
+    parentSpanContext?: {
+        spanId: string;
+    };
+    /** Older OTel SDKs carried the parent as a bare id. */
+    parentSpanId?: string;
+    attributes?: Record<string, unknown>;
+    status?: {
+        code: number;
+        message?: string;
+    };
+}
+/** A span in the shape the story report carries. */
+interface CollectedSpan {
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    attributes?: Record<string, unknown>;
+    status: "ok" | "error" | "unset";
+    statusMessage?: string;
+}
+/**
+ * Structurally an OpenTelemetry `SpanProcessor`, plus the drain the story API
+ * uses. Declared here rather than imported so the published types carry no
+ * OTel dependency; `otel-span-processor.test.ts` holds it to the real
+ * interface by handing one to a real tracer provider.
+ *
+ * `onStart`, `forceFlush` and `shutdown` are not optional. A provider wraps
+ * every processor in a `MultiSpanProcessor`, which calls all three without
+ * checking they exist — only `onEnding` is guarded — so a collector missing
+ * one throws on the first span of the run.
+ */
+interface StorySpanCollector {
+    onStart(): void;
+    onEnd(span: ReadableSpanLike): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    takeSpansForTrace(traceId: string): CollectedSpan[];
+}
+/**
+ * The spans that ended during `traceId`, or none when no collector is
+ * installed. Called by `story.init()` at test end; a suite that never
+ * configured OpenTelemetry gets an empty list and no behaviour change.
+ */
+declare function takeCollectedSpans(traceId: string): CollectedSpan[];
+declare function storySpanCollector(): StorySpanCollector;
+
+export { type CollectedSpan, type ReadableSpanLike, type StorySpanCollector, storySpanCollector, takeCollectedSpans };

package/dist/otel.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Collect the spans Vitest's OpenTelemetry instrumentation produces, so a
+ * story can claim the ones that belong to it.
+ *
+ * Vitest wraps every test in a span, which means `story.init()` already
+ * captures a trace id with no extra wiring. This is the other half: a
+ * SpanProcessor that keeps finished spans grouped by trace id, so the story
+ * can take its own at the end of the test.
+ */
+/** A finished span, in the shape an OTel SDK hands a SpanProcessor. */
+interface ReadableSpanLike {
+    name: string;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+    };
+    /** Current OTel SDKs. */
+    parentSpanContext?: {
+        spanId: string;
+    };
+    /** Older OTel SDKs carried the parent as a bare id. */
+    parentSpanId?: string;
+    attributes?: Record<string, unknown>;
+    status?: {
+        code: number;
+        message?: string;
+    };
+}
+/** A span in the shape the story report carries. */
+interface CollectedSpan {
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    attributes?: Record<string, unknown>;
+    status: "ok" | "error" | "unset";
+    statusMessage?: string;
+}
+/**
+ * Structurally an OpenTelemetry `SpanProcessor`, plus the drain the story API
+ * uses. Declared here rather than imported so the published types carry no
+ * OTel dependency; `otel-span-processor.test.ts` holds it to the real
+ * interface by handing one to a real tracer provider.
+ *
+ * `onStart`, `forceFlush` and `shutdown` are not optional. A provider wraps
+ * every processor in a `MultiSpanProcessor`, which calls all three without
+ * checking they exist — only `onEnding` is guarded — so a collector missing
+ * one throws on the first span of the run.
+ */
+interface StorySpanCollector {
+    onStart(): void;
+    onEnd(span: ReadableSpanLike): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    takeSpansForTrace(traceId: string): CollectedSpan[];
+}
+/**
+ * The spans that ended during `traceId`, or none when no collector is
+ * installed. Called by `story.init()` at test end; a suite that never
+ * configured OpenTelemetry gets an empty list and no behaviour change.
+ */
+declare function takeCollectedSpans(traceId: string): CollectedSpan[];
+declare function storySpanCollector(): StorySpanCollector;
+
+export { type CollectedSpan, type ReadableSpanLike, type StorySpanCollector, storySpanCollector, takeCollectedSpans };

package/dist/otel.js

@@ -0,0 +1,59 @@
+// src/otel.ts
+var MAX_SPANS_PER_TRACE = 500;
+function statusOf(code) {
+  if (code === 2) return "error";
+  if (code === 1) return "ok";
+  return "unset";
+}
+var REGISTRY = /* @__PURE__ */ Symbol.for("executable-stories.span-collector");
+function registry() {
+  return globalThis;
+}
+function takeCollectedSpans(traceId) {
+  return registry()[REGISTRY]?.takeSpansForTrace(traceId) ?? [];
+}
+function storySpanCollector() {
+  const byTrace = /* @__PURE__ */ new Map();
+  const collector = {
+    // Nothing to do at span start: a span is only useful once it has ended and
+    // carries its duration, status and attributes. Present because the SDK
+    // calls it, not because it has work.
+    onStart() {
+    },
+    onEnd(span) {
+      const { traceId, spanId } = span.spanContext();
+      const spans = byTrace.get(traceId) ?? [];
+      if (spans.length >= MAX_SPANS_PER_TRACE) return;
+      const parentSpanId = span.parentSpanContext?.spanId ?? span.parentSpanId;
+      spans.push({
+        spanId,
+        ...parentSpanId ? { parentSpanId } : {},
+        name: span.name,
+        ...span.attributes && Object.keys(span.attributes).length > 0 ? { attributes: span.attributes } : {},
+        status: statusOf(span.status?.code),
+        ...span.status?.message ? { statusMessage: span.status.message } : {}
+      });
+      byTrace.set(traceId, spans);
+    },
+    // Nothing is buffered for export and nothing outlives the worker, so both
+    // lifecycle calls have nothing to do. Spans are held in memory until the
+    // story that owns them takes them, and a shutdown must not discard them:
+    // an SDK shut down before the last story drains would otherwise lose it.
+    async forceFlush() {
+    },
+    async shutdown() {
+    },
+    takeSpansForTrace(traceId) {
+      const spans = byTrace.get(traceId) ?? [];
+      byTrace.delete(traceId);
+      return spans;
+    }
+  };
+  registry()[REGISTRY] = collector;
+  return collector;
+}
+export {
+  storySpanCollector,
+  takeCollectedSpans
+};
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/otel.ts"],"sourcesContent":["/**\n * Collect the spans Vitest's OpenTelemetry instrumentation produces, so a\n * story can claim the ones that belong to it.\n *\n * Vitest wraps every test in a span, which means `story.init()` already\n * captures a trace id with no extra wiring. This is the other half: a\n * SpanProcessor that keeps finished spans grouped by trace id, so the story\n * can take its own at the end of the test.\n */\n\n/** A finished span, in the shape an OTel SDK hands a SpanProcessor. */\nexport interface ReadableSpanLike {\n  name: string;\n  spanContext(): { traceId: string; spanId: string };\n  /** Current OTel SDKs. */\n  parentSpanContext?: { spanId: string };\n  /** Older OTel SDKs carried the parent as a bare id. */\n  parentSpanId?: string;\n  attributes?: Record<string, unknown>;\n  status?: { code: number; message?: string };\n}\n\n/** A span in the shape the story report carries. */\nexport interface CollectedSpan {\n  spanId: string;\n  parentSpanId?: string;\n  name: string;\n  attributes?: Record<string, unknown>;\n  status: \"ok\" | \"error\" | \"unset\";\n  statusMessage?: string;\n}\n\n/**\n * Structurally an OpenTelemetry `SpanProcessor`, plus the drain the story API\n * uses. Declared here rather than imported so the published types carry no\n * OTel dependency; `otel-span-processor.test.ts` holds it to the real\n * interface by handing one to a real tracer provider.\n *\n * `onStart`, `forceFlush` and `shutdown` are not optional. A provider wraps\n * every processor in a `MultiSpanProcessor`, which calls all three without\n * checking they exist — only `onEnding` is guarded — so a collector missing\n * one throws on the first span of the run.\n */\nexport interface StorySpanCollector {\n  onStart(): void;\n  onEnd(span: ReadableSpanLike): void;\n  forceFlush(): Promise<void>;\n  shutdown(): Promise<void>;\n  takeSpansForTrace(traceId: string): CollectedSpan[];\n}\n\n/**\n * Spans kept per trace. Auto-instrumentation on a loop of queries produces\n * hundreds of near-identical leaf spans, and the architecture is described by\n * the first few of them. The head is kept because a trace arrives roughly\n * root-first, so keeping it keeps the shape and drops the repetition.\n */\nconst MAX_SPANS_PER_TRACE = 500;\n\n/** OTel SpanStatusCode: 0 UNSET, 1 OK, 2 ERROR. */\nfunction statusOf(code: number | undefined): \"ok\" | \"error\" | \"unset\" {\n  if (code === 2) return \"error\";\n  if (code === 1) return \"ok\";\n  return \"unset\";\n}\n\n/**\n * The collector the story API drains from, parked on `globalThis`.\n *\n * A module-level variable would be wrong here. The collector is constructed in\n * the OTel SDK module Vitest loads, and the story API is imported by the test\n * file; those are not guaranteed to be the same module instance, and a test\n * that mocks anything in the story API's import chain gets a second module\n * graph where a module-level `installed` reads as undefined. The realm is the\n * only thing both sides reliably share.\n *\n * Still per-worker: Vitest gives each worker its own realm, so two workers\n * never see each other's spans.\n */\nconst REGISTRY = Symbol.for(\"executable-stories.span-collector\");\n\ntype Registry = { [REGISTRY]?: StorySpanCollector };\n\nfunction registry(): Registry {\n  return globalThis as unknown as Registry;\n}\n\n/**\n * The spans that ended during `traceId`, or none when no collector is\n * installed. Called by `story.init()` at test end; a suite that never\n * configured OpenTelemetry gets an empty list and no behaviour change.\n */\nexport function takeCollectedSpans(traceId: string): CollectedSpan[] {\n  return registry()[REGISTRY]?.takeSpansForTrace(traceId) ?? [];\n}\n\nexport function storySpanCollector(): StorySpanCollector {\n  const byTrace = new Map<string, CollectedSpan[]>();\n\n  const collector: StorySpanCollector = {\n    // Nothing to do at span start: a span is only useful once it has ended and\n    // carries its duration, status and attributes. Present because the SDK\n    // calls it, not because it has work.\n    onStart() {},\n    onEnd(span) {\n      const { traceId, spanId } = span.spanContext();\n      const spans = byTrace.get(traceId) ?? [];\n      if (spans.length >= MAX_SPANS_PER_TRACE) return;\n      // The parent moved from a bare id to a span context across OTel SDK\n      // versions, and this package pins neither.\n      const parentSpanId = span.parentSpanContext?.spanId ?? span.parentSpanId;\n      spans.push({\n        spanId,\n        ...(parentSpanId ? { parentSpanId } : {}),\n        name: span.name,\n        ...(span.attributes && Object.keys(span.attributes).length > 0\n          ? { attributes: span.attributes }\n          : {}),\n        status: statusOf(span.status?.code),\n        ...(span.status?.message ? { statusMessage: span.status.message } : {}),\n      });\n      byTrace.set(traceId, spans);\n    },\n    // Nothing is buffered for export and nothing outlives the worker, so both\n    // lifecycle calls have nothing to do. Spans are held in memory until the\n    // story that owns them takes them, and a shutdown must not discard them:\n    // an SDK shut down before the last story drains would otherwise lose it.\n    async forceFlush() {},\n    async shutdown() {},\n    takeSpansForTrace(traceId) {\n      const spans = byTrace.get(traceId) ?? [];\n      byTrace.delete(traceId);\n      return spans;\n    },\n  };\n\n  registry()[REGISTRY] = collector;\n  return collector;\n}\n"],"mappings":";AAyDA,IAAM,sBAAsB;AAG5B,SAAS,SAAS,MAAoD;AACpE,MAAI,SAAS,EAAG,QAAO;AACvB,MAAI,SAAS,EAAG,QAAO;AACvB,SAAO;AACT;AAeA,IAAM,WAAW,uBAAO,IAAI,mCAAmC;AAI/D,SAAS,WAAqB;AAC5B,SAAO;AACT;AAOO,SAAS,mBAAmB,SAAkC;AACnE,SAAO,SAAS,EAAE,QAAQ,GAAG,kBAAkB,OAAO,KAAK,CAAC;AAC9D;AAEO,SAAS,qBAAyC;AACvD,QAAM,UAAU,oBAAI,IAA6B;AAEjD,QAAM,YAAgC;AAAA;AAAA;AAAA;AAAA,IAIpC,UAAU;AAAA,IAAC;AAAA,IACX,MAAM,MAAM;AACV,YAAM,EAAE,SAAS,OAAO,IAAI,KAAK,YAAY;AAC7C,YAAM,QAAQ,QAAQ,IAAI,OAAO,KAAK,CAAC;AACvC,UAAI,MAAM,UAAU,oBAAqB;AAGzC,YAAM,eAAe,KAAK,mBAAmB,UAAU,KAAK;AAC5D,YAAM,KAAK;AAAA,QACT;AAAA,QACA,GAAI,eAAe,EAAE,aAAa,IAAI,CAAC;AAAA,QACvC,MAAM,KAAK;AAAA,QACX,GAAI,KAAK,cAAc,OAAO,KAAK,KAAK,UAAU,EAAE,SAAS,IACzD,EAAE,YAAY,KAAK,WAAW,IAC9B,CAAC;AAAA,QACL,QAAQ,SAAS,KAAK,QAAQ,IAAI;AAAA,QAClC,GAAI,KAAK,QAAQ,UAAU,EAAE,eAAe,KAAK,OAAO,QAAQ,IAAI,CAAC;AAAA,MACvE,CAAC;AACD,cAAQ,IAAI,SAAS,KAAK;AAAA,IAC5B;AAAA;AAAA;AAAA;AAAA;AAAA,IAKA,MAAM,aAAa;AAAA,IAAC;AAAA,IACpB,MAAM,WAAW;AAAA,IAAC;AAAA,IAClB,kBAAkB,SAAS;AACzB,YAAM,QAAQ,QAAQ,IAAI,OAAO,KAAK,CAAC;AACvC,cAAQ,OAAO,OAAO;AACtB,aAAO;AAAA,IACT;AAAA,EACF;AAEA,WAAS,EAAE,QAAQ,IAAI;AACvB,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-vitest",
-  "version": "8.8.5",
+  "version": "8.9.0",
   "description": "TS-first story/given/when/then helpers for Vitest with Markdown user-story doc generation.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "homepage": "https://github.com/jagreehal/executable-stories#readme",
@@ -28,6 +28,11 @@
       "types": "./dist/reporter.d.ts",
       "import": "./dist/reporter.js",
       "require": "./dist/reporter.cjs"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "import": "./dist/otel.js",
+      "require": "./dist/otel.cjs"
     }
   },
   "files": [
@@ -41,11 +46,12 @@
   "dependencies": {
     "fast-glob": "^3.3.3",
     "picomatch": "^4.0.5",
-    "executable-stories-core": "0.24.0",
-    "executable-stories-formatters": "1.16.1"
+    "executable-stories-core": "0.25.0",
+    "executable-stories-formatters": "1.17.0"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@types/node": "^26.2.0",
     "@types/picomatch": "^4.0.3",
     "tsup": "^8.5.1",