Extract web-preview comment renderer to a testable module

[mthines]

The sticky PR comment that displays preview URLs is now rendered by a dedicated, unit-tested module instead of being inlined in the GitHub Actions workflow. This ensures the comment structure — which is a contract with external tooling that scrapes PRs for preview URLs — stays consistent and verifiable.

Summary

Extracted the web-preview comment rendering logic from .github/workflows/web-preview-deploy.yml into scripts/ci/web-preview-comment.mjs, with comprehensive unit tests in scripts/ci/web-preview-comment.test.mjs. The comment deliberately mirrors Vercel's own preview comment structure because external tooling was written to parse that format.

Key changes

• New module scripts/ci/web-preview-comment.mjs: Exports renderReadyComment() and renderErrorComment() functions that generate the sticky comment body. The module includes detailed comments explaining why the table structure matches Vercel's format exactly — the four-column header (Project | Deployment | Actions | Updated), the [Preview](…) link in the Actions cell, and the <relative-time> element are all load-bearing for external scrapers.

• New test file scripts/ci/web-preview-comment.test.mjs: 16 unit tests that verify:

  • The Vercel-shaped table header is present and unchanged
  • The [Preview](…) link is extractable the way external scrapers do it
  • The [Ready](…) link points to the immutable per-commit deployment
  • The <relative-time> element has a parseable ISO datetime
  • The marker line records the full SHA on success, omits it on failure
  • All content (commit link, redeploy hint, workflow logs) survives the reshape
  • Error details are blockquoted with a fallback message
  • Input validation rejects malformed SHAs
  • The workflow still imports and uses this module (not inlined)

• Updated web-preview-deploy.yml: Both the success and failure comment steps now dynamically import and call the renderer functions instead of building the comment inline. The marker find-key is now exported from the module (WEB_PREVIEW_MARKER).

• Updated filter and CI config: Added scripts/ci/web-preview-comment.mjs to the web-preview change filter in both ci.yml and web-preview-filter.test.mjs, since the comment's output is part of the deployed preview machinery. The .test.mjs file is deliberately excluded from the filter (via the \.mjs$ anchor) because test-only edits don't change output.

• Updated documentation: docs/deployment.md now explains why the comment is Vercel-shaped, what parts are reproduced and why, and how the marker is a contract with the "Decide" step.

Implementation details

• The comment format is machine-readable: the marker line <!-- lorekit-web-preview sha=<40 hex> --> is parsed by the "Decide" step to detect whether a redeploy is needed. Failed deploys omit the sha= so the next push re-attempts instead of treating the failed commit as deployed.

• The formatUpdatedLabel() function spells midnight and noon the way Vercel does (12:04am, 12:00pm), and the <relative-time> element includes both an ISO datetime attribute (for parsing) and a human-readable fallback (for emails/API reads).

• The module is imported via pathToFileURL() in the workflow because github-script runs in a Node.js context where dynamic imports need file URLs.

• All three copies of the change filter regex (grep in ci.yml, RegExp in web-preview-filter.mjs, test cases in web-preview-filter.test.mjs) are held in sync by the test file, which now also includes the new path.

https://claude.ai/code/session_01M4KFDkxuzXK9k541xRoc9G

[dash0-dev]

Darkplane auto-approval is enabled for this repository (mode: Auto-approve).

An evaluation will run once this pull request's CI checks have completed — no action needed.

[dash0-dev]

Reviewed your changes — no blocking issues, 1 warning(s): CI still pending.
_{Updated 2026-09-02 14:01 UTC}

Review details

^{Reviewed for commit 38adaba.}

Gate	Status	Details
Description vs. code	✅	The description matches the diff in detail and scope.
Prior review feedback	✅	No prior review comments exist.
Documentation	✅	docs/deployment.md and inline comments explain the change thoroughly.
Self-review signals	✅	No debug logs, leftover TODOs, or unreviewed stubs.
Code review	✅	The multi-lens review found no blocking or non-blocking issues.

CI — Darkplane auto-approval and Web — Vercel preview (changed) / Deploy Vercel preview are pending, not failing; every substantive check (typecheck/test/lint, both new unit-test suites, Storybook, migration/deploy-scope checks) is green.

Run mode — full · 537 lines in delta · 7 files touched — first review of this PR

Memories — 308 indexed (harvested handoff, no live memory access this run)

Quality — produced 0 → posted inline 0 · cleared 0 · carried forward 0 · deferred 0 · below-bar 0

Integrations — not activated

Optimality (2.4c) — ran · 1 judged · 1 optimal · 0 proposal(s) · 0 inline pointer(s) · 0 withheld

Standards (2.4d) — ran · 1 doc · 0 finding(s)

Skipped files — none

^{Reviewed by the pr-reviewer agent — open it to read how these gates and findings are produced.}

[github-actions]

The dashboard preview for this PR — redeployed on each push that changes the web app.

Project	Deployment	Actions	Updated
lorekit	Ready	Preview	Sep 2, 2026 2:10pm UTC

_{Preview always points at this PR's latest commit; Deployment is the immutable build of 38adaba. · Comment /web-preview to force a redeploy. · Deployed on demand. · Workflow logs}

[dash0-dev]

Darkplane did not approve this pull request. It scored 63.58 of 100, and 75 was required.

• 🔴 Change footprint scored 30.
  This is a genuine refactor with functional change to comment output shape (new Vercel-mimicking table format, new marker semantics for failed deploys, embedded in .github/workflows/web-preview-deploy.yml via dynamic import), not a mechanical extract-only move — the rendered markdown structure, status icons, and relative-time cells are newly authored. It touches CI/deploy-adjacent, load-bearing automation (PR commenting and preview-deploy gating regexes in ci.yml and web-preview-filter.mjs), and is backed by new unit tests, but the hand-written formatting logic and altered contract (marker sha= semantics, external-scraper compatibility) make it a non-trivial, judgment-heavy change rather than routine.

The other 2 criteria

• 🟢 Blast radius scored 88.
  The change extracts a previously-inline PR-comment rendering (in web-preview-deploy.yml) into a new, isolated module scripts/ci/web-preview-comment.mjs with its own unit tests, plus small, mechanical filter/CI-config updates to include the new file in existing path-filter regexes and CI test steps. All changes are confined to CI/workflow tooling (no application code, runtime, or data paths touched), the diff is behaviorally equivalent (verified by tests asserting the workflow still renders through the module and that content is preserved), and reverting is a straightforward git revert since no other systems depend on this internal script.
• 🟢 Evidence quality scored 72.
  The PR adds a new module with 16 unit tests (web-preview-comment.test.mjs) and updates related filter tests, and all CI checks are green, including the specific Web-preview filter (unit) and generic Typecheck, Test & Lint (affected) jobs that would cover this code. No human review or approval is present beyond an automated PR-reviewer bot summary reporting no blocking issues; there is no independent maintainer sign-off.

_{An AI evaluator produced these scores from the diff, the repository history, and the pull request text. The pull request text is author-controlled, so treat the scores as signals rather than proof. Reviewed for commit 38adaba.}