ccqa-tools 1.37.0

package/dist/coverage/slack.cjs

@@ -0,0 +1,228 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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;
+}
+/**
+* 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 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
+/**
+* Enables the instrumentation. Unset means the register hook is never loaded
+* and the application pays nothing at all.
+*
+* `1` / `true` turns it on and leaves attribution to the incoming carrier.
+* Any other value is itself a `<runId>.<specId>` and becomes the ambient spec
+* for the process — the only way to attribute an entry point that has no
+* inbound request to read, such as a worker started per spec.
+*/
+const ENV_NAME = "CCQA_COVERAGE";
+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/runtime-env.ts
+function readConfig(env = process.env) {
+	const raw = env[ENV_NAME];
+	const include = (env["CCQA_COVERAGE_INCLUDE"] ?? "src").split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	return {
+		enabled: raw !== void 0 && raw !== "" && raw !== "0" && raw !== "false",
+		ambientSpecId: parseSpecId(raw),
+		root: env["CCQA_COVERAGE_ROOT"] ?? process.cwd(),
+		include,
+		debug: env["CCQA_COVERAGE_DEBUG"] === "1" || env["CCQA_COVERAGE_DEBUG"] === "true"
+	};
+}
+/**
+* Diagnostics go to stderr and nowhere else. A `--import` preload is inherited
+* by every child node process, and writing to stdout corrupts whatever the host
+* was parsing there — enough to make a framework's own toolchain fail to start.
+*/
+function debugLog(config, message) {
+	if (!config.debug) return;
+	process.stderr.write(`[ccqa-tools] ${message}\n`);
+}
+//#endregion
+//#region src/coverage/presets/slack.ts
+/**
+* Records who caused a Slack request, so the flows a chat platform drives can
+* be attributed at all.
+*
+* Those requests are sent by Slack, not by the browser under test, so none of
+* the carriers the rest of this package relies on is present — no cookie, no
+* baggage header, nothing. What the payload does say is which user acted, and
+* that is the whole of what this records:
+*
+*   app.use(slackActor())        // after whatever parses the body
+*
+* No arguments, no configuration, no environment. It does not know which users
+* are being measured, when a spec is running, or that ccqa exists — the run
+* decides all of that from the other end. With `CCQA_COVERAGE` unset the
+* runtime is absent and every call here returns immediately.
+*
+* Extraction is a fixed list of the places Slack puts a user id. A payload
+* shape not on the list records nothing rather than guessing, because a wrong
+* identity is a wrong answer while a missing one is a counted gap.
+*/
+/**
+* Read once: the identity of every inbound request would otherwise re-read the
+* environment, and this sits in front of every Slack request the app serves.
+*/
+const config = readConfig();
+/** The tag prefix, and therefore the provider key a project writes in its config. */
+const SLACK_PROVIDER = "slack";
+/**
+* Middleware for either shape a Slack app uses.
+*
+* Bolt hands its middleware one object holding the parsed body and its own
+* `next`, and awaits what comes back. A connect-style stack hands
+* `(request, response, next)`, and a context-style one `(ctx, next)`. All are
+* accepted so the application's one line does not have to know which it is —
+* and in a Bolt app `app.use()` is the only insertion point there is.
+*
+* Place it after whatever parses the body: the payload is what carries the
+* identity, and before parsing there is none. A framework whose body is only
+* available by awaiting it is out of reach here for the same reason — there is
+* nothing to read at the moment this runs.
+*/
+function slackActor() {
+	return async function coverageSlackActor(...args) {
+		const first = args[0];
+		const bolt = args.length === 1 && isRecord(first) && typeof first.next === "function" ? first : void 0;
+		const body = bolt ? bolt.body : requestBody(first);
+		const next = bolt ? bolt.next : args.slice(1).find(isFunction);
+		if (next === void 0) return;
+		const user = slackUserId(body);
+		if (user === void 0) {
+			await next();
+			return;
+		}
+		const tag = `${SLACK_PROVIDER}:${user}`;
+		debugLog(config, `slack actor ${tag}`);
+		await runAsActor(tag, Date.now(), next);
+	};
+}
+/**
+* The user id in a Slack payload, or undefined if this shape carries none.
+*
+* Exported for its own tests: the list is the entire contract, and a shape
+* silently dropping off it looks exactly like a flow that reached no code.
+*/
+function slackUserId(body) {
+	if (!isRecord(body)) return void 0;
+	const payload = parsePayload(body.payload);
+	if (payload !== void 0) return idOf(payload.user);
+	const event = body.event;
+	if (isRecord(event)) return idOf(event.user);
+	if (body.user !== void 0) return idOf(body.user);
+	if (typeof body.user_id === "string") return nonEmpty(body.user_id);
+}
+function parsePayload(raw) {
+	if (isRecord(raw)) return raw;
+	if (typeof raw !== "string") return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Slack writes a user as a bare id in some payloads and as an object in others. */
+function idOf(user) {
+	if (typeof user === "string") return nonEmpty(user);
+	if (isRecord(user) && typeof user.id === "string") return nonEmpty(user.id);
+}
+function nonEmpty(value) {
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isFunction(value) {
+	return typeof value === "function";
+}
+/**
+* The parsed request body, from the request itself or from a context wrapping
+* it. A context's own `body` is the *response* it is building, so reading that
+* would hand the extractor the wrong object and quietly find no identity.
+*/
+function requestBody(first) {
+	if (!isRecord(first)) return void 0;
+	const request = first.request;
+	if (isRecord(request) && isRecord(request.body)) return request.body;
+	return isRecord(first.body) ? first.body : void 0;
+}
+//#endregion
+exports.SLACK_PROVIDER = SLACK_PROVIDER;
+exports.slackActor = slackActor;
+exports.slackUserId = slackUserId;

package/dist/coverage/slack.d.cts

@@ -0,0 +1,47 @@
+//#region src/coverage/presets/slack.d.ts
+/**
+ * Records who caused a Slack request, so the flows a chat platform drives can
+ * be attributed at all.
+ *
+ * Those requests are sent by Slack, not by the browser under test, so none of
+ * the carriers the rest of this package relies on is present — no cookie, no
+ * baggage header, nothing. What the payload does say is which user acted, and
+ * that is the whole of what this records:
+ *
+ *   app.use(slackActor())        // after whatever parses the body
+ *
+ * No arguments, no configuration, no environment. It does not know which users
+ * are being measured, when a spec is running, or that ccqa exists — the run
+ * decides all of that from the other end. With `CCQA_COVERAGE` unset the
+ * runtime is absent and every call here returns immediately.
+ *
+ * Extraction is a fixed list of the places Slack puts a user id. A payload
+ * shape not on the list records nothing rather than guessing, because a wrong
+ * identity is a wrong answer while a missing one is a counted gap.
+ */
+/** The tag prefix, and therefore the provider key a project writes in its config. */
+declare const SLACK_PROVIDER = "slack";
+/**
+ * Middleware for either shape a Slack app uses.
+ *
+ * Bolt hands its middleware one object holding the parsed body and its own
+ * `next`, and awaits what comes back. A connect-style stack hands
+ * `(request, response, next)`, and a context-style one `(ctx, next)`. All are
+ * accepted so the application's one line does not have to know which it is —
+ * and in a Bolt app `app.use()` is the only insertion point there is.
+ *
+ * Place it after whatever parses the body: the payload is what carries the
+ * identity, and before parsing there is none. A framework whose body is only
+ * available by awaiting it is out of reach here for the same reason — there is
+ * nothing to read at the moment this runs.
+ */
+declare function slackActor(): (...args: unknown[]) => Promise<void>;
+/**
+ * The user id in a Slack payload, or undefined if this shape carries none.
+ *
+ * Exported for its own tests: the list is the entire contract, and a shape
+ * silently dropping off it looks exactly like a flow that reached no code.
+ */
+declare function slackUserId(body: unknown): string | undefined;
+//#endregion
+export { SLACK_PROVIDER, slackActor, slackUserId };

package/dist/coverage/slack.d.ts

@@ -0,0 +1,47 @@
+//#region src/coverage/presets/slack.d.ts
+/**
+ * Records who caused a Slack request, so the flows a chat platform drives can
+ * be attributed at all.
+ *
+ * Those requests are sent by Slack, not by the browser under test, so none of
+ * the carriers the rest of this package relies on is present — no cookie, no
+ * baggage header, nothing. What the payload does say is which user acted, and
+ * that is the whole of what this records:
+ *
+ *   app.use(slackActor())        // after whatever parses the body
+ *
+ * No arguments, no configuration, no environment. It does not know which users
+ * are being measured, when a spec is running, or that ccqa exists — the run
+ * decides all of that from the other end. With `CCQA_COVERAGE` unset the
+ * runtime is absent and every call here returns immediately.
+ *
+ * Extraction is a fixed list of the places Slack puts a user id. A payload
+ * shape not on the list records nothing rather than guessing, because a wrong
+ * identity is a wrong answer while a missing one is a counted gap.
+ */
+/** The tag prefix, and therefore the provider key a project writes in its config. */
+declare const SLACK_PROVIDER = "slack";
+/**
+ * Middleware for either shape a Slack app uses.
+ *
+ * Bolt hands its middleware one object holding the parsed body and its own
+ * `next`, and awaits what comes back. A connect-style stack hands
+ * `(request, response, next)`, and a context-style one `(ctx, next)`. All are
+ * accepted so the application's one line does not have to know which it is —
+ * and in a Bolt app `app.use()` is the only insertion point there is.
+ *
+ * Place it after whatever parses the body: the payload is what carries the
+ * identity, and before parsing there is none. A framework whose body is only
+ * available by awaiting it is out of reach here for the same reason — there is
+ * nothing to read at the moment this runs.
+ */
+declare function slackActor(): (...args: unknown[]) => Promise<void>;
+/**
+ * The user id in a Slack payload, or undefined if this shape carries none.
+ *
+ * Exported for its own tests: the list is the entire contract, and a shape
+ * silently dropping off it looks exactly like a flow that reached no code.
+ */
+declare function slackUserId(body: unknown): string | undefined;
+//#endregion
+export { SLACK_PROVIDER, slackActor, slackUserId };

package/dist/coverage/slack.js

@@ -0,0 +1,225 @@
+//#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;
+}
+/**
+* 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 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
+/**
+* Enables the instrumentation. Unset means the register hook is never loaded
+* and the application pays nothing at all.
+*
+* `1` / `true` turns it on and leaves attribution to the incoming carrier.
+* Any other value is itself a `<runId>.<specId>` and becomes the ambient spec
+* for the process — the only way to attribute an entry point that has no
+* inbound request to read, such as a worker started per spec.
+*/
+const ENV_NAME = "CCQA_COVERAGE";
+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/runtime-env.ts
+function readConfig(env = process.env) {
+	const raw = env[ENV_NAME];
+	const include = (env["CCQA_COVERAGE_INCLUDE"] ?? "src").split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	return {
+		enabled: raw !== void 0 && raw !== "" && raw !== "0" && raw !== "false",
+		ambientSpecId: parseSpecId(raw),
+		root: env["CCQA_COVERAGE_ROOT"] ?? process.cwd(),
+		include,
+		debug: env["CCQA_COVERAGE_DEBUG"] === "1" || env["CCQA_COVERAGE_DEBUG"] === "true"
+	};
+}
+/**
+* Diagnostics go to stderr and nowhere else. A `--import` preload is inherited
+* by every child node process, and writing to stdout corrupts whatever the host
+* was parsing there — enough to make a framework's own toolchain fail to start.
+*/
+function debugLog(config, message) {
+	if (!config.debug) return;
+	process.stderr.write(`[ccqa-tools] ${message}\n`);
+}
+//#endregion
+//#region src/coverage/presets/slack.ts
+/**
+* Records who caused a Slack request, so the flows a chat platform drives can
+* be attributed at all.
+*
+* Those requests are sent by Slack, not by the browser under test, so none of
+* the carriers the rest of this package relies on is present — no cookie, no
+* baggage header, nothing. What the payload does say is which user acted, and
+* that is the whole of what this records:
+*
+*   app.use(slackActor())        // after whatever parses the body
+*
+* No arguments, no configuration, no environment. It does not know which users
+* are being measured, when a spec is running, or that ccqa exists — the run
+* decides all of that from the other end. With `CCQA_COVERAGE` unset the
+* runtime is absent and every call here returns immediately.
+*
+* Extraction is a fixed list of the places Slack puts a user id. A payload
+* shape not on the list records nothing rather than guessing, because a wrong
+* identity is a wrong answer while a missing one is a counted gap.
+*/
+/**
+* Read once: the identity of every inbound request would otherwise re-read the
+* environment, and this sits in front of every Slack request the app serves.
+*/
+const config = readConfig();
+/** The tag prefix, and therefore the provider key a project writes in its config. */
+const SLACK_PROVIDER = "slack";
+/**
+* Middleware for either shape a Slack app uses.
+*
+* Bolt hands its middleware one object holding the parsed body and its own
+* `next`, and awaits what comes back. A connect-style stack hands
+* `(request, response, next)`, and a context-style one `(ctx, next)`. All are
+* accepted so the application's one line does not have to know which it is —
+* and in a Bolt app `app.use()` is the only insertion point there is.
+*
+* Place it after whatever parses the body: the payload is what carries the
+* identity, and before parsing there is none. A framework whose body is only
+* available by awaiting it is out of reach here for the same reason — there is
+* nothing to read at the moment this runs.
+*/
+function slackActor() {
+	return async function coverageSlackActor(...args) {
+		const first = args[0];
+		const bolt = args.length === 1 && isRecord(first) && typeof first.next === "function" ? first : void 0;
+		const body = bolt ? bolt.body : requestBody(first);
+		const next = bolt ? bolt.next : args.slice(1).find(isFunction);
+		if (next === void 0) return;
+		const user = slackUserId(body);
+		if (user === void 0) {
+			await next();
+			return;
+		}
+		const tag = `${SLACK_PROVIDER}:${user}`;
+		debugLog(config, `slack actor ${tag}`);
+		await runAsActor(tag, Date.now(), next);
+	};
+}
+/**
+* The user id in a Slack payload, or undefined if this shape carries none.
+*
+* Exported for its own tests: the list is the entire contract, and a shape
+* silently dropping off it looks exactly like a flow that reached no code.
+*/
+function slackUserId(body) {
+	if (!isRecord(body)) return void 0;
+	const payload = parsePayload(body.payload);
+	if (payload !== void 0) return idOf(payload.user);
+	const event = body.event;
+	if (isRecord(event)) return idOf(event.user);
+	if (body.user !== void 0) return idOf(body.user);
+	if (typeof body.user_id === "string") return nonEmpty(body.user_id);
+}
+function parsePayload(raw) {
+	if (isRecord(raw)) return raw;
+	if (typeof raw !== "string") return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Slack writes a user as a bare id in some payloads and as an object in others. */
+function idOf(user) {
+	if (typeof user === "string") return nonEmpty(user);
+	if (isRecord(user) && typeof user.id === "string") return nonEmpty(user.id);
+}
+function nonEmpty(value) {
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isFunction(value) {
+	return typeof value === "function";
+}
+/**
+* The parsed request body, from the request itself or from a context wrapping
+* it. A context's own `body` is the *response* it is building, so reading that
+* would hand the extractor the wrong object and quietly find no identity.
+*/
+function requestBody(first) {
+	if (!isRecord(first)) return void 0;
+	const request = first.request;
+	if (isRecord(request) && isRecord(request.body)) return request.body;
+	return isRecord(first.body) ? first.body : void 0;
+}
+//#endregion
+export { SLACK_PROVIDER, slackActor, slackUserId };