@lernapps/tooling 0.3.0 → 0.4.0

package/archetypes/shared/playwright.ts

@@ -32,6 +32,11 @@ const base: PlaywrightTestConfig = {
   // another number of workers: the tooling's own tests set 1, because they run many apps' checks at the same time.
   fullyParallel: true,
   workers: Number(process.env["LERNAPPS_PLAYWRIGHT_WORKERS"]) || "75%",
+  // On CI (a small shared runner) a single interaction can now and then wait past the timeout under load
+  // (lernapps/app-templates#125): a failed test runs up to twice more there. One that passes on a retry counts as
+  // "flaky" in the output, not as passed, so it stays visible; a test that fails every time still fails the check.
+  // Locally no retry, so that a test that only sometimes passes shows up while the app is written.
+  retries: process.env["CI"] ? 2 : 0,
   reporter: [["line"]],
   // LERNAPPS_CHROMIUM: an installed Chromium that lernapps check starts where Playwright's own is missing
   // (check/visit.ts)

package/dist/cli.mjs

@@ -5,14 +5,219 @@ import { a as countFailedChecks, c as planFrontMatter, i as PLAN_NAME, l as plan
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir, hostname, tmpdir } from "node:os";
 import { basename, delimiter, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { parse, stringify } from "yaml";
+import { createHash } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createServer } from "node:http";
 import { chromium } from "playwright";
-import { createHash } from "node:crypto";
+/** Every package the lock file installs below node_modules, by its path: the version it asks for and whether it is optional. */
+function lockedPackages(dir) {
+	const file = join(dir, "package-lock.json");
+	if (!existsSync(file)) return void 0;
+	const lock = JSON.parse(readFileSync(file, "utf8"));
+	return new Map(Object.entries(lock.packages ?? {}).filter(([path, entry]) => path.startsWith("node_modules/") && entry.link !== true));
+}
+/** The version of the package installed at `path` (below `dir`), or undefined when none is installed there. */
+function installedVersion(dir, path) {
+	try {
+		const manifest = JSON.parse(readFileSync(join(dir, path, "package.json"), "utf8"));
+		return typeof manifest.version === "string" ? manifest.version : "";
+	} catch {
+		return;
+	}
+}
+/**
+* The installed version of every package the lock file names, as one line per package ("path version", "path -" when
+* none is installed), sorted: what node_modules holds, for the key of a cached result. Undefined without a lock file.
+*/
+function installedPackages(dir) {
+	const locked = lockedPackages(dir);
+	if (locked === void 0) return void 0;
+	return [...locked.keys()].sort().map((path) => `${path} ${installedVersion(dir, path) ?? "-"}`).join("\n");
+}
+/** How many mismatches a finding names before it says how many more there are. */
+const SHOWN = 5;
+/**
+* Whether node_modules holds what package-lock.json asks for: every package at its version. An optional package that
+* is not installed (one for another platform) is no mismatch. Empty without a lock file or when everything matches;
+* else one problem that names the first mismatches.
+*/
+function installedProblems(dir) {
+	const locked = lockedPackages(dir);
+	if (locked === void 0 || locked.size === 0) return [];
+	const mismatches = [];
+	for (const [path, entry] of [...locked].sort(([a], [b]) => a.localeCompare(b))) {
+		const installed = installedVersion(dir, path);
+		if (installed === void 0 && entry.optional === true) continue;
+		if (installed !== void 0 && (entry.version === void 0 || installed === entry.version)) continue;
+		const name = path.slice(path.lastIndexOf("node_modules/") + 13);
+		mismatches.push(installed === void 0 ? `${name} is not installed (the lock file asks for ${entry.version ?? "it"})` : `${name} ${installed} is installed, the lock file asks for ${entry.version}`);
+	}
+	if (mismatches.length === 0) return [];
+	const more = mismatches.length > SHOWN ? ` and ${mismatches.length - SHOWN} more` : "";
+	return [{
+		where: "node_modules",
+		found: `node_modules does not hold what package-lock.json asks for: ${mismatches.slice(0, SHOWN).join("; ")}${more}. CI installs with npm ci, so the check would test other packages than CI`,
+		fix: "Run npm ci, which installs exactly what package-lock.json asks for, then check again"
+	}];
+}
+/** A warning when this Node has another major version than CI, or undefined. */
+function nodeMajorProblem(version = process.versions.node) {
+	if (Number(version.split(".")[0]) === 26) return void 0;
+	return {
+		where: "node",
+		found: `Node ${version} runs this check, CI runs Node 26: what passes here may fail in CI`,
+		fix: `Use Node 26 (for example nvm install 26); the check does not fail for this`,
+		severity: "warning"
+	};
+}
+const git$2 = (cwd, ...args) => {
+	const result = spawnSync("git", args, {
+		cwd,
+		encoding: "utf8"
+	});
+	return result.status === 0 ? result.stdout : void 0;
+};
+/** The folder of the cache and the lock: <git common dir>/lernapps, or undefined outside a repository. */
+function stateDir(cwd = ".") {
+	const common = git$2(cwd, "rev-parse", "--git-common-dir")?.trim();
+	return common === void 0 || common === "" ? void 0 : join(resolve(cwd, common), "lernapps");
+}
+/**
+* The key of the state in `cwd` for a check of `parts`, or the reason it has none: not a repository, no commit, a
+* working tree with changes git sees (untracked files included), or a run in CI.
+*/
+function cacheKey(cwd, parts, toolingVersion, env = process.env) {
+	if (env["CI"] !== void 0 && env["CI"] !== "" && env["CI"] !== "false") return { none: "CI checks every time" };
+	const top = git$2(cwd, "rev-parse", "--show-toplevel")?.trim();
+	if (top === void 0) return { none: "not a git repository" };
+	const tree = git$2(cwd, "rev-parse", "--verify", "--quiet", "HEAD^{tree}")?.trim();
+	if (tree === void 0 || tree === "") return { none: "no commit yet" };
+	const status = git$2(top, "status", "--porcelain", "--untracked-files=all");
+	if (status === void 0) return { none: "git status failed" };
+	if (status.trim() !== "") return { none: "the working tree has changes that are not committed" };
+	const variables = Object.keys(env).filter((name) => name.startsWith("LERNAPPS_")).sort().map((name) => `${name}=${env[name]}`);
+	const hash = createHash("sha256");
+	for (const part of [
+		`tree ${tree}`,
+		`folder ${relative(top, resolve(cwd)).split("\\").join("/")}`,
+		`parts ${[...parts].sort().join(",")}`,
+		`tooling ${toolingVersion}`,
+		`node ${process.versions.node}`,
+		...variables,
+		`installed\n${installedPackages(cwd) ?? ""}`
+	]) {
+		hash.update(part);
+		hash.update("\0");
+	}
+	return { key: hash.digest("hex") };
+}
+const checkedFile = (dir, key) => join(dir, "checked", `${key}.yaml`);
+/** The report of a passing check of this state, and when it was made; undefined when there is none. */
+function cachedReport(dir, key) {
+	const file = checkedFile(dir, key);
+	try {
+		return {
+			report: readFileSync(file, "utf8"),
+			at: statSync(file).mtime
+		};
+	} catch {
+		return;
+	}
+}
+/** Keeps the report of a passing check of this state; the cache keeps the newest KEEP states. */
+function storeReport(dir, key, report) {
+	const folder = join(dir, "checked");
+	mkdirSync(folder, { recursive: true });
+	writeFileSync(checkedFile(dir, key), report);
+	const files = readdirSync(folder).filter((name) => name.endsWith(".yaml")).map((name) => ({
+		file: join(folder, name),
+		at: statSync(join(folder, name)).mtimeMs
+	})).sort((a, b) => b.at - a.at);
+	for (const { file } of files.slice(20)) rmSync(file, { force: true });
+}
+/** Whether a process with this id runs on this machine. */
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+function readOwner(lock) {
+	try {
+		return JSON.parse(readFileSync(join(lock, "owner.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/**
+* Takes the lock of checks in this clone (a folder, made atomically with mkdir), waiting while another check holds
+* it; `waiting` is called once, with its owner, when it has to wait. A lock whose process no longer runs on this
+* machine is taken over. Returns the function that releases it; the lock is also released when the process exits or
+* is interrupted.
+*/
+async function acquireLock(dir, waiting, poll = 1e3) {
+	mkdirSync(dir, { recursive: true });
+	const lock = join(dir, "check.lock");
+	let told = false;
+	for (;;) {
+		try {
+			mkdirSync(lock);
+			break;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		const owner = readOwner(lock);
+		if (owner !== void 0 && owner.host === hostname() && !alive(owner.pid)) {
+			rmSync(lock, {
+				recursive: true,
+				force: true
+			});
+			continue;
+		}
+		const made = statSync(lock, { throwIfNoEntry: false })?.mtimeMs;
+		if (owner === void 0 && made !== void 0 && Date.now() - made > 10 * poll) {
+			rmSync(lock, {
+				recursive: true,
+				force: true
+			});
+			continue;
+		}
+		if (!told) {
+			waiting(owner);
+			told = true;
+		}
+		await sleep(poll);
+	}
+	writeFileSync(join(lock, "owner.json"), JSON.stringify({
+		pid: process.pid,
+		host: hostname(),
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	}));
+	const release = () => {
+		process.off("exit", release);
+		process.off("SIGINT", interrupted);
+		process.off("SIGTERM", interrupted);
+		if (readOwner(lock)?.pid === process.pid) rmSync(lock, {
+			recursive: true,
+			force: true
+		});
+	};
+	const interrupted = (signal) => {
+		release();
+		process.exit(signal === "SIGINT" ? 130 : 143);
+	};
+	process.on("exit", release);
+	process.on("SIGINT", interrupted);
+	process.on("SIGTERM", interrupted);
+	return release;
+}
 // check/run.ts
 const RULE_PAGE = "https://lernapps.net/tooling/rules/#";
 const finding = (rule, severity, problem) => ({
@@ -644,6 +849,10 @@ const CHECK_OPTIONS = {
 		type: "boolean",
 		default: false
 	},
+	"no-cache": {
+		type: "boolean",
+		default: false
+	},
 	entry: { type: "string" },
 	report: { type: "string" },
 	help: {
@@ -652,7 +861,7 @@ const CHECK_OPTIONS = {
 		default: false
 	}
 };
-const CHECK_USAGE = `Usage: lernapps check [--pre-commit] [--pre-push] [<dir|url>] [--entry <file>] [--report <file>]
+const CHECK_USAGE = `Usage: lernapps check [--pre-commit] [--pre-push] [--no-cache] [<dir|url>] [--entry <file>] [--report <file>]
 
 Runs every check that has something to check. Passing, it prints one line; otherwise the validation report in
 YAML (schema: https://lernapps.net/tooling/schemas/validation-report.v1.schema.json). Every finding names its
@@ -681,8 +890,20 @@ In a repo (no <dir|url>):
   checks the site in a repo with one (npm run build, then npm run check:site in the tooling, npm run check in a
   site). Then it prints one line and writes no report. Anything else, or changed files it cannot know, runs the
   part. CI decides the same in the app check action (lernapps changes --help).
+  Every run in a repo first compares node_modules with package-lock.json: a package installed at another
+  version, or missing, fails the run before anything else (run npm ci), since CI installs with npm ci.
+  The heavy part (--pre-push, or both) then:
+    - reuses a passing result of the same state: the tree of HEAD, the folder, the parts, the versions of
+      the tooling and of Node, the packages installed and every LERNAPPS_* variable, with a working tree
+      that has no changes git sees (untracked files included). It prints that line with "already checked".
+      Kept in <git common dir>/lernapps/, which the worktrees of a clone share; never in CI (CI set)
+    - waits for another check of the heavy part in this clone (and its worktrees), saying so in one line
+      on standard error; a lock whose process no longer runs is taken over
+    - warns in one line on standard error when Node has another major version than CI (no finding:
+      the report is the same for the same state wherever it is checked)
   Every run in a repo also writes the full report to node_modules/.cache/lernapps/validation-report.yaml,
-  passing or not; the app check action keeps it. A failed run counts each rule with an error in failedChecks
+  passing or not; the app check action keeps it. A run that checked writes how long each step took to
+  node_modules/.cache/lernapps/timings.json; the passing line ends with the whole time. A failed run counts each rule with an error in failedChecks
   of the current plan's front matter, when it has the key.
 
 On a built app, without its repo:
@@ -712,6 +933,7 @@ Options:
                    #<section> (or #<section>/<sub>) is an element id of its page as the server sends it, the
                    fitness values match; without <dir|url> the app at the entry's url is checked
   --report <file>  also write the full report to <file>, passing or not
+  --no-cache       check again even when this state passed before (in a repo)
   -h, --help       print this help
 
 `;
@@ -2514,6 +2736,34 @@ const REPORT = "node_modules/.cache/lernapps/validation-report.yaml";
 const CHECKS_PASS = "checks-pass";
 /** A built app or a URL that could not be checked at all: a platform rule, unlike the toolchain's checks-pass. */
 const APP_CHECKABLE = "app-checkable";
+/** The duration of every step of the last check in a repo that ran: not in the report, which is deterministic. */
+const TIMINGS = "node_modules/.cache/lernapps/timings.json";
+/** The steps of this run and how long each took, in seconds, for TIMINGS. */
+const timings = [];
+/** Runs `run` and records how long it took as the step `name`. */
+function timed(name, run) {
+	const start = performance.now();
+	try {
+		return run();
+	} finally {
+		timings.push({
+			step: name,
+			seconds: Math.round(performance.now() - start) / 1e3
+		});
+	}
+}
+/** Like timed, for a step that returns a promise. */
+async function timedAsync(name, run) {
+	const start = performance.now();
+	try {
+		return await run();
+	} finally {
+		timings.push({
+			step: name,
+			seconds: Math.round(performance.now() - start) / 1e3
+		});
+	}
+}
 /** The Playwright tests' results, as its JSON reporter writes them, to tell the runtime's tests from the app's. */
 const E2E_RESULTS = "node_modules/.cache/lernapps/playwright-results.json";
 const RUNTIME_ISSUES = "https://github.com/lernapps/app-templates/issues";
@@ -2852,6 +3102,9 @@ function architectureDiffFindings(where, stdout, stderr) {
 }
 /** Runs a step and returns its findings: a diff's as architectureDiffFindings judges them, else runStep's one. */
 function stepFindings(step) {
+	return timed(step.name, () => untimedStepFindings(step));
+}
+function untimedStepFindings(step) {
 	if (!step.architectureDiff) {
 		const failure = runStep(step);
 		return failure ? [failure] : [];
@@ -2937,12 +3190,12 @@ async function checkProject(fast, heavy, context) {
 	if (heavy && built) {
 		context.project = process.cwd();
 		if (existsSync(join("dist", "index.html"))) try {
-			context.app = await visit({ bundle: "dist" });
+			context.app = await timedAsync("visit of the built app", () => visit({ bundle: "dist" }));
 		} catch (error) {
 			if (!(error instanceof BrowserError)) throw error;
 			findings.push(browserFinding(error));
 		}
-		const checks = await runChecks(context);
+		const checks = await timedAsync("checks of the built app", () => runChecks(context));
 		rules.push(...checks.rules);
 		findings.push(...checks.findings);
 		if ([
@@ -2951,7 +3204,8 @@ async function checkProject(fast, heavy, context) {
 			"mjs",
 			"cjs"
 		].map((ext) => `playwright.config.${ext}`).find((file) => existsSync(file)) !== void 0) try {
-			const failure = runEndToEndTests(await browserForTests());
+			const browser = await browserForTests();
+			const failure = timed("end-to-end tests", () => runEndToEndTests(browser));
 			if (failure) findings.push(failure);
 		} catch (error) {
 			if (!(error instanceof BrowserError)) throw error;
@@ -3014,6 +3268,62 @@ function checkSite(script) {
 		suppressions: []
 	};
 }
+/**
+* The check of a repo: first whether node_modules holds what package-lock.json asks for (else nothing else runs, its
+* result would not be CI's). The heavy part warns on standard error when Node has another major version than CI,
+* then reuses a passing report of the same state (check/cache.ts) or waits for another check in this clone.
+*/
+async function checkRepo(fast, heavy, context, noCache) {
+	const parts = [...fast ? ["pre-commit"] : [], ...heavy ? ["pre-push"] : []];
+	const installed = timed("installed packages", () => installedProblems("."));
+	if (installed.length > 0) return { report: {
+		checked: commitOrDirectory(),
+		parts,
+		rules: [CHECKS_PASS],
+		findings: installed.map((problem) => finding(CHECKS_PASS, "error", problem)),
+		suppressions: []
+	} };
+	if (!heavy) return { report: await checkProject(fast, heavy, context) };
+	const node = nodeMajorProblem();
+	if (node !== void 0) process.stderr.write(`lernapps check: warning: ${node.found}. ${node.fix}\n`);
+	const dir = stateDir();
+	const keyOf = () => {
+		if (noCache || dir === void 0) return void 0;
+		const key = cacheKey(".", parts, version());
+		return "key" in key ? key.key : void 0;
+	};
+	const cached = (key) => {
+		if (key === void 0 || dir === void 0) return void 0;
+		const hit = cachedReport(dir, key);
+		if (hit === void 0) return void 0;
+		return {
+			report: {
+				...parse(hit.report),
+				checked: commitOrDirectory()
+			},
+			cachedAt: hit.at
+		};
+	};
+	const before = keyOf();
+	const hit = cached(before);
+	if (hit !== void 0) return hit;
+	let waited = false;
+	const release = dir === void 0 ? () => {} : await acquireLock(dir, (owner) => {
+		waited = true;
+		process.stderr.write(`lernapps check: waiting for another lernapps check in this clone${owner === void 0 ? "" : ` (process ${owner.pid}, since ${owner.at})`}\n`);
+	});
+	try {
+		if (waited) {
+			const after = cached(keyOf());
+			if (after !== void 0) return after;
+		}
+		const report = await checkProject(fast, heavy, context);
+		if (!failed(report) && before !== void 0 && dir !== void 0 && keyOf() === before) storeReport(dir, before, toYaml(report));
+		return { report };
+	} finally {
+		release();
+	}
+}
 /** The checks of a built app alone: a bundle directory or a URL. */
 async function checkApp(target, context) {
 	const isUrl = /^https?:\/\//.test(target);
@@ -3054,6 +3364,9 @@ async function check(args) {
 	if (values.entry !== void 0) context.entry = readEntry(values.entry);
 	const target = positionals[0] ?? context.entry?.value.url;
 	let report;
+	/** When the report comes from the cache: when that state was checked. */
+	let cachedAt;
+	const start = performance.now();
 	if (target !== void 0) {
 		if (values["pre-commit"] || values["pre-push"]) throw new UsageError("--pre-commit and --pre-push check a repo; a built app is checked without them");
 		report = await checkApp(target, context);
@@ -3073,21 +3386,32 @@ async function check(args) {
 			process.stdout.write(`${scope.skip}\n`);
 			return 0;
 		} else {
-			report = scope !== void 0 ? checkSite(scope.site) : await checkProject(all || values["pre-commit"], all || values["pre-push"], context);
+			if (scope !== void 0) report = checkSite(scope.site);
+			else {
+				const result = await checkRepo(all || values["pre-commit"], all || values["pre-push"], context, values["no-cache"]);
+				report = result.report;
+				cachedAt = result.cachedAt;
+			}
 			if (values["pre-push"] && failed(report)) countPrePushFailure();
 		}
 	}
 	if (target === void 0 && failed(report)) countFailedChecks(report.findings.filter((found) => found.severity === "error").map((found) => found.rule));
 	const yaml = toYaml(report);
+	const seconds = Math.round((performance.now() - start) / 100) / 10;
 	if (target === void 0) {
 		mkdirSync(dirname(REPORT), { recursive: true });
 		writeFileSync(REPORT, yaml);
+		if (cachedAt === void 0 && timings.length > 0) writeFileSync(TIMINGS, `${JSON.stringify({
+			seconds,
+			steps: timings
+		}, null, 2)}\n`);
 	}
 	if (values.report !== void 0) writeFileSync(values.report, yaml);
 	if (report.findings.length > 0) process.stdout.write(yaml);
 	else {
 		const what = "commit" in report.checked ? `commit ${report.checked.commit.slice(0, 7)}` : "bundle" in report.checked ? relative(process.cwd(), resolve(report.checked.bundle)) || "." : "url" in report.checked ? report.checked.url : report.checked.directory;
-		process.stdout.write(`lernapps check: ok, ${report.rules.length} rule${report.rules.length === 1 ? "" : "s"}, no findings (${what})\n`);
+		const how = cachedAt !== void 0 ? `, already checked at ${cachedAt.toTimeString().slice(0, 5)} (--no-cache checks again)` : ` in ${seconds} s`;
+		process.stdout.write(`lernapps check: ok, ${report.rules.length} rule${report.rules.length === 1 ? "" : "s"}, no findings (${what})${how}\n`);
 	}
 	return failed(report) ? 1 : 0;
 }

package/dist/playwright.mjs

@@ -18,6 +18,7 @@ const base = {
 	forbidOnly: true,
 	fullyParallel: true,
 	workers: Number(process.env["LERNAPPS_PLAYWRIGHT_WORKERS"]) || "75%",
+	retries: process.env["CI"] ? 2 : 0,
 	reporter: [["line"]],
 	use: {
 		baseURL: URL,

package/generator/app/.github/workflows/pages.yml

@@ -15,7 +15,9 @@ name: Pages
 # paths filter: a check skipped by a paths filter stays "Pending" and blocks a pull request that requires it. GitHub
 # may start no run for a push that creates main from commits it already has (the first publish): then start it by
 # hand, Actions → Pages → Run workflow on main (gh workflow run Pages --ref main), as the plan says; a run started by
-# hand checks and publishes everything.
+# hand checks and publishes everything. A push to main whose commit has the same tree as the pull request that the job
+# `app` checked already (the pull request was up to date with main when it was merged) takes that run's bundle and
+# report instead of checking again.
 on:
   push:
     branches: [main]
@@ -34,6 +36,9 @@ jobs:
   app:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read # on main: find the run of the pull request that checked the same tree, and take its result
     steps:
       - uses: lernapps/tooling/actions/app-check@{{tooling}}
   deploy:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared tooling of the lernapps.net apps and sites: the CLI lernapps, site actions, Renovate preset, guidance for building apps; documentation at https://lernapps.net/tooling/",
   "license": "MIT",
   "repository": {
@@ -115,7 +115,7 @@
   },
   "devDependencies": {
     "@doctc/arc42": "0.38.0",
-    "@lernapps/site": "github:lernapps/lernapps.github.io#8b6c98f76170c313519d04b38937a48747c05b09",
+    "@lernapps/site": "github:lernapps/lernapps.github.io#0f6257d3dffcbf69ffe962d0b80bd7298a62de02",
     "@types/node": "26.6.5",
     "ajv": "8.20.0",
     "vite-plus": "1.4.0"