@boxxy/model 0.1.2 → 0.1.3

package/src/test-utils/create-fake-notifier.ts

@@ -0,0 +1,54 @@
+import type { HoldNotice, NoticeOutcome, Notifier } from '../ports/types.ts';
+
+export interface FakeNotifier extends Notifier {
+  // each notice that was sent, in order
+  readonly told: readonly HoldNotice[];
+
+  // the number of calls, sent or failed
+  readonly calls: () => number;
+
+  // the next call fails with the reason
+  failNext: (reason: string) => void;
+
+  // every call fails with the reason until `recover`
+  failAlways: (reason: string) => void;
+  recover: () => void;
+}
+
+export function createFakeNotifier(): FakeNotifier {
+  const told: HoldNotice[] = [];
+  let calls = 0;
+  let next: string | null = null;
+  let always: string | null = null;
+
+  return {
+    told,
+    calls: () => calls,
+    failNext: (reason) => {
+      next = reason;
+    },
+    failAlways: (reason) => {
+      always = reason;
+    },
+    recover: () => {
+      always = null;
+    },
+    tellHold: (notice) => {
+      calls += 1;
+
+      const reason = next ?? always;
+
+      next = null;
+
+      if (reason !== null) {
+        const failed: NoticeOutcome = { kind: 'failed', reason };
+
+        return Promise.resolve(failed);
+      }
+
+      told.push(notice);
+
+      return Promise.resolve({ kind: 'sent' });
+    },
+  };
+}

package/src/test-utils/create-fake-pepys-reader.ts

@@ -0,0 +1,73 @@
+import type { PepysAnswer, PepysReader } from '../ports/types.ts';
+import { stageSteps } from '../reports/constants.ts';
+import type { CostToLand, StageTime } from '../reports/types.ts';
+import type { ItemId } from '../types.ts';
+
+interface FakeValues {
+  readonly cost?: CostToLand;
+  readonly stageTime?: StageTime;
+}
+
+export interface FakePepysReader extends PepysReader {
+  // an item with no value set answers as pepys does for an item it holds no fact of
+  set: (item: ItemId, values: FakeValues) => void;
+
+  // the next call, of either method, answers `unavailable` with this reason; each call of
+  // `failNext` fails one more call
+  failNext: (reason: string) => void;
+}
+
+export function createFakePepysReader(environment = 'production'): FakePepysReader {
+  const costs = new Map<ItemId, CostToLand>();
+  const stageTimes = new Map<ItemId, StageTime>();
+
+  const failures: string[] = [];
+
+  const answer = <Value>(value: Value): Promise<PepysAnswer<Value>> => {
+    const reason = failures.shift();
+
+    const answered: PepysAnswer<Value> =
+      reason === undefined ? { kind: 'value', value } : { kind: 'unavailable', reason };
+
+    return Promise.resolve(answered);
+  };
+
+  return {
+    set: (item, values) => {
+      if (values.cost !== undefined) {
+        costs.set(item, values.cost);
+      }
+
+      if (values.stageTime !== undefined) {
+        stageTimes.set(item, values.stageTime);
+      }
+    },
+    failNext: (reason) => {
+      failures.push(reason);
+    },
+    readCostToLand: (item) => answer(costs.get(item) ?? buildEmptyCost(item)),
+    readStageTime: (item) => answer(stageTimes.get(item) ?? buildEmptyStageTime(item, environment)),
+  };
+}
+
+function buildEmptyCost(item: ItemId): CostToLand {
+  return {
+    item: `boxxy:item:${item}`,
+    landedAt: null,
+    attempts: 0,
+    lines: [],
+    totals: { requests: 0, costUSD: 0, reworkCostUSD: 0, requestsWithoutCost: 0 },
+  };
+}
+
+function buildEmptyStageTime(item: ItemId, environment: string): StageTime {
+  return {
+    item: `boxxy:item:${item}`,
+    environment,
+    steps: stageSteps.map((step) => ({ step, minutes: null, endedAt: null })),
+    rework: { count: 0, minutes: 0 },
+    reviewWaitMinutes: null,
+    sleepMinutes: 0,
+    pullRequests: [],
+  };
+}

package/src/test-utils/fact-sink-contract.ts

@@ -0,0 +1,103 @@
+import type { FactId, FactSink, OutboxFact } from '@boxxy/model';
+import { buildMockOutboxFact } from '@boxxy/model/test-utils/build-mock-outbox-fact';
+
+export interface FactSinkHarness {
+  readonly sink: FactSink;
+
+  // the fact IDs the log holds, in the order they arrived, a copy of an ID counted once
+  readStored: () => Promise<readonly FactId[]>;
+
+  // the same fact, changed so that the sink refuses a batch that holds it
+  corrupt: (fact: OutboxFact) => OutboxFact;
+}
+
+export type FactSinkCase = readonly [
+  title: string,
+  check: (harness: FactSinkHarness) => Promise<{ received: unknown; expected: unknown }>,
+];
+
+// The cases that every adapter of the sink port must pass: the fake, and the pepys adapter behind
+// ingest's route handler. Each case gets a harness with an empty log.
+export const factSinkContract: readonly FactSinkCase[] = [
+  [
+    'a batch is stored whole and in order',
+    async (harness) => {
+      const batch = buildFacts(3, 1);
+
+      const answer = await harness.sink.send(batch);
+
+      return {
+        received: { answer, stored: await harness.readStored() },
+        expected: { answer: { kind: 'stored' }, stored: batch.map((fact) => fact.factId) },
+      };
+    },
+  ],
+  [
+    'the same batch sent twice is stored as one copy of each fact',
+    async (harness) => {
+      const batch = buildFacts(2, 1);
+
+      await harness.sink.send(batch);
+
+      const answer = await harness.sink.send(batch);
+
+      return {
+        received: { answer, stored: await harness.readStored() },
+        expected: { answer: { kind: 'stored' }, stored: batch.map((fact) => fact.factId) },
+      };
+    },
+  ],
+  [
+    'two batches sent one after the other keep their order',
+    async (harness) => {
+      const first = buildFacts(2, 1);
+      const second = buildFacts(2, 3);
+
+      await harness.sink.send(first);
+      await harness.sink.send(second);
+
+      return {
+        received: await harness.readStored(),
+        expected: [...first, ...second].map((fact) => fact.factId),
+      };
+    },
+  ],
+  [
+    'a batch with a bad fact is refused whole and stores none of it',
+    async (harness) => {
+      const [good, bad] = buildPair();
+
+      const answer = await harness.sink.send([good, harness.corrupt(bad)]);
+
+      return {
+        received: { kind: answer.kind, stored: await harness.readStored() },
+        expected: { kind: 'refused-batch', stored: [] },
+      };
+    },
+  ],
+  [
+    'a good batch is stored after a bad one was refused',
+    async (harness) => {
+      const [good, bad] = buildPair();
+
+      await harness.sink.send([good, harness.corrupt(bad)]);
+
+      const answer = await harness.sink.send([good]);
+
+      return {
+        received: { answer, stored: await harness.readStored() },
+        expected: { answer: { kind: 'stored' }, stored: [good.factId] },
+      };
+    },
+  ],
+];
+
+function buildFacts(count: number, firstSeq: number): OutboxFact[] {
+  return Array.from({ length: count }, (_unused, index) =>
+    buildMockOutboxFact({ seq: firstSeq + index }),
+  );
+}
+
+function buildPair(): [OutboxFact, OutboxFact] {
+  return [buildMockOutboxFact({ seq: 1 }), buildMockOutboxFact({ seq: 2 })];
+}

package/src/test-utils/pepys-reader-contract.ts

@@ -0,0 +1,117 @@
+import { faker } from '@faker-js/faker';
+import type { PepysReader } from '../ports/types.ts';
+import type { CostToLand } from '../reports/types.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { ItemId } from '../types.ts';
+import { buildMockCostToLand } from './build-mock-cost-to-land.ts';
+
+export interface PepysReaderHarness {
+  readonly reader: PepysReader;
+
+  // the environment the reader passes to the stage times
+  readonly environment: string;
+
+  // pepys holds this cost for the item
+  writeCost: (item: ItemId, cost: CostToLand) => Promise<void>;
+
+  // every later call finds pepys down
+  takeDown: () => Promise<void>;
+}
+
+export type PepysReaderCase = readonly [
+  title: string,
+  check: (harness: PepysReaderHarness) => Promise<{ received: unknown; expected: unknown }>,
+];
+
+// The cases that every adapter of the reader port must pass: the fake, and the pepys adapter
+// behind the plug-in's queries. Each case gets a harness with an empty pepys.
+export const pepysReaderContract: readonly PepysReaderCase[] = [
+  [
+    'an item that pepys holds no fact of gives the empty cost, not unavailable',
+    async (harness) => {
+      const item = buildItemId();
+
+      return {
+        received: await harness.reader.readCostToLand(item),
+        expected: {
+          kind: 'value',
+          value: {
+            item: `boxxy:item:${item}`,
+            landedAt: null,
+            attempts: 0,
+            lines: [],
+            totals: { requests: 0, costUSD: 0, reworkCostUSD: 0, requestsWithoutCost: 0 },
+          },
+        },
+      };
+    },
+  ],
+  [
+    'an item that pepys holds no fact of gives seven steps with null minutes',
+    async (harness) => {
+      const item = buildItemId();
+      const empty = { minutes: null, endedAt: null };
+
+      return {
+        received: await harness.reader.readStageTime(item),
+        expected: {
+          kind: 'value',
+          value: {
+            item: `boxxy:item:${item}`,
+            environment: harness.environment,
+            steps: [
+              { step: 'triage', ...empty },
+              { step: 'design', ...empty },
+              { step: 'build', ...empty },
+              { step: 'review', ...empty },
+              { step: 'merge', ...empty },
+              { step: 'release', ...empty },
+              { step: 'deploy', ...empty },
+            ],
+            rework: { count: 0, minutes: 0 },
+            reviewWaitMinutes: null,
+            sleepMinutes: 0,
+            pullRequests: [],
+          },
+        },
+      };
+    },
+  ],
+  [
+    'a cost that pepys holds comes back whole',
+    async (harness) => {
+      const item = buildItemId();
+      const cost = buildMockCostToLand({ item: `boxxy:item:${item}` });
+
+      await harness.writeCost(item, cost);
+
+      return {
+        received: await harness.reader.readCostToLand(item),
+        expected: { kind: 'value', value: cost },
+      };
+    },
+  ],
+  [
+    'a pepys that is down gives unavailable with a reason for both reads',
+    async (harness) => {
+      const item = buildItemId();
+
+      await harness.takeDown();
+
+      return {
+        received: [
+          await harness.reader.readCostToLand(item),
+          await harness.reader.readStageTime(item),
+        ].map((answer) => ({ kind: answer.kind, hasReason: 'reason' in answer })),
+        expected: [
+          { kind: 'unavailable', hasReason: true },
+          { kind: 'unavailable', hasReason: true },
+        ],
+      };
+    },
+  ],
+];
+
+function buildItemId(): ItemId {
+  return brandSchemas.itemId.parse(faker.string.uuid({ version: 7 }));
+}