ci-sdk 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diffling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
 # ci-sdk
 
-Coming soon.
+Insanely fast CI. No migration. By [Diffling](https://diffling.com).
+
+ci-sdk makes the CI you already have skip work your change can't affect: packages whose inputs didn't change, tests your change can't reach, and jobs that already passed on the same code. No pipeline to rewrite, no config, any runner.
+
+On [React Router](https://github.com/remix-run/react-router) (10 packages), whole CI jobs (setup, install, build, typecheck, lint, unit tests) ran **40% faster on pushes and 27% faster on pull requests**, with the same results, replaying real commits on GitHub's standard runners. Gains are largest in monorepos with many packages and commits that touch a few of them; repos whose jobs take only seconds gain little.
+
+Needs Node 22.18 or newer. Works with pnpm and npm workspaces (yarn and bun run through their own `run`).
+
+## run
+
+Run a package script in every workspace package, skipping packages whose inputs haven't changed since they last passed:
+
+```bash
+npx ci-sdk run build
+npx ci-sdk run typecheck
+```
+
+- A package reruns when its own files, a workspace package it depends on, or its dependencies in `pnpm-lock.yaml` change. Docs, changelogs, licenses and CI config don't count.
+- Outputs are whatever the script creates outside git. On a cache hit they are restored and the script's log is replayed. No config.
+- Packages run dependencies first, up to 4 at a time. Failures are never cached, and packages that depend on a failure don't run.
+- The cache lives in `node_modules/.cache/ci-sdk`. In CI, entries the run didn't use are pruned, so a saved cache stays small.
+- `--filter './packages/*'` limits it to some folders. `--no-cache` runs everything and refreshes the cache.
+- Environment variables are not part of a package's inputs. If a script's output depends on one, run it with `--no-cache`.
+
+## test
+
+Run only the tests your changes can reach:
+
+```bash
+npx ci-sdk test                      # uncommitted and untracked changes
+npx ci-sdk test --since origin/main  # plus commits on your branch
+npx ci-sdk test --since HEAD~1       # in CI: the commit being tested
+```
+
+- Follows imports through barrel files, so a change in a shared package only runs the tests that use it.
+- Runs each package's own test script with the affected files. Packages without one run through the root's script, such as `jest` or `vitest run`. `--script test-unit` picks a different script.
+- If a change can affect everything, such as a root config, it runs the full suite.
+- It never reports success for tests it couldn't run: if no script can take the affected files, it fails and names them.
+- `--list` prints the affected test files instead of running them.
+
+## GitHub Action
+
+Restores tool caches (Turborepo, Next.js, ESLint, `node_modules/.cache`, which includes ci-sdk's own) and tells you when this exact code already passed this job:
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+    with:
+      fetch-depth: 2 # lets `ci-sdk test --since HEAD~1` see the commit's changes
+  - uses: pnpm/action-setup@v6
+  - uses: actions/setup-node@v7
+    with:
+      node-version: 24
+  - id: ci-sdk
+    uses: jaymalve/ci-sdk@v0.0.3
+  - if: steps.ci-sdk.outputs.already-passed != 'true'
+    run: |
+      pnpm install --frozen-lockfile
+      npx ci-sdk run build
+      npx ci-sdk run typecheck
+      npx ci-sdk test --since HEAD~1
+```
+
+- Add `ci-sdk` to your devDependencies to pin its version; `npx` then uses the installed copy instead of downloading it.
+- `already-passed` is `true` when this job already passed on the same code (same git tree, job and matrix). Skip the rest of the job when it is.
+- Each run saves a fresh cache entry and restores the latest one. On pull requests, that includes the base branch's.
+- On runners that serve the GitHub Actions cache API from their own storage, such as Blacksmith and Depot, the Action uses that automatically.
+
+## scan
+
+See where your GitHub Actions minutes and dollars go, and how much ci-sdk would save. Run it in your repo:
+
+```bash
+npx ci-sdk scan
+```
+
+- Looks at the last 30 days of workflow runs (`--days`, `--max-runs` to change).
+- Estimates savings from your repo's own history: repeated runs, tests a change could not reach (via an oxc import graph), and slow installs.
+- `--markdown` for a PR or Slack, `--json` for tooling.
+- Needs a GitHub token with **Actions: read**. Uses `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`.
+- Runs locally. Your code and CI data never leave your machine.

package/dist/classify.js

@@ -0,0 +1,31 @@
+// Order matters: first match wins, so "Setup pnpm" is setup and "Run pnpm test" is test.
+const RULES = [
+    // pnpm/action-setup usually runs the install itself (run_install: true); when it doesn't, it takes seconds.
+    ['install', /pnpm\/action-setup/i],
+    ['setup', /^(set up job|complete job|post )|checkout|\bset ?up\b|actions\/cache/i],
+    ['install', /\b(npm (ci|install|i)|pnpm (i|install)|yarn install|bun install|deno install|install dependencies)\b|^run yarn$|^install( deps| dependencies| packages)?$/i],
+    ['test', /\b(test|tests|vitest|jest|spec|e2e|playwright|cypress|coverage)\b/i],
+    ['lint', /\b(lint|eslint|oxlint|biome|prettier|format|typecheck|type-check|tsc|check)\b/i],
+    ['build', /\b(build|compile|bundle|tsup|rollup|webpack)\b/i],
+];
+export function categorize(stepName, durationMs = 0) {
+    const cat = RULES.find(([, re]) => re.test(stepName))?.[0] ?? 'other';
+    // Custom setup actions ("Setup pnpm and Node.js") often install deps too; installing a toolchain alone takes seconds.
+    if (cat === 'setup' && durationMs > 60_000 && /pnpm|npm|yarn|bun|node|deps|dependencies/i.test(stepName))
+        return 'install';
+    return cat;
+}
+// GitHub's published per-minute USD rates: https://docs.github.com/en/billing/reference/actions-minute-multipliers
+// shortcut: larger-runner sizes are not detected and are priced as 2-core; read runner size from the org's runner API when we need exact larger-runner pricing.
+export function ratePerMinute(labels) {
+    const l = labels.join(' ').toLowerCase();
+    if (l.includes('self-hosted'))
+        return null;
+    if (l.includes('macos'))
+        return 0.062;
+    if (l.includes('windows'))
+        return 0.01;
+    if (l.includes('arm'))
+        return 0.005;
+    return 0.006;
+}

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { getToken, repoFromGit } from './github.js';
+import { json, markdown, text } from './report.js';
+import { runCached } from './run.js';
+import { scan } from './scan.js';
+import { testAffected } from './test.js';
+const HELP = `Usage: ci-sdk <command> [options]
+
+Commands:
+  run      Run a package script in every workspace package, skipping packages whose inputs already passed
+  test     Run only the tests your changes can reach
+  scan     Show where your GitHub Actions minutes and dollars go, and what ci-sdk would save
+
+run options:  ci-sdk run <script>
+  --filter <glob>      Only packages in matching folders, e.g. './packages/*' (repeatable)
+  --concurrency <n>    Packages at a time (default: up to 4)
+  --no-cache           Run everything and refresh the cache
+
+test options:
+  --since <ref>        Also include changes committed since <ref>, e.g. origin/main (default: uncommitted only)
+  --list               Print the affected test files instead of running them
+  --script <name>      Script that runs tests and takes file paths (default: test), e.g. test-unit
+
+scan options:
+  --repo <owner/name>  Repo to scan (default: this checkout's origin)
+  --days <n>           Days of history (default: 30)
+  --max-runs <n>       Runs to sample evenly across the window (default: 300)
+  --json               Print JSON
+  --markdown           Print markdown to paste into a PR or Slack
+  -h, --help           Show this help
+
+scan needs a GitHub token with Actions: read. Uses GITHUB_TOKEN, GH_TOKEN, or \`gh auth token\`.
+Everything runs locally; nothing leaves your machine.`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            repo: { type: 'string' },
+            days: { type: 'string', default: '30' },
+            'max-runs': { type: 'string', default: '300' },
+            json: { type: 'boolean' },
+            markdown: { type: 'boolean' },
+            since: { type: 'string' },
+            list: { type: 'boolean' },
+            script: { type: 'string' },
+            filter: { type: 'string', multiple: true },
+            concurrency: { type: 'string' },
+            'no-cache': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const command = positionals[0];
+    if (values.help || !['scan', 'test', 'run'].includes(command) || (command === 'run' && !positionals[1])) {
+        console.log(HELP);
+        process.exit(values.help ? 0 : 1);
+    }
+    const log = (m) => process.stderr.write(`ci-sdk: ${m}\n`);
+    if (command === 'run')
+        process.exit(await runCached({ cwd: process.cwd(), script: positionals[1], filter: values.filter, concurrency: values.concurrency ? Number(values.concurrency) : undefined, noCache: values['no-cache'], log }));
+    if (command === 'test')
+        process.exit(await testAffected({ cwd: process.cwd(), since: values.since, list: values.list, script: values.script, log }));
+    const root = process.cwd();
+    const repo = values.repo ?? repoFromGit(root);
+    if (!repo)
+        throw new Error('Could not find a GitHub remote. Run inside a clone, or pass --repo owner/name.');
+    const token = getToken();
+    if (!token)
+        throw new Error('No GitHub token found. Set GITHUB_TOKEN (a fine-grained token with Actions: read), or run `gh auth login`.');
+    const days = Number(values.days);
+    const maxRuns = Number(values['max-runs']);
+    if (!(days > 0) || !(maxRuns > 0))
+        throw new Error('--days and --max-runs must be positive numbers.');
+    const result = await scan({ root, repo, token, days, maxRuns, log: (m) => process.stderr.write(m + '\n') });
+    console.log(values.json ? json(result) : values.markdown ? markdown(result) : text(result));
+}
+main().catch((err) => {
+    console.error(`ci-sdk: ${err.message}`);
+    process.exit(1);
+});

package/dist/github.js

@@ -0,0 +1,171 @@
+import { execFileSync } from 'node:child_process';
+const API = 'https://api.github.com';
+export function getToken() {
+    const env = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (env)
+        return env;
+    try {
+        return execFileSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function repoFromGit(cwd) {
+    try {
+        const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return url.trim().match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+async function gh(path, token, attempt = 1) {
+    const res = await fetch(API + path, {
+        headers: {
+            Accept: 'application/vnd.github+json',
+            Authorization: `Bearer ${token}`,
+            'X-GitHub-Api-Version': '2022-11-28',
+        },
+    });
+    if (res.ok)
+        return res.json();
+    const outOfQuota = res.headers.get('x-ratelimit-remaining') === '0';
+    // Flaky 5xx and secondary rate limits (Retry-After) clear up; a spent hourly quota does not.
+    const retryAfter = Number(res.headers.get('retry-after'));
+    if (attempt < 4 && (res.status >= 500 || res.status === 429 || (res.status === 403 && retryAfter && !outOfQuota))) {
+        await new Promise((r) => setTimeout(r, retryAfter ? retryAfter * 1000 : 1000 * 2 ** attempt));
+        return gh(path, token, attempt + 1);
+    }
+    const body = (await res.json().catch(() => ({})));
+    const reset = new Date(Number(res.headers.get('x-ratelimit-reset')) * 1000).toLocaleTimeString();
+    const hint = res.status === 401 ? ' (the token is invalid or expired)'
+        : outOfQuota ? ` (GitHub API rate limit used up; it resets at ${reset})`
+            : res.status === 403 ? ' (the token needs Actions: read on this repo)'
+                : res.status === 404 ? ' (check the repo name and that your token can read it)'
+                    : '';
+    throw new Error(`GitHub API ${res.status} on ${path}: ${body.message ?? res.statusText}${hint}`);
+}
+export function getRepo(repo, token) {
+    return gh(`/repos/${repo}`, token);
+}
+const COUNT_CAP = 2500;
+/** How many runs a slot held. Past GitHub's 2,500 count cap, scale the spacing of the newest 100 runs to the whole slot. */
+export function slotCount(totalCount, runs, width) {
+    if (totalCount < COUNT_CAP || runs.length < 2)
+        return totalCount;
+    const span = Date.parse(runs[0].created_at) - Date.parse(runs.at(-1).created_at);
+    return span > 0 ? Math.max(COUNT_CAP, Math.round(((runs.length - 1) * width) / span)) : COUNT_CAP;
+}
+/** `n` items spread evenly through `items`, so a slot's sample is not just its last minutes. */
+const spread = (items, n) => (items.length <= n ? items : Array.from({ length: n }, (_, i) => items[Math.floor((i * items.length) / n)]));
+/**
+ * Splits `budget` samples across workflows by `score`, never more than a workflow's run count.
+ * Samples a small workflow cannot use go back to the others, so the whole budget gets spent.
+ */
+export function allocate(items, budget) {
+    const k = items.map(() => 0);
+    let open = items.map((_, i) => i).filter((i) => items[i].count > 0);
+    let left = budget;
+    while (left > 0 && open.length) {
+        const total = open.reduce((a, i) => a + items[i].score, 0) || 1;
+        let used = 0;
+        for (const i of open) {
+            const next = Math.min(items[i].count, k[i] + Math.max(1, Math.floor((left * items[i].score) / total)));
+            used += next - k[i];
+            k[i] = next;
+        }
+        left -= used;
+        open = open.filter((i) => k[i] < items[i].count);
+    }
+    return k;
+}
+const iso = (t) => new Date(t).toISOString().slice(0, 19) + 'Z';
+const wallMs = (r) => Math.max(1000, Date.parse(r.updated_at ?? r.created_at) - Date.parse(r.run_started_at ?? r.created_at));
+/**
+ * `k` runs of one workflow spread over time, each weighted by how many runs its time slot held.
+ * Small workflows are sampled straight from their first page; busy ones get one query per slot.
+ */
+async function sampleWorkflow(repo, token, id, first, since, now, k) {
+    // Up to GitHub's 1,000-result listing limit, list every run (1 call per 100) and pick evenly: exact count, no empty slots.
+    if (first.total_count <= 1000) {
+        const all = [...first.workflow_runs];
+        const created = encodeURIComponent(`>=${iso(since).slice(0, 10)}`);
+        for (let page = 2; all.length < first.total_count; page++) {
+            const data = await gh(`/repos/${repo}/actions/workflows/${id}/runs?created=${created}&status=completed&per_page=100&page=${page}`, token);
+            if (!data.workflow_runs.length)
+                break;
+            all.push(...data.workflow_runs);
+        }
+        const picked = spread(all, k);
+        return { count: all.length, estimated: false, runs: picked.map((run) => ({ run, weight: all.length / picked.length })) };
+    }
+    const width = (now - since) / k;
+    const slots = await pool(Array.from({ length: k }, (_, i) => since + i * width), 4, async (start) => {
+        const created = encodeURIComponent(`${iso(start)}..${iso(start + width - 1000)}`);
+        const data = await gh(`/repos/${repo}/actions/workflows/${id}/runs?created=${created}&status=completed&per_page=100`, token);
+        const count = slotCount(data.total_count, data.workflow_runs, width);
+        return { count, estimated: data.total_count >= COUNT_CAP, runs: spread(data.workflow_runs, 1).map((run) => ({ run, weight: count })) };
+    });
+    return { count: slots.reduce((a, s) => a + s.count, 0), estimated: slots.some((s) => s.estimated), runs: slots.flatMap((s) => s.runs) };
+}
+/**
+ * About `max` completed runs since `since`, sampled per workflow and weighted so they add up to every run in the window.
+ * Busy repos mix 2-second bot workflows with 20-minute test workflows, so samples are split by each workflow's share of
+ * CI time (runs x typical length), and each sample stands only for runs of its own workflow.
+ * `estimated` means some period passed GitHub's count cap and its count was estimated from run spacing.
+ */
+export async function listRuns(repo, token, since, max) {
+    // Small enough to take every run: exact, and repeats and push-to-push diffs stay visible.
+    const all = [];
+    const created = encodeURIComponent(`>=${since.toISOString().slice(0, 10)}`);
+    for (let page = 1;; page++) {
+        const data = await gh(`/repos/${repo}/actions/runs?created=${created}&status=completed&per_page=100&page=${page}`, token);
+        if (data.total_count > max)
+            break;
+        all.push(...data.workflow_runs);
+        if (data.workflow_runs.length < 100)
+            return { runs: all.map((run) => ({ run, weight: 1 })), total: all.length, estimated: false };
+    }
+    const now = Date.now();
+    const ids = [];
+    for (let page = 1;; page++) {
+        const data = await gh(`/repos/${repo}/actions/workflows?per_page=100&page=${page}`, token);
+        ids.push(...data.workflows.map((w) => w.id));
+        if (data.workflows.length < 100)
+            break;
+    }
+    const firsts = (await pool(ids, 8, async (id) => ({ id, first: await gh(`/repos/${repo}/actions/workflows/${id}/runs?created=${created}&status=completed&per_page=100`, token) }))).filter((w) => w.first.total_count > 0);
+    // Share of CI time: run count x average run length from the first page.
+    const score = (w) => w.first.total_count * (w.first.workflow_runs.reduce((a, r) => a + wallMs(r), 0) / w.first.workflow_runs.length);
+    const ks = allocate(firsts.map((w) => ({ count: w.first.total_count, score: score(w) })), max);
+    const sampled = await pool(firsts.map((w, i) => ({ w, k: ks[i] })), 4, ({ w, k }) => sampleWorkflow(repo, token, w.id, w.first, since.getTime(), now, k));
+    return {
+        runs: sampled.flatMap((s) => s.runs),
+        total: sampled.reduce((a, s) => a + s.count, 0),
+        estimated: sampled.some((s) => s.estimated),
+    };
+}
+/** Every attempt's jobs for a run, so re-runs are counted. */
+export async function listJobs(repo, runId, token) {
+    const jobs = [];
+    for (let page = 1;; page++) {
+        const data = await gh(`/repos/${repo}/actions/runs/${runId}/jobs?filter=all&per_page=100&page=${page}`, token);
+        jobs.push(...data.jobs);
+        if (data.jobs.length < 100)
+            return jobs;
+    }
+}
+/** Runs `fn` over `items` with at most `limit` in flight. */
+export async function pool(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}