@moku-labs/ci 1.5.3 → 1.5.5

package/README.md

@@ -119,7 +119,7 @@ flowchart LR
 | [`examples/package/publish.local-publish.yml`](examples/package/publish.local-publish.yml) | Fallback: publish from the project's own job. Use it only if the central publish fails npm auth. |
 | [`rulesets/main.json`](rulesets/main.json) | Branch ruleset for `main`: PR only, no force-push, the four `ci / …` checks required. |
 | [`examples/dependabot.yml`](examples/dependabot.yml) | Dependabot config: one grouped PR a day for `@moku-labs/*` only. `setup` writes it to `.github/dependabot.yml`. |
-| [`examples/org/fleet.yml`](examples/org/fleet.yml) | For the organization's `.github` repository. Every 15 minutes it runs `moku-release fleet --markdown` and puts the table between `<!-- fleet:start -->` and `<!-- fleet:end -->` of `profile/README.md`. |
+| [`examples/org/fleet.yml`](examples/org/fleet.yml) | For the organization's `.github` repository. Every 15 minutes it runs `moku-release fleet --markdown --deps` and puts the table between `<!-- fleet:start -->` and `<!-- fleet:end -->` of `profile/README.md`. |
 | [`examples/package/dependabot-automerge.yml`](examples/package/dependabot-automerge.yml) | Turns on auto-merge for a Dependabot PR; the ruleset checks stay the gate. After the merge it dispatches `publish.yml` with `patch`, because a merge made by `GITHUB_TOKEN` starts no push run. `setup` writes it and allows auto-merge on the repo. |
 
 > [!TIP]
@@ -209,7 +209,7 @@ Examples: `examples/package/ci-with-demos.yml` (label `demos:full`) and
 | `bun run release:setup` | once per project | Idempotent wizard: workflows, Dependabot, script contract, first publish, first tag, trusted publisher, branch ruleset, auto-merge, then `doctor`. `--dry-run` prints every action, changes nothing and asks nothing. `--yes` answers every confirmation for an agent or CI; a step that needs your npm OTP is then printed, not run. |
 | `bun run release:doctor` | any time | Changes nothing in the project; it only runs `git fetch --tags` first. Twelve checks, one line each, and the exact `fix:` command for every red line. `--json` for machines. |
 | `bun run release wait` | after each merge to `main` | Refuses unless `origin/main` holds `HEAD`. Waits for the first release tag that holds the commit, then for npm to serve that version. Stops on a failed run and prints the log command. |
-| `bun run release fleet` | any time | Read-only. One table for every repository of the organization: CI on `main`, the release of `main`, tag against npm, commits nobody released, open PRs, old `@moku-labs/*` pins. Then the list of what waits for a person. `--markdown` prints the public rows for the organization page, `--json` every row. |
+| `bun run release fleet` | any time | Read-only. One table for every repository of the organization: CI on `main`, the release of `main`, tag against npm, commits nobody released, open PRs, old `@moku-labs/*` pins. Then the list of what waits for a person. `--markdown` prints the public rows for the organization page, `--json` every row. `--deps` adds two tables: the shared toolchain with the version most repositories are on, and the runtime dependencies that are behind npm. Only the dependencies a manifest names are read. |
 | `bun run release <patch\|minor\|major\|prerelease>` | a release a person asks for | Refuses unless the tree is clean and `HEAD == origin/main`. Dispatches `publish.yml`, watches the run, verifies the version and dist-tag on npm. |
 
 The scripts are plain aliases of the `moku-release` bin. Internals and the list of checks:

package/dist/release.mjs

@@ -2055,7 +2055,7 @@ const PROFILE_REPO = ".github";
 /** Matches a release tag, prereleases included: `v1.2.3`, `v1.2.3-rc.0`. Not the moving `v1`. */
 const RELEASE_TAG = /^v\d+\.\d+\.\d+/;
 /** Matches a dependency pinned to one exact version. A range is not a pin and is not judged. */
-const EXACT_VERSION = /^\d+\.\d+\.\d+/;
+const EXACT_VERSION$1 = /^\d+\.\d+\.\d+/;
 /** The query `gh api graphql -F org=<org>` runs. One call answers the whole table. */
 const FLEET_QUERY = `query($org: String!) {
   organization(login: $org) {
@@ -2064,6 +2064,7 @@ const FLEET_QUERY = `query($org: String!) {
         name
         isPrivate
         manifest: object(expression: "HEAD:package.json") { ... on Blob { text } }
+        bun: object(expression: "HEAD:.bun-version") { ... on Blob { text } }
         publish: object(expression: "HEAD:.github/workflows/publish.yml") { ... on Blob { byteSize } }
         defaultBranchRef {
           target {
@@ -2173,7 +2174,7 @@ function familyPins(manifest) {
 		...manifest.devDependencies,
 		...manifest.dependencies
 	};
-	return Object.fromEntries(Object.entries(all).filter(([name, spec]) => name.startsWith(FAMILY_SCOPE) && EXACT_VERSION.test(spec)));
+	return Object.fromEntries(Object.entries(all).filter(([name, spec]) => name.startsWith(FAMILY_SCOPE) && EXACT_VERSION$1.test(spec)));
 }
 /**
 * Whether a check belongs to `publish.yml`.
@@ -2200,6 +2201,17 @@ function repoUrl(org, repo, path = "") {
 	return `https://github.com/${org}/${repo.name}${path}`;
 }
 /**
+* The entries of a dependency map that are not family packages.
+*
+* @param dependencies - A dependency map of a manifest, when it has one.
+* @returns The same map without `@moku-labs/*`.
+* @example
+* outsideFamily({ "@moku-labs/core": "1.7.2", preact: "10.27.0" }); // { preact: "10.27.0" }
+*/
+function outsideFamily(dependencies) {
+	return Object.fromEntries(Object.entries(dependencies ?? {}).filter(([name]) => !name.startsWith(FAMILY_SCOPE)));
+}
+/**
 * Turn one repository of the answer into a row. The pins are judged later, once the
 * newest version of every package is known.
 *
@@ -2211,6 +2223,7 @@ function repoUrl(org, repo, path = "") {
 function toRepo(raw) {
 	const manifest = parseManifest(raw.manifest?.text ?? void 0);
 	const head = raw.defaultBranchRef?.target;
+	const bun = raw.bun?.text?.trim();
 	const checks = (head?.statusCheckRollup?.contexts?.nodes ?? []).filter((check) => check?.name !== void 0);
 	const publishes = raw.publish?.byteSize !== void 0 && manifest.private !== true && manifest.name !== void 0;
 	const newest = publishes ? newestRelease(raw) : void 0;
@@ -2232,7 +2245,14 @@ function toRepo(raw) {
 			state: rollupState(pr.commits?.nodes?.[0]?.commit?.statusCheckRollup?.state)
 		})),
 		pins: [],
-		pinned: familyPins(manifest)
+		pinned: familyPins(manifest),
+		external: {
+			runtime: outsideFamily(manifest.dependencies),
+			dev: {
+				...outsideFamily(manifest.devDependencies),
+				...bun === void 0 || bun === "" ? {} : { bun }
+			}
+		}
 	};
 }
 /**
@@ -2369,6 +2389,160 @@ function renderFleetMarkdown(org, repos) {
 	].join("\n");
 }
 //#endregion
+//#region src/lib/fleet-deps.ts
+/** A tool counts as shared once this many repositories use it. */
+const SHARED_FROM = 2;
+/** Matches a dependency pinned to one exact version. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+/;
+/** Matches a range that names a lowest version: `^1.2.3`, `~1.2.3`, `>=1.2.3`. */
+const RANGE_PREFIX = /^(?:\^|~|>=)\s*(?=\d+\.\d+\.\d+)/;
+/**
+* Whether a written version is older than the newest one. An exact version is compared in
+* full. A range is behind only when the newest major is above its own: inside the major it
+* already takes the newest. Anything else (`*`, a tag, a URL) is not judged.
+*
+* @param spec - The version as the manifest writes it.
+* @param latest - The newest version on npm.
+* @returns `true` when the dependency is behind.
+* @example
+* isBehind("^5.1.0", "6.0.0"); // true
+*/
+function isBehind(spec, latest) {
+	if (EXACT_VERSION.test(spec)) return compareSemver(spec, latest) < 0;
+	if (!RANGE_PREFIX.test(spec)) return false;
+	return (parseSemver(spec.replace(RANGE_PREFIX, "")).core[0] ?? 0) < (parseSemver(latest).core[0] ?? 0);
+}
+/**
+* Order two written versions, newest first. Two exact versions are compared as semver,
+* anything else as text, so the order is stable for a range too.
+*
+* @param left - One written version.
+* @param right - Another written version.
+* @returns Negative when `left` is the newer one.
+* @example
+* newestFirst("1.4.2", "1.3.14"); // negative
+*/
+function newestFirst(left, right) {
+	return EXACT_VERSION.test(left) && EXACT_VERSION.test(right) ? compareSemver(right, left) : right.localeCompare(left);
+}
+/**
+* The version most repositories are on. On a tie the newer version wins.
+*
+* @param versions - The version each repository writes, one entry per repository.
+* @returns The accepted version, or an empty string for an empty list.
+* @example
+* acceptedVersion(["6.0.3", "6.0.3", "7.0.2"]); // "6.0.3"
+*/
+function acceptedVersion(versions) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const version of versions) counts.set(version, (counts.get(version) ?? 0) + 1);
+	const [accepted = ""] = [...counts.keys()].toSorted((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0) || newestFirst(a, b));
+	return accepted;
+}
+/**
+* The toolchain table: every dev dependency that at least two repositories use, with the
+* version most of them are on. On a tie the newer version is the accepted one.
+*
+* @param repos - The rows of the fleet.
+* @returns One row per shared tool, the ones with a repository on another version first.
+* @example
+* const tools = toolchainRows(repos);
+*/
+function toolchainRows(repos) {
+	const uses = /* @__PURE__ */ new Map();
+	for (const repo of repos) for (const [name, version] of Object.entries(repo.external.dev)) uses.set(name, [...uses.get(name) ?? [], {
+		repo: repo.name,
+		version
+	}]);
+	return [...uses.entries()].filter(([, users]) => users.length >= SHARED_FROM).map(([name, users]) => {
+		const accepted = acceptedVersion(users.map((use) => use.version));
+		return {
+			name,
+			accepted,
+			users: users.length,
+			others: users.filter((use) => use.version !== accepted)
+		};
+	}).toSorted((a, b) => Number(b.others.length > 0) - Number(a.others.length > 0) || a.name.localeCompare(b.name));
+}
+/**
+* Every package name whose newest version the two tables need.
+*
+* @param repos - The rows of the fleet.
+* @returns The names of the shared tools and of every runtime dependency, each once.
+* @example
+* const names = externalNames(repos);
+*/
+function externalNames(repos) {
+	const runtime = repos.flatMap((repo) => Object.keys(repo.external.runtime));
+	return [.../* @__PURE__ */ new Set([...toolchainRows(repos).map((row) => row.name), ...runtime])].toSorted();
+}
+/**
+* The runtime table: every runtime dependency that is behind the newest version on npm.
+*
+* @param repos - The rows of the fleet.
+* @param latest - Package name to its newest version on npm.
+* @returns One row per dependency and repository, by package name.
+* @example
+* const behind = runtimeRows(repos, new Map([["preact", "10.27.0"]]));
+*/
+function runtimeRows(repos, latest) {
+	return repos.flatMap((repo) => Object.entries(repo.external.runtime).flatMap(([name, version]) => {
+		const newest = latest.get(name);
+		return newest !== void 0 && isBehind(version, newest) ? [{
+			name,
+			repo: repo.name,
+			version,
+			latest: newest
+		}] : [];
+	})).toSorted((a, b) => a.name.localeCompare(b.name) || a.repo.localeCompare(b.repo));
+}
+/**
+* The "not on it" cell of a toolchain row.
+*
+* @param row - The row.
+* @returns E.g. `game 2.4.2, core 7.0.2`, or a dash when every repository is on the accepted version.
+* @example
+* othersCell(row); // "game 2.4.2"
+*/
+function othersCell(row) {
+	if (row.others.length === 0) return "—";
+	return row.others.map((use) => `${use.repo} ${use.version}`).join(", ");
+}
+/**
+* Render both tables as two collapsed Markdown blocks, for the organization page.
+*
+* @param tools - The toolchain rows, with `latest` filled.
+* @param runtime - The runtime rows.
+* @returns The Markdown, without a trailing newline.
+* @example
+* renderDepsMarkdown(tools, runtime);
+*/
+function renderDepsMarkdown(tools, runtime) {
+	const split = tools.filter((row) => row.others.length > 0).length;
+	const old = tools.filter((row) => row.latest !== void 0 && isBehind(row.accepted, row.latest));
+	return [
+		"<details>",
+		`<summary>Toolchain: ${tools.length} shared tools, ${split} on more than one version, ${old.length} behind npm</summary>`,
+		"",
+		"| Tool | Accepted | npm | Used by | Not on it |",
+		"| --- | --- | --- | --- | --- |",
+		...tools.map((row) => `| ${row.name} | ${row.accepted} | ${row.latest ?? "—"} | ${row.users} | ${othersCell(row)} |`),
+		"",
+		"</details>",
+		"",
+		"<details>",
+		`<summary>Runtime dependencies: ${runtime.length} behind npm</summary>`,
+		"",
+		...runtime.length === 0 ? ["Every runtime dependency is on the newest version."] : [
+			"| Package | Repo | Version | npm |",
+			"| --- | --- | --- | --- |",
+			...runtime.map((row) => `| ${row.name} | ${row.repo} | ${row.version} | ${row.latest} |`)
+		],
+		"",
+		"</details>"
+	].join("\n");
+}
+//#endregion
 //#region src/commands/fleet.ts
 /**
 * The organization the command reads: the owner of this checkout's remote, or of the
@@ -2461,6 +2635,133 @@ function renderTerminal(ui, repos) {
 	if (waiting.length === 0) ui.check(true, "nothing waits");
 	for (const line of waiting) ui.check(false, line);
 }
+/** How many `npm view` calls run at once. The registry answers each in under a second. */
+const REGISTRY_BATCH = 8;
+/**
+* The newest version on npm of every named package, read a few at a time.
+*
+* @param ctx - The ports and flags.
+* @param names - The package names.
+* @returns Package name to its newest version; a package the registry did not answer for is left out.
+* @example
+* const latest = await newestVersions(ctx, ["typescript", "preact"]);
+*/
+async function newestVersions(ctx, names) {
+	const latest = /* @__PURE__ */ new Map();
+	for (let start = 0; start < names.length; start += REGISTRY_BATCH) {
+		const batch = names.slice(start, start + REGISTRY_BATCH);
+		const views = await Promise.all(batch.map((name) => ctx.exec.capture("npm", [
+			"view",
+			name,
+			"version"
+		])));
+		for (const [index, view] of views.entries()) {
+			const name = batch[index];
+			if (name !== void 0 && view.code === 0 && view.stdout.trim() !== "") latest.set(name, view.stdout.trim());
+		}
+	}
+	return latest;
+}
+/**
+* Build both dependency tables: the shared toolchain, and the runtime dependencies that
+* npm has moved past.
+*
+* @param ctx - The ports and flags.
+* @param repos - The rows the tables are built from.
+* @returns The toolchain rows with `latest` filled, and the runtime rows.
+* @example
+* const tables = await dependencyTables(ctx, repos);
+*/
+async function dependencyTables(ctx, repos) {
+	const latest = await newestVersions(ctx, externalNames(repos));
+	return {
+		toolchain: toolchainRows(repos).map((row) => {
+			const newest = latest.get(row.name);
+			return newest === void 0 ? row : {
+				...row,
+				latest: newest
+			};
+		}),
+		runtime: runtimeRows(repos, latest)
+	};
+}
+/**
+* Print both dependency tables, for a person at a terminal.
+*
+* @param ui - The branded console.
+* @param toolchain - The toolchain rows.
+* @param runtime - The runtime rows.
+* @example
+* renderDepsTerminal(ui, toolchain, runtime);
+*/
+function renderDepsTerminal(ui, toolchain, runtime) {
+	ui.heading("Toolchain");
+	ui.line([
+		"tool".padEnd(28),
+		"accepted".padEnd(14),
+		"npm".padEnd(14),
+		"not on it"
+	].join(" "));
+	for (const row of toolchain) ui.line([
+		row.name.padEnd(28),
+		row.accepted.padEnd(14),
+		(row.latest ?? "—").padEnd(14),
+		othersCell(row)
+	].join(" "));
+	ui.heading("Runtime dependencies behind npm");
+	if (runtime.length === 0) ui.check(true, "every runtime dependency is on the newest version");
+	for (const row of runtime) ui.line([
+		row.name.padEnd(28),
+		row.repo.padEnd(10),
+		row.version.padEnd(14),
+		row.latest
+	].join(" "));
+}
+/**
+* Print every row as JSON: the rows alone, or the rows with both dependency tables.
+*
+* @param ui - The branded console.
+* @param repos - The rows.
+* @param tables - The dependency tables, when asked for.
+* @example
+* printJson(ui, repos, tables);
+*/
+function printJson(ui, repos, tables) {
+	const output = tables === void 0 ? repos : {
+		repos,
+		...tables
+	};
+	ui.line(JSON.stringify(output, void 0, 2));
+}
+/**
+* Print the public rows as Markdown, then the dependency tables as collapsed blocks.
+*
+* @param ui - The branded console.
+* @param org - The organization login.
+* @param repos - The rows.
+* @param tables - The dependency tables, when asked for.
+* @example
+* printMarkdown(ui, "moku-labs", repos, tables);
+*/
+function printMarkdown(ui, org, repos, tables) {
+	ui.line(renderFleetMarkdown(org, repos));
+	if (tables === void 0) return;
+	ui.line("");
+	ui.line(renderDepsMarkdown(tables.toolchain, tables.runtime));
+}
+/**
+* Print the table for a terminal, then the dependency tables.
+*
+* @param ui - The branded console.
+* @param repos - The rows.
+* @param tables - The dependency tables, when asked for.
+* @example
+* printTerminal(ui, repos, tables);
+*/
+function printTerminal(ui, repos, tables) {
+	renderTerminal(ui, repos);
+	if (tables !== void 0) renderDepsTerminal(ui, tables.toolchain, tables.runtime);
+}
 /**
 * Read the state of every repository of the organization and print it.
 *
@@ -2470,7 +2771,7 @@ function renderTerminal(ui, repos) {
 * const code = await runFleet({ ctx, ui });
 */
 async function runFleet(options) {
-	const { ctx, ui, json = false, markdown = false } = options;
+	const { ctx, ui, json = false, markdown = false, deps = false } = options;
 	if (!(json || markdown)) ui.lockup({
 		wordmark: "moku release",
 		label: "fleet"
@@ -2494,9 +2795,11 @@ async function runFleet(options) {
 		return 1;
 	}
 	const repos = await withRegistry(ctx, parsed);
-	if (json) ui.line(JSON.stringify(repos, void 0, 2));
-	else if (markdown) ui.line(renderFleetMarkdown(org, repos));
-	else renderTerminal(ui, repos);
+	const shown = markdown ? repos.filter((repo) => !repo.isPrivate) : repos;
+	const tables = deps ? await dependencyTables(ctx, shown) : void 0;
+	if (json) printJson(ui, repos, tables);
+	else if (markdown) printMarkdown(ui, org, repos, tables);
+	else printTerminal(ui, repos, tables);
 	return 0;
 }
 //#endregion
@@ -3364,7 +3667,7 @@ async function runWait(options) {
 * dispatcher.
 *
 * The grammar is deliberately tiny: one positional (a command name, or a semver bump that
-* implies the `release` command) plus five flags. Anything unrecognized resolves to
+* implies the `release` command) plus six flags. Anything unrecognized resolves to
 * `help` with an `error` set — the CLI never guesses what an operator meant.
 */
 /** The semver bumps `moku-release <type>` accepts, in menu order. */
@@ -3378,6 +3681,7 @@ const RELEASE_TYPES = [
 const KNOWN_FLAGS = /* @__PURE__ */ new Set([
 	"--json",
 	"--markdown",
+	"--deps",
 	"--dry-run",
 	"--yes",
 	"-y"
@@ -3452,7 +3756,8 @@ function parseArgv(argv) {
 		json,
 		dryRun,
 		yes,
-		markdown: flags.includes("--markdown")
+		markdown: flags.includes("--markdown"),
+		deps: flags.includes("--deps")
 	};
 	if (first === "help") return {
 		command: "help",
@@ -3649,7 +3954,7 @@ const USAGE = [
 	"  moku-release setup              one-time wizard: workflows, contract, first publish",
 	"  moku-release doctor [--json]    read-only diagnosis of the release setup",
 	"  moku-release wait               wait for the auto-release of HEAD, verify it on npm",
-	"  moku-release fleet [--json|--markdown]",
+	"  moku-release fleet [--json|--markdown] [--deps]",
 	"                                  every repository of the organization in one table",
 	`  moku-release <${RELEASE_TYPES.join("|")}>`,
 	"",
@@ -3719,7 +4024,8 @@ async function dispatch(parsed, ctx, ui) {
 		ctx,
 		ui,
 		json: parsed.json,
-		markdown: parsed.markdown === true
+		markdown: parsed.markdown === true,
+		deps: parsed.deps === true
 	});
 	if (parsed.command === "release" && parsed.releaseType !== void 0) return runRelease({
 		ctx,

package/examples/org/fleet.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Read the fleet
         env:
           GH_TOKEN: ${{ github.token }}
-        run: npx --yes --package @moku-labs/ci@1 moku-release fleet --markdown > fleet.md
+        run: npx --yes --package @moku-labs/ci@1 moku-release fleet --markdown --deps > fleet.md
       - name: Put the table between the markers of profile/README.md
         run: |
           set -euo pipefail

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/ci",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Central CI and release for the moku family: reusable workflows, caller examples and the moku-release CLI.",
   "type": "module",
   "sideEffects": [
@@ -32,7 +32,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@moku-labs/common": "0.3.4",
+    "@moku-labs/common": "0.3.6",
     "@types/bun": "1.3.14",
     "@vitest/coverage-istanbul": "4.0.18",
     "eslint": "9.39.3",