@apex-actions/cli 0.98.1 → 0.100.0

package/README.md

@@ -125,7 +125,6 @@ refused · 2 usage or configuration · 3 not found on `delete`.
 - `src/application/` — use cases over ports
 - `src/infrastructure/` — adapters: the engine and runner binaries, the REST API
 - Documentation is the root's: decisions in `docs/adrs/cli/`, the rest by category in `docs/` (TASK-0526)
-- `VERSION` — the release version, which `version:sync` writes from the root (ADR-0048); never edited by hand
 
 ## Licence
 

package/dist/cli/main.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { packageVersion } from '../src/infrastructure/binary-install.js';
 import { buildProgram } from './program.js';
-// The version from the nearest `package.json` — what ships, and what `version:check` keeps equal to
-// `VERSION` (see `packageVersion`); it also names which engine and runner the CLI downloads.
+// The version from the nearest `package.json` — the tag's, written at publish (ADR-0053; see `packageVersion`);
+// it also names which engine and runner the CLI downloads.
 buildProgram(packageVersion()).parse(process.argv);

package/dist/cli/reference.js

@@ -173,6 +173,7 @@ export const REFERENCE = {
         examples: [
             { command: 'apex why 4812', description: 'Why a run happened: the event, the workflow and the rule that matched.' },
             { command: 'apex why --delivery 7c1e0a52-3b9f-11ef-8e6b-2f4d1c9a0b77', description: 'Why a webhook produced no run at all.' },
+            { command: 'apex why --repo acme/web --pr 168', description: 'Why a pull request has no checks: the newest delivery about it that started nothing.' },
         ],
     },
     reproduce: {

package/dist/cli/why/main.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { explainWhy } from '../../src/application/explain-runs.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
-import { jobMarker, retryNote, verdictLine, worthShowing } from '../../src/domain/provenance.js';
+import { jobMarker, quietHeadline, retryNote, verdictLine, worthShowing } from '../../src/domain/provenance.js';
 import { parseRepository, unknownRunMessage } from '../../src/domain/runs.js';
 const printRun = (e) => {
     const { run, repository, trigger } = e;
@@ -36,8 +36,9 @@ const printRun = (e) => {
 const printDelivery = (e) => {
     const { delivery } = e;
     const action = delivery.action === undefined ? '' : `.${delivery.action}`;
-    console.log(chalk.bold(`Delivery ${delivery.deliveryId}`) + chalk.dim(` · ${delivery.event}${action} · ${delivery.status}`));
-    console.log(`  ${e.summary}`);
+    const pr = delivery.pullRequest === undefined ? '' : ` · #${delivery.pullRequest}`;
+    console.log(chalk.bold(`Delivery ${delivery.deliveryId}`) + chalk.dim(` · ${delivery.event}${action}${pr} · ${delivery.status}`));
+    console.log(`  ${quietHeadline(e)}`);
     if (e.verdicts.length > 0) {
         console.log(chalk.bold('\nWorkflows considered'));
         for (const t of e.verdicts) {
@@ -53,6 +54,12 @@ const handler = async (run, options) => {
         process.exitCode = 2;
         return;
     }
+    if (options.pr !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.pr)) {
+        console.error(chalk.red(`--pr must be a pull request number, got ${options.pr}`));
+        process.exitCode = 2;
+        return;
+    }
+    const pullRequest = options.pr === undefined ? undefined : Number(options.pr);
     let api;
     try {
         api = new HttpControlPlane();
@@ -64,7 +71,7 @@ const handler = async (run, options) => {
     }
     let outcome;
     try {
-        outcome = await explainWhy(api, { run: run ?? 'latest', repository, delivery: options.delivery });
+        outcome = await explainWhy(api, { run: run ?? 'latest', repository, delivery: options.delivery, pullRequest, nothing: options.nothing });
     }
     catch (err) {
         console.error(chalk.red(err instanceof Error ? err.message : String(err)));
@@ -84,6 +91,16 @@ const handler = async (run, options) => {
             console.error(chalk.red(`no delivery ${outcome.selector} is stored`));
             process.exitCode = 2;
             return;
+        case 'needs-repository':
+            console.error(chalk.red('--pr and --nothing need --repo <owner/repo>'));
+            process.exitCode = 2;
+            return;
+        case 'no-quiet-delivery':
+            console.error(chalk.yellow(outcome.pullRequest === undefined
+                ? 'every stored delivery for this repository started a run'
+                : `no stored delivery about #${outcome.pullRequest} started nothing — if it has no checks, GitHub may not have sent one`));
+            process.exitCode = 2;
+            return;
         case 'run':
             if (options.json === true)
                 console.log(JSON.stringify(outcome.explanation, null, 2));
@@ -102,5 +119,7 @@ export default new Command('why')
     .argument('[run]', 'run id, #number, or "latest"', 'latest')
     .option('--repo <owner/repo>', 'limit the run search to one repository')
     .option('--delivery <id>', 'explain a webhook delivery instead of a run')
+    .option('--pr <number>', "with --repo, explain the newest delivery about this pull request that started no run")
+    .option('--nothing', "with --repo, explain the repository's newest delivery that started no run")
     .option('--json', 'print the explanation as JSON')
     .action(handler);

package/dist/src/application/explain-runs.js

@@ -11,6 +11,14 @@ export const explainWhy = async (api, request) => {
         const explanation = await api.explainDelivery(request.delivery);
         return explanation === undefined ? { kind: 'unknown-delivery', selector: request.delivery } : { kind: 'delivery', explanation };
     }
+    // A pull request with no checks has no run to start from, and its delivery id is in nobody's hands: the
+    // repository's activity names the newest delivery that decided nothing, and why (BUG-0559).
+    if (request.pullRequest !== undefined || request.nothing === true) {
+        if (request.repository === undefined)
+            return { kind: 'needs-repository' };
+        const explanation = await api.newestQuietDelivery(request.repository, request.pullRequest);
+        return explanation === undefined ? { kind: 'no-quiet-delivery', pullRequest: request.pullRequest } : { kind: 'delivery', explanation };
+    }
     const resolved = await resolveRunId(api, request);
     if (resolved.kind !== 'run')
         return resolved;

package/dist/src/domain/provenance.js

@@ -23,6 +23,20 @@ export const retryNote = (job) => {
                 : job.requeueReason;
     return why === undefined ? `attempt ${attempt}` : `attempt ${attempt} — ${why}`;
 };
+/**
+ * The first line about a delivery that started nothing, said of what a person was looking at: their pull request.
+ * GitHub runs nothing for a pull request it cannot merge, and says so nowhere; the one it is most often asked about
+ * gets its own sentence ("#168 has a merge conflict with its base"), any other the delivery's own summary.
+ */
+export const quietHeadline = (e) => {
+    const pr = e.delivery.pullRequest;
+    if (pr === undefined)
+        return e.summary;
+    if (e.delivery.reasonCode === 'pull-request-conflict') {
+        return `#${pr} has a merge conflict with its base, so there is no merge commit to run against and nothing ran — resolve the conflict and push`;
+    }
+    return `#${pr}: ${e.summary}`;
+};
 /**
  * A verdict worth printing under "and here is what else this delivery
  * decided". `planned` is the run the reader is already looking at, and

package/dist/src/infrastructure/binary-install.js

@@ -12,24 +12,35 @@ import { promisify } from 'node:util';
  * platform and a SHA256SUMS file per command, under the lockstep version.
  */
 export const DIST_BASE = 'https://apexactions.com/dl';
-/**
- * The CLI's version, from the nearest `package.json` above this file.
- *
- * `VERSION` is the source of truth in the repository and is not in the published package; what ships is
- * `package.json`, and `version:check` guarantees the two agree. Walking up survives the layout differing
- * between `tsx` (`src/…`) and a tarball (`dist/src/…`).
- */
-export const packageVersion = (from = import.meta.dirname) => {
+/** What every workspace's `package.json` says in the repository: a constant, not a release (ADR-0053). */
+const UNRELEASED = '0.0.0';
+/** The first directory at or above `from` that `read` succeeds in, read; undefined when none does. */
+const nearest = (from, read) => {
     for (let dir = from;; dir = dirname(dir)) {
         try {
-            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+            return read(dir);
         }
         catch {
             if (dirname(dir) === dir)
-                return '0.0.0-unknown';
+                return undefined;
         }
     }
 };
+/**
+ * The CLI's version, from the nearest `package.json` above this file.
+ *
+ * In the repository a workspace's `package.json` carries `0.0.0` and the release is the root `VERSION` alone
+ * (ADR-0053), so a release changes nothing a build hashes; `publish.yml` writes the tag's version into the package
+ * it publishes, and that is what an installed CLI reads. A checkout's `0.0.0` reads on to the root `VERSION`, so a
+ * development CLI downloads the last release's binaries rather than ones nobody published. Walking up survives the
+ * layout differing between `tsx` (`src/…`) and a tarball (`dist/src/…`).
+ */
+export const packageVersion = (from = import.meta.dirname) => {
+    const declared = nearest(from, (dir) => JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version);
+    if (declared !== undefined && declared !== UNRELEASED)
+        return declared;
+    return nearest(from, (dir) => readFileSync(join(dir, 'VERSION'), 'utf8').trim()) ?? '0.0.0-unknown';
+};
 /** Node's names to Go's, for the four targets that are published; anything else has no download. */
 export const platformOf = (platform, arch) => {
     const os = platform === 'darwin' ? 'darwin' : platform === 'linux' ? 'linux' : undefined;

package/dist/src/infrastructure/binary-install.test.js

@@ -111,4 +111,11 @@ describe('the names', () => {
         writeFileSync(join(root, 'package.json'), JSON.stringify({ version: '9.8.7' }));
         expect(packageVersion(join(root, 'dist', 'src'))).toBe('9.8.7');
     });
+    it("reads a checkout's 0.0.0 on to the root VERSION, the release (ADR-0053)", () => {
+        const root = mkdtempSync(join(tmpdir(), 'repo-'));
+        mkdirSync(join(root, 'apps', 'cli', 'src'), { recursive: true });
+        writeFileSync(join(root, 'VERSION'), '0.99.0\n');
+        writeFileSync(join(root, 'apps', 'cli', 'package.json'), JSON.stringify({ version: '0.0.0' }));
+        expect(packageVersion(join(root, 'apps', 'cli', 'src'))).toBe('0.99.0');
+    });
 });

package/dist/src/infrastructure/control-plane-http.js

@@ -191,6 +191,12 @@ export class HttpControlPlane {
             return undefined;
         return (await this.#decodeOk(response));
     }
+    async newestQuietDelivery(repository, pullRequest) {
+        const pr = pullRequest === undefined ? '' : `&pull_request=${pullRequest}`;
+        const path = `/api/v1/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/activity?outcome=nothing&limit=1${pr}`;
+        const body = await this.#json('GET', path);
+        return body.activity[0];
+    }
     async reproduction(runId, job) {
         const query = job === undefined ? '' : `?job=${encodeURIComponent(job)}`;
         const response = await this.#request('GET', `/api/v1/runs/${encodeURIComponent(runId)}/reproduction${query}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-actions/cli",
-  "version": "0.98.1",
+  "version": "0.100.0",
   "license": "SEE LICENSE IN LICENSE",
   "//files": "Without this npm ships src, test and the CI config alongside the binary a user installs.",
   "files": [