@boxxy/verifier-wringer 0.0.1 → 0.2.4

package/README.md

@@ -1,3 +1,43 @@
-# @boxxy/verifier-wringer
+<div align="center">
+  <h1>@boxxy/verifier-wringer</h1>
 
-A placeholder. CI publishes the real versions from https://github.com/zgeoff/boxxy.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/verifier-wringer"><img src="https://img.shields.io/npm/v/@boxxy/verifier-wringer" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's `Verifier` port on wringer: it reads the verify gate check at a pull request's head and the
+wringer report in the pull request's body.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/verifier-wringer) with Bun:
+
+```bash
+bun add @boxxy/verifier-wringer
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `createWringerVerifier({ forge, gateCheck })` returns a `Verifier`. The app passes its forge and
+  the name of the gate check, such as `verify / gate`.
+- `readAt(pullRequest, head)` reads the latest run of the gate check at `head`. A passed gate reads
+  `verified` and a failed gate reads `incomplete`, each with the features of the report.
+- A head with no gate check run, or one still running, cancelled or skipped, reads `not-covered`.
+  The adapter then never reads the body. A commit status of the gate's name never counts.
+- A finished gate with no report in the body, or a report that does not parse, reads `incomplete`
+  with no features.
+- The adapter does no I/O of its own. It reads the forge, and parses the report with wringer's
+  `parseReportBlock`.
+
+## Documentation
+
+[The verifier](../../docs/design/boxxy/review-and-merge.md#the-verifier) describes how the verdict
+reaches the merge.

package/dist/create-wringer-verifier.d.ts

@@ -0,0 +1,3 @@
+import type { Verifier } from '@boxxy/model';
+import type { WringerVerifierOptions } from './types.ts';
+export declare function createWringerVerifier(options: WringerVerifierOptions): Verifier;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createWringerVerifier } from './create-wringer-verifier.ts';
+export type { WringerVerifierOptions } from './types.ts';

package/dist/test-utils/build-mock-wringer-report.d.ts

@@ -0,0 +1,9 @@
+import type { FeatureStatus, Report } from '@wringer/core';
+interface MockWringerReportInput {
+    readonly features: readonly {
+        readonly name: string;
+        readonly status: FeatureStatus;
+    }[];
+}
+export declare function buildMockWringerReport(input: MockWringerReportInput): Report;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+import type { Forge } from '@boxxy/model';
+export interface WringerVerifierOptions {
+    readonly forge: Pick<Forge, 'readChecks' | 'readPullRequestBody'>;
+    readonly gateCheck: string;
+}

package/package.json

@@ -1,13 +1,52 @@
 {
   "name": "@boxxy/verifier-wringer",
-  "version": "0.0.1",
+  "version": "0.2.4",
+  "description": "boxxy's verifier on wringer: reads the verify gate check and the report in a pull request",
+  "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/verifier-wringer#readme",
+  "bugs": "https://github.com/zgeoff/boxxy/issues",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zgeoff/boxxy.git",
     "directory": "adapters/verifier-wringer"
   },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/model": "0.2.4",
+    "@wringer/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@boxxy/dispatch": "0.2.4",
+    "@faker-js/faker": "10.6.0"
+  },
+  "peerDependencies": {
+    "@faker-js/faker": "10.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@faker-js/faker": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
   }
 }

package/src/create-wringer-verifier.ts

@@ -0,0 +1,54 @@
+import type { CheckReading, CommitSha, Verifier, VerifyReading } from '@boxxy/model';
+import { parseReportBlock } from '@wringer/core';
+import type { WringerVerifierOptions } from './types.ts';
+
+// The `Verifier` port on wringer. The gate check in CI computes the fingerprint, which needs a
+// checkout, so the verifier trusts the gate's conclusion and takes the features from the report.
+export function createWringerVerifier(options: WringerVerifierOptions): Verifier {
+  return {
+    readAt: async (pullRequest, head) => {
+      const checks = await options.forge.readChecks(pullRequest.repo, head);
+
+      const gate = pickGateState(checks.get(options.gateCheck));
+
+      if (gate === null) {
+        return { status: 'not-covered', head };
+      }
+
+      const body = await options.forge.readPullRequestBody(pullRequest);
+
+      return buildVerifyReading(head, gate, body);
+    },
+  };
+}
+
+// Only the workflow's check run counts: any token that may write statuses could post a commit
+// status of the gate's name. A cancelled or skipped run gave no verdict, as a run still going.
+function pickGateState(gate: CheckReading | undefined): 'success' | 'failure' | null {
+  if (gate?.source !== 'check-run') {
+    return null;
+  }
+
+  return gate.state === 'success' || gate.state === 'failure' ? gate.state : null;
+}
+
+function buildVerifyReading(
+  head: CommitSha,
+  gate: 'success' | 'failure',
+  body: string,
+): VerifyReading {
+  const parsed = parseReportBlock(body);
+
+  if (!parsed.ok) {
+    return { status: 'incomplete', head, features: [] };
+  }
+
+  return {
+    status: gate === 'success' ? 'verified' : 'incomplete',
+    head,
+    features: parsed.report.features.map((feature) => ({
+      name: feature.name,
+      status: feature.status,
+    })),
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createWringerVerifier } from './create-wringer-verifier.ts';
+export type { WringerVerifierOptions } from './types.ts';

package/src/test-utils/build-mock-wringer-report.ts

@@ -0,0 +1,40 @@
+import { faker } from '@faker-js/faker';
+import type { FeatureStatus, Report } from '@wringer/core';
+
+interface MockWringerReportInput {
+  readonly features: readonly { readonly name: string; readonly status: FeatureStatus }[];
+}
+
+// A wringer report against `origin/main` at a random fingerprint. A `verified` or `stale` feature
+// carries a verdict, and only an `unchanged` feature is unchanged.
+export function buildMockWringerReport(input: MockWringerReportInput): Report {
+  const fingerprint = faker.string.hexadecimal({ length: 16, casing: 'lower', prefix: '' });
+
+  return {
+    version: 1,
+    base: 'origin/main',
+    fingerprint,
+    complete: input.features.every(
+      (feature) => feature.status === 'verified' || feature.status === 'unchanged',
+    ),
+    features: input.features.map((feature) => ({
+      name: feature.name,
+      changed: feature.status !== 'unchanged',
+      status: feature.status,
+      verdict:
+        feature.status === 'verified' || feature.status === 'stale'
+          ? {
+              feature: feature.name,
+              fingerprint:
+                feature.status === 'verified'
+                  ? fingerprint
+                  : faker.string.hexadecimal({ length: 16, casing: 'lower', prefix: '' }),
+              run: `run-${faker.string.alphanumeric(8)}`,
+              at: faker.date.recent().toISOString(),
+              evidence: [],
+            }
+          : null,
+    })),
+    unmapped: [],
+  };
+}

package/src/types.ts

@@ -0,0 +1,8 @@
+import type { Forge } from '@boxxy/model';
+
+export interface WringerVerifierOptions {
+  readonly forge: Pick<Forge, 'readChecks' | 'readPullRequestBody'>;
+
+  // the name of the check run that runs `bun verify gate`, such as `verify / gate`
+  readonly gateCheck: string;
+}