workspace-conformance 1.6.0 → 2.0.0

package/dist/index.d.cts

@@ -2,6 +2,14 @@ import { ConfigFileOptions, LayoutConfig, RankSkipOptions, Section } from "@exad
 import { IViolation } from "dependency-cruiser";
 import { z } from "zod";
 import { CompilerOptions } from "ts-morph";
+//#region src/errors.d.ts
+/**
+ * A problem with how the tool was used or configured rather than a finding about the workspace: an unknown or disabled check, a missing or invalid section, a layout that cannot be resolved, a repository that is not a git checkout. The command line reports it and exits 2.
+ */
+export declare class ConformanceError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+//#endregion
 //#region src/github.d.ts
 /**
  * A repository on GitHub.
@@ -39,7 +47,13 @@ interface BranchRules {
   }[];
 }
 /**
- * What the settings checks need from GitHub, so a test or another host can supply it without a network. The real implementation is {@link createGitHubClient}. Both methods reject when the repository or branch cannot be read.
+ * 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.
+ */
+export declare class RulesetsUnavailableError extends ConformanceError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * What the settings checks need from GitHub, so a test or another host can supply it without a network. The real implementation is {@link createGitHubClient}. Both methods reject when the repository or branch cannot be read, `branchRules` with {@link RulesetsUnavailableError} when the repository's plan has no rulesets.
  */
 interface GitHubClient {
   readonly repository: (slug: RepositorySlug) => Promise<RepositorySettings>;
@@ -95,14 +109,18 @@ interface Violation {
  */
 interface CheckContext<Options> {
   /**
-   * The directory the checks run in; every path option is relative to it.
+   * The directory the checks run in, absolute or relative to the working directory of the process; every path option is relative to it.
    */
   readonly cwd: string;
   readonly options: Options;
   /**
-   * How config files that a check evaluates itself (the commitlint and release configs of `commit-types`) are loaded. Only `alias` and `fsCache` apply to evaluating a file; `trust` and `merge` are for `extends`. No transpile cache is written when omitted.
+   * How config files that a check evaluates itself (the commitlint and release configs of `commit-types`) are loaded. Only `alias` and `fsCache` apply to evaluating a file; `trust` and the per-shape `unified` and `standalone` layer options are for `extends`. No transpile cache is written when omitted.
    */
   readonly configFiles?: ConfigFileOptions;
+  /**
+   * Receives what the check reports beside its violations: a line about what it did, such as how many files it linted, so a clean result can be told apart from one that looked at little. Nothing is reported when omitted.
+   */
+  readonly note?: (text: string) => void;
 }
 /**
  * What a check that reads the workspace layout receives.
@@ -524,6 +542,15 @@ interface CommitTypesOptions {
    */
   readonly release?: string;
 }
+/**
+ * Options of the `engines-floor` check: the `engines.node` range of a package is a subset of the `engines.node` range of each of its installed dependencies.
+ */
+interface EnginesFloorOptions {
+  /**
+   * Globs of the package directories to judge, in the form of the `packages` list of `pnpm-workspace.yaml` (a `!` pattern excludes), relative to the directory the checks run in; `.` is the root package. The root package and the `packages` of `pnpm-workspace.yaml`, when that file exists, when omitted.
+   */
+  readonly packages?: readonly string[];
+}
 /**
  * Options of the `dockerfile-package-manager` check: a package manager version pinned in a Dockerfile is the one `packageManager` names.
  */
@@ -790,6 +817,7 @@ interface CheckOptionsByName {
   readonly "instruction-symlinks": InstructionSymlinksOptions;
   readonly "single-storybook": SingleStorybookOptions;
   readonly "commit-types": CommitTypesOptions;
+  readonly "engines-floor": EnginesFloorOptions;
   readonly "dockerfile-package-manager": DockerfilePackageManagerOptions;
   readonly "migrations-directory": MigrationsDirectoryOptions;
   readonly eslint: EslintOptions;
@@ -872,6 +900,18 @@ export declare const derivedTypes: CheckFunction<DerivedTypesOptions>;
  */
 export declare const dockerfilePackageManager: CheckFunction<DockerfilePackageManagerOptions>;
 //#endregion
+//#region src/checks/engines-floor.d.ts
+/**
+ * The `engines.node` range of each package is a subset of the `engines.node` range of each dependency and optional dependency it lists, and of each peer dependency whose range admits a single version, as installed in `node_modules`, so the package admits no Node version that something it needs at run time rejects. A package that declares no range admits every version, so it is reported for each dependency that declares one. A dependency that declares no range constrains nothing and is ignored.
+ *
+ * The comparison is `semver.subset(package, dependency)`: every version the package's range admits satisfies the dependency's range. A floor alone is not enough, because a range of several lines (`^20.19.0 || ^22.13.0 || >=24`) also rejects the versions between them, which `>=20.19.0` admits. semver compares a range of several comparator sets set by set, so each set of the package's range must lie within one set of the dependency's; a set that only two adjacent dependency sets cover together (`>=22` against `^22.0.0 || >=23`) is reported, and splitting it the same way (`^22.0.0 || >=23`) satisfies the check.
+ *
+ * A peer dependency is judged only when its range admits a single version (`1.2.3` or `=1.2.3`), and then by the copy installed, which must be that version. The consumer chooses which admitted version to install, so the package's range holds when each Node version in it is accepted by some admitted version; one installed copy that rejects a Node version does not show that every admitted version does, and the others are not on disk.
+ *
+ * A dependency that is not installed fails the run: its range cannot be read, and passing it unjudged would read as a pass. An optional dependency and a peer dependency marked optional in `peerDependenciesMeta` may be absent and are then skipped.
+ */
+export declare const enginesFloor: CheckFunction<EnginesFloorOptions>;
+//#endregion
 //#region src/checks/eslint.d.ts
 /**
  * Proves the repository's own ESLint is applied, which no check that runs inside ESLint can notice: a config that dropped a shared preset, switched its rules off or narrowed `ignores` until nothing is linted still passes its own lint.
@@ -888,7 +928,7 @@ export declare const eslint: CheckFunction<EslintOptions>;
  */
 interface DiscoveredPackage {
   /**
-   * Relative to the workspace root, with `/` separators.
+   * Relative to the workspace root, with `/` separators; {@link ROOT_PACKAGE_DIR} for the package at the root.
    */
   readonly dir: string;
   /**
@@ -916,7 +956,7 @@ interface WorkspacePackage extends DiscoveredPackage {
 /**
  * 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.
  */
 export declare function classifyPackages(discovered: readonly DiscoveredPackage[], layout: LayoutConfig): readonly WorkspacePackage[];
 //#endregion
@@ -938,7 +978,7 @@ interface ImportRule {
   };
 }
 /**
- * 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}.
  */
 export declare function packagesPattern(packages: readonly WorkspacePackage[]): string;
 /**
@@ -1026,7 +1066,7 @@ export declare const importUphill: LayoutCheckFunction<ImportGraphOptions>;
 //#endregion
 //#region src/checks/instruction-symlinks.d.ts
 /**
- * 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.
  */
 export declare const instructionSymlinks: CheckFunction<InstructionSymlinksOptions>;
 //#endregion
@@ -1042,6 +1082,8 @@ export declare const migrationsDirectory: CheckFunction<MigrationsDirectoryOptio
 /**
  * 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.
  */
 export declare const settingsMergeMethods: GitHubCheckFunction<SettingsMergeMethodsOptions>;
@@ -1050,7 +1092,7 @@ export declare const settingsMergeMethods: GitHubCheckFunction<SettingsMergeMeth
 /**
  * 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.
  */
@@ -1060,6 +1102,8 @@ export declare const settingsRequiredChecks: GitHubCheckFunction<SettingsRequire
 /**
  * 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.
  */
 export declare const settingsReviewThreadResolution: GitHubCheckFunction<SettingsReviewThreadResolutionOptions>;
@@ -1180,14 +1224,6 @@ export declare const conformanceSchema: z.ZodType<ConformanceConfig, Conformance
  */
 export declare const conformanceSection: Section<"conformance", z.ZodType<ConformanceConfig, ConformanceConfig>>;
 //#endregion
-//#region src/errors.d.ts
-/**
- * A problem with how the tool was used or configured rather than a finding about the workspace: an unknown or disabled check, a missing or invalid section, a layout that cannot be resolved, a repository that is not a git checkout. The command line reports it and exits 2.
- */
-export declare class ConformanceError extends Error {
-  constructor(message: string, options?: ErrorOptions);
-}
-//#endregion
 //#region src/registry.d.ts
 /**
  * What a check needs to run once the configuration is loaded.
@@ -1201,6 +1237,10 @@ interface RunInput {
    * The client the settings checks read through; `undefined` when the run is offline.
    */
   readonly github: GitHubClient | undefined;
+  /**
+   * Receives the check's notes, what it reports beside its violations.
+   */
+  readonly note: (text: string) => void;
 }
 /**
  * What every registered check has, whichever way it runs.
@@ -1267,7 +1307,7 @@ export declare const EXIT_CODES: {
  */
 interface RunChecksOptions {
   /**
-   * The directory that holds the config files and that every path option is relative to.
+   * The directory that holds the config files and that every path option is relative to. A relative path is resolved against the working directory of the process, once, before any check runs.
    */
   readonly cwd: string;
   /**
@@ -1297,6 +1337,10 @@ interface RunChecksOptions {
 interface CheckResult {
   readonly check: CheckName;
   readonly violations: readonly Violation[];
+  /**
+   * What the check reported beside its violations, such as how many files it linted, in the order it reported them.
+   */
+  readonly notes: readonly string[];
 }
 /**
  * The outcome of running checks.
@@ -1320,7 +1364,7 @@ interface RunResult {
  *
  * 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.
  */
-export declare function runChecks(options: RunChecksOptions): Promise<RunResult>;
+export declare function runChecks(given: RunChecksOptions): Promise<RunResult>;
 //#endregion
 //#region src/type-level.d.ts
 /**
@@ -1386,4 +1430,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, 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, 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, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, 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

@@ -1,7 +1,15 @@
 import { CompilerOptions } from "ts-morph";
-import { ConfigFileOptions, LayoutConfig, RankSkipOptions, Section } from "@exadev/config";
 import { z } from "zod";
+import { ConfigFileOptions, LayoutConfig, RankSkipOptions, Section } from "@exadev/config";
 import { IViolation } from "dependency-cruiser";
+//#region src/errors.d.ts
+/**
+ * A problem with how the tool was used or configured rather than a finding about the workspace: an unknown or disabled check, a missing or invalid section, a layout that cannot be resolved, a repository that is not a git checkout. The command line reports it and exits 2.
+ */
+export declare class ConformanceError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+//#endregion
 //#region src/github.d.ts
 /**
  * A repository on GitHub.
@@ -39,7 +47,13 @@ interface BranchRules {
   }[];
 }
 /**
- * What the settings checks need from GitHub, so a test or another host can supply it without a network. The real implementation is {@link createGitHubClient}. Both methods reject when the repository or branch cannot be read.
+ * 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.
+ */
+export declare class RulesetsUnavailableError extends ConformanceError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * What the settings checks need from GitHub, so a test or another host can supply it without a network. The real implementation is {@link createGitHubClient}. Both methods reject when the repository or branch cannot be read, `branchRules` with {@link RulesetsUnavailableError} when the repository's plan has no rulesets.
  */
 interface GitHubClient {
   readonly repository: (slug: RepositorySlug) => Promise<RepositorySettings>;
@@ -95,14 +109,18 @@ interface Violation {
  */
 interface CheckContext<Options> {
   /**
-   * The directory the checks run in; every path option is relative to it.
+   * The directory the checks run in, absolute or relative to the working directory of the process; every path option is relative to it.
    */
   readonly cwd: string;
   readonly options: Options;
   /**
-   * How config files that a check evaluates itself (the commitlint and release configs of `commit-types`) are loaded. Only `alias` and `fsCache` apply to evaluating a file; `trust` and `merge` are for `extends`. No transpile cache is written when omitted.
+   * How config files that a check evaluates itself (the commitlint and release configs of `commit-types`) are loaded. Only `alias` and `fsCache` apply to evaluating a file; `trust` and the per-shape `unified` and `standalone` layer options are for `extends`. No transpile cache is written when omitted.
    */
   readonly configFiles?: ConfigFileOptions;
+  /**
+   * Receives what the check reports beside its violations: a line about what it did, such as how many files it linted, so a clean result can be told apart from one that looked at little. Nothing is reported when omitted.
+   */
+  readonly note?: (text: string) => void;
 }
 /**
  * What a check that reads the workspace layout receives.
@@ -524,6 +542,15 @@ interface CommitTypesOptions {
    */
   readonly release?: string;
 }
+/**
+ * Options of the `engines-floor` check: the `engines.node` range of a package is a subset of the `engines.node` range of each of its installed dependencies.
+ */
+interface EnginesFloorOptions {
+  /**
+   * Globs of the package directories to judge, in the form of the `packages` list of `pnpm-workspace.yaml` (a `!` pattern excludes), relative to the directory the checks run in; `.` is the root package. The root package and the `packages` of `pnpm-workspace.yaml`, when that file exists, when omitted.
+   */
+  readonly packages?: readonly string[];
+}
 /**
  * Options of the `dockerfile-package-manager` check: a package manager version pinned in a Dockerfile is the one `packageManager` names.
  */
@@ -790,6 +817,7 @@ interface CheckOptionsByName {
   readonly "instruction-symlinks": InstructionSymlinksOptions;
   readonly "single-storybook": SingleStorybookOptions;
   readonly "commit-types": CommitTypesOptions;
+  readonly "engines-floor": EnginesFloorOptions;
   readonly "dockerfile-package-manager": DockerfilePackageManagerOptions;
   readonly "migrations-directory": MigrationsDirectoryOptions;
   readonly eslint: EslintOptions;
@@ -872,6 +900,18 @@ export declare const derivedTypes: CheckFunction<DerivedTypesOptions>;
  */
 export declare const dockerfilePackageManager: CheckFunction<DockerfilePackageManagerOptions>;
 //#endregion
+//#region src/checks/engines-floor.d.ts
+/**
+ * The `engines.node` range of each package is a subset of the `engines.node` range of each dependency and optional dependency it lists, and of each peer dependency whose range admits a single version, as installed in `node_modules`, so the package admits no Node version that something it needs at run time rejects. A package that declares no range admits every version, so it is reported for each dependency that declares one. A dependency that declares no range constrains nothing and is ignored.
+ *
+ * The comparison is `semver.subset(package, dependency)`: every version the package's range admits satisfies the dependency's range. A floor alone is not enough, because a range of several lines (`^20.19.0 || ^22.13.0 || >=24`) also rejects the versions between them, which `>=20.19.0` admits. semver compares a range of several comparator sets set by set, so each set of the package's range must lie within one set of the dependency's; a set that only two adjacent dependency sets cover together (`>=22` against `^22.0.0 || >=23`) is reported, and splitting it the same way (`^22.0.0 || >=23`) satisfies the check.
+ *
+ * A peer dependency is judged only when its range admits a single version (`1.2.3` or `=1.2.3`), and then by the copy installed, which must be that version. The consumer chooses which admitted version to install, so the package's range holds when each Node version in it is accepted by some admitted version; one installed copy that rejects a Node version does not show that every admitted version does, and the others are not on disk.
+ *
+ * A dependency that is not installed fails the run: its range cannot be read, and passing it unjudged would read as a pass. An optional dependency and a peer dependency marked optional in `peerDependenciesMeta` may be absent and are then skipped.
+ */
+export declare const enginesFloor: CheckFunction<EnginesFloorOptions>;
+//#endregion
 //#region src/checks/eslint.d.ts
 /**
  * Proves the repository's own ESLint is applied, which no check that runs inside ESLint can notice: a config that dropped a shared preset, switched its rules off or narrowed `ignores` until nothing is linted still passes its own lint.
@@ -888,7 +928,7 @@ export declare const eslint: CheckFunction<EslintOptions>;
  */
 interface DiscoveredPackage {
   /**
-   * Relative to the workspace root, with `/` separators.
+   * Relative to the workspace root, with `/` separators; {@link ROOT_PACKAGE_DIR} for the package at the root.
    */
   readonly dir: string;
   /**
@@ -916,7 +956,7 @@ interface WorkspacePackage extends DiscoveredPackage {
 /**
  * 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.
  */
 export declare function classifyPackages(discovered: readonly DiscoveredPackage[], layout: LayoutConfig): readonly WorkspacePackage[];
 //#endregion
@@ -938,7 +978,7 @@ interface ImportRule {
   };
 }
 /**
- * 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}.
  */
 export declare function packagesPattern(packages: readonly WorkspacePackage[]): string;
 /**
@@ -1026,7 +1066,7 @@ export declare const importUphill: LayoutCheckFunction<ImportGraphOptions>;
 //#endregion
 //#region src/checks/instruction-symlinks.d.ts
 /**
- * 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.
  */
 export declare const instructionSymlinks: CheckFunction<InstructionSymlinksOptions>;
 //#endregion
@@ -1042,6 +1082,8 @@ export declare const migrationsDirectory: CheckFunction<MigrationsDirectoryOptio
 /**
  * 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.
  */
 export declare const settingsMergeMethods: GitHubCheckFunction<SettingsMergeMethodsOptions>;
@@ -1050,7 +1092,7 @@ export declare const settingsMergeMethods: GitHubCheckFunction<SettingsMergeMeth
 /**
  * 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.
  */
@@ -1060,6 +1102,8 @@ export declare const settingsRequiredChecks: GitHubCheckFunction<SettingsRequire
 /**
  * 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.
  */
 export declare const settingsReviewThreadResolution: GitHubCheckFunction<SettingsReviewThreadResolutionOptions>;
@@ -1180,14 +1224,6 @@ export declare const conformanceSchema: z.ZodType<ConformanceConfig, Conformance
  */
 export declare const conformanceSection: Section<"conformance", z.ZodType<ConformanceConfig, ConformanceConfig>>;
 //#endregion
-//#region src/errors.d.ts
-/**
- * A problem with how the tool was used or configured rather than a finding about the workspace: an unknown or disabled check, a missing or invalid section, a layout that cannot be resolved, a repository that is not a git checkout. The command line reports it and exits 2.
- */
-export declare class ConformanceError extends Error {
-  constructor(message: string, options?: ErrorOptions);
-}
-//#endregion
 //#region src/registry.d.ts
 /**
  * What a check needs to run once the configuration is loaded.
@@ -1201,6 +1237,10 @@ interface RunInput {
    * The client the settings checks read through; `undefined` when the run is offline.
    */
   readonly github: GitHubClient | undefined;
+  /**
+   * Receives the check's notes, what it reports beside its violations.
+   */
+  readonly note: (text: string) => void;
 }
 /**
  * What every registered check has, whichever way it runs.
@@ -1267,7 +1307,7 @@ export declare const EXIT_CODES: {
  */
 interface RunChecksOptions {
   /**
-   * The directory that holds the config files and that every path option is relative to.
+   * The directory that holds the config files and that every path option is relative to. A relative path is resolved against the working directory of the process, once, before any check runs.
    */
   readonly cwd: string;
   /**
@@ -1297,6 +1337,10 @@ interface RunChecksOptions {
 interface CheckResult {
   readonly check: CheckName;
   readonly violations: readonly Violation[];
+  /**
+   * What the check reported beside its violations, such as how many files it linted, in the order it reported them.
+   */
+  readonly notes: readonly string[];
 }
 /**
  * The outcome of running checks.
@@ -1320,7 +1364,7 @@ interface RunResult {
  *
  * 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.
  */
-export declare function runChecks(options: RunChecksOptions): Promise<RunResult>;
+export declare function runChecks(given: RunChecksOptions): Promise<RunResult>;
 //#endregion
 //#region src/type-level.d.ts
 /**
@@ -1386,4 +1430,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, 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, 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, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };