eslint-plugin-github-actions-2 1.0.2 → 1.0.4

package/docs/rules/require-dependabot-commit-message-prefix-development.md

@@ -0,0 +1,60 @@
+# require-dependabot-commit-message-prefix-development
+
+> **Rule catalog ID:** R090
+
+## Targeted pattern scope
+
+Dependabot update entries for ecosystems that support `commit-message.prefix-development`, including values inherited from `multi-ecosystem-groups`.
+
+## What this rule reports
+
+This rule reports supported update entries that do not define a non-empty `commit-message.prefix-development`.
+
+## Why this rule exists
+
+Development dependency updates often deserve different review and merge treatment than production dependencies. Requiring a dedicated development prefix makes that distinction visible in Dependabot commit messages and pull request titles.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    commit-message:
+      prefix: "deps"
+      prefix-development: "deps-dev"
+      include: "scope"
+```
+
+## Additional examples
+
+This rule only applies to ecosystems that GitHub documents as supporting `prefix-development`, so unrelated ecosystems are ignored.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally wants identical Dependabot title prefixes for production and development dependencies.
+
+## Further reading
+
+- [Dependabot options reference: commit-message](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#commit-message--)

package/docs/rules/require-dependabot-commit-message-prefix.md

@@ -0,0 +1,64 @@
+# require-dependabot-commit-message-prefix
+
+> **Rule catalog ID:** R079
+
+## Targeted pattern scope
+
+Dependabot update entries and multi-ecosystem groups that configure `commit-message` formatting.
+
+## What this rule reports
+
+This rule reports update entries that do not resolve to a non-empty `commit-message.prefix`.
+
+## Why this rule exists
+
+Dependabot commit messages also shape pull request titles. Requiring a prefix keeps automation, filtering, and review conventions consistent across dependency update pull requests.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+    commit-message:
+      prefix: "deps"
+```
+
+## Additional examples
+
+Teams that trigger automation from pull request titles or commit conventions often use this rule to keep Dependabot updates aligned with the rest of the repository.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule when the repository intentionally relies on Dependabot's default commit message heuristics.
+
+## Further reading
+
+- [Dependabot options reference: commit-message](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#commit-message--)
+- [Customizing Dependabot pull requests: Adding a prefix to commit messages](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#adding-a-prefix-to-commit-messages)

package/docs/rules/require-dependabot-cooldown.md

@@ -0,0 +1,59 @@
+# require-dependabot-cooldown
+
+> **Rule catalog ID:** R086
+
+## Targeted pattern scope
+
+Dependabot update entries in `.github/dependabot.yml`.
+
+## What this rule reports
+
+This rule reports update entries that omit the `cooldown` key.
+
+## Why this rule exists
+
+Cooldown settings reduce noisy pull request churn by delaying fresh version updates for a defined period. Requiring the key makes update pacing an explicit policy decision instead of an accidental default.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    cooldown:
+      default-days: 3
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+Teams that prefer fewer routine Dependabot pull requests often combine cooldown with grouped updates and explicit pull request limits.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally wants Dependabot to consider each new release immediately.
+
+## Further reading
+
+- [Dependabot options reference: cooldown](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#cooldown-)

package/docs/rules/require-dependabot-directory.md

@@ -0,0 +1,79 @@
+# require-dependabot-directory
+
+> **Rule catalog ID:** R073
+
+## Targeted pattern scope
+
+Entries under the top-level `updates` sequence in Dependabot configuration files.
+
+## What this rule reports
+
+This rule reports update entries that omit both `directory` and `directories`, define both at once, or provide only empty values.
+
+## Why this rule exists
+
+Dependabot needs a manifest search location for every update block. Requiring exactly one directory form keeps update intent explicit and avoids ambiguous configuration.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    schedule:
+      interval: "weekly"
+```
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    directories:
+      - "/docs/docusaurus"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directories:
+      - "/"
+      - "/docs/docusaurus"
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+Use this rule together with monorepo-oriented Dependabot settings when some workspaces live outside the repository root and need their own manifest scan locations.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only if another repository-specific validator already enforces directory selection semantics.
+
+## Further reading
+
+- [Dependabot options reference: directories or directory](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#directories-or-directory--)
+- [Defining multiple locations for manifest files](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-multiple-locations-for-manifest-files)

package/docs/rules/require-dependabot-github-actions-directory-root.md

@@ -0,0 +1,62 @@
+# require-dependabot-github-actions-directory-root
+
+> **Rule catalog ID:** R084
+
+## Targeted pattern scope
+
+Dependabot update entries that use `package-ecosystem: "github-actions"`.
+
+## What this rule reports
+
+This rule reports GitHub Actions ecosystem entries that do not use `directory: "/"` exactly, or that try to use `directories` instead.
+
+## Why this rule exists
+
+GitHub documents `directory: "/"` as the correct location for the `github-actions` ecosystem. Dependabot uses that root setting to scan the standard workflow directory and root action metadata locations. Using a narrower or alternate directory is misleading and can cause missed updates.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/.github/workflows"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## Behavior and migration notes
+
+The autofixer rewrites GitHub Actions ecosystem entries to the canonical `directory: "/"` form. If the entry incorrectly uses `directories`, the fix replaces that block with the single documented `directory` key because that is the only supported location for `package-ecosystem: "github-actions"`.
+
+## Additional examples
+
+This rule is a good fit for repositories that maintain both workflow YAML and root-level composite or JavaScript actions, because the documented root scan location covers both surfaces.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only if GitHub changes the documented scan behavior for the `github-actions` ecosystem and the repository intentionally follows that newer contract.
+
+## Further reading
+
+- [Dependabot options reference: directories or directory](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#directories-or-directory--)
+- [Example dependabot.yml file](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-dependabot-version-updates#example-dependabotyml-file)

package/docs/rules/require-dependabot-labels.md

@@ -0,0 +1,65 @@
+# require-dependabot-labels
+
+> **Rule catalog ID:** R080
+
+## Targeted pattern scope
+
+Dependabot update entries and multi-ecosystem groups that decide pull request labels.
+
+## What this rule reports
+
+This rule reports update entries that do not resolve to a non-empty `labels` list, either directly or via `multi-ecosystem-groups` inheritance.
+
+## Why this rule exists
+
+Labels are a high-leverage way to route Dependabot pull requests into automation, project boards, or triage queues. Requiring them keeps dependency updates easy to filter and process consistently.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+    labels:
+      - "dependabot"
+      - "dependencies"
+```
+
+## Additional examples
+
+This rule is a strong fit when Dependabot pull requests feed dashboards, project automation, or triage workflows that rely on consistent labels.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally accepts Dependabot's default labels without any custom triage flow.
+
+## Further reading
+
+- [Dependabot options reference: labels](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#labels--)
+- [Customizing Dependabot pull requests: Labeling pull requests with custom labels](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#labeling-pull-requests-with-custom-labels)

package/docs/rules/require-dependabot-open-pull-requests-limit.md

@@ -0,0 +1,58 @@
+# require-dependabot-open-pull-requests-limit
+
+> **Rule catalog ID:** R087
+
+## Targeted pattern scope
+
+Dependabot update entries in `.github/dependabot.yml`.
+
+## What this rule reports
+
+This rule reports update entries that do not define `open-pull-requests-limit`.
+
+## Why this rule exists
+
+Dependabot defaults can be reasonable, but they are still implicit. Requiring an explicit open pull request limit makes update volume a deliberate repository policy.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    open-pull-requests-limit: 5
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+This rule works well with grouped updates because the repository can cap Dependabot volume even when multiple manifests are monitored.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally relies on Dependabot's built-in default PR limit.
+
+## Further reading
+
+- [Dependabot options reference: open-pull-requests-limit](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#open-pull-requests-limit-)

package/docs/rules/require-dependabot-package-ecosystem.md

@@ -0,0 +1,57 @@
+# require-dependabot-package-ecosystem
+
+> **Rule catalog ID:** R072
+
+## Targeted pattern scope
+
+Entries under the top-level `updates` sequence in Dependabot configuration files.
+
+## What this rule reports
+
+This rule reports `updates` entries that are not mappings, or mappings that omit a non-empty `package-ecosystem`.
+
+## Why this rule exists
+
+Dependabot cannot resolve package-manager-specific behavior without knowing the ecosystem for each update block. Missing `package-ecosystem` means the rest of the block has no clear target.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+This rule is especially helpful when large `updates` blocks are copied and edited by hand, since missing `package-ecosystem` is easy to overlook in repetitive YAML.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+If you already validate Dependabot files against a stricter schema elsewhere, this rule can be redundant.
+
+## Further reading
+
+- [Dependabot options reference: package-ecosystem](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#package-ecosystem-)
+- [Dependabot options reference: Required keys](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#required-keys)

package/docs/rules/require-dependabot-patterns-for-multi-ecosystem-group.md

@@ -0,0 +1,67 @@
+# require-dependabot-patterns-for-multi-ecosystem-group
+
+> **Rule catalog ID:** R082
+
+## Targeted pattern scope
+
+Dependabot update entries that opt into `multi-ecosystem-group`.
+
+## What this rule reports
+
+This rule reports grouped update entries that do not declare a non-empty `patterns` list.
+
+## Why this rule exists
+
+GitHub's multi-ecosystem update guide calls out `patterns` as a required part of assigning ecosystems to a group. Without patterns, the grouping intent is underspecified and Dependabot may not consolidate updates the way the configuration suggests.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+multi-ecosystem-groups:
+  app:
+    schedule:
+      interval: "weekly"
+
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    multi-ecosystem-group: "app"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+multi-ecosystem-groups:
+  app:
+    schedule:
+      interval: "weekly"
+
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    multi-ecosystem-group: "app"
+    patterns: ["*"]
+```
+
+## Additional examples
+
+Use `patterns: ["*"]` when the goal is to group every dependency in that ecosystem rather than a narrower allowlist.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only if the repository intentionally avoids multi-ecosystem updates entirely.
+
+## Further reading
+
+- [Configuring multi-ecosystem updates for Dependabot](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/configuring-multi-ecosystem-updates)
+- [Dependabot options reference: multi-ecosystem-groups](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#multi-ecosystem-groups-)

package/docs/rules/require-dependabot-schedule-cronjob.md

@@ -0,0 +1,74 @@
+# require-dependabot-schedule-cronjob
+
+> **Rule catalog ID:** R083
+
+## Targeted pattern scope
+
+Dependabot schedule mappings that use `interval: "cron"`, including schedules inherited from `multi-ecosystem-groups`.
+
+## What this rule reports
+
+This rule reports two cases:
+
+- `interval: "cron"` without a non-empty `cronjob`
+- non-cron intervals that still define `cronjob`
+
+## Why this rule exists
+
+`cronjob` is meaningful only when Dependabot is configured with `interval: "cron"`. Requiring it in cron mode and forbidding it elsewhere keeps schedule intent explicit and avoids configuration that looks more precise than Dependabot will actually honor.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "cron"
+      timezone: "UTC"
+```
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      cronjob: "0 9 * * *"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "cron"
+      cronjob: "0 9 * * *"
+      timezone: "UTC"
+```
+
+## Additional examples
+
+This rule complements `require-dependabot-schedule-time` and `require-dependabot-schedule-timezone` by covering the schedule branch where `cronjob` replaces `time`.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only if the repository bans cron-based schedules and enforces that policy with a different rule set.
+
+## Further reading
+
+- [Dependabot options reference: schedule](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#schedule-)
+- [Dependabot options reference: schedule.cronjob](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#schedule-)