workspace-conformance 3.0.0 → 4.0.1

package/README.md

@@ -1,6 +1,6 @@
 # workspace-conformance
 
-Conformance checks for a pnpm workspace that ESLint cannot express. Type-graph checks run on [ts-morph](https://ts-morph.com), import-graph checks run on [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) with rules generated from the shared `layout` section of [`@exadev/config`](https://github.com/ExaDev/config), file-tree and cross-config checks compare two files or read git state, workflow checks read GitHub Actions files, and settings checks read the repository's settings through the GitHub API. Each check reports violations with a stable code, a message, a file and, where it has one, a position.
+Conformance checks for a pnpm workspace that ESLint cannot express. Type-graph checks run on [ts-morph](https://ts-morph.com), import-graph checks run on [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) with rules generated from the shared `layout` section of [`@exadev/config`](https://github.com/ExaDev/config), file-tree and cross-config checks compare two files or read git state, workflow checks read GitHub Actions files, and settings checks read the repository's settings through the GitHub API. Each check reports violations with a stable code, a message and what the violation is about: a file and, where it has one, a position, or for the settings checks the repository.
 
 It complements the workspace architecture rules of [`@exadev/eslint-config`](https://github.com/ExaDev/eslint-config), it does not replace them. Those rules run in the editor and check what `package.json` files declare (`no-uphill-dependency` and `no-dependency-cycle`), incrementally and one file at a time. This tool checks what the code does: the import statements that actually cross packages, whether written as a package name, a relative path or a path alias, and everything that needs two files, the type checker or git. Both read the same `layout` section, so one description of the workspace drives both. Naming (`package-name-mirrors-path`) and per-file lint stay in ESLint.
 
@@ -257,7 +257,7 @@ What zizmor already covers, and what this check adds, as observed with zizmor 1.
 
 **`workflow-update-bot-cooldown`** takes `dependabot` (`.github/dependabot.yml`, else `.yaml`) and `renovate` (`renovate.json`, `.renovaterc.json`, `.renovaterc` and `.github/renovate.json`, the first that exists). Every Dependabot `updates` entry needs a `cooldown` with `default-days` or one of the `semver-*-days` above zero. Renovate needs `minimumReleaseAge` at the top level or in a `packageRules` entry, as a duration above zero (`0 days` and `null` wait for nothing). Limits: Dependabot's cooldown does not apply to security updates; a Renovate preset is not resolved (an `extends` entry counts only when its name contains `minimumReleaseAge`); a Renovate config is read as JSON with comments and trailing commas, so other JSON5 syntax and a `renovate` key in `package.json` are not read. A repository with neither bot has nothing to report; a file named in the options that does not exist fails the run.
 
-**`workflow-merge-group`** reports a workflow with a `pull_request` trigger and no `merge_group` trigger: GitHub starts no run of it for a queued pull request, so its required checks never report. Whether the branch has a merge queue at all is a repository setting. When the run is given a GitHub client (`runChecks({ github })`, `--settings`), the check reads the rules of the branch, as the `settings-*` checks do and with the same `repository` and `branch` options, once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies; without a queue no `merge_group` event is sent, so the trigger is not needed. Offline it cannot tell, and it reports every such workflow, as it always has. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too; narrow it with `workflows` and `exclude`. `pull_request_target` is left out, since it is not a place for required checks, and a workflow with no `pull_request` trigger is not judged. Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger, and the `branches` filter of a `merge_group` trigger is not read ([workflow syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)); with a client only rulesets are read, so a merge queue configured through classic branch protection is not seen and nothing is reported.
+**`workflow-merge-group`** reports a workflow with a `pull_request` trigger and no `merge_group` trigger: GitHub starts no run of it for a queued pull request, so its required checks never report. Whether the branch has a merge queue at all is a repository setting. When the run is given a GitHub client (`runChecks({ github })`, `--settings`), the check reads the rules of the branch, as the `settings-*` checks do and with the same `repository` and `branch` options, once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies; without a queue no `merge_group` event is sent, so the trigger is not needed. Offline it cannot tell, and it reports every such workflow, as it always has. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too; narrow it with `workflows` and `exclude`. `pull_request_target` is left out, since it is not a place for required checks, and a workflow with no `pull_request` trigger is not judged. Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger, and the `branches` filter of a `merge_group` trigger is not read ([workflow syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)); with a client only rulesets are read, so a merge queue configured through classic branch protection is not seen and nothing is reported. When GitHub refuses the rules because the plan of the repository has no rulesets (the refusal the `settings-*` checks report as `rules-unavailable`, and `RulesetsUnavailableError` from a client of your own), nothing is reported either, since the repository cannot have a merge queue: GitHub offers merge queues only in public repositories owned by an organisation and in private ones of organisations on GitHub Enterprise Cloud, which have rulesets ([managing a merge queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue), [archived](https://web.archive.org/web/20261002170053/https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)); any other refusal fails the run.
 
 **`workflow-action-pinning`** encodes a pinning policy, and does not choose a side silently: pinning to a commit SHA protects against a moved tag or branch, and a ref lets the owner of a shared workflow roll out a fix without every caller changing. The default follows the reasoning that you do not control a third party but do control your own organisation: an action or reusable workflow from outside `organisations` must be pinned by full 40-character commit SHA (`thirdParty: 'sha'`), a Docker image by digest, and one owned by a listed organisation may use any ref (`sameOrganisation: 'ref'`). With no `organisations` configured, nothing is relaxed. `thirdParty` and `sameOrganisation` each take `sha` or `ref`, so either side of the policy can be flipped, `organisations` lists the owners that count as the same organisation, and `allow` exempts `owner/repository` or `owner/*` (for example `actions/*`). Local actions and workflows (`./...`) are not judged. Limits: it checks the form of the ref, not that the SHA belongs to the repository or to a release; composite actions are not read.
 
@@ -269,7 +269,7 @@ What zizmor already covers, and what this check adds, as observed with zizmor 1.
 
 ### Repository settings
 
-The `settings-*` checks read repository settings through the GitHub API, so they need a token and are kept apart from the file checks. They run only when the run is given a GitHub client: `runChecks({ github })` in the library, `--settings` on the command line (which reads the token from `GITHUB_TOKEN` or `GH_TOKEN`). Without one they are left out, even when enabled, so the same configuration runs offline; naming one with `--check` or `checks` without a client, or enabling only settings checks and running offline, fails the run instead of reporting a pass. The client is an interface (`GitHubClient`, with `repository` and `branchRules`, whose `BranchRules` result also says whether a `required_linear_history` and a `merge_queue` rule apply); `workflow-merge-group` reads it too when it is given, and runs without it; `createGitHubClient({ token })` is the implementation over the REST API (GitHub reports the merge-method settings only to a token with write access to the repository, so `repository` fails with a `ConformanceError` for a read-only token), and a test or another host can supply its own. A violation's `file` is the repository, `owner/name`.
+The `settings-*` checks read repository settings through the GitHub API, so they need a token and are kept apart from the file checks. They run only when the run is given a GitHub client: `runChecks({ github })` in the library, `--settings` on the command line (which reads the token from `GITHUB_TOKEN` or `GH_TOKEN`). Without one they are left out, even when enabled, so the same configuration runs offline; naming one with `--check` or `checks` without a client, or enabling only settings checks and running offline, fails the run instead of reporting a pass. The client is an interface (`GitHubClient`, with `repository` and `branchRules`, whose `BranchRules` result also says whether a `required_linear_history` and a `merge_queue` rule apply); `workflow-merge-group` reads it too when it is given, and runs without it; `createGitHubClient({ token })` is the implementation over the REST API (GitHub reports the merge-method settings only to a token with write access to the repository, so `repository` fails with a `ConformanceError` for a read-only token), and a test or another host can supply its own. A settings violation is about the repository, not a file in it, so it has `repository` (`owner/name`) in place of `file` and no `location`.
 
 All three take `repository` (`owner/name`; the `origin` remote of the working directory, as configured before any `insteadOf` rewriting, when omitted) and `branch` (the repository's default branch). Rules are the effective rules of the branch from `GET /repos/{owner}/{repo}/rules/branches/{branch}` ([docs](https://docs.github.com/en/rest/repos/rules), [archived](https://web.archive.org/web/20260924024404/https://docs.github.com/en/rest/repos/rules)), which covers rulesets and not classic branch protection.
 
@@ -293,9 +293,9 @@ workspace-conformance check [--cwd <directory>] [--check <name>]... [--list] [--
 
 | Format | Output |
 |---|---|
-| `text` | The default. Violations on standard error as `file:line:column: code: message` (`file: code: message` for one without a position), a check's notes on standard output as `check: note`, and on a clean run a line naming the checks that ran. |
-| `json` | One JSON document on standard output: the `RunResult` of `runChecks`, so `results` (each `{ check, violations, notes }`), `violations` (the library's `{ code, message, file, location? }` objects, with `file` relative to `--cwd`) and `exitCode`. |
-| `github` | A GitHub Actions error annotation per violation on standard output, `::error file=<file>,line=<line>,col=<column>,title=<code>::<message>` (no `line` and `col` without a position), and a `::notice` per note. The runner turns each into an annotation on the file ([workflow commands](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-error-message), [archived](https://web.archive.org/web/20260918001346/https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands)). `file` is relative to the directory the command runs in, the repository root in a workflow step unless it sets `working-directory`, so `--cwd` may name a subdirectory. Reserved characters are percent-encoded as `@actions/core` encodes them (`%`, carriage return and line feed everywhere, and `:` and `,` in properties; [`command.ts`](https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts), [archived](https://web.archive.org/web/20250901085906/https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts)). A settings violation names the repository rather than a file, so its annotation is attached to no file. |
+| `text` | The default. Violations on standard error as `file:line:column: code: message` (`file: code: message` for one without a position, `owner/name: code: message` for a settings violation), a check's notes on standard output as `check: note`, and on a clean run a line naming the checks that ran. |
+| `json` | One JSON document on standard output: the `RunResult` of `runChecks`, so `results` (each `{ check, violations, notes }`), `violations` (the library's `{ code, message, file, location? }` objects, with `file` relative to `--cwd`, and `{ code, message, repository }` for a settings violation) and `exitCode`. |
+| `github` | A GitHub Actions error annotation per violation on standard output, `::error file=<file>,line=<line>,col=<column>,title=<code>::<message>` (no `line` and `col` without a position), and a `::notice` per note. The runner turns each into an annotation on the file ([workflow commands](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-error-message), [archived](https://web.archive.org/web/20260918001346/https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands)). `file` is relative to the directory the command runs in, the repository root in a workflow step unless it sets `working-directory`, so `--cwd` may name a subdirectory. Reserved characters are percent-encoded as `@actions/core` encodes them (`%`, carriage return and line feed everywhere, and `:` and `,` in properties; [`command.ts`](https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts), [archived](https://web.archive.org/web/20250901085906/https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts)). A settings violation names the repository rather than a file, so its annotation has no `file` and is attached to no file: `::error title=<code>::<message>`. |
 
 When the checks cannot run (exit status 2), the reason is printed to standard error as text in every format.
 
@@ -328,7 +328,7 @@ it('conforms to the workspace layout', async () => {
 });
 ```
 
-Every check is also exported as a function taking `{ cwd, options }` (and `layout` for the import checks): `aggregateMappers`, `codecPairs`, `commandTypes`, `derivedTypes`, `importUphill`, `importRankSkip`, `importCrossSlice`, `importIsolatedGroups`, `importCycles`, `instructionSymlinks`, `singleStorybook`, `commitTypes`, `enginesFloor`, `dockerfilePackageManager`, `migrationsDirectory`, `eslint`, the workflow checks (`workflowJobOrdering`, `workflowSkippableJobs`, `workflowRunnerResolution`, `workflowVersionSingleSource`, `workflowCredentials`, `workflowReleaseJob`, `workflowRepositoryDispatch`, `workflowUpdateBotCooldown`, `workflowMergeGroup` and `workflowActionPinning`) and, taking `{ cwd, options, github }`, the settings checks (`settingsMergeMethods`, `settingsRequiredChecks` and `settingsReviewThreadResolution`); `workflowMergeGroup` takes `github` too, optionally. These take options and a layout as already validated and do not check them again; go through `runChecks` for validation. `parseWorkflow` and `loadWorkflows` expose the workflow model the workflow checks read. A check is a function that returns `Promise<readonly Violation[]>`, where a `Violation` is `{ code, message, file, location? }`.
+Every check is also exported as a function taking `{ cwd, options }` (and `layout` for the import checks): `aggregateMappers`, `codecPairs`, `commandTypes`, `derivedTypes`, `importUphill`, `importRankSkip`, `importCrossSlice`, `importIsolatedGroups`, `importCycles`, `instructionSymlinks`, `singleStorybook`, `commitTypes`, `enginesFloor`, `dockerfilePackageManager`, `migrationsDirectory`, `eslint`, the workflow checks (`workflowJobOrdering`, `workflowSkippableJobs`, `workflowRunnerResolution`, `workflowVersionSingleSource`, `workflowCredentials`, `workflowReleaseJob`, `workflowRepositoryDispatch`, `workflowUpdateBotCooldown`, `workflowMergeGroup` and `workflowActionPinning`) and, taking `{ cwd, options, github }`, the settings checks (`settingsMergeMethods`, `settingsRequiredChecks` and `settingsReviewThreadResolution`); `workflowMergeGroup` takes `github` too, optionally. These take options and a layout as already validated and do not check them again; go through `runChecks` for validation. `parseWorkflow` and `loadWorkflows` expose the workflow model the workflow checks read. A check is a function that returns `Promise<readonly Violation[]>`, where a `Violation` is either a `FileViolation`, `{ code, message, file, location? }`, or, from a settings check, a `RepositoryViolation`, `{ code, message, repository }`; exactly one of `file` and `repository` is present, so `violation.file === undefined` tells them apart.
 
 ### Proving a handler map is exhaustive
 
@@ -379,6 +379,8 @@ Each check has a fixture that violates it and one that does not, under `test/fix
 
 Every push to `main` runs semantic-release once the commitlint, lint, typecheck and package jobs pass. It derives the next version from the Conventional Commits since the last tag, publishes to npm through trusted publishing with provenance, creates the tag and the GitHub Release, and pushes a `chore(release)` commit that updates `CHANGELOG.md` and `package.json`. `main` is protected by a ruleset that requires the Required Checks status, a branch up to date with `main`, linear history, and forbids deletion and non-fast-forward pushes. Pull requests therefore reach `main` by rebase merge once checks pass, and the release commit and tag are pushed over SSH with the repository deploy key, which the ruleset lets bypass it (as it does organisation admins). The key exists on disk only for the release step.
 
+CI also lints the workflows themselves with [actionlint](https://github.com/rhysd/actionlint) (and the shellcheck it runs on every `run:` script) and [zizmor](https://docs.zizmor.sh), each at a pinned version and configured in `.github/actionlint.yaml` and `.github/zizmor.yml`; both are part of the Required Checks status.
+
 CI selects its runner with `ExaDev/runner-fallback-action` (self-hosted fleet first, Blacksmith as fallback). The release job stays on a GitHub-hosted runner because npm trusted publishing needs one, and publishes with provenance through OIDC, with no stored token. The repository deploy key (the `RELEASE_DEPLOY_KEY` secret) is a ruleset bypass actor, so it is written to disk by the step immediately before the release step, and only the release step's own environment carries `GIT_SSH_COMMAND` (absolute `/usr/bin/ssh`, no ssh config, a pinned GitHub host key, only the ssh protocol allowed); the key is deleted afterwards. The build and package checks run before the key exists and the release step sets `NPM_CONFIG_IGNORE_SCRIPTS`, so no dev dependency runs beside the key, the job's actions are pinned by commit SHA, and the checkout, the action setup and the dependency install run with no write-capable credential in git config. That limits what code from those steps can read; it is not a sandbox, since a process started earlier in the job still runs as the same user. `release.config.ts` sets an SSH `repositoryUrl`, so semantic-release pushes the release commit and tag over SSH. The default `GITHUB_TOKEN` cannot bypass a branch ruleset on `main`, and semantic-release falls back to pushing as it only when the SSH push fails, so the job dry-run pushes first and fails before publishing if the key does not authenticate, and refuses the https URL outright. Commits follow [Conventional Commits](https://www.conventionalcommits.org); semantic-release derives the version from them.
 
 `README.md`, `AGENTS.md` and `CLAUDE.md` are one file: the two instruction files are tracked symlinks to this one.

package/dist/cli.js

@@ -1323,9 +1323,9 @@ async function branchOf(github, slug, options) {
 	return options.branch ?? (await github.repository(slug)).defaultBranch;
 }
 /**
-* What a violation of a settings check names as its file.
+* The repository a violation of a settings check names, `owner/name`.
 */
-function repositoryFile(slug) {
+function repositoryName(slug) {
 	return `${slug.owner}/${slug.name}`;
 }
 /**
@@ -1343,8 +1343,8 @@ async function branchRulesOf(github, slug, options) {
 /**
 * 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})`;
+function rulesUnavailableMessage(repository, what, githubMessage) {
+	return `the branch rules of ${repository} cannot be read or enforced on its plan, so ${what} cannot be required (GitHub: ${githubMessage})`;
 }
 //#endregion
 //#region src/checks/settings-merge-methods.ts
@@ -1370,7 +1370,7 @@ const METHOD_NAMES = {
 */
 const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	const settings = await github.repository(slug);
 	const read = await branchRulesOf(github, slug, options);
 	const pullRequests = "unavailable" in read ? [] : read.rules.pullRequests;
@@ -1385,13 +1385,13 @@ const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const available = METHODS.filter((method) => repositoryAllows[method] && rulesAllow(method));
 	const violations = available.filter((method) => method !== wanted).map((method) => ({
 		code: "settings-merge-methods/method-enabled",
-		message: `${file} allows ${METHOD_NAMES[method]}; only ${METHOD_NAMES[wanted]} should be allowed`,
-		file
+		message: `${repository} allows ${METHOD_NAMES[method]}; only ${METHOD_NAMES[wanted]} should be allowed`,
+		repository
 	}));
 	if (!available.includes(wanted)) violations.push({
 		code: "settings-merge-methods/method-unavailable",
-		message: `${file} does not allow ${METHOD_NAMES[wanted]}`,
-		file
+		message: `${repository} does not allow ${METHOD_NAMES[wanted]}`,
+		repository
 	});
 	return violations;
 };
@@ -1789,12 +1789,12 @@ const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 */
 const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	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
+		message: rulesUnavailableMessage(repository, "a status check", read.unavailable),
+		repository
 	}];
 	const { rules } = read;
 	const junctions = (await loadWorkflows(cwd, options)).flatMap((workflow) => jobsNamed(workflow, options.junctionJobs ?? DEFAULT_JUNCTION_JOBS).map((job) => ({
@@ -1805,26 +1805,26 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	if (junctions.length === 0) violations.push({
 		code: "settings-required-checks/no-junction-job",
 		message: "no workflow has a junction job, so there is no check that reports for the whole workflow to require",
-		file
+		repository
 	});
 	if (rules.requiredStatusChecks.length === 0) {
 		violations.push({
 			code: "settings-required-checks/no-required-checks",
-			message: `no rule requires status checks on the branch of ${file}`,
-			file
+			message: `no rule requires status checks on the branch of ${repository}`,
+			repository
 		});
 		return violations;
 	}
 	const required = new Set(rules.requiredStatusChecks.flatMap((rule) => rule.contexts));
 	for (const { workflow, name } of junctions.filter((junction) => !required.has(junction.name))) violations.push({
 		code: "settings-required-checks/required-check-missing",
-		message: `${file} does not require the check '${name}' of ${workflow.file}`,
-		file
+		message: `${repository} does not require the check '${name}' of ${workflow.file}`,
+		repository
 	});
 	if (!rules.requiredStatusChecks.some((rule) => rule.strict)) violations.push({
 		code: "settings-required-checks/not-strict",
-		message: `${file} does not require branches to be up to date before merging`,
-		file
+		message: `${repository} does not require branches to be up to date before merging`,
+		repository
 	});
 	return violations;
 };
@@ -1840,16 +1840,16 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 const settingsReviewThreadResolution = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
 	const read = await branchRulesOf(github, slug, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	if ("unavailable" in read) return [{
 		code: "settings-review-thread-resolution/rules-unavailable",
-		message: rulesUnavailableMessage(file, "resolving review conversations", read.unavailable),
-		file
+		message: rulesUnavailableMessage(repository, "resolving review conversations", read.unavailable),
+		repository
 	}];
 	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
+		message: `no rule requires review conversations to be resolved before merging on the branch of ${repository}`,
+		repository
 	}];
 };
 //#endregion
@@ -2277,7 +2277,7 @@ const workflowJobOrdering = async ({ cwd, options }) => (await loadWorkflows(cwd
 *
 * A workflow is taken to produce required checks when it is triggered by `pull_request`; `pull_request_target` is left out, since it runs trusted code against untrusted input and is not a place for required checks. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too: narrow the check with `workflows` and `exclude`. A `merge_group` trigger on a workflow with no `pull_request` trigger is not judged.
 *
-* Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. Offline it cannot tell, so it reports every such workflow.
+* Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. A repository whose plan has no rulesets (the client rejects with `RulesetsUnavailableError`) has no merge queue either, since GitHub offers merge queues only in public repositories of an organisation and in private ones on GitHub Enterprise Cloud, both of which have rulesets, so nothing is reported for it; any other refusal fails the run. Offline it cannot tell, so it reports every such workflow.
 *
 * Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger; the `branches` filter of a `merge_group` trigger is not read; only rulesets are read, so a queue configured through classic branch protection is not seen and, with a client, nothing is reported for it.
 */
@@ -2287,8 +2287,8 @@ const workflowMergeGroup = async ({ cwd, options, github }) => {
 		return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 	});
 	if (violations.length === 0 || github === void 0) return violations;
-	const slug = await repositoryOf(cwd, options);
-	return (await github.branchRules(slug, await branchOf(github, slug, options))).mergeQueue ? violations : [];
+	const branch = await branchRulesOf(github, await repositoryOf(cwd, options), options);
+	return "rules" in branch && branch.rules.mergeQueue ? violations : [];
 };
 //#endregion
 //#region src/checks/workflow-release-job.ts
@@ -4376,8 +4376,15 @@ Exit status: ${String(EXIT_CODES.clean)} when nothing is found, ${String(EXIT_CO
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+/**
+* Where a violation is, as text: the repository a violation of the settings is about, else the file and, when the violation has one, its position.
+*/
+function placeOf(violation) {
+	if (violation.file === void 0) return violation.repository;
+	return violation.location === void 0 ? violation.file : `${violation.file}:${String(violation.location.line)}:${String(violation.location.column)}`;
+}
 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`;
+	return `${placeOf(violation)}: ${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.
@@ -4392,11 +4399,15 @@ 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.
+* The GitHub Actions `error` workflow command for a violation, with its code as the title. A violation about a file is placed at its `file`, which must be relative to the directory the job runs in (that is how the runner places an annotation), and at its position when it has one; a violation about the repository names no file, so its annotation is attached to none.
 */
-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 githubAnnotation(violation) {
+	const properties = [`title=${escapeProperty(violation.code)}`];
+	if (violation.file !== void 0) {
+		const position = violation.location === void 0 ? [] : [`line=${String(violation.location.line)}`, `col=${String(violation.location.column)}`];
+		properties.unshift(`file=${escapeProperty(violation.file)}`, ...position);
+	}
+	return `::error ${properties.join(",")}::${escapeData(violation.message)}\n`;
 }
 function formatOf(value) {
 	if (value === void 0) return "text";
@@ -4415,7 +4426,10 @@ function printResult(result, format, cwd, output) {
 		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))));
+	for (const violation of result.violations) if (format === "github") output.stdout(githubAnnotation(violation.file !== void 0 ? {
+		...violation,
+		file: relativePosix(process.cwd(), resolve(cwd, violation.file))
+	} : violation));
 	else output.stderr(formatViolation(violation));
 	if (result.violations.length === 0) output.stdout(summaryOf(result));
 }

package/dist/index.cjs

@@ -2320,9 +2320,9 @@ async function branchOf(github, slug, options) {
 	return options.branch ?? (await github.repository(slug)).defaultBranch;
 }
 /**
-* What a violation of a settings check names as its file.
+* The repository a violation of a settings check names, `owner/name`.
 */
-function repositoryFile(slug) {
+function repositoryName(slug) {
 	return `${slug.owner}/${slug.name}`;
 }
 /**
@@ -2340,8 +2340,8 @@ async function branchRulesOf(github, slug, options) {
 /**
 * 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})`;
+function rulesUnavailableMessage(repository, what, githubMessage) {
+	return `the branch rules of ${repository} cannot be read or enforced on its plan, so ${what} cannot be required (GitHub: ${githubMessage})`;
 }
 //#endregion
 //#region src/checks/settings-merge-methods.ts
@@ -2367,7 +2367,7 @@ const METHOD_NAMES = {
 */
 const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	const settings = await github.repository(slug);
 	const read = await branchRulesOf(github, slug, options);
 	const pullRequests = "unavailable" in read ? [] : read.rules.pullRequests;
@@ -2382,13 +2382,13 @@ const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const available = METHODS.filter((method) => repositoryAllows[method] && rulesAllow(method));
 	const violations = available.filter((method) => method !== wanted).map((method) => ({
 		code: "settings-merge-methods/method-enabled",
-		message: `${file} allows ${METHOD_NAMES[method]}; only ${METHOD_NAMES[wanted]} should be allowed`,
-		file
+		message: `${repository} allows ${METHOD_NAMES[method]}; only ${METHOD_NAMES[wanted]} should be allowed`,
+		repository
 	}));
 	if (!available.includes(wanted)) violations.push({
 		code: "settings-merge-methods/method-unavailable",
-		message: `${file} does not allow ${METHOD_NAMES[wanted]}`,
-		file
+		message: `${repository} does not allow ${METHOD_NAMES[wanted]}`,
+		repository
 	});
 	return violations;
 };
@@ -2786,12 +2786,12 @@ const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 */
 const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	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
+		message: rulesUnavailableMessage(repository, "a status check", read.unavailable),
+		repository
 	}];
 	const { rules } = read;
 	const junctions = (await loadWorkflows(cwd, options)).flatMap((workflow) => jobsNamed(workflow, options.junctionJobs ?? DEFAULT_JUNCTION_JOBS).map((job) => ({
@@ -2802,26 +2802,26 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	if (junctions.length === 0) violations.push({
 		code: "settings-required-checks/no-junction-job",
 		message: "no workflow has a junction job, so there is no check that reports for the whole workflow to require",
-		file
+		repository
 	});
 	if (rules.requiredStatusChecks.length === 0) {
 		violations.push({
 			code: "settings-required-checks/no-required-checks",
-			message: `no rule requires status checks on the branch of ${file}`,
-			file
+			message: `no rule requires status checks on the branch of ${repository}`,
+			repository
 		});
 		return violations;
 	}
 	const required = new Set(rules.requiredStatusChecks.flatMap((rule) => rule.contexts));
 	for (const { workflow, name } of junctions.filter((junction) => !required.has(junction.name))) violations.push({
 		code: "settings-required-checks/required-check-missing",
-		message: `${file} does not require the check '${name}' of ${workflow.file}`,
-		file
+		message: `${repository} does not require the check '${name}' of ${workflow.file}`,
+		repository
 	});
 	if (!rules.requiredStatusChecks.some((rule) => rule.strict)) violations.push({
 		code: "settings-required-checks/not-strict",
-		message: `${file} does not require branches to be up to date before merging`,
-		file
+		message: `${repository} does not require branches to be up to date before merging`,
+		repository
 	});
 	return violations;
 };
@@ -2837,16 +2837,16 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 const settingsReviewThreadResolution = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
 	const read = await branchRulesOf(github, slug, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	if ("unavailable" in read) return [{
 		code: "settings-review-thread-resolution/rules-unavailable",
-		message: rulesUnavailableMessage(file, "resolving review conversations", read.unavailable),
-		file
+		message: rulesUnavailableMessage(repository, "resolving review conversations", read.unavailable),
+		repository
 	}];
 	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
+		message: `no rule requires review conversations to be resolved before merging on the branch of ${repository}`,
+		repository
 	}];
 };
 //#endregion
@@ -3289,7 +3289,7 @@ const workflowJobOrdering = async ({ cwd, options }) => (await loadWorkflows(cwd
 *
 * A workflow is taken to produce required checks when it is triggered by `pull_request`; `pull_request_target` is left out, since it runs trusted code against untrusted input and is not a place for required checks. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too: narrow the check with `workflows` and `exclude`. A `merge_group` trigger on a workflow with no `pull_request` trigger is not judged.
 *
-* Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. Offline it cannot tell, so it reports every such workflow.
+* Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. A repository whose plan has no rulesets (the client rejects with `RulesetsUnavailableError`) has no merge queue either, since GitHub offers merge queues only in public repositories of an organisation and in private ones on GitHub Enterprise Cloud, both of which have rulesets, so nothing is reported for it; any other refusal fails the run. Offline it cannot tell, so it reports every such workflow.
 *
 * Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger; the `branches` filter of a `merge_group` trigger is not read; only rulesets are read, so a queue configured through classic branch protection is not seen and, with a client, nothing is reported for it.
 */
@@ -3299,8 +3299,8 @@ const workflowMergeGroup = async ({ cwd, options, github }) => {
 		return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 	});
 	if (violations.length === 0 || github === void 0) return violations;
-	const slug = await repositoryOf(cwd, options);
-	return (await github.branchRules(slug, await branchOf(github, slug, options))).mergeQueue ? violations : [];
+	const branch = await branchRulesOf(github, await repositoryOf(cwd, options), options);
+	return "rules" in branch && branch.rules.mergeQueue ? violations : [];
 };
 //#endregion
 //#region src/checks/workflow-release-job.ts

package/dist/index.d.cts

@@ -98,9 +98,9 @@ interface SourceLocation {
   readonly column: number;
 }
 /**
- * One way the workspace fails a check.
+ * A way the workspace fails a check that is about a file.
  */
-interface Violation {
+interface FileViolation {
   /**
    * Stable identifier of the rule that was broken, `<check name>/<reason>`. Callers may match on it; the message may change.
    */
@@ -111,7 +111,28 @@ interface Violation {
    */
   readonly file: string;
   readonly location?: SourceLocation;
+  readonly repository?: never;
 }
+/**
+ * A way the repository fails a check that reads its settings, which is about the repository and no file in it.
+ */
+interface RepositoryViolation {
+  /**
+   * Stable identifier of the rule that was broken, `<check name>/<reason>`. Callers may match on it; the message may change.
+   */
+  readonly code: string;
+  readonly message: string;
+  /**
+   * The repository the violation is about, `owner/name`.
+   */
+  readonly repository: string;
+  readonly file?: never;
+  readonly location?: never;
+}
+/**
+ * One way the workspace fails a check: about a file ({@link FileViolation}, with `file`) or about the repository's settings ({@link RepositoryViolation}, with `repository`). A violation has exactly one of the two, so `violation.file === undefined` tells them apart.
+ */
+type Violation = FileViolation | RepositoryViolation;
 /**
  * What every check receives.
  */
@@ -139,11 +160,11 @@ interface LayoutCheckContext<Options> extends CheckContext<Options> {
 /**
  * A check: reads the workspace and returns everything it finds wrong, in a stable order. It throws `ConformanceError` when it cannot run.
  */
-type CheckFunction<Options> = (context: CheckContext<Options>) => Promise<readonly Violation[]>;
+type CheckFunction<Options> = (context: CheckContext<Options>) => Promise<readonly FileViolation[]>;
 /**
  * A check that also needs the resolved workspace layout.
  */
-type LayoutCheckFunction<Options> = (context: LayoutCheckContext<Options>) => Promise<readonly Violation[]>;
+type LayoutCheckFunction<Options> = (context: LayoutCheckContext<Options>) => Promise<readonly FileViolation[]>;
 /**
  * What a check that reads repository settings through the GitHub API receives.
  */
@@ -151,9 +172,9 @@ interface GitHubCheckContext<Options> extends CheckContext<Options> {
   readonly github: GitHubClient;
 }
 /**
- * A check that reads repository settings through the GitHub API. Its violations name the repository (`owner/name`) as the file.
+ * A check that reads repository settings through the GitHub API. Its violations are about the repository, which they name as `owner/name`.
  */
-type GitHubCheckFunction<Options> = (context: GitHubCheckContext<Options>) => Promise<readonly Violation[]>;
+type GitHubCheckFunction<Options> = (context: GitHubCheckContext<Options>) => Promise<readonly RepositoryViolation[]>;
 /**
  * What a check that reads files, and the repository's settings too when it can, receives.
  */
@@ -166,7 +187,7 @@ interface SettingsAwareCheckContext<Options> extends CheckContext<Options> {
 /**
  * A check that reads files and refines its judgement with the repository's settings when the run is given a GitHub client. It runs offline too, unlike a {@link GitHubCheckFunction}.
  */
-type SettingsAwareCheckFunction<Options> = (context: SettingsAwareCheckContext<Options>) => Promise<readonly Violation[]>;
+type SettingsAwareCheckFunction<Options> = (context: SettingsAwareCheckContext<Options>) => Promise<readonly FileViolation[]>;
 //#endregion
 //#region src/migrations/adapters.d.ts
 /**
@@ -1058,7 +1079,7 @@ interface ImportCheckSpec {
   /**
    * The violations for the findings of this check's rules, in a stable order.
    */
-  readonly report: (findings: readonly IViolation[], scope: ImportScope) => readonly Violation[];
+  readonly report: (findings: readonly IViolation[], scope: ImportScope) => readonly FileViolation[];
 }
 //#endregion
 //#region src/checks/import-cross-slice.d.ts
@@ -1179,7 +1200,7 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  *
  * A workflow is taken to produce required checks when it is triggered by `pull_request`; `pull_request_target` is left out, since it runs trusted code against untrusted input and is not a place for required checks. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too: narrow the check with `workflows` and `exclude`. A `merge_group` trigger on a workflow with no `pull_request` trigger is not judged.
  *
- * Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. Offline it cannot tell, so it reports every such workflow.
+ * Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. A repository whose plan has no rulesets (the client rejects with `RulesetsUnavailableError`) has no merge queue either, since GitHub offers merge queues only in public repositories of an organisation and in private ones on GitHub Enterprise Cloud, both of which have rulesets, so nothing is reported for it; any other refusal fails the run. Offline it cannot tell, so it reports every such workflow.
  *
  * Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger; the `branches` filter of a `merge_group` trigger is not read; only rulesets are read, so a queue configured through classic branch protection is not seen and, with a client, nothing is reported for it.
  */
@@ -1469,4 +1490,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EnginesFloorOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsAwareCheckContext, SettingsAwareCheckFunction, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EnginesFloorOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, FileViolation, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RepositoryViolation, RunChecksOptions, RunResult, RunsOn, SettingsAwareCheckContext, SettingsAwareCheckFunction, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.d.ts

@@ -98,9 +98,9 @@ interface SourceLocation {
   readonly column: number;
 }
 /**
- * One way the workspace fails a check.
+ * A way the workspace fails a check that is about a file.
  */
-interface Violation {
+interface FileViolation {
   /**
    * Stable identifier of the rule that was broken, `<check name>/<reason>`. Callers may match on it; the message may change.
    */
@@ -111,7 +111,28 @@ interface Violation {
    */
   readonly file: string;
   readonly location?: SourceLocation;
+  readonly repository?: never;
 }
+/**
+ * A way the repository fails a check that reads its settings, which is about the repository and no file in it.
+ */
+interface RepositoryViolation {
+  /**
+   * Stable identifier of the rule that was broken, `<check name>/<reason>`. Callers may match on it; the message may change.
+   */
+  readonly code: string;
+  readonly message: string;
+  /**
+   * The repository the violation is about, `owner/name`.
+   */
+  readonly repository: string;
+  readonly file?: never;
+  readonly location?: never;
+}
+/**
+ * One way the workspace fails a check: about a file ({@link FileViolation}, with `file`) or about the repository's settings ({@link RepositoryViolation}, with `repository`). A violation has exactly one of the two, so `violation.file === undefined` tells them apart.
+ */
+type Violation = FileViolation | RepositoryViolation;
 /**
  * What every check receives.
  */
@@ -139,11 +160,11 @@ interface LayoutCheckContext<Options> extends CheckContext<Options> {
 /**
  * A check: reads the workspace and returns everything it finds wrong, in a stable order. It throws `ConformanceError` when it cannot run.
  */
-type CheckFunction<Options> = (context: CheckContext<Options>) => Promise<readonly Violation[]>;
+type CheckFunction<Options> = (context: CheckContext<Options>) => Promise<readonly FileViolation[]>;
 /**
  * A check that also needs the resolved workspace layout.
  */
-type LayoutCheckFunction<Options> = (context: LayoutCheckContext<Options>) => Promise<readonly Violation[]>;
+type LayoutCheckFunction<Options> = (context: LayoutCheckContext<Options>) => Promise<readonly FileViolation[]>;
 /**
  * What a check that reads repository settings through the GitHub API receives.
  */
@@ -151,9 +172,9 @@ interface GitHubCheckContext<Options> extends CheckContext<Options> {
   readonly github: GitHubClient;
 }
 /**
- * A check that reads repository settings through the GitHub API. Its violations name the repository (`owner/name`) as the file.
+ * A check that reads repository settings through the GitHub API. Its violations are about the repository, which they name as `owner/name`.
  */
-type GitHubCheckFunction<Options> = (context: GitHubCheckContext<Options>) => Promise<readonly Violation[]>;
+type GitHubCheckFunction<Options> = (context: GitHubCheckContext<Options>) => Promise<readonly RepositoryViolation[]>;
 /**
  * What a check that reads files, and the repository's settings too when it can, receives.
  */
@@ -166,7 +187,7 @@ interface SettingsAwareCheckContext<Options> extends CheckContext<Options> {
 /**
  * A check that reads files and refines its judgement with the repository's settings when the run is given a GitHub client. It runs offline too, unlike a {@link GitHubCheckFunction}.
  */
-type SettingsAwareCheckFunction<Options> = (context: SettingsAwareCheckContext<Options>) => Promise<readonly Violation[]>;
+type SettingsAwareCheckFunction<Options> = (context: SettingsAwareCheckContext<Options>) => Promise<readonly FileViolation[]>;
 //#endregion
 //#region src/migrations/adapters.d.ts
 /**
@@ -1058,7 +1079,7 @@ interface ImportCheckSpec {
   /**
    * The violations for the findings of this check's rules, in a stable order.
    */
-  readonly report: (findings: readonly IViolation[], scope: ImportScope) => readonly Violation[];
+  readonly report: (findings: readonly IViolation[], scope: ImportScope) => readonly FileViolation[];
 }
 //#endregion
 //#region src/checks/import-cross-slice.d.ts
@@ -1179,7 +1200,7 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  *
  * A workflow is taken to produce required checks when it is triggered by `pull_request`; `pull_request_target` is left out, since it runs trusted code against untrusted input and is not a place for required checks. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too: narrow the check with `workflows` and `exclude`. A `merge_group` trigger on a workflow with no `pull_request` trigger is not judged.
  *
- * Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. Offline it cannot tell, so it reports every such workflow.
+ * Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. A repository whose plan has no rulesets (the client rejects with `RulesetsUnavailableError`) has no merge queue either, since GitHub offers merge queues only in public repositories of an organisation and in private ones on GitHub Enterprise Cloud, both of which have rulesets, so nothing is reported for it; any other refusal fails the run. Offline it cannot tell, so it reports every such workflow.
  *
  * Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger; the `branches` filter of a `merge_group` trigger is not read; only rulesets are read, so a queue configured through classic branch protection is not seen and, with a client, nothing is reported for it.
  */
@@ -1469,4 +1490,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EnginesFloorOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsAwareCheckContext, SettingsAwareCheckFunction, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EnginesFloorOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, FileViolation, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RepositoryViolation, RunChecksOptions, RunResult, RunsOn, SettingsAwareCheckContext, SettingsAwareCheckFunction, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.js

@@ -2319,9 +2319,9 @@ async function branchOf(github, slug, options) {
 	return options.branch ?? (await github.repository(slug)).defaultBranch;
 }
 /**
-* What a violation of a settings check names as its file.
+* The repository a violation of a settings check names, `owner/name`.
 */
-function repositoryFile(slug) {
+function repositoryName(slug) {
 	return `${slug.owner}/${slug.name}`;
 }
 /**
@@ -2339,8 +2339,8 @@ async function branchRulesOf(github, slug, options) {
 /**
 * 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})`;
+function rulesUnavailableMessage(repository, what, githubMessage) {
+	return `the branch rules of ${repository} cannot be read or enforced on its plan, so ${what} cannot be required (GitHub: ${githubMessage})`;
 }
 //#endregion
 //#region src/checks/settings-merge-methods.ts
@@ -2366,7 +2366,7 @@ const METHOD_NAMES = {
 */
 const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	const settings = await github.repository(slug);
 	const read = await branchRulesOf(github, slug, options);
 	const pullRequests = "unavailable" in read ? [] : read.rules.pullRequests;
@@ -2381,13 +2381,13 @@ const settingsMergeMethods = async ({ cwd, options, github }) => {
 	const available = METHODS.filter((method) => repositoryAllows[method] && rulesAllow(method));
 	const violations = available.filter((method) => method !== wanted).map((method) => ({
 		code: "settings-merge-methods/method-enabled",
-		message: `${file} allows ${METHOD_NAMES[method]}; only ${METHOD_NAMES[wanted]} should be allowed`,
-		file
+		message: `${repository} allows ${METHOD_NAMES[method]}; only ${METHOD_NAMES[wanted]} should be allowed`,
+		repository
 	}));
 	if (!available.includes(wanted)) violations.push({
 		code: "settings-merge-methods/method-unavailable",
-		message: `${file} does not allow ${METHOD_NAMES[wanted]}`,
-		file
+		message: `${repository} does not allow ${METHOD_NAMES[wanted]}`,
+		repository
 	});
 	return violations;
 };
@@ -2785,12 +2785,12 @@ const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 */
 const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	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
+		message: rulesUnavailableMessage(repository, "a status check", read.unavailable),
+		repository
 	}];
 	const { rules } = read;
 	const junctions = (await loadWorkflows(cwd, options)).flatMap((workflow) => jobsNamed(workflow, options.junctionJobs ?? DEFAULT_JUNCTION_JOBS).map((job) => ({
@@ -2801,26 +2801,26 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 	if (junctions.length === 0) violations.push({
 		code: "settings-required-checks/no-junction-job",
 		message: "no workflow has a junction job, so there is no check that reports for the whole workflow to require",
-		file
+		repository
 	});
 	if (rules.requiredStatusChecks.length === 0) {
 		violations.push({
 			code: "settings-required-checks/no-required-checks",
-			message: `no rule requires status checks on the branch of ${file}`,
-			file
+			message: `no rule requires status checks on the branch of ${repository}`,
+			repository
 		});
 		return violations;
 	}
 	const required = new Set(rules.requiredStatusChecks.flatMap((rule) => rule.contexts));
 	for (const { workflow, name } of junctions.filter((junction) => !required.has(junction.name))) violations.push({
 		code: "settings-required-checks/required-check-missing",
-		message: `${file} does not require the check '${name}' of ${workflow.file}`,
-		file
+		message: `${repository} does not require the check '${name}' of ${workflow.file}`,
+		repository
 	});
 	if (!rules.requiredStatusChecks.some((rule) => rule.strict)) violations.push({
 		code: "settings-required-checks/not-strict",
-		message: `${file} does not require branches to be up to date before merging`,
-		file
+		message: `${repository} does not require branches to be up to date before merging`,
+		repository
 	});
 	return violations;
 };
@@ -2836,16 +2836,16 @@ const settingsRequiredChecks = async ({ cwd, options, github }) => {
 const settingsReviewThreadResolution = async ({ cwd, options, github }) => {
 	const slug = await repositoryOf(cwd, options);
 	const read = await branchRulesOf(github, slug, options);
-	const file = repositoryFile(slug);
+	const repository = repositoryName(slug);
 	if ("unavailable" in read) return [{
 		code: "settings-review-thread-resolution/rules-unavailable",
-		message: rulesUnavailableMessage(file, "resolving review conversations", read.unavailable),
-		file
+		message: rulesUnavailableMessage(repository, "resolving review conversations", read.unavailable),
+		repository
 	}];
 	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
+		message: `no rule requires review conversations to be resolved before merging on the branch of ${repository}`,
+		repository
 	}];
 };
 //#endregion
@@ -3288,7 +3288,7 @@ const workflowJobOrdering = async ({ cwd, options }) => (await loadWorkflows(cwd
 *
 * A workflow is taken to produce required checks when it is triggered by `pull_request`; `pull_request_target` is left out, since it runs trusted code against untrusted input and is not a place for required checks. The file cannot show which checks are required, so a `pull_request` workflow whose checks are not required is reported too: narrow the check with `workflows` and `exclude`. A `merge_group` trigger on a workflow with no `pull_request` trigger is not judged.
 *
-* Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. Offline it cannot tell, so it reports every such workflow.
+* Whether the branch has a merge queue is a setting, not something a file shows. Given a GitHub client, the check reads the rules of the branch (`branch`, else the default branch, of `repository`, else the `origin` remote) once it has found a workflow without the trigger, and reports only when a `merge_queue` rule applies, since without a queue no `merge_group` event is ever sent. A repository whose plan has no rulesets (the client rejects with `RulesetsUnavailableError`) has no merge queue either, since GitHub offers merge queues only in public repositories of an organisation and in private ones on GitHub Enterprise Cloud, both of which have rulesets, so nothing is reported for it; any other refusal fails the run. Offline it cannot tell, so it reports every such workflow.
 *
 * Limits: a `merge_group` trigger takes only `branches` filters (`paths` is a filter of `push`, `pull_request` and `pull_request_target`), so a workflow path-filtered for pull requests still runs in the queue once it has the trigger; the `branches` filter of a `merge_group` trigger is not read; only rulesets are read, so a queue configured through classic branch protection is not seen and, with a client, nothing is reported for it.
 */
@@ -3298,8 +3298,8 @@ const workflowMergeGroup = async ({ cwd, options, github }) => {
 		return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 	});
 	if (violations.length === 0 || github === void 0) return violations;
-	const slug = await repositoryOf(cwd, options);
-	return (await github.branchRules(slug, await branchOf(github, slug, options))).mergeQueue ? violations : [];
+	const branch = await branchRulesOf(github, await repositoryOf(cwd, options), options);
+	return "rules" in branch && branch.rules.mergeQueue ? violations : [];
 };
 //#endregion
 //#region src/checks/workflow-release-job.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "workspace-conformance",
   "description": "Conformance checks for a pnpm workspace that ESLint cannot express: type-graph, import-graph and cross-file checks driven by the shared layout section of @exadev/config",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "bin": {
     "workspace-conformance": "./dist/cli.js"
   },