@mark1russell7/site-pages 0.2.1 → 0.2.3

package/README.md

@@ -368,6 +368,36 @@ The theme `auto` removes `data-theme`, and the CSS of the site then obeys `prefe
 </script>
 ```
 
+## The measures of a site
+
+The file `kpi.json` at the root of a site holds the measures of the project, in the format `kpi/1`. A reader outside the site takes the numbers from this file.
+
+```ts
+import { defineConfig } from "vite";
+import { siteKpi } from "@mark1russell7/site-pages/vite";
+
+export default defineConfig({
+  plugins: [siteKpi({ project: "acme", at: data.at, measures: [{ id: "cases", value: data.cases.length, unit: "cases" }] })],
+});
+```
+
+```ts
+interface KpiFile {
+  format: "kpi/1";
+  project: string;
+  at: string; // the ISO time of the data in UTC, never the time of the build
+  commit: string; // the full commit of the build
+  measures: Array<{ id: string; value: number; unit?: string }>;
+  engines?: Array<{ name: string; version: string }>; // the Status page shows them
+}
+```
+
+- Give `at` from the record of the data. The writer has no default for this field, because a build time hides old data.
+- Without `commit`, the plugin takes `GITHUB_SHA`, else the head of the repository.
+- A fault in the data stops the build, and the old site stays. A fault is a wrong form, a value that is not finite, a repeated id or a time after the check.
+- A site with no Vite build calls `writeKpi(out, input)` from the root entry, before `site-pages build`.
+- `site-pages build` reads the file from the output folder. It adds the file to `data/status.json`, and the Status page shows the measures, the data date and the engines.
+
 ## The shell of a site
 
 The shell is the part of a page that is not its content. The package has two parts of the shell, and each part is optional.

package/build/{build-xJqNIzdO.js → chunks/build.js}

@@ -1,5 +1,5 @@
+import { d as headingDate, f as isShallow, l as gitTagDates, p as originRepository, r as KpiError, s as readKpi, t as KPI_FILE, u as headCommit } from "./kpi.js";
 import { stripTypeScriptTypes } from "node:module";
-import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { parseArgs } from "node:util";
@@ -496,65 +496,6 @@ async function npmPublishTimes(options) {
 		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/glob.ts
 /**
 * A small glob for the changelog files. The syntax has `*` and `?` in one path segment, and `**` for
@@ -2197,6 +2138,15 @@ function openWork(data) {
 	const doneList = done.length === 0 ? `<p class="sp-done sp-small"><span aria-hidden="true">✓</span> No item is done.</p>` : `<details class="sp-done sp-c-done" data-sp-done><summary><span aria-hidden="true">✓</span> ${doneText} <span data-sp-done-label>Show the done items</span></summary><section class="sp-group sp-c-done" data-sp-group data-class="done" aria-label="The done items">${itemTable(done, data, columns)}<p class="sp-callout" data-sp-done-empty hidden>No done item matches the filters.</p></section></details>`;
 	return `<section class="sp-section" aria-labelledby="open-work" data-sp-board><h2 id="open-work">Open work</h2><p class="sp-small sp-muted">Each row of a table of ${link(roadmapUrl(data), `<code>${escapeHtml(file)}</code>`)} with an ID and a status that is not done. The build reads the file, so this list follows each commit.</p>` + meter(items) + (open.length > 0 ? filters : "") + list + doneList + "</section>";
 }
+/** This function renders the measures of `kpi.json`: their values, the date of the data and the engines that made it. */
+function measures(data) {
+	const { kpi } = data;
+	if (kpi === void 0) return "";
+	const rows = kpi.measures.map((measure) => `<tr><th scope="row">${escapeHtml(measure.id)}</th><td>${measure.value}${measure.unit === void 0 ? "" : ` ${escapeHtml(measure.unit)}`}</td></tr>`).join("");
+	const engines = kpi.engines ?? [];
+	const commit = link(`https://github.com/${data.source.github}/commit/${kpi.commit}`, `<code>${kpi.commit.slice(0, 7)}</code>`);
+	return `<section class="sp-section" aria-labelledby="measures"><h2 id="measures">Measures</h2><p>The data of these numbers is from <time datetime="${escapeHtml(kpi.at)}" data-sp-data-date>${escapeHtml(longDate(kpi.at))}</time>. The build of ${commit} published them.</p>` + (engines.length > 0 ? `<p>The engines of the data: ${listText(engines.map((engine) => `<code>${escapeHtml(engine.name)}</code> ${escapeHtml(engine.version)}`))}.</p>` : "") + `<div class="sp-table-box" tabindex="0" role="region" aria-label="Measures"><table class="sp-table"><thead><tr><th scope="col">Measure</th><th scope="col">Value</th></tr></thead><tbody>${rows}</tbody></table></div></section>`;
+}
 function when(date) {
 	const text = escapeHtml(longDate(date));
 	return `<time datetime="${escapeHtml(date)}" title="${text}" data-sp-rel>${text}</time>`;
@@ -2333,7 +2283,7 @@ function renderStatusPage(data, options) {
 		title: "Status",
 		description: lead,
 		current: "status",
-		main: `<h1>Status</h1><p class="sp-lead">${escapeHtml(lead)}</p><p class="sp-small sp-muted">The build reads the roadmap file and GitHub again after each commit and on a schedule.</p>` + (data.source.roadmap ? openWork(data) : "") + pullRequests(data) + issues(data),
+		main: `<h1>Status</h1><p class="sp-lead">${escapeHtml(lead)}</p><p class="sp-small sp-muted">The build reads the roadmap file and GitHub again after each commit and on a schedule.</p>` + measures(data) + (data.source.roadmap ? openWork(data) : "") + pullRequests(data) + issues(data),
 		script: STATUS_SCRIPT
 	}, options);
 }
@@ -2366,9 +2316,10 @@ function write(file, content, files) {
 }
 /**
 * This function reads the sources and writes `data/releases.json`, `data/status.json`,
-* `releases/index.html` and `status/index.html` into the output folder.
+* `releases/index.html` and `status/index.html` into the output folder. When the output folder has a
+* `kpi.json`, the status data and the status page show it.
 *
-* @throws ReleaseDataError or RoadmapParseError when a source on disk is not correct
+* @throws ReleaseDataError, RoadmapParseError or KpiError when a source on disk is not correct
 */
 async function build(options) {
 	const { repoDir, repository, warn = () => {} } = options;
@@ -2389,7 +2340,9 @@ async function build(options) {
 		warn,
 		...fetcher
 	});
-	const status = await readStatusBoard({
+	const kpiPath = join(out, KPI_FILE);
+	const kpi = existsSync(kpiPath) ? readKpi(readFileSync(kpiPath, "utf8"), Date.parse(now)) : void 0;
+	const board = await readStatusBoard({
 		repoDir,
 		roadmap: options.roadmap ?? null,
 		owner,
@@ -2399,6 +2352,10 @@ async function build(options) {
 		generatedAt: now,
 		...fetcher
 	});
+	const status = kpi === void 0 ? board : {
+		...board,
+		kpi
+	};
 	if (!status.github.available) warn(`the status page has no GitHub data: ${status.github.reason ?? "no reason"}.`);
 	const files = [];
 	write(join(out, "data", "releases.json"), `${JSON.stringify(releases, null, 2)}\n`, files);
@@ -2541,13 +2498,13 @@ async function runCli(argv, io) {
 		io.stdout(`site-pages: ${plural(result.releases.length, "release")}, ${plural(result.status.items.length, "roadmap item")} (${open} open), ${github}.\n` + result.files.map((file) => `  ${file}\n`).join(""));
 		return 0;
 	} catch (error) {
-		if (error instanceof ReleaseDataError || error instanceof RoadmapParseError || error?.code === "ENOENT") {
+		if (error instanceof ReleaseDataError || error instanceof RoadmapParseError || error instanceof KpiError || error?.code === "ENOENT") {
 			io.stderr(`site-pages: ${error.message}\n`);
 			return 1;
 		}
 		throw error;
 	}
 }
-export { originRepository 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, isShallow as Q, plainText as R, BASE_CSS as S, longDate as T, DEFAULT_CHANGELOGS as U, splitRow as V, ReleaseDataError as W, headCommit as X, gitTagDates as Y, headingDate as Z, renderReleasesPage as _, runCli as a, githubOpenWork as at, releaseSummary as b, STATUS_SCRIPT as c, headingAnchor as ct, renderStatusPage as d, compareVersions as dt, NPM_REGISTRY as et, sectionsOf as f, kindOf as ft, releasesLead as g, RELEASES_SCRIPT as h, parseBuildArgs as i, checkStateOf as it, OPEN_CLASSES as j, inlineMarkdown as k, classCounts as l, parseChangelog as lt, statusLead as m, versionOfTag as mt, UsageError as n, GITHUB_API as nt, TYPESCRIPT_PROBE as o, githubReleases as ot, slugOf as p, parseVersion as pt, readReleases as q, build as r, GITHUB_GRAPHQL as rt, probeScript as s, firstSentence as st, HELP as t, npmPublishTimes as tt, openGroups as u, releaseBodyEntries as ut, laneCenter as v, dayRange as w, timelineLayout as x, oldestFirst as y, readStatusBoard as z };
+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 };
 
-//# sourceMappingURL=build-xJqNIzdO.js.map
+//# sourceMappingURL=build.js.map