website-comment: add per-pull-request website preview actions

.github/workflows/release-actions.yml

@@ -34,10 +34,11 @@ on:
       - "allowlist-check/**"
       - "pelican/**"
       - "stash/**"
+      - "website-comment/**"
   workflow_dispatch:
     inputs:
       action:
-        description: "Tag prefix to release (allowlist-check, pelican, save, restore). Leave empty to auto-detect from the latest commit."
+        description: "Tag prefix to release (allowlist-check, pelican, save, restore, preview-annotate, preview-artifact, preview-main-overlay, preview-publish). Leave empty to auto-detect from the latest commit."
         required: false
         default: ""
       bump:

.github/workflows/website-comment-test.yml

@@ -0,0 +1,224 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+name: Test the PR preview actions
+on:
+  pull_request:
+    paths:
+      - "website-comment/**"
+      - ".github/workflows/website-comment-test.yml"
+  push:
+    # Branches only, so release tag pushes do not re-run it.
+    branches:
+      - main
+    paths:
+      - "website-comment/**"
+      - ".github/workflows/website-comment-test.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  node:
+    name: "publisher, overlay and Astro adapter"
+    runs-on: ubuntu-26.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: "22"
+
+      - name: Install the locked test dependencies
+        working-directory: website-comment
+        run: npm ci --ignore-scripts --no-audit --no-fund
+
+      - name: Unit tests
+        working-directory: website-comment
+        run: npm test
+
+      - name: preview-annotate outputs the Astro plugin
+        id: astro
+        uses: ./website-comment/preview-annotate
+        with:
+          generator: astro
+
+      - name: The plugin path resolves
+        env:
+          PLUGIN: ${{ steps.astro.outputs.vite-plugin }}
+        run: test -f "$PLUGIN"
+
+      - name: A built site
+        run: |
+          mkdir -p "$RUNNER_TEMP/main-site"
+          echo '<html><body><h1 data-preview-src="index.md:1">x</h1></body></html>' > "$RUNNER_TEMP/main-site/index.html"
+
+      - name: preview-main-overlay injects the overlay in main mode
+        uses: ./website-comment/preview-main-overlay
+        with:
+          path: ${{ runner.temp }}/main-site
+          branch: main
+
+      - name: The page loads the overlay, configured for the published site
+        run: |
+          grep -q '_preview/review.js' "$RUNNER_TEMP/main-site/index.html"
+          grep -q '"mode":"main"' "$RUNNER_TEMP/main-site/_preview/review.js"
+
+      - name: preview-publish does nothing outside its events
+        id: gate
+        continue-on-error: true
+        uses: ./website-comment/preview-publish
+        with:
+          site-name: example
+
+      - name: It did not fail
+        if: steps.gate.outcome != 'failure'
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          echo "::error::preview-publish accepted a $EVENT_NAME event"
+          exit 1
+
+      - name: A production site that documents the attribute
+        run: |
+          mkdir -p "$RUNNER_TEMP/docs-site"
+          echo '<html><body><pre><code>&lt;h1 data-preview-src="index.md:1"&gt;</code></pre><p>Stamp data-preview-src in preview builds.</p></body></html>' > "$RUNNER_TEMP/docs-site/index.html"
+
+      - name: preview-annotate accepts escaped and prose mentions
+        uses: ./website-comment/preview-annotate
+        with:
+          generator: none
+          production-output: ${{ runner.temp }}/docs-site
+
+      - name: A production page with the attribute on a tag split across lines
+        run: |
+          mkdir -p "$RUNNER_TEMP/split-site"
+          printf '<html><body><div\n  class="x"\n  data-preview-src="index.md:1">x</div></body></html>\n' > "$RUNNER_TEMP/split-site/index.html"
+
+      - name: preview-annotate rejects it
+        id: split
+        continue-on-error: true
+        uses: ./website-comment/preview-annotate
+        with:
+          generator: none
+          production-output: ${{ runner.temp }}/split-site
+
+      - name: It did not fail
+        if: steps.split.outcome != 'failure'
+        run: |
+          echo "::error::preview-annotate accepted a split-line annotated tag"
+          exit 1
+
+      - name: preview-annotate rejects an unknown generator
+        id: unknown
+        continue-on-error: true
+        uses: ./website-comment/preview-annotate
+        with:
+          generator: gatsby
+
+      - name: It did not fail
+        if: steps.unknown.outcome != 'failure'
+        run: |
+          echo "::error::preview-annotate accepted an unknown generator"
+          exit 1
+
+  # ubuntu-slim cannot start a job container, so Ruby comes from apt rather
+  # than a Ruby image, and no third-party setup-ruby action is added.
+  jekyll:
+    name: "Jekyll adapter, end to end"
+    runs-on: ubuntu-slim
+    permissions:
+      contents: read
+      pull-requests: read # preview-artifact lists the PR's changed files for anchors
+    timeout-minutes: 10
+    env:
+      # Install exactly what the lockfile names, checksums included.
+      BUNDLE_GEMFILE: website-comment/adapters/jekyll/test/Gemfile
+      BUNDLE_FROZEN: "true"
+      FIXTURE: website-comment/adapters/jekyll/test/fixture
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      # eventmachine and friends build native extensions, hence the toolchain.
+      - name: Install Ruby, Bundler and a C toolchain
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y -q --no-install-recommends ruby-full ruby-bundler build-essential
+          ruby --version
+
+      # A writable gem home, so Bundler can switch itself to the version the
+      # lockfile's BUNDLED WITH names, instead of an unpinned `gem install`.
+      - name: Use a user gem home
+        run: |
+          echo "GEM_HOME=$RUNNER_TEMP/gems" >> "$GITHUB_ENV"
+          echo "$RUNNER_TEMP/gems/bin" >> "$GITHUB_PATH"
+
+      - name: Install the locked test dependencies
+        run: bundle install
+
+      - name: Plugin tests
+        run: bundle exec ruby website-comment/adapters/jekyll/test/preview_src_test.rb
+
+      - name: Production build
+        run: bundle exec jekyll build -s "$FIXTURE" -d "$RUNNER_TEMP/production"
+
+      - name: preview-annotate installs the plugin
+        uses: ./website-comment/preview-annotate
+        with:
+          generator: jekyll
+          source: website-comment/adapters/jekyll/test/fixture
+          production-output: ${{ runner.temp }}/production
+
+      - name: Preview build is annotated with repository paths
+        run: |
+          bundle exec jekyll build -s "$FIXTURE" -d "$RUNNER_TEMP/preview"
+          grep -q 'data-preview-src="website-comment/adapters/jekyll/test/fixture/index.md:7"' "$RUNNER_TEMP/preview/index.html"
+
+      - name: preview-annotate rejects an annotated production build
+        id: dirty
+        continue-on-error: true
+        uses: ./website-comment/preview-annotate
+        with:
+          generator: none
+          production-output: ${{ runner.temp }}/preview
+
+      - name: It did not fail
+        if: steps.dirty.outcome != 'failure'
+        run: |
+          echo "::error::preview-annotate accepted an annotated production build"
+          exit 1
+
+      - name: preview-artifact packages the preview
+        if: github.event_name == 'pull_request'
+        uses: ./website-comment/preview-artifact
+        with:
+          path: ${{ runner.temp }}/preview
+          retention-days: 1
+
+      - name: The metadata names this pull request
+        if: github.event_name == 'pull_request'
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          grep -q "\"pr\":$PR_NUMBER," "$RUNNER_TEMP/preview/preview-meta.json"
+          grep -q '"anchors":{' "$RUNNER_TEMP/preview/preview-meta.json"

.gitignore

@@ -70,3 +70,5 @@ approved_patterns.yml
 
 # RAT work dir
 utils/.rat/**
+
+node_modules/

.pre-commit-config.yaml

@@ -113,7 +113,8 @@ repos:
           (?x)
           ^(?:.*/)?AGENTS\.md$|
           ^(?:.*/)?CLAUDE\.md$|
-          ^stash/.*\.md$
+          ^stash/.*\.md$|
+          ^website-comment/adapters/jekyll/test/fixture/
         args:
           - --comment-style
           - "<!--|  |-->"

.rat-excludes

@@ -14,3 +14,11 @@
 # limitations under the License.
 
 **/uv.lock
+# website-comment: vendored MIT library (credited in LICENSE), JSON and lock files
+# that cannot carry a header, and a Jekyll fixture site whose line numbers the
+# adapter's tests assert.
+website-comment/vendor/**
+website-comment/package.json
+website-comment/package-lock.json
+website-comment/adapters/jekyll/test/Gemfile.lock
+website-comment/adapters/jekyll/test/fixture/**

LICENSE

@@ -207,3 +207,12 @@ This product includes code from cache GitHub action in the `stash` directory.
 Copyright (c) 2018 GitHub, Inc. and contributors
 Homepage: https://github.com/actions/cache
 License: The MIT License (MIT): https://raw.githubusercontent.com/actions/cache/refs/heads/main/LICENSE
+
+--------------------------------------------------------------------------------
+
+This product bundles html2canvas-pro 2.4.3 in the `website-comment/vendor/html2canvas-pro`
+directory.
+
+Copyright (c) 2024-present yorickshan and html2canvas-pro contributors
+Homepage: https://github.com/yorickshan/html2canvas-pro
+License: The MIT License (MIT): see website-comment/vendor/html2canvas-pro/LICENSE

README.md

@@ -121,6 +121,7 @@ verification from `verify-action-build` directly.
   - [ASF Infrastructure Pelican Action](/pelican/README.md): Generate and publish project websites with GitHub Actions
   - [Stash Action](/stash/README.md): Manage large build caches
   - [ASF Allowlist Check](/allowlist-check/README.md): Verify workflow action refs are on the ASF allowlist
+  - [Website Comment](/website-comment/README.md): Publish per-pull-request website previews on ASF staging, with a review overlay that links a marked region to its diff line
 
 ## Versioning and Pinning Actions
 
@@ -135,6 +136,10 @@ which you repeat after the `@`:
 | `pelican`             | `apache/infrastructure-actions/pelican@<sha>          # pelican/v1.2.3`        |
 | `stash/save`          | `apache/infrastructure-actions/stash/save@<sha>       # save/v1.2.3`           |
 | `stash/restore`       | `apache/infrastructure-actions/stash/restore@<sha>    # restore/v1.2.3`        |
+| `website-comment/preview-annotate` | `apache/infrastructure-actions/website-comment/preview-annotate@<sha> # preview-annotate/v1.0.0` |
+| `website-comment/preview-artifact` | `apache/infrastructure-actions/website-comment/preview-artifact@<sha> # preview-artifact/v1.0.0` |
+| `website-comment/preview-publish`  | `apache/infrastructure-actions/website-comment/preview-publish@<sha>  # preview-publish/v1.0.0`  |
+| `website-comment/preview-main-overlay` | `apache/infrastructure-actions/website-comment/preview-main-overlay@<sha> # preview-main-overlay/v1.0.0` |
 
 Pinning to a commit SHA with the version in a trailing comment is the
 recommended, [Zizmor](https://zizmor.sh/)-friendly form: the SHA is immutable,

RELEASING.md

@@ -35,6 +35,10 @@ prefix a consumer repeats in the `@ref`:
 | `pelican`                                       | `pelican`        | `pelican/v1.2.3`         |
 | `stash/save`                                    | `save`           | `save/v1.2.3`            |
 | `stash/restore`                                 | `restore`        | `restore/v1.2.3`         |
+| `website-comment/preview-annotate`              | `preview-annotate` | `preview-annotate/v1.2.3` |
+| `website-comment/preview-artifact`              | `preview-artifact` | `preview-artifact/v1.2.3` |
+| `website-comment/preview-publish`               | `preview-publish`  | `preview-publish/v1.2.3`  |
+| `website-comment/preview-main-overlay`          | `preview-main-overlay` | `preview-main-overlay/v1.2.3` |
 
 For every `X.Y.Z` release we also move a **major** tag (`<prefix>/vN`) to the
 same commit, so consumers can track a major line if they prefer.
@@ -62,7 +66,10 @@ on every push to `main` that touches an action's files. The workflow runs
 
 1. Diffs the pushed range and maps changed files to the affected action(s). A
    change under `stash/shared/` releases **both** stash actions, since they
-   import that shared code at runtime.
+   import that shared code at runtime. Likewise `website-comment/adapters/`
+   releases `preview-annotate`; `website-comment/lib/` releases `preview-artifact`,
+   `preview-publish` and `preview-main-overlay`; and `overlay/` and `vendor/`
+   release `preview-publish` and `preview-main-overlay`.
 2. Picks the bump type (see below).
 3. For each affected action, computes the next version from the newest
    existing `<prefix>/vX.Y.Z` tag (the first release seeds `v1.0.0`), creates

scripts/release_actions.py

@@ -72,12 +72,46 @@ class Action:
 
 # The actions this repo publishes.  ``stash/save`` and ``stash/restore`` both
 # import ``stash/shared/mung.py`` at runtime (PYTHONPATH -> ../shared), so a
-# change there releases both.
+# change there releases both.  The ``website-comment/*`` actions run code from
+# sibling directories through ``github.action_path/..``: the annotator the
+# generator adapters, the artifact step the library's metadata writer, and the
+# publisher and main-site overlay the library, the overlay they inject and the
+# vendored screenshot library.
 ACTIONS: tuple[Action, ...] = (
     Action("allowlist-check", "allowlist-check", ("allowlist-check/",)),
     Action("pelican", "pelican", ("pelican/",)),
     Action("save", "stash/save", ("stash/save/", "stash/shared/")),
     Action("restore", "stash/restore", ("stash/restore/", "stash/shared/")),
+    Action(
+        "preview-annotate",
+        "website-comment/preview-annotate",
+        ("website-comment/preview-annotate/", "website-comment/adapters/"),
+    ),
+    Action(
+        "preview-artifact",
+        "website-comment/preview-artifact",
+        ("website-comment/preview-artifact/", "website-comment/lib/"),
+    ),
+    Action(
+        "preview-main-overlay",
+        "website-comment/preview-main-overlay",
+        (
+            "website-comment/preview-main-overlay/",
+            "website-comment/lib/",
+            "website-comment/overlay/",
+            "website-comment/vendor/",
+        ),
+    ),
+    Action(
+        "preview-publish",
+        "website-comment/preview-publish",
+        (
+            "website-comment/preview-publish/",
+            "website-comment/lib/",
+            "website-comment/overlay/",
+            "website-comment/vendor/",
+        ),
+    ),
 )
 
 VALID_BUMPS = ("major", "minor", "patch")