firstlight 0.0.0-stage → 0.3.0

package/dist/baseline.js

@@ -0,0 +1,86 @@
+// Which failures of a run are new: the earlier result each check is
+// compared with, and the comparison of the two. It only computes; reading
+// the earlier runs is the store's, and parsing and printing their logs is
+// the report's. No I/O.
+//
+// A diagnostic is identified by its file, rule, and message, without its
+// line and column, so code that only moved does not count as a new
+// failure. The cost is that a second copy of a known error in the same
+// file, with the same rule and message, is not new either.
+export function isFailure(status) {
+    return status === "failed" || status === "timed_out";
+}
+// The baseline of a check is the newest earlier kept run in which a check
+// with the same name and the same `run` command passed, failed, or timed
+// out. Per check rather than one run for all, because `run --failed` and
+// `run <name>` leave runs that hold only some of the checks. A cancelled,
+// skipped, or unfinished result proved nothing either way, so it is passed
+// over; a changed command is a different check that shares the name.
+export function findBaselines(specs, newestFirst) {
+    const baselines = new Map();
+    for (const spec of specs) {
+        for (const past of newestFirst) {
+            const pastSpec = past.checks.find((check) => check.name === spec.name);
+            if (pastSpec === undefined || pastSpec.run !== spec.run)
+                continue;
+            const status = past.states.find((check) => check.name === spec.name)?.status;
+            if (status === "passed" || status === "failed" || status === "timed_out") {
+                baselines.set(spec.name, { run: past.id, status });
+                break;
+            }
+        }
+    }
+    return baselines;
+}
+export function diagnosticKey(diagnostic) {
+    return JSON.stringify([diagnostic.file, diagnostic.rule, diagnostic.message]);
+}
+// One entry per failed check of the latest run, in its order. A failure
+// with diagnostics is compared diagnostic by diagnostic; a failure without
+// them is new when its baseline did not fail. A check without a baseline
+// has only new failures.
+export function compareFailures(latest, baselines) {
+    const comparisons = [];
+    for (const check of latest) {
+        if (!check.failed)
+            continue;
+        const baseline = baselines.get(check.name);
+        if (check.diagnostics.length === 0) {
+            comparisons.push({ name: check.name, isNew: baseline?.failed !== true, newDiagnostics: [], oldDiagnostics: 0 });
+            continue;
+        }
+        const known = new Set(baseline?.failed === true ? baseline.diagnostics.map(diagnosticKey) : []);
+        const newDiagnostics = check.diagnostics.filter((diagnostic) => !known.has(diagnosticKey(diagnostic)));
+        comparisons.push({
+            name: check.name,
+            isNew: newDiagnostics.length > 0,
+            newDiagnostics,
+            oldDiagnostics: check.diagnostics.length - newDiagnostics.length,
+        });
+    }
+    return comparisons;
+}
+// A failure is one diagnostic, or one failed check that has none.
+export function countFailures(comparisons) {
+    let fresh = 0;
+    let old = 0;
+    for (const comparison of comparisons) {
+        if (comparison.newDiagnostics.length === 0 && comparison.oldDiagnostics === 0) {
+            if (comparison.isNew)
+                fresh += 1;
+            else
+                old += 1;
+        }
+        else {
+            fresh += comparison.newDiagnostics.length;
+            old += comparison.oldDiagnostics;
+        }
+    }
+    return { new: fresh, old };
+}
+// A check that proved nothing yet: still to finish, stopped, or left
+// without a result by its supervisor. A skipped check is not one of these:
+// it is judged through the `after` check whose failure skipped it.
+export function isUnproven(status) {
+    return status === "pending" || status === "running" || status === "cancelled" || status === "unknown";
+}

package/dist/cache.js

@@ -0,0 +1,54 @@
+// Cache keys for checks and the lookup of a pass that an earlier run
+// already proved. A key names exactly what a pass depends on as far as
+// firstlight can see: the working tree, the check's command, and the keys
+// of its `after` checks. Computing the tree key is tree.ts's, and reading
+// earlier runs is the store's. No I/O.
+import { createHash } from "node:crypto";
+// Bumped when the inputs of a key change meaning, so an old key can never
+// match a new one by accident.
+const KEY_VERSION = "firstlight-cache-1";
+// The check's name is left out: two names for one command on one tree
+// prove the same thing. timeoutSec is left out too: a pass that finished
+// in time is a pass under any limit that let it finish. Environment
+// variables are left out because firstlight cannot know which ones a
+// command reads.
+export function cacheKey(tree, run, depKeys) {
+    const deps = [...depKeys].sort();
+    return createHash("sha256").update(JSON.stringify([KEY_VERSION, tree, run, deps])).digest("hex");
+}
+// The after graph is acyclic once config.ts accepted it, so the recursion
+// ends. A dependency outside `specs` cannot come from config.ts or
+// resolveRun; it still gets a key of its own rather than none.
+export function cacheKeys(specs, tree) {
+    const byName = new Map(specs.map((spec) => [spec.name, spec]));
+    const keys = new Map();
+    const keyOf = (name) => {
+        const known = keys.get(name);
+        if (known !== undefined)
+            return known;
+        const spec = byName.get(name);
+        const key = spec === undefined ? cacheKey(tree, `missing check ${name}`, []) : cacheKey(tree, spec.run, spec.after.map(keyOf));
+        keys.set(name, key);
+        return key;
+    };
+    for (const spec of specs)
+        keyOf(spec.name);
+    return new Map(specs.map((spec) => [spec.name, keys.get(spec.name)]));
+}
+// Only a pass is reused: a failure may be flaky, and a timed-out, cancelled,
+// skipped, or unknown check proved nothing. A pass that was itself reused
+// points at the run that really ran the check, so a chain of unchanged runs
+// keeps one origin and its real duration.
+export function findReuse(keys, newestFirst) {
+    const found = new Map();
+    for (const [name, key] of keys) {
+        for (const past of newestFirst) {
+            const state = past.states.find((candidate) => past.keys[candidate.name] === key && candidate.status === "passed");
+            if (state === undefined)
+                continue;
+            found.set(name, { run: state.cached_from ?? past.id, elapsed_ms: state.elapsed_ms ?? 0 });
+            break;
+        }
+    }
+    return found;
+}

package/dist/checks.js

@@ -0,0 +1,125 @@
+// The check status state machine and the event vocabulary built on it.
+// The supervisor advances a check only through `advance`, and readers fold
+// events.jsonl through the same transition table, so the file can never
+// describe a path the machine does not allow. This module does no I/O.
+//
+// A result reused from an earlier run is the one step outside the table:
+// `passed` straight from `pending`, legal only on an event that names the
+// run it came from. Widening the table instead would let any check pass
+// without ever running.
+const TRANSITIONS = {
+    pending: ["running", "skipped", "cancelled"],
+    running: ["passed", "failed", "timed_out", "cancelled"],
+    passed: [],
+    failed: [],
+    timed_out: [],
+    cancelled: [],
+    skipped: [],
+};
+export const CHECK_STATUSES = Object.keys(TRANSITIONS);
+export function isTerminal(status) {
+    return TRANSITIONS[status].length === 0;
+}
+export function canAdvance(from, to) {
+    return TRANSITIONS[from].includes(to);
+}
+export function canApply(from, event) {
+    if (event.cached_from !== undefined)
+        return from === "pending" && event.status === "passed";
+    return canAdvance(from, event.status);
+}
+export function initialState(name) {
+    return { name, status: "pending", pid: null, exit_code: null, started_at: null, elapsed_ms: null, cached_from: null };
+}
+export class IllegalTransition extends Error {
+    constructor(check, from, to) {
+        super(`check ${check} cannot go from ${from} to ${to}`);
+        this.name = "IllegalTransition";
+    }
+}
+export function advance(state, event) {
+    if (!canApply(state.status, event)) {
+        throw new IllegalTransition(state.name, state.status, event.status);
+    }
+    return {
+        name: state.name,
+        status: event.status,
+        pid: event.pid ?? state.pid,
+        exit_code: event.exit_code !== undefined ? event.exit_code : state.exit_code,
+        started_at: event.status === "running" ? event.at : state.started_at,
+        elapsed_ms: event.elapsed_ms ?? state.elapsed_ms,
+        cached_from: event.cached_from ?? state.cached_from,
+    };
+}
+export function foldEvents(names, events) {
+    const states = new Map(names.map((name) => [name, initialState(name)]));
+    let outcome = null;
+    for (const event of events) {
+        if (event.type === "run") {
+            outcome = event.status;
+            continue;
+        }
+        const current = states.get(event.check);
+        if (current === undefined) {
+            throw new IllegalTransition(event.check, "pending", event.status);
+        }
+        states.set(event.check, advance(current, event));
+    }
+    return { checks: names.map((name) => states.get(name)), outcome };
+}
+// The run as it stood right after each check event, one step per event, so
+// a reader that arrives late still sees every status change in order. The
+// last step of each check agrees with foldEvents.
+export function replay(names, events) {
+    const states = new Map(names.map((name) => [name, initialState(name)]));
+    const steps = [];
+    for (const event of events) {
+        if (event.type === "run")
+            continue;
+        const current = states.get(event.check);
+        if (current === undefined) {
+            throw new IllegalTransition(event.check, "pending", event.status);
+        }
+        states.set(event.check, advance(current, event));
+        steps.push({ event, checks: names.map((name) => states.get(name)) });
+    }
+    return steps;
+}
+// Supervisor liveness is passed in rather than probed here, so the rule
+// stays a pure function: a non-terminal check of a run whose supervisor is
+// gone and that never wrote its final event has an unknown result.
+export function presentChecks(run, supervisorAlive) {
+    const orphaned = run.outcome === null && !supervisorAlive;
+    return run.checks.map((state) => {
+        const orphan = orphaned && !isTerminal(state.status);
+        return {
+            name: state.name,
+            status: orphan ? "unknown" : state.status,
+            exit_code: state.exit_code,
+            elapsed_ms: state.elapsed_ms,
+            started_at: state.started_at,
+            pid: state.pid,
+            orphan,
+            cached_from: state.cached_from,
+        };
+    });
+}
+export function bucketOf(status) {
+    switch (status) {
+        case "passed":
+            return "passed";
+        case "pending":
+        case "running":
+            return "running";
+        case "cancelled":
+            return "cancelled";
+        case "failed":
+        case "timed_out":
+        case "skipped":
+        case "unknown":
+            return "failed";
+    }
+}
+export function isSettled(view) {
+    return view.status === "unknown" || isTerminal(view.status);
+}