@intentius/chant 0.124.12 → 0.124.14

package/dist/op/composites/reconcile-op.js

@@ -0,0 +1,84 @@
+/**
+ * ReconcileOp composite — the cloud → code workflow as an Op.
+ *
+ * Keeps source tracking reality: when live drifts from declarations, open a PR
+ * that regenerates the affected TypeScript. Mirrors the {@link WatchOp} shape.
+ *
+ * Phases: snapshot → plan → regenerate (live import) → open PR. The
+ * regenerate-and-PR step is the `reconcilePr` activity (#122), which derives
+ * the change set from `chant lifecycle plan` and opens a reviewable PR.
+ *
+ * Runs one-shot on the local Op executor for a `chant run`; with a `schedule`
+ * the cadence rides on the Op itself (#2120) for whichever runtime honours it.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor
+ * export const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+ *
+ * // hourly
+ * export const { op } = ReconcileOp({
+ *   name: "prod-reconcile",
+ *   env: "prod",
+ *   schedule: "0 * * * *",
+ *   scope: { owned: true },
+ * });
+ * ```
+ *
+ * @see #112 — stateless-authoritative state model + live import
+ */
+import { Op, phase, activity } from "../builders.js";
+export function ReconcileOp(config) {
+    const onDrift = config.onDrift ?? "pull-request";
+    const owned = config.scope?.owned ?? false;
+    // The reconcile's headline output is the opened PR (or issue, or the comment
+    // it posted on the triggering pull request) URL. Expose it as an outcome
+    // attribute so it prints in `chant run` and lands on the ledger. `report`
+    // mode opens nothing, so it has no URL outcome.
+    const reconcileOutcome = onDrift === "pull-request"
+        ? { name: "PR", from: "prUrl" }
+        : onDrift === "issue"
+            ? { name: "Issue", from: "issueUrl" }
+            : onDrift === "comment"
+                ? { name: "Comment", from: "commentUrl" }
+                : undefined;
+    const op = Op({
+        name: config.name,
+        overview: `Reconcile the ${config.env} environment into source (cloud → code)`,
+        labels: {
+            Reconcile: "true",
+            Env: config.env,
+        },
+        ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+        phases: [
+            phase("Snapshot", [activity("lifecycleSnapshot", { env: config.env })]),
+            phase("Plan", [
+                {
+                    kind: "activity",
+                    fn: "lifecycleDiff",
+                    args: { env: config.env, live: true },
+                    outcomeAttribute: { name: "Drift", from: "drifted" },
+                },
+            ]),
+            phase("Reconcile", [
+                // reconcilePr derives the change set from `chant lifecycle plan`,
+                // regenerates via `chant import --from`, and opens a PR. Surface the
+                // opened PR/issue URL as an outcome so `chant run` prints it — the
+                // reconcile's result is the link.
+                //
+                // `op` names this Op in the marker `issue` mode's sticky issue is
+                // found by (#2319). The env alone is not unique across Ops: it shares
+                // a marker namespace with `TerraformWatchOp`, which passes a terraform
+                // *root* as its `env`, so a chant environment and a root that happen
+                // to share a name resolved to one marker and overwrote each other.
+                {
+                    kind: "activity",
+                    fn: "reconcilePr",
+                    args: { env: config.env, op: config.name, mode: onDrift, owned },
+                    ...(reconcileOutcome ? { outcomeAttribute: reconcileOutcome } : {}),
+                },
+            ]),
+        ],
+    });
+    return { op };
+}

package/dist/op/composites/watch-op.js

@@ -0,0 +1,69 @@
+/**
+ * WatchOp composite — periodic state observation as an Op.
+ *
+ * Composes existing pieces:
+ *   - The local executor (`../local-executor.ts`) runs the phases in order and
+ *     files each step's record under the phase it belongs to
+ *   - The pre-built lifecycleSnapshot + lifecycleDiff activities
+ *   - `schedule` puts the cadence on the Op itself (#2120)
+ *
+ * The cron is Op data, not a resource: `chant operator` ticks on it, the
+ * github/gitlab/forgejo generators render it as a CI cron, and a hosting
+ * lexicon hands it to its own scheduler.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = WatchOp({
+ *   name: "prod-watch",
+ *   env: "prod",
+ *   schedule: "0,15,30,45 * * * *", // every 15 minutes
+ * });
+ * ```
+ *
+ * @see #31 — Continuous observation (the issue this composite addresses)
+ */
+import { Op, phase, activity } from "../builders.js";
+import { receiptCheckInput } from "../receipt-store.js";
+export function WatchOp(config) {
+    const live = config.live ?? true;
+    const op = Op({
+        name: config.name,
+        overview: `Periodically snapshot and diff the ${config.env} environment`,
+        labels: {
+            Watch: "true",
+            Env: config.env,
+        },
+        ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+        ...(config.failOn ? { failOn: config.failOn } : {}),
+        phases: [
+            phase("Snapshot", [activity("lifecycleSnapshot", { env: config.env })]),
+            phase("Diff", [
+                // outcomeAttribute surfaces lifecycleDiff's `drifted` boolean as the
+                // run's `Drift` outcome on the run ledger, so a reader of the ledger
+                // can pick out the runs that detected drift.
+                {
+                    kind: "activity",
+                    fn: "lifecycleDiff",
+                    args: { env: config.env, live },
+                    outcomeAttribute: { name: "Drift", from: "drifted" },
+                },
+            ]),
+            // Receipt staleness (#1834): read-only over the receipt store — absent
+            // or differing receipts surface as findings (and a StaleReceipts run
+            // outcome); nothing runs and nothing is written.
+            ...(config.receipts && config.receipts.length > 0
+                ? [
+                    phase("Receipts", [
+                        {
+                            kind: "activity",
+                            fn: "receiptStaleness",
+                            args: { receipts: config.receipts.map(receiptCheckInput) },
+                            outcomeAttribute: { name: "StaleReceipts", from: "stale" },
+                        },
+                    ]),
+                ]
+                : []),
+        ],
+    });
+    return { op };
+}

package/dist/op/composites/workflow-audit-op.js

@@ -0,0 +1,57 @@
+/**
+ * WorkflowAuditOp composite — the live supply-chain audit of GitHub workflows
+ * as a chant Op with an optional schedule (#292).
+ *
+ * The github post-synth checks (#286-#291) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — stale SHA pins, impostor refs,
+ * symbolic-ref confusion, pin/comment mismatch, advisories, archived upstreams.
+ * It sits at **observe** on the lifecycle dial, with a finding-mode (mirroring
+ * `ReconcileOp`: `report | issue | pull-request`) as the **reconcile** step.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; a `schedule` puts
+ * the cadence on the Op itself (#2120), for continuous re-audit between
+ * change windows.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor
+ * export const { op } = WorkflowAuditOp({ name: "actions-audit" });
+ *
+ * // daily, opening a PR that bumps a stale pin
+ * export const { op } = WorkflowAuditOp({
+ *   name: "actions-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "pull-request",
+ * });
+ * ```
+ *
+ * @see #286 — the deterministic counterpart this freshens.
+ */
+import { Op, phase } from "../builders.js";
+export function WorkflowAuditOp(config) {
+    const onFinding = config.onFinding ?? "report";
+    const op = Op({
+        name: config.name,
+        overview: "Resolve workflow action references against live upstreams and report supply-chain drift",
+        labels: {
+            Audit: "true",
+            Surface: "github-workflows",
+        },
+        ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+        phases: [
+            phase("Audit", [
+                {
+                    kind: "activity",
+                    fn: "workflowSupplyChainAudit",
+                    args: { workflowsDir: config.workflowsDir ?? ".github/workflows", mode: onFinding },
+                    // Surface the finding count as the run's `Findings` outcome on the
+                    // run ledger, so a reader can pick out the audits that found
+                    // something.
+                    outcomeAttribute: { name: "Findings", from: "findings" },
+                },
+            ]),
+        ],
+    });
+    return { op };
+}

package/dist/op/converge-rule.js

@@ -0,0 +1,205 @@
+/**
+ * Converge rules (#1484) — the typed, JSON-serializable predicate language a
+ * `ConvergeOp` rule table is built from.
+ *
+ * The issue's illustrative sketch writes a rule's condition as a JS arrow
+ * function (`s => s.status === "drifted"`). That reads well but can't
+ * actually ship: a rule is evaluated per-tick against live, freshly-observed
+ * data inside an activity, and an activity's arguments — including whatever a
+ * `ConvergeOp` composite bakes into the Op it builds — must be plain JSON (see
+ * `step-output-ref.ts`'s module doc on why a value crossing an activity
+ * boundary can't carry a closure). A rule
+ * "outside the evaluable subset" is one of the build-time refusals #1484
+ * names explicitly, which only makes sense if there IS an evaluable subset
+ * to be outside of — so rules here are data: a small comparison language
+ * over one typed symptom record, interpreted by {@link evaluatePredicate}
+ * (pure, no I/O, matching Accessible Ops factor I — "predictable from the
+ * text alone").
+ *
+ * `S` is the symptom record type a `ConvergeOp` instance evaluates against
+ * (`ConvergeSymptom`, ../lifecycle/symptoms.ts, for the real thing — kept
+ * generic here so the predicate language and its tests don't depend on the
+ * lifecycle package). Since a predicate's `field` is typed `keyof S`, a rule
+ * that names a field the symptom record doesn't have is refused by
+ * TypeScript itself at the author's call site — the "symptom field nothing
+ * produces" refusal, satisfied for free. {@link isWellFormedPredicate} is the
+ * runtime backstop for a rule assembled by hand (bypassing `when()`/the
+ * comparison builders) rather than authored through them, and is what a
+ * build-time check (OPS014, ../lint/rules/op/ops014-converge-rule-refusals.ts)
+ * re-validates the serialized rule table against.
+ */
+const FIELD_COMPARISON_OPS = new Set(["eq", "neq", "gt", "gte", "lt", "lte"]);
+const FIELD_TRUTHINESS_OPS = new Set(["truthy", "falsy"]);
+/**
+ * Structural validator for a value claiming to be a {@link SymptomPredicate}
+ * — the runtime backstop OPS014
+ * (../lint/rules/op/ops014-converge-rule-refusals.ts) re-checks a serialized
+ * rule table against, since nothing forces a rule
+ * assembled by hand (rather than through the builders below) to match this
+ * shape. Recurses through `allOf`/`anyOf`; `fieldWhitelist`, when given,
+ * additionally refuses a field name the symptom record doesn't actually
+ * produce (defense in depth over TypeScript's `keyof S` check, which only
+ * applies at the author's original call site — not to a rule table replayed
+ * from JSON).
+ */
+export function isWellFormedPredicate(value, fieldWhitelist) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    switch (v.kind) {
+        case "field-comparison":
+            return (typeof v.field === "string" &&
+                (!fieldWhitelist || fieldWhitelist.has(v.field)) &&
+                typeof v.op === "string" &&
+                FIELD_COMPARISON_OPS.has(v.op) &&
+                (typeof v.value === "string" || typeof v.value === "number" || typeof v.value === "boolean"));
+        case "field-truthiness":
+            return (typeof v.field === "string" &&
+                (!fieldWhitelist || fieldWhitelist.has(v.field)) &&
+                typeof v.op === "string" &&
+                FIELD_TRUTHINESS_OPS.has(v.op));
+        case "all-of":
+        case "any-of":
+            return Array.isArray(v.predicates) && v.predicates.every((p) => isWellFormedPredicate(p, fieldWhitelist));
+        default:
+            return false;
+    }
+}
+/** Evaluate a {@link SymptomPredicate} against a symptom record. Pure — no I/O, no ambient reads. */
+export function evaluatePredicate(predicate, symptom) {
+    switch (predicate.kind) {
+        case "field-comparison": {
+            const actual = symptom[predicate.field];
+            switch (predicate.op) {
+                case "eq":
+                    return actual === predicate.value;
+                case "neq":
+                    return actual !== predicate.value;
+                case "gt":
+                    return typeof actual === "number" && typeof predicate.value === "number" && actual > predicate.value;
+                case "gte":
+                    return typeof actual === "number" && typeof predicate.value === "number" && actual >= predicate.value;
+                case "lt":
+                    return typeof actual === "number" && typeof predicate.value === "number" && actual < predicate.value;
+                case "lte":
+                    return typeof actual === "number" && typeof predicate.value === "number" && actual <= predicate.value;
+            }
+            break;
+        }
+        case "field-truthiness": {
+            const actual = symptom[predicate.field];
+            return predicate.op === "truthy" ? !!actual : !actual;
+        }
+        case "all-of":
+            return predicate.predicates.every((p) => evaluatePredicate(p, symptom));
+        case "any-of":
+            return predicate.predicates.some((p) => evaluatePredicate(p, symptom));
+    }
+    // Unreachable for a well-formed predicate; a malformed one (bypassing the
+    // builders and isWellFormedPredicate) never matches rather than throwing
+    // mid-tick — the build-time check is what refuses it before this runs.
+    return false;
+}
+/**
+ * Does a predicate reference the given symptom field anywhere in it,
+ * recursing through `allOf`/`anyOf`? The build-time backstop for a claim
+ * about a *category* of rule (e.g. "a rule reading `adoptCount`") rather
+ * than a single comparison — OPS014's adopt-safety check
+ * (../lint/rules/op/ops014-converge-rule-refusals.ts) uses this to refuse a
+ * rule that both reads `adoptCount` and dispatches a
+ * mutating op, rather than merely documenting that authors shouldn't write
+ * one.
+ */
+export function predicateReferencesField(predicate, field) {
+    switch (predicate.kind) {
+        case "field-comparison":
+        case "field-truthiness":
+            return predicate.field === field;
+        case "all-of":
+        case "any-of":
+            return predicate.predicates.some((p) => predicateReferencesField(p, field));
+    }
+}
+// ── Predicate builders ──────────────────────────────────────────────────────
+export function eq(field, value) {
+    return { kind: "field-comparison", field, op: "eq", value };
+}
+export function neq(field, value) {
+    return { kind: "field-comparison", field, op: "neq", value };
+}
+export function gt(field, value) {
+    return { kind: "field-comparison", field, op: "gt", value };
+}
+export function gte(field, value) {
+    return { kind: "field-comparison", field, op: "gte", value };
+}
+export function lt(field, value) {
+    return { kind: "field-comparison", field, op: "lt", value };
+}
+export function lte(field, value) {
+    return { kind: "field-comparison", field, op: "lte", value };
+}
+export function truthy(field) {
+    return { kind: "field-truthiness", field, op: "truthy" };
+}
+export function falsy(field) {
+    return { kind: "field-truthiness", field, op: "falsy" };
+}
+export function allOf(...predicates) {
+    return { kind: "all-of", predicates };
+}
+export function anyOf(...predicates) {
+    return { kind: "any-of", predicates };
+}
+export function run(op) {
+    return { kind: "run", op };
+}
+export function report(reason) {
+    return { kind: "report", reason };
+}
+// ── Rules ────────────────────────────────────────────────────────────────────
+/** A rule table's default flap-damping threshold (issue: "with a default"). */
+export const DEFAULT_FLAP_THRESHOLD = 3;
+/**
+ * Declare one converge rule. Throws immediately (build time — this runs
+ * while `chant build` evaluates the authoring `*.op.ts` file, exactly like
+ * `ApplyOp`'s `compensate` refusal) when `id` or `why` is missing or blank,
+ * or `flapThreshold` isn't a positive integer.
+ *
+ * @example
+ * ```ts
+ * when(eq("status", "drifted"), run("fountain-apply"), {
+ *   id: "drift-apply",
+ *   why: "Live config drifted from declared source; re-apply converges it back.",
+ * })
+ * ```
+ */
+export function when(predicate, action, opts) {
+    if (!opts.id || opts.id.trim().length === 0) {
+        throw new Error("when(): a rule must have a non-empty `id` (used for flap-damping and diagnostics)");
+    }
+    if (!opts.why || opts.why.trim().length === 0) {
+        throw new Error(`when("${opts.id}"): a rule must carry its \`why\` — every rule's rationale is required, refused at build otherwise`);
+    }
+    if (opts.flapThreshold !== undefined && (!Number.isInteger(opts.flapThreshold) || opts.flapThreshold < 1)) {
+        throw new Error(`when("${opts.id}"): flapThreshold must be a positive integer`);
+    }
+    return {
+        id: opts.id,
+        when: predicate,
+        then: action,
+        why: opts.why,
+        ...(opts.flapThreshold !== undefined ? { flapThreshold: opts.flapThreshold } : {}),
+    };
+}
+/** Every rule id in a table must be unique — flap-damping counters and dispatch/report accounting are keyed by id. */
+export function duplicateRuleIds(rules) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const r of rules) {
+        if (seen.has(r.id))
+            dupes.add(r.id);
+        seen.add(r.id);
+    }
+    return [...dupes].sort();
+}

package/dist/op/cron.js

@@ -0,0 +1,146 @@
+/**
+ * Cron for an Op's own schedule (#2120) — validation at `Op()` construction
+ * and minute-granularity matching for `chant operator`'s per-op cadence.
+ *
+ * `OpConfig.schedule.cron` is runtime-neutral data: the github lexicon turns
+ * it into `on.schedule`, a hosting lexicon hands it to its own scheduler,
+ * `chant operator` reads it as that Op's tick cadence, and the local one-shot
+ * executor ignores it entirely. Nothing here talks to a scheduler.
+ *
+ * The validator a lexicon's own post-synth cron check imports rather than
+ * keeping its own copy:
+ * deliberately permissive, a pre-submission guard rather than a full parser,
+ * since the final word belongs to whichever scheduler runs the cron.
+ *
+ * {@link cronMatches} is stricter about what it can *evaluate* than
+ * {@link isValidCronExpression} is about what it accepts, so a field carrying
+ * a Quartz extension the evaluator does not implement (`L`, `W`, `#`, `?`)
+ * matches everything rather than nothing — an operator that ticks too often
+ * is a wasted converge, one that never ticks is a silent outage.
+ */
+/** Very permissive cron field pattern — catches obvious syntax errors. */
+const CRON_FIELD = /^[0-9*,/\-?LW#]+$/;
+/**
+ * True when `expr` looks like 5- or 6-field cron. Field-shape only: it does
+ * not check that a number is in range for its position, and it accepts the
+ * Quartz extensions (`L`, `W`, `#`, `?`) some schedulers take.
+ */
+export function isValidCronExpression(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length < 5 || fields.length > 6)
+        return false;
+    return fields.every((f) => CRON_FIELD.test(f));
+}
+/**
+ * The message `Op()` throws with and a lexicon's post-synth cron check
+ * reports, so one wording covers both the build-time refusal and the
+ * post-synth diagnostic.
+ */
+export function cronSyntaxMessage(expr) {
+    return `cron expression "${expr}" does not look like valid 5- or 6-field cron syntax`;
+}
+const ANY = { any: true };
+/**
+ * Parse one field into the set of values it matches. Anything the evaluator
+ * cannot make sense of — a Quartz extension, an inverted range, a zero step —
+ * degrades to {@link ANY} rather than throwing: this runs on an expression
+ * `Op()` already accepted, and refusing at tick time would strand the Op.
+ */
+function parseField(field, min, max) {
+    if (field === "*" || field === "?" || /[LW#]/.test(field))
+        return ANY;
+    const values = new Set();
+    for (const part of field.split(",")) {
+        const [rangePart, stepPart] = part.split("/");
+        const step = stepPart === undefined ? 1 : Number(stepPart);
+        if (!Number.isInteger(step) || step < 1)
+            return ANY;
+        let lo;
+        let hi;
+        if (rangePart === "*" || rangePart === "") {
+            lo = min;
+            hi = max;
+        }
+        else if (rangePart.includes("-")) {
+            const [a, b] = rangePart.split("-");
+            lo = Number(a);
+            hi = Number(b);
+        }
+        else {
+            lo = Number(rangePart);
+            // `5/10` means "from 5, every 10" — a bare `5` means only 5.
+            hi = stepPart === undefined ? lo : max;
+        }
+        if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo > hi)
+            return ANY;
+        for (let v = lo; v <= hi; v += step)
+            values.add(v);
+    }
+    return values.size === 0 ? ANY : { any: false, values };
+}
+function fieldMatches(spec, value) {
+    return spec.any || spec.values.has(value);
+}
+/**
+ * True when `date` falls on a minute `expr` fires at, in the host's local
+ * time zone (the only clock the operator daemon has).
+ *
+ * A 6-field expression is read as Quartz's `second minute hour dom month dow`
+ * and the seconds field is dropped — nothing in chant ticks sub-minute.
+ * Day-of-month and day-of-week follow the usual cron rule: when both are
+ * restricted, either one matching is enough.
+ */
+export function cronMatches(expr, date) {
+    const fields = expr.trim().split(/\s+/);
+    const five = fields.length === 6 ? fields.slice(1) : fields;
+    if (five.length !== 5)
+        return false;
+    const [minuteF, hourF, domF, monthF, dowF] = five;
+    if (!fieldMatches(parseField(minuteF, 0, 59), date.getMinutes()))
+        return false;
+    if (!fieldMatches(parseField(hourF, 0, 23), date.getHours()))
+        return false;
+    if (!fieldMatches(parseField(monthF, 1, 12), date.getMonth() + 1))
+        return false;
+    const dom = parseField(domF, 1, 31);
+    const dow = parseField(dowF, 0, 7);
+    const weekday = date.getDay();
+    const domOk = fieldMatches(dom, date.getDate());
+    const dowOk = fieldMatches(dow, weekday) || (weekday === 0 && fieldMatches(dow, 7));
+    if (dom.any && dow.any)
+        return true;
+    if (dom.any)
+        return dowOk;
+    if (dow.any)
+        return domOk;
+    return domOk || dowOk;
+}
+/**
+ * The longest window {@link cronDueBetween} scans minute by minute. Past it
+ * the answer is "yes" without scanning: an operator that has not looked at an
+ * op for two days has certainly missed a fire of any cron worth putting on an
+ * Op, and the alternative — 100k iterations on a clock jump — buys nothing.
+ */
+const MAX_SCAN_MINUTES = 2 * 24 * 60;
+/**
+ * True when `expr` fires at some minute in `(after, upTo]` — what a round
+ * asks for an Op it last ticked at `after`. Level-triggered on purpose: a
+ * round that arrives late still ticks the Op it owes rather than waiting for
+ * the next exact match, and several missed fires collapse into the one tick a
+ * convergent verb needs.
+ */
+export function cronDueBetween(expr, after, upTo) {
+    if (upTo.getTime() <= after.getTime())
+        return false;
+    const startMs = Math.floor(after.getTime() / 60000) * 60000 + 60000;
+    if (startMs > upTo.getTime())
+        return false;
+    const spanMinutes = Math.floor((upTo.getTime() - startMs) / 60000) + 1;
+    if (spanMinutes > MAX_SCAN_MINUTES)
+        return true;
+    for (let i = 0; i < spanMinutes; i++) {
+        if (cronMatches(expr, new Date(startMs + i * 60000)))
+            return true;
+    }
+    return false;
+}