Files
pipelines/web/src/runs.js
T

532 lines
19 KiB
JavaScript

// Pure, DOM-free helpers for the runs history list: the status vocabulary, run
// identity, progress/meta wording, filtering, sorting and day grouping.
//
// This mirrors the Android app exactly — ui/screens/RunHistoryScreen.kt,
// screens/ListFilter.kt, screens/ListSort.kt, ui/RunIdentity.kt and ui/Format.kt
// — so the browser list reads the same words in the same order as the app. It is
// deliberately DOM-free: every rule here is unit-testable under `node --test`
// with no browser and no server. app.js keeps the wiring.
//
// Every server-provided string is only ever compared or rendered, never parsed
// as markup; the caller sets it with textContent.
import { runScheduleState, matchesScheduleState } from "./scheduleOrigin.js";
// ---------------------------------------------------------------------------
// Status vocabulary
// ---------------------------------------------------------------------------
/**
* The server's own run vocabulary, in the filter's display order
* (internal/pipeline/runs.go: queued/running/waiting/succeeded/failed/canceled/
* interrupted). The app-only `active` usage bucket, the stage-outcome words
* (`blocked`/`skipped`) and the `unknown` fallback are deliberately not offered
* as run-status filters, mirroring RUN_STATUS_FILTERS.
*/
export const RUN_STATES = [
"queued",
"running",
"waiting",
"succeeded",
"failed",
"canceled",
"interrupted",
];
/**
* Maps a server status or outcome word to its canonical display state, accepting
* the server's vocabulary only (the steps/outcomes synonyms resolve onto the same
* states so one chip set renders list, detail and timeline). Mirrors
* runStateOf: blank or unrecognised input is the safe `unknown` fallback.
*/
export function runStatusLabel(run) {
if (["queued", "running", "waiting"].includes(run?.status)) {
if (run.cleanup_unconfirmed) return "Cleanup unconfirmed — workspace reserved";
if (run.cancel_requested) return "Stopping — waiting for execution to stop";
if (run.status === "waiting" && Number(run.export_pending_sequence) > 0) return "Waiting for session export";
}
return run?.status || "unknown";
}
export function runStateOf(status) {
switch (String(status ?? "").trim().toLowerCase()) {
case "running":
return "running";
case "queued":
return "queued";
case "waiting":
return "waiting";
case "active":
return "active";
case "succeeded":
case "success":
case "completed":
case "done":
return "succeeded";
case "failed":
case "error":
return "failed";
case "canceled":
case "cancelled":
return "canceled";
case "interrupted":
return "interrupted";
case "blocked":
return "blocked";
case "skipped":
return "skipped";
default:
return "unknown";
}
}
// ---------------------------------------------------------------------------
// Identity, wording and time formatting
// ---------------------------------------------------------------------------
/**
* The runs list's two identity lines: `label` is the run's primary line and
* `pipeline` is the pipeline the run belongs to, shown as a second line only
* when the label is a stored title. A run with no title falls back to the
* pipeline name as its only line — never a title followed by an empty one.
* Mirrors ui/RunIdentity.kt runIdentity.
*/
export function runIdentity(title, name) {
const stored = String(title ?? "").trim();
return stored
? { label: stored, pipeline: String(name ?? "") }
: { label: String(name ?? ""), pipeline: null };
}
/** The version chip label, e.g. `v5` (mirrors RunHistoryScreen.VersionChip). */
export function versionLabel(version) {
return `v${version}`;
}
/**
* A visit count in the app's one singular/plural spelling (`1 visit` /
* `n visits`), mirroring ui/Format.kt visitCount so the same run is never
* described inconsistently.
*/
export function visitCount(count, adjective) {
const n = Number(count) || 0;
return `${n} ${adjective} ${n === 1 ? "visit" : "visits"}`;
}
/** Parses an RFC3339 timestamp to epoch millis, or null when blank/unparseable. */
export function parseInstant(text) {
if (text == null) return null;
const value = String(text).trim();
if (!value) return null;
const ms = Date.parse(value);
return Number.isNaN(ms) ? null : ms;
}
/**
* Non-negative whole seconds between two RFC3339 timestamps, or null when either
* is blank/unparseable or the end precedes the start. Mirrors Format.durationSeconds
* (truncating toward zero), so a sort key and the printed duration never disagree.
*/
export function durationSeconds(start, end) {
const from = parseInstant(start);
const to = parseInstant(end);
if (from == null || to == null) return null;
const seconds = Math.trunc((to - from) / 1000);
return seconds >= 0 ? seconds : null;
}
/**
* Non-negative whole seconds from a [start] RFC3339 timestamp to [nowMillis], or
* null when [start] is blank/unparseable. A future start (clock skew) reads as 0,
* never a negative. Mirrors Format.secondsSince.
*/
export function secondsSince(start, nowMillis) {
const from = parseInstant(start);
if (from == null) return null;
return Math.max(0, Math.trunc((nowMillis - from) / 1000));
}
/**
* Human duration for a whole number of seconds: `Ns`, `Nm Ss`, `Hh Mm`. Mirrors
* Format.formatDuration (a negative total renders as `0s`).
*/
export function formatDuration(totalSeconds) {
const seconds = Math.max(0, Math.trunc(Number(totalSeconds) || 0));
if (seconds < 60) return `${seconds}s`;
if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
}
/**
* An RFC3339 timestamp as the app's one human, local rendering (`d MMM HH:mm`,
* e.g. `17 Oct 21:26`), or null when blank/unparseable so a caller omits the
* value rather than printing a blank. [options] may carry a `zone` (IANA name)
* and `locale` for deterministic tests; both default to the runtime's.
*/
export function formatLocalTimestamp(instant, options = {}) {
const ms = parseInstant(instant);
if (ms == null) return null;
return formatInZone(ms, options, (parts) => `${parts.day} ${parts.month} ${parts.hour}:${parts.minute}`);
}
/** The run's calendar day (`YYYY-MM-DD`) in [zone], or null when unparseable. */
export function localDayKey(value, zone) {
const ms = value instanceof Date ? value.getTime() : parseInstant(value);
if (ms == null || !Number.isFinite(ms)) return null;
try {
const fmt = new Intl.DateTimeFormat("en-CA", {
year: "numeric",
month: "2-digit",
day: "2-digit",
timeZone: zone,
});
return fmt.format(new Date(ms));
} catch {
return null;
}
}
/**
* The day header for a run: `Today`, `Yesterday`, `d MMM yyyy`, or `Unknown date`
* for a blank/unparseable timestamp. [today] may be a day-key string or a Date.
* Mirrors RunHistoryScreen.dayLabel.
*/
export function dayLabel(createdAt, today, zone) {
const key = localDayKey(createdAt, zone);
if (key == null) return "Unknown date";
const todayKey = typeof today === "string" ? today : localDayKey(today, zone);
if (todayKey == null) return "Unknown date";
if (key === todayKey) return "Today";
if (key === addDays(todayKey, -1)) return "Yesterday";
return formatDayKey(key);
}
/**
* The runs list's meta line: `run {id} · {local d MMM HH:mm} · {duration}` for a
* finished run, and `run {id} · {live elapsed}` for an executing one (elapsed
* computed from its server start timestamp against [nowMillis]). Mirrors
* RunHistoryScreen.metaText.
*/
export function metaText(run, nowMillis, options = {}) {
const parts = [`run ${run.id}`];
if (run.executing) {
const elapsed = secondsSince(run.created_at, nowMillis);
if (elapsed != null) parts.push(formatDuration(elapsed));
} else {
const stamp = formatLocalTimestamp(run.created_at, options);
if (stamp != null) parts.push(stamp);
const duration = durationSeconds(run.created_at, run.finished_at);
if (duration != null) parts.push(formatDuration(duration));
}
return parts.join(" · ");
}
/**
* Progress from the fields a summary actually has: an optional resource-wait
* line, completed visits, then the current stage. Mirrors
* RunHistoryScreen.progressText.
*/
export function progressText(run) {
const parts = [];
if (run.resource_wait != null) {
parts.push(`Waiting for resource ${String(run.resource_wait.resource ?? "")}`);
}
parts.push(visitCount(run.completed_steps, "completed"));
const stage = String(run.current_stage ?? "").trim();
if (stage) parts.push(`stage ${stage}`);
return parts.join(" · ");
}
// ---------------------------------------------------------------------------
// Filters
// ---------------------------------------------------------------------------
/** The run-list time windows offered by the filter control. */
export const RUN_TIME_RANGES = [
{ value: "any_time", label: "Any time" },
{ value: "today", label: "Today" },
{ value: "last_7_days", label: "Last 7 days" },
{ value: "last_30_days", label: "Last 30 days" },
];
export const DEFAULT_TIME_RANGE = "any_time";
export const RUN_SCHEDULE_FILTERS = [
{ value: "any", label: "Any trigger" },
{ value: "scheduled", label: "Scheduled runs" },
{ value: "unscheduled", label: "Not scheduled" },
];
/** The runs-list filters, each defaulting to "no narrowing". */
export function defaultRunFilters() {
return { statuses: new Set(), pipelineId: null, timeRange: DEFAULT_TIME_RANGE, scheduled: "any" };
}
/** The number of active facets (one per status/pipeline/time choice). */
export function runFiltersActiveCount(filters) {
return (
(filters.statuses && filters.statuses.size > 0 ? 1 : 0) +
(filters.pipelineId != null ? 1 : 0) +
(filters.timeRange && filters.timeRange !== DEFAULT_TIME_RANGE ? 1 : 0) +
(["scheduled", "unscheduled"].includes(filters.scheduled) ? 1 : 0)
);
}
/** True when [run] is in [statuses]; an empty set means "any status". */
export function runMatchesStatuses(run, statuses) {
if (!statuses || statuses.size === 0) return true;
return statuses.has(runStateOf(run.status));
}
/** True when [run] belongs to [pipelineId]; null means "any pipeline". */
export function runMatchesPipeline(run, pipelineId) {
return pipelineId == null || run.pipeline_id === pipelineId;
}
/**
* True when [run] falls inside [range] relative to [today]. A blank/unparseable
* timestamp and a future-dated run never match a finite window; `any_time`
* matches everything. The window is inclusive calendar days ending today.
*/
export function runMatchesTimeRange(run, range, today, zone) {
if (!range || range === DEFAULT_TIME_RANGE) return true;
const key = localDayKey(run.created_at, zone);
if (key == null) return false;
const todayKey = typeof today === "string" ? today : localDayKey(today, zone);
if (todayKey == null) return false;
if (key > todayKey) return false;
switch (range) {
case "today":
return key === todayKey;
case "last_7_days":
return key >= addDays(todayKey, -6);
case "last_30_days":
return key >= addDays(todayKey, -29);
default:
return true;
}
}
/** Every run facet combined with AND. */
export function runMatchesFilters(run, filters, today, zone) {
return (
runMatchesStatuses(run, filters.statuses) &&
runMatchesPipeline(run, filters.pipelineId) &&
runMatchesTimeRange(run, filters.timeRange, today, zone) &&
matchesScheduleState(runScheduleState(run), filters.scheduled)
);
}
/** Narrows [runs] by [filters]; the default filters change nothing. */
export function filterRuns(runs, filters, today, zone) {
if (runFiltersActiveCount(filters) === 0) return runs;
return (runs ?? []).filter((run) => runMatchesFilters(run, filters, today, zone));
}
/** One selectable pipeline in the run filter, named from its runs. */
export function pipelineFilterOptions(runs) {
const names = new Map();
for (const run of runs ?? []) {
const current = names.get(run.pipeline_id);
if (current == null || current.trim() === "") names.set(run.pipeline_id, run.name ?? "");
}
return [...names.entries()]
.map(([id, name]) => ({ id, name: name.trim() === "" ? `Pipeline ${id}` : name }))
.sort((a, b) => caseInsensitiveCompare(a.name, b.name) || a.id - b.id);
}
// ---------------------------------------------------------------------------
// Sort
// ---------------------------------------------------------------------------
/** The run-list orderings offered by the sort control. */
export const RUN_SORTS = [
{ value: "newest_first", label: "Newest first" },
{ value: "oldest_first", label: "Oldest first" },
{ value: "longest_duration", label: "Longest duration" },
{ value: "shortest_duration", label: "Shortest duration" },
{ value: "pipeline_name", label: "Pipeline name" },
{ value: "status", label: "Status" },
];
export const DEFAULT_RUN_SORT = "newest_first";
/**
* The pure comparator for [sort]. Every case ends in an explicit id tie-break
* (`id` is unique) so runs that compare equal on the primary key always order
* the same way. A blank/unparseable timestamp and a run with no recorded
* duration (still executing) sort last regardless of direction and never crash.
* Mirrors ListSort.runComparator.
*/
export function runComparator(sort) {
switch (sort) {
case "oldest_first":
return (a, b) =>
ascending(instantOr(a.created_at, Infinity), instantOr(b.created_at, Infinity)) ||
ascending(a.id, b.id);
case "longest_duration":
return (a, b) => {
const da = durationSeconds(a.created_at, a.finished_at);
const db = durationSeconds(b.created_at, b.finished_at);
return (
ascending(da == null ? 1 : 0, db == null ? 1 : 0) ||
descending(da ?? -Infinity, db ?? -Infinity) ||
descending(instantOr(a.created_at, -Infinity), instantOr(b.created_at, -Infinity)) ||
descending(a.id, b.id)
);
};
case "shortest_duration":
return (a, b) => {
const da = durationSeconds(a.created_at, a.finished_at);
const db = durationSeconds(b.created_at, b.finished_at);
return (
ascending(da == null ? 1 : 0, db == null ? 1 : 0) ||
ascending(da ?? Infinity, db ?? Infinity) ||
descending(instantOr(a.created_at, -Infinity), instantOr(b.created_at, -Infinity)) ||
descending(a.id, b.id)
);
};
case "pipeline_name":
return (a, b) =>
caseInsensitiveCompare(a.name, b.name) ||
descending(instantOr(a.created_at, -Infinity), instantOr(b.created_at, -Infinity)) ||
descending(a.id, b.id);
case "status":
return (a, b) =>
caseInsensitiveCompare(a.status, b.status) ||
descending(instantOr(a.created_at, -Infinity), instantOr(b.created_at, -Infinity)) ||
descending(a.id, b.id);
case "newest_first":
default:
return (a, b) =>
descending(instantOr(a.created_at, -Infinity), instantOr(b.created_at, -Infinity)) ||
descending(a.id, b.id);
}
}
/** Orders [runs] by [sort], returning a new array. */
export function sortRuns(runs, sort) {
return [...(runs ?? [])].sort(runComparator(sort));
}
// ---------------------------------------------------------------------------
// Day grouping and the list's slots
// ---------------------------------------------------------------------------
/**
* Groups runs by calendar day in [zone], preserving the order [order] puts them
* in and the order within a day. A blank/unparseable timestamp gets a safe
* "Unknown date" group. Mirrors RunHistoryScreen.groupRunsByDay.
*/
export function groupRunsByDay(runs, today, zone, order = runComparator(DEFAULT_RUN_SORT)) {
const groups = new Map();
for (const run of [...(runs ?? [])].sort(order)) {
const label = dayLabel(run.created_at, today, zone);
if (!groups.has(label)) groups.set(label, []);
groups.get(label).push(run);
}
return [...groups.entries()].map(([label, list]) => ({ label, runs: list }));
}
export const NO_RUNS_MESSAGE = "No runs have been recorded yet.";
export const NO_MATCH_MESSAGE = "No runs match the current filters.";
export const CLEAR_FILTERS_LABEL = "Clear filters";
/**
* The runs list's slots in layout order: the usage block when there is one, then
* either the single empty line (nothing recorded, or nothing matching the
* filters) or the day groups, then the inline error row. Pure and single-sourced
* with the renderer, so its size is exactly the list's entry count. Mirrors
* RunHistoryScreen.runListEntries.
*/
export function runListEntries(usage, nothingRecorded, nothingMatched, groups, error) {
const entries = [];
if (usage != null) entries.push({ kind: "usage", key: "usage", usage });
if (nothingRecorded) {
entries.push({ kind: "empty", key: "runs-empty", message: NO_RUNS_MESSAGE, actionLabel: null });
} else if (nothingMatched) {
entries.push({
kind: "empty",
key: "runs-filtered-empty",
message: NO_MATCH_MESSAGE,
actionLabel: CLEAR_FILTERS_LABEL,
});
} else {
for (const group of groups ?? []) {
entries.push({ kind: "day", key: `day-${group.label}`, label: group.label });
for (const run of group.runs) entries.push({ kind: "run", key: `run-${run.id}`, run });
}
}
if (error) entries.push({ kind: "error", key: "runs-error", message: error });
return entries;
}
// ---------------------------------------------------------------------------
// Internals
// ---------------------------------------------------------------------------
/** Ascending compare of two numbers/strings, safe on the -Infinity sentinels. */
function ascending(x, y) {
if (x < y) return -1;
if (x > y) return 1;
return 0;
}
/** Descending compare: the larger value sorts first. */
function descending(x, y) {
return ascending(y, x);
}
function instantOr(iso, fallback) {
const ms = parseInstant(iso);
return ms == null ? fallback : ms;
}
function caseInsensitiveCompare(a, b) {
const left = String(a ?? "").toLowerCase();
const right = String(b ?? "").toLowerCase();
if (left < right) return -1;
if (left > right) return 1;
return 0;
}
/** `dayKey` shifted by [days] calendar days (keys are `YYYY-MM-DD`). */
function addDays(dayKey, days) {
const [year, month, day] = dayKey.split("-").map(Number);
const shifted = new Date(Date.UTC(year, month - 1, day) + days * 86400000);
return `${shifted.getUTCFullYear()}-${pad2(shifted.getUTCMonth() + 1)}-${pad2(shifted.getUTCDate())}`;
}
function pad2(value) {
return String(value).padStart(2, "0");
}
function formatDayKey(dayKey) {
const [year, month, day] = dayKey.split("-").map(Number);
const parts = zoneParts(Date.UTC(year, month - 1, day), "UTC", "en-GB");
return `${parts.day} ${parts.month} ${parts.year}`;
}
function formatInZone(ms, options, assemble) {
const parts = zoneParts(ms, options.zone, options.locale);
return parts ? assemble(parts) : null;
}
/** The named parts of `ms` in [zone], or null when the zone is unusable. */
function zoneParts(ms, zone, locale) {
try {
const fmt = new Intl.DateTimeFormat(locale ?? "en-GB", {
day: "numeric",
month: "short",
year: "numeric",
hour: "2-digit",
minute: "2-digit",
hourCycle: "h23",
timeZone: zone,
});
return Object.fromEntries(fmt.formatToParts(new Date(ms)).map((part) => [part.type, part.value]));
} catch {
return null;
}
}