workspace-conformance 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,6 +1,72 @@
 import { CompilerOptions } from "ts-morph";
 import { ConfigFileOptions, LayoutConfig, RankSkipOptions, Section } from "@exadev/config";
 import { z } from "zod";
+import { IViolation } from "dependency-cruiser";
+//#region src/github.d.ts
+/**
+ * A repository on GitHub.
+ */
+interface RepositorySlug {
+  readonly owner: string;
+  readonly name: string;
+}
+/**
+ * The repository settings the settings checks read.
+ */
+interface RepositorySettings {
+  readonly defaultBranch: string;
+  readonly allowRebaseMerge: boolean;
+  readonly allowSquashMerge: boolean;
+  readonly allowMergeCommit: boolean;
+}
+/**
+ * The rules that apply to a branch, whichever ruleset they come from, reduced to what the settings checks read.
+ */
+interface BranchRules {
+  /**
+   * One entry per `required_status_checks` rule.
+   */
+  readonly requiredStatusChecks: readonly {
+    readonly contexts: readonly string[];
+    readonly strict: boolean;
+  }[];
+  /**
+   * One entry per `pull_request` rule. `allowedMergeMethods` is undefined when the rule does not restrict them.
+   */
+  readonly pullRequests: readonly {
+    readonly requiredReviewThreadResolution: boolean;
+    readonly allowedMergeMethods: readonly string[] | undefined;
+  }[];
+}
+/**
+ * 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.
+ */
+interface GitHubClient {
+  readonly repository: (slug: RepositorySlug) => Promise<RepositorySettings>;
+  readonly branchRules: (slug: RepositorySlug, branch: string) => Promise<BranchRules>;
+}
+/**
+ * Options of {@link createGitHubClient}.
+ */
+interface GitHubClientOptions {
+  /**
+   * A token that can read the repository's settings and rulesets. The API reports the merge-method settings only to a token with write access to the repository, so a token without it makes {@link GitHubClient.repository} reject.
+   */
+  readonly token: string;
+  /**
+   * The API root. `https://api.github.com` when omitted.
+   */
+  readonly apiUrl?: string;
+  /**
+   * The `fetch` to use. The global one when omitted.
+   */
+  readonly fetch?: typeof fetch;
+}
+/**
+ * A {@link GitHubClient} over the REST API.
+ */
+export declare function createGitHubClient(options: GitHubClientOptions): GitHubClient;
+//#endregion
 //#region src/check.d.ts
 /**
  * A position in a file, both numbers counted from 1.
@@ -52,6 +118,237 @@ type CheckFunction<Options> = (context: CheckContext<Options>) => Promise<readon
  * A check that also needs the resolved workspace layout.
  */
 type LayoutCheckFunction<Options> = (context: LayoutCheckContext<Options>) => Promise<readonly Violation[]>;
+/**
+ * What a check that reads repository settings through the GitHub API receives.
+ */
+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.
+ */
+type GitHubCheckFunction<Options> = (context: GitHubCheckContext<Options>) => Promise<readonly Violation[]>;
+//#endregion
+//#region src/migrations/adapters.d.ts
+/**
+ * Which of several things in a deploy tool's config the generator's output belongs to.
+ */
+interface DeploySelector {
+  /**
+   * The binding of the database, when the config declares more than one.
+   */
+  readonly database?: string;
+  /**
+   * The named environment whose settings apply instead of the top-level ones.
+   */
+  readonly environment?: string;
+}
+/**
+ * What a deploy tool's config says about the directory it applies migrations from.
+ */
+type DeployDirectory = {
+  readonly directory: string;
+  readonly none?: never;
+} | {
+  readonly none: string;
+  readonly directory?: never;
+};
+/**
+ * A schema generator, for the cross-check between where it writes migrations and where the deploy tool applies them from. The data of a config file is already read; an adapter only knows where in it the directory is.
+ */
+interface GeneratorAdapter {
+  /**
+   * The names the config file may have, by precedence. The extension decides how the file is read.
+   */
+  readonly configFiles: readonly [string, ...string[]];
+  /**
+   * Matches a shell command that applies migrations with the generator itself, bypassing the deploy tool.
+   */
+  readonly applyCommand: RegExp;
+  /**
+   * The command as it is written, for messages.
+   */
+  readonly applyCommandName: string;
+  /**
+   * The directory the generator writes migrations to, as the config writes it (relative to the config file's directory) or the generator's default when the config sets none. Throws `ConformanceError` when the config is not of a shape the adapter can read.
+   */
+  readonly outputDirectory: (config: unknown, file: string) => string;
+}
+/**
+ * A deploy tool that applies migrations from a directory.
+ */
+interface DeployToolAdapter {
+  /**
+   * The names the config file may have, by precedence. The extension decides how the file is read.
+   */
+  readonly configFiles: readonly [string, ...string[]];
+  /**
+   * The directory the tool applies migrations from, as the config writes it (relative to the config file's directory) or the tool's default when the config sets none. Throws `ConformanceError` when the config is not of a shape the adapter can read or `selector` is needed and absent.
+   */
+  readonly migrationsDirectory: (config: unknown, file: string, selector: DeploySelector) => DeployDirectory;
+}
+/**
+ * The generators that have an adapter.
+ */
+declare const generatorNames: readonly ["drizzle-kit"];
+/**
+ * The deploy tools that have an adapter.
+ */
+declare const deployToolNames: readonly ["wrangler"];
+type GeneratorName = (typeof generatorNames)[number];
+type DeployToolName = (typeof deployToolNames)[number];
+export declare const generators: Readonly<Record<GeneratorName, GeneratorAdapter>>;
+export declare const deployTools: Readonly<Record<DeployToolName, DeployToolAdapter>>;
+//#endregion
+//#region src/workflows/model.d.ts
+/**
+ * How much of a scope the `GITHUB_TOKEN` is granted.
+ */
+type PermissionAccess = "read" | "write" | "none";
+/**
+ * The `permissions` of a workflow or job as written. A scope missing from a `scopes` mapping is `none`, because GitHub sets every scope that is not specified to `none` as soon as any is specified. When nothing is declared the token gets the repository's default permissions, a setting the workflow file cannot show.
+ */
+type Permissions = {
+  readonly kind: "default";
+} | {
+  readonly kind: "all";
+  readonly access: "read" | "write";
+} | {
+  readonly kind: "scopes";
+  readonly scopes: ReadonlyMap<string, PermissionAccess>;
+};
+/**
+ * The access `permissions` grants to `scope`, or `undefined` when the permissions are not declared and the repository default applies.
+ */
+export declare function accessOf(permissions: Permissions, scope: string): PermissionAccess | undefined;
+/**
+ * What a job's `runs-on` names: literal labels, labels that are expressions, and a runner group.
+ */
+interface RunsOn {
+  readonly labels: readonly string[];
+  readonly expressions: readonly string[];
+  readonly group: string | undefined;
+}
+/**
+ * One step of a job. Every value is the text written in the file; expressions are not evaluated.
+ */
+interface Step {
+  readonly index: number;
+  readonly id: string | undefined;
+  readonly name: string | undefined;
+  readonly uses: string | undefined;
+  readonly run: string | undefined;
+  readonly with: Readonly<Record<string, string>>;
+  readonly env: Readonly<Record<string, string>>;
+  readonly condition: string | undefined;
+  readonly location: SourceLocation;
+}
+/**
+ * One job. A job that calls a reusable workflow has `uses` and no steps.
+ */
+interface Job {
+  readonly id: string;
+  readonly name: string | undefined;
+  /**
+   * The jobs named by `needs`, directly.
+   */
+  readonly needs: readonly string[];
+  readonly condition: string | undefined;
+  readonly permissions: Permissions;
+  readonly env: Readonly<Record<string, string>>;
+  readonly runsOn: RunsOn;
+  readonly timeoutMinutes: string | undefined;
+  readonly uses: string | undefined;
+  readonly with: Readonly<Record<string, string>>;
+  readonly outputs: Readonly<Record<string, string>>;
+  readonly steps: readonly Step[];
+  readonly location: SourceLocation;
+}
+/**
+ * A parsed workflow file.
+ */
+interface Workflow {
+  /**
+   * The path relative to the directory the checks run in, with `/` separators.
+   */
+  readonly file: string;
+  readonly name: string | undefined;
+  /**
+   * The events in `on`, each with its configuration (`undefined` for an event written without any).
+   */
+  readonly triggers: ReadonlyMap<string, unknown>;
+  /**
+   * Where each event of `triggers` is written.
+   */
+  readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
+  readonly permissions: Permissions;
+  readonly env: Readonly<Record<string, string>>;
+  readonly jobs: readonly Job[];
+  /**
+   * The `value` of each output a reusable workflow declares under `on.workflow_call.outputs`.
+   */
+  readonly callOutputs: Readonly<Record<string, string>>;
+}
+/**
+ * Parse the text of a workflow file into the model the checks read. It throws `ConformanceError` when the file is not YAML or is not shaped like a workflow, since a check cannot judge what it cannot read.
+ */
+export declare function parseWorkflow(file: string, source: string): Workflow;
+/**
+ * The permissions that apply to a job: its own when it declares any, else the workflow's. A job's declaration replaces the workflow's whole, it is not merged with it.
+ */
+export declare function effectivePermissions(workflow: Workflow, job: Job): Permissions;
+/**
+ * The environment a step runs with: the workflow's, the job's and the step's, the later winning.
+ */
+export declare function effectiveEnv(workflow: Workflow, job: Job, step: Step | undefined): Readonly<Record<string, string>>;
+/**
+ * Every job `jobId` waits for, directly or through other jobs, not including itself. A `needs` that names no job of the workflow is followed no further.
+ */
+export declare function transitiveNeeds(workflow: Workflow, jobId: string): ReadonlySet<string>;
+/**
+ * A `uses` value: a local action or workflow, a Docker image, or a repository reference.
+ */
+type UsesReference = {
+  readonly kind: "local";
+  readonly path: string;
+} | {
+  readonly kind: "docker";
+  readonly image: string;
+  readonly digest: string | undefined;
+} | {
+  readonly kind: "remote";
+  readonly owner: string;
+  readonly repository: string;
+  readonly path: string;
+  readonly ref: string | undefined;
+};
+/**
+ * Split a `uses` value into its parts.
+ */
+export declare function parseUses(uses: string): UsesReference;
+//#endregion
+//#region src/workflows/load.d.ts
+/**
+ * Which workflow files a check reads.
+ */
+interface WorkflowSelection {
+  /**
+   * Globs of the workflow files, relative to the directory the checks run in. `.github/workflows/*.yml` and `.github/workflows/*.yaml` when omitted.
+   */
+  readonly workflows?: readonly string[];
+  /**
+   * Globs of files that are left out.
+   */
+  readonly exclude?: readonly string[];
+}
+/**
+ * Where GitHub looks for workflows: only this directory, and only the files directly in it.
+ */
+export declare const DEFAULT_WORKFLOWS: readonly string[];
+/**
+ * Read and parse the selected workflow files, sorted by path.
+ */
+export declare function loadWorkflows(cwd: string, selection: WorkflowSelection): Promise<readonly Workflow[]>;
 //#endregion
 //#region src/options.d.ts
 /**
@@ -177,6 +474,188 @@ interface DockerfilePackageManagerOptions {
    */
   readonly packageJson?: string;
 }
+/**
+ * Options of the `migrations-directory` check: the directory a schema generator writes migrations to is the one the deploy tool applies them from, and no script applies them with the generator.
+ */
+interface MigrationsDirectoryOptions {
+  /**
+   * The schema generator, which has an adapter that knows its config file and where in it the output directory is.
+   */
+  readonly generator: GeneratorName;
+  /**
+   * The deploy tool, which has an adapter that knows its config file and where in it the migrations directory is.
+   */
+  readonly deployTool: DeployToolName;
+  /**
+   * The generator's config file, relative to the directory the checks run in. The first of the adapter's default file names that exists when omitted.
+   */
+  readonly generatorConfig?: string;
+  /**
+   * The deploy tool's config file. The first of the adapter's default file names that exists when omitted.
+   */
+  readonly deployConfig?: string;
+  /**
+   * The binding of the database the generator writes migrations for. Needed when the deploy config declares more than one; the only one is used when omitted.
+   */
+  readonly database?: string;
+  /**
+   * The named environment of the deploy config to read instead of its top-level settings.
+   */
+  readonly environment?: string;
+  /**
+   * Globs of the `package.json` files whose scripts are searched for the generator's apply command. Every `package.json` at any depth when omitted.
+   */
+  readonly packageJsons?: readonly string[];
+}
+/**
+ * Options of the `workflow-job-ordering` check: the jobs that release, deploy and report a required check are ordered so a failure stops what follows. Jobs are named by id; a role whose jobs are absent from a workflow is not judged there.
+ */
+interface WorkflowJobOrderingOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs, which must wait for every deploy job. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+  /**
+   * Ids of deploy jobs. `deploy` when omitted.
+   */
+  readonly deployJobs?: readonly string[];
+  /**
+   * Ids of jobs that deploy documentation, which must wait for every release job and check out the default branch afresh. `docs-deploy` when omitted.
+   */
+  readonly docsDeployJobs?: readonly string[];
+  /**
+   * Ids of junction jobs: the one job that reports a single required check for the whole workflow. `required-checks` when omitted.
+   */
+  readonly junctionJobs?: readonly string[];
+  /**
+   * Ids of jobs a junction job need not wait for, such as a release job that only runs after the junction's own checks or a job that runs on demand only.
+   */
+  readonly junctionExempt?: readonly string[];
+  /**
+   * The default branch a documentation job must check out when it names a branch literally. `main` when omitted. The `github.event.repository.default_branch` expression is always accepted.
+   */
+  readonly defaultBranch?: string;
+}
+/**
+ * Options of the `workflow-skippable-jobs` check: a path filter must not leave a required check pending or skip a job without a junction job to report for it.
+ */
+interface WorkflowSkippableJobsOptions extends WorkflowSelection {
+  /**
+   * Ids of junction jobs. `required-checks` when omitted.
+   */
+  readonly junctionJobs?: readonly string[];
+  /**
+   * The actions whose outputs say which paths changed, as `owner/repository`. `dorny/paths-filter`, `tj-actions/changed-files` and `step-security/changed-files` when omitted.
+   */
+  readonly pathFilterActions?: readonly string[];
+}
+/**
+ * Options of the `workflow-runner-resolution` check: a self-hosted or custom runner label is resolved once and read, not repeated.
+ */
+interface WorkflowRunnerResolutionOptions extends WorkflowSelection {
+  /**
+   * Regular expressions, as source text, for the labels GitHub hosts itself and that may be repeated freely. `ubuntu`, `windows` and `macos` images, `-latest`, versioned, `-arm`, `-intel`, `-xlarge`, `-large` and `-slim` forms, when omitted. Setting it replaces that default.
+   */
+  readonly hostedLabels?: readonly string[];
+}
+/**
+ * Options of the `workflow-version-single-source` check.
+ */
+type WorkflowVersionSingleSourceOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-credentials` check.
+ */
+type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
+ */
+interface WorkflowRepositoryDispatchOptions extends WorkflowSelection {
+  /**
+   * Branch names that count as the default branch when a push names one literally. `main` and `master` when omitted. The `github.event.repository.default_branch` expression always counts.
+   */
+  readonly defaultBranches?: readonly string[];
+  /**
+   * Set when the repository has a rule requiring status checks on the default branch, which is what makes `gh pr merge --auto` wait. The file cannot show it, so by default an auto merge in a handler is reported; the `settings-required-checks` check verifies the rule itself.
+   */
+  readonly assumeRequiredChecks?: boolean;
+}
+/**
+ * Options of the `workflow-update-bot-cooldown` check: the update bots wait before proposing a release.
+ */
+interface WorkflowUpdateBotCooldownOptions {
+  /**
+   * The Dependabot config, relative to the directory the checks run in. `.github/dependabot.yml`, else `.github/dependabot.yaml`, when omitted.
+   */
+  readonly dependabot?: string;
+  /**
+   * The Renovate config. `renovate.json`, `.renovaterc.json`, `.renovaterc` and `.github/renovate.json`, the first that exists, when omitted.
+   */
+  readonly renovate?: string;
+}
+/**
+ * Options of the `workflow-merge-group` check.
+ */
+type WorkflowMergeGroupOptions = WorkflowSelection;
+/**
+ * How strictly a reference must be pinned: to a full commit SHA, or any ref (tag, branch or SHA).
+ */
+type PinningLevel = "sha" | "ref";
+/**
+ * Options of the `workflow-action-pinning` check: the pinning policy for what workflows `uses`.
+ */
+interface WorkflowActionPinningOptions extends WorkflowSelection {
+  /**
+   * What an action or reusable workflow from outside `organisations` must be pinned to. `sha` when omitted.
+   */
+  readonly thirdParty?: PinningLevel;
+  /**
+   * What an action or reusable workflow owned by one of `organisations` must be pinned to. `ref` when omitted.
+   */
+  readonly sameOrganisation?: PinningLevel;
+  /**
+   * The owners (users or organisations) that count as the same organisation. None when omitted, so nothing is relaxed unless it is named.
+   */
+  readonly organisations?: readonly string[];
+  /**
+   * Repositories exempt from the policy, as `owner/repository` or `owner/*`.
+   */
+  readonly allow?: readonly string[];
+}
+/**
+ * What the settings checks need to find the repository.
+ */
+interface SettingsOptions {
+  /**
+   * The repository as `owner/name`. The `origin` remote of the working directory when omitted.
+   */
+  readonly repository?: string;
+  /**
+   * The branch whose rules are read. The repository's default branch when omitted.
+   */
+  readonly branch?: string;
+}
+/**
+ * Options of the `settings-merge-methods` check.
+ */
+interface SettingsMergeMethodsOptions extends SettingsOptions {
+  /**
+   * The only merge method the repository allows. `rebase` when omitted.
+   */
+  readonly allowed?: "rebase" | "squash" | "merge";
+}
+/**
+ * Options of the `settings-required-checks` check.
+ */
+interface SettingsRequiredChecksOptions extends SettingsOptions, WorkflowSelection {
+  /**
+   * Ids of the junction jobs whose check names must be required. `required-checks` when omitted.
+   */
+  readonly junctionJobs?: readonly string[];
+}
+/**
+ * Options of the `settings-review-thread-resolution` check.
+ */
+type SettingsReviewThreadResolutionOptions = SettingsOptions;
 /**
  * The options of every check, by check name.
  */
@@ -192,6 +671,19 @@ interface CheckOptionsByName {
   readonly "single-storybook": SingleStorybookOptions;
   readonly "commit-types": CommitTypesOptions;
   readonly "dockerfile-package-manager": DockerfilePackageManagerOptions;
+  readonly "migrations-directory": MigrationsDirectoryOptions;
+  readonly "workflow-job-ordering": WorkflowJobOrderingOptions;
+  readonly "workflow-skippable-jobs": WorkflowSkippableJobsOptions;
+  readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
+  readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
+  readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
+  readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
+  readonly "workflow-merge-group": WorkflowMergeGroupOptions;
+  readonly "workflow-action-pinning": WorkflowActionPinningOptions;
+  readonly "settings-merge-methods": SettingsMergeMethodsOptions;
+  readonly "settings-required-checks": SettingsRequiredChecksOptions;
+  readonly "settings-review-thread-resolution": SettingsReviewThreadResolutionOptions;
 }
 /**
  * The name of a check.
@@ -238,6 +730,116 @@ export declare const commitTypes: CheckFunction<CommitTypesOptions>;
  */
 export declare const dockerfilePackageManager: CheckFunction<DockerfilePackageManagerOptions>;
 //#endregion
+//#region src/workspace/packages.d.ts
+/**
+ * A package directory found under the workspace root, before the layout classifies it.
+ */
+interface DiscoveredPackage {
+  /**
+   * Relative to the workspace root, with `/` separators.
+   */
+  readonly dir: string;
+  /**
+   * The manifest's `name`; a manifest may omit it.
+   */
+  readonly name: string | undefined;
+}
+/**
+ * A workspace package as the layout sees it.
+ */
+interface WorkspacePackage extends DiscoveredPackage {
+  /**
+   * The name of the group whose root is the longest prefix of the package directory.
+   */
+  readonly group: string;
+  /**
+   * The rank from `nameRanks`, else the group's rank, else `defaultRank`; `undefined` when none of them applies.
+   */
+  readonly rank: number | undefined;
+  /**
+   * The slice the group's `slice` rule derives; `undefined` for a group without one and for a package that yields none.
+   */
+  readonly slice: string | undefined;
+}
+/**
+ * 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.
+ */
+export declare function classifyPackages(discovered: readonly DiscoveredPackage[], layout: LayoutConfig): readonly WorkspacePackage[];
+//#endregion
+//#region src/workspace/rules.d.ts
+/**
+ * A forbidden-dependency rule in the shape dependency-cruiser takes: a dependency from a file matching `from` to a file matching `to` is a violation.
+ */
+interface ImportRule {
+  readonly name: string;
+  readonly severity: "error";
+  readonly comment: string;
+  readonly from: {
+    readonly path?: string;
+  };
+  readonly to: {
+    readonly path?: string;
+    readonly circular?: boolean;
+    readonly couldNotResolve?: boolean;
+  };
+}
+/**
+ * A regular expression, as source text, matching every file inside any of the packages. The trailing `/` keeps `packages/a` from matching `packages/ab`.
+ */
+export declare function packagesPattern(packages: readonly WorkspacePackage[]): string;
+/**
+ * One rule per rank that has a higher rank above it: files of a package at that rank may not import a package at a strictly higher rank. A rule compares no numbers, so the ordering is expanded into path alternations here. Each rule comes with a `-by-name` rule for imports that do not resolve to a file.
+ */
+export declare function uphillRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
+/**
+ * One rule per rank with a package more than `rankSkip.maxDistance` ranks below it that is not an exempt rank.
+ */
+export declare function rankSkipRules(packages: readonly WorkspacePackage[], rankSkip: RankSkipOptions): readonly ImportRule[];
+/**
+ * One rule per slice: a package in it may not import a package that has a different slice. A package without a slice is in none and is never restricted.
+ */
+export declare function crossSliceRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
+/**
+ * Two rules per isolated pair, one for each direction.
+ */
+export declare function isolatedGroupRules(packages: readonly WorkspacePackage[], isolatedGroups: NonNullable<LayoutConfig["isolatedGroups"]>): readonly ImportRule[];
+/**
+ * The rule that forbids any import cycle among the packages' files.
+ */
+export declare function cycleRule(): ImportRule;
+//#endregion
+//#region src/checks/import-graph.d.ts
+/**
+ * What a check's report may need to know about the workspace the graph was cruised over.
+ */
+interface ImportScope {
+  readonly cwd: string;
+  /**
+   * The workspace root; finding paths are relative to it.
+   */
+  readonly root: string;
+  readonly packages: readonly WorkspacePackage[];
+}
+/**
+ * How an import check takes part in a shared cruise: the rules it adds and how it reads its own findings. Findings are routed to a check by the names of the rules it generated, so those names must differ from every other check's.
+ */
+interface ImportCheckSpec {
+  /**
+   * The check's name; the violation code is `<name>/<reason>`.
+   */
+  readonly name: string;
+  /**
+   * The forbidden rules for the workspace's packages. Throws `ConformanceError` when the layout does not configure what the check needs.
+   */
+  readonly rules: (packages: readonly WorkspacePackage[], layout: LayoutConfig) => readonly ImportRule[];
+  /**
+   * The violations for the findings of this check's rules, in a stable order.
+   */
+  readonly report: (findings: readonly IViolation[], scope: ImportScope) => readonly Violation[];
+}
+//#endregion
 //#region src/checks/import-cross-slice.d.ts
 /**
  * A package imports a package in a different slice.
@@ -276,12 +878,124 @@ export declare const importUphill: LayoutCheckFunction<ImportGraphOptions>;
  */
 export declare const instructionSymlinks: CheckFunction<InstructionSymlinksOptions>;
 //#endregion
+//#region src/checks/migrations-directory.d.ts
+/**
+ * The directory a schema generator writes migrations to is the one the deploy tool applies them from, and no script applies them with the generator instead of the deploy tool. The generator and the deploy tool are named in the options and each has an adapter that knows its config file names and where in them the directory is; both directories are resolved against the directory of the file that sets them.
+ *
+ * The config files are read as data: JSON, JSONC and TOML are parsed, and a module (a generator's TypeScript config) is evaluated, so it must be trusted.
+ */
+export declare const migrationsDirectory: CheckFunction<MigrationsDirectoryOptions>;
+//#endregion
+//#region src/checks/settings-merge-methods.d.ts
+/**
+ * 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.
+ *
+ * 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>;
+//#endregion
+//#region src/checks/settings-required-checks.d.ts
+/**
+ * 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`).
+ *
+ * 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.
+ */
+export declare const settingsRequiredChecks: GitHubCheckFunction<SettingsRequiredChecksOptions>;
+//#endregion
+//#region src/checks/settings-review-thread-resolution.d.ts
+/**
+ * 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`.
+ *
+ * Limits: it reads the rules of rulesets; classic branch protection is not read.
+ */
+export declare const settingsReviewThreadResolution: GitHubCheckFunction<SettingsReviewThreadResolutionOptions>;
+//#endregion
 //#region src/checks/single-storybook.d.ts
 /**
  * At most one Storybook exists, in the permitted directory (the workspace root unless the options say otherwise), and none in a package such as a UI package. A Storybook is a `.storybook` directory.
  */
 export declare const singleStorybook: CheckFunction<SingleStorybookOptions>;
 //#endregion
+//#region src/checks/workflow-action-pinning.d.ts
+/**
+ * Every `uses` of a step or job follows the pinning policy. By default an action or reusable workflow from outside the organisations in the options must be pinned by full commit SHA (a Docker image by digest), and one owned by an organisation listed in `organisations` may use any ref; `thirdParty` and `sameOrganisation` set either to `sha` or `ref`, and `allow` exempts repositories. Local actions and workflows (`./...`) are not judged.
+ *
+ * The check encodes whichever policy the options state and is never silent about it: with nothing configured every remote reference must be a SHA. Limits: it checks the form of the ref, not that the SHA belongs to the repository or to a release; a SHA written with a trailing version comment is read as the SHA; composite actions are not read.
+ */
+export declare const workflowActionPinning: CheckFunction<WorkflowActionPinningOptions>;
+//#endregion
+//#region src/checks/workflow-credentials.d.ts
+/**
+ * Credentials are granted to the steps that need them, and a publish with no token cannot quietly use one.
+ *
+ * `workflow-credentials/attestation-permissions`: a step of `actions/attest`, `actions/attest-build-provenance` or `actions/attest-sbom` needs `id-token: write` and `attestations: write` in the job's effective permissions. Permissions a job declares replace the workflow's; permissions declared nowhere are the repository's default, which the file cannot show and which never includes `id-token`, so they are reported.
+ *
+ * `workflow-credentials/tokenless-publish-unprotected`: a job with `id-token: write` that publishes (`npm`, `pnpm` or `yarn npm publish`, with options such as `-r` or `--filter <package>` before `publish`, `semantic-release`, `changeset publish`, `lerna publish`, bare or run through `pnpm`, `pnpm exec`, `yarn` or `npx`) and passes no token must blank `NODE_AUTH_TOKEN` and `NPM_TOKEN` (set them to `''` at step, job or workflow level) or request provenance (`--provenance`, `NPM_CONFIG_PROVENANCE: true`, or `publishConfig.provenance: true` in the `package.json` of the working directory). The npm CLI replaces any configured token with the one from the OIDC exchange, but when the exchange fails it falls back to whatever token the environment holds, silently. Only blanking the variables prevents that fallback. Provenance does not: npm signs it with the CI's own OIDC identity (through Sigstore), separately from the registry token, so a fallback publish still goes ahead with the inherited token and carries an attestation of where it was built. Requesting provenance is accepted because it makes such a publish traceable, not because it makes it safe.
+ *
+ * Limits: `registry-url` is not reported, because it does not stop the exchange (see the README); a job that calls a reusable workflow is not read; a publish inside a script file or composite action is not seen; provenance set in a `package.json` other than the one in the working directory is not read; a job is tokenless only when no token variable is non-empty anywhere in the job, so a publish that uses a secret is left alone.
+ */
+export declare const workflowCredentials: CheckFunction<WorkflowCredentialsOptions>;
+//#endregion
+//#region src/checks/workflow-job-ordering.d.ts
+/**
+ * The jobs that release, deploy and report a required check are ordered so that a failure stops what follows: a release job needs the deploy job, a documentation deploy job needs the release job and checks out the default branch afresh, and one junction job with `if: always()` needs every other job and fails only on `failure` or `cancelled`.
+ *
+ * Jobs are recognised by id (see the options), and a role with no job in a workflow is not judged there. Ordering is judged through the transitive `needs` graph; the junction job must list every job directly, because `needs.*.result` only covers direct needs, except jobs that never run for a pull request or a merge group (an `if` on `github.ref` or `github.event_name` that mentions neither `pull_request` nor `merge_group`, where an `&&` needs one such operand and an `||` needs every operand to be), jobs that need such a job or the junction job itself, and the ids in `junctionExempt`. What the junction job decides on is read as text: it must read the results of its needs (`needs.*.result`, `needs.<job>.result` or `toJSON(needs)`) and name both `'failure'` and `'cancelled'`, or use the `re-actors/alls-green` action; a result read in a way the text does not show is reported as incomplete.
+ */
+export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptions>;
+//#endregion
+//#region src/checks/workflow-merge-group.d.ts
+/**
+ * A workflow that checks pull requests also runs for the merge queue: GitHub starts no run of it for a queued pull request unless the workflow has a `merge_group` trigger, and a required check that never reports blocks the queue.
+ *
+ * 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. 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.
+ */
+export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
+//#endregion
+//#region src/checks/workflow-repository-dispatch.d.ts
+/**
+ * A workflow that handles `repository_dispatch` can be started by anyone with write access through the API, so what it does with the repository is held to a higher bar.
+ *
+ * `workflow-repository-dispatch/pushes-default-branch`: a `git push` to the default branch, or one with no refspec while the default branch is checked out, or `git-auto-commit-action` on it. `auto-merge-without-required-checks`: `gh pr merge --auto`, which merges at once when the base branch requires no checks (the file cannot show the rule; `assumeRequiredChecks` states it, and `settings-required-checks` verifies it). `default-token-triggers-nothing`: a push (the checkout leaves `GITHUB_TOKEN` in git config unless it is given a `token`, and a push to a URL carrying its own credentials does not use it) or a pull request opened as `GITHUB_TOKEN`; events created with it start no workflows, apart from `workflow_dispatch` and `repository_dispatch`, so the pushed commit gets no checks. `dispatch-other-repository-with-default-token`: a dispatch to a repository other than `github.repository` with `GITHUB_TOKEN`, whose access is limited to its own repository. Dispatching in the same repository with `GITHUB_TOKEN` is allowed by GitHub and is not reported.
+ *
+ * Limits: commands are read as text, so a script file or composite action is not seen; a push is judged by its command line, so a branch created by a helper is not seen, and a quoted word that contains a space is not read as one word; a dispatch target written literally as this repository's own name is reported, since the file does not know the name; a job that calls a reusable workflow is not read.
+ */
+export declare const workflowRepositoryDispatch: CheckFunction<WorkflowRepositoryDispatchOptions>;
+//#endregion
+//#region src/checks/workflow-runner-resolution.d.ts
+/**
+ * A self-hosted or custom runner label named literally in more than one job of a workflow is resolved once instead: a resolver job decides the runner and the others read it with `fromJson(needs.<resolver>.outputs.<name>)`. The resolver must have a `timeout-minutes` and its output a literal fallback that names only hosted runner labels, so jobs still get a runner when resolution fails or the self-hosted fleet is down.
+ *
+ * A label is custom when it matches none of `hostedLabels`; the default patterns recognise GitHub's standard images, so a larger runner is named by a custom label and counts. Labels are compared within a workflow file, not across files. A resolver that is a reusable workflow is followed when it is a file of this repository (the output is traced through `on.workflow_call.outputs` to the job that sets it); a resolver in another repository cannot be read and is not judged. An output is taken to have a fallback when its expression has `||` followed by a string literal, and the last such literal is read as JSON (a label or a list of labels) and matched against `hostedLabels`; a fallback that is not valid JSON, or names any other label, is reported.
+ */
+export declare const workflowRunnerResolution: CheckFunction<WorkflowRunnerResolutionOptions>;
+//#endregion
+//#region src/checks/workflow-skippable-jobs.d.ts
+/**
+ * Keeping work off a pull request must not leave a required check without a result. A `paths` or `paths-ignore` filter on the trigger of a workflow with a junction job skips the whole workflow, so the required check stays pending forever; a job whose own `if` reads a path filter's outputs is skipped, which is only safe when a junction job with `if: always()` needs it and reports for it. Filter the steps of the job instead and the job still runs and reports.
+ *
+ * Limits: a workflow is taken to produce a required check when it has a junction job, so a trigger path filter in a workflow without one is not reported; a path filter is recognised by the actions in the options, so a script that computes changed paths itself is not seen, and a job gated on the output of such a script is not reported; only the filters of the `pull_request` and `pull_request_target` triggers are read, so a `paths` filter on `push` is not reported; only `needs.<job>.outputs` in the job's own `if` is read. Whether the junction job really reports is judged by `workflow-job-ordering`.
+ */
+export declare const workflowSkippableJobs: CheckFunction<WorkflowSkippableJobsOptions>;
+//#endregion
+//#region src/checks/workflow-update-bot-cooldown.d.ts
+/**
+ * The update bots wait before proposing a release, so a compromised release is withdrawn before it is installed. Dependabot: every `updates` entry needs a `cooldown` with `default-days` or one of the `semver-*-days` above zero. Renovate: `minimumReleaseAge` must be set to a duration above zero at the top level or in a `packageRules` entry.
+ *
+ * Limits: the bots' own rules differ, since Dependabot's cooldown does not apply to security updates, and a Renovate preset is not resolved (an `extends` entry counts only when its name contains `minimumReleaseAge`), so a setting that comes from a preset under another name is reported. Renovate configs in JSON5 syntax beyond comments and trailing commas, and a `renovate` key in `package.json`, are not read. A repository with neither bot has nothing to report.
+ */
+export declare const workflowUpdateBotCooldown: CheckFunction<WorkflowUpdateBotCooldownOptions>;
+//#endregion
+//#region src/checks/workflow-version-single-source.d.ts
+/**
+ * A setup step keeps a runtime version in the workflow when a version file already says it: `.nvmrc` for Node, `.tool-versions` for any tool it lists. The step reads the file instead (`node-version-file`, or `mise` or `asdf` actions), so there is one place to change.
+ *
+ * A version is a literal when it contains no expression, so `${{ matrix.node }}` is not reported: a matrix tests versions on purpose. A range or alias such as `lts/*` is a literal. Only the setup actions listed in the README are recognised, only the files in the working directory are looked for, and composite actions are not read.
+ */
+export declare const workflowVersionSingleSource: CheckFunction<WorkflowVersionSingleSourceOptions>;
+//#endregion
 //#region src/config.d.ts
 /**
  * The `checks` map of the `conformance` section: a check runs when its name is present with an options object (`{}` for the defaults), and `false` turns it off, which lets a config that extends another switch one of its checks off.
@@ -319,23 +1033,49 @@ interface RunInput {
   readonly checks: ChecksConfig;
   readonly layout: LayoutConfig | undefined;
   readonly configFiles: ConfigFileOptions | undefined;
+  /**
+   * The client the settings checks read through; `undefined` when the run is offline.
+   */
+  readonly github: GitHubClient | undefined;
 }
 /**
- * A check bound to its place in the `checks` map.
+ * What every registered check has, whichever way it runs.
  */
-interface RegisteredCheck<Name extends CheckName> {
+interface RegisteredCheckBase<Name extends CheckName> {
   readonly name: Name;
   readonly description: string;
   /**
    * Whether the check reads the workspace layout, and so needs the `layout` section.
    */
   readonly requiresLayout: boolean;
+  /**
+   * Whether the check reads the repository's settings through the GitHub API, and so runs only when the run is given a client.
+   */
+  readonly requiresGitHub: boolean;
   /**
    * Whether the `checks` map turns this check on.
    */
   readonly isEnabled: (checks: ChecksConfig) => boolean;
+}
+/**
+ * A check that runs on its own.
+ */
+interface StandaloneCheck<Name extends CheckName> extends RegisteredCheckBase<Name> {
   readonly run: (input: RunInput) => Promise<readonly Violation[]>;
 }
+/**
+ * An import check. It has no `run` of its own: it always joins a cruise shared with the other import checks of the run, so there is one path from the registry to dependency-cruiser.
+ */
+interface ImportGraphCheck<Name extends CheckName> extends RegisteredCheckBase<Name> {
+  readonly importGraph: {
+    readonly spec: ImportCheckSpec;
+    readonly optionsOf: (checks: ChecksConfig) => ImportGraphOptions | undefined;
+  };
+}
+/**
+ * A check bound to its place in the `checks` map.
+ */
+type RegisteredCheck<Name extends CheckName> = StandaloneCheck<Name> | ImportGraphCheck<Name>;
 /**
  * Every check, by name, in the order they run. The key is the name used in the `checks` map, on the command line and in violation codes.
  */
@@ -382,6 +1122,10 @@ interface RunChecksOptions {
    * How config files are loaded: the sections loaded from `cwd` and the config files a check evaluates itself, such as the commitlint and release configs of `commit-types`. Only `alias` and `fsCache` apply to the latter.
    */
   readonly configFiles?: ConfigFileOptions;
+  /**
+   * The client the settings checks (`settings-*`) read the repository through. They run only when it is given, so a run without it stays offline and needs no token; naming one of them in `checks` without a client is an error.
+   */
+  readonly github?: GitHubClient;
 }
 /**
  * The violations of one check.
@@ -478,84 +1222,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-//#region src/workspace/packages.d.ts
-/**
- * A package directory found under the workspace root, before the layout classifies it.
- */
-interface DiscoveredPackage {
-  /**
-   * Relative to the workspace root, with `/` separators.
-   */
-  readonly dir: string;
-  /**
-   * The manifest's `name`; a manifest may omit it.
-   */
-  readonly name: string | undefined;
-}
-/**
- * A workspace package as the layout sees it.
- */
-interface WorkspacePackage extends DiscoveredPackage {
-  /**
-   * The name of the group whose root is the longest prefix of the package directory.
-   */
-  readonly group: string;
-  /**
-   * The rank from `nameRanks`, else the group's rank, else `defaultRank`; `undefined` when none of them applies.
-   */
-  readonly rank: number | undefined;
-  /**
-   * The slice the group's `slice` rule derives; `undefined` for a group without one and for a package that yields none.
-   */
-  readonly slice: string | undefined;
-}
-/**
- * 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.
- */
-export declare function classifyPackages(discovered: readonly DiscoveredPackage[], layout: LayoutConfig): readonly WorkspacePackage[];
-//#endregion
-//#region src/workspace/rules.d.ts
-/**
- * A forbidden-dependency rule in the shape dependency-cruiser takes: a dependency from a file matching `from` to a file matching `to` is a violation.
- */
-interface ImportRule {
-  readonly name: string;
-  readonly severity: "error";
-  readonly comment: string;
-  readonly from: {
-    readonly path?: string;
-  };
-  readonly to: {
-    readonly path?: string;
-    readonly circular?: boolean;
-    readonly couldNotResolve?: boolean;
-  };
-}
-/**
- * A regular expression, as source text, matching every file inside any of the packages. The trailing `/` keeps `packages/a` from matching `packages/ab`.
- */
-export declare function packagesPattern(packages: readonly WorkspacePackage[]): string;
-/**
- * One rule per rank that has a higher rank above it: files of a package at that rank may not import a package at a strictly higher rank. A rule compares no numbers, so the ordering is expanded into path alternations here. Each rule comes with a `-by-name` rule for imports that do not resolve to a file.
- */
-export declare function uphillRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
-/**
- * One rule per rank with a package more than `rankSkip.maxDistance` ranks below it that is not an exempt rank.
- */
-export declare function rankSkipRules(packages: readonly WorkspacePackage[], rankSkip: RankSkipOptions): readonly ImportRule[];
-/**
- * One rule per slice: a package in it may not import a package that has a different slice. A package without a slice is in none and is never restricted.
- */
-export declare function crossSliceRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
-/**
- * Two rules per isolated pair, one for each direction.
- */
-export declare function isolatedGroupRules(packages: readonly WorkspacePackage[], isolatedGroups: NonNullable<LayoutConfig["isolatedGroups"]>): readonly ImportRule[];
-/**
- * The rule that forbids any import cycle among the packages' files.
- */
-export declare function cycleRule(): ImportRule;
-//#endregion
-export type { AggregateMappersOptions, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DiscoveredPackage, DockerfilePackageManagerOptions, ExhaustivenessProof, ImportGraphOptions, InstructionSymlinksOptions, LayoutCheckContext, LayoutCheckFunction, RegisteredCheck, RunChecksOptions, RunResult, SingleStorybookOptions, SourceLocation, TypeErrorReport, Violation, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DiscoveredPackage, DockerfilePackageManagerOptions, 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, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };