@mark1russell7/site-pages 0.2.4 → 0.2.5

package/README.md

@@ -126,6 +126,37 @@ The check runs the probe on the first page, in the first scheme, at each width.
 
 The check finds a browser in this order: `--browser`, `$SITE_CHECK_BROWSER`, the newest Chromium of Playwright, and then Chrome or Edge. The folder `src/check` imports only Node.js. Thus Node.js 22.18 or later can start `src/check/main.ts` with no install. The workflow `reusable-pages.yml` of the template uses it this way.
 
+## The freshness of a measured page
+
+A measured page shows numbers from a run. The numbers become old when the run becomes old or when an engine has a new release. A site keeps one file of data stamps. Each stamp names the page, its runs, the date of each run and the engine versions of each run. The gate reads this file:
+
+```sh
+site-pages freshness --stamps data/stamps.json
+```
+
+```json
+{
+  "schema": "data-stamp/1",
+  "pages": [
+    {
+      "page": "index.html",
+      "runs": [{ "id": "101", "url": "https://github.com/owner/repo/actions/runs/101", "date": "2026-11-02T10:00:00Z", "engines": { "@scope/engine": "0.7.0" } }],
+      "inFlight": { "id": "102", "url": "https://github.com/owner/repo/actions/runs/102", "date": "2026-11-04T10:00:00Z", "engines": { "@scope/engine": "0.8.0" } }
+    }
+  ]
+}
+```
+
+The gate has three rules. A fault of one rule gives the exit code 1.
+
+1. Each page names a run, and each run has an id, a link, a date and its engine versions.
+2. The data of a page is at most 3 days old (`MAX_DATA_AGE_DAYS`), or a run on newer engines is in flight. The stamp of that run is at most 3 days old, so an old stamp does not hold the gate open.
+3. The engines of the newest run are at most 1 minor version behind npm at the start of the run (`MAX_MINORS_BEHIND`). A release during a long run does not fail the gate.
+
+When npm does not answer, the gate prints the rule 3 under `Not run` and does not fail. A workflow turns the gate on with the input `data-stamps` of `reusable-pages.yml`. The gate then runs from the template commit, so it needs no install.
+
+`renderDataStamp(stamp)` gives the line that the page shows with its data: the run, its date, its engine versions and the run in flight.
+
 ## The releases
 
 The command merges four sources by version:

package/build/chunks/build.js

@@ -1414,7 +1414,7 @@ function listText(parts) {
 * The dates of the pages. The pages show each date in UTC, so the build and the browser agree.
 */
 /** The milliseconds of one day. */
-const DAY_MS = 864e5;
+const DAY_MS$1 = 864e5;
 const MONTHS = [
 	"Jan",
 	"Feb",
@@ -1431,7 +1431,7 @@ const MONTHS = [
 ];
 /** This function gives the start of the UTC day of a time. */
 function utcDay(time) {
-	return Math.floor(time / DAY_MS) * DAY_MS;
+	return Math.floor(time / DAY_MS$1) * DAY_MS$1;
 }
 /** This function gives "Oct 18": the UTC day of a time or of an ISO date. */
 function shortDate(date) {
@@ -1688,13 +1688,13 @@ function timelineLayout(releases, options) {
 		counts.set(day, (counts.get(day) ?? 0) + 1);
 	}
 	const raw = [];
-	for (let day = utcDay(Date.parse(first.date)); day <= utcDay(Date.parse(last.date)); day += DAY_MS) {
+	for (let day = utcDay(Date.parse(first.date)); day <= utcDay(Date.parse(last.date)); day += DAY_MS$1) {
 		const count = counts.get(day) ?? 0;
 		const previous = raw[raw.length - 1];
-		if (count === 0 && previous?.empty) previous.end = day + DAY_MS;
+		if (count === 0 && previous?.empty) previous.end = day + DAY_MS$1;
 		else raw.push({
 			start: day,
-			end: day + DAY_MS,
+			end: day + DAY_MS$1,
 			count,
 			empty: count === 0,
 			weight: count === 0 ? emptyWeight : 1
@@ -2302,6 +2302,195 @@ const TYPESCRIPT_PROBE = /\.[cm]?ts$/i;
 function probeScript(source) {
 	return stripTypeScriptTypes(source, { mode: "strip" }).replace(/^export \{\s*\};?[ \t]*$/m, "");
 }
+// src/check/freshness.ts
+/**
+* The freshness gate of a measured page. A site keeps a file of data stamps.
+* Each stamp names the page, its runs, their dates and their engine versions.
+* The gate fails on a page with no versions or no run date, and on old data with no newer run in flight.
+* The gate also fails on a run that started behind the engines on npm.
+* This file imports only Node.js and the folder `data`, so `reusable-pages.yml` starts it with no npm release of the package.
+*/
+/** The schema of a file of data stamps. */
+const DATA_STAMP_SCHEMA = "data-stamp/1";
+/** The largest age of the data of a page, in days, when no newer run is in flight. */
+const MAX_DATA_AGE_DAYS = 3;
+/** The most minor versions that an engine of a run can be behind npm at the start of the run. */
+const MAX_MINORS_BEHIND = 1;
+const DAY_MS = 864e5;
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+/** This function gives the faults of one run of a stamp. */
+function runFaults(raw, at) {
+	const run = record(raw);
+	if (run === null) return [`${at}: a run is not an object.`];
+	const faults = [];
+	if (typeof run["id"] !== "string" || run["id"] === "") faults.push(`${at}: a run has no id.`);
+	const label = `${at}, run ${String(run["id"])}`;
+	if (typeof run["url"] !== "string" || !run["url"].startsWith("https://")) faults.push(`${label}: the run has no https link.`);
+	if (typeof run["date"] !== "string" || !Number.isFinite(Date.parse(run["date"]))) faults.push(`${label}: the run has no date.`);
+	const engines = record(run["engines"]);
+	if (engines === null || Object.keys(engines).length === 0) return [...faults, `${label}: the run names no engine versions.`];
+	for (const [name, version] of Object.entries(engines)) if (typeof version !== "string" || parseVersion(version) === null) faults.push(`${label}: the version of ${name} is not a version.`);
+	return faults;
+}
+/**
+* This function reads the content of a file of data stamps. It gives each fault of the content, so a page with no versions
+* or no run date fails here.
+*/
+function parseDataStamps(raw) {
+	const file = record(raw);
+	if (file === null) return {
+		ok: false,
+		faults: ["The file is not an object."]
+	};
+	if (file["schema"] !== "data-stamp/1") return {
+		ok: false,
+		faults: [`The schema is not ${DATA_STAMP_SCHEMA}.`]
+	};
+	const pages = file["pages"];
+	if (!Array.isArray(pages) || pages.length === 0) return {
+		ok: false,
+		faults: ["The file has no pages."]
+	};
+	const faults = [];
+	for (const item of pages) {
+		const page = record(item);
+		if (page === null || typeof page["page"] !== "string" || page["page"] === "") {
+			faults.push("A stamp has no page.");
+			continue;
+		}
+		const at = page["page"];
+		const runs = page["runs"];
+		if (!Array.isArray(runs) || runs.length === 0) faults.push(`${at}: the page names no run.`);
+		else for (const run of runs) faults.push(...runFaults(run, at));
+		if (page["inFlight"] !== void 0) faults.push(...runFaults(page["inFlight"], `${at}, in flight`));
+	}
+	return faults.length > 0 ? {
+		ok: false,
+		faults
+	} : {
+		ok: true,
+		stamps: raw
+	};
+}
+/** This function gives the count of minor versions from `used` to `latest`. A newer major version counts as no limit. */
+function minorsBehind(used, latest) {
+	const a = parseVersion(used);
+	const b = parseVersion(latest);
+	if (a === null || b === null) return Number.POSITIVE_INFINITY;
+	if (a.major !== b.major) return b.major > a.major ? Number.POSITIVE_INFINITY : 0;
+	return Math.max(0, b.minor - a.minor);
+}
+/** This function gives the newest stable version of a package on npm at a time, or undefined when npm has none. */
+function latestAt(times, name, date) {
+	const limit = Date.parse(date);
+	return times.filter((t) => t.name === name && Date.parse(t.date) <= limit && parseVersion(t.version)?.prerelease.length === 0).map((t) => t.version).sort(compareVersions).at(-1);
+}
+const ageInDays = (date, now) => (now - Date.parse(date)) / DAY_MS;
+/** This function tells if a run uses a newer version of an engine than another run. */
+function hasNewerEngine(run, than) {
+	return Object.entries(run.engines).some(([name, version]) => {
+		const old = than.engines[name];
+		return old !== void 0 && compareVersions(version, old) > 0;
+	});
+}
+/**
+* This function applies the rules of the gate to the stamps.
+*
+* - The data of each page is at most `maxAgeDays` old, or a run on newer engines is in flight.
+* - The engines of the newest run are at most `maxMinorsBehind` behind npm at the start of that run.
+* - A run in flight has the same age limit, so an old stamp does not hold the gate open.
+*/
+function checkFreshness(stamps, options) {
+	const { times, maxAgeDays = 3, maxMinorsBehind = 1 } = options;
+	const now = Date.parse(options.now);
+	const faults = [];
+	const notRun = [];
+	for (const stamp of stamps.pages) {
+		for (const run of [...stamp.runs, ...stamp.inFlight === void 0 ? [] : [stamp.inFlight]]) if (ageInDays(run.date, now) < 0) faults.push(`${stamp.page}: the run ${run.id} has a date after the check.`);
+		const flight = stamp.inFlight;
+		const flying = flight !== void 0 && ageInDays(flight.date, now) <= maxAgeDays;
+		if (flight !== void 0 && !flying) faults.push(`${stamp.page}: the run ${flight.id} is in flight for more than ${maxAgeDays} days.`);
+		for (const run of stamp.runs) {
+			const age = ageInDays(run.date, now);
+			if (age > maxAgeDays && !(flying && hasNewerEngine(flight, run))) faults.push(`${stamp.page}: the run ${run.id} is ${age.toFixed(1)} days old, over the limit of ${maxAgeDays}, and no run on newer engines is in flight.`);
+		}
+		const newest = flight ?? [...stamp.runs].sort((a, b) => Date.parse(a.date) - Date.parse(b.date)).at(-1);
+		if (newest === void 0) continue;
+		for (const [name, version] of Object.entries(newest.engines)) {
+			const latest = latestAt(times, name, newest.date);
+			if (latest === void 0) notRun.push(`${stamp.page}: npm gives no version of ${name} at the start of the run ${newest.id}.`);
+			else if (minorsBehind(version, latest) > maxMinorsBehind) faults.push(`${stamp.page}: the run ${newest.id} used ${name} ${version}, and npm had ${latest} at its start. The limit is ${maxMinorsBehind} minor version behind.`);
+		}
+	}
+	return {
+		faults,
+		notRun
+	};
+}
+/** The help of the command `site-pages freshness`. */
+const FRESHNESS_HELP = `Usage: site-pages freshness --stamps <file> [options]
+
+Examine the data stamps of the measured pages of a site.
+
+  --stamps <file>  The file of data stamps, schema ${DATA_STAMP_SCHEMA}. (necessary)
+  --now <time>     The ISO time of the check. The default is the time of the call.
+  --help           Show this text.
+
+The exit code is 0 when the stamps pass, 1 for a fault, and 2 for an incorrect command line.
+`;
+/** This function is the command `site-pages freshness`. The `fetch` option is for a test. */
+async function runFreshnessCli(argv, io, fetcher) {
+	let values;
+	try {
+		({values} = parseArgs({
+			args: [...argv],
+			allowPositionals: false,
+			options: {
+				stamps: { type: "string" },
+				now: { type: "string" },
+				help: { type: "boolean" }
+			}
+		}));
+	} catch (error) {
+		io.stderr(`site-pages freshness: ${error instanceof Error ? error.message : String(error)}\n\n${FRESHNESS_HELP}`);
+		return 2;
+	}
+	if (values.help === true) {
+		io.stdout(FRESHNESS_HELP);
+		return 0;
+	}
+	if (values.stamps === void 0) {
+		io.stderr(`site-pages freshness: --stamps is necessary.\n\n${FRESHNESS_HELP}`);
+		return 2;
+	}
+	const path = isAbsolute(values.stamps) ? values.stamps : join(io.cwd, values.stamps);
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		io.stderr(`site-pages freshness: the file ${values.stamps} cannot be read: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	const parsed = parseDataStamps(raw);
+	if (!parsed.ok) {
+		for (const fault of parsed.faults) io.stderr(`${fault}\n`);
+		return 1;
+	}
+	const engines = parsed.stamps.pages.flatMap((p) => [...p.runs, ...p.inFlight === void 0 ? [] : [p.inFlight]]).flatMap((r) => Object.keys(r.engines));
+	const npm = await npmPublishTimes({
+		packages: [...new Set(engines)],
+		...fetcher === void 0 ? {} : { fetch: fetcher }
+	});
+	const result = checkFreshness(parsed.stamps, {
+		now: values.now ?? (/* @__PURE__ */ new Date()).toISOString(),
+		times: npm.times
+	});
+	for (const problem of [...npm.problems, ...result.notRun]) io.stdout(`Not run: ${problem}\n`);
+	for (const fault of result.faults) io.stderr(`${fault}\n`);
+	if (result.faults.length > 0) return 1;
+	io.stdout(`The data stamps of ${parsed.stamps.pages.length} pages pass.\n`);
+	return 0;
+}
 // src/build.ts
 /**
 * The `site-pages build` command. It reads the sources. Then it writes the JSON data and the two
@@ -2402,6 +2591,11 @@ Usage: site-pages check (--out <dir> | --url <url>) [options]
 
 Opens the pages of the site in a headless Chromium at phone and desktop widths. Start
 "site-pages check --help" for its options.
+
+Usage: site-pages freshness --stamps <file> [options]
+
+Examine the data stamps of the measured pages of a site. See
+"site-pages freshness --help" for its options.
 `;
 /**
 * This function reads the command line into the options of `build`.
@@ -2505,6 +2699,6 @@ async function runCli(argv, io) {
 		throw error;
 	}
 }
-export { checkStateOf as $, safeUrl as A, roadmapItems as B, pageShell as C, utcDay as D, shortDate as E, linksOf as F, mergeReleases as G, statusClassOf as H, markdownTables as I, globFiles as J, readChangelogs as K, parseRoadmap as L, RoadmapParseError as M, STATUS_CLASSES as N, escapeHtml as O, buildStatusBoard as P, GITHUB_GRAPHQL as Q, plainText as R, BASE_CSS as S, longDate as T, DEFAULT_CHANGELOGS as U, splitRow as V, ReleaseDataError as W, npmPublishTimes as X, NPM_REGISTRY as Y, GITHUB_API as Z, renderReleasesPage as _, runCli as a, releaseBodyEntries as at, releaseSummary as b, STATUS_SCRIPT as c, parseVersion as ct, renderStatusPage as d, githubOpenWork as et, sectionsOf as f, releasesLead as g, RELEASES_SCRIPT as h, parseBuildArgs as i, parseChangelog as it, OPEN_CLASSES as j, inlineMarkdown as k, classCounts as l, versionOfTag as lt, statusLead as m, UsageError as n, firstSentence as nt, TYPESCRIPT_PROBE as o, compareVersions as ot, slugOf as p, readReleases as q, build as r, headingAnchor as rt, probeScript as s, kindOf as st, HELP as t, githubReleases as tt, openGroups as u, laneCenter as v, dayRange as w, timelineLayout as x, oldestFirst as y, readStatusBoard as z };
+export { DEFAULT_CHANGELOGS as $, BASE_CSS as A, safeUrl as B, RELEASES_SCRIPT as C, oldestFirst as D, laneCenter as E, utcDay as F, linksOf as G, RoadmapParseError as H, escapeHtml as I, plainText as J, markdownTables as K, inlineMarkdown as L, dayRange as M, longDate as N, releaseSummary as O, shortDate as P, statusClassOf as Q, link as R, statusLead as S, renderReleasesPage as T, STATUS_CLASSES as U, OPEN_CLASSES as V, buildStatusBoard as W, roadmapItems as X, readStatusBoard as Y, splitRow as Z, classCounts as _, kindOf as _t, runCli as a, NPM_REGISTRY as at, sectionsOf as b, MAX_MINORS_BEHIND as c, GITHUB_GRAPHQL as ct, minorsBehind as d, githubReleases as dt, ReleaseDataError as et, parseDataStamps as f, firstSentence as ft, STATUS_SCRIPT as g, compareVersions as gt, probeScript as h, releaseBodyEntries as ht, parseBuildArgs as i, globFiles as it, pageShell as j, timelineLayout as k, checkFreshness as l, checkStateOf as lt, TYPESCRIPT_PROBE as m, parseChangelog as mt, UsageError as n, readChangelogs as nt, DATA_STAMP_SCHEMA as o, npmPublishTimes as ot, runFreshnessCli as p, headingAnchor as pt, parseRoadmap as q, build as r, readReleases as rt, MAX_DATA_AGE_DAYS as s, GITHUB_API as st, HELP as t, mergeReleases as tt, latestAt as u, githubOpenWork as ut, openGroups as v, parseVersion as vt, releasesLead as w, slugOf as x, renderStatusPage as y, versionOfTag as yt, listText as z };
 
 //# sourceMappingURL=build.js.map