workspace-conformance 1.7.0 → 2.0.0

package/dist/cli.js

@@ -26,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()),
@@ -41,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";
 /**
@@ -53,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 {
@@ -77,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;
 			}
@@ -95,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.
@@ -146,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;
 /**
@@ -853,8 +893,18 @@ const dockerfilePackageManager = async ({ cwd, options }) => {
 	}
 	return violations;
 };
-//#endregion
-//#region src/workspace/packages.ts
+/**
+* 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 !== ".");
 }
@@ -903,7 +953,7 @@ function sliceByNamePrefix(name, known) {
 /**
 * 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.
+* 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) => {
@@ -931,7 +981,7 @@ function classifyPackages(discovered, layout) {
 		};
 	});
 	for (const outer of packages) {
-		const nested = packages.find((inner) => inner.dir !== outer.dir && inner.dir.startsWith(`${outer.dir}/`));
+		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;
@@ -980,7 +1030,7 @@ async function readName(manifest) {
 	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.
+* 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`);
@@ -989,18 +1039,24 @@ async function discoverPackages(root, patterns) {
 		dot: true,
 		ignore: [INSTALLED_DEPENDENCIES_GLOB],
 		onlyFiles: true
-	})).map((manifest) => manifest.replace(/\/?package\.json$/u, "")).filter((dir) => dir !== "");
+	})).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.
+* 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);
-	return classifyPackages(await discoverPackages(root, await workspacePatterns(root, layout)), 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
@@ -1235,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 = [
@@ -1245,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`,
@@ -1657,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
@@ -1701,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
@@ -2492,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.
@@ -2654,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;
 }
@@ -2797,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
@@ -3072,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`;
+}
 /**
-* 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.
+* 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 lintViolations(cwd, eslint, patterns) {
+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. 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, note) {
 	const violations = [];
 	const results = /* @__PURE__ */ new Map();
 	for (const pattern of patterns) try {
@@ -3119,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);
 }
 /**
@@ -3128,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) }
@@ -3136,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
@@ -3173,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;
@@ -3181,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
@@ -3201,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
@@ -3442,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 }
 			});
 		}
@@ -3460,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`);
@@ -3468,6 +3588,7 @@ function online(spec) {
 				cwd,
 				options,
 				github,
+				note,
 				...configFiles === void 0 ? {} : { configFiles }
 			});
 		}
@@ -3878,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`);
@@ -3888,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));
@@ -3938,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));
@@ -3946,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);
@@ -3967,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).
 
@@ -3975,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.
@@ -3985,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(", ")}`);
@@ -4010,6 +4193,7 @@ async function runCheck(args, output) {
 			},
 			list: { type: "boolean" },
 			settings: { type: "boolean" },
+			format: { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -4026,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;
 }
 /**