willfire 0.1.9 → 0.1.11

package/README.md

@@ -20,10 +20,14 @@ pnpm add willfire
 import { predict } from "willfire";
 import { getOctokit } from "@actions/github"; // or new Octokit({ auth: token })
 
-const { entries, checkNames, skip } = await predict(getOctokit(token), "owner/repo", 123, {
-  action: context.payload.action, // "opened" | "synchronize" | "reopened"
-});
+const { entries, checkNames, skip, sources } = await predict(
+  getOctokit(token),
+  "owner/repo",
+  123,
+  { action: context.payload.action }, // "opened" | "synchronize" | "reopened"
+);
 // checkNames: sorted, deduped checkName of every entry with status "run"
+// sources: every repo read, and the commit each ref resolved to
 ```
 
 `action` is optional but worth passing. Omitted, the event action is inferred
@@ -50,13 +54,25 @@ 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;
 - a `name:` interpolating something we cannot evaluate statically.
 
+`sources` is the provenance of the answer: the PR's own repo at the head
+commit, then one entry per cross-repo `uses:` that was read, each carrying both
+the `ref` the workflow wrote and the `sha` it resolved to. A ref is resolved
+before the file behind it is read, so the commit named is the commit used. `v0`
+is a tag someone moves; without the sha, "willfire predicted these checks" is
+not a claim that can be checked against the run afterwards.
+
+A ref that will not resolve is not a source. Its callee is never read, the jobs
+behind it come back `unknown`, and nothing falls back to reading the mutable
+ref.
+
 Duplicate names in `checkNames` are not possible (it is a set), but duplicate
 check names *are* — GitHub happily creates two identically named checks when a
 matrix job's `name:` does not vary per combination. `entries` shows them.
@@ -68,9 +84,13 @@ 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`
+line per source. `--json` prints the whole `Prediction`, `sources` included.
+
 ## What it handles
 
 Path filters (`paths`, `paths-ignore`, order-sensitive `!` negation), branch
@@ -78,12 +98,91 @@ filters, event `types`, combined filters, `[skip ci]` and friends, disabled
 workflows, multi-job workflows, static matrix expansion (including
 `exclude`/`include`), `needs` skip-propagation, job-level `if`, and reusable
 workflows — both the local `./.github/workflows/x.yml` form and the cross-repo
-`owner/repo/.github/workflows/x.yml@ref` form, whose callee is fetched from its
-own repo at the pinned tag, branch, or SHA. Jobs whose `if` is false are
+`owner/repo/.github/workflows/x.yml@ref` form, whose ref is resolved to a
+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/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 "./predict.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;