Docs Coverage Weekly Audit #3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |