docs-coverage-weekly.yml

name: Docs Coverage Weekly Audit

# Runs the docs-coverage script weekly against main and opens a tracking
# issue if drift has accumulated. This is the structural safety net that
# catches doc drift even when no contributor is actively watching for it.
#
# The job is intentionally light: it doesn't fix docs, it only surfaces
# what needs fixing. The actual write-up happens in deliberate doc-update
# PRs with review.

on:
  schedule:
    # Monday 10:00 UTC — quiet time across most timezones.
    - cron: '0 10 * * 1'
  # Allow manual triggers for ad-hoc checks.
  workflow_dispatch:

jobs:
  audit:
    name: Run docs coverage audit
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Run coverage script
        # Always write the JSON + MD reports. Don't fail the workflow on
        # below-floor coverage — that's the per-PR job's responsibility.
        run: node scripts/docs-coverage.mjs --json > coverage.json
      - name: Render report
        run: cat .instar/docs-coverage.md
      - name: Upload coverage artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-coverage-weekly
          path: |
            coverage.json
            .instar/docs-coverage.md
      - name: Open or update tracking issue
        # Use the GitHub CLI to post the weekly report as a comment on a
        # standing issue. If no issue exists, create one. The issue acts
        # as a running ledger of weekly coverage observations.
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          REPORT_PATH=".instar/docs-coverage.md"
          if [ ! -f "$REPORT_PATH" ]; then
            echo "No coverage report — skipping issue update."
            exit 0
          fi
          # Find an open issue tagged with our marker label, or create one.
          ISSUE_NUMBER="$(gh issue list --label docs-coverage --state open --json number --jq '.[0].number // empty')"
          BODY=$(cat <<EOF
          ## Weekly docs coverage snapshot — $(date -u +"%Y-%m-%d")

          $(cat "$REPORT_PATH")

          ---

          Generated by \`.github/workflows/docs-coverage-weekly.yml\`. The full JSON report is attached to the workflow run.
          EOF
          )
          if [ -z "$ISSUE_NUMBER" ]; then
            gh issue create \
              --title "Docs coverage — running weekly ledger" \
              --label docs-coverage \
              --body "$BODY"
          else
            gh issue comment "$ISSUE_NUMBER" --body "$BODY"
          fi