willfire 0.1.10 → 0.1.12

package/README.md

@@ -54,8 +54,9 @@ workflows all applied. That is the unit required status checks key on, so it
 is the one worth comparing against. On a `JobEntry` it is `null` only where no
 single name is knowable ahead of the run:
 
-- a matrix computed at runtime (`fromJSON` of another job's output), reported
-  as one `unknown` entry for that job and nothing else;
+- a matrix computed at runtime (`fromJSON` of another job's output) whose
+  outputs were not supplied, reported as one `unknown` entry for that job and
+  nothing else — see "Supplying job outputs" below;
 - a reusable workflow we cannot read — private, deleted, a ref that does not
   exist, a `uses:` built from an expression, or one nested past GitHub's
   four-level limit;
@@ -83,7 +84,8 @@ Auth is any token with `contents: read`, `actions: read`, and
 
 ```sh
 GH_TOKEN=... willfire --repo owner/repo --pr 123 \
-  [--action opened|synchronize|reopened] [--json]
+  [--action opened|synchronize|reopened] [--json] \
+  [--execute owner/repo:job1,job2]...
 ```
 
 Plain-text output is one line per entry, then a `# read owner/repo@ref -> sha`
@@ -100,8 +102,87 @@ workflows — both the local `./.github/workflows/x.yml` form and the cross-repo
 commit and the callee then read at that commit. Jobs whose `if` is false are
 predicted as `skipped` entries, matching how they appear in the checks UI.
 
-Things that cannot be known statically — e.g. a matrix computed at runtime
-from another job's output — are reported as `unknown` rather than guessed.
+Things that cannot be known statically are reported as `unknown` rather than
+guessed.
+
+## Supplying job outputs
+
+A matrix built from another job's output is the common way a workflow decides
+its own check names:
+
+```yaml
+strategy:
+  matrix:
+    language: ${{ fromJSON(needs.detect.outputs.coverage_languages) }}
+```
+
+Given those outputs, willfire expands it. `expandWorkflowJobs` takes a `scope`
+whose `needs` maps a job id to its outputs:
+
+```ts
+await expandWorkflowJobs(wf, ctx, fetchWorkflow, source, {
+  needs: { detect: { outputs: { coverage_languages: '["typescript"]' } } },
+});
+```
+
+Values are raw strings — what a step wrote to `$GITHUB_OUTPUT`, and what the
+runner substitutes. Parsing them here would break the guards written against
+them: `!= '[]'` compares a string to a string, and an array on the left makes
+it unknown. `fromJSON` is the only thing that turns one into a structure.
+
+`outputs` must be the job's *complete* output set, because a key absent from it
+reads as the empty string — the same answer the runner gives for an output no
+step wrote. A job you know nothing about belongs left out entirely; every
+lookup against it then stays unknown.
+
+`needs` is workflow-scoped and is not inherited across a reusable-workflow
+call: a callee's `needs.detect` is the callee's own job.
+
+Nothing in willfire works out what those outputs are on its own. `predict`
+supplies none unless the caller grants execution — see below — so a dynamic
+matrix stays `unknown` by default.
+
+## Executing granted jobs
+
+The job those outputs come from is usually a few shell steps over the checked
+out tree — cheap to run for real. `predict` will do that, but only for jobs
+the caller names:
+
+```ts
+await predict(octokit, "owner/repo", 123, {
+  execute: [{ repo: "the-org/conventions", jobs: ["detect"] }],
+});
+```
+
+```sh
+willfire --repo owner/repo --pr 123 \
+  --execute the-org/conventions:detect
+```
+
+A grant names the repo the workflow *file* lives in — for a reusable workflow,
+the callee — and the job ids within it. Before expansion reads `needs`, each
+granted job that is predicted to run is executed: the PR's head tree is
+materialized from a tarball, the job's steps run in order under their declared
+shell and env, step-level `if:` guards are evaluated, composite actions are
+fetched at their pinned commit and recursed into, and a bare
+`actions/checkout` is satisfied by the tree already present. What the steps
+write to `$GITHUB_OUTPUT` becomes the job's outputs, exactly as if they had
+been supplied by hand.
+
+Execution is mechanism, not policy: willfire knows nothing about any repo, and
+with no grants nothing runs. The steps execute for real — nothing interprets
+or approximates shell — so grant only jobs whose code you trust at the commit
+being predicted; a granted job runs the PR's version of itself.
+
+Anything execution cannot do faithfully fails the grant rather than guessing:
+a JavaScript or Docker action, a checkout with inputs, a matrix'd or
+containerized granted job, an undecidable step `if:`, a non-zero exit, output
+willfire cannot parse. The failure does not change any verdict — entries that
+needed the outputs stay `unknown`, with the reason threaded through:
+
+```
+dynamic matrix; executing 'detect' failed: step 'scan': exited 1 (...)
+```
 
 ## Development
 

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export { parseArgs } from "./parseArgs.js";

package/dist/cli/index.js

@@ -0,0 +1 @@
+export { parseArgs } from "./parseArgs.js";

package/dist/cli/parseArgs.d.ts

@@ -0,0 +1,9 @@
+import { type ExecutionGrant } from "../execute.js";
+import type { PrEventAction } from "../types.js";
+export declare function parseArgs(argv: string[]): {
+    repo: string;
+    pr: number;
+    json: boolean;
+    action?: PrEventAction;
+    execute: ExecutionGrant[];
+};

package/dist/cli/parseArgs.js

@@ -0,0 +1,42 @@
+import { parseGrant } from "../execute.js";
+const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened]" +
+    " [--execute owner/repo:job1,job2]... [--json]";
+const isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
+export function parseArgs(argv) {
+    const get = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const repo = get("--repo");
+    const pr = get("--pr");
+    if (!repo || !pr) {
+        console.error(USAGE);
+        process.exit(2);
+    }
+    // An unrecognised action is refused rather than ignored. Silently falling
+    // back to the guess would turn a typo into a wrong prediction, which is the
+    // failure this flag exists to remove.
+    const action = get("--action");
+    if (action !== undefined && !isPrEventAction(action)) {
+        console.error(`unknown --action: ${action}`);
+        console.error(USAGE);
+        process.exit(2);
+    }
+    // Repeatable, one grant per flag. A malformed grant is refused for the same
+    // reason a bad --action is: silently dropping it would predict without the
+    // execution the caller thought they asked for.
+    const execute = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] !== "--execute")
+            continue;
+        const spec = argv[i + 1];
+        const grant = spec == null ? null : parseGrant(spec);
+        if (grant == null) {
+            console.error(`bad --execute: ${spec}`);
+            console.error(USAGE);
+            process.exit(2);
+        }
+        execute.push(grant);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action, execute };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Usage: pnpm predict --repo owner/name --pr N [--json]
+//
+// Auth: GH_TOKEN or GITHUB_TOKEN env var (any token with
+// contents/actions/pull-requests read). Inside an action, pass the workflow's
+// GITHUB_TOKEN.
+import { parseArgs } from "./cli/parseArgs.js";
+import { isWorkflowEntry } from "./entries/isWorkflowEntry.js";
+import { makeOctokit } from "./predict/makeOctokit.js";
+import { predict } from "./predict/predict.js";
+const isMain = /cli\.(ts|js)$|\/willfire$/.test(process.argv[1] ?? "");
+if (isMain) {
+    const args = parseArgs(process.argv.slice(2));
+    const prediction = await predict(makeOctokit(), args.repo, args.pr, {
+        action: args.action,
+        execute: args.execute,
+    });
+    const { entries, skip, sources } = prediction;
+    if (args.json) {
+        console.log(JSON.stringify(prediction, null, 2));
+    }
+    else {
+        if (skip) {
+            console.log(`# ${skip} -> nothing dispatches`);
+        }
+        else {
+            for (const e of entries) {
+                if (isWorkflowEntry(e))
+                    console.log(`# ${e.workflow} :: ${e.status} (${e.reason})`);
+                else {
+                    const name = e.checkName ?? `${e.job} (name unresolved)`;
+                    console.log(`${e.workflow} :: ${name} :: ${e.status}`);
+                }
+            }
+        }
+        // Last, and on the skip path too, so a red gate's first question — which
+        // commits was this read from? — is answered wherever the reader lands.
+        for (const s of sources)
+            console.log(`# read ${s.owner}/${s.repo}@${s.ref} -> ${s.sha}`);
+    }
+}

package/dist/entries/index.d.ts

@@ -0,0 +1,3 @@
+export { jobName } from "./jobName.js";
+export { isWorkflowEntry } from "./isWorkflowEntry.js";
+export { isJobEntry } from "./isJobEntry.js";

package/dist/entries/index.js

@@ -0,0 +1,3 @@
+export { jobName } from "./jobName.js";
+export { isWorkflowEntry } from "./isWorkflowEntry.js";
+export { isJobEntry } from "./isJobEntry.js";

package/dist/entries/isJobEntry.d.ts

@@ -0,0 +1,3 @@
+import type { Entry, JobEntry } from "../types.js";
+/** Narrow to the job-level variant without inspecting the sentinel. */
+export declare const isJobEntry: (e: Entry) => e is JobEntry;

package/dist/entries/isJobEntry.js

@@ -0,0 +1,2 @@
+/** Narrow to the job-level variant without inspecting the sentinel. */
+export const isJobEntry = (e) => e.job !== "*";

package/dist/entries/isWorkflowEntry.d.ts

@@ -0,0 +1,3 @@
+import type { Entry, WorkflowEntry } from "../types.js";
+/** Narrow to the workflow-level variant without inspecting the sentinel. */
+export declare const isWorkflowEntry: (e: Entry) => e is WorkflowEntry;

package/dist/entries/isWorkflowEntry.js

@@ -0,0 +1,2 @@
+/** Narrow to the workflow-level variant without inspecting the sentinel. */
+export const isWorkflowEntry = (e) => e.job === "*";

package/dist/entries/jobName.d.ts

@@ -0,0 +1,3 @@
+import type { JobName } from "../types.js";
+/** Tag a job display name. Rejects the workflow-level sentinel. */
+export declare const jobName: <S extends string>(name: S extends "*" ? never : S) => JobName;

package/dist/entries/jobName.js

@@ -0,0 +1,2 @@
+/** Tag a job display name. Rejects the workflow-level sentinel. */
+export const jobName = (name) => name;

package/dist/execute.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Execute a job the caller granted, to learn what static reading cannot.
+ *
+ * A dynamic matrix — `language: ${{ fromJSON(needs.detect.outputs.x) }}` — is
+ * the values another job computes at runtime. No amount of reading the YAML
+ * yields them; the fleet's `detect` job runs a script over the repo tree and
+ * writes what it finds to `$GITHUB_OUTPUT`. So this module runs that job the
+ * way the runner would: materialize the tree at the pinned commit, walk the
+ * steps in order, execute each `run:` under its declared shell and env, and
+ * assemble the job's `outputs:` map from what the steps actually wrote.
+ *
+ * Three rules keep this honest:
+ *
+ * 1. **Nothing runs without a grant.** willfire has no opinion about which
+ *    jobs are safe to execute; the caller names them, one repo and job id at
+ *    a time, and everything else stays as unresolved as it was.
+ * 2. **Run it, never interpret it.** The `run:` script is handed to the shell
+ *    the step declares, with the env it declares. What lands in
+ *    `$GITHUB_OUTPUT` is the answer; no shell text is ever parsed for meaning.
+ * 3. **Anything off the modelled path is a hard stop with a reason.** A
+ *    JavaScript action, an undecidable `if:`, a `${{ }}` that will not
+ *    resolve, a step that exits non-zero — each fails the execution and says
+ *    what it hit, and the consumers of that job's outputs stay unresolved.
+ *    Guessing is the one move this module never makes.
+ *
+ * `actions/checkout` is the deliberate exception to rule 2. It is provided by
+ * the runner, not run from its repo, and its whole postcondition — the
+ * workspace tree at the commit under test — is something the executor has
+ * already satisfied by materializing the tree. A bare checkout is therefore
+ * recorded as done; a checkout *with inputs* is not modelled and stops.
+ */
+import { type Scope } from "./expr.js";
+import type { ResolveRef, WorkflowSource } from "./types.js";
+/**
+ * Permission to execute named jobs from one repo's workflows.
+ *
+ * `repo` is the repo the *workflow file* lives in — for a fleet consumer
+ * calling `testing-conventions/.github/workflows/testing-conventions.yml@v0`,
+ * that is `thekevinscott/testing-conventions`, whatever repo the PR is on.
+ * The grant is deliberately this narrow: a job id alone would execute
+ * whatever any transitively-reached workflow happens to call by that name.
+ */
+export interface ExecutionGrant {
+    /** `owner/name` of the repo whose workflow defines the jobs. */
+    repo: string;
+    /** Job ids within that repo's workflows that may be executed. */
+    jobs: string[];
+}
+/** `owner/repo:job1,job2` as the CLI spells a grant. */
+export declare function parseGrant(spec: string): ExecutionGrant | null;
+/** One shell invocation, fully specified — nothing is inherited implicitly. */
+export interface RunSpec {
+    script: string;
+    shell: "bash" | "sh";
+    cwd: string;
+    env: Record<string, string>;
+}
+export interface RunResult {
+    code: number;
+    /** Captured so a failing step can say *why* in its reason. */
+    stderr: string;
+}
+export type RunCommand = (spec: RunSpec) => Promise<RunResult>;
+/**
+ * Materialize a repo tree at a commit and return its root directory, or null
+ * when it cannot be had. Must not throw.
+ */
+export type ProvideTree = (source: WorkflowSource) => Promise<string | null>;
+/** The three reaches into the world an execution needs, bundled for injection. */
+export interface ExecDeps {
+    provideTree: ProvideTree;
+    runCommand: RunCommand;
+    resolveRef: ResolveRef;
+}
+export type ExecOutcome = {
+    ok: true;
+    outputs: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * What expansion asks of an executor. The caller decides *whether* a job
+ * runs with its own scope — the executor only decides what running it
+ * yields. Step-level guards inside the job are evaluated here, against the
+ * fixed facts of the run (notably `github.repository`, which the fleet's
+ * hermetic-vs-published guards are written against).
+ */
+export interface JobExecutor {
+    granted(source: WorkflowSource, jobId: string): boolean;
+    executeJob(jobId: string, job: any, wf: any, scope: Scope): Promise<ExecOutcome>;
+}
+/**
+ * The `$GITHUB_OUTPUT` file format: `name=value` lines, or a
+ * `name<<DELIMITER … DELIMITER` heredoc for multi-line values. Anything else
+ * fails the parse — the runner fails the step on a malformed line, so
+ * tolerating one here would invent outputs a real run never had.
+ */
+export declare function parseGithubOutput(text: string): Record<string, string> | null;
+export declare function makeExecutor(opts: {
+    grants: ExecutionGrant[];
+    /**
+     * The PR's own repo at the head commit — what `actions/checkout` provides
+     * on a real runner, wherever the workflow file itself lives. A reusable
+     * workflow's jobs run in the caller's workspace; this is that fact.
+     */
+    workspace: WorkflowSource;
+    deps: ExecDeps;
+}): JobExecutor;
+/**
+ * The runner's default shell invocations, faithfully: `bash --noprofile
+ * --norc -e -o pipefail` and `sh -e`. Nothing of the parent environment
+ * leaks in beyond what the spec names.
+ */
+export declare const runShell: RunCommand;
+/**
+ * Materialize repo trees from tarballs, one download per commit however many
+ * steps ask. GitHub's tarballs wrap the tree in a single
+ * `owner-repo-shortsha/` directory, which is unwrapped so callers get the
+ * tree root itself. Extraction shells out to `tar` through the same
+ * `RunCommand` seam every other subprocess uses.
+ */
+export declare function makeTreeProvider(download: (source: WorkflowSource) => Promise<Uint8Array | null>, runCommand: RunCommand): ProvideTree;