@mark1russell7/site-pages 0.2.7 → 0.2.9

package/build/chunks/freshness.js

@@ -0,0 +1,741 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { parseArgs } from "node:util";
+// src/data/versions.ts
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/** This function gives the parts of a version, or null when the text is not a SemVer version. */
+function parseVersion(version) {
+	const match = SEMVER.exec(version);
+	if (!match) return null;
+	return {
+		major: Number(match[1]),
+		minor: Number(match[2]),
+		patch: Number(match[3]),
+		prerelease: match[4] ? match[4].split(".") : []
+	};
+}
+/**
+* This function compares two versions by the SemVer precedence. It gives a negative number when `a`
+* is older, a positive number when `a` is newer, and 0 for the same version. A text that is not a
+* version comes before each version.
+*/
+function compareVersions(a, b) {
+	const x = parseVersion(a);
+	const y = parseVersion(b);
+	if (!x || !y) return x ? 1 : y ? -1 : a.localeCompare(b);
+	const core = x.major - y.major || x.minor - y.minor || x.patch - y.patch;
+	if (core !== 0) return core;
+	if (x.prerelease.length === 0 || y.prerelease.length === 0) return y.prerelease.length - x.prerelease.length;
+	for (let index = 0; index < Math.max(x.prerelease.length, y.prerelease.length); index++) {
+		const p = x.prerelease[index];
+		const q = y.prerelease[index];
+		if (p === void 0) return -1;
+		if (q === void 0) return 1;
+		if (p === q) continue;
+		const pNumber = /^\d+$/.test(p);
+		const qNumber = /^\d+$/.test(q);
+		if (pNumber && qNumber) return Number(p) - Number(q);
+		if (pNumber !== qNumber) return pNumber ? -1 : 1;
+		return p < q ? -1 : 1;
+	}
+	return 0;
+}
+/**
+* This function gives the kind of a version. The oldest version of the list is "first". The caller
+* tells if the version is the oldest.
+*/
+function kindOf(version, oldest) {
+	if (oldest) return "first";
+	const parsed = parseVersion(version);
+	if (!parsed) return "patch";
+	if (parsed.major > 0 && parsed.minor === 0 && parsed.patch === 0) return "major";
+	return parsed.patch === 0 ? "minor" : "patch";
+}
+/**
+* This function reads the version of a git tag. It knows `1.2.3`, `v1.2.3` and the tags of Changesets:
+* `name@1.2.3` and `@scope/name@1.2.3`. It gives null for another tag.
+*/
+function versionOfTag(tag) {
+	const match = /^(?:(.+)@)?v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?)$/.exec(tag.trim());
+	if (!match || match[2] === void 0 || !parseVersion(match[2])) return null;
+	return {
+		version: match[2],
+		package: match[1] ?? null
+	};
+}
+// src/data/npm.ts
+/** The public npm registry. */
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const object = (value) => value !== null && typeof value === "object" ? value : {};
+function message(error) {
+	if (object(error)["name"] === "TimeoutError") return "npm did not answer in time";
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* This function reads the publication time of each version of the packages from the npm registry.
+* A scope (`@name`) gives each package of the scope. It does not throw. Each failure gives a
+* message in `problems`.
+*/
+async function npmPublishTimes(options) {
+	const { registry = NPM_REGISTRY, timeoutMs = 15e3 } = options;
+	const fetcher = options.fetch ?? globalThis.fetch;
+	const problems = [];
+	const times = [];
+	if (typeof fetcher !== "function") return {
+		times,
+		problems: ["this Node has no fetch"]
+	};
+	const get = async (url) => {
+		const response = await fetcher(url, {
+			headers: { accept: "application/json" },
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		return response.json();
+	};
+	const names = /* @__PURE__ */ new Set();
+	for (const entry of options.packages.map((name) => name.trim()).filter(Boolean)) {
+		if (!/^@[^/]+$/.test(entry)) {
+			names.add(entry);
+			continue;
+		}
+		try {
+			const found = object(await get(`${registry}/-/v1/search?text=scope:${encodeURIComponent(entry.slice(1))}&size=250`));
+			const objects = Array.isArray(found["objects"]) ? found["objects"] : [];
+			const before = names.size;
+			for (const item of objects) {
+				const name = object(object(item)["package"])["name"];
+				if (typeof name === "string" && name.startsWith(`${entry}/`)) names.add(name);
+			}
+			if (names.size === before) problems.push(`npm has no package in the scope ${entry}`);
+		} catch (error) {
+			problems.push(`npm did not give the packages of ${entry}: ${message(error)}`);
+		}
+	}
+	const queue = [...names].sort();
+	const worker = async () => {
+		for (let name = queue.shift(); name !== void 0; name = queue.shift()) try {
+			const packument = object(await get(`${registry}/${name.replaceAll("/", "%2f")}`));
+			const published = object(packument["versions"]);
+			for (const [version, date] of Object.entries(object(packument["time"]))) {
+				if (version === "created" || version === "modified" || typeof date !== "string") continue;
+				if (!(version in published)) continue;
+				times.push({
+					name,
+					version,
+					date
+				});
+			}
+		} catch (error) {
+			problems.push(`npm did not give the versions of ${name}: ${message(error)}`);
+		}
+	};
+	await Promise.all(Array.from({ length: 4 }, worker));
+	times.sort((a, b) => a.name.localeCompare(b.name) || a.date.localeCompare(b.date));
+	return {
+		times,
+		problems
+	};
+}
+// src/data/git.ts
+/**
+* The git source: the tags with their dates, the commit of the build and the GitHub remote. Each
+* function gives an empty result when git or the repository is not available.
+*/
+/** This function starts git in a folder and gives its output, or null when git fails. */
+function git(repoDir, ...args) {
+	try {
+		return execFileSync("git", args, {
+			cwd: repoDir,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			windowsHide: true
+		});
+	} catch {
+		return null;
+	}
+}
+/** This function tells if the clone is shallow. A shallow clone has not all the tags and commits. */
+function isShallow(repoDir) {
+	return git(repoDir, "rev-parse", "--is-shallow-repository")?.trim() === "true";
+}
+/** This function gives each tag of the repository with its date. An annotated tag has its own date. */
+function gitTagDates(repoDir) {
+	const output = git(repoDir, "for-each-ref", "--format=%(refname:strip=2) %(creatordate:iso-strict)", "refs/tags");
+	if (!output) return [];
+	const tags = [];
+	for (const line of output.split(/\r?\n/)) {
+		const match = /^(\S+) (\S+)$/.exec(line.trim());
+		if (match?.[1] && match[2]) tags.push({
+			tag: match[1],
+			date: match[2]
+		});
+	}
+	return tags;
+}
+/**
+* This function gives the date of the oldest commit that added a version heading to a changelog,
+* or null. The path of the changelog starts at `repoDir`.
+*/
+function headingDate(repoDir, version, file) {
+	const dates = (git(repoDir, "log", "--format=%cI", `-S## ${version}`, "--", file) ?? "").trim().split(/\r?\n/).filter(Boolean);
+	return dates[dates.length - 1] ?? null;
+}
+/** This function gives the full SHA of `HEAD`, or null. */
+function headCommit(repoDir) {
+	const sha = git(repoDir, "rev-parse", "HEAD")?.trim();
+	return sha && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+}
+/** This function gives "owner/name" of the GitHub remote "origin", or null. */
+function originRepository(repoDir) {
+	const url = git(repoDir, "remote", "get-url", "origin")?.trim() ?? "";
+	const match = /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(url);
+	return match ? `${match[1]}/${match[2]}` : null;
+}
+// src/data/kpi.ts
+/**
+* The file `kpi.json` at the root of a site, format `kpi/1`. A reader outside the site takes the measures of the project
+* from this file. Thus a number on a progress page comes from a record and not from a person.
+*
+* The field `at` is the time of the data and not the time of the build. Thus the writer has no default for it.
+* A measure can have its own `at` when its data is from another time than the rest of the file.
+*/
+/** The name of the format. A new format gets a new name, so that an old reader refuses it. */
+const KPI_FORMAT = "kpi/1";
+/** The name of the file at the root of the built site. */
+const KPI_FILE = "kpi.json";
+/** The form of a project and a measure. A double hyphen separates fields in the file name of a reading. */
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The form of a time in UTC, with or without seconds. */
+const UTC_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?Z$/;
+/** The form of a full commit. */
+const COMMIT = /^[0-9a-f]{40}$/;
+/** The clock difference between two computers that the check accepts, in milliseconds. */
+const CLOCK_MARGIN = 3e5;
+/** An error in the data of `kpi.json`. The field `problems` has one line for each fault. */
+var KpiError = class extends Error {
+	problems;
+	constructor(problems) {
+		super(`${KPI_FILE} is not correct: ${problems.join(" ")}`);
+		this.name = "KpiError";
+		this.problems = problems;
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isText = (value) => typeof value === "string" && value.trim() !== "";
+/** This function gives the fault of a time of the data, or an empty list. The name tells which field it is. */
+function timeProblems(at, name, now) {
+	if (typeof at !== "string" || !UTC_TIME.test(at) || Number.isNaN(Date.parse(at))) return [`${name} is not a time in UTC.`];
+	return Date.parse(at) > now + CLOCK_MARGIN ? [`The time of the data ${at} is after the time of the check.`] : [];
+}
+/** This function gives the faults of one measure. */
+function measureProblems(value, index, seen, now) {
+	if (!isRecord(value)) return [`Measure ${index} is not an object.`];
+	const { id, value: amount, unit, at } = value;
+	const problems = [];
+	if (typeof id !== "string" || !SLUG.test(id)) problems.push(`Measure ${index} has no id of lowercase words with single hyphens.`);
+	else if (seen.has(id)) problems.push(`The id ${id} occurs two times.`);
+	else seen.add(id);
+	if (typeof amount !== "number" || !Number.isFinite(amount)) problems.push(`Measure ${index} has no finite number as its value.`);
+	if (unit !== void 0 && !isText(unit)) problems.push(`Measure ${index} has a unit that is not a text.`);
+	if (at !== void 0) problems.push(...timeProblems(at, `The field at of measure ${index}`, now));
+	return problems;
+}
+/** This function gives the faults of the list of engines. */
+function engineProblems(value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) return ["The field engines is not a list."];
+	return value.flatMap((engine, index) => isRecord(engine) && isText(engine["name"]) && isText(engine["version"]) ? [] : [`Engine ${index} has no name and version.`]);
+}
+/**
+* This function gives the faults of a parsed `kpi.json`, or an empty list.
+*
+* @param value - The parsed file.
+* @param now - The time of the check, in milliseconds. A time of the data after this time is a fault.
+*/
+function kpiProblems(value, now = Date.now()) {
+	if (!isRecord(value)) return ["The file is not an object."];
+	const problems = [];
+	if (value["format"] !== "kpi/1") problems.push(`The format is not ${KPI_FORMAT}.`);
+	const { project, at, commit, measures } = value;
+	if (typeof project !== "string" || !SLUG.test(project)) problems.push("The project is not lowercase words with single hyphens.");
+	problems.push(...timeProblems(at, "The field at", now));
+	if (typeof commit !== "string" || !COMMIT.test(commit)) problems.push("The commit is not a full commit.");
+	if (!Array.isArray(measures) || measures.length === 0) problems.push("The file has no measures.");
+	else {
+		const seen = /* @__PURE__ */ new Set();
+		problems.push(...measures.flatMap((measure, index) => measureProblems(measure, index, seen, now)));
+	}
+	problems.push(...engineProblems(value["engines"]));
+	return problems;
+}
+/** This function gives a copy of a measure with only its known fields. */
+function cleanMeasure({ id, value, unit, at }) {
+	return {
+		id,
+		value,
+		...unit === void 0 ? {} : { unit },
+		...at === void 0 ? {} : { at }
+	};
+}
+/** This function gives a copy of an engine with only its known fields. */
+function cleanEngine({ name, version }) {
+	return {
+		name,
+		version
+	};
+}
+/**
+* This function gives the checked content of `kpi.json`. The file has only its known fields, in a fixed order.
+*
+* @throws KpiError when the data is not correct
+*/
+function kpiFile(input, now) {
+	const problems = kpiProblems({
+		format: KPI_FORMAT,
+		...input
+	}, now);
+	if (problems.length > 0) throw new KpiError(problems);
+	const { project, at, commit, measures, engines } = input;
+	const file = {
+		format: KPI_FORMAT,
+		project,
+		at,
+		commit,
+		measures: measures.map(cleanMeasure)
+	};
+	return engines === void 0 ? file : {
+		...file,
+		engines: engines.map(cleanEngine)
+	};
+}
+/** This function gives the text of `kpi.json`. */
+function kpiText(file) {
+	return `${JSON.stringify(file, null, 2)}\n`;
+}
+/**
+* This function reads the text of a `kpi.json`.
+*
+* @throws KpiError when the text is not correct
+*/
+function readKpi(text, now) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		throw new KpiError([`The file is not JSON: ${error instanceof Error ? error.message : String(error)}`]);
+	}
+	const problems = kpiProblems(value, now);
+	if (problems.length > 0) throw new KpiError(problems);
+	const { project, at, commit, measures, engines } = value;
+	return kpiFile(engines === void 0 ? {
+		project,
+		at,
+		commit,
+		measures
+	} : {
+		project,
+		at,
+		commit,
+		measures,
+		engines
+	}, now);
+}
+/**
+* This function writes `kpi.json` into the built output folder of a site, and gives the path of the file.
+*
+* @throws KpiError when the data is not correct
+*/
+function writeKpi(out, input, now) {
+	const text = kpiText(kpiFile(input, now));
+	mkdirSync(out, { recursive: true });
+	const file = join(out, KPI_FILE);
+	writeFileSync(file, text);
+	return file;
+}
+// src/render/html.ts
+/**
+* The HTML helpers of the pages: the escape functions and a small inline Markdown renderer.
+*/
+const ESCAPES = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;",
+	"'": "&#39;"
+};
+/** This function escapes a text for HTML content and for an attribute value in double quotes. */
+function escapeHtml(text) {
+	return String(text).replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+}
+/**
+* This function removes the control characters and the spaces (U+0000 to U+0020) at the two ends
+* of a text. A loop does it, because the regular expression `[\u0000- ]+$` backtracks. For a long
+* run of these characters, its time grows with the square of the length.
+*/
+function trimControl(text) {
+	let start = 0;
+	let end = text.length;
+	while (start < end && text.charCodeAt(start) <= 32) start++;
+	while (end > start && text.charCodeAt(end - 1) <= 32) end--;
+	return text.slice(start, end);
+}
+/**
+* This function gives a URL that a link can hold, or null. It accepts `http:`, `https:` and
+* `mailto:` URLs, and relative URLs. It refuses each other scheme, for example `javascript:`.
+*
+* The URL parser of a browser removes each tab and line break, and the control characters and
+* spaces at the two ends. This function removes them before the scheme check, as the browser does.
+* Thus a control character before `javascript:` does not hide the scheme.
+*/
+function safeUrl(url) {
+	const trimmed = trimControl(url.trim().replace(/[\t\n\r]/g, ""));
+	if (/^(?:https?:|mailto:)/i.test(trimmed)) return trimmed;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed) || /^[/\\]{2}/.test(trimmed)) return null;
+	return trimmed;
+}
+/** This function gives an `<a>` element, or the escaped text when the URL is not safe. */
+function link(url, html, attributes = "") {
+	const href = safeUrl(url);
+	return href === null ? html : `<a href="${escapeHtml(href)}"${attributes ? ` ${attributes}` : ""}>${html}</a>`;
+}
+/** The emphasis of a text without code spans or links. The text is already escaped. */
+function emphasis(escaped) {
+	return escaped.replace(/\*\*([^*]+?)\*\*/g, "<strong>$1</strong>").replace(/(^|[^\w*])\*([^*\s][^*]*?)\*(?![\w*])/g, "$1<em>$2</em>").replace(/(^|[^\w])_([^_\s][^_]*?)_(?![\w])/g, "$1<em>$2</em>");
+}
+const INLINE = "`([^`]+)`|\\[((?:[^\\]`]|`[^`]*`)+)\\]\\(([^)\\s]+)\\)";
+/**
+* This function renders inline Markdown as HTML: code spans, links, strong text and emphasis. It
+* escapes all other text, so the result is safe.
+*/
+function inlineMarkdown(markdown) {
+	const text = String(markdown ?? "");
+	const pattern = new RegExp(INLINE, "g");
+	let html = "";
+	let last = 0;
+	for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+		html += emphasis(escapeHtml(text.slice(last, match.index)));
+		if (match[1] !== void 0) html += `<code>${escapeHtml(match[1])}</code>`;
+		else html += link(match[3] ?? "", inlineMarkdown(match[2] ?? ""));
+		last = match.index + match[0].length;
+	}
+	return html + emphasis(escapeHtml(text.slice(last)));
+}
+/** This function gives "1 item" or "2 items". */
+function plural(count, word, many = `${word}s`) {
+	return `${count} ${count === 1 ? word : many}`;
+}
+/** This function gives "a", "a and b" or "a, b and c". */
+function listText(parts) {
+	if (parts.length <= 1) return parts.join("");
+	return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+// 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.
+* A fixed study has no age limit. A page with a longer limit names the reason and the scheduled workflow that meets the limit.
+* 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;
+/** The longest limit of a page, in days, with no ruling for that site. */
+const MAX_LIMIT_DAYS_WITHOUT_RULING = 14;
+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 gives the faults of the age limit of one page. */
+function limitFaults(raw, at) {
+	const limit = record(raw);
+	if (limit === null) return [`${at}: the limit is not an object.`];
+	const faults = [];
+	const days = limit["days"];
+	if (typeof days !== "number" || !Number.isFinite(days) || days <= 0) faults.push(`${at}: the limit has no count of days.`);
+	if (typeof limit["reason"] !== "string" || limit["reason"].trim() === "") faults.push(`${at}: the limit has no reason.`);
+	if (typeof limit["workflow"] !== "string" || limit["workflow"] === "") faults.push(`${at}: the limit names no workflow.`);
+	const ruling = limit["ruling"];
+	if (ruling !== void 0 && (typeof ruling !== "string" || !ruling.startsWith("https://"))) faults.push(`${at}: the ruling of the limit has no https link.`);
+	if (typeof days === "number" && days > 14 && ruling === void 0) faults.push(`${at}: a limit over 14 days needs a ruling for this site.`);
+	return faults;
+}
+/** This function gives the faults of the fields of a page that change the age rule. */
+function ageRuleFaults(page, at) {
+	const faults = [];
+	const study = page["study"];
+	if (study !== void 0 && study !== true) faults.push(`${at}: the field study is not true.`);
+	if (study === true && page["limit"] !== void 0) faults.push(`${at}: a fixed study has no limit.`);
+	if (study === true && page["inFlight"] !== void 0) faults.push(`${at}: a fixed study has no run in flight.`);
+	if (page["limit"] !== void 0) faults.push(...limitFaults(page["limit"], at));
+	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`));
+		faults.push(...ageRuleFaults(page, at));
+	}
+	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 gives the values of one field of a cron line, or undefined for a form that it cannot read. */
+function cronValues(field, low, high) {
+	const values = /* @__PURE__ */ new Set();
+	for (const part of field.split(",")) {
+		const match = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+		if (match === null) return void 0;
+		const [, range = "", step = "1"] = match;
+		const [from = low, to = from] = range === "*" ? [low, high] : range.split("-").map(Number);
+		const by = Number(step);
+		if (by <= 0 || from < low || to > high || from > to) return void 0;
+		for (let value = from; value <= to; value += by) values.add(value);
+	}
+	return values;
+}
+/** This function gives the start of each day of a cron line, in a span of two years. It gives undefined for a line that it cannot read. */
+function cronDays(line, from, days) {
+	const fields = line.trim().split(/\s+/);
+	if (fields.length !== 5) return void 0;
+	const [minute = "", hour = "", dayOfMonth = "", month = "", dayOfWeek = ""] = fields;
+	const minutes = cronValues(minute, 0, 59);
+	const hours = cronValues(hour, 0, 23);
+	const monthDays = cronValues(dayOfMonth, 1, 31);
+	const months = cronValues(month, 1, 12);
+	const weekDays = cronValues(dayOfWeek, 0, 6);
+	if (minutes === void 0 || hours === void 0 || monthDays === void 0 || months === void 0 || weekDays === void 0) return void 0;
+	const firstTime = (Math.min(...hours) * 60 + Math.min(...minutes)) * 6e4;
+	const starts = [];
+	for (let day = 0; day < days; day += 1) {
+		const time = from + day * DAY_MS;
+		const date = new Date(time);
+		if (!months.has(date.getUTCMonth() + 1)) continue;
+		const onMonthDay = monthDays.has(date.getUTCDate());
+		const onWeekDay = weekDays.has(date.getUTCDay());
+		if (dayOfMonth !== "*" && dayOfWeek !== "*" ? onMonthDay || onWeekDay : onMonthDay && onWeekDay) starts.push(time + firstTime);
+	}
+	return starts;
+}
+/** This function gives the cron text of one line of a workflow in a list, or an empty list for another line. */
+function cronLine(line) {
+	const text = line.trim().replace(/^- */, "");
+	if (!text.startsWith("cron:")) return [];
+	return [(text.slice(5).split("#")[0]?.trim() ?? "").replaceAll("\"", "").replaceAll("'", "")];
+}
+/**
+* This function gives the largest gap between the scheduled starts of a workflow, in days. The gap counts from the first start of a day.
+* It gives a text in place of the gap for a workflow with no schedule, and for a line that it cannot read. The text names the line, and the gate fails on it.
+*/
+function scheduleGapDays(workflow) {
+	const lines = workflow.split("\n").flatMap(cronLine);
+	if (lines.length === 0) return "the workflow has no line `cron:`";
+	const from = Date.UTC(2027, 0, 1);
+	const span = 731;
+	const starts = [];
+	for (const line of lines) {
+		const days = cronDays(line, from, span);
+		if (days === void 0) return `the gate cannot read the line \`cron: ${line}\``;
+		starts.push(...days);
+	}
+	if (starts.length < 2) return `the lines \`cron: ${lines.join("`, `cron: ")}\` give fewer than two starts in two years`;
+	starts.sort((a, b) => a - b);
+	let largest = 0;
+	for (let index = 1; index < starts.length; index += 1) largest = Math.max(largest, ((starts[index] ?? 0) - (starts[index - 1] ?? 0)) / DAY_MS);
+	return largest;
+}
+/** 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.
+* - A page with its own limit uses that limit, and the schedule of its workflow meets the limit.
+* - A fixed study has no age limit and no limit of the engines, because it tells about the versions that it names.
+*/
+function checkFreshness(stamps, options) {
+	const { times, maxAgeDays: defaultAge = 3, maxMinorsBehind = 1, schedules = {} } = 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.`);
+		if (stamp.study === true) continue;
+		const maxAgeDays = stamp.limit?.days ?? defaultAge;
+		if (stamp.limit !== void 0) {
+			const gap = schedules[stamp.limit.workflow];
+			if (gap === void 0 || typeof gap === "string") faults.push(`${stamp.page}: the limit of ${maxAgeDays} days has no schedule that the gate can read in ${stamp.limit.workflow}: ${gap ?? "the check has no read of this workflow"}.`);
+			else if (gap > maxAgeDays) faults.push(`${stamp.page}: the schedule of ${stamp.limit.workflow} has a gap of ${gap.toFixed(1)} days, over the limit of ${maxAgeDays}.`);
+		}
+		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 gives the largest gap of the schedule in a workflow file. It gives a text for a file that it cannot read. */
+function readSchedule(path) {
+	try {
+		return scheduleGapDays(readFileSync(path, "utf8"));
+	} catch (error) {
+		return `the file cannot be read: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
+/** 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.filter((p) => p.study !== true).flatMap((p) => [...p.runs, ...p.inFlight === void 0 ? [] : [p.inFlight]]).flatMap((r) => Object.keys(r.engines));
+	const schedules = {};
+	for (const page of parsed.stamps.pages) if (page.limit !== void 0) schedules[page.limit.workflow] = readSchedule(join(io.cwd, page.limit.workflow));
+	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,
+		schedules
+	});
+	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;
+}
+export { npmPublishTimes as A, writeKpi as C, isShallow as D, headingDate as E, kindOf as M, parseVersion as N, originRepository as O, versionOfTag as P, readKpi as S, headCommit as T, KPI_FORMAT as _, checkFreshness as a, kpiProblems as b, parseDataStamps as c, inlineMarkdown as d, link as f, KPI_FILE as g, safeUrl as h, MAX_MINORS_BEHIND as i, compareVersions as j, NPM_REGISTRY as k, runFreshnessCli as l, plural as m, MAX_DATA_AGE_DAYS as n, latestAt as o, listText as p, MAX_LIMIT_DAYS_WITHOUT_RULING as r, minorsBehind as s, DATA_STAMP_SCHEMA as t, escapeHtml as u, KpiError as v, gitTagDates as w, kpiText as x, kpiFile as y };
+
+//# sourceMappingURL=freshness.js.map