@qawolf/ci-sdk 3.1.0 → 3.3.0

package/dist/lib/sdk/domain/waitForVerdict/awaitRuns.d.ts

@@ -0,0 +1,14 @@
+import type { DeploymentVerdict, MatchedRun, WaitContext } from "./types.js";
+export type RunsFound = {
+    kind: "runs";
+    runs: MatchedRun[];
+};
+type Phase = DeploymentVerdict | RunsFound;
+/**
+ * Polls the deployment's trigger evaluations until they name the runs that
+ * answer for it, or until it is clear nothing will run. Bounded by
+ * `runAppearanceTimeout`: a trigger that never resolves does not hold up the
+ * runs that did start.
+ */
+export declare function awaitRuns(ctx: WaitContext): Promise<Phase>;
+export {};

package/dist/lib/sdk/domain/waitForVerdict/awaitVerdict.d.ts

@@ -0,0 +1,19 @@
+import type { DeploymentVerdict, MatchedRun, VerdictRun, WaitContext } from "./types.js";
+/**
+ * The whole-deployment answer: one failing run fails the deployment, and a
+ * cancellation means QA Wolf reached no verdict rather than that it passed.
+ *
+ * A superseded run has no verdict either: a newer deployment replaced it, and
+ * the wait stops there rather than follow `supersededBy`, because the
+ * replacement may be testing a later commit. Its status is `superseded` even
+ * when a flow found a blocking bug before the run was abandoned, and that bug
+ * is still a bug in this commit, so the blocking bug count fails the
+ * deployment ahead of the status.
+ *
+ * A deployment is expected to resolve to exactly one run; the fold over several
+ * is a guard, so that a violation of that expectation cannot be reported as
+ * passing. When more than one run was superseded, the top-level replacement is
+ * the first one's, and each run carries its own.
+ */
+export declare function aggregateRuns(deploymentId: string, runs: VerdictRun[]): DeploymentVerdict;
+export declare function awaitVerdict(ctx: WaitContext, matched: MatchedRun[]): Promise<DeploymentVerdict>;

package/dist/lib/sdk/domain/waitForVerdict/consts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * If you change these, update the JSDoc on `WaitForVerdictConfig` with them.
+ * The whole-operation budget matches the legacy `pollCiGreenlightStatus`
+ * `pollTimeout`, so moving off that function does not also move the default.
+ */
+export declare const waitForVerdictDefaults: {
+    maxRetries: number;
+    retryInterval: number;
+    runAppearanceTimeout: number;
+    runPollInterval: number;
+    timeout: number;
+    triggerPollInterval: number;
+};

package/dist/lib/sdk/domain/waitForVerdict/failures.d.ts

@@ -0,0 +1,14 @@
+import type { PublicApiCallFailure } from "../../publicApi/callContract.js";
+import type { DeploymentVerdict } from "./types.js";
+/**
+ * How the wait should answer a failed call: retry it until the budget runs
+ * out, or stop on a refusal that retrying cannot change.
+ */
+export type FailureHandling = {
+    exhaustedVerdict: DeploymentVerdict;
+    kind: "retry";
+} | {
+    kind: "stop";
+    verdict: DeploymentVerdict;
+};
+export declare function handleCallFailure(failure: PublicApiCallFailure, deploymentId: string): FailureHandling;

package/dist/lib/sdk/domain/waitForVerdict/index.d.ts

@@ -0,0 +1,12 @@
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+import type { DeploymentVerdict, WaitForVerdictParams } from "./types.js";
+/**
+ * Blocks until QA Wolf can say whether a deployment's tests passed.
+ *
+ * It takes only the deployment id the report gave back: resolving that to the
+ * runs its triggers created, and those runs to a status, stays inside. Nothing
+ * throws — a refusal, a dead network, a cancellation and an exhausted budget
+ * are all arms of the returned verdict.
+ */
+export declare function waitForVerdict(deps: SdkDependencies, apiConfig: ApiConfig, { deploymentId, maxRetries, onProgress, retryInterval, runAppearanceTimeout, runPollInterval, signal, timeout, triggerPollInterval, }: WaitForVerdictParams): Promise<DeploymentVerdict>;

package/dist/lib/sdk/domain/waitForVerdict/logVerdict.d.ts

@@ -0,0 +1,3 @@
+import type { LogDriver } from "@qawolf/ci-utils";
+import type { DeploymentVerdict } from "./types.js";
+export declare function logVerdict(log: LogDriver, verdict: DeploymentVerdict): void;

package/dist/lib/sdk/domain/waitForVerdict/poll.d.ts

@@ -0,0 +1,20 @@
+import type { PublicApiCallResult } from "../../publicApi/callContract.js";
+import type { DeploymentVerdict, WaitContext } from "./types.js";
+export type PollStep<Result> = {
+    intervalMs: number;
+    kind: "continue";
+} | {
+    kind: "done";
+    result: Result;
+};
+/**
+ * Repeats one public API call until it answers something terminal, the caller
+ * hangs up, or the deadline passes. Nothing here throws: a refusal, a dead
+ * network and an exhausted budget are all verdicts the caller receives.
+ */
+export declare function pollUntil<Data, Result>(ctx: WaitContext, { deadlineAt, onData, onDeadline, request, }: {
+    deadlineAt: number;
+    onData: (data: Data) => Promise<PollStep<Result>>;
+    onDeadline: () => DeploymentVerdict | Result;
+    request: () => Promise<PublicApiCallResult<Data>>;
+}): Promise<DeploymentVerdict | Result>;

package/dist/lib/sdk/domain/waitForVerdict/progress.d.ts

@@ -0,0 +1,7 @@
+import type { VerdictStage, WaitContext } from "./types.js";
+/**
+ * Reports a stage once, when it differs from the one before it. The log line
+ * is the identity of a stage, so a run that keeps executing does not repeat
+ * itself in the build log.
+ */
+export declare function reportStage(ctx: WaitContext, previousDescription: string | undefined, stage: VerdictStage): Promise<string>;

package/dist/lib/sdk/domain/waitForVerdict/readEvaluations.d.ts

@@ -0,0 +1,20 @@
+import type { PublicApiOutput, publicContractsV1 } from "@qawolf/api-contracts";
+import type { MatchedRun, NotTestedReason, TriggerNote } from "./types.js";
+export type TriggerEvaluations = PublicApiOutput<typeof publicContractsV1.deployment.listTriggerEvaluations>;
+export type EvaluationReading = {
+    kind: "not-evaluated";
+}
+/** Some trigger is still creating a run; `runs` are the ones already known. */
+ | {
+    kind: "awaiting-run";
+    matchedTriggerCount: number;
+    runs: MatchedRun[];
+} | {
+    kind: "runs";
+    runs: MatchedRun[];
+} | {
+    kind: "not-tested";
+    reason: NotTestedReason;
+    triggers: TriggerNote[];
+};
+export declare function readEvaluations(evaluations: TriggerEvaluations): EvaluationReading;

package/dist/lib/sdk/domain/waitForVerdict/testHarness.d.ts

@@ -0,0 +1,53 @@
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+export type Reply = {
+    body: unknown;
+    status: number;
+} | {
+    kind: "network-error";
+};
+export declare function ok(payload: unknown): Reply;
+export declare function httpError(status: number, message: string): Reply;
+export declare const networkError: Reply;
+export declare function evaluated(evaluations: unknown[]): Reply;
+export declare const notEvaluated: Reply;
+export declare function matchedTrigger(run: unknown, triggerName?: string): unknown;
+export declare function unmatchedTrigger(reason: string, triggerName?: string): {
+    triggerName: string;
+    verdict: {
+        conditionSets: {
+            conditions: {
+                kind: string;
+                outcome: string;
+                reason: string;
+            }[];
+            outcome: string;
+        }[];
+        outcome: string;
+    };
+};
+export declare function runPayload({ blockingBugCount, runId, status, }: {
+    blockingBugCount?: number;
+    runId?: string;
+    status: string;
+}): Record<string, unknown>;
+/**
+ * A fetch that answers each contract from its own queue, holding on the last
+ * reply once a queue runs out, plus a clock that only moves when the SDK
+ * sleeps. Together they let a test walk a two-hour poll in milliseconds and
+ * count exactly how many times the SDK asked. `runs` is one queue shared by
+ * every run, or a queue per requested run id when a test needs to tell two
+ * runs apart.
+ */
+export declare function makeHarness({ evaluations, runs, }: {
+    evaluations?: Reply[];
+    runs?: Record<string, Reply[]> | Reply[];
+}): {
+    apiConfig: ApiConfig;
+    calls: {
+        evaluations: number;
+        runs: number;
+    };
+    deps: SdkDependencies;
+    fetch: import("jest-mock").Mock<(url: unknown, init: unknown) => Promise<Response>>;
+};

package/dist/lib/sdk/domain/waitForVerdict/types.d.ts

@@ -0,0 +1,48 @@
+import type { DeploymentVerdict, NotTestedReason, TriggerNote, VerdictRun, VerdictStage } from "@qawolf/api-contracts";
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+export type { DeploymentVerdict, NotTestedReason, TriggerNote, VerdictRun, VerdictStage, };
+export type WaitForVerdictConfig = {
+    /** Network and server-error retries before giving up. @default 10 */
+    maxRetries: number;
+    /** Fired on every stage change, for CI logs. */
+    onProgress: (stage: VerdictStage) => unknown | Promise<unknown>;
+    /** Between retries of a failed call. @default 10s */
+    retryInterval: number;
+    /**
+     * Give up if no trigger has produced a run by then. Runs that did appear are
+     * still waited on. @default 5min
+     */
+    runAppearanceTimeout: number;
+    /** Between polls while a run executes. @default 30s */
+    runPollInterval: number;
+    /** Cancels the wait; yields `outcome: "canceled-by-caller"`. */
+    signal: AbortSignal;
+    /**
+     * Whole-operation budget. Set it below the CI job's own ceiling, so the wait
+     * ends with a run URL and a stage instead of the job being killed.
+     * @default 2h
+     */
+    timeout: number;
+    /** Between polls while a trigger is still producing a run. @default 3s */
+    triggerPollInterval: number;
+};
+export type WaitForVerdictParams = {
+    deploymentId: string;
+} & Partial<WaitForVerdictConfig>;
+export type ResolvedWaitConfig = Omit<WaitForVerdictConfig, "onProgress" | "signal"> & {
+    onProgress: ((stage: VerdictStage) => unknown | Promise<unknown>) | undefined;
+    signal: AbortSignal | undefined;
+};
+export type WaitContext = {
+    apiConfig: ApiConfig;
+    config: ResolvedWaitConfig;
+    deploymentId: string;
+    deps: SdkDependencies;
+    startedAt: number;
+};
+/** A run one trigger created, before its status is known. */
+export type MatchedRun = {
+    runId: string;
+    triggerName: string;
+};

package/dist/lib/sdk/index.d.ts

@@ -3,7 +3,7 @@ export declare function makeQaWolfSdk({ apiKey, serviceBase, userAgent, }: {
     apiKey: string;
     serviceBase?: string;
     userAgent?: string;
-}, { fetch, log, }?: Partial<SdkDependencies>): {
+}, { clock, fetch, log, }?: Partial<SdkDependencies>): {
     /**
      * @deprecated Reports through the legacy `deploy_success` webhook, which
      * triggers do not see. Use `deployment.reportStatus` instead.
@@ -34,6 +34,137 @@ export declare function makeQaWolfSdk({ apiKey, serviceBase, userAgent, }: {
             } | undefined;
             service?: string | undefined;
         }) => Promise<import("./domain/reportDeployment/types.js").ReportDeploymentResult>;
+        waitForVerdict: (args_0: import("./domain/waitForVerdict/types.js").WaitForVerdictParams) => Promise<{
+            deploymentId: string;
+            outcome: "passed";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "superseded" | "queued" | "running";
+                triggerName: string;
+                supersededBy?: {
+                    runId: string;
+                    url: string;
+                } | undefined;
+            }[];
+        } | {
+            blockingBugCount: number;
+            deploymentId: string;
+            outcome: "failed";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "superseded" | "queued" | "running";
+                triggerName: string;
+                supersededBy?: {
+                    runId: string;
+                    url: string;
+                } | undefined;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "not-tested";
+            reason: "no-trigger-matched" | "no-run-created";
+            triggers: {
+                message: string;
+                triggerName: string;
+                reason?: "skipped" | "billing-prevented" | "branch-still-syncing" | "deployment-no-longer-live" | "duplicate-run" | "environment-not-linked-to-branch" | "environment-not-ready" | "environment-terminated" | "internal-error" | "low-risk-change" | "no-flows-to-run" | "no-matching-trigger" | "no-pull-request" | "no-relevant-flows" | "rate-limited" | "run-not-created" | "test-configuration-error" | "trigger-not-found" | "workspace-inactive" | "workspace-not-ready" | undefined;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "run-canceled";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "superseded" | "queued" | "running";
+                triggerName: string;
+                supersededBy?: {
+                    runId: string;
+                    url: string;
+                } | undefined;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "superseded";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "superseded" | "queued" | "running";
+                triggerName: string;
+                supersededBy?: {
+                    runId: string;
+                    url: string;
+                } | undefined;
+            }[];
+            supersededBy: {
+                runId: string;
+                url: string;
+            };
+        } | {
+            deploymentId: string;
+            elapsedMs: number;
+            lastStage: {
+                stage: "waiting-for-evaluation";
+            } | {
+                matchedTriggerCount: number;
+                stage: "waiting-for-run";
+            } | {
+                runs: {
+                    blockingBugCount: number;
+                    runId: string;
+                    runUrl: string;
+                    status: "canceled" | "failed" | "passed" | "superseded" | "queued" | "running";
+                    triggerName: string;
+                    supersededBy?: {
+                        runId: string;
+                        url: string;
+                    } | undefined;
+                }[];
+                stage: "waiting-for-verdict";
+            };
+            outcome: "timed-out";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "superseded" | "queued" | "running";
+                triggerName: string;
+                supersededBy?: {
+                    runId: string;
+                    url: string;
+                } | undefined;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "canceled-by-caller";
+        } | {
+            deploymentId: string;
+            outcome: "unauthorized";
+            message?: string | undefined;
+        } | {
+            deploymentId: string;
+            outcome: "not-found";
+            message?: string | undefined;
+        } | {
+            deploymentId: string;
+            httpStatus: number;
+            outcome: "server-error";
+        } | {
+            deploymentId: string;
+            httpStatus: number;
+            outcome: "unexpected-status";
+            message?: string | undefined;
+        } | {
+            deploymentId: string;
+            outcome: "network-error";
+        } | {
+            deploymentId: string;
+            outcome: "invalid-response-body";
+        }>;
     };
     generateSignedUrlForRunInputsExecutablesStorage: (config: import("./domain/generateSignedUrls/types.js").GenerateSignedUrlConfig) => Promise<import("./domain/generateSignedUrls/types.js").GenerateSignedUrlStatus>;
     generateSignedUrlForTempTeamStorage: (config: import("./domain/generateSignedUrls/types.js").GenerateSignedUrlConfig) => Promise<{
@@ -60,3 +191,4 @@ export type * from "./domain/generateSignedUrls/types.js";
 export type * from "./domain/notifyTerminatedEphemeralEnvironment/types.js";
 export type * from "./domain/pollCiGreenlight/types.js";
 export type * from "./domain/reportDeployment/types.js";
+export type * from "./domain/waitForVerdict/types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/ci-sdk",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "private": false,
   "description": "A simple SDK for interacting with QAWolf in CI scripts.",
   "keywords": [],
@@ -29,7 +29,7 @@
     "tsc:check": "tsc --noEmit"
   },
   "dependencies": {
-    "@qawolf/api-contracts": ">=0.68.0",
+    "@qawolf/api-contracts": ">=0.73.0",
     "@qawolf/ci-utils": "^2.0.0",
     "@sinonjs/fake-timers": "^10.3.0",
     "tslib": "^2.6.2",