@mark1russell7/site-pages 0.2.14 → 0.2.19

package/README.md

@@ -199,6 +199,18 @@ The pipeline needs the full history for the tags and the commits. Use `fetch-dep
 
 For a monorepo with one version for all its packages, give `--group` and the name of one package. Then only its changelog gives the versions, and the dates come from its tags. Without `--group`, each version of each source is a version.
 
+`changelogFaults(markdown, { from, fixedGroup })` examines a changelog and gives its faults:
+
+- An empty section.
+- A section with only dependency lines on a break of the version rule.
+- A first statement that names only the version kind.
+- A break of the version rule with no mark.
+- A mark on a release with no break.
+
+The option `from` leaves out older sections. The option `fixedGroup` passes a section with no change or with only PATCH changes, because its raise comes from another package of the group.
+
+`sectionMarksBreak(section)` tells if the text of a section marks a break. The marks are the heading `### Breaking` and the words "has breaking changes". A page that counts breaks uses this function.
+
 A repository can have no changelog and no GitHub release. Then each npm version of each package of `--packages` is a release:
 
 - The label is the version when there is one package. With more packages, the label is the name without its scope and the version, for example `service@0.5.8`.
@@ -397,6 +409,14 @@ The class sets `overflow-x: auto` and the background color of the box. Set `--sc
 }
 ```
 
+Markdown has no way to set the class of a table. For a Markdown page, add the plugin `rehypeScrollCue` of the entry `@mark1russell7/site-pages/vite`. It gives the class, a tab stop and a label to each table:
+
+```js
+import { rehypeScrollCue } from "@mark1russell7/site-pages/vite";
+
+export default defineConfig({ markdown: { rehypePlugins: [rehypeScrollCue] } });
+```
+
 ## The page helpers
 
 The entry `@mark1russell7/site-pages/chrome` has small helpers for the script of a page. It imports no Node.js module, so a site can bundle it for the browser. The package root does not export these helpers. Thus a Node.js program that imports the root gets no DOM types.
@@ -452,13 +472,14 @@ interface KpiFile {
   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; at?: string }>;
+  measures: Array<{ id: string; value: number; unit?: string; at?: string; notCounted?: 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.
 - Give `at` on a measure when its data is from another time than the file. The Status page then shows a date for each measure.
+- Give `notCounted` on a count of faults, for example a count of old text. The text names what the count does not read, so a 0 does not seem to tell more than it measured. The Status page shows the text.
 - 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. The time rules apply to the file and to each measure.
 - A site with no Vite build calls `writeKpi(out, input)` from the root entry, before `site-pages build`.

package/build/chunks/build.js

@@ -96,6 +96,138 @@ function parseChangelog(markdown) {
 		entries: raw.map(entryOf).filter((change) => change !== null)
 	}));
 }
+const KIND_WORDS = /* @__PURE__ */ new Set([
+	"major",
+	"minor",
+	"patch"
+]);
+const FILL_WORDS = /* @__PURE__ */ new Set([
+	"a",
+	"the",
+	"this",
+	"is",
+	"raises",
+	"bumps",
+	"release",
+	"version",
+	"bump"
+]);
+const BREAK_HEADING = /^### Breaking\b/m;
+const BREAK_SENTENCE = /\bhas breaking changes\b/;
+/**
+* This function tells if the text of a version section marks a break. The marks are the heading
+* `### Breaking` and the words "has breaking changes", for a text that goes through Changesets.
+*
+* @remarks A page that counts breaks and {@link changelogFaults} use this one test, so they agree.
+*/
+function sectionMarksBreak(section) {
+	return BREAK_HEADING.test(section) || BREAK_SENTENCE.test(section);
+}
+/** This function tells if a statement has only the kind of the version and words that state no change. */
+function namesOnlyKind(statement) {
+	const words = statement.toLowerCase().match(/[\p{L}\p{N}`]+/gu) ?? [];
+	return words.some((word) => KIND_WORDS.has(word)) && words.every((word) => KIND_WORDS.has(word) || FILL_WORDS.has(word));
+}
+/** This function gives the three numbers of a version without its pre-release text, or null for another text. */
+function versionCore(version) {
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:-|$)/.exec(version);
+	return match ? [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	] : null;
+}
+/** This function compares two versions without their pre-release texts. */
+function compareCores(a, b) {
+	return (a[0] ?? 0) - (b[0] ?? 0) || (a[1] ?? 0) - (b[1] ?? 0) || (a[2] ?? 0) - (b[2] ?? 0);
+}
+/**
+* This function tells if the version rule makes a release a break. Before 1.0.0, a break raises
+* MINOR. From 1.0.0, a break raises MAJOR.
+*/
+function ruleGivesBreak([major, minor, patch]) {
+	if (patch !== 0) return false;
+	return major === 0 ? minor > 0 : minor === 0;
+}
+/** This function gives the version and the body of each version section. Another heading of level 1 or 2 ends a section. */
+function versionSections(markdown) {
+	const sections = [];
+	let section = null;
+	for (const line of markdown.split(/\r?\n/)) {
+		const heading = VERSION_HEADING.exec(line);
+		if (heading?.[1] !== void 0) {
+			section = {
+				version: heading[1],
+				heading: line,
+				body: []
+			};
+			sections.push(section);
+		} else if (/^#{1,2}\s/.test(line)) section = null;
+		else section?.body.push(line);
+	}
+	return sections;
+}
+/**
+* This function gives the first statement of a section: the first sentence of its first paragraph,
+* else the first change of its lists. A dependency line is not a change.
+*/
+function firstStatement(section) {
+	const first = section.body.join("\n").split(/\n[ \t]*\n/).map((block) => block.trim()).find((block) => block !== "" && !block.startsWith("#"));
+	if (first !== void 0 && !/^[-*+]\s/.test(first)) return firstSentence(first);
+	const [parsed] = parseChangelog([section.heading, ...section.body].join("\n"));
+	return parsed?.entries[0]?.text ?? "";
+}
+/** This function tells if a section of a fixed group has no change of its own above the level of PATCH. */
+function raisedByGroup(text) {
+	if (/^### (?:Minor|Major) Changes\b/m.test(text)) return false;
+	return text.trim() === "" || /^### Patch Changes\b/m.test(text) || /^No changes in this release\.$/m.test(text);
+}
+/** This function tells if a section has a line that names a new version of a dependency. */
+function hasDependencyLine(section) {
+	return section.body.some((line) => {
+		const item = /^[-*+]\s+(.*)$/.exec(line)?.[1];
+		return item !== void 0 && DEPENDENCY_ENTRY.test((COMMIT_ENTRY.exec(item)?.[2] ?? item).trim());
+	});
+}
+/**
+* This function gives the faults of the version sections of a changelog, in the order of the file.
+* A section can have two faults: one for its statement and one for its break mark.
+*
+* @remarks The break rule does not read a pre-release or the oldest section of the file, because
+* the oldest section has no earlier release to break. A dependency line does not say why the API
+* broke. Thus a section with only dependency lines has a fault on a break of the version rule. The
+* option `fixedGroup` removes this fault.
+*/
+function changelogFaults(markdown, options = {}) {
+	const from = options.from === void 0 ? null : versionCore(options.from);
+	if (options.from !== void 0 && from === null) throw new RangeError(`"${options.from}" is not a version.`);
+	const sections = versionSections(markdown);
+	const oldest = sections.map((section) => versionCore(section.version)).filter((core) => core !== null).reduce((low, core) => low === null || compareCores(core, low) < 0 ? core : low, null);
+	const faults = [];
+	for (const section of sections) {
+		const core = versionCore(section.version);
+		if (core === null || from !== null && compareCores(core, from) < 0) continue;
+		const statement = firstStatement(section);
+		const fault = (kind) => {
+			faults.push({
+				version: section.version,
+				kind,
+				statement
+			});
+		};
+		if (statement === "" && options.fixedGroup === true) continue;
+		const ruled = !section.version.includes("-") && oldest !== null && compareCores(core, oldest) !== 0;
+		if (statement === "" && (!hasDependencyLine(section) || ruled && ruleGivesBreak(core))) fault("no-statement");
+		else if (statement !== "" && namesOnlyKind(statement)) fault("version-kind-only");
+		if (!ruled) continue;
+		const text = section.body.join("\n");
+		const marked = sectionMarksBreak(text);
+		if (!ruleGivesBreak(core)) {
+			if (marked) fault("mark-without-break");
+		} else if (!marked && !(options.fixedGroup === true && raisedByGroup(text))) fault("break-unmarked");
+	}
+	return faults;
+}
 /**
 * This function gives the changes of the text of a GitHub release: one change for each top-level
 * list item. Fenced code is not read.
@@ -1997,6 +2129,7 @@ function openWork(data) {
 /**
 * This function renders the measures of `kpi.json`: their values, the date of the data and the engines that made it.
 * A measure with its own date shows that date in a column, so that the line above the table stays true.
+* A measure that names what it does not count shows that text under the table.
 */
 function measures(data) {
 	const { kpi } = data;
@@ -2004,9 +2137,10 @@ function measures(data) {
 	const ownDates = kpi.measures.some((measure) => measure.at !== void 0);
 	const dateCell = (at) => ownDates ? `<td><time datetime="${escapeHtml(at)}">${escapeHtml(longDate(at))}</time></td>` : "";
 	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>${dateCell(measure.at ?? kpi.at)}</tr>`).join("");
+	const limits = kpi.measures.filter((measure) => measure.notCounted !== void 0).map((measure) => `<p><code>${escapeHtml(measure.id)}</code> does not count: ${escapeHtml(measure.notCounted ?? "")}</p>`).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>${ownDates ? "The data date of the file is" : "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>${ownDates ? "<th scope=\"col\">Data date</th>" : ""}</tr></thead><tbody>${rows}</tbody></table></div></section>`;
+	return `<section class="sp-section" aria-labelledby="measures"><h2 id="measures">Measures</h2><p>${ownDates ? "The data date of the file is" : "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>${ownDates ? "<th scope=\"col\">Data date</th>" : ""}</tr></thead><tbody>${rows}</tbody></table></div>` + limits + "</section>";
 }
 function when(date) {
 	const text = escapeHtml(longDate(date));
@@ -2371,6 +2505,6 @@ async function runCli(argv, io) {
 		throw error;
 	}
 }
-export { firstSentence as $, STATUS_CLASSES as A, DEFAULT_CHANGELOGS as B, pageShell as C, utcDay as D, shortDate as E, plainText as F, releaseReading as G, mergeReleases as H, readStatusBoard as I, GITHUB_GRAPHQL as J, globFiles as K, roadmapItems as L, linksOf as M, markdownTables as N, OPEN_CLASSES as O, parseRoadmap as P, changelogVersions as Q, splitRow as R, BASE_CSS as S, longDate as T, readChangelogs as U, ReleaseDataError as V, readReleases as W, githubOpenWork as X, checkStateOf as Y, githubReleases as Z, renderReleasesPage as _, runCli as a, releaseSummary as b, STATUS_SCRIPT as c, renderStatusPage as d, headingAnchor as et, sectionsOf as f, releasesLead as g, RELEASES_SCRIPT as h, parseBuildArgs as i, buildStatusBoard as j, RoadmapParseError as k, classCounts as l, statusLead as m, UsageError as n, releaseBodyEntries as nt, TYPESCRIPT_PROBE as o, slugOf as p, GITHUB_API as q, build as r, probeScript as s, HELP as t, parseChangelog as tt, openGroups as u, laneCenter as v, dayRange as w, timelineLayout as x, oldestFirst as y, statusClassOf as z };
+export { changelogVersions as $, STATUS_CLASSES as A, DEFAULT_CHANGELOGS as B, pageShell as C, utcDay as D, shortDate as E, plainText as F, releaseReading as G, mergeReleases as H, readStatusBoard as I, GITHUB_GRAPHQL as J, globFiles as K, roadmapItems as L, linksOf as M, markdownTables as N, OPEN_CLASSES as O, parseRoadmap as P, changelogFaults as Q, splitRow as R, BASE_CSS as S, longDate as T, readChangelogs as U, ReleaseDataError as V, readReleases as W, githubOpenWork as X, checkStateOf as Y, githubReleases as Z, renderReleasesPage as _, runCli as a, releaseSummary as b, STATUS_SCRIPT as c, renderStatusPage as d, firstSentence as et, sectionsOf as f, releasesLead as g, RELEASES_SCRIPT as h, parseBuildArgs as i, sectionMarksBreak as it, buildStatusBoard as j, RoadmapParseError as k, classCounts as l, statusLead as m, UsageError as n, parseChangelog as nt, TYPESCRIPT_PROBE as o, slugOf as p, GITHUB_API as q, build as r, releaseBodyEntries as rt, probeScript as s, HELP as t, headingAnchor as tt, openGroups as u, laneCenter as v, dayRange as w, timelineLayout as x, oldestFirst as y, statusClassOf as z };
 
 //# sourceMappingURL=build.js.map