@fitzzero/quickdraw-core 5.0.1 → 5.1.1

package/dist/testing/index.d.ts

@@ -1,18 +1,18 @@
-import { T as TestApp } from '../createTestApp-Cg2CZa1g.js';
-export { E as EventQuery, F as FrameMatch, d as FrameQuery, f as FrameRecorder, R as RecordedFrame, S as ServerFrameOf, a as TestAppOptions, b as TestConnection, c as createTestApp, g as emitWithAck, e as eventFrames, s as streamFrames, w as waitForEvent } from '../createTestApp-Cg2CZa1g.js';
-import { d as FlushSink, W as WriteRecord, e as FlushInfo, A as AnyService, f as Service } from '../caller-BqCYnpmC.js';
-export { g as DevWarning, D as DevWarningError, h as DevWarningKind } from '../caller-BqCYnpmC.js';
-import { J as AnyContract, ap as MethodName, al as InputOf } from '../infer-Dw21kmLw.js';
+import { T as TestApp } from '../createTestApp-UKVGEmOf.js';
+export { E as EventQuery, F as FrameMatch, d as FrameQuery, f as FrameRecorder, R as RecordedFrame, S as ServerFrameOf, a as TestAppOptions, b as TestConnection, c as createTestApp, g as emitWithAck, e as eventFrames, s as streamFrames, w as waitForEvent } from '../createTestApp-UKVGEmOf.js';
+import { e as FlushSink, W as WriteRecord, f as FlushInfo, A as AnyService, g as ServiceMethod, h as Service } from '../caller-CXTFswBO.js';
+export { i as DevWarning, D as DevWarningError, j as DevWarningKind } from '../caller-CXTFswBO.js';
+import { P as PrincipalOfServices } from '../http-Djj2Inuu.js';
 import { a as ErrorCode } from '../errors-S-bxEIBC.js';
-import { P as PrincipalOfServices } from '../http-D3fSFQ57.js';
-import { Q as QuickdrawTypes, P as Principal } from '../types-Bwg3kIEc.js';
-import '../envelope-nf5eGB-a.js';
-import '../createServer-CGsJlxM8.js';
+import { J as AnyContract, ap as MethodName, al as InputOf } from '../infer-Teo1xpsd.js';
+import { Q as QuickdrawTypes, P as Principal } from '../types-Cu0vmx7c.js';
+import '../envelope-Cp3YcVxC.js';
+import '../createServer-CP9eDHZZ.js';
 import 'node:http';
-import '../auth-CMyRkfjZ.js';
+import '../auth-BhWqdyb-.js';
 import 'socket.io';
 import '../logger-BY28acW-.js';
-import '../metrics-C0WvB7-I.js';
+import '../metrics-BdBu5o8G.js';
 import 'socket.io-client';
 
 /** One flush a recording sink received. */
@@ -113,6 +113,148 @@ declare function budgetFileOf(testFile: string): string;
  */
 declare function expectBudget(run: () => unknown, options: BudgetOptions): Promise<BudgetResult>;
 
+/** What one cell recorded: `"ok"`, or the error code the call or subscribe failed with. */
+type AccessOutcome = "ok" | ErrorCode;
+/**
+ * A principal as the snapshot records it: its `kind` (`null` for a principal
+ * without one), or `null` for the anonymous caller.
+ */
+type AccessSnapshotPrincipal = {
+    readonly kind: string | null;
+} | null;
+/** One row of the matrix (a method, subscribe or scope, with its row variant): an outcome per principal. */
+type AccessSnapshotRow = Readonly<Record<string, AccessOutcome>>;
+/** The contents of an access snapshot file. */
+interface AccessSnapshot {
+    readonly version: 1;
+    /** Every principal of the matrix, the anonymous caller included, by name. */
+    readonly principals: Readonly<Record<string, AccessSnapshotPrincipal>>;
+    /** Method calls: `<service>.<method>`, plus ` (<variant>)` for a row variant. */
+    readonly methods: Readonly<Record<string, AccessSnapshotRow>>;
+    /** Entity subscribes (`qd:sub`): `<service>`, plus ` (<variant>)`. */
+    readonly subscriptions: Readonly<Record<string, AccessSnapshotRow>>;
+    /** Collection scopes (`qd:col:sub`): `<service>.<collection>`, plus ` (<variant>)` (`(self)` for a `"self"` scope). */
+    readonly collections: Readonly<Record<string, AccessSnapshotRow>>;
+    /** The methods left out with `exclude`, as `<service>.<method>`. */
+    readonly excluded: readonly string[];
+}
+
+/** The environment variable that rewrites access snapshots: `QD_UPDATE_ACCESS_SNAPSHOT=1` (or `true`). */
+declare const ACCESS_SNAPSHOT_ENV = "QD_UPDATE_ACCESS_SNAPSHOT";
+/** What a run did with the snapshot file. */
+type AccessSnapshotChange = "written" | "unchanged" | "updated";
+/** The access snapshot file of `testFile`: `__access__/<its name>.json` in its directory. */
+declare function accessSnapshotFileOf(testFile: string): string;
+
+/** The row ids a matrix's cells are about, by service name: one id, or named variants (`{ own, other }`). */
+type AccessRows = Readonly<Record<string, string | Readonly<Record<string, string>>>>;
+/** The callers of a matrix by name, or a function of the fixture making them. */
+type AccessPrincipals<P, Fixture, Name extends string = string> = Readonly<Record<Name, P | null>> | ((fixture: Fixture) => Readonly<Record<Name, P | null>>);
+
+/** The cell an `inputs` function makes the input of. */
+interface AccessSnapshotRef {
+    /** The service's name. */
+    readonly service: string;
+    /** The method's name. */
+    readonly method: string;
+    readonly kind: ServiceMethod["kind"];
+    /** The row variant, when `rows` names variants for the service whose row the method is about. */
+    readonly variant: string | undefined;
+    /**
+     * The row the cell is about, from `rows`: the method's own service's for
+     * an `entry` form, the `of` contract's for a `scope` form, and its own
+     * for any other form whose input has an `id`; `undefined` for a method
+     * about no row.
+     */
+    readonly row: string | undefined;
+    /** The name of the principal the cell runs as. */
+    readonly principal: string;
+}
+/** Options of {@link snapshotAccessMatrix}. `Fixture` is what `reset` resolves with. */
+interface AccessSnapshotOptions<P, Fixture, Name extends string> {
+    /**
+     * The callers, by name, or a function of the fixture making them (read
+     * again after every reset, for a seed that makes new ids); their names
+     * must stay the same. An anonymous caller named `"anonymous"` is added
+     * unless one is `null`.
+     */
+    readonly principals: AccessPrincipals<P, Fixture, Name>;
+    /**
+     * Empties the database and seeds it, resolving with what the seed made
+     * (the fixture): the app's `resetDatabase` (from `./testing/prisma`) and
+     * its seed, writing with the untracked client. Called first, and again
+     * after every mutation the pipeline did not refuse.
+     */
+    readonly reset: () => Fixture | PromiseLike<Fixture>;
+    /**
+     * The row each service's cells are about, by service name: a row id, or
+     * named variants (`{ own: p1, other: p2 }`), each a row of its own in the
+     * snapshot. It must name every service whose rows a method's form, an
+     * entity subscribe or a collection scope of the matrix reads.
+     */
+    readonly rows: (fixture: Fixture) => AccessRows;
+    /**
+     * A method's input for one cell, when the generated one will not do;
+     * `undefined` to generate it. An input that fails the method's input
+     * schema is recorded as `VALIDATION` and never called.
+     */
+    readonly inputs?: (ref: AccessSnapshotRef, fixture: Fixture) => unknown;
+    /** The services whose methods, subscribes and scopes the matrix holds. Default: every service the app serves. */
+    readonly services?: readonly AnyService[];
+    /** Methods left out, as `<service>.<method>`: those whose outcome is not the same on every run. */
+    readonly exclude?: readonly string[];
+    /** The test file the snapshot sits beside. Default: the running test's file, from the test runner. */
+    readonly file?: string;
+}
+/** What {@link snapshotAccessMatrix} recorded, and what it did with the snapshot file. */
+interface AccessSnapshotReport {
+    /** The snapshot file. */
+    readonly path: string;
+    /**
+     * `"written"`: there was no file; `"unchanged"`: the matrix is the stored
+     * one; `"updated"`: the file was rewritten (cells added or removed in a
+     * local run, or changes accepted with `QD_UPDATE_ACCESS_SNAPSHOT=1`).
+     */
+    readonly change: AccessSnapshotChange;
+    /** The matrix this run recorded. */
+    readonly snapshot: AccessSnapshot;
+    /**
+     * The cells never called because no input passed the method's input
+     * schema (or named the cell's row where its form reads it), as
+     * `<row> as <principal>`: recorded as `VALIDATION`, they pin nothing
+     * about access. Give their inputs with `inputs`.
+     */
+    readonly inconclusive: readonly string[];
+}
+/**
+ * Records who may call what through `app` (from `createTestApp`): every
+ * method of `services` (default: every service the app serves), each
+ * entity subscribe (`qd:sub`) and each collection scope (`qd:col:sub`), as
+ * every principal and anonymously, against the rows `reset` seeds, and
+ * compares the matrix with the snapshot file beside the test
+ * (`__access__/<test file>.json`, keys sorted: commit it).
+ *
+ * - A missing file is written. Under CI (`CI=1` or `CI=true`) it fails
+ *   instead: a snapshot that writes itself pins nothing.
+ * - A cell whose outcome changed fails, naming the row (method and
+ *   variant), the principal and both outcomes, and whether the change opens
+ *   or closes access. Accept the changes with `QD_UPDATE_ACCESS_SNAPSHOT=1`,
+ *   which rewrites the file (never under CI).
+ * - Cells added or removed (a new method, principal or exclusion) rewrite
+ *   the file locally, and fail under CI.
+ *
+ * Outcomes are exact: `"ok"`, or the error code. Each principal's `kind` is
+ * recorded too, and a changed kind fails like a cell. A cell whose input
+ * failed the method's input schema is `VALIDATION`, never called, and
+ * listed in the report's `inconclusive`. Leave out methods whose outcome is
+ * not the same on every run with `exclude`. One snapshot per test file.
+ *
+ * @example
+ * const report = await snapshotAccessMatrix(app, { principals, reset, rows });
+ * expect(report.inconclusive).toEqual([]);
+ */
+declare function snapshotAccessMatrix<S extends readonly AnyService[], Fixture, const Name extends string>(app: TestApp<S>, options: AccessSnapshotOptions<PrincipalOfServices<S>, Fixture, Name>): Promise<AccessSnapshotReport>;
+
 /**
  * What one cell expects: `"allow"` (the call succeeds), `"deny"` (it fails
  * with `UNAUTHENTICATED` without a principal and `FORBIDDEN` with one), or
@@ -162,6 +304,8 @@ interface AccessMatrixOptions<C extends AnyContract, P, Name extends string> {
 interface AccessMatrixCell {
     readonly case: string;
     readonly principal: string;
+    /** The principal's `kind`; `undefined` for the anonymous caller and a principal without one. */
+    readonly kind: string | undefined;
     readonly expected: MatrixOutcome;
     /** `"allow"` when the call succeeded, or its error code. */
     readonly actual: "allow" | ErrorCode;
@@ -179,4 +323,4 @@ interface AccessMatrixReport {
  */
 declare function describeAccessMatrix<S extends readonly AnyService[], C extends AnyContract, const Name extends string>(app: TestApp<S>, options: AccessMatrixOptions<C, PrincipalOfServices<S>, Name>): Promise<AccessMatrixReport>;
 
-export { ANONYMOUS, type AccessMatrixCase, type AccessMatrixCell, type AccessMatrixOptions, type AccessMatrixReport, BUDGET_BYTES_TOLERANCE, BUDGET_GROWTH_ENV, type Budget, type BudgetCall, type BudgetOptions, type BudgetResult, type MatrixCell, type MatrixInputFactory, type MatrixOutcome, type RecordedFlush, type RecordingSink, TestApp, budgetFileOf, createRecordingSink, describeAccessMatrix, expectBudget };
+export { ACCESS_SNAPSHOT_ENV, ANONYMOUS, type AccessMatrixCase, type AccessMatrixCell, type AccessMatrixOptions, type AccessMatrixReport, type AccessOutcome, type AccessPrincipals, type AccessRows, type AccessSnapshot, type AccessSnapshotChange, type AccessSnapshotOptions, type AccessSnapshotPrincipal, type AccessSnapshotRef, type AccessSnapshotReport, type AccessSnapshotRow, BUDGET_BYTES_TOLERANCE, BUDGET_GROWTH_ENV, type Budget, type BudgetCall, type BudgetOptions, type BudgetResult, type MatrixCell, type MatrixInputFactory, type MatrixOutcome, type RecordedFlush, type RecordingSink, TestApp, accessSnapshotFileOf, budgetFileOf, createRecordingSink, describeAccessMatrix, expectBudget, snapshotAccessMatrix };