@storyshelf/core 0.6.2 → 0.8.0

package/dist/adapters/capture-target.d.mts

@@ -0,0 +1,69 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/**
+ * Capture targets (ADR 0007, decision 3): what a project names to render on. A target is a rendering
+ * engine (`chromium`) or a remote one, `<engine>@<name>` (`chromium@grid`), which has its own
+ * baselines and fingerprint.
+ */
+/** A rendering engine. */
+type BrowserName = "chromium" | "firefox" | "webkit" | "chrome";
+/** Engine names accepted for capture rendering (Chromium default). */
+declare const BROWSER_NAMES: readonly ["chromium", "firefox", "webkit", "chrome"];
+/** Engine that legacy rows and single-browser projects belong to. */
+declare const DEFAULT_BROWSER: BrowserName;
+/** What a project's `browsers` setting, a snapshot's `browser` and a baseline key hold. */
+type CaptureTarget = BrowserName | `${BrowserName}@${string}`;
+/** Remote target names: they become part of a storage key and a unique index. */
+declare const TARGET_NAME_PATTERN: RegExp;
+/** How a runner's browser reaches the Storybook (ADR 0007, decision 5). */
+type TargetReach = "loopback" | "url";
+/** Whether a target can render now; `unavailable` carries the reason shown to operators. */
+type TargetStatus = "ready" | {
+  readonly unavailable: string;
+};
+/** One target a runner offers, in its metadata. */
+interface RunnerTarget {
+  target: CaptureTarget;
+  reach: TargetReach;
+  status: TargetStatus;
+}
+/** A target split into its engine and, for a remote one, its name. */
+interface ParsedTarget {
+  engine: BrowserName;
+  /** Set for `<engine>@<name>`; absent for a local engine. */
+  name?: string;
+}
+/** Whether `value` is an engine name. */
+declare function isBrowserName(value: unknown): value is BrowserName;
+/** Split a target into engine and name; `null` when it is not a valid target. */
+declare function tryParseTarget(value: unknown): ParsedTarget | null;
+/** Split a target into engine and name; throws on anything that is not a target. */
+declare function parseTarget(value: string): ParsedTarget;
+/** Whether `value` is a capture target. */
+declare function isCaptureTarget(value: unknown): value is CaptureTarget;
+/** The engine half of a target. */
+declare function engineOf(target: CaptureTarget): BrowserName;
+/** The reason a status is unavailable, or `null` when it is ready. */
+declare function unavailableReason(status: TargetStatus): string | null;
+/**
+ * A launch or connect failure: the browser never started, so the job fails at once with this
+ * reason. Crash isolation (`capture/isolate.ts`) must not see it, since no story is at fault
+ * (ADR 0007, decision 7).
+ */
+declare class TargetLaunchError extends Error {
+  readonly name = "TargetLaunchError";
+  readonly target: CaptureTarget;
+  /** Why it did not start, without the target's name. */
+  readonly reason: string;
+  /**
+   * The failure may pass (a remote browser service that is down or full): the target is not marked
+   * unavailable for it, though the job still fails at once. A wrong version or credentials do not.
+   */
+  readonly transient: boolean;
+  constructor(target: CaptureTarget, reason: string, options?: {
+    cause?: unknown;
+    transient?: boolean;
+  });
+}
+export { BROWSER_NAMES, BrowserName, CaptureTarget, DEFAULT_BROWSER, ParsedTarget, RunnerTarget, TARGET_NAME_PATTERN, TargetLaunchError, TargetReach, TargetStatus, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason };
+//# sourceMappingURL=capture-target.d.mts.map

package/dist/adapters/capture-target.mjs

@@ -0,0 +1,75 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/adapters/capture-target.ts
+/** Engine names accepted for capture rendering (Chromium default). */
+const BROWSER_NAMES = [
+	"chromium",
+	"firefox",
+	"webkit",
+	"chrome"
+];
+/** Engine that legacy rows and single-browser projects belong to. */
+const DEFAULT_BROWSER = "chromium";
+/** Remote target names: they become part of a storage key and a unique index. */
+const TARGET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/u;
+/** Whether `value` is an engine name. */
+function isBrowserName(value) {
+	return typeof value === "string" && BROWSER_NAMES.includes(value);
+}
+/** Split a target into engine and name; `null` when it is not a valid target. */
+function tryParseTarget(value) {
+	if (typeof value !== "string") return null;
+	const at = value.indexOf("@");
+	const engine = at === -1 ? value : value.slice(0, at);
+	if (!isBrowserName(engine)) return null;
+	if (at === -1) return { engine };
+	const name = value.slice(at + 1);
+	return TARGET_NAME_PATTERN.test(name) ? {
+		engine,
+		name
+	} : null;
+}
+/** Split a target into engine and name; throws on anything that is not a target. */
+function parseTarget(value) {
+	const parsed = tryParseTarget(value);
+	if (parsed === null) throw new Error(`Invalid capture target "${value}": expected one of ${BROWSER_NAMES.join(", ")}, or <engine>@<name> with a lowercase name of at most 32 letters, digits and hyphens`);
+	return parsed;
+}
+/** Whether `value` is a capture target. */
+function isCaptureTarget(value) {
+	return tryParseTarget(value) !== null;
+}
+/** The engine half of a target. */
+function engineOf(target) {
+	return parseTarget(target).engine;
+}
+/** The reason a status is unavailable, or `null` when it is ready. */
+function unavailableReason(status) {
+	return status === "ready" ? null : status.unavailable;
+}
+/**
+* A launch or connect failure: the browser never started, so the job fails at once with this
+* reason. Crash isolation (`capture/isolate.ts`) must not see it, since no story is at fault
+* (ADR 0007, decision 7).
+*/
+var TargetLaunchError = class extends Error {
+	name = "TargetLaunchError";
+	target;
+	/** Why it did not start, without the target's name. */
+	reason;
+	/**
+	* The failure may pass (a remote browser service that is down or full): the target is not marked
+	* unavailable for it, though the job still fails at once. A wrong version or credentials do not.
+	*/
+	transient;
+	constructor(target, reason, options) {
+		super(`Cannot launch ${target}: ${reason}`, options);
+		this.target = target;
+		this.reason = reason;
+		this.transient = options?.transient ?? false;
+	}
+};
+export { BROWSER_NAMES, DEFAULT_BROWSER, TARGET_NAME_PATTERN, TargetLaunchError, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason };
+
+//# sourceMappingURL=capture-target.mjs.map

package/dist/adapters/capture-target.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-target.mjs","names":[],"sources":["../../src/adapters/capture-target.ts"],"sourcesContent":["/**\n * Capture targets (ADR 0007, decision 3): what a project names to render on. A target is a rendering\n * engine (`chromium`) or a remote one, `<engine>@<name>` (`chromium@grid`), which has its own\n * baselines and fingerprint.\n */\n\n/** A rendering engine. */\nexport type BrowserName = \"chromium\" | \"firefox\" | \"webkit\" | \"chrome\";\n\n/** Engine names accepted for capture rendering (Chromium default). */\nexport const BROWSER_NAMES = [\"chromium\", \"firefox\", \"webkit\", \"chrome\"] as const;\n\n/** Engine that legacy rows and single-browser projects belong to. */\nexport const DEFAULT_BROWSER: BrowserName = \"chromium\";\n\n/** What a project's `browsers` setting, a snapshot's `browser` and a baseline key hold. */\nexport type CaptureTarget = BrowserName | `${BrowserName}@${string}`;\n\n/** Remote target names: they become part of a storage key and a unique index. */\nexport const TARGET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/u;\n\n/** How a runner's browser reaches the Storybook (ADR 0007, decision 5). */\nexport type TargetReach = \"loopback\" | \"url\";\n\n/** Whether a target can render now; `unavailable` carries the reason shown to operators. */\nexport type TargetStatus = \"ready\" | { readonly unavailable: string };\n\n/** One target a runner offers, in its metadata. */\nexport interface RunnerTarget {\n  target: CaptureTarget;\n  reach: TargetReach;\n  status: TargetStatus;\n}\n\n/** A target split into its engine and, for a remote one, its name. */\nexport interface ParsedTarget {\n  engine: BrowserName;\n  /** Set for `<engine>@<name>`; absent for a local engine. */\n  name?: string;\n}\n\n/** Whether `value` is an engine name. */\nexport function isBrowserName(value: unknown): value is BrowserName {\n  return typeof value === \"string\" && (BROWSER_NAMES as readonly string[]).includes(value);\n}\n\n/** Split a target into engine and name; `null` when it is not a valid target. */\nexport function tryParseTarget(value: unknown): ParsedTarget | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const at = value.indexOf(\"@\");\n  const engine = at === -1 ? value : value.slice(0, at);\n  if (!isBrowserName(engine)) {\n    return null;\n  }\n  if (at === -1) {\n    return { engine };\n  }\n  const name = value.slice(at + 1);\n  return TARGET_NAME_PATTERN.test(name) ? { engine, name } : null;\n}\n\n/** Split a target into engine and name; throws on anything that is not a target. */\nexport function parseTarget(value: string): ParsedTarget {\n  const parsed = tryParseTarget(value);\n  if (parsed === null) {\n    throw new Error(\n      `Invalid capture target \"${value}\": expected one of ${BROWSER_NAMES.join(\", \")}, or <engine>@<name> with a lowercase name of at most 32 letters, digits and hyphens`,\n    );\n  }\n  return parsed;\n}\n\n/** Whether `value` is a capture target. */\nexport function isCaptureTarget(value: unknown): value is CaptureTarget {\n  return tryParseTarget(value) !== null;\n}\n\n/** The engine half of a target. */\nexport function engineOf(target: CaptureTarget): BrowserName {\n  return parseTarget(target).engine;\n}\n\n/** The reason a status is unavailable, or `null` when it is ready. */\nexport function unavailableReason(status: TargetStatus): string | null {\n  return status === \"ready\" ? null : status.unavailable;\n}\n\n/**\n * A launch or connect failure: the browser never started, so the job fails at once with this\n * reason. Crash isolation (`capture/isolate.ts`) must not see it, since no story is at fault\n * (ADR 0007, decision 7).\n */\nexport class TargetLaunchError extends Error {\n  override readonly name = \"TargetLaunchError\";\n  readonly target: CaptureTarget;\n  /** Why it did not start, without the target's name. */\n  readonly reason: string;\n  /**\n   * The failure may pass (a remote browser service that is down or full): the target is not marked\n   * unavailable for it, though the job still fails at once. A wrong version or credentials do not.\n   */\n  readonly transient: boolean;\n\n  constructor(\n    target: CaptureTarget,\n    reason: string,\n    options?: { cause?: unknown; transient?: boolean },\n  ) {\n    super(`Cannot launch ${target}: ${reason}`, options);\n    this.target = target;\n    this.reason = reason;\n    this.transient = options?.transient ?? false;\n  }\n}\n"],"mappings":";;;;;AAUA,MAAa,gBAAgB;CAAC;CAAY;CAAW;CAAU;AAAQ;;AAGvE,MAAa,kBAA+B;;AAM5C,MAAa,sBAAsB;;AAuBnC,SAAgB,cAAc,OAAsC;CAClE,OAAO,OAAO,UAAU,YAAa,cAAoC,SAAS,KAAK;AACzF;;AAGA,SAAgB,eAAe,OAAqC;CAClE,IAAI,OAAO,UAAU,UACnB,OAAO;CAET,MAAM,KAAK,MAAM,QAAQ,GAAG;CAC5B,MAAM,SAAS,OAAO,KAAK,QAAQ,MAAM,MAAM,GAAG,EAAE;CACpD,IAAI,CAAC,cAAc,MAAM,GACvB,OAAO;CAET,IAAI,OAAO,IACT,OAAO,EAAE,OAAO;CAElB,MAAM,OAAO,MAAM,MAAM,KAAK,CAAC;CAC/B,OAAO,oBAAoB,KAAK,IAAI,IAAI;EAAE;EAAQ;CAAK,IAAI;AAC7D;;AAGA,SAAgB,YAAY,OAA6B;CACvD,MAAM,SAAS,eAAe,KAAK;CACnC,IAAI,WAAW,MACb,MAAM,IAAI,MACR,2BAA2B,MAAM,qBAAqB,cAAc,KAAK,IAAI,EAAE,qFACjF;CAEF,OAAO;AACT;;AAGA,SAAgB,gBAAgB,OAAwC;CACtE,OAAO,eAAe,KAAK,MAAM;AACnC;;AAGA,SAAgB,SAAS,QAAoC;CAC3D,OAAO,YAAY,MAAM,CAAC,CAAC;AAC7B;;AAGA,SAAgB,kBAAkB,QAAqC;CACrE,OAAO,WAAW,UAAU,OAAO,OAAO;AAC5C;;;;;;AAOA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,OAAyB;CACzB;;CAEA;;;;;CAKA;CAEA,YACE,QACA,QACA,SACA;EACA,MAAM,iBAAiB,OAAO,IAAI,UAAU,OAAO;EACnD,KAAK,SAAS;EACd,KAAK,SAAS;EACd,KAAK,YAAY,SAAS,aAAa;CACzC;AACF"}

package/dist/adapters/notifier/build-comment.d.mts

@@ -0,0 +1,22 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DesiredStatus } from "./build-state.mjs";
+/** Inputs of {@link buildCommentMarkdown}. */
+interface BuildCommentInput {
+  buildUrl: string;
+  /** Present once the Storybook is published. */
+  storybookUrl?: string | undefined;
+  /** The gating statuses (`testing` or `review`), in display order. */
+  gates: readonly DesiredStatus[];
+  /** Present when `testing` or review is on: the snapshot totals to summarize. */
+  counts?: {
+    snapshotCount: number;
+    changedCount: number;
+    approvedCount: number;
+    rejectedCount: number;
+  } | undefined;
+}
+/** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */
+declare function buildCommentMarkdown(input: BuildCommentInput): string;
+export { BuildCommentInput, buildCommentMarkdown };
+//# sourceMappingURL=build-comment.d.mts.map

package/dist/adapters/notifier/build-comment.mjs

@@ -0,0 +1,23 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/adapters/notifier/build-comment.ts
+const LABEL = {
+	testing: "Visual tests",
+	review: "Review",
+	storybook: "Storybook"
+};
+/** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */
+function buildCommentMarkdown(input) {
+	const lines = [`**StoryShelf** — [View build](${input.buildUrl})`];
+	for (const gate of input.gates) lines.push(`- ${LABEL[gate.name]}: ${gate.description}`);
+	if (input.counts !== void 0 && input.counts.snapshotCount > 0) {
+		const { snapshotCount, changedCount, approvedCount, rejectedCount } = input.counts;
+		lines.push(`- Snapshots: ${String(snapshotCount)} total, ${String(changedCount)} changed, ${String(approvedCount)} approved, ${String(rejectedCount)} rejected`);
+	}
+	if (input.storybookUrl !== void 0) lines.push(`- Storybook: [Open the published Storybook](${input.storybookUrl})`);
+	return lines.join("\n");
+}
+export { buildCommentMarkdown };
+
+//# sourceMappingURL=build-comment.mjs.map

package/dist/adapters/notifier/build-comment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-comment.mjs","names":[],"sources":["../../../src/adapters/notifier/build-comment.ts"],"sourcesContent":["/** Markdown of the pull-request comment, derived from the same inputs as the statuses (ADR 0014, decision 6). */\nimport type { DesiredStatus } from \"./build-state.ts\";\n\n/** Inputs of {@link buildCommentMarkdown}. */\nexport interface BuildCommentInput {\n  buildUrl: string;\n  /** Present once the Storybook is published. */\n  storybookUrl?: string | undefined;\n  /** The gating statuses (`testing` or `review`), in display order. */\n  gates: readonly DesiredStatus[];\n  /** Present when `testing` or review is on: the snapshot totals to summarize. */\n  counts?:\n    | {\n        snapshotCount: number;\n        changedCount: number;\n        approvedCount: number;\n        rejectedCount: number;\n      }\n    | undefined;\n}\n\nconst LABEL: Record<DesiredStatus[\"name\"], string> = {\n  testing: \"Visual tests\",\n  review: \"Review\",\n  storybook: \"Storybook\",\n};\n\n/** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */\nexport function buildCommentMarkdown(input: BuildCommentInput): string {\n  const lines = [`**StoryShelf** — [View build](${input.buildUrl})`];\n  for (const gate of input.gates) {\n    lines.push(`- ${LABEL[gate.name]}: ${gate.description}`);\n  }\n  if (input.counts !== undefined && input.counts.snapshotCount > 0) {\n    const { snapshotCount, changedCount, approvedCount, rejectedCount } = input.counts;\n    lines.push(\n      `- Snapshots: ${String(snapshotCount)} total, ${String(changedCount)} changed, ${String(approvedCount)} approved, ${String(rejectedCount)} rejected`,\n    );\n  }\n  if (input.storybookUrl !== undefined) {\n    lines.push(`- Storybook: [Open the published Storybook](${input.storybookUrl})`);\n  }\n  return lines.join(\"\\n\");\n}\n"],"mappings":";;;;AAqBA,MAAM,QAA+C;CACnD,SAAS;CACT,QAAQ;CACR,WAAW;AACb;;AAGA,SAAgB,qBAAqB,OAAkC;CACrE,MAAM,QAAQ,CAAC,iCAAiC,MAAM,SAAS,EAAE;CACjE,KAAK,MAAM,QAAQ,MAAM,OACvB,MAAM,KAAK,KAAK,MAAM,KAAK,MAAM,IAAI,KAAK,aAAa;CAEzD,IAAI,MAAM,WAAW,KAAA,KAAa,MAAM,OAAO,gBAAgB,GAAG;EAChE,MAAM,EAAE,eAAe,cAAc,eAAe,kBAAkB,MAAM;EAC5E,MAAM,KACJ,gBAAgB,OAAO,aAAa,EAAE,UAAU,OAAO,YAAY,EAAE,YAAY,OAAO,aAAa,EAAE,aAAa,OAAO,aAAa,EAAE,UAC5I;CACF;CACA,IAAI,MAAM,iBAAiB,KAAA,GACzB,MAAM,KAAK,+CAA+C,MAAM,aAAa,EAAE;CAEjF,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/dist/adapters/notifier/build-state.d.mts

@@ -0,0 +1,97 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { NotifierState, StateAnnotation } from "./types.mjs";
+import { UrlBuilder } from "../../urls.mjs";
+/** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */
+declare const MAX_ANNOTATIONS = 200;
+/** Names of the statuses below a channel's prefix. */
+type StatusName = "testing" | "review" | "storybook";
+/** How publishing the build's Storybook stands. */
+type PublishingState = "pending" | "success" | "failure";
+/** What decides which statuses exist (ADR 0014, decision 5). */
+interface BuildStateFlags {
+  /** `testing` is on: `<prefix>/testing` is the merge gate. */
+  testing: boolean;
+  /** Review is on for the project: with `testing` off, `<prefix>/review` is the gate. */
+  review: boolean;
+}
+/** The part of a build row the function reads. */
+interface BuildStateBuild {
+  id: string;
+  gitSha: string;
+  /** Build status: `pending`, `capturing`, `comparing`, `reviewing`, `approved`, `rejected`, `failed`, `cancelled`. */
+  status: string;
+  snapshotCount: number;
+  changedCount: number;
+  approvedCount: number;
+  rejectedCount: number;
+}
+/** The part of a snapshot row the annotations read. */
+interface BuildStateChange {
+  id: string;
+  /** `changed` or `new`; anything else is not a change to review. */
+  status: string;
+  storyTitle: string;
+  storyName: string;
+  storyImportPath: string | null;
+  viewportName: string;
+  browser?: string | undefined;
+}
+/** Inputs of {@link statusesForBuild}. */
+interface BuildStateInput {
+  build: BuildStateBuild;
+  projectSlug: string;
+  /** The channel's status-name prefix, without a trailing slash. */
+  prefix: string;
+  /**
+   * Absolute links (`createUrlBuilder(publicOrigin)`). A build's state is only ever shown once a
+   * public origin is resolved (ADR 0014, decision 11), so every status links and the comment exists.
+   */
+  urls: Pick<UrlBuilder, "build" | "storybookBuild" | "snapshot">;
+  flags: BuildStateFlags;
+  publishing: PublishingState;
+  /**
+   * Approval progress of the build-level review: the approvals among each reviewer's latest
+   * verdict and the approvals the project requires. Shown on `<prefix>/review` while it waits.
+   */
+  approvals?: {
+    given: number;
+    required: number;
+  } | undefined;
+  /** The build's snapshots; the `changed` and `new` ones become annotations of `<prefix>/testing`. */
+  changes?: readonly BuildStateChange[] | undefined;
+}
+/** One commit status to show. */
+interface DesiredStatus {
+  name: StatusName;
+  /** Full name on the host, `<prefix>/<name>`. */
+  context: string;
+  state: NotifierState;
+  description: string;
+  /** What the status links to: the build page, or the published Storybook for `storybook`. */
+  url: string;
+  /** True for the Storybook status, which is never a gate. */
+  informational?: boolean;
+  /** Set on a `pending` status: `queued` before capture starts, else `running`. */
+  progress?: "queued" | "running";
+  /** Per-snapshot findings (only `testing`), at most {@link MAX_ANNOTATIONS}. */
+  annotations?: StateAnnotation[];
+  /** Changes beyond the cap. */
+  omitted?: number;
+}
+/** The pull-request comment to show. */
+interface DesiredComment {
+  /** The build page; it keys the comment, one per build. */
+  url: string;
+  markdown: string;
+  state: NotifierState;
+}
+/** Everything a channel should show for a build. */
+interface BuildStateSet {
+  statuses: DesiredStatus[];
+  comment: DesiredComment | null;
+}
+/** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */
+declare function statusesForBuild(input: BuildStateInput): BuildStateSet;
+export { BuildStateBuild, BuildStateChange, BuildStateFlags, BuildStateInput, BuildStateSet, DesiredComment, DesiredStatus, MAX_ANNOTATIONS, PublishingState, StatusName, statusesForBuild };
+//# sourceMappingURL=build-state.d.mts.map

package/dist/adapters/notifier/build-state.mjs

@@ -0,0 +1,217 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildCommentMarkdown } from "./build-comment.mjs";
+import { LOCAL_SHA_PREFIX } from "@storyshelf/affected";
+// src/adapters/notifier/build-state.ts
+/**
+* The states a build's git channels show, as one pure function of the build (ADR 0014, decision 5).
+* It reads no clock, database or provider: callers hand it the build, the channel's prefix and the
+* flags, and write the result to the host. Every transition and the end of publishing call it
+* again, so a build that was never captured still gets its statuses and a repeated call changes
+* nothing.
+*/
+/** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */
+const MAX_ANNOTATIONS = 200;
+/** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */
+function statusesForBuild(input) {
+	const { build } = input;
+	if (build.gitSha.length === 0 || build.gitSha.startsWith(LOCAL_SHA_PREFIX)) return {
+		statuses: [],
+		comment: null
+	};
+	const links = linksOf(input);
+	const statuses = [...withAnnotations(gateStatus(input, links.build), input), storybookStatus(input.publishing, input.prefix, links)].map((status) => withProgress(status, input.build));
+	return {
+		statuses,
+		comment: commentOf(input, statuses, links)
+	};
+}
+/** `pending` is `queued` while the build waits to be captured, `running` after. */
+function withProgress(status, build) {
+	if (status.state !== "pending") return status;
+	const queued = status.name !== "storybook" && build.status === "pending";
+	return {
+		...status,
+		progress: queued ? "queued" : "running"
+	};
+}
+/** One annotation per changed snapshot, on the `testing` gate. */
+function withAnnotations(gates, input) {
+	const changed = (input.changes ?? []).filter((c) => c.status === "changed" || c.status === "new");
+	if (changed.length === 0) return gates;
+	const annotations = changed.slice(0, 200).map((change) => annotationOf(change, input));
+	const omitted = changed.length - annotations.length;
+	return gates.map((gate) => gate.name === "testing" ? {
+		...gate,
+		annotations,
+		...omitted > 0 ? { omitted } : {}
+	} : gate);
+}
+function annotationOf(change, input) {
+	const where = [change.viewportName, change.browser].filter(Boolean).join(", ");
+	const isNew = change.status === "new";
+	const name = `${change.storyTitle} / ${change.storyName}`;
+	return {
+		path: change.storyImportPath?.replace(/^(?:\.\/)+/u, "") ?? ".storybook",
+		title: where === "" ? name : `${name} (${where})`,
+		message: `${isNew ? "New snapshot" : "Visual change"}: review it at ${input.urls.snapshot(input.projectSlug, input.build.id, change.id)}`,
+		url: input.urls.snapshot(input.projectSlug, input.build.id, change.id),
+		level: isNew ? "notice" : "warning"
+	};
+}
+function commentOf(input, statuses, links) {
+	const gates = statuses.filter((status) => status.name !== "storybook");
+	return {
+		url: links.build,
+		state: gates[0]?.state ?? "success",
+		markdown: buildCommentMarkdown({
+			buildUrl: links.build,
+			storybookUrl: input.publishing === "success" ? links.storybook : void 0,
+			gates,
+			counts: input.flags.testing || input.flags.review ? input.build : void 0
+		})
+	};
+}
+/** The links to show. */
+function linksOf(input) {
+	const { urls, projectSlug, build } = input;
+	return {
+		build: urls.build(projectSlug, build.id),
+		storybook: `${urls.storybookBuild(projectSlug, build.id).replace(/\/+$/u, "")}/`
+	};
+}
+/** `testing` when it is on; `review` when only review is on; none for a hosting-only build. */
+function gateStatus(input, url) {
+	const { flags, build, prefix } = input;
+	if (flags.testing) return [{
+		name: "testing",
+		context: `${prefix}/testing`,
+		url,
+		...testingOutcome(build)
+	}];
+	if (flags.review) return [{
+		name: "review",
+		context: `${prefix}/review`,
+		url,
+		...reviewOutcome(build, input.approvals)
+	}];
+	return reviewClosed(input, url);
+}
+/**
+* Review is off and the build is accepted: a final `success`, so a `<prefix>/review` status left
+* `pending` by the time review was on (the switch-off pass accepts such builds) does not stay on
+* the pull request. The function sees no history, so every accepted build of a project with review
+* off shows it, and a host that requires the status never waits for one that will not come.
+*/
+function reviewClosed(input, url) {
+	if (input.build.status !== "approved") return [];
+	const { prefix } = input;
+	return [{
+		name: "review",
+		context: `${prefix}/review`,
+		url,
+		state: "success",
+		description: "Review is off"
+	}];
+}
+/**
+* A user cancelled the build (ADR 0006). It closes both gates the same way: the host shows
+* `cancelled` where it has the state (GitLab `canceled`, GitHub `error`), so a required status does
+* not wait for a result that will never come, and nothing says the build failed or was reviewed.
+*/
+const CANCELLED = {
+	state: "cancelled",
+	description: "Cancelled"
+};
+/** `pending` until captured, `pending` while review is open, then the review's result. */
+function testingOutcome(build) {
+	switch (build.status) {
+		case "reviewing": return {
+			state: "pending",
+			description: `Review open: ${plural(openCount(build), "change")} to review`
+		};
+		case "approved": return {
+			state: "success",
+			description: approvedText(build)
+		};
+		case "rejected": return {
+			state: "failure",
+			description: `Review closed: ${plural(build.rejectedCount, "change")} rejected`
+		};
+		case "failed": return {
+			state: "failure",
+			description: "Capture failed"
+		};
+		case "cancelled": return CANCELLED;
+		default: return {
+			state: "pending",
+			description: "Capturing and comparing screenshots"
+		};
+	}
+}
+/** The build-level verdict: `pending` until given, then `success` or `failure`. */
+function reviewOutcome(build, approvals) {
+	switch (build.status) {
+		case "approved": return {
+			state: "success",
+			description: "Build approved"
+		};
+		case "rejected": return {
+			state: "failure",
+			description: "Build rejected"
+		};
+		case "failed": return {
+			state: "failure",
+			description: "Build failed"
+		};
+		case "cancelled": return CANCELLED;
+		default: return {
+			state: "pending",
+			description: waitingText(approvals)
+		};
+	}
+}
+/** Informational: never a gate, linking to the published Storybook once there is one. */
+function storybookStatus(publishing, prefix, links) {
+	const base = {
+		name: "storybook",
+		context: `${prefix}/storybook`,
+		informational: true
+	};
+	if (publishing === "success") return {
+		...base,
+		state: "success",
+		description: "Storybook published",
+		url: links.storybook
+	};
+	if (publishing === "failure") return {
+		...base,
+		state: "failure",
+		description: "Storybook could not be published",
+		url: links.build
+	};
+	return {
+		...base,
+		state: "pending",
+		description: "Publishing Storybook",
+		url: links.build
+	};
+}
+/** `1 of 2 approvals` when the project needs several; a single approval just waits for a verdict. */
+function waitingText(approvals) {
+	if (approvals === void 0 || approvals.required <= 1) return "Waiting for a review verdict";
+	return `Waiting for approvals: ${String(approvals.given)} of ${String(approvals.required)}`;
+}
+function openCount(build) {
+	return Math.max(0, build.changedCount - build.approvedCount - build.rejectedCount);
+}
+function approvedText(build) {
+	return build.changedCount === 0 ? "Review closed: no visual changes" : `Review closed: ${plural(build.approvedCount, "change")} approved`;
+}
+function plural(count, noun) {
+	return `${String(count)} ${noun}${count === 1 ? "" : "s"}`;
+}
+export { MAX_ANNOTATIONS, statusesForBuild };
+
+//# sourceMappingURL=build-state.mjs.map

package/dist/adapters/notifier/build-state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-state.mjs","names":[],"sources":["../../../src/adapters/notifier/build-state.ts"],"sourcesContent":["/**\n * The states a build's git channels show, as one pure function of the build (ADR 0014, decision 5).\n * It reads no clock, database or provider: callers hand it the build, the channel's prefix and the\n * flags, and write the result to the host. Every transition and the end of publishing call it\n * again, so a build that was never captured still gets its statuses and a repeated call changes\n * nothing.\n */\nimport { LOCAL_SHA_PREFIX } from \"@storyshelf/affected\";\nimport type { UrlBuilder } from \"../../urls.ts\";\nimport { buildCommentMarkdown } from \"./build-comment.ts\";\nimport type { NotifierState, StateAnnotation } from \"./types.ts\";\n\n/** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */\nexport const MAX_ANNOTATIONS = 200;\n\n/** Names of the statuses below a channel's prefix. */\nexport type StatusName = \"testing\" | \"review\" | \"storybook\";\n\n/** How publishing the build's Storybook stands. */\nexport type PublishingState = \"pending\" | \"success\" | \"failure\";\n\n/** What decides which statuses exist (ADR 0014, decision 5). */\nexport interface BuildStateFlags {\n  /** `testing` is on: `<prefix>/testing` is the merge gate. */\n  testing: boolean;\n  /** Review is on for the project: with `testing` off, `<prefix>/review` is the gate. */\n  review: boolean;\n}\n\n/** The part of a build row the function reads. */\nexport interface BuildStateBuild {\n  id: string;\n  gitSha: string;\n  /** Build status: `pending`, `capturing`, `comparing`, `reviewing`, `approved`, `rejected`, `failed`, `cancelled`. */\n  status: string;\n  snapshotCount: number;\n  changedCount: number;\n  approvedCount: number;\n  rejectedCount: number;\n}\n\n/** The part of a snapshot row the annotations read. */\nexport interface BuildStateChange {\n  id: string;\n  /** `changed` or `new`; anything else is not a change to review. */\n  status: string;\n  storyTitle: string;\n  storyName: string;\n  storyImportPath: string | null;\n  viewportName: string;\n  browser?: string | undefined;\n}\n\n/** Inputs of {@link statusesForBuild}. */\nexport interface BuildStateInput {\n  build: BuildStateBuild;\n  projectSlug: string;\n  /** The channel's status-name prefix, without a trailing slash. */\n  prefix: string;\n  /**\n   * Absolute links (`createUrlBuilder(publicOrigin)`). A build's state is only ever shown once a\n   * public origin is resolved (ADR 0014, decision 11), so every status links and the comment exists.\n   */\n  urls: Pick<UrlBuilder, \"build\" | \"storybookBuild\" | \"snapshot\">;\n  flags: BuildStateFlags;\n  publishing: PublishingState;\n  /**\n   * Approval progress of the build-level review: the approvals among each reviewer's latest\n   * verdict and the approvals the project requires. Shown on `<prefix>/review` while it waits.\n   */\n  approvals?: { given: number; required: number } | undefined;\n  /** The build's snapshots; the `changed` and `new` ones become annotations of `<prefix>/testing`. */\n  changes?: readonly BuildStateChange[] | undefined;\n}\n\n/** One commit status to show. */\nexport interface DesiredStatus {\n  name: StatusName;\n  /** Full name on the host, `<prefix>/<name>`. */\n  context: string;\n  state: NotifierState;\n  description: string;\n  /** What the status links to: the build page, or the published Storybook for `storybook`. */\n  url: string;\n  /** True for the Storybook status, which is never a gate. */\n  informational?: boolean;\n  /** Set on a `pending` status: `queued` before capture starts, else `running`. */\n  progress?: \"queued\" | \"running\";\n  /** Per-snapshot findings (only `testing`), at most {@link MAX_ANNOTATIONS}. */\n  annotations?: StateAnnotation[];\n  /** Changes beyond the cap. */\n  omitted?: number;\n}\n\n/** The pull-request comment to show. */\nexport interface DesiredComment {\n  /** The build page; it keys the comment, one per build. */\n  url: string;\n  markdown: string;\n  state: NotifierState;\n}\n\n/** Everything a channel should show for a build. */\nexport interface BuildStateSet {\n  statuses: DesiredStatus[];\n  comment: DesiredComment | null;\n}\n\n/** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */\nexport function statusesForBuild(input: BuildStateInput): BuildStateSet {\n  const { build } = input;\n  if (build.gitSha.length === 0 || build.gitSha.startsWith(LOCAL_SHA_PREFIX)) {\n    return { statuses: [], comment: null };\n  }\n  const links = linksOf(input);\n  const statuses = [\n    ...withAnnotations(gateStatus(input, links.build), input),\n    storybookStatus(input.publishing, input.prefix, links),\n  ].map((status) => withProgress(status, input.build));\n  return { statuses, comment: commentOf(input, statuses, links) };\n}\n\n/** `pending` is `queued` while the build waits to be captured, `running` after. */\nfunction withProgress(status: DesiredStatus, build: BuildStateBuild): DesiredStatus {\n  if (status.state !== \"pending\") {\n    return status;\n  }\n  const queued = status.name !== \"storybook\" && build.status === \"pending\";\n  return { ...status, progress: queued ? \"queued\" : \"running\" };\n}\n\n/** One annotation per changed snapshot, on the `testing` gate. */\nfunction withAnnotations(gates: DesiredStatus[], input: BuildStateInput): DesiredStatus[] {\n  const changed = (input.changes ?? []).filter((c) => c.status === \"changed\" || c.status === \"new\");\n  if (changed.length === 0) {\n    return gates;\n  }\n  const annotations = changed\n    .slice(0, MAX_ANNOTATIONS)\n    .map((change) => annotationOf(change, input));\n  const omitted = changed.length - annotations.length;\n  return gates.map((gate) =>\n    gate.name === \"testing\" ? { ...gate, annotations, ...(omitted > 0 ? { omitted } : {}) } : gate,\n  );\n}\n\nfunction annotationOf(change: BuildStateChange, input: BuildStateInput): StateAnnotation {\n  const where = [change.viewportName, change.browser].filter(Boolean).join(\", \");\n  const isNew = change.status === \"new\";\n  const name = `${change.storyTitle} / ${change.storyName}`;\n  return {\n    path: change.storyImportPath?.replace(/^(?:\\.\\/)+/u, \"\") ?? \".storybook\",\n    title: where === \"\" ? name : `${name} (${where})`,\n    message: `${isNew ? \"New snapshot\" : \"Visual change\"}: review it at ${input.urls.snapshot(input.projectSlug, input.build.id, change.id)}`,\n    url: input.urls.snapshot(input.projectSlug, input.build.id, change.id),\n    level: isNew ? \"notice\" : \"warning\",\n  };\n}\n\nfunction commentOf(\n  input: BuildStateInput,\n  statuses: DesiredStatus[],\n  links: Links,\n): DesiredComment {\n  const gates = statuses.filter((status) => status.name !== \"storybook\");\n  return {\n    url: links.build,\n    state: gates[0]?.state ?? \"success\",\n    markdown: buildCommentMarkdown({\n      buildUrl: links.build,\n      storybookUrl: input.publishing === \"success\" ? links.storybook : undefined,\n      gates,\n      counts: input.flags.testing || input.flags.review ? input.build : undefined,\n    }),\n  };\n}\n\ninterface Links {\n  build: string;\n  storybook: string;\n}\n\n/** The links to show. */\nfunction linksOf(input: BuildStateInput): Links {\n  const { urls, projectSlug, build } = input;\n  return {\n    build: urls.build(projectSlug, build.id),\n    storybook: `${urls.storybookBuild(projectSlug, build.id).replace(/\\/+$/u, \"\")}/`,\n  };\n}\n\n/** `testing` when it is on; `review` when only review is on; none for a hosting-only build. */\nfunction gateStatus(input: BuildStateInput, url: string): DesiredStatus[] {\n  const { flags, build, prefix } = input;\n  if (flags.testing) {\n    return [{ name: \"testing\", context: `${prefix}/testing`, url, ...testingOutcome(build) }];\n  }\n  if (flags.review) {\n    return [\n      {\n        name: \"review\",\n        context: `${prefix}/review`,\n        url,\n        ...reviewOutcome(build, input.approvals),\n      },\n    ];\n  }\n  return reviewClosed(input, url);\n}\n\n/**\n * Review is off and the build is accepted: a final `success`, so a `<prefix>/review` status left\n * `pending` by the time review was on (the switch-off pass accepts such builds) does not stay on\n * the pull request. The function sees no history, so every accepted build of a project with review\n * off shows it, and a host that requires the status never waits for one that will not come.\n */\nfunction reviewClosed(input: BuildStateInput, url: string): DesiredStatus[] {\n  if (input.build.status !== \"approved\") {\n    return [];\n  }\n  const { prefix } = input;\n  return [\n    {\n      name: \"review\",\n      context: `${prefix}/review`,\n      url,\n      state: \"success\",\n      description: \"Review is off\",\n    },\n  ];\n}\n\ntype Outcome = Pick<DesiredStatus, \"state\" | \"description\">;\n\n/**\n * A user cancelled the build (ADR 0006). It closes both gates the same way: the host shows\n * `cancelled` where it has the state (GitLab `canceled`, GitHub `error`), so a required status does\n * not wait for a result that will never come, and nothing says the build failed or was reviewed.\n */\nconst CANCELLED: Outcome = { state: \"cancelled\", description: \"Cancelled\" };\n\n/** `pending` until captured, `pending` while review is open, then the review's result. */\nfunction testingOutcome(build: BuildStateBuild): Outcome {\n  switch (build.status) {\n    case \"reviewing\": {\n      return {\n        state: \"pending\",\n        description: `Review open: ${plural(openCount(build), \"change\")} to review`,\n      };\n    }\n    case \"approved\": {\n      return { state: \"success\", description: approvedText(build) };\n    }\n    case \"rejected\": {\n      return {\n        state: \"failure\",\n        description: `Review closed: ${plural(build.rejectedCount, \"change\")} rejected`,\n      };\n    }\n    case \"failed\": {\n      return { state: \"failure\", description: \"Capture failed\" };\n    }\n    case \"cancelled\": {\n      return CANCELLED;\n    }\n    default: {\n      return { state: \"pending\", description: \"Capturing and comparing screenshots\" };\n    }\n  }\n}\n\n/** The build-level verdict: `pending` until given, then `success` or `failure`. */\nfunction reviewOutcome(build: BuildStateBuild, approvals: BuildStateInput[\"approvals\"]): Outcome {\n  switch (build.status) {\n    case \"approved\": {\n      return { state: \"success\", description: \"Build approved\" };\n    }\n    case \"rejected\": {\n      return { state: \"failure\", description: \"Build rejected\" };\n    }\n    case \"failed\": {\n      return { state: \"failure\", description: \"Build failed\" };\n    }\n    case \"cancelled\": {\n      return CANCELLED;\n    }\n    default: {\n      return { state: \"pending\", description: waitingText(approvals) };\n    }\n  }\n}\n\n/** Informational: never a gate, linking to the published Storybook once there is one. */\nfunction storybookStatus(publishing: PublishingState, prefix: string, links: Links): DesiredStatus {\n  const base = { name: \"storybook\", context: `${prefix}/storybook`, informational: true } as const;\n  if (publishing === \"success\") {\n    return {\n      ...base,\n      state: \"success\",\n      description: \"Storybook published\",\n      url: links.storybook,\n    };\n  }\n  if (publishing === \"failure\") {\n    return {\n      ...base,\n      state: \"failure\",\n      description: \"Storybook could not be published\",\n      url: links.build,\n    };\n  }\n  return { ...base, state: \"pending\", description: \"Publishing Storybook\", url: links.build };\n}\n\n/** `1 of 2 approvals` when the project needs several; a single approval just waits for a verdict. */\nfunction waitingText(approvals: BuildStateInput[\"approvals\"]): string {\n  if (approvals === undefined || approvals.required <= 1) {\n    return \"Waiting for a review verdict\";\n  }\n  return `Waiting for approvals: ${String(approvals.given)} of ${String(approvals.required)}`;\n}\n\nfunction openCount(build: BuildStateBuild): number {\n  return Math.max(0, build.changedCount - build.approvedCount - build.rejectedCount);\n}\n\nfunction approvedText(build: BuildStateBuild): string {\n  return build.changedCount === 0\n    ? \"Review closed: no visual changes\"\n    : `Review closed: ${plural(build.approvedCount, \"change\")} approved`;\n}\n\nfunction plural(count: number, noun: string): string {\n  return `${String(count)} ${noun}${count === 1 ? \"\" : \"s\"}`;\n}\n"],"mappings":"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"}

package/dist/adapters/notifier/events.d.mts

@@ -1,15 +1,16 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { NotificationBrand, NotificationChannel, NotificationEvent, SystemNotification } from "./types.mjs";
-import { NotifierProvider } from "./provider.mjs";
 import { Logger } from "../../logger.mjs";
-//#region src/adapters/notifier/events.d.ts
+import { ChannelOutcome, NotificationBrand, NotificationChannel, NotificationEvent, SystemNotification } from "./types.mjs";
+import { NotifierProvider } from "./provider.mjs";
 /** Options for project-event fan-out (inline best-effort, non-fatal). */
 interface EmitNotificationsOptions {
   notifiers?: NotifierProvider[];
   channels?: NotificationChannel[];
   brand?: NotificationBrand;
   logger?: Logger;
+  /** Called once per attempted channel so the host can record or clear its last error. */
+  onOutcome?: (outcome: ChannelOutcome) => Promise<void> | void;
 }
 /**
  * Deliver a project event to every subscribed channel.
@@ -21,6 +22,5 @@ declare function emitNotifications(event: NotificationEvent, options?: EmitNotif
  * (e.g. `sys:user-created`, `sys:capture-failed`, `sys:purge-completed`).
  */
 declare function emitSystemNotification(event: SystemNotification, options?: EmitNotificationsOptions): Promise<void>;
-//#endregion
 export { EmitNotificationsOptions, emitNotifications, emitSystemNotification };
 //# sourceMappingURL=events.d.mts.map