willfire 0.1.37 → 0.1.38

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.37",
+  "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",