rvlib-shipkit 1.1.1 → 1.3.0

package/src/plan/cadence.ts

@@ -0,0 +1,253 @@
+// WHEN A CHECK RUNS, as a check declares it: `every` (a span, a range, or a
+// pure function of its last result), `cron`, and `whenInactive`. Pure: no
+// clock, no disk, so the planner (planner.ts) and every test read the same
+// answer from the same facts.
+//
+// the one constraint a reader breaks first: a lambda must stay pure. It is
+// called on every plan look, and one that throws is an error row, never a
+// silence: the check falls back to running on change only.
+import { parseDuration } from '../core/wire.ts'
+
+export type LastStatus = 'pass' | 'warn' | 'fail' | 'skip'
+
+/** a check's last result on record: its status, when it finished, how many
+ *  runs in a row ended on that same status, and its last MEASURED run (a
+ *  replay costs nothing, so it never counts) */
+export type LastResult = {
+    status: LastStatus
+    at: number
+    streak: number
+    cost?: { at: number; ms: number }
+    /** a decided fact with no answer for its key, whose last run skipped (its
+     *  probe could not answer): it retries on a backoff from `at` */
+    unknown?: boolean
+}
+
+/** what a lambda sees beside the last result */
+export type CadenceState = { active: boolean }
+
+/** a span (`'24h'`), a range (`['10h', '12h']`), a cron expression
+ *  (`'0 9 * * 1'`), `'once'` (only while it has no answer: what a
+ *  `ttl: 'forever'` reads as), or null for on change only */
+export type EveryValue = string | readonly [string, string] | null
+
+export type Every = EveryValue | ((last: LastResult | null, s: CadenceState) => EveryValue)
+
+export type WhenInactive = 'run' | 'wait'
+
+export type WhenInactiveDecl = WhenInactive | ((last: LastResult | null, s: CadenceState) => WhenInactive)
+
+/** what a check declared about its timing, as the planner reads it */
+export type PlanDecl = { every?: Every; cron?: string; whenInactive?: WhenInactiveDecl }
+
+/** one resolved cadence */
+export type Cadence =
+    | { kind: 'change' }
+    | { kind: 'once' }
+    | { kind: 'every'; ms: number }
+    | { kind: 'range'; min: number; max: number; point: number }
+    | { kind: 'cron'; expr: string; cron: Cron }
+
+/** the cadence a check runs on, and the words saying what chose it */
+export type Resolved = { cadence: Cadence; rule: string; error: string | null }
+
+/** runs while it has no answer, never on a clock */
+export const ONCE = 'once'
+
+const isCron = (s: string): boolean => s.trim().split(/\s+/).length === 5
+
+/** a stable fraction in [0, 1) for one repo and check: the same pair always
+ *  lands on the same point of its range, and pairs spread over it */
+export function stablePoint(seed: string): number {
+    let h = 0x811c9dc5
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i)
+        h = Math.imul(h, 0x01000193) >>> 0
+    }
+    return h / 0x1_0000_0000
+}
+
+/** one value to a cadence, or the reason it is not one */
+export function cadenceOf(v: EveryValue, seed: string): Cadence | string {
+    if (v == null) return { kind: 'change' }
+    if (v === ONCE) return { kind: 'once' }
+    if (Array.isArray(v)) {
+        if (v.length !== 2) return `a range is two spans, as in ['10h', '12h']`
+        try {
+            const min = parseDuration(v[0]!)
+            const max = parseDuration(v[1]!)
+            if (!(max > min) || min <= 0) return `range ${JSON.stringify(v)}: the second span must be longer than the first, and both above zero`
+            return { kind: 'range', min, max, point: Math.round(min + stablePoint(seed) * (max - min)) }
+        } catch (e) {
+            return (e as Error).message
+        }
+    }
+    if (typeof v !== 'string') return `every takes a span, a range, a cron expression or null, got ${typeof v}`
+    if (isCron(v)) {
+        const c = parseCron(v)
+        return typeof c === 'string' ? c : { kind: 'cron', expr: v.trim(), cron: c }
+    }
+    try {
+        const ms = parseDuration(v)
+        if (ms <= 0) return `every '${v}' must be above zero`
+        return { kind: 'every', ms }
+    } catch (e) {
+        return (e as Error).message
+    }
+}
+
+/** the problem with a static declaration, or null. A lambda is judged when it
+ *  runs, so it passes here */
+export function planDeclProblem(d: PlanDecl): string | null {
+    if (d.every != null && d.cron != null) return 'every and cron contradict each other: declare one'
+    if (d.every != null && typeof d.every !== 'function') {
+        const c = cadenceOf(d.every, '')
+        if (typeof c === 'string') return `every: ${c}`
+    }
+    if (d.cron != null) {
+        if (typeof d.cron !== 'string' || !isCron(d.cron)) return `cron takes five fields, as in '0 9 * * 1'`
+        const c = parseCron(d.cron)
+        if (typeof c === 'string') return `cron: ${c}`
+    }
+    if (d.whenInactive != null && typeof d.whenInactive !== 'function' && d.whenInactive !== 'run' && d.whenInactive !== 'wait')
+        return `whenInactive takes 'run', 'wait' or a function returning one`
+    return null
+}
+
+const words = (v: EveryValue): string => (v == null ? 'on change' : v === ONCE ? 'once, while its answer is unknown' : Array.isArray(v) ? `every ${v[0]}..${v[1]}` : isCron(v as string) ? `cron ${v}` : `every ${v}`)
+
+const stateWords = (last: LastResult | null, s: CadenceState): string =>
+    `${last == null ? 'never ran' : `last ${last.status} x${last.streak}`}, ${s.active ? 'active' : 'inactive'}`
+
+/** the cadence one check runs on now. `fallback` is what applies when the
+ *  check declared nothing: its ttl, or the daily default */
+export function resolveCadence(d: PlanDecl, fallback: { value: EveryValue; why: string }, last: LastResult | null, s: CadenceState, seed: string): Resolved {
+    let value: EveryValue
+    let rule: string
+    if (d.cron != null) {
+        value = d.cron
+        rule = `cron ${d.cron}`
+    } else if (typeof d.every === 'function') {
+        try {
+            value = d.every(last, s)
+        } catch (e) {
+            return { cadence: { kind: 'change' }, rule: `every lambda threw (${stateWords(last, s)}), on change only`, error: `every lambda threw: ${(e as Error).message}` }
+        }
+        rule = `every lambda returned ${JSON.stringify(value)} (${stateWords(last, s)})`
+    } else if (d.every !== undefined) {
+        value = d.every
+        rule = words(value)
+    } else {
+        value = fallback.value
+        rule = `${words(value)} (${fallback.why})`
+    }
+    const c = cadenceOf(value, seed)
+    if (typeof c === 'string') return { cadence: { kind: 'change' }, rule: `${rule}, on change only`, error: c }
+    return { cadence: c, rule, error: null }
+}
+
+/** what the check does while its repo is inactive, and the error when a
+ *  lambda threw (then it waits) */
+export function resolveWhenInactive(d: PlanDecl, last: LastResult | null, s: CadenceState): { value: WhenInactive; rule: string; error: string | null } {
+    const w = d.whenInactive
+    if (w == null) return { value: 'wait', rule: 'whenInactive wait (default)', error: null }
+    if (typeof w !== 'function') return { value: w, rule: `whenInactive ${w}`, error: null }
+    try {
+        const v = w(last, s)
+        if (v !== 'run' && v !== 'wait') return { value: 'wait', rule: `whenInactive lambda returned ${JSON.stringify(v)}, read as wait`, error: `whenInactive lambda returned ${JSON.stringify(v)}: it takes 'run' or 'wait'` }
+        return { value: v, rule: `whenInactive lambda returned '${v}' (${stateWords(last, s)})`, error: null }
+    } catch (e) {
+        return { value: 'wait', rule: 'whenInactive lambda threw, read as wait', error: `whenInactive lambda threw: ${(e as Error).message}` }
+    }
+}
+
+/** when a cadence is next due after a run at `last`, null for on change
+ *  only. A check that never ran is due now, except a cron one, which waits
+ *  for its next slot */
+export function nextDue(c: Cadence, last: number | null, now: number): number | null {
+    if (c.kind === 'change') return null
+    if (c.kind === 'once') return last == null ? now : null
+    if (c.kind === 'every') return last == null ? now : last + c.ms
+    if (c.kind === 'range') return last == null ? now : last + c.point
+    return cronNext(c.cron, last ?? now)
+}
+
+// ── a five field cron: minute hour day-of-month month day-of-week ─────────
+
+export type Cron = { min: Set<number>; hour: Set<number>; dom: Set<number>; mon: Set<number>; dow: Set<number>; domAny: boolean; dowAny: boolean }
+
+const FIELDS: [string, number, number][] = [['minute', 0, 59], ['hour', 0, 23], ['day of month', 1, 31], ['month', 1, 12], ['day of week', 0, 7]]
+
+function field(raw: string, name: string, lo: number, hi: number): Set<number> | string {
+    const out = new Set<number>()
+    for (const part of raw.split(',')) {
+        const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part)
+        if (m == null) return `${name} '${part}' is not a number, a range, * or a step`
+        const step = m[2] == null ? 1 : Number(m[2])
+        if (step < 1) return `${name} step must be at least 1`
+        let a = lo
+        let b = hi
+        if (m[1] !== '*') {
+            const [x, y] = m[1]!.split('-').map(Number)
+            a = x!
+            b = y ?? (m[2] == null ? x! : hi)
+        }
+        if (a < lo || b > hi || a > b) return `${name} '${part}' is outside ${lo}..${hi}`
+        for (let v = a; v <= b; v += step) out.add(v)
+    }
+    return out
+}
+
+export function parseCron(expr: string): Cron | string {
+    const parts = expr.trim().split(/\s+/)
+    if (parts.length !== 5) return `cron takes five fields (minute hour day month weekday), got ${parts.length}`
+    const sets: Set<number>[] = []
+    for (let i = 0; i < 5; i++) {
+        const [name, lo, hi] = FIELDS[i]!
+        const s = field(parts[i]!, name, lo, hi)
+        if (typeof s === 'string') return s
+        sets.push(s)
+    }
+    const dow = sets[4]!
+    if (dow.has(7)) dow.add(0)
+    return { min: sets[0]!, hour: sets[1]!, dom: sets[2]!, mon: sets[3]!, dow, domAny: parts[2] === '*', dowAny: parts[4] === '*' }
+}
+
+/** the first minute strictly after `after` that the cron matches, in local
+ *  time. Walks months, days and hours before minutes, so a yearly slot costs
+ *  a few hundred steps */
+export function cronNext(c: Cron, after: number): number {
+    const d = new Date(after)
+    d.setSeconds(0, 0)
+    d.setMinutes(d.getMinutes() + 1)
+    const dayOk = (x: Date): boolean => {
+        const dom = c.dom.has(x.getDate())
+        const dow = c.dow.has(x.getDay())
+        // the classic rule: both restricted means either one matches
+        if (c.domAny) return dow
+        if (c.dowAny) return dom
+        return dom || dow
+    }
+    for (let guard = 0; guard < 100_000; guard++) {
+        if (!c.mon.has(d.getMonth() + 1)) {
+            d.setMonth(d.getMonth() + 1, 1)
+            d.setHours(0, 0, 0, 0)
+            continue
+        }
+        if (!dayOk(d)) {
+            d.setDate(d.getDate() + 1)
+            d.setHours(0, 0, 0, 0)
+            continue
+        }
+        if (!c.hour.has(d.getHours())) {
+            d.setHours(d.getHours() + 1, 0, 0, 0)
+            continue
+        }
+        if (!c.min.has(d.getMinutes())) {
+            d.setMinutes(d.getMinutes() + 1, 0, 0)
+            continue
+        }
+        return d.getTime()
+    }
+    throw new Error('cron has no matching minute within the search window')
+}

package/src/plan/catch-up.ts

@@ -0,0 +1,37 @@
+// when the plan's catch up window started, kept across restarts in place: work
+// already overdue when the plan starts is spread over CATCH_UP_MS from this
+// start (planner.ts), so a daemon restarted every few minutes never pushes it
+// back into a fresh window.
+//
+// the one constraint a reader breaks first: only a real pause opens a new
+// window. The daemon beats while it runs, and a boot less than
+// CATCH_UP_GAP_MS after the last beat keeps the start it had.
+import { machineGet, machineSet } from '../core/machine-db.ts'
+
+/** a boot this long after the plan's last beat is a pause (a machine asleep,
+ *  pm stopped), and opens a new window. A restart in place takes seconds */
+export const CATCH_UP_GAP_MS = 10 * 60_000
+
+/** how often a running plan says it is alive */
+export const CATCH_UP_BEAT_MS = 60_000
+
+export type CatchUpMark = { start: number; seen: number }
+
+export type CatchUpStore = { get: () => CatchUpMark | null; set: (v: CatchUpMark) => void }
+
+const KEY = 'plan.catch-up'
+
+/** the machine db row (core/machine-db.ts): one per machine, like the plan */
+export const machineCatchUp: CatchUpStore = {
+    get: () => machineGet<CatchUpMark>(KEY),
+    set: (v) => void machineSet(KEY, v),
+}
+
+/** the start of the window this boot belongs to, written back with `now` as
+ *  its last beat */
+export function resumeCatchUp(now: number, store: CatchUpStore): number {
+    const m = store.get()
+    const start = m != null && Number.isFinite(m.start) && Number.isFinite(m.seen) && now - m.seen < CATCH_UP_GAP_MS && m.start <= now ? m.start : now
+    store.set({ start, seen: now })
+    return start
+}

package/src/plan/plan-timeline.ts

@@ -0,0 +1,99 @@
+// the planned page's words, pure: the one timeline (now, next), the checks
+// waiting for their repo to be active, the filter, and every word a row says. The page (planned-st.ts) and `shipkit
+// planned` both draw from these, so the two can never disagree.
+import type { LastStatus } from './cadence.ts'
+import type { PlanReason, PlanRow } from './planner.ts'
+
+export type Section = 'now' | 'next'
+
+/** the section a row sits in; null for a check with no time of its own, and
+ *  for one waiting for its repo to be active: it waits by design, so it is
+ *  counted on one line (waitingWords), never listed as late */
+export function sectionOf(r: PlanRow): Section | null {
+    if (r.state === 'running' || r.state === 'due') return 'now'
+    if (r.state === 'next') return 'next'
+    return null
+}
+
+/** the checks a `wait` rule holds until their repo is active, by repo then check */
+export function waitingRows(rows: PlanRow[], query = ''): PlanRow[] {
+    return rows.filter((r) => r.state === 'late' && matches(r, query)).sort((a, b) => a.repo.localeCompare(b.repo) || a.check.localeCompare(b.check))
+}
+
+/** their one line, or '' when none waits */
+export function waitingWords(rows: PlanRow[], query = ''): string {
+    const w = waitingRows(rows, query)
+    if (w.length === 0) return ''
+    const repos = new Set(w.map((r) => r.repo)).size
+    return `waiting for their repo to be active: ${w.length} check${w.length === 1 ? '' : 's'} in ${repos} repo${repos === 1 ? '' : 's'}`
+}
+
+/** a row matches a text filter when its project or check holds every word
+ *  of it, in any case */
+export function matches(r: PlanRow, query: string): boolean {
+    const words = query.toLowerCase().split(/\s+/).filter((w) => w !== '')
+    const hay = `${r.repo} ${r.check}`.toLowerCase()
+    return words.every((w) => hay.includes(w))
+}
+
+/** the one list: running first, then due, then the next ones soonest
+ *  first. Each row carries its section */
+export function timeline(rows: PlanRow[], query = ''): { section: Section; row: PlanRow }[] {
+    const rank = (r: PlanRow): number => (r.state === 'running' ? 0 : r.state === 'due' ? 1 : 2)
+    return rows
+        .filter((r) => sectionOf(r) != null && matches(r, query))
+        .sort((a, b) => rank(a) - rank(b) || (a.dueAt ?? Infinity) - (b.dueAt ?? Infinity) || a.repo.localeCompare(b.repo) || a.check.localeCompare(b.check))
+        .map((row) => ({ section: sectionOf(row)!, row }))
+}
+
+const MIN = 60_000
+const HOUR = 60 * MIN
+const DAY = 24 * HOUR
+
+/** a span in its largest unit: `<1m`, `25m`, `2h`, `3d` */
+export function spanShort(ms: number): string {
+    if (ms < MIN) return '<1m'
+    if (ms < HOUR) return `${Math.round(ms / MIN)}m`
+    if (ms < DAY) return `${Math.round(ms / HOUR)}h`
+    return `${Math.round(ms / DAY)}d`
+}
+
+/** when the row runs, relative to now: `now`, `in 4m`, or `when active`
+ *  for one waiting for its repo */
+export function whenWords(r: PlanRow, now: number): string {
+    if (r.state === 'late') return 'when active'
+    if (r.dueAt == null || r.state === 'running' || r.state === 'due') return 'now'
+    const d = r.dueAt - now
+    return d > 0 ? `in ${spanShort(d)}` : 'now'
+}
+
+export type Mark = 'running' | 'failed' | 'waiting' | 'due' | 'next'
+
+/** the one mark a row shows and its few words: running wins, then a failed
+ *  last result, then waiting for its repo */
+export function markOf(r: PlanRow): { mark: Mark; words: string } {
+    if (r.state === 'running') return { mark: 'running', words: 'running' }
+    if (r.last?.status === 'fail') return { mark: 'failed', words: 'last failed' }
+    if (r.state === 'late') return { mark: 'waiting', words: 'waits: repo inactive' }
+    if (r.state === 'due') return { mark: 'due', words: 'due' }
+    return { mark: 'next', words: '' }
+}
+
+/** why it is due or planned, in words */
+export const REASON_WORDS: Record<PlanReason, string> = {
+    changed: 'files changed',
+    scheduled: 'scheduled',
+    late: 'waits for its repo to be active',
+    asked: 'asked by hand',
+}
+
+export const reasonWords = (r: PlanRow): string => (r.reason == null ? '' : REASON_WORDS[r.reason])
+
+/** the tone of a last result: red failing, warn warning, ok passing */
+export const LAST_TONE: Record<LastStatus, 'red' | 'warn' | 'ok' | 'dim'> = { fail: 'red', warn: 'warn', pass: 'ok', skip: 'dim' }
+
+/** a title worth showing beside the id: a title that repeats the id loses it */
+export function titleWords(title: string | null, check: string): string | null {
+    const t = title?.startsWith(check) === true ? title.slice(check.length).replace(/^[\s:·]+/, '') : title
+    return t == null || t === '' ? null : t
+}