feat: add ncu-ci workload

Count running and queued PR CI jobs for workload threshold checks.
Include PR builds waiting for downstream tests and count requests only
once when they move from the queue to an executor between reads.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
Assisted-by: Codex

Author: panva

bin/ncu-ci.js

@@ -25,6 +25,7 @@ import {
 } from '../lib/ci/run_ci.js';
 import { ResumePRJob } from '../lib/ci/resume_ci.js';
 import { checkAvailability } from '../lib/ci/availability.js';
+import { getPRWorkload } from '../lib/ci/workload.js';
 import { writeJson, writeFile } from '../lib/file.js';
 import { getMergedConfig } from '../lib/config.js';
 import { runPromise } from '../lib/run.js';
@@ -60,6 +61,11 @@ const args = yargs(hideBin(process.argv))
     desc: 'Check whether Jenkins is available for PR CI requests',
     handler
   })
+  .command({
+    command: 'workload',
+    desc: 'Print the number of running and queued node-test-pull-request jobs',
+    handler
+  })
   .command({
     command: 'rate <type>',
     desc: 'Calculate the green rate of a CI job in the last 100 runs',
@@ -604,7 +610,7 @@ class DailyCommand extends CICommand {
   }
 }
 
-async function checkJenkins() {
+async function checkJenkins(command) {
   try {
     let jenkins;
     try {
@@ -614,16 +620,23 @@ async function checkJenkins() {
       throw new Error('Configure username and jenkins_token with ncu-config');
     }
     const request = new Request({ jenkins });
-    await checkAvailability(request);
+    if (command === 'available') {
+      await checkAvailability(request);
+    } else {
+      console.log(await getPRWorkload(request));
+    }
   } catch (err) {
-    console.error(`Unable to check Jenkins availability: ${err.message}`);
+    const action = command === 'available'
+      ? 'check Jenkins availability'
+      : 'read the PR CI workload';
+    console.error(`Unable to ${action}: ${err.message}`);
     process.exitCode = 1;
   }
 }
 
 async function main(command, argv) {
-  if (command === 'available') {
-    return checkJenkins();
+  if (command === 'available' || command === 'workload') {
+    return checkJenkins(command);
   }
   const cli = new CLI();
   const credentials = await auth({

docs/ncu-ci.md

@@ -14,6 +14,7 @@ ncu-ci <command>
 
 Commands:
   ncu-ci available          Check whether Jenkins is available for PR CI requests
+  ncu-ci workload           Print the number of running and queued node-test-pull-request jobs
   ncu-ci rate <type>        Calculate the green rate of a CI job in the last 100
                             runs
   ncu-ci walk <type>        Walk the CI and display the failures
@@ -48,14 +49,30 @@ The command only reads Jenkins state. It does not start or resume a build, check
 individual PRs, or require idle executors. Availability can change after the
 check.
 
-The command uses the configured `username` and `jenkins_token`; no GitHub token,
-repository configuration, or PR argument is required. It has a 20-second deadline
-for its Jenkins requests, including response bodies.
+### `ncu-ci workload`
 
-For example, skip processing requests unless Jenkins is available:
+`ncu-ci workload` prints the number of running and queued `node-test-pull-request`
+jobs, followed by a newline. This includes PR builds waiting for downstream tests.
+Each PR build counts once; downstream test jobs do not add to the count. If no PR
+builds are running or queued, it prints `0`. A failed query exits with status 1,
+reports the reason on stderr, and does not print a count.
+
+The command reads Jenkins executors and the waiting queue, so older active builds
+are counted without relying on a limited build history. A request that starts
+between the two reads is counted once. The count is a snapshot and can change
+before a new request starts.
+
+Both commands use the configured `username` and `jenkins_token`; no GitHub token,
+repository configuration, or PR argument is required. Each command has a
+20-second deadline for its Jenkins requests, including response bodies.
+
+For example, skip processing requests unless Jenkins is available and fewer than
+five PR jobs are running or queued:
 
 ```sh
 ncu-ci available || exit 0
+workload=$(ncu-ci workload) || exit 0
+[ "$workload" -lt 5 ] || exit 0
 
 # Process requests here.
 ```

lib/ci/workload.js

@@ -0,0 +1,72 @@
+import { CI_DOMAIN, CI_TYPES, CI_TYPES_KEYS } from './ci_type_parser.js';
+import { readJenkinsJSON } from './jenkins.js';
+
+const PR_JOB_URL = `https://${CI_DOMAIN}/job/${CI_TYPES.get(CI_TYPES_KEYS.PR).jobName}`;
+
+export async function getPRWorkload(request) {
+  const signal = AbortSignal.timeout(20_000);
+  const data = await readJenkinsJSON(request, '/queue/api/json?tree=items[id,task[url]]', signal);
+  if (!Array.isArray(data?.items)) {
+    throw new Error('Jenkins returned an invalid queue');
+  }
+
+  const queued = new Set();
+  for (const item of data.items) {
+    if (!item || typeof item !== 'object' || Array.isArray(item) ||
+        !item.task || typeof item.task !== 'object' || Array.isArray(item.task)) {
+      throw new Error('Jenkins returned an invalid queue item');
+    }
+    const { url } = item.task;
+    // Some Jenkins task types do not export a URL.
+    if (url === undefined || url === null) continue;
+    if (typeof url !== 'string') {
+      throw new Error('Jenkins returned an invalid queue task URL');
+    }
+    if (url === PR_JOB_URL || url === `${PR_JOB_URL}/`) {
+      if (!Number.isSafeInteger(item.id) || item.id < 0) {
+        throw new Error('Jenkins returned an invalid queue item ID');
+      }
+      queued.add(item.id);
+    }
+  }
+
+  // PR multijobs stay on an executor while waiting for downstream tests. The
+  // waiting queue alone misses those builds, and build history can be truncated.
+  const computers = await readJenkinsJSON(request,
+    '/computer/api/json?tree=computer[executors[currentExecutable[url,queueId]],' +
+    'oneOffExecutors[currentExecutable[url,queueId]]]', signal);
+  if (!Array.isArray(computers?.computer)) {
+    throw new Error('Jenkins returned invalid executor data');
+  }
+  const running = new Set();
+  for (const computer of computers.computer) {
+    if (!Array.isArray(computer?.executors) || !Array.isArray(computer?.oneOffExecutors)) {
+      throw new Error('Jenkins returned invalid executor lists');
+    }
+    for (const executor of [...computer.executors, ...computer.oneOffExecutors]) {
+      if (!executor || typeof executor !== 'object' || Array.isArray(executor)) {
+        throw new Error('Jenkins returned an invalid executor');
+      }
+      const build = executor.currentExecutable;
+      if (build === undefined || build === null) continue;
+      if (typeof build !== 'object' || Array.isArray(build)) {
+        throw new Error('Jenkins returned an invalid executable');
+      }
+      const { url, queueId } = build;
+      if (url === undefined || url === null) continue;
+      if (typeof url !== 'string') {
+        throw new Error('Jenkins returned an invalid executable URL');
+      }
+      if (!url.startsWith(`${PR_JOB_URL}/`)) continue;
+      const match = /^([1-9]\d*)\/?$/.exec(url.slice(PR_JOB_URL.length + 1));
+      if (!match) continue;
+      if (!Number.isSafeInteger(queueId)) {
+        throw new Error('Jenkins returned an invalid executable queue ID');
+      }
+      running.add(match[1]);
+      // A queued request can start between the two reads. Count it only once.
+      queued.delete(queueId);
+    }
+  }
+  return queued.size + running.size;
+}

test/unit/ci_preflight_cli.test.js

@@ -9,12 +9,28 @@ import { fileURLToPath } from 'node:url';
 const binaryURL = new URL('../../bin/ncu-ci.js', import.meta.url);
 const requestURL = new URL('../../lib/request.js', import.meta.url);
 const undiciURL = import.meta.resolve('undici');
+const jobURL = 'https://ci.nodejs.org/job/node-test-pull-request/';
 const root = (data, extra = {}) => ({
   path: '/api/json', tree: 'quietingDown', data, ...extra
 });
 const job = (data, extra = {}) => ({
   path: '/job/node-test-pull-request/api/json', tree: 'disabled,buildable', data, ...extra
 });
+const queue = (data, extra = {}) => ({
+  path: '/queue/api/json', tree: 'items[id,task[url]]', data, ...extra
+});
+const computers = (data, extra = {}) => ({
+  path: '/computer/api/json',
+  tree: 'computer[executors[currentExecutable[url,queueId]],' +
+    'oneOffExecutors[currentExecutable[url,queueId]]]',
+  data,
+  ...extra
+});
+const idleComputers = () => computers({ computer: [] });
+const running = (number, queueId = number) => ({
+  currentExecutable: { url: `${jobURL}${number}/`, queueId }
+});
+
 function run(t, command, responses, credentials = {
   username: 'test', jenkins_token: 'test-jenkins-token'
 }) {
@@ -169,3 +185,132 @@ describe('ncu-ci available', () => {
     assert.doesNotMatch(result.stdout + result.stderr, /secret-invalid-token/);
   });
 });
+
+describe('ncu-ci workload', () => {
+  it('prints only the number of unfinished and queued PR jobs', (t) => {
+    const result = run(t, 'workload', [queue({
+      items: [
+        { id: 1, task: { url: jobURL } },
+        { task: { url: 'https://ci.nodejs.org/job/node-test-commit/' } },
+        { task: { url: `${jobURL}123/` } },
+        { task: { url: 'https://example.org/job/node-test-pull-request/' } },
+        { task: { url: 'https://ci.nodejs.org/job/node-test-pull-request-other/' } },
+        { id: 2, task: { url: jobURL.slice(0, -1) } },
+        { task: {} },
+        { task: { url: null } },
+        { id: 3, task: { url: jobURL } }
+      ]
+    }), idleComputers()]);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '3\n');
+    assert.equal(result.stderr, '');
+  });
+
+  it('includes all 20 working PR builds when the waiting queue is empty', (t) => {
+    const result = run(t, 'workload', [queue({ items: [] }), computers({
+      computer: [{
+        executors: Array.from({ length: 3 }, (_, i) => running(i + 1)),
+        oneOffExecutors: Array.from({ length: 17 }, (_, i) => running(i + 4))
+      }]
+    })]);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '20\n');
+    assert.equal(result.stderr, '');
+    assert.equal(result.trace.jsonReads, 2);
+  });
+
+  it('combines queued and working PR builds without double counting transitions', (t) => {
+    const result = run(t, 'workload', [queue({
+      items: [
+        { id: 10, task: { url: jobURL } },
+        { id: 11, task: { url: jobURL } },
+        { id: 12, task: { url: jobURL } }
+      ]
+    }), computers({
+      computer: [{
+        executors: [running(101, 10), running(102, 20), { currentExecutable: null }, {}],
+        oneOffExecutors: [
+          running(102, 20),
+          { currentExecutable: { url: `${jobURL}102`, queueId: 20 } },
+          { currentExecutable: { url: 'https://ci.nodejs.org/job/node-test-commit/1/' } },
+          { currentExecutable: { url: 'https://example.org/job/node-test-pull-request/1/' } },
+          { currentExecutable: {} }
+        ]
+      }]
+    })]);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '4\n');
+    assert.equal(result.stderr, '');
+  });
+
+  for (const items of [[], [{ task: { url: 'https://ci.nodejs.org/job/node-test-commit/' } }]]) {
+    it(`prints zero for a valid queue with no PR jobs: ${JSON.stringify(items)}`, (t) => {
+      const result = run(t, 'workload', [queue({ items }), idleComputers()]);
+      assert.equal(result.status, 0, result.stderr);
+      assert.equal(result.stdout, '0\n');
+      assert.equal(result.stderr, '');
+    });
+  }
+
+  for (const data of [null, {}, { items: null }, { items: {} }]) {
+    it(`fails without a misleading count for invalid queue data: ${JSON.stringify(data)}`, (t) => {
+      assertFailure(run(t, 'workload', [queue(data)]));
+    });
+  }
+
+  for (const item of [null, {}, { task: null }, { task: false }, { task: { url: 123 } }]) {
+    it(`fails for a malformed queue item: ${JSON.stringify(item)}`, (t) => {
+      assertFailure(run(t, 'workload', [queue({ items: [item] })]));
+    });
+  }
+
+  for (const id of [undefined, null, -1, 1.5, '1', Number.MAX_SAFE_INTEGER + 1]) {
+    it(`rejects a queued PR item with invalid ID: ${JSON.stringify(id)}`, (t) => {
+      assertFailure(run(t, 'workload', [queue({ items: [{ id, task: { url: jobURL } }] })]));
+    });
+  }
+
+  for (const data of [
+    null,
+    {},
+    { computer: null },
+    { computer: {} },
+    { computer: [{ executors: {}, oneOffExecutors: [] }] },
+    { computer: [{ executors: [], oneOffExecutors: null }] },
+    { computer: [{ executors: [{ currentExecutable: false }], oneOffExecutors: [] }] },
+    { computer: [{ executors: [], oneOffExecutors: [{ currentExecutable: { url: 1 } }] }] }
+  ]) {
+    it(`fails without a partial count for invalid executor data: ${JSON.stringify(data)}`, (t) => {
+      assertFailure(run(t, 'workload', [
+        queue({ items: [{ id: 1, task: { url: jobURL } }] }), computers(data)
+      ]));
+    });
+  }
+
+  it('reports executor API failure without printing the already counted queue', (t) => {
+    const result = run(t, 'workload', [
+      queue({ items: [{ id: 1, task: { url: jobURL } }] }),
+      computers(null, { status: 503, statusText: 'Service Unavailable' })
+    ]);
+    assertFailure(result, /503/);
+    assert.equal(result.trace.jsonReads, 1);
+    assert.equal(result.trace.cancellations, 1);
+  });
+
+  it('reports HTTP failures instead of printing zero', (t) => {
+    const result = run(t, 'workload', [queue(null, { status: 403, statusText: 'Forbidden' })]);
+    assertFailure(result, /403/);
+    assert.equal(result.trace.jsonReads, 0);
+    assert.equal(result.trace.cancellations, 1);
+  });
+
+  it('reports malformed JSON instead of printing zero', (t) => {
+    assertFailure(run(t, 'workload', [queue(null, { jsonError: 'Invalid queue JSON' })]),
+      /Jenkins returned invalid JSON/);
+  });
+
+  it('reports a network failure instead of printing zero', (t) => {
+    assertFailure(run(t, 'workload', [queue(null, { error: 'Connection reset' })]),
+      /Connection reset/);
+  });
+});