[reports] Validate published HTML with proof-html

Author: coisa

.github/workflows/reports.yml

@@ -194,12 +194,56 @@ jobs:
                   /coverage/|Preview coverage report
                   /metrics/|Preview metrics report
 
+    validate_main_reports_html:
+        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && !(github.event_name == 'workflow_dispatch' && inputs.cleanup-previews)
+        name: Validate Main Reports HTML
+        needs: verify_main_reports
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout published reports
+              uses: actions/checkout@v6
+              with:
+                ref: gh-pages
+                path: gh-pages
+
+            - name: Exclude pull request previews from main validation
+              run: rm -rf gh-pages/previews
+
+            - name: Validate published main reports HTML
+              uses: anishathalye/proof-html@v2
+              with:
+                directory: ./gh-pages
+                disable_external: true
+                check_external_hash: false
+
+    validate_preview_reports_html:
+        if: github.event_name == 'pull_request' && github.event.action != 'closed'
+        name: Validate Pull Request Reports HTML
+        needs: verify_preview_reports
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout published reports
+              uses: actions/checkout@v6
+              with:
+                ref: gh-pages
+                path: gh-pages
+
+            - name: Validate published preview reports HTML
+              uses: anishathalye/proof-html@v2
+              with:
+                directory: ./gh-pages/previews/pr-${{ github.event.pull_request.number }}
+                disable_external: true
+                check_external_hash: false
+
     comment_preview:
         if: github.event_name == 'pull_request' && github.event.action != 'closed'
         name: Comment Pull Request Preview URLs
         needs:
             - reports
             - verify_preview_reports
+            - validate_preview_reports_html
         runs-on: ubuntu-latest
         permissions:
             pull-requests: write
@@ -299,6 +343,8 @@ jobs:
             - reports
             - verify_main_reports
             - verify_preview_reports
+            - validate_main_reports_html
+            - validate_preview_reports_html
             - cleanup_preview
             - cleanup_orphaned_previews
         runs-on: ubuntu-latest
@@ -325,7 +371,9 @@ jobs:
                   echo "- PHP version source: \`${{ needs.resolve_php.outputs.php-version-source }}\`"
                   echo "- Reports job result: \`${{ needs.reports.result }}\`"
                   echo "- Main verification result: \`${{ needs.verify_main_reports.result }}\`"
+                  echo "- Main HTML validation result: \`${{ needs.validate_main_reports_html.result }}\`"
                   echo "- Preview verification result: \`${{ needs.verify_preview_reports.result }}\`"
+                  echo "- Preview HTML validation result: \`${{ needs.validate_preview_reports_html.result }}\`"
                   echo "- Closed-preview cleanup result: \`${{ needs.cleanup_preview.result }}\`"
                   echo "- Orphan cleanup result: \`${{ needs.cleanup_orphaned_previews.result }}\`"
                   echo "- Trigger: \`${TRIGGER_LABEL}\`"
@@ -335,13 +383,15 @@ jobs:
                     echo "- Coverage: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/coverage/"
                     echo "- Metrics: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/metrics/"
                     echo "- Deployment verification: \`${{ needs.verify_main_reports.result }}\`"
+                    echo "- HTML validation: \`${{ needs.validate_main_reports_html.result }}\`"
                   fi
 
                   if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ github.event.action }}" != "closed" ]; then
                     echo "- Preview docs: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/"
                     echo "- Preview coverage: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/coverage/"
                     echo "- Preview metrics: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/metrics/"
                     echo "- Preview verification: \`${{ needs.verify_preview_reports.result }}\`"
+                    echo "- Preview HTML validation: \`${{ needs.validate_preview_reports_html.result }}\`"
                   fi
 
                   if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ github.event.action }}" = "closed" ]; then

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Keep required PHPUnit matrix checks reporting after workflow-managed `.github/wiki` pointer commits by running the pull-request test workflow without top-level path filters and aligning the packaged consumer test wrapper (#230)
 - Ignore intentional Composer Dependency Analyser shadow dependency findings by default while adding `dependencies --show-shadow-dependencies` for audits (#233)
 - Dispatch the required test workflow after wiki preview automation updates a pull-request `.github/wiki` pointer, avoiding permanently pending required checks on bot-authored pointer commits (#230)
+- Validate published main and pull-request report HTML with `proof-html` after GitHub Pages deployment health checks pass (#178)
 
 ## [1.21.0] - 2026-04-24
 

docs/advanced/consumer-automation.rst

@@ -71,7 +71,8 @@ How GitHub Pages Publishing Works
 ---------------------------------
 
 - ``.github/workflows/reports.yml`` runs ``composer dev-tools reports``.
-- The workflow delegates repeated GitHub Pages tasks to
+- The workflow verifies published URLs, validates published HTML with
+  ``proof-html``, and delegates repeated GitHub Pages tasks to
   ``.github/actions/github-pages/*`` instead of keeping that shell logic inline.
 - Pull requests publish previews under ``previews/pr-<number>/``.
 - On the ``main`` branch, GitHub Pages serves the generated site from the root

docs/usage/github-actions.rst

@@ -71,13 +71,17 @@ The ``reports.yml`` workflow is responsible for generating technical documentati
 **Behavior:**
 *   **Main Branch**: Runs all checks and deploys the final reports to the root of the ``gh-pages`` branch.
     *   Runs a post-deploy health check against the published reports index and coverage URLs with retry/backoff to account for Pages propagation.
+    *   Checks out the published ``gh-pages`` content after deployment
+        verification and runs ``proof-html`` against the main reports site,
+        excluding historical pull-request previews from that main-site scan.
     *   Resolves the workflow PHP version from ``composer.lock`` or ``composer.json`` before installing dependencies.
     *   Removes ``.dev-tools/cache`` from the publish directory before deployment so repository-local tool caches never leak into GitHub Pages output.
     *   Appends a run summary with the published docs, coverage, and metrics URLs plus deployment verification status.
 *   **Pull Requests**:
     *   Generates a **Preview** of the documentation, coverage, and metrics.
     *   Deploys the preview to ``gh-pages`` under ``previews/pr-{number}/``.
     *   Verifies the preview index and coverage URLs after deployment before posting preview links.
+    *   Runs ``proof-html`` against the published preview directory before posting preview links.
     *   Posts a **Sticky Comment** on the PR with links to the live preview, coverage report, and metrics site.
     *   Appends a run summary with preview URLs and verification status.
     *   Groups nested command output into collapsible GitHub Actions log sections so docs, tests, and metrics are easier to inspect independently.