components/publish-gate/publish-gate-model.ts

Functions

Imports

It imports no other module of this repo. Imported by components/publish-gate/publish-gate.ts.

Source

1// The publish gate's data and its pure helpers (publish-gate.ts).
2
3export type GateState = "blocked" | "held" | "ready" | "published";
4export type CheckState = "failing" | "advisory" | "passed";
5
6export interface GateCheck {
7  id: string;
8  // The rule's name in words the operator uses: "Alt text".
9  name: string;
10  // Required checks block publishing; advisory ones do not.
11  required: boolean;
12  ok: boolean;
13  // What causes it, when failing: "The cover image has no alt text".
14  cause: string;
15  // What it says when it passes: "Every image has alt text".
16  pass?: string;
17  // Where the cause is: the passage, field or setting (href="#field-alt").
18  href?: string;
19  // How to fix it: "Describe what the image shows."
20  fix?: string;
21  // The destination it concerns. Without it the check applies to every destination.
22  site?: string;
23}
24
25export interface GateHold {
26  // A person or a schedule holds it.
27  by?: string;
28  // "review", "legal check".
29  reason?: string;
30  // The time it is held until, ISO, and how it reads: "Fri 09:00".
31  until?: string;
32  untilLabel?: string;
33  // Anything more the person needs to know.
34  note?: string;
35  // A hold read back from the page carries its sentence whole, and it wins over the parts.
36  text?: string;
37}
38
39export interface GatePublished {
40  // ISO.
41  at: string;
42  // The live page.
43  url: string;
44}
45
46export interface GateSite {
47  id: string;
48  name: string;
49  hold?: GateHold | null;
50  published?: GatePublished | null;
51  // It has never been public: publishing is one-way, so it is previewed first.
52  first?: boolean;
53}
54
55// ---------------------------------------------------------------------------------------
56// Pure helpers.
57
58export function checkState(c: Pick<GateCheck, "ok" | "required">): CheckState {
59  return c.ok ? "passed" : c.required ? "failing" : "advisory";
60}
61
62// Failing required checks first, then failing advisory ones, then the ones that pass. Stable.
63export function sortChecks<T extends Pick<GateCheck, "ok" | "required">>(checks: readonly T[]): T[] {
64  const rank = (c: T) => (c.ok ? 2 : c.required ? 0 : 1);
65  return checks
66    .map((c, i) => [c, i] as const)
67    .sort(([a, i], [b, j]) => rank(a) - rank(b) || i - j)
68    .map(([c]) => c);
69}
70
71// Blocked while a required check fails; else held while someone or something holds it; else ready.
72export function gateState(checks: readonly Pick<GateCheck, "ok" | "required">[], hold?: GateHold | null): Exclude<GateState, "published"> {
73  if (checks.some((c) => c.required && !c.ok)) return "blocked";
74  return hold ? "held" : "ready";
75}
76
77export function appliesTo(check: Pick<GateCheck, "site">, siteId: string): boolean {
78  return !check.site || check.site === siteId;
79}
80
81// A destination's own state: published once published, else what its checks and hold say.
82export function siteState(site: Pick<GateSite, "id" | "hold" | "published">, checks: readonly GateCheck[]): GateState {
83  if (site.published) return "published";
84  return gateState(checks.filter((c) => appliesTo(c, site.id)), site.hold);
85}
86
87const WORST: GateState[] = ["blocked", "held", "ready", "published"];
88
89// The overall state is the worst of the destinations'.
90export function worstState(states: readonly GateState[]): GateState {
91  return WORST.find((s) => states.includes(s)) ?? "ready";
92}
93
94export interface GateCounts {
95  requiredFailing: number;
96  advisoryFailing: number;
97  passed: number;
98  total: number;
99}
100
101export function countChecks(checks: readonly Pick<GateCheck, "ok" | "required">[]): GateCounts {
102  const requiredFailing = checks.filter((c) => c.required && !c.ok).length;
103  const advisoryFailing = checks.filter((c) => !c.required && !c.ok).length;
104  return { requiredFailing, advisoryFailing, passed: checks.length - requiredFailing - advisoryFailing, total: checks.length };
105}
106
107const plural = (n: number, one: string, many: string = `${one}s`) => `${n} ${n === 1 ? one : many}`;
108
109// The headings: "Required, 2 failing", "Advisory, 3", "9 checks passed".
110export const requiredHeading = (n: number) => `Required, ${n} failing`;
111export const advisoryHeading = (n: number) => `Advisory, ${n}`;
112export const passedHeading = (n: number) => `${plural(n, "check")} passed`;
113
114// "Held for review by Rosa until Fri 09:00".
115export function holdText(h: GateHold): string {
116  if (h.text) return h.text;
117  return `Held${h.reason ? ` for ${h.reason}` : ""}${h.by ? ` by ${h.by}` : ""}${h.untilLabel ? ` until ${h.untilLabel}` : ""}`;
118}
119
120// Names in a sentence: "a", "a and b", "a, b and c", "4 sites" beyond three.
121export function nameList(names: readonly string[]): string {
122  if (names.length <= 2) return names.join(" and ");
123  if (names.length === 3) return `${names[0]}, ${names[1]} and ${names[2]}`;
124  return `${names.length} sites`;
125}
126
127export const WORD: Record<GateState, string> = { blocked: "Blocked", held: "Held", ready: "Ready", published: "Published" };
128export const stateWord = (s: GateState) => WORD[s];
129
130export interface GateReading {
131  sites: Array<{ site: GateSite; state: GateState; failing: GateCheck[] }>;
132  state: GateState;
133  // The words after the status word, with the colon: "Blocked" then ": 2 required checks failing on dustinedwards.info".
134  rest: string;
135}
136
137// The one sentence for the whole region: "Blocked: 2 required checks failing on dustinedwards.info".
138export function describeGate(sites: readonly GateSite[], checks: readonly GateCheck[]): GateReading {
139  const read = sites.map((site) => ({ site, state: siteState(site, checks), failing: checks.filter((c) => appliesTo(c, site.id) && !c.ok && c.required) }));
140  const state = worstState(read.map((r) => r.state));
141  const of = (s: GateState) => read.filter((r) => r.state === s);
142  const where = nameList(of(state).map((r) => r.site.name));
143  let rest = "";
144  if (state === "blocked") {
145    // A check that applies to every destination is one check, however many it blocks.
146    const distinct = new Set(of("blocked").flatMap((r) => r.failing.map((c) => c.id))).size;
147    rest = `: ${plural(distinct, "required check")} failing on ${where}`;
148  } else if (state === "held") {
149    const held = of("held").map((r) => r.site);
150    // "Held for review by Rosa until Fri 09:00": the word, then what the hold says.
151    const said = held.length === 1 && held[0]?.hold ? holdText(held[0].hold).replace(/^Held/, "") : "";
152    rest = held.length === 1 ? `${said}${sites.length > 1 ? ` on ${where}` : ""}` : `: ${where}`;
153  } else if (state === "ready") {
154    const adv = new Set(checks.filter((c) => !c.required && !c.ok).map((c) => c.id)).size;
155    rest = `: nothing required is failing on ${where}${adv ? `, ${plural(adv, "advisory check")} failing` : ""}`;
156  } else rest = `: live on ${where}`;
157  return { sites: read, state, rest };
158}
159
160// The line under a destination's name.
161export function siteDetail(state: GateState, failing: readonly GateCheck[], advisory: number, site: Pick<GateSite, "hold">): string {
162  if (state === "blocked") return `${plural(failing.length, "required check")} failing: ${failing.map((c) => c.cause).join("; ")}`;
163  if (state === "held") return `${site.hold ? holdText(site.hold) : "Held"}.${site.hold?.note ? ` ${site.hold.note}` : ""}`;
164  if (state === "ready") return `Nothing required is failing.${advisory ? ` ${plural(advisory, "advisory check")} failing.` : ""}`;
165  return "Live.";
166}