audit.py: check Dependabot ecosystem coverage against the repo tree (#346)

[ptr727]

Fixes the audit-coverage half of #346. (The concrete ESPHome-Config drift is filed as a separate downstream issue for that repo to fix.)

The gap

spec/audit.py checked Dependabot secret stores but never that a repo's .github/dependabot.yml declares the ecosystems its tree implies. So ESPHome-Config - which ships test-pull-request.yml / publish-release.yml / merge-bot-pull-request.yml with SHA-pinned actions but tracks only devcontainers - passed the standup audit clean, even though its action pins get no bump PRs and the merge-bot it just stood up has no action-update PRs to act on.

The check

New crossCutting check setup.dependabot.ecosystems (repo-setup dimension): for each ecosystem the tree implies, dependabot.yml must declare it (dual-target main+develop per the fleet norm):

• github-actions when .github/workflows/ ships actions,
• devcontainers when a .devcontainer is present.

A missing implied ecosystem is a DRIFT finding. dependabot.yml is YAML (audit.py is stdlib-only, no parser), so the declared package-ecosystem values are scanned by regex - enough to assert presence. The check only runs when the file exists (its absence is already a file-presence LETTER). Language ecosystems (nuget/uv/npm) are directory-scoped and left to inspection for now (noted in AUDIT.md).

Codified in AUDIT.md section 6 (with a shell snippet) and spec/project-types.json.

Verification (live, read-only)

ESPHome-Config    -> DRIFT dependabot: github-actions ecosystem not declared though .github/workflows/ ships SHA-pinned actions
Vantage-Config    -> clean       HomeAutomation-Config -> clean
PlexCleaner       -> clean       Utilities -> clean       aiopurpleair -> clean

The devcontainers ecosystem ESPHome-Config does declare is correctly not flagged. spec/validate.py passes; markdownlint + editorconfig-checker clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new audit check to ensure repos’ Dependabot configuration covers ecosystems implied by the repo tree (notably github-actions when workflows exist, and devcontainers when a .devcontainer/ exists), so action SHA pins receive update PRs and the merge-bot has relevant PRs to auto-merge.

Changes:

• Extend spec/audit.py with a new DRIFT check that compares implied ecosystems (from repo contents) vs declared package-ecosystem values in .github/dependabot.yml.
• Document the new audit step in AUDIT.md and add a supporting reference link.
• Register the new check as setup.dependabot.ecosystems in spec/project-types.json.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
spec/project-types.json	Adds the new cross-cutting repo-setup check definition for Dependabot ecosystem coverage.
spec/audit.py	Implements the new live audit logic to detect missing implied Dependabot ecosystems.
AUDIT.md	Documents the new manual audit step and provides a CLI snippet for verification.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

AUDIT.md:92

• This section states github-actions is implied when workflows "ship SHA-pinned actions", but the mechanical check (and the snippet below) only test for the presence of .github/workflows/ and workflow YAML files. To avoid inconsistent guidance, align this wording with what is mechanically asserted (or update both the snippet and spec/audit.py to actually detect action usage/pins in workflow contents).

- **Dependabot ecosystem coverage** - for each ecosystem the repo's tree implies, `.github/dependabot.yml` must declare it: `github-actions` when `.github/workflows/` ships SHA-pinned actions - otherwise the pins go stale and a stood-up merge-bot has no action-update PRs to auto-merge - and `devcontainers` when a `.devcontainer` is present. The mechanical check (`spec/audit.py`) asserts each implied ecosystem's **presence**; a tree-implied ecosystem declared nowhere is a **drift finding** (the file exists; its absence would instead be a file-presence letter). Then confirm **by inspection** that each declared ecosystem **dual-targets `main` + `develop`** per the [Branching Model][agents-branching-model] - the regex below cannot pair an ecosystem with its `target-branch`. Language ecosystems (`nuget`/`uv`/`npm`) are directory-scoped and audited by inspection too.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

spec/audit.py:198

• The audit currently implies the github-actions ecosystem based only on the presence of workflow YAML files (directory listing), but the rationale string says ".github/workflows/ uses actions". That is not what is being checked and can make the DRIFT message misleading. Either scan workflow contents for non-local uses: entries, or adjust the reason text to match the actual heuristic (workflows present).

        workflows = gh(f"repos/{slug}/contents/.github/workflows?ref={ground}", ok404=True)
        if isinstance(workflows, list) and any(e["name"].endswith((".yml", ".yaml")) for e in workflows):
            implied["github-actions"] = ".github/workflows/ uses actions"
        if gh(f"repos/{slug}/contents/.devcontainer?ref={ground}", ok404=True) is not None:

spec/project-types.json:127

• This intent text says the github-actions ecosystem is implied when .github/workflows/ "uses actions", but the mechanical check in spec/audit.py only keys off the presence of workflow YAML files. To keep the spec aligned with the implemented audit, adjust this wording (or strengthen the audit to actually detect uses: entries).

                { "id": "setup.dependabot.ecosystems", "verdict": "intent", "assert": "For each ecosystem the repo's tree implies, .github/dependabot.yml declares it (dual-target main+develop per the fleet norm): github-actions when .github/workflows/ uses actions (else their versions go stale and a stood-up merge-bot has no PRs to auto-merge), devcontainers when a .devcontainer is present. A missing implied ecosystem is a drift finding. Language ecosystems (nuget/uv/npm) are directory-scoped, audited by inspection.", "intentRef": "AGENTS.md#branching-model" }

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

spec/audit.py:197

• The implied-reason string says ".github/workflows/ uses actions", but this check only verifies that workflow YAML exists (it does not scan for uses:). This can make the DRIFT message misleading. Reword the reason to match what is actually checked (workflow YAML presence), or strengthen the check to detect uses: entries.

            implied["github-actions"] = ".github/workflows/ uses actions"

spec/project-types.json:127

• This assertion says the ecosystem is implied when workflows "use actions", but the mechanical audit (spec/audit.py) currently only checks for workflow YAML presence. Either align this text to the implemented check (workflow YAML present) or update the audit to actually detect uses: lines.

                { "id": "setup.dependabot.ecosystems", "verdict": "intent", "assert": "For each ecosystem the repo's tree implies, .github/dependabot.yml declares it (dual-target main+develop per the fleet norm): github-actions when .github/workflows/ uses actions (else their versions go stale and a stood-up merge-bot has no PRs to auto-merge), devcontainers when a .devcontainer is present. A missing implied ecosystem is a drift finding. Language ecosystems (nuget/uv/npm) are directory-scoped, audited by inspection.", "intentRef": "AGENTS.md#branching-model" }

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.