@mark1russell7/site-pages 0.2.8 → 0.2.10

package/build/chunks/data-stamp.js

@@ -0,0 +1,23 @@
+import { f as link, p as listText, u as escapeHtml } from "./freshness.js";
+// src/render/data-stamp.ts
+/** This function gives an engine and its version in the short form, without the npm scope. */
+function engineText(name, version) {
+	return `${name.slice(name.indexOf("/") + 1)} ${version}`;
+}
+/** This function gives the html of one run: a link to the run, the day of its start and each engine. */
+function runHtml(run) {
+	const engines = Object.entries(run.engines).map(([name, version]) => escapeHtml(engineText(name, version)));
+	return `run ${link(run.url, escapeHtml(run.id))} of ${escapeHtml(run.date.slice(0, 10))}, on ${listText(engines)}`;
+}
+/** This function gives the html of the sentence of a fixed study, with each version of its runs once. */
+function studyHtml(stamp) {
+	const engines = [...new Set(stamp.runs.flatMap((run) => Object.entries(run.engines).map(([name, version]) => engineText(name, version))))].map(escapeHtml);
+	return `<span>This page is a fixed study of ${listText(engines)}. It tells nothing about a newer release.</span> `;
+}
+/** This function gives the html line of the stamp of a page. A page shows this line with its data. */
+function renderDataStamp(stamp) {
+	return `<p class="data-stamp">${stamp.study === true ? studyHtml(stamp) : ""}${`<span>The data comes from ${listText(stamp.runs.map(runHtml))}.</span>`}${stamp.inFlight === void 0 ? "" : ` <span>A newer run is in flight: ${runHtml(stamp.inFlight)}.</span>`}${stamp.limit === void 0 ? "" : ` <span>The age limit of this data is ${stamp.limit.days} days. ${escapeHtml(stamp.limit.reason)}</span>`}</p>`;
+}
+export { renderDataStamp as t };
+
+//# sourceMappingURL=data-stamp.js.map

package/build/chunks/data-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-stamp.js","names":[],"sources":["../../src/render/data-stamp.ts"],"sourcesContent":["/**\n * The line that a measured page shows for its data: the run, its date and its engine versions, and a run in flight.\n * The line also tells when the page is a fixed study, and it shows the reason for a longer age limit.\n */\n\nimport type { DataRun, PageStamp } from \"../check/freshness.ts\";\nimport { escapeHtml, link, listText } from \"./html.ts\";\n\n/** This function gives an engine and its version in the short form, without the npm scope. */\nfunction engineText(name: string, version: string): string {\n  return `${name.slice(name.indexOf(\"/\") + 1)} ${version}`;\n}\n\n/** This function gives the html of one run: a link to the run, the day of its start and each engine. */\nfunction runHtml(run: DataRun): string {\n  const engines = Object.entries(run.engines).map(([name, version]) => escapeHtml(engineText(name, version)));\n  return `run ${link(run.url, escapeHtml(run.id))} of ${escapeHtml(run.date.slice(0, 10))}, on ${listText(engines)}`;\n}\n\n/** This function gives the html of the sentence of a fixed study, with each version of its runs once. */\nfunction studyHtml(stamp: PageStamp): string {\n  const engines = [...new Set(stamp.runs.flatMap((run) => Object.entries(run.engines).map(([name, version]) => engineText(name, version))))].map(escapeHtml);\n  return `<span>This page is a fixed study of ${listText(engines)}. It tells nothing about a newer release.</span> `;\n}\n\n/** This function gives the html line of the stamp of a page. A page shows this line with its data. */\nexport function renderDataStamp(stamp: PageStamp): string {\n  const study = stamp.study === true ? studyHtml(stamp) : \"\";\n  const data = `<span>The data comes from ${listText(stamp.runs.map(runHtml))}.</span>`;\n  const flight = stamp.inFlight === undefined ? \"\" : ` <span>A newer run is in flight: ${runHtml(stamp.inFlight)}.</span>`;\n  const limit = stamp.limit === undefined ? \"\" : ` <span>The age limit of this data is ${stamp.limit.days} days. ${escapeHtml(stamp.limit.reason)}</span>`;\n  return `<p class=\"data-stamp\">${study}${data}${flight}${limit}</p>`;\n}\n"],"mappings":";;;AASA,SAAS,WAAW,MAAc,SAAyB;CACzD,OAAO,GAAG,KAAK,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAC,EAAE,GAAG;AACjD;;AAGA,SAAS,QAAQ,KAAsB;CACrC,MAAM,UAAU,OAAO,QAAQ,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,aAAa,WAAW,WAAW,MAAM,OAAO,CAAC,CAAC;CAC1G,OAAO,OAAO,KAAK,IAAI,KAAK,WAAW,IAAI,EAAE,CAAC,EAAE,MAAM,WAAW,IAAI,KAAK,MAAM,GAAG,EAAE,CAAC,EAAE,OAAO,SAAS,OAAO;AACjH;;AAGA,SAAS,UAAU,OAA0B;CAC3C,MAAM,UAAU,CAAC,GAAG,IAAI,IAAI,MAAM,KAAK,SAAS,QAAQ,OAAO,QAAQ,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,aAAa,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU;CACzJ,OAAO,uCAAuC,SAAS,OAAO,EAAE;AAClE;;AAGA,SAAgB,gBAAgB,OAA0B;CAKxD,OAAO,yBAJO,MAAM,UAAU,OAAO,UAAU,KAAK,IAAI,KAIhB,6BAHE,SAAS,MAAM,KAAK,IAAI,OAAO,CAAC,EAAE,YAC7D,MAAM,aAAa,KAAA,IAAY,KAAK,oCAAoC,QAAQ,MAAM,QAAQ,EAAE,YACjG,MAAM,UAAU,KAAA,IAAY,KAAK,wCAAwC,MAAM,MAAM,KAAK,SAAS,WAAW,MAAM,MAAM,MAAM,EAAE,SAClF;AAChE"}

package/build/chunks/{kpi.d.ts → freshness.d.ts}

@@ -210,5 +210,97 @@ declare function readKpi(text: string, now?: number): KpiFile;
  * @throws KpiError when the data is not correct
  */
 declare function writeKpi(out: string, input: KpiInput, now?: number): string;
-export { OpenWorkTotals as C, StatusBoardData as D, ReleaseKind as E, StatusClass as O, NpmVersionTime as S, ReleaseChange as T, KpiEngine as _, kpiFile as a, Link as b, readKpi as c, BoardItem as d, BoardPullRequest as f, GitHubReleases as g, GitHubRelease as h, KpiInput as i, writeKpi as l, GitHubOpenWork as m, KPI_FORMAT as n, kpiProblems as o, CheckState as p, KpiError as r, kpiText as s, KPI_FILE as t, BoardIssue as u, KpiFile as v, Release as w, NpmPublishTimes as x, KpiMeasure as y };
-//# sourceMappingURL=kpi.d.ts.map
+/** The schema of a file of data stamps. */
+declare 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. */
+declare 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. */
+declare const MAX_MINORS_BEHIND = 1;
+/** The longest limit of a page, in days, with no ruling for that site. */
+declare const MAX_LIMIT_DAYS_WITHOUT_RULING = 14;
+/** One run that gives the data of a page. */
+interface DataRun {
+  readonly id: string;
+  readonly url: string;
+  /** The ISO time of the start of the run. */
+  readonly date: string;
+  /** The version of each engine of the run, by its npm name. */
+  readonly engines: Readonly<Record<string, string>>;
+}
+/** The age limit of one page, in place of `MAX_DATA_AGE_DAYS`. */
+interface DataLimit {
+  /** The largest age of the data, in days. */
+  readonly days: number;
+  /** The reason for the limit, as one sentence. The page shows it. */
+  readonly reason: string;
+  /** The path of the workflow from the root of the repository. Its schedule must meet the limit. */
+  readonly workflow: string;
+  /** The link to the public ruling. A limit over `MAX_LIMIT_DAYS_WITHOUT_RULING` needs it. */
+  readonly ruling?: string;
+}
+/** The stamp of one measured page. */
+interface PageStamp {
+  readonly page: string;
+  /** Each run that gives data to the page. */
+  readonly runs: readonly DataRun[];
+  /** The run on newer engines that is in progress. */
+  readonly inFlight?: DataRun;
+  /** The page shows a fixed study of the versions of its runs, so its data has no age limit. It makes no claim about a newer release. */
+  readonly study?: true;
+  /** The age limit of this page, in place of the default. */
+  readonly limit?: DataLimit;
+}
+/** The content of a file of data stamps. */
+interface DataStamps {
+  readonly schema: typeof DATA_STAMP_SCHEMA;
+  readonly pages: readonly PageStamp[];
+}
+/** The result of `parseDataStamps`. */
+type DataStampsParse = {
+  readonly ok: true;
+  readonly stamps: DataStamps;
+} | {
+  readonly ok: false;
+  readonly faults: readonly string[];
+};
+/** The options of `checkFreshness`. */
+interface FreshnessOptions {
+  /** The ISO time of the check. */
+  readonly now: string;
+  /** The publication times of the engines on npm. */
+  readonly times: readonly NpmVersionTime[];
+  /** The limit of the age. The default is `MAX_DATA_AGE_DAYS`. */
+  readonly maxAgeDays?: number;
+  /** The limit of the minor versions. The default is `MAX_MINORS_BEHIND`. */
+  readonly maxMinorsBehind?: number;
+  /** The schedule of each workflow of a limit. A number is the largest gap between its starts in days. A text tells why the gate cannot read it. */
+  readonly schedules?: Readonly<Record<string, number | string>>;
+}
+/** The result of `checkFreshness`. */
+interface FreshnessCheck {
+  /** Each break of a rule. One fault fails the gate. */
+  readonly faults: readonly string[];
+  /** Each rule that the gate could not run, with the reason. */
+  readonly notRun: readonly string[];
+}
+/**
+ * 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.
+ */
+declare function parseDataStamps(raw: unknown): DataStampsParse;
+/** This function gives the count of minor versions from `used` to `latest`. A newer major version counts as no limit. */
+declare function minorsBehind(used: string, latest: string): number;
+/** This function gives the newest stable version of a package on npm at a time, or undefined when npm has none. */
+declare function latestAt(times: readonly NpmVersionTime[], name: string, date: string): string | undefined;
+/**
+ * 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.
+ */
+declare function checkFreshness(stamps: DataStamps, options: FreshnessOptions): FreshnessCheck;
+export { GitHubRelease as A, ReleaseChange as B, readKpi as C, BoardPullRequest as D, BoardItem as E, Link as F, StatusBoardData as H, NpmPublishTimes as I, NpmVersionTime as L, KpiEngine as M, KpiFile as N, CheckState as O, KpiMeasure as P, OpenWorkTotals as R, kpiText as S, BoardIssue as T, StatusClass as U, ReleaseKind as V, KPI_FORMAT as _, DataStampsParse as a, kpiFile as b, MAX_DATA_AGE_DAYS as c, PageStamp as d, checkFreshness as f, KPI_FILE as g, parseDataStamps as h, DataStamps as i, GitHubReleases as j, GitHubOpenWork as k, MAX_LIMIT_DAYS_WITHOUT_RULING as l, minorsBehind as m, DataLimit as n, FreshnessCheck as o, latestAt as p, DataRun as r, FreshnessOptions as s, DATA_STAMP_SCHEMA as t, MAX_MINORS_BEHIND as u, KpiError as v, writeKpi as w, kpiProblems as x, KpiInput as y, Release as z };
+//# sourceMappingURL=freshness.d.ts.map

package/build/chunks/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","names":[],"sources":["../../src/data/types.ts","../../src/data/kpi.ts","../../src/check/freshness.ts"],"mappings":";;;;;UAMiB;EACf;EACA;;;;;;KAWU;;UAGK;;EAEf;;EAEA;;EAEA;;;UAIe;EACf;;EAEA;EACA,MAAM;;EAEN,SAAS;;EAET,OAAO;;;UAIQ;EACf;EACA;;EAEA;;EAEA;EACA;EACA;;;KAIU;EAAmB;EAAiB,UAAU;;EAAsB;EAAkB;;;UAGjF;EACf;EACA;EACA;;;UAIe;EACf,OAAO;EACP;;;KAQU;;UAGK;EACf;EACA;;EAEA;EACA,aAAa;EACb;EACA;;EAEA;;EAEA;;EAEA;EACA,OAAO;;;KAIG;;UAGK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;;UAIO;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;;;KAIU;EACN;EAAiB,cAAc;EAAoB,QAAQ;EAAc,QAAQ;;EACjF;EAAkB;;;UAGP;;EAEf;EACA;EACA;;EAEA;;;UAIe;;EAEf;EACA;;;UAIe;EACf;;EAEA;;EAEA;;EAEA;EACA,UAAU;;EAEV,UAAU;;;UAIK;;EAEf;;EAEA;;EAEA;IAAU;IAAwB;;EAClC,OAAO;EACP,cAAc;EACd,QAAQ;;EAER;IAAU;IAAoB;IAAiB,SAAS;;;EAExD,MAAM;;;cCvKK;;cAGA;;KAGD,WAAW,KAAK;;cAef,iBAAiB;WACnB;EAET,YAAY;;;;;;;;iBA4CE,YAAY,gBAAgB;;;;;;iBAgC5B,QAAQ,OAAO,UAAU,eAAe;;iBASxC,QAAQ,MAAM;;;;;;iBASd,QAAQ,cAAc,eAAe;;;;;;iBAkBrC,SAAS,aAAa,OAAO,UAAU;;cCnI1C;;cAGA;;cAGA;;cAGA;;UAKI;WACN;WACA;;WAEA;;WAEA,SAAS,SAAS;;;UAIZ;;WAEN;;WAEA;;WAEA;;WAEA;;;UAIM;WACN;;WAEA,eAAe;;WAEf,WAAW;;WAEX;;WAEA,QAAQ;;;UAIF;WACN,eAAe;WACf,gBAAgB;;;KAIf;WAA6B;WAAmB,QAAQ;;WAA0B;WAAoB;;;UAGjG;;WAEN;;WAEA,gBAAgB;;WAEhB;;WAEA;;WAEA,YAAY,SAAS;;;UAIf;;WAEN;;WAEA;;;;;;iBAsDK,gBAAgB,eAAe;;iBAwB/B,aAAa,cAAc;;iBAS3B,SAAS,gBAAgB,kBAAkB,cAAc;;;;;;;;;;iBAmGzD,eAAe,QAAQ,YAAY,SAAS,mBAAmB"}