willfire 0.1.36 → 0.1.38

package/dist/cli/parseArgs.js

@@ -11,9 +11,8 @@ export function parseArgs(argv) {
         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.
+    // Refused, not ignored: falling back to the guess would turn a typo into a
+    // wrong prediction, the failure this flag exists to remove.
     const action = get("--action");
     if (action !== undefined && !isPrEventAction(action)) {
         console.error(`unknown --action: ${action}`);

package/dist/cli.js

@@ -1,9 +1,6 @@
 #!/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.
+// Auth: GH_TOKEN or GITHUB_TOKEN, needing contents/actions/pull-requests read.
 import { parseArgs } from "./cli/parseArgs.js";
 import { isWorkflowEntry } from "./entries/isWorkflowEntry.js";
 import { makeGithubClient } from "./predict/makeGithubClient.js";
@@ -33,8 +30,8 @@ if (isMain) {
                 }
             }
         }
-        // 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.
+        // Last, and on the skip path too, so a red gate's reader always sees which
+        // commits this was read from.
         for (const s of sources) {
             console.log(`# read ${s.owner}/${s.repo}@${s.ref} -> ${s.sha}`);
         }

package/dist/expr/applyFunction.d.ts

@@ -1,11 +1,7 @@
 import { type Val } from "./val.js";
 /**
- * The functions worth modelling.
- *
- * `always()` is true by definition. `contains` on two known strings is the one
- * that unlocks the fleet's `gates` pattern. `fromJSON` is what a dynamic matrix
- * axis is built out of. `success()`, `failure()` and `cancelled()` depend on
- * jobs that have not run, and everything else is simply not modelled — all
- * unknown.
+ * `always()` is true by definition and `fromJSON` is what a dynamic matrix axis
+ * is built out of. The job-status functions depend on jobs that have not run,
+ * so they are unknown — as is every function not modelled here.
  */
 export declare function applyFunction(name: string, args: Val[]): Val;

package/dist/expr/applyFunction.js

@@ -2,13 +2,9 @@ import { asBool } from "./asBool.js";
 import { fromJson } from "./fromJson.js";
 import { UNKNOWN } from "./val.js";
 /**
- * The functions worth modelling.
- *
- * `always()` is true by definition. `contains` on two known strings is the one
- * that unlocks the fleet's `gates` pattern. `fromJSON` is what a dynamic matrix
- * axis is built out of. `success()`, `failure()` and `cancelled()` depend on
- * jobs that have not run, and everything else is simply not modelled — all
- * unknown.
+ * `always()` is true by definition and `fromJSON` is what a dynamic matrix axis
+ * is built out of. The job-status functions depend on jobs that have not run,
+ * so they are unknown — as is every function not modelled here.
  */
 export function applyFunction(name, args) {
     if (name === "always") {

package/dist/expr/asBool.d.ts

@@ -1,10 +1,7 @@
 import { type Val } from "./val.js";
 /**
- * Wrap a decided answer as a concrete boolean value.
- *
- * Comparison, negation and the string functions all yield a real boolean, so
- * they produce a `value` — which keeps `!x == true` comparable. Only
- * short-circuiting produces the bare `truthy`/`falsy` points, because that is
- * the one case where truthiness is known and the value is not.
+ * A `value`, not a bare `truthy`/`falsy`, so `!x == true` stays comparable.
+ * Short-circuiting is the only producer of those points: it is the one case
+ * where truthiness is known and the value is not.
  */
 export declare function asBool(b: boolean | null): Val;

package/dist/expr/asBool.js

@@ -1,11 +1,8 @@
 import { UNKNOWN } from "./val.js";
 /**
- * Wrap a decided answer as a concrete boolean value.
- *
- * Comparison, negation and the string functions all yield a real boolean, so
- * they produce a `value` — which keeps `!x == true` comparable. Only
- * short-circuiting produces the bare `truthy`/`falsy` points, because that is
- * the one case where truthiness is known and the value is not.
+ * A `value`, not a bare `truthy`/`falsy`, so `!x == true` stays comparable.
+ * Short-circuiting is the only producer of those points: it is the one case
+ * where truthiness is known and the value is not.
  */
 export function asBool(b) {
     return b === null ? UNKNOWN : { kind: "value", v: b };

package/dist/expr/coalesceAnd.d.ts

@@ -1,7 +1,6 @@
 import { type Val } from "./val.js";
 /**
- * `A && B`. Short-circuits from either side: a falsy left decides it, and so
- * does a falsy right, because a truthy left would then yield the falsy right.
- * Only "left unknown, right not falsy" is genuinely undecided.
+ * Short-circuits from either side: a falsy right decides it too, because a
+ * truthy left would then yield that falsy right.
  */
 export declare function coalesceAnd(left: Val, right: Val): Val;

package/dist/expr/coalesceAnd.js

@@ -1,9 +1,8 @@
 import { truthy } from "./truthy.js";
 import { UNKNOWN } from "./val.js";
 /**
- * `A && B`. Short-circuits from either side: a falsy left decides it, and so
- * does a falsy right, because a truthy left would then yield the falsy right.
- * Only "left unknown, right not falsy" is genuinely undecided.
+ * Short-circuits from either side: a falsy right decides it too, because a
+ * truthy left would then yield that falsy right.
  */
 export function coalesceAnd(left, right) {
     const l = truthy(left);

package/dist/expr/coalesceOr.d.ts

@@ -1,6 +1,6 @@
 import { type Val } from "./val.js";
 /**
- * `A || B`. The mirror image: a truthy left decides it, and so does a truthy
- * right, since a falsy left would then yield the truthy right.
+ * Short-circuits from either side: a truthy right decides it too, since a falsy
+ * left would then yield that truthy right.
  */
 export declare function coalesceOr(left: Val, right: Val): Val;

package/dist/expr/coalesceOr.js

@@ -1,8 +1,8 @@
 import { truthy } from "./truthy.js";
 import { UNKNOWN } from "./val.js";
 /**
- * `A || B`. The mirror image: a truthy left decides it, and so does a truthy
- * right, since a falsy left would then yield the truthy right.
+ * Short-circuits from either side: a truthy right decides it too, since a falsy
+ * left would then yield that truthy right.
  */
 export function coalesceOr(left, right) {
     const l = truthy(left);

package/dist/expr/compare.d.ts

@@ -1,12 +1,7 @@
 import { type Val } from "./val.js";
 /**
- * Comparison, deliberately narrow: both sides must be concrete and of the same
- * primitive type.
- *
- * GitHub coerces across types when it compares, and the corner cases are
- * genuinely surprising (`'' == 0` is true). Every comparison that matters in
- * practice is string-to-string — `inputs.gates == ''`,
- * `github.event_name == 'pull_request'` — so modelling the coercion table
- * would add risk without adding reach. Mixed types return unknown.
+ * Both sides must be concrete and of the same primitive type. GitHub coerces
+ * across types and the corner cases surprise (`'' == 0` is true), so modelling
+ * that table would add risk without reach. Mixed types return unknown.
  */
 export declare function compare(op: string, left: Val, right: Val): Val;

package/dist/expr/compare.js

@@ -1,14 +1,9 @@
 import { asBool } from "./asBool.js";
 import { UNKNOWN } from "./val.js";
 /**
- * Comparison, deliberately narrow: both sides must be concrete and of the same
- * primitive type.
- *
- * GitHub coerces across types when it compares, and the corner cases are
- * genuinely surprising (`'' == 0` is true). Every comparison that matters in
- * practice is string-to-string — `inputs.gates == ''`,
- * `github.event_name == 'pull_request'` — so modelling the coercion table
- * would add risk without adding reach. Mixed types return unknown.
+ * Both sides must be concrete and of the same primitive type. GitHub coerces
+ * across types and the corner cases surprise (`'' == 0` is true), so modelling
+ * that table would add risk without reach. Mixed types return unknown.
  */
 export function compare(op, left, right) {
     // GitHub compares arrays and objects by instance, and two written sides are

package/dist/expr/evaluate.d.ts

@@ -1,3 +1,2 @@
 import type { Scope } from "./val.js";
-/** Evaluate a condition to a truthiness, or null when it cannot be settled. */
 export declare function evaluate(cond: string, scope?: Scope): boolean | null;

package/dist/expr/evaluate.js

@@ -1,6 +1,5 @@
 import { evaluateValue } from "./evaluateValue.js";
 import { truthy } from "./truthy.js";
-/** Evaluate a condition to a truthiness, or null when it cannot be settled. */
 export function evaluate(cond, scope = {}) {
     return truthy(evaluateValue(cond, scope));
 }

package/dist/expr/index.d.ts

@@ -1,33 +1,12 @@
 /**
  * A tri-state evaluator for the slice of GitHub expressions that job `if:`
- * conditions actually use.
+ * conditions use. Two rules carry the module:
  *
- * The point is not to reimplement the expression language. It is to stop
- * returning `unknown` for conditions that are already decided. A reusable
- * workflow's jobs commonly guard on the caller's own literals:
- *
- *     if: ${{ github.event_name == 'pull_request'
- *             && (inputs.gates == '' || contains(inputs.gates, '"mutation"'))
- *             && (needs.detect.outputs.mutation_languages || ...) != '[]' }}
- *
- * The last clause needs a job that has not run yet. The middle one does not:
- * the caller passed `gates` as a literal string, and it does not contain
- * `"mutation"`, so the clause is false, so the whole `&&` is false whatever
- * `detect` reports. Deciding that is the difference between a predictable
- * check name and a hole in the prediction.
- *
- * Two ideas carry the whole module:
- *
- * 1. **Truthiness can be known when the value is not.** `A && B` with an
- *    unknown `A` and a false `B` is false either way. So the lattice has four
- *    points, not three: a concrete value, known-truthy, known-falsy, and
- *    nothing at all.
- *
- * 2. **Unrecognized is unknown, never a guess.** An unparseable condition, an
- *    unsupported function, a comparison between types we do not model — all
- *    collapse to `unknown` and leave the caller exactly where it was. This
- *    adds no tolerance and no third outcome; it converts conditions that are
- *    already decidable into the answer they already have.
+ * 1. Truthiness can be known when the value is not — `A && B` with an unknown
+ *    `A` and a false `B` is false either way. So the lattice has four points,
+ *    not three: a concrete value, known-truthy, known-falsy, nothing at all.
+ * 2. Unrecognized is unknown, never a guess. An unparseable condition, an
+ *    unsupported function, an unmodelled comparison all collapse to `unknown`.
  */
 export { evaluate } from "./evaluate.js";
 export { evaluateValue } from "./evaluateValue.js";

package/dist/expr/index.js

@@ -1,33 +1,12 @@
 /**
  * A tri-state evaluator for the slice of GitHub expressions that job `if:`
- * conditions actually use.
+ * conditions use. Two rules carry the module:
  *
- * The point is not to reimplement the expression language. It is to stop
- * returning `unknown` for conditions that are already decided. A reusable
- * workflow's jobs commonly guard on the caller's own literals:
- *
- *     if: ${{ github.event_name == 'pull_request'
- *             && (inputs.gates == '' || contains(inputs.gates, '"mutation"'))
- *             && (needs.detect.outputs.mutation_languages || ...) != '[]' }}
- *
- * The last clause needs a job that has not run yet. The middle one does not:
- * the caller passed `gates` as a literal string, and it does not contain
- * `"mutation"`, so the clause is false, so the whole `&&` is false whatever
- * `detect` reports. Deciding that is the difference between a predictable
- * check name and a hole in the prediction.
- *
- * Two ideas carry the whole module:
- *
- * 1. **Truthiness can be known when the value is not.** `A && B` with an
- *    unknown `A` and a false `B` is false either way. So the lattice has four
- *    points, not three: a concrete value, known-truthy, known-falsy, and
- *    nothing at all.
- *
- * 2. **Unrecognized is unknown, never a guess.** An unparseable condition, an
- *    unsupported function, a comparison between types we do not model — all
- *    collapse to `unknown` and leave the caller exactly where it was. This
- *    adds no tolerance and no third outcome; it converts conditions that are
- *    already decidable into the answer they already have.
+ * 1. Truthiness can be known when the value is not — `A && B` with an unknown
+ *    `A` and a false `B` is false either way. So the lattice has four points,
+ *    not three: a concrete value, known-truthy, known-falsy, nothing at all.
+ * 2. Unrecognized is unknown, never a guess. An unparseable condition, an
+ *    unsupported function, an unmodelled comparison all collapse to `unknown`.
  */
 export { evaluate } from "./evaluate.js";
 export { evaluateValue } from "./evaluateValue.js";

package/dist/expr/parseOr.d.ts

@@ -1,11 +1,8 @@
 import type { Cursor } from "./cursor.js";
 import type { Scope, Val } from "./val.js";
 /**
- * Recursive descent over GitHub's precedence order, loosest first:
- * `||`, then `&&`, then comparison, then `!`, then a primary.
- *
  * `&&` and `||` are value operators, not boolean ones — `a || b` yields the
- * first truthy operand, which is why `(x || y) != '[]'` parses as a
- * comparison against a coalesced value rather than a boolean.
+ * first truthy operand, which is why `(x || y) != '[]'` parses as a comparison
+ * against a coalesced value rather than a boolean.
  */
 export declare function parseOr(cur: Cursor, scope: Scope): Val;

package/dist/expr/parseOr.js

@@ -1,12 +1,9 @@
 import { coalesceOr } from "./coalesceOr.js";
 import { parseAnd } from "./parseAnd.js";
 /**
- * Recursive descent over GitHub's precedence order, loosest first:
- * `||`, then `&&`, then comparison, then `!`, then a primary.
- *
  * `&&` and `||` are value operators, not boolean ones — `a || b` yields the
- * first truthy operand, which is why `(x || y) != '[]'` parses as a
- * comparison against a coalesced value rather than a boolean.
+ * first truthy operand, which is why `(x || y) != '[]'` parses as a comparison
+ * against a coalesced value rather than a boolean.
  */
 export function parseOr(cur, scope) {
     let left = parseAnd(cur, scope);

package/dist/expr/truthy.d.ts

@@ -1,7 +1,6 @@
 import type { Val } from "./val.js";
 /**
- * GitHub's truthiness: empty string, zero, `false` and null are false, and
- * every other value is true. `'0'` and `'false'` are non-empty strings, so
- * both are true — the same trap as JavaScript, kept deliberately identical.
+ * GitHub's truthiness: `''`, 0, `false` and null are false. `'0'` and `'false'`
+ * are non-empty strings, so both are true — the same trap as JavaScript.
  */
 export declare function truthy(val: Val): boolean | null;

package/dist/expr/truthy.js

@@ -1,7 +1,6 @@
 /**
- * GitHub's truthiness: empty string, zero, `false` and null are false, and
- * every other value is true. `'0'` and `'false'` are non-empty strings, so
- * both are true — the same trap as JavaScript, kept deliberately identical.
+ * GitHub's truthiness: `''`, 0, `false` and null are false. `'0'` and `'false'`
+ * are non-empty strings, so both are true — the same trap as JavaScript.
  */
 export function truthy(val) {
     switch (val.kind) {
@@ -11,8 +10,8 @@ export function truthy(val) {
             return false;
         case "unknown":
             return null;
-        // GitHub does cast an array or an object to a boolean, but no workflow
-        // asks it to, and the answer is not worth guessing at to find out.
+        // GitHub does cast these, but no workflow asks it to, so guessing buys
+        // nothing.
         case "json":
             return null;
         case "value": {

package/dist/jobs/prScope.d.ts

@@ -1,10 +1,3 @@
 import type { Scope } from "../expr/val.js";
-/**
- * A scope with the fixed pull-request facts filled in.
- *
- * Every `${{ }}` this module evaluates — a job `if:`, a matrix axis — is
- * evaluated for the same event, so they all get the same `github.*`. Anything
- * the caller states wins; there is nothing here worth overriding, but a scope
- * that silently ignored what it was handed would be the wrong shape.
- */
+/** Anything the caller states wins over the defaults. */
 export declare const prScope: (scope: Scope) => Scope;

package/dist/jobs/prScope.js

@@ -1,18 +1,10 @@
 /**
- * The `github.*` values that are fixed for everything this module predicts.
- * `predict` only ever answers for a pull request, so `event_name` is not a
- * variable — which is what lets a `github.event_name == 'pull_request'` guard
- * resolve instead of hanging the job on an unknown.
+ * `predict` only ever answers for a pull request, so `event_name` is fixed —
+ * which is what lets a `github.event_name == 'pull_request'` guard resolve
+ * instead of hanging the job on an unknown.
  */
 const PR_GITHUB_CONTEXT = { event_name: "pull_request" };
-/**
- * A scope with the fixed pull-request facts filled in.
- *
- * Every `${{ }}` this module evaluates — a job `if:`, a matrix axis — is
- * evaluated for the same event, so they all get the same `github.*`. Anything
- * the caller states wins; there is nothing here worth overriding, but a scope
- * that silently ignored what it was handed would be the wrong shape.
- */
+/** Anything the caller states wins over the defaults. */
 export const prScope = (scope) => ({
     ...scope,
     github: { ...PR_GITHUB_CONTEXT, ...scope.github },

package/dist/names/capDisplayName.d.ts

@@ -1,6 +1,6 @@
 /**
- * GitHub cuts a display name over 100 characters to 97 plus `...`. Verified
- * on a live dispatch (dirsql PR #1013): the cap applies to the leaf name
- * before any reusable-call prefixing, so it lives here, not on the entry.
+ * GitHub cuts a display name over 100 characters to 97 plus `...`. Verified on
+ * dirsql PR #1013: the cap applies to the leaf name before any reusable-call
+ * prefixing, so it lives here, not on the entry.
  */
 export declare function capDisplayName(name: string): string;

package/dist/names/capDisplayName.js

@@ -1,7 +1,7 @@
 /**
- * GitHub cuts a display name over 100 characters to 97 plus `...`. Verified
- * on a live dispatch (dirsql PR #1013): the cap applies to the leaf name
- * before any reusable-call prefixing, so it lives here, not on the entry.
+ * GitHub cuts a display name over 100 characters to 97 plus `...`. Verified on
+ * dirsql PR #1013: the cap applies to the leaf name before any reusable-call
+ * prefixing, so it lives here, not on the entry.
  */
 export function capDisplayName(name) {
     return name.length > 100 ? `${name.slice(0, 97)}...` : name;

package/dist/predict/makeGithubClient.d.ts

@@ -70,7 +70,6 @@ export interface GithubClient {
             }): Promise<{
                 data: GithubCommit;
             }>;
-            /** The file at `path` as text — always the `raw` media type. */
             getContent(params: RepoParams & {
                 path: string;
                 ref: string;

package/dist/predict/makeGithubClient.js

@@ -1,6 +1,5 @@
-// The GitHub REST surface willfire uses: a handful of GET endpoints plus the
-// tarball download, over plain `fetch`. The shape mirrors the octokit subset
-// it replaced (#75) so call sites and their fakes carry over unchanged.
+// Plain `fetch`, shaped to mirror the octokit subset it replaced (#75) so call
+// sites and their fakes carry over unchanged.
 export function makeGithubClient() {
     const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
     if (!token) {
@@ -76,9 +75,8 @@ export function makeGithubClient() {
                 },
             },
         },
-        // A short page ends the walk. A count landing exactly on a page boundary
-        // costs one extra empty-page request, which keeps this free of Link-header
-        // parsing.
+        // A short page ends the walk. An exact page boundary costs one extra empty
+        // request, which keeps this free of Link-header parsing.
         paginate: async (route, params) => {
             const perPage = params.per_page ?? 30;
             const all = [];

package/dist/sandbox/sandboxConfig.d.ts

@@ -1,7 +1,4 @@
-/**
- * The node major the image ships — also the refusal boundary for `setup-node`
- * and `node2x` runtimes asking for any other major.
- */
+/** Also the refusal boundary: `setup-node` and `node2x` get no other major. */
 export declare const SANDBOX_NODE_MAJOR = 24;
 export declare const DOCKERFILE = "FROM node:24-slim\nRUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates python3 && rm -rf /var/lib/apt/lists/*\n";
 export interface SandboxConfig {

package/dist/sandbox/sandboxConfig.js

@@ -1,7 +1,4 @@
-/**
- * The node major the image ships — also the refusal boundary for `setup-node`
- * and `node2x` runtimes asking for any other major.
- */
+/** Also the refusal boundary: `setup-node` and `node2x` get no other major. */
 export const SANDBOX_NODE_MAJOR = 24;
 // git and python3: checkout's postcondition and the interpreters a script on
 // a GitHub-hosted runner takes for granted.

package/dist/uses/parseUses.d.ts

@@ -1,15 +1,12 @@
 import type { UsesTarget } from "../types.js";
 /**
- * Split a job-level `uses:` into the file it names and the repo it lives in.
- *
  * Two spellings are legal:
  *
  *   `./.github/workflows/x.yml`              -> the caller's repo, same commit
  *   `owner/repo/.github/workflows/x.yml@ref` -> another repo, at `ref`
  *
- * The ref is taken from the last `@` so a branch containing a slash
- * (`@feature/foo`) survives. Returns null for anything else — including a
- * reference built from an expression, which we cannot evaluate and so must not
- * guess a fetch target for.
+ * The ref comes off the last `@`, so a branch with a slash survives. Anything
+ * else is null, including a reference built from an expression — no fetch
+ * target to guess at.
  */
 export declare function parseUses(uses: string): UsesTarget | null;

package/dist/uses/parseUses.js

@@ -1,16 +1,13 @@
 import { EXPRESSION_RE } from "../names/jobDisplayName.js";
 /**
- * Split a job-level `uses:` into the file it names and the repo it lives in.
- *
  * Two spellings are legal:
  *
  *   `./.github/workflows/x.yml`              -> the caller's repo, same commit
  *   `owner/repo/.github/workflows/x.yml@ref` -> another repo, at `ref`
  *
- * The ref is taken from the last `@` so a branch containing a slash
- * (`@feature/foo`) survives. Returns null for anything else — including a
- * reference built from an expression, which we cannot evaluate and so must not
- * guess a fetch target for.
+ * The ref comes off the last `@`, so a branch with a slash survives. Anything
+ * else is null, including a reference built from an expression — no fetch
+ * target to guess at.
  */
 export function parseUses(uses) {
     if (EXPRESSION_RE.test(uses)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",