workspace-conformance 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -255,6 +255,10 @@ interface Job {
   readonly needs: readonly string[];
   readonly condition: string | undefined;
   readonly permissions: Permissions;
+  /**
+   * The name of the deployment environment the job runs in, written as `environment: <name>` or `environment: { name: <name> }`; `undefined` when it names none.
+   */
+  readonly environment: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly runsOn: RunsOn;
   readonly timeoutMinutes: string | undefined;
@@ -282,6 +286,10 @@ interface Workflow {
    */
   readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
   readonly permissions: Permissions;
+  /**
+   * Where the workflow's `permissions` is written; `undefined` when it declares none.
+   */
+  readonly permissionsLocation: SourceLocation | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly jobs: readonly Job[];
   /**
@@ -516,6 +524,15 @@ interface CommitTypesOptions {
    */
   readonly release?: string;
 }
+/**
+ * Options of the `engines-floor` check: the `engines.node` range of a package is a subset of the `engines.node` range of each of its installed dependencies.
+ */
+interface EnginesFloorOptions {
+  /**
+   * Globs of the package directories to judge, in the form of the `packages` list of `pnpm-workspace.yaml` (a `!` pattern excludes), relative to the directory the checks run in; `.` is the root package. The root package and the `packages` of `pnpm-workspace.yaml`, when that file exists, when omitted.
+   */
+  readonly packages?: readonly string[];
+}
 /**
  * Options of the `dockerfile-package-manager` check: a package manager version pinned in a Dockerfile is the one `packageManager` names.
  */
@@ -667,6 +684,15 @@ type WorkflowVersionSingleSourceOptions = WorkflowSelection;
  * Options of the `workflow-credentials` check.
  */
 type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-release-job` check: the job that publishes is the only one that can mint the OIDC identity, runs in an environment and leaves no credentials behind.
+ */
+interface WorkflowReleaseJobOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs: the jobs that publish, and the only ones that may hold `id-token: write`. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+}
 /**
  * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
  */
@@ -773,6 +799,7 @@ interface CheckOptionsByName {
   readonly "instruction-symlinks": InstructionSymlinksOptions;
   readonly "single-storybook": SingleStorybookOptions;
   readonly "commit-types": CommitTypesOptions;
+  readonly "engines-floor": EnginesFloorOptions;
   readonly "dockerfile-package-manager": DockerfilePackageManagerOptions;
   readonly "migrations-directory": MigrationsDirectoryOptions;
   readonly eslint: EslintOptions;
@@ -781,6 +808,7 @@ interface CheckOptionsByName {
   readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
   readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
   readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-release-job": WorkflowReleaseJobOptions;
   readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
   readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
   readonly "workflow-merge-group": WorkflowMergeGroupOptions;
@@ -854,6 +882,18 @@ export declare const derivedTypes: CheckFunction<DerivedTypesOptions>;
  */
 export declare const dockerfilePackageManager: CheckFunction<DockerfilePackageManagerOptions>;
 //#endregion
+//#region src/checks/engines-floor.d.ts
+/**
+ * The `engines.node` range of each package is a subset of the `engines.node` range of each dependency and optional dependency it lists, and of each peer dependency whose range admits a single version, as installed in `node_modules`, so the package admits no Node version that something it needs at run time rejects. A package that declares no range admits every version, so it is reported for each dependency that declares one. A dependency that declares no range constrains nothing and is ignored.
+ *
+ * The comparison is `semver.subset(package, dependency)`: every version the package's range admits satisfies the dependency's range. A floor alone is not enough, because a range of several lines (`^20.19.0 || ^22.13.0 || >=24`) also rejects the versions between them, which `>=20.19.0` admits. semver compares a range of several comparator sets set by set, so each set of the package's range must lie within one set of the dependency's; a set that only two adjacent dependency sets cover together (`>=22` against `^22.0.0 || >=23`) is reported, and splitting it the same way (`^22.0.0 || >=23`) satisfies the check.
+ *
+ * A peer dependency is judged only when its range admits a single version (`1.2.3` or `=1.2.3`), and then by the copy installed, which must be that version. The consumer chooses which admitted version to install, so the package's range holds when each Node version in it is accepted by some admitted version; one installed copy that rejects a Node version does not show that every admitted version does, and the others are not on disk.
+ *
+ * A dependency that is not installed fails the run: its range cannot be read, and passing it unjudged would read as a pass. An optional dependency and a peer dependency marked optional in `peerDependenciesMeta` may be absent and are then skipped.
+ */
+export declare const enginesFloor: CheckFunction<EnginesFloorOptions>;
+//#endregion
 //#region src/checks/eslint.d.ts
 /**
  * Proves the repository's own ESLint is applied, which no check that runs inside ESLint can notice: a config that dropped a shared preset, switched its rules off or narrowed `ignores` until nothing is linted still passes its own lint.
@@ -1088,6 +1128,18 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  */
 export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
 //#endregion
+//#region src/checks/workflow-release-job.d.ts
+/**
+ * npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+ *
+ * In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+ *
+ * In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+ *
+ * Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+ */
+export declare const workflowReleaseJob: CheckFunction<WorkflowReleaseJobOptions>;
+//#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.
@@ -1356,4 +1408,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EnginesFloorOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.d.ts

@@ -255,6 +255,10 @@ interface Job {
   readonly needs: readonly string[];
   readonly condition: string | undefined;
   readonly permissions: Permissions;
+  /**
+   * The name of the deployment environment the job runs in, written as `environment: <name>` or `environment: { name: <name> }`; `undefined` when it names none.
+   */
+  readonly environment: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly runsOn: RunsOn;
   readonly timeoutMinutes: string | undefined;
@@ -282,6 +286,10 @@ interface Workflow {
    */
   readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
   readonly permissions: Permissions;
+  /**
+   * Where the workflow's `permissions` is written; `undefined` when it declares none.
+   */
+  readonly permissionsLocation: SourceLocation | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly jobs: readonly Job[];
   /**
@@ -516,6 +524,15 @@ interface CommitTypesOptions {
    */
   readonly release?: string;
 }
+/**
+ * Options of the `engines-floor` check: the `engines.node` range of a package is a subset of the `engines.node` range of each of its installed dependencies.
+ */
+interface EnginesFloorOptions {
+  /**
+   * Globs of the package directories to judge, in the form of the `packages` list of `pnpm-workspace.yaml` (a `!` pattern excludes), relative to the directory the checks run in; `.` is the root package. The root package and the `packages` of `pnpm-workspace.yaml`, when that file exists, when omitted.
+   */
+  readonly packages?: readonly string[];
+}
 /**
  * Options of the `dockerfile-package-manager` check: a package manager version pinned in a Dockerfile is the one `packageManager` names.
  */
@@ -667,6 +684,15 @@ type WorkflowVersionSingleSourceOptions = WorkflowSelection;
  * Options of the `workflow-credentials` check.
  */
 type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-release-job` check: the job that publishes is the only one that can mint the OIDC identity, runs in an environment and leaves no credentials behind.
+ */
+interface WorkflowReleaseJobOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs: the jobs that publish, and the only ones that may hold `id-token: write`. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+}
 /**
  * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
  */
@@ -773,6 +799,7 @@ interface CheckOptionsByName {
   readonly "instruction-symlinks": InstructionSymlinksOptions;
   readonly "single-storybook": SingleStorybookOptions;
   readonly "commit-types": CommitTypesOptions;
+  readonly "engines-floor": EnginesFloorOptions;
   readonly "dockerfile-package-manager": DockerfilePackageManagerOptions;
   readonly "migrations-directory": MigrationsDirectoryOptions;
   readonly eslint: EslintOptions;
@@ -781,6 +808,7 @@ interface CheckOptionsByName {
   readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
   readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
   readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-release-job": WorkflowReleaseJobOptions;
   readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
   readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
   readonly "workflow-merge-group": WorkflowMergeGroupOptions;
@@ -854,6 +882,18 @@ export declare const derivedTypes: CheckFunction<DerivedTypesOptions>;
  */
 export declare const dockerfilePackageManager: CheckFunction<DockerfilePackageManagerOptions>;
 //#endregion
+//#region src/checks/engines-floor.d.ts
+/**
+ * The `engines.node` range of each package is a subset of the `engines.node` range of each dependency and optional dependency it lists, and of each peer dependency whose range admits a single version, as installed in `node_modules`, so the package admits no Node version that something it needs at run time rejects. A package that declares no range admits every version, so it is reported for each dependency that declares one. A dependency that declares no range constrains nothing and is ignored.
+ *
+ * The comparison is `semver.subset(package, dependency)`: every version the package's range admits satisfies the dependency's range. A floor alone is not enough, because a range of several lines (`^20.19.0 || ^22.13.0 || >=24`) also rejects the versions between them, which `>=20.19.0` admits. semver compares a range of several comparator sets set by set, so each set of the package's range must lie within one set of the dependency's; a set that only two adjacent dependency sets cover together (`>=22` against `^22.0.0 || >=23`) is reported, and splitting it the same way (`^22.0.0 || >=23`) satisfies the check.
+ *
+ * A peer dependency is judged only when its range admits a single version (`1.2.3` or `=1.2.3`), and then by the copy installed, which must be that version. The consumer chooses which admitted version to install, so the package's range holds when each Node version in it is accepted by some admitted version; one installed copy that rejects a Node version does not show that every admitted version does, and the others are not on disk.
+ *
+ * A dependency that is not installed fails the run: its range cannot be read, and passing it unjudged would read as a pass. An optional dependency and a peer dependency marked optional in `peerDependenciesMeta` may be absent and are then skipped.
+ */
+export declare const enginesFloor: CheckFunction<EnginesFloorOptions>;
+//#endregion
 //#region src/checks/eslint.d.ts
 /**
  * Proves the repository's own ESLint is applied, which no check that runs inside ESLint can notice: a config that dropped a shared preset, switched its rules off or narrowed `ignores` until nothing is linted still passes its own lint.
@@ -1088,6 +1128,18 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  */
 export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
 //#endregion
+//#region src/checks/workflow-release-job.d.ts
+/**
+ * npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+ *
+ * In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+ *
+ * In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+ *
+ * Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+ */
+export declare const workflowReleaseJob: CheckFunction<WorkflowReleaseJobOptions>;
+//#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.
@@ -1356,4 +1408,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EnginesFloorOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };