lighthouse.yaml

# Eco-design performance audit — Lighthouse CI
#
# Runs Lighthouse against the built VitePress docs to enforce resource budgets
# that directly map to eco-design principles (transfer weight, request count,
# Core Web Vitals, render-blocking resources).
#
# Configuration is in .lhci.config.cjs.
#
# On every pull_request a sticky comment is posted (or updated) with a full
# structured report so reviewers can see the impact of doc changes at a glance.
#
# Strategy:
#   1. Build docs with localhost sitemap URLs.
#   2. Run `bun run docs:lhci` (= `lhci autorun`) (continue-on-error) — LHCI
#      reads all collect/assert/upload options from .lhci.config.cjs, starts
#      the preview server via the locally-installed vitepress binary (no npx),
#      collects 2 runs per URL, asserts budgets, and uploads to temporary-public-storage.
#   3. Run `scripts/generate-lhci-report.ts` — reads .lighthouseci/*.json AND
#      the assertion thresholds from .lhci.config.cjs so dot colours / pass-fail
#      status always mirror what `lhci assert` enforces. Produces:
#        • /tmp/lhci-report.md  — read by the sticky PR comment step
#        • $GITHUB_STEP_SUMMARY — visible in the Actions UI on both PRs and pushes
#   4. Post / update the comment via marocchino/sticky-pull-request-comment
#      (identified by the `lighthouse-ci` header so it is reused across pushes).
#   5. Re-fail the job if `lhci assert` had errors (the report was posted first).
#
# Chrome: Ubuntu latest ships google-chrome-stable. Puppeteer is told to skip
# its own Chromium download and use the system binary instead (~200 MB saved).
name: Eco-design audit (Lighthouse CI)

on:
  pull_request:
    paths:
      - "docs/**"
      - ".bun-version"
      - "package.json"
      - "bun.lock"
      - ".github/workflows/lighthouse.yaml"
      - ".lhci.config.cjs"
      - "scripts/generate-lhci-report.ts"
  workflow_dispatch:

# One audit at a time per branch; cancel stale runs on new push.
concurrency:
  group: lighthouse-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  audit:
    name: Lighthouse performance budgets
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Setup Bun
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
        with:
          bun-version-file: .bun-version

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Build docs (a11y build — sitemap URLs use localhost)
        run: bun run docs:build:a11y

      # Run `lhci autorun` — reads collect/assert/upload config from .lhci.config.cjs.
      # The preview server is started by LHCI itself via ci.collect.startServerCommand
      # (./node_modules/.bin/vitepress — no npx, uses the locally-installed binary).
      # continue-on-error so the report and PR comment are always generated,
      # even when assertions fail — the job is re-failed explicitly below.
      - name: Run Lighthouse CI (eco-design budgets)
        id: lhci
        continue-on-error: true
        env:
          PUPPETEER_EXECUTABLE_PATH: /usr/bin/google-chrome-stable
          PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: "1"
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: bun run docs:lhci

      # Generate the structured Markdown report from .lighthouseci/*.json.
      # scripts/generate-lhci-report.ts reads assertion thresholds directly from
      # .lhci.config.cjs so dot colours and pass/fail status always mirror what
      # `lhci assert` enforces — no hard-coded magic numbers that can drift.
      # Output is written to /tmp/lhci-report.md (read by the PR-comment step)
      # and appended to $GITHUB_STEP_SUMMARY (visible in the Actions UI for
      # both PRs and push runs, with per-category <details> blocks).
      - name: Generate Lighthouse report
        run: |
          bun scripts/generate-lhci-report.ts --out /tmp/lhci-report.md || true
          cat /tmp/lhci-report.md >> "$GITHUB_STEP_SUMMARY"

      # Post or update a single sticky comment per PR identified by `lighthouse-ci`.
      # Uses marocchino/sticky-pull-request-comment which upserts the comment
      # (one create, then updates on every subsequent push to the PR).
      # Reads the report written by the previous step via the `path:` input.
      # continue-on-error: fork PRs get a read-only GITHUB_TOKEN, so posting the
      # comment can fail even when the audit passes. The job summary and the
      # "Fail if LHCI assertions failed" step below still reflect the result.
      - name: Post / update Lighthouse report on PR
        if: github.event_name == 'pull_request'
        continue-on-error: true
        uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5
        with:
          header: lighthouse-ci
          path: /tmp/lhci-report.md

      # Re-fail the job now that the report has been generated and posted.
      # (The LHCI step was marked continue-on-error so the report could always
      # be produced and surfaced to reviewers, even on assertion failure.)
      - name: Fail if LHCI assertions failed
        if: steps.lhci.outcome == 'failure'
        run: |
          echo "::error::Lighthouse CI assertions failed — see report above for details"
          exit 1

      # Upload the full Lighthouse HTML reports as an artifact so failures can
      # be inspected in detail without re-running the workflow.
      - name: Upload Lighthouse reports
        if: always()
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: lighthouse-reports
          path: .lighthouseci/
          if-no-files-found: ignore