Compare commits

...
Author SHA1 Message Date
Brent Vatne 3ffd22a5af Keep the fake device's state per session in the CI fixture
Base and head capture run in parallel, each on its own simulator, but the
fixture's fake agent-device kept one route, appearance and current session for
all of them. A head screenshot could take the base session's build, so /home
matched its base and the round-trip test intermittently listed five changed
screens instead of six. Each request names its session in the daemon URL; the
fake device now answers from that session's state.
2026-10-15 18:19:32 -07:00
Brent Vatne 2943c63313 Keep the review's counts honest across readers
- The PR comment counts screens whose captures were verified but that got no
  verdict (the comparison did not run or failed) as "N not compared" with a
  yellow result, and says "No compared screen changed" rather than claiming
  nothing changed. Screens never captured stay unlisted.
- A screen accessibility-only on one platform and visibly changed on another is
  listed and saved as the visible change, whichever platform comes first.
- The Viewer's Changes filter has an Accessibility only chip apart from
  Modified, Compare reviews those screens after the visible changes, and the
  focus survives in the URL.
- The agent API reports a failed or misattributed capture as unavailable, as
  the Viewer does, and its index sentence names every status so the parts add
  up to the total.
- A route family is accessibility-only only when every changed member is.
- Report summaries count changes as the comment lists them, map card handles
  take the accessibility-only colour, and the local text names the status.
2026-10-15 18:14:27 -07:00
Brent Vatne 63199bf3d9 Expect Not compared in the hosted report tests
The artifact-report browser tests still expected Source-affected frames for
source changes nobody compared; those screens are now Not compared.
2026-10-15 17:56:22 -07:00
Brent Vatne e291be651b Stop reporting source changes nobody compared
A screen whose source changed but whose screenshots were not compared was
listed as Source-affected: a guess from the code, not something the captures
showed. Explore reports what the captures show, so it is no longer a change.
The PR comment does not list or count it, the agent API reports it as
not-compared rather than modified, saved runs and the reports picker leave it
out, and the Viewer marks it Not compared and drops it from the legend. A
planned capture that failed is still counted as unavailable and named under
Validation.
2026-10-15 17:39:52 -07:00
Brent Vatne 593e3ba689 Always list Accessibility only in the Screens legend
A reader learns the kinds of change from the legend, so it names
Accessibility only even on a report without one, as it does Source-affected.
2026-10-15 17:35:03 -07:00
Brent Vatne 2419d57eb7 Label accessibility-only changes
A modified screen whose screenshots match changed only in what assistive
technology reads: its accessibility tree (a label, a role, an element added to
the tree). It was counted as a plain change in the PR comment, and the Viewer
called it "Changed (not visible)" and left it out of Compare and the Changed
filter. Screen readers and voice control see these changes, so they are now
named and reviewed as their own kind of change:

- The PR comment counts them apart ("3 visual changes · 12 accessibility
  only") and lists them under 🟦 Accessibility only.
- The Viewer marks them "Accessibility only" in blue, with square marks so the
  status does not rest on colour alone. Compare steps through them and Screens'
  Changed filter keeps them.
- What changed lists what assistive technology reads under its own heading:
  every finding on an accessibility-only screen, and label and role findings on
  a screen whose pixels also changed. Highlight says there is nothing to
  outline.
- The agent API reports status "accessibility-only" (sourceStatus "modified")
  and includes it in the changed-screens link. The reports picker counts it.

The report contract is unchanged: the review status stays "modified" and
readers derive the label from the matching screenshots, so earlier reports read
the same way.
2026-10-15 17:29:11 -07:00
Brent Vatne bdd2d8349c Release 0.19.1 2026-10-15 16:00:46 -07:00
Brent Vatne 4d0eddd811 Count only visible changes
A screen whose source changed but whose before and after captures match is
now Unchanged ("No visible change"), not Needs review: Explore reports
visual changes. Needs review is left for comparisons that could not tell.
The PR comment's counts and lists, saved runs, report uploads and the agent
API follow, and reports from before this change read the same way: their
"Source changed; no visible difference was captured" verdict is unchanged.

The agent API's screen counts and status filter use the review verdict the
Viewer and comment show (with sourceStatus kept when it differs), so
status=modified means visibly modified.
2026-10-15 16:00:40 -07:00
Brent Vatne 02f470dde4 README: split Set up CI into PR reviews and comparisons
Set up CI now has two subsections, each with a sentence and a prompt:
Review on every PR (the setup prompt) and Compare any two commits (a prompt
that sets up release comparisons, then the ways to snapshot a release). The
PR setup collapsibles are grouped into five, with Hosted previews first and
the setup steps as one ordered Manual setup; Requirements sit collapsed under
the example report; More is now Additional information.

The explore-setup skill gains a "Compare any two commits" section for the
new prompt to follow, and the readme-refresh skill describes the layout.
2026-10-15 15:38:05 -07:00
Brent Vatne a0f192b1d7 README: answer how to explore a release
The comparison section opens with the ways to snapshot a release or release
candidate (on demand from the Actions tab, automatically on every tag, or on
your machine), titled "Explore a release or release candidate, or any two
commits".
2026-10-15 15:24:25 -07:00
Brent Vatne d9137f1647 README: show the reports picker at the top level
Review a change before you push it had been placed between Try it on your
app's prompt and its collapsibles, so two "Run it yourself" sections sat
together. It now follows Try it on your app, with the reports picker image
at the top level of the section instead of inside a collapsible. The
readme-refresh skill's outline says the same.
2026-10-15 14:15:14 -07:00
Brent Vatne 4481b50fc7 Review any two commits, in CI or on your machine (#1)
Adds explore-compare.yml and capture:review --compare for reviews without a PR; local reviews with capture:review (worktrees, local logins, capture cache, local Viewer with the agent API); report:upload and expo-explore reports (saved runs and a terminal picker); and moves the workflows' inline logic into ci:* commands. Release 0.19.0.
2026-10-15 14:01:56 -07:00
98 changed files with 4695 additions and 703 deletions

No files matched your search

+29 -10
View File
@@ -2,7 +2,7 @@
How a review runs, from the pull request event to the Viewer link, and how the same pipeline runs locally. Readers who want the user-facing instructions should start with the [CI quick start](docs/quickstart-ci.md); this file is the map of the implementation.
Source of truth: `templates/explore-review.yml`, `templates/explore-baseline.yml`, `action.yml`, `src/ci/pipeline.ts`, `src/ci/verified-plan.ts`, `src/capture/run.ts`, `src/capture/route-capture.ts`, `src/capture/agent/*`, `test/ci/run.mjs`.
Source of truth: `templates/explore-review.yml`, `templates/explore-baseline.yml`, `templates/explore-compare.yml`, `action.yml`, `src/ci/pipeline.ts`, `src/ci/verified-plan.ts`, `src/capture/run.ts`, `src/capture/route-capture.ts`, `src/capture/agent/*`, `test/ci/run.mjs`.
## At a glance
@@ -35,22 +35,23 @@ Older setups vendored the tools into `.github/vendor/expo-explore` and pinned th
| --- | --- | --- | --- |
| `explore-review.yml` | `pull_request_target` (opened, synchronize, reopened, ready_for_review), `workflow_dispatch` with `pr=N` | Open, non-draft, same-repository PR whose author has write access or is listed in `ci.trustedAuthors` | Captures base and head, compares, packages a report, comments on the PR |
| `explore-baseline.yml` | `push` to the default branch, `workflow_dispatch` | Default branch only | Captures every route of one commit per configured platform and uploads `explore-baseline-<sha>-<platform>` for later PRs to reuse |
| `explore-compare.yml` | `workflow_dispatch` or `workflow_call` with `base` and `head` (branch, tag or SHA) | Whoever can run or call workflows (write access) | Captures base and head, compares, packages a report like a PR review (`capture:review --compare`), and links it from the run summary; no PR comment |
Both workflows start with a `platforms` job: it installs the pinned CLI and runs `expo-explore config:platforms`, whose JSON list (`["ios"]`, `["ios","android"]`) becomes the matrix of the capture, report, and baseline jobs (`fail-fast: false`). Every matrix job passes `--platform ${{ matrix.platform }}`, so one platform's failure neither cancels nor hides the other's report.
Each workflow starts with a `platforms` job: it installs the pinned CLI and runs `expo-explore config:platforms`, whose JSON list (`["ios"]`, `["ios","android"]`) becomes the matrix of the capture, report, and baseline jobs (`fail-fast: false`). Every matrix job passes `--platform ${{ matrix.platform }}`, so one platform's failure neither cancels nor hides the other's report.
### 2.2 `explore-review.yml`
| Job | Step | What it does |
| --- | --- | --- |
| capture (matrix: platform) | Resolve the live pull request and authorize its source | Reads the PR through the API. Forks, drafts and authors without write access (unless listed in `ci.trustedAuthors` of the default branch's `config.yaml`, read through the API) fail with `SOURCE_NOT_TRUSTED`. Writes `explore-pr.json` (repository, number, base/head ref and SHA). |
| platforms | Install Explore, resolve and authorize the live pull request | As in the capture job below; it exports the PR's number and commits so the failure job can comment even when a capture job fails before resolving the PR itself. Then checks out head and lists the platforms. |
| capture (matrix: platform) | Install Explore | Validates `EXPLORE_VERSION`, `npm pack`s that release into `$TOOLS_PREFIX`, then `npm ci --omit=dev --include=optional --ignore-scripts` against the release's shrinkwrap. The agent runtimes and `eas-cli` are optional dependencies, so `--include=optional` is what makes capture possible. The step is defined once per workflow file (a YAML anchor) and reused in every job. |
| | Resolve and authorize the live pull request | `ci:pr` reads the PR through the API. Forks, drafts and authors without write access (unless listed in `ci.trustedAuthors` of the default branch's `config.yaml`, read through the API) fail with `SOURCE_NOT_TRUSTED`. Writes `explore-pr.json` (repository, number, base/head ref and SHA) and the step outputs. Runs before any PR code is checked out. |
| | checkout `app-base`, `app-head` | Checks out the exact base and head SHAs with full history and without persisted credentials. |
| | Install Explore | Validates `EXPLORE_VERSION`, `npm pack`s that release into `$TOOLS_PREFIX`, then `npm ci --omit=dev --include=optional --ignore-scripts` against the release's shrinkwrap. The agent runtimes and `eas-cli` are optional dependencies, so `--include=optional` is what makes capture possible. |
| | Verify deterministic source planning | `source:verify` builds the capture plan from source alone in two fresh processes and compares the bytes. Runs before any build or simulator work and needs no credentials. |
| | Install app dependencies | `npm ci --ignore-scripts` in both checkouts (`APP_INSTALL_DIR` for monorepos). |
| | Find / Download optional exact-base evidence | Looks for a successful `explore-baseline-<base sha>-<platform>` artifact (iOS also accepts the older unsuffixed `explore-baseline-<base sha>`) from the baseline workflow on the default branch and downloads it as `EXPLORE_CAPTURE_CACHE`. Missing evidence is not an error. |
| | Capture review | `capture:review` (§3). `EXPO_TOKEN`, the provider key and the app's `{{secret:NAME}}` values reach only this step. The sticky PR comment is updated while it runs. |
| | Stop retained capture sessions | `always()`: stops the EAS Simulator sessions named in `head-session` / `base-session`, nothing else. |
| | Verify application checkouts remain clean | A capture that modified an app checkout fails with `CHECKOUT_MODIFIED`. |
| | Find / Download optional exact-base evidence | `ci:find-baseline` looks for a successful `explore-baseline-<base sha>-<platform>` artifact (iOS also accepts the older unsuffixed `explore-baseline-<base sha>`) from the baseline workflow on the default branch and downloads it as `EXPLORE_CAPTURE_CACHE`. Missing evidence is not an error. |
| | Capture review | `capture:review` (§3). `EXPO_TOKEN`, the provider key and the app's `{{secret:NAME}}` values reach only this step. The sticky PR comment is updated while it runs. It writes `preview=<hosting>` to the step outputs, which decides whether the deploy job runs. |
| | Stop capture sessions and check the checkouts | `ci:after-capture`, whenever the PR was resolved, success or not: stops the EAS Simulator sessions named in `head-session` / `base-session`, nothing else, then fails with `CHECKOUT_MODIFIED` if capture modified an app checkout. |
| | Upload captured review / diagnostics | `explore-capture-<run>-<attempt>-<platform>` feeds the report job. On failure `explore-diagnostics-<run>-<attempt>-<platform>` keeps plans, exports and agent diagnostics for 7 days. |
| report (matrix: platform) | Install Explore, download the capture | Runs without Expo or model credentials. |
| | Package hosted review bundle | `ci:report` writes the report directory. |
@@ -63,7 +64,11 @@ A reviewer downloads the report ZIP and drops it on the hosted Viewer; downloadi
### 2.3 `explore-baseline.yml`
Validate baseline source → Install Explore → Verify deterministic source planning (base = head = this SHA) → Install app dependencies → Capture complete single-commit baseline (`capture:baseline`; any missing route fails the job) → Stop retained baseline session → Verify application checkout remains clean → Upload exact-commit baseline evidence (`explore-baseline-<sha>`, 30 days) and, on failure, `explore-baseline-diagnostics-<run>-<attempt>`.
Validate baseline source → Install Explore → Verify deterministic source planning (base = head = this SHA) → Install app dependencies → Capture complete single-commit baseline (`capture:baseline`; any missing route fails the job) → Stop the capture session and check the checkout (`ci:after-capture`) → Upload exact-commit baseline evidence (`explore-baseline-<sha>`, 30 days) and, on failure, `explore-baseline-diagnostics-<run>-<attempt>`.
### 2.4 `explore-compare.yml`
The same jobs as a PR review, for any `base` and `head` without a pull request. The `platforms` job resolves both refs once with `ci:compare-refs` (a tag wins over a branch of the same name; the same commit twice fails with `COMPARE_SAME_COMMIT`) and passes the comparison to the capture jobs, which run `capture:review --compare` with no GitHub requests. The optional `scope` and `expires-in` inputs override `exploration.scope` and `report.preview.expiresAfter` for that run. The report job's `ci:publish` writes each platform's **Open** and **zip** links to the run summary, and the deploy job adds the hosted link there; nothing comments on a pull request.
## 3. Inside `capture:review` (`runCiReview`)
@@ -134,10 +139,24 @@ A failure at any stage is recorded in `state.failure`, a partial report is writt
| Source change \ evidence | Differs | Same | Not comparable |
| --- | --- | --- | --- |
| Route added / removed | Added / Removed | Added / Removed | Added / Removed |
| Screen source changed (`screen`) | Modified | Needs review | Needs review |
| Screen source changed (`screen`) | Modified | Unchanged (not counted as a change) | Needs review |
| Only app-wide inputs changed (`app-wide`) | Modified | Unchanged (one line in the PR comment) | Needs review |
| No source change (`none`) | Screen variant (listed apart from Changes) | Unchanged | Unchanged |
A screen whose source changed but whose screenshots were not compared (it is outside the capture scope) has no
verdict: the PR comment does not list it, the agent API reports `not-compared`, and the Viewer marks it Not compared.
Earlier versions listed it as Source-affected. A planned capture that failed is counted as unavailable and named under
Validation.
"Differs" means the screenshots differ or the accessibility tree does. A Modified screen whose screenshots match is
**Accessibility only**: what screen readers and voice control read changed (a label, a role, an element added to the tree)
but nothing shows in the capture. It is still a change: the PR comment counts it apart ("3 visual changes · 12
accessibility only") under 🟦 Accessibility only, the Viewer marks it blue and Compare steps through it, and the agent API
reports `status: "accessibility-only"` with `sourceStatus: "modified"`. The report contract is unchanged (its review
status stays `modified`), so earlier reports read the same way. The accessibility tree can include content outside the
screenshot, such as rows scrolled below the fold or elements under a sheet, so an accessibility-only change is not always
invisible on a device.
A pixel mismatch that rounds to 0.00% is noise and counts as "same". Diff regions inside the status-bar band are excluded from the verdict and reported as `ignoredStatusBarRegions`; the Viewer marks that band in Compare.
## 7. Local CI test
+151 -63
View File
@@ -9,6 +9,17 @@ Explore maps your app: a screenshot of every screen, connected by the taps betwe
**See a real report:** [euxy](https://explore-example--euxy.expo.app/p/rfcoic27ccgnrmzgijubxkmuzmptcrva?platform=ios), a MIDI sequencer, reviewed by Explore. It is redeployed with the current Viewer on every merge to main.
<details>
<summary><strong>Requirements</strong></summary>
- An iOS app, an Android app, or both. Explore is in v0; Android capture is newer than iOS.
- Expo SDK 57 or newer, with Expo Router (57 or newer) or React Navigation (6 or newer).
- An EAS build profile per platform: `ios.simulator: true` for iOS, `android.buildType: apk` for Android. Its EAS environment cannot have secret-visibility variables.
- EAS Simulator access (in preview, [join the waitlist](https://expo.dev/services/simulators)).
- Node.js 24.12 or newer, and admin access to the GitHub repository.
</details>
## Try it on your app
Paste this into Claude Code or Codex from your app's directory. It explores a build you point to, or an Expo project straight from its source:
@@ -70,15 +81,55 @@ npx @expo/explore explore:session <session-id> --env-file path/.env.eas-simulato
<details>
<summary><strong>What a run without source shows</strong></summary>
One card per screen the run reached, laid out by how many taps it took, with the tapped control on each edge. There is no before and after; that needs [CI](#set-up-ci-reviews-on-every-pr).
One card per screen the run reached, laid out by how many taps it took, with the tapped control on each edge. There is no before and after; that needs [CI](#set-up-ci).
![The Map of an exploration report for the euxy app: one card per screen the run reached, laid out by taps from the launch screen, each edge labelled with the control that was tapped](docs/screenshots/readme-exploration-light.png)
</details>
## Set up CI: reviews on every PR
### Review a change before you push it
Paste this into Claude Code or Codex from your app's repository:
Once Explore is [set up](#set-up-ci) (`.expo-explore/config.yaml` committed), the review a PR gets also runs on your machine, between any two commits. No tokens or keys to set: it uses your `eas login` and your Claude Code or Codex login.
```text
Review my current changes with Expo Explore. Follow the "Review a change on this machine"
section of https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md, compare my
branch (with my uncommitted changes) against main, and open the report.
```
Every run is kept on your machine for 30 days. `npx @expo/explore reports` lists your local reviews, explorations and uploaded reports with their commits, and reopens or hosts one without capturing again:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-reports-dark.png">
<img alt="npx @expo/explore reports in a terminal: the Expo Explore wordmark, then one line per saved run (a local review of HEAD vs main selected, an exploration of an app, and PR #1), and below them the selected run's head and base commits with their messages and its 13 modified, 2 added, 2 removed and 17 need-review screens" src="docs/screenshots/readme-reports-light.png">
</picture>
<details>
<summary><strong>Run it yourself</strong></summary>
```sh
npx @expo/explore capture:review # HEAD against where it left the default branch
npx @expo/explore capture:review --uncommitted # your uncommitted changes too
npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all --upload
```
- It checks out both commits as temporary worktrees, installs their dependencies, captures every configured platform on EAS Simulator (`--platform` picks one), and opens the report in a local Viewer. `--upload` hosts it and prints the link; `report:upload <report.zip>` hosts one you already have.
- Your checkout, index and branches are never touched. `--uncommitted` takes tracked changes only; `--include-untracked` adds untracked files, which are uploaded with the EAS build.
- It runs both commits' code on your machine, as you: installing their dependencies, evaluating the app config, and bundling the JavaScript. That is what checking them out and running them would do, so review only commits you would run, and someone else's branch only if you trust it.
- Installs run without credential environment variables, which keeps tokens out of reach of a registry a commit's `.npmrc` names; that is not a sandbox. A registry that needs `${NPM_TOKEN}` in the project's `.npmrc` must be authenticated in your own `~/.npmrc`.
- Captures are cached in `~/.cache/expo-explore`, so the same base is not captured twice (`--no-cache` skips it); a capture unused for 30 days goes, and the cache stays under 2 GB. Ctrl+C stops the run's simulator sessions.
- Like a CI review, it builds on EAS (reusing a matching build) and runs simulator sessions: expect several minutes and EAS usage.
- Saved runs take up to 2 GB in all, the oldest going first. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
</details>
## Set up CI
Explore runs in your repository's GitHub Actions in two ways, both from the same setup: a review on every pull request, and a comparison of any two commits, such as a release against the last one.
### Review on every PR
Each pull request gets a comment linking its report: the screens it added, removed or changed, before and after, on each platform you capture. Paste this into Claude Code or Codex from your app's repository:
```text
Set up this app for Expo Explore CI reviews. Follow
@@ -90,44 +141,45 @@ what to merge and how to start the first review.
```
<details>
<summary><strong>Requirements</strong></summary>
<summary id="hosted-previews"><strong>Hosted previews</strong></summary>
- An iOS app, an Android app, or both. Explore is in v0; Android capture is newer than iOS.
- Expo SDK 57 or newer, with Expo Router (57 or newer) or React Navigation (6 or newer).
- An EAS build profile per platform: `ios.simulator: true` for iOS, `android.buildType: apk` for Android. Its EAS environment cannot have secret-visibility variables.
- EAS Simulator access (in preview, [join the waitlist](https://expo.dev/services/simulators)).
- Node.js 24.12 or newer, and admin access to the GitHub repository.
By default reviewers download the report from GitHub. With hosted previews, the comment's **Explore report** link opens it in one click, even in private repositories.
```yaml
report:
preview:
hosting: eas # default: off
expiresAfter: 30d # default 30d, max 365d, or never
# project: acme-explore # default <repository name>-explore, created on first run
```
- Run `expo-explore setup --workflows` after enabling it to add the `deploy` job.
- A [comparison of two commits](#compare-any-two-commits) links its hosted report from the run's summary instead of a PR comment. `capture:review --upload` on your machine deploys to the same project with your `eas login`.
- `expo-explore report:upload <report.zip>...` hosts reports already on your machine the same way: a review's reports (one per platform, from `capture:review --output` or a downloaded `explore-review` artifact) or an `explore:binary` report.
- `EXPO_TOKEN` must be able to create the EAS project, so use a [robot user's](https://docs.expo.dev/accounts/programmatic-access/) token.
- The report is encrypted, and only a request carrying the link's token can open it. Treat the link like a shared file link; see [report access](docs/private-review.md#hosted-previews).
</details>
<details>
<summary><strong>After setup: your first review</strong></summary>
<summary><strong>Manual setup</strong></summary>
1. Set the repository secrets that `expo-explore doctor` lists, such as `EXPO_TOKEN`.
2. Merge the setup to the default branch and run **Expo Explore baseline** from GitHub Actions.
3. Open a PR. **Expo Explore review** runs and posts a comment with the report.
The prompt above walks through these steps with you. To do them yourself:
```sh
expo-explore doctor # check every step; exits 1 until ready
expo-explore doctor --capture # capture the committed app on EAS once, before the first PR
```
1. Run `npx @expo/explore setup` in your app's directory (in a monorepo, add `--project apps/mobile`). It writes `.expo-explore/config.yaml` and the workflows.
2. Run `npx @expo/explore doctor` and fix each problem it reports, until it exits 0. `doctor --capture` captures the committed app on EAS once, to check every screen before your first PR.
3. Set the repository secrets `doctor` lists:
- `EXPO_TOKEN`: create it in [Expo access tokens](https://expo.dev/settings/access-tokens). For [hosted previews](#hosted-previews), use a [robot user](https://docs.expo.dev/accounts/programmatic-access/) that can create projects.
- A secret for each `{{secret:NAME}}` in your setup steps. Run `npx @expo/explore setup --workflows` after you add one.
4. Commit, merge to the default branch, and run **Expo Explore baseline** from GitHub Actions.
5. Open a PR. **Expo Explore review** runs and posts a comment with the report. To see a whole review of your branch first, run `npx @expo/explore capture:review` on your machine.
A failed run shows an error code and a next action in the PR comment; see [CI troubleshooting](docs/quickstart-ci.md#diagnose-a-failed-run).
</details>
<details>
<summary><strong>Set up without a coding agent</strong></summary>
```sh
npx @expo/explore setup # writes .expo-explore/config.yaml and the two workflows; in a monorepo: --project apps/mobile
npx @expo/explore doctor # fix each problem it reports, then commit
```
</details>
<details>
<summary><strong>Choose a capture mode</strong></summary>
<summary><strong>Capture modes: deterministic or agent</strong></summary>
| | **Deterministic** (recommended to start) | **Agent** |
| --- | --- | --- |
@@ -138,10 +190,7 @@ npx @expo/explore doctor # fix each problem it reports, then commit
Both modes use the same comparison rules and report. You can change modes later.
</details>
<details>
<summary><strong>Configure agent mode</strong></summary>
**To use agent mode:**
1. Create an [Anthropic](https://platform.claude.com/settings/keys) or [OpenAI](https://platform.openai.com/api-keys) API key.
2. Set `mode: agent` and an `agent.model` your account can use.
@@ -153,15 +202,7 @@ The model navigates and recovers on each uncaptured revision; see [agent usage](
</details>
<details>
<summary><strong>Repository settings</strong></summary>
- `EXPO_TOKEN`: create it in [Expo access tokens](https://expo.dev/settings/access-tokens). For [hosted previews](#hosted-previews), use a [robot user](https://docs.expo.dev/accounts/programmatic-access/) that can create projects.
- A secret for each `{{secret:NAME}}` in your setup steps. Run `expo-explore setup --workflows` after you add one.
</details>
<details>
<summary id="platforms"><strong>Android and several platforms</strong></summary>
<summary id="platforms"><strong>iOS, Android, or both</strong></summary>
`app.platform` names the primary platform, and a `platforms` map adds the other. Each entry can set its own `device`, `bundleId`, and `easProfile`.
@@ -186,31 +227,76 @@ platforms:
</details>
<details>
<summary id="hosted-previews"><strong>Hosted previews</strong></summary>
By default reviewers download the report from GitHub. With hosted previews, the comment's **Explore report** link opens it in one click, even in private repositories.
```yaml
report:
preview:
hosting: eas # default: off
expiresAfter: 30d # default 30d, max 365d, or never
# project: acme-explore # default <repository name>-explore, created on first run
```
- Run `expo-explore setup --workflows` after enabling it to add the `deploy` job.
- `EXPO_TOKEN` must be able to create the EAS project, so use a [robot user's](https://docs.expo.dev/accounts/programmatic-access/) token.
- The report is encrypted, and only a request carrying the link's token can open it. Treat the link like a shared file link; see [report access](docs/private-review.md#hosted-previews).
</details>
<details>
<summary><strong>Keep your setup current</strong></summary>
- A PR that adds a guarded screen or a dynamic route should also update `config.yaml`.
- Renamed identifiers or labels break deterministic setup steps.
- To update Explore, run `npx @expo/explore@latest setup --workflows` and commit the new version.
- To update Explore, run `npx @expo/explore@latest setup --workflows` and commit the new version. It also adds `explore-compare.yml` if you don't have it, and `doctor` warns when it is missing.
</details>
### Compare any two commits
A release, a release candidate, a nightly: any two branches, tags or commits, reviewed like a PR without one, with the report linked from the run's summary. Once CI reviews PRs, paste this into Claude Code or Codex:
```text
Set up Expo Explore to review this app's releases. Follow the "Compare any two commits"
section of https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md: make sure
explore-compare.yml is installed, add a workflow that compares each release tag (and
release candidate) with the last stable release, then run it once on the latest tag and
give me the report link.
```
There are a few ways to snapshot a release:
- **On demand:** in your repository's Actions tab, open **Expo Explore compare**, choose **Run workflow**, and set `base` to the last release's tag (`v1.3.0`), `head` to the new tag or release candidate (`v1.4.0-rc.1`), `scope` to `all` and `expires-in` to `never`. The run's summary links the report.
- **Automatically, on every tag:** add the `release-review.yml` in [The comparison workflow](#compare) below. It compares each tag, release candidates included, with the last stable tag, so a release candidate is reviewed against what people have now.
- **On your machine, without CI:** `npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all --upload`, with your `eas login`. `npx @expo/explore reports` lists the runs you have kept.
`scope: all` captures every screen, not only those whose source changed, so the report shows the whole release with what changed since the last one marked; `expires-in: never` keeps its link.
<details>
<summary id="compare"><strong>The comparison workflow</strong></summary>
`.github/workflows/explore-compare.yml` reviews a `head` against a `base`, each a branch, tag or commit SHA, with no pull request. It captures, compares and reports exactly like a PR review, and links the report from the run's summary.
Run it from the Actions tab, or call it from a workflow on any event:
```yaml
# .github/workflows/release-review.yml: each release tag (or release candidate) against the last stable release
on:
push:
tags: ['v*']
jobs:
previous:
runs-on: ubuntu-latest
outputs: { tag: '${{ steps.tag.outputs.tag }}' }
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
# The newest earlier tag that is not a prerelease (v1.4.0-rc.1 has a "-"); none for the first release.
- id: tag
run: echo "tag=$(git describe --tags --abbrev=0 --exclude '*-*' "$GITHUB_REF_NAME^" 2>/dev/null || true)" >> "$GITHUB_OUTPUT"
explore:
needs: previous
if: needs.previous.outputs.tag != ''
permissions: { contents: read, actions: read }
uses: ./.github/workflows/explore-compare.yml
with:
base: '${{ needs.previous.outputs.tag }}'
head: '${{ github.ref_name }}'
scope: all # every screen, not only those whose source changed
expires-in: never # keep the hosted link (with report.preview.hosting: eas)
secrets: inherit
```
- Pick whatever `base` the event calls for: `main` for a release branch, yesterday's tag for a nightly, the last stable tag for a release candidate.
- `scope` and `expires-in` are optional and override `exploration.scope` and `report.preview.expiresAfter` for that run. Without them a comparison captures what a PR review would (`scope: changes` captures only screens whose source changed), and the hosted link expires like a PR's.
- The run summary links each platform's report (**Open** and **zip**, like a PR comment) and, with hosting, the hosted report.
- `setup --workflows` installs it from 0.19.0; `npx @expo/explore@latest setup --workflows` adds it to an existing setup. The caller grants `contents: read` and `actions: read`; `secrets: inherit` passes `EXPO_TOKEN` and any app-test secrets.
- Call it once per workflow run. A called workflow runs inside its caller's run, so a second call in the same run would reuse the first one's artifact names; use separate workflows instead.
- When the baseline workflow captured `base` in the last 30 days, that capture is reused and only `head` is captured. The report artifact is kept 30 days; only a hosted link with `expires-in: never` lasts longer.
</details>
@@ -301,7 +387,7 @@ The same link answers differently depending on who asks. It already carries the
- A browser gets the Viewer.
- Anything that does not ask for HTML (`curl`, `fetch`, agents' URL tools) gets a Markdown index of the report, also at `/llms.txt`.
- The index links to a read-only JSON API under `/api/v1`: `/screens?status=modified,added,removed`, `/screens/<id>`, `/transitions`, and `/raw` for the report file.
- The index links to a read-only JSON API under `/api/v1`: `/screens?status=modified,accessibility-only,added,removed`, `/screens/<id>`, `/transitions`, and `/raw` for the report file.
- Reports without source also expose `/journeys`, `/gaps`, and `/frontier`.
- Multi-platform reports take `?platform=ios|android`. Expired links answer `410`.
@@ -311,7 +397,7 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
</details>
## More
## Additional information
<details>
<summary><strong>How it works</strong></summary>
@@ -322,6 +408,8 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
4. It compares the captures. A screen with a source change is **Modified** if its captures differ.
5. It uploads the report to GitHub Actions and posts a PR comment.
The same review runs for any two commits without a PR ([`explore-compare.yml`](#compare-any-two-commits), linking the report from the run summary) and on your machine (`capture:review`, [above](#review-a-change-before-you-push-it)). The workflows' logic lives in `expo-explore ci:*` commands, so a fix reaches CI with the `@expo/explore` version the workflows pin.
Reports and baselines are kept for 30 days and diagnostics for 7. Hosted deployments are never deleted automatically; see [report access](docs/private-review.md).
</details>
+8 -5
View File
@@ -164,7 +164,7 @@ imported source changed), `app-wide` (only app-wide inputs such as dependencies,
| Source \ Evidence | Differs | No visible difference | Inconclusive |
| --- | --- | --- | --- |
| Added / removed route | Added / Removed | Added / Removed | Added / Removed |
| Screen source changed | Modified | Needs review | Needs review |
| Screen source changed | Modified | Unchanged (not counted as a change) | Needs review |
| Only app-wide inputs changed | Modified | Unchanged (the PR comment names the app-wide change once) | Needs review |
| Source unchanged | Screen variant | Unchanged | Unchanged |
@@ -172,13 +172,16 @@ imported source changed), `app-wide` (only app-wide inputs such as dependencies,
| --- | --- |
| Added / Removed | Route presence differs between source inventories |
| Modified | The screen's source changed and comparable evidence differs |
| Needs review | The screen's source changed but no visible difference was captured, or its evidence is inconclusive; still a review target |
| Accessibility only | Modified, but the screenshots match: only the accessibility tree (what screen readers and voice control read) differs. Counted as a change and listed apart from the visual ones |
| Needs review | The screen's source changed and the comparison could not tell whether it looks different; a review target |
| Screen variant | No source change reaches the screen, but its captures differ in runtime UI state (balances, timestamps, loaded content). Listed apart from changes |
| Source-affected | Source impact without a comparison |
| Unchanged | No visible difference and no screen-specific source change |
| Not compared | No comparison was performed |
| Unchanged | No visible difference, whether or not the screen's source changed. Explore reports visual changes; reports before 0.19.1 called a source change with no visible difference Needs review |
| Not compared | No comparison was performed, including for a screen whose source changed. Not counted as a change: Explore reports what the captures show, not what the code might do. Earlier versions listed these as Source-affected |
A difference that rounds to 0.00% of pixels is rendering noise and counts as no difference.
Accessibility only is how readers present a `modified` verdict whose visual verdict is `unchanged`; the contract has no
separate status for it, so reports from earlier versions show it too. The accessibility tree can include content outside
the screenshot (rows below the fold, elements under a sheet), so such a change may still be visible on a device.
A runtime difference is not proof that the code change caused it. Deterministic mode uses template notes and evidence facts. Agent mode adds AI explanations from the captured evidence and source changes through a separate CLI session; those explanations cannot override fixed verdicts. Structural flows describe possible source navigation; semantic business grouping remains deferred.
## Artifacts and cache
+2 -2
View File
@@ -319,13 +319,13 @@ The capture and publishing jobs use Expo and GitHub credentials. The review work
Older setups committed a copy of the tools to `.github/vendor/expo-explore` and pinned it with an `EXPLORE_TOOLS_COMMIT` repository variable. `expo-explore doctor` reports these: delete the directory and both workflows, rerun `expo-explore setup --workflows`, and delete the variable.
## 3. Install the two workflows
## 3. Install the workflows
```sh
expo-explore setup --workflows
```
Install these on the default branch. Remove superseded Explore workflows to prevent duplicate captures and comments.
This writes `explore-review.yml` (pull requests), `explore-baseline.yml` (the default branch) and `explore-compare.yml` (any two commits, from the Actions tab or another workflow; see [Review any two commits](../README.md#compare)). Install these on the default branch. Remove superseded Explore workflows to prevent duplicate captures and comments.
Both templates use `APP_PROJECT_DIR` and `APP_INSTALL_DIR`, defaulting to `.`. For a monorepo, the project directory might be `apps/mobile` while the lockfile/install directory remains `.`. Keep config paths relative to the app. `expo-explore setup --workflows` replaces `npm ci --ignore-scripts` with the frozen-lockfile install of the package manager whose lockfile it finds: pnpm, Yarn, or bun. For bun it also adds an `oven-sh/setup-bun` step, because the runner does not have bun.
Binary file not shown.

After

Width:  |  Height:  |  Size: 169 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 179 KiB

+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "@expo/explore",
"version": "0.18.1",
"version": "0.19.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@expo/explore",
"version": "0.18.1",
"version": "0.19.1",
"license": "MIT",
"dependencies": {
"@expo/repack-app": "0.10.1",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.18.1",
"version": "0.19.1",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
+78
View File
@@ -0,0 +1,78 @@
// Renders `expo-explore reports` over the saved runs in $EXPLORE_CACHE_DIR, as the CLI draws it, and writes the terminal
// body as HTML for the README image's Paper artboards (skills/readme-refresh/SKILL.md says how it is used):
//
// EXPLORE_CACHE_DIR=<dir with saved runs> node scripts/readme-reports-rows.mjs > reports-rows.html
//
// Every coloured piece of a row is its own text box exactly as wide as its characters (7.8px cells of 13px JetBrains
// Mono), so columns line up as they do in a terminal, and the wordmark is drawn as cell rectangles, since a design
// tool's fonts do not render the block characters cell for cell.
import { listSavedRuns } from "../dist/report/saved-runs.js";
import { renderPicker } from "../dist/cli/reports-picker.js";
import { WORDMARK } from "../dist/cli/title-intros.js";
const COLUMNS = 96, CELL = 7.8, ROW = 18;
const runs = await listSavedRuns();
if (!runs.length) { console.error("No saved runs in EXPLORE_CACHE_DIR; save the README's runs there first."); process.exit(1); }
// Shown from a repository's checkout with every repository listed, so the keys include tab.
const repository = runs.find(run => run.repository)?.repository;
const lines = renderPicker({ runs, ...(repository ? { repository } : {}), scope: "all", filter: "", filtering: false, selected: 0, offset: 0 },
{ width: COLUMNS, height: 20, color: true, totalBytes: runs.reduce((sum, run) => sum + run.bytes, 0) });
// The picker pads to the terminal's height above its keys; the image keeps one blank row there.
const keys = lines.slice(-2);
let body = lines.slice(0, -2);
while (body.length > 1 && body.at(-1).trim() === "" && body.at(-2).trim() === "") body = body.slice(0, -1);
const xterm = n => {
if (n >= 232) { const v = 8 + (n - 232) * 10; return [v, v, v]; }
const level = [0, 95, 135, 175, 215, 255]; n -= 16;
return [level[Math.floor(n / 36)], level[Math.floor(n / 6) % 6], level[n % 6]];
};
const hex = rgb => `#${rgb.map(v => v.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
const escape = text => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
const FONT = "font-family: 'JetBrains Mono'; font-size: 13px; line-height: 18px; white-space: pre; flex-shrink: 0; overflow: hidden;";
/** One terminal row as coloured pieces; a selected row (a background colour) gets it across the whole row. */
function row(line) {
if (/^\x1b\[38;5;238m─+/.test(line)) return `<div data-name="Rule" style="display: flex; align-items: center; height: ${ROW}px; flex-shrink: 0;"><div style="height: 1px; flex-grow: 1; background-color: #444444;"></div></div>`;
let colour = "#D4D4D4", bold = false, background;
const pieces = [];
for (const part of line.split(/(\x1b\[[0-9;]*m)/)) {
if (part.startsWith("\x1b[")) {
const codes = part.slice(2, -1).split(";").map(Number);
for (let i = 0; i < codes.length; i += 1) {
const code = codes[i];
if (code === 0) { colour = "#D4D4D4"; bold = false; }
else if (code === 1) bold = true;
else if (code === 2) colour = "#808080";
else if (code === 97) colour = "#FFFFFF";
else if (code === 38 && codes[i + 1] === 5) { colour = hex(xterm(codes[i + 2])); i += 2; }
else if (code === 48 && codes[i + 1] === 5) { background = hex(xterm(codes[i + 2])); i += 2; }
}
continue;
}
if (!part) continue;
pieces.push(`<div style="${FONT} width: ${([...part].length * CELL).toFixed(1)}px; color: ${colour};${bold ? " font-weight: 700;" : ""}">${escape(part)}</div>`);
}
return `<div data-name="${background ? "Row — selected" : "Row"}" style="display: flex; height: ${ROW}px; flex-shrink: 0;${background ? ` background-color: ${background};` : ""}">${pieces.join("")}</div>`;
}
/** The wordmark's two rows as rectangles: █ a whole cell, ▀ and ▄ its top or bottom half, overlapping a little so no seams show. */
function wordmark() {
const rects = [];
WORDMARK.forEach((line, r) => [...line].forEach((ch, c) => {
const x = c * CELL, y = r * ROW;
if (ch === "█") rects.push([x, y, ROW]); else if (ch === "▀") rects.push([x, y, ROW / 2]); else if (ch === "▄") rects.push([x, y + ROW / 2, ROW / 2]);
}));
const svg = rects.map(([x, y, h]) => `<rect x="${(x - 0.25).toFixed(2)}" y="${(y - 0.25).toFixed(2)}" width="${(CELL + 0.5).toFixed(2)}" height="${(h + 0.5).toFixed(2)}"/>`).join("");
const width = (WORDMARK[0].length * CELL).toFixed(1);
return `<div data-name="Wordmark" style="display: flex; padding-left: ${(3 * CELL).toFixed(1)}px; height: ${2 * ROW}px; flex-shrink: 0;"><svg width="${width}" height="${2 * ROW}" viewBox="0 0 ${width} ${2 * ROW}" fill="#FFFFFF" xmlns="http://www.w3.org/2000/svg">${svg}</svg></div>`;
}
const rows = [];
for (let index = 0; index < body.length; index += 1) {
// The picker draws the wordmark as two text rows; the image draws both as one picture.
if (body[index].includes(WORDMARK[0])) { rows.push(wordmark()); index += 1; continue; }
rows.push(body[index].trim() ? row(body[index]) : `<div data-name="Blank" style="height: ${ROW}px; flex-shrink: 0;"></div>`);
}
rows.push(...keys.map(row));
console.log(`<div data-name="Terminal" style="display: flex; flex-direction: column; padding: 12px 18px 16px 18px;">\n${rows.join("\n")}\n</div>`);
+31 -1
View File
@@ -134,7 +134,7 @@ Adapt this to the app; do not copy sign-in guidance into an app without sign-in.
## Step 6: install the CI files
Run `expo-explore setup --workflows` from the app directory. It installs `explore-review.yml` and `explore-baseline.yml` at the repository root with the app and install directories and the package manager's install command, pins both to this CLI's `@expo/explore` version, and forwards every `{{secret:NAME}}` from the config and instructions to both capture steps. Existing workflows keep their edits; setup only updates the version and adds missing secret lines. Rerun it after adding a new secret reference. Replace a superseded Explore workflow only after identifying it, to avoid duplicate captures and comments.
Run `expo-explore setup --workflows` from the app directory. It installs `explore-review.yml`, `explore-baseline.yml` and `explore-compare.yml` at the repository root with the app and install directories and the package manager's install command, pins them to this CLI's `@expo/explore` version, and forwards every `{{secret:NAME}}` from the config and instructions to each capture step. Existing workflows keep their edits; setup only updates the version and adds missing secret lines. Rerun it after adding a new secret reference. Replace a superseded Explore workflow only after identifying it, to avoid duplicate captures and comments.
The review workflow runs on `pull_request_target`, so GitHub runs the default branch's copy of the workflow and its `EXPLORE_VERSION`; a pull request cannot replace the tools that capture and publish its own review. This does not sandbox the app's build. If an app still has `.github/vendor/expo-explore` or an `EXPLORE_TOOLS_COMMIT` workflow from an older setup, `doctor` reports it: delete them and rerun `setup --workflows`.
@@ -150,6 +150,36 @@ Repeat `expo-explore doctor --json` and fix each `fail` until none remain, colle
`setup --check` validates only the config schema and instruction file; it is not runtime verification. When the static checks pass and the user approves the EAS usage (and model usage in agent mode), commit locally and run `expo-explore doctor --capture --yes`. It captures the committed HEAD like the baseline workflow with the local EAS login and reports each route. `CAPTURE_LANDING_UNVERIFIED` means the screen redirected: fix the state that setup or the instructions establish. Open the screenshots of guarded screens and confirm each shows the intended state, not just the right route. Do not start paid builds or simulators merely to validate YAML, and do not weaken capture checks to make a replay pass. A setup that was not run on a device is **authored but not runtime-verified**; say so.
## Review a change on this machine
Once `.expo-explore/config.yaml` is committed, the same review CI runs works locally, between any two commits:
```sh
npx @expo/explore capture:review # HEAD against where it left the default branch
npx @expo/explore capture:review --uncommitted # your uncommitted changes to tracked files against HEAD's base
npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all
```
- It prints which commits it compares. Each is checked out as a detached worktree in a temporary directory, its dependencies installed (frozen lockfile, no scripts, no Explore credentials in the environment), and removed afterwards; the user's checkout, index and branches are never touched.
- It runs both commits' code as the user (dependency installs, the app config, bundling). Before reviewing a branch the user did not write, say so and ask; credential-free installs are not a sandbox.
- Logins: `EXPO_TOKEN` and the provider's API key when they are set; otherwise the user's `eas login` and their local `claude` or `codex` login for the configured provider. If `eas whoami` fails, tell them to run `eas login`.
- `--uncommitted` includes tracked files only. `--include-untracked` adds untracked, non-ignored files, which are uploaded with the EAS build, so check the listed files first and never include secrets.
- Every configured platform is reviewed unless `--platform` picks one. It opens the report in a local Viewer; `--upload` hosts it instead and prints the link, `--no-open` or `--json` only prints the report paths.
- Every run is kept on this machine for 30 days: `npx @expo/explore reports list` (or `--json`) shows them, `reports open <id|latest>` reopens one in the local Viewer, and `reports upload <id>` hosts it without capturing again. Run bare in a terminal, `reports` is an arrow-key picker for the user.
- To host a report after the fact, run `npx @expo/explore report:upload <report.zip>...` with the paths it printed (or the `--output` directory's `<platform>/report.zip`), one per platform. It uses the same project as `--upload` and does not capture again.
- Captures are cached in `~/.cache/expo-explore`, so a second review of the same base does not capture it again (`--no-cache` skips the cache). Ctrl+C stops the EAS Simulator sessions the review started.
- It builds on EAS and runs simulator sessions, like a CI review: expect several minutes and EAS usage per run.
## Compare any two commits
`explore-compare.yml` (installed by `setup --workflows` from 0.19.0; run `npx @expo/explore@latest setup --workflows` to add it to an existing setup) reviews a `head` against a `base`, each a branch, tag or commit SHA, with no pull request. It captures, compares and reports like a PR review and links the report from the run's summary. Its inputs are `base`, `head`, and the optional `scope` (`changes` or `all`) and `expires-in` (such as `30d`, or `never`).
- **Releases.** Unless the user asks otherwise, compare each release with the last stable release, with `scope: all` (every screen, so the report shows the whole release with what changed marked) and, when hosted previews are on, `expires-in: never` (the link outlives the 30-day artifact). For every tag as it is pushed, add the `release-review.yml` from the README's "Compare any two commits" section: it finds the newest earlier tag without a `-` (so a release candidate is compared with the last stable release) and calls `explore-compare.yml` with `secrets: inherit` and `permissions: { contents: read, actions: read }`. A nightly compares with yesterday's tag; a release branch with `main`.
- **Once, on demand.** The workflow must be on the default branch to be dispatched: `gh workflow run explore-compare.yml -f base=<ref> -f head=<ref> -f scope=all -f expires-in=never`, or **Run workflow** under Actions → Expo Explore compare.
- **Without CI.** `npx @expo/explore capture:review --base <ref> --head <ref> --scope all --upload` runs the same comparison on this machine (see the previous section).
- Call the workflow once per workflow run (a second call in the same run reuses the first one's artifact names). A `base` the baseline workflow captured in the last 30 days is reused, so only `head` is captured.
- To verify, run it once on the latest tag and open the run's summary: it lists each platform's result and links the report.
## Learn from observed failures
When revising an existing setup, read the previous run's diagnostics, navigation trace and screenshots together. Separate an app prerequisite or defect from a controller failure and a provider or configuration failure. A successful tool response alone does not prove recovery: check the field value, destination, or visible content. For agent mode, inspect `agent-usage.jsonl` before proposing another paid run; missing accounting is unknown, not zero, and dollar fields are estimates. Respect exhausted credit and requests to stop paid calls.
+18 -3
View File
@@ -38,6 +38,21 @@ node scripts/readme-screenshots.mjs --report ~/euxy-report/ios.zip --select /set
`docs/screenshots/readme-exploration-light.png` is the black-box map and comes from a euxy `explore:binary` run (`npx @expo/explore explore:binary <euxy simulator build> --no-upload`, then `expo-explore view --dir <output>` at 1760×1000, Map, Fit canvas). It has no dark variant and is a plain Markdown image. Regenerate it when the Map's rendering of edges or labels changed; otherwise keep it, and say so in the PR.
`docs/screenshots/readme-reports-light.png` and `-dark.png` show `npx @expo/explore reports` in a terminal window on the same stage as the PR comment image. They are laid out in Paper (Brent's "Patient umbrella" file, page "README — reports picker image", one artboard per theme), from the real picker over real saved runs. Refresh them when the picker's layout or colours change:
```sh
npx @expo/explore reports list # your saved runs: note a euxy local review's id
export EXPLORE_CACHE_DIR=$(mktemp -d) # a scratch store for the image, not your own runs
cd ~/code/euxy # inside euxy, so the commit messages are found
npx @expo/explore reports add ~/.cache/expo-explore/reports/<that id>/ios.zip
npx @expo/explore reports add ~/euxy-report/ios.zip # the PR report from step 1
npx @expo/explore reports add <an explore:binary report directory> # an exploration, so all three kinds show
cd - && npm run build:cli && node scripts/readme-reports-rows.mjs > /tmp/reports-rows.html
```
- The script renders the picker as the CLI draws it (96 columns, the newest run selected) and writes the terminal body as HTML: each coloured piece is exactly its characters wide, so columns line up, and the wordmark is drawn as cell rectangles, since a design tool's font does not draw `█▀▄` cell for cell.
- In Paper, replace the frame named "Terminal" inside each artboard's window with that HTML, check both artboards in a screenshot (crisp wordmark, aligned columns, the selected row highlighted to the end, coloured counts), and export both at 2x as `readme-reports-light.png` and `readme-reports-dark.png`. The window's title bar reads `npx @expo/explore reports`, as people run it.
Look at every PNG you produced before committing, light and dark: the selected screen should be the one you asked for, the Compare view must show Before and After with outlines, the Screens grid must show the Added/Removed/Modified badges, the PR comment must show the heading links and result glyphs. Describe each in its Markdown alt text as what the picture shows, not what the feature is.
## 3. Pass over the content as a first-time user
@@ -45,11 +60,11 @@ Look at every PNG you produced before committing, light and dark: the selected s
Read the README top to bottom once without opening a collapsible. At that level it may only answer, in this order:
1. What Explore is (one short paragraph), the hero image, and the link to the live euxy example (`explore-example--euxy.expo.app`, redeployed on every merge to main by `.github/workflows/example-report.yml`).
2. **Try it on your app**: one sentence and a prompt to paste into Claude Code or Codex that gets a simulator build of any app (Expo or not, or just a build) and runs `explore:binary` on it.
3. **Set up CI: reviews on every PR**: one sentence and the setup prompt.
2. **Try it on your app**: one sentence and a prompt to paste into Claude Code or Codex that gets a simulator build of any app (Expo or not, or just a build) and runs `explore:binary` on it. After its collapsibles, **Review a change before you push it**: one sentence, a prompt that runs `capture:review` locally (the explore-setup skill's "Review a change on this machine" section) on a set-up app, and the `reports` picker image (`readme-reports-*.png`) with one sentence on saved runs, at the top level, not inside a collapsible. Each section keeps its own "Run it yourself"; never put one section between another's prompt and its collapsibles.
3. **Set up CI**: one sentence, then two subsections, each a sentence on what it gives and a prompt to paste: **Review on every PR** (the setup prompt, then a few grouped collapsibles: Hosted previews first, then Manual setup (the setup prompt's steps done by hand, in order: setup, doctor, secrets, baseline, first PR), Capture modes: deterministic or agent, iOS, Android, or both, Keep your setup current) and **Compare any two commits** (a prompt that follows the explore-setup skill's "Compare any two commits" section, the ways to snapshot a release as bullets, then the comparison workflow collapsed).
4. **What you get**: the PR comment, Compare, and Screens, each a heading, one line, and its picture, then a prompt for asking an agent about a report.
Lead with prompts, not explanations: a reader should be able to copy something and see Explore work. Everything else, the manual commands, requirements, options, the manual setup, capture modes, hosted previews, several platforms, agent mode, repository settings, how agents read a report, how it works, limitations, contributing, goes into a `<details>` block under the section it belongs to, with a `<summary>` that says what the reader will find. Keep bullets to one or two sentences. Keep the collapsibles' `id` attributes that other docs link to (`#hosted-previews`, `#platforms`, `#agents`), and keep the Inspiration section (screenmap and Revyl's Atlas).
Lead with prompts, not explanations: a reader should be able to copy something and see Explore work. Everything else, the manual commands, requirements, options, the manual setup, capture modes, hosted previews, iOS and Android, agent mode, repository settings, how agents read a report, how it works, limitations, contributing, goes into a `<details>` block under the section it belongs to, with a `<summary>` that says what the reader will find. Keep bullets to one or two sentences. Group related collapsibles rather than adding one per topic, so a section shows a handful, not nine. Requirements sit collapsed right under the example report link. Keep the collapsibles' `id` attributes that other docs link to (`#hosted-previews`, `#platforms`, `#compare`, `#agents`), and keep the Inspiration section (screenmap and Revyl's Atlas).
Check that each prompt still works as written:
- the skill links it names (`https://unpkg.com/@expo/explore/skills/...`) are files the package ships (`files` in `package.json`), and they open from the published release;
+3 -1
View File
@@ -483,9 +483,11 @@ async function prepareHostedRepack(options: {
}): Promise<string> {
const staged = join(options.root, "project");
await mkdir(staged, { mode: 0o700 });
// Paths relative to the app directory, which is what is staged. With --full-name they were relative to the
// repository root, so an app in a monorepo subdirectory (apps/mobile) copied apps/mobile/apps/mobile/... .
const listed = options.runner({
command: "git",
args: ["ls-files", "-z", "--cached", "--full-name"],
args: ["ls-files", "-z", "--cached"],
cwd: options.project,
environment: options.restrictedEnvironment,
timeoutMs: 60_000,
+1
View File
@@ -1066,6 +1066,7 @@ export async function capturePlannedRoutes(options: {
};
if (rootLink) say(`reset: opening ${rootLink} before each route link (capture.reset: root-link)`);
for (const route of options.routes) {
capture.signal?.throwIfAborted();
if (outcomes[route.id]?.status === "captured" && !setupFailure) continue;
// The default app link would show this route without the prepared state. Keep the setup capture failure.
if (prepared.has(route.id) && outcomes[route.id]?.status !== "captured") continue;
+5
View File
@@ -65,6 +65,8 @@ export type CiMapOptions = {
readinessSeconds?: number;
/** Reports each step as it starts; capture output stays in the map and bundle. */
progress?: Progress;
/** Stops the capture between steps (before the build, the session and each route); a session it started is still stopped. */
signal?: AbortSignal;
};
export type SimulatorRuntimeMetadata = {
provider: "eas-simulator"; controller: "agent-device"; controllerPackageVersion: string;
@@ -392,6 +394,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
setStage("build");
// Historical frames do not replace the fresh build needed for missing targets.
easBuildId = null;
options.signal?.throwIfAborted();
say("computing the native fingerprint");
const fingerprintResult = eas(["fingerprint:generate", "--platform", options.platform, "--build-profile", options.easProfile, "--json", "--non-interactive"]);
fingerprint = fingerprintFrom(fingerprintResult.stdout);
@@ -409,6 +412,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
if (!app.version && reusable.appVersion) app.version = reusable.appVersion;
if (!app.buildNumber && reusable.appBuildVersion) app.buildNumber = reusable.appBuildVersion;
}
options.signal?.throwIfAborted();
if (!easBuildId) {
say(options.forceFreshBuild ? "building on EAS (a fresh build was requested); waiting for it to finish"
: `no finished simulator build has fingerprint ${fingerprint.slice(0, 12)}; building on EAS and waiting for it to finish`);
@@ -424,6 +428,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
if (!app.version && built.appVersion) app.version = built.appVersion;
if (!app.buildNumber && built.appBuildVersion) app.buildNumber = built.appBuildVersion;
}
options.signal?.throwIfAborted();
const simulatorProject = await realpath(await mkdtemp(join(tmpdir(), "expo-explore-session-")));
const dotenvPath = join(simulatorProject, SIMULATOR_DOTENV_FILE_NAME);
const statePath = options.sessionStatePath ? absoluteContractFile(options.sessionStatePath, "sessionStatePath") : undefined;
+13 -3
View File
@@ -4,14 +4,20 @@ import { CiError, serializeCiError, type CiErrorData } from "../shared/ci-errors
import type { Progress } from "../shared/progress.js";
type WorkerMessage = { type: "progress"; message: string } | { type: "done"; result: CiMapResult } | { type: "error"; error: CiErrorData };
/** From the parent: stop between steps, as `signal` does for a capture on the main thread. */
type ParentMessage = { type: "abort"; reason: CiErrorData };
/** Options a worker can receive: the controller runs through synchronous subprocesses, so a side only overlaps another from its own thread. */
export type CaptureWorkerOptions = Omit<CiMapOptions, "progress" | "runner" | "now" | "fetch" | "agent">;
export type CaptureWorkerOptions = Omit<CiMapOptions, "progress" | "runner" | "now" | "fetch" | "agent" | "signal">;
/** Run one capture side on a worker thread so head and base can drive their simulator sessions at the same time. */
export function runCiMapOnWorker(options: CaptureWorkerOptions, progress: Progress): Promise<CiMapResult> {
export function runCiMapOnWorker(options: CaptureWorkerOptions, progress: Progress, signal?: AbortSignal): Promise<CiMapResult> {
return new Promise((resolve, reject) => {
const worker = new Worker(new URL("./capture-worker.js", import.meta.url), { workerData: options });
// An AbortSignal cannot cross threads; the worker aborts its own, and its capture stops its session as usual.
const abort = () => worker.postMessage({ type: "abort", reason: serializeCiError(signal!.reason) } satisfies ParentMessage);
if (signal?.aborted) abort(); else signal?.addEventListener("abort", abort, { once: true });
worker.once("exit", () => signal?.removeEventListener("abort", abort));
let settled = false;
const finish = (callback: () => void) => { if (!settled) { settled = true; callback(); } };
worker.on("message", (message: WorkerMessage) => {
@@ -29,7 +35,11 @@ export function runCiMapOnWorker(options: CaptureWorkerOptions, progress: Progre
if (!isMainThread && parentPort) {
const port = parentPort;
const options = workerData as CaptureWorkerOptions;
runCiMap({ ...options, progress: message => port.postMessage({ type: "progress", message } satisfies WorkerMessage) })
const controller = new AbortController();
port.on("message", (message: ParentMessage) => { if (message.type === "abort") controller.abort(new CiError(message.reason)); });
// Listening for an abort must not keep the worker alive once its capture is done.
port.unref();
runCiMap({ ...options, signal: controller.signal, progress: message => port.postMessage({ type: "progress", message } satisfies WorkerMessage) })
.then(result => port.postMessage({ type: "done", result } satisfies WorkerMessage))
.catch((error: unknown) => port.postMessage({ type: "error", error: serializeCiError(error, { secrets: [options.expoToken] }) } satisfies WorkerMessage));
}
+11 -4
View File
@@ -15,7 +15,7 @@ import { captureCompatibility } from "../capture/observer.js";
import { assertCaptureEasProfile, assertSimulatorAvailable, repackProfileFrom, unreproducibleEasVariables } from "../capture/eas-build.js";
import { createCiAgentSession } from "../capture/agent/session.js";
import { readRouteEntry, type RouteEntry, type RouteEntryReport } from "./route-entry.js";
import { LEGACY_VENDOR_DIRECTORY, WORKFLOW_FILES, ciLayout, renderWorkflow, workflowIssues, workflowTemplateDrift, workflowVersion } from "./workflow-install.js";
import { LEGACY_VENDOR_DIRECTORY, OPTIONAL_WORKFLOW_FILES, WORKFLOW_FILES, ciLayout, renderWorkflow, workflowIssues, workflowTemplateDrift, workflowVersion } from "./workflow-install.js";
import { EXPLORE_VERSION, TOOL_ROOT, packageBin } from "../shared/package-paths.js";
import type { Progress } from "../shared/progress.js";
@@ -240,8 +240,11 @@ async function ciFileChecks(project: string, secretNames: readonly string[], run
const file = `.github/workflows/${name}`;
const path = join(layout.root, file);
if (!await exists(path)) {
checks.push({ step: 6, id: `workflow-${name}`, status: "fail", code: "WORKFLOW_MISSING", message: `${file} is missing.`,
nextAction: "Run expo-explore setup --workflows, then commit the workflows." });
checks.push(OPTIONAL_WORKFLOW_FILES.has(name)
? { step: 6, id: `workflow-${name}`, status: "warn", code: "WORKFLOW_MISSING", message: `${file} is missing, so reviews of two commits without a pull request (a tag against the last release, say) cannot run.`,
nextAction: "Run expo-explore setup --workflows to add it, then commit it." }
: { step: 6, id: `workflow-${name}`, status: "fail", code: "WORKFLOW_MISSING", message: `${file} is missing.`,
nextAction: "Run expo-explore setup --workflows, then commit the workflows." });
continue;
}
const text = await readFile(path, "utf8");
@@ -301,6 +304,7 @@ function githubChecks(root: string, config: ExploreConfig, secretNames: readonly
const published = remote(path, branch);
let local: string | undefined;
try { local = readFileSync(join(root, path), "utf8"); } catch { /* Reported by the CI file checks. */ }
if (local === undefined && OPTIONAL_WORKFLOW_FILES.has(name)) return [];
return published === undefined ? [`${name} (missing)`] : local !== undefined && published !== local ? [`${name} (different)`] : [];
});
checks.push(stale.length
@@ -465,7 +469,7 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
checks.push(...files.checks);
if (files.root) {
const pending = run("git", ["status", "--porcelain", "--untracked-files=all", "--", DEFAULT_EXPLORE_CONFIG_PATH, ...(config.agent?.instructions ? [config.agent.instructions] : [])], project).stdout
+ run("git", ["status", "--porcelain", "--untracked-files=normal", "--", ".github/workflows/explore-review.yml", ".github/workflows/explore-baseline.yml"], files.root).stdout;
+ run("git", ["status", "--porcelain", "--untracked-files=normal", "--", ...WORKFLOW_FILES.map(name => `.github/workflows/${name}`)], files.root).stdout;
const paths = [...new Set(pending.split("\n").map(line => line.slice(3).trim()).filter(Boolean))];
if (paths.length) checks.push({ step: 6, id: "committed", status: "fail", code: "SETUP_FILES_UNCOMMITTED",
message: `Setup files are not committed: ${list(paths)}. CI reads them from the pushed repository.`,
@@ -565,7 +569,10 @@ export async function runCaptureCheck(options: { project: string; output: string
nextAction: "Omit --output to use a new temporary directory, or pass a directory inside the system temporary directory." });
let failure: CaptureCheckResult["failure"];
try {
// Agent mode with no API key set uses the local claude or codex login, as a local review does.
const subscription = config.mode === "agent" && config.agent !== undefined && !(options.environment ?? process.env)[PROVIDERS[config.agent.provider].secret]?.trim();
await runBaselineCi({ ...(options.platform ? { platform: options.platform } : {}), project, sha: commit, output, config, useLocalEasSession: true,
...(subscription ? { subscription: true } : {}),
...(options.environment ? { environment: options.environment } : {}), ...(options.runner ? { runner: options.runner } : {}),
...(options.progress ? { progress: options.progress } : {}) });
} catch (error) {
+440
View File
@@ -0,0 +1,440 @@
import { spawnSync } from "node:child_process";
import { randomBytes } from "node:crypto";
import { readFileSync } from "node:fs";
import { copyFile, cp, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, relative, resolve } from "node:path";
import { runCiReview } from "./pipeline.js";
import { resolveCommit } from "./workflow-steps.js";
import { ciLayout, installCommand, type PackageManager } from "./workflow-install.js";
import { configPlatforms, readExploreConfig, resolvePlatformConfig, withRunOverrides, DEFAULT_EXPLORE_CONFIG_PATH, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
import { AGENT_PROVIDERS } from "../config/setup.js";
import type { PrepareCiExplorationOptions } from "../capture/agent/exploration.js";
import { createCiAgentSession } from "../capture/agent/session.js";
import { createLocalCiAgentSession } from "../capture/agent/session-local.js";
import type { CommandRunner } from "../capture/run.js";
import { isSafeBranchRef, type LocalReviewPresentation, type PullRequestSidePresentation } from "../contracts/review.js";
import { exportCiReport, readCiReportInput } from "../report/artifact.js";
import { reviewChangeCount, reviewDevice, type PublicCommentState } from "../report/pr-comment-body.js";
import { zipReportDirectory } from "../report/preview-deploy.js";
import { CiError } from "../shared/ci-errors.js";
import { exploreCacheRoot } from "../shared/cache-root.js";
import { packageBin } from "../shared/package-paths.js";
import { silentProgress, type Progress } from "../shared/progress.js";
/**
* `capture:review --base REF [--head REF]` on a laptop: the same review CI runs (`runCiReview`), on two commits of the
* current repository, with your own `eas login` and your local Claude or Codex login when no token or key is set.
* Each commit is checked out as a detached worktree in a private temporary directory, its dependencies installed
* without credentials in the environment, and both are removed afterwards. The report is packaged per platform.
*/
export type LocalReviewOptions = {
project: string;
base?: string | undefined;
head?: string | undefined;
/** Review uncommitted changes to tracked files as the head (the working tree, not a commit). */
uncommitted?: boolean | undefined;
/** With `uncommitted`: also include untracked files that are not ignored. */
untracked?: boolean | undefined;
platform?: ExplorePlatform | undefined;
scope?: string | undefined;
expiresIn?: string | undefined;
/** Reuse and keep captures in the local capture cache (default true). */
cache?: boolean | undefined;
configPath?: string | undefined;
environment?: NodeJS.ProcessEnv;
progress?: Progress;
/** Behaves like Ctrl+C when aborted: for callers (and tests) that stop a review without a signal. */
interrupt?: AbortSignal | undefined;
/** Tests: replace the dependency install (given the app directory in that side's checkout) and the capture process. */
install?: (project: string, side: "base" | "head") => Promise<void>;
runner?: CommandRunner; now?: () => number; sleep?: (milliseconds: number) => void;
agentSessionFactory?: PrepareCiExplorationOptions["createSession"];
};
export type LocalReviewReport = { platform: ExplorePlatform; directory: string; zip: string; changes?: number; device?: string };
export type LocalReviewResult = {
runId: string; base: PullRequestSidePresentation; head: PullRequestSidePresentation & { uncommitted?: string[] };
work: string; reports: LocalReviewReport[]; config: ExploreConfig; repository: string;
};
/** Git, without the user's hooks or fsmonitor, and never with a terminal prompt. */
function git(cwd: string, args: string[], environment: NodeJS.ProcessEnv = process.env, input?: string) {
const result = spawnSync("git", ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-C", cwd, ...args],
{ encoding: "utf8", env: { ...environment, GIT_TERMINAL_PROMPT: "0" }, maxBuffer: 64 * 1024 * 1024, ...(input === undefined ? {} : { input }) });
return { ok: result.status === 0, stdout: result.stdout?.trim() ?? "", stderr: result.stderr?.trim() ?? "" };
}
function must(result: ReturnType<typeof git>, message: string, nextAction: string): string {
if (!result.ok) throw new CiError({ code: "LOCAL_REVIEW_GIT_FAILED", stage: "preflight", message: `${message}: ${result.stderr || "git failed"}`, nextAction });
return result.stdout;
}
const UNTRACKED_LIMIT_BYTES = 50 * 1024 * 1024;
/**
* The working tree as a commit on top of HEAD, without touching the user's index, files or refs: a temporary
* index seeded from the real one, `git add`, `write-tree`, `commit-tree`. Tracked changes only, unless `untracked`.
* Undefined when nothing changed.
*/
export async function snapshotWorkingTree(root: string, options: { untracked?: boolean | undefined; work: string }):
Promise<{ sha: string; changed: string[]; untracked: string[] } | undefined> {
const index = join(options.work, "snapshot-index");
const real = resolve(root, must(git(root, ["rev-parse", "--git-path", "index"]), "Cannot find the repository index", "Run this inside a git repository."));
try { await copyFile(real, index); } catch { /* A repository without an index starts empty. */ }
const environment = { ...process.env, GIT_INDEX_FILE: index, GIT_OPTIONAL_LOCKS: "0" };
const untracked = options.untracked ? must(git(root, ["ls-files", "-z", "--others", "--exclude-standard"]), "Cannot list untracked files", "Check the repository.")
.split("\0").filter(Boolean) : [];
let bytes = 0;
for (const file of untracked) bytes += (await stat(join(root, file)).catch(() => ({ size: 0 }))).size;
if (bytes > UNTRACKED_LIMIT_BYTES) throw new CiError({ code: "LOCAL_REVIEW_UNTRACKED_TOO_LARGE", stage: "preflight",
message: `The untracked files add up to ${Math.round(bytes / 1024 / 1024)} MB; they would be uploaded with the EAS build.`,
nextAction: "Ignore or commit the large files, or leave out --include-untracked." });
must(git(root, ["add", options.untracked ? "-A" : "-u", "--", "."], environment), "Cannot stage the working tree", "Check the repository's state.");
const tree = must(git(root, ["write-tree"], environment), "Cannot write the working tree", "Check the repository's state.");
await rm(index, { force: true });
if (tree === must(git(root, ["rev-parse", "HEAD^{tree}"]), "The repository has no commit", "Commit once, then rerun.")) return undefined;
const changed = must(git(root, ["diff", "--name-only", "-z", "HEAD", tree]), "Cannot list the changes", "Check the repository.").split("\0").filter(Boolean);
const sha = must(git(root, ["commit-tree", tree, "-p", "HEAD", "-m", "Expo Explore: uncommitted changes"],
{ ...process.env, GIT_AUTHOR_NAME: "Expo Explore", GIT_AUTHOR_EMAIL: "explore@localhost", GIT_COMMITTER_NAME: "Expo Explore", GIT_COMMITTER_EMAIL: "explore@localhost" }),
"Cannot record the uncommitted changes", "Check the repository's state.");
return { sha, changed, untracked: untracked.filter(file => changed.includes(file)) };
}
/**
* The base when none is given: where HEAD left the default branch (what it would merge), named after it. Both the
* local branch and origin's are considered, by exact ref (a tag of the same name never counts), and the newer fork
* point wins, so neither a stale local `main` nor an unfetched `origin/main` adds other people's changes. On the
* default branch itself, its unpushed commits are reviewed against origin's.
*/
export function defaultBase(root: string, headSha: string): PullRequestSidePresentation {
const remote = git(root, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
for (const branch of remote.ok ? [remote.stdout.replace(/^origin\//, "")] : ["main", "master"]) {
const tips = [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`]
.map(ref => git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])).filter(result => result.ok).map(result => result.stdout);
if (!tips.length) continue;
const forks = tips.map(tip => git(root, ["merge-base", tip, headSha])).filter(result => result.ok).map(result => result.stdout);
if (!forks.length) throw new CiError({ code: "LOCAL_REVIEW_BASE_REQUIRED", stage: "preflight", message: `${branch} and the head share no history.`,
nextAction: "Pass --base with a commit the head descends from." });
// Each fork point is an ancestor of the other; the newer one is where the head actually branched off. A fork point
// that is the head itself is the branch you are on (main with unpushed commits): the other one is what you would push onto.
const candidates = forks.filter(fork => fork !== headSha);
const fork = (candidates.length ? candidates : forks).reduce((older, newer) => git(root, ["merge-base", "--is-ancestor", older, newer]).ok ? newer : older);
return { ref: tips.includes(fork) ? branch : `${branch} (merge base)`, sha: fork };
}
throw new CiError({ code: "LOCAL_REVIEW_BASE_REQUIRED", stage: "preflight", message: "This repository has no default branch to compare with.",
nextAction: "Pass --base with a branch, tag or commit SHA." });
}
/**
* The name a report gives a ref: as typed, unless the report's ref rules refuse it (`@{u}`, `@{-1}`, `HEAD@{1}`); then
* the branch it names, or the commit's short SHA. Checked here, since the report itself is only written after capture.
*/
export function reportRef(root: string, ref: string, sha: string): string {
if (isSafeBranchRef(ref)) return ref;
const name = git(root, ["rev-parse", "--abbrev-ref", "--verify", "--quiet", ref]);
return name.ok && name.stdout && name.stdout !== "HEAD" && isSafeBranchRef(name.stdout) ? name.stdout : sha.slice(0, 8);
}
/** owner/name from a github.com `origin`, or a local name; the report shows it and the hosted project is named after it. */
export function repositoryName(root: string, config: ExploreConfig): string {
const remote = git(root, ["remote", "get-url", "origin"]).stdout;
const match = /github\.com[:/]([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(remote);
return match ? `${match[1]}/${match[2]}` : `local/${(config.app.name ?? "app").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "") || "app"}`;
}
/**
* The environment of app installs: no variable named like a credential. A reviewed commit's .npmrc or .yarnrc.yml
* could otherwise send `${NPM_TOKEN}` or `${CLAUDE_CODE_OAUTH_TOKEN}` to a registry it chooses, even with
* --ignore-scripts. Proxy, certificate, cache and SSH-agent settings stay. This matches CI, whose install step
* gets no secrets; registry auth in your own ~/.npmrc is scoped to its host and still applies. It is not a sandbox: a
* commit's yarnPath, Yarn plugins or .pnpmfile.cjs still run as you, as its app config and bundling do later.
*/
export function appEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
return Object.fromEntries(Object.entries(environment).filter(([key]) =>
key === "SSH_AUTH_SOCK" || !/(TOKEN|SECRET|PASSWORD|KEY|AUTH|CREDENTIAL|SESSION|COOKIE)/i.test(key)));
}
/** The frozen-lockfile install setup derives for CI, without `corepack enable` (that changes your Node install). */
export function localInstallCommand(manager: PackageManager, directory: string): string {
return installCommand(manager, directory).replace(/^corepack enable && /, "");
}
/** Install from the app directory: the lockfile is the nearest one at or above it, as `setup` finds it for CI. */
export async function installDependencies(project: string, logFile: string, environment: NodeJS.ProcessEnv): Promise<void> {
const layout = await ciLayout(project);
if (!layout.manager) throw new CiError({ code: "LOCAL_REVIEW_LOCKFILE_MISSING", stage: "preflight", message: "The app has no lockfile at this commit.",
nextAction: "Commit the app's lockfile, then rerun." });
const command = localInstallCommand(layout.manager, layout.installDir);
const result = spawnSync("sh", ["-c", command], { cwd: layout.root, env: appEnvironment(environment), encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
await writeFile(logFile, `$ ${command}\n${result.stdout ?? ""}${result.stderr ?? ""}`);
if (result.status !== 0) throw new CiError({ code: "LOCAL_REVIEW_INSTALL_FAILED", stage: "preflight", message: `Installing the app's dependencies failed: ${command}`,
nextAction: `Read ${logFile}; ${layout.manager === "npm" ? "" : `make sure ${layout.manager.replace("-classic", "")} is installed, and `}check the lockfile at that commit. `
+ "Installs run without credential environment variables: a registry that needs ${NPM_TOKEN} in the project's .npmrc must be authenticated in your own ~/.npmrc instead." });
}
/** `~/.cache/expo-explore/captures/<platform>/<sha>`: one capture per commit and platform, reused while its recipe matches. */
export function captureCacheDirectory(environment: NodeJS.ProcessEnv, platform: ExplorePlatform, sha: string): string {
return join(exploreCacheRoot(environment), "captures", platform, sha);
}
async function exists(path: string): Promise<boolean> { try { await lstat(path); return true; } catch { return false; } }
const CACHE_METADATA = "cache-metadata.json";
/**
* Drops cached captures not used for 30 days, then the least recently used until the rest fit in 2 GB, as saved runs
* are pruned. A capture counts as used when a review keeps or reuses it (its cache-metadata.json is touched then).
*/
export async function pruneCaptureCache(environment: NodeJS.ProcessEnv, now = Date.now(), limits = { maxAgeDays: 30, maxBytes: 2 * 1024 * 1024 * 1024 }): Promise<string[]> {
const root = join(exploreCacheRoot(environment), "captures");
const entries: Array<{ path: string; used: number; bytes: number }> = [];
const size = async (path: string): Promise<number> => {
const info = await lstat(path);
if (!info.isDirectory()) return info.size;
let total = 0;
for (const name of await readdir(path)) total += await size(join(path, name));
return total;
};
for (const platform of await readdir(root).catch(() => [] as string[])) {
for (const sha of await readdir(join(root, platform)).catch(() => [] as string[])) {
const path = join(root, platform, sha);
if (!/^[0-9a-f]{40}$/.test(sha)) continue;
const used = await stat(join(path, CACHE_METADATA)).then(info => info.mtimeMs, () => 0);
entries.push({ path, used, bytes: await size(path).catch(() => 0) });
}
}
entries.sort((a, b) => a.used - b.used);
let total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
const removed: string[] = [];
for (const entry of entries) {
if (now - entry.used <= limits.maxAgeDays * 86_400_000 && total <= limits.maxBytes) continue;
await rm(entry.path, { recursive: true, force: true });
total -= entry.bytes;
removed.push(entry.path);
}
return removed;
}
async function cacheRecipe(directory: string): Promise<{ recipe: string; images: number } | undefined> {
try {
const metadata = JSON.parse(await readFile(join(directory, CACHE_METADATA), "utf8")) as { recipe?: unknown };
const bundle = JSON.parse(await readFile(join(directory, "bundle.json"), "utf8")) as { images?: Record<string, unknown> };
return typeof metadata.recipe === "string" ? { recipe: metadata.recipe, images: Object.keys(bundle.images ?? {}).length } : undefined;
} catch { return undefined; }
}
/**
* Keep an export as a commit's cached capture. Only exports whose evidence validated carry cache metadata. An entry
* from another recipe (an Explore upgrade, a config change) is replaced; one with the same recipe only by an export
* with at least as many screens, so a partial capture never shrinks a fuller one.
*/
export async function keepCapture(exported: string, target: string): Promise<boolean> {
const next = await cacheRecipe(exported);
if (!next) return false;
const current = await cacheRecipe(target);
if (current && current.recipe === next.recipe && current.images > next.images) return false;
// Copied beside the entry and renamed into place, so a review reading the cache (or another one writing it) never
// sees a half-copied capture; when two write at once, the first rename wins and the other copy is dropped.
await mkdir(resolve(target, ".."), { recursive: true });
const staged = `${target}.${randomBytes(4).toString("hex")}.tmp`;
try {
await cp(exported, staged, { recursive: true });
await rm(target, { recursive: true, force: true });
await rename(staged, target);
return true;
} catch (error) {
if (!["ENOTEMPTY", "EEXIST"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
return false;
} finally {
await rm(staged, { recursive: true, force: true });
}
}
function recordedSessionIds(outputs: string[]): string[] {
return outputs.flatMap(output => ["head-session", "base-session"].flatMap(name => {
try { const id = readFileSync(join(output, name), "utf8").trim(); return /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(id) ? [id] : []; } catch { return []; }
}));
}
/** Stop the EAS Simulator sessions a capture recorded and did not stop itself (an interrupted run), with the local login. */
export async function stopRecordedSessions(outputs: string[], environment: NodeJS.ProcessEnv, runner: (args: string[]) => { status: number | null } =
args => spawnSync(packageBin("eas-cli", "eas"), args, { env: environment, encoding: "utf8", timeout: 120_000 }), quiet = false): Promise<string[]> {
const stopped: string[] = [];
for (const output of outputs) for (const name of ["head-session", "base-session"]) {
const file = join(output, name);
const id = (await readFile(file, "utf8").catch(() => "")).trim();
if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(id)) continue;
if (runner(["simulator:stop", "--id", id, "--json", "--non-interactive"]).status === 0) { stopped.push(id); await rm(file, { force: true }); }
// During an interrupt the capture may stop the same session first; only the final pass reports a failure.
else if (!quiet) process.stderr.write(`Could not stop EAS Simulator session ${id}; stop it with: eas simulator:stop --id ${id}\n`);
}
return stopped;
}
export async function runLocalReview(options: LocalReviewOptions): Promise<LocalReviewResult> {
const environment = { ...(options.environment ?? process.env) };
const progress = options.progress ?? silentProgress;
const project = await realpath(options.project);
const root = await realpath(must(git(project, ["rev-parse", "--show-toplevel"]), "Not a git repository", "Run this inside the app's git repository."));
const appDirectory = relative(root, project) || ".";
const runId = `local-${new Date((options.now ?? Date.now)()).toISOString().replace(/[^0-9]/g, "").slice(0, 14)}-${randomBytes(3).toString("hex")}`;
const work = await realpath(await mkdtemp(join(tmpdir(), "expo-explore-review-")));
const worktrees: string[] = [];
const outputs: string[] = [];
// The first Ctrl+C stops the captures between steps (deterministic or agent), aborts model requests and stops the
// recorded simulator sessions, so the capture fails fast and unwinds through its own cleanup and the finally below. A second one quits now, naming any session left running.
const abort = new AbortController();
let interrupts = 0;
const interrupt = () => {
interrupts += 1;
if (interrupts === 1) {
process.stderr.write("\nStopping the review and its EAS Simulator sessions… (Ctrl+C again to quit now)\n");
abort.abort(new CiError({ code: "LOCAL_REVIEW_INTERRUPTED", stage: "capture", message: "The review was interrupted.", nextAction: "Rerun it when you are ready." }));
if (!options.runner) void stopRecordedSessions(outputs, environment, undefined, true);
return;
}
for (const tree of worktrees) git(root, ["worktree", "remove", "--force", tree]);
for (const id of recordedSessionIds(outputs)) process.stderr.write(`Still running: stop it with eas simulator:stop --id ${id}\n`);
process.exit(130);
};
process.on("SIGINT", interrupt);
process.on("SIGTERM", interrupt);
options.interrupt?.addEventListener("abort", interrupt, { once: true });
const factory = options.agentSessionFactory;
let failed = false;
try {
// The commits.
const headRef = options.head ?? "HEAD";
let head: LocalReviewResult["head"];
if (options.uncommitted) {
if (options.head && options.head !== "HEAD") throw new CiError({ code: "LOCAL_REVIEW_UNCOMMITTED_HEAD", stage: "preflight",
message: "--uncommitted reviews the working tree, which is on top of HEAD.", nextAction: "Leave out --head, or leave out --uncommitted." });
const snapshot = await snapshotWorkingTree(root, { untracked: options.untracked, work });
head = snapshot ? { ref: "uncommitted changes", sha: snapshot.sha, uncommitted: snapshot.changed } : { ref: "HEAD", sha: resolveCommit(root, "HEAD", "head") };
if (snapshot) progress(`head: your uncommitted changes to ${snapshot.changed.length} file${snapshot.changed.length === 1 ? "" : "s"}`
+ (snapshot.untracked.length ? ` (untracked, uploaded with the build and kept in .git/objects until git gc: ${snapshot.untracked.join(", ")})` : ""));
else progress("head: no uncommitted changes, reviewing HEAD");
} else {
const sha = resolveCommit(root, headRef, "head");
head = { ref: reportRef(root, headRef, sha), sha };
}
const baseSha = options.base ? resolveCommit(root, options.base, "base") : undefined;
const base = options.base && baseSha ? { ref: reportRef(root, options.base, baseSha), sha: baseSha } : defaultBase(root, head.sha);
if (base.sha === head.sha) throw new CiError({ code: "COMPARE_SAME_COMMIT", stage: "preflight", message: `${base.ref} and ${head.ref} are the same commit (${head.sha.slice(0, 8)}).`,
nextAction: "Pass --base with an earlier commit, or --uncommitted to review your uncommitted changes." });
progress(`comparing ${head.ref} (${head.sha.slice(0, 8)}) with ${base.ref} (${base.sha.slice(0, 8)})`);
// The checkouts, and the config at head.
const checkouts = { base: join(work, "base"), head: join(work, "head") };
for (const side of ["base", "head"] as const) {
must(git(root, ["worktree", "add", "--detach", "--quiet", checkouts[side], side === "base" ? base.sha : head.sha]),
`Cannot check out the ${side} commit`, "Check the repository's state, then rerun.");
worktrees.push(checkouts[side]);
}
const projects = { base: join(checkouts.base, appDirectory), head: join(checkouts.head, appDirectory) };
const configPath = options.configPath ?? DEFAULT_EXPLORE_CONFIG_PATH;
const rawConfig = await readExploreConfig(projects.head, configPath);
const platforms = options.platform ? [options.platform] : configPlatforms(rawConfig);
const repository = repositoryName(root, rawConfig);
// Credentials: tokens and keys when set, otherwise your own logins.
const useLocalEasSession = !environment.EXPO_TOKEN?.trim();
if (useLocalEasSession && !options.runner) {
const whoami = spawnSync(packageBin("eas-cli", "eas"), ["whoami"], { cwd: projects.head, env: environment, encoding: "utf8", timeout: 60_000 });
if (whoami.status !== 0) throw new CiError({ code: "EXPO_LOGIN_REQUIRED", stage: "preflight", message: "You are not logged in to EAS.",
nextAction: "Run eas login (or set EXPO_TOKEN), then rerun." });
}
const subscription = rawConfig.mode === "agent" && rawConfig.agent !== undefined && !environment[AGENT_PROVIDERS[rawConfig.agent.provider].secret]?.trim();
if (subscription) progress(`model: your local ${rawConfig.agent!.provider === "anthropic" ? "claude" : "codex"} login (no ${AGENT_PROVIDERS[rawConfig.agent!.provider].secret} set)`);
let installed = false;
const install = options.install ?? (async (project: string, side: "base" | "head") => {
progress(`installing the ${side} commit's dependencies`);
await installDependencies(project, join(work, `install-${side}.log`), environment);
});
const reports: LocalReviewReport[] = [];
for (const platform of platforms) {
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: options.scope, expiresIn: options.expiresIn });
const output = join(work, platform); await mkdir(output);
outputs.push(output);
const platformEnvironment = { ...environment };
delete platformEnvironment.EXPLORE_CAPTURE_CACHE;
const cachedBase = captureCacheDirectory(environment, platform, base.sha);
if (options.cache !== false && await exists(join(cachedBase, CACHE_METADATA))) {
platformEnvironment.EXPLORE_CAPTURE_CACHE = cachedBase;
// Reusing a capture counts as using it, so pruning keeps the bases reviews come back to.
await utimes(join(cachedBase, CACHE_METADATA), new Date(), new Date()).catch(() => undefined);
}
const presentation: LocalReviewPresentation = { origin: "local", repository, runId, title: `${head.ref} vs ${base.ref}`,
base: { ref: base.ref, sha: base.sha }, head: { ref: head.ref, sha: head.sha } };
const state: PublicCommentState = { phase: "pending", pullRequest: presentation, mode: config.exploration.scope, executionMode: config.mode,
configPath: appDirectory === "." ? configPath : `${appDirectory}/${configPath}`,
links: { viewer: null, download: null, run: "", config: "", artifacts: "" }, startedAt: Date.now(), updatedAt: Date.now(),
build: { platform: config.app.platform, easProfile: config.app.easProfile }, artifactOnly: true };
progress(`${platform}: reviewing`);
const result = await runCiReview({ projects, output, config, presentation, runId, runAttempt: "1", state, environment: platformEnvironment,
...(platforms.length > 1 ? { platforms } : {}), subscription, useLocalEasSession, progress: message => progress(`${platform}: ${message}`),
...(options.runner ? { runner: options.runner } : {}), ...(options.now ? { now: options.now } : {}), ...(options.sleep ? { sleep: options.sleep } : {}),
signal: abort.signal,
// Model requests end on Ctrl+C: the session kills its own process group and restores any login it changed.
agentSessionFactory: (configuration, sessionOptions) => {
const session = (factory ?? (subscription ? createLocalCiAgentSession : createCiAgentSession))(configuration, sessionOptions);
return { ...session,
preflight: preflightOptions => session.preflight({ ...preflightOptions, signal: preflightOptions?.signal ? AbortSignal.any([preflightOptions.signal, abort.signal]) : abort.signal }),
run: request => session.run({ ...request, signal: request.signal ? AbortSignal.any([request.signal, abort.signal]) : abort.signal }) };
},
prepareCapture: async () => {
if (installed) return;
for (const side of ["head", "base"] as const) await install(projects[side], side);
installed = true;
},
assertCurrentHead: async () => {
abort.signal.throwIfAborted();
for (const side of ["base", "head"] as const) {
if (git(projects[side], ["rev-parse", "HEAD"]).stdout !== (side === "base" ? base.sha : head.sha)
|| git(checkouts[side], ["status", "--porcelain", "--untracked-files=normal"]).stdout) {
throw new CiError({ code: "CHECKOUT_MODIFIED", stage: "capture", message: `The ${side} checkout changed during capture.`,
nextAction: "Keep generated files outside the app's source, then rerun." });
}
}
},
postComment: async () => {} });
const directory = join(output, "report");
await exportCiReport({ inputPath: result.inputPath, outputPath: directory });
const zip = join(output, "report.zip");
await writeFile(zip, await zipReportDirectory(directory));
const input = await readCiReportInput(result.inputPath);
const changes = reviewChangeCount(input.commentState); const device = reviewDevice(input.commentState);
reports.push({ platform, directory, zip, ...(changes === undefined ? {} : { changes }), ...(device ? { device } : {}) });
// Keep both sides' captures for later reviews of these commits; a working-tree snapshot is never reviewed again.
if (options.cache !== false) for (const side of ["base", "head"] as const) {
if (side === "head" && head.uncommitted) continue;
await keepCapture(join(output, `${side}-export`), captureCacheDirectory(environment, platform, side === "base" ? base.sha : head.sha));
}
if (options.cache !== false) await pruneCaptureCache(environment).catch(() => []);
// The report is all that is kept; the captures, maps and checkouts are the bulk of the run.
for (const entry of await readdir(output)) if (entry !== "report" && entry !== "report.zip") await rm(join(output, entry), { recursive: true, force: true });
abort.signal.throwIfAborted();
}
// The install logs and snapshot index go too; the checkouts are removed with git below.
for (const entry of await readdir(work)) if (![...platforms, "base", "head"].includes(entry)) await rm(join(work, entry), { recursive: true, force: true });
return { runId, base, head, work, reports, config: rawConfig, repository };
} catch (error) {
failed = true;
// A capture interrupted mid-session reports its cleanup; the interruption is what happened.
throw abort.signal.aborted ? abort.signal.reason : error;
} finally {
process.off("SIGINT", interrupt);
process.off("SIGTERM", interrupt);
options.interrupt?.removeEventListener("abort", interrupt);
// A capture stops its own sessions; this catches one that ended before it could. Tests inject their own runner.
if (!options.runner) await stopRecordedSessions(outputs, environment).catch(() => []);
// Only the run's own worktrees: a repository-wide prune would also drop the user's own worktrees on an unmounted disk.
for (const tree of worktrees) git(root, ["worktree", "remove", "--force", tree]);
// A failed run keeps what it produced for inspection; one that failed before producing anything leaves nothing.
if (failed) {
if ((await readdir(work).catch(() => [])).length) progress(`kept this review's files for inspection: ${work}`);
else await rm(work, { recursive: true, force: true });
}
}
}
+46 -17
View File
@@ -14,7 +14,7 @@ import { runCiMapOnWorker } from "./capture-worker.js";
import { writeCiReportInput, readAppDirectory } from "../report/artifact.js";
import { assessPublicEvidence, readExportedMap, type PublicEvidenceSide } from "../review/evidence-assessment.js";
import { parseRuntimeExecutionContext } from "../review/runtime-adapter.js";
import { projectPullRequestPresentation, type ReviewPresentation } from "../contracts/review.js";
import { projectComparePresentation, projectPullRequestPresentation, type ReviewPresentation } from "../contracts/review.js";
import { renderPublicComment, platformSectionMerge, type PublicCommentState } from "../report/pr-comment-body.js";
import { upsertStickyComment } from "../report/pr-comment.js";
import { viewerLinks } from "../report/viewer-links.js";
@@ -105,35 +105,59 @@ export type PublicCiOptions = {
progress?: Progress;
};
export async function runPublicCi(options: PublicCiOptions) {
const environment = options.environment ?? process.env;
const transport = options.transport ?? fetch;
const now = options.now ?? Date.now;
const config = options.config;
const githubToken = requireSecret(environment, "GITHUB_TOKEN");
function assertRunIdentity(environment: NodeJS.ProcessEnv): void {
if (!/^[1-9][0-9]*$/.test(environment.GITHUB_RUN_ID ?? "") || !/^[1-9][0-9]*$/.test(environment.GITHUB_RUN_ATTEMPT ?? "")) {
throw new CiError({ code: "CI_RUN_IDENTITY_MISSING", stage: "preflight", message: "The GitHub run ID or attempt is missing.",
nextAction: "Run capture:review inside the maintained Explore GitHub Actions workflow." });
}
const pr = projectPullRequestPresentation(JSON.parse(await readFile(options.pullRequestPath, "utf8")));
}
/** What both CI adapters check before capture: exact checkouts of both sides and an output outside them. */
async function prepareCiRun(options: Pick<PublicCiOptions, "baseProject" | "headProject" | "output" | "config" | "configPath" | "now">,
environment: NodeJS.ProcessEnv, presentation: ReviewPresentation) {
const now = options.now ?? Date.now;
const config = options.config;
const projects = { base: await realpath(options.baseProject), head: await realpath(options.headProject) };
const output = resolve(options.output);
const temporary = await realpath(environment.RUNNER_TEMP || tmpdir());
const outputRelative = relative(temporary, output);
if (!outputRelative || outputRelative.startsWith("..") || isAbsolute(outputRelative)) throw new Error("CI output must be inside RUNNER_TEMP, outside source checkouts");
for (const side of ["base", "head"] as const) {
assertCheckout(projects[side], pr[side].sha);
assertCheckout(projects[side], presentation[side].sha);
const rel = relative(projects[side], output);
if (!rel.startsWith("..") && !isAbsolute(rel)) throw new Error("Capture output cannot be inside a source checkout");
}
const appDirectory = await readAppDirectory(projects.head);
const configPath = options.configPath ?? DEFAULT_EXPLORE_CONFIG_PATH;
const repositoryConfigPath = appDirectory === "." ? configPath : `${appDirectory}/${configPath}`;
const state: PublicCommentState = { phase: "pending", pullRequest: pr, mode: config.exploration.scope,
const state: PublicCommentState = { phase: "pending", pullRequest: presentation, mode: config.exploration.scope,
executionMode: config.mode, configPath: repositoryConfigPath,
links: viewerLinks({ repository: pr.repository, headSha: pr.head.sha, runId: environment.GITHUB_RUN_ID!,
links: viewerLinks({ repository: presentation.repository, headSha: presentation.head.sha, runId: environment.GITHUB_RUN_ID!,
runAttempt: environment.GITHUB_RUN_ATTEMPT!, configPath: repositoryConfigPath }),
startedAt: now(), updatedAt: now(), build: { platform: config.app.platform, easProfile: config.app.easProfile }, artifactOnly: true };
return { projects, output, state };
}
/** A review of any two commits (`capture:review --compare FILE`): the same capture as a PR's, with no PR to verify or comment on. */
export async function runCompareCi(options: Omit<PublicCiOptions, "pullRequestPath" | "transport" | "onComment"> & { comparePath: string }) {
const environment = options.environment ?? process.env;
assertRunIdentity(environment);
const comparison = projectComparePresentation(JSON.parse(await readFile(options.comparePath, "utf8")));
const { projects, output, state } = await prepareCiRun(options, environment, comparison);
const assertCurrentHead = async () => { for (const side of ["base", "head"] as const) assertCheckout(projects[side], comparison[side].sha); };
return runCiReview({ ...options, projects, output, state, presentation: comparison,
environment, runId: environment.GITHUB_RUN_ID!, runAttempt: environment.GITHUB_RUN_ATTEMPT!,
assertCurrentHead, postComment: async () => {} });
}
export async function runPublicCi(options: PublicCiOptions) {
const environment = options.environment ?? process.env;
const transport = options.transport ?? fetch;
const now = options.now ?? Date.now;
const githubToken = requireSecret(environment, "GITHUB_TOKEN");
assertRunIdentity(environment);
const pr = projectPullRequestPresentation(JSON.parse(await readFile(options.pullRequestPath, "utf8")));
const { projects, output, state } = await prepareCiRun(options, environment, pr);
const postComment = async () => {
await assertCurrentPr();
state.updatedAt = now(); const body = renderPublicComment(state); options.onComment?.(state, body);
@@ -217,6 +241,8 @@ export async function runCiReview(options: {
agentSessionFactory?: PrepareCiExplorationOptions["createSession"];
prepareCapture?: () => Promise<void>;
progress?: Progress;
/** Stops the captures between steps; model requests take it through agentSessionFactory. */
signal?: AbortSignal;
}) {
const { projects, output, config, environment, state, assertCurrentHead, postComment } = options;
const progress = options.progress ?? silentProgress;
@@ -274,11 +300,11 @@ export async function runCiReview(options: {
...(options.useLocalEasSession ? { useLocalEasSession: true } : {}),
...(exploration.agent ? { agent: exploration.agent } : {}), project: projects[side],
mapDirectory: join(output, `${side}-map`), outputDirectory: directory,
name: config.app.name ?? pr.repository, buildId: pr.origin === "local" ? `local-${pr.runId}-${side}` : `pr-${pr.number}-${side}`, buildVersion: pr[side].sha.slice(0, 8), gitCommit: pr[side].sha,
name: config.app.name ?? pr.repository, buildId: pr.origin === "local" ? `local-${pr.runId}-${side}` : pr.origin === "compare" ? `compare-${options.runId}-${side}` : `pr-${pr.number}-${side}`, buildVersion: pr[side].sha.slice(0, 8), gitCommit: pr[side].sha,
planPath: join(output, "execution-plan.json"), side, sessionStatePath: join(output, `${side}-session`),
...(reuseDirectory ? { reuseDirectory } : {}) };
...(reuseDirectory ? { reuseDirectory } : {}), ...(options.signal ? { signal: options.signal } : {}) };
const captured = concurrent
? await runCiMapOnWorker((({ progress: _progress, runner: _runner, agent: _agent, ...rest }) => rest)(mapOptions), progress)
? await runCiMapOnWorker((({ progress: _progress, runner: _runner, agent: _agent, signal: _signal, ...rest }) => rest)(mapOptions), progress, options.signal)
: await runCiMap(mapOptions);
const bundle = await readCaptureBundle(directory);
bundle.profile = cacheRecipe.profile;
@@ -394,7 +420,7 @@ export async function runCiReview(options: {
}
}
await preserveReport();
progress("writing the report and updating the pull request comment");
progress(pr.origin === "compare" || pr.origin === "local" ? "writing the report" : "writing the report and updating the pull request comment");
await assertCurrentHead(); await postComment();
return { ...result, evidence, inputPath };
} catch (error) {
@@ -413,7 +439,9 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
now?: () => number; sleep?: (milliseconds: number) => void;
agentSessionFactory?: PrepareCiExplorationOptions["createSession"]; progress?: Progress;
/** Use the local `eas login` session instead of EXPO_TOKEN (expo-explore doctor --capture). */
useLocalEasSession?: boolean }) {
useLocalEasSession?: boolean;
/** Agent mode with the local claude or codex login instead of the provider's API key. */
subscription?: boolean }) {
const environment = options.environment ?? process.env;
assertCheckout(options.project, options.sha);
const output = resolve(options.output);
@@ -429,7 +457,7 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
let usagePhase: AgentUsagePhase = "preflight";
const exploration = await prepareCiExploration(options.config, options.project, environment, active,
{ ...(options.agentSessionFactory ? { createSession: options.agentSessionFactory } : {}),
onUsage: recordAgentUsage(output, () => usagePhase) });
onUsage: recordAgentUsage(output, () => usagePhase), ...(options.subscription ? { subscription: true } : {}) });
const directory = join(output, "baseline-export");
usagePhase = "capture-baseline";
const result = await runCiMap({ ...captureOptions(options.config, environment, options.runner, { now: options.now, sleep: options.sleep }), progress,
@@ -439,6 +467,7 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
buildId: `baseline-${options.sha.slice(0, 12)}`, buildVersion: options.sha.slice(0, 8), gitCommit: options.sha,
side: "head", planPath: join(output, "execution-plan.json"), sessionStatePath: join(output, "baseline-session") });
const cacheRecipe = await recipe(options.config, plan, "head", environment, exploration.instructionsSha256);
if (options.subscription) cacheRecipe.toolsCommit += ":local-subscription";
const bundle = await readCaptureBundle(directory); bundle.profile = cacheRecipe.profile;
await writeFile(join(directory, "bundle.json"), JSON.stringify(bundle));
const cached = await writeCaptureArtifactCache(directory, cacheRecipe);
+12 -8
View File
@@ -4,7 +4,9 @@ import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
import { dirname, join, relative } from "node:path";
import { EXPLORE_VERSION, TOOL_ROOT } from "../shared/package-paths.js";
export const WORKFLOW_FILES = ["explore-review.yml", "explore-baseline.yml"] as const;
export const WORKFLOW_FILES = ["explore-review.yml", "explore-baseline.yml", "explore-compare.yml"] as const;
/** Installed by setup but not needed for pull request reviews: doctor reports one that is missing as a warning. */
export const OPTIONAL_WORKFLOW_FILES: ReadonlySet<string> = new Set(["explore-compare.yml"]);
/** Written by setup before npm distribution; CI now installs @expo/explore instead. */
export const LEGACY_VENDOR_DIRECTORY = ".github/vendor/expo-explore";
export const SECRET_ANCHOR = "# App-test secrets: one NAME: line per {{secret:NAME}} input in .expo-explore (expo-explore setup adds them).";
@@ -116,8 +118,8 @@ export function forwardedSecretNames(workflow: string): string[] {
export function renderWorkflow(template: string, options: { projectDir: string; installDir: string; manager: PackageManager | undefined; secretNames: readonly string[] }): string {
let text = pinWorkflowVersion(template)
.replace(/^(\s+APP_PROJECT_DIR:) \.$/m, `$1 ${options.projectDir}`)
.replace(/^(\s+APP_INSTALL_DIR:) \.$/m, `$1 ${options.installDir}`);
.replace(/^(\s+APP_PROJECT_DIR:) \.$/gm, `$1 ${options.projectDir}`)
.replace(/^(\s+APP_INSTALL_DIR:) \.$/gm, `$1 ${options.installDir}`);
if (options.manager && options.manager !== "npm") {
text = text.replace(TEMPLATE_INSTALL, (_match, directory: string) => installCommand(options.manager!, directory));
}
@@ -149,12 +151,14 @@ export function workflowIssues(file: string, text: string, expected: { projectDi
if (!version || !EXACT_VERSION.test(version)) issues.push({ code: "EXPLORE_VERSION_INVALID", file,
message: `${file} does not pin an exact @expo/explore version (EXPLORE_VERSION is ${version ?? "missing"}).`,
nextAction: "Run expo-explore setup --workflows to set it." });
const value = (name: string) => new RegExp(`^\\s+${name}: (.+)$`, "m").exec(text)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
// Workflows generated before 0.19 set these per job; every job must name the same directory.
const values = (name: string) => [...text.matchAll(new RegExp(`^\\s+${name}: (.+)$`, "gm"))].map(match => match[1]!.trim().replace(/^['"]|['"]$/g, ""));
for (const [name, wanted] of [["APP_PROJECT_DIR", expected.projectDir], ["APP_INSTALL_DIR", expected.installDir]] as const) {
const actual = value(name);
if (actual !== wanted) issues.push({ code: "WORKFLOW_APP_DIR_MISMATCH", file,
message: `${name} is ${actual ?? "missing"}, but the app layout needs ${wanted}.`,
nextAction: `Set ${name}: ${wanted} in ${file}.` });
const actual = values(name);
const wrong = actual.find(value => value !== wanted);
if (!actual.length || wrong !== undefined) issues.push({ code: "WORKFLOW_APP_DIR_MISMATCH", file,
message: `${name} is ${actual.length ? wrong : "missing"}${actual.length > 1 ? " in one of its jobs" : ""}, but the app layout needs ${wanted}.`,
nextAction: `Set ${name}: ${wanted} everywhere in ${file}, or rerun expo-explore setup --workflows --force.` });
}
if (expected.manager && expected.manager !== "npm" && /npm ci --ignore-scripts --prefix/.test(text)) {
const command = installCommand(expected.manager, "<dir>");
+218
View File
@@ -0,0 +1,218 @@
import { spawnSync } from "node:child_process";
import { appendFile, lstat, mkdir, writeFile } from "node:fs/promises";
import { join, resolve } from "node:path";
import { tmpdir } from "node:os";
import { pathToFileURL } from "node:url";
import { parseTrustedAuthors, DEFAULT_EXPLORE_CONFIG_PATH } from "../config/explore-config.js";
import { compareTitle, compareUrl, projectComparePresentation, projectPullRequestPresentation,
type CompareReviewPresentation, type PullRequestPresentation } from "../contracts/review.js";
import { CiError } from "../shared/ci-errors.js";
import { readCiReportInput } from "../report/artifact.js";
import { TOOL_ROOT, packageBin } from "../shared/package-paths.js";
/**
* The work the GitHub workflows used to do in inline scripts: deciding which commits a run captures and whether it
* may, finding a baseline to reuse, and cleaning up after capture. Each is one `expo-explore ci:*` command, so a
* fix ships with the npm release instead of a regenerated workflow.
*/
type Environment = NodeJS.ProcessEnv;
const SHA = /^[0-9a-f]{40}$/;
/** `name=value` lines for later steps; a value never spans lines. */
export async function writeStepOutputs(environment: Environment, values: Record<string, string>): Promise<void> {
if (!environment.GITHUB_OUTPUT) return;
await appendFile(environment.GITHUB_OUTPUT, Object.entries(values).map(([name, value]) => `${name}=${value.replace(/[\r\n]+/g, " ")}\n`).join(""));
}
/** `capture:review`'s step output: `preview=eas` when the reviewed config hosts the report, which is what starts the deploy job. */
export async function writeCaptureOutputs(inputPath: string, environment: Environment = process.env): Promise<void> {
await writeStepOutputs(environment, { preview: (await readCiReportInput(inputPath)).preview?.hosting ?? "" });
}
function githubContext(environment: Environment) {
const repository = environment.GITHUB_REPOSITORY ?? "";
const token = environment.GITHUB_TOKEN?.trim();
if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) throw new CiError({ code: "CI_RUN_IDENTITY_MISSING", stage: "preflight",
message: "GITHUB_REPOSITORY is missing.", nextAction: "Run this command inside a GitHub Actions workflow." });
if (!token) throw new CiError({ code: "GITHUB_TOKEN_MISSING", stage: "preflight", message: "GITHUB_TOKEN is missing.",
nextAction: "Pass GitHub's automatic github.token to this step as GITHUB_TOKEN." });
return { repository, token };
}
/** One GitHub REST read; 404 is an answer (undefined), every other failure stops the step with what to do. */
async function githubGet<T>(path: string, context: { token: string }, transport: typeof fetch): Promise<T | undefined> {
let response: Response;
try {
response = await transport(`https://api.github.com/${path}`, { redirect: "error", signal: AbortSignal.timeout(30_000),
headers: { authorization: `Bearer ${context.token}`, accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28" } });
} catch (error) {
throw new CiError({ code: "GITHUB_REQUEST_FAILED", stage: "preflight", message: `GitHub could not be reached (${path}).`,
nextAction: "Check GitHub availability and rerun the workflow.", retryable: true, cause: error });
}
if (response.status === 404) { await response.body?.cancel().catch(() => {}); return undefined; }
if (!response.ok) throw new CiError({ code: response.status === 401 ? "GITHUB_TOKEN_INVALID" : response.status === 403 ? "GITHUB_PERMISSION_DENIED" : "GITHUB_REQUEST_FAILED",
stage: "preflight", message: `GitHub answered HTTP ${response.status} for ${path}.`, retryable: response.status >= 500,
nextAction: response.status === 403 ? "Grant this job the permissions the workflow template gives it, then rerun." : "Rerun the workflow; check GitHub's status if it keeps failing." });
return await response.json() as T;
}
type GithubPull = {
number: number; state: string; draft?: boolean; title: string; html_url: string; user?: { login?: string };
base: { ref: string; sha: string; repo: { id: number; full_name: string; default_branch: string } };
head: { ref: string; sha: string; repo?: { full_name?: string } | null };
};
/**
* `ci:pr`: the live pull request a review captures, refused unless it is open, not a draft, from this repository,
* and written by someone with write access or listed in ci.trustedAuthors of the default branch's config.yaml.
*/
export async function resolvePullRequest(options: { number: number; appDirectory?: string; configPath?: string; environment?: Environment; transport?: typeof fetch }):
Promise<{ presentation: PullRequestPresentation; author: string }> {
const environment = options.environment ?? process.env; const transport = options.transport ?? fetch;
const context = githubContext(environment);
if (!Number.isSafeInteger(options.number) || options.number <= 0) throw new CiError({ code: "PR_NUMBER_INVALID", stage: "preflight",
message: "The pull request number is invalid.", nextAction: "Provide an open pull request number." });
const pr = await githubGet<GithubPull>(`repos/${context.repository}/pulls/${options.number}`, context, transport);
if (!pr || pr.state !== "open" || pr.draft || pr.head.repo?.full_name !== context.repository) throw new CiError({ code: "SOURCE_NOT_TRUSTED", stage: "preflight",
message: "Capture requires an open, non-draft same-repository pull request.", nextAction: "Run Explore for an open pull request from a branch of this repository." });
const author = pr.user?.login ?? "";
const permission = await githubGet<{ permission?: string }>(`repos/${context.repository}/collaborators/${encodeURIComponent(author)}/permission`, context, transport);
if (!["admin", "maintain", "write"].includes(permission?.permission ?? "")) {
const trusted = await trustedAuthors(context, transport, pr.base.repo.default_branch, options.appDirectory, options.configPath);
if (!trusted.logins.includes(author.toLowerCase())) throw new CiError({ code: "SOURCE_NOT_TRUSTED", stage: "preflight",
message: `${author || "The PR author"} has no write access to this repository and is not listed in ci.trustedAuthors.`
+ (trusted.invalid ? ` The default branch's ci.trustedAuthors was ignored: ${trusted.invalid}` : ""),
nextAction: trusted.invalid ? "Fix ci.trustedAuthors in .expo-explore/config.yaml on the default branch, then rerun Explore."
: "The PR author must have current repository write access, or be listed in ci.trustedAuthors of .expo-explore/config.yaml on the default branch." });
}
for (const side of [pr.base, pr.head]) if (!SHA.test(side.sha)) throw new CiError({ code: "PR_COMMIT_INVALID", stage: "preflight",
message: "GitHub returned an invalid commit for the pull request.", nextAction: "Refresh the PR and rerun Explore." });
return { author, presentation: projectPullRequestPresentation({ repositoryId: String(pr.base.repo.id), repository: pr.base.repo.full_name,
number: pr.number, title: pr.title, url: pr.html_url, base: { ref: pr.base.ref, sha: pr.base.sha }, head: { ref: pr.head.ref, sha: pr.head.sha } }) };
}
/** ci.trustedAuthors from the default branch's config: a pull request cannot add its own author. An invalid list trusts no one, and says why. */
async function trustedAuthors(context: { repository: string; token: string }, transport: typeof fetch, branch: string, appDirectory = ".", configPath = DEFAULT_EXPLORE_CONFIG_PATH): Promise<{ logins: string[]; invalid?: string }> {
const directory = appDirectory.replace(/^\.(\/|$)/, "").replace(/\/$/, "");
const path = `${directory ? `${directory}/` : ""}${configPath}`;
const file = await githubGet<{ content?: string }>(`repos/${context.repository}/contents/${path.split("/").map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(branch)}`, context, transport);
if (!file?.content) return { logins: [] };
try { return { logins: parseTrustedAuthors(Buffer.from(file.content, "base64").toString("utf8")).map(login => login.toLowerCase()) }; }
catch (error) { return { logins: [], invalid: error instanceof Error ? error.message : String(error) }; }
}
type GithubArtifact = { id: number; expired: boolean; workflow_run?: { id?: number } };
type GithubRun = { conclusion: string | null; workflow_id: number; head_sha: string; head_branch: string; event: string; head_repository?: { full_name?: string } };
/**
* `ci:find-baseline`: the newest successful baseline-workflow artifact of exactly this commit, uploaded from the
* default branch of this repository. Its id and run go to the step outputs for actions/download-artifact.
*/
export async function findBaselineArtifact(options: { sha: string; platform?: string; environment?: Environment; transport?: typeof fetch }): Promise<{ id: number; run: number } | undefined> {
const environment = options.environment ?? process.env; const transport = options.transport ?? fetch;
const context = githubContext(environment);
if (!SHA.test(options.sha)) throw new CiError({ code: "SHA_INVALID", stage: "preflight", message: "The base commit must be a full SHA.", nextAction: "Pass --sha with a 40-character commit SHA." });
const repository = await githubGet<{ default_branch: string }>(`repos/${context.repository}`, context, transport);
const workflow = await githubGet<{ id: number }>(`repos/${context.repository}/actions/workflows/explore-baseline.yml`, context, transport);
if (!repository || !workflow) return undefined;
// Baselines carry the platform suffix; iOS also accepts the unsuffixed name older baseline workflows uploaded.
const names = [`explore-baseline-${options.sha}-${options.platform ?? "ios"}`, ...(options.platform === "android" ? [] : [`explore-baseline-${options.sha}`])];
const artifacts: GithubArtifact[] = [];
for (const name of names) for (let page = 1; page <= 10; page++) {
const listed = await githubGet<{ artifacts: GithubArtifact[] }>(`repos/${context.repository}/actions/artifacts?name=${encodeURIComponent(name)}&per_page=100&page=${page}`, context, transport);
artifacts.push(...listed?.artifacts ?? []);
if ((listed?.artifacts.length ?? 0) < 100) break;
}
for (const artifact of artifacts.filter(candidate => !candidate.expired).sort((a, b) => b.id - a.id)) {
if (!artifact.workflow_run?.id) continue;
const run = await githubGet<GithubRun>(`repos/${context.repository}/actions/runs/${artifact.workflow_run.id}`, context, transport);
if (!run || run.conclusion !== "success" || run.workflow_id !== workflow.id || run.head_sha !== options.sha
|| run.head_branch !== repository.default_branch || !["push", "workflow_dispatch"].includes(run.event)
|| run.head_repository?.full_name !== context.repository) continue;
return { id: artifact.id, run: artifact.workflow_run.id };
}
return undefined;
}
/**
* `ci:find-baseline` as the workflow runs it: a baseline is optional, so a lookup that fails (a GitHub 5xx, a rate
* limit) is a warning and no baseline, never an error. A `ci:*` error would write explore-diagnostics/error.json,
* which the failure comment would then report as the cause of an unrelated failure, possibly on another platform.
*/
export async function findOptionalBaseline(options: Parameters<typeof findBaselineArtifact>[0]):
Promise<{ baseline?: { id: number; run: number }; warning?: { code: string; message: string } }> {
try {
const baseline = await findBaselineArtifact(options);
return baseline ? { baseline } : {};
} catch (error) {
return { warning: { code: error instanceof CiError ? error.code : "BASELINE_LOOKUP_FAILED",
message: `No baseline is reused, so capture captures the base too: ${error instanceof Error ? error.message : String(error)}` } };
}
}
/**
* The commit a ref names in a checkout. `HEAD` (and `HEAD~1`, `@`) is the checked-out commit, never `origin/HEAD`.
* A name is tried as a tag, then a local branch, then a branch of `origin` (all CI has after a full checkout),
* then as git spells it (a SHA, `origin/main`, `refs/heads/...`).
*/
export function resolveCommit(project: string, ref: string, side: "base" | "head"): string {
if (!ref.trim() || ref.startsWith("-") || /[\s\u0000-\u001f]/.test(ref)) throw new CiError({ code: "COMPARE_REF_INVALID", stage: "preflight",
message: `The ${side} '${ref}' is not a ref.`, nextAction: `Pass ${side} as a branch, tag or commit SHA.` });
const relative = /^(?:HEAD|@)(?:[~^].*)?$/.test(ref);
for (const candidate of relative ? [ref] : [`refs/tags/${ref}`, `refs/heads/${ref}`, `refs/remotes/origin/${ref}`, ref]) {
const result = spawnSync("git", ["-C", project, "rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], { encoding: "utf8" });
if (result.status === 0 && SHA.test(result.stdout.trim())) return result.stdout.trim();
}
throw new CiError({ code: "COMPARE_REF_NOT_FOUND", stage: "preflight", message: `${ref} is not a branch, tag or commit of this repository.`,
nextAction: "Check the ref's spelling, and that the checkout fetched every branch and tag (fetch-depth: 0)." });
}
/**
* `ci:compare-refs`: the commits two refs (branch, tag or SHA) name in a full clone, as the comparison a
* `capture:review --compare` run captures. A tag wins over a branch of the same name.
*/
export function resolveCompareRefs(options: { project: string; base: string; head: string; title?: string; environment?: Environment }): CompareReviewPresentation {
const environment = options.environment ?? process.env;
const repository = environment.GITHUB_REPOSITORY ?? "", repositoryId = environment.GITHUB_REPOSITORY_ID ?? "";
const commit = (ref: string, side: "base" | "head") => resolveCommit(options.project, ref, side);
const base = { ref: options.base, sha: commit(options.base, "base") }, head = { ref: options.head, sha: commit(options.head, "head") };
if (base.sha === head.sha) throw new CiError({ code: "COMPARE_SAME_COMMIT", stage: "preflight",
message: `${options.base} and ${options.head} are the same commit (${head.sha}).`, nextAction: "Compare two different commits; the baseline workflow captures a single one." });
return projectComparePresentation({ origin: "compare", repositoryId, repository, base, head,
title: options.title ?? compareTitle(base, head), url: compareUrl(repository, base, head) });
}
/**
* `ci:after-capture`: after capture, success or not. Stops the EAS Simulator sessions the capture recorded in its output
* directory, then checks that capture left each source checkout as it found it. Reports every problem, then fails.
*/
export async function cleanupAfterCapture(options: { output: string; checkouts: string[]; environment?: Environment }):
Promise<{ stopped: string[]; failures: Array<{ code: string; message: string; nextAction: string }> }> {
const environment = options.environment ?? process.env;
const result: { stopped: string[]; failures: Array<{ code: string; message: string; nextAction: string }> } = { stopped: [], failures: [] };
const sessionFiles: string[] = [];
for (const name of ["head-session", "base-session", "baseline-session"]) {
const path = resolve(options.output, name);
try { await lstat(path); sessionFiles.push(path); } catch { /* That side never started a session. */ }
}
if (sessionFiles.length) {
const script = await import(pathToFileURL(join(TOOL_ROOT, "scripts", "cleanup-ci-sessions.mjs")).href) as {
cleanupCiSessions(input: { sessionFiles: string[]; easCommand: string; environment: Environment }): Promise<{ stopped: string[]; failures: Array<{ code: string; message: string; nextAction: string }> }> };
const sessions = await script.cleanupCiSessions({ sessionFiles, easCommand: packageBin("eas-cli", "eas"), environment });
result.stopped.push(...sessions.stopped); result.failures.push(...sessions.failures);
}
for (const directory of options.checkouts) {
const checkout = resolve(directory);
try { await lstat(join(checkout, ".git")); } catch { continue; }
const status = spawnSync("git", ["-C", checkout, "status", "--porcelain", "--untracked-files=all"], { encoding: "utf8" });
if (status.status !== 0 || status.stdout.trim()) result.failures.push({ code: "CHECKOUT_MODIFIED", message: `Capture modified ${directory}.`,
nextAction: "Keep generated files outside source checkouts." });
}
if (result.failures.length) {
const diagnostics = join(environment.RUNNER_TEMP || tmpdir(), "explore-diagnostics");
await mkdir(diagnostics, { recursive: true });
await writeFile(join(diagnostics, "cleanup.json"), `${JSON.stringify(result, null, 2)}\n`);
}
return result;
}
+9 -2
View File
@@ -9,8 +9,9 @@ import { command, resultContract, argumentError, validateCommandArguments, flag,
import { help } from "./cli/help.js";
import { listScreens, getScreen, listElements, listObservations, getObservation, nextFrontier, listAttempts, getAttempt, listTransitions, getTransition, neighbors, pathQuery, listJourneys, getJourney, listFrontier, listGaps, summary, search, status, validate, exportArtifacts } from "./cli/map-commands.js";
import { compareCommand, exportWeb, view } from "./cli/catalog-commands.js";
import { ciReport, ciPublish, ciFailure, ciDeploy, setup, doctor, sourceVerify, captureReview, captureBaseline, configPlatforms } from "./cli/ci-commands.js";
import { ciReport, ciPublish, ciFailure, ciDeploy, ciPullRequest, ciFindBaseline, ciCompareRefs, ciAfterCapture, setup, doctor, sourceVerify, captureReview, captureBaseline, configPlatforms } from "./cli/ci-commands.js";
import { exploreBinary, exploreSession } from "./cli/binary-commands.js";
import { reports, reportUpload } from "./cli/report-commands.js";
const handlers: Record<string, () => Promise<void> | void> = {
setup,
@@ -38,10 +39,16 @@ const handlers: Record<string, () => Promise<void> | void> = {
"export:web": exportWeb,
"explore:binary": exploreBinary,
"explore:session": exploreSession,
"report:upload": reportUpload,
reports,
"ci:report": ciReport,
"ci:publish": ciPublish,
"ci:failure": ciFailure,
"ci:deploy": ciDeploy,
"ci:pr": ciPullRequest,
"ci:find-baseline": ciFindBaseline,
"ci:compare-refs": ciCompareRefs,
"ci:after-capture": ciAfterCapture,
"capture:review": captureReview,
"capture:baseline": captureBaseline,
"source:verify": sourceVerify,
@@ -58,7 +65,7 @@ const handlers: Record<string, () => Promise<void> | void> = {
};
/** Commands people type at a terminal; everything else answers agents and scripts in JSON. */
const HUMAN_COMMANDS = new Set(["setup", "doctor", "view", "help", "explore:binary", "explore:session"]);
const HUMAN_COMMANDS = new Set(["setup", "doctor", "view", "help", "explore:binary", "explore:session", "report:upload", "reports"]);
function version(): void {
console.log(EXPLORE_VERSION);
+24 -3
View File
@@ -29,12 +29,14 @@ const aliases: Record<string, string> = {
const first = argv[0] ?? "help";
const pair = `${first} ${argv[1] ?? ""}`.trim();
export const command = aliases[pair] ?? first;
export const resultContract = ["source:verify", "capture:review", "capture:baseline", "ci:report", "ci:publish", "ci:failure", "ci:deploy", "config:platforms", "explore:binary", "explore:session"].includes(command)
export const resultContract = ["source:verify", "capture:review", "capture:baseline", "ci:report", "ci:publish", "ci:failure", "ci:deploy", "ci:pr", "ci:find-baseline", "ci:compare-refs", "ci:after-capture", "config:platforms", "explore:binary", "explore:session", "report:upload", "reports"].includes(command)
? "explore.result" : QUERY_CONTRACT;
const commandArgCount = aliases[pair] ? 2 : 1;
const args = argv.slice(commandArgCount);
/** Commands that take one bare argument before their flags, e.g. `explore:binary ./app.apk`. */
const POSITIONAL_COMMANDS = new Set(["explore:binary", "explore:session"]);
/** Commands that take any number of bare arguments among their flags, e.g. `report:upload ios/report.zip android/report.zip`. */
const VARIADIC_COMMANDS = new Set(["report:upload", "reports"]);
const commonFlagKinds: Record<string, "value" | "boolean"> = {
dir: "value",
@@ -78,7 +80,8 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
validate: {},
export: { output: "value" },
"export:web": {catalog:"value",output:"value"},
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", output:"value", config:"value", platform:"value" },
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", platform:"value", scope:"value", "expires-in":"value",
base:"value", head:"value", project:"value", uncommitted:"boolean", "include-untracked":"boolean", upload:"boolean", "no-open":"boolean", "no-cache":"boolean", port:"value" },
@@ -92,6 +95,10 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
"ci:publish": { input:"value", "artifact-url":"value", platform:"value", inputs:"value" },
"ci:failure": { pr:"value", head:"value", base:"value", diagnostics:"value", platform:"value" },
"ci:deploy": { input:"value", report:"value", "artifact-url":"value", platform:"value", inputs:"value", reports:"value" },
"ci:pr": { pr:"value", output:"value", "app-dir":"value", config:"value" },
"ci:find-baseline": { sha:"value", platform:"value" },
"ci:compare-refs": { project:"value", base:"value", head:"value", title:"value", output:"value" },
"ci:after-capture": { output:"value", checkout:"value" },
compare: {
baseline: "value",
current: "value",
@@ -106,6 +113,8 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
},
view: { port: "value", catalog: "value", "no-open": "boolean" },
"report:upload": { owner: "value", project: "value", "expires-in": "value", config: "value" },
reports: { all: "boolean", owner: "value", project: "value", "expires-in": "value", config: "value", port: "value", "no-open": "boolean", "no-intro": "boolean" },
help: { all: "boolean" },
"--help": { all: "boolean" },
"-h": { all: "boolean" },
@@ -127,7 +136,7 @@ export function validateCommandArguments(): void {
for (let index = 0; index < args.length; index += 1) {
const token = args[index]!;
if (!token.startsWith("--")) {
if (index === 0 && POSITIONAL_COMMANDS.has(command)) continue;
if ((index === 0 && POSITIONAL_COMMANDS.has(command)) || VARIADIC_COMMANDS.has(command)) continue;
argumentError(`Unexpected argument: ${token}`);
}
const name = token.slice(2);
@@ -150,6 +159,18 @@ export function positional(): string | undefined {
return POSITIONAL_COMMANDS.has(command) && first !== undefined && !first.startsWith("--") ? first : undefined;
}
/** The bare arguments of a variadic command, in order: every token that is neither a flag nor a flag's value. */
export function positionals(): string[] {
const allowed = { ...commonFlagKinds, ...flagKinds[command] };
const values: string[] = [];
for (let index = 0; index < args.length; index += 1) {
const token = args[index]!;
if (!token.startsWith("--")) values.push(token);
else if (allowed[token.slice(2)] === "value") index += 1;
}
return values;
}
export function flag(name: string): string | undefined {
const index = args.indexOf(`--${name}`);
if (index < 0) return undefined;
+6 -3
View File
@@ -3,7 +3,8 @@ import { basename, join, resolve } from "node:path";
import { DEFAULT_BINARY_PROJECT, runBinaryExploration, runSessionExploration } from "../binary/run.js";
import { openViewerInBrowser, startViewerServer, waitForViewerShutdown } from "../map/viewer-server.js";
import { writeExplorationReport } from "../binary/report.js";
import { assertHostingExport, deployExplorationReport } from "../report/preview-deploy.js";
import { assertHostingExport, deployExplorationReport, zipReportDirectory } from "../report/preview-deploy.js";
import { keepReports } from "./report-commands.js";
import { argumentError, flag, flags, has, nonNegativeInteger, oneOf, output, positional, positiveInteger } from "./args.js";
const MAX_EXPIRY_DAYS = 90;
@@ -54,10 +55,11 @@ export async function exploreBinary(): Promise<void> {
});
say(`exploration ${result.exploration.stopReason}: ${result.exploration.screens} screens, ${result.exploration.observations} captures, ${result.exploration.actions} actions`);
const report = await writeExplorationReport(result, join(outputDirectory, "report"));
await keepReports(async () => [{ platform: result.archive.platform, zip: await zipReportDirectory(report.reportPath) }]);
let hosted: Awaited<ReturnType<typeof deployExplorationReport>> | undefined;
if (!has("no-upload")) {
say("hosting the report on EAS Hosting");
hosted = await deployExplorationReport({ reportPath: report.reportPath, project: flag("project") ?? DEFAULT_BINARY_PROJECT, owner: result.session.owner, expiresAfterDays, ...stableLinkOptions() });
hosted = await deployExplorationReport({ reportPath: report.reportPath, platform: result.archive.platform, project: flag("project") ?? DEFAULT_BINARY_PROJECT, owner: result.session.owner, expiresAfterDays, ...stableLinkOptions() });
say(`report: ${hosted.previewUrl}${hosted.expiresAt ? ` (expires ${hosted.expiresAt})` : ""}`);
}
const summary = { ok: true,
@@ -111,10 +113,11 @@ export async function exploreSession(): Promise<void> {
});
say(`exploration ${result.exploration.stopReason}: ${result.exploration.screens} screens, ${result.exploration.observations} captures, ${result.exploration.actions} actions`);
const report = await writeExplorationReport(result, join(outputDirectory, "report"));
await keepReports(async () => [{ platform: result.app.platform, zip: await zipReportDirectory(report.reportPath) }]);
let hosted: Awaited<ReturnType<typeof deployExplorationReport>> | undefined;
if (has("upload")) {
say("hosting the report on EAS Hosting");
hosted = await deployExplorationReport({ reportPath: report.reportPath, project: flag("project") ?? DEFAULT_BINARY_PROJECT, ...(flag("owner") ? { owner: flag("owner")! } : {}), expiresAfterDays, ...stableLinkOptions() });
hosted = await deployExplorationReport({ reportPath: report.reportPath, platform: result.app.platform, project: flag("project") ?? DEFAULT_BINARY_PROJECT, ...(flag("owner") ? { owner: flag("owner")! } : {}), expiresAfterDays, ...stableLinkOptions() });
say(`report: ${hosted.previewUrl}${hosted.expiresAt ? ` (expires ${hosted.expiresAt})` : ""}`);
}
const summary = { ok: true, app: result.app, device: { model: result.runtime.deviceModel, osVersion: result.runtime.osVersion },
+112 -10
View File
@@ -1,20 +1,25 @@
import { lstat, mkdtemp } from "node:fs/promises";
import { cp, lstat, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { commitSubject, keepReports } from "./report-commands.js";
import { createInterface } from "node:readline/promises";
import { runPublicCi, runBaselineCi } from "../ci/pipeline.js";
import { runPublicCi, runBaselineCi, runCompareCi } from "../ci/pipeline.js";
import { exportCiReport, publishCiReportComment } from "../report/artifact.js";
import { collectPlatformReports, deployPreview } from "../report/preview-deploy.js";
import { collectPlatformReports, deployLocalReports, deployPreview, previewProjectSlug } from "../report/preview-deploy.js";
import { startLocalReportServer } from "../report/local-report-server.js";
import { openViewerInBrowser } from "../map/viewer-server.js";
import { runLocalReview } from "../ci/local-review.js";
import { publishFailureComment } from "../report/failure-comment.js";
import { runExploreSetup } from "../config/setup.js";
import { installCiFiles } from "../ci/workflow-install.js";
import { readRouteEntry } from "../ci/route-entry.js";
import { buildVerifiedPlan } from "../ci/verified-plan.js";
import { formatCaptureCheck, formatDoctorReport, referencedSecretNames, runCaptureCheck, runDoctor } from "../ci/doctor.js";
import { readExploreConfig, readExploreInstructions, resolvePlatformConfig, configPlatforms as listPlatforms, EXPLORE_PLATFORMS, DEFAULT_EXPLORE_CONFIG_PATH, type ExplorePlatform } from "../config/explore-config.js";
import { argumentError, output, required, has, flag, flags, oneOf } from "./args.js";
import { readExploreConfig, readExploreInstructions, resolvePlatformConfig, withRunOverrides, previewDays, configPlatforms as listPlatforms, EXPLORE_PLATFORMS, DEFAULT_EXPLORE_CONFIG_PATH, PREVIEW_DEFAULT_DAYS, type ExplorePlatform } from "../config/explore-config.js";
import { argumentError, output, required, has, flag, flags, nonNegativeInteger, oneOf } from "./args.js";
import { help } from "./help.js";
import { CiError } from "../shared/ci-errors.js";
import { cleanupAfterCapture, findOptionalBaseline, resolveCompareRefs, resolvePullRequest, writeCaptureOutputs, writeStepOutputs } from "../ci/workflow-steps.js";
import { stderrProgress } from "../shared/progress.js";
export async function doctor(): Promise<void> {
@@ -41,7 +46,7 @@ Fix the problems in steps 1–5 before a capture check.`);
if (!has("yes")) {
if (!process.stdin.isTTY || has("json")) argumentError("A capture check starts an EAS build and simulator session; pass --yes to confirm.", "yes");
const terminal = createInterface({ input: process.stdin, output: process.stderr });
const answer = await terminal.question(`This builds the app on EAS and runs an EAS Simulator session (EAS usage applies${report.mode === "agent" ? "; agent mode also uses your model API key" : ""}). Continue? (yes/no) `);
const answer = await terminal.question(`This builds the app on EAS and runs an EAS Simulator session (EAS usage applies${report.mode === "agent" ? "; agent mode also uses your model API key or local claude/codex login" : ""}). Continue? (yes/no) `);
terminal.close();
if (!/^(y|yes)$/i.test(answer.trim())) return;
}
@@ -73,7 +78,9 @@ export async function ciDeploy(): Promise<void> {
const result = has("inputs") || has("reports")
? await deployPreview({ reports: await collectPlatformReports({ inputsPath: required("inputs"), reportsPath: required("reports") }), onSecret })
: await deployPreview({ inputPath: required("input"), reportPath: required("report"), artifactUrl: required("artifact-url"), onSecret });
output({ ok: true, ...result });
// A comparison's token is not masked (see deployPreview), so its link stays out of the log.
const { previewUrl, ...unlinked } = result;
output({ ok: true, ...(result.linkedFromRunSummary ? unlinked : { previewUrl, ...unlinked }) });
}
export async function ciPublish(): Promise<void> {
@@ -93,6 +100,41 @@ export async function ciFailure(): Promise<void> {
...(has("diagnostics") ? { diagnosticsPath: required("diagnostics") } : {}), ...(platform ? { platform } : {}) }) });
}
/** `ci:pr --pr N [--output FILE]`: the live, authorized pull request; its commits go to the step outputs. */
export async function ciPullRequest(): Promise<void> {
const { presentation, author } = await resolvePullRequest({ number: Number(required("pr")),
...(has("app-dir") ? { appDirectory: required("app-dir") } : {}), ...(has("config") ? { configPath: required("config") } : {}) });
if (has("output")) await writeFile(required("output"), JSON.stringify(presentation));
await writeStepOutputs(process.env, { pr_number: String(presentation.number), base: presentation.base.sha, head: presentation.head.sha });
output({ ok: true, pullRequest: presentation, author });
}
/** `ci:find-baseline --sha SHA [--platform P]`: a reusable baseline artifact of the base commit, if one exists. */
export async function ciFindBaseline(): Promise<void> {
const platform = platformFlag();
const { baseline, warning } = await findOptionalBaseline({ sha: required("sha"), ...(platform ? { platform } : {}) });
if (baseline) await writeStepOutputs(process.env, { id: String(baseline.id), run: String(baseline.run) });
if (warning && process.env.GITHUB_ACTIONS) console.log(`::warning title=${warning.code}::${warning.message.replace(/[\r\n]+/g, " ")}`);
output({ ok: true, baseline: baseline ?? null, ...(warning ? { warning } : {}) });
}
/** `ci:compare-refs --project DIR --base REF --head REF [--output FILE]`: the two commits a comparison captures. */
export async function ciCompareRefs(): Promise<void> {
const comparison = resolveCompareRefs({ project: required("project"), base: required("base"), head: required("head"),
...(has("title") ? { title: required("title") } : {}) });
if (has("output")) await writeFile(required("output"), JSON.stringify(comparison));
await writeStepOutputs(process.env, { base: comparison.base.sha, head: comparison.head.sha, compare: JSON.stringify(comparison) });
output({ ok: true, comparison });
}
/** `ci:after-capture --output DIR --checkout DIR...`: stop recorded sessions and check the checkouts are untouched; fails after reporting every problem. */
export async function ciAfterCapture(): Promise<void> {
const result = await cleanupAfterCapture({ output: required("output"), checkouts: flags("checkout") });
for (const failure of result.failures) console.error(`::error title=${failure.code}::${failure.message} ${failure.nextAction}`);
output({ ok: result.failures.length === 0, ...result });
if (result.failures.length) process.exitCode = 1;
}
/** The `--platform` flag, when given; capture then reads that platform's fields from config.yaml. */
export function platformFlag(): ExplorePlatform | undefined {
return has("platform") ? oneOf("platform", EXPLORE_PLATFORMS) : undefined;
@@ -155,13 +197,20 @@ export async function sourceVerify(): Promise<void> {
}
export async function captureReview(): Promise<void> {
// Refs without the CI flags: a review on this machine, with your own logins (see runLocalReview).
if (!has("base-project") && !has("head-project") && !has("pull-request") && !has("compare")) return localReview();
const headProject = required("head-project");
const configPath = flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH;
const platform = platformFlag();
const rawConfig = await readExploreConfig(headProject, configPath);
const config = resolvePlatformConfig(rawConfig, platform);
const result = await runPublicCi({ ...(platform ? { platform } : {}), platforms: listPlatforms(rawConfig), baseProject: required("base-project"), headProject,
pullRequestPath: required("pull-request"), output: required("output"), config, configPath, progress: stderrProgress() });
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: flag("scope"), expiresIn: flag("expires-in") });
if (has("pull-request") === has("compare")) argumentError("Pass --pull-request FILE for a pull request, or --compare FILE for any two commits.", has("compare") ? "compare" : "pull-request");
const common = { ...(platform ? { platform } : {}), platforms: listPlatforms(rawConfig), baseProject: required("base-project"), headProject,
output: required("output"), config, configPath, progress: stderrProgress() };
const result = has("compare") ? await runCompareCi({ ...common, comparePath: required("compare") })
: await runPublicCi({ ...common, pullRequestPath: required("pull-request") });
// The deploy job runs only when the reviewed config asks for a hosted report.
await writeCaptureOutputs(result.inputPath);
output({ ok: true, inputPath: result.inputPath });
}
@@ -171,3 +220,56 @@ export async function captureBaseline(): Promise<void> {
const config = resolvePlatformConfig(await readExploreConfig(project, flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH), platform);
output({ ok: true, ...await runBaselineCi({ ...(platform ? { platform } : {}), project, sha: required("sha"), output: required("output"), config, progress: stderrProgress() }) });
}
/** `capture:review [--base REF] [--head REF | --uncommitted]`: a local review, opened in the Viewer or hosted with --upload. */
async function localReview(): Promise<void> {
const platform = platformFlag();
const result = await runLocalReview({ project: flag("project") ?? process.cwd(), base: flag("base"), head: flag("head"),
uncommitted: has("uncommitted"), untracked: has("include-untracked"), ...(platform ? { platform } : {}),
scope: flag("scope"), expiresIn: flag("expires-in"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
if (has("output")) {
for (const report of result.reports) {
const target = resolve(required("output"), report.platform);
await cp(report.directory, join(target, "report"), { recursive: true });
await cp(report.zip, join(target, "report.zip"));
report.directory = join(target, "report"); report.zip = join(target, "report.zip");
}
// The reports now live under --output; the temporary copies are not needed.
await rm(result.work, { recursive: true, force: true });
}
const summary = { ok: true, runId: result.runId, base: result.base, head: result.head,
reports: result.reports.map(({ platform, directory, zip, changes, device }) => ({ platform, directory, zip, ...(changes === undefined ? {} : { changes }), ...(device ? { device } : {}) })) };
const zips = await Promise.all(result.reports.map(async report => ({ platform: report.platform, zip: new Uint8Array(await readFile(report.zip)),
...(report.changes === undefined ? {} : { changes: report.changes }), ...(report.device ? { device: report.device } : {}) })));
// Kept among the saved runs, with the commits' subjects (an uncommitted head is named by the commit under it).
const project = resolve(flag("project") ?? process.cwd());
const headSubject = commitSubject(project, result.head.uncommitted ? `${result.head.sha}^` : result.head.sha), baseSubject = commitSubject(project, result.base.sha);
const saved = await keepReports(zips.map(({ platform, zip }) => ({ platform, zip })), { subjects: { ...(headSubject ? { head: headSubject } : {}), ...(baseSubject ? { base: baseSubject } : {}) },
...(result.head.uncommitted?.length ? { uncommittedFiles: result.head.uncommitted.length } : {}) });
if (has("upload")) {
const preview = result.config.report?.preview;
const hosted = await deployLocalReports({ reports: zips, project: previewProjectSlug(result.repository, preview?.project), ...(preview?.owner ? { owner: preview.owner } : {}),
// null is expiresAfter: never, which must not fall back to the default.
expiresAfterDays: has("expires-in") ? previewDays(required("expires-in"), "--expires-in") : preview ? preview.expiresAfterDays : PREVIEW_DEFAULT_DAYS });
// Hosted, the temporary copies are not needed (a failed upload keeps them for report:upload); --output keeps its own.
const copied = has("output");
if (!copied) await rm(result.work, { recursive: true, force: true });
if (has("json")) output({ ...summary, ...(copied ? {} : { reports: summary.reports.map(({ directory: _directory, zip: _zip, ...report }) => report) }),
url: hosted.previewUrl, expiresAt: hosted.expiresAt });
else console.log(`Report: ${hosted.previewUrl}${hosted.expiresAt ? ` (until ${hosted.expiresAt.slice(0, 10)})` : ""}`);
return;
}
if (has("json") || has("no-open")) {
if (has("json")) output(summary);
else for (const report of result.reports) console.log(`${report.platform}: ${report.zip}`);
return;
}
const server = await startLocalReportServer({ reports: zips, ...(has("port") ? { port: nonNegativeInteger("port") } : {}) });
console.log(`Viewer: ${server.url} (Ctrl+C to stop)`);
if (saved) console.log(`Saved as ${saved.id}: expo-explore reports reopens it, and reports upload ${saved.id} hosts it.`);
openViewerInBrowser(server.url);
await new Promise<void>(done => { process.once("SIGINT", () => done()); process.once("SIGTERM", () => done()); });
await server.close();
// The Viewer served the reports from memory, and the saved run keeps them; the temporary copy is no longer needed.
if (saved) await rm(result.work, { recursive: true, force: true });
}
+23 -3
View File
@@ -17,8 +17,20 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
(--offline skips EAS and GitHub; --check-model sends one small request with the local provider key)
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--platform ios|android] [--yes]
(captures the committed HEAD like the baseline workflow, with your eas login, and reports each route)
capture:review [--base REF] [--head REF | --uncommitted [--include-untracked]] [--platform ios|android] [--scope all|changes]
[--upload [--expires-in 7d|30d|never]] [--no-open] [--no-cache] [--output DIRECTORY] [--project DIRECTORY]
(on this machine: checks out both commits in temporary worktrees, captures them with your eas login and your
local claude or codex login, and opens the report; the base defaults to where HEAD left the default branch;
it runs both commits' code as you, so review only commits you would run)
view [--catalog FILE] [--port N] [--no-open]
(opens a report in the Viewer)`;
(opens a report in the Viewer)
reports [list | open ID | add REPORT... | upload ID | rm ID | prune] [--all] [--json]
(the runs kept on this machine: local reviews, explorations and uploaded reports, for 30 days or up to 2 GB;
in a terminal, an arrow-key picker: Enter opens a run in the local Viewer, u hosts it, d deletes it;
ID is a run's id from reports list, or latest; EXPLORE_INTRO=off skips the title animation)
report:upload <report.zip | report directory>... [--owner ACCOUNT] [--project SLUG] [--expires-in 7d|30d|never] [--config FILE] [--json]
(hosts reports already on this machine on EAS Hosting behind one link, with your eas login: one per platform
of the same review, from capture:review --output or a downloaded explore-review artifact, or one explore:binary report)`;
const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your local claude or codex login):
explore:binary <app.apk | app.app | app.tar.gz | simulator .ipa> [--output DIRECTORY] [--no-upload] [--json]
@@ -45,8 +57,9 @@ const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your
const CI = `CI (the installed workflows run these; they manage remote EAS Simulator sessions):
config:platforms [--project DIRECTORY] [--config FILE]
(lists the platforms config.yaml captures; the review workflow's matrix)
capture:review --base-project DIRECTORY --head-project DIRECTORY --pull-request FILE
capture:review --base-project DIRECTORY --head-project DIRECTORY (--pull-request FILE | --compare FILE)
--output TEMP_DIRECTORY [--config .expo-explore/config.yaml] [--platform ios|android]
(--compare reviews any two commits without a PR: {"origin":"compare","repositoryId","repository","base":{ref,sha},"head":{ref,sha}})
capture:baseline --project DIRECTORY --sha COMMIT --output TEMP_DIRECTORY [--config FILE] [--platform ios|android]
source:verify --base-project DIRECTORY --head-project DIRECTORY
--base-sha COMMIT --head-sha COMMIT --output DIRECTORY [--config FILE] [--scope all|changes] [--platform ios|android]
@@ -58,7 +71,14 @@ const CI = `CI (the installed workflows run these; they manage remote EAS Simula
ci:publish --input REPORT_INPUT --artifact-url GITHUB_ARTIFACT_URL [--platform ios|android]
ci:publish --inputs DIRECTORY (one <platform>/ subdirectory per captured platform)
ci:deploy --input REPORT_INPUT --report REPORT_DIR --artifact-url GITHUB_ARTIFACT_URL [--platform ios|android]
ci:deploy --inputs DIRECTORY --reports DIRECTORY`;
ci:deploy --inputs DIRECTORY --reports DIRECTORY
ci:pr --pr N [--output FILE] [--app-dir DIRECTORY]
(resolves the live PR and refuses it unless it is open, from this repository, and by a trusted author)
ci:compare-refs --project DIRECTORY --base REF --head REF [--output FILE]
ci:find-baseline --sha COMMIT [--platform ios|android]
ci:after-capture --output TEMP_DIRECTORY --checkout DIRECTORY...
(stops the capture's EAS Simulator sessions and checks capture left each checkout unchanged)
(the ci:* commands write their results to $GITHUB_OUTPUT for the next steps)`;
const MAP_QUERIES = `Map queries (for coding agents reading a local exploration map; JSON output, never provision devices):
summary
+239
View File
@@ -0,0 +1,239 @@
import { spawnSync } from "node:child_process";
import { readFile, stat } from "node:fs/promises";
import { basename, dirname, join, relative, resolve, sep } from "node:path";
import { DEFAULT_BINARY_PROJECT } from "../binary/run.js";
import { pruneCaptureCache, repositoryName } from "../ci/local-review.js";
import { readExploreConfig, previewDays, DEFAULT_EXPLORE_CONFIG_PATH, PREVIEW_DEFAULT_DAYS, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
import { assertHostingExport, deployLocalReports, previewProjectSlug, readReportZip, zipReportDirectory, MAX_REPORT_BYTES, type ReportZipSummary } from "../report/preview-deploy.js";
import { startLocalReportServer } from "../report/local-report-server.js";
import { findSavedRun, listSavedRuns, pruneSavedRuns, readSavedReports, removeSavedRun, saveRun, savedRunsDirectory, SAVED_RUN_LIMITS, type SavedReport, type SavedRun } from "../report/saved-runs.js";
import { openViewerInBrowser } from "../map/viewer-server.js";
import { formatBytes, friendlyTime, kindLabel, runPicker, runTitle } from "./reports-picker.js";
import { pickIntro } from "./title-intros.js";
import { CiError, toCiError } from "../shared/ci-errors.js";
import { argumentError, flag, has, nonNegativeInteger, output, positionals, required } from "./args.js";
/** explore:binary's default: an exploration link is for a quick look. */
const EXPLORATION_DEFAULT_DAYS = 7;
/** A report directory (review.json or exploration.json and assets/), its parent holding report.zip, or a report ZIP. */
async function readReport(path: string): Promise<{ path: string; zip: Uint8Array; summary: ReportZipSummary }> {
const target = resolve(process.cwd(), path);
const info = await stat(target).catch(() => undefined);
if (!info) argumentError(`There is no report at ${path}`, undefined, "Pass a report.zip or report directory that exists.");
try {
// A ZIP is sized before it is read: nothing larger than a hosted report can be is loaded into memory.
const readZip = async (file: string) => {
if ((await stat(file)).size > MAX_REPORT_BYTES) throw new Error(`${path} is larger than the ${MAX_REPORT_BYTES / 1024 / 1024} MiB a hosted report can be`);
return new Uint8Array(await readFile(file));
};
let zip: Uint8Array;
if (!info.isDirectory()) zip = await readZip(target);
else if (await stat(join(target, "report.zip")).then(file => file.isFile()).catch(() => false)) zip = await readZip(join(target, "report.zip"));
else zip = await zipReportDirectory(target);
return { path, zip, summary: await readReportZip(zip) };
} catch (error) {
throw toCiError(error, { code: "REPORT_ZIP_FAILED", stage: "export",
nextAction: `${path} is not an Explore report. Pass a report.zip or report directory written by capture:review, explore:binary or ci:report, or a downloaded explore-review artifact.` });
}
}
type PreviewSettings = NonNullable<ExploreConfig["report"]>["preview"];
/** `<app>/.expo-explore/config.yaml` as the app directory and the path config readers take. */
function configLocation(file: string): { app: string; path: string } {
return basename(dirname(file)) === ".expo-explore" ? { app: dirname(dirname(file)), path: relative(dirname(dirname(file)), file) } : { app: dirname(file), path: basename(file) };
}
/**
* The report.preview a review's own uploads use: from --config, or else from this repository's committed config when the
* reports are this repository's (the one in the current directory, or the only one, as in a monorepo). Says which.
*/
async function repositoryPreview(repository: string): Promise<{ preview: PreviewSettings; source: string } | undefined> {
const explicit = flag("config");
if (explicit) {
const { app, path } = configLocation(resolve(process.cwd(), explicit));
return { preview: (await readExploreConfig(app, path)).report?.preview, source: explicit };
}
const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd(), encoding: "utf8" });
if (top.status !== 0) return undefined;
const root = top.stdout.trim();
const listed = spawnSync("git", ["ls-files", "--full-name", "--", ":(glob)**/.expo-explore/config.yaml"], { cwd: root, encoding: "utf8" });
const committed = listed.status === 0 ? listed.stdout.split("\n").filter(Boolean) : [];
const here = relative(root, join(process.cwd(), DEFAULT_EXPLORE_CONFIG_PATH)).split(sep).join("/");
const file = committed.includes(here) ? here : committed.length === 1 ? committed[0]! : undefined;
if (!file) return undefined;
const { app, path } = configLocation(join(root, file));
const config = await readExploreConfig(app, path);
return repositoryName(root, config) === repository ? { preview: config.report?.preview, source: file } : undefined;
}
type ReadReport = Awaited<ReturnType<typeof readReport>>;
/** Several reports share one link only as one review's platforms; an exploration goes up on its own. */
function assertOneReview(reports: ReadReport[]): void {
const [first, ...others] = reports as [ReadReport, ...ReadReport[]];
const platforms = new Set<ExplorePlatform>([first.summary.platform]);
for (const report of others) {
if (platforms.has(report.summary.platform)) throw new CiError({ code: "PREVIEW_REPORTS_INVALID", stage: "preflight",
message: `More than one ${report.summary.platform} report: one link holds one report per platform.`, nextAction: "Upload each platform's report once." });
platforms.add(report.summary.platform);
const a = first.summary, b = report.summary;
if (a.kind !== "review" || b.kind !== "review" || a.repository !== b.repository || a.runId !== b.runId || a.base !== b.base || a.head !== b.head) {
throw new CiError({ code: "PREVIEW_REPORTS_MISMATCH", stage: "preflight", message: `${first.path} and ${report.path} are not the same review's platforms.`,
nextAction: "Upload the reports of one review together (one per platform), and anything else on its own." });
}
}
}
/** Hosts checked reports in the project `--upload` would have used (flags win), and prints the link. */
async function hostReports(reports: ReadReport[]): Promise<void> {
await assertHostingExport();
const first = reports[0]!;
const review = first.summary.kind === "review" ? first.summary : undefined;
const found = review ? await repositoryPreview(review.repository) : undefined;
const preview = found?.preview;
if (review) process.stderr.write(found ? `report.preview from ${found.source}\n`
: `no config of ${review.repository} here: hosting with the defaults (pass --config, or --owner, --project and --expires-in)\n`);
const project = flag("project") ?? (review ? previewProjectSlug(review.repository, preview?.project) : DEFAULT_BINARY_PROJECT);
const owner = flag("owner") ?? preview?.owner;
const expiresAfterDays = has("expires-in") ? previewDays(required("expires-in"), "--expires-in")
: preview ? preview.expiresAfterDays : review ? PREVIEW_DEFAULT_DAYS : EXPLORATION_DEFAULT_DAYS;
const hosted = await deployLocalReports({ project, ...(owner ? { owner } : {}), expiresAfterDays,
reports: reports.map(report => ({ platform: report.summary.platform, zip: report.zip,
...(report.summary.changes === undefined ? {} : { changes: report.summary.changes }), ...(report.summary.device ? { device: report.summary.device } : {}) })),
ownerHint: "Pass --owner with the Expo account that should host the report.",
projectHint: "Give this EAS login permission to create projects under the owner, or pass --project with an existing project slug." });
if (has("json")) {
output({ ok: true, url: hosted.previewUrl, expiresAt: hosted.expiresAt, project: hosted.project, owner: hosted.owner,
reports: reports.map(report => ({ path: report.path, platform: report.summary.platform, kind: report.summary.kind })) });
return;
}
console.log(`Report: ${hosted.previewUrl}${hosted.expiresAt ? ` (until ${hosted.expiresAt.slice(0, 10)})` : ""}`);
console.log(`Hosted on @${hosted.owner}/${hosted.project}. Anyone with the link can open it.`);
}
/** Keeps reports among the saved runs; a failure to keep them never fails the command that made them. */
export async function keepReports(reports: SavedReport[] | (() => Promise<SavedReport[]>), extra: Parameters<typeof saveRun>[1] = {}): Promise<SavedRun | undefined> {
try { return await saveRun(typeof reports === "function" ? await reports() : reports, extra); }
catch (error) { process.stderr.write(`Could not keep this run in expo-explore reports: ${error instanceof Error ? error.message : String(error)}\n`); return undefined; }
}
/** The subject line of a commit, when this checkout has it. */
export function commitSubject(cwd: string, sha: string): string | undefined {
// --end-of-options: a commit named by a report is never read as one of git's options.
const result = spawnSync("git", ["log", "-1", "--format=%s", "--end-of-options", sha], { cwd, encoding: "utf8" });
return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : undefined;
}
/**
* `report:upload <report.zip | report directory>...`: hosts reports already on this machine behind one token-gated EAS
* Hosting link, as `capture:review --upload` and `explore:binary` do for the report they just wrote. Several reports
* must be one review's platforms; a review goes to the repository's preview project, an exploration to expo-explore.
* The reports are also kept among the saved runs (`expo-explore reports`).
*/
export async function reportUpload(): Promise<void> {
const paths = positionals();
if (!paths.length) argumentError("Pass the report to host: expo-explore report:upload ios/report.zip", undefined,
"Run expo-explore report:upload with a report.zip or report directory, one per platform of the same review.");
const reports: ReadReport[] = [];
for (const path of paths) reports.push(await readReport(path));
assertOneReview(reports);
const review = reports[0]!.summary.kind === "review" ? reports[0]!.summary : undefined;
const head = review && commitSubject(process.cwd(), review.head), base = review && commitSubject(process.cwd(), review.base);
await keepReports(reports.map(report => ({ platform: report.summary.platform, zip: report.zip })), { subjects: { ...(head ? { head } : {}), ...(base ? { base } : {}) } });
await hostReports(reports);
}
/** Serves reports in the local Viewer, opens it, and waits for Ctrl+C. */
export async function openInViewer(reports: SavedReport[]): Promise<void> {
const server = await startLocalReportServer({ reports, ...(has("port") ? { port: nonNegativeInteger("port") } : {}) });
console.log(`Viewer: ${server.url} (Ctrl+C to stop)`);
if (!has("no-open")) openViewerInBrowser(server.url);
await new Promise<void>(done => { process.once("SIGINT", () => done()); process.once("SIGTERM", () => done()); });
await server.close();
}
/** This checkout's GitHub repository (owner/name), which saved reviews name; undefined outside one. */
function currentRepository(): string | undefined {
const remote = spawnSync("git", ["remote", "get-url", "origin"], { cwd: process.cwd(), encoding: "utf8" });
const match = remote.status === 0 ? /github\.com[:/]([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(remote.stdout.trim()) : null;
return match ? `${match[1]}/${match[2]}` : undefined;
}
async function savedRun(id: string | undefined): Promise<SavedRun> {
if (!id) argumentError("Name the run: an id from expo-explore reports list, or latest", undefined, "Run expo-explore reports list to see the saved runs.");
const run = await findSavedRun(id);
if (!run) throw new CiError({ code: "REPORT_RUN_NOT_FOUND", stage: "preflight", message: id === "latest" ? "There are no saved runs yet." : `There is no saved run ${id}.`,
nextAction: "Run expo-explore reports list to see the saved runs." });
return run;
}
async function uploadSavedRun(run: SavedRun): Promise<void> {
const reports: ReadReport[] = [];
for (const report of await readSavedReports(run)) reports.push({ path: `${run.id}/${report.platform}.zip`, zip: report.zip, summary: await readReportZip(report.zip) });
await hostReports(reports);
}
function listLines(runs: SavedRun[], now = Date.now()): string[] {
if (!runs.length) return ["No saved runs yet. expo-explore capture:review reviews your branch on this machine, and its report is kept here."];
const idWidth = Math.max(...runs.map(run => run.id.length));
return [...runs.map(run => `${run.id.padEnd(idWidth)} ${kindLabel(run).padEnd(9)}${runTitle(run)} (${run.platforms.join(", ")}, ${friendlyTime(run.createdAt, now)})`),
"", "Open one with: expo-explore reports open <id>"];
}
/**
* `reports [list | open ID | add REPORT... | upload ID | rm ID | prune] [--all] [--json]`: the runs kept on this machine. In a terminal
* with no subcommand it is an arrow-key picker (Enter opens the run in the local Viewer, u hosts it); elsewhere it lists.
* ID is a run's id or `latest`.
*/
export async function reports(): Promise<void> {
const [subcommand = "", id, ...rest] = positionals();
const all = await listSavedRuns();
const repository = currentRepository();
const scoped = has("all") || !repository || !all.some(run => run.repository === repository) ? all : all.filter(run => run.repository === repository);
const totalBytes = () => all.reduce((sum, run) => sum + run.bytes, 0);
switch (subcommand) {
case "open": return openInViewer(await readSavedReports(await savedRun(id)));
case "add": {
// A report already on disk (a downloaded explore-review artifact, say), kept like a run made here, without hosting it.
const paths = [id, ...rest].filter((path): path is string => !!path);
if (!paths.length) argumentError("Pass the report to keep: expo-explore reports add ios/report.zip", undefined, "Run expo-explore reports add with a report.zip or report directory, one per platform of the same review.");
const read: ReadReport[] = [];
for (const path of paths) read.push(await readReport(path));
assertOneReview(read);
const review = read[0]!.summary.kind === "review" ? read[0]!.summary : undefined;
const head = review && commitSubject(process.cwd(), review.head), base = review && commitSubject(process.cwd(), review.base);
const run = await saveRun(read.map(report => ({ platform: report.summary.platform, zip: report.zip })), { subjects: { ...(head ? { head } : {}), ...(base ? { base } : {}) } });
if (has("json")) output({ ok: true, run }); else console.log(`Kept ${runTitle(run)} as ${run.id}.`);
return;
}
case "upload": return uploadSavedRun(await savedRun(id));
case "rm": {
const run = await savedRun(id);
await removeSavedRun(run.id);
if (has("json")) output({ ok: true, removed: run.id }); else console.log(`Deleted ${runTitle(run)} (${run.id}).`);
return;
}
case "prune": {
const removed = await pruneSavedRuns();
const captures = await pruneCaptureCache(process.env);
if (has("json")) output({ ok: true, removed: removed.map(run => run.id), captures: captures.length });
else console.log(removed.length || captures.length
? `Removed ${removed.length} run${removed.length === 1 ? "" : "s"} and ${captures.length} cached capture${captures.length === 1 ? "" : "s"} kept longer than ${SAVED_RUN_LIMITS.maxAgeDays} days or past ${formatBytes(SAVED_RUN_LIMITS.maxBytes)}.`
: "Nothing to prune.");
return;
}
case "list": case "": break;
default: argumentError(`Unknown reports subcommand: ${subcommand}`, undefined, "Use expo-explore reports, or reports list, open, add, upload, rm or prune.");
}
if (has("json")) { output({ ok: true, runs: scoped, bytes: totalBytes(), directory: savedRunsDirectory() }); return; }
if (subcommand === "list" || !process.stdin.isTTY || !process.stdout.isTTY || process.env.CI) { for (const line of listLines(scoped)) console.log(line); return; }
const color = !process.env.NO_COLOR && process.env.TERM !== "dumb";
const action = await runPicker({ runs: all, ...(repository ? { repository } : {}),
scope: scoped === all ? "all" : "repository", filter: "", filtering: false, selected: 0, offset: 0 },
{ input: process.stdin, output: process.stdout, color, intro: color && !has("no-intro") ? pickIntro(process.env) : undefined,
remove: async run => { await removeSavedRun(run.id); all.splice(all.findIndex(each => each.id === run.id), 1); }, totalBytes });
if (action.type === "open") { console.log(`${runTitle(action.run)}`); await openInViewer(await readSavedReports(action.run)); }
else if (action.type === "upload") { console.log(`Hosting ${runTitle(action.run)}…`); await uploadSavedRun(action.run); }
}
+299
View File
@@ -0,0 +1,299 @@
import { cleanRun, type SavedRun } from "../report/saved-runs.js";
import { intros, WORDMARK, type IntroName, type Paint } from "./title-intros.js";
/**
* The `expo-explore reports` picker: one aligned line per saved run, the selected run's details in a strip below,
* arrow keys to move, Enter to open. Rendering and key handling are pure (state in, lines or state out); `runPicker`
* owns the terminal: the alternate screen, raw input, resizes and the intro.
*/
export type PickerState = {
runs: SavedRun[];
/** This repository (owner/name), when run inside one with saved runs; `tab` switches to every repository. */
repository?: string;
scope: "repository" | "all";
filter: string;
filtering: boolean;
selected: number;
offset: number;
/** The run awaiting `y` to delete. */
confirming?: string | undefined;
message?: string | undefined;
};
export type PickerAction = { type: "open" | "upload" | "delete"; run: SavedRun } | { type: "quit" };
export type Key = "up" | "down" | "pageup" | "pagedown" | "home" | "end" | "enter" | "escape" | "tab" | "backspace" | "quit" | { text: string };
const PLAIN: Paint = { white: s => s, text: s => s, dim: s => s, faint: s => s, amber: s => s, green: s => s, yellow: s => s, blue: s => s, red: s => s };
const sgr = (code: string) => (text: string) => `\x1b[${code}m${text}\x1b[0m`;
export const COLOR: Paint = { white: sgr("1;97"), text: sgr("97"), dim: sgr("38;5;244"), faint: sgr("38;5;238"), amber: sgr("38;5;214"), green: sgr("38;5;114"),
yellow: sgr("38;5;221"), blue: sgr("38;5;111"), red: sgr("38;5;203") };
/** The selected row's background, kept across the row's own colour resets so it reaches the end of the line. */
const SELECT = (text: string) => `\x1b[48;5;236m${text.replaceAll("\x1b[0m", "\x1b[0m\x1b[48;5;236m")}\x1b[0m`;
const visible = (text: string) => text.replace(/\x1b\[[0-9;]*m/g, "");
const length = (text: string) => [...visible(text)].length;
const pad = (text: string, width: number) => text + " ".repeat(Math.max(0, width - length(text)));
/** A line cut to `width` visible columns, keeping its colour codes and closing them. */
function fit(line: string, width: number): string {
if (length(line) <= width) return line;
let out = "", count = 0;
for (const part of line.split(/(\x1b\[[0-9;]*m)/)) {
if (part.startsWith("\x1b[")) { out += part; continue; }
for (const ch of part) { if (count === width - 1) return `${out}…${out.includes("\x1b[") ? "\x1b[0m" : ""}`; out += ch; count += 1; }
}
return out;
}
const cut = (text: string, width: number) => [...text].length > width ? `${[...text].slice(0, Math.max(0, width - 1)).join("")}…` : text;
export function formatBytes(bytes: number): string {
if (bytes < 1024 * 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`;
if (bytes < 1024 ** 3) return `${Math.round(bytes / 1024 / 1024)} MB`;
return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
}
/** "5 min ago", "this morning", "yesterday", "last Sunday", then "Oct 12" (with the year when it is not this year). */
export function friendlyTime(iso: string, now = Date.now()): string {
const then = new Date(iso), today = new Date(now);
const minutes = Math.floor((now - then.getTime()) / 60_000);
if (minutes < 1) return "just now";
if (minutes < 60) return `${minutes} min ago`;
const midnight = new Date(today.getFullYear(), today.getMonth(), today.getDate()).getTime();
const days = Math.ceil((midnight - then.getTime()) / 86_400_000);
if (then.getTime() >= midnight) return then.getHours() < 12 ? "this morning" : then.getHours() < 18 ? "this afternoon" : "this evening";
if (days <= 1) return "yesterday";
if (days < 7) return `last ${then.toLocaleDateString("en-US", { weekday: "long" })}`;
return then.toLocaleDateString("en-US", { month: "short", day: "numeric", ...(then.getFullYear() === today.getFullYear() ? {} : { year: "numeric" }) });
}
export function kindLabel(run: SavedRun): string {
return run.kind === "local" ? "Local" : run.kind === "compare" ? "Compare" : run.kind === "exploration" ? "Explore" : `PR #${run.number ?? "?"}`;
}
/** What the list calls a run: a local review of uncommitted changes says how many files; the rest use the report's title. */
export function runTitle(run: SavedRun): string {
if (run.kind === "local" && run.uncommittedFiles && run.base) return `HEAD + ${run.uncommittedFiles} uncommitted file${run.uncommittedFiles === 1 ? "" : "s"} vs ${run.base.ref}`;
if (run.kind === "compare" && run.base && run.head) return `${run.base.ref} → ${run.head.ref}`;
return run.title;
}
const PLATFORM_NAMES: Record<string, string> = { ios: "iOS", android: "Android" };
const platforms = (run: SavedRun) => run.platforms.map(platform => PLATFORM_NAMES[platform] ?? platform).join(" ");
/** The runs the list shows: this repository's (or all) that match the filter, across title, refs, subjects, SHAs and PR number. */
export function visibleRuns(state: PickerState): SavedRun[] {
const query = state.filter.trim().toLowerCase();
return state.runs.filter(run => (state.scope === "all" || !state.repository || run.repository === state.repository)
&& (!query || [runTitle(run), run.title, kindLabel(run), run.repository, run.head?.ref, run.head?.sha, run.head?.subject, run.base?.ref, run.base?.sha, run.base?.subject,
run.explored?.app].some(field => field?.toLowerCase().includes(query))));
}
function counts(run: SavedRun, paint: Paint): string {
if (run.explored) return `${paint.text(String(run.explored.screens))} ${paint.dim("screens")} ${paint.dim(`${run.explored.unexplored} unexplored`)}`;
const parts = ([["modified", paint.amber, "modified"], ["accessibility-only", paint.blue, "accessibility only"], ["added", paint.green, "added"], ["removed", paint.red, "removed"],
["needs-review", paint.yellow, "need review"]] as const)
.filter(([group]) => run.changes?.[group]).map(([group, colour, label]) => `${colour(String(run.changes![group]))} ${paint.dim(label)}`);
return parts.length ? parts.join(" ") : paint.dim("no visible changes");
}
const KIND_COLOUR = (run: SavedRun, paint: Paint) => ({ local: paint.blue, compare: paint.text, exploration: paint.green, "pull-request": paint.amber }[run.kind]);
/** The whole screen for a terminal `width` × `height`, top to bottom. */
export function renderPicker(state: PickerState, options: { width: number; height: number; now?: number; color?: boolean; totalBytes: number; header?: string[] }): string[] {
const paint = options.color === false ? PLAIN : COLOR;
const select = options.color === false ? (text: string) => text : SELECT;
const width = Math.max(40, options.width), now = options.now ?? Date.now();
// Runs are made plain when saved and read; drawing them again plain keeps a hand-edited run.json from reaching the terminal.
const runs = visibleRuns(state).map(cleanRun);
const scope = state.scope === "all" || !state.repository ? "all repositories" : state.repository;
const subtitle = paint.dim(`${state.runs.length} saved run${state.runs.length === 1 ? "" : "s"} · ${formatBytes(options.totalBytes)} on disk · ${scope}`);
const tall = options.height >= 20 && width >= WORDMARK[0]!.length + 6;
const header = options.header ?? (tall ? ["", ...WORDMARK.map(row => ` ${paint.white(row)}`), "", ` ${subtitle}`, ""] : [` ${paint.white("Expo Explore")} ${subtitle}`, ""]);
const rule = paint.faint("─".repeat(width));
// Columns: kind, title (what is left), head SHA, platforms, when; the SHA and platforms go first when narrow.
const wide = width >= 72;
const fixed = 2 + 9 + 2 + (wide ? 2 + 7 + 2 + 11 : 0) + 2 + 14;
const titleWidth = Math.max(12, width - fixed);
const row = (run: SavedRun) => [pad(KIND_COLOUR(run, paint)(kindLabel(run)), 9), " ", pad(cut(runTitle(run), titleWidth), titleWidth),
...(wide ? [" ", paint.dim(pad(run.head?.sha.slice(0, 7) ?? "", 7)), " ", paint.dim(pad(cut(platforms(run), 11), 11))] : []), " ", paint.dim(cut(friendlyTime(run.createdAt, now), 14))].join("");
const footer: string[] = [rule];
if (state.filtering) footer.push(` ${paint.amber("/")} ${state.filter}${paint.amber("▏")} ${paint.dim(`${runs.length} of ${state.runs.length} · Esc clears · ⏎ done`)}`);
else if (state.confirming) {
const run = state.runs.find(each => each.id === state.confirming);
footer.push(` ${paint.red("Delete")} ${paint.white(run ? cut(runTitle(run), 50) : state.confirming)} ${paint.dim(`(${formatBytes(run?.bytes ?? 0)})`)}? ${paint.dim("y/N")}`);
} else {
const keys = width >= 80 ? `↑↓ move ⏎ open / filter u upload d delete${state.repository ? " tab all repos" : ""} q quit`
: `↑↓ ⏎ open / filter u upload d delete${state.repository ? " tab" : ""} q`;
footer.push(` ${state.message ? `${paint.text(state.message)} ` : ""}${paint.dim(keys)}`);
}
if (!runs.length) {
const empty = state.runs.length
? [` ${paint.dim(state.filter ? `Nothing matches "${state.filter}".` : `No saved runs of ${state.repository}. Press tab for every repository.`)}`]
: [` ${paint.text("No saved runs yet.")}`, ` ${paint.dim("expo-explore capture:review reviews your branch on this machine, and its report is kept here.")}`];
return [...header, ...empty, "", ...footer].map(line => fit(line, width));
}
const selected = runs[Math.min(state.selected, runs.length - 1)]!;
const detail = [rule, ` ${paint.white(runTitle(selected))}${selected.repository && state.scope === "all" ? paint.dim(` ${selected.repository}`) : ""}`];
if (selected.explored) detail.push(` ${paint.dim("app ")} ${selected.explored.app}${selected.explored.version ? ` ${selected.explored.version}` : ""}${selected.explored.buildNumber ? ` (${selected.explored.buildNumber})` : ""}`, "");
else {
const commit = (label: string, side: SavedRun["head"], uncommitted?: number) => side
? ` ${paint.dim(label)} ${(label === "head" ? paint.amber : paint.dim)(side.sha.slice(0, 7))} ${cut(side.subject ?? side.ref, width - 20)}${uncommitted ? paint.dim(` + ${uncommitted} uncommitted`) : ""}${side.subject && side.ref !== "HEAD" && !/^[0-9a-f]{7,40}$/.test(side.ref) && side.subject !== side.ref ? paint.dim(` ${side.ref}`) : ""}`
: "";
detail.push(commit("head", selected.head, selected.uncommittedFiles), commit("base", selected.base));
}
detail.push(` ${counts(selected, paint)}${selected.device ? paint.dim(` · ${selected.device}`) : ""}`);
// The list gets whatever the header, details and footer leave, and scrolls to keep the selection in view.
const room = Math.max(3, options.height - header.length - detail.length - footer.length);
const index = Math.min(state.selected, runs.length - 1);
const offset = Math.min(Math.max(state.offset, index - room + 1, 0), index);
const list = runs.slice(offset, offset + room).map((run, position) => offset + position === index
? select(`${paint.amber("▌")} ${pad(row(run), width - 3)}`) : ` ${row(run)}`);
// The details follow the list; what is left over sits above the keys, so a short list does not float away from them.
return [...header, ...list, ...detail, ...Array.from({ length: room - list.length }, () => ""), ...footer].map(line => fit(line, width));
}
/** One key against the state: the next state, and an action when the key asks for one. */
export function reducePicker(state: PickerState, key: Key, pageSize = 10): { state: PickerState; action?: PickerAction } {
const runs = visibleRuns(state);
const at = Math.min(state.selected, Math.max(0, runs.length - 1));
const move = (to: number): { state: PickerState } => ({ state: { ...state, selected: Math.max(0, Math.min(runs.length - 1, to)), message: undefined } });
if (state.confirming) {
const run = state.runs.find(each => each.id === state.confirming);
const next: PickerState = { ...state, confirming: undefined };
return typeof key === "object" && key.text.toLowerCase() === "y" && run ? { state: next, action: { type: "delete", run } } : { state: { ...next, message: "Kept it." } };
}
// Ctrl+C always quits, whatever the picker is in the middle of.
if (key === "quit") return { state, action: { type: "quit" } };
if (state.filtering) {
if (key === "escape") return { state: { ...state, filtering: false, filter: "", selected: 0, offset: 0 } };
if (key === "enter") return { state: { ...state, filtering: false } };
if (key === "backspace") return { state: { ...state, filter: [...state.filter].slice(0, -1).join(""), selected: 0, offset: 0 } };
if (key === "up" || key === "down") return reducePicker({ ...state, filtering: false }, key, pageSize);
if (typeof key === "object") return { state: { ...state, filter: state.filter + key.text, selected: 0, offset: 0 } };
return { state };
}
const run = runs[at];
switch (key) {
case "up": return move(at - 1);
case "down": return move(at + 1);
case "pageup": return move(at - pageSize);
case "pagedown": return move(at + pageSize);
case "home": return move(0);
case "end": return move(runs.length - 1);
case "enter": return run ? { state, action: { type: "open", run } } : { state };
case "tab": return state.repository ? { state: { ...state, scope: state.scope === "all" ? "repository" : "all", selected: 0, offset: 0, message: undefined } } : { state };
case "escape": return state.filter ? { state: { ...state, filter: "", selected: 0, offset: 0 } } : { state, action: { type: "quit" } };
case "backspace": return { state };
}
switch (key.text) {
case "j": return move(at + 1);
case "k": return move(at - 1);
case "g": return move(0);
case "G": return move(runs.length - 1);
case "/": return { state: { ...state, filtering: true, message: undefined } };
case "u": return run ? { state, action: { type: "upload", run } } : { state };
case "d": return run ? { state: { ...state, confirming: run.id, message: undefined } } : { state };
case "q": return { state, action: { type: "quit" } };
}
return { state };
}
/**
* Raw terminal input to keys; a paste or several keys in one chunk become several keys. Escape sequences the picker has
* no use for (Delete, F-keys, modified arrows, Alt+key) are consumed whole and ignored, so they never read as Esc.
*/
export function decodeKeys(data: string): Key[] {
const keys: Key[] = [];
const named: Record<string, Key> = { "[A": "up", OA: "up", "[B": "down", OB: "down", "[5~": "pageup", "[6~": "pagedown",
"[H": "home", OH: "home", "[1~": "home", "[F": "end", OF: "end", "[4~": "end" };
let rest = data;
while (rest) {
if (rest.startsWith("\x1b")) {
// CSI: ESC [ parameters final byte; SS3: ESC O and one byte; Alt+key: ESC and the key; a lone ESC is Esc.
const sequence = /^\x1b(\[[0-?]*[ -/]*[@-~]|O.|[^[O])/s.exec(rest);
if (!sequence) { keys.push("escape"); rest = rest.slice(1); continue; }
const key = named[sequence[1]!];
if (key) keys.push(key);
rest = rest.slice(sequence[0].length);
continue;
}
const [first] = rest;
rest = rest.slice(first!.length);
if (first === "\r" || first === "\n") keys.push("enter");
else if (first === "\t") keys.push("tab");
else if (first === "\x7f" || first === "\b") keys.push("backspace");
else if (first === "\x03" || first === "\x04") keys.push("quit");
else if (first! >= " " && !/[\u007f-\u009f]/.test(first!)) keys.push({ text: first! });
}
return keys;
}
export type PickerTerminal = {
input: NodeJS.ReadStream; output: NodeJS.WriteStream;
color: boolean; intro?: IntroName | undefined;
/** Deletes a run; the picker drops it from the list. */
remove: (run: SavedRun) => Promise<void>;
totalBytes: () => number;
};
/** Shows the picker until the person opens, uploads or quits; the terminal is restored before it returns. */
export async function runPicker(initial: PickerState, terminal: PickerTerminal): Promise<PickerAction> {
const { input, output } = terminal;
let state = initial;
const size = () => ({ width: output.columns || 80, height: output.rows || 24 });
const paint = terminal.color ? COLOR : PLAIN;
const draw = (header?: string[]) => {
const lines = renderPicker(state, { ...size(), color: terminal.color, totalBytes: terminal.totalBytes(), ...(header ? { header } : {}) });
output.write(`\x1b[H${lines.map(line => `${line}\x1b[K`).join("\n")}\x1b[J`);
};
output.write("\x1b[?1049h\x1b[?25l");
input.setRawMode(true);
input.setEncoding("utf8");
input.resume();
const pending: Key[] = [];
let wake: (() => void) | undefined;
const onData = (data: string) => { pending.push(...decodeKeys(data)); wake?.(); };
const onResize = () => draw();
input.on("data", onData);
output.on("resize", onResize);
try {
// The intro plays where the wordmark will rest, with the list already drawn under it; any key skips it.
const { height, width } = size();
if (terminal.intro && height >= 20 && width >= WORDMARK[0]!.length + 6) {
const intro = intros(Date.now())[terminal.intro];
const start = Date.now();
for (;;) {
const t = Math.min(1, (Date.now() - start) / intro.duration);
draw(["", ...intro.frame(t, paint).map(row => ` ${row}`), "", "", ""]);
if (t === 1 || pending.length) break;
await new Promise(done => setTimeout(done, 16));
}
// A key that skipped the intro only skips it; Ctrl+C still quits.
const quit = pending.includes("quit");
pending.length = 0;
if (quit) pending.push("quit");
}
draw();
for (;;) {
if (!pending.length) await new Promise<void>(done => { wake = done; });
wake = undefined;
while (pending.length) {
const result = reducePicker(state, pending.shift()!, Math.max(1, size().height - 16));
state = result.state;
const action = result.action;
if (action?.type === "delete") {
await terminal.remove(action.run);
state = { ...state, runs: state.runs.filter(run => run.id !== action.run.id), message: `Deleted ${runTitle(action.run)}.` };
} else if (action) return action;
}
draw();
}
} finally {
input.off("data", onData);
output.off("resize", onResize);
input.setRawMode(false);
input.pause();
output.write("\x1b[?25h\x1b[?1049l");
}
}
+91
View File
@@ -0,0 +1,91 @@
/**
* The "Expo Explore" wordmark `expo-explore reports` opens with, and the five ways it can arrive. One is picked at
* random each launch (EXPLORE_INTRO names one, or `off`). Each intro is a function of progress t (0..1) to the
* wordmark's two rows, so it can be drawn at any frame rate and tested without a terminal.
*/
export type Paint = Record<"white" | "text" | "dim" | "faint" | "amber" | "green" | "yellow" | "blue" | "red", (text: string) => string>;
export type Intro = { duration: number; frame: (t: number, paint: Paint) => string[] };
// A two-row pixel font: one column between letters, three between words.
const GLYPHS: Record<string, [string, string]> = { e: ["█▀▀", "██▄"], x: ["▀▄▀", "█ █"], p: ["█▀█", "█▀▀"], o: ["█▀█", "█▄█"], l: ["█ ", "█▄▄"], r: ["█▀█", "█▀▄"] };
export const WORDMARK: string[] = [0, 1].map(row => "expo explore".split(" ").map(word => [...word].map(letter => GLYPHS[letter]![row]).join(" ")).join(" "));
const WIDTH = WORDMARK[0]!.length;
const NOISE = [..."░▒▓▚▞▖▗▘▝◆◇○●■□▪▫"];
const ease = (t: number) => 1 - (1 - t) ** 3;
/** A small seeded random, so an intro plays the same way for the same seed (and in tests). */
function seeded(seed: number): () => number {
let state = seed % 2147483647 || 1;
return () => { state = (state * 16807) % 2147483647; return state / 2147483647; };
}
const cells = (fn: (ch: string, row: number, column: number) => string) => WORDMARK.map((row, r) => [...row].map((ch, c) => fn(ch, r, c)).join(""));
export function intros(seed = 7): Record<"slider" | "decrypt" | "beams" | "snap" | "slide", Intro> {
const random = seeded(seed);
// decrypt: when each letter locks in.
const lock = WORDMARK.map(row => [...row].map(() => 0.3 + random() * 0.6));
// snap: letters start in each other's places and each snaps home at its own moment.
const swaps = WORDMARK.map(row => {
const map = [...row].map((_, c) => c);
const letters = map.filter(c => row[c] !== " ");
for (let i = 0; i < letters.length * 0.35; i += 1) {
const a = letters[Math.floor(random() * letters.length)]!, b = letters[Math.floor(random() * letters.length)]!;
[map[a], map[b]] = [map[b]!, map[a]!];
}
return map.map((from, c) => ({ from, at: from === c ? 0 : 0.3 + random() * 0.5 }));
});
const noise = () => NOISE[Math.floor(random() * NOISE.length)]!;
return {
// The Viewer's compare slider: the crisp "after" behind the handle, the faded "before" ahead of it.
slider: { duration: 600, frame: (t, paint) => {
const at = Math.round(ease(t) * WIDTH);
return cells((ch, _r, c) => c === at && t < 1 ? paint.amber("┃") : c < at ? paint.white(ch) : paint.faint(ch === " " ? " " : "░"));
} },
// Every letter cycles through noise, then locks in with an amber flash.
decrypt: { duration: 900, frame: (t, paint) => cells((ch, r, c) => {
if (ch === " ") return " ";
const at = lock[r]![c]!;
if (t < at) return (t < 0.15 ? paint.faint : paint.blue)(noise());
return t < at + 0.07 ? paint.amber(ch) : paint.white(ch);
}) },
// A diagonal beam of light draws the wordmark as it passes.
beams: { duration: 700, frame: (t, paint) => {
const beam = t * (WIDTH + 16) - 6;
return cells((ch, r, c) => {
const distance = c + r * 3 - beam;
return distance > 0 ? " " : distance > -3 ? paint.amber(ch === " " ? "·" : ch) : distance > -6 ? paint.yellow(ch) : paint.white(ch);
});
} },
// A visual diff resolving: misplaced letters (amber, modified) snap home (green), then settle.
snap: { duration: 900, frame: (t, paint) => cells((ch, r, c) => {
const { from, at } = swaps[r]![c]!;
const original = WORDMARK[r]![from]!;
if (t < 0.12) return paint.faint(original === " " ? " " : "░");
if (at === 0) return paint.text(ch);
if (t < at) return paint.amber(original);
return t < at + 0.1 ? paint.green(ch) : paint.white(ch);
}) },
// Letters glide in from the right one after another, gray to white.
slide: { duration: 800, frame: (t, paint) => WORDMARK.map(row => {
const out = Array.from({ length: WIDTH + 24 }, () => " ");
for (let c = 0; c < WIDTH; c += 1) {
if (row[c] === " ") continue;
const local = Math.min(1, Math.max(0, (t - (c / WIDTH) * 0.5) / 0.5));
if (local === 0) continue;
out[c + Math.round((1 - ease(local)) * 24)] = (local < 1 ? paint.dim : paint.white)(row[c]!);
}
return out.join("").trimEnd();
}) },
};
}
export const INTRO_NAMES = ["slider", "decrypt", "beams", "snap", "slide"] as const;
export type IntroName = (typeof INTRO_NAMES)[number];
/** EXPLORE_INTRO when it names one (or `off`), otherwise a random one. */
export function pickIntro(environment: NodeJS.ProcessEnv, random = Math.random): IntroName | undefined {
const chosen = environment.EXPLORE_INTRO?.trim().toLowerCase();
if (chosen === "off" || chosen === "none") return undefined;
if (chosen && (INTRO_NAMES as readonly string[]).includes(chosen)) return chosen as IntroName;
return INTRO_NAMES[Math.floor(random() * INTRO_NAMES.length)];
}
+43 -5
View File
@@ -365,6 +365,25 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
device: { name: entry.device ?? (primary ? config.device.name : platform === "android" ? DEFAULT_ANDROID_DEVICE : config.device.name) } };
}
/**
* One run's choices over the reviewed config, from the workflow that started it: a release comparison can capture
* every screen (`scope: all`) and keep its hosted link (`expiresIn: never`). `expiresIn` changes nothing when the
* config hosts no report.
*/
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined }): ExploreConfig {
let result = config;
if (overrides.scope !== undefined) {
if (overrides.scope !== "changes" && overrides.scope !== "all") fail("--scope must be changes or all", "--scope");
result = { ...result, exploration: { ...result.exploration, scope: overrides.scope } };
}
if (overrides.expiresIn !== undefined) {
// Validated even without hosting, so a typo in a release workflow surfaces before hosting is turned on.
const expiresAfterDays = previewDays(overrides.expiresIn, "--expires-in");
if (result.report?.preview) result = { ...result, report: { ...result.report, preview: { ...result.report.preview, expiresAfterDays } } };
}
return result;
}
/** `expiresAfter` is a whole number of days (`30d`, `30 days`, or `30`), at most PREVIEW_MAX_DAYS, or `never` (null). */
export function previewDays(value: unknown, field: string): number | null {
if (value === undefined) return PREVIEW_DEFAULT_DAYS;
@@ -385,11 +404,15 @@ function ciConfig(value: unknown): ExploreConfig["ci"] {
const ci = record(value, "ci");
exactKeys(ci, ["trustedAuthors"], "ci");
if (ci.trustedAuthors === undefined) return {};
if (!Array.isArray(ci.trustedAuthors)) fail("ci.trustedAuthors must be a list of GitHub logins", "ci.trustedAuthors");
if (ci.trustedAuthors.length > TRUSTED_AUTHORS_MAX) {
return { trustedAuthors: trustedAuthorList(ci.trustedAuthors) };
}
function trustedAuthorList(value: unknown): string[] {
if (!Array.isArray(value)) fail("ci.trustedAuthors must be a list of GitHub logins", "ci.trustedAuthors");
if (value.length > TRUSTED_AUTHORS_MAX) {
fail(`ci.trustedAuthors lists at most ${TRUSTED_AUTHORS_MAX} logins`, "ci.trustedAuthors");
}
const trustedAuthors = ci.trustedAuthors.map((entry, index) => {
const trustedAuthors = value.map((entry, index) => {
const login = text(entry, `ci.trustedAuthors[${index}]`, 64);
if (!GITHUB_LOGIN.test(login)) {
fail(`ci.trustedAuthors[${index}] must be a GitHub login such as devin-ai-integration[bot]`, `ci.trustedAuthors[${index}]`);
@@ -399,7 +422,7 @@ function ciConfig(value: unknown): ExploreConfig["ci"] {
if (new Set(trustedAuthors.map(login => login.toLowerCase())).size !== trustedAuthors.length) {
fail("ci.trustedAuthors lists a login twice", "ci.trustedAuthors");
}
return { trustedAuthors };
return trustedAuthors;
}
function reportConfig(value: unknown): ExploreConfig["report"] {
@@ -425,8 +448,23 @@ function reportConfig(value: unknown): ExploreConfig["report"] {
} };
}
/**
* ci.trustedAuthors alone, from a config the rest of which may be incomplete or from another release: the review
* workflow's trust check reads only this list from the default branch, and other keys, under ci: too, are ignored.
*/
export function parseTrustedAuthors(source: string): string[] {
const value = plainDocument(source);
const ci = value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>).ci : undefined;
const list = ci && typeof ci === "object" && !Array.isArray(ci) ? (ci as Record<string, unknown>).trustedAuthors : undefined;
return list === undefined ? [] : trustedAuthorList(list);
}
/** Parse YAML as plain data: no anchors, aliases, merge keys, or custom tags. */
export function parseExploreConfig(source: string): ExploreConfig {
return validateExploreConfig(plainDocument(source));
}
function plainDocument(source: string): unknown {
if (Buffer.byteLength(source) > MAX_CONFIG_BYTES) fail("file is too large");
const document = parseDocument(source, { uniqueKeys: true, merge: false, schema: "core" });
if (document.errors.length > 0) fail(document.errors[0]!.message.split("\n")[0]!);
@@ -436,7 +474,7 @@ export function parseExploreConfig(source: string): ExploreConfig {
fail("custom tags are not allowed");
}
});
return validateExploreConfig(document.toJS());
return document.toJS();
}
/** Credential gate for active agent execution; never call during static planning. */
+16 -1
View File
@@ -8,12 +8,13 @@ const REVIEW_STATUSES = new Set(["added", "modified", "removed", "unchanged", "n
const SOURCE_SCOPES = new Set(["screen", "app-wide", "none"]);
/** Verdicts each source scope allows: only a source change makes a screen a review target. */
const SCOPE_VERDICTS: Record<string, readonly string[]> = {
screen: ["modified", "needs-review"],
screen: ["modified", "needs-review", "unchanged"],
"app-wide": ["modified", "needs-review", "unchanged"],
none: ["unchanged", "variant"],
};
const VISUAL_VERDICTS = new Set(["unchanged", "modified", "needs-review"]);
const MAX_REVIEW_DESCRIPTION = 160;
const LEGACY_NO_VISIBLE_DIFFERENCE = "Source changed; no visible difference was captured.";
/** Source analysis belongs to capture planning; delivered reports contain runtime review evidence. */
/** Capture shrinks the app icon to at most this many pixels on a side. */
@@ -31,6 +32,14 @@ function hasVerifiedPair(surface: Surface): boolean {
&& surface[`${side}Outcome`]?.landing === "verified");
}
/**
* A modified screen whose verified screenshots match: only what assistive technology reads (its accessibility tree)
* changed. Screen readers and voice control see it, so it is a change to review, listed apart from the visual ones.
*/
export function isAccessibilityOnlyChange(surface: Surface): boolean {
return surface.review?.status === "modified" && surface.visual?.verdict === "unchanged" && hasVerifiedPair(surface);
}
function assertReviewFields(surface: Surface, enforceComparisonEvidence: boolean): void {
const assertVerifiedPair = () => {
if (enforceComparisonEvidence && !hasVerifiedPair(surface)) {
@@ -207,6 +216,12 @@ export function normalizePublicReviewForReading(review: PublicReview, onGap?: (g
surface = { ...surface, review: { ...surface.review, status: "variant",
description: description.length > MAX_REVIEW_DESCRIPTION ? `${description.slice(0, MAX_REVIEW_DESCRIPTION - 1)}…` : description } };
}
// Reports before 0.19.1 called a screen whose source changed but whose captures matched "needs review". It has no
// visible change, so it reads as unchanged and is not counted as a change.
if (surface.review?.status === "needs-review" && surface.review.description === LEGACY_NO_VISIBLE_DIFFERENCE) {
changed = true;
surface = { ...surface, review: { ...surface.review, status: "unchanged", description: "No visible change" } };
}
const comparisonVerdict = surface.review && surface.review.status !== "added" && surface.review.status !== "removed";
if (!((!hasVerifiedPair(surface) && (comparisonVerdict || surface.visual)) || surface.visual?.reason === "diff-failed")) return surface;
changed = true;
+59 -10
View File
@@ -32,10 +32,48 @@ export type LocalReviewPresentation = {
number?: never;
url?: never;
};
export type ReviewPresentation = PullRequestPresentation | LocalReviewPresentation;
/** Any two commits of a GitHub repository, compared without a pull request: a tag against the last release, a nightly against yesterday. */
export type CompareReviewPresentation = {
origin: "compare";
repositoryId: string;
repository: string;
title: string;
/** github.com's compare page for the two commits. */
url: string;
base: PullRequestSidePresentation;
head: PullRequestSidePresentation;
number?: never;
};
export type ReviewPresentation = PullRequestPresentation | LocalReviewPresentation | CompareReviewPresentation;
/** "v1.4.0 vs v1.3.0": the title a comparison gets when its caller names none; a ref given as a SHA reads as its short form. */
export function compareTitle(base: PullRequestSidePresentation, head: PullRequestSidePresentation): string {
const name = (side: PullRequestSidePresentation) => /^[0-9a-f]{40}$/i.test(side.ref) ? side.sha.slice(0, 8) : side.ref;
return `${name(head)} vs ${name(base)}`;
}
/**
* The title for Markdown (job summaries): refs may contain ] ) < >, which would break a line's links, so each
* ref, or a caller's own title, is a code span.
*/
export function compareTitleMarkdown(comparison: CompareReviewPresentation): string {
const code = (value: string) => `\`${value.replace(/`/g, "'")}\``;
if (comparison.title !== compareTitle(comparison.base, comparison.head)) return code(comparison.title);
const name = (side: PullRequestSidePresentation) => /^[0-9a-f]{40}$/i.test(side.ref) ? side.sha.slice(0, 8) : side.ref;
return `${code(name(comparison.head))} vs ${code(name(comparison.base))}`;
}
/**
* github.com's two-dot comparison: the direct diff between the two commits, as capture compares them. The three-dot
* form diffs from their merge base, which shows nothing for a rollback and drops base-only changes on diverged branches.
*/
export function compareUrl(repository: string, base: PullRequestSidePresentation, head: PullRequestSidePresentation): string {
return `https://github.com/${repository}/compare/${base.sha}..${head.sha}`;
}
export function projectReviewPresentation(value: unknown): ReviewPresentation {
const candidate = record(value, "Review presentation");
if (candidate.origin === "compare") return projectComparePresentation(value);
if (candidate.origin !== "local") return projectPullRequestPresentation(value);
exactKeys(candidate, ["origin", "repository", "runId", "title", "base", "head"], [], "Local review");
const runId = text(candidate.runId, "Local run", 160);
@@ -137,17 +175,14 @@ function fullSha(value: unknown, label: string): string {
return candidate.toLowerCase();
}
/** Whether a report may name a ref as given: no leading or trailing slash, `..`, backslash or reflog syntax (`@{`). */
export function isSafeBranchRef(candidate: string): boolean {
return !(candidate.startsWith("/") || candidate.endsWith("/") || candidate.includes("..") || candidate.includes("\\") || candidate.includes("@{"));
}
function branchRef(value: unknown, label: string): string {
const candidate = text(value, label, 255);
if (
candidate.startsWith("/")
|| candidate.endsWith("/")
|| candidate.includes("..")
|| candidate.includes("\\")
|| candidate.includes("@{")
) {
throw new Error(`${label} is not a safe branch ref`);
}
if (!isSafeBranchRef(candidate)) throw new Error(`${label} is not a safe branch ref`);
return candidate;
}
@@ -167,6 +202,20 @@ function pullRequestSide(value: unknown, label: string): PullRequestSidePresenta
};
}
/** Strictly project a two-commit comparison before it enters a published workspace; its URL is always github.com's compare page. */
export function projectComparePresentation(value: unknown): CompareReviewPresentation {
const candidate = record(value, "Comparison presentation");
exactKeys(candidate, ["origin", "repositoryId", "repository", "base", "head"], ["title", "url"], "Comparison presentation");
const repo = repository(candidate.repository);
const base = pullRequestSide(candidate.base, "base");
const head = pullRequestSide(candidate.head, "head");
if (base.sha === head.sha) throw new Error("comparison base and head must be different commits");
const url = compareUrl(repo, base, head);
if (candidate.url !== undefined && candidate.url !== url) throw new Error("comparison URL must be the github.com compare URL of its two commits");
return { origin: "compare", repositoryId: repositoryId(candidate.repositoryId), repository: repo,
title: candidate.title === undefined ? compareTitle(base, head) : text(candidate.title, "comparison title", 512), url, base, head };
}
/** Strictly project live GitHub PR metadata before it enters a published workspace. */
export function projectPullRequestPresentation(value: unknown): PullRequestPresentation {
const candidate = record(value, "Pull request presentation");
@@ -4,10 +4,11 @@
* shell carries for fetchers that convert HTML to text. It reads the decrypted archive directly, so
* it only picks the fields it publishes from the report JSON and treats everything else as untrusted.
*/
import { readZipDirectory, readZipEntry, type ZipEntry } from "./report-zip";
import { readZipDirectory, readZipEntry, type ZipEntry } from "./zip-reader.js";
export const AGENT_API_VERSION = "v1";
const MAX_METADATA_BYTES = 64 * 1024 * 1024;
/** The largest review.json or exploration.json a hosted report reads. */
export const MAX_METADATA_BYTES = 64 * 1024 * 1024;
const MAX_ASSET_BYTES = 32 * 1024 * 1024;
const MAX_RAW_BYTES = 8 * 1024 * 1024;
const DEFAULT_LIMIT = 50;
@@ -97,7 +98,8 @@ function reviewSurfaceItem(context: AgentContext, surface: Json): Json {
const visual = rec(surface.visual), review = rec(surface.review);
const id = str(surface.id) ?? "";
return defined({
id, route: str(route.route), kind: str(route.kind), routeFile: str(route.routeFile), status: str(surface.status), colorScheme: str(surface.colorScheme),
id, route: str(route.route), kind: str(route.kind), routeFile: str(route.routeFile), status: verdictOf(surface),
sourceStatus: verdictOf(surface) === str(surface.status) ? undefined : str(surface.status), colorScheme: str(surface.colorScheme),
review: surface.review === undefined ? undefined : defined({ status: str(review.status), description: str(review.description), facts: arr(review.facts).map(fact => str(rec(fact).bullet)).filter(Boolean) }),
visual: surface.visual === undefined ? undefined : defined({ verdict: str(visual.verdict), reason: str(visual.reason), mismatchPercentage: num(visual.mismatchPercentage), threshold: num(visual.threshold) }),
note: str(rec(surface.note).text),
@@ -119,19 +121,66 @@ function reviewSurfaceDetail(context: AgentContext, review: Json, surface: Json)
}
const edgeItem = (edge: Json): Json => defined({ from: str(edge.from), to: str(edge.to), kind: str(edge.kind), sourceFile: str(edge.sourceFile), provenance: str(edge.provenance) });
/**
* A screen's status as the Viewer and the PR comment show it: the review's verdict where there is one, so `modified`
* means a visible change. A screen whose source changed but whose captures match is unchanged, including in reports
* from before 0.19.1, which called it "needs review". A modified screen whose screenshots match changed only in what
* assistive technology reads: `accessibility-only`. A screen whose capture failed is `unavailable`, and one whose
* source changed but that has no verdict was not compared: `not-compared`.
*/
/** Both sides captured at their verified destination route, as a verdict requires (isAccessibilityOnlyChange in the contract). */
function verifiedPair(surface: Json): boolean {
return (["base", "head"] as const).every(side => str(rec(surface[side]).kind) === "screen" && Boolean(surface[`${side}Image`])
&& str(rec(surface[`${side}Outcome`]).status) === "captured" && str(rec(surface[`${side}Outcome`]).landing) === "verified");
}
/** The side's planned capture ended without a screenshot, or captured another screen than the route (the Viewer's Unavailable). */
function captureUnavailable(surface: Json, side: "base" | "head"): boolean {
const outcome = surface[`${side}Outcome`];
if (str(rec(surface[side]).kind) !== "screen" || outcome === undefined) return false;
const image = Boolean(surface[`${side}Image`]);
if (!image) return str(rec(outcome).status) !== "captured";
return str(rec(outcome).status) === "captured" && str(rec(outcome).landing) !== "verified" && rec(outcome).observed !== undefined;
}
function verdictOf(surface: Json): string | undefined {
// A capture that failed is unavailable, as the Viewer says, whatever the source or an older verdict claims.
if (str(surface.status) !== "removed" && captureUnavailable(surface, "head")) return "unavailable";
if (["modified", "unchanged"].includes(str(surface.status) ?? "") && captureUnavailable(surface, "base")) return "unavailable";
const review = rec(surface.review);
const status = str(review.status);
if (status === "needs-review" && str(review.description) === "Source changed; no visible difference was captured.") return "unchanged";
if (status === "modified" && str(rec(surface.visual).verdict) === "unchanged" && verifiedPair(surface)) return "accessibility-only";
// A source change nobody compared is not a change Explore saw.
if (status === undefined && str(surface.status) === "modified") return "not-compared";
return status ?? str(surface.status);
}
const STATUS_ORDER = ["modified", "accessibility-only", "added", "removed", "needs-review", "unavailable", "not-compared", "unchanged", "variant"];
const STATUS_WORDS: Record<string, string> = { "accessibility-only": "accessibility only (screenshots match, the accessibility tree does not)",
"needs-review": "need review", "not-compared": "not compared", variant: "screen variants" };
/** "3 modified, 1 added, 1 removed, 30 unchanged": every status counted, so the parts add up to the total. */
function screenCounts(screens: Json): string {
const statuses = Object.keys(screens).filter(status => status !== "total")
.sort((left, right) => (STATUS_ORDER.indexOf(left) + 1 || 99) - (STATUS_ORDER.indexOf(right) + 1 || 99));
const parts = statuses.flatMap(status => (num(screens[status]) ? [`${num(screens[status])} ${STATUS_WORDS[status] ?? status}`] : []));
return parts.length ? parts.join(", ") : "none";
}
function reviewSummary(context: AgentContext, review: Json): Json {
const surfaces = arr(review.surfaces).map(rec);
const counts: Record<string, number> = {};
for (const surface of surfaces) { const status = str(surface.status) ?? "unknown"; counts[status] = (counts[status] ?? 0) + 1; }
for (const surface of surfaces) { const status = verdictOf(surface) ?? "unknown"; counts[status] = (counts[status] ?? 0) + 1; }
const pr = rec(review.pullRequest), runtime = rec(review.runtime);
return defined({
kind: "pr-review", api: AGENT_API_VERSION, contract: str(review.contract),
pullRequest: defined({ repository: str(pr.repository), number: num(pr.number), title: str(pr.title), url: str(pr.url), head: str(rec(pr.head).sha), base: str(rec(pr.base).sha) }),
pullRequest: defined({ origin: str(pr.origin), repository: str(pr.repository), number: num(pr.number), title: str(pr.title), url: str(pr.url), head: str(rec(pr.head).sha), base: str(rec(pr.base).sha) }),
app: defined({ name: str(runtime.appName), version: str(runtime.appVersion), build: str(runtime.appBuildNumber), platform: str(runtime.platform) ?? context.platform, device: rec(runtime.device).model === undefined ? undefined : `${str(rec(runtime.device).model)} ${str(rec(runtime.device).osVersion) ?? ""}`.trim() }),
createdAt: str(review.createdAt), mode: str(review.mode), platforms: context.platforms, expiresAt: context.expiresAt,
screens: { total: surfaces.length, ...counts },
links: {
screens: withPlatform(context, apiUrl(context, "/screens")), changed: withPlatform(context, apiUrl(context, "/screens?status=modified,added,removed")),
screens: withPlatform(context, apiUrl(context, "/screens")), changed: withPlatform(context, apiUrl(context, "/screens?status=modified,accessibility-only,added,removed")),
transitions: withPlatform(context, apiUrl(context, "/transitions")), raw: withPlatform(context, apiUrl(context, "/raw")),
viewer: viewerUrl(context), viewerChanges: viewerUrl(context, { focus: "modified", inspect: "diff" }), markdown: `${context.pageUrl}/llms.txt`,
},
@@ -211,11 +260,14 @@ export function agentIndexMarkdown(context: AgentContext, loaded: LoadedReport):
const lines: string[] = [];
if (loaded.kind === "pr-review") {
const pr = rec(summary.pullRequest);
lines.push(`# Expo Explore report: ${escapeMd(app.name ?? pr.repository)} PR #${escapeMd(pr.number)}${app.platform ? ` (${escapeMd(app.platform)})` : ""}`, "",
`> Visual review of pull request ${escapeMd(pr.repository)}#${escapeMd(pr.number)} by Expo Explore. ${screens.total} screens captured: ${screens.modified ?? 0} modified, ${screens.added ?? 0} added, ${screens.removed ?? 0} removed, ${screens.unchanged ?? 0} unchanged.${context.expiresAt ? ` This link stops serving the report after ${context.expiresAt}.` : ""}`, "",
// A comparison of two commits has a title ("v1.4.0 vs v1.3.0") where a pull request has a number.
// A comparison of two commits, or a local review on someone's machine, has no pull request: its title names both refs.
const compared = pr.origin === "compare" || pr.origin === "local";
lines.push(`# Expo Explore report: ${escapeMd(app.name ?? pr.repository)} ${compared ? escapeMd(pr.title) : `PR #${escapeMd(pr.number)}`}${app.platform ? ` (${escapeMd(app.platform)})` : ""}`, "",
`> Visual review of ${compared ? `${escapeMd(pr.repository)} ${escapeMd(pr.title)}` : `pull request ${escapeMd(pr.repository)}#${escapeMd(pr.number)}`} by Expo Explore. ${screens.total} screens: ${screenCounts(screens)}.${context.expiresAt ? ` This link stops serving the report after ${context.expiresAt}.` : ""}`, "",
"This URL is the human Viewer. The same report is available as read-only JSON (no credentials beyond this URL):", "",
`- [Summary](${links.summary ?? withPlatform(context, apiUrl(context))}): kind, counts by status, app and PR identity, links`,
`- [Changed screens](${links.changed}): the modified, added and removed screens with the review description, visual verdict and mismatch percentage; \`status=\` filters, \`limit=\`/\`cursor=\` page`,
`- [Changed screens](${links.changed}): the modified, accessibility-only (screenshots match, the accessibility tree does not), added and removed screens with the review description, visual verdict and mismatch percentage; \`status=\` filters, \`limit=\`/\`cursor=\` page`,
`- [All screens](${links.screens}): every captured screen; \`${links.screens}/{id}\` (the \`id\` field of a screen) adds source files and navigation in and out`,
`- [Transitions](${links.transitions}): navigation edges between screens (\`?from=\`/\`?to=\` take a screen id or route)`,
`- Screenshots: each screen's \`headImage\`/\`baseImage\` URL returns the PNG`,
@@ -335,7 +387,7 @@ export async function agentApiReply(context: AgentContext, loaded: LoadedReport,
const surfaces = arr(loaded.json.surfaces).map(rec);
if (id !== undefined) { const surface = surfaces.find(s => s.id === id); return surface ? json(reviewSurfaceDetail(context, loaded.json, surface)) : notFound(); }
const statuses = params.get("status")?.split(",").filter(Boolean);
const items = surfaces.filter(s => !statuses || statuses.includes(str(s.status) ?? "")).map(s => reviewSurfaceItem(context, s));
const items = surfaces.filter(s => !statuses || statuses.includes(verdictOf(s) ?? "")).map(s => reviewSurfaceItem(context, s));
const paged = page(items, params);
if (!paged) return json({ error: "bad_request", message: `limit must be 1-${MAX_LIMIT} and cursor a non-negative integer` }, 400);
return wantsMarkdown ? markdown(screensMarkdown(loaded, paged.items, paged.total)) : json(paged);
+29 -4
View File
@@ -1,11 +1,11 @@
import { spawnSync } from "node:child_process";
import { copyFile, mkdir, lstat, readFile, realpath, writeFile } from "node:fs/promises";
import { appendFile, copyFile, mkdir, lstat, readFile, realpath, writeFile } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { assertPublicReview, projectPublicReviewForReport } from "../contracts/review-validation.js";
import { createHash } from "node:crypto";
import type { ArtifactReport } from "../contracts/artifact-report.js";
import { projectReviewPresentation } from "../contracts/review.js";
import { renderPublicComment, platformSectionMerge, type PublicCommentState } from "./pr-comment-body.js";
import { compareTitleMarkdown, projectReviewPresentation, type CompareReviewPresentation } from "../contracts/review.js";
import { renderPublicComment, platformSectionMerge, reviewChangeCount, type PublicCommentState } from "./pr-comment-body.js";
import type { ExplorePlatform } from "../config/explore-config.js";
import { upsertStickyComment } from "./pr-comment.js";
import { previewLinks, viewerLinks } from "./viewer-links.js";
@@ -123,10 +123,11 @@ export async function publishCiReportComment(options: {
previewFailed?: boolean;
}) {
const environment = options.environment ?? process.env; const transport = options.transport ?? fetch;
const input = await readInput(options.inputPath); const review = input.publicReview; const pr = review.pullRequest;
if (pr.origin === "compare") return publishCompareSummary(input, options, environment);
if (!environment.GITHUB_TOKEN?.trim()) throw new CiError({ code: "GITHUB_TOKEN_MISSING", stage: "preflight",
message: "GITHUB_TOKEN is required to publish the PR report comment",
nextAction: "Pass GITHUB_TOKEN to the publish job with Actions read and PR comment write permissions." });
const input = await readInput(options.inputPath); const review = input.publicReview; const pr = review.pullRequest;
if (review.runId !== environment.GITHUB_RUN_ID || review.runAttempt !== environment.GITHUB_RUN_ATTEMPT
|| (environment.GITHUB_REPOSITORY && environment.GITHUB_REPOSITORY !== pr.repository)) {
throw new CiError({ code: "REPORT_RUN_MISMATCH", stage: "publication",
@@ -196,3 +197,27 @@ export async function publishCiReportComment(options: {
return { artifactUrl: links.viewer!.open, headSha: pr.head.sha, ...(links.preview ? { previewUrl: links.preview.open } : {}),
...(previousBody !== undefined ? { previousBody } : {}) };
}
/**
* A comparison has no pull request to comment on: `ci:publish` links its report from the run summary instead,
* with the same Open (central Viewer) and zip links a PR comment carries for this platform.
*/
async function publishCompareSummary(input: CiReportInput, options: { artifactUrl: string; platform?: ExplorePlatform }, environment: NodeJS.ProcessEnv) {
const review = input.publicReview; const comparison = review.pullRequest as CompareReviewPresentation;
if (review.runId !== environment.GITHUB_RUN_ID || review.runAttempt !== environment.GITHUB_RUN_ATTEMPT
|| (environment.GITHUB_REPOSITORY && environment.GITHUB_REPOSITORY !== comparison.repository)) {
throw new CiError({ code: "REPORT_RUN_MISMATCH", stage: "publication",
message: "Report input is not from the current repository run and attempt",
nextAction: "Publish the report-input.json produced by this repository's current workflow run and attempt." });
}
const links = viewerLinks({ repository: comparison.repository, headSha: comparison.head.sha, runId: review.runId,
runAttempt: review.runAttempt, configPath: input.commentState.configPath, artifactUrl: options.artifactUrl,
...(options.platform ? { platform: options.platform } : {}) });
const changes = input.commentState.review ?? review;
const count = reviewChangeCount({ review: changes }) ?? 0;
const platform = (options.platform ?? review.runtime.platform) === "android" ? "Android" : "iOS";
if (environment.GITHUB_STEP_SUMMARY) {
await appendFile(environment.GITHUB_STEP_SUMMARY, `- ${platform} report of ${compareTitleMarkdown(comparison)}: [Open](${links.viewer!.open}) · [zip](${links.download!}) · ${count} ${count === 1 ? "change" : "changes"}\n`);
}
return { artifactUrl: links.viewer!.open, headSha: comparison.head.sha };
}
+79
View File
@@ -0,0 +1,79 @@
import { randomBytes } from "node:crypto";
import { readFile, stat } from "node:fs/promises";
import { createServer, type Server } from "node:http";
import { extname, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
import type { ExplorePlatform } from "../config/explore-config.js";
import { AGENT_API_VERSION, agentApiReply, agentIndexMarkdown, loadReport, prefersHtml, type AgentContext, type LoadedReport } from "./agent-api.js";
/**
* Serve review reports on this machine the way a hosted report serves them: the built Viewer at `/p/<token>`, each
* platform's report at `/p/<token>/report.zip?platform=…`, and the platform list at `/p/<token>/reports.json`. The
* Viewer already knows this layout, so nothing in it changes. An agent on this machine gets what it gets from a hosted
* link: the Markdown index when it fetches `/p/<token>` without asking for HTML, `/p/<token>/llms.txt`, and the JSON
* API at `/p/<token>/api/v1/...` (agent-api.ts, shared with the hosted Worker). Loopback only; anything else answers 404.
*/
export type LocalReport = { platform: ExplorePlatform; zip: Uint8Array; changes?: number; device?: string };
export type LocalReportServer = { server: Server; url: string; close: () => Promise<void> };
const TYPES: Record<string, string> = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8",
".svg": "image/svg+xml", ".png": "image/png", ".woff2": "font/woff2", ".woff": "font/woff", ".json": "application/json; charset=utf-8", ".cur": "image/x-icon" };
const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
const AGENT_ROUTE = /^(?:\/llms\.txt|\/api\/v1(?:\/[A-Za-z0-9._:@-]{1,200}){0,2}\/?)$/;
export async function startLocalReportServer(options: { reports: LocalReport[]; port?: number; viewerRoot?: string; token?: string }): Promise<LocalReportServer> {
if (!options.reports.length) throw new Error("There is no report to serve");
const viewerRoot = resolve(options.viewerRoot ?? fileURLToPath(new URL("../viewer/", import.meta.url)));
await stat(resolve(viewerRoot, "index.html"));
const token = options.token ?? [...randomBytes(32)].map(byte => BASE32[byte % 32]).join("");
const page = `/p/${token}`;
const listing = JSON.stringify(options.reports.map(report => ({ platform: report.platform,
...(report.changes === undefined ? {} : { changes: report.changes }), ...(report.device ? { device: report.device } : {}) })));
const loaded = new Map<LocalReport, Promise<LoadedReport | undefined>>();
let pageUrl = "";
const server = createServer((request, response) => {
void (async () => {
const url = new URL(request.url ?? "/", "http://localhost");
const send = (status: number, body: Uint8Array | string, type = "text/plain; charset=utf-8", headers: Record<string, string> = {}) => {
response.writeHead(status, { "content-type": type, "cache-control": "no-store", "x-content-type-options": "nosniff", ...headers });
response.end(body);
};
if (request.method !== "GET" && request.method !== "HEAD") return send(405, "Method not allowed");
// `?platform=` picks one of several reports, the first otherwise; an unknown platform matches nothing.
const platforms = url.searchParams.getAll("platform");
const report = platforms.length > 1 ? undefined : platforms.length ? options.reports.find(candidate => candidate.platform === platforms[0]) : options.reports[0];
const accept = request.headers.accept ?? null;
const isPage = url.pathname === page || url.pathname === `${page}/`;
const agentPath = url.pathname.startsWith(`${page}/`) ? url.pathname.slice(page.length) : "";
if ((isPage && !prefersHtml(accept)) || AGENT_ROUTE.test(agentPath)) {
if (!report) return send(404, "Not found");
if (!loaded.has(report)) loaded.set(report, loadReport(report.zip));
const content = await loaded.get(report);
if (!content) return send(404, "Not found");
const context: AgentContext = { pageUrl, platform: report.platform, platforms: options.reports.map(entry => entry.platform), expiresAt: null };
const link = { link: `<${pageUrl}/api/${AGENT_API_VERSION}>; rel="alternate"; type="application/json", <${pageUrl}/llms.txt>; rel="alternate"; type="text/markdown"`, vary: "Accept" };
if (isPage || agentPath === "/llms.txt") return send(200, agentIndexMarkdown(context, content), "text/markdown; charset=utf-8", link);
const reply = await agentApiReply(context, content, agentPath.slice("/api/v1".length).replace(/\/$/, ""), url.searchParams, accept);
const body = typeof reply.body === "string" ? reply.body : new Uint8Array(await new Response(reply.body).arrayBuffer());
return send(reply.status, body, reply.contentType, { vary: "Accept", ...reply.headers });
}
if (isPage) return send(200, await readFile(resolve(viewerRoot, "index.html")), TYPES[".html"]);
if (url.pathname === `${page}/report.zip`) return report ? send(200, report.zip, "application/zip") : send(404, "Not found");
if (url.pathname === `${page}/reports.json` && options.reports.length > 1) return send(200, listing, TYPES[".json"]);
// The Viewer's own assets, at the absolute paths its index.html names; never anything outside the build.
if (/^\/(assets|fonts|cursors)\/[A-Za-z0-9._/-]+$/.test(url.pathname) || url.pathname === "/favicon.svg") {
const file = resolve(viewerRoot, `.${url.pathname}`);
if (!file.startsWith(viewerRoot + sep)) return send(404, "Not found");
try { return send(200, await readFile(file), TYPES[extname(file)] ?? "application/octet-stream"); }
catch { return send(404, "Not found"); }
}
send(404, "Not found");
})().catch(() => { if (!response.headersSent) response.writeHead(500); response.end(); });
});
await new Promise<void>((done, fail) => { server.once("error", fail); server.listen(options.port ?? 0, "127.0.0.1", done); });
const address = server.address();
if (!address || typeof address === "string") throw new Error("The local report server has no port");
pageUrl = `http://127.0.0.1:${address.port}${page}`;
return { server, url: pageUrl,
close: () => new Promise<void>(done => server.close(() => done())) };
}
+64 -24
View File
@@ -1,8 +1,8 @@
import type { PublicReview } from "../contracts/capture.js";
import type { SimulatorRuntimeMetadata } from "../capture/run.js";
import { CI_COMMENT_MARKER } from "./pr-comment.js";
import { CHANGE_GROUPS, foldRecord, historyLine, readCommentRecords, recordLine, recordSummary, type ChangeGroup, type CommentPlatform, type CommentRecords, type HistoryEntry, type PlatformRecord } from "./pr-comment-record.js";
import { sourceImpactSentences } from "../contracts/source-change.js";
import { CHANGE_GROUPS, changeCountText, foldRecord, strongerGroup, historyLine, readCommentRecords, recordLine, recordSummary, type ChangeGroup, type CommentPlatform, type CommentRecords, type HistoryEntry, type PlatformRecord } from "./pr-comment-record.js";
import { isAccessibilityOnlyChange } from "../contracts/review-validation.js";
import type { PublicCaptureHealth, PublicEvidenceSummary } from "../review/evidence-assessment.js";
import type { ReviewPresentation } from "../contracts/review.js";
import type { ViewerLinks } from "./viewer-links.js";
@@ -60,8 +60,8 @@ const GROUP_LABEL: Record<ReviewGroup, string> = {
added: "🟩 Added",
modified: "🟧 Modified",
removed: "🟥 Removed",
"accessibility-only": "🟦 Accessibility only",
"needs-review": "🟨 Needs review",
"source-affected": "🟨 Source-affected",
};
/** The body is HTML, so no blank lines are needed and the block keeps its natural spacing. */
@@ -121,16 +121,32 @@ function plural(count: number, noun: string): string {
type Surface = PublicReview["surfaces"][number];
/** Evidence-based group when the run produced verdicts; otherwise the source-based status. */
function groupOf(surface: Surface, evidenceBased: boolean): ReviewGroup | "unchanged" | "variant" {
/**
* The group a surface is listed under, from the run's verdicts. A screen without one (its source changed but no
* screenshots were compared) is not listed: Explore reports what the captures show. A capture that failed is counted as
* unavailable in the result and named under Validation instead.
*/
function groupOf(surface: Surface, evidenceBased: boolean): ReviewGroup | "unlisted" {
if (surface.status === "added" || surface.status === "removed") return surface.status;
const verified = (["base", "head"] as const).every(side => surface[`${side}Image`]
&& surface[`${side}Outcome`]?.status === "captured" && surface[`${side}Outcome`]?.landing === "verified");
if (evidenceBased && verified && surface.review && surface.visual?.reason !== "diff-failed") return surface.review.status;
switch (surface.status) {
case "modified": return "source-affected";
case "unchanged": return "unchanged";
if (evidenceBased && verified && surface.review && surface.visual?.reason !== "diff-failed") {
const status = surface.review.status;
if (status === "unchanged" || status === "variant") return "unlisted";
return isAccessibilityOnlyChange(surface) ? "accessibility-only" : status;
}
return "unlisted";
}
/**
* A screen whose source changed and whose captures were both verified, but that has no verdict: the comparison did
* not run or failed. Not a change, but not a screen that looks the same either, so the result says how many.
*/
function notComparedChange(surface: Surface): boolean {
if (surface.status !== "modified" || (surface.head ?? surface.base)?.kind === "redirect") return false;
const verified = (["base", "head"] as const).every(side => surface[`${side}Image`]
&& surface[`${side}Outcome`]?.status === "captured" && surface[`${side}Outcome`]?.landing === "verified");
return verified && (!surface.review || surface.visual?.reason === "diff-failed");
}
function routeOf(surface: Surface): string {
@@ -143,9 +159,6 @@ function descriptionOf(surface: Surface, group: ReviewGroup): string {
if (group === "added") return `Added ${route} screen`;
if (group === "removed") return `Removed ${route} screen`;
// A group's own label already says added or removed; the route makes the line readable alone.
if (group === "source-affected") {
return sourceImpactSentences(surface.sourceImpact) ?? "Source-affected; not compared";
}
if (surface.review) return plainText(surface.review.description, MAX_DESCRIPTION_LENGTH);
return "No visible change";
}
@@ -270,10 +283,12 @@ export function platformRecordOf(state: PublicCommentState, platform?: CommentPl
for (const surface of state.review.surfaces) {
if ((surface.head ?? surface.base)?.kind === "redirect") continue;
const group = groupOf(surface, evidenceBased);
if (group === "unchanged" || group === "variant") continue;
if (group === "unlisted") continue;
const scheme = schemeOf(surface.id);
record.changes.push({ id: surface.id, route: routeOf(surface), group, description: descriptionOf(surface, group), ...(scheme ? { scheme } : {}) });
}
const notCompared = state.review.surfaces.filter(notComparedChange).length;
if (notCompared) record.notCompared = notCompared;
record.context = contextLines(state.review).filter(line => line.length);
const diagnostics = [...(state.evidence?.diagnostics ?? [])];
for (const surface of state.review.surfaces) {
@@ -318,12 +333,12 @@ function resultCell(record: PlatformRecord): string {
}
case "failed": return `🟥 failed · ${inlineText(record.failure?.step ?? "capture", 48)}`;
case "ready": {
const changes = record.changes?.length ?? 0;
const unavailable = record.health ? record.health.base.unavailable + record.health.head.unavailable : 0;
const unverified = record.health ? record.health.base.unverified + record.health.head.unverified : 0;
const failed = (record.validation?.visual?.failed ?? 0) + (record.validation?.accessibility?.failed ?? 0);
const icon = unavailable || unverified || failed ? "🟨" : "🟩";
return [`${icon} ${plural(changes, "change")}`, unavailable ? `${unavailable} unavailable` : undefined, unverified ? `${unverified} unattributed` : undefined,
const notCompared = record.notCompared ?? 0;
const icon = unavailable || unverified || failed || notCompared ? "🟨" : "🟩";
return [`${icon} ${changeCountText(record.changes?.map(change => change.group) ?? [])}`, notCompared ? `${notCompared} not compared` : undefined, unavailable ? `${unavailable} unavailable` : undefined, unverified ? `${unverified} unattributed` : undefined,
failed ? `${failed} comparison${failed === 1 ? "" : "s"} failed` : undefined, duration(record.startedAt, record.updatedAt)].filter(Boolean).join(" · ");
}
}
@@ -363,6 +378,8 @@ function changeRows(records: PlatformRecord[]): Map<ReviewGroup, ChangeRow[]> {
for (const change of record.changes ?? []) {
const href = record.links.report ? surfaceLink(record.links.report, change.id) : undefined;
const row = rows.get(change.id) ?? { id: change.id, route: change.route, group: change.group, description: change.description, perPlatform: {}, ...(change.scheme ? { scheme: change.scheme } : {}) };
// A screen accessibility-only on one platform and visibly changed on another is listed as the visible change.
if (strongerGroup(row.group, change.group) !== row.group) Object.assign(row, { group: change.group, description: change.description });
row.perPlatform[record.platform] = { group: change.group, ...(href ? { href } : {}) };
rows.set(change.id, row);
}
@@ -390,12 +407,14 @@ function changesSection(records: PlatformRecord[], platforms: CommentPlatform[],
const lines: string[] = [];
const total = [...groups.values()].reduce((sum, rows) => sum + rows.length, 0);
lines.push(`**Changes** · ${plural(total, "screen")}${platforms.length > 1 && ready.length > 1 ? " · a screen is listed once, with a link per platform" : ""}`, "");
if (total === 0) lines.push("No screen changed on the reviewed platforms.", "");
// With screens left uncompared, nothing changed only among the ones compared.
if (total === 0) lines.push(ready.some(record => record.notCompared) ? "No compared screen changed on the reviewed platforms." : "No screen changed on the reviewed platforms.", "");
for (const group of GROUP_ORDER) {
const rows = groups.get(group) ?? [];
if (!rows.length) continue;
const shown = rows.slice(0, rowCap);
const content = ["", ...shown.map(row => renderChangeRow(row, platforms))];
const content = ["", ...(group === "accessibility-only" ? ["Before and After look the same. What screen readers and voice control read changed.", ""] : []),
...shown.map(row => renderChangeRow(row, platforms))];
if (rows.length > shown.length) {
const report = ready.find(record => record.links.report)?.links.report;
content.push(`- ${rows.length - shown.length} more${report ? ` — ${link("Explore report", report)}` : ""}`);
@@ -593,20 +612,41 @@ export function platformSectionMerge(state: PublicCommentState, platform: Commen
}
/** "iPhone 17 Pro 26.0 · light + dark": the device model and OS version the report's head capture ran on, and its appearances when it captured several. */
export function reviewDevice(state: PublicCommentState): string {
export function reviewDevice(state: { runtime?: Pick<SimulatorRuntimeMetadata, "deviceModel" | "osVersion" | "colorSchemes"> | undefined }): string {
const device = [state.runtime?.deviceModel, state.runtime?.osVersion && state.runtime.osVersion !== "unknown" ? state.runtime.osVersion : undefined].filter(Boolean).join(" ");
const schemes = state.runtime?.colorSchemes;
return schemes && schemes.length > 1 ? [device, schemes.join(" + ")].filter(Boolean).join(" · ") : device;
}
/** Surfaces the review calls changed (reviewer verdicts first, raw status otherwise); undefined before the review exists. */
export function reviewChangeCount(state: PublicCommentState): number | undefined {
return state.review?.surfaces.filter(surface => surface.review ? surface.review.status !== "unchanged" && surface.review.status !== "variant"
: surface.status !== "unchanged").length;
/** Each changed surface's group, as the comment lists it: what a summary of the review counts. */
export function reviewChanges(review: PublicReview): Map<string, ChangeGroup> {
const evidenceBased = review.surfaces.some(surface => surface.review);
const changes = new Map<string, ChangeGroup>();
for (const surface of review.surfaces) {
if ((surface.head ?? surface.base)?.kind === "redirect") continue;
const group = groupOf(surface, evidenceBased);
if (group !== "unlisted") changes.set(surface.id, group);
}
return changes;
}
/** How many screens the comment lists as changed; undefined before the review exists. */
export function reviewChangeCount(state: Pick<PublicCommentState, "review">): number | undefined {
return state.review ? reviewChanges(state.review).size : undefined;
}
export { recordSummary, readCommentRecords };
/** A surface's status in the local text summary, named as the comment groups it. */
function localStatus(surface: Surface): string {
if (isAccessibilityOnlyChange(surface)) return "accessibility only";
if (surface.review) return surface.review.status;
if (surface.status === "added" || surface.status === "removed") return surface.status;
const failed = (["base", "head"] as const).some(side => surface[side]?.kind === "screen" && !surface[`${side}Image`]
&& surface[`${side}Outcome`] && surface[`${side}Outcome`]?.status !== "captured");
return failed ? "unavailable" : "not compared";
}
function renderLocalText(state: PublicCommentState): string {
const pr = state.pullRequest as Extract<ReviewPresentation, { origin: "local" }>;
const counts = state.capture;
@@ -618,6 +658,6 @@ function renderLocalText(state: PublicCommentState): string {
...(counts && counts.planned.base + counts.planned.head === 0 ? ["No captures selected; visual comparison was not required.", ""] : []),
...(state.review?.surfaces.filter(s => (s.status === "added" || s.status === "removed"
|| s.baseOutcome || s.headOutcome || s.review) && s.review?.status !== "unchanged" && s.review?.status !== "variant").map(s =>
`- ${inlineText((s.head ?? s.base)?.route ?? s.id, 160)}: ${s.review?.status ?? (s.status === "added" || s.status === "removed" ? s.status : "not compared")}${s.note ? ` — ${inlineText(s.note.text, 500)}` : ""}`) ?? []),
`- ${inlineText((s.head ?? s.base)?.route ?? s.id, 160)}: ${localStatus(s)}${s.note ? ` — ${inlineText(s.note.text, 500)}` : ""}`) ?? []),
"", ...(state.review ? contextLines(state.review) : []), "Report: artifacts/report.zip", "Details: README.md, agent-mode-cost.md, issues.md", ""].join("\n");
}
+31 -5
View File
@@ -13,8 +13,32 @@ import { deflateRawSync, inflateRawSync } from "node:zlib";
*/
export type CommentPlatform = "ios" | "android";
export type RecordPhase = "pending" | "capturing" | "ready" | "failed";
export type ChangeGroup = "added" | "modified" | "removed" | "needs-review" | "source-affected";
export const CHANGE_GROUPS: ChangeGroup[] = ["added", "removed", "modified", "needs-review", "source-affected"];
/**
* `accessibility-only`: modified, but the screenshots match; only what assistive technology reads changed. A screen
* whose source changed but that was not compared is no group: Explore reports what the captures show, not what the code
* might do.
*/
export type ChangeGroup = "added" | "modified" | "removed" | "accessibility-only" | "needs-review";
export const CHANGE_GROUPS: ChangeGroup[] = ["added", "removed", "modified", "accessibility-only", "needs-review"];
/**
* "12 changes", or "3 visual changes · 12 accessibility only" when some changed only for assistive technology: those
* are changes too (screen readers and voice control see them), but not ones a screenshot shows.
*/
/**
* The group of a screen that changed on several platforms. Accessibility only says the screenshots match, so it
* yields to any other group; otherwise the first platform's group stands, as it always has.
*/
export function strongerGroup(first: ChangeGroup, other: ChangeGroup): ChangeGroup {
return first === "accessibility-only" ? other : first;
}
export function changeCountText(groups: readonly ChangeGroup[]): string {
const accessibility = groups.filter(group => group === "accessibility-only").length;
const visual = groups.length - accessibility;
if (!accessibility) return `${visual} change${visual === 1 ? "" : "s"}`;
return [visual ? `${visual} visual change${visual === 1 ? "" : "s"}` : undefined, `${accessibility} accessibility only`].filter(Boolean).join(" · ");
}
export type SideHealth = { planned: number; captured: number; verified: number; unverified: number; unavailable: number };
@@ -41,6 +65,8 @@ export type PlatformRecord = {
};
/** The review's changed surfaces, one per surface; `scheme` for a secondary appearance (`<route>@<scheme>`). */
changes?: { id: string; route: string; group: ChangeGroup; description: string; scheme?: string }[];
/** Screens whose source changed and whose captures were verified, but that got no verdict: the comparison did not run or failed. */
notCompared?: number;
/** Differences stated once rather than per screen (variants, app-wide source changes). */
context?: string[];
diagnostics?: { side?: "base" | "head"; route: string; code: string; message: string; nextAction: string }[];
@@ -166,6 +192,7 @@ export function parsePlatformRecord(value: unknown): PlatformRecord | undefined
&& isString(entry.message) && isString(entry.nextAction)
? [{ ...(isSide(entry.side) ? { side: entry.side } : {}), route: entry.route, code: entry.code, message: entry.message, nextAction: entry.nextAction }] : []).slice(0, 20);
}
if (isCount(value.notCompared) && value.notCompared > 0) record.notCompared = value.notCompared;
if (isCount(value.diagnosticCount)) record.diagnosticCount = value.diagnosticCount;
if (isRecord(value.failure) && isString(value.failure.step, 200) && isString(value.failure.message)) record.failure = { step: value.failure.step, message: value.failure.message };
if (value.superseded === true) record.superseded = true;
@@ -207,13 +234,12 @@ export function readCommentRecords(body: string | undefined): CommentRecords {
/** A short result for a run that is no longer current: "🟩 34 changes", "🟨 12 changes · 4 unavailable", "🟥 failed · capture". */
export function recordSummary(record: PlatformRecord): string {
const changes = record.changes?.length;
switch (record.phase) {
case "failed": return `🟥 failed · ${record.failure?.step ?? "capture"}`;
case "ready": {
const unavailable = record.health ? record.health.base.unavailable + record.health.head.unavailable : 0;
const icon = unavailable > 0 || (record.validation?.visual?.failed ?? 0) > 0 ? "🟨" : "🟩";
return `${icon} ${changes ?? 0} change${changes === 1 ? "" : "s"}${unavailable > 0 ? ` · ${unavailable} unavailable` : ""}`;
const icon = unavailable > 0 || (record.validation?.visual?.failed ?? 0) > 0 || record.notCompared ? "🟨" : "🟩";
return `${icon} ${changeCountText(record.changes?.map(change => change.group) ?? [])}${unavailable > 0 ? ` · ${unavailable} unavailable` : ""}${record.notCompared ? ` · ${record.notCompared} not compared` : ""}`;
}
default: return "⏳ did not finish";
}
+154 -16
View File
@@ -1,12 +1,18 @@
import { createCipheriv, createHash, randomBytes } from "node:crypto";
import { spawnSync } from "node:child_process";
import { cp, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { appendFile, cp, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, relative, resolve, sep } from "node:path";
import { Uint8ArrayReader, Uint8ArrayWriter, ZipWriter, configure } from "@zip.js/zip.js";
import { MAX_METADATA_BYTES } from "./agent-api.js";
import { publishCiReportComment, readCiReportInput, type CiReportInput } from "./artifact.js";
import { readZipDirectory, readZipEntry } from "./zip-reader.js";
import { reviewChangeCount, reviewDevice } from "./pr-comment-body.js";
import type { ExplorePlatform } from "../config/explore-config.js";
import type { ArtifactReport } from "../contracts/artifact-report.js";
import { normalizePublicReviewForReading } from "../contracts/review-validation.js";
import { EXPLORATION_REPORT_KIND, type ExplorationReport } from "../contracts/standalone-report.js";
import { compareTitleMarkdown, type CompareReviewPresentation } from "../contracts/review.js";
import { CiError, toCiError } from "../shared/ci-errors.js";
import { TOOL_ROOT, packageBin } from "../shared/package-paths.js";
@@ -63,12 +69,15 @@ export type PreviewDeployResult = {
reportBytes: number;
reports: Array<{ platform?: ExplorePlatform; artifactUrl: string; reportSha256: string; reportBytes: number }>;
headSha: string;
/** A comparison's link is in the run summary only: callers must not print previewUrl, which is unmasked for it. */
linkedFromRunSummary?: true;
};
export const PREVIEW_EXPORT_PATH = join(TOOL_ROOT, "dist", "hosting-preview");
const CIPHER_AAD = "expo-explore-preview/1";
const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
const MAX_REPORT_BYTES = 256 * 1024 * 1024;
/** The largest report ZIP a hosted preview serves. */
export const MAX_REPORT_BYTES = 256 * 1024 * 1024;
const ZIP_DATE = new Date("2000-01-01T00:00:00Z");
function base32(bytes: Uint8Array): string {
@@ -154,6 +163,54 @@ export async function zipReportDirectory(reportPath: string): Promise<Uint8Array
return writer.close();
}
/** What a report ZIP holds, from its review.json or exploration.json: where to host it and how the platform switch labels it. */
export type ReportZipSummary = { platform: ExplorePlatform; changes?: number; device?: string }
& ({ kind: "review"; repository: string; runId: string; base: string; head: string } | { kind: "exploration" });
/**
* Reads a report ZIP as `zipReportDirectory` writes it (or GitHub's download of a report artifact): one report file and
* its assets, nothing else. It uses the hosted reader (zip-reader.ts) with its limits, so a ZIP accepted here is one a
* hosted or local Viewer link can serve, and a crafted one cannot inflate past them.
*/
export async function readReportZip(zip: Uint8Array): Promise<ReportZipSummary> {
if (zip.byteLength > MAX_REPORT_BYTES) throw new Error("Report exceeds the 256 MiB hosted preview limit");
const entries = readZipDirectory(zip);
if (!entries) throw new Error("Not a ZIP archive a hosted report can read");
const names = [...entries.keys()].filter(name => !name.endsWith("/"));
const reportFile = REPORT_FILE_NAMES.find(name => names.includes(name));
if (!reportFile || names.some(name => name !== reportFile && !/^assets\/[a-f0-9]{64}\.(png|mp4)$/.test(name))) {
throw new Error("A report ZIP must contain review.json (or exploration.json) and assets/<sha256>.png or .mp4 only");
}
const bytes = await readZipEntry(zip, entries.get(reportFile)!, MAX_METADATA_BYTES);
if (!bytes) throw new Error(`${reportFile} is unreadable or larger than ${MAX_METADATA_BYTES / 1024 / 1024} MiB`);
const report = JSON.parse(new TextDecoder().decode(bytes));
if (reportFile === "exploration.json") {
const exploration = (report as Partial<ExplorationReport>).exploration;
if (report?.kind !== EXPLORATION_REPORT_KIND || !exploration || (exploration.app?.platform !== "ios" && exploration.app?.platform !== "android")) {
throw new Error("exploration.json is not an Explore exploration report");
}
return { kind: "exploration", platform: exploration.app.platform, device: `${exploration.device.model} ${exploration.device.osVersion}`.trim() };
}
const review = (report as Partial<ArtifactReport>).review;
const pr = review?.pullRequest;
// Reports from before Android support carry no platform; they are all iOS.
const platform = review?.runtime?.platform ?? "ios";
if (report?.kind !== "explore.report" || !review || !pr || (platform !== "ios" && platform !== "android")) {
throw new Error("review.json is not an Explore review report");
}
// What the CLI later hands to git and shows in a terminal: full SHAs and plain text, or the ZIP is not a report.
const sha = (value: unknown) => typeof value === "string" && /^[0-9a-f]{40}$/i.test(value);
const text = (value: unknown) => typeof value === "string" && value.length > 0 && value.length <= 1000;
if (!sha(pr.head?.sha) || !sha(pr.base?.sha) || !text(pr.head?.ref) || !text(pr.base?.ref) || !text(pr.repository) || !text(pr.title) || !text(review.runId)) {
throw new Error("review.json does not name its repository, title and commits as a report does");
}
const changes = reviewChangeCount({ review: normalizePublicReviewForReading(review) });
const device = reviewDevice({ runtime: { deviceModel: review.runtime?.device?.model ?? "", osVersion: review.runtime?.device?.osVersion ?? "",
...(review.runtime?.colorSchemes ? { colorSchemes: review.runtime.colorSchemes } : {}) } });
return { kind: "review", platform, repository: pr.repository, runId: review.runId, base: pr.base.sha, head: pr.head.sha,
...(changes === undefined ? {} : { changes }), ...(device ? { device } : {}) };
}
/** iv (12 bytes) || AES-256-GCM ciphertext || tag, authenticated with the preview AAD; what the Worker decrypts. */
export function sealReport(plain: Uint8Array, key: Uint8Array, iv: Uint8Array): Uint8Array {
const cipher = createCipheriv("aes-256-gcm", key, iv);
@@ -179,11 +236,21 @@ type SealedReport = { entry: PreviewReportInput; input: CiReportInput; zip: Uint
function previewError(code: string, message: string, nextAction: string): CiError { return new CiError({ code, stage: "preflight", message, nextAction }); }
/** A device label for the platform switch, safe in the sealed .env: no `#` (a dotenv comment), markup or control characters, and short. */
/**
* A device label for the platform switch, safe in the sealed .env: letters, digits and a few separators only. `eas
* deploy` reads that file with variable expansion, so a `$` (even single-quoted) would pull the deploying process's
* environment into the label, and a `#` or a backslash would cut or corrupt the JSON around it.
*/
function listingDevice(device: string): string {
return device.replace(/[^\p{L}\p{N} .,()+·_:/-]/gu, "").replace(/\s+/g, " ").trim().slice(0, 120);
}
/** The worker's EXPLORE_PREVIEW_REPORTS entries, in the order the workflow lists platforms; also what reports.json must echo. */
export function previewReportListing(reports: ReadonlyArray<Pick<SealedReport, "entry" | "input" | "file">>, reportDirectory: string) {
return reports.map(report => {
const changes = reviewChangeCount(report.input.commentState);
const device = reviewDevice(report.input.commentState).replace(/[#<>\u0000-\u001f\u007f]/g, "").trim().slice(0, 120);
const device = listingDevice(reviewDevice(report.input.commentState));
return { platform: report.entry.platform!, path: `/_report/${reportDirectory}/${report.file}`,
...(changes === undefined ? {} : { changes }), ...(device ? { device } : {}) };
});
@@ -212,8 +279,8 @@ export async function deployPreview(options: PreviewDeployOptions): Promise<Prev
if (pr.origin === "local") throw new Error("Local reports cannot be deployed as hosted previews");
for (const { input } of inputs.slice(1)) {
const other = input.publicReview;
if (!input.preview || other.pullRequest.origin === "local" || other.pullRequest.repository !== pr.repository || other.pullRequest.number !== pr.number
|| other.pullRequest.head.sha !== pr.head.sha || other.runId !== review.runId || other.runAttempt !== review.runAttempt) {
if (!input.preview || other.pullRequest.origin !== pr.origin || other.pullRequest.repository !== pr.repository || other.pullRequest.number !== pr.number
|| other.pullRequest.head.sha !== pr.head.sha || other.pullRequest.base.sha !== pr.base.sha || other.runId !== review.runId || other.runAttempt !== review.runAttempt) {
throw previewError("PREVIEW_REPORTS_MISMATCH", "The platform reports do not come from the same review run", "Deploy only the reports this workflow run produced for the same PR head.");
}
}
@@ -240,11 +307,14 @@ export async function deployPreview(options: PreviewDeployOptions): Promise<Prev
reportDirectory, ...(listing ? { listing } : {}), project, ...(first.preview.owner ? { owner: first.preview.owner } : {}),
ownerHint: "Set report.preview.owner in .expo-explore/config.yaml to the account that should hold the preview project.",
projectHint: "Give EXPO_TOKEN's account permission to create projects, or set report.preview.project to an existing project it can deploy to.",
expiresAt, exportPath, environment, run, transport, now, random, ...(options.sleep ? { sleep: options.sleep } : {}), ...(options.onSecret ? { onSecret: options.onSecret } : {}),
expiresAt, exportPath, environment, run, transport, now, random, ...(options.sleep ? { sleep: options.sleep } : {}),
// The runner masks secrets in job summaries too, so a masked token would reach a comparison's summary as ***.
// Its link appears nowhere else (not in the log), as a PR's appears only in its comment, for the same readers.
...(options.onSecret && pr.origin !== "compare" ? { onSecret: options.onSecret } : {}),
verifyTimeoutMs: options.verifyTimeoutMs ?? 180_000 });
} catch (error) {
// The report job's comment says the report is deploying; it must now offer the download-and-drop flow instead.
for (const report of reports) {
if (pr.origin !== "compare") for (const report of reports) {
try {
await publishCiReportComment({ inputPath: report.entry.inputPath, artifactUrl: report.entry.artifactUrl, environment, transport,
...(report.entry.platform ? { platform: report.entry.platform } : {}), previewFailed: true });
@@ -253,9 +323,11 @@ export async function deployPreview(options: PreviewDeployOptions): Promise<Prev
throw error;
}
const previewUrl = hosted.previewUrl;
// A comparison has no pull request: its link goes to the run's summary, which the same repository readers see.
if (pr.origin === "compare") await writeCompareSummary(environment, pr, previewUrl, expiresAt, reports.map(report => report.input));
{
let headSha = pr.head.sha;
for (const report of reports) {
if (pr.origin !== "compare") for (const report of reports) {
const published = await publishCiReportComment({ inputPath: report.entry.inputPath, artifactUrl: report.entry.artifactUrl, environment, transport,
...(report.entry.platform ? { platform: report.entry.platform } : {}), preview: { url: previewUrl, expiresAt } });
headSha = published.headSha;
@@ -263,10 +335,30 @@ export async function deployPreview(options: PreviewDeployOptions): Promise<Prev
return { previewUrl, expiresAt: expiresAt === null ? null : new Date(expiresAt).toISOString(), deploymentId: hosted.deploymentId, deploymentUrl: hosted.deploymentUrl,
project, owner: hosted.owner, reportSha256: reports[0]!.sha256, reportBytes: reports[0]!.zip.byteLength,
reports: reports.map(report => ({ ...(report.entry.platform ? { platform: report.entry.platform } : {}), artifactUrl: report.entry.artifactUrl,
reportSha256: report.sha256, reportBytes: report.zip.byteLength })), headSha };
reportSha256: report.sha256, reportBytes: report.zip.byteLength })), headSha,
...(pr.origin === "compare" ? { linkedFromRunSummary: true as const } : {}) };
}
}
/** The comparison's job summary: what was compared, the hosted link, and each platform's change count. */
export function renderCompareSummary(comparison: CompareReviewPresentation, previewUrl: string, expiresAt: number | null, inputs: CiReportInput[]): string {
const platforms = inputs.map(input => {
const changes = reviewChangeCount(input.commentState);
const device = reviewDevice(input.commentState);
return `- ${input.publicReview.runtime.platform === "android" ? "Android" : "iOS"}${device ? ` (${device})` : ""}: ${changes === undefined ? "no review" : `${changes} ${changes === 1 ? "change" : "changes"}`}`;
});
return [`### Explore: ${compareTitleMarkdown(comparison)}`, "",
`[Open the report](${previewUrl}) · [${comparison.base.sha.slice(0, 8)}..${comparison.head.sha.slice(0, 8)}](${comparison.url})`
+ (expiresAt === null ? "" : ` · link expires ${new Date(expiresAt).toISOString().slice(0, 10)}`), "",
...platforms, ""].join("\n");
}
async function writeCompareSummary(environment: NodeJS.ProcessEnv, comparison: CompareReviewPresentation, previewUrl: string, expiresAt: number | null, inputs: CiReportInput[]) {
const path = environment.GITHUB_STEP_SUMMARY;
if (!path) return;
await appendFile(path, renderCompareSummary(comparison, previewUrl, expiresAt, inputs));
}
type HostedReportInput = { zip: Uint8Array; sha256: string; file: string; query: string };
export type HostedDeployment = { previewUrl: string; expiresAt: string | null; deploymentId: string; deploymentUrl: string; aliasUrl?: string; project: string; owner: string };
@@ -316,11 +408,13 @@ async function deploySealedReports(options: {
const who = run(process.execPath, [eas, "whoami"], { cwd: work, env: easEnvironment });
const accounts = who.status === 0 ? whoamiAccounts(who.stdout) : [];
if (!accounts.length) throw deployError("EAS_NOT_AUTHENTICATED", "The EAS CLI could not sign in with EXPO_TOKEN.",
"Use a valid EXPO_TOKEN for a robot user of the app's Expo account.", { details: { stderr: lastLine(who.stderr) } });
// On a laptop without EXPO_TOKEN the deploy uses your `eas login`, and the messages say so.
const login = environment.EXPO_TOKEN?.trim() ? "EXPO_TOKEN" : "Your EAS login";
if (!accounts.length) throw deployError("EAS_NOT_AUTHENTICATED", login === "EXPO_TOKEN" ? "The EAS CLI could not sign in with EXPO_TOKEN." : "You are not logged in to EAS.",
login === "EXPO_TOKEN" ? "Use a valid EXPO_TOKEN for a robot user of the app's Expo account." : "Run eas login (or set EXPO_TOKEN), then rerun.", { details: { stderr: lastLine(who.stderr) } });
const owner = options.owner ?? (accounts.length === 1 ? accounts[0]! : undefined);
if (!owner || !accounts.includes(owner)) throw deployError("PREVIEW_OWNER_AMBIGUOUS",
owner ? `EXPO_TOKEN has no access to the Expo account ${owner}.` : `EXPO_TOKEN can deploy to several Expo accounts: ${accounts.join(", ")}.`,
owner ? `${login} has no access to the Expo account ${owner}.` : `${login} can deploy to several Expo accounts: ${accounts.join(", ")}.`,
options.ownerHint, { details: { accounts } });
await writeFile(join(work, "package.json"), JSON.stringify({ name: project, version: "0.0.0", private: true }));
await writeFile(join(work, "app.json"), JSON.stringify({ expo: { name: `${project}`, slug: project, owner, web: { output: "server" } } }));
@@ -396,6 +490,8 @@ async function deploySealedReports(options: {
export type ExplorationDeployOptions = {
/** The `explore:binary` report directory (exploration.json plus assets/). */
reportPath: string;
/** The explored app's platform, listed so the Worker does not take the report for iOS. */
platform?: ExplorePlatform;
project: string;
owner?: string;
/** Days until the hosted link stops serving the report; null never expires. */
@@ -431,7 +527,10 @@ export async function deployExplorationReport(options: ExplorationDeployOptions)
const random = options.random ?? (bytes => new Uint8Array(randomBytes(bytes)));
const now = options.now ?? Date.now;
const sha256 = createHash("sha256").update(zip).digest("hex");
const hosted = await deploySealedReports({ reports: [{ zip, sha256, file: "report.zip.enc", query: "" }], reportDirectory: base32(random(10)), project: options.project,
const reportDirectory = base32(random(10));
const file = options.platform ? `${options.platform}.zip.enc` : "report.zip.enc";
const hosted = await deploySealedReports({ reports: [{ zip, sha256, file, query: options.platform ? `?platform=${options.platform}` : "" }], reportDirectory,
...(options.platform ? { listing: [{ platform: options.platform, path: `/_report/${reportDirectory}/${file}` }] } : {}), project: options.project,
...(options.owner ? { owner: options.owner } : {}), ownerHint: "Pass --owner with the Expo account that should host the report.",
projectHint: "Give this EAS login permission to create projects under the owner, or pass --project with an existing slug.",
expiresAt: options.expiresAfterDays === null ? null : now() + options.expiresAfterDays * 86_400_000, exportPath, environment, run: options.run ?? defaultRun, ...(options.sleep ? { sleep: options.sleep } : {}),
@@ -492,6 +591,43 @@ export async function deployFixturePreview(options: FixturePreviewOptions): Prom
...(options.token ? { token: options.token } : {}) });
}
/**
* Report ZIPs on this machine behind one token (`capture:review --upload`, `report:upload`), one per platform: the same
* sealed deployment as a PR preview, from ZIPs instead of GitHub artifacts, with the local EAS login or EXPO_TOKEN.
*/
export async function deployLocalReports(options: {
reports: Array<{ platform: ExplorePlatform; zip: Uint8Array; changes?: number; device?: string }>;
project: string; owner?: string; expiresAfterDays: number | null;
/** What to change when the owner or project is not usable; defaults name report.preview in config.yaml. */
ownerHint?: string; projectHint?: string;
exportPath?: string; environment?: NodeJS.ProcessEnv; run?: CommandRunner; sleep?: (milliseconds: number) => Promise<void>;
transport?: typeof fetch; now?: () => number; random?: (bytes: number) => Uint8Array; verifyTimeoutMs?: number;
}): Promise<HostedDeployment> {
const environment = options.environment ?? process.env;
if (!options.reports.length || new Set(options.reports.map(report => report.platform)).size !== options.reports.length) {
throw previewError("PREVIEW_REPORTS_INVALID", "A local upload needs one report per platform", "Capture each platform once, then upload.");
}
const exportPath = resolve(options.exportPath ?? PREVIEW_EXPORT_PATH);
await assertExport(exportPath);
const now = options.now ?? Date.now;
const random = options.random ?? (bytes => new Uint8Array(randomBytes(bytes)));
const reportDirectory = base32(random(10));
// Always listed, even alone: the Worker takes an unlisted report for iOS, so an Android one would be mislabelled.
const reports = options.reports.map(report => ({ ...report, sha256: createHash("sha256").update(report.zip).digest("hex"), file: `${report.platform}.zip.enc` }));
const listing = reports.map(report => {
const device = report.device ? listingDevice(report.device) : "";
return { platform: report.platform, path: `/_report/${reportDirectory}/${report.file}`, ...(report.changes === undefined ? {} : { changes: report.changes }), ...(device ? { device } : {}) };
});
return deploySealedReports({
reports: reports.map(report => ({ zip: report.zip, sha256: report.sha256, file: report.file, query: `?platform=${report.platform}` })),
reportDirectory, listing, project: options.project, ...(options.owner ? { owner: options.owner } : {}),
ownerHint: options.ownerHint ?? "Set report.preview.owner in .expo-explore/config.yaml to the account that should hold the hosted reports.",
projectHint: options.projectHint ?? "Make sure your Expo account can create projects, or set report.preview.project to an existing project you can deploy to.",
expiresAt: options.expiresAfterDays === null ? null : now() + options.expiresAfterDays * 86_400_000, exportPath, environment,
run: options.run ?? defaultRun, ...(options.sleep ? { sleep: options.sleep } : {}), transport: options.transport ?? fetch, now, random,
verifyTimeoutMs: options.verifyTimeoutMs ?? 180_000 });
}
const ARTIFACT_DIRECTORY = /^explore-(capture|review)-\d+-\d+-(ios|android)$/;
/**
@@ -591,10 +727,12 @@ async function verifyDeployment(check: { origin: string; token: string; reports:
"Rerun the deploy job; the deployment's report listing did not match.", { details: { status: list.status } });
}
const other = check.token.endsWith("a") ? `${check.token.slice(0, -1)}b` : `${check.token.slice(0, -1)}a`;
for (const path of ["/", `/p/${other}`, `/p/${other}/report.zip`, `/p/${check.token}/viewer/index.html`]) {
// Errors name each probe by its shape: the near-miss token differs from the real one in its last character only.
for (const [path, shape] of [["/", "/"], [`/p/${other}`, "/p/<wrong token>"], [`/p/${other}/report.zip`, "/p/<wrong token>/report.zip"],
[`/p/${check.token}/viewer/index.html`, "/p/<token>/viewer/index.html"]] as const) {
const response = await get(path);
if (response.status !== 404) throw deployError("PREVIEW_VERIFY_FAILED", `The hosted preview answered HTTP ${response.status} without a valid token at ${path}.`,
"Do not share this deployment; delete it in the EAS Hosting dashboard and report the issue to Explore.", { details: { path, status: response.status } });
if (response.status !== 404) throw deployError("PREVIEW_VERIFY_FAILED", `The hosted preview answered HTTP ${response.status} without a valid token at ${shape}.`,
"Do not share this deployment; delete it in the EAS Hosting dashboard and report the issue to Explore.", { details: { path: shape, status: response.status } });
}
return { liveAfterMs };
}
+220
View File
@@ -0,0 +1,220 @@
import { createHash, randomBytes } from "node:crypto";
import { lstat, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import type { ExplorePlatform } from "../config/explore-config.js";
import type { ArtifactReport } from "../contracts/artifact-report.js";
import { EXPLORATION_REPORT_KIND, type ExplorationReport } from "../contracts/standalone-report.js";
import { exploreCacheRoot } from "../shared/cache-root.js";
import { MAX_METADATA_BYTES } from "./agent-api.js";
import { normalizePublicReviewForReading } from "../contracts/review-validation.js";
import { reviewChanges, reviewDevice } from "./pr-comment-body.js";
import { strongerGroup, type ChangeGroup } from "./pr-comment-record.js";
import { readZipDirectory, readZipEntry } from "./zip-reader.js";
/**
* Every report a run produces on this machine is kept under `<cache>/reports/<id>/`: one `<platform>.zip` per platform
* (the same ZIP a hosted or local Viewer serves) and `run.json`, what `expo-explore reports` lists. Local reviews,
* explorations and uploaded reports land here, so a past run can be reopened or hosted without capturing it again.
* Runs older than 30 days, and the oldest beyond 2 GB, are pruned whenever a run is saved.
*/
export type SavedCommit = { ref: string; sha: string; subject?: string };
export type SavedRun = {
version: 1;
id: string;
kind: "local" | "pull-request" | "compare" | "exploration";
title: string;
repository?: string;
number?: number;
head?: SavedCommit;
base?: SavedCommit;
/** A local review of uncommitted changes: how many files differed from HEAD. */
uncommittedFiles?: number;
platforms: ExplorePlatform[];
device?: string;
/** Changed surfaces by group across the platforms, as the PR comment counts them. */
changes?: Partial<Record<ChangeGroup, number>>;
explored?: { app: string; version?: string; buildNumber?: string; screens: number; unexplored: number };
/** When the run happened, from its report. */
createdAt: string;
/** When it was kept here; pruning goes by this, so an old report saved today stays for the full period. */
savedAt: string;
bytes: number;
};
export type SavedReport = { platform: ExplorePlatform; zip: Uint8Array; changes?: number; device?: string };
export const SAVED_RUN_LIMITS = { maxAgeDays: 30, maxBytes: 2 * 1024 * 1024 * 1024 } as const;
const ID = /^[a-z0-9][a-z0-9._-]{0,119}$/;
export function savedRunsDirectory(environment: NodeJS.ProcessEnv = process.env): string {
return join(exploreCacheRoot(environment), "reports");
}
const slug = (value: string, max: number) => value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, max).replace(/[-.]+$/, "") || "run";
/** Text from a report or a commit, as a terminal may print it: no control characters (C0, DEL, C1), so no escape sequences. */
export function plainText(value: string): string {
return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
}
/** A run with every string a report or a commit supplied made plain, including runs saved before this was enforced. */
export function cleanRun(run: SavedRun): SavedRun {
const commit = (side?: SavedCommit) => side && { ...side, ref: plainText(side.ref), ...(side.subject === undefined ? {} : { subject: plainText(side.subject) }) };
return { ...run, title: plainText(run.title), ...(run.repository === undefined ? {} : { repository: plainText(run.repository) }),
...(run.head ? { head: commit(run.head)! } : {}), ...(run.base ? { base: commit(run.base)! } : {}), ...(run.device === undefined ? {} : { device: plainText(run.device) }),
...(run.explored ? { explored: { ...run.explored, app: plainText(run.explored.app), ...(run.explored.version ? { version: plainText(run.explored.version) } : {}),
...(run.explored.buildNumber ? { buildNumber: plainText(run.explored.buildNumber) } : {}) } } : {}) };
}
async function reportJson(zip: Uint8Array): Promise<{ file: "review.json" | "exploration.json"; json: unknown } | undefined> {
const entries = readZipDirectory(zip);
const file = entries?.has("review.json") ? "review.json" : entries?.has("exploration.json") ? "exploration.json" : undefined;
if (!entries || !file) return undefined;
const bytes = await readZipEntry(zip, entries.get(file)!, MAX_METADATA_BYTES);
if (!bytes) return undefined;
try { return { file, json: JSON.parse(new TextDecoder().decode(bytes)) }; } catch { return undefined; }
}
/**
* What a run's report ZIPs say about it: its kind, title, commits, platforms and changes. Commit subjects are not in
* the reports; the caller adds them when it has the repository (`subjects`).
*/
export async function describeReports(reports: SavedReport[], extra: { subjects?: { head?: string; base?: string }; uncommittedFiles?: number; createdAt?: string } = {}):
Promise<Omit<SavedRun, "version" | "bytes" | "savedAt">> {
const parsed = await Promise.all(reports.map(async report => ({ report, content: await reportJson(report.zip) })));
const first = parsed[0]?.content;
if (!first) throw new Error("Not an Explore report ZIP");
const createdAt = extra.createdAt ?? new Date().toISOString();
const platforms = parsed.map(entry => entry.report.platform);
if (first.file === "exploration.json") {
const report = first.json as Partial<ExplorationReport>;
if (report.kind !== EXPLORATION_REPORT_KIND || !report.exploration || !report.map) throw new Error("Not an Explore exploration report");
const { app, device } = report.exploration;
const zipHash = createHash("sha256").update(reports[0]!.zip).digest("hex").slice(0, 10);
return { id: `explore-${slug(app.name, 40)}-${zipHash}`, kind: "exploration", title: `${app.name}${app.version ? ` ${app.version}` : ""}${app.buildNumber ? ` (${app.buildNumber})` : ""} on ${device.model}`,
platforms, device: `${device.model} ${device.osVersion}`.trim(),
explored: { app: app.name, ...(app.version ? { version: app.version } : {}), ...(app.buildNumber ? { buildNumber: app.buildNumber } : {}),
screens: report.map.screens.length, unexplored: report.coverage?.frontier.pending ?? 0 },
createdAt: report.exploration.completedAt ?? createdAt };
}
const reviews = parsed.map(entry => (entry.content?.json as Partial<ArtifactReport> | undefined)?.review);
const review = reviews[0];
const pr = review?.pullRequest;
if (!review || !pr) throw new Error("Not an Explore review report");
// One surface changed on two platforms is one change, under the group the PR comment lists it in (strongerGroup).
const merged = new Map<string, ChangeGroup>();
for (const each of reviews) if (each) for (const [id, group] of reviewChanges(normalizePublicReviewForReading(each))) {
const first = merged.get(id);
merged.set(id, first ? strongerGroup(first, group) : group);
}
const changes: Partial<Record<ChangeGroup, number>> = {};
for (const group of merged.values()) changes[group] = (changes[group] ?? 0) + 1;
const devices = [...new Set(reviews.map(each => each ? reviewDevice({ runtime: { deviceModel: each.runtime?.device?.model ?? "", osVersion: each.runtime?.device?.osVersion ?? "",
...(each.runtime?.colorSchemes ? { colorSchemes: each.runtime.colorSchemes } : {}) } }) : "").filter(Boolean))];
const kind = pr.origin === "local" ? "local" : pr.origin === "compare" ? "compare" : "pull-request";
const number = "number" in pr && typeof pr.number === "number" ? pr.number : undefined;
// The run's own id and attempt are never cut short: two runs of one repository must not share a folder.
const id = kind === "local" ? slug(review.runId, 100)
: `${kind === "compare" ? "compare" : `pr-${number}`}-${slug(pr.repository.split("/").at(-1) ?? "", 40)}-${slug(review.runId, 40)}-${slug(String(review.runAttempt), 8)}`;
const commit = (side: "head" | "base"): SavedCommit => ({ ref: pr[side].ref, sha: pr[side].sha, ...(extra.subjects?.[side] ? { subject: extra.subjects[side] } : {}) });
return { id, kind, title: pr.title, repository: pr.repository, ...(number === undefined ? {} : { number }), head: commit("head"), base: commit("base"),
...(extra.uncommittedFiles ? { uncommittedFiles: extra.uncommittedFiles } : {}), platforms, ...(devices.length ? { device: devices.join(", ") } : {}),
changes, createdAt: review.createdAt ?? createdAt };
}
/**
* Keeps a run's reports, then prunes. A review's platforms saved one at a time join the run already kept for the same
* review (same repository, run, attempt and commits); anything else under that id is replaced. Written beside and
* renamed into place.
*/
export async function saveRun(reports: SavedReport[], extra: Parameters<typeof describeReports>[1] = {}, environment: NodeJS.ProcessEnv = process.env, now = Date.now()): Promise<SavedRun> {
let described = await describeReports(reports, extra);
if (!ID.test(described.id)) throw new Error(`Cannot keep a run named ${described.id}`);
const root = savedRunsDirectory(environment);
await mkdir(root, { recursive: true });
const target = join(root, described.id);
const kept = await findSavedRun(described.id, environment);
if (kept && described.kind !== "exploration" && kept.kind === described.kind && kept.repository === described.repository
&& kept.head?.sha === described.head?.sha && kept.base?.sha === described.base?.sha) {
const others = (await readSavedReports(kept, environment).catch(() => [] as SavedReport[])).filter(report => !reports.some(each => each.platform === report.platform));
if (others.length) {
const order: ExplorePlatform[] = ["ios", "android"];
reports = [...reports, ...others].sort((a, b) => order.indexOf(a.platform) - order.indexOf(b.platform));
const subjects = { ...(kept.head?.subject ? { head: kept.head.subject } : {}), ...(kept.base?.subject ? { base: kept.base.subject } : {}), ...extra.subjects };
described = await describeReports(reports, { ...extra, subjects, ...(kept.uncommittedFiles && !extra.uncommittedFiles ? { uncommittedFiles: kept.uncommittedFiles } : {}) });
}
}
const staged = join(root, `.${described.id}.${randomBytes(4).toString("hex")}.tmp`);
const run = cleanRun({ version: 1, ...described, savedAt: new Date(now).toISOString(), bytes: reports.reduce((total, report) => total + report.zip.byteLength, 0) });
try {
await mkdir(staged);
for (const report of reports) await writeFile(join(staged, `${report.platform}.zip`), report.zip);
await writeFile(join(staged, "run.json"), `${JSON.stringify(run, null, 2)}\n`);
await rm(target, { recursive: true, force: true });
await rename(staged, target);
} finally {
await rm(staged, { recursive: true, force: true });
}
await pruneSavedRuns(environment, now, SAVED_RUN_LIMITS, run.id);
return run;
}
function validRun(value: unknown, id: string): SavedRun | undefined {
const run = value as Partial<SavedRun> | undefined;
if (!run || run.version !== 1 || run.id !== id || typeof run.title !== "string" || typeof run.bytes !== "number") return undefined;
// Platforms name the ZIP files read back, so only the two there are.
if (!Array.isArray(run.platforms) || !run.platforms.length || run.platforms.some(platform => platform !== "ios" && platform !== "android")) return undefined;
if (!["local", "pull-request", "compare", "exploration"].includes(run.kind ?? "") || Number.isNaN(Date.parse(run.createdAt ?? "")) || Number.isNaN(Date.parse(run.savedAt ?? ""))) return undefined;
return run as SavedRun;
}
/** The saved runs, newest first; a folder without a readable run.json is skipped. */
export async function listSavedRuns(environment: NodeJS.ProcessEnv = process.env): Promise<SavedRun[]> {
const root = savedRunsDirectory(environment);
const names = await readdir(root).catch(() => [] as string[]);
const runs: SavedRun[] = [];
for (const name of names) {
if (!ID.test(name)) continue;
try {
const run = validRun(JSON.parse(await readFile(join(root, name, "run.json"), "utf8")), name);
if (run) runs.push(cleanRun(run));
} catch { /* a run being written, or not a run */ }
}
return runs.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
}
/** A saved run by id, or `latest`. */
export async function findSavedRun(idOrLatest: string, environment: NodeJS.ProcessEnv = process.env): Promise<SavedRun | undefined> {
const runs = await listSavedRuns(environment);
return idOrLatest === "latest" ? runs[0] : runs.find(run => run.id === idOrLatest);
}
/** A saved run's reports, in the order the run lists its platforms, labelled for a Viewer's platform switch. */
export async function readSavedReports(run: SavedRun, environment: NodeJS.ProcessEnv = process.env): Promise<SavedReport[]> {
const root = join(savedRunsDirectory(environment), run.id);
return Promise.all(run.platforms.map(async platform => ({ platform, zip: new Uint8Array(await readFile(join(root, `${platform}.zip`))) })));
}
export async function removeSavedRun(id: string, environment: NodeJS.ProcessEnv = process.env): Promise<boolean> {
if (!ID.test(id)) return false;
const target = join(savedRunsDirectory(environment), id);
if (!await lstat(target).then(() => true, () => false)) return false;
await rm(target, { recursive: true, force: true });
return true;
}
/** Drops runs kept longer than the age limit, then the longest kept until the rest fit the size limit; never `keep`. Returns what it removed. */
export async function pruneSavedRuns(environment: NodeJS.ProcessEnv = process.env, now = Date.now(), limits: { maxAgeDays: number; maxBytes: number } = SAVED_RUN_LIMITS,
keep?: string): Promise<SavedRun[]> {
const runs = (await listSavedRuns(environment)).sort((a, b) => Date.parse(a.savedAt) - Date.parse(b.savedAt));
const removed: SavedRun[] = [];
let total = runs.reduce((sum, run) => sum + run.bytes, 0);
for (const run of runs) {
if (run.id === keep) continue;
const old = now - Date.parse(run.savedAt) > limits.maxAgeDays * 86_400_000;
if (!old && total <= limits.maxBytes) continue;
await removeSavedRun(run.id, environment);
total -= run.bytes;
removed.push(run);
}
return removed;
}
@@ -59,8 +59,17 @@ export async function readZipEntry(bytes: Uint8Array, entry: ZipEntry, maxBytes:
const compressed = bytes.subarray(start, start + entry.compressedSize);
if (entry.method === 0) return compressed.byteLength === entry.size ? compressed : undefined;
try {
const stream = new Blob([compressed as BlobPart]).stream().pipeThrough(new DecompressionStream("deflate-raw"));
const inflated = new Uint8Array(await new Response(stream).arrayBuffer());
return inflated.byteLength === entry.size ? inflated : undefined;
// Inflated in chunks and abandoned once past the declared size, so a header that lies cannot exhaust memory.
const reader = new Blob([compressed as BlobPart]).stream().pipeThrough(new DecompressionStream("deflate-raw")).getReader();
const inflated = new Uint8Array(entry.size);
let length = 0;
for (;;) {
const { done, value } = await reader.read();
if (done) break;
if (length + value.byteLength > entry.size) { await reader.cancel(); return undefined; }
inflated.set(value, length);
length += value.byteLength;
}
return length === entry.size ? inflated : undefined;
} catch { return undefined; }
}
+1
View File
@@ -268,6 +268,7 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
if (pr.head.sha !== plan.headSha || pr.base.sha !== plan.baseSha) throw new Error("PR identity differs from capture plan");
const run = `${identifier(options.runId)}-${identifier(options.runAttempt)}`;
const prefix = pr.origin === "local" ? `local/${identifier(pr.runId)}/${run}`
: pr.origin === "compare" ? `reviews/${identifier(pr.repositoryId)}/compare/${pr.base.sha}-${pr.head.sha}/${run}`
: `reviews/${identifier(pr.repositoryId)}/pr-${pr.number}/${pr.head.sha}/${run}`;
await options.assertCurrentHead();
const base = await uploadSide(store, options.baseDirectory, plan.baseSha, plan.baseCaptureSurfaceIds, `${prefix}/base`);
+6 -7
View File
@@ -277,11 +277,11 @@ function localEvidencePath(side: PublicEvidenceSide, relativePath: string): stri
/**
* The verdict combines the source scope with the evidence. Only a source change makes a surface a
* review target: a changed screen is Modified when evidence differs and Needs review when nothing
* visible differs. A source-unchanged screen is never a review target: a difference there is the
* same screen captured in another runtime state (a screen variant), not a change. When only
* app-wide inputs changed, a screen without a visible difference stays Unchanged; the PR comment
* names the app-wide change once.
* review target: a changed screen is Modified when its evidence differs, Needs review when the
* comparison could not tell, and Unchanged when both captures show the same thing. Explore reports
* visual changes, so a source change nobody can see is not one. A source-unchanged screen is never a
* review target: a difference there is the same screen captured in another runtime state (a screen
* variant), not a change. The PR comment names an app-wide change once.
*/
export function decideReview(scope: SurfaceSourceScope, visual: PublicVisualVerdict, summary?: WhatChangedSummary): PublicSurfaceReview {
const facts = summary?.facts.map((fact) => ({ category: fact.category, templateId: fact.templateId, bullet: truncate(fact.bullet) })) ?? [];
@@ -303,8 +303,7 @@ export function decideReview(scope: SurfaceSourceScope, visual: PublicVisualVerd
if (inconclusive) {
return { status: "needs-review", description: truncate(visual.verdict === "needs-review" ? visualReasonText(visual) : issue ?? "Needs review") };
}
if (scope === "app-wide") return { status: "unchanged", description: "No visible change" };
return { status: "needs-review", description: "Source changed; no visible difference was captured." };
return { status: "unchanged", description: "No visible change" };
}
function captureDiagnostic(surface: PlanSurface, side: "base" | "head", evidence: PublicEvidenceSide, surfaceId: string = surface.id): PublicEvidenceDiagnostic | undefined {
+7
View File
@@ -0,0 +1,7 @@
import { homedir } from "node:os";
import { join } from "node:path";
/** Where Explore keeps what outlives a run on this machine: `$EXPLORE_CACHE_DIR`, else `$XDG_CACHE_HOME/expo-explore`, else `~/.cache/expo-explore`. */
export function exploreCacheRoot(environment: NodeJS.ProcessEnv): string {
return environment.EXPLORE_CACHE_DIR || join(environment.XDG_CACHE_HOME || join(environment.HOME || homedir(), ".cache"), "expo-explore");
}
+3 -1
View File
@@ -159,7 +159,9 @@ export async function reportCiError(error: unknown, options: {
const renderOptions = { secrets };
const diagnostic = serializeCiError(error, renderOptions);
const write = options.write ?? ((value: string) => process.stderr.write(`${value}\n`));
write(renderCiErrorAnnotation(error, renderOptions));
// An annotation in Actions; in a terminal (a local capture:review) the same redacted text, readable.
write(env.GITHUB_ACTIONS === "true" || env.GITHUB_STEP_SUMMARY ? renderCiErrorAnnotation(error, renderOptions)
: `Error [${diagnostic.code}]: ${diagnostic.message}\nNext action: ${diagnostic.nextAction}`);
const outputs: Array<{ label: string; operation: Promise<unknown> }> = [];
if (env.GITHUB_STEP_SUMMARY) outputs.push({ label: "job summary", operation: appendFile(env.GITHUB_STEP_SUMMARY, `${renderCiErrorSummary(error, renderOptions)}\n`) });
if (options.diagnosticsPath) outputs.push({ label: "diagnostics file", operation: (async () => {
+16 -44
View File
@@ -5,9 +5,13 @@ on:
push:
workflow_dispatch:
permissions: {}
# The exact @expo/explore release CI installs. expo-explore setup --workflows sets it.
env:
# The exact @expo/explore release CI installs. expo-explore setup --workflows sets it.
EXPLORE_VERSION: set-by-expo-explore-setup
APP_PROJECT_DIR: .
APP_INSTALL_DIR: .
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
concurrency:
group: explore-baseline-${{ github.sha }}
cancel-in-progress: false
@@ -21,16 +25,15 @@ jobs:
contents: read
outputs:
platforms: ${{ steps.platforms.outputs.platforms }}
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
APP_PROJECT_DIR: .
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ github.sha }}', path: app, persist-credentials: false }
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- &setup-node
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
- &install-explore
name: Install Explore
id: explore
shell: bash
run: |
set -euo pipefail
@@ -61,10 +64,6 @@ jobs:
permissions:
contents: read
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
APP_PROJECT_DIR: .
APP_INSTALL_DIR: .
PLATFORM: ${{ matrix.platform }}
steps:
- name: Validate baseline source
@@ -78,21 +77,8 @@ jobs:
fi
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ github.sha }}', path: app, fetch-depth: 0, persist-credentials: false }
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
shell: bash
run: |
set -euo pipefail
if [[ ! "$EXPLORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo '::error title=EXPLORE_VERSION_INVALID::Set EXPLORE_VERSION to an exact @expo/explore version. Run expo-explore setup --workflows.'; exit 1
fi
# npm ci against the release's npm-shrinkwrap.json installs the exact dependency tree it was tested with.
mkdir -p "$TOOLS_PREFIX"
npm pack "@expo/explore@$EXPLORE_VERSION" --pack-destination "$TOOLS_PREFIX" --silent > /dev/null
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- *setup-node
- *install-explore
- name: Install the launch recording decoder
shell: bash
# Launch recordings (capture.launch) are decoded with ffmpeg; GitHub's Ubuntu runners do not ship it.
@@ -123,27 +109,13 @@ jobs:
set -euo pipefail
node "$TOOLS/dist/cli.js" capture:baseline --project "$GITHUB_WORKSPACE/app/$APP_PROJECT_DIR" \
--sha "$GITHUB_SHA" --config .expo-explore/config.yaml --output "$RUNNER_TEMP/explore-baseline" --platform "$PLATFORM"
- name: Stop retained baseline session
if: always()
timeout-minutes: 3
- name: Stop the capture session and check the checkout
if: always() && steps.explore.outcome == 'success'
timeout-minutes: 5
env:
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
shell: bash
run: |
set -euo pipefail
if [[ ! -e "$RUNNER_TEMP/explore-baseline/baseline-session" && ! -L "$RUNNER_TEMP/explore-baseline/baseline-session" ]]; then exit 0; fi
node "$TOOLS/scripts/cleanup-ci-sessions.mjs" --eas "$GITHUB_WORKSPACE/$TOOLS/node_modules/.bin/eas" \
--session-file "$RUNNER_TEMP/explore-baseline/baseline-session"
- name: Verify application checkout remains clean
if: always()
shell: bash
run: |
set -euo pipefail
if [[ -d app/.git || -f app/.git ]]; then
if [[ -n "$(git -C app status --porcelain --untracked-files=all)" ]]; then
echo '::error title=CHECKOUT_MODIFIED::Capture modified the application checkout. Keep generated files outside source.'; exit 1
fi
fi
run: node "$TOOLS/dist/cli.js" ci:after-capture --output "$RUNNER_TEMP/explore-baseline" --checkout app
- name: Upload exact-commit baseline evidence
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
+288
View File
@@ -0,0 +1,288 @@
# Generated by expo-explore setup. Fingerprint: set-by-expo-explore-setup
# Install on the default branch. Reviews any two commits of this repository, with no pull request:
# run it from the Actions tab, or call it from any workflow with the base and head that event needs.
#
# on: { push: { tags: ['v*'] } }
# jobs:
# explore:
# permissions: { contents: read, actions: read }
# uses: ./.github/workflows/explore-compare.yml
# with: { base: v1.3.0, head: '${{ github.ref_name }}' }
# secrets: inherit
#
# Call it once per workflow run: a called workflow shares its caller's run, and its artifact names come from the run.
# The report links are written to the run's summary. For a release, pass scope: all to capture every screen,
# and expires-in: never to keep the hosted link (report.preview.hosting: eas) working.
name: Expo Explore compare
on:
workflow_dispatch:
inputs:
base: { description: 'Base: a branch, tag or commit SHA', required: true }
head: { description: 'Head: a branch, tag or commit SHA', required: true }
scope: { description: 'changes (screens whose source changed) or all; default: exploration.scope in config.yaml', required: false, default: '' }
expires-in: { description: 'Hosted link lifetime such as 30d, or never; default: report.preview.expiresAfter', required: false, default: '' }
workflow_call:
inputs:
base: { description: 'Base: a branch, tag or commit SHA', required: true, type: string }
head: { description: 'Head: a branch, tag or commit SHA', required: true, type: string }
scope: { description: 'changes (screens whose source changed) or all; default: exploration.scope in config.yaml', required: false, type: string, default: '' }
expires-in: { description: 'Hosted link lifetime such as 30d, or never; default: report.preview.expiresAfter', required: false, type: string, default: '' }
permissions: {}
env:
# The exact @expo/explore release CI installs. expo-explore setup --workflows sets it.
EXPLORE_VERSION: set-by-expo-explore-setup
APP_PROJECT_DIR: .
APP_INSTALL_DIR: .
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
concurrency:
# ".." cannot appear in a ref name, so no two different comparisons share a group.
group: explore-compare-${{ inputs.base }}..${{ inputs.head }}
cancel-in-progress: false
jobs:
# Resolves both refs to commits once, and lists the platforms .expo-explore/config.yaml captures at head.
platforms:
runs-on: ubuntu-22.04
timeout-minutes: 10
permissions:
contents: read
outputs:
platforms: ${{ steps.platforms.outputs.platforms }}
base: ${{ steps.refs.outputs.base }}
head: ${{ steps.refs.outputs.head }}
compare: ${{ steps.refs.outputs.compare }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { path: app-head, fetch-depth: 0, persist-credentials: false }
- &setup-node
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- &install-explore
name: Install Explore
id: explore
shell: bash
run: |
set -euo pipefail
if [[ ! "$EXPLORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo '::error title=EXPLORE_VERSION_INVALID::Set EXPLORE_VERSION to an exact @expo/explore version. Run expo-explore setup --workflows.'; exit 1
fi
# npm ci against the release's npm-shrinkwrap.json installs the exact dependency tree it was tested with.
mkdir -p "$TOOLS_PREFIX"
npm pack "@expo/explore@$EXPLORE_VERSION" --pack-destination "$TOOLS_PREFIX" --silent > /dev/null
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- name: Resolve base and head to commits
id: refs
env:
BASE_REF: ${{ inputs.base }}
HEAD_REF: ${{ inputs.head }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:compare-refs --project app-head --base "$BASE_REF" --head "$HEAD_REF"
- name: Check out head
env:
HEAD_SHA: ${{ steps.refs.outputs.head }}
shell: bash
run: git -C app-head checkout --quiet --detach "$HEAD_SHA"
- name: List the configured platforms
id: platforms
shell: bash
run: |
set -euo pipefail
platforms="$(node "$TOOLS/dist/cli.js" config:platforms --project "$GITHUB_WORKSPACE/app-head/$APP_PROJECT_DIR" --config .expo-explore/config.yaml | jq -c '.platforms')"
echo "platforms=$platforms" >> "$GITHUB_OUTPUT"
capture:
needs: platforms
strategy:
fail-fast: false
matrix:
platform: ${{ fromJSON(needs.platforms.outputs.platforms) }}
runs-on: ubuntu-22.04
timeout-minutes: 120
permissions:
contents: read
actions: read
outputs:
# "eas" when .expo-explore/config.yaml sets report.preview.hosting; the deploy job runs only then.
preview: ${{ steps.capture.outputs.preview }}
env:
PLATFORM: ${{ matrix.platform }}
BASE_SHA: ${{ needs.platforms.outputs.base }}
HEAD_SHA: ${{ needs.platforms.outputs.head }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ needs.platforms.outputs.base }}', path: app-base, fetch-depth: 0, persist-credentials: false }
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ needs.platforms.outputs.head }}', path: app-head, fetch-depth: 0, persist-credentials: false }
- *setup-node
- *install-explore
- name: Install the launch recording decoder
shell: bash
# Launch recordings (capture.launch) are decoded with ffmpeg; GitHub's Ubuntu runners do not ship it.
run: |
set -euo pipefail
command -v ffmpeg > /dev/null || { sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends ffmpeg > /dev/null; }
ffmpeg -version | head -1
- name: Verify deterministic source planning
env:
SCOPE: ${{ inputs.scope }}
shell: bash
run: |
set -euo pipefail
node "$TOOLS/dist/cli.js" source:verify \
--base-project "$GITHUB_WORKSPACE/app-base/$APP_PROJECT_DIR" --head-project "$GITHUB_WORKSPACE/app-head/$APP_PROJECT_DIR" \
--base-sha "$BASE_SHA" --head-sha "$HEAD_SHA" --config .expo-explore/config.yaml --output "$RUNNER_TEMP/explore-consistency" \
--platform "$PLATFORM" ${SCOPE:+--scope "$SCOPE"}
- name: Install app dependencies
shell: bash
run: |
set -euo pipefail
npm ci --ignore-scripts --prefix "app-base/$APP_INSTALL_DIR"
npm ci --ignore-scripts --prefix "app-head/$APP_INSTALL_DIR"
- name: Find optional exact-base evidence
id: cache
continue-on-error: true
env:
GITHUB_TOKEN: ${{ github.token }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:find-baseline --sha "$BASE_SHA" --platform "$PLATFORM"
- name: Download optional exact-base evidence
if: steps.cache.outputs.id != ''
continue-on-error: true
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
artifact-ids: ${{ steps.cache.outputs.id }}
path: ${{ runner.temp }}/explore-cache
merge-multiple: true
run-id: ${{ steps.cache.outputs.run }}
github-token: ${{ github.token }}
- name: Capture review
id: capture
env:
COMPARE: ${{ needs.platforms.outputs.compare }}
SCOPE: ${{ inputs.scope }}
EXPIRES_IN: ${{ inputs.expires-in }}
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
ANTHROPIC_WORKSPACE_ID: ${{ vars.ANTHROPIC_WORKSPACE_ID }}
# App-test secrets: one NAME: line per {{secret:NAME}} input in .expo-explore (expo-explore setup adds them).
EXPLORE_CAPTURE_CACHE: ${{ runner.temp }}/explore-cache
shell: bash
run: |
set -euo pipefail
printf '%s' "$COMPARE" > "$RUNNER_TEMP/explore-compare.json"
node "$TOOLS/dist/cli.js" capture:review \
--base-project "$GITHUB_WORKSPACE/app-base/$APP_PROJECT_DIR" --head-project "$GITHUB_WORKSPACE/app-head/$APP_PROJECT_DIR" \
--compare "$RUNNER_TEMP/explore-compare.json" --output "$RUNNER_TEMP/explore-review" --config .expo-explore/config.yaml \
--platform "$PLATFORM" ${SCOPE:+--scope "$SCOPE"} ${EXPIRES_IN:+--expires-in "$EXPIRES_IN"}
- name: Stop capture sessions and check the checkouts
if: always() && steps.explore.outcome == 'success'
timeout-minutes: 5
env:
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:after-capture --output "$RUNNER_TEMP/explore-review" --checkout app-base --checkout app-head
- name: Upload captured review for packaging
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: explore-capture-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.platform }}
path: |
${{ runner.temp }}/explore-review/report-input.json
${{ runner.temp }}/explore-review/plan.json
${{ runner.temp }}/explore-review/bundle.json
${{ runner.temp }}/explore-review/review.json
${{ runner.temp }}/explore-review/execution.json
${{ runner.temp }}/explore-review/base-export
${{ runner.temp }}/explore-review/head-export
retention-days: 7
if-no-files-found: error
- name: Upload planning and failure diagnostics
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: explore-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.platform }}
path: |
${{ runner.temp }}/explore-consistency
${{ runner.temp }}/explore-diagnostics
${{ runner.temp }}/explore-review/execution.json
${{ runner.temp }}/explore-review/diagnostics.json
${{ runner.temp }}/explore-review/base-export
${{ runner.temp }}/explore-review/head-export
${{ runner.temp }}/explore-review/base-map/capture-diagnostics
${{ runner.temp }}/explore-review/head-map/capture-diagnostics
${{ runner.temp }}/explore-review/agent-notes-diagnostics.json
${{ runner.temp }}/explore-review/agent-usage.jsonl
retention-days: 7
if-no-files-found: ignore
report:
needs: [platforms, capture]
strategy:
fail-fast: false
matrix:
platform: ${{ fromJSON(needs.platforms.outputs.platforms) }}
runs-on: ubuntu-22.04
timeout-minutes: 20
permissions:
contents: read
env:
PLATFORM: ${{ matrix.platform }}
steps:
- *setup-node
- *install-explore
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: explore-capture-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.platform }}
path: ${{ runner.temp }}/explore-review
- name: Package the report
shell: bash
run: node "$TOOLS/dist/cli.js" ci:report --input "$RUNNER_TEMP/explore-review/report-input.json" --output "$RUNNER_TEMP/explore-report" --platform "$PLATFORM"
- name: Upload the report
id: report
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: explore-review-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.platform }}
path: ${{ runner.temp }}/explore-report
retention-days: 30
if-no-files-found: error
- name: Link the report from the run summary
env:
ARTIFACT_URL: ${{ steps.report.outputs.artifact-url }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:publish --input "$RUNNER_TEMP/explore-review/report-input.json" --artifact-url "$ARTIFACT_URL" --platform "$PLATFORM"
- name: Upload report failure diagnostics
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: explore-report-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.platform }}
path: ${{ runner.temp }}/explore-diagnostics
retention-days: 7
if-no-files-found: ignore
# Hosted report (opt-in, report.preview in config.yaml): one token-gated EAS Hosting deployment serving every platform's report.
# This is the only job after capture that holds EXPO_TOKEN; it writes the link to the run summary.
deploy:
needs: [platforms, capture, report]
if: needs.capture.outputs.preview == 'eas'
runs-on: ubuntu-22.04
timeout-minutes: 20
permissions:
contents: read
actions: read
steps:
- *setup-node
- *install-explore
# One directory per platform artifact (explore-capture-<run>-<attempt>-<platform>, explore-review-<run>-<attempt>-<platform>).
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
pattern: explore-capture-${{ github.run_id }}-${{ github.run_attempt }}-*
path: ${{ runner.temp }}/explore-review
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
pattern: explore-review-${{ github.run_id }}-${{ github.run_attempt }}-*
path: ${{ runner.temp }}/explore-report
- name: Deploy the hosted report and link it from the run summary
env:
GITHUB_TOKEN: ${{ github.token }}
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:deploy --inputs "$RUNNER_TEMP/explore-review" --reports "$RUNNER_TEMP/explore-report"
+49 -185
View File
@@ -9,9 +9,14 @@ on:
inputs:
pr: { description: Open same-repository pull request number, required: true }
permissions: {}
# The exact @expo/explore release CI installs. expo-explore setup --workflows sets it.
env:
# The exact @expo/explore release CI installs. expo-explore setup --workflows sets it.
EXPLORE_VERSION: set-by-expo-explore-setup
APP_PROJECT_DIR: .
APP_INSTALL_DIR: .
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr }}
concurrency:
group: explore-review-${{ github.event.pull_request.number || inputs.pr }}
cancel-in-progress: false
@@ -28,31 +33,17 @@ jobs:
pull-requests: read
outputs:
platforms: ${{ steps.platforms.outputs.platforms }}
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
APP_PROJECT_DIR: .
# The failure job comments with these when a capture job fails before it resolves the PR itself.
pr_number: ${{ steps.pr.outputs.pr_number }}
base: ${{ steps.pr.outputs.base }}
head: ${{ steps.pr.outputs.head }}
steps:
- name: Resolve the live pull request head
id: pr
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr }}
with:
script: |
const number = Number(process.env.PR_NUMBER);
if (!Number.isSafeInteger(number) || number <= 0) throw new Error('PR_NUMBER_INVALID: Provide an open pull request number.');
const { data: pr } = await github.rest.pulls.get({ ...context.repo, pull_number: number });
if (pr.state !== 'open' || pr.draft || pr.head.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}`) {
throw new Error('SOURCE_NOT_TRUSTED: Capture requires an open, non-draft same-repository pull request.');
}
if (!/^[0-9a-f]{40}$/.test(pr.head.sha)) throw new Error('PR_COMMIT_INVALID: Refresh the PR and rerun Explore.');
core.setOutput('head', pr.head.sha);
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ steps.pr.outputs.head }}', path: app-head, persist-credentials: false }
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- &setup-node
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
- &install-explore
name: Install Explore
id: explore
shell: bash
run: |
set -euo pipefail
@@ -65,6 +56,14 @@ jobs:
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- name: Resolve and authorize the live pull request
id: pr
env:
GITHUB_TOKEN: ${{ github.token }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:pr --pr "$PR_NUMBER" --app-dir "$APP_PROJECT_DIR"
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ steps.pr.outputs.head }}', path: app-head, persist-credentials: false }
- name: List the configured platforms
id: platforms
shell: bash
@@ -90,71 +89,22 @@ jobs:
base: ${{ steps.pr.outputs.base }}
head: ${{ steps.pr.outputs.head }}
# "eas" when .expo-explore/config.yaml sets report.preview.hosting; the deploy job runs only then.
preview: ${{ steps.preview.outputs.preview }}
preview: ${{ steps.capture.outputs.preview }}
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
APP_PROJECT_DIR: .
APP_INSTALL_DIR: .
PLATFORM: ${{ matrix.platform }}
steps:
- name: Resolve the live pull request and authorize its source
- *setup-node
- *install-explore
- name: Resolve and authorize the live pull request
id: pr
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr }}
with:
script: |
const number = Number(process.env.PR_NUMBER);
if (!Number.isSafeInteger(number) || number <= 0) throw new Error('PR_NUMBER_INVALID: Provide an open pull request number.');
const { data: pr } = await github.rest.pulls.get({ ...context.repo, pull_number: number });
if (pr.state !== 'open' || pr.draft || pr.head.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}`) {
throw new Error('SOURCE_NOT_TRUSTED: Capture requires an open, non-draft same-repository pull request.');
}
// ci.trustedAuthors in the default branch's config.yaml: logins (bots) reviewed without write access. A PR cannot add its own author.
const trustedAuthors = async () => {
const dir = (process.env.APP_PROJECT_DIR || '.').replace(/^\.(\/|$)/, '').replace(/\/$/, '');
const path = `${dir ? `${dir}/` : ''}.expo-explore/config.yaml`;
let yaml;
try {
const { data } = await github.rest.repos.getContent({ ...context.repo, path, ref: pr.base.repo.default_branch });
yaml = Buffer.from(data.content, 'base64').toString('utf8');
} catch (error) { if (error.status === 404) return []; throw error; }
const block = yaml.match(/^ci:[ \t]*(?:#.*)?\n((?:[ \t]+\S.*\n?|[ \t]*\n)*)/m)?.[1] ?? '';
const list = block.match(/^[ \t]+trustedAuthors:[ \t]*(?:\[(.*?)\][ \t]*(?:#.*)?$|(?:#.*)?\n((?:[ \t]+-[ \t]*\S.*\n?)+))/m);
if (!list) return [];
const entries = list[1] !== undefined ? list[1].split(',') : list[2].split('\n').map(line => line.replace(/^[ \t]+-[ \t]*/, ''));
return entries.map(entry => entry.replace(/\s+#.*$/, '').trim().replace(/^(['"])(.*)\1$/, '$2').toLowerCase()).filter(Boolean);
};
const { data: permission } = await github.rest.repos.getCollaboratorPermissionLevel({ ...context.repo, username: pr.user.login });
if (!['admin', 'maintain', 'write'].includes(permission.permission) && !(await trustedAuthors()).includes(pr.user.login.toLowerCase())) {
throw new Error('SOURCE_NOT_TRUSTED: The PR author must have current repository write access (or be listed in ci.trustedAuthors of .expo-explore/config.yaml on the default branch).');
}
for (const side of [pr.base, pr.head]) if (!/^[0-9a-f]{40}$/.test(side.sha)) throw new Error('PR_COMMIT_INVALID: Refresh the PR and rerun Explore.');
require('node:fs').writeFileSync(`${process.env.RUNNER_TEMP}/explore-pr.json`, JSON.stringify({
repositoryId: String(pr.base.repo.id), repository: pr.base.repo.full_name, number: pr.number,
title: pr.title, url: pr.html_url, base: { ref: pr.base.ref, sha: pr.base.sha }, head: { ref: pr.head.ref, sha: pr.head.sha }
}));
core.setOutput('pr_number', pr.number); core.setOutput('base', pr.base.sha); core.setOutput('head', pr.head.sha);
GITHUB_TOKEN: ${{ github.token }}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:pr --pr "$PR_NUMBER" --app-dir "$APP_PROJECT_DIR" --output "$RUNNER_TEMP/explore-pr.json"
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ steps.pr.outputs.base }}', path: app-base, fetch-depth: 0, persist-credentials: false }
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ steps.pr.outputs.head }}', path: app-head, fetch-depth: 0, persist-credentials: false }
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
shell: bash
run: |
set -euo pipefail
if [[ ! "$EXPLORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo '::error title=EXPLORE_VERSION_INVALID::Set EXPLORE_VERSION to an exact @expo/explore version. Run expo-explore setup --workflows.'; exit 1
fi
# npm ci against the release's npm-shrinkwrap.json installs the exact dependency tree it was tested with.
mkdir -p "$TOOLS_PREFIX"
npm pack "@expo/explore@$EXPLORE_VERSION" --pack-destination "$TOOLS_PREFIX" --silent > /dev/null
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- name: Install the launch recording decoder
shell: bash
# Launch recordings (capture.launch) are decoded with ffmpeg; GitHub's Ubuntu runners do not ship it.
@@ -182,24 +132,11 @@ jobs:
- name: Find optional exact-base evidence
id: cache
continue-on-error: true
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
GITHUB_TOKEN: ${{ github.token }}
BASE_SHA: ${{ steps.pr.outputs.base }}
with:
script: |
const { data: repository } = await github.rest.repos.get(context.repo);
const { data: baseline } = await github.rest.actions.getWorkflow({ ...context.repo, workflow_id: 'explore-baseline.yml' });
// Baselines carry the platform suffix; iOS also accepts the unsuffixed name older baseline workflows uploaded.
const names = [`explore-baseline-${process.env.BASE_SHA}-${process.env.PLATFORM}`, ...(process.env.PLATFORM === 'ios' ? [`explore-baseline-${process.env.BASE_SHA}`] : [])];
const records = (await Promise.all(names.map(name => github.paginate(github.rest.actions.listArtifactsForRepo, { ...context.repo, name, per_page: 100 })))).flat();
for (const artifact of records.filter(a => !a.expired).sort((a, b) => b.id - a.id)) {
if (!artifact.workflow_run?.id) continue;
const { data: run } = await github.rest.actions.getWorkflowRun({ ...context.repo, run_id: artifact.workflow_run.id });
if (run.conclusion !== 'success' || run.workflow_id !== baseline.id || run.head_sha !== process.env.BASE_SHA
|| run.head_branch !== repository.default_branch || !['push', 'workflow_dispatch'].includes(run.event)
|| run.head_repository?.full_name !== `${context.repo.owner}/${context.repo.repo}`) continue;
core.setOutput('id', artifact.id); core.setOutput('run', run.id); break;
}
shell: bash
run: node "$TOOLS/dist/cli.js" ci:find-baseline --sha "$BASE_SHA" --platform "$PLATFORM"
- name: Download optional exact-base evidence
if: steps.cache.outputs.id != ''
continue-on-error: true
@@ -211,6 +148,7 @@ jobs:
run-id: ${{ steps.cache.outputs.run }}
github-token: ${{ github.token }}
- name: Capture review
id: capture
env:
GITHUB_TOKEN: ${{ github.token }}
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
@@ -226,35 +164,13 @@ jobs:
--base-project "$GITHUB_WORKSPACE/app-base/$APP_PROJECT_DIR" --head-project "$GITHUB_WORKSPACE/app-head/$APP_PROJECT_DIR" \
--pull-request "$RUNNER_TEMP/explore-pr.json" --output "$RUNNER_TEMP/explore-review" --config .expo-explore/config.yaml \
--platform "$PLATFORM"
- name: Stop retained capture sessions
if: always()
- name: Stop capture sessions and check the checkouts
if: always() && steps.pr.outcome == 'success'
timeout-minutes: 5
env:
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
shell: bash
run: |
set -euo pipefail
if [[ ! -e "$RUNNER_TEMP/explore-review/head-session" && ! -L "$RUNNER_TEMP/explore-review/head-session" && ! -e "$RUNNER_TEMP/explore-review/base-session" && ! -L "$RUNNER_TEMP/explore-review/base-session" ]]; then exit 0; fi
node "$TOOLS/scripts/cleanup-ci-sessions.mjs" --eas "$GITHUB_WORKSPACE/$TOOLS/node_modules/.bin/eas" \
--session-file "$RUNNER_TEMP/explore-review/head-session" --session-file "$RUNNER_TEMP/explore-review/base-session"
- name: Verify application checkouts remain clean
if: always() && steps.pr.outcome == 'success'
shell: bash
run: |
set -euo pipefail
for directory in app-base app-head; do
if [[ -d "$directory/.git" || -f "$directory/.git" ]]; then
if [[ -n "$(git -C "$directory" status --porcelain --untracked-files=all)" ]]; then
echo "::error title=CHECKOUT_MODIFIED::Capture modified $directory. Keep generated files outside source checkouts."; exit 1
fi
fi
done
- name: Read the hosted preview request
id: preview
shell: bash
run: |
set -euo pipefail
echo "preview=$(jq -r '.preview.hosting // ""' "$RUNNER_TEMP/explore-review/report-input.json")" >> "$GITHUB_OUTPUT"
run: node "$TOOLS/dist/cli.js" ci:after-capture --output "$RUNNER_TEMP/explore-review" --checkout app-base --checkout app-head
- name: Upload captured review for packaging
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
@@ -300,34 +216,17 @@ jobs:
actions: read
pull-requests: write
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
PLATFORM: ${{ matrix.platform }}
steps:
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
shell: bash
run: |
set -euo pipefail
if [[ ! "$EXPLORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo '::error title=EXPLORE_VERSION_INVALID::Set EXPLORE_VERSION to an exact @expo/explore version. Run expo-explore setup --workflows.'; exit 1
fi
# npm ci against the release's npm-shrinkwrap.json installs the exact dependency tree it was tested with.
mkdir -p "$TOOLS_PREFIX"
npm pack "@expo/explore@$EXPLORE_VERSION" --pack-destination "$TOOLS_PREFIX" --silent > /dev/null
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- *setup-node
- *install-explore
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
name: explore-capture-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.platform }}
path: ${{ runner.temp }}/explore-review
- name: Package hosted review bundle
shell: bash
run: |
set -euo pipefail
node "$TOOLS/dist/cli.js" ci:report --input "$RUNNER_TEMP/explore-review/report-input.json" --output "$RUNNER_TEMP/explore-report" --platform "$PLATFORM"
run: node "$TOOLS/dist/cli.js" ci:report --input "$RUNNER_TEMP/explore-review/report-input.json" --output "$RUNNER_TEMP/explore-report" --platform "$PLATFORM"
- name: Upload hosted review bundle
id: viewer
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -341,9 +240,7 @@ jobs:
GITHUB_TOKEN: ${{ github.token }}
ARTIFACT_URL: ${{ steps.viewer.outputs.artifact-url }}
shell: bash
run: |
set -euo pipefail
node "$TOOLS/dist/cli.js" ci:publish --input "$RUNNER_TEMP/explore-review/report-input.json" --artifact-url "$ARTIFACT_URL" --platform "$PLATFORM"
run: node "$TOOLS/dist/cli.js" ci:publish --input "$RUNNER_TEMP/explore-review/report-input.json" --artifact-url "$ARTIFACT_URL" --platform "$PLATFORM"
- name: Upload report failure diagnostics
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -364,31 +261,15 @@ jobs:
contents: read
actions: read
pull-requests: write
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
steps:
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
shell: bash
run: |
set -euo pipefail
if [[ ! "$EXPLORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo '::error title=EXPLORE_VERSION_INVALID::Set EXPLORE_VERSION to an exact @expo/explore version. Run expo-explore setup --workflows.'; exit 1
fi
mkdir -p "$TOOLS_PREFIX"
npm pack "@expo/explore@$EXPLORE_VERSION" --pack-destination "$TOOLS_PREFIX" --silent > /dev/null
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- *setup-node
- *install-explore
# One directory per platform artifact (explore-capture-<run>-<attempt>-<platform>, explore-review-<run>-<attempt>-<platform>).
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
pattern: explore-capture-${{ github.run_id }}-${{ github.run_attempt }}-*
path: ${{ runner.temp }}/explore-review
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
id: report
with:
pattern: explore-review-${{ github.run_id }}-${{ github.run_attempt }}-*
path: ${{ runner.temp }}/explore-report
@@ -397,9 +278,7 @@ jobs:
GITHUB_TOKEN: ${{ github.token }}
EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}
shell: bash
run: |
set -euo pipefail
node "$TOOLS/dist/cli.js" ci:deploy --inputs "$RUNNER_TEMP/explore-review" --reports "$RUNNER_TEMP/explore-report"
run: node "$TOOLS/dist/cli.js" ci:deploy --inputs "$RUNNER_TEMP/explore-review" --reports "$RUNNER_TEMP/explore-report"
failure:
needs: [platforms, capture, report, deploy]
if: always() && (needs.platforms.result == 'failure' || needs.capture.result == 'failure' || needs.report.result == 'failure' || needs.deploy.result == 'failure')
@@ -408,9 +287,6 @@ jobs:
permissions:
actions: read
pull-requests: write
env:
TOOLS_PREFIX: explore-tools
TOOLS: explore-tools/package
steps:
- name: Download capture failure diagnostic
if: needs.capture.result == 'failure'
@@ -426,26 +302,14 @@ jobs:
with:
pattern: explore-report-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-*
path: ${{ runner.temp }}/explore-failure/report
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with: { node-version: 24, package-manager-cache: false }
- name: Install Explore
shell: bash
run: |
set -euo pipefail
if [[ ! "$EXPLORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
echo '::error title=EXPLORE_VERSION_INVALID::Set EXPLORE_VERSION to an exact @expo/explore version. Run expo-explore setup --workflows.'; exit 1
fi
mkdir -p "$TOOLS_PREFIX"
npm pack "@expo/explore@$EXPLORE_VERSION" --pack-destination "$TOOLS_PREFIX" --silent > /dev/null
tar -xzf "$TOOLS_PREFIX"/expo-explore-*.tgz -C "$TOOLS_PREFIX"
cd "$TOOLS"
npm ci --omit=dev --include=optional --ignore-scripts --no-audit --no-fund
- *setup-node
- *install-explore
- name: Report failure only on the current PR
env:
GITHUB_TOKEN: ${{ github.token }}
PR_NUMBER: ${{ needs.capture.outputs.pr_number }}
HEAD_SHA: ${{ needs.capture.outputs.head }}
BASE_SHA: ${{ needs.capture.outputs.base }}
PR_NUMBER: ${{ needs.capture.outputs.pr_number || needs.platforms.outputs.pr_number }}
HEAD_SHA: ${{ needs.capture.outputs.head || needs.platforms.outputs.head }}
BASE_SHA: ${{ needs.capture.outputs.base || needs.platforms.outputs.base }}
shell: bash
run: |
set -euo pipefail
+8 -7
View File
@@ -403,7 +403,7 @@ test("a hosted preview link downloads the report from its own token route, opens
preview: { ...preview, token: "cdefghijklmnopqrstuvwxyz23456723", status: 410, body: JSON.stringify({ error: "expired", expiredAt: "2030-01-01T00:00:00.000Z" }) } });
const goneShell = gone.page.locator(".report-loading-shell");
await expect(goneShell).toHaveAttribute("data-loading-status", "failed");
await expect(goneShell).toContainText("This preview link expired on Jan 1, 2030. Download the report from the pull request instead");
await expect(goneShell).toContainText("This preview link expired on Jan 1, 2030. Download the report from the pull request or workflow run instead");
await expect(gone.page.locator(".report-drop-input")).toHaveCount(0);
assert.deepEqual(gone.errors, []);
});
@@ -1005,7 +1005,7 @@ test("a docs-only report with zero images and no EAS build opens Screens without
assert.deepEqual(errors, []);
});
test("unverified capture diagnostics stay separate from verified Needs review and source impact filters", async t => {
test("unverified capture diagnostics stay separate from verified Needs review, and source changes nobody compared are not changes", async t => {
const report = reportFixture();
const home = report.review.surfaces[0];
const uncertain = structuredClone(home);
@@ -1029,12 +1029,13 @@ test("unverified capture diagnostics stay separate from verified Needs review an
await expect(page.locator(".app-shell")).toBeVisible();
await page.getByRole("button", { name: "Screens", exact: true }).click();
await expect(page.locator(".screens-page .diff-frame.diff-needs-review")).toHaveCount(1);
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(2);
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(1);
// The unverified /home and the never-captured /candidate changed in source only: not compared, like /untouched.
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(0);
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(3);
await expect(page.locator(".screens-page .diff-frame.diff-modified")).toHaveCount(0);
const menu = await openChangesMenu(page);
const chips = menu.getByRole("group", { name: "Filter changes" }).getByRole("button");
await expect(chips).toHaveText(["Modified 0", "No visible change 1", "Source-affected 2"]);
await expect(chips).toHaveText(["Modified 0", "No visible change 1"]);
assert.deepEqual(errors, []);
});
@@ -1068,8 +1069,8 @@ test("an existing report with operational verdicts opens as diagnostics without
const { page, errors } = await harness(t, await archive(report), { app: true });
await expect(page.locator(".app-shell")).toBeVisible();
await page.getByRole("button", { name: "Screens", exact: true }).click();
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(1);
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(1);
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(0);
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(2);
await expect(page.locator(".screens-page .diff-frame.diff-unavailable")).toHaveCount(1, "an added route whose capture failed has nothing to show");
await expect(page.locator(".screens-page .diff-frame.diff-removed")).toHaveCount(1);
await expect(page.locator(".diff-frame.diff-needs-review, .diff-frame.diff-modified, .diff-frame.diff-unchanged, .diff-frame.diff-added")).toHaveCount(0);
+14 -11
View File
@@ -103,7 +103,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
const pullRequestPath = join(root, 'pull-request.json'); await writeFile(pullRequestPath, JSON.stringify(pr));
const environment = { PATH: process.env.PATH, HOME: root, RUNNER_TEMP: root, EXPO_TOKEN: 'test-expo-secret', GITHUB_TOKEN: 'test-github-secret',
GITHUB_RUN_ID: '1234', GITHUB_RUN_ATTEMPT: '1', GITHUB_REPOSITORY: pr.repository, TOOLS_COMMIT: 'c'.repeat(40), EXPLORE_VIEWER_ORIGIN: 'https://viewer.example' };
const requests = []; const comments = []; const sessions = new Map(); let currentSession; let currentPath = '/'; let sessionCounter = 0; let repackedSha; let openFailed = false; let currentScheme = 'light';
const requests = []; const comments = []; const sessions = new Map(); let currentSession; const idleDevice = { path: '/', scheme: 'light' }; let sessionCounter = 0; let repackedSha; let openFailed = false;
const identity = () => ({ session: 'expo-explore-runtime', appBundleId: config.app.bundleId,
device: { id: 'device-1', name: config.device.name, platform, target: 'mobile', osVersion: '26.0', locale: 'en-US', orientation: 'portrait', colorScheme: 'light' },
identifiers: { session: 'expo-explore-runtime', appBundleId: config.app.bundleId, deviceId: 'device-1', deviceName: config.device.name } });
@@ -140,8 +140,8 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
return json({ jobs: [{ key: 'repack', status: 'SUCCESS', outputs: { build_id: `repacked-${repackedSha}`, platform } }] });
}
if (command === 'simulator:start') {
const id = `session-${++sessionCounter}`; currentSession = id; currentPath = '/'; openFailed = false;
const session = { id, name: value(request, '--name'), build: value(request, '--build-id') }; sessions.set(id, session);
const id = `session-${++sessionCounter}`; currentSession = id; openFailed = false;
const session = { id, name: value(request, '--name'), build: value(request, '--build-id'), path: '/', scheme: 'light' }; sessions.set(id, session);
writeFileSync(join(request.cwd, '.env.eas-simulator'), `${HEADER}EAS_SIMULATOR_SESSION_ID='${id}'\nAGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/${id}'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='controller-private-token'\n`);
return { stdout: 'ready', stderr: '' };
}
@@ -155,6 +155,9 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
return { stdout: '', stderr: '' };
}
if (basename(request.command) === 'agent-device') {
// Base and head capture in parallel, each on its own simulator: a request names its session in the daemon URL,
// so the route, appearance and build it sees are that session's, not whichever session started last.
const device = sessions.get(/\/([^/]+)$/.exec(request.environment?.AGENT_DEVICE_DAEMON_BASE_URL ?? '')?.[1]) ?? sessions.get(currentSession) ?? idleDevice;
if (command === '--version') return { stdout: AGENT_DEVICE_VERSION, stderr: '' };
if (command === 'open') {
if (request.args[2]?.startsWith('sample://')) {
@@ -162,7 +165,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
openFailed = true;
return json({ success: false, error: { code: 'COMMAND_FAILED', message: 'The app is not ready for this link yet.' } });
}
currentPath = '/' + request.args[2].slice('sample://'.length);
device.path = '/' + request.args[2].slice('sample://'.length);
}
return ok(identity());
}
@@ -170,17 +173,17 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
if (command === 'wait') return ok({});
if (command === 'alert' && request.args[1] === 'get') return json({ success: false, error: { code: 'COMMAND_FAILED', message: 'alert not found' } });
if (command === 'snapshot') {
const dynamic = currentPath.startsWith('/item/');
const dynamic = device.path.startsWith('/item/');
const destination = provider === 'expo-router'
? { provider, pathname: currentPath, segments: dynamic ? ['item', '[id]'] : currentPath.split('/').filter(Boolean), parameters: dynamic ? { id: currentPath.slice('/item/'.length) } : {} }
: { provider, segments: [currentPath.slice(1).replace(/^./, first => first.toUpperCase())], parameters: {} };
? { provider, pathname: device.path, segments: dynamic ? ['item', '[id]'] : device.path.split('/').filter(Boolean), parameters: dynamic ? { id: device.path.slice('/item/'.length) } : {} }
: { provider, segments: [device.path.slice(1).replace(/^./, first => first.toUpperCase())], parameters: {} };
return ok({ truncated: false, nodes: [
{ index: 0, type: 'StaticText', label: currentPath, identifier: 'screen-title', enabled: true, visible: true, rect: { x: 0, y: 0, width: 16, height: 24 } },
...(currentPath === observerFailurePath ? [] : [{ index: 1, type: 'StaticText', label: JSON.stringify(destination), identifier: CAPTURE_OBSERVER_IDENTIFIER, enabled: true, visible: true }]),
{ index: 0, type: 'StaticText', label: device.path, identifier: 'screen-title', enabled: true, visible: true, rect: { x: 0, y: 0, width: 16, height: 24 } },
...(device.path === observerFailurePath ? [] : [{ index: 1, type: 'StaticText', label: JSON.stringify(destination), identifier: CAPTURE_OBSERVER_IDENTIFIER, enabled: true, visible: true }]),
] });
}
if (command === 'settings') { if (request.args[1] === 'appearance') currentScheme = request.args[2]; return ok({ setting: request.args[1], value: request.args[2] }); }
if (command === 'screenshot') { const color = createHash('sha256').update(`${currentPath}:${currentScheme}:${currentPath === '/home' ? sessions.get(currentSession).build : 'unchanged-source'}`).digest(); const data = Buffer.alloc(16 * 24 * 4); for (let i = 0; i < data.length; i += 4) { data[i] = color[0]; data[i + 1] = color[1]; data[i + 2] = color[2]; data[i + 3] = 255; } writeFileSync(request.args[1], PNG.sync.write({ width: 16, height: 24, data })); return ok({ path: request.args[1] }); }
if (command === 'settings') { if (request.args[1] === 'appearance') device.scheme = request.args[2]; return ok({ setting: request.args[1], value: request.args[2] }); }
if (command === 'screenshot') { const color = createHash('sha256').update(`${device.path}:${device.scheme}:${device.path === '/home' ? device.build : 'unchanged-source'}`).digest(); const data = Buffer.alloc(16 * 24 * 4); for (let i = 0; i < data.length; i += 4) { data[i] = color[0]; data[i + 1] = color[1]; data[i + 2] = color[2]; data[i + 3] = 255; } writeFileSync(request.args[1], PNG.sync.write({ width: 16, height: 24, data })); return ok({ path: request.args[1] }); }
}
throw new Error(`Unexpected mocked command: ${request.command} ${request.args.join(' ')}`);
};
+48 -23
View File
@@ -12,12 +12,14 @@ const reviewSource = await readFile(new URL("../../templates/explore-review.yml"
const review = parse(reviewSource);
const baselineSource = await readFile(new URL("../../templates/explore-baseline.yml", import.meta.url), "utf8");
const baseline = parse(baselineSource);
const workflows = [review, baseline];
const compareSource = await readFile(new URL("../../templates/explore-compare.yml", import.meta.url), "utf8");
const compare = parse(compareSource);
const workflows = [review, baseline, compare];
test("one review and one baseline template replace all duplicate CI entrypoints", async () => {
test("one review, one baseline and one compare template replace all duplicate CI entrypoints", async () => {
const names = (await readdir(new URL("../../templates/", import.meta.url))).filter(name => name.endsWith(".yml"));
assert.deepEqual(names.sort(), ["explore-baseline.yml", "explore-review.yml"]);
for (const source of [actionSource, reviewSource, baselineSource]) {
assert.deepEqual(names.sort(), ["explore-baseline.yml", "explore-compare.yml", "explore-review.yml"]);
for (const source of [actionSource, reviewSource, baselineSource, compareSource]) {
assert.doesNotMatch(source, /surface_manifest|surfaces\.json|runtime_probe|--keyless|KEYLESS|claude-code|agent_sandbox|report:export|report:comment/);
}
for (const removed of ["surface_manifest", "impact_plan", "runtime_probe_url", "keyless", "agent_sandbox", "bundle_id"]) {
@@ -117,7 +119,7 @@ test("trusted tools retain native agent runtimes while omitting development depe
const builds = [action.runs.steps.find(step => step.name === "Build the pinned Explore CLI"),
...workflows.flatMap(workflow => Object.values(workflow.jobs)
.flatMap(job => job.steps.filter(step => step.name === "Install Explore")))];
assert.equal(builds.length, 8, "composite action, review platforms/capture/report/deploy/failure, and baseline platforms/baseline install the trusted tools");
assert.equal(builds.length, 12, "composite action, review platforms/capture/report/deploy/failure, baseline platforms/baseline, and compare platforms/capture/report/deploy install the trusted tools");
for (const step of builds) {
const install = step.run.split("\n").find(line => /^\s*npm ci\b/.test(line));
assert.ok(install, step.name);
@@ -227,20 +229,18 @@ test("capture receives the automatic GitHub token for current PR verification",
assert.equal(review.jobs.capture.permissions["pull-requests"], "write");
});
test("always-run cleanup consumes only explicit retained handoffs before checkout verification", () => {
for (const [job, name, sessionFiles] of [
[review.jobs.capture, "Stop retained capture sessions", ["head-session", "base-session"]],
[baseline.jobs.baseline, "Stop retained baseline session", ["baseline-session"]],
test("after capture, success or not, ci:after-capture stops the recorded sessions and checks every checkout", () => {
for (const [job, condition, output, checkouts] of [
[review.jobs.capture, "always() && steps.pr.outcome == 'success'", "explore-review", ["app-base", "app-head"]],
[compare.jobs.capture, "always() && steps.explore.outcome == 'success'", "explore-review", ["app-base", "app-head"]],
[baseline.jobs.baseline, "always() && steps.explore.outcome == 'success'", "explore-baseline", ["app"]],
]) {
const index = job.steps.findIndex(step => step.name === name);
const cleanup = job.steps[index];
assert.equal(cleanup.if, "always()");
const cleanup = job.steps.find(step => step.run?.includes("ci:after-capture"));
assert.equal(cleanup.if, condition);
assert.ok(cleanup["timeout-minutes"] <= 5);
assert.equal(cleanup.env.EXPO_TOKEN, "${{ secrets.EXPO_TOKEN }}");
assert.match(cleanup.run, /cleanup-ci-sessions\.mjs/);
for (const path of sessionFiles) assert.ok(cleanup.run.includes(path));
assert.ok(index < job.steps.findIndex(step => step.name?.startsWith("Verify application checkout")));
assert.doesNotMatch(cleanup.run, /simulator:list|--all/);
assert.equal(cleanup.run, `node "$TOOLS/dist/cli.js" ci:after-capture --output "$RUNNER_TEMP/${output}" ${checkouts.map(dir => `--checkout ${dir}`).join(" ")}`);
assert.ok(job.steps.indexOf(cleanup) < job.steps.findIndex(step => step.uses?.startsWith("actions/upload-artifact@")), "before any upload");
}
assert.equal(action.runs.steps.at(-1).name, "Stop retained capture sessions");
assert.equal(action.runs.steps.at(-1).if, "always() && steps.preflight.outcome == 'success'");
@@ -305,10 +305,9 @@ test("the deploy job is the only post-capture job that holds EXPO_TOKEN, and it
assert.ok(downloads.every(step => step.with.name === undefined && step.with["merge-multiple"] === undefined));
assert.doesNotMatch(JSON.stringify(deploy), /OPENAI_API_KEY|ANTHROPIC_API_KEY/);
assert.equal(review.jobs.report.outputs, undefined);
assert.equal(review.jobs.capture.outputs.preview, "${{ steps.preview.outputs.preview }}");
const previewStep = review.jobs.capture.steps.find(step => step.id === "preview");
assert.match(previewStep.run, /jq -r '\.preview\.hosting \/\/ ""'/);
assert.ok(review.jobs.capture.steps.indexOf(previewStep) < review.jobs.capture.steps.findIndex(step => step.name === "Upload captured review for packaging"));
// capture:review writes preview=<hosting> to the step outputs from the reviewed config.
assert.equal(review.jobs.capture.outputs.preview, "${{ steps.capture.outputs.preview }}");
assert.match(review.jobs.capture.steps.find(step => step.id === "capture").run, /capture:review/);
assert.deepEqual(review.jobs.failure.needs, ["platforms", "capture", "report", "deploy"]);
assert.match(review.jobs.failure.if, /needs\.platforms\.result == 'failure'/);
assert.match(review.jobs.failure.if, /needs\.deploy\.result == 'failure'/);
@@ -339,12 +338,38 @@ test("review captures and reports each configured platform in its own matrix job
assert.ok(uses.length > 0, command);
for (const run of uses) assert.match(run, /--platform "\$PLATFORM"/, command);
}
const baselineLookup = review.jobs.capture.steps.find(step => step.name === "Find optional exact-base evidence").with.script;
assert.match(baselineLookup, /explore-baseline-\$\{process\.env\.BASE_SHA\}-\$\{process\.env\.PLATFORM\}/);
assert.match(baselineLookup, /process\.env\.PLATFORM === 'ios' \? \[`explore-baseline-\$\{process\.env\.BASE_SHA\}`\]/);
for (const workflow of [review, compare]) {
assert.equal(workflow.jobs.capture.steps.find(step => step.name === "Find optional exact-base evidence").run,
'node "$TOOLS/dist/cli.js" ci:find-baseline --sha "$BASE_SHA" --platform "$PLATFORM"');
}
for (const [job, name] of [[review.jobs.capture, "Upload captured review for packaging"], [review.jobs.capture, "Upload planning and failure diagnostics"],
[review.jobs.report, "Upload hosted review bundle"], [review.jobs.report, "Upload report failure diagnostics"],
[baseline.jobs.baseline, "Upload exact-commit baseline evidence"], [baseline.jobs.baseline, "Upload planning and baseline diagnostics"]]) {
assert.ok(job.steps.find(step => step.name === name).with.name.endsWith("-${{ matrix.platform }}"), name);
}
});
test("compare reviews any two refs from a manual run or another workflow, with no pull request access", () => {
for (const trigger of ["workflow_dispatch", "workflow_call"]) {
assert.deepEqual(Object.keys(compare.on[trigger].inputs).sort(), ["base", "expires-in", "head", "scope"]);
for (const name of ["base", "head"]) assert.equal(compare.on[trigger].inputs[name].required, true);
for (const name of ["scope", "expires-in"]) assert.deepEqual([compare.on[trigger].inputs[name].required, compare.on[trigger].inputs[name].default], [false, ""]);
}
assert.deepEqual(Object.keys(compare.on).sort(), ["workflow_call", "workflow_dispatch"]);
for (const job of Object.values(compare.jobs)) assert.equal(job.permissions["pull-requests"], undefined, "a comparison never touches pull requests");
const capture = compare.jobs.capture.steps.find(step => step.name === "Capture review");
assert.match(capture.run, /capture:review[\s\S]*--compare "\$RUNNER_TEMP\/explore-compare\.json"/);
assert.doesNotMatch(compareSource, /ci:failure|--pull-request/);
// Each override reaches the CLI only when the caller set it; the CLI validates the value.
assert.match(capture.run, /\$\{SCOPE:\+--scope "\$SCOPE"\} \$\{EXPIRES_IN:\+--expires-in "\$EXPIRES_IN"\}/);
assert.match(compare.jobs.capture.steps.find(step => step.name === "Verify deterministic source planning").run, /\$\{SCOPE:\+--scope "\$SCOPE"\}/);
assert.match(compare.jobs.report.steps.find(step => step.name === "Link the report from the run summary").run, /ci:publish --input .* --artifact-url "\$ARTIFACT_URL" --platform "\$PLATFORM"/);
assert.equal(compare.jobs.capture.env.BASE_SHA, "${{ needs.platforms.outputs.base }}", "capture checks out the commits the refs resolved to once");
assert.equal(compare.jobs.capture.env.HEAD_SHA, "${{ needs.platforms.outputs.head }}");
assert.equal(compare.concurrency.group, "explore-compare-${{ inputs.base }}..${{ inputs.head }}", "\"..\" cannot appear in a ref, so groups never collide");
const diagnostics = compare.jobs.report.steps.find(step => step.name === "Upload report failure diagnostics");
assert.deepEqual([diagnostics.if, diagnostics.with.path], ["always()", "${{ runner.temp }}/explore-diagnostics"]);
assert.match(compare.jobs.platforms.steps.find(step => step.id === "refs").run, /ci:compare-refs --project app-head --base "\$BASE_REF" --head "\$HEAD_REF"/);
assert.match(compare.jobs.capture.steps.find(step => step.id === "capture").run, /printf '%s' "\$COMPARE" > "\$RUNNER_TEMP\/explore-compare\.json"/);
assert.match(compare.jobs.deploy.steps.at(-1).run, /ci:deploy --inputs/);
});
+7 -3
View File
@@ -64,7 +64,11 @@ test("failure reporting downloads only this run attempt's failed-job diagnostics
assert.equal(step.with["run-id"], undefined, "download-artifact defaults to this run");
assert.equal(step.with.repository, undefined);
}
const resolve = workflow.jobs.capture.steps.findIndex(step => step.id === "pr");
const install = workflow.jobs.capture.steps.findIndex(step => step.name === "Install Explore");
assert.ok(resolve >= 0 && resolve < install, "authorized PR identity survives early tool settings failures");
// A capture job that fails before it resolves the PR (its tool install, say) still gets its failure comment:
// the platforms job already resolved and authorized the same PR.
const report = job.steps.find(step => step.name === "Report failure only on the current PR");
for (const [env, output] of [["PR_NUMBER", "pr_number"], ["HEAD_SHA", "head"], ["BASE_SHA", "base"]]) {
assert.equal(report.env[env], `\${{ needs.capture.outputs.${output} || needs.platforms.outputs.${output} }}`);
assert.equal(workflow.jobs.platforms.outputs[output], `\${{ steps.pr.outputs.${output} }}`);
}
});
+38 -10
View File
@@ -2,16 +2,44 @@ import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { isVisibleChange } = await tsImport("../../viewer/src/utils/changed-screens.ts", import.meta.url);
const { isCapturedChange } = await tsImport("../../viewer/src/utils/changed-screens.ts", import.meta.url);
test("only a change the captures show counts for Compare and Screens' Changed filter", () => {
assert.equal(isVisibleChange({ status: "added" }), true);
assert.equal(isVisibleChange({ status: "removed" }), true);
assert.equal(isVisibleChange({ status: "modified" }), true);
// The source changed but the captures look the same.
assert.equal(isVisibleChange({ status: "modified", notVisible: true }), false);
assert.equal(isVisibleChange({ status: "needs-review" }), false);
assert.equal(isVisibleChange({ status: "source-affected" }), false);
assert.equal(isVisibleChange({ status: "unchanged" }), false);
assert.equal(isVisibleChange(undefined), false);
assert.equal(isCapturedChange({ status: "added" }), true);
assert.equal(isCapturedChange({ status: "removed" }), true);
assert.equal(isCapturedChange({ status: "modified" }), true);
// The screenshots match but the accessibility tree changed: screen readers see it, so it is reviewed.
assert.equal(isCapturedChange({ status: "modified", accessibilityOnly: true }), true);
// The source changed but the captures show nothing different.
assert.equal(isCapturedChange({ status: "needs-review" }), false);
assert.equal(isCapturedChange({ status: "source-affected" }), false);
assert.equal(isCapturedChange({ status: "unchanged" }), false);
assert.equal(isCapturedChange(undefined), false);
});
const { splitForAssistiveTechnology } = await tsImport("../../viewer/src/utils/presented-changes.ts", import.meta.url);
test("What changed lists what assistive technology reads under its own heading", () => {
const change = (id, category) => ({ id, copy: id, fact: { id, category, templateId: `${category}.x`, priority: 0, evidenceRefs: [] } });
const changes = [change("Added button “Play”.", "element"), change("Changed accessibility label.", "accessibility")];
const ids = ({ visible, assistive }) => [visible.map(entry => entry.id), assistive.map(entry => entry.id)];
// Pixels differ: an added element may be visible, a label is not.
assert.deepEqual(ids(splitForAssistiveTechnology(changes, { status: "modified" })), [["Added button “Play”."], ["Changed accessibility label."]]);
// The screenshots match: nothing on the screen looks different, so every finding is for assistive technology.
assert.deepEqual(ids(splitForAssistiveTechnology(changes, { status: "modified", accessibilityOnly: true })), [[], ["Added button “Play”.", "Changed accessibility label."]]);
// A reviewer note is not a finding about the accessibility tree.
assert.deepEqual(ids(splitForAssistiveTechnology([{ id: "review-note", copy: "Note" }], { status: "modified", accessibilityOnly: true })), [["review-note"], []]);
});
const { focusCounts, focusStatusOf } = await tsImport("../../viewer/src/utils/changed-screens.ts", import.meta.url);
test("the Changes filter counts Accessibility only apart from Modified", () => {
const screens = new Map([
["a", { status: "modified" }], ["b", { status: "modified", accessibilityOnly: true }], ["c", { status: "modified", accessibilityOnly: true }],
["d", { status: "added" }], ["e", { status: "not-compared" }], ["f", { status: "unchanged" }],
]);
assert.deepEqual(focusCounts({ screens }), { added: 1, modified: 1, "accessibility-only": 2, removed: 0, "needs-review": 0, "source-affected": 0 });
assert.equal(focusStatusOf({ status: "modified", accessibilityOnly: true }), "accessibility-only");
assert.equal(focusStatusOf({ status: "modified" }), "modified");
assert.equal(focusStatusOf(undefined), undefined);
});
+77
View File
@@ -0,0 +1,77 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { runCompareCi } from '../../dist/ci/pipeline.js';
import { writeCaptureOutputs } from '../../dist/ci/workflow-steps.js';
import { exportCiReport, publishCiReportComment, readCiReportInput } from '../../dist/report/artifact.js';
import { renderCompareSummary } from '../../dist/report/preview-deploy.js';
import { readCaptureBundle } from '../../dist/review/capture-review.js';
import { fixture, git } from '../helpers/public-ci-fixture.mjs';
test('any two commits: a capture and report like a pull request\'s, with no pull request, GitHub token or GitHub request', async t => {
const f = await fixture(t, 'expo-router');
t.mock.method(globalThis, 'fetch', async input => assert.fail(`Unmocked network request: ${input}`));
const comparePath = join(f.root, 'compare.json');
await writeFile(comparePath, JSON.stringify({ origin: 'compare', repositoryId: '123', repository: 'acme/example',
base: { ref: 'v1.0.0', sha: f.baseSha }, head: { ref: 'v1.1.0', sha: f.headSha } }));
const output = join(f.root, 'compare');
const result = await runCompareCi({ baseProject: f.baseProject, headProject: f.headProject, comparePath, output, config: f.config,
environment: { ...f.environment, GITHUB_TOKEN: '' }, runner: f.runner, now: f.now, sleep: f.sleep });
assert.deepEqual(result.review.pullRequest, { origin: 'compare', repositoryId: '123', repository: 'acme/example', title: 'v1.1.0 vs v1.0.0',
url: `https://github.com/acme/example/compare/${f.baseSha}..${f.headSha}`,
base: { ref: 'v1.0.0', sha: f.baseSha }, head: { ref: 'v1.1.0', sha: f.headSha } });
for (const status of ['added', 'removed', 'modified']) assert.ok(result.review.surfaces.some(row => row.status === status), `a ${status} screen`);
assert.equal(f.comments.length, 0, 'no pull request comment');
assert.equal((await readCaptureBundle(join(output, 'head-export'))).gitCommit, f.headSha);
assert.ok(f.requests.filter(request => request.args[0] === 'simulator:start').every(request => !request.args.join(' ').includes('pr-')),
'no build or session is named after a pull request');
const packaged = await exportCiReport({ inputPath: result.inputPath, outputPath: join(f.root, 'artifact') });
const report = JSON.parse(await readFile(join(packaged.outputPath, 'review.json'), 'utf8'));
assert.equal(report.review.pullRequest.origin, 'compare');
assert.ok(packaged.imageCount > 0);
// ci:publish links a comparison from the run summary, with the Open and zip links a PR comment would carry.
const runSummary = join(f.root, 'run-summary.md');
await publishCiReportComment({ inputPath: result.inputPath, artifactUrl: 'https://github.com/acme/example/actions/runs/1234/artifacts/900',
environment: { ...f.environment, GITHUB_TOKEN: '', GITHUB_STEP_SUMMARY: runSummary }, transport: async input => assert.fail(`no GitHub request: ${input}`) });
const line = await readFile(runSummary, 'utf8');
assert.match(line, /^- iOS report of `v1\.1\.0` vs `v1\.0\.0`: \[Open\]\(https:\/\/explore-preview\.expo\.app\/\?repo=acme%2Fexample&run=1234&attempt=1&artifact=900\) · \[zip\]\(https:\/\/github\.com\/acme\/example\/actions\/runs\/1234\/artifacts\/900\) · \d+ changes?\n$/);
assert.equal(f.comments.length, 0);
const summary = renderCompareSummary(result.review.pullRequest, 'https://example.expo.app/p/token', null, [await readCiReportInput(result.inputPath)]);
assert.match(summary, /^### Explore: `v1\.1\.0` vs `v1\.0\.0`$/m);
// Refs are code spans: one with ] ( ) would otherwise break the line's links. A caller's own title is one span.
const odd = { ...result.review.pullRequest, base: { ...result.review.pullRequest.base, ref: 'x](evil)' }, title: 'v1.1.0 vs x](evil)' };
assert.match(renderCompareSummary(odd, 'https://example.expo.app/p/token', null, []), /^### Explore: `v1\.1\.0` vs `x\]\(evil\)`$/m);
assert.match(renderCompareSummary({ ...odd, title: 'Nightly `build`' }, 'https://example.expo.app/p/token', null, []), /^### Explore: `Nightly 'build'`$/m);
// capture:review's preview output starts the deploy job only when the reviewed config hosts the report.
const outputs = join(f.root, 'outputs');
await writeCaptureOutputs(result.inputPath, { GITHUB_OUTPUT: outputs });
const hosted = join(f.root, 'hosted-input.json');
await writeFile(hosted, JSON.stringify({ ...JSON.parse(await readFile(result.inputPath, 'utf8')), preview: { hosting: 'eas', expiresAfterDays: null } }));
await writeCaptureOutputs(hosted, { GITHUB_OUTPUT: outputs });
assert.equal(await readFile(outputs, 'utf8'), 'preview=\npreview=eas\n');
assert.match(summary, /\[Open the report\]\(https:\/\/example\.expo\.app\/p\/token\)/);
assert.match(summary, new RegExp(`\\(https://github\\.com/acme/example/compare/${f.baseSha}\\.\\.${f.headSha}\\)`));
assert.match(summary, /^- iOS.*: \d+ changes?$/m);
assert.equal(git(f.baseProject, 'status', '--porcelain'), '');
assert.equal(git(f.headProject, 'status', '--porcelain'), '');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length,
f.requests.filter(request => request.args[0] === 'simulator:stop').length);
});
test('a comparison needs the run identity and checkouts of exactly its two commits', async t => {
const f = await fixture(t, 'expo-router', { docsOnly: true });
const comparePath = join(f.root, 'compare.json');
await writeFile(comparePath, JSON.stringify({ origin: 'compare', repositoryId: '123', repository: 'acme/example',
base: { ref: 'main', sha: f.headSha }, head: { ref: 'v2', sha: f.baseSha } }));
const options = { baseProject: f.baseProject, headProject: f.headProject, comparePath, config: f.config, runner: f.runner, now: f.now, sleep: f.sleep };
await assert.rejects(runCompareCi({ ...options, output: join(f.root, 'no-run'), environment: { ...f.environment, GITHUB_RUN_ID: '' } }),
error => error.code === 'CI_RUN_IDENTITY_MISSING');
await assert.rejects(runCompareCi({ ...options, output: join(f.root, 'swapped'), environment: f.environment }),
error => error.code === 'SOURCE_CHECKOUT_MISMATCH', 'the base checkout must be the base commit');
});
+15 -6
View File
@@ -7,7 +7,7 @@ import test from "node:test";
import { stringify } from "yaml";
import { formatCaptureCheck, formatDoctorReport, runCaptureCheck, runDoctor, summarizeCaptureCheck } from "../../dist/ci/doctor.js";
import { readRouteEntry, readSearchParameters } from "../../dist/ci/route-entry.js";
import { installCiFiles, renderWorkflow, stampWorkflow, workflowIssues, workflowTemplateDrift, workflowUnmodified, workflowVersion } from "../../dist/ci/workflow-install.js";
import { WORKFLOW_FILES, installCiFiles, renderWorkflow, stampWorkflow, workflowIssues, workflowTemplateDrift, workflowUnmodified, workflowVersion } from "../../dist/ci/workflow-install.js";
import { unreproducibleEasVariables } from "../../dist/capture/eas-build.js";
import { DRAFT_INSTRUCTIONS_MARKER } from "../../dist/config/setup.js";
import { CiError } from "../../dist/shared/ci-errors.js";
@@ -62,7 +62,7 @@ async function app(t, config = baseConfig, extra = {}) {
}
async function workflows(root, options = {}) {
for (const name of ["explore-review.yml", "explore-baseline.yml"]) {
for (const name of WORKFLOW_FILES) {
const text = renderWorkflow(await readFile(resolve("templates", name), "utf8"),
{ projectDir: ".", installDir: ".", manager: "npm", secretNames: [], ...options });
await write(root, { [`.github/workflows/${name}`]: text });
@@ -275,7 +275,7 @@ test("workflows render for the app's package manager, monorepo layout, and app-t
});
test("bun workflows set up bun before the frozen-lockfile install", async () => {
for (const name of ["explore-review.yml", "explore-baseline.yml"]) {
for (const name of WORKFLOW_FILES) {
const template = await readFile(resolve("templates", name), "utf8");
const layout = { projectDir: ".", installDir: ".", manager: "bun", secretNames: [] };
const rendered = renderWorkflow(template, layout);
@@ -293,8 +293,8 @@ test("CI install keeps an existing workflow, adding only missing secret lines",
await workflows(root);
const result = await installCiFiles(root, ["EXAMPLE_LOGIN"]);
assert.deepEqual(result.kept, []);
assert.deepEqual(result.written, [".github/workflows/explore-review.yml (secret lines)", ".github/workflows/explore-baseline.yml (secret lines)"]);
for (const name of ["explore-review.yml", "explore-baseline.yml"]) {
assert.deepEqual(result.written, WORKFLOW_FILES.map(name => `.github/workflows/${name} (secret lines)`));
for (const name of WORKFLOW_FILES) {
const text = await readFile(join(root, ".github/workflows", name), "utf8");
assert.equal(text.match(/EXAMPLE_LOGIN: \$\{\{ secrets\.EXAMPLE_LOGIN \}\}/g).length, 1);
}
@@ -456,6 +456,15 @@ test("the CLI shows why a capture check did not start, with its next action", as
assert.match(result.stdout, /→ .*git worktree add --detach/);
});
test("a missing compare workflow is a warning: pull request reviews do not need it", async (t) => {
const root = await app(t);
await workflows(root);
await rm(join(root, ".github/workflows/explore-compare.yml"));
const report = await runDoctor(offline(root));
assert.deepEqual(check(report, "workflow-explore-compare.yml").map(item => [item.status, item.code]), [["warn", "WORKFLOW_MISSING"]]);
assert.equal(check(report, "workflow-explore-review.yml")[0].status, "pass");
});
test("workflows count as on the default branch only when its copy matches this checkout", async (t) => {
const root = await app(t);
await workflows(root);
@@ -469,7 +478,7 @@ test("workflows count as on the default branch only when its copy matches this c
}
return { status: 1, stdout: "", stderr: "" };
};
const same = { "explore-review.yml": await local("explore-review.yml"), "explore-baseline.yml": await local("explore-baseline.yml") };
const same = Object.fromEntries(await Promise.all(WORKFLOW_FILES.map(async name => [name, await local(name)])));
assert.equal(check(await runDoctor({ project: root, online: false, run: github(same) }), "default-branch")[0].status, "pass");
const older = await runDoctor({ project: root, online: false, run: github({ ...same, "explore-review.yml": "name: an older review workflow\n" }) });
assert.equal(check(older, "default-branch")[0].code, "WORKFLOW_NOT_ON_DEFAULT_BRANCH");
+18 -1
View File
@@ -6,13 +6,14 @@ const { claudeDeepLink, codexDeepLink, handoffPageUrl, handoffPrompt } = await t
const TOKEN = "exwitrhlayedwcxt7ogiwauyiugp4vpk";
test("only a hosted preview has a link an agent can fetch", () => {
test("a hosted preview and a local review's Viewer have a link an agent can fetch; other pages do not", () => {
assert.equal(
handoffPageUrl(new URL(`https://app-explore--abc.expo.app/p/${TOKEN}?platform=android&screen=x#/map`)),
`https://app-explore--abc.expo.app/p/${TOKEN}?platform=android`,
);
assert.equal(handoffPageUrl(new URL(`https://app-explore--abc.expo.app/p/${TOKEN}/`)), `https://app-explore--abc.expo.app/p/${TOKEN}`);
assert.equal(handoffPageUrl(new URL("http://127.0.0.1:4319/#/map")), undefined);
assert.equal(handoffPageUrl(new URL(`http://127.0.0.1:4319/p/${TOKEN}?platform=ios`)), `http://127.0.0.1:4319/p/${TOKEN}?platform=ios`, "a local review's Viewer serves the agent API too");
assert.equal(handoffPageUrl(new URL("https://explore.expo.app/r?repo=a/b&run=1&attempt=1")), undefined);
});
@@ -46,3 +47,19 @@ test("deep links carry the encoded prompt", () => {
assert.equal(claudeDeepLink("a & b\nc"), "claude-cli://open?q=a%20%26%20b%0Ac");
assert.equal(codexDeepLink("a & b\nc"), "codex://new?prompt=a%20%26%20b%0Ac");
});
test("a comparison of two commits is reviewed by its refs", () => {
const sha = c => c.repeat(40);
const prompt = handoffPrompt({ ...input, pullRequest: { origin: "compare", title: "v1.4.0 vs v1.3.0",
url: `https://github.com/brentvatne/euxy/compare/${sha("a")}..${sha("b")}`, base: { ref: "v1.3.0", sha: sha("a") }, head: { ref: "v1.4.0", sha: sha("b") } } });
assert.match(prompt, /^Review the visual changes from v1\.3\.0 to v1\.4\.0 of brentvatne\/euxy\.\n/);
});
test("a local review is reviewed by its refs, and its prompt says the link is local and lives while capture:review runs", () => {
const prompt = handoffPrompt({ ...input, pageUrl: `http://127.0.0.1:4319/p/${TOKEN}`,
pullRequest: { origin: "local", title: "HEAD vs main", base: { ref: "main", sha: "a".repeat(40) }, head: { ref: "HEAD", sha: "b".repeat(40) } } });
assert.match(prompt, /^Review the visual changes from main to HEAD\.\n/);
assert.ok(prompt.includes("Fetch the link first (from this machine, with curl if your fetch tool refuses local addresses)."));
assert.match(prompt, /stops working when it exits\.$/);
assert.ok(!handoffPrompt(input).includes("this machine"), "a hosted link's prompt is unchanged");
});
+255
View File
@@ -0,0 +1,255 @@
import assert from 'node:assert/strict';
import http from 'node:http';
import test from 'node:test';
import { spawnSync } from 'node:child_process';
import { lstat, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { appEnvironment, captureCacheDirectory, defaultBase, installDependencies, keepCapture, localInstallCommand, reportRef, runLocalReview, snapshotWorkingTree } from '../../dist/ci/local-review.js';
import { mkdir, readdir } from 'node:fs/promises';
import { startLocalReportServer } from '../../dist/report/local-report-server.js';
import { fixture, git } from '../helpers/public-ci-fixture.mjs';
import { writeCaptureObserverPackages } from '../helpers/capture-observer-fixture.mjs';
async function scratch(t, prefix) {
const directory = await realpath(await mkdtemp(join(tmpdir(), prefix)));
t.after(() => rm(directory, { recursive: true, force: true }));
return directory;
}
async function repository(t) {
const root = await scratch(t, 'explore-local-repo-');
for (const args of [['init', '-q', '-b', 'main'], ['config', 'user.email', '[email protected]'], ['config', 'user.name', 'T']]) git(root, ...args);
await writeFile(join(root, 'tracked.txt'), 'one\n'); await writeFile(join(root, '.gitignore'), 'ignored.txt\n');
git(root, 'add', '-A'); git(root, 'commit', '-q', '-m', 'one');
return root;
}
/** A GET over node:http, which the review tests' fetch mock does not intercept. */
function httpGet(url, accept) {
return new Promise((done, fail) => {
http.get(url, { headers: { accept } }, response => {
let body = '';
response.setEncoding('utf8').on('data', chunk => { body += chunk; }).on('end', () =>
done({ status: response.statusCode, type: response.headers['content-type'] ?? '', headers: response.headers, body }));
}).on('error', fail);
});
}
test('the working tree becomes a commit on HEAD without touching the index, files or refs; untracked files only on request', async t => {
const root = await repository(t);
const work = await scratch(t, 'explore-local-work-');
assert.equal(await snapshotWorkingTree(root, { work }), undefined, 'nothing changed');
await writeFile(join(root, 'tracked.txt'), 'two\n');
await writeFile(join(root, 'staged.txt'), 'staged\n'); git(root, 'add', 'staged.txt');
await writeFile(join(root, 'untracked.txt'), 'new\n'); await writeFile(join(root, 'ignored.txt'), 'secret\n');
const before = { status: git(root, 'status', '--porcelain'), index: git(root, 'diff', '--cached', '--name-only'), refs: git(root, 'for-each-ref'), head: git(root, 'rev-parse', 'HEAD') };
const tracked = await snapshotWorkingTree(root, { work });
assert.deepEqual(tracked.changed.sort(), ['staged.txt', 'tracked.txt'], 'tracked changes, staged or not; no untracked file');
assert.equal(git(root, 'show', `${tracked.sha}:tracked.txt`), 'two');
assert.equal(git(root, 'rev-parse', `${tracked.sha}^`), before.head, 'on top of HEAD');
const withUntracked = await snapshotWorkingTree(root, { work, untracked: true });
assert.deepEqual(withUntracked.changed.sort(), ['staged.txt', 'tracked.txt', 'untracked.txt']);
assert.deepEqual(withUntracked.untracked, ['untracked.txt'], 'named, since they would be uploaded with the build');
assert.equal(spawnSync('git', ['-C', root, 'cat-file', '-e', `${withUntracked.sha}:ignored.txt`]).status !== 0, true, 'ignored files never go in');
assert.deepEqual({ status: git(root, 'status', '--porcelain'), index: git(root, 'diff', '--cached', '--name-only'), refs: git(root, 'for-each-ref'), head: git(root, 'rev-parse', 'HEAD') }, before);
});
test('with no base, a branch is compared with where it left the default branch', async t => {
const root = await repository(t);
const fork = git(root, 'rev-parse', 'HEAD');
git(root, 'checkout', '-q', '-b', 'feature'); await writeFile(join(root, 'tracked.txt'), 'feature\n'); git(root, 'commit', '-q', '-am', 'feature');
const head = git(root, 'rev-parse', 'HEAD');
assert.deepEqual(defaultBase(root, head), { ref: 'main', sha: fork });
git(root, 'checkout', '-q', 'main'); await writeFile(join(root, 'other.txt'), 'later\n'); git(root, 'add', '-A'); git(root, 'commit', '-q', '-m', 'later on main');
assert.deepEqual(defaultBase(root, head), { ref: 'main (merge base)', sha: fork }, 'main moved on; the merge base keeps its changes out of the review');
});
test('installs run without any credential-named variable, keeping network and cache settings, and without changing the Node install', () => {
const environment = appEnvironment({ PATH: '/bin', HOME: '/h', EXPO_TOKEN: 'e', GITHUB_TOKEN: 'g', ANTHROPIC_API_KEY: 'a', OPENAI_API_KEY: 'o',
NPM_TOKEN: 'n', CLAUDE_CODE_OAUTH_TOKEN: 'c', NODE_AUTH_TOKEN: 'x', AWS_SECRET_ACCESS_KEY: 's', HTTPS_PROXY: 'http://proxy:8080', NO_PROXY: 'localhost',
NODE_EXTRA_CA_CERTS: '/ca.pem', npm_config_cache: '/cache', SSH_AUTH_SOCK: '/agent' });
// A reviewed commit's .npmrc can expand any of these into a request to a registry it picks, even with --ignore-scripts.
assert.deepEqual(environment, { PATH: '/bin', HOME: '/h', HTTPS_PROXY: 'http://proxy:8080', NO_PROXY: 'localhost',
NODE_EXTRA_CA_CERTS: '/ca.pem', npm_config_cache: '/cache', SSH_AUTH_SOCK: '/agent' });
assert.equal(localInstallCommand('pnpm', '.'), 'pnpm install --frozen-lockfile --ignore-scripts --dir "."');
assert.equal(localInstallCommand('npm', 'apps/mobile'), 'npm ci --ignore-scripts --prefix "apps/mobile"');
assert.equal(captureCacheDirectory({ HOME: '/h' }, 'ios', 'a'.repeat(40)), `/h/.cache/expo-explore/captures/ios/${'a'.repeat(40)}`);
assert.equal(captureCacheDirectory({ XDG_CACHE_HOME: '/x', EXPLORE_CACHE_DIR: '/c' }, 'android', 'b'), '/c/captures/android/b');
});
test('the dependency install starts at the app directory, so an app with its own lockfile in a monorepo installs', async t => {
const root = await repository(t);
await mkdir(join(root, 'apps/mobile'), { recursive: true });
await writeFile(join(root, 'apps/mobile/package.json'), JSON.stringify({ name: 'mobile', version: '1.0.0' }));
await writeFile(join(root, 'apps/mobile/package-lock.json'), JSON.stringify({ name: 'mobile', version: '1.0.0', lockfileVersion: 3, requires: true, packages: { '': { name: 'mobile', version: '1.0.0' } } }));
git(root, 'add', '-A'); git(root, 'commit', '-q', '-m', 'app');
const log = join(await scratch(t, 'explore-local-log-'), 'install.log');
await installDependencies(join(root, 'apps/mobile'), log, { ...process.env, NPM_TOKEN: 'never-passed' });
assert.match(await readFile(log, 'utf8'), /^\$ npm ci --ignore-scripts --prefix "apps\/mobile"/);
// Starting from the repository root, as before, finds no lockfile at all.
await assert.rejects(installDependencies(root, log, process.env), error => error.code === 'LOCAL_REVIEW_LOCKFILE_MISSING');
});
test('the default base is the newer fork point of the local and origin default branches, never a tag of that name', async t => {
const upstream = await repository(t);
const clone = await scratch(t, 'explore-local-clone-');
assert.equal(spawnSync('git', ['clone', '-q', upstream, clone]).status, 0);
for (const args of [['config', 'user.email', '[email protected]'], ['config', 'user.name', 'T']]) git(clone, ...args);
const old = git(clone, 'rev-parse', 'HEAD');
git(clone, 'tag', 'main', old);
// Upstream moves on and is fetched; local main stays behind. The branch starts from origin/main.
await writeFile(join(upstream, 'upstream.txt'), 'u\n'); git(upstream, 'add', '-A'); git(upstream, 'commit', '-q', '-m', 'upstream');
git(clone, 'fetch', '-q', 'origin');
const fetched = git(clone, 'rev-parse', 'origin/main');
git(clone, 'checkout', '-q', '-b', 'feature', 'origin/main'); await writeFile(join(clone, 'tracked.txt'), 'feature\n'); git(clone, 'commit', '-q', '-am', 'feature');
const head = git(clone, 'rev-parse', 'HEAD');
assert.deepEqual(defaultBase(clone, head), { ref: 'main', sha: fetched }, 'a stale local main and the tag named main are both passed over');
// The other way round: local main is ahead of an unfetched origin/main and the branch starts from it.
git(clone, 'checkout', '-q', 'main'); git(clone, 'merge', '-q', '--ff-only', 'origin/main');
await writeFile(join(clone, 'local.txt'), 'l\n'); git(clone, 'add', '-A'); git(clone, 'commit', '-q', '-m', 'local');
const local = git(clone, 'rev-parse', 'HEAD');
git(clone, 'checkout', '-q', '-b', 'feature2'); await writeFile(join(clone, 'tracked.txt'), 'two\n'); git(clone, 'commit', '-q', '-am', 'feature2');
assert.deepEqual(defaultBase(clone, git(clone, 'rev-parse', 'HEAD')), { ref: 'main', sha: local });
// On main itself, its unpushed commits are reviewed against origin/main rather than against themselves.
git(clone, 'checkout', '-q', 'main');
assert.deepEqual(defaultBase(clone, local), { ref: 'main', sha: fetched });
});
test('a ref the report cannot name as typed is named by its branch or short SHA, before anything is captured', async t => {
const upstream = await repository(t);
const clone = await scratch(t, 'explore-local-refs-');
assert.equal(spawnSync('git', ['clone', '-q', upstream, clone]).status, 0);
const sha = git(clone, 'rev-parse', 'HEAD');
assert.equal(reportRef(clone, '@{u}', sha), 'origin/main');
assert.equal(reportRef(clone, 'HEAD@{0}', sha), sha.slice(0, 8));
for (const ref of ['main', 'HEAD~0', 'v1.2.0']) assert.equal(reportRef(clone, ref, sha), ref);
});
test('a cached capture is replaced by another recipe, kept against a smaller one of the same recipe, and never made from unvalidated evidence', async t => {
const root = await scratch(t, 'explore-local-keep-');
const exportOf = async (name, recipe, images) => {
const directory = join(root, name); await mkdir(directory);
await writeFile(join(directory, 'bundle.json'), JSON.stringify({ images: Object.fromEntries(Array.from({ length: images }, (_, index) => [`s${index}`, {}])) }));
if (recipe) await writeFile(join(directory, 'cache-metadata.json'), JSON.stringify({ recipe }));
return directory;
};
const target = join(root, 'cache/ios/sha');
assert.equal(await keepCapture(await exportOf('unvalidated', undefined, 5), target), false);
assert.equal(await keepCapture(await exportOf('full', 'r1', 5), target), true);
assert.equal(await keepCapture(await exportOf('partial', 'r1', 2), target), false, 'a partial capture never shrinks a fuller one');
assert.equal(await keepCapture(await exportOf('upgraded', 'r2', 2), target), true, 'a stale recipe is replaced even by fewer screens');
assert.equal(JSON.parse(await readFile(join(target, 'cache-metadata.json'), 'utf8')).recipe, 'r2');
});
test('the local Viewer serves the built Viewer and each report the way a hosted report does, and nothing else', async t => {
const viewerRoot = await scratch(t, 'explore-local-viewer-');
await writeFile(join(viewerRoot, 'index.html'), '<!doctype html><title>Viewer</title>');
const reports = [{ platform: 'ios', zip: new Uint8Array([1, 2]), changes: 3, device: 'iPhone 17' }, { platform: 'android', zip: new Uint8Array([4]) }];
const server = await startLocalReportServer({ reports, viewerRoot, token: 'abcdefghijklmnopqrstuvwxyz234567' });
t.after(() => server.close());
assert.match(server.url, /^http:\/\/127\.0\.0\.1:\d+\/p\/abcdefghijklmnopqrstuvwxyz234567$/);
const get = path => fetch(new URL(path, server.url));
assert.match(await (await fetch(server.url, { headers: { accept: 'text/html' } })).text(), /<title>Viewer/);
assert.equal((await get(server.url)).status, 404, 'an agent fetch of a report the agent API cannot read is a 404, not the Viewer shell');
assert.deepEqual(new Uint8Array(await (await get(`${server.url}/report.zip?platform=android`)).arrayBuffer()), new Uint8Array([4]));
assert.deepEqual(new Uint8Array(await (await get(`${server.url}/report.zip`)).arrayBuffer()), new Uint8Array([1, 2]));
assert.deepEqual(await (await get(`${server.url}/reports.json`)).json(), [{ platform: 'ios', changes: 3, device: 'iPhone 17' }, { platform: 'android' }]);
for (const path of ['/', '/p/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', '/p/abcdefghijklmnopqrstuvwxyz234567/x', '/assets/../index.html', '/assets/missing.js']) {
assert.equal((await get(path)).status, 404, path);
}
});
test('a local review captures two commits of the repository in its own worktrees and packages a report', async t => {
const f = await fixture(t, 'expo-router');
t.mock.method(globalThis, 'fetch', async input => assert.fail(`Unmocked network request: ${input}`));
const installs = [];
const cache = await scratch(t, 'explore-local-cache-');
const environment = { ...f.environment, EXPLORE_CACHE_DIR: cache, GITHUB_RUN_ID: '', GITHUB_RUN_ATTEMPT: '', GITHUB_TOKEN: '' };
const result = await runLocalReview({ project: f.headProject, base: f.baseSha, head: f.headSha, environment,
install: async (checkout, side) => { installs.push(side); await writeCaptureObserverPackages(checkout, { provider: 'expo-router' }); },
runner: f.runner, now: f.now, sleep: f.sleep });
t.after(() => rm(result.work, { recursive: true, force: true }));
assert.deepEqual(installs, ['head', 'base'], 'installed once, only once there is capture work');
assert.match(result.runId, /^local-\d{14}-[0-9a-f]{6}$/);
assert.deepEqual([result.base.sha, result.head.sha], [f.baseSha, f.headSha]);
const [report] = result.reports;
assert.equal(report.platform, 'ios');
const review = JSON.parse(await readFile(join(report.directory, 'review.json'), 'utf8')).review;
assert.equal(review.pullRequest.origin, 'local');
assert.equal(review.runId, result.runId);
for (const status of ['added', 'removed', 'modified']) assert.ok(review.surfaces.some(row => row.status === status), status);
assert.ok((await lstat(report.zip)).size > 0);
// Only the reports are kept; the captures, maps and checkouts are gone.
assert.deepEqual((await readdir(result.work)).sort(), ['ios']);
assert.deepEqual((await readdir(join(result.work, 'ios'))).sort(), ['report', 'report.zip']);
// The worktrees are gone and the repository's own checkout is untouched.
assert.equal(git(f.headProject, 'worktree', 'list').split('\n').length, 2, 'only the fixture\'s own two checkouts remain');
assert.equal(git(f.headProject, 'status', '--porcelain'), '');
// Both commits' captures are kept for the next review of either.
for (const sha of [f.baseSha, f.headSha]) assert.ok((await lstat(join(captureCacheDirectory(environment, 'ios', sha), 'bundle.json'))).isFile(), sha);
// An agent on this machine reads the report the way it reads a hosted one: the Markdown index, then the JSON API.
const viewerRoot = await scratch(t, 'explore-local-viewer-');
await writeFile(join(viewerRoot, 'index.html'), '<!doctype html><title>Viewer</title>');
const server = await startLocalReportServer({ reports: [{ platform: 'ios', zip: new Uint8Array(await readFile(report.zip)) }], viewerRoot });
t.after(() => server.close());
const index = await httpGet(server.url, '*/*');
assert.equal(index.status, 200);
assert.match(index.type, /^text\/markdown/);
assert.match(index.headers.link, new RegExp(`<${server.url}/api/v1>; rel="alternate"`));
assert.ok(index.body.includes(`${server.url}/api/v1`), 'the index links the local API, not a hosted one');
assert.match(index.body.split('\n')[0], new RegExp(`^# Expo Explore report: .+ ${f.headSha} vs ${f.baseSha} \\(ios\\)$`), 'a local review is named by its refs, not as a pull request');
assert.equal((await httpGet(`${server.url}/llms.txt`, '*/*')).body, index.body);
const api = JSON.parse((await httpGet(`${server.url}/api/v1`, 'application/json')).body);
assert.equal(api.kind, 'pr-review');
const screens = await httpGet(`${server.url}/api/v1/screens?status=modified`, 'application/json');
assert.equal(screens.status, 200);
assert.ok(JSON.parse(screens.body).items.length > 0);
assert.match((await httpGet(server.url, 'text/html')).body, /<title>Viewer/, 'a browser still gets the Viewer');
assert.equal((await httpGet(`${server.url}/api/v1?platform=android`, 'application/json')).status, 404);
});
test('Ctrl+C during a deterministic capture stops it before the next route and still stops its session', async t => {
const f = await fixture(t, 'expo-router');
t.mock.method(globalThis, 'fetch', async input => assert.fail(`Unmocked network request: ${input}`));
const environment = { ...f.environment, EXPLORE_CACHE_DIR: await scratch(t, 'explore-local-cache-'), GITHUB_RUN_ID: '', GITHUB_RUN_ATTEMPT: '', GITHUB_TOKEN: '' };
const ctrlC = new AbortController();
const calls = [];
const runner = request => {
const name = request.command.split('/').at(-1);
calls.push({ name, command: request.args[0], afterCtrlC: ctrlC.signal.aborted });
// The first route link is opened: the person presses Ctrl+C while it loads.
if (name === 'agent-device' && request.args[0] === 'open' && /sample:\/\//.test(request.args[2] ?? '') && !ctrlC.signal.aborted) ctrlC.abort();
return f.runner(request);
};
let kept;
await assert.rejects(runLocalReview({ project: f.headProject, base: f.baseSha, head: f.headSha, environment, interrupt: ctrlC.signal,
progress: message => { kept ??= /^kept this review's files for inspection: (.+)$/.exec(message)?.[1]; },
install: async checkout => { await writeCaptureObserverPackages(checkout, { provider: 'expo-router' }); }, runner, now: f.now, sleep: f.sleep }),
error => error.code === 'LOCAL_REVIEW_INTERRUPTED');
if (kept) t.after(() => rm(kept, { recursive: true, force: true }));
assert.ok(calls.some(call => call.afterCtrlC === false && call.command === 'simulator:start'), 'the capture had started a session');
const after = calls.filter(call => call.afterCtrlC);
assert.ok(after.some(call => call.command === 'simulator:stop'), 'its session is stopped');
assert.equal(after.filter(call => call.command === 'simulator:start').length, 0, 'no other session starts');
assert.ok(after.filter(call => call.name === 'agent-device' && call.command === 'open').length <= 1, 'no further route is opened');
});
test('Ctrl+C stops the review, and the checkouts are removed while its files are kept', async t => {
const f = await fixture(t, 'expo-router');
t.mock.method(globalThis, 'fetch', async input => assert.fail(`Unmocked network request: ${input}`));
const environment = { ...f.environment, EXPLORE_CACHE_DIR: await scratch(t, 'explore-local-cache-'), GITHUB_RUN_ID: '', GITHUB_RUN_ATTEMPT: '', GITHUB_TOKEN: '' };
const messages = []; const ctrlC = new AbortController();
const listeners = process.listenerCount('SIGINT');
await assert.rejects(runLocalReview({ project: f.headProject, base: f.baseSha, head: f.headSha, environment, progress: message => messages.push(message),
interrupt: ctrlC.signal,
install: async checkout => { await writeCaptureObserverPackages(checkout, { provider: 'expo-router' }); ctrlC.abort(); },
runner: f.runner, now: f.now, sleep: f.sleep }), error => error.code === 'LOCAL_REVIEW_INTERRUPTED');
assert.equal(git(f.headProject, 'worktree', 'list').split('\n').length, 2, 'the review\'s checkouts are removed');
const kept = messages.map(message => /^kept this review's files for inspection: (.+)$/.exec(message)?.[1]).find(Boolean);
assert.ok(kept, 'a failed run says where its files are');
t.after(() => rm(kept, { recursive: true, force: true }));
assert.equal(process.listenerCount('SIGINT'), listeners, 'its handlers are gone, so a later Ctrl+C behaves normally');
});
+163 -5
View File
@@ -1,13 +1,14 @@
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { mkdtemp, mkdir, rename, rm, writeFile } from "node:fs/promises";
import { cp, mkdtemp, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { prepareCaptureReview } from "../../dist/review/capture-review.js";
import { createSourceCapturePlan } from "../../dist/source/capture-plan.js";
import { writeCiReportInput, exportCiReport } from "../../dist/report/artifact.js";
import { collectPlatformReports, deployExplorationReport, deployFixturePreview, deployPreview, previewProjectSlug, sealReport, whoamiAccounts, zipReportDirectory } from "../../dist/report/preview-deploy.js";
import { collectPlatformReports, deployExplorationReport, deployFixturePreview, deployLocalReports, deployPreview, previewProjectSlug, readReportZip, sealReport, whoamiAccounts, zipReportDirectory } from "../../dist/report/preview-deploy.js";
import { spawnSync } from "node:child_process";
import { createDecipheriv } from "node:crypto";
import { ZipReader, Uint8ArrayReader, TextWriter, configure } from "@zip.js/zip.js";
import { viewerLinks } from "../../dist/report/viewer-links.js";
@@ -20,7 +21,7 @@ const pr = { repositoryId: "123", repository: "expo/explore-playground", number:
const artifactUrl = "https://github.com/expo/explore-playground/actions/runs/10/artifacts/20";
const environment = { GITHUB_TOKEN: "test-token", GITHUB_RUN_ID: "10", GITHUB_RUN_ATTEMPT: "1", GITHUB_REPOSITORY: pr.repository };
async function fixture(t, { verified = true, preview = { hosting: "eas", expiresAfterDays: 7 } } = {}) {
async function fixture(t, { verified = true, preview = { hosting: "eas", expiresAfterDays: 7 }, presentation = pr } = {}) {
const root = await mkdtemp(join(tmpdir(), "explore-artifact-ci-"));
t.after(() => rm(root, { recursive: true, force: true }));
const files = new Map([["app/index.tsx", "export default function Home() { return null; }"]]);
@@ -37,12 +38,12 @@ async function fixture(t, { verified = true, preview = { hosting: "eas", expires
buildId: "build", capturedAt: "2026-09-15T00:00:00Z" } },
outcomes: { [id]: { status: "captured", attempts: 1, landing: verified ? "verified" : "unverified" } } }));
}
const prepared = await prepareCaptureReview({ plan, pullRequest: pr, baseDirectory: join(root, "base"),
const prepared = await prepareCaptureReview({ plan, pullRequest: presentation, baseDirectory: join(root, "base"),
headDirectory: join(root, "head"), runId: "10", runAttempt: "1", assertCurrentHead: async () => {},
...(verified ? { assessments: { [id]: { review: { status: "unchanged", description: "No visible change" } } } } : {}) });
const inputPath = join(root, "report-input.json");
await writeCiReportInput({ inputPath, publicReview: prepared.review, assets: prepared.assets,
commentState: { phase: "capturing", pullRequest: pr, mode: "all", executionMode: "deterministic", configPath: ".expo-explore/config.yaml",
commentState: { phase: "capturing", pullRequest: presentation, mode: "all", executionMode: "deterministic", configPath: ".expo-explore/config.yaml",
startedAt: 1, updatedAt: 2, artifactOnly: true,
links: viewerLinks({ repository: pr.repository, headSha: pr.head.sha, runId: "10", runAttempt: "1", configPath: ".expo-explore/config.yaml" }) },
...(preview ? { preview } : {}) });
@@ -271,6 +272,23 @@ test("ci:deploy rejects a deployment that serves the report without the token",
assert.doesNotMatch(JSON.parse(posted[0].options.body).body, /acme-explore--/);
});
test("a deployment that leaks past the token is named by the path's shape, never the token", async t => {
const { inputPath, reportPath, exportPath } = await exportFixture(t);
const eas = easFixture();
const leaky = async (input, options) => {
const url = new URL(input);
if (/^\/p\/[a-z2-7]{32}\/viewer\/index\.html$/.test(url.pathname)) return new Response("<!doctype html>", { status: 200 });
return eas.transport(input, options);
};
await assert.rejects(deployPreview({ inputPath, reportPath, artifactUrl, exportPath, environment: deployEnvironment, transport: leaky, run: eas.run, verifyTimeoutMs: 1 }), error => {
const token = eas.captured.env.EXPLORE_PREVIEW_TOKEN;
assert.equal(error.code, "PREVIEW_VERIFY_FAILED");
assert.match(error.message, /at \/p\/<token>\/viewer\/index\.html\.$/);
assert.ok(!JSON.stringify({ message: error.message, details: error.details }).includes(token.slice(0, 31)), "neither the token nor its near miss");
return true;
});
});
test("the preview owner comes from config or the token's single account; several accounts need report.preview.owner", async t => {
assert.deepEqual(whoamiAccounts("Devin (robot) (authenticated using EXPO_TOKEN)\nAccounts:\n• brent-org (Role: Developer)\n• acme (Role: Owner)\n"), ["brent-org", "acme"]);
assert.deepEqual(whoamiAccounts("brentvatne\n"), ["brentvatne"]);
@@ -493,3 +511,143 @@ test("ci:deploy writes its own deployments line over the one report jobs carried
assert.match(JSON.parse(patched.options.body).body, /^<!-- expo-explore-ci -->\n<!-- expo-explore-deployments:explore-playground-explore--1lcbdcpwn3 -->\n/);
});
test("a comparison of two commits deploys the same way and links its report from the run summary, not a pull request", async t => {
const comparison = { origin: "compare", repositoryId: "123", repository: pr.repository,
base: { ref: "v1.3.0", sha: pr.base.sha }, head: { ref: "v1.4.0", sha: pr.head.sha } };
const { root, inputPath, reportPath, exportPath } = await exportFixture(t, { presentation: comparison });
const summaryPath = join(root, "summary.md");
const eas = easFixture(); const secrets = [];
const result = await deployPreview({ inputPath, reportPath, artifactUrl, exportPath, environment: { ...deployEnvironment, GITHUB_STEP_SUMMARY: summaryPath },
transport: eas.transport, run: eas.run, now: () => Date.parse("2026-09-11T03:07:00Z"), verifyTimeoutMs: 1, onSecret: secret => secrets.push(secret) });
// The runner masks registered secrets in job summaries as well; a masked token would make the summary link ***.
assert.deepEqual(secrets, [], "a comparison's token is not registered as a mask");
assert.equal(result.linkedFromRunSummary, true, "so the CLI keeps the link out of the log");
assert.deepEqual(eas.calls.map(call => call.args[0]), ["whoami", "init", "deploy"]);
assert.equal(eas.requests.filter(request => request.url.origin === "https://api.github.com").length, 0, "no pull request to read or comment on");
const summary = readFileSyncUtf8(summaryPath);
assert.match(summary, /^### Explore: `v1\.4\.0` vs `v1\.3\.0`$/m);
assert.ok(summary.includes(`[Open the report](${result.previewUrl})`));
assert.ok(summary.includes(`(https://github.com/${pr.repository}/compare/${pr.base.sha}..${pr.head.sha})`));
assert.match(summary, /link expires 2026-09-18/);
});
test("readReportZip reads a review ZIP's platform, run and labels, and rejects anything that is not a report", async t => {
const { reportPath } = await exportFixture(t);
const zip = await zipReportDirectory(reportPath);
const { platform, device: _device, ...summary } = await readReportZip(zip);
assert.ok(["ios", "android"].includes(platform));
assert.deepEqual(summary, { kind: "review", repository: pr.repository, runId: "10", base: pr.base.sha, head: pr.head.sha, changes: 0 });
// GitHub's artifact download lists directories as entries of their own.
const { ZipWriter, Uint8ArrayWriter } = await import("@zip.js/zip.js");
const entries = new ZipReader(new Uint8ArrayReader(zip));
const withDirectory = new ZipWriter(new Uint8ArrayWriter());
await withDirectory.add("assets/", undefined, { directory: true });
for (const entry of await entries.getEntries()) await withDirectory.add(entry.filename, new Uint8ArrayReader(await entry.getData(new Uint8ArrayWriter())));
const extra = new ZipWriter(new Uint8ArrayWriter());
for (const entry of await entries.getEntries()) await extra.add(entry.filename, new Uint8ArrayReader(await entry.getData(new Uint8ArrayWriter())));
await extra.add("notes.txt", new Uint8ArrayReader(new TextEncoder().encode("hi")));
await entries.close();
assert.equal((await readReportZip(await withDirectory.close())).kind, "review");
await assert.rejects(readReportZip(await extra.close()), /review.json \(or exploration.json\) and assets/);
await assert.rejects(readReportZip(new Uint8Array([1, 2, 3])));
// Commits are full SHAs and the names are text: what the CLI hands to git and prints is never anything else.
const original = await readFile(join(reportPath, "review.json"), "utf8");
for (const [field, value] of [["head", { ref: "x", sha: "--output=/tmp/explore-victim" }], ["title", 42]]) {
const report = JSON.parse(original);
report.review.pullRequest[field] = value;
await writeFile(join(reportPath, "review.json"), JSON.stringify(report));
await assert.rejects(readReportZip(await zipReportDirectory(reportPath)), /does not name its repository, title and commits/, field);
}
await writeFile(join(reportPath, "review.json"), original);
// A review renamed to exploration.json is neither.
await rename(join(reportPath, "review.json"), join(reportPath, "exploration.json"));
await assert.rejects(readReportZip(await zipReportDirectory(reportPath)), /not an Explore exploration report/);
await writeFile(join(reportPath, "exploration.json"), JSON.stringify({ kind: "explore.exploration-report",
exploration: { app: { name: "Acme", bundleId: "com.acme", platform: "android" }, device: { model: "Pixel 9", osVersion: "16" } } }));
assert.deepEqual(await readReportZip(await zipReportDirectory(reportPath)), { kind: "exploration", platform: "android", device: "Pixel 9 16" });
});
test("deployLocalReports hosts one review's platforms behind one link, labelled from each ZIP", async t => {
const { reportPath, exportPath } = await exportFixture(t);
const zip = await zipReportDirectory(reportPath);
const eas = easFixture();
const result = await deployLocalReports({ reports: [{ platform: "ios", zip, changes: 3, device: "iPhone 17 26.5" }, { platform: "android", zip }],
project: "acme-explore", expiresAfterDays: null, exportPath, environment: deployEnvironment, transport: eas.transport, run: eas.run, now: () => now, verifyTimeoutMs: 1 });
assert.match(result.previewUrl, /^https:\/\/acme-explore--1lcbdcpwn3\.expo\.app\/p\/[a-z2-7]{32}$/);
assert.equal(result.owner, "brent-org", "the only account of the login holds the project");
assert.equal(result.expiresAt, null);
assert.deepEqual(captureListing(eas.captured.listing), [
{ platform: "ios", path: "ios.zip.enc", changes: 3, device: "iPhone 17 26.5" },
{ platform: "android", path: "android.zip.enc" },
]);
await assert.rejects(deployLocalReports({ reports: [{ platform: "ios", zip }, { platform: "ios", zip }], project: "acme-explore", expiresAfterDays: 7, exportPath,
environment: deployEnvironment, transport: eas.transport, run: eas.run }), error => error.code === "PREVIEW_REPORTS_INVALID");
// One Android report is still listed, so the Worker does not take it for iOS; a label with `#` cannot cut the sealed .env short.
await deployLocalReports({ reports: [{ platform: "android", zip, changes: 1, device: "Pixel #9 <Pro>\n" }], project: "acme-explore", expiresAfterDays: 7, exportPath,
environment: deployEnvironment, transport: eas.transport, run: eas.run, now: () => now, verifyTimeoutMs: 1 });
assert.equal(eas.captured.env.EXPLORE_PREVIEW_REPORT, undefined);
assert.deepEqual(captureListing(eas.captured.listing), [{ platform: "android", path: "android.zip.enc", changes: 1, device: "Pixel 9 Pro" }]);
// eas deploy expands $VARIABLES in that .env, even single-quoted: a label never carries one in, nor a backslash.
await deployLocalReports({ reports: [{ platform: "ios", zip, device: "iPhone ${EXPO_TOKEN} $EXPLORE_PREVIEW_KEY \\$ · light + dark" }], project: "acme-explore",
expiresAfterDays: 7, exportPath, environment: deployEnvironment, transport: eas.transport, run: eas.run, now: () => now, verifyTimeoutMs: 1 });
assert.deepEqual(captureListing(eas.captured.listing), [{ platform: "ios", path: "ios.zip.enc", device: "iPhone EXPO_TOKEN EXPLORE_PREVIEW_KEY · light + dark" }]);
});
test("an explore:binary report names its platform, so an Android exploration is not served as iOS", async t => {
const { reportPath, exportPath } = await exportFixture(t);
await rename(join(reportPath, "review.json"), join(reportPath, "exploration.json"));
const eas = easFixture();
await deployExplorationReport({ reportPath, platform: "android", project: "acme-explore", owner: "brent-org", expiresAfterDays: 7, exportPath,
environment: deployEnvironment, transport: eas.transport, run: eas.run, now: () => now, verifyTimeoutMs: 1 });
assert.deepEqual(captureListing(eas.captured.listing), [{ platform: "android", path: "android.zip.enc" }]);
});
test("readReportZip stops inflating a report file once it passes the size its header declares", async () => {
const { deflateRawSync } = await import("node:zlib");
const name = Buffer.from("review.json");
const data = deflateRawSync(Buffer.alloc(32 * 1024 * 1024, 32));
const header = size => {
const local = Buffer.alloc(30); local.writeUInt32LE(0x04034b50, 0); local.writeUInt16LE(20, 4); local.writeUInt16LE(8, 8);
local.writeUInt32LE(data.length, 18); local.writeUInt32LE(size, 22); local.writeUInt16LE(name.length, 26);
return local;
};
// The directory claims 10 bytes of JSON; the entry inflates to 32 MiB.
const local = Buffer.concat([header(10), name, data]);
const central = Buffer.alloc(46); central.writeUInt32LE(0x02014b50, 0); central.writeUInt16LE(20, 4); central.writeUInt16LE(20, 6); central.writeUInt16LE(8, 10);
central.writeUInt32LE(data.length, 20); central.writeUInt32LE(10, 24); central.writeUInt16LE(name.length, 28); central.writeUInt32LE(0, 42);
const end = Buffer.alloc(22); end.writeUInt32LE(0x06054b50, 0); end.writeUInt16LE(1, 8); end.writeUInt16LE(1, 10);
end.writeUInt32LE(46 + name.length, 12); end.writeUInt32LE(local.length, 16);
const zip = new Uint8Array(Buffer.concat([local, central, name, end]));
const before = process.memoryUsage().arrayBuffers;
await assert.rejects(readReportZip(zip), /review\.json is unreadable or larger than 64 MiB/);
assert.ok(process.memoryUsage().arrayBuffers - before < 16 * 1024 * 1024, "the inflated bytes were never all held");
});
test("report:upload checks its reports before it deploys anything", async t => {
const { root, reportPath } = await exportFixture(t);
const cli = join(import.meta.dirname, "../../dist/cli.js");
const upload = (...args) => {
const result = spawnSync(process.execPath, [cli, "report:upload", ...args], { cwd: root, encoding: "utf8", env: { ...process.env, EXPO_TOKEN: "", EXPLORE_CACHE_DIR: join(root, "cache") } });
return { status: result.status, output: `${result.stdout}${result.stderr}` };
};
const zip = await zipReportDirectory(reportPath);
await writeFile(join(root, "one.zip"), zip); await writeFile(join(root, "two.zip"), zip);
await writeFile(join(root, "notes.txt"), "not a report");
const other = JSON.parse(await readFile(join(reportPath, "review.json"), "utf8"));
other.review.runtime.platform = other.review.runtime.platform === "ios" ? "android" : "ios";
await mkdir(join(root, "other")); await writeFile(join(root, "other/review.json"), JSON.stringify({ ...other, review: { ...other.review, runId: "11" } }));
await cp(join(reportPath, "assets"), join(root, "other/assets"), { recursive: true });
assert.match(upload().output, /Pass the report to host/);
assert.match(upload("missing.zip").output, /There is no report at missing\.zip/);
assert.match(upload("notes.txt").output, /notes\.txt is not an Explore report/);
assert.match(upload("one.zip", "--expires-in", "7d", "two.zip").output, /More than one (ios|android) report/, "a value flag between paths is not read as a path");
assert.match(upload("one.zip", "other").output, /one\.zip and other are not the same review's platforms/, "another run's report of the other platform");
assert.match(upload("one.zip", "--alias", "x").output, /Unknown flag for report:upload: --alias/);
for (const result of [upload(), upload("one.zip", "two.zip")]) assert.equal(result.status, 1);
});
+71 -7
View File
@@ -196,14 +196,15 @@ test('an OS version the simulator did not report is omitted, not shown as unknow
assert.doesNotMatch(body, /unknown/i);
});
test('without evidence the comment falls back to source statuses and says comparisons did not run', () => {
test('without evidence the comment lists only added and removed screens and says comparisons did not run', () => {
const plain = review([surface('care-guide', 'added'), surface('sweet-bee', 'removed'), surface('settings', 'modified'), surface('cats', 'unchanged')]);
const body = renderPublicComment(reviewOnlyState(plain));
assert.match(body, /<summary>🟨 Source-affected \(1\)<\/summary>/);
assert.match(body, /\n- `\/settings` — Source\\-affected; not compared · \[iOS\]/);
// A source change nobody compared is not a change the captures show.
assert.deepEqual(summaries(body).slice(0, 2), ['🟩 Added (1)', '🟥 Removed (1)']);
assert.doesNotMatch(body, /Source-affected|screen=settings/);
assert.equal(checkRow(body, 'Visual comparison'), '| Visual comparison | 🟨 not run |');
assert.equal(checkRow(body, 'Accessibility comparison'), '| Accessibility comparison | 🟨 not run |');
assert.match(platformRow(body, 'iOS'), /^\| iOS \| Example 1\\\.4\\\.0 \\\(27\\\) \| 🟩 3 changes · 0s \|/);
assert.match(platformRow(body, 'iOS'), /^\| iOS \| Example 1\\\.4\\\.0 \\\(27\\\) \| 🟨 2 changes · 1 not compared · 0s \|/, 'the uncompared /settings is counted, not hidden');
assert.doesNotMatch(body, /Needs review|Unchanged|screen=cats/);
});
@@ -261,8 +262,10 @@ test('capture problems are listed as diagnostics inside the validation block wit
flagged.surfaces[2].headOutcome.landing = 'unverified';
flagged.surfaces[2].review = { status: 'needs-review', description: 'old destination failure' };
const body = renderPublicComment(state({ review: flagged, capture: { planned: { base: 3, head: 3 }, done: { base: 1, head: 2 }, baseFromCache: false } }));
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', '🟨 Source-affected (1)', 'Validation · iOS 🟨 3/6 captured']);
assert.match(platformRow(body, 'iOS'), /\| 🟨 3 changes · 3 unavailable · 1 unattributed · 6m 12s \|/);
// /settings could not be compared, so it is no change: its failures are named under Validation.
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', 'Validation · iOS 🟨 3/6 captured']);
assert.match(platformRow(body, 'iOS'), /\| 🟨 2 changes · 3 unavailable · 1 unattributed · 6m 12s \|/);
assert.match(body, /\n- Base · \/settings · /);
assert.match(body, /\*\*iOS\*\* · base 1\/3 verified · 2 unavailable · head 1\/3 verified · 1 unattributed · 1 unavailable/);
assert.match(body, /\n- Base · \/cats\/sweet\\-bee · BASE\\_SESSION\\_FAILED: base simulator disconnected; token=\\\[redacted\\\] Next action: Restart the base simulator session and rerun capture\\\./);
assert.match(body, /\n- Head · \/cats\/care\\-guide · HEAD\\_SESSION\\_FAILED/);
@@ -284,7 +287,7 @@ test('zero eligible pairs are visibly skipped instead of successful comparisons'
assert.equal(checkRow(body, 'Route verification'), '| Route verification | 🟨 0/6 verified · 6 unattributed |');
assert.equal(checkRow(body, 'Visual comparison'), '| Visual comparison | 🟨 0 compared · threshold 0.1 · 2 skipped |');
assert.equal(checkRow(body, 'Accessibility comparison'), '| Accessibility comparison | 🟨 0 compared · 0 descriptions |');
assert.match(platformRow(body, 'iOS'), /\| 🟨 4 changes · 6 unattributed · 6m 12s \|/);
assert.match(platformRow(body, 'iOS'), /\| 🟨 2 changes · 6 unattributed · 6m 12s \|/, 'the uncompared modified screens are not changes');
});
test('the review-only comment counts failed outcomes in planned coverage and lists the reason', () => {
@@ -450,3 +453,64 @@ test('a report whose hosted preview is still deploying says so instead of linkin
assert.equal(record.links.report, undefined, 'the record carries no report link while deploying');
assert.equal(parsePlatformRecord(record).links.deploying, true, 'the deploying flag survives the comment round trip');
});
test('a screen whose screenshots match but whose accessibility tree changed is listed as accessibility only, apart from the visual changes', () => {
const accessibilityOnly = (id) => surface(id, 'modified', { extra: {
review: { status: 'modified', description: 'Added button “Edit tempo”.', facts: [
{ category: 'element', templateId: 'element.added', bullet: 'Added button “Edit tempo”.' },
{ category: 'accessibility', templateId: 'accessibility.label-changed', bullet: 'Changed accessibility label from “lane-row-title-3” to “Clap”.' },
] },
visual: { verdict: 'unchanged', reason: 'matched', mismatchPercentage: 0, threshold: 0.1, tool: '[email protected]' },
sourceChange: sourceChange('Labelled the lane rows.'),
} });
const withAccessibility = review([...evidenceReview().surfaces, accessibilityOnly('device-picker'), accessibilityOnly('enable-midi')]);
const body = renderPublicComment(state({ review: withAccessibility, artifactOnly: true }));
assert.match(platformRow(body, 'iOS'), /\| 🟩 3 visual changes · 2 accessibility only · 6m 12s \|/);
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', '🟧 Modified (1)', '🟦 Accessibility only (2)', 'Validation · iOS 🟩 10/10 captured']);
assert.match(body, /\n\*\*Changes\*\* · 5 screens\n/);
assert.match(body, /<summary>🟦 Accessibility only \(2\)<\/summary>\n\nBefore and After look the same\. What screen readers and voice control read changed\.\n\n- `\/device-picker` — Added button “Edit tempo”\\\. · \[iOS\]/);
const record = parsePlatformRecord(JSON.parse(JSON.stringify(platformRecordOf(state({ review: withAccessibility, artifactOnly: true })))));
assert.deepEqual(record.changes.filter(change => change.group === 'accessibility-only').map(change => change.id), ['device-picker', 'enable-midi'],
'the group survives the comment round trip');
// A comment with no accessibility-only screen keeps its plain count.
assert.match(platformRow(renderPublicComment(state({ artifactOnly: true })), 'iOS'), /\| 🟩 3 changes · 6m 12s \|/);
});
test('a comment whose only changes are for assistive technology counts just those', () => {
const only = review([surface('device-picker', 'modified', { extra: {
review: { status: 'modified', description: 'Changed “Play” from a text to a button.', facts: [{ category: 'accessibility', templateId: 'accessibility.role-changed', bullet: 'Changed “Play” from a text to a button.' }] },
visual: { verdict: 'unchanged', reason: 'matched', mismatchPercentage: 0, threshold: 0.1, tool: '[email protected]' },
sourceChange: sourceChange('Made Play a button.'),
} })]);
assert.match(platformRow(renderPublicComment(state({ review: only, artifactOnly: true })), 'iOS'), /\| 🟩 1 accessibility only · 6m 12s \|/);
});
test('a screen accessibility-only on iOS and visibly modified on Android is listed as Modified, whichever platform comes first', async () => {
const { platformSectionMerge } = await import('../../dist/report/pr-comment-body.js');
const settings = (verdict) => {
const changed = evidenceReview();
changed.surfaces[2].visual = { ...changed.surfaces[2].visual, verdict, mismatchPercentage: verdict === 'modified' ? 3.2 : 0 };
return changed;
};
const androidState = overrides => state({ artifactOnly: true, build: { ...state().build, platform: 'android' },
runtime: { ...state().runtime, platform: 'android', deviceModel: 'EasAndroidDevice01', osVersion: '15.0' }, ...overrides });
const ios = renderPublicComment(state({ review: settings('unchanged'), artifactOnly: true }));
assert.ok(summaries(ios).includes('🟦 Accessibility only (1)'), 'iOS alone: the screenshots match');
const both = platformSectionMerge(androidState({ review: settings('modified') }), 'android').merge(ios);
assert.deepEqual(summaries(both).slice(0, 3), ['🟩 Added (1)', '🟥 Removed (1)', '🟧 Modified (1)']);
assert.doesNotMatch(both, /Accessibility only \(|Before and After look the same/);
assert.match(both, /\n- `\/settings` — [^\n]+ · \[iOS \(accessibility only\)\]\(<[^>]+>\) · \[Android\]\(<[^>]+>\)\n/);
});
test('screens whose comparison did not run are counted as not compared, never as a green "no change"', () => {
const uncompared = review([surface('settings', 'modified'), surface('tempo', 'modified')]);
const body = renderPublicComment(state({ review: uncompared, artifactOnly: true }));
assert.match(platformRow(body, 'iOS'), /\| 🟨 0 changes · 2 not compared · 6m 12s \|/);
assert.match(body, /\nNo compared screen changed on the reviewed platforms\.\n/);
// A screen that was never captured (outside the capture scope) stays out of the count.
const outOfScope = surface('channel', 'modified');
for (const key of ['baseImage', 'headImage', 'baseOutcome', 'headOutcome']) delete outOfScope[key];
const quiet = renderPublicComment(state({ review: review([outOfScope]), artifactOnly: true, evidence: undefined, capture: { planned: { base: 0, head: 0 }, done: { base: 0, head: 0 }, baseFromCache: false } }));
assert.match(platformRow(quiet, 'iOS'), /\| 🟩 0 changes · 6m 12s \|/);
assert.match(quiet, /\nNo screen changed on the reviewed platforms\.\n/);
});
+2 -3
View File
@@ -210,10 +210,9 @@ test("the verdict table: source scope decides whether a screen is a review targe
const head = await side(root, "head", manifests.head);
const assess = (overrides, mismatches = {}) => assessPublicEvidence({ plan: plan("all", overrides), base, head,
profile: "explore:bundle", agentDeviceCommand: "/nonexistent/agent-device", measure: measurer(mismatches) });
// Screen-specific source change, identical evidence: still a review target.
// Screen-specific source change, identical evidence: not a visible change, so Unchanged and not counted.
let result = await assess({});
assert.equal(result.surfaces.pixels.review.status, "needs-review");
assert.equal(result.surfaces.pixels.review.description, "Source changed; no visible difference was captured.");
assert.deepEqual(result.surfaces.pixels.review, { status: "unchanged", description: "No visible change" });
assert.equal(result.surfaces.changed.review.status, "modified", "an accessibility fact is a visible difference");
// Only app-wide inputs changed: no visible difference is Unchanged; a difference is Modified.
result = await assess({ pixels: { status: "modified", reasons: ["App configuration changed: package.json"] },
+8 -1
View File
@@ -172,7 +172,7 @@ test("reader never shows malformed original verdicts, capture outcomes, or prove
});
test("a source scope allows only its verdicts, and legacy source-unchanged differences read as variants", () => {
const allowed = { screen: ["modified", "needs-review"], "app-wide": ["modified", "needs-review", "unchanged"], none: ["unchanged", "variant"] };
const allowed = { screen: ["modified", "needs-review", "unchanged"], "app-wide": ["modified", "needs-review", "unchanged"], none: ["unchanged", "variant"] };
for (const [scope, statuses] of Object.entries(allowed)) {
for (const status of ["modified", "needs-review", "unchanged", "variant"]) {
const input = review();
@@ -194,6 +194,13 @@ test("a source scope allows only its verdicts, and legacy source-unchanged diffe
const read = normalizePublicReviewForReading(legacy);
assert.deepEqual(read.surfaces[0].review, { status: "variant", description: "Runtime state differs: Removed text “84”." });
assert.deepEqual(read.surfaces[1].review, legacy.surfaces[1].review, "a legacy source-changed verdict has no scope to re-judge");
// A report from before 0.19.1 called a source change with matching captures "needs review": it reads as unchanged.
const older = review();
older.surfaces[0].review = { status: "needs-review", description: "Source changed; no visible difference was captured." };
older.surfaces[1].review = { status: "needs-review", description: "Visual comparison was inconclusive" };
const reread = normalizePublicReviewForReading(older);
assert.deepEqual(reread.surfaces[0].review, { status: "unchanged", description: "No visible change" });
assert.equal(reread.surfaces[1].review.status, "needs-review", "an inconclusive comparison still needs a look");
});
test("launch evidence carries verified splash and settled frames, an mp4 with provenance, and a splash verdict only when both sides observed one", () => {
+10 -10
View File
@@ -211,7 +211,7 @@ test("public inventory preserves source classification while unverified images s
const workspace = publicReviewToWorkspace(review);
const { baseline, current } = workspaceSides(workspace);
assert.deepEqual(workspace.comparison.entries.map(({ id, status }) => ({ id, status })), [
{ id: "games-free", status: "source-affected" }, { id: "games-pro", status: "not-compared" },
{ id: "games-free", status: "not-compared" }, { id: "games-pro", status: "not-compared" },
{ id: "care-guide", status: "added" }, { id: "sweet-bee", status: "removed" },
{ id: "scan-mood", status: "not-compared" }, { id: "scan-breed", status: "not-compared" },
{ id: "home", status: "not-compared" }, { id: "camera-alias", status: "not-compared" },
@@ -231,9 +231,9 @@ test("public inventory preserves source classification while unverified images s
assert.ok(payload.map.screens.every((screen) => !screen.start && !screen.terminal));
}
const diff = diffFor(review);
assert.equal(diff.screens.get("games-free").status, "source-affected", "Equal PNG hashes cannot prove verified destinations");
assert.equal(diff.screens.get("games-free").status, "not-compared", "Equal PNG hashes cannot prove verified destinations");
assert.equal(diff.screens.get("games-pro").status, "not-compared", "Different PNG hashes cannot prove a route modification");
assert.deepEqual(diff.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 1, "not-compared": 5, unavailable: 0, variant: 0 });
assert.deepEqual(diff.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 0, "not-compared": 6, unavailable: 0, variant: 0 });
assert.equal(workspace.review, undefined, "The adapter must not fabricate semantic review evidence");
assert.deepEqual(review, before, "The source publication remains immutable");
});
@@ -281,7 +281,7 @@ test("existing route-family presentation groups query variants without losing th
assert.equal(scan.observationIds.length, 2);
assert.deepEqual(scan.variantIds.map((id) => presentation.index.variants.get(id).name), ["mood", "breed"]);
const displayed = presentBuildDiff(diff, presentation);
assert.deepEqual(displayed.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 1, "not-compared": 3, unavailable: 0, variant: 0 });
assert.deepEqual(displayed.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 0, "not-compared": 4, unavailable: 0, variant: 0 });
assert.equal(presentation.map.screens.length, 6);
assert.equal(scan.title, "Scan — Instruction");
const graph = buildObservedGraph(presentation.map, presentation.index);
@@ -455,7 +455,7 @@ test("What changed uses commit-bound Git summaries without changing screenshot i
review.surfaces[0].sourceChange = summary;
const diff = diffFor(review).screens.get("games-free");
assert.equal(diff.changeSummary, summary.summary);
assert.equal(diff.status, "source-affected");
assert.equal(diff.status, "not-compared");
assert.equal(diff.beforeScreenshot, review.surfaces[0].baseImage.url);
assert.equal(diff.afterScreenshot, review.surfaces[0].headImage.url);
assert.doesNotMatch(diff.changeSummary, /Visual changes have not been classified/);
@@ -583,16 +583,16 @@ test("public notes survive viewer projection without changing deterministic verd
});
test("source-only impact and untouched uncaptured inventory stay distinct from runtime verdicts", () => {
test("a source change without a comparison is not compared, as untouched uncaptured inventory is: it is no change the captures show", () => {
const review = fixture("changes");
delete review.surfaces[0].baseImage;
delete review.surfaces[0].headImage;
const diff = diffFor(review);
assert.equal(diff.screens.get("games-free").status, "source-affected");
assert.equal(diff.screens.get("games-free").status, "not-compared");
assert.equal(diff.screens.get("games-pro").status, "not-compared");
assert.equal(diff.counts.modified, 0);
assert.equal(diff.counts.unchanged, 0);
assert.equal(diff.counts["source-affected"], 1);
assert.equal(diff.counts["source-affected"], 0);
assert.equal(review.surfaces[0].status, "modified", "source classification is retained without inventing a visual verdict");
});
@@ -657,7 +657,7 @@ test("unverified captures on either side remain diagnostics and cannot become ap
assert.equal(affected.coverage.observations, 6, "an unverified image is retained as diagnostic evidence");
assert.match(affected.map.gaps.find(gap => gap.screenId === surface.id).message, /destination unverified/);
const diff = diffFor(review);
assert.equal(diff.screens.get(surface.id).status, "source-affected");
assert.equal(diff.screens.get(surface.id).status, "not-compared");
assert.equal(diff.screens.get(surface.id).noVisibleChange, false);
assert.deepEqual(diff.screens.get(surface.id).reviewerChanges, []);
assert.equal(diff.counts["needs-review"], 0);
@@ -710,7 +710,7 @@ test("direct reads of existing operational verdicts preserve diagnostics without
deepFreeze(input);
publicReviewToWorkspace(input);
const diff = diffFor(input);
assert.equal(diff.screens.get(surface.id).status, "source-affected");
assert.equal(diff.screens.get(surface.id).status, "not-compared");
assert.equal(diff.counts["needs-review"], 0);
assert.deepEqual(diff.screens.get(surface.id).reviewerChanges, []);
assert.equal(surface.review.status, "needs-review", "the original report is not mutated by reading");
+159
View File
@@ -0,0 +1,159 @@
import assert from 'node:assert/strict';
import { PassThrough } from 'node:stream';
import test from 'node:test';
import { decodeKeys, formatBytes, friendlyTime, reducePicker, renderPicker, runPicker, runTitle, visibleRuns } from '../../dist/cli/reports-picker.js';
import { INTRO_NAMES, intros, pickIntro, WORDMARK } from '../../dist/cli/title-intros.js';
const now = new Date(2026, 9, 15, 16, 0).getTime();
const at = (days, hour = 10) => new Date(2026, 9, 15 - days, hour, 29).toISOString();
const run = (id, fields) => ({ version: 1, id, platforms: ['ios'], createdAt: at(0), savedAt: at(0), bytes: 6_000_000, ...fields });
const RUNS = [
run('local-1', { kind: 'local', title: 'HEAD vs main', repository: 'brentvatne/euxy', head: { ref: 'HEAD', sha: 'a8e71e1aaaa', subject: 'Refresh the explore report' },
base: { ref: 'main', sha: 'aef021fbbbb', subject: 'Bump workflows' }, device: 'iPhone 17 · light + dark', changes: { modified: 32, added: 2, removed: 2 } }),
run('pr-157', { kind: 'pull-request', number: 157, title: 'Splash screen and about page', repository: 'brentvatne/euxy', createdAt: at(1),
head: { ref: 'about', sha: '3f09c2eaaaa', subject: 'Add /about' }, base: { ref: 'main', sha: 'aef021fbbbb' }, changes: { modified: 15, 'needs-review': 17 } }),
run('local-2', { kind: 'local', title: 'uncommitted changes vs main', repository: 'brentvatne/euxy', uncommittedFiles: 3, platforms: ['ios', 'android'], createdAt: at(3),
head: { ref: 'uncommitted changes', sha: '9c1d2aaaaaa', subject: 'Wire up the BPM column' }, base: { ref: 'main', sha: '71be0f3bbbb' }, changes: {} }),
run('compare-1', { kind: 'compare', title: 'v1.4.0 vs v1.3.0', repository: 'expo/other', createdAt: at(6), head: { ref: 'v1.4.0', sha: 'e81f00baaaa' }, base: { ref: 'v1.3.0', sha: 'c2a9d41bbbb' } }),
run('explore-acme', { kind: 'exploration', title: 'Acme 2.0 (41) on Pixel 9', platforms: ['android'], createdAt: new Date(2026, 8, 30).toISOString(),
explored: { app: 'Acme', version: '2.0', buildNumber: '41', screens: 41, unexplored: 3 } }),
];
const state = (fields = {}) => ({ runs: RUNS, repository: 'brentvatne/euxy', scope: 'repository', filter: '', filtering: false, selected: 0, offset: 0, ...fields });
const screen = (fields, options = {}) => renderPicker(state(fields), { width: 100, height: 30, now, color: false, totalBytes: 184 * 1024 * 1024, ...options });
test('the list shows this repository\'s runs in aligned columns, and the selected one\'s commits and changes below', () => {
const lines = screen();
assert.ok(lines.includes(` ${WORDMARK[0]}`), 'a tall terminal gets the wordmark');
assert.ok(lines.some(line => line.includes('5 saved runs · 184 MB on disk · brentvatne/euxy')), 'the size says what it is');
const rows = lines.filter(line => /^(▌ | {2})(Local|PR #|Compare|Explore)/.test(line));
assert.deepEqual(rows.map(line => line.slice(2, 11).trim()), ['Local', 'PR #157', 'Local'], 'other repositories and explorations wait for tab');
assert.match(rows[0], /^▌ Local {6}HEAD vs main {2,}a8e71e1 {2}iOS {10}this morning/);
assert.match(rows[2], /HEAD \+ 3 uncommitted files vs main.*iOS Android {2}last Monday/);
assert.equal(new Set(rows.map(row => row.indexOf('iOS'))).size, 1, 'the columns line up');
assert.ok(lines.includes(' head a8e71e1 Refresh the explore report'));
assert.ok(lines.includes(' base aef021f Bump workflows main'));
assert.ok(lines.includes(' 32 modified 2 added 2 removed · iPhone 17 · light + dark'));
assert.match(lines.at(-1), /↑↓ move {3}⏎ open {3}\/ filter {3}u upload {3}d delete {3}tab all repos {3}q quit/);
assert.equal(lines.length, 30, 'it fills the terminal, with the keys on the last line');
});
test('tab shows every repository, and an exploration lists its screens', () => {
const lines = screen({ scope: 'all', selected: 4 });
assert.ok(lines.some(line => line.includes('· all repositories')));
assert.ok(lines.some(line => /^▌ Explore {4}Acme 2\.0 \(41\) on Pixel 9 .* Android {6}Sep 30/.test(line)));
assert.ok(lines.some(line => line.startsWith(' Compare v1.3.0 → v1.4.0')));
assert.ok(lines.includes(' 41 screens 3 unexplored'));
});
test('a narrow or short terminal keeps the essentials', () => {
const narrow = screen({}, { width: 60, height: 14 });
assert.ok(narrow[0].includes('Expo Explore'), 'a plain name instead of the wordmark');
assert.ok(!narrow.some(line => line.includes('a8e71e1 iOS')), 'the SHA and platform columns go first');
assert.ok(narrow.every(line => [...line].length <= 60 || line.startsWith('─')), 'nothing runs past the edge');
assert.ok(narrow.some(line => line.startsWith('▌ Local')));
});
test('filtering matches titles, commit subjects, SHAs and PR numbers, and says when nothing matches', () => {
for (const [query, ids] of [['bpm', ['local-2']], ['157', ['pr-157']], ['a8e71e1', ['local-1']], ['ABOUT', ['pr-157']]]) {
assert.deepEqual(visibleRuns(state({ filter: query })).map(each => each.id), ids, query);
}
assert.ok(screen({ filter: 'zzz' }).some(line => line.includes('Nothing matches "zzz".')));
assert.ok(screen({ filtering: true, filter: 'bp' }).at(-1).includes('/ bp▏ 1 of 5'));
assert.ok(renderPicker(state({ runs: [] }), { width: 100, height: 30, now, color: false, totalBytes: 0 }).some(line => line.includes('No saved runs yet.')));
});
test('keys move, filter, open, upload, and delete only after y', () => {
let current = state();
const press = (...keys) => { let action; for (const key of keys) ({ state: current, action } = reducePicker(current, key)); return action; };
press('down', 'down', 'down');
assert.equal(current.selected, 2, 'the selection stops at the last run');
press({ text: 'k' }, { text: 'g' });
assert.equal(current.selected, 0);
assert.deepEqual(press('enter'), { type: 'open', run: RUNS[0] });
assert.deepEqual(press({ text: 'u' }), { type: 'upload', run: RUNS[0] });
assert.equal(press({ text: 'd' }), undefined);
assert.equal(current.confirming, 'local-1');
assert.equal(press({ text: 'n' }), undefined);
assert.equal(current.message, 'Kept it.');
assert.deepEqual(press({ text: 'd' }, { text: 'y' }), { type: 'delete', run: RUNS[0] });
press({ text: '/' }, { text: 'b' }, { text: 'p' }, { text: 'x' }, 'backspace');
assert.deepEqual([current.filtering, current.filter], [true, 'bp']);
assert.equal(press({ text: 'q' }), undefined, 'q is text while filtering');
press('escape');
assert.deepEqual([current.filtering, current.filter], [false, '']);
press({ text: '/' }, { text: 'x' });
assert.deepEqual(press('quit'), { type: 'quit' }, 'Ctrl+C quits while filtering too');
press('escape');
press('tab');
assert.equal(current.scope, 'all');
assert.deepEqual(press('escape'), { type: 'quit' });
assert.deepEqual(press('quit'), { type: 'quit' });
});
test('raw terminal input becomes keys, several at a time', () => {
assert.deepEqual(decodeKeys('\x1b[A\x1b[B\r\tjk\x7f\x03\x1b'), ['up', 'down', 'enter', 'tab', { text: 'j' }, { text: 'k' }, 'backspace', 'quit', 'escape']);
assert.deepEqual(decodeKeys('\x1b[5~\x1b[6~\x1b[H\x1b[F\x1b[C'), ['pageup', 'pagedown', 'home', 'end']);
// Keys the picker has no use for are swallowed whole, never read as Esc (which quits): Delete, F1, Shift+Tab, Ctrl+Up, Alt+x.
assert.deepEqual(decodeKeys('\x1b[3~\x1bOP\x1b[Z\x1b[1;5A\x1bxj'), [{ text: 'j' }]);
assert.deepEqual(decodeKeys('\x1b'), ['escape']);
assert.deepEqual(decodeKeys('a\u009b2Jb'), [{ text: 'a' }, { text: '2' }, { text: 'J' }, { text: 'b' }], 'a C1 control is not typed into the filter');
});
test('times and sizes read like a person would say them', () => {
assert.equal(friendlyTime(new Date(now - 30_000).toISOString(), now), 'just now');
assert.equal(friendlyTime(new Date(now - 5 * 60_000).toISOString(), now), '5 min ago');
assert.equal(friendlyTime(at(0, 9), now), 'this morning');
assert.equal(friendlyTime(at(1), now), 'yesterday');
assert.equal(friendlyTime(at(3), now), 'last Monday');
assert.equal(friendlyTime(new Date(2025, 0, 2).toISOString(), now), 'Jan 2, 2025');
assert.deepEqual([formatBytes(900), formatBytes(6_000_000), formatBytes(3 * 1024 ** 3)], ['1 KB', '6 MB', '3.0 GB']);
assert.equal(runTitle(RUNS[2]), 'HEAD + 3 uncommitted files vs main');
});
test('every title animation ends on the wordmark, stays inside it, and one is picked at random unless named', () => {
const plain = Object.fromEntries(['white', 'text', 'dim', 'faint', 'amber', 'green', 'yellow', 'blue'].map(name => [name, text => text]));
for (const [name, intro] of Object.entries(intros(3))) {
assert.deepEqual(intro.frame(1, plain).map(row => row.trimEnd()), WORDMARK.map(row => row.trimEnd()), name);
for (const t of [0, 0.25, 0.5, 0.75]) assert.ok(intro.frame(t, plain).every(row => [...row].length <= WORDMARK[0].length + 24), `${name} at ${t}`);
assert.ok(intro.duration <= 900, `${name} is quick`);
}
assert.equal(pickIntro({ EXPLORE_INTRO: 'off' }), undefined);
assert.equal(pickIntro({ EXPLORE_INTRO: 'Beams' }), 'beams');
assert.deepEqual(new Set([0, 0.2, 0.4, 0.6, 0.8].map(value => pickIntro({}, () => value))), new Set(INTRO_NAMES));
});
test('the picker restores the terminal however it ends', async () => {
const input = Object.assign(new PassThrough(), { isTTY: true, modes: [], setRawMode(mode) { this.modes.push(mode); return this; } });
const output = Object.assign(new PassThrough(), { columns: 100, rows: 30 });
let written = '';
output.on('data', chunk => { written += chunk; });
const removed = [];
const picked = runPicker(state(), { input, output, color: false, remove: async each => { removed.push(each.id); }, totalBytes: () => 0 });
input.write('jd');
input.write('y');
setTimeout(() => input.write('\r'), 20);
const action = await picked;
assert.deepEqual(removed, ['pr-157']);
assert.deepEqual([action.type, action.run.id], ['open', 'local-2'], 'after a delete the selection moves to the next run');
assert.deepEqual(input.modes, [true, false]);
assert.ok(written.startsWith('\x1b[?1049h\x1b[?25l') && written.endsWith('\x1b[?25h\x1b[?1049l'), 'the alternate screen and cursor are restored');
assert.ok(written.includes('Deleted Splash screen and about page.'));
});
test('a key that skips the title animation only skips it; Ctrl+C during it still quits', async () => {
const terminal = () => {
const input = Object.assign(new PassThrough(), { isTTY: true, setRawMode() { return this; } });
const output = Object.assign(new PassThrough(), { columns: 100, rows: 30 });
output.resume();
return { input, output };
};
const first = terminal();
const picked = runPicker(state(), { ...first, color: false, intro: 'snap', remove: async () => {}, totalBytes: () => 0 });
first.input.write('\r');
setTimeout(() => first.input.write('q'), 60);
assert.deepEqual(await picked, { type: 'quit' }, 'Enter skipped the animation instead of opening a run');
const second = terminal();
const quitting = runPicker(state(), { ...second, color: false, intro: 'decrypt', remove: async () => {}, totalBytes: () => 0 });
second.input.write('\x03');
assert.deepEqual(await quitting, { type: 'quit' });
});
+48 -1
View File
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
import { projectPullRequestPresentation } from "../../dist/contracts/review.js";
import { projectPullRequestPresentation, projectReviewPresentation } from "../../dist/contracts/review.js";
const input = {
repositoryId: "123456789",
@@ -26,3 +26,50 @@ test("rejects PR URLs and metadata that can escape the fixed repository", () =>
/unsupported field/,
);
});
const comparison = {
origin: "compare",
repositoryId: "123456789",
repository: "expo/explore-playground",
base: { ref: "v1.3.0", sha: "a".repeat(40) },
head: { ref: "v1.4.0-rc.1", sha: "b".repeat(40) },
};
test("a comparison of two commits gets github.com's compare URL and a title from its refs", () => {
assert.deepEqual(projectReviewPresentation(comparison), {
...comparison, title: "v1.4.0-rc.1 vs v1.3.0",
url: `https://github.com/expo/explore-playground/compare/${"a".repeat(40)}..${"b".repeat(40)}`,
});
const bySha = projectReviewPresentation({ ...comparison, head: { ref: "b".repeat(40), sha: "b".repeat(40) } });
assert.equal(bySha.title, "bbbbbbbb vs v1.3.0", "a ref given as a SHA reads as its short form");
assert.equal(projectReviewPresentation({ ...comparison, title: "Nightly" }).title, "Nightly");
const projected = projectReviewPresentation(comparison);
assert.deepEqual(projectReviewPresentation(projected), projected, "projection is stable, so a stored comparison validates again");
});
test("rejects comparisons that name another URL, a PR number, or one commit twice", () => {
assert.throws(() => projectReviewPresentation({ ...comparison, url: "https://example.com/compare" }), /compare URL/);
assert.throws(() => projectReviewPresentation({ ...comparison, number: 7 }), /unsupported field/);
assert.throws(() => projectReviewPresentation({ ...comparison, head: comparison.base }), /different commits/);
assert.throws(() => projectReviewPresentation({ ...comparison, repositoryId: "x" }), /decimal GitHub id/);
});
test("a run's scope and link lifetime override the reviewed config only where the workflow set them", async () => {
const { withRunOverrides } = await import("../../dist/config/explore-config.js");
const config = { exploration: { scope: "changes" }, report: { preview: { hosting: "eas", expiresAfterDays: 30 } } };
assert.deepEqual(withRunOverrides(config, {}), config);
assert.deepEqual(withRunOverrides(config, { scope: "all", expiresIn: "never" }),
{ exploration: { scope: "all" }, report: { preview: { hosting: "eas", expiresAfterDays: null } } });
assert.equal(withRunOverrides(config, { expiresIn: "90d" }).report.preview.expiresAfterDays, 90);
assert.deepEqual(withRunOverrides({ exploration: { scope: "changes" } }, { expiresIn: "never" }), { exploration: { scope: "changes" } }, "no hosting, nothing to expire");
assert.throws(() => withRunOverrides(config, { scope: "everything" }), /--scope must be changes or all/);
assert.throws(() => withRunOverrides(config, { expiresIn: "forever" }), /--expires-in/);
assert.throws(() => withRunOverrides({ exploration: { scope: "changes" } }, { expiresIn: "forevr" }), /--expires-in/, "a typo fails even before hosting is on");
});
test("a comparison links GitHub's direct two-dot diff, which matches what capture compares, also for a rollback", () => {
// Three dots diff from the merge base: comparing a newer base to an older head would show nothing there.
const rollback = projectReviewPresentation({ ...comparison, base: comparison.head, head: comparison.base });
assert.equal(rollback.url, `https://github.com/expo/explore-playground/compare/${"b".repeat(40)}..${"a".repeat(40)}`);
assert.throws(() => projectReviewPresentation({ ...comparison, url: `https://github.com/expo/explore-playground/compare/${"a".repeat(40)}...${"b".repeat(40)}` }), /compare URL/);
});
+21
View File
@@ -0,0 +1,21 @@
import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { reviewProjectionFromWorkspace } = await tsImport("../../viewer/src/utils/review-model.ts", import.meta.url);
const base = { ref: "v1.3.0", sha: "a".repeat(40) };
const head = { ref: "v1.4.0", sha: "b".repeat(40) };
const url = `https://github.com/acme/app/compare/${base.sha}..${head.sha}`;
const projection = pullRequest => reviewProjectionFromWorkspace({ review: { surfaces: {}, runtimeEvidence: {}, pullRequest } })?.pullRequest;
test("the Viewer reads a comparison of two commits, with its compare page and no PR number", () => {
assert.deepEqual(projection({ origin: "compare", title: "v1.4.0 vs v1.3.0", url, base, head }),
{ origin: "compare", title: "v1.4.0 vs v1.3.0", url, base, head });
});
test("the Viewer drops a comparison whose link is not the compare page of its own commits", () => {
assert.equal(projection({ origin: "compare", title: "x", url: "https://example.com/compare", base, head }), undefined);
assert.equal(projection({ origin: "compare", title: "x", url: `https://github.com/acme/app/compare/${head.sha}..${base.sha}`, base, head }), undefined);
assert.equal(projection({ origin: "compare", title: "x", url: `https://github.com/acme/app/pull/7`, base, head }), undefined);
});
+1 -1
View File
@@ -51,7 +51,7 @@ test('round trip: iOS and Android jobs of one run share a single comment: one ro
assert.equal(comment.match(/^### Explore review/gm).length, 1, 'one header');
const routeLines = comment.split('\n').filter(line => /^- `\/(added|removed|home)`/.test(line));
assert.ok(routeLines.length >= 1, `the comment lists changed routes once:\n${comment}`);
assert.equal(routeLines.length, 6, 'each changed screen is listed once');
assert.equal(routeLines.length, 6, `each changed screen is listed once:\n${comment}`);
for (const line of routeLines) assert.ok(/\[iOS\]\(/.test(line) && /\[Android\]\(/.test(line), `each changed route carries both platforms once: ${line}`);
const projection = publicReviewProjection(android.report.review);
for (const surface of android.report.review.surfaces) assert.ok(projection.surfaces[surface.id], `the Viewer projects the Android surface ${surface.id}`);
+208
View File
@@ -0,0 +1,208 @@
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import test from 'node:test';
import { describeReports, findSavedRun, listSavedRuns, pruneSavedRuns, readSavedReports, removeSavedRun, saveRun, savedRunsDirectory } from '../../dist/report/saved-runs.js';
import { pruneCaptureCache } from '../../dist/ci/local-review.js';
import { readReportZip, zipReportDirectory } from '../../dist/report/preview-deploy.js';
const root = resolve(import.meta.dirname, '../..');
const cli = join(root, 'dist', 'cli.js');
const review = new Uint8Array(await readFile(join(import.meta.dirname, '../fixtures/example-review-artifact.zip')));
async function cache(t) {
const directory = await mkdtemp(join(tmpdir(), 'explore-saved-runs-'));
t.after(() => rm(directory, { recursive: true, force: true }));
return { EXPLORE_CACHE_DIR: directory };
}
async function exploration(t) {
const directory = await mkdtemp(join(tmpdir(), 'explore-saved-exploration-'));
t.after(() => rm(directory, { recursive: true, force: true }));
await writeFile(join(directory, 'exploration.json'), JSON.stringify({ kind: 'explore.exploration-report', map: { screens: [{}, {}, {}] }, coverage: { frontier: { pending: 2 } },
exploration: { app: { name: 'Acme', bundleId: 'com.acme', platform: 'android', version: '2.0', buildNumber: '41' }, device: { model: 'Pixel 9', osVersion: '16' },
completedAt: '2026-10-12T09:00:00.000Z' } }));
return zipReportDirectory(directory);
}
test('a review report is kept with what the list shows: kind, title, commits, platforms and changes', async t => {
const environment = await cache(t);
const run = await saveRun([{ platform: 'ios', zip: review }], { subjects: { head: 'Add cats', base: 'Initial commit' } }, environment);
assert.deepEqual({ ...run, savedAt: undefined }, { version: 1, id: 'pr-1-explore-playground-35721157511-1', kind: 'pull-request', title: 'Add cats care guide, retire Sweet Bee, refresh share label',
repository: 'expo/explore-playground', number: 1, head: { ref: 'pilot/viewer-coverage', sha: 'efa2903d85090a8906b5fd42cd6d13608d1cb5ff', subject: 'Add cats' },
base: { ref: 'main', sha: 'afdd3403fd85a5ec3b312339a9b18a683554a6c1', subject: 'Initial commit' }, platforms: ['ios'], changes: { added: 1, removed: 1, modified: 3 },
createdAt: '2026-09-22T11:42:08.764Z', savedAt: undefined, bytes: review.byteLength });
assert.deepEqual((await readdir(join(savedRunsDirectory(environment), run.id))).sort(), ['ios.zip', 'run.json']);
assert.deepEqual(await listSavedRuns(environment), [run]);
assert.deepEqual((await findSavedRun('latest', environment))?.id, run.id);
const [saved] = await readSavedReports(run, environment);
assert.deepEqual(saved.zip, review, 'the ZIP is kept as is, so it opens and hosts like the original');
// Saving the same run again replaces it rather than adding a second copy.
await saveRun([{ platform: 'ios', zip: review }], {}, environment);
assert.equal((await listSavedRuns(environment)).length, 1);
assert.equal(await removeSavedRun(run.id, environment), true);
assert.deepEqual(await listSavedRuns(environment), []);
assert.equal(await removeSavedRun('../escape', environment), false);
});
test('an exploration is kept under its app, with its screens and what was left unexplored', async t => {
const environment = await cache(t);
const run = await saveRun([{ platform: 'android', zip: await exploration(t) }], {}, environment);
assert.match(run.id, /^explore-acme-[0-9a-f]{10}$/);
assert.equal(run.kind, 'exploration');
assert.equal(run.title, 'Acme 2.0 (41) on Pixel 9');
assert.deepEqual(run.explored, { app: 'Acme', version: '2.0', buildNumber: '41', screens: 3, unexplored: 2 });
assert.equal(run.createdAt, '2026-10-12T09:00:00.000Z');
});
test('pruning drops runs kept too long, then the longest kept past the size limit, never the one just saved', async t => {
const environment = await cache(t);
const day = 86_400_000, now = Date.UTC(2026, 9, 15);
const old = await saveRun([{ platform: 'android', zip: await exploration(t) }], {}, environment, now - 40 * day);
const recent = await saveRun([{ platform: 'ios', zip: review }], {}, environment, now - 20 * day);
assert.deepEqual((await listSavedRuns(environment)).map(run => run.id).sort(), [old.id, recent.id].sort(), 'twenty days on, the first run is still within the limit');
assert.deepEqual((await pruneSavedRuns(environment, now)).map(run => run.id), [old.id], 'forty days on, it is not');
assert.deepEqual((await pruneSavedRuns(environment, now, { maxAgeDays: 30, maxBytes: 1 }, recent.id)).map(run => run.id), [], 'the run being kept is never pruned');
assert.deepEqual((await pruneSavedRuns(environment, now, { maxAgeDays: 30, maxBytes: 1 })).map(run => run.id), [recent.id]);
});
test('a folder that is not a readable run is skipped, and a report from before Android support is iOS', async t => {
const environment = await cache(t);
await mkdir(join(savedRunsDirectory(environment), 'broken'), { recursive: true });
await writeFile(join(savedRunsDirectory(environment), 'broken', 'run.json'), '{"version":1}');
assert.deepEqual(await listSavedRuns(environment), []);
assert.equal((await readReportZip(review)).platform, 'ios', 'review.json has no runtime.platform');
await assert.rejects(describeReports([{ platform: 'ios', zip: new Uint8Array([1, 2, 3]) }]), /Not an Explore report ZIP/);
});
test('reports lists, opens by id, removes and prunes from the command line', async t => {
const environment = await cache(t);
const run = await saveRun([{ platform: 'ios', zip: review }], {}, environment);
const reports = (...args) => spawnSync(process.execPath, [cli, 'reports', ...args], { cwd: tmpdir(), encoding: 'utf8', env: { ...process.env, ...environment, CI: '' } });
// Not a terminal: the plain list rather than the picker.
const list = reports();
assert.equal(list.status, 0, list.stderr);
assert.match(list.stdout, new RegExp(`^${run.id} PR #1 Add cats care guide`));
assert.match(list.stdout, /Open one with: expo-explore reports open <id>/);
const json = JSON.parse(reports('--json').stdout);
assert.deepEqual(json.runs.map(each => each.id), [run.id]);
assert.equal(json.directory, savedRunsDirectory(environment));
assert.match(reports('open', 'nope').stderr, /There is no saved run nope/);
assert.match(reports('open').stderr, /Name the run/);
assert.match(reports('frobnicate').stderr, /Unknown reports subcommand: frobnicate/);
assert.match(reports('prune').stdout, /Nothing to prune/);
assert.match(reports('rm', 'latest').stdout, /Deleted Add cats care guide/);
assert.match(reports().stdout, /No saved runs yet/);
// A downloaded report is kept without hosting it.
const added = reports('add', join(import.meta.dirname, '../fixtures/example-review-artifact.zip'));
assert.equal(added.status, 0, added.stderr);
assert.match(added.stdout, new RegExp(`Kept Add cats care guide, retire Sweet Bee, refresh share label as ${run.id}\\.`));
assert.deepEqual((await listSavedRuns(environment)).map(each => each.id), [run.id]);
assert.match(reports('add').stderr, /Pass the report to keep/);
});
test('what a report or commit says reaches the terminal as plain text, and run.json can only name the two platforms', async t => {
const environment = await cache(t);
const run = await saveRun([{ platform: 'ios', zip: review }], { subjects: { head: 'Add cats\x1b]52;c;cHduZWQ=\x07\x1b[2J', base: 'Initial\x9b2J commit' } }, environment);
assert.equal(run.head.subject, 'Add cats]52;c;cHduZWQ=[2J');
assert.equal(run.base.subject, 'Initial2J commit');
// A run.json edited (or written by an older version) with escape sequences is read back plain.
const file = join(savedRunsDirectory(environment), run.id, 'run.json');
const edited = JSON.parse(await readFile(file, 'utf8'));
await writeFile(file, JSON.stringify({ ...edited, title: 'Evil\x1b[2J title', device: 'Pixel\x07' }));
const [read] = await listSavedRuns(environment);
assert.deepEqual([read.title, read.device], ['Evil[2J title', 'Pixel']);
// Platforms name the ZIPs read back: anything else is not a run.
await writeFile(file, JSON.stringify({ ...edited, platforms: ['../../private'] }));
assert.deepEqual(await listSavedRuns(environment), []);
});
test('a review\'s platforms saved one at a time are one run, and runs of a long-named repository keep apart', async t => {
const environment = await cache(t);
const dir = await mkdtemp(join(tmpdir(), 'explore-saved-platforms-'));
t.after(() => rm(dir, { recursive: true, force: true }));
await writeFile(join(dir, 'a.zip'), review);
spawnSync('unzip', ['-q', '-o', join(dir, 'a.zip'), '-d', join(dir, 'report')]);
const variant = async (mutate, name) => {
const json = JSON.parse(await readFile(join(dir, 'report', 'review.json'), 'utf8'));
mutate(json.review);
const copy = join(dir, name);
await rm(copy, { recursive: true, force: true });
await mkdir(copy);
await writeFile(join(copy, 'review.json'), JSON.stringify(json));
await spawnSync('cp', ['-R', join(dir, 'report', 'assets'), join(copy, 'assets')]);
return zipReportDirectory(copy);
};
const android = await variant(r => { r.runtime.platform = 'android'; }, 'android');
await saveRun([{ platform: 'ios', zip: review }], { subjects: { head: 'Add cats' } }, environment);
const both = await saveRun([{ platform: 'android', zip: android }], {}, environment);
assert.deepEqual(both.platforms, ['ios', 'android']);
assert.equal(both.head.subject, 'Add cats', 'what the first save knew is kept');
assert.deepEqual((await readdir(join(savedRunsDirectory(environment), both.id))).sort(), ['android.zip', 'ios.zip', 'run.json']);
// Another attempt of the same run is another run, however long the repository's name.
const long = 'an-unusually-long-repository-name-for-the-app';
const first = await variant(r => { r.pullRequest.repository = `acme/${long}`; r.runId = '18234567890'; r.runAttempt = '1'; }, 'first');
const second = await variant(r => { r.pullRequest.repository = `acme/${long}`; r.runId = '18234567890'; r.runAttempt = '2'; }, 'second');
const a = await saveRun([{ platform: 'ios', zip: first }], {}, environment), b = await saveRun([{ platform: 'ios', zip: second }], {}, environment);
assert.notEqual(a.id, b.id);
assert.equal((await listSavedRuns(environment)).length, 3);
});
test('a commit named by a report is never read as one of git\'s options', async t => {
const { commitSubject } = await import('../../dist/cli/report-commands.js');
const repo = await mkdtemp(join(tmpdir(), 'explore-subject-'));
t.after(() => rm(repo, { recursive: true, force: true }));
for (const args of [['init', '-q'], ['-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'First']]) spawnSync('git', args, { cwd: repo });
const sha = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).stdout.trim();
assert.equal(commitSubject(repo, sha), 'First');
assert.equal(commitSubject(repo, `--output=${join(repo, 'victim')}`), undefined);
await assert.rejects(readFile(join(repo, 'victim')), { code: 'ENOENT' });
});
test('cached captures go after 30 days unused, then the least recently used past the size limit', async t => {
const environment = await cache(t);
const { utimes } = await import('node:fs/promises');
const day = 86_400_000, now = Date.UTC(2026, 9, 15);
const capture = async (sha, usedDaysAgo, bytes) => {
const dir = join(environment.EXPLORE_CACHE_DIR, 'captures', 'ios', sha);
await mkdir(dir, { recursive: true });
await writeFile(join(dir, 'image.png'), Buffer.alloc(bytes));
await writeFile(join(dir, 'cache-metadata.json'), '{}');
const when = new Date(now - usedDaysAgo * day);
await utimes(join(dir, 'cache-metadata.json'), when, when);
return dir;
};
const old = await capture('a'.repeat(40), 40, 10), recent = await capture('b'.repeat(40), 2, 10), newest = await capture('c'.repeat(40), 1, 10);
assert.deepEqual(await pruneCaptureCache(environment, now), [old]);
assert.deepEqual(await pruneCaptureCache(environment, now, { maxAgeDays: 30, maxBytes: 15 }), [recent], 'the least recently used goes first');
assert.deepEqual((await readdir(join(environment.EXPLORE_CACHE_DIR, 'captures', 'ios'))), ['c'.repeat(40)]);
assert.ok(newest);
});
test('a screen accessibility-only on one platform and visibly modified on the other counts as modified, whatever the order', async t => {
const { readZipDirectory, readZipEntry } = await import('../../dist/report/zip-reader.js');
const directory = readZipDirectory(review);
const original = JSON.parse(new TextDecoder().decode(await readZipEntry(review, directory.get('review.json'), 50_000_000)));
const variant = async (platform, verdict) => {
const report = structuredClone(original);
report.review.runtime.platform = platform;
const surface = report.review.surfaces.find(entry => entry.id === 'expo-cats-add-9b770c554b11');
surface.review = { status: 'modified', description: 'Changed accessibility label from “Add” to “Add a cat”.',
facts: [{ category: 'accessibility', templateId: 'accessibility.label-changed', bullet: 'Changed accessibility label from “Add” to “Add a cat”.' }] };
surface.visual = { ...surface.visual, verdict, mismatchPercentage: verdict === 'modified' ? 2.4 : 0 };
const folder = await mkdtemp(join(tmpdir(), 'explore-saved-a11y-'));
t.after(() => rm(folder, { recursive: true, force: true }));
await writeFile(join(folder, 'review.json'), JSON.stringify(report));
return zipReportDirectory(folder);
};
const ios = { platform: 'ios', zip: await variant('ios', 'unchanged') };
const android = { platform: 'android', zip: await variant('android', 'modified') };
const alone = (await describeReports([ios])).changes;
assert.equal(alone['accessibility-only'], 1, 'on iOS alone the screenshots match');
const both = (await describeReports([ios, android])).changes;
assert.equal(both['accessibility-only'], undefined);
assert.equal(both.modified, alone.modified + 1, 'the Android visual change is what the run counts');
assert.deepEqual((await describeReports([android, ios])).changes, both);
});
+24
View File
@@ -327,3 +327,27 @@ test("keeps source provenance while reducing the viewer to route-level screens",
false,
);
});
test("a route family is accessibility-only only when every changed member is", () => {
const family = (statuses) => {
// Screens recorded on one router path are one family.
const members = statuses.map((_, index) => screen(`screen-${index}`, `Policy ${index}`, "/policies", [`variant-${index}`]));
const sourceMap = mapWith(members);
const presentation = presentationModel.presentScreensByPath(sourceMap);
const screens = new Map(members.map((member, index) => {
const [status, accessibilityOnly] = statuses[index];
return [member.id, { status, changeSummary: "", reviewerChanges: [], runtimeEvidenceRefs: [], noVisibleChange: false,
...(status !== "added" ? { beforeScreenshot: `before-${index}.png` } : {}), afterScreenshot: `after-${index}.png`,
...(accessibilityOnly ? { accessibilityOnly: true } : {}) }];
}));
const presented = presentationModel.presentBuildDiff({ baselineId: "build-1", map: sourceMap, index: indexMap(sourceMap), screens,
counts: { added: 0, modified: 0, removed: 0, unchanged: 0 } }, presentation);
assert.equal(presented.screens.size, 1, "the members are one family");
return [...presented.screens.values()][0];
};
assert.equal(family([["modified", true], ["modified", true]]).accessibilityOnly, true);
assert.equal(family([["modified", true], ["unchanged", false]]).accessibilityOnly, true);
// An added or visibly modified member is a visible change, so the family is not accessibility-only.
assert.equal(family([["modified", true], ["added", false]]).accessibilityOnly, undefined);
assert.equal(family([["modified", true], ["modified", false]]).accessibilityOnly, undefined);
});
+95
View File
@@ -0,0 +1,95 @@
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { cleanupAfterCapture, resolveCommit, resolveCompareRefs, writeStepOutputs } from "../../dist/ci/workflow-steps.js";
import { renderWorkflow, workflowIssues } from "../../dist/ci/workflow-install.js";
const git = (cwd, ...args) => {
const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
assert.equal(result.status, 0, result.stderr);
return result.stdout.trim();
};
async function repository(t) {
const root = await realpath(await mkdtemp(join(tmpdir(), "explore-steps-")));
t.after(() => rm(root, { recursive: true, force: true }));
git(root, "init", "-q", "-b", "main");
git(root, "config", "user.email", "[email protected]"); git(root, "config", "user.name", "Test");
await writeFile(join(root, "a.txt"), "1"); git(root, "add", "-A"); git(root, "commit", "-q", "-m", "one"); git(root, "tag", "v1.0.0");
const first = git(root, "rev-parse", "HEAD");
await writeFile(join(root, "a.txt"), "2"); git(root, "commit", "-q", "-am", "two"); git(root, "branch", "release");
const second = git(root, "rev-parse", "HEAD");
return { root, first, second };
}
const environment = { GITHUB_REPOSITORY: "acme/app", GITHUB_REPOSITORY_ID: "42" };
test("ci:compare-refs resolves tags, branches and SHAs to the comparison a capture uses", async t => {
const { root, first, second } = await repository(t);
assert.deepEqual(resolveCompareRefs({ project: root, base: "v1.0.0", head: "release", environment }), {
origin: "compare", repositoryId: "42", repository: "acme/app", title: "release vs v1.0.0",
url: `https://github.com/acme/app/compare/${first}..${second}`,
base: { ref: "v1.0.0", sha: first }, head: { ref: "release", sha: second } });
assert.equal(resolveCompareRefs({ project: root, base: first, head: "HEAD", environment }).title, `HEAD vs ${first.slice(0, 8)}`);
for (const [base, head, code] of [["v1.0.0", "v1.0.0", "COMPARE_SAME_COMMIT"], ["v9", "main", "COMPARE_REF_NOT_FOUND"],
["--upload-pack=x", "main", "COMPARE_REF_INVALID"], ["main", "", "COMPARE_REF_INVALID"], ["a b", "main", "COMPARE_REF_INVALID"]]) {
assert.throws(() => resolveCompareRefs({ project: root, base, head, environment }), error => error.code === code, `${base}..${head}`);
}
});
test("HEAD is the checked-out commit and a local branch beats origin's, while CI's remote-only branches still resolve", async t => {
const { root: upstream, first, second } = await repository(t);
const clone = await realpath(await mkdtemp(join(tmpdir(), "explore-steps-clone-")));
t.after(() => rm(clone, { recursive: true, force: true }));
assert.equal(spawnSync("git", ["clone", "-q", upstream, clone]).status, 0);
git(clone, "config", "user.email", "[email protected]"); git(clone, "config", "user.name", "Test");
git(clone, "commit", "-q", "--allow-empty", "-m", "local only");
const local = git(clone, "rev-parse", "HEAD");
git(clone, "checkout", "-q", "--detach", first);
assert.equal(git(clone, "rev-parse", "refs/remotes/origin/HEAD"), second, "origin/HEAD is not HEAD here");
assert.equal(resolveCommit(clone, "HEAD", "head"), first);
assert.equal(resolveCommit(clone, "@", "head"), first);
assert.equal(resolveCommit(clone, "HEAD~0", "head"), first);
assert.equal(resolveCommit(clone, "main", "base"), local, "your main, not a stale origin/main");
assert.equal(resolveCommit(clone, "origin/main", "base"), second);
assert.equal(resolveCommit(clone, "release", "base"), second, "a branch only origin has, as in a CI checkout");
assert.equal(resolveCommit(clone, "v1.0.0", "base"), first);
});
test("ci:after-capture reports a checkout that capture modified, and passes clean ones and missing ones", async t => {
const { root } = await repository(t);
const output = await mkdtemp(join(tmpdir(), "explore-steps-output-"));
t.after(() => rm(output, { recursive: true, force: true }));
const env = { RUNNER_TEMP: output };
assert.deepEqual(await cleanupAfterCapture({ output, checkouts: [root, join(output, "never-checked-out")], environment: env }), { stopped: [], failures: [] });
await writeFile(join(root, "generated.json"), "{}");
const dirty = await cleanupAfterCapture({ output, checkouts: [root], environment: env });
assert.deepEqual(dirty.failures.map(failure => failure.code), ["CHECKOUT_MODIFIED"]);
assert.equal(JSON.parse(await readFile(join(output, "explore-diagnostics", "cleanup.json"), "utf8")).failures.length, 1);
});
test("step outputs go to GITHUB_OUTPUT one line each, and nowhere outside Actions", async t => {
const directory = await mkdtemp(join(tmpdir(), "explore-steps-outputs-"));
t.after(() => rm(directory, { recursive: true, force: true }));
const path = join(directory, "output");
await writeStepOutputs({ GITHUB_OUTPUT: path }, { base: "a".repeat(40), compare: JSON.stringify({ title: "x\ny" }) });
assert.equal(await readFile(path, "utf8"), `base=${"a".repeat(40)}\ncompare={"title":"x\\ny"}\n`);
await writeStepOutputs({}, { ignored: "1" });
});
test("doctor names a workflow that sets the app directory in one job but not another", async () => {
const layout = { projectDir: "apps/mobile", installDir: ".", manager: "npm", secretNames: [] };
for (const name of ["explore-review.yml", "explore-baseline.yml", "explore-compare.yml"]) {
const rendered = renderWorkflow(await readFile(new URL(`../../templates/${name}`, import.meta.url), "utf8"), layout);
assert.deepEqual([...rendered.matchAll(/APP_PROJECT_DIR: (.*)/g)].map(match => match[1]), ["apps/mobile"], `${name} sets it once, for every job`);
assert.deepEqual(workflowIssues(name, rendered, layout), []);
}
// Workflows generated before this release set it per job, and only the first was rendered.
const older = "env:\n EXPLORE_VERSION: 1.0.0\njobs:\n a:\n env:\n APP_PROJECT_DIR: apps/mobile\n APP_INSTALL_DIR: .\n b:\n env:\n APP_PROJECT_DIR: .\n APP_INSTALL_DIR: .\n";
const issues = workflowIssues("review", older, layout);
assert.deepEqual(issues.map(issue => issue.code), ["WORKFLOW_APP_DIR_MISMATCH"]);
assert.match(issues[0].message, /APP_PROJECT_DIR is \. in one of its jobs/);
});
+68 -43
View File
@@ -1,5 +1,4 @@
import assert from "node:assert/strict";
import { createRequire } from "node:module";
import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -7,37 +6,42 @@ import test from "node:test";
import { parse } from "yaml";
const workflow = parse(await readFile(new URL("../../templates/explore-review.yml", import.meta.url), "utf8"));
const require = createRequire(import.meta.url);
const scriptFor = (job, name) => workflow.jobs[job].steps.find(step => step.name === name).with.script;
const execute = (source, github, context, core, processEnv) => new Function("github", "context", "core", "require", "process",
`return (async () => {${source}\n})();`)(github, context, core, require, { env: processEnv });
const context = { repo: { owner: "acme", repo: "app" }, runId: 1234 };
const { resolvePullRequest, findBaselineArtifact, findOptionalBaseline } = await import("../../dist/ci/workflow-steps.js");
const environment = { GITHUB_REPOSITORY: "acme/app", GITHUB_TOKEN: "test-token" };
const samplePr = () => ({
state: "open", draft: false, number: 91, title: "PR", html_url: "https://github.com/acme/app/pull/91", user: { login: "author" },
base: { ref: "main", sha: "a".repeat(40), repo: { id: 12, full_name: "acme/app" } },
base: { ref: "main", sha: "a".repeat(40), repo: { id: 12, full_name: "acme/app", default_branch: "main" } },
head: { ref: "feature/settings", sha: "b".repeat(40), repo: { full_name: "acme/app" } },
});
async function authorize(t, { pr = samplePr(), permission = "write", number = "91", config } = {}) {
const directory = await mkdtemp(join(tmpdir(), "explore-workflow-"));
t.after(() => rm(directory, { recursive: true, force: true }));
const outputs = {};
await execute(scriptFor("capture", "Resolve the live pull request and authorize its source"), { rest: {
pulls: { get: async () => ({ data: pr }) },
repos: {
getCollaboratorPermissionLevel: async () => ({ data: { permission } }),
getContent: async ({ path }) => {
assert.equal(path, ".expo-explore/config.yaml");
if (config === undefined) throw Object.assign(new Error("Not Found"), { status: 404 });
return { data: { content: Buffer.from(config).toString("base64") } };
},
},
} }, context, { setOutput: (key, value) => { outputs[key] = value; } }, {
RUNNER_TEMP: directory, PR_NUMBER: number,
});
return { metadata: JSON.parse(await readFile(join(directory, "explore-pr.json"), "utf8")), outputs };
/** `ci:pr` against a GitHub that answers with this PR, the author's permission, and the default branch's config. */
async function authorize(t, { pr = samplePr(), permission = "write", number = "91", config, configStatus } = {}) {
const transport = async (input, init = {}) => {
const url = new URL(input);
assert.equal(init.headers?.authorization, "Bearer test-token");
if (url.pathname === "/repos/acme/app/pulls/91") return Response.json(pr);
if (url.pathname === `/repos/acme/app/collaborators/${encodeURIComponent(pr.user.login)}/permission`) return Response.json({ permission });
if (url.pathname === "/repos/acme/app/contents/.expo-explore/config.yaml") {
assert.equal(url.searchParams.get("ref"), "main", "trust comes from the default branch, never the PR");
if (configStatus) return new Response("boom", { status: configStatus });
return config === undefined ? new Response("Not Found", { status: 404 }) : Response.json({ content: Buffer.from(config).toString("base64") });
}
throw new Error(`unexpected request ${url}`);
};
const { presentation } = await resolvePullRequest({ number: Number(number), environment, transport });
return { metadata: presentation, outputs: { pr_number: presentation.number } };
}
test("the review workflow resolves and authorizes the PR with ci:pr from the installed release, in both jobs that need it", () => {
for (const job of ["platforms", "capture"]) {
const step = workflow.jobs[job].steps.find(step => step.id === "pr");
assert.match(step.run, /cli\.js" ci:pr --pr "\$PR_NUMBER"/);
assert.equal(step.env.GITHUB_TOKEN, "${{ github.token }}");
assert.ok(workflow.jobs[job].steps.indexOf(step) < workflow.jobs[job].steps.findIndex(step => step.uses?.startsWith("actions/checkout@")), `${job}: authorize before checking out PR code`);
}
assert.equal(JSON.stringify(workflow).includes("actions/github-script"), false);
});
test("live API metadata is used for public and private PR branch identity", async t => {
for (const privateRepo of [true, false]) {
const pr = samplePr();
@@ -52,14 +56,13 @@ test("forks, closed/draft PRs, invalid numbers, and revoked author write permiss
for (const mutate of [pr => { pr.head.repo.full_name = "fork/app"; }, pr => { pr.head.repo = null; },
pr => { pr.draft = true; }, pr => { pr.state = "closed"; }]) {
const pr = samplePr(); mutate(pr);
await assert.rejects(authorize(t, { pr }), /SOURCE_NOT_TRUSTED/);
await assert.rejects(authorize(t, { pr }), /Capture requires an open, non-draft same-repository pull request/);
}
for (const permission of ["read", "triage", "none"]) await assert.rejects(authorize(t, { permission }), /write access/);
for (const number of ["", "NaN", "0", "-2", "1.5"]) await assert.rejects(authorize(t, { number }), /PR_NUMBER_INVALID/);
for (const number of ["", "NaN", "0", "-2", "1.5"]) await assert.rejects(authorize(t, { number }), error => error.code === "PR_NUMBER_INVALID");
});
test("baseline restore rejects foreign workflows, revisions, branches, and unfinished runs", async () => {
const outputs = {};
const valid = { id: 20, workflow_id: 77, conclusion: "success", head_sha: "a".repeat(40), head_branch: "main",
event: "push", head_repository: { full_name: "acme/app" } };
const mutations = [
@@ -70,15 +73,30 @@ test("baseline restore rejects foreign workflows, revisions, branches, and unfin
runs[20] = valid;
const artifacts = Object.keys(runs).map(id => ({ id: Number(id), workflow_run: { id: Number(id) }, expired: false }));
artifacts.push({ id: 99, expired: true, workflow_run: { id: 99 } });
await execute(scriptFor("capture", "Find optional exact-base evidence"), {
paginate: async () => artifacts,
rest: {
repos: { get: async () => ({ data: { default_branch: "main" } }) },
actions: { getWorkflow: async () => ({ data: { id: 77 } }), listArtifactsForRepo() {},
getWorkflowRun: async ({ run_id }) => ({ data: runs[run_id] }) },
},
}, context, { setOutput: (key, value) => { outputs[key] = value; } }, { BASE_SHA: "a".repeat(40) });
assert.deepEqual(outputs, { id: 20, run: 20 });
const names = [];
const transport = async input => {
const url = new URL(input);
if (url.pathname === "/repos/acme/app") return Response.json({ default_branch: "main" });
if (url.pathname === "/repos/acme/app/actions/workflows/explore-baseline.yml") return Response.json({ id: 77 });
if (url.pathname === "/repos/acme/app/actions/artifacts") {
names.push(url.searchParams.get("name"));
return Response.json({ artifacts: url.searchParams.get("name").endsWith("-ios") ? artifacts : [] });
}
const run = /^\/repos\/acme\/app\/actions\/runs\/(\d+)$/.exec(url.pathname);
if (run) return Response.json(runs[run[1]]);
throw new Error(`unexpected request ${url}`);
};
assert.deepEqual(await findBaselineArtifact({ sha: "a".repeat(40), platform: "ios", environment, transport }), { id: 20, run: 20 });
assert.deepEqual(names, [`explore-baseline-${"a".repeat(40)}-ios`, `explore-baseline-${"a".repeat(40)}`], "iOS also accepts the unsuffixed name older baselines used");
});
test("a failed baseline lookup is a warning and no baseline, never an error a failure comment could blame", async () => {
const outage = async () => new Response("bad gateway", { status: 502 });
const result = await findOptionalBaseline({ sha: "a".repeat(40), platform: "ios", environment, transport: outage });
assert.equal(result.baseline, undefined);
assert.equal(result.warning.code, "GITHUB_REQUEST_FAILED");
assert.match(result.warning.message, /^No baseline is reused, so capture captures the base too: GitHub answered HTTP 502/);
assert.deepEqual(await findOptionalBaseline({ sha: "a".repeat(40), environment, transport: async () => new Response("", { status: 404 }) }), {}, "no baseline workflow: nothing to say");
});
const { publishFailureComment } = await import("../../dist/report/failure-comment.js");
@@ -233,13 +251,20 @@ test("ci.trustedAuthors on the default branch admits listed authors without writ
await assert.rejects(authorize(t, { pr: bot, permission: "read", config: "ci:\n trustedAuthors: []\n" }), /write access/);
await assert.rejects(authorize(t, { pr: bot, permission: "read", config: "report:\n preview:\n hosting: eas\n" }), /write access/);
const fork = samplePr(); fork.user.login = "devin-ai-integration[bot]"; fork.head.repo.full_name = "fork/app";
await assert.rejects(authorize(t, { pr: fork, permission: "read", config: block }), /SOURCE_NOT_TRUSTED/);
await assert.rejects(authorize(t, { pr: fork, permission: "read", config: block }), error => error.code === "SOURCE_NOT_TRUSTED");
const draft = samplePr(); draft.user.login = "devin-ai-integration[bot]"; draft.draft = true;
await assert.rejects(authorize(t, { pr: draft, permission: "read", config: block }), /SOURCE_NOT_TRUSTED/);
await assert.rejects(authorize(t, { pr: draft, permission: "read", config: block }), error => error.code === "SOURCE_NOT_TRUSTED");
await assert.rejects(authorize(t, { pr: bot, permission: "read", config: "x: [\n" }), /write access/);
// A list that fails validation trusts no one, and the refusal says the list was ignored and why.
await assert.rejects(authorize(t, { pr: bot, permission: "read", config: "ci:\n trustedAuthors: [\"devin-ai-integration[bot]\", \"not a login\"]\n" }), error => {
assert.equal(error.code, "SOURCE_NOT_TRUSTED");
assert.match(error.message, /The default branch's ci\.trustedAuthors was ignored: .*trustedAuthors\[1\]/);
assert.match(error.nextAction, /^Fix ci\.trustedAuthors/);
return true;
});
// Only the list is read: a default-branch config written for another release, with keys this one does not know,
// still trusts its bots.
assert.equal((await authorize(t, { pr: bot, permission: "read", config: "ci:\n trustedAuthors: [\"devin-ai-integration[bot]\"]\n someLaterKey: true\nlaterSection: {}\n" })).outputs.pr_number, 91);
const server = samplePr(); server.user.login = "devin-ai-integration[bot]";
await assert.rejects(execute(scriptFor("capture", "Resolve the live pull request and authorize its source"), { rest: {
pulls: { get: async () => ({ data: server }) },
repos: { getCollaboratorPermissionLevel: async () => ({ data: { permission: "read" } }), getContent: async () => { throw Object.assign(new Error("boom"), { status: 500 }); } },
} }, context, { setOutput() {} }, { RUNNER_TEMP: tmpdir(), PR_NUMBER: "91" }), /boom/);
await assert.rejects(authorize(t, { pr: server, permission: "read", configStatus: 500 }), error => error.code === "GITHUB_REQUEST_FAILED" && error.retryable);
});
+18
View File
@@ -0,0 +1,18 @@
// The preview Worker shares the agent API with the CLI's local report server: src/report/agent-api.ts and
// zip-reader.ts at the repository root. Metro only bundles files under its watch folders, and those files import
// each other with the `.js` extensions the CLI's NodeNext build needs, which name `.ts` sources here.
const path = require("node:path");
const { getDefaultConfig } = require("expo/metro-config");
const shared = path.resolve(__dirname, "../src/report");
const config = getDefaultConfig(__dirname);
config.watchFolders = [...(config.watchFolders ?? []), shared];
const resolveRequest = config.resolver.resolveRequest;
config.resolver.resolveRequest = (context, moduleName, platform) => {
const resolve = resolveRequest ?? context.resolveRequest;
if (moduleName.startsWith("./") && moduleName.endsWith(".js") && context.originModulePath.startsWith(`${shared}${path.sep}`)) {
return resolve(context, moduleName.slice(0, -".js".length), platform);
}
return resolve(context, moduleName, platform);
};
module.exports = config;
+1 -1
View File
@@ -5,7 +5,7 @@
* only in that environment, and streams it. Static files on the CDN are ciphertext; the Viewer
* bundle under /viewer/ is public and identical to the central host's.
*/
import { AGENT_API_VERSION, agentApiReply, agentIndexHtml, agentIndexMarkdown, loadReport, prefersHtml, type AgentContext, type LoadedReport } from "./agent-api";
import { AGENT_API_VERSION, agentApiReply, agentIndexHtml, agentIndexMarkdown, loadReport, prefersHtml, type AgentContext, type LoadedReport } from "../../../src/report/agent-api";
export type PreviewEnvironment = {
/** Lowercase base32 path token the review comment links to. */
+52 -4
View File
@@ -4,8 +4,8 @@ import { webcrypto, createHash } from "node:crypto";
import { deflateRawSync } from "node:zlib";
import { readFileSync } from "node:fs";
import { PREVIEW_CIPHER, previewResponse, type PreviewEnvironment } from "../src/server/preview";
import { loadReport, prefersHtml, prefersMarkdown } from "../src/server/agent-api";
import { readZipDirectory } from "../src/server/report-zip";
import { agentApiReply, agentIndexMarkdown, loadReport, prefersHtml, prefersMarkdown } from "../../src/report/agent-api";
import { readZipDirectory } from "../../src/report/zip-reader";
const subtle = webcrypto.subtle as SubtleCrypto;
const token = "abcdefghijklmnopqrstuvwxyz234567";
@@ -105,7 +105,7 @@ test("the token page negotiates: browsers get the shell carrying the agent index
const shell = await browser.text();
assert.ok(shell.startsWith("<!doctype html>"));
assert.match(shell, /<div id="root"><section data-explore-agent-index style="[^"]*clip:rect\(0 0 0 0\)[^"]*"><h1>Expo Explore report: .* PR #\d+/);
assert.match(shell, new RegExp(`href="${origin}/p/${token}/api/v1/screens\\?status=modified,added,removed"`));
assert.match(shell, new RegExp(`href="${origin}/p/${token}/api/v1/screens\\?status=modified,accessibility-only,added,removed"`));
assert.match(shell, /<\/section><\/div><script type="module"/);
assert.equal(browser.headers.get("vary"), "Accept");
assert.equal(browser.headers.get("link"), `<${origin}/p/${token}/api/v1>; rel="alternate"; type="application/json", <${origin}/p/${token}/llms.txt>; rel="alternate"; type="text/markdown"`);
@@ -119,7 +119,7 @@ test("the token page negotiates: browsers get the shell carrying the agent index
const body = await response.text();
assert.match(body, /^# Expo Explore report: /, String(accept));
assert.match(body, /This link stops serving the report after 2030-01-01T00:00:00.000Z/);
assert.ok(body.includes(`(${origin}/p/${token}/api/v1/screens?status=modified,added,removed)`), body);
assert.ok(body.includes(`(${origin}/p/${token}/api/v1/screens?status=modified,accessibility-only,added,removed)`), body);
assert.equal(response.headers.get("content-security-policy"), browser.headers.get("content-security-policy"));
}
const llms = await site.get("/llms.txt", "text/html");
@@ -286,3 +286,51 @@ test("Accept negotiation honours quality values and listing order, and wildcards
assert.equal(prefersMarkdown("text/markdown;q=0"), false);
assert.equal(prefersMarkdown("*/*"), false);
});
test("screens count and filter by what changed visibly: a source change with matching captures is unchanged, even from an older report", async () => {
const surface = (id: string, status: string, review: { status: string; description: string }) =>
({ id, status, sourceScope: "screen", head: { route: `/${id}`, kind: "screen" }, base: { route: `/${id}`, kind: "screen" }, review });
const report = { kind: "explore.report", review: { contract: "explore.review", pullRequest: { origin: "local", repository: "a/b", title: "HEAD vs main", base: { ref: "main", sha: "a".repeat(40) }, head: { ref: "HEAD", sha: "b".repeat(40) } },
runtime: { platform: "ios" }, surfaces: [
surface("tempo", "modified", { status: "modified", description: "Added text “Beat pulse”." }),
surface("enable-midi", "modified", { status: "needs-review", description: "Source changed; no visible difference was captured." }),
surface("lane-editor", "modified", { status: "needs-review", description: "Visual comparison was inconclusive" }),
] }, assets: [] };
const loaded = (await loadReport(zip({ "review.json": new TextEncoder().encode(JSON.stringify(report)) })))!;
const context = { pageUrl: "http://127.0.0.1:1/p/t", platforms: ["ios"], expiresAt: null };
const summary = JSON.parse((await agentApiReply(context, loaded, "", new URLSearchParams(), "application/json")).body as string);
assert.deepEqual(summary.screens, { total: 3, modified: 1, unchanged: 1, "needs-review": 1 });
const modified = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams("status=modified"), "application/json")).body as string);
assert.deepEqual(modified.items.map((item: { id: string }) => item.id), ["tempo"]);
const all = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams(), "application/json")).body as string);
const midi = all.items.find((item: { id: string }) => item.id === "enable-midi");
assert.deepEqual([midi.status, midi.sourceStatus], ["unchanged", "modified"], "its source status is still there");
});
test("statuses follow the Viewer: accessibility-only, unavailable for a failed or misattributed capture, not-compared for the rest", async () => {
const side = (id: string) => ({ route: `/${id}`, kind: "screen" });
const verified = { status: "captured", landing: "verified", attempts: 1 };
const surface = (id: string, verdict: string) => ({ id, status: "modified", sourceScope: "screen", head: side(id), base: side(id),
headImage: { sha256: "c".repeat(64) }, baseImage: { sha256: "c".repeat(64) }, headOutcome: verified, baseOutcome: verified,
review: { status: "modified", description: "Added button “Edit tempo”." }, visual: { verdict, reason: "matched", threshold: 0.1, tool: "agent-device" } });
const report = { kind: "explore.report", review: { contract: "explore.review", pullRequest: { origin: "local", repository: "a/b", title: "HEAD vs main", base: { ref: "main", sha: "a".repeat(40) }, head: { ref: "HEAD", sha: "b".repeat(40) } },
runtime: { platform: "ios" }, surfaces: [surface("tempo", "modified"), surface("device-picker", "unchanged"),
// Its source changed but nothing was compared: not a change Explore saw.
{ id: "c-explore", status: "modified", sourceScope: "screen", head: side("c/_explore"), base: side("c/_explore") },
// Its head capture failed, and another landed on the wrong screen: both unavailable, as the Viewer says.
{ id: "cards", status: "modified", sourceScope: "screen", head: side("cards"), base: side("cards"), baseImage: { sha256: "c".repeat(64) },
baseOutcome: verified, headOutcome: { status: "failed", attempts: 1, landing: "unverified" } },
{ id: "login", status: "modified", sourceScope: "screen", head: side("login"), base: side("login"), ...{ baseImage: { sha256: "c".repeat(64) }, headImage: { sha256: "c".repeat(64) } },
baseOutcome: verified, headOutcome: { status: "captured", attempts: 2, landing: "unverified", observed: { reason: "landing-mismatch", route: "/home", attempts: 2 } } }] }, assets: [] };
const loaded = (await loadReport(zip({ "review.json": new TextEncoder().encode(JSON.stringify(report)) })))!;
const context = { pageUrl: "http://127.0.0.1:1/p/t", platforms: ["ios"], expiresAt: null };
const summary = JSON.parse((await agentApiReply(context, loaded, "", new URLSearchParams(), "application/json")).body as string);
assert.deepEqual(summary.screens, { total: 5, modified: 1, "accessibility-only": 1, "not-compared": 1, unavailable: 2 });
const unavailable = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams("status=unavailable"), "application/json")).body as string);
assert.deepEqual(unavailable.items.map((item: { id: string }) => item.id), ["cards", "login"]);
// The index sentence names every status, so its parts add up to the total.
assert.match(agentIndexMarkdown(context, loaded), /5 screens: 1 modified, 1 accessibility only \(screenshots match, the accessibility tree does not\), 2 unavailable, 1 not compared\./);
assert.match(summary.links.changed, /status=modified,accessibility-only,added,removed/);
const only = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams("status=accessibility-only"), "application/json")).body as string);
assert.deepEqual(only.items.map((item: { id: string; status: string; sourceStatus: string }) => [item.id, item.status, item.sourceStatus]), [["device-picker", "accessibility-only", "modified"]]);
});
+4 -10
View File
@@ -12,7 +12,7 @@ import { AppLoading } from "./components/shared/app-loading";
import { ReportLoadingShell } from "./components/shared/report-loading-shell";
import { screenLabel } from "./utils/screen-path";
import { AppPill, PLATFORM_NAMES } from "./components/panels/app-pill";
import { changedScreens, isVisibleChange, type ChangedScreen } from "./utils/changed-screens";
import { changedScreens, focusCounts as countFocusStatuses, isCapturedChange, type ChangedScreen } from "./utils/changed-screens";
import { MapView } from "./components/views/semantic-map";
import { RightPanel } from "./components/panels/right";
import { SearchCommand } from "./components/search-command";
@@ -1181,16 +1181,10 @@ function ViewerApp() {
), [presentedMap, workspace]);
// Focus singles out diff states, so it means nothing without a baseline to diff against.
const focusFilter = diff ? route.focus : [];
const focusCounts = {
added: diff?.counts.added ?? 0,
modified: diff?.counts.modified ?? 0,
removed: diff?.counts.removed ?? 0,
"needs-review": diff?.counts["needs-review"] ?? 0,
"source-affected": diff?.counts["source-affected"] ?? 0,
};
const focusCounts = useMemo(() => countFocusStatuses(diff), [diff]);
const index = diff?.index ?? screenPresentation?.index;
const compareOrder = useMemo(
() => (diff && index ? changedScreens(diff, index).filter(entry => isVisibleChange(diff.screens.get(entry.id))) : []),
() => (diff && index ? changedScreens(diff, index).filter(entry => isCapturedChange(diff.screens.get(entry.id))) : []),
[diff, index],
);
compareOrderRef.current = compareOrder;
@@ -1487,7 +1481,7 @@ function ViewerApp() {
onOpenChange: setChangesOpen,
} : undefined;
// A hosted preview serves an agent-readable index of this report, so it can be handed to an agent.
// A hosted preview, or a local review's Viewer, serves an agent-readable index of this report, so it can be handed to an agent.
const handoffUrl = typeof window === "undefined" ? undefined : handoffPageUrl(new URL(window.location.href));
const handoffInput = handoffUrl ? {
pageUrl: handoffUrl,
+5 -4
View File
@@ -1,15 +1,16 @@
import { diffLabel, type DiffStatus } from "../../utils/build-diff";
import { diffClass, diffLabel, type DiffStatus } from "../../utils/build-diff";
/**
* Colour ring + label chip around a screenshot item on any canvas. It sits outside the
* item's box (negative margins) so layout geometry is untouched. Renders as a span so it can
* sit inside a button.
*/
export function DiffFrame(props: { status?: DiffStatus | undefined; notVisible?: boolean | undefined; children: React.ReactNode }) {
export function DiffFrame(props: { status?: DiffStatus | undefined; accessibilityOnly?: boolean | undefined; children: React.ReactNode }) {
const status = props.status ?? "unchanged";
const label = diffLabel({ status, ...(props.notVisible ? { notVisible: true as const } : {}) });
const diff = { status, ...(props.accessibilityOnly ? { accessibilityOnly: true as const } : {}) };
const label = diffLabel(diff);
return (
<span className={`diff-frame diff-${status}`}>
<span className={`diff-frame ${diffClass(diff)}`}>
{status !== "unchanged" && (
<span className="diff-label" aria-label={`${label} in this build`}>
{label}
@@ -1,6 +1,6 @@
import type { CSSProperties, MouseEventHandler, ReactNode } from "react";
import { ImageOff, PanelRight } from "lucide-react";
import type { DiffStatus } from "../../utils/build-diff";
import { diffClass, type DiffStatus } from "../../utils/build-diff";
import { ScreenPathText } from "../shared/screen-path-text";
import { DEFAULT_SCREENSHOT_SIZE, ScreenshotImage } from "../shared/screenshot-image";
import { CanvasActiveFrame } from "./active-frame";
@@ -15,8 +15,8 @@ export type ScreenScreenshotCardProps = {
/** Shown in place of the image when the run recorded why there is none. */
missingReason?: string;
diff?: DiffStatus;
/** A modified screen whose screenshots match: the label says the change is not visible. */
notVisible?: boolean;
/** A modified screen whose screenshots match: the label says only what assistive technology reads changed. */
accessibilityOnly?: boolean;
className?: string;
style?: CSSProperties;
selected?: boolean;
@@ -56,7 +56,7 @@ export function ScreenScreenshotCard(props: ScreenScreenshotCardProps) {
"screen-screenshot-card",
props.className,
// The status class carries the frame colour to the card, so its handles can share it.
props.diff ? `diff-${props.diff}` : undefined,
props.diff ? diffClass({ status: props.diff, ...(props.accessibilityOnly ? { accessibilityOnly: true as const } : {}) }) : undefined,
props.selected ? "selected" : undefined,
props.highlighted ? "highlighted" : undefined,
].filter(Boolean).join(" ");
@@ -92,7 +92,7 @@ export function ScreenScreenshotCard(props: ScreenScreenshotCardProps) {
aria-label={props.ariaLabel ?? `Open ${props.plainTitle ? props.title : props.path}`}
{...(props.ariaPressed !== undefined ? { "aria-pressed": props.ariaPressed } : {})}
onClick={props.onClick}>
<DiffFrame status={props.diff} notVisible={props.notVisible}>
<DiffFrame status={props.diff} accessibilityOnly={props.accessibilityOnly}>
<span className={`screen-node-image${props.screenshot ? " has-screenshot" : " is-missing"}`}>
{props.screenshot ? (
<ScreenshotImage
@@ -1,4 +1,4 @@
import { useEffect, useRef } from "react";
import { useEffect, useId, useRef } from "react";
import { ChevronLeft, ChevronRight, List } from "lucide-react";
import { ChangesMenu } from "../panels/changes-menu";
import { StatusGlyph } from "../shared/status-icon";
@@ -15,6 +15,8 @@ import type { ComparePicker } from "./compare-section";
*/
export function CompareNav(props: {
status: DiffStatus;
/** Modified only in what assistive technology reads: the mark takes that status's colour and shape. */
accessibilityOnly?: boolean | undefined;
route: string;
title: string;
/** Zero-based; below zero when the screen is not in the order. */
@@ -39,7 +41,7 @@ export function CompareNav(props: {
disabled={!desktop || picker.open}>
<button type="button" className="compare-nav-picker" aria-haspopup="true"
aria-expanded={picker.open} onClick={() => picker.onOpenChange(!picker.open)}>
<StatusGlyph status={props.status} label={props.statusLabel ?? DIFF_LABELS[props.status]} />
<StatusGlyph status={props.status} accessibilityOnly={props.accessibilityOnly} label={props.statusLabel ?? DIFF_LABELS[props.status]} />
{/* A route that does not fit loses its start, not the end that names the screen. */}
<code className="compare-nav-route" title={props.title}><bdi>{props.route}</bdi></code>
</button>
@@ -87,9 +89,12 @@ export function CompareSteps(props: {
/**
* What changed on a screen, as the phone's sheet and the desktop popover both list it: CI's
* findings as bullets, then the notes about the comparison under a hairline.
* findings as bullets, then what changed for assistive technology under its own heading, then the
* notes about the comparison under a hairline.
*/
export function WhatChangedContent(props: { facts: string[]; notes: string[] }) {
export function WhatChangedContent(props: { facts: string[]; assistive?: string[]; accessibilityOnly?: boolean | undefined; notes: string[] }) {
const assistive = props.assistive ?? [];
const assistiveTitle = useId();
return (
<div className="what-changed-content" role="region" aria-label="What changed on this screen">
{props.facts.length > 0 ? (
@@ -97,6 +102,22 @@ export function WhatChangedContent(props: { facts: string[]; notes: string[] })
{props.facts.map((fact) => <li key={fact}>{fact}</li>)}
</ul>
) : null}
{assistive.length > 0 ? (
<section className="what-changed-assistive" aria-labelledby={assistiveTitle}>
<h4 id={assistiveTitle} className="what-changed-assistive-title">
<span className="status-glyph-dot diff-accessibility-only" aria-hidden="true" />
For assistive technology
</h4>
<p className="what-changed-assistive-context">
{props.accessibilityOnly
? "Before and After look the same. Only what screen readers and voice control read changed."
: "Read by screen readers and voice control, not shown in the screenshot."}
</p>
<ul className="what-changed-content-list">
{assistive.map((fact) => <li key={fact}>{fact}</li>)}
</ul>
</section>
) : null}
{props.notes.length > 0 ? (
<div className="what-changed-content-notes">
{props.notes.map((note) => <p key={note}>{note}</p>)}
@@ -113,13 +134,15 @@ export function WhatChangedContent(props: { facts: string[]; notes: string[] })
*/
export function WhatChangedPopover(props: {
facts: string[];
assistive?: string[];
accessibilityOnly?: boolean | undefined;
notes: string[];
open: boolean;
onOpenChange: (open: boolean) => void;
}) {
const ref = useRef<HTMLDivElement>(null);
const { open, onOpenChange } = props;
const empty = props.facts.length === 0 && props.notes.length === 0;
const empty = props.facts.length === 0 && !props.assistive?.length && props.notes.length === 0;
useEffect(() => {
if (!open) return;
const onPointerDown = (event: PointerEvent) => {
@@ -149,8 +172,11 @@ export function WhatChangedPopover(props: {
</Tooltip>
{open ? (
<div className="compare-what-changed-popover" role="dialog" aria-modal="false" aria-label="What changed">
<strong className="compare-what-changed-popover-title">What changed</strong>
<WhatChangedContent facts={props.facts} notes={props.notes} />
{/* A screen that changed only for assistive technology has nothing else to title. */}
{props.facts.length > 0 || props.notes.length > 0
? <strong className="compare-what-changed-popover-title">What changed</strong> : null}
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
accessibilityOnly={props.accessibilityOnly} notes={props.notes} />
</div>
) : null}
</div>
@@ -196,6 +196,13 @@
}
.what-changed-content-list > li::marker { color: var(--tertiary); }
.what-changed-content-notes { display: flex; flex-direction: column; gap: 6px; }
/* What changed for assistive technology: its own heading, led by Accessibility only's blue square. */
.what-changed-assistive { display: flex; flex-direction: column; gap: 6px; }
.what-changed-content-list + .what-changed-assistive { padding-top: 12px; border-top: 1px solid var(--panel-line); }
.what-changed-assistive-title { display: flex; align-items: center; gap: 8px; margin: 0; color: var(--text); font-size: 13px; font-weight: 600; line-height: 18px; }
.what-changed-assistive-title > .status-glyph-dot { width: 8px; height: 8px; border-radius: 2px; background: var(--diff); }
.what-changed-assistive-context { margin: 0; color: var(--secondary); font-size: 12px; line-height: 17px; }
.what-changed-assistive + .what-changed-content-notes { padding-top: 12px; border-top: 1px solid var(--panel-line); }
.what-changed-content-list + .what-changed-content-notes { padding-top: 12px; border-top: 1px solid var(--panel-line); }
.what-changed-content-notes > p { margin: 0; color: var(--secondary); font-size: 12px; line-height: 17px; }
@@ -1,7 +1,7 @@
import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, type CSSProperties, type ReactNode, type RefObject } from "react";
import { ImageOff, ScanSearch } from "lucide-react";
import type { ChangesMenuData } from "../panels/changes-menu";
import { diffLabel, NOT_VISIBLE_HIGHLIGHT, type BuildDiff, type ScreenDiff } from "../../utils/build-diff";
import { diffLabel, ACCESSIBILITY_ONLY_HIGHLIGHT, type BuildDiff, type ScreenDiff } from "../../utils/build-diff";
import type { MapIndex } from "../../utils/model";
import type { ChangedScreen } from "../../utils/changed-screens";
import { groupVisualRegions, type VisualChange } from "../../utils/visual-diff";
@@ -13,7 +13,7 @@ import { ToggleGroup } from "../shared/toggle-group";
import { Tooltip } from "../shared/tooltip";
import { DEFAULT_SCREENSHOT_RATIO, ScreenshotImage, ScreenshotPlaceholder } from "../shared/screenshot-image";
import { ChangeOutlines, HomeIndicatorBand, StatusBarBand, SwipeCompare, SWIPE_STEP } from "../panels/visual-diff";
import { placeholderFor, presentedChanges } from "../../utils/presented-changes";
import { placeholderFor, presentedChanges, splitForAssistiveTechnology } from "../../utils/presented-changes";
import { CompareNav, WhatChangedPopover } from "./compare-header";
import "./compare-section.css";
@@ -105,6 +105,8 @@ export function useCompareController(options: CompareControllerOptions) {
() => presentedChanges(screenDiff).filter((change) => change.id !== "legacy-summary"),
[screenDiff],
);
// What changed for assistive technology is listed under its own heading.
const split = useMemo(() => splitForAssistiveTechnology(facts, screenDiff), [facts, screenDiff]);
const phone = usePhoneLayout();
const [desktopMode, setDesktopMode] = useState<CompareMode>(() => storedMode(MODE_STORAGE_KEY, "split"));
@@ -239,7 +241,7 @@ export function useCompareController(options: CompareControllerOptions) {
const chosenMode: CompareMode = phone ? phoneMode : desktopMode;
const modesDisabled = !comparable;
return {
screen, screenDiff, route, position, previous, next, comparable, areas, facts,
screen, screenDiff, route, position, previous, next, comparable, areas, facts, split,
mode, chosenMode, modesDisabled, chooseMode, modeOptions, outlines, shownOutlines, statusBarIgnored, homeIndicatorIgnored, toggleOutlines,
activeArea, setActiveArea, stepArea, flipSide, flip, swipePosition, setSwipePosition,
aspect, setAspect, factsOpen, setFactsOpen,
@@ -318,8 +320,9 @@ export function CompareSection(props: CompareSectionProps) {
</>
) : null;
const factCopies = facts.map((fact) => fact.copy);
const notes = compareNotes(screenDiff, factCopies.length, statusBarIgnored, homeIndicatorIgnored);
const factCopies = compare.split.visible.map((fact) => fact.copy);
const assistive = compare.split.assistive.map((fact) => fact.copy);
const notes = compareNotes(screenDiff, facts.length, statusBarIgnored, homeIndicatorIgnored);
return (
<section ref={sectionRef} className="compare-section" aria-label={`Compare ${route}`}
@@ -328,7 +331,7 @@ export function CompareSection(props: CompareSectionProps) {
how to look at it, and what to look for. The bottom toolbar stays the same on every section. */}
<header className="compare-top">
<div className="compare-bar">
<CompareNav variant="desktop" status={screenDiff.status} statusLabel={diffLabel(screenDiff)} route={route} title={title}
<CompareNav variant="desktop" status={screenDiff.status} accessibilityOnly={screenDiff.accessibilityOnly} statusLabel={diffLabel(screenDiff)} route={route} title={title}
position={compare.position} count={props.order.length} picker={props.picker}
onPrevious={compare.previous ? () => props.onSelectScreen(compare.previous!.id) : undefined}
onNext={compare.next ? () => props.onSelectScreen(compare.next!.id) : undefined} />
@@ -345,13 +348,14 @@ export function CompareSection(props: CompareSectionProps) {
/>
</div>
<span className="toolbar-divider" aria-hidden="true" />
<Tooltip label={screenDiff.notVisible ? NOT_VISIBLE_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom">
<Tooltip label={screenDiff.accessibilityOnly ? ACCESSIBILITY_ONLY_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom">
<button type="button" className="toolbar-button compare-outlines" aria-label="Highlight changes"
aria-pressed={outlines} disabled={areas.length === 0} onClick={toggleOutlines}>
<ScanSearch aria-hidden="true" />
</button>
</Tooltip>
<WhatChangedPopover facts={factCopies} notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
<WhatChangedPopover facts={factCopies} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
</div>
</header>
@@ -44,11 +44,14 @@ function ReviewModes(props: {
*/
function WhatChangedAccordion(props: {
facts: string[];
assistive?: string[];
accessibilityOnly?: boolean | undefined;
notes: string[];
open: boolean;
onOpenChange?: (open: boolean) => void;
}) {
const empty = !props.onOpenChange || (props.facts.length === 0 && props.notes.length === 0);
const count = props.facts.length + (props.assistive?.length ?? 0);
const empty = !props.onOpenChange || (count === 0 && props.notes.length === 0);
const open = props.open && !empty;
return (
<section className="what-changed-accordion">
@@ -60,7 +63,7 @@ function WhatChangedAccordion(props: {
onClick={() => props.onOpenChange?.(!props.open)}>
<span className="what-changed-toggle-title">
What changed
{props.facts.length > 0 ? <span className="what-changed-toggle-count">{props.facts.length}</span> : null}
{count > 0 ? <span className="what-changed-toggle-count">{count}</span> : null}
</span>
<ChevronDown aria-hidden="true" />
</button>
@@ -68,7 +71,8 @@ function WhatChangedAccordion(props: {
</div>
{open ? (
<div className="what-changed-accordion-content" id="what-changed-accordion-content">
<WhatChangedContent facts={props.facts} notes={props.notes} />
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
accessibilityOnly={props.accessibilityOnly} notes={props.notes} />
</div>
) : null}
</section>
@@ -109,7 +113,8 @@ export function SidebarReview(props: CompareControllerOptions) {
</>
)
: null;
const facts = compare.facts.map((fact) => fact.copy);
const facts = compare.split.visible.map((fact) => fact.copy);
const assistive = compare.split.assistive.map((fact) => fact.copy);
const notes = compareNotes(screenDiff, compare.facts.length, compare.statusBarIgnored, compare.homeIndicatorIgnored);
return (
@@ -140,7 +145,8 @@ export function SidebarReview(props: CompareControllerOptions) {
/>
</div>
<WhatChangedAccordion facts={facts} notes={notes} open={compare.factsOpen} onOpenChange={compare.setFactsOpen} />
<WhatChangedAccordion facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly} notes={notes}
open={compare.factsOpen} onOpenChange={compare.setFactsOpen} />
</section>
);
}
+14 -3
View File
@@ -105,8 +105,8 @@ export function AppPill(props: AppPillProps) {
const prDetails = pullRequest
? `${pullRequest.title}\n${pullRequest.head.ref} → ${pullRequest.base.ref}\n${device}`
: device;
// The PR URL is validated as https://github.com/owner/repo/pull/N, so its parent is the repository.
const repositoryUrl = pullRequest?.url && pullRequest.origin !== "local" ? pullRequest.url.replace(/\/pull\/\d+$/, "") : undefined;
// The URL is validated as https://github.com/owner/repo/pull/N (or /compare/<base>..<head>), so its parent is the repository.
const repositoryUrl = pullRequest?.url && pullRequest.origin !== "local" ? pullRequest.url.replace(/\/(pull\/\d+|compare\/.+)$/, "") : undefined;
const appTitle = device ? `${applicationName} · ${device}` : applicationName;
// Reports of a multi-platform review name every platform; the other ones are one menu away.
const siblings = (props.map.run.platforms ?? [])
@@ -170,7 +170,18 @@ export function AppPill(props: AppPillProps) {
<Menu items={appearanceItems} open={appearanceOpen} anchorRef={appearanceRef} ariaLabel="Appearance" onDismiss={() => setAppearanceOpen(false)} />
</>
) : null}
{pullRequest && pullRequest.origin !== "local" ? (
{pullRequest?.origin === "compare" ? (
<Tooltip label={prDetails} placement="bottom">
<a
className="collapsed-pr"
href={pullRequest.url}
target="_blank"
rel="noreferrer noopener"
aria-label={`${pullRequest.title} on GitHub`}>
{pullRequest.title}
</a>
</Tooltip>
) : pullRequest && pullRequest.origin !== "local" ? (
<Tooltip label={prDetails} placement="bottom">
<a
className="collapsed-pr"
+3 -3
View File
@@ -17,7 +17,7 @@ import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { changedScreens, compareText } from "../../utils/changed-screens";
import "./changes.css";
const STATUSES: FocusStatus[] = ["added", "modified", "removed", "needs-review", "source-affected"];
const STATUSES: FocusStatus[] = ["added", "modified", "accessibility-only", "removed", "needs-review", "source-affected"];
export type ChangesPanelProps = {
diff: BuildDiff;
@@ -176,10 +176,10 @@ export function ChangesPanel(props: ChangesPanelProps) {
<button
type="button"
className={`changes-screen-row diff-${screen.status}`}
aria-label={`Open ${screen.title}, ${DIFF_LABELS[screen.status]}, ${screen.route}`}
aria-label={`Open ${screen.title}, ${FOCUS_LABELS[screen.status]}, ${screen.route}`}
aria-current={screen.id === props.selectedScreenId ? "true" : undefined}
onClick={() => props.onOpenScreen(screen.id)}>
<StatusGlyph status={screen.status} />
<StatusGlyph status={screen.status === "accessibility-only" ? "modified" : screen.status} accessibilityOnly={screen.status === "accessibility-only"} />
<code className="changes-screen-path" title={screen.title}>{screen.route}</code>
</button>
</li>
+5 -3
View File
@@ -23,7 +23,8 @@ import { copyImageToClipboard } from "../../utils/copy-image";
import type { NavigationEdge } from "../../../../src/contracts/navigation-graph";
import { navigationEdgeKey } from "../../utils/source-navigation";
import {
DIFF_LABELS,
diffClass,
diffLabel,
type BuildDiff,
type ScreenDiff,
} from "../../utils/build-diff";
@@ -111,7 +112,8 @@ function TransitionRow(props: {
const { screen, sources, observed } = props.item;
const targetId = screen.id;
const screenshot = artifactUrl(screenshotForScreen(screen, props.index));
const status = props.diff?.screens.get(targetId)?.status ?? "unchanged";
const targetDiff = props.diff?.screens.get(targetId);
const status = targetDiff?.status ?? "unchanged";
const kinds = [...new Set(sources.length
? sources.map(({ edge }) => edge.kind)
: observed.map(transition => transition.actionKind))].sort();
@@ -141,7 +143,7 @@ function TransitionRow(props: {
<span className="transition-copy">
<strong className="transition-path">{screenLabel(screen, props.index)}</strong>
</span>
<span className={`diff-dot diff-${status}`} title={DIFF_LABELS[status]} />
<span className={`diff-dot ${diffClass(targetDiff ?? { status })}`} title={diffLabel(targetDiff ?? { status })} />
<ChevronRight size={13} aria-hidden="true" />
</button>
</Tooltip>
+3 -3
View File
@@ -4,7 +4,7 @@ import { Tooltip } from "../shared/tooltip";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { InspectorPanel } from "./inspector";
import type { ChangedScreen } from "../../utils/changed-screens";
import { diffLabel, NOT_VISIBLE_HIGHLIGHT, type BuildDiff } from "../../utils/build-diff";
import { diffLabel, ACCESSIBILITY_ONLY_HIGHLIGHT, type BuildDiff } from "../../utils/build-diff";
import type { MapIndex, Screen } from "../../utils/model";
import type { TransitionDirection } from "../../utils/navigation";
import { displayPathForScreen } from "../../utils/screen-path";
@@ -93,7 +93,7 @@ export function RightPanel(props: RightPanelProps) {
{/* The screen's status as Compare's header and the Changes list mark it: a dot (+ or −
for added or removed) in the status colour, named for screen readers. */}
{screenDiff ? (
<StatusGlyph status={screenDiff.status} label={diffLabel(screenDiff)}
<StatusGlyph status={screenDiff.status} accessibilityOnly={screenDiff.accessibilityOnly} label={diffLabel(screenDiff)}
className="inspector-diff-status" />
) : null}
{props.index.plainTitles ? (
@@ -114,7 +114,7 @@ export function RightPanel(props: RightPanelProps) {
both in place, off. */}
{props.screen && props.diff && props.onOpenCompare ? (
<>
<Tooltip label={screenDiff?.notVisible ? NOT_VISIBLE_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom-end">
<Tooltip label={screenDiff?.accessibilityOnly ? ACCESSIBILITY_ONLY_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom-end">
<button type="button" className="icon-button inspector-highlight" aria-label="Highlight changes"
aria-pressed={outlinable ? outlines : false} disabled={!outlinable}
onClick={() => setOutlinesShown(!outlines)}>
@@ -45,8 +45,9 @@ export function PhoneCompare(props: CompareControllerOptions & {
{compare.homeIndicatorIgnored ? <HomeIndicatorBand /> : null}
</>
) : null;
const facts = compare.facts.map((fact) => fact.copy);
const notes = compareNotes(screenDiff, facts.length, compare.statusBarIgnored, compare.homeIndicatorIgnored);
const facts = compare.split.visible.map((fact) => fact.copy);
const assistive = compare.split.assistive.map((fact) => fact.copy);
const notes = compareNotes(screenDiff, compare.facts.length, compare.statusBarIgnored, compare.homeIndicatorIgnored);
const previous = compare.previous ? () => props.onSelectScreen(compare.previous!.id) : undefined;
const next = compare.next ? () => props.onSelectScreen(compare.next!.id) : undefined;
// A tap near either side of the stage steps through the screens, like the stepper in the header. It runs
@@ -67,14 +68,14 @@ export function PhoneCompare(props: CompareControllerOptions & {
return (
<section className="phone-compare" aria-label={`Compare ${route}`}>
<header className="phone-compare-head">
<CompareNav variant="phone" status={screenDiff.status} statusLabel={diffLabel(screenDiff)} route={route} title={screen.title}
<CompareNav variant="phone" status={screenDiff.status} accessibilityOnly={screenDiff.accessibilityOnly} statusLabel={diffLabel(screenDiff)} route={route} title={screen.title}
position={compare.position} count={props.order.length} picker={props.picker} stepsApart />
<button type="button" className="phone-icon-button" aria-label="Outlines" aria-pressed={compare.outlines}
disabled={areas.length === 0} onClick={compare.toggleOutlines}>
<ScanSearch aria-hidden="true" />
</button>
<button type="button" className="phone-icon-button" aria-label="What changed" aria-haspopup="dialog"
disabled={facts.length === 0 && notes.length === 0} onClick={() => compare.setFactsOpen(true)}>
disabled={compare.facts.length === 0 && notes.length === 0} onClick={() => compare.setFactsOpen(true)}>
<List aria-hidden="true" />
</button>
{props.headerAction}
@@ -121,7 +122,7 @@ export function PhoneCompare(props: CompareControllerOptions & {
</div>
<PhoneSheet title="What changed" open={compare.factsOpen} onClose={() => compare.setFactsOpen(false)}>
<WhatChangedContent facts={facts} notes={notes} />
<WhatChangedContent facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly} notes={notes} />
</PhoneSheet>
</section>
);
@@ -132,7 +132,7 @@ function ReportDropScreen({ status, identity, error, workflowUrl, downloadUrl, e
</div> : <>
<h1 className="report-drop-title">{identity ? "Open this report" : "Open a report"}</h1>
<ol className="report-drop-steps" aria-label="How to open a report">
<li>Open the Explore comment on your pull request</li>
<li>Open the Explore comment on your pull request, or the summary of the Explore workflow run</li>
<li>Download {downloadUrl
? <a className="report-drop-file" href={downloadUrl} target="_blank" rel="noopener noreferrer" title="Download from GitHub">{fileName}</a>
: fileName}</li>
+4 -3
View File
@@ -1,17 +1,18 @@
import { Minus, Plus } from "lucide-react";
import type { DiffStatus } from "../../utils/build-diff";
import { diffClass, type DiffStatus } from "../../utils/build-diff";
/**
* A screen's diff status as a bare glyph in the status colour: + added, − removed, a dot for the
* rest. The Changes list marks its rows with it; a header that names the same screen uses it too.
* With a label it is an image of that name; without one it is decoration beside text that says it.
* An accessibility-only change is a square in its own colour, so it does not rest on colour alone.
*/
export function StatusGlyph(props: { status: DiffStatus; label?: string; className?: string }) {
export function StatusGlyph(props: { status: DiffStatus; accessibilityOnly?: boolean | undefined; label?: string; className?: string }) {
const glyph = props.status === "added" ? <Plus />
: props.status === "removed" ? <Minus />
: <span className="status-glyph-dot" />;
return (
<span className={`status-glyph diff-${props.status}${props.className ? ` ${props.className}` : ""}`}
<span className={`status-glyph ${diffClass({ status: props.status, ...(props.accessibilityOnly ? { accessibilityOnly: true as const } : {}) })}${props.className ? ` ${props.className}` : ""}`}
{...(props.label ? { role: "img", "aria-label": props.label } : { "aria-hidden": true })}>
{glyph}
</span>
+1
View File
@@ -136,6 +136,7 @@ button.screens-tree-row:hover { color: var(--text); background: var(--panel-hove
cursor: pointer;
}
.screens-tree-dot[class*="diff-"] { background: var(--diff); }
.screens-tree-dot.diff-accessibility-only { border-radius: 2px; }
.screens-tree-dot.elsewhere { background: color-mix(in srgb, var(--modified) 50%, transparent); }
.screens-tree-legend {
display: flex;
+10 -9
View File
@@ -2,8 +2,8 @@ import { useEffect, useMemo, useRef, useState, type CSSProperties, type Keyboard
import { ChevronRight, ChevronsDownUp, ChevronsUpDown, ListTree } from "lucide-react";
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
import { primaryScreenshotForScreen, screenshotSize } from "../../utils/screen-images";
import type { BuildDiff, DiffStatus } from "../../utils/build-diff";
import { isVisibleChange } from "../../utils/changed-screens";
import { diffClass, type BuildDiff, type DiffStatus } from "../../utils/build-diff";
import { focusStatusOf, isCapturedChange } from "../../utils/changed-screens";
import { displayPathForScreen, screenLabel } from "../../utils/screen-path";
import { screenTree, treeIndex, treeNodeKey, type ScreenTree, type ScreenTreeNode } from "../../utils/screen-tree";
import type { Appearance } from "../../utils/appearance";
@@ -13,7 +13,7 @@ import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
import { PhoneSheet } from "../phone/phone-chrome";
import "./screens.css";
/** The statuses a tree dot marks. The Changed filter keeps only the screens that look different (isVisibleChange). */
/** The statuses a tree dot marks. The Changed filter keeps only the screens whose captures differ (isCapturedChange). */
const CHANGED_STATUSES = new Set<DiffStatus>(["modified", "added", "removed", "needs-review", "source-affected"]);
type Filter = "changed" | "all";
@@ -45,13 +45,13 @@ function statusOf(diff: BuildDiff | undefined, id: string): DiffStatus | undefin
}
function isChanged(diff: BuildDiff | undefined, id: string): boolean {
return isVisibleChange(diff?.screens.get(id));
return isCapturedChange(diff?.screens.get(id));
}
/** The dot beside a tree row: changed here, changed only in another appearance, or nothing. */
function dotClass(diff: BuildDiff | undefined, elsewhere: ReadonlyMap<string, Appearance[]> | undefined, id: string): string | undefined {
const status = statusOf(diff, id);
if (status && CHANGED_STATUSES.has(status)) return `diff-${status}`;
const screen = diff?.screens.get(id);
if (screen && CHANGED_STATUSES.has(screen.status)) return diffClass(screen);
if (elsewhere?.get(id)?.length) return "elsewhere";
return undefined;
}
@@ -109,7 +109,7 @@ function ScreenCell(props: {
{...(url ? { screenshot: url } : {})}
{...(size ? size : {})}
{...(status ? { diff: status } : {})}
{...(props.diff?.screens.get(props.screen.id)?.notVisible ? { notVisible: true } : {})}
{...(props.diff?.screens.get(props.screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {})}
selected={props.selected}
ariaPressed={props.selected}
loading="lazy"
@@ -188,14 +188,15 @@ function TreeRows(props: {
});
}
/** Changed and Accessibility only always: a reader learns the kinds even on a report without one. */
function Legend(props: { others: Appearance[] }) {
return (
<div className="screens-tree-legend">
<span><span className="screens-tree-dot diff-modified" aria-hidden="true" />Changed</span>
<span><span className="screens-tree-dot diff-modified diff-accessibility-only" aria-hidden="true" />Accessibility only</span>
{props.others.length ? (
<span><span className="screens-tree-dot elsewhere" aria-hidden="true" />Changed in {props.others.join(" and ")} only</span>
) : null}
<span><span className="screens-tree-dot diff-source-affected" aria-hidden="true" />Source-affected</span>
</div>
);
}
@@ -392,7 +393,7 @@ export function ScreensView(props: ScreensViewProps) {
elsewhere={isChanged(props.diff, id) ? undefined : props.changedElsewhere?.get(id)}
via={tree.via.get(id)}
selected={props.selectedScreenId === id}
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === statusOf(props.diff, id))}
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === focusStatusOf(props.diff?.screens.get(id)))}
onSelect={() => props.onSelectScreen(id)} />
) : null;
})}
+6 -4
View File
@@ -23,6 +23,7 @@ import type { BuildDiff, DiffStatus } from "../../utils/build-diff";
import { CANVAS_MAX_ZOOM } from "../../utils/canvas-zoom";
import { usePhoneLayout } from "../../utils/phone-layout";
import type { FocusBehavior, FocusRequest, FocusStatus, MapDirection } from "../../utils/navigation";
import { focusStatusOf } from "../../utils/changed-screens";
import { displayPathForScreen } from "../../utils/screen-path";
import { shortcutsLive } from "../../utils/shortcuts";
import { mapKeyDirection, mapKeyTarget } from "../../utils/map-keyboard";
@@ -58,7 +59,7 @@ type ScreenNodeData = {
highlighted: boolean;
direction: MapDirection;
diff?: DiffStatus;
notVisible?: boolean;
accessibilityOnly?: boolean;
projectionDelayMs?: number;
projectionScreenScale?: number;
projectionMotion: ProjectionMotionMetadata;
@@ -93,7 +94,7 @@ function ScreenNodeCard({ data, selected }: NodeProps<ScreenGraphNode>) {
{...(data.screenshot ? { screenshot: data.screenshot } : {})}
{...(data.missingReason ? { missingReason: data.missingReason } : {})}
{...(data.diff ? { diff: data.diff } : {})}
{...(data.notVisible ? { notVisible: true } : {})}
{...(data.accessibilityOnly ? { accessibilityOnly: true } : {})}
selected={selected}
highlighted={data.highlighted}
style={{
@@ -287,7 +288,8 @@ function projectionElements(
const screenshot = structure.screenshots.get(screen.id);
const highlighted = false;
const status = diff?.screens.get(screen.id)?.status;
const muted = focus.length > 0 && !focus.some((state) => state === status);
const focusStatus = focusStatusOf(diff?.screens.get(screen.id));
const muted = focus.length > 0 && !focus.some((state) => state === focusStatus);
const projectionMotion: ProjectionMotionMetadata = {
motionKey: `screen:${screen.id}`,
role: "screen",
@@ -318,7 +320,7 @@ function projectionElements(
highlighted,
direction: structure.horizontal ? "LR" : "TB",
...(status ? { diff: status } : {}),
...(diff?.screens.get(screen.id)?.notVisible ? { notVisible: true } : {}),
...(diff?.screens.get(screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {}),
projectionMotion,
onSelect: onSelectScreen,
onHover: onHoverScreen,
+3 -2
View File
@@ -50,7 +50,8 @@ function comparisonStatus(surface: Surface): BuildComparisonEntry["status"] {
if (captureUnavailable(surface, "base") || unattributed("base")) return "unavailable";
}
if (surface.status === "added" || surface.status === "removed") return surface.status;
return comparisonReview(surface)?.status ?? (surface.status === "modified" ? "source-affected" : "not-compared");
// A source change with no comparison is not a change the captures show: not compared, whatever the source did.
return comparisonReview(surface)?.status ?? "not-compared";
}
/** The side's route exists and was planned, but its capture ended without a screenshot. */
@@ -623,7 +624,7 @@ export function publicReviewProjection(review: PublicReview): ViewerReviewProjec
}
return {
pullRequest: {
...(review.pullRequest.origin === "local" ? { origin: "local" as const } : {}),
...(review.pullRequest.origin === "local" || review.pullRequest.origin === "compare" ? { origin: review.pullRequest.origin } : {}),
number: review.pullRequest.number, title: review.pullRequest.title, url: review.pullRequest.url,
base: { ...review.pullRequest.base }, head: { ...review.pullRequest.head },
},
+10
View File
@@ -64,6 +64,9 @@
/* Modified is orange in both themes, as in the PR comment (🟧). Yellow means "needs review". */
--modified: #ea580c;
--modified-soft: #ffefd6;
/* Accessibility only is blue, as in the PR comment (🟦), deeper than the accent a screen variant uses. */
--accessibility: #2f6feb;
--accessibility-soft: #e8f0fe;
--graph-dot: #d9d9e0;
--graph-line: #8b8d98;
--graph-line-soft: #c5c7ce;
@@ -181,6 +184,8 @@
--purple-soft: #301c3b;
--modified: #ff9a3c;
--modified-soft: #331e0b;
--accessibility: #8fa8ff;
--accessibility-soft: #17224a;
--graph-dot: #212225;
--graph-line: #696e77;
--graph-line-soft: #3f4349;
@@ -1665,6 +1670,11 @@ code {
/* Modified reads orange everywhere: the Changes list, the canvas chip and border, the Inspector badge. */
.diff-modified { --diff: var(--modified); --diff-soft: var(--modified-soft); }
.diff-removed { --diff: var(--danger); --diff-soft: var(--danger-soft); }
/* Accessibility only: modified for assistive technology, with matching screenshots. It keeps Modified's frame
(it carries diff-modified too) in blue, and its marks are squares, so it does not rest on colour alone. */
.diff-accessibility-only { --diff: var(--accessibility); --diff-soft: var(--accessibility-soft); }
.diff-accessibility-only.diff-dot,
.diff-accessibility-only .status-glyph-dot { border-radius: 2px; }
.diff-unchanged { --diff: var(--tertiary); --diff-soft: var(--element); }
.diff-needs-review { --diff: var(--tertiary); --diff-soft: var(--element); }
.diff-source-affected { --diff: var(--purple); --diff-soft: var(--purple-soft); }
+20 -8
View File
@@ -67,16 +67,28 @@ export type ScreenDiff = {
reviewerChanges: ReviewerChangeFact[];
runtimeEvidenceRefs: string[];
noVisibleChange: boolean;
/** Modified in what the review read (the accessibility tree, text), with no pixel difference: nothing to outline. */
notVisible?: true;
/**
* Modified only in what assistive technology reads (the accessibility tree): the screenshots match, so there is
* nothing to outline. Screen readers and voice control still see the change, so it is reviewed like any other.
*/
accessibilityOnly?: true;
};
/** Why Highlight changes is off for a change that is not visible. */
export const NOT_VISIBLE_HIGHLIGHT = "Nothing to highlight: the screenshots match";
/** Why Highlight changes is off for an accessibility-only change. */
export const ACCESSIBILITY_ONLY_HIGHLIGHT = "Nothing to highlight: only what assistive technology reads changed";
/** A screen's status as the Viewer names it: a modified screen whose screenshots match says the change is not visible. */
export function diffLabel(diff: Pick<ScreenDiff, "status" | "notVisible">): string {
return diff.notVisible && diff.status === "modified" ? "Changed (not visible)" : DIFF_LABELS[diff.status];
/** A screen's status as the Viewer names it: a modified screen whose screenshots match changed for assistive technology only. */
export function diffLabel(diff: Pick<ScreenDiff, "status" | "accessibilityOnly">): string {
return isAccessibilityOnly(diff) ? "Accessibility only" : DIFF_LABELS[diff.status];
}
export function isAccessibilityOnly(diff: Pick<ScreenDiff, "status" | "accessibilityOnly"> | undefined): boolean {
return diff?.status === "modified" && Boolean(diff.accessibilityOnly);
}
/** The class that colours a screen's status: an accessibility-only change keeps Modified's frame in its own colour. */
export function diffClass(diff: Pick<ScreenDiff, "status" | "accessibilityOnly">): string {
return isAccessibilityOnly(diff) ? "diff-modified diff-accessibility-only" : `diff-${diff.status}`;
}
export type BuildDiff = {
@@ -355,7 +367,7 @@ export function buildDiff(options: {
reviewerChanges: reviewSurface?.reviewerChanges ?? [],
runtimeEvidenceRefs: reviewSurface?.runtimeEvidenceRefs ?? [],
noVisibleChange: screen.status === "unchanged" && (reviewSurface?.noVisibleChange ?? false),
...(screen.status === "modified" && reviewSurface?.pixelsUnchanged ? { notVisible: true as const } : {}),
...(screen.status === "modified" && reviewSurface?.pixelsUnchanged ? { accessibilityOnly: true as const } : {}),
...(before ?? borrowed.before ? { beforeScreenshot: (before ?? borrowed.before)! } : {}),
...(after ?? borrowed.after ? { afterScreenshot: (after ?? borrowed.after)! } : {}),
...(redirectTo && (borrowed.before || borrowed.after) ? { redirectTo } : {}),
+28 -10
View File
@@ -1,15 +1,17 @@
import type { BuildDiff, DiffStatus, ScreenDiff } from "./build-diff";
import { isAccessibilityOnly, type BuildDiff, type DiffStatus, type ScreenDiff } from "./build-diff";
import type { MapIndex } from "./model";
import { isLaunchScreen } from "./model";
import type { FocusStatus } from "./navigation";
import { displayPathForScreen } from "./screen-path";
/** Review order: the visible changes first, then what changed only for assistive technology. */
const STATUS_ORDER: Record<FocusStatus, number> = {
added: 0,
modified: 1,
removed: 2,
"needs-review": 3,
"source-affected": 4,
"accessibility-only": 3,
"needs-review": 4,
"source-affected": 5,
};
export type ChangedScreen = {
@@ -19,17 +21,33 @@ export type ChangedScreen = {
route: string;
};
export function isChangedStatus(status: DiffStatus): status is FocusStatus {
/** The status the Changes filter and focus match a screen on: Accessibility only apart from Modified. */
export function focusStatusOf(diff: Pick<ScreenDiff, "status" | "accessibilityOnly"> | undefined): DiffStatus | "accessibility-only" | undefined {
return isAccessibilityOnly(diff) ? "accessibility-only" : diff?.status;
}
/** Each focus status's count: Modified counts only the visible changes, Accessibility only the rest. */
export function focusCounts(diff: BuildDiff | undefined): Record<FocusStatus, number> {
const counts: Record<FocusStatus, number> = { added: 0, modified: 0, "accessibility-only": 0, removed: 0, "needs-review": 0, "source-affected": 0 };
for (const screen of diff?.screens.values() ?? []) {
const status = focusStatusOf(screen);
if (status && status in counts) counts[status as FocusStatus] += 1;
}
return counts;
}
export function isChangedStatus(status: DiffStatus): status is Exclude<FocusStatus, "accessibility-only"> {
return status !== "unchanged" && status !== "not-compared" && status !== "unavailable" && status !== "variant";
}
/**
* A change the captures show: an added or removed screen, or a modified one whose pixels differ. A screen whose
* source changed but whose captures look the same ("No visible change", source-affected, or modified with
* unchanged pixels) stays in the Changes list, but Compare does not step through it and Screens' Changed hides it.
* A change the captures show: an added, removed or modified screen, including one modified only in what assistive
* technology reads (its screenshots match, its accessibility tree does not). A screen whose source changed but whose
* captures show nothing different ("No visible change") stays in the Changes list, but Compare does
* not step through it and Screens' Changed hides it.
*/
export function isVisibleChange(diff: Pick<ScreenDiff, "status" | "notVisible"> | undefined): boolean {
return diff !== undefined && (diff.status === "added" || diff.status === "removed" || (diff.status === "modified" && !diff.notVisible));
export function isCapturedChange(diff: Pick<ScreenDiff, "status"> | undefined): boolean {
return diff !== undefined && (diff.status === "added" || diff.status === "removed" || diff.status === "modified");
}
export function compareText(left: string, right: string): number {
@@ -58,7 +76,7 @@ export function changedScreens(diff: BuildDiff, index: MapIndex): ChangedScreen[
if (!isChangedStatus(screenDiff.status)) continue;
const screen = index.screens.get(id);
if (!screen) continue;
result.push({ id, status: screenDiff.status, title: screen.title, route: displayPathForScreen(screen) });
result.push({ id, status: isAccessibilityOnly(screenDiff) ? "accessibility-only" : screenDiff.status, title: screen.title, route: displayPathForScreen(screen) });
}
return result.sort(compareChangedScreens);
}
+11 -6
View File
@@ -2,9 +2,9 @@ import { isPreviewPath } from "./artifact-report";
import type { PullRequestPresentation } from "./review-model";
/**
* The link an agent can read: a hosted preview (`/p/<token>`) answers a fetch that does not ask for
* HTML with a Markdown index of the report's JSON API. Other pages (a local `explore view`, a dropped
* report) have nothing an agent can fetch, so they get no handoff.
* The link an agent can read: a hosted preview (`/p/<token>`), or a local review's Viewer (`capture:review` on this
* machine serves the same path), answers a fetch that does not ask for HTML with a Markdown index of the report's
* JSON API. Other pages (a local `explore view`, a dropped report) have nothing an agent can fetch, so they get no handoff.
*/
export function handoffPageUrl(page: URL): string | undefined {
if (!isPreviewPath(page.pathname)) return undefined;
@@ -32,24 +32,29 @@ export type HandoffInput = {
};
function repository(pullRequest: PullRequestPresentation): string | undefined {
return /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/\d+$/.exec(pullRequest.url ?? "")?.[1];
return /^https:\/\/github\.com\/([^/]+\/[^/]+)\/(?:pull\/\d+|compare\/.+)$/.exec(pullRequest.url ?? "")?.[1];
}
/** The prompt to paste into an agent; `view` adds what the reader is looking at as its last line. */
export function handoffPrompt(input: HandoffInput, view?: HandoffView): string {
const repo = input.pullRequest ? repository(input.pullRequest) : undefined;
const subject = input.pullRequest && input.pullRequest.origin !== "local"
const subject = input.pullRequest?.origin === "compare" || input.pullRequest?.origin === "local"
? `Review the visual changes from ${input.pullRequest.base.ref} to ${input.pullRequest.head.ref}${repo ? ` of ${repo}` : ""}.`
: input.pullRequest
? `Review the visual changes in PR #${input.pullRequest.number}${repo ? ` of ${repo}` : ""}.`
: `Review this Expo Explore report of ${input.appName}.`;
const appearances = input.appearances.length > 1
? ` in ${input.appearances.map(name => name.toLowerCase()).join(" and ")}`
: "";
// A local review's link answers only on this machine, and only while `capture:review` keeps serving it.
const local = ["127.0.0.1", "localhost", "[::1]"].includes(new URL(input.pageUrl).hostname);
const lines = [
subject,
"Expo Explore report:",
input.pageUrl,
"",
`Fetch the link first. It explains the report's JSON API. Go through the changed screens, compare the before and after screenshots${appearances}, and tell me which changes look intended and which look like regressions. For each regression, name the source file to fix.`,
`Fetch the link first${local ? " (from this machine, with curl if your fetch tool refuses local addresses)" : ""}. It explains the report's JSON API. Go through the changed screens, compare the before and after screenshots${appearances}, and tell me which changes look intended and which look like regressions. For each regression, name the source file to fix.`,
...(local ? ["", "The link is served by `expo-explore capture:review` on this machine and stops working when it exits."] : []),
];
if (view) {
const where = [view.screen, view.view, view.platform, view.appearance].filter(Boolean).join(" · ");
+4 -2
View File
@@ -8,7 +8,8 @@ export type ThemePreference = "light" | "dark" | "system";
export type MapDirection = "TB" | "LR";
/** The explicitly selected amount of Map hierarchy, independent from camera zoom. */
/** The diff states the canvas can single out. An empty selection is "All": nothing drops back. */
export type FocusStatus = "added" | "modified" | "removed" | "needs-review" | "source-affected";
/** `accessibility-only`: a modified screen whose screenshots match, filtered apart from the visible changes. */
export type FocusStatus = "added" | "modified" | "accessibility-only" | "removed" | "needs-review" | "source-affected";
/** The right panel shows Session and Diff. */
export type InspectView = "session" | "diff";
/** Which way the inspector's transition list reads: into the screen, or out of it. */
@@ -83,7 +84,7 @@ export type FocusRequest = {
const CANVASES: CanvasView[] = ["map", "screens", "compare"];
const INSPECTS: InspectView[] = ["session", "diff"];
const DIRECTIONS: TransitionDirection[] = ["in", "out"];
const FOCUSES: FocusStatus[] = ["added", "modified", "removed", "needs-review", "source-affected"];
const FOCUSES: FocusStatus[] = ["added", "modified", "accessibility-only", "removed", "needs-review", "source-affected"];
function isCanvas(value: string | null | undefined): value is CanvasView {
return CANVASES.includes(value as CanvasView);
@@ -326,6 +327,7 @@ export const CANVAS_DESCRIPTIONS: Record<CanvasView, string> = {
export const FOCUS_LABELS: Record<FocusStatus, string> = {
added: "Added",
modified: "Modified",
"accessibility-only": "Accessibility only",
removed: "Removed",
"needs-review": "No visible change",
"source-affected": "Source-affected",
+14 -1
View File
@@ -1,4 +1,4 @@
import type { DiffStatus, ScreenDiff } from "./build-diff";
import { isAccessibilityOnly, type DiffStatus, type ScreenDiff } from "./build-diff";
import { formatReviewerChange, sortReviewerChanges, type CaptureNotes, type ReviewerChangeFact } from "./review-model";
/** One line of "What changed": a reviewer note, a CI finding, or the legacy summary. */
@@ -25,6 +25,19 @@ export function presentedChanges(diff: ScreenDiff | undefined): PresentedChange[
return legacy ? [{ id: "legacy-summary", copy: legacy }] : [];
}
/**
* What changed, split by who sees it. On a screen whose screenshots match, every finding is for assistive technology:
* nothing on it looks different. Elsewhere only the accessibility findings (labels, roles) are, since an added
* element or new text may well be visible.
*/
export function splitForAssistiveTechnology(changes: PresentedChange[], diff: Pick<ScreenDiff, "status" | "accessibilityOnly"> | undefined): {
visible: PresentedChange[];
assistive: PresentedChange[];
} {
const assistive = (change: PresentedChange) => Boolean(change.fact) && (isAccessibilityOnly(diff) || change.fact?.category === "accessibility");
return { visible: changes.filter((change) => !assistive(change)), assistive: changes.filter(assistive) };
}
/** What a missing side of a comparison shows instead of a screenshot. */
export function placeholderFor(side: "before" | "after", status: DiffStatus, notes?: CaptureNotes): string {
if (side === "before" && status === "added") return "Not in baseline";
+2 -2
View File
@@ -92,8 +92,8 @@ export class ReportSource {
private async download(url: string): Promise<void> {
try {
const response = await fetch(url, { credentials: "omit", cache: "no-store" });
if (response.status === 410) throw new ReportFileError("invalid", `This preview link expired${await expiredOn(response)}. Download the report from the pull request instead, or rerun Explore for a fresh link.`);
if (response.status === 404) throw new ReportFileError("invalid", "This preview link is not valid, or its deployment was deleted. Ask for a new review, or download the report from the pull request.");
if (response.status === 410) throw new ReportFileError("invalid", `This preview link expired${await expiredOn(response)}. Download the report from the pull request or workflow run instead, or rerun Explore for a fresh link.`);
if (response.status === 404) throw new ReportFileError("invalid", "This preview link is not valid, or its deployment was deleted. Ask for a new review, or download the report from the pull request or workflow run.");
if (!response.ok || !response.body) throw new ReportFileError("invalid", `The report could not be downloaded (HTTP ${response.status}).`);
const total = Number(response.headers.get("content-length")) || undefined;
const reader = response.body.getReader();
+25 -2
View File
@@ -4,7 +4,8 @@ export type PullRequestRef = {
};
export type PullRequestPresentation = {
origin?: "local";
/** "compare": two commits reviewed without a pull request; `url` is github.com's compare page and there is no number. */
origin?: "local" | "compare";
number?: number | undefined;
title: string;
url?: string | undefined;
@@ -97,7 +98,7 @@ export type ReviewSurface = {
reviewerChanges: ReviewerChangeFact[];
runtimeEvidenceRefs: string[];
noVisibleChange: boolean;
/** CI compared both verified screenshots and found no pixel difference: whatever changed is not visible. */
/** CI compared both verified screenshots and found no pixel difference: anything that changed is in the accessibility tree. */
pixelsUnchanged?: true;
/** Route this surface declares instead of rendering a screen of its own. */
redirectTo?: string;
@@ -159,6 +160,21 @@ function pullRequestRef(value: unknown): PullRequestRef | undefined {
return ref && sha ? { ref, sha } : undefined;
}
/** github.com's two-dot compare page for exactly these two commits, or nothing. */
function githubCompareUrl(value: unknown, baseSha: string, headSha: string): string | undefined {
const string = nonEmptyString(value);
if (!string) return undefined;
try {
const url = new URL(string);
if (url.protocol !== "https:" || url.hostname !== "github.com" || url.username || url.password || url.search || url.hash
|| !/^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/compare\/[0-9a-f]{40}\.\.[0-9a-f]{40}$/.test(url.pathname)
|| !url.pathname.endsWith(`/compare/${baseSha}..${headSha}`)) return undefined;
return url.href;
} catch {
return undefined;
}
}
function githubPullRequestUrl(value: unknown, number: number): string | undefined {
const string = nonEmptyString(value);
if (!string) return undefined;
@@ -186,6 +202,13 @@ function githubPullRequestUrl(value: unknown, number: number): string | undefine
function pullRequest(value: unknown): PullRequestPresentation | undefined {
const candidate = record(value);
if (!candidate) return undefined;
if (candidate.origin === "compare") {
const title = nonEmptyString(candidate.title);
const base = pullRequestRef(candidate.base);
const head = pullRequestRef(candidate.head);
const url = base && head ? githubCompareUrl(candidate.url, base.sha, head.sha) : undefined;
return title && base && head && url ? { origin: "compare", title, url, base, head } : undefined;
}
const number = candidate.number;
if (!Number.isSafeInteger(number) || (number as number) <= 0) return undefined;
const title = nonEmptyString(candidate.title);
+8 -4
View File
@@ -218,6 +218,11 @@ function aggregateStatus(statuses: readonly DiffStatus[]): DiffStatus {
return "modified";
}
function accessibilityOnlyFamily(diffs: readonly ScreenDiff[]): boolean {
const changed = diffs.filter((diff) => diff.status === "added" || diff.status === "removed" || diff.status === "modified");
return changed.length > 0 && changed.every((diff) => diff.status === "modified" && diff.accessibilityOnly);
}
function firstDiffWithScreenshot(
diffs: readonly ScreenDiff[],
side: "beforeScreenshot" | "afterScreenshot",
@@ -241,7 +246,7 @@ function familyEvidence(diffs: readonly ScreenDiff[]): {
reviewerChanges: ScreenDiff["reviewerChanges"];
runtimeEvidenceRefs: string[];
noVisibleChange: boolean;
notVisible?: true;
accessibilityOnly?: true;
} {
const first = diffs[0];
if (!first) throw new Error("Cannot present an empty diff family");
@@ -251,7 +256,6 @@ function familyEvidence(diffs: readonly ScreenDiff[]): {
const beforeDiff = firstDiffWithScreenshot(diffs, "beforeScreenshot");
const afterDiff = firstDiffWithScreenshot(diffs, "afterScreenshot");
const primary = paired ?? afterDiff ?? beforeDiff ?? first;
const modified = diffs.filter((diff) => diff.status === "modified");
const reviewerChanges = [...new Map(diffs
.flatMap((diff) => diff.reviewerChanges ?? [])
.map((change) => [change.id, change])).values()];
@@ -263,8 +267,8 @@ function familyEvidence(diffs: readonly ScreenDiff[]): {
reviewerChanges,
runtimeEvidenceRefs,
noVisibleChange: diffs.some((diff) => diff.noVisibleChange),
// Not visible only when no modified member of the family shows a difference.
...(modified.length > 0 && modified.every((diff) => diff.notVisible) ? { notVisible: true as const } : {}),
// Accessibility only when every changed member is: an added, removed or visibly modified member is a visible change.
...(accessibilityOnlyFamily(diffs) ? { accessibilityOnly: true as const } : {}),
...(primary.captureNotes ? { captureNotes: primary.captureNotes } : {}),
// A redirect's screenshots belong to the route it declares; the panel must keep saying so.
...(primary.redirectTo ? { redirectTo: primary.redirectTo } : {}),