@graphty/visual-review 0.0.1 → 0.1.0

package/package.json

@@ -1,12 +1,71 @@
 {
-    "name": "@graphty/visual-review",
-    "version": "0.0.1",
-    "description": "Placeholder: reserves the name so the package can be published through npm trusted publishing. The first real release follows from github.com/graphty-org/graphty-monorepo.",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/graphty-org/graphty-monorepo.git",
-        "directory": "visual-review"
-    },
-    "files": ["README.md"]
-}
+  "name": "@graphty/visual-review",
+  "version": "0.1.0",
+  "description": "Self-hosted visual review of Storybook stories: capture in GitHub Actions, keep the baselines in git (Git LFS), accept or reject each change in a local page, and gate pull requests",
+  "author": "Adam Powers <apowers@ato.ms>",
+  "type": "module",
+  "bin": {
+    "visual-review": "./trusted/cli.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "trusted/",
+    "capture/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphty-org/graphty-monorepo.git",
+    "directory": "visual-review"
+  },
+  "keywords": [
+    "storybook",
+    "visual-regression",
+    "visual-testing",
+    "screenshot",
+    "snapshot",
+    "playwright",
+    "github-actions",
+    "git-lfs",
+    "chromatic-alternative",
+    "review"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/graphty-org/graphty-monorepo/issues"
+  },
+  "homepage": "https://graphty.app/docs/visual-review/",
+  "dependencies": {
+    "pngjs": "7.0.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.49.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "^9.29.0",
+    "playwright": "1.57.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "coverage": "vitest run --coverage",
+    "lint": "eslint . && npm run typecheck",
+    "lint:knip": "cd .. && ./tools/run-knip.sh --workspace visual-review",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/templates/visual-review.yml

@@ -0,0 +1,141 @@
+# Generated by visual-review init (@graphty/visual-review). `visual-review init --force` rewrites
+# this file; change visual-review.config.json rather than this file where you can.
+#
+# Visual review. On every pull request and every push to __BRANCH__, each Storybook named in
+# visual-review.config.json is built, every story is screenshot and compared with its baseline PNG
+# in git, and the results are uploaded as the artifact "visual-<project>-<attempt>" for
+# `visual-review serve`, which finds this workflow by its file name (the config's "workflow") and
+# the capture jobs by their names, "visual (<project>)". A difference never fails a capture job;
+# on a pull request the "Visual gate" job fails while any difference is not accepted, so make
+# "Visual gate" a required status check (Settings, Branches or Rulesets).
+
+name: Visual review
+
+on:
+    pull_request:
+    push:
+        branches: [__BRANCH__]
+
+permissions:
+    contents: read
+
+jobs:
+    # The projects of visual-review.config.json, as the capture job's matrix.
+    plan:
+        name: Plan
+        runs-on: ubuntu-24.04
+        outputs:
+            projects: ${{ steps.plan.outputs.projects }}
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  sparse-checkout: visual-review.config.json
+                  sparse-checkout-cone-mode: false
+
+            - name: List the projects
+              id: plan
+              run: |
+                  echo "projects=$(jq -c '(.baselines // "visual-baselines") as $b
+                      | [.projects | to_entries[] | {project: .key, storybook: .value.storybook,
+                         build: .value.build, baselines: $b}]' visual-review.config.json)" >> "$GITHUB_OUTPUT"
+
+    # continue-on-error: a crash of the tool itself must not fail the run; the gate below judges.
+    visual:
+        name: visual (${{ matrix.project }})
+        needs: plan
+        runs-on: ubuntu-24.04
+        permissions:
+            contents: read
+            # To download the default branch's newest capture (the reference step below).
+            actions: read
+        continue-on-error: true
+        timeout-minutes: 45
+        strategy:
+            fail-fast: false
+            matrix:
+                include: ${{ fromJSON(needs.plan.outputs.projects) }}
+        steps:
+            - uses: actions/checkout@v4
+
+            # Baseline PNGs are Git LFS objects. They are cached by the pointer files' hash, so a run
+            # downloads from LFS only the images accepted since the cache was saved.
+            - name: Restore this project's baseline images
+              uses: actions/cache@v4
+              with:
+                  path: .git/lfs/objects
+                  key: lfs-${{ matrix.project }}-${{ hashFiles(format('{0}/{1}/**/*.png', matrix.baselines, matrix.project)) }}
+                  restore-keys: lfs-${{ matrix.project }}-
+
+            - name: Fetch this project's baseline images from Git LFS
+              run: git lfs pull --include "${{ matrix.baselines }}/${{ matrix.project }}/**"
+
+            # __SETUP__
+
+            - name: Install Chromium
+              run: __CLI__ install-browser
+
+            - name: Build Storybook
+              if: matrix.build
+              run: ${{ matrix.build }}
+
+            # A story with no baseline that looks as it does in the default branch's newest capture is
+            # "unseeded" and does not block this pull request; without a reference every one is "new".
+            - name: Download the default branch's newest capture
+              id: reference
+              if: github.event_name == 'pull_request'
+              continue-on-error: true
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: echo "dir=$(__CLI__ reference --project ${{ matrix.project }} --out "$RUNNER_TEMP/reference")" >> "$GITHUB_OUTPUT"
+
+            - name: Capture
+              run: __CLI__ capture --project ${{ matrix.project }} --out "$RUNNER_TEMP/visual" --reference "${{ steps.reference.outputs.dir }}"
+
+            # Kept even when capture crashed, so the reviewer sees the partial results.json.
+            - name: Upload captures
+              if: always()
+              uses: actions/upload-artifact@v4
+              with:
+                  name: visual-${{ matrix.project }}-${{ github.run_attempt }}
+                  path: ${{ runner.temp }}/visual/
+                  retention-days: 30
+
+            - name: Write the counts to the job summary
+              if: always()
+              run: |
+                  f="$RUNNER_TEMP/visual/results.json"
+                  {
+                      echo "### Visual review (${{ matrix.project }})"
+                      if [[ -f "$f" ]]; then
+                          jq -r '"seeded: \(.seeded), complete: \(.complete), \(.items | length) of \(.expected) items, reference run: \(.reference)",
+                              "", "| status | items |", "|---|---|",
+                              (.items | group_by(.status)[] | "| \(.[0].status) | \(length) |")' "$f"
+                      else
+                          echo "No results.json: capture did not start."
+                      fi
+                  } >> "$GITHUB_STEP_SUMMARY"
+
+    # Fails while a project with baselines on the base branch holds anything but unchanged, excluded
+    # or unseeded items in its newest capture, or a baseline file changed without a review record.
+    # It runs the published gate at a pinned version, so a pull request's own dependencies cannot
+    # change it. Depth 2: HEAD^1, the merge commit's first parent, is the base branch tip.
+    visual-gate:
+        name: Visual gate
+        needs: visual
+        if: always() && github.event_name == 'pull_request'
+        runs-on: ubuntu-24.04
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 2
+                  filter: blob:none
+
+            - name: Download visual captures
+              continue-on-error: true
+              uses: actions/download-artifact@v4
+              with:
+                  pattern: visual-*
+                  path: ${{ runner.temp }}/visual
+
+            - name: Check visual changes were accepted
+              run: npx --yes @graphty/visual-review@__VERSION__ gate --captures "$RUNNER_TEMP/visual" --base HEAD^1 --head HEAD

package/templates/visual-seed.yml

@@ -0,0 +1,144 @@
+# Generated by visual-review init (@graphty/visual-review). `visual-review init --force` rewrites
+# this file; change visual-review.config.json rather than this file where you can.
+#
+# Captures the Storybooks of an older, known-good commit with the default branch's capture tool, so
+# baselines can be seeded from it: `visual-review serve --master-run <this run's id>` lists the run
+# as the default branch, and Finish opens the seed pull request. Dispatch it from __BRANCH__:
+#   gh workflow run visual-seed.yml --ref __BRANCH__ -f ref=<sha>
+# Only the projects whose "seedFromDefaultBranch" is not false are captured. The capture job
+# repeats the "visual" job of the review workflow, except that it has no reference (every story
+# without a baseline is "new") and results.json names the captured commit.
+
+name: Visual seed capture
+
+on:
+    workflow_dispatch:
+        inputs:
+            ref:
+                description: "The commit (or branch or tag) whose Storybooks are captured"
+                required: true
+                type: string
+
+permissions:
+    contents: read
+
+jobs:
+    plan:
+        name: Plan
+        runs-on: ubuntu-24.04
+        outputs:
+            projects: ${{ steps.plan.outputs.projects }}
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  sparse-checkout: visual-review.config.json
+                  sparse-checkout-cone-mode: false
+
+            - name: List the projects
+              id: plan
+              run: |
+                  echo "projects=$(jq -c '(.baselines // "visual-baselines") as $b
+                      | [.projects | to_entries[] | select(.value.seedFromDefaultBranch != false)
+                         | {project: .key, storybook: .value.storybook, build: .value.build, baselines: $b}]' \
+                      visual-review.config.json)" >> "$GITHUB_OUTPUT"
+
+    storybook:
+        name: Build ${{ matrix.project }} at ${{ inputs.ref }}
+        needs: plan
+        runs-on: ubuntu-24.04
+        outputs:
+            sha: ${{ steps.sha.outputs.sha }}
+        strategy:
+            fail-fast: false
+            matrix:
+                include: ${{ fromJSON(needs.plan.outputs.projects) }}
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  ref: ${{ inputs.ref }}
+
+            - name: Resolve the commit
+              id: sha
+              run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+            # __SETUP__
+
+            - name: Build Storybook
+              run: ${{ matrix.build }}
+
+            - uses: actions/upload-artifact@v4
+              with:
+                  name: storybook-${{ matrix.project }}
+                  path: ${{ matrix.storybook }}/
+
+    visual:
+        name: visual (${{ matrix.project }})
+        needs: [plan, storybook]
+        runs-on: ubuntu-24.04
+        timeout-minutes: 45
+        strategy:
+            fail-fast: false
+            matrix:
+                include: ${{ fromJSON(needs.plan.outputs.projects) }}
+        steps:
+            # The default branch's checkout: the capture tool, the config and the baselines come from here.
+            - uses: actions/checkout@v4
+
+            - name: Restore this project's baseline images
+              uses: actions/cache@v4
+              with:
+                  path: .git/lfs/objects
+                  key: lfs-${{ matrix.project }}-${{ hashFiles(format('{0}/{1}/**/*.png', matrix.baselines, matrix.project)) }}
+                  restore-keys: lfs-${{ matrix.project }}-
+
+            - name: Fetch this project's baseline images from Git LFS
+              run: git lfs pull --include "${{ matrix.baselines }}/${{ matrix.project }}/**"
+
+            # __SETUP__
+
+            - name: Install Chromium
+              run: __CLI__ install-browser
+
+            - name: Download Storybook build
+              uses: actions/download-artifact@v4
+              with:
+                  name: storybook-${{ matrix.project }}
+                  path: ${{ matrix.storybook }}/
+
+            - name: Capture
+              run: __CLI__ capture --project ${{ matrix.project }} --out "$RUNNER_TEMP/visual"
+
+            # capture takes the commit from GITHUB_SHA, the default branch's here; a seed Finish branches
+            # from results.json's commit, so it must name the commit whose Storybook was captured.
+            - name: Record the captured commit
+              if: always()
+              env:
+                  SHA: ${{ needs.storybook.outputs.sha }}
+              run: |
+                  f="$RUNNER_TEMP/visual/results.json"
+                  if [[ -f "$f" ]]; then
+                      jq --arg sha "$SHA" '.commit = $sha' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
+                  fi
+
+            - name: Upload captures
+              if: always()
+              uses: actions/upload-artifact@v4
+              with:
+                  name: visual-${{ matrix.project }}-${{ github.run_attempt }}
+                  path: ${{ runner.temp }}/visual/
+                  retention-days: 30
+
+            - name: Write the counts to the job summary
+              if: always()
+              run: |
+                  f="$RUNNER_TEMP/visual/results.json"
+                  {
+                      echo "### Visual seed capture (${{ matrix.project }}) at ${{ needs.storybook.outputs.sha }}"
+                      if [[ -f "$f" ]]; then
+                          jq -r '"complete: \(.complete), \(.items | length) of \(.expected) items",
+                              "", "| status | items |", "|---|---|",
+                              (.items | group_by(.status)[] | "| \(.[0].status) | \(length) |")' "$f"
+                      else
+                          echo "No results.json: capture did not start."
+                      fi
+                  } >> "$GITHUB_STEP_SUMMARY"