@datadisco/qa 0.2.0 → 0.3.0

package/README.md

@@ -38,17 +38,60 @@ to the hosted app and is overridable with `--api-url` / `DATADISCO_API_URL`.
 export DATADISCO_API_TOKEN=ddqa_xxx
 ```
 
+## Works in any CI
+
+`report-preview` and `wait` auto-detect the repository, PR number, and head
+SHA from whatever CI they're running in — GitHub Actions gets full support out
+of the box, and every other CI (or a bare git checkout) still works with zero
+flags in the common case:
+
+```sh
+DATADISCO_API_TOKEN=ddqa_xxx npx @datadisco/qa report-preview --url https://pr-482.preview.acme.dev
+```
+
+Each value is resolved through its own chain of fallbacks, in order, stopping
+at the first one that resolves:
+
+| Value      | Resolution order                                                                                                                         |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Repository | `--repo` → `$GITHUB_REPOSITORY` → the git checkout's github.com `origin` remote                                                          |
+| Head SHA   | `--sha` → the GitHub Actions `pull_request` event payload → `$GITHUB_SHA` → the git checkout's `HEAD`                                    |
+| PR number  | `--pr` → GitHub Actions (`GITHUB_REF` / event payload) → CircleCI, Jenkins, Buildkite, Travis CI, or Drone's PR env var → _(unresolved)_ |
+
+`--repo`, `--pr`, and `--sha` always override auto-detection when passed.
+
+Unlike the repository and head SHA, the PR number is allowed to stay
+unresolved: `report-preview` will still report the preview URL with just the
+repo + head SHA, and the DataDisco server resolves the PR from the commit
+itself. `wait` needs _either_ a PR number or a head SHA to poll by — pass
+`--sha` explicitly if neither auto-detects (e.g. a CI DataDisco doesn't
+recognize yet).
+
+| CI                | Repo                | Head SHA                              | PR number                                                         |
+| ----------------- | ------------------- | ------------------------------------- | ----------------------------------------------------------------- |
+| GitHub Actions    | `GITHUB_REPOSITORY` | `pull_request` payload / `GITHUB_SHA` | `GITHUB_REF` / `pull_request` payload                             |
+| CircleCI          | git origin remote   | git `HEAD`                            | `CIRCLE_PULL_REQUEST` / `CIRCLE_PR_NUMBER`                        |
+| Jenkins           | git origin remote   | git `HEAD`                            | `CHANGE_ID`                                                       |
+| Buildkite         | git origin remote   | git `HEAD`                            | `BUILDKITE_PULL_REQUEST`                                          |
+| Travis CI         | git origin remote   | git `HEAD`                            | `TRAVIS_PULL_REQUEST`                                             |
+| Drone             | git origin remote   | git `HEAD`                            | `DRONE_PULL_REQUEST`                                              |
+| Bare git checkout | git origin remote   | git `HEAD`                            | not auto-detected — pass `--pr` or rely on server-side resolution |
+
+The git `origin` remote fallback only recognizes github.com remotes (SSH or
+HTTPS); for anything else, pass `--repo` explicitly.
+
 ## Commands
 
 ### `report-preview`
 
 Report the deployed preview URL for a PR head SHA so its pending QA run leaves
-`PENDING_PREVIEW` and starts. In GitHub Actions, `--repo`, `--pr`, and `--sha`
-are auto-detected from the `pull_request` event.
+`PENDING_PREVIEW` and starts. `--repo`, `--pr`, and `--sha` are auto-detected —
+see [Works in any CI](#works-in-any-ci) — and the PR number is optional: if it
+can't be auto-detected, the server resolves it from the head SHA itself.
 
 ```sh
 datadisco-qa report-preview --url https://pr-482.preview.acme.dev
-# explicit outside Actions:
+# explicit, e.g. outside any auto-detected CI:
 datadisco-qa report-preview \
   --url https://pr-482.preview.acme.dev \
   --repo acme/site --pr 482 --sha "$GIT_SHA"
@@ -73,10 +116,14 @@ message, instead of burning the retry window.
 ### `wait`
 
 Block until the PR's QA run reaches a verdict, printing each phase transition.
-Polls every 15s; `--timeout` (minutes, default 30) caps the wait.
+Polls every 15s; `--timeout` (minutes, default 30) caps the wait. `--repo` and
+`--pr` are auto-detected the same way as `report-preview`; if the PR number
+isn't detectable, pass `--sha` to poll by head SHA instead.
 
 ```sh
 datadisco-qa wait --pr 482
+# or, when the PR number isn't auto-detected:
+datadisco-qa wait --sha "$GIT_SHA"
 ```
 
 **Exit codes** (so pipelines can branch on the outcome):

package/dist/cli.js

@@ -35,60 +35,137 @@ function assertValidPreviewUrl(url) {
 
 // src/context.ts
 import { readFileSync } from "fs";
+
+// src/git.ts
+import { execFileSync } from "child_process";
+var defaultRunner = (args) => execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+function detectRepoFullName(run2 = defaultRunner) {
+  const remote = tryGit(run2, ["remote", "get-url", "origin"]);
+  return remote ? parseRepoFromRemote(remote) : void 0;
+}
+function detectHeadSha(run2 = defaultRunner) {
+  return tryGit(run2, ["rev-parse", "HEAD"]);
+}
+function parseRepoFromRemote(remote) {
+  const match = remote.match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/);
+  return match ? match[1] : void 0;
+}
+function tryGit(run2, args) {
+  try {
+    return run2(args) || void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/context.ts
 var REPO_PATTERN = /^[^/\s]+\/[^/\s]+$/;
 var PR_REF_PATTERN = /^refs\/pull\/(\d+)\//;
-function resolvePrContext(input = {}) {
+var REPO_MISSING_MESSAGE = "Repository not set: pass --repo owner/name (auto-detected from the GitHub Actions env or a github.com origin remote on the git checkout).";
+var HEAD_SHA_MISSING_MESSAGE = "Head SHA not set: pass --sha <sha> (auto-detected from the GitHub Actions env or the git checkout's HEAD).";
+var PR_NUMBER_MISSING_MESSAGE = "Pull request number not set: pass --pr <number> (auto-detected in GitHub Actions, CircleCI, Jenkins, Buildkite, Travis CI, and Drone).";
+var PR_OR_SHA_MISSING_MESSAGE = "Neither a pull request number nor a head SHA could be resolved: pass --pr <number> or --sha <sha> (or run inside a supported CI, or a git checkout).";
+function resolveRunContext(input = {}) {
+  const context = resolveRunContextAllowingShaOnly(input);
+  if (context.prNumber === void 0) {
+    throw new ConfigError(PR_NUMBER_MISSING_MESSAGE);
+  }
+  return { ...context, prNumber: context.prNumber };
+}
+function resolveRunContextAllowingShaOnly(input = {}) {
   const env = input.env ?? process.env;
   const payload = loadEventPayload(input, env);
+  const headSha = resolveHeadSha(input, env, payload) ?? detectHeadSha(input.gitRunner);
+  if (!headSha) {
+    throw new ConfigError(HEAD_SHA_MISSING_MESSAGE);
+  }
   return {
     repo: resolveRepo(input, env),
-    prNumber: resolvePrNumber(input, env, payload)
+    prNumber: resolvePrNumber(input, env, payload),
+    headSha
   };
 }
-function resolveRunContext(input = {}) {
+function resolvePrContext(input = {}) {
   const env = input.env ?? process.env;
   const payload = loadEventPayload(input, env);
-  return {
-    repo: resolveRepo(input, env),
-    prNumber: resolvePrNumber(input, env, payload),
-    headSha: resolveHeadSha(input, env, payload)
-  };
+  const prNumber = resolvePrNumber(input, env, payload);
+  const knownHeadSha = resolveHeadSha(input, env, payload);
+  const headSha = prNumber === void 0 ? knownHeadSha ?? detectHeadSha(input.gitRunner) : knownHeadSha;
+  if (prNumber === void 0 && !headSha) {
+    throw new ConfigError(PR_OR_SHA_MISSING_MESSAGE);
+  }
+  return { repo: resolveRepo(input, env), prNumber, headSha };
 }
 function resolveRepo(input, env = {}) {
-  const repo = input.repo ?? env.GITHUB_REPOSITORY;
+  const repo = input.repo ?? env.GITHUB_REPOSITORY ?? detectRepoFullName(input.gitRunner);
   if (!repo) {
-    throw new ConfigError(
-      "Repository not set: pass --repo owner/name (auto-detected from $GITHUB_REPOSITORY in GitHub Actions)."
-    );
+    throw new ConfigError(REPO_MISSING_MESSAGE);
   }
   if (!REPO_PATTERN.test(repo)) {
     throw new ConfigError(`--repo must look like "owner/name", got "${repo}".`);
   }
   return repo;
 }
+function resolveHeadSha(input, env = {}, payload) {
+  return input.sha ?? payload.headSha ?? env.GITHUB_SHA;
+}
 function resolvePrNumber(input, env = {}, payload) {
-  const candidate = input.pr ?? parsePrFromRef(env.GITHUB_REF) ?? payload.prNumber;
-  const prNumber = Number(candidate);
-  if (candidate === void 0 || !Number.isInteger(prNumber) || prNumber <= 0) {
-    throw new ConfigError(
-      "Pull request number not set: pass --pr <number> (auto-detected from the pull_request event in GitHub Actions)."
-    );
-  }
-  return prNumber;
+  const candidate = input.pr ?? parsePrFromRef(env.GITHUB_REF) ?? payload.prNumber ?? resolvePrNumberFromCiEnv(env);
+  return toPositiveInteger(candidate);
 }
-function resolveHeadSha(input, env = {}, payload) {
-  const headSha = input.sha ?? payload.headSha ?? env.GITHUB_SHA;
-  if (!headSha) {
-    throw new ConfigError(
-      "Head SHA not set: pass --sha <sha> (the commit the preview was built from)."
-    );
-  }
-  return headSha;
+function toPositiveInteger(candidate) {
+  if (candidate === void 0) return void 0;
+  const parsed = Number(candidate);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
 }
 function parsePrFromRef(ref) {
   const match = ref?.match(PR_REF_PATTERN);
   return match ? match[1] : void 0;
 }
+var CI_PR_ENV_SOURCES = [
+  {
+    // CircleCI: CIRCLE_PULL_REQUEST is a URL (https://github.com/o/r/pull/123);
+    // CIRCLE_PR_NUMBER is a plain number and is checked as a fallback.
+    ci: "CircleCI",
+    read: (env) => numericPrCandidate(trailingNumber(env.CIRCLE_PULL_REQUEST)) ?? numericPrCandidate(env.CIRCLE_PR_NUMBER)
+  },
+  {
+    // Jenkins (Multibranch/PR builders): CHANGE_ID is the PR number.
+    ci: "Jenkins",
+    read: (env) => numericPrCandidate(env.CHANGE_ID)
+  },
+  {
+    // Buildkite: BUILDKITE_PULL_REQUEST is "false" on non-PR builds.
+    ci: "Buildkite",
+    read: (env) => numericPrCandidate(env.BUILDKITE_PULL_REQUEST)
+  },
+  {
+    // Travis CI: TRAVIS_PULL_REQUEST is "false" on non-PR builds.
+    ci: "Travis CI",
+    read: (env) => numericPrCandidate(env.TRAVIS_PULL_REQUEST)
+  },
+  {
+    // Drone: DRONE_PULL_REQUEST is the PR number, unset outside PR builds.
+    ci: "Drone",
+    read: (env) => numericPrCandidate(env.DRONE_PULL_REQUEST)
+  }
+];
+function resolvePrNumberFromCiEnv(env) {
+  for (const source of CI_PR_ENV_SOURCES) {
+    const candidate = source.read(env);
+    if (candidate !== void 0) return candidate;
+  }
+  return void 0;
+}
+function trailingNumber(value) {
+  const match = value?.match(/(\d+)\/?$/);
+  return match?.[1];
+}
+function numericPrCandidate(value) {
+  if (!value || value === "false") return void 0;
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? value : void 0;
+}
 function loadEventPayload(input, env = {}) {
   const read = input.readEventPayload ?? (() => readEventFile(env.GITHUB_EVENT_PATH));
   const raw = safeRead(read);
@@ -120,6 +197,21 @@ function numberOrUndefined(value) {
 function stringOrUndefined(value) {
   return typeof value === "string" ? value : void 0;
 }
+function describeContextTarget(context) {
+  if (context.prNumber !== void 0) return `${context.repo}#${context.prNumber}`;
+  if (context.headSha) return `${context.repo}@${context.headSha}`;
+  return context.repo;
+}
+
+// src/legacy-server.ts
+var LEGACY_SERVER_BAD_REQUEST_STATUS = 400;
+function isUnresolvedPrOnLegacyServer(options) {
+  return !options.prNumberKnown && options.status === LEGACY_SERVER_BAD_REQUEST_STATUS && !options.code;
+}
+var LEGACY_SERVER_PR_HINT = "if this is an older DataDisco server, pass --pr <number> explicitly";
+function withLegacyServerPrHint(error) {
+  return `${error} (${LEGACY_SERVER_PR_HINT})`;
+}
 
 // src/api.ts
 var REPORT_PREVIEW_PATH = "/api/qa/report-preview";
@@ -159,7 +251,7 @@ async function reportPreview(config, params, fetchImpl) {
 async function getRunStatus(config, params, fetchImpl) {
   const url = new URL(joinUrl(config.apiUrl, RUN_STATUS_PATH));
   url.searchParams.set("repo", params.repo);
-  url.searchParams.set("prNumber", String(params.prNumber));
+  setRunLookupParam(url, params);
   const response = await fetchImpl(url.toString(), {
     headers: { authorization: `Bearer ${config.apiToken}` }
   });
@@ -167,7 +259,19 @@ async function getRunStatus(config, params, fetchImpl) {
   if (response.ok && isRunStatus(payload.run)) {
     return { ok: true, run: payload.run };
   }
-  return { ok: false, status: response.status, error: errorMessage(payload) };
+  return {
+    ok: false,
+    status: response.status,
+    error: errorMessage(payload),
+    code: stringOrUndefined2(payload.code)
+  };
+}
+function setRunLookupParam(url, params) {
+  if (params.prNumber !== void 0) {
+    url.searchParams.set("prNumber", String(params.prNumber));
+  } else if (params.headSha) {
+    url.searchParams.set("headSha", params.headSha);
+  }
 }
 function joinUrl(base, path) {
   return `${base.replace(/\/+$/, "")}${path}`;
@@ -301,7 +405,7 @@ var POLL_INTERVAL_MS = 15e3;
 var MINUTE_MS = 6e4;
 async function waitForVerdict(api, context, deps, timeoutMs) {
   const deadline = deps.now() + timeoutMs;
-  deps.logger.info(`Waiting for QA verdict on ${context.repo}#${context.prNumber}\u2026`);
+  deps.logger.info(`Waiting for QA verdict on ${describeContextTarget(context)}\u2026`);
   let lastStatus;
   while (true) {
     const outcome = await api.getRunStatus(context);
@@ -316,7 +420,9 @@ async function waitForVerdict(api, context, deps, timeoutMs) {
         return verdict.exitCode;
       }
     } else if (outcome.status !== 404) {
-      deps.logger.error(`Could not read QA run status: ${outcome.error}`);
+      deps.logger.error(
+        `Could not read QA run status: ${describeRunStatusFailure(outcome, context)}`
+      );
       return 1;
     }
     if (deps.now() >= deadline) {
@@ -328,6 +434,16 @@ async function waitForVerdict(api, context, deps, timeoutMs) {
     await deps.sleep(POLL_INTERVAL_MS);
   }
 }
+function describeRunStatusFailure(outcome, context) {
+  if (isUnresolvedPrOnLegacyServer({
+    prNumberKnown: context.prNumber !== void 0,
+    status: outcome.status,
+    code: outcome.code
+  })) {
+    return withLegacyServerPrHint(outcome.error);
+  }
+  return outcome.error;
+}
 var DEFAULT_TIMEOUT_FLAG = {
   flag: "--timeout",
   defaultMinutes: DEFAULT_TIMEOUT_MINUTES
@@ -359,7 +475,7 @@ async function runReportPreview(options, deps = defaultDeps) {
   }
   assertValidPreviewUrl(options.url);
   const config = resolveConfig(options);
-  const context = resolveRunContext(options);
+  const context = resolveRunContextAllowingShaOnly(options);
   const waitRunTimeoutMs = resolveTimeoutMs(options.waitRunTimeout, WAIT_RUN_TIMEOUT_SPEC);
   const api = deps.createApi(config);
   const outcome = await reportPreviewUntilRunExists(api, context, options.url, deps, {
@@ -367,11 +483,11 @@ async function runReportPreview(options, deps = defaultDeps) {
     waitRunTimeoutMs
   });
   if (!outcome.ok) {
-    deps.logger.error(`Could not report preview URL: ${describeFailure(outcome)}`);
+    deps.logger.error(`Could not report preview URL: ${describeFailure(outcome, context)}`);
     return 1;
   }
   deps.logger.success(
-    `Preview reported for ${context.repo}#${context.prNumber} \u2014 QA run ${outcome.runId} queued.`
+    `Preview reported for ${describeContextTarget(context)} \u2014 QA run ${outcome.runId} queued.`
   );
   return 0;
 }
@@ -385,7 +501,14 @@ async function reportPreviewUntilRunExists(api, context, url, deps, policy) {
 function isRunNotCreatedYet(outcome) {
   return !outcome.ok && outcome.status === RUN_NOT_CREATED_YET_STATUS && outcome.retryable !== false;
 }
-function describeFailure(outcome) {
+function describeFailure(outcome, context) {
+  if (isUnresolvedPrOnLegacyServer({
+    prNumberKnown: context.prNumber !== void 0,
+    status: outcome.status,
+    code: outcome.code
+  })) {
+    return withLegacyServerPrHint(outcome.error);
+  }
   return outcome.code ? `${outcome.error} [${outcome.code}]` : outcome.error;
 }
 async function retryReportPreviewUntilRunExists(api, context, url, deps, waitRunTimeoutMs) {
@@ -410,28 +533,6 @@ function withRunNeverAppearedHint(error) {
   return `${error} (gave up waiting \u2014 the QA run never appeared)`;
 }
 
-// src/git.ts
-import { execFileSync } from "child_process";
-var defaultRunner = (args) => execFileSync("git", args, { encoding: "utf8" }).trim();
-function detectRepoFullName(run2 = defaultRunner) {
-  const remote = tryGit(run2, ["remote", "get-url", "origin"]);
-  return remote ? parseRepoFromRemote(remote) : void 0;
-}
-function detectHeadSha(run2 = defaultRunner) {
-  return tryGit(run2, ["rev-parse", "HEAD"]);
-}
-function parseRepoFromRemote(remote) {
-  const match = remote.match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/);
-  return match ? match[1] : void 0;
-}
-function tryGit(run2, args) {
-  try {
-    return run2(args) || void 0;
-  } catch {
-    return void 0;
-  }
-}
-
 // src/tunnel-provider.ts
 import localtunnel from "localtunnel";
 async function openTunnel(port) {
@@ -505,7 +606,7 @@ cli.command("report-preview", "Report a PR's preview-deploy URL so its pending Q
   "--wait-run-timeout <minutes>",
   "How long to retry while the QA run hasn't been created yet (default 12)"
 ).action((options) => run(() => runReportPreview(options)));
-cli.command("wait", "Block until the PR's QA run reaches a verdict").option("--repo <owner/name>", "Repository the PR belongs to").option("--pr <number>", "Pull request number").option("--timeout <minutes>", "Give up after this many minutes (default 30)").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runWait(options)));
+cli.command("wait", "Block until the PR's QA run reaches a verdict").option("--repo <owner/name>", "Repository the PR belongs to").option("--pr <number>", "Pull request number").option("--sha <sha>", "Head SHA to look up the run by, if the PR number isn't known").option("--timeout <minutes>", "Give up after this many minutes (default 30)").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runWait(options)));
 cli.command("tunnel", "Expose a local build and start a QA run against it").option("--port <port>", "Local port serving the build").option("--url <url>", "Use an externally managed tunnel URL instead of --port").option("--repo <owner/name>", "Repository (defaults to the git origin remote)").option("--pr <number>", "Pull request number").option("--sha <sha>", "Head SHA (defaults to the local git HEAD)").option("--no-wait", "Queue the run and exit without waiting for a verdict").option("--timeout <minutes>", "Give up waiting after this many minutes").option("--api-url <url>", "DataDisco API base URL").option("--api-token <token>", "Workspace API token (or DATADISCO_API_TOKEN)").action((options) => run(() => runTunnel(options)));
 async function run(command) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datadisco/qa",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CI companion for DataDisco QA — report preview URLs, wait on persona-simulation gates, and tunnel local builds into QA runs.",
   "keywords": [
     "ci",