workspace-conformance 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -2,6 +2,71 @@ 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.
@@ -53,6 +118,16 @@ 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
 /**
@@ -125,6 +200,156 @@ 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
 /**
  * Options of the `aggregate-mappers` check: every aggregate type a contract exports has a mapper file in the place the template names.
@@ -282,6 +507,155 @@ interface MigrationsDirectoryOptions {
    */
   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.
  */
@@ -298,6 +672,18 @@ interface CheckOptionsByName {
   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.
@@ -500,12 +886,116 @@ export declare const instructionSymlinks: CheckFunction<InstructionSymlinksOptio
  */
 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.
@@ -543,6 +1033,10 @@ 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;
 }
 /**
  * What every registered check has, whichever way it runs.
@@ -554,6 +1048,10 @@ interface RegisteredCheckBase<Name extends CheckName> {
    * 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.
    */
@@ -624,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.
@@ -720,4 +1222,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DiscoveredPackage, DockerfilePackageManagerOptions, ExhaustivenessProof, GeneratorAdapter, GeneratorName, ImportGraphOptions, InstructionSymlinksOptions, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, 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 };