ci-sdk 0.0.0-stage → 0.0.2

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,32 @@
-# Temporary Holding Version
+# ci-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Insanely fast CI. No migration. By [Diffling](https://diffling.com).
+
+## 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.
+
+## test
+
+Run only the tests your changes can reach, using each package's own `test` script:
+
+```bash
+npx ci-sdk test
+```
+
+- Looks at uncommitted and untracked changes. Add `--since origin/main` to include commits on your branch.
+- `--list` prints the affected test files instead of running them.
+- Follows imports through barrel files, so a change in a shared package only runs the tests that use it.
+- If a change can affect everything, such as a root config, it runs the full suite.
+
+Needs Node 22.18 or newer.

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,66 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { getToken, repoFromGit } from './github.js';
+import { json, markdown, text } from './report.js';
+import { scan } from './scan.js';
+import { testAffected } from './test.js';
+const HELP = `Usage: ci-sdk <command> [options]
+
+Commands:
+  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
+
+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
+
+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' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const command = positionals[0];
+    if (values.help || (command !== 'scan' && command !== 'test')) {
+        console.log(HELP);
+        process.exit(values.help ? 0 : 1);
+    }
+    const log = (m) => process.stderr.write(`ci-sdk: ${m}\n`);
+    if (command === 'test')
+        process.exit(await testAffected({ cwd: process.cwd(), since: values.since, list: values.list, 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;
+}

package/dist/graph.js

@@ -0,0 +1,315 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { ResolverFactory } from 'oxc-resolver';
+import { glob } from 'tinyglobby';
+import { isPure } from './purity.js';
+const CODE = '**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}';
+const IGNORE = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.git/**', '**/*.d.ts'];
+const TEST = /(\.(test|spec)\.[cm]?[jt]sx?$)|(^|\/)__tests__\//;
+// CommonJS requires and test-runner mocks are not in oxc's ESM module record, so pick them up by pattern.
+const EXTRA = /\b(?:require|(?:jest|vi)\.(?:mock|requireActual|importActual))\(\s*['"]([^'"]+)['"]/g;
+// Export conditions every package uses; anything else (e.g. "@zod/source") is a repo's own way to point at source.
+const STANDARD_CONDITIONS = new Set(['import', 'require', 'default', 'node', 'types', 'typings', 'browser', 'module', 'module-sync', 'production', 'development', 'worker', 'deno', 'bun', 'react-native', 'react-server', 'edge-light', 'workerd', 'electron', 'style']);
+const PKG = 'pkg:';
+const BUILD_OUTPUT = /(^|\/)(dist|build|out)\//;
+const ALL = '*';
+/**
+ * Where names really come from. A barrel (`export * from './dates'`) re-exports dozens of files; a test that imports
+ * `formatDate` through it depends on the file defining formatDate and the barrels on the way, not on every file the
+ * barrel exposes. Files with load-time side effects stay linked to everyone who loads them.
+ */
+function exportsIndex(infos) {
+    const union = (a, b) => {
+        const out = a ?? new Set();
+        for (const x of b)
+            out.add(x);
+        return out;
+    };
+    const wholeMemo = new Map();
+    /** The module plus every file it re-exports from, transitively: what `import * as ns` can reach. */
+    const whole = (m) => {
+        const cached = wholeMemo.get(m);
+        if (cached)
+            return cached;
+        const out = new Set([m]);
+        wholeMemo.set(m, out); // seeded first so re-export cycles terminate
+        for (const r of infos.get(m)?.reexports ?? [])
+            union(out, whole(r.from));
+        return out;
+    };
+    const memo = new Map();
+    /** Files that define `name` as exported by `m`, plus the barrels it passes through; undefined if `m` lacks it. */
+    const definers = (m, name, seen = new Set()) => {
+        const key = `${m}\0${name}`;
+        if (memo.has(key))
+            return memo.get(key);
+        const info = infos.get(m);
+        // Unparsed targets (JSON, CSS) and names a module defines itself end here.
+        if (!info || m.startsWith(PKG) || info.local.has(name))
+            return new Set([m]);
+        if (seen.has(m))
+            return undefined;
+        seen.add(m);
+        let out;
+        for (const r of info.reexports) {
+            if (r.exported === name)
+                out = union(out, r.imported === ALL ? whole(r.from) : (definers(r.from, r.imported, seen) ?? whole(r.from)));
+            else if (r.exported === ALL && name !== 'default') {
+                const found = definers(r.from, name, seen);
+                if (found)
+                    out = union(out, found);
+            }
+        }
+        if (out)
+            out.add(m);
+        memo.set(key, out);
+        return out;
+    };
+    return { definers, whole };
+}
+// `fx:<file>` stands for what loading <file> does. It changes when <file> has side effects and changes, or when
+// anything <file> loads has side effects that change; a pure file's own edits never reach it.
+const FX = 'fx:';
+const bareName = (spec) => (/^[./]|:/.test(spec) ? undefined : spec.split('/').slice(0, spec.startsWith('@') ? 2 : 1).join('/'));
+export async function buildGraph(dir) {
+    // The resolver returns real paths, so a symlinked checkout (e.g. macOS /var -> /private/var) must be compared by its real path.
+    const root = realpathSync(dir);
+    const files = await glob(CODE, { cwd: root, ignore: IGNORE });
+    // Workspace packages by name, so `import 'zod/v4'` resolves to repo source even without node_modules installed.
+    const packages = new Map();
+    const packageDirs = [];
+    const custom = new Set();
+    const collect = (o) => {
+        if (o && typeof o === 'object')
+            for (const [k, v] of Object.entries(o)) {
+                if (!k.startsWith('.') && !STANDARD_CONDITIONS.has(k))
+                    custom.add(k);
+                collect(v);
+            }
+    };
+    for (const m of await glob('**/package.json', { cwd: root, ignore: IGNORE })) {
+        if (m !== 'package.json')
+            packageDirs.push(m.slice(0, -'package.json'.length));
+        try {
+            const pkg = JSON.parse(readFileSync(join(root, m), 'utf8'));
+            if (pkg.name)
+                packages.set(pkg.name, m.slice(0, -'package.json'.length));
+            collect(pkg.exports);
+        }
+        catch {
+            // unreadable manifest: its package just resolves through node_modules
+        }
+    }
+    const resolver = new ResolverFactory({
+        extensions: ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'],
+        extensionAlias: { '.js': ['.ts', '.tsx', '.js'], '.mjs': ['.mts', '.mjs'], '.cjs': ['.cts', '.cjs'] },
+        conditionNames: [...custom, 'source', 'node', 'import', 'require', 'default'],
+    });
+    const inRepo = (abs) => {
+        const rel = abs && relative(root, abs).split(sep).join('/');
+        return rel && !rel.startsWith('..') && !rel.includes('node_modules/') ? rel : undefined;
+    };
+    // Built output (dist/index.js) is what package exports point at once a build has run; an edit to src/ never reaches it.
+    // Map it back to the source file it was compiled from: dist/x.js -> src/x.ts, or x.ts when outDir mirrors the root.
+    const toSource = (rel) => {
+        for (const swap of ['$1src/', '$1']) {
+            const guess = rel.replace(BUILD_OUTPUT, swap).replace(/\.(d\.)?[cm]?js$/, '');
+            const hit = inRepo(resolver.sync(root, `./${guess}`).path);
+            if (hit && !BUILD_OUTPUT.test(hit))
+                return hit;
+        }
+    };
+    const sourceOf = (rel) => (rel && BUILD_OUTPUT.test(rel) ? toSource(rel) : rel);
+    const resolve = (abs, spec) => {
+        let rel = sourceOf(inRepo(resolver.resolveFileSync(abs, spec).path));
+        const pkgDir = rel ? undefined : packages.get(bareName(spec) ?? '');
+        if (pkgDir !== undefined) {
+            // Resolve as a self-reference from inside the package, which applies its exports with our conditions.
+            // Exports that point only at build output fall back to the same path under src/ or the package root,
+            // and failing that to the whole package.
+            const manifest = join(root, pkgDir, 'package.json');
+            const sub = spec.slice(bareName(spec).length);
+            rel =
+                sourceOf(inRepo(resolver.resolveFileSync(manifest, spec).path)) ??
+                    inRepo(resolver.resolveFileSync(manifest, `./src${sub}`).path) ??
+                    inRepo(resolver.resolveFileSync(manifest, `.${sub || '/index'}`).path) ??
+                    PKG + pkgDir;
+        }
+        return rel;
+    };
+    const infos = new Map();
+    for (const file of files) {
+        const abs = join(root, file);
+        let src;
+        try {
+            src = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseSync(file, src);
+        const info = { uses: new Map(), loads: new Set(), local: new Set(), reexports: [], pure: isPure(parsed.program) };
+        const resolved = new Map();
+        const target = (spec) => {
+            if (!resolved.has(spec))
+                resolved.set(spec, resolve(abs, spec));
+            const t = resolved.get(spec);
+            if (t)
+                info.loads.add(t);
+            return t;
+        };
+        // name: one export it asks for; ALL: the whole module (namespace import, require, dynamic import, mock).
+        const use = (spec, name) => {
+            const t = target(spec);
+            if (!t)
+                return;
+            const u = info.uses.get(t) ?? info.uses.set(t, { names: new Set(), all: false }).get(t);
+            if (name === ALL)
+                u.all = true;
+            else if (name)
+                u.names.add(name);
+        };
+        const mod = parsed.module;
+        for (const i of mod.staticImports) {
+            const live = i.entries.filter((e) => !e.isType);
+            if (i.entries.length && !live.length)
+                continue; // type-only imports are erased before tests run
+            if (!live.length)
+                use(i.moduleRequest.value); // import './setup': loads it for its effects
+            for (const e of live)
+                use(i.moduleRequest.value, e.importName.kind === 'Name' ? e.importName.name : e.importName.kind === 'Default' ? 'default' : ALL);
+        }
+        for (const e of mod.staticExports)
+            for (const entry of e.entries) {
+                if (entry.isType)
+                    continue;
+                const exported = entry.exportName.kind === 'Name' ? entry.exportName.name : entry.exportName.kind === 'Default' ? 'default' : ALL;
+                if (!entry.moduleRequest)
+                    info.local.add(exported);
+                else {
+                    const from = target(entry.moduleRequest.value);
+                    // export * as ns / export * : the whole module (all but default for the latter, which `definers` respects)
+                    if (from)
+                        info.reexports.push({ from, imported: entry.importName.kind === 'Name' ? entry.importName.name : ALL, exported });
+                }
+            }
+        for (const d of mod.dynamicImports) {
+            const text = src.slice(d.moduleRequest.start, d.moduleRequest.end);
+            if (/^['"`][^'"`$]*['"`]$/.test(text))
+                use(text.slice(1, -1), ALL);
+        }
+        for (const m of src.matchAll(EXTRA))
+            use(m[1], ALL);
+        infos.set(file, info);
+    }
+    const importers = new Map();
+    const nodes = new Set(files);
+    const edge = (target, from) => {
+        if (!target.startsWith(PKG) && !target.startsWith(FX))
+            nodes.add(target);
+        (importers.get(target) ?? importers.set(target, new Set()).get(target)).add(from);
+    };
+    const { definers, whole } = exportsIndex(infos);
+    for (const [file, info] of infos) {
+        if (!info.pure)
+            edge(file, FX + file);
+        for (const t of info.loads) {
+            if (t.startsWith(PKG)) {
+                edge(t, file);
+                continue;
+            }
+            // Loading t runs whatever t's loading does, so this file and its own load effects depend on it.
+            edge(FX + t, file);
+            edge(FX + t, FX + file);
+        }
+        for (const [t, u] of info.uses) {
+            edge(t, file);
+            if (t.startsWith(PKG))
+                continue;
+            const deps = u.all ? whole(t) : new Set([...u.names].flatMap((n) => [...(definers(t, n) ?? whole(t))]));
+            for (const d of deps)
+                edge(d, file);
+        }
+    }
+    for (const [key, from] of importers) {
+        if (!key.startsWith(PKG))
+            continue;
+        const pkgDir = key.slice(PKG.length);
+        // No package entry imports its tests, so a test change never flows through the package.
+        for (const n of nodes)
+            if (n.startsWith(pkgDir) && !TEST.test(n))
+                for (const f of from)
+                    (importers.get(n) ?? importers.set(n, new Set()).get(n)).add(f);
+        importers.delete(key);
+    }
+    return { tests: new Set(files.filter((f) => TEST.test(f))), importers, nodes, packages: packageDirs.sort((a, b) => b.length - a.length) };
+}
+const CODE_FILE = /\.[cm]?[jt]sx?$/;
+// Changes to these never affect test results. CI workflows change which commands run, not what tests read.
+// Lint, format and editor configs change how code is checked or shown, not what tests do.
+const INERT = new RegExp([
+    /\.(md|mdx|txt|png|jpe?g|gif|svg|ico|webp)$/,
+    /^(docs?|\.changeset|\.github)\//,
+    /(^|\/)(LICENSE|CHANGELOG)[^/]*$/,
+    /(^|\/)(\.vscode|\.idea)\//,
+    /(^|\/)(\.gitignore|\.editorconfig|\.?oxlintrc[^/]*|\.oxfmtrc[^/]*|biome\.jsonc?|\.eslintrc[^/]*|eslint\.config\.[^/]+|\.prettierrc[^/]*|prettier\.config\.[^/]+|\.prettierignore|knip\.jsonc?|\.lintstagedrc[^/]*|commitlint\.config\.[^/]+)$/,
+]
+    .map((r) => r.source)
+    .join('|'), 'i');
+const LOCKFILE = /(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?)$/;
+/**
+ * Test files a change can reach, or 'all' when we cannot tell (root config, root lockfile alone, unknown root files).
+ * A non-code file inside a workspace package (its manifest, tsconfig, fixtures, nested lockfile) affects that package only.
+ */
+export function affectedTests(graph, changed) {
+    const packageOf = (f) => graph.packages.find((p) => f.startsWith(p));
+    const changesManifests = changed.some((f) => f.endsWith('/package.json') && packageOf(f));
+    // Packages this change creates: nothing existing imports them, so only their own (changed, seeded) files matter.
+    const newPackages = changed
+        .filter((f) => /(^|\/)(package|deno|jsr)\.json$/.test(f) && f.includes('/'))
+        .map((f) => f.slice(0, f.lastIndexOf('/') + 1))
+        .filter((dir) => !graph.packages.includes(dir) && ![...graph.nodes].some((n) => n.startsWith(dir)));
+    const seen = new Set();
+    const queue = [];
+    const seed = (f) => {
+        if (!seen.has(f)) {
+            seen.add(f);
+            queue.push(f);
+        }
+    };
+    for (const f of changed) {
+        if (INERT.test(f))
+            continue;
+        if (graph.nodes.has(f))
+            seed(f);
+        else if (newPackages.some((dir) => f.startsWith(dir))) {
+            if (CODE_FILE.test(f))
+                seed(f);
+        }
+        // A code file the graph lacks is new in this change; only changed files can import it, and they are seeded too.
+        else if (CODE_FILE.test(f))
+            seed(f);
+        else if (packageOf(f)) {
+            const dir = packageOf(f);
+            for (const n of graph.nodes)
+                if (n.startsWith(dir))
+                    seed(n);
+        }
+        // estimate-only: a root lockfile changed alongside package manifests is those packages' dependency bump.
+        // A real cache must not rely on this; a bump can shift shared transitive dependencies.
+        else if (LOCKFILE.test(f) && changesManifests)
+            continue;
+        else
+            return 'all';
+    }
+    while (queue.length) {
+        for (const importer of graph.importers.get(queue.pop()) ?? []) {
+            if (!seen.has(importer)) {
+                seen.add(importer);
+                queue.push(importer);
+            }
+        }
+    }
+    return new Set([...seen].filter((f) => graph.tests.has(f) || (TEST.test(f) && !f.startsWith(FX))));
+}

package/dist/purity.js

@@ -0,0 +1,140 @@
+// Does loading a module do anything besides defining bindings? A barrel loads every file it re-exports, so a file
+// with load-time effects (registering handlers, patching globals, starting clients) can change a test that never
+// names it. Anything we cannot prove harmless counts as a side effect: a wrong "pure" means a wrongly skipped test.
+// Calls on these build values without touching anything else: Object.freeze({...}), new Map(), z.object({...}).
+const PURE_GLOBALS = ['Symbol', 'Object', 'Array', 'Number', 'String', 'Boolean', 'BigInt', 'Math', 'JSON', 'Map', 'Set', 'WeakMap', 'WeakSet', 'RegExp', 'Date', 'URL', 'Error', 'z'];
+// Libraries whose top-level calls define schemas, tables and styles: z.object(), pgTable(), cva().
+const PURE_LIBRARIES = /^(zod(\/.*)?|drizzle-orm(\/.*)?|valibot|@sinclair\/typebox(\/.*)?|yup|superstruct|arktype|io-ts|class-variance-authority)$/;
+// Methods that derive a new schema or column from an existing one: Base.extend({...}), uuid('id').notNull().
+const BUILDER_METHODS = new Set('extend merge pick omit partial deepPartial required optional nullable nullish array and or default describe brand catch readonly refine superRefine transform pipe strict passthrough strip min max length regex email url uuid int positive negative nonnegative nonpositive keyof element unwrap meta notNull primaryKey defaultRandom defaultNow references unique $type $defaultFn $onUpdate $onUpdateFn'.split(' '));
+// Set per file by isPure: globals plus names imported from PURE_LIBRARIES.
+let pureRoots = new Set(PURE_GLOBALS);
+const pureArgs = (e) => e.arguments.every((a) => pureExpr(a.type === 'SpreadElement' ? a.argument : a));
+// A call chain like z.object({...}).extend({...}).optional() is pure when it starts at a pure root and every call's
+// arguments are pure.
+function pureChain(e) {
+    switch (e.type) {
+        case 'Identifier':
+            return pureRoots.has(e.name);
+        case 'MemberExpression':
+            return pureChain(e.object) && (!e.computed || pureExpr(e.property));
+        case 'ChainExpression':
+            return pureChain(e.expression);
+        case 'CallExpression':
+        case 'NewExpression':
+            return pureArgs(e) && (pureChain(e.callee) || builderCall(e.callee));
+        default:
+            return false;
+    }
+}
+// OtherSchema.extend({...}).optional(): builder methods on any existing value, ending at a plain identifier.
+function builderCall(callee) {
+    if (callee.type !== 'MemberExpression' || callee.computed || !BUILDER_METHODS.has(callee.property.name))
+        return false;
+    const base = callee.object;
+    if (base.type === 'Identifier')
+        return true;
+    if (base.type === 'MemberExpression')
+        return !base.computed && (base.object.type === 'Identifier' || builderCall(base) || pureChain(base));
+    return (base.type === 'CallExpression' || base.type === 'NewExpression') && pureChain(base);
+}
+function pureClass(c) {
+    if (c.decorators?.length || (c.superClass && !pureExpr(c.superClass)))
+        return false;
+    return c.body.body.every((m) => {
+        if (m.type === 'StaticBlock' || m.decorators?.length)
+            return false;
+        if (m.computed && !pureExpr(m.key))
+            return false;
+        // Static field initializers run at load; instance ones only on `new`.
+        return !(m.static && m.value && m.type !== 'MethodDefinition' && !pureExpr(m.value));
+    });
+}
+export function pureExpr(e) {
+    if (!e)
+        return true;
+    switch (e.type) {
+        case 'Literal':
+        case 'Identifier':
+        case 'ThisExpression':
+        case 'MetaProperty':
+        case 'ArrowFunctionExpression':
+        case 'FunctionExpression':
+        case 'Super':
+            return true;
+        case 'TemplateLiteral':
+            return e.expressions.every(pureExpr);
+        case 'ClassExpression':
+            return pureClass(e);
+        case 'ObjectExpression':
+            return e.properties.every((p) => (p.type === 'SpreadElement' ? pureExpr(p.argument) : (!p.computed || pureExpr(p.key)) && pureExpr(p.value)));
+        case 'ArrayExpression':
+            return e.elements.every((x) => !x || pureExpr(x.type === 'SpreadElement' ? x.argument : x));
+        case 'UnaryExpression':
+            return e.operator !== 'delete' && pureExpr(e.argument);
+        case 'BinaryExpression':
+        case 'LogicalExpression':
+            return pureExpr(e.left) && pureExpr(e.right);
+        case 'ConditionalExpression':
+            return pureExpr(e.test) && pureExpr(e.consequent) && pureExpr(e.alternate);
+        case 'MemberExpression':
+            return pureExpr(e.object) && (!e.computed || pureExpr(e.property));
+        case 'ChainExpression':
+        case 'ParenthesizedExpression':
+        case 'TSAsExpression':
+        case 'TSSatisfiesExpression':
+        case 'TSNonNullExpression':
+        case 'TSTypeAssertion':
+        case 'TSInstantiationExpression':
+            return pureExpr(e.expression);
+        case 'CallExpression':
+        case 'NewExpression':
+            return pureChain(e);
+        case 'TaggedTemplateExpression':
+            // sql`now()` from drizzle-orm
+            return pureChain(e.tag) && e.quasi.expressions.every(pureExpr);
+        default:
+            return false;
+    }
+}
+function pureStatement(s) {
+    switch (s.type) {
+        case 'ImportDeclaration':
+        case 'ExportAllDeclaration':
+        case 'FunctionDeclaration':
+        case 'TSDeclareFunction':
+        case 'TSTypeAliasDeclaration':
+        case 'TSInterfaceDeclaration':
+        case 'TSEnumDeclaration':
+        case 'EmptyStatement':
+            return true;
+        case 'TSModuleDeclaration':
+            return Boolean(s.declare);
+        case 'ClassDeclaration':
+            return pureClass(s);
+        case 'VariableDeclaration':
+            return s.declarations.every((d) => pureExpr(d.init));
+        case 'ExportNamedDeclaration':
+            return !s.declaration || pureStatement(s.declaration);
+        case 'ExportDefaultDeclaration': {
+            const d = s.declaration;
+            return d.type === 'FunctionDeclaration' || d.type === 'TSInterfaceDeclaration' ? true : d.type === 'ClassDeclaration' ? pureClass(d) : pureExpr(d);
+        }
+        case 'TSExportAssignment':
+            return pureExpr(s.expression);
+        case 'ExpressionStatement':
+            // "use strict" and other directives
+            return Boolean(s.directive);
+        default:
+            return false;
+    }
+}
+/** True when the module's top level only defines bindings. */
+export function isPure(program) {
+    pureRoots = new Set(PURE_GLOBALS);
+    for (const s of program.body)
+        if (s.type === 'ImportDeclaration' && PURE_LIBRARIES.test(s.source.value))
+            for (const spec of s.specifiers)
+                pureRoots.add(spec.local.name);
+    return program.body.every(pureStatement);
+}

package/dist/report.js

@@ -0,0 +1,104 @@
+const LABELS = {
+    test: 'test',
+    install: 'install',
+    build: 'build',
+    lint: 'lint & typecheck',
+    setup: 'setup',
+    other: 'other',
+};
+export function summarize(r) {
+    const low = { minutes: r.repeated.minutes + r.affected.minutes, dollars: r.repeated.dollars + r.affected.dollars };
+    const high = { minutes: low.minutes + r.install.minutes, dollars: low.dollars + r.install.dollars };
+    const billable = r.billable;
+    const pct = (a) => (billable.minutes ? (100 * a.minutes) / billable.minutes : 0);
+    const notes = [];
+    if (r.analyzedRuns < r.totalRuns)
+        notes.push(`Sampled ${r.analyzedRuns} of ${r.totalRuns} runs per workflow across the ${r.days} days; each stands in for its workflow's runs around it.`);
+    if (r.analyzedRuns < r.totalRuns)
+        notes.push('Repeated runs of the same commit are only counted when every run is analyzed; re-runs of jobs that already passed still count.');
+    if (r.estimated)
+        notes.push("Some periods passed GitHub's 2,500-run count limit; their run counts are estimated from how closely runs are spaced.");
+    if (!r.isPrivate)
+        notes.push('Public repo: standard runners are free, so dollars are list-price value.');
+    if (r.selfHostedMinutes)
+        notes.push(`${Math.round(r.selfHostedMinutes)} self-hosted minutes are counted in minutes only.`);
+    if (r.shallow)
+        notes.push('This clone is shallow, so past changes cannot be replayed and affected-only savings show as 0. Run `git fetch --unshallow` and scan again.');
+    else if (r.missingCommits)
+        notes.push(`${r.missingCommits} commits could not be fetched (deleted forks or branches), so those runs count as no saving.`);
+    notes.push(`Affected-only tests replayed ${r.affected.replayed} of ${r.affected.codeRuns} push and PR runs against the current import graph (${r.testFiles} test files); runs we could not replay count as no saving.`);
+    notes.push('Dollars use GitHub list prices; larger runners are priced as 2-core.');
+    return {
+        billable,
+        queueMinutes: r.queueMinutes,
+        low,
+        high,
+        lowPct: pct(low),
+        highPct: pct(high),
+        parts: { repeated: r.repeated, affected: r.affected, install: r.install },
+        notes,
+    };
+}
+const min = (n) => `${Math.round(n).toLocaleString('en-US')} min`;
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+const both = (a) => `${min(a.minutes)} · ${usd(a.dollars)}`;
+// A range only when the ends differ once rounded; "7–7%" reads like a bug.
+const range = (lo, hi) => (lo === hi ? lo : `${lo}–${hi}`);
+const noRuns = (r) => `${r.repo} had no completed workflow runs in the last ${r.days} days. Try --days 90.`;
+function breakdown(r) {
+    const total = Object.values(r.categories).reduce((a, b) => a + b, 0) || 1;
+    return Object.entries(r.categories)
+        .sort((a, b) => b[1] - a[1])
+        .filter(([, v]) => v > 0)
+        .map(([k, v]) => ({ label: LABELS[k], share: (100 * v) / total }));
+}
+export function text(r) {
+    if (!r.analyzedRuns)
+        return noRuns(r);
+    const s = summarize(r);
+    const rows = breakdown(r).map(({ label, share }) => `  ${label.padEnd(17)}${share.toFixed(0).padStart(3)}%  ${'█'.repeat(Math.round(share / 4))}`);
+    return [
+        '',
+        `${r.repo} · last ${r.days} days · ${r.totalRuns} runs`,
+        `CI time: ${both(s.billable)}   (plus ${min(s.queueMinutes)} waiting in queue)`,
+        '',
+        'Where the time goes',
+        ...rows,
+        '',
+        `Estimated savings with ci-sdk: ${range(s.lowPct.toFixed(0), s.highPct.toFixed(0))}%  (${range(min(s.low.minutes), min(s.high.minutes))}, ${range(usd(s.low.dollars), usd(s.high.dollars))} per ${r.days} days)`,
+        `  repeated work        ${both(s.parts.repeated)}   same commit run again`,
+        `  affected-only tests  ${both(s.parts.affected)}   tests the change could not reach`,
+        `  install cache        ${both(s.parts.install)}   installs slower than your fastest 10%`,
+        '',
+        ...s.notes.map((n) => `  · ${n}`),
+        '',
+    ].join('\n');
+}
+export function markdown(r) {
+    if (!r.analyzedRuns)
+        return noRuns(r);
+    const s = summarize(r);
+    return [
+        `### CI scan: ${r.repo} (last ${r.days} days)`,
+        '',
+        `**${r.totalRuns} runs · ${both(s.billable)}** · estimated savings with ci-sdk: **${range(s.lowPct.toFixed(0), s.highPct.toFixed(0))}%** (${range(usd(s.low.dollars), usd(s.high.dollars))})`,
+        '',
+        '| Where the time goes | Share |',
+        '| --- | --- |',
+        ...breakdown(r).map(({ label, share }) => `| ${label} | ${share.toFixed(0)}% |`),
+        '',
+        '| Saving | Minutes · dollars |',
+        '| --- | --- |',
+        `| Repeated work | ${both(s.parts.repeated)} |`,
+        `| Affected-only tests | ${both(s.parts.affected)} |`,
+        `| Install cache | ${both(s.parts.install)} |`,
+        '',
+        ...s.notes.map((n) => `- ${n}`),
+        '',
+        '_Generated by `npx ci-sdk scan`. Runs locally; no data leaves your machine._',
+        '',
+    ].join('\n');
+}
+export function json(r) {
+    return JSON.stringify({ ...r, summary: summarize(r) }, null, 2);
+}

package/dist/scan.js

@@ -0,0 +1,157 @@
+import { execFileSync } from 'node:child_process';
+import { categorize, ratePerMinute } from './classify.js';
+import { getRepo, listJobs, listRuns, pool } from './github.js';
+import { affectedTests, buildGraph } from './graph.js';
+const ms = (a, b) => (a && b ? Math.max(0, Date.parse(b) - Date.parse(a)) : 0);
+const add = (x, minutes, rate) => {
+    x.minutes += minutes;
+    x.dollars += minutes * (rate ?? 0);
+};
+/** Pure estimate over fetched runs; `scan` handles I/O. */
+export function estimate(data, graph) {
+    const e = {
+        billable: { minutes: 0, dollars: 0 },
+        selfHostedMinutes: 0,
+        queueMinutes: 0,
+        categories: { setup: 0, install: 0, build: 0, lint: 0, test: 0, other: 0 },
+        repeated: { minutes: 0, dollars: 0 },
+        affected: { minutes: 0, dollars: 0, replayed: 0, codeRuns: 0 },
+        install: { minutes: 0, dollars: 0 },
+    };
+    const installs = data.flatMap((d) => d.jobs.flatMap((j) => (j.steps ?? []).map((s) => ms(s.started_at, s.completed_at)).filter((d, i) => categorize(j.steps[i].name, d) === 'install')));
+    const fastInstall = installs.sort((a, b) => a - b)[Math.floor(installs.length * 0.1)] ?? 0;
+    const seenRuns = new Set();
+    const ordered = [...data].sort((a, b) => Date.parse(a.run.created_at) - Date.parse(b.run.created_at));
+    for (const { run, jobs, changed, weight = 1 } of ordered) {
+        // Only code runs repeat cacheable work; comment, schedule and bot runs all sit on the default branch's head.
+        const isCode = run.event === 'push' || run.event === 'pull_request';
+        const key = `${run.workflow_id}:${run.event}:${run.head_sha}`;
+        // A sampled run stands for many, and spotting a repeat needs both runs in the sample: one lucky pair would swing
+        // the estimate by thousands of minutes. Only count repeats when every run is present (weight 1).
+        const repeatRun = isCode && weight === 1 && seenRuns.has(key);
+        seenRuns.add(key);
+        const affected = !repeatRun && changed && graph && graph.tests.size ? affectedTests(graph, changed) : undefined;
+        const skipShare = affected === undefined || affected === 'all' ? 0 : Math.max(0, 1 - affected.size / graph.tests.size);
+        if (affected !== undefined)
+            e.affected.replayed++;
+        if (isCode)
+            e.affected.codeRuns++;
+        const passedBefore = new Set();
+        for (const job of [...jobs].sort((a, b) => a.run_attempt - b.run_attempt)) {
+            const rate = ratePerMinute(job.labels);
+            const minutes = (weight * ms(job.started_at, job.completed_at)) / 60000;
+            const billable = weight * Math.ceil(minutes / weight);
+            add(e.billable, billable, rate);
+            if (rate === null)
+                e.selfHostedMinutes += billable;
+            e.queueMinutes += (weight * ms(job.created_at, job.started_at)) / 60000;
+            let testMs = 0;
+            let extraInstallMs = 0;
+            for (const step of job.steps ?? []) {
+                const d = ms(step.started_at, step.completed_at);
+                const cat = categorize(step.name, d);
+                e.categories[cat] += (weight * d) / 60000;
+                if (cat === 'test')
+                    testMs += d;
+                if (cat === 'install')
+                    extraInstallMs += Math.max(0, d - fastInstall);
+            }
+            // A repeated run, or a re-run of a job that already passed on the same commit, is a full cache hit.
+            if (repeatRun || passedBefore.has(job.name)) {
+                add(e.repeated, minutes, rate);
+                continue;
+            }
+            if (job.conclusion === 'success')
+                passedBefore.add(job.name);
+            add(e.affected, (weight * testMs * skipShare) / 60000, rate);
+            add(e.install, (weight * extraInstallMs) / 60000, rate);
+        }
+    }
+    return e;
+}
+const git = (root, args, input) => execFileSync('git', args, { cwd: root, encoding: 'utf8', input, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'], maxBuffer: 1 << 26 });
+const isShallow = (root) => {
+    try {
+        return git(root, ['rev-parse', '--is-shallow-repository']).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Commits the replay needs but this clone lacks (fork PRs, deleted branches), fetched by SHA: objects only, no refs.
+ * Returns how many are still missing.
+ */
+function fetchMissing(root, shas, log) {
+    const wanted = [...new Set(shas)];
+    const missing = () => git(root, ['cat-file', '--batch-check'], wanted.map((s) => `${s}^{commit}`).join('\n') + '\n')
+        .split('\n')
+        .filter((l) => l.endsWith(' missing'))
+        .map((l) => l.slice(0, 40));
+    const fetch = (list) => {
+        try {
+            git(root, ['fetch', '--quiet', '--no-tags', '--no-write-fetch-head', 'origin', ...list]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    let todo = missing();
+    if (!todo.length)
+        return 0;
+    log(`Fetching ${todo.length} commits this clone lacks…`);
+    for (let i = 0; i < todo.length; i += 200) {
+        const chunk = todo.slice(i, i + 200);
+        // One unknown SHA fails the whole batch, so retry those one by one.
+        if (!fetch(chunk))
+            for (const sha of chunk.slice(0, 100))
+                fetch([sha]);
+    }
+    todo = missing();
+    return todo.length;
+}
+function changedFiles(root, base, head) {
+    try {
+        const out = execFileSync('git', ['diff', '--name-only', `${base}...${head}`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return out.split('\n').filter(Boolean);
+    }
+    catch {
+        return undefined; // commit not in the local clone
+    }
+}
+/** What each run tested: the PR diff against its base, or a push diffed against the previous push run on that branch. */
+function attachChanges(root, data, defaultBranch) {
+    const ordered = [...data].sort((a, b) => Date.parse(a.run.created_at) - Date.parse(b.run.created_at));
+    const lastPush = new Map();
+    for (const d of ordered) {
+        const { run } = d;
+        if (run.event === 'pull_request') {
+            // Fork PRs come without pull_requests; their merge-base with the default branch gives the same diff.
+            d.changed = changedFiles(root, run.pull_requests[0]?.base.sha ?? `origin/${defaultBranch}`, run.head_sha);
+        }
+        else if (run.event === 'push') {
+            const branch = `${run.workflow_id}:${run.head_branch}`;
+            const prev = lastPush.get(branch);
+            if (prev && prev !== run.head_sha)
+                d.changed = changedFiles(root, prev, run.head_sha);
+            lastPush.set(branch, run.head_sha);
+        }
+    }
+}
+export async function scan(o) {
+    const since = new Date(Date.now() - o.days * 864e5);
+    const info = await getRepo(o.repo, o.token);
+    o.log(`Fetching workflow runs for ${info.full_name} since ${since.toISOString().slice(0, 10)}…`);
+    const { runs, total, estimated } = await listRuns(o.repo, o.token, since, o.maxRuns);
+    o.log(`Fetching jobs for ${runs.length} runs sampled from ${total}…`);
+    const data = await pool(runs, 8, async ({ run, weight }) => ({ run, weight, jobs: await listJobs(o.repo, run.id, o.token) }));
+    o.log('Building import graph with oxc…');
+    const graph = await buildGraph(o.root);
+    const shallow = isShallow(o.root);
+    const code = data.filter((d) => d.run.event === 'push' || d.run.event === 'pull_request');
+    const missingCommits = shallow ? 0 : fetchMissing(o.root, code.flatMap((d) => [d.run.head_sha, ...d.run.pull_requests.map((p) => p.base.sha)]), o.log);
+    attachChanges(o.root, data, info.default_branch);
+    const e = estimate(data, graph);
+    return { repo: info.full_name, isPrivate: info.private, days: o.days, totalRuns: total, estimated, analyzedRuns: runs.length, testFiles: graph.tests.size, shallow, missingCommits, ...e };
+}

package/dist/test.js

@@ -0,0 +1,101 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { affectedTests, buildGraph } from './graph.js';
+const git = (root, args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1 << 26 });
+const lines = (s) => s.split('\n').filter(Boolean);
+export const repoRoot = (cwd) => git(cwd, ['rev-parse', '--show-toplevel']).trim();
+/** Files changed since `since` (committed on this branch), plus uncommitted and untracked changes. */
+export function changedFiles(root, since = 'HEAD') {
+    const committed = since === 'HEAD' ? [] : lines(git(root, ['diff', '--name-only', `${since}...HEAD`]));
+    return [...new Set([...committed, ...lines(git(root, ['diff', '--name-only', 'HEAD'])), ...lines(git(root, ['ls-files', '--others', '--exclude-standard']))])];
+}
+const packageManager = (root) => existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : existsSync(join(root, 'bun.lock')) || existsSync(join(root, 'bun.lockb')) ? 'bun' : 'npm';
+// How each package manager appends extra arguments to a package script.
+const runScript = (pm, script, args) => (pm === 'npm' ? ['npm', ['run', script, '--', ...args]] : [pm, ['run', script, ...args]]);
+const readJson = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Affected test files grouped by the workspace package that owns them, each run through that package's own test script. */
+export function plan(root, graph, tests) {
+    const byDir = new Map();
+    for (const t of tests) {
+        const dir = graph.packages.find((p) => t.startsWith(p)) ?? '';
+        (byDir.get(dir) ?? byDir.set(dir, []).get(dir)).push(t.slice(dir.length));
+    }
+    return [...byDir]
+        .map(([dir, files]) => {
+        const pkg = readJson(join(root, dir, 'package.json'));
+        // A root script that fans out to every package (turbo, nx, lerna, pnpm -r) can't be narrowed to files.
+        const script = pkg?.scripts?.test ?? '';
+        const fansOut = !dir && /\b(turbo|nx|lerna)\b|\s-r\b|--recursive|--workspaces?\b/.test(script);
+        return { dir, name: pkg?.name ?? (dir || '(root)'), files: files.sort(), hasTestScript: Boolean(script) && !fansOut };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Turbo repos whose test task depends on ^build test against built dependencies, so rebuild those first (cached when unchanged). */
+function buildCommand(root, pm, runs) {
+    const deps = readJson(join(root, 'turbo.json'))?.tasks?.test?.dependsOn ?? [];
+    if (!deps.includes('^build'))
+        return undefined;
+    const filters = runs.filter((r) => r.dir).map((r) => `--filter=${r.name}^...`);
+    if (!filters.length)
+        return undefined;
+    return pm === 'npm' ? ['npx', ['turbo', 'run', 'build', ...filters]] : [pm, ['exec', 'turbo', 'run', 'build', ...filters]];
+}
+/** Runs only the tests a change can reach. Returns the process exit code. */
+export async function testAffected(o) {
+    const root = repoRoot(o.cwd);
+    const changed = changedFiles(root, o.since);
+    if (!changed.length) {
+        o.log(`No changes since ${o.since ?? 'HEAD'}; nothing to test.`);
+        return 0;
+    }
+    const graph = await buildGraph(root);
+    const affected = affectedTests(graph, changed);
+    const pm = packageManager(root);
+    const exec = ([cmd, args], cwd) => {
+        o.log(`$ ${cmd} ${args.join(' ')}${cwd === root ? '' : `   (in ${cwd.slice(root.length + 1)})`}`);
+        return spawnSync(cmd, args, { cwd, stdio: 'inherit' }).status ?? 1;
+    };
+    if (affected === 'all') {
+        const why = changed.filter((f) => affectedTests(graph, [f]) === 'all');
+        o.log(`${changed.length} changed files; ${why.slice(0, 3).join(', ')} can affect every test, so running the full suite.`);
+        if (o.list) {
+            for (const t of [...graph.tests].sort())
+                console.log(t);
+            return 0;
+        }
+        return exec(runScript(pm, 'test', []), root);
+    }
+    const runs = plan(root, graph, affected);
+    o.log(`${changed.length} changed files → ${affected.size} of ${graph.tests.size} test files in ${runs.length} packages`);
+    if (o.list) {
+        for (const t of [...affected].sort())
+            console.log(t);
+        return 0;
+    }
+    if (!affected.size)
+        return 0;
+    const build = buildCommand(root, pm, runs);
+    if (build && exec(build, root) !== 0) {
+        o.log('Building dependencies failed; not running tests.');
+        return 1;
+    }
+    let failed = 0;
+    for (const r of runs) {
+        if (!r.hasTestScript) {
+            o.log(`${r.name} has no test script that runs single files; skipped ${r.files.length} test files: ${r.files.slice(0, 3).join(', ')}`);
+            continue;
+        }
+        if (exec(runScript(pm, 'test', r.files), join(root, r.dir)) !== 0)
+            failed++;
+    }
+    o.log(failed ? `${failed} of ${runs.length} packages had failing tests.` : `All affected tests passed (${affected.size} of ${graph.tests.size} test files).`);
+    return failed ? 1 : 0;
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "ci-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Insanely fast CI. No migration. By Diffling.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://ci-sdk.com",
+  "bin": {
+    "ci-sdk": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "oxc-parser": "^0.156.0",
+    "oxc-resolver": "^11.24.2",
+    "tinyglobby": "^0.2.17"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  }
+}