workspace-conformance 1.6.0 → 2.0.0

package/dist/cli.js

@@ -8,8 +8,9 @@ import { escapePath, glob, isDynamicPattern } from "tinyglobby";
 import { Node, Project, SyntaxKind } from "ts-morph";
 import { createJitiLoader, validateStandard } from "cosmiconfig-extends";
 import { readFile, realpath } from "node:fs/promises";
-import { execFile } from "node:child_process";
+import { Range, subset, valid, validRange } from "semver";
 import { LineCounter, isMap, isNode, isScalar, isSeq, parse, parseDocument } from "yaml";
+import { execFile } from "node:child_process";
 import { findNodeAtLocation, parse as parse$1, parseTree, printParseErrorCode } from "jsonc-parser";
 import { parse as parse$2 } from "smol-toml";
 import { defineSection, layoutSection, loadSection } from "@exadev/config";
@@ -25,6 +26,15 @@ var ConformanceError = class extends Error {
 };
 //#endregion
 //#region src/github.ts
+/**
+* GitHub's refusal to read a branch's rules because the repository's plan does not offer rulesets, as for a private repository on a plan without them: no ruleset applies to its branches, so a check that requires one cannot be met. The message is GitHub's own. A {@link GitHubClient} rejects `branchRules` with it, and with any other error for every other refusal.
+*/
+var RulesetsUnavailableError = class extends ConformanceError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "RulesetsUnavailableError";
+	}
+};
 const repositorySchema = z.object({
 	default_branch: z.string(),
 	allow_rebase_merge: z.optional(z.boolean()),
@@ -40,6 +50,33 @@ const rulesSchema = z.array(z.looseObject({
 		allowed_merge_methods: z.optional(z.array(z.string()))
 	}))
 }));
+/**
+* The body of an error response of the REST API: `message` explains the refusal.
+*/
+const errorBodySchema = z.looseObject({ message: z.string() });
+/**
+* The 403 status of a request that GitHub refuses, for a missing permission, a rate limit or a feature the plan lacks alike.
+*/
+const FORBIDDEN = 403;
+/**
+* How GitHub's message starts when it refuses a request for a feature the repository's plan does not include ('Upgrade to GitHub Pro or make this repository public to enable this feature.'). The REST documentation of the branch rules endpoint lists no error status, and a 403 also means a missing permission ('Resource not accessible by personal access token') or a rate limit, so the message is the only thing that tells a plan limit apart.
+*/
+const PLAN_LIMIT_PREFIX = "Upgrade to GitHub ";
+/**
+* The plan-limit refusal of a branch's rules as {@link RulesetsUnavailableError}.
+*/
+const rulesRefusal = (status, githubMessage) => status === FORBIDDEN && githubMessage?.startsWith(PLAN_LIMIT_PREFIX) === true ? new RulesetsUnavailableError(githubMessage) : void 0;
+async function githubMessageOf(response) {
+	const text = await response.text();
+	let body;
+	try {
+		body = JSON.parse(text);
+	} catch {
+		return;
+	}
+	const parsed = errorBodySchema.safeParse(body);
+	return parsed.success ? parsed.data.message : void 0;
+}
 const API_ROOT = "https://api.github.com";
 const API_VERSION = "2022-11-28";
 /**
@@ -52,13 +89,16 @@ const PAGE_SIZE = 100;
 function createGitHubClient(options) {
 	const request = options.fetch ?? fetch;
 	const root = options.apiUrl ?? API_ROOT;
-	async function get(path) {
+	async function get(path, refusal) {
 		const response = await request(`${root}${path}`, { headers: {
 			Accept: "application/vnd.github+json",
 			Authorization: `Bearer ${options.token}`,
 			"X-GitHub-Api-Version": API_VERSION
 		} });
-		if (!response.ok) throw new ConformanceError(`GET ${path} failed: ${String(response.status)} ${response.statusText}`);
+		if (!response.ok) {
+			const githubMessage = await githubMessageOf(response);
+			throw refusal?.(response.status, githubMessage) ?? new ConformanceError(`GET ${path} failed: ${String(response.status)} ${response.statusText}${githubMessage === void 0 ? "" : `: ${githubMessage}`}`);
+		}
 		return response.json();
 	}
 	return {
@@ -76,7 +116,8 @@ function createGitHubClient(options) {
 		branchRules: async (slug, branch) => {
 			const rules = [];
 			for (let page = 1, more = true; more; page += 1) {
-				const found = rulesSchema.parse(await get(`/repos/${slug.owner}/${slug.name}/rules/branches/${encodeURIComponent(branch)}?per_page=${String(PAGE_SIZE)}&page=${String(page)}`));
+				const body = await get(`/repos/${slug.owner}/${slug.name}/rules/branches/${encodeURIComponent(branch)}?per_page=${String(PAGE_SIZE)}&page=${String(page)}`, rulesRefusal);
+				const found = rulesSchema.parse(body);
 				rules.push(...found);
 				more = found.length === PAGE_SIZE;
 			}
@@ -94,6 +135,20 @@ function createGitHubClient(options) {
 	};
 }
 //#endregion
+//#region src/paths.ts
+/**
+* `path` with the platform separator replaced by `/`, the form paths take in violations and in options.
+*/
+function toPosix(path) {
+	return path.split(sep).join("/");
+}
+/**
+* `absolute` relative to `cwd`, with `/` separators.
+*/
+function relativePosix(cwd, absolute) {
+	return toPosix(relative(cwd, absolute));
+}
+//#endregion
 //#region src/files.ts
 /**
 * Directories no check descends into: installed dependencies are not the workspace's own files.
@@ -145,20 +200,6 @@ async function findDirectories(cwd, patterns) {
 	})).map((directory) => directory.replace(/\/$/u, "")).sort();
 }
 //#endregion
-//#region src/paths.ts
-/**
-* `path` with the platform separator replaced by `/`, the form paths take in violations and in options.
-*/
-function toPosix(path) {
-	return path.split(sep).join("/");
-}
-/**
-* `absolute` relative to `cwd`, with `/` separators.
-*/
-function relativePosix(cwd, absolute) {
-	return toPosix(relative(cwd, absolute));
-}
-//#endregion
 //#region src/template.ts
 const PLACEHOLDER = /\{([a-z]+)\}/gu;
 /**
@@ -852,6 +893,317 @@ const dockerfilePackageManager = async ({ cwd, options }) => {
 	}
 	return violations;
 };
+/**
+* What every path inside the package in `dir` starts with, relative to the workspace root: `dir` and a `/`, or nothing for the root package, which holds every path. The trailing `/` keeps `packages/a` from holding `packages/ab`.
+*/
+function packagePathPrefix(dir) {
+	return dir === "." ? "" : `${dir}/`;
+}
+/**
+* Whether `path`, relative to the workspace root, is inside the package in `dir`.
+*/
+function isInPackage(dir, path) {
+	return path.startsWith(packagePathPrefix(dir));
+}
+function segmentsOf(path) {
+	return path.split("/").filter((segment) => segment !== "" && segment !== ".");
+}
+function groupRoot(group) {
+	return segmentsOf(group.path ?? group.name);
+}
+function startsWithSegments(segments, prefix) {
+	return prefix.every((segment, index) => segments[index] === segment);
+}
+/**
+* The group whose root is the longest prefix of `dir`; the first declared wins a tie. `undefined` when no group owns the directory.
+*/
+function owningGroup(dir, groups) {
+	const segments = segmentsOf(dir);
+	let best;
+	let bestLength = -1;
+	for (const group of groups) {
+		const root = groupRoot(group);
+		if (root.length > bestLength && startsWithSegments(segments, root)) {
+			best = group;
+			bestLength = root.length;
+		}
+	}
+	return best;
+}
+function rankOf(name, group, layout) {
+	if (name !== void 0) {
+		const rule = layout.nameRanks?.find((candidate) => new RegExp(candidate.pattern, "u").test(name));
+		if (rule !== void 0) return rule.rank;
+	}
+	return group.rank ?? layout.defaultRank;
+}
+/**
+* The name without its npm scope: `@scope/store-cli` gives `store-cli`.
+*/
+function unscoped(name) {
+	return name.replace(/^@[^/]+\//u, "");
+}
+/**
+* The longest slice value that is the whole unscoped name or its prefix up to a `-`.
+*/
+function sliceByNamePrefix(name, known) {
+	const bare = unscoped(name);
+	return [...known].filter((candidate) => bare === candidate || bare.startsWith(`${candidate}-`)).sort((a, b) => b.length - a.length)[0];
+}
+/**
+* Classify discovered packages by the layout: group, rank and slice. Pure.
+*
+* A package no group owns is a configuration error, because every check would otherwise skip it without saying so. Nested package directories are one too: the checks attribute a file to the package whose directory is its prefix, which is ambiguous for a package inside another. The root package holds every other directory, so it is a package only in a single-package repository. A `namePrefix` slice takes the longest slice value that a `segment` group produced and that prefixes the package's unscoped name; a package without a name has no such slice.
+*/
+function classifyPackages(discovered, layout) {
+	const owned = discovered.map((found) => {
+		const group = owningGroup(found.dir, layout.groups);
+		if (group === void 0) throw new ConformanceError(`the package directory '${found.dir}' is not under any layout group's path; add a group whose path prefixes it, or narrow the workspace package globs`);
+		return {
+			found,
+			group
+		};
+	});
+	const knownSlices = /* @__PURE__ */ new Set();
+	for (const { found, group } of owned) if (group.slice !== void 0 && "segment" in group.slice) {
+		const value = segmentsOf(found.dir).slice(groupRoot(group).length)[group.slice.segment];
+		if (value !== void 0) knownSlices.add(value);
+	}
+	const packages = owned.map(({ found, group }) => {
+		let slice;
+		if (group.slice !== void 0 && "segment" in group.slice) slice = segmentsOf(found.dir).slice(groupRoot(group).length)[group.slice.segment];
+		else if (group.slice !== void 0 && found.name !== void 0) slice = sliceByNamePrefix(found.name, knownSlices);
+		return {
+			...found,
+			group: group.name,
+			rank: rankOf(found.name, group, layout),
+			slice
+		};
+	});
+	for (const outer of packages) {
+		const nested = packages.find((inner) => inner.dir !== outer.dir && isInPackage(outer.dir, inner.dir));
+		if (nested !== void 0) throw new ConformanceError(`the package directory '${nested.dir}' is inside the package directory '${outer.dir}'; workspace packages must not nest`);
+	}
+	return packages;
+}
+/**
+* The workspace root: `layout.root` resolved against `cwd`, or `cwd` itself.
+*/
+function workspaceRoot(cwd, layout) {
+	return layout.root === void 0 ? cwd : resolve(cwd, layout.root);
+}
+const PNPM_WORKSPACE_FILE = "pnpm-workspace.yaml";
+/**
+* The `packages` list of `pnpm-workspace.yaml` in `root`, or `undefined` when there is no such file. A file that exists but cannot be read, or has no list of strings under `packages`, is a configuration error.
+*/
+async function pnpmWorkspacePatterns(root) {
+	const file = join(root, PNPM_WORKSPACE_FILE);
+	if (!existsSync(file)) return;
+	let source;
+	try {
+		source = await readFile(file, "utf8");
+	} catch (error) {
+		throw new ConformanceError(`${file} cannot be read`, { cause: error });
+	}
+	const document = parse(source);
+	if (typeof document !== "object" || document === null || !("packages" in document) || !Array.isArray(document.packages)) throw new ConformanceError(`${file} has no 'packages' list`);
+	const patterns = document.packages;
+	if (!patterns.every((pattern) => typeof pattern === "string")) throw new ConformanceError(`${file}: every entry of 'packages' must be a string`);
+	return patterns;
+}
+/**
+* The package globs: `layout.packages`, else the `packages` list of `pnpm-workspace.yaml` in `root`.
+*/
+async function workspacePatterns(root, layout) {
+	if (layout.packages !== void 0) return layout.packages;
+	const patterns = await pnpmWorkspacePatterns(root);
+	if (patterns === void 0) throw new ConformanceError(`the layout has no 'packages' and ${join(root, PNPM_WORKSPACE_FILE)} does not exist`);
+	return patterns;
+}
+async function readName(manifest) {
+	let content;
+	try {
+		content = JSON.parse(await readFile(manifest, "utf8"));
+	} catch (error) {
+		throw new ConformanceError(`${manifest} cannot be read as JSON`, { cause: error });
+	}
+	if (typeof content === "object" && content !== null && "name" in content && typeof content.name === "string") return content.name;
+}
+/**
+* The directories under `root` that the pnpm-style `patterns` select and that hold a `package.json`, sorted. A `!` pattern excludes. The root package is found, as {@link ROOT_PACKAGE_DIR}, when a pattern selects it (`.`, or `**`).
+*/
+async function discoverPackages(root, patterns) {
+	const manifests = patterns.map((pattern) => pattern.startsWith("!") ? `!${pattern.slice(1)}/**` : `${pattern}/package.json`);
+	const dirs = (await glob(manifests, {
+		cwd: root,
+		dot: true,
+		ignore: [INSTALLED_DEPENDENCIES_GLOB],
+		onlyFiles: true
+	})).map((manifest) => {
+		const dir = manifest.replace(/\/?package\.json$/u, "");
+		return dir === "" ? "." : dir;
+	});
+	return Promise.all([...new Set(dirs)].sort().map(async (dir) => ({
+		dir,
+		name: await readName(join(root, dir, "package.json"))
+	})));
+}
+/**
+* The layout's packages found under the workspace root. Finding none is a configuration error: every check that reads the packages would otherwise look at nothing and report a clean workspace.
+*/
+async function readWorkspacePackages(cwd, layout) {
+	const root = workspaceRoot(cwd, layout);
+	const patterns = await workspacePatterns(root, layout);
+	const discovered = await discoverPackages(root, patterns);
+	if (discovered.length === 0) throw new ConformanceError(`no workspace package found: ${patterns.length === 0 ? "the package patterns are empty, so no directory is selected" : `no directory the patterns ${patterns.join(", ")} select holds a package.json`}; for a single-package repository, set the layout's packages to ['.']`);
+	return classifyPackages(discovered, layout);
+}
+//#endregion
+//#region src/checks/engines-floor.ts
+/**
+* The pattern that selects the root package, the `package.json` in the directory the checks run in.
+*/
+const ROOT_PACKAGE = ".";
+const MANIFEST = "package.json";
+const ANY_INSTALLED_COPY = {};
+const DEPENDENCY_FIELDS = [
+	{
+		field: "dependencies",
+		noun: "dependency",
+		mayBeAbsent: () => false,
+		judgedCopy: () => ANY_INSTALLED_COPY
+	},
+	{
+		field: "optionalDependencies",
+		noun: "optional dependency",
+		mayBeAbsent: () => true,
+		judgedCopy: () => ANY_INSTALLED_COPY
+	},
+	{
+		field: "peerDependencies",
+		noun: "peer dependency",
+		mayBeAbsent: (manifest, name) => {
+			const meta = manifest["peerDependenciesMeta"];
+			const entry = isRecord(meta) ? meta[name] : void 0;
+			return isRecord(entry) && entry["optional"] === true;
+		},
+		judgedCopy: (spec) => {
+			const version = onlyAdmittedVersion(spec);
+			return version === null ? void 0 : { version };
+		}
+	}
+];
+/**
+* The one version `spec` admits, when it is a semver range of a single comparator naming an exact version (`1.2.3` or `=1.2.3`); `null`, as semver gives for no version, for any other range, including one of a single major, and for a spec that is not a semver range (`workspace:^`, a tag or a URL).
+*/
+function onlyAdmittedVersion(spec) {
+	if (validRange(spec) === null) return null;
+	const [comparators, ...others] = new Range(spec).set;
+	if (comparators === void 0 || others.length > 0 || comparators.length !== 1) return null;
+	const [comparator] = comparators;
+	if (comparator?.operator !== "") return null;
+	return valid(comparator.value);
+}
+async function readManifest(cwd, file) {
+	let content;
+	try {
+		content = JSON.parse(await readFile(resolve(cwd, file), "utf8"));
+	} catch (error) {
+		throw new ConformanceError(`${file} cannot be read as JSON`, { cause: error });
+	}
+	if (!isRecord(content)) throw new ConformanceError(`${file} is not a JSON object`);
+	return content;
+}
+/**
+* The `engines.node` range the manifest at `file` declares, or `undefined` when it declares none. A range semver cannot parse is a configuration error, since nothing can be said about the versions it admits.
+*/
+function nodeRange(manifest, file) {
+	const engines = manifest["engines"];
+	if (engines === void 0) return;
+	if (!isRecord(engines)) throw new ConformanceError(`${file}: engines must be an object`);
+	const node = engines["node"];
+	if (node === void 0) return;
+	if (typeof node !== "string") throw new ConformanceError(`${file}: engines.node must be a string, not ${JSON.stringify(node)}`);
+	if (validRange(node) === null) throw new ConformanceError(`${file}: engines.node '${node}' is not a valid semver range`);
+	return node;
+}
+/**
+* The name and version spec of each dependency a dependency field of the manifest at `file` lists, sorted by name; none when the field is absent.
+*/
+function dependencyEntries(manifest, field, file) {
+	const listed = manifest[field];
+	if (listed === void 0) return [];
+	if (!isRecord(listed)) throw new ConformanceError(`${file}: ${field} must be an object`);
+	return Object.keys(listed).sort().map((name) => {
+		const spec = listed[name];
+		if (typeof spec !== "string") throw new ConformanceError(`${file}: ${field}.${name} must be a string, not ${JSON.stringify(spec)}`);
+		return [name, spec];
+	});
+}
+/**
+* The `package.json` of the dependency `name` as installed for the package in `packageDirectory`, found the way Node finds a package directory: in `node_modules` of the package's own directory, then of each directory above it, stopping at the working directory, since a copy above the workspace is not one its install put there. A symbolic link, as pnpm installs every dependency, is followed. `undefined` when no directory has it.
+*/
+function installedManifest(cwd, packageDirectory, name) {
+	const top = resolve(cwd);
+	for (let directory = resolve(cwd, packageDirectory);; directory = dirname(directory)) {
+		const candidate = join(directory, "node_modules", name, MANIFEST);
+		if (existsSync(candidate)) return relativePosix(cwd, candidate);
+		if (directory === top) return;
+	}
+}
+/**
+* The directories of the packages to judge: those `packages` selects, else the root package and the `packages` of `pnpm-workspace.yaml`. Selecting none is a configuration error, so a pattern that matches nothing never reads as a pass.
+*/
+async function packageDirectories(cwd, options) {
+	const patterns = options.packages ?? [ROOT_PACKAGE, ...await pnpmWorkspacePatterns(cwd) ?? []];
+	const members = await discoverPackages(cwd, patterns.filter((pattern) => pattern !== ROOT_PACKAGE));
+	const directories = [...patterns.includes(ROOT_PACKAGE) ? [ROOT_PACKAGE] : [], ...members.map((member) => member.dir)];
+	if (directories.length === 0) throw new ConformanceError(`no package.json is selected by ${patterns.join(", ")}`);
+	return directories;
+}
+/**
+* The `engines.node` range of each package is a subset of the `engines.node` range of each dependency and optional dependency it lists, and of each peer dependency whose range admits a single version, as installed in `node_modules`, so the package admits no Node version that something it needs at run time rejects. A package that declares no range admits every version, so it is reported for each dependency that declares one. A dependency that declares no range constrains nothing and is ignored.
+*
+* The comparison is `semver.subset(package, dependency)`: every version the package's range admits satisfies the dependency's range. A floor alone is not enough, because a range of several lines (`^20.19.0 || ^22.13.0 || >=24`) also rejects the versions between them, which `>=20.19.0` admits. semver compares a range of several comparator sets set by set, so each set of the package's range must lie within one set of the dependency's; a set that only two adjacent dependency sets cover together (`>=22` against `^22.0.0 || >=23`) is reported, and splitting it the same way (`^22.0.0 || >=23`) satisfies the check.
+*
+* A peer dependency is judged only when its range admits a single version (`1.2.3` or `=1.2.3`), and then by the copy installed, which must be that version. The consumer chooses which admitted version to install, so the package's range holds when each Node version in it is accepted by some admitted version; one installed copy that rejects a Node version does not show that every admitted version does, and the others are not on disk.
+*
+* A dependency that is not installed fails the run: its range cannot be read, and passing it unjudged would read as a pass. An optional dependency and a peer dependency marked optional in `peerDependenciesMeta` may be absent and are then skipped.
+*/
+const enginesFloor = async ({ cwd, options }) => {
+	const violations = [];
+	for (const directory of await packageDirectories(cwd, options)) {
+		const file = posix.join(directory, MANIFEST);
+		const manifest = await readManifest(cwd, file);
+		const own = nodeRange(manifest, file);
+		const seen = /* @__PURE__ */ new Set();
+		for (const { field, noun, mayBeAbsent, judgedCopy } of DEPENDENCY_FIELDS) for (const [name, spec] of dependencyEntries(manifest, field, file).filter(([candidate]) => !seen.has(candidate))) {
+			seen.add(name);
+			const copy = judgedCopy(spec);
+			if (copy === void 0) continue;
+			const installed = installedManifest(cwd, directory, name);
+			if (installed === void 0) {
+				if (mayBeAbsent(manifest, name)) continue;
+				throw new ConformanceError(`${file}: the ${noun} '${name}' is not installed (no node_modules/${name}/package.json in its directory or any directory above it up to the working directory); install the workspace before running engines-floor`);
+			}
+			const dependency = await readManifest(cwd, installed);
+			if (copy.version !== void 0 && dependency["version"] !== copy.version) throw new ConformanceError(`${file}: the ${noun} '${name}' admits only version ${copy.version}, but ${installed} is version ${String(dependency["version"])}; install the workspace before running engines-floor`);
+			const theirs = nodeRange(dependency, installed);
+			if (theirs === void 0) continue;
+			if (own === void 0) violations.push({
+				code: "engines-floor/no-engines",
+				message: `no engines.node is declared, so every Node version is admitted, but the ${noun} '${name}' requires engines.node '${theirs}'; declare a subset of that range`,
+				file
+			});
+			else if (!subset(own, theirs)) violations.push({
+				code: "engines-floor/wider-than-dependency",
+				message: `engines.node '${own}' admits Node versions that the ${noun} '${name}' rejects with engines.node '${theirs}'; narrow it to a subset of that range`,
+				file
+			});
+		}
+	}
+	return violations;
+};
 async function git(cwd, args) {
 	return new Promise((resolve, reject) => {
 		execFile("git", [...args], {
@@ -939,6 +1291,24 @@ async function branchOf(github, slug, options) {
 function repositoryFile(slug) {
 	return `${slug.owner}/${slug.name}`;
 }
+/**
+* The rules of the branch, or GitHub's message when the repository's plan has no rulesets, in which case no rule applies to the branch and none can be added. Any other refusal rejects.
+*/
+async function branchRulesOf(github, slug, options) {
+	const branch = await branchOf(github, slug, options);
+	try {
+		return { rules: await github.branchRules(slug, branch) };
+	} catch (error) {
+		if (error instanceof RulesetsUnavailableError) return { unavailable: error.message };
+		throw error;
+	}
+}
+/**
+* The message of a `rules-unavailable` violation: the branch rules of the repository cannot be read or enforced on its plan, so `what` cannot be required.
+*/
+function rulesUnavailableMessage(file, what, githubMessage) {
+	return `the branch rules of ${file} cannot be read or enforced on its plan, so ${what} cannot be required (GitHub: ${githubMessage})`;
+}
 //#endregion
 //#region src/checks/settings-merge-methods.ts
 const METHODS = [
@@ -949,20 +1319,23 @@ const METHODS = [
 /**
 * Only one merge method is available for a pull request into the branch, `rebase` unless the options say otherwise. A method is available when the repository allows it and no `pull_request` rule that applies to the branch leaves it out of its allowed methods.
 *
+* When the repository's plan has no rulesets, no rule applies to the branch and the repository settings alone decide.
+*
 * Limits: it reads the repository settings and the rules of rulesets that apply to the branch; classic branch protection and a merge queue's own merge method are not read, so a repository whose queue owns the strategy is judged by what it still allows for a direct merge.
 */
 const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
 	const file = repositoryFile(slug);
 	const settings = await github.repository(slug);
-	const rules = await github.branchRules(slug, await branchOf(github, slug, options));
+	const read = await branchRulesOf(github, slug, options);
+	const pullRequests = "unavailable" in read ? [] : read.rules.pullRequests;
 	const wanted = options.allowed ?? "rebase";
 	const repositoryAllows = {
 		rebase: settings.allowRebaseMerge,
 		squash: settings.allowSquashMerge,
 		merge: settings.allowMergeCommit
 	};
-	const available = METHODS.filter((method) => repositoryAllows[method] && rules.pullRequests.every((rule) => rule.allowedMergeMethods === void 0 || rule.allowedMergeMethods.includes(method)));
+	const available = METHODS.filter((method) => repositoryAllows[method] && pullRequests.every((rule) => rule.allowedMergeMethods === void 0 || rule.allowedMergeMethods.includes(method)));
 	const violations = available.filter((method) => method !== wanted).map((method) => ({
 		code: "settings-merge-methods/method-enabled",
 		message: `${file} allows ${method} merges; only ${wanted} should be allowed`,
@@ -1361,14 +1734,20 @@ const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 /**
 * The branch requires the check of every junction job of the workflows, and requires branches to be up to date before merging (strict mode). The check name of a job is its `name`, else its id.
 *
-* The junction job is the one that reports for the whole workflow, so requiring it requires everything it needs, including jobs a path filter may skip. Codes: `no-required-checks` (no `required_status_checks` rule applies), `required-check-missing` (a junction job's check is not among the required ones), `not-strict` (no rule sets the strict policy) and `no-junction-job` (no workflow has a job with an id from `junctionJobs`).
+* The junction job is the one that reports for the whole workflow, so requiring it requires everything it needs, including jobs a path filter may skip. Codes: `no-required-checks` (no `required_status_checks` rule applies), `required-check-missing` (a junction job's check is not among the required ones), `not-strict` (no rule sets the strict policy), `no-junction-job` (no workflow has a job with an id from `junctionJobs`) and `rules-unavailable` (the repository's plan has no rulesets, so no check can be required; reported alone, with GitHub's message).
 *
 * Limits: it reads the rules of rulesets that apply to the branch; classic branch protection is not read, so a repository that uses it is reported as having no required checks. A junction job in a reusable workflow, or a name that is an expression, is not resolved.
 */
 const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
 	const file = repositoryFile(slug);
-	const rules = await github.branchRules(slug, await branchOf(github, slug, options));
+	const read = await branchRulesOf(github, slug, options);
+	if ("unavailable" in read) return [{
+		code: "settings-required-checks/rules-unavailable",
+		message: rulesUnavailableMessage(file, "a status check", read.unavailable),
+		file
+	}];
+	const { rules } = read;
 	const junctions = (await loadWorkflows(cwd, options)).flatMap((workflow) => jobsNamed(workflow, options.junctionJobs ?? DEFAULT_JUNCTION_JOBS).map((job) => ({
 		workflow,
 		name: job.name ?? job.id
@@ -1405,13 +1784,20 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 /**
 * A pull request cannot merge while a review conversation is unresolved: a `pull_request` rule that applies to the branch sets `required_review_thread_resolution`.
 *
+* When the repository's plan has no rulesets it reports `rules-unavailable` with GitHub's message, since nothing can require it.
+*
 * Limits: it reads the rules of rulesets; classic branch protection is not read.
 */
 const settingsReviewThreadResolution = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const rules = await github.branchRules(slug, await branchOf(github, slug, options));
+	const read = await branchRulesOf(github, slug, options);
 	const file = repositoryFile(slug);
-	return rules.pullRequests.some((rule) => rule.requiredReviewThreadResolution) ? [] : [{
+	if ("unavailable" in read) return [{
+		code: "settings-review-thread-resolution/rules-unavailable",
+		message: rulesUnavailableMessage(file, "resolving review conversations", read.unavailable),
+		file
+	}];
+	return read.rules.pullRequests.some((rule) => rule.requiredReviewThreadResolution) ? [] : [{
 		code: "settings-review-thread-resolution/not-required",
 		message: `no rule requires review conversations to be resolved before merging on the branch of ${file}`,
 		file
@@ -2196,10 +2582,10 @@ function escapeRegExp(text) {
 	return text.replace(REGEXP_SPECIAL, "\\$&");
 }
 /**
-* A regular expression, as source text, matching every file inside any of the packages. The trailing `/` keeps `packages/a` from matching `packages/ab`.
+* A regular expression, as source text, matching every file inside any of the packages: the path starts with one's {@link packagePathPrefix}.
 */
 function packagesPattern(packages) {
-	return `^(${packages.map((member) => `${escapeRegExp(member.dir)}/`).join("|")})`;
+	return `^(${packages.map((member) => escapeRegExp(packagePathPrefix(member.dir))).join("|")})`;
 }
 /**
 * A regular expression, as source text, matching the name an import uses for any of the named packages: the name itself or a subpath of it. It matches nothing but those names, and is `undefined` when no package has a name.
@@ -2345,145 +2731,6 @@ function unresolvedNameImportRule(packages) {
 	};
 }
 //#endregion
-//#region src/workspace/packages.ts
-function segmentsOf(path) {
-	return path.split("/").filter((segment) => segment !== "" && segment !== ".");
-}
-function groupRoot(group) {
-	return segmentsOf(group.path ?? group.name);
-}
-function startsWithSegments(segments, prefix) {
-	return prefix.every((segment, index) => segments[index] === segment);
-}
-/**
-* The group whose root is the longest prefix of `dir`; the first declared wins a tie. `undefined` when no group owns the directory.
-*/
-function owningGroup(dir, groups) {
-	const segments = segmentsOf(dir);
-	let best;
-	let bestLength = -1;
-	for (const group of groups) {
-		const root = groupRoot(group);
-		if (root.length > bestLength && startsWithSegments(segments, root)) {
-			best = group;
-			bestLength = root.length;
-		}
-	}
-	return best;
-}
-function rankOf(name, group, layout) {
-	if (name !== void 0) {
-		const rule = layout.nameRanks?.find((candidate) => new RegExp(candidate.pattern, "u").test(name));
-		if (rule !== void 0) return rule.rank;
-	}
-	return group.rank ?? layout.defaultRank;
-}
-/**
-* The name without its npm scope: `@scope/store-cli` gives `store-cli`.
-*/
-function unscoped(name) {
-	return name.replace(/^@[^/]+\//u, "");
-}
-/**
-* The longest slice value that is the whole unscoped name or its prefix up to a `-`.
-*/
-function sliceByNamePrefix(name, known) {
-	const bare = unscoped(name);
-	return [...known].filter((candidate) => bare === candidate || bare.startsWith(`${candidate}-`)).sort((a, b) => b.length - a.length)[0];
-}
-/**
-* Classify discovered packages by the layout: group, rank and slice. Pure.
-*
-* A package no group owns is a configuration error, because every check would otherwise skip it without saying so. Nested package directories are one too: the checks attribute a file to the package whose directory is its prefix, which is ambiguous for a package inside another. A `namePrefix` slice takes the longest slice value that a `segment` group produced and that prefixes the package's unscoped name; a package without a name has no such slice.
-*/
-function classifyPackages(discovered, layout) {
-	const owned = discovered.map((found) => {
-		const group = owningGroup(found.dir, layout.groups);
-		if (group === void 0) throw new ConformanceError(`the package directory '${found.dir}' is not under any layout group's path; add a group whose path prefixes it, or narrow the workspace package globs`);
-		return {
-			found,
-			group
-		};
-	});
-	const knownSlices = /* @__PURE__ */ new Set();
-	for (const { found, group } of owned) if (group.slice !== void 0 && "segment" in group.slice) {
-		const value = segmentsOf(found.dir).slice(groupRoot(group).length)[group.slice.segment];
-		if (value !== void 0) knownSlices.add(value);
-	}
-	const packages = owned.map(({ found, group }) => {
-		let slice;
-		if (group.slice !== void 0 && "segment" in group.slice) slice = segmentsOf(found.dir).slice(groupRoot(group).length)[group.slice.segment];
-		else if (group.slice !== void 0 && found.name !== void 0) slice = sliceByNamePrefix(found.name, knownSlices);
-		return {
-			...found,
-			group: group.name,
-			rank: rankOf(found.name, group, layout),
-			slice
-		};
-	});
-	for (const outer of packages) {
-		const nested = packages.find((inner) => inner.dir !== outer.dir && inner.dir.startsWith(`${outer.dir}/`));
-		if (nested !== void 0) throw new ConformanceError(`the package directory '${nested.dir}' is inside the package directory '${outer.dir}'; workspace packages must not nest`);
-	}
-	return packages;
-}
-/**
-* The workspace root: `layout.root` resolved against `cwd`, or `cwd` itself.
-*/
-function workspaceRoot(cwd, layout) {
-	return layout.root === void 0 ? cwd : resolve(cwd, layout.root);
-}
-/**
-* The package globs: `layout.packages`, else the `packages` list of `pnpm-workspace.yaml` in `root`.
-*/
-async function workspacePatterns(root, layout) {
-	if (layout.packages !== void 0) return layout.packages;
-	const file = join(root, "pnpm-workspace.yaml");
-	let source;
-	try {
-		source = await readFile(file, "utf8");
-	} catch (error) {
-		throw new ConformanceError(`the layout has no 'packages' and ${file} cannot be read`, { cause: error });
-	}
-	const document = parse(source);
-	if (typeof document !== "object" || document === null || !("packages" in document) || !Array.isArray(document.packages)) throw new ConformanceError(`${file} has no 'packages' list`);
-	const patterns = document.packages;
-	if (!patterns.every((pattern) => typeof pattern === "string")) throw new ConformanceError(`${file}: every entry of 'packages' must be a string`);
-	return patterns;
-}
-async function readName(manifest) {
-	let content;
-	try {
-		content = JSON.parse(await readFile(manifest, "utf8"));
-	} catch (error) {
-		throw new ConformanceError(`${manifest} cannot be read as JSON`, { cause: error });
-	}
-	if (typeof content === "object" && content !== null && "name" in content && typeof content.name === "string") return content.name;
-}
-/**
-* The directories under `root` that the pnpm-style `patterns` select and that hold a `package.json`, sorted. A `!` pattern excludes. The root package itself (`.`) is not a member of any group and is left out.
-*/
-async function discoverPackages(root, patterns) {
-	const manifests = patterns.map((pattern) => pattern.startsWith("!") ? `!${pattern.slice(1)}/**` : `${pattern}/package.json`);
-	const dirs = (await glob(manifests, {
-		cwd: root,
-		dot: true,
-		ignore: [INSTALLED_DEPENDENCIES_GLOB],
-		onlyFiles: true
-	})).map((manifest) => manifest.replace(/\/?package\.json$/u, "")).filter((dir) => dir !== "");
-	return Promise.all([...new Set(dirs)].sort().map(async (dir) => ({
-		dir,
-		name: await readName(join(root, dir, "package.json"))
-	})));
-}
-/**
-* The layout's packages found under the workspace root.
-*/
-async function readWorkspacePackages(cwd, layout) {
-	const root = workspaceRoot(cwd, layout);
-	return classifyPackages(await discoverPackages(root, await workspacePatterns(root, layout)), layout);
-}
-//#endregion
 //#region src/checks/import-graph.ts
 /**
 * Paths left out of the import graph unless the options say otherwise: a package's own installed dependencies.
@@ -2497,7 +2744,7 @@ const DEFAULT_DO_NOT_FOLLOW = ["(^|/)dist/"];
 * The package a path in the graph belongs to: the one whose directory holds the file, and only when no directory does, the one whose name the path is (an import that resolved to no file is known only by the name it was written with, or a subpath of it). The directory wins because an unscoped package name can equal the leading directory of another package's files. It throws `ConformanceError` for a path the graph should not contain.
 */
 function packageOfPath(packages, path) {
-	const found = packages.find((member) => path.startsWith(`${member.dir}/`)) ?? packages.find((member) => member.name !== void 0 && (path === member.name || path.startsWith(`${member.name}/`)));
+	const found = packages.find((member) => isInPackage(member.dir, path)) ?? packages.find((member) => member.name !== void 0 && (path === member.name || path.startsWith(`${member.name}/`)));
 	if (found === void 0) throw new ConformanceError(`${path} is in no workspace package, although the graph is limited to the packages' files and names`);
 	return found;
 }
@@ -2640,7 +2887,7 @@ function describePackage(member) {
 */
 function describeTarget(edge) {
 	const { to, toFile } = edge;
-	return !toFile.startsWith(`${to.dir}/`) && to.name !== void 0 && (toFile === to.name || toFile.startsWith(`${to.name}/`)) ? toFile : `${toFile} in ${describePackage(to)}`;
+	return !isInPackage(to.dir, toFile) && to.name !== void 0 && (toFile === to.name || toFile.startsWith(`${to.name}/`)) ? toFile : `${toFile} in ${describePackage(to)}`;
 }
 //#endregion
 //#region src/checks/import-cross-slice.ts
@@ -2915,40 +3162,61 @@ async function sampleViolations(eslint, sample, shared) {
 function isNothingLinted(error) {
 	return error instanceof Error && isRecord(error) && (error["messageTemplate"] === "file-not-found" || error["messageTemplate"] === "all-matched-files-ignored");
 }
+/**
+* Where a message is, or `undefined` for a message about the whole file. ESLint types `line` and `column` as numbers, but a parsing error copies them from the parser's error, which may carry none: typescript-eslint's project service reports a file outside every tsconfig that way.
+*/
+function locationOf(message) {
+	const line = message.line;
+	const column = message.column;
+	return typeof line === "number" && typeof column === "number" ? {
+		line,
+		column
+	} : void 0;
+}
 function messageViolation(cwd, result, message) {
 	const file = relativePosix(cwd, result.filePath);
-	const location = {
-		line: message.line,
-		column: message.column
+	const location = locationOf(message);
+	const at = location === void 0 ? { file } : {
+		file,
+		location
 	};
 	if (message.ruleId !== null) {
 		const severity = message.severity === 1 ? "warn" : "error";
 		return {
 			code: `eslint/lint/${message.ruleId}`,
 			message: `${message.ruleId} (${severity}): ${message.message}`,
-			file,
-			location
+			...at
 		};
 	}
 	return message.fatal === true ? {
 		code: "eslint/fatal",
 		message: message.message,
-		file,
-		location
+		...at
 	} : {
 		code: "eslint/lint-message",
 		message: message.message,
-		file,
-		location
+		...at
 	};
 }
 function byPosition(left, right) {
 	return left.file.localeCompare(right.file) || (left.location?.line ?? 0) - (right.location?.line ?? 0) || (left.location?.column ?? 0) - (right.location?.column ?? 0) || left.code.localeCompare(right.code);
 }
+function files(count) {
+	return count === 1 ? "1 file" : `${String(count)} files`;
+}
+/**
+* The files below `cwd` that ESLint has a configuration for (not ignored, and matched by a configuration block) and that the lint did not reach: the patterns are narrower than what the config covers.
+*/
+async function unreachedFiles(cwd, eslint, linted) {
+	const candidates = (await findFiles(cwd, ["**"])).filter((file) => !linted.has(resolve(cwd, file)));
+	const unreached = [];
+	for (const file of candidates) if (!await eslint.isPathIgnored(file)) unreached.push(file);
+	return unreached;
+}
 /**
-* Lints the workspace through the Node API, with the repository's own config, and maps every message to a violation. A pattern that selects no linted file is itself a violation, since the workspace is then not linted at all.
+* Lints the workspace through the Node API, with the repository's own config, and maps every message to a violation. A pattern that selects no linted file is itself a violation, since the workspace is then not linted at all. It notes how many files it linted and how many files the config covers that the patterns did not reach.
 */
-async function lintViolations(cwd, eslint, patterns) {
+async function lintViolations(cwd, eslint, patterns, note) {
 	const violations = [];
 	const results = /* @__PURE__ */ new Map();
 	for (const pattern of patterns) try {
@@ -2962,6 +3230,10 @@ async function lintViolations(cwd, eslint, patterns) {
 		});
 	}
 	for (const result of results.values()) for (const message of result.messages) violations.push(messageViolation(cwd, result, message));
+	if (note !== void 0) {
+		const unreached = await unreachedFiles(cwd, eslint, new Set(results.keys()));
+		note(unreached.length === 0 ? `linted ${files(results.size)}` : `linted ${files(results.size)}; ${unreached.length === 1 ? "1 other file has" : `${String(unreached.length)} other files have`} an ESLint configuration and ${unreached.length === 1 ? "was" : "were"} not reached by lintPatterns (${patterns.join(", ")})`);
+	}
 	return violations.sort(byPosition);
 }
 /**
@@ -2971,7 +3243,9 @@ async function lintViolations(cwd, eslint, patterns) {
 *
 * The config is a black box: the check sees which rules are active on a file, not why. It does not embed a config, so a repository without one is reported and nothing is substituted.
 */
-const eslint = async ({ cwd, options }) => {
+const eslint = async (context) => {
+	const { options } = context;
+	const cwd = resolve(context.cwd);
 	const instance = new (loadEslint(cwd))({
 		cwd,
 		...options.configFile === void 0 ? {} : { overrideConfigFile: resolve(cwd, options.configFile) }
@@ -2979,7 +3253,7 @@ const eslint = async ({ cwd, options }) => {
 	const shared = options.rules ?? {};
 	const violations = [];
 	for (const sample of options.samples.map(sampleOf)) violations.push(...await sampleViolations(instance, sample, shared));
-	if (options.lint === true) violations.push(...await lintViolations(cwd, instance, options.lintPatterns ?? DEFAULT_LINT_PATTERNS));
+	if (options.lint === true) violations.push(...await lintViolations(cwd, instance, options.lintPatterns ?? DEFAULT_LINT_PATTERNS, context.note));
 	return violations;
 };
 //#endregion
@@ -3016,7 +3290,7 @@ async function leadsTo(cwd, file, entry, destination) {
 	}
 }
 /**
-* Each agent instruction file is tracked by git as a symbolic link (mode 120000) whose target is the README beside it, so the two cannot diverge. The link may be written in any form that resolves there (`./README.md`), and may lead through other tracked links, as in `CLAUDE.md` to `AGENTS.md` to `README.md`. It reads the index, not the working tree, so a checkout with `core.symlinks` false, where a link is written out as a plain file, is judged by what is committed.
+* Each agent instruction file is tracked by git as a symbolic link (mode 120000) whose target is the README beside it, so the two cannot diverge. A directory without a tracked README has nothing to link to, so a missing instruction file there is not reported; one that exists is still judged. The link may be written in any form that resolves there (`./README.md`), and may lead through other tracked links, as in `CLAUDE.md` to `AGENTS.md` to `README.md`. It reads the index, not the working tree, so a checkout with `core.symlinks` false, where a link is written out as a plain file, is judged by what is committed.
 */
 const instructionSymlinks = async ({ cwd, options }) => {
 	const files = options.files ?? DEFAULT_INSTRUCTION_FILES;
@@ -3024,15 +3298,17 @@ const instructionSymlinks = async ({ cwd, options }) => {
 	const violations = [];
 	for (const directory of await directoriesOf(cwd, options.directories ?? ["."])) {
 		const readme = posix.join(directory, target);
+		const readmeTracked = await indexEntry(cwd, readme) !== void 0;
 		for (const name of files) {
 			const file = posix.join(directory, name);
 			const entry = await indexEntry(cwd, file);
-			if (entry === void 0) violations.push({
-				code: "instruction-symlinks/missing",
-				message: `${file} is not tracked; commit it as a symbolic link to ${target}`,
-				file
-			});
-			else if (entry.mode !== "120000") violations.push({
+			if (entry === void 0) {
+				if (readmeTracked) violations.push({
+					code: "instruction-symlinks/missing",
+					message: `${file} is not tracked; commit it as a symbolic link to ${target}`,
+					file
+				});
+			} else if (entry.mode !== "120000") violations.push({
 				code: "instruction-symlinks/not-a-symlink",
 				message: `${file} is committed as a regular file (mode ${entry.mode}); commit it as a symbolic link to ${target}`,
 				file
@@ -3044,7 +3320,7 @@ const instructionSymlinks = async ({ cwd, options }) => {
 					message: `${file} links to ${linked}; it should link to ${target}`,
 					file
 				});
-			} else if (await indexEntry(cwd, readme) === void 0) violations.push({
+			} else if (!readmeTracked) violations.push({
 				code: "instruction-symlinks/dangling",
 				message: `${file} links to ${target}, which is not tracked`,
 				file
@@ -3285,12 +3561,13 @@ function plain(spec) {
 		requiresLayout: false,
 		requiresGitHub: false,
 		isEnabled: (checks) => spec.select(checks) !== void 0,
-		run: async ({ cwd, checks, configFiles }) => {
+		run: async ({ cwd, checks, configFiles, note }) => {
 			const options = spec.select(checks);
 			if (options === void 0) throw new ConformanceError(`the check '${spec.name}' is not enabled`);
 			return spec.check({
 				cwd,
 				options,
+				note,
 				...configFiles === void 0 ? {} : { configFiles }
 			});
 		}
@@ -3303,7 +3580,7 @@ function online(spec) {
 		requiresLayout: false,
 		requiresGitHub: true,
 		isEnabled: (checks) => spec.select(checks) !== void 0,
-		run: async ({ cwd, checks, configFiles, github }) => {
+		run: async ({ cwd, checks, configFiles, github, note }) => {
 			const options = spec.select(checks);
 			if (options === void 0) throw new ConformanceError(`the check '${spec.name}' is not enabled`);
 			if (github === void 0) throw new ConformanceError(`the check '${spec.name}' reads the repository's settings and needs a GitHub client`);
@@ -3311,6 +3588,7 @@ function online(spec) {
 				cwd,
 				options,
 				github,
+				note,
 				...configFiles === void 0 ? {} : { configFiles }
 			});
 		}
@@ -3405,6 +3683,12 @@ const registry = {
 		select: (checks) => enabledOptions(checks["commit-types"]),
 		check: commitTypes
 	}),
+	"engines-floor": plain({
+		name: "engines-floor",
+		description: "A package's engines.node range admits no Node version that one of its installed dependencies rejects",
+		select: (checks) => enabledOptions(checks["engines-floor"]),
+		check: enginesFloor
+	}),
 	"dockerfile-package-manager": plain({
 		name: "dockerfile-package-manager",
 		description: "A package manager version pinned in a Dockerfile is the version packageManager names",
@@ -3609,6 +3893,7 @@ const checks = z.strictObject({
 		commitlint: z.exactOptional(path),
 		release: z.exactOptional(path)
 	}))),
+	"engines-floor": z.exactOptional(enabled(z.strictObject({ packages: z.exactOptional(paths) }))),
 	"dockerfile-package-manager": z.exactOptional(enabled(z.strictObject({
 		dockerfiles: z.exactOptional(paths),
 		exclude: z.exactOptional(paths),
@@ -3714,7 +3999,7 @@ async function conformanceOf(options) {
 		cwd: options.cwd
 	});
 	if (loaded === void 0) throw new ConformanceError(`no 'conformance' section in ${options.cwd}; define it in exadev.config.ts or in exadev.conformance.config.ts`);
-	return loaded;
+	return loaded.value;
 }
 async function layoutOf(options, needed) {
 	if (options.layout !== void 0) return validateStandard(layoutSection.schema, options.layout, `'${layoutSection.name}' section passed to runChecks`);
@@ -3724,7 +4009,7 @@ async function layoutOf(options, needed) {
 		cwd: options.cwd
 	});
 	if (loaded === void 0) throw new ConformanceError(`${needed.join(", ")} read the workspace layout, and there is no 'layout' section in ${options.cwd}; define it in exadev.config.ts or in exadev.layout.config.ts`);
-	return loaded;
+	return loaded.value;
 }
 function selected(config, requested, online) {
 	const enabled = checkNames.filter((name) => registry[name].isEnabled(config.checks));
@@ -3774,7 +4059,11 @@ function readImported(imported, name) {
 *
 * Violations do not throw. It throws `ConformanceError` when the checks cannot run (nothing enabled, a requested check disabled, a section missing) and `ConfigValidationError` when a section fails its schema, whether it was loaded from `cwd` or passed in.
 */
-async function runChecks(options) {
+async function runChecks(given) {
+	const options = {
+		...given,
+		cwd: resolve(given.cwd)
+	};
 	const config = await conformanceOf(options);
 	const names = selected(config, options.checks, options.github !== void 0);
 	const layout = await layoutOf(options, names.filter((name) => registry[name].requiresLayout));
@@ -3782,16 +4071,22 @@ async function runChecks(options) {
 	const results = [];
 	for (const name of names) {
 		const check = registry[name];
+		const notes = [];
+		const note = (text) => {
+			notes.push(text);
+		};
 		const violations = "run" in check ? await check.run({
 			cwd: options.cwd,
 			checks: config.checks,
 			layout,
 			configFiles: options.configFiles,
-			github: options.github
+			github: options.github,
+			note
 		}) : readImported(imported, name);
 		results.push({
 			check: name,
-			violations
+			violations,
+			notes
 		});
 	}
 	const violations = results.flatMap((result) => result.violations);
@@ -3803,7 +4098,18 @@ async function runChecks(options) {
 }
 //#endregion
 //#region src/cli-command.ts
-const USAGE = `Usage: workspace-conformance check [--cwd <directory>] [--check <name>]... [--list] [--settings]
+/**
+* How the command prints a result.
+*/
+const FORMATS = [
+	"text",
+	"json",
+	"github"
+];
+function isFormat(value) {
+	return FORMATS.some((format) => format === value);
+}
+const USAGE = `Usage: workspace-conformance check [--cwd <directory>] [--check <name>]... [--list] [--settings] [--format <text|json|github>]
 
 Runs the conformance checks enabled in the 'conformance' section of exadev.config.ts (or exadev.conformance.config.ts).
 
@@ -3811,6 +4117,7 @@ Runs the conformance checks enabled in the 'conformance' section of exadev.confi
   --check <name>      Run only this check, which must be enabled. Repeatable.
   --list              Print the names of all checks and stop.
   --settings          Also run the enabled settings-* checks, which read the repository's settings through the GitHub API with the token in GITHUB_TOKEN or GH_TOKEN. Offline otherwise.
+  --format <format>   text (the default): violations on standard error, notes on standard output. json: the result as one JSON document on standard output. github: a GitHub Actions error annotation per violation on standard output.
   --help, -h          Show this message.
 
 Exit status: ${String(EXIT_CODES.clean)} when nothing is found, ${String(EXIT_CODES.violations)} when a check finds a violation, ${String(EXIT_CODES.failed)} when the checks could not run.
@@ -3821,6 +4128,46 @@ function messageOf(error) {
 function formatViolation(violation) {
 	return `${violation.location === void 0 ? violation.file : `${violation.file}:${String(violation.location.line)}:${String(violation.location.column)}`}: ${violation.code}: ${violation.message}\n`;
 }
+/**
+* A workflow command property value with the characters the runner reserves percent-encoded, as `escapeProperty` of `@actions/core` encodes them.
+*/
+function escapeProperty(value) {
+	return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A").replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+/**
+* A workflow command message with the characters the runner reserves percent-encoded, as `escapeData` of `@actions/core` encodes them.
+*/
+function escapeData(value) {
+	return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+/**
+* The GitHub Actions `error` workflow command for a violation at `file` (relative to the directory the job runs in, which is how the runner places an annotation), with the violation's code as its title and its position when it has one.
+*/
+function githubAnnotation(violation, file) {
+	const position = violation.location === void 0 ? "" : `,line=${String(violation.location.line)},col=${String(violation.location.column)}`;
+	return `::error file=${escapeProperty(file)}${position},title=${escapeProperty(violation.code)}::${escapeData(violation.message)}\n`;
+}
+function formatOf(value) {
+	if (value === void 0) return "text";
+	if (!isFormat(value)) throw new TypeError(`unknown format '${value}'; the formats are ${FORMATS.join(", ")}`);
+	return value;
+}
+function summaryOf(result) {
+	return `no violations from ${result.results.map((entry) => entry.check).join(", ")}\n`;
+}
+/**
+* Print `result` in `format`. A violation's file is relative to `cwd`; an annotation needs it relative to the directory the command runs in.
+*/
+function printResult(result, format, cwd, output) {
+	if (format === "json") {
+		output.stdout(`${JSON.stringify(result, void 0, 2)}\n`);
+		return;
+	}
+	for (const entry of result.results) for (const note of entry.notes) output.stdout(format === "github" ? `::notice title=${escapeProperty(entry.check)}::${escapeData(note)}\n` : `${entry.check}: ${note}\n`);
+	for (const violation of result.violations) if (format === "github") output.stdout(githubAnnotation(violation, relativePosix(process.cwd(), resolve(cwd, violation.file))));
+	else output.stderr(formatViolation(violation));
+	if (result.violations.length === 0) output.stdout(summaryOf(result));
+}
 function requestedChecks(names) {
 	return names.map((name) => {
 		if (!isCheckName(name)) throw new TypeError(`unknown check '${name}'; the checks are ${checkNames.join(", ")}`);
@@ -3846,6 +4193,7 @@ async function runCheck(args, output) {
 			},
 			list: { type: "boolean" },
 			settings: { type: "boolean" },
+			format: { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -3862,13 +4210,14 @@ async function runCheck(args, output) {
 		for (const name of checkNames) output.stdout(`${name}\t${registry[name].description}\n`);
 		return EXIT_CODES.clean;
 	}
+	const format = formatOf(values.format);
+	const cwd = values.cwd ?? process.cwd();
 	const result = await runChecks({
-		cwd: resolve(values.cwd ?? process.cwd()),
+		cwd,
 		...requested === void 0 ? {} : { checks: requested },
 		...values.settings === true ? { github: clientFromEnvironment() } : {}
 	});
-	for (const violation of result.violations) output.stderr(formatViolation(violation));
-	if (result.violations.length === 0) output.stdout(`no violations from ${result.results.map((entry) => entry.check).join(", ")}\n`);
+	printResult(result, format, cwd, output);
 	return result.exitCode;
 }
 /**