@qawolf/ci-sdk 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,23 @@
+# v0.11.0
+
+- Support `reproducedBugs` field from CI-greenlight API.
+
+> :warning: These are the last breaking changes brought to the 0.x major version.
+> These are being introduced while the SDK hasn't been advertised to the public yet.
+> Future changes will follow the SemVer versioning scheme.
+
+BREAKING CHANGES:
+
+- `pollCiGreenlightStatus` and `attemptNotifyDeploy` now return a "result" object
+  with an `outcome` field that can be either `"success"`, `"failed"` or `"aborted"`,
+  instead of exiting the process with a non-zero code. This will provide more
+  flexibility to the user to decide how to handle the outcome.
+
 # v0.10.3
 
-_No visible changes_
+BREAKING CHANGES:
+
+- Renamed `attemptDeploy` to `attemptNotifyDeploy`.
 
 # v0.10.2
 

package/README.md

@@ -8,6 +8,13 @@
 This package provides a TypeScript (CSM and ESM compatible) SDK
 to interact with the QAWolf Customer-facing API.
 
+It exposes two functions associated with the two central endpoints, showcased in
+the examples below.
+
+Note that these functions do not throw. They yield a result object that
+contains the outcome of the operation. This outcome should be scrutinized
+to determine the status of your CI/CD step/job/action.
+
 ## Example: Trigger Run on Deployment
 
 ```ts
@@ -31,7 +38,12 @@ const { attemptNotifyDeploy } = makeQaWolfSdk({
 });
 
 (async () => {
-  const runId = await attemptNotifyDeploy(deployConfig);
+  const result = await attemptNotifyDeploy(deployConfig);
+  if (result.outcome !== "success") {
+    // Fail the job.
+    process.exit(1);
+  }
+  const runId = result.runId;
   // Store the runId as an output of the job to be used in a CI-greenlight job.
   // This will depend on the CI platform you are using.
 })();
@@ -48,7 +60,7 @@ const { pollCiGreenlightStatus } = makeQaWolfSdk({
 
 (async () => {
   // Retrieve runId from the previous job.
-  await pollCiGreenlightStatus({
+  const { outcome } = await pollCiGreenlightStatus({
     runId,
     // Optional: Callback to be called when the run stage changes.
     // See https://qawolf.notion.site/dc42843313c246c8bf2a3a314ceb2c61 for
@@ -57,6 +69,14 @@ const { pollCiGreenlightStatus } = makeQaWolfSdk({
       console.log(current, previous);
     },
   });
+  if (outcome !== "success") {
+    // Fail the job.
+    // This will depend on the CI platform you are using.
+    // You can also distinguish between "failed" and "aborted" outcomes.
+    // Only "failed" outcome indicates bugs were found.
+    process.exit(1);
+  }
+  // Continue CI.
 })();
 ```
 

package/dist/cjs/lib/sdk/domain/attempt-deploy.js

@@ -4,16 +4,18 @@ exports.attemptNotifyDeploy = void 0;
 const deploy_js_1 = require("../../api/deploy.js");
 const utils_js_1 = require("../../utils.js");
 async function attemptNotifyDeploy(deps, apiConfig, config) {
-    const { job, log } = deps;
+    const { log } = deps;
     const responseState = await (0, deploy_js_1.postDeploySuccess)(apiConfig, config, deps);
     if (!responseState.success) {
         if (responseState.failureReason === "no-matched-trigger") {
-            log.error(`🚫 No trigger matched the request, aborting. Please contact support.`);
+            log.error(`🚫 No trigger matched the request. Please contact support.`);
+            return { outcome: "failed" };
         }
         else if (responseState.failureReason === "run-could-not-be-created") {
-            log.error(`🚫 Run could not be created, aborting. Reason: "${responseState.details}". Please contact support.`);
+            log.error(`🚫 Run could not be created. Reason: "${responseState.details}". Please contact support.`);
+            return { outcome: "failed" };
         }
-        else if (responseState.failureReason === "network-error")
+        if (responseState.failureReason === "network-error")
             log.error(`🚫 Network error from deploy_success, aborting.`);
         else if (responseState.failureReason === "server-error")
             log.error(`🚫 Server error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
@@ -29,9 +31,12 @@ async function attemptNotifyDeploy(deps, apiConfig, config) {
         else {
             (0, utils_js_1.assertType)(responseState);
         }
-        return job.abort();
+        return { outcome: "aborted" };
     }
     log.info(`✅ Run created with ID: ${responseState.runId}`);
-    return responseState.runId;
+    return {
+        outcome: "success",
+        runId: responseState.runId,
+    };
 }
 exports.attemptNotifyDeploy = attemptNotifyDeploy;

package/dist/cjs/lib/sdk/domain/poll-ci-greenlight.js

@@ -11,7 +11,7 @@ const safeDefaults = {
 };
 async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
     let retries = 0;
-    const { job, log } = deps;
+    const { log } = deps;
     const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
     let currentStatus = undefined;
     while (true) {
@@ -20,25 +20,25 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
         }, deps);
         if (!responseState.ok && !responseState.canRetry) {
             log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
-            return job.abort();
+            return { outcome: "aborted" };
         }
         if (!responseState.ok) {
             // This is a non-OK retryable status.
             retries += 1;
             if (retries > maxRetries) {
-                log.error(`🚫 Unrecoverable error ${responseState.httpStatus
-                    ? `(status ${responseState.httpStatus})`
+                log.error(`🚫 Unrecoverable error${responseState.httpStatus
+                    ? ` (status ${responseState.httpStatus})`
                     : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-                return job.abort();
+                return { outcome: "aborted" };
             }
             const { errorType, httpStatus } = responseState;
-            const retryLabel = `${httpStatus ? `(status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
+            const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
             if (errorType === "network")
-                log.warn(`❌ Network error ${retryLabel}`);
+                log.warn(`❌ Network error${retryLabel}`);
             else if (errorType === "not-found")
-                log.info(`⏳ Run not found ${retryLabel}`);
+                log.info(`⏳ Run not found${retryLabel}`);
             else if (errorType === "server")
-                log.warn(`❌ Server error ${retryLabel}`);
+                log.warn(`❌ Server error${retryLabel}`);
             await (0, utils_js_1.sleep)(retryInterval);
             continue;
         }
@@ -74,10 +74,10 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
                 ? `\nNON BLOCKING BUGS:${nonBlockingBugList}`
                 : ""}`;
             if (greenlight) {
-                log.info(`✅ Run passed and no blocking bugs found ${nonBlockingBugsCount > 0
+                log.info(`✅ Run passed and no blocking bugs found${nonBlockingBugsCount > 0
                     ? ` and ${nonBlockingBugsCount} non-blocking bug${(0, utils_js_1.pluralize)(nonBlockingBugsCount)} found`
                     : ""}.\n${urlInfo}`);
-                return;
+                return { outcome: "success", greenlightStatus };
             }
             else {
                 log.warn(`❌ Run failed and ${blockingBugsCount} blocking bug${(0, utils_js_1.pluralize)(blockingBugsCount)} found${nonBlockingBugsCount
@@ -85,7 +85,7 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
                     : ""}.\nSee ${relevantRunWithBugsUrl}\n` +
                     "You may review the priority of certain bugs to mark these non-blocking and retry the job.\n" +
                     bugsListInText);
-                return job.fail();
+                return { outcome: "failed", greenlightStatus };
             }
         }
         if (runStage === "initializing") {
@@ -98,7 +98,7 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
         }
         else if (runStage === "canceled") {
             log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
-            return job.abort();
+            return { outcome: "aborted" };
         }
         else
             throw new Error(`Unexpected run stage: ${runStage}`);

package/dist/cjs/lib/sdk/index.js

@@ -2,11 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeQaWolfSdk = void 0;
 const attempt_deploy_js_1 = require("./domain/attempt-deploy.js");
-const default_js_1 = require("./job/default.js");
-const default_js_2 = require("./log/default.js");
+const default_js_1 = require("./log/default.js");
 const poll_ci_greenlight_js_1 = require("./domain/poll-ci-greenlight.js");
-function makeQaWolfSdk({ apiKey, serviceBase = "https://app.qawolf.com/", }, { job = default_js_1.defaultJobDriver, log = default_js_2.defaultLogDriver, fetch = globalThis.fetch, } = {}) {
-    const deps = { job, log, fetch };
+function makeQaWolfSdk({ apiKey, serviceBase = "https://app.qawolf.com/", }, { log = default_js_1.defaultLogDriver, fetch = globalThis.fetch, } = {}) {
+    const deps = { log, fetch };
     const apiConfig = { apiKey, serviceBase };
     return {
         attemptNotifyDeploy: attempt_deploy_js_1.attemptNotifyDeploy.bind(null, deps, apiConfig),

package/dist/esm/lib/sdk/domain/attempt-deploy.js

@@ -1,16 +1,18 @@
 import { postDeploySuccess } from "../../api/deploy.js";
 import { assertType } from "../../utils.js";
 export async function attemptNotifyDeploy(deps, apiConfig, config) {
-    const { job, log } = deps;
+    const { log } = deps;
     const responseState = await postDeploySuccess(apiConfig, config, deps);
     if (!responseState.success) {
         if (responseState.failureReason === "no-matched-trigger") {
-            log.error(`🚫 No trigger matched the request, aborting. Please contact support.`);
+            log.error(`🚫 No trigger matched the request. Please contact support.`);
+            return { outcome: "failed" };
         }
         else if (responseState.failureReason === "run-could-not-be-created") {
-            log.error(`🚫 Run could not be created, aborting. Reason: "${responseState.details}". Please contact support.`);
+            log.error(`🚫 Run could not be created. Reason: "${responseState.details}". Please contact support.`);
+            return { outcome: "failed" };
         }
-        else if (responseState.failureReason === "network-error")
+        if (responseState.failureReason === "network-error")
             log.error(`🚫 Network error from deploy_success, aborting.`);
         else if (responseState.failureReason === "server-error")
             log.error(`🚫 Server error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
@@ -26,8 +28,11 @@ export async function attemptNotifyDeploy(deps, apiConfig, config) {
         else {
             assertType(responseState);
         }
-        return job.abort();
+        return { outcome: "aborted" };
     }
     log.info(`✅ Run created with ID: ${responseState.runId}`);
-    return responseState.runId;
+    return {
+        outcome: "success",
+        runId: responseState.runId,
+    };
 }

package/dist/esm/lib/sdk/domain/poll-ci-greenlight.js

@@ -8,7 +8,7 @@ const safeDefaults = {
 };
 export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
     let retries = 0;
-    const { job, log } = deps;
+    const { log } = deps;
     const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
     let currentStatus = undefined;
     while (true) {
@@ -17,25 +17,25 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
         }, deps);
         if (!responseState.ok && !responseState.canRetry) {
             log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
-            return job.abort();
+            return { outcome: "aborted" };
         }
         if (!responseState.ok) {
             // This is a non-OK retryable status.
             retries += 1;
             if (retries > maxRetries) {
-                log.error(`🚫 Unrecoverable error ${responseState.httpStatus
-                    ? `(status ${responseState.httpStatus})`
+                log.error(`🚫 Unrecoverable error${responseState.httpStatus
+                    ? ` (status ${responseState.httpStatus})`
                     : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-                return job.abort();
+                return { outcome: "aborted" };
             }
             const { errorType, httpStatus } = responseState;
-            const retryLabel = `${httpStatus ? `(status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
+            const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
             if (errorType === "network")
-                log.warn(`❌ Network error ${retryLabel}`);
+                log.warn(`❌ Network error${retryLabel}`);
             else if (errorType === "not-found")
-                log.info(`⏳ Run not found ${retryLabel}`);
+                log.info(`⏳ Run not found${retryLabel}`);
             else if (errorType === "server")
-                log.warn(`❌ Server error ${retryLabel}`);
+                log.warn(`❌ Server error${retryLabel}`);
             await sleep(retryInterval);
             continue;
         }
@@ -71,10 +71,10 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
                 ? `\nNON BLOCKING BUGS:${nonBlockingBugList}`
                 : ""}`;
             if (greenlight) {
-                log.info(`✅ Run passed and no blocking bugs found ${nonBlockingBugsCount > 0
+                log.info(`✅ Run passed and no blocking bugs found${nonBlockingBugsCount > 0
                     ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)} found`
                     : ""}.\n${urlInfo}`);
-                return;
+                return { outcome: "success", greenlightStatus };
             }
             else {
                 log.warn(`❌ Run failed and ${blockingBugsCount} blocking bug${pluralize(blockingBugsCount)} found${nonBlockingBugsCount
@@ -82,7 +82,7 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
                     : ""}.\nSee ${relevantRunWithBugsUrl}\n` +
                     "You may review the priority of certain bugs to mark these non-blocking and retry the job.\n" +
                     bugsListInText);
-                return job.fail();
+                return { outcome: "failed", greenlightStatus };
             }
         }
         if (runStage === "initializing") {
@@ -95,7 +95,7 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
         }
         else if (runStage === "canceled") {
             log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
-            return job.abort();
+            return { outcome: "aborted" };
         }
         else
             throw new Error(`Unexpected run stage: ${runStage}`);

package/dist/esm/lib/sdk/index.js

@@ -1,9 +1,8 @@
 import { attemptNotifyDeploy } from "./domain/attempt-deploy.js";
-import { defaultJobDriver } from "./job/default.js";
 import { defaultLogDriver } from "./log/default.js";
 import { pollCiGreenlightStatus } from "./domain/poll-ci-greenlight.js";
-export function makeQaWolfSdk({ apiKey, serviceBase = "https://app.qawolf.com/", }, { job = defaultJobDriver, log = defaultLogDriver, fetch = globalThis.fetch, } = {}) {
-    const deps = { job, log, fetch };
+export function makeQaWolfSdk({ apiKey, serviceBase = "https://app.qawolf.com/", }, { log = defaultLogDriver, fetch = globalThis.fetch, } = {}) {
+    const deps = { log, fetch };
     const apiConfig = { apiKey, serviceBase };
     return {
         attemptNotifyDeploy: attemptNotifyDeploy.bind(null, deps, apiConfig),

package/dist/types/lib/api/ci-greenlight.d.ts

@@ -1,5 +1,57 @@
 import { ApiConfig } from "../api-types.js";
 import { SdkDependencies } from "../sdk/dependencies.js";
+export type CiGreenlightBugDetails = {
+    /**
+     * The URL of this BR in the QAWolf application.
+     */
+    applicationUrl: string;
+    /**
+     * If this bug report is linked to an external issue, it will
+     * show up here.
+     */
+    externalIssue: {
+        /**
+         * The URL of the external issue in the external platform
+         * application.
+         */
+        applicationUrl: string;
+        /**
+         * The ID of this issue in the external platform.
+         */
+        externalIssueId: string;
+        /**
+         * Lowercase platform name (e.g. "jira").
+         */
+        platform: string;
+    } | undefined;
+    /**
+     * True if the bug is blocking.
+     */
+    isBlocking: boolean;
+    /**
+     * True if the bug has been found in this run.
+     */
+    isNew: boolean;
+    /**
+     * The name of this bug.
+     */
+    name: string;
+    /**
+     * The bug number.
+     */
+    number: number;
+    /**
+     * The priority of this bug.
+     */
+    priority: "medium" | "unprioritized" | "low" | "high" | "urgent";
+};
+export type CiGreenlightCompletedSuiteDetails = {
+    blockingBugsCount: number;
+    blockingBugUrls: string[];
+    nonBlockingBugsCount: number;
+    nonBlockingBugUrls: string[];
+    reproducedBugs: CiGreenlightBugDetails[];
+};
 export type CiGreenlightStatusBase = {
     relevantRunId: string;
     relevantRunUrl: string;
@@ -21,6 +73,7 @@ export type CiGreenlightStatus = CiGreenlightStatusBase & ({
     nonBlockingBugsCount: number;
     nonBlockingBugUrls: string[];
     runStage: "completed";
+    reproducedBugs: CiGreenlightBugDetails[];
 } | {
     greenlight: false;
     runStage: "initializing" | "underReview" | "canceled";

package/dist/types/lib/sdk/dependencies.d.ts

@@ -1,20 +1,3 @@
-export interface JobDriver {
-    /**
-     * Called only when job completed and failed.
-     * **This method must exit the process or throw**.
-     */
-    fail(): Promise<never>;
-    /**
-     * Called anywhere the job cannot continue and has to
-     * be aborted. **This method must exit the process or throw**.
-     *
-     * The main difference with "fail" is its semantics. For
-     * jobs performing tests, "fail" is called when the job
-     * completed and the tests yield a negative result.
-     * "abort" is called when the job could not complete.
-     */
-    abort(): Promise<never>;
-}
 export interface LogDriver {
     info(...messages: unknown[]): void;
     warn(...messages: unknown[]): void;
@@ -22,7 +5,6 @@ export interface LogDriver {
 }
 export type FetchDriver = typeof fetch;
 export type SdkDependencies = {
-    job: JobDriver;
     log: LogDriver;
     fetch: FetchDriver;
 };

package/dist/types/lib/sdk/domain/attempt-deploy.d.ts

@@ -1,4 +1,21 @@
 import { DeployConfig } from "../../api/deploy.js";
 import { SdkDependencies } from "../dependencies.js";
 import { ApiConfig } from "../../api-types.js";
-export declare function attemptNotifyDeploy(deps: SdkDependencies, apiConfig: ApiConfig, config: Partial<DeployConfig>): Promise<string>;
+export type NotifyDeployStatus = {
+    /**
+     * A run was successfully created.
+     */
+    outcome: "success";
+    runId: string;
+} | {
+    /**
+     * A run could not be created.
+     */
+    outcome: "failed";
+} | {
+    /**
+     * An unrecoverable error occurred.
+     */
+    outcome: "aborted";
+};
+export declare function attemptNotifyDeploy(deps: SdkDependencies, apiConfig: ApiConfig, config: Partial<DeployConfig>): Promise<NotifyDeployStatus>;

package/dist/types/lib/sdk/domain/poll-ci-greenlight.d.ts

@@ -7,6 +7,28 @@ export type PollConfig = {
     runInProgressInterval: number;
     runUnderReviewInterval: number;
 };
+export type PollCiGreenlightStatus = {
+    /**
+     * No blocking bugs were found in the run.
+     */
+    outcome: "success";
+    greenlightStatus: Extract<CiGreenlightStatus, {
+        runStage: "completed";
+    }>;
+} | {
+    /**
+     * Blocking bugs were found in the run.
+     */
+    outcome: "failed";
+    greenlightStatus: Extract<CiGreenlightStatus, {
+        runStage: "completed";
+    }>;
+} | {
+    /**
+     * The run was aborted due to an unrecoverable error.
+     */
+    outcome: "aborted";
+};
 export type PollCiGreenlightParams = {
     runId: string;
     /**
@@ -14,4 +36,4 @@ export type PollCiGreenlightParams = {
      */
     onRunStageChanged?: (current: CiGreenlightStatus, previous: CiGreenlightStatus | undefined) => unknown | Promise<unknown>;
 } & Partial<PollConfig>;
-export declare function pollCiGreenlightStatus(deps: SdkDependencies, apiConfig: ApiConfig, { runId, onRunStageChanged: onRunStageChanged, ...pollConfig }: PollCiGreenlightParams): Promise<undefined>;
+export declare function pollCiGreenlightStatus(deps: SdkDependencies, apiConfig: ApiConfig, { runId, onRunStageChanged: onRunStageChanged, ...pollConfig }: PollCiGreenlightParams): Promise<PollCiGreenlightStatus>;

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

@@ -2,7 +2,7 @@ import { SdkDependencies } from "./dependencies.js";
 export declare function makeQaWolfSdk({ apiKey, serviceBase, }: {
     apiKey: string;
     serviceBase?: string;
-}, { job, log, fetch, }?: Partial<SdkDependencies>): {
-    attemptNotifyDeploy: (config: Partial<import("../api/deploy.js").DeployConfig>) => Promise<string>;
-    pollCiGreenlightStatus: (args_0: import("./domain/poll-ci-greenlight.js").PollCiGreenlightParams) => Promise<undefined>;
+}, { log, fetch, }?: Partial<SdkDependencies>): {
+    attemptNotifyDeploy: (config: Partial<import("../api/deploy.js").DeployConfig>) => Promise<import("./domain/attempt-deploy.js").NotifyDeployStatus>;
+    pollCiGreenlightStatus: (args_0: import("./domain/poll-ci-greenlight.js").PollCiGreenlightParams) => Promise<import("./domain/poll-ci-greenlight.js").PollCiGreenlightStatus>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/ci-sdk",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "A simple SDK for interacting with QAWolf in CI scripts.",
   "type": "module",
   "private": false,

package/dist/cjs/lib/sdk/job/default.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultJobDriver = void 0;
-exports.defaultJobDriver = {
-    fail() {
-        process.exit(1);
-    },
-    abort() {
-        process.exit(1);
-    },
-};

package/dist/esm/lib/sdk/job/default.js

@@ -1,8 +0,0 @@
-export const defaultJobDriver = {
-    fail() {
-        process.exit(1);
-    },
-    abort() {
-        process.exit(1);
-    },
-};

package/dist/types/lib/sdk/job/default.d.ts

@@ -1,2 +0,0 @@
-import { type JobDriver } from "../dependencies.js";
-export declare const defaultJobDriver: JobDriver;