workspace-conformance 1.7.0 → 2.0.1

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.
@@ -910,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;
   /**
@@ -938,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
@@ -960,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;
 /**
@@ -1048,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
@@ -1064,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>;
@@ -1072,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.
  */
@@ -1082,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>;
@@ -1202,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.
@@ -1223,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.
@@ -1289,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;
   /**
@@ -1319,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.
@@ -1342,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
 /**

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.
@@ -910,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;
   /**
@@ -938,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
@@ -960,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;
 /**
@@ -1048,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
@@ -1064,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>;
@@ -1072,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.
  */
@@ -1082,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>;
@@ -1202,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.
@@ -1223,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.
@@ -1289,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;
   /**
@@ -1319,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.
@@ -1342,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
 /**