ccqa-tools 1.37.0

package/dist/coverage/temporal.js

@@ -0,0 +1,250 @@
+//#region src/coverage/core.ts
+const RUNTIME_KEY = Symbol.for("ccqa.coverage.runtime");
+function globals() {
+	return globalThis;
+}
+/**
+* Memoized so the hot path skips the `globalThis` read. `installRuntime`
+* primes it and never replaces an installed runtime, so once set it never
+* goes stale — but it must stay undefined (and keep re-reading `globalThis`)
+* until then, or a module that finished loading before `register` installs
+* the runtime would be stuck uninstrumented for the rest of the process.
+*/
+let cachedRuntime;
+function runtime() {
+	if (cachedRuntime === void 0) cachedRuntime = globals()[RUNTIME_KEY];
+	return cachedRuntime;
+}
+/** The spec the current async context belongs to, if any. */
+function currentSpecId() {
+	return runtime()?.als.getStore()?.specId;
+}
+/**
+* Opens `specId`'s bucket and runs `fn` inside its context. Every entry point —
+* HTTP, Temporal activity, manual — funnels through here.
+*
+* The bucket outlives `fn`: work a request schedules and does not await still
+* belongs to the spec that caused it.
+*/
+function runInSpec(specId, fn) {
+	const rt = runtime();
+	if (rt === void 0) return fn();
+	return rt.als.run({
+		specId,
+		files: openBucket(rt, specId)
+	}, fn);
+}
+/**
+* Records that `tag` caused this work at `at`, without deciding whose it is.
+*
+* Carrier wins: a request that already named a spec needs no identity, and
+* overwriting it would replace a fact with something the run still has to
+* interpret. Everything else is recorded whoever it came from — the application
+* is never told which identities are being measured, so it cannot filter, and
+* the run discards the ones it did not ask for.
+*/
+function runAsActor(tag, at, fn) {
+	const rt = runtime();
+	if (rt === void 0) return fn();
+	if (rt.als.getStore()?.specId !== void 0) return fn();
+	return rt.als.run({
+		actor: {
+			tag,
+			at
+		},
+		files: openActorBucket(rt, tag, at)
+	}, fn);
+}
+/** The identity mark on the current async context, if it has one. */
+function currentActor() {
+	return runtime()?.als.getStore()?.actor;
+}
+/** Returns `specId`'s file set, creating it — and arming the gate — if new. */
+function openBucket(runtime, specId) {
+	let files = runtime.buckets.get(specId);
+	if (files === void 0) {
+		files = /* @__PURE__ */ new Set();
+		runtime.buckets.set(specId, files);
+		armGate(runtime);
+	}
+	return files;
+}
+/**
+* The key both halves of the collector agree on. A space separates them safely:
+* a spec id can never contain one, so identity keys and spec ids stay disjoint
+* where the collector tracks both in one map.
+*/
+function actorBucketKey(tag, at) {
+	return `${tag} ${at}`;
+}
+/** Returns the identity's file set for that instant, creating it if new. */
+function openActorBucket(runtime, tag, at) {
+	const key = actorBucketKey(tag, at);
+	let bucket = runtime.actors.get(key);
+	if (bucket === void 0) {
+		bucket = {
+			tag,
+			at,
+			files: /* @__PURE__ */ new Set()
+		};
+		runtime.actors.set(key, bucket);
+		armGate(runtime);
+	}
+	return bucket.files;
+}
+function armGate(runtime) {
+	runtime.active = runtime.buckets.size + runtime.actors.size;
+}
+//#endregion
+//#region src/coverage/wire.ts
+/** Temporal header key, for the hop from client to workflow to activity. */
+const TEMPORAL_HEADER = "ccqa-tools";
+/**
+* `<provider>:<identity>` — who caused a request, for the requests that cannot
+* say which spec they belong to.
+*
+* The application stamps this and nothing else: which spec an identity was
+* acting for at a given instant is decided by the run, which is the only side
+* that knows. Nothing about the mapping is ever sent back here.
+*/
+const ACTOR_TAG = /^[A-Za-z0-9][A-Za-z0-9._-]*:\S{1,200}$/;
+function parseActorTag(raw) {
+	if (!raw) return void 0;
+	const value = raw.trim();
+	return ACTOR_TAG.test(value) ? value : void 0;
+}
+/** Reads a mark off the wire, refusing anything that is not one of the two shapes. */
+function parseMark(value) {
+	if (typeof value === "string") {
+		const spec = parseSpecId(value);
+		return spec === void 0 ? void 0 : { spec };
+	}
+	if (typeof value !== "object" || value === null) return void 0;
+	const { tag, at } = value;
+	if (typeof at !== "number" || !Number.isFinite(at)) return void 0;
+	const parsed = parseActorTag(typeof tag === "string" ? tag : void 0);
+	return parsed === void 0 ? void 0 : {
+		tag: parsed,
+		at
+	};
+}
+const SPEC_ID = /^[A-Za-z0-9._\-/]{1,200}$/;
+/**
+* Accepts a carrier value only if it looks like an id we wrote.
+*
+* The cookie is client-controlled, so this is the first of two gates: the
+* second is the hub refusing runs it never started.
+*/
+function parseSpecId(raw) {
+	if (!raw) return void 0;
+	const value = raw.trim();
+	if (!SPEC_ID.test(value)) return void 0;
+	if (value === "1" || value === "true") return void 0;
+	return value;
+}
+//#endregion
+//#region src/coverage/temporal/header.ts
+/**
+* Reads and writes the one Temporal header this package uses.
+*
+* The payload is built by hand rather than through `defaultPayloadConverter` so
+* that the workflow half of the integration stays free of Temporal imports —
+* the workflow sandbox is picky, and a plain `json/plain` string is exactly
+* what the default converter would have produced anyway.
+*/
+const ENCODING = "json/plain";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+* A spec travels as a bare string and an identity as an object, so the two are
+* told apart by shape rather than by a discriminator nobody else would read.
+*/
+function toHeader(mark) {
+	const value = "spec" in mark ? mark.spec : {
+		tag: mark.tag,
+		at: mark.at
+	};
+	return { [TEMPORAL_HEADER]: {
+		metadata: { encoding: encode(ENCODING) },
+		data: encode(JSON.stringify(value))
+	} };
+}
+/** The raw value off the header. Callers validate it with `parseMark`. */
+function fromHeader(headers) {
+	const payload = headers?.[TEMPORAL_HEADER];
+	if (!payload?.data) return void 0;
+	try {
+		return JSON.parse(decode(payload.data));
+	} catch {
+		return;
+	}
+}
+function encode(value) {
+	return textEncoder.encode(value);
+}
+function decode(value) {
+	return textDecoder.decode(value);
+}
+//#endregion
+//#region src/coverage/temporal/index.ts
+/**
+* Carries the spec id across Temporal, whose activities are the one async-job
+* boundary that can be attributed at all: the SDK hands interceptors the same
+* header map on the way out of a client and on the way into an activity.
+*
+* Three hops, three interceptors. The middle one — the workflow — lives in
+* `ccqa-tools/coverage/temporal/workflow` because it is evaluated inside a
+* deterministic sandbox that has no Node built-ins.
+*/
+/**
+* Client side: stamps the spec of whatever request is starting the workflow.
+*
+* Both `start` and `signalWithStart` begin executions; covering only one leaves
+* a hole that shows up as an unattributed activity much later.
+*/
+function createClientInterceptor() {
+	const stamp = (input, next) => {
+		const mark = currentMark();
+		if (mark === void 0) return next(input);
+		return next({
+			...input,
+			headers: {
+				...input.headers,
+				...toHeader(mark)
+			}
+		});
+	};
+	return {
+		start: stamp,
+		signalWithStart: stamp
+	};
+}
+/**
+* Activity side: reopens the context the work came from. Activities run in an
+* ordinary Node context, so everything the activity touches is attributed from
+* here on.
+*
+* An identity mark keeps the instant it was stamped with rather than taking
+* the current time — an activity may run long after the request that scheduled
+* it, and the run matches on when the work was asked for.
+*/
+function createActivityInterceptor() {
+	return { execute: (input, next) => {
+		const mark = parseMark(fromHeader(input.headers));
+		if (mark === void 0) return next(input);
+		if ("spec" in mark) return runInSpec(mark.spec, () => next(input));
+		return runAsActor(mark.tag, mark.at, () => next(input));
+	} };
+}
+/** What the current context has to hand on: its spec, or who caused it. */
+function currentMark() {
+	const specId = currentSpecId();
+	if (specId !== void 0) return { spec: specId };
+	const actor = currentActor();
+	return actor === void 0 ? void 0 : {
+		tag: actor.tag,
+		at: actor.at
+	};
+}
+//#endregion
+export { TEMPORAL_HEADER, createActivityInterceptor, createClientInterceptor };

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "ccqa-tools",
+  "version": "1.37.0",
+  "type": "module",
+  "description": "Instrumentation the application under test installs, for ccqa. Currently: per-spec reach coverage.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shibukazu/ccqa.git",
+    "directory": "packages/tools"
+  },
+  "license": "MIT",
+  "exports": {
+    "./coverage": {
+      "types": "./dist/coverage/core.d.ts",
+      "import": "./dist/coverage/core.js",
+      "require": "./dist/coverage/core.cjs"
+    },
+    "./coverage/register": {
+      "types": "./dist/coverage/register.d.ts",
+      "import": "./dist/coverage/register.js",
+      "require": "./dist/coverage/register.cjs"
+    },
+    "./coverage/middleware": {
+      "types": "./dist/coverage/middleware.d.ts",
+      "import": "./dist/coverage/middleware.js",
+      "require": "./dist/coverage/middleware.cjs"
+    },
+    "./coverage/slack": {
+      "types": "./dist/coverage/slack.d.ts",
+      "import": "./dist/coverage/slack.js",
+      "require": "./dist/coverage/slack.cjs"
+    },
+    "./coverage/collector": {
+      "types": "./dist/coverage/collector.d.ts",
+      "import": "./dist/coverage/collector.js",
+      "require": "./dist/coverage/collector.cjs"
+    },
+    "./coverage/next": {
+      "types": "./dist/coverage/next.d.ts",
+      "import": "./dist/coverage/next.js",
+      "require": "./dist/coverage/next.cjs"
+    },
+    "./coverage/next/loader": {
+      "default": "./dist/coverage/next-loader.cjs"
+    },
+    "./coverage/temporal": {
+      "types": "./dist/coverage/temporal.d.ts",
+      "import": "./dist/coverage/temporal.js",
+      "require": "./dist/coverage/temporal.cjs"
+    },
+    "./coverage/temporal/workflow": {
+      "types": "./dist/coverage/temporal-workflow.d.ts",
+      "import": "./dist/coverage/temporal-workflow.js",
+      "require": "./dist/coverage/temporal-workflow.cjs"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "acorn": "^8.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsdown": "^0.21.9",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@temporalio/activity": ">=1.9.0",
+    "@temporalio/client": ">=1.9.0",
+    "@temporalio/worker": ">=1.9.0",
+    "@temporalio/workflow": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@temporalio/activity": {
+      "optional": true
+    },
+    "@temporalio/client": {
+      "optional": true
+    },
+    "@temporalio/worker": {
+      "optional": true
+    },
+    "@temporalio/workflow": {
+      "optional": true
+    }
+  }
+}