Compare commits

..
Author SHA1 Message Date
Brent Vatne 61c1c1bd62 Release 0.19.0 2026-10-15 13:59:08 -07:00
Brent Vatne ddb8005e09 Harden report uploads and the reports picker after review
- Device labels in the sealed .env allow only letters, digits and a few
  separators: eas deploy expands $VARIABLES there, even single-quoted, so a
  label from an uploaded report could pull the deploying environment (or the
  report's own key) into the deployment.
- readReportZip rejects a report whose commits are not full SHAs or whose
  repository, title, refs and run id are not text, and commitSubject passes
  --end-of-options, so a crafted report cannot hand git an option.
- Text from reports and commits is stripped of control characters when a
  run is saved, read and drawn, so it cannot reach the terminal as escape
  sequences; run.json may only name ios and android.
- The picker: Ctrl+C quits while filtering, escape sequences it has no use
  for (Delete, F-keys, modified arrows, Alt+key) are ignored instead of
  quitting, and a key that skips the title animation only skips it.
- Saved-run ids keep the whole run id and attempt, and a review's platforms
  saved one at a time join one run (same repository and commits).
- A local review removes only its own worktrees, not every stale one.
- Cached captures go after 30 days unused or past 2 GB (also on
  `reports prune`), and a review shown in the Viewer removes its temporary
  copy once the run is saved.
2026-10-15 13:51:49 -07:00
Brent Vatne 07152721ed Show the reports picker in the README, and add reports add
The README shows `npx @expo/explore reports` (light and dark), laid out in
Paper from the real picker over real saved runs. The readme-refresh skill
regenerates it: scripts/readme-reports-rows.mjs renders the picker as the
CLI draws it and writes the terminal body as Paper-ready HTML.

`reports add <report.zip | directory>...` keeps a report already on disk,
such as a downloaded explore-review artifact, among the saved runs without
hosting it.

Also: the picker's selected row kept its background only up to its first
coloured word; it now reaches the end of the row.
2026-10-15 13:39:01 -07:00
Brent Vatne d873690542 Add expo-explore reports: an arrow-key picker of your saved runs
Every local review, exploration and uploaded report is now kept under
~/.cache/expo-explore/reports/<id>/ (its report ZIPs and a run.json with the
kind, title, commits and their subjects, platforms and change counts), for
30 days or up to 2 GB.

`expo-explore reports` in a terminal opens a picker: one aligned line per
run, the selected run's commits and changes below, arrow keys or j/k to
move, / to filter by title, branch, commit subject, SHA or PR number, Enter
to open the run in the local Viewer, u to host it, d to delete it after y,
and tab to switch between this repository and all of them. It opens with
the "Expo Explore" wordmark arriving one of five ways, picked at random
(EXPLORE_INTRO names one, or off). Outside a terminal it lists the runs;
`reports list|open|upload|rm|prune` and --json cover scripts and agents.

Also: report:upload accepts reports from before Android support (no
runtime.platform), which are iOS.
2026-10-15 13:05:11 -07:00
Brent Vatne 2700db1051 Hand off local reports to AI, and fix the review's findings
The local report server now answers agents the way a hosted link does: the
Markdown index at /p/<token>, llms.txt and the api/v1 JSON API, from the
agent API the hosted Worker uses (moved to src/report/agent-api.ts and
zip-reader.ts). The Viewer shows "Hand off to AI" on local reviews, and the
prompt says the link is local and lives while capture:review runs. Local
reviews are named by their refs in the index and the prompt.

Fixes from the multi-model review:
- Single-platform uploads (and explore:binary) list their platform, so an
  Android report is not served as iOS.
- Device labels are cleaned before they reach the sealed .env.
- report:upload sizes files before reading them; the shared ZIP reader stops
  inflating past an entry's declared size.
- Refs like @{u} are named by branch or short SHA before capture, not
  rejected after it.
- On the default branch, unpushed commits are reviewed against origin's tip.
- Ctrl+C stops deterministic captures between steps, on the main thread and
  on capture workers.
- report:upload takes --config, finds a monorepo's committed config, and
  says where its preview settings came from.
- The docs say plainly that a local review runs both commits' code as you.
- The work directory goes after --upload or --output, and cache entries are
  written atomically.
2026-10-15 12:20:09 -07:00
Brent Vatne be82f16d6b Add report:upload to host reports already on this machine
Hosts a report.zip or report directory (one per platform of a review, or
one explore:binary report) behind one token-gated EAS Hosting link, in the
project --upload would have used. capture:review prints the command under
the Viewer link. Deploy errors name your eas login when EXPO_TOKEN is unset.
2026-10-15 10:56:48 -07:00
Brent Vatne adf2249612 Update the README for comparisons and local reviews; tidy local runs
README: the local review needs only a committed config, and its section
says what it does to your checkout, installs, cache and EAS usage. "After
setup", hosted previews, "How it works" and "Keep your setup current"
cover comparisons, local reviews and the ci:* commands. The README
checklist keeps the local-review prompt.

A local review that fails before producing anything removes its work
directory, the progress line no longer mentions a pull request comment,
and the tests delete the directories they create.
2026-10-15 10:39:38 -07:00
Brent Vatne 250eaafa77 Harden local reviews after the multi-model review
- Installs run without any credential-named environment variable, so a
  reviewed commit's .npmrc cannot send NPM_TOKEN or a Claude login token to
  a registry it picks; proxy, CA, cache and SSH-agent settings stay. The
  lockfile is found from the app directory, so an app with its own lockfile
  in a monorepo installs.
- Ctrl+C aborts model requests, stops the recorded simulator sessions and
  lets the review unwind through its cleanup; a second Ctrl+C quits and
  names any session left running. runLocalReview also takes an interrupt
  signal.
- The default base is the newer fork point of the local and origin default
  branches, by exact ref, so a stale branch or a tag of that name never
  adds unrelated changes.
- The capture cache replaces an entry from another recipe, keeps a fuller
  one against a partial capture of the same recipe, and never caches
  evidence that did not validate.
- --upload keeps expiresAfter: never. A finished review keeps only its
  reports; a failed one keeps everything and says where. The local Viewer
  offers no agent handoff, which it cannot serve.
2026-10-15 10:17:19 -07:00
Brent Vatne 906d51a873 Run capture:review on this machine between any two commits
capture:review with refs and none of the CI flags runs the same review
locally: --base (default: where HEAD left the default branch) and --head
or --uncommitted (tracked changes; --include-untracked adds untracked,
non-ignored files). Both commits are checked out as detached worktrees in a
private temporary directory, installed with the frozen-lockfile command
without Explore credentials or corepack enable, and removed afterwards.

It uses EXPO_TOKEN and the provider's API key when set, otherwise your eas
login and your local claude or codex login for the configured provider.
Every configured platform is reviewed; reports are packaged and opened in
a local Viewer (the built Viewer served at /p/<token>, as hosted reports
are) or hosted with --upload. Captures are cached per commit in
~/.cache/expo-explore, and Ctrl+C stops the review's simulator sessions.

doctor --capture uses the local model login the same way, and CLI errors
read as plain text outside GitHub Actions.
2026-10-15 09:44:06 -07:00
Brent Vatne 29bd225775 Stage app-relative paths for hosted repacks
git ls-files --full-name lists paths from the repository root, which were
then joined under the app directory: an app in a monorepo subdirectory
(apps/mobile) staged apps/mobile/apps/mobile/... and missed its own files.
Listing from the app directory without --full-name gives the paths the
staging copies. Standalone apps are unchanged.
2026-10-15 09:44:06 -07:00
Brent Vatne 5db1373ce7 Resolve HEAD to the checked-out commit in ci:compare-refs
The resolver tried refs/remotes/origin/<ref> before the ref itself, so HEAD
resolved through origin/HEAD to the default branch, and a local branch lost
to a possibly stale origin branch. HEAD, @ and their ~/^ forms now resolve
literally, and names are tried as a tag, a local branch, an origin branch,
then as git spells them.
2026-10-15 09:35:29 -07:00
Brent Vatne a3e7bcfa7b Address the multi-model review of comparisons
- Comparisons link GitHub's two-dot diff (base..head), the direct diff that
  capture compares; three dots diffed from the merge base and showed nothing
  for a rollback.
- ci:find-baseline turns a failed lookup into a warning and no baseline. As a
  ci:* error it wrote explore-diagnostics/error.json, which the failure
  comment could report as the cause of another platform's failure.
- The compare concurrency group joins the refs with "..", which no ref name
  contains, so different comparisons never share a group.
- The compare report job uploads its failure diagnostics, like the review's.
- --expires-in is validated even when the config hosts no report.
- When the default branch's ci.trustedAuthors fails validation, the
  SOURCE_NOT_TRUSTED refusal says so and why.
2026-10-14 21:29:31 -07:00
Brent Vatne b54877ba1f Address the second review of comparisons
- Job summaries render refs as code spans, so a ref with ] ( ) cannot break
  their links.
- ci:pr reads only ci.trustedAuthors from the default branch's config and
  ignores other keys, as before this branch, so a config written for another
  release still trusts its bots.
- The deploy check names its probes by shape (/p/<token>/...), never the
  token or its one-character near miss.
- capture:review's preview output is written by writeCaptureOutputs, now
  tested, since it alone starts the deploy job.
- The compare template's calling example grants contents and actions read,
  and the template and README say to call it once per workflow run.
2026-10-14 20:11:48 -07:00
Brent Vatne ac4400296f Keep a comparison's hosted link usable in the run summary
The runner masks registered secrets in job summaries as well as logs, so a
masked report token made the summary link read .../p/***. For a comparison,
ci:deploy no longer registers the token as a mask and leaves the link out
of the log; it appears only in the summary, as a PR's link appears only in
its comment.
2026-10-14 19:48:53 -07:00
Brent Vatne c3b8b2769e Fix review findings for comparisons
- ci:publish links a comparison from the run summary with the Open (hosted
  Viewer) and zip links a PR comment carries, replacing a summary line that
  pointed at expo-explore view, which does not open a report ZIP.
- explore-compare.yml takes optional scope and expires-in inputs, applied as
  capture:review --scope/--expires-in over the reviewed config, so a release
  comparison can capture every screen and keep its hosted link.
- ci:after-capture runs only when Explore installed, so a failed install
  reports one error instead of two.
- The Viewer's drop page and expired-link text mention the workflow run as
  well as the pull request.
- CI-FLOW.md describes the ci:* steps and the compare workflow; the README
  release example skips prereleases as the base and the first release.
2026-10-14 18:45:48 -07:00
Brent Vatne fa32f8e45e Move workflow logic into ci:* commands
The inline scripts in the review, baseline and compare workflows become CLI
commands, so fixes ship with an npm release instead of regenerated workflows:
ci:pr (resolve and authorize the PR), ci:find-baseline, ci:compare-refs and
ci:after-capture (stop sessions, check checkouts). capture:review writes the
preview request to the step outputs. The templates define the install steps
once with YAML anchors and the app directories once in the workflow env,
which fixes monorepo capture jobs that used the repository root; doctor now
checks every APP_PROJECT_DIR and APP_INSTALL_DIR in a workflow.
2026-10-14 18:23:02 -07:00
Brent Vatne 9e067e6308 Review any two commits without a pull request
A comparison origin, capture:review --compare, and an explore-compare.yml
workflow (workflow_dispatch and workflow_call with base and head refs) that
captures and reports like a PR review and links the report from the run
summary. setup --workflows installs it; doctor treats it as optional.
2026-10-14 17:52:10 -07:00
15 changed files with 133 additions and 195 deletions

No files matched your search

+1 -1
View File
@@ -139,7 +139,7 @@ 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 | Unchanged (not counted as a change) | Needs review |
| Screen source changed (`screen`) | Modified | Needs review | 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 |
+105 -110
View File
@@ -9,17 +9,6 @@ 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:
@@ -36,6 +25,40 @@ need to log in to something first, tell me the command.
For apps behind a sign-in, see [Sign-in and other app state](#sign-in-and-other-app-state).
### Review a change before you push it
Once Explore is [set up](#set-up-ci-reviews-on-every-pr) (`.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.
```
<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.
- Every run is kept for 30 days (up to 2 GB in all): `npx @expo/explore reports` lists your local reviews, explorations and uploaded reports with their commits, and opens or hosts one without capturing again. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
<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>
<details>
<summary><strong>Run it yourself</strong></summary>
@@ -81,55 +104,15 @@ 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).
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).
![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>
### Review a change before you push it
## Set up CI: reviews on every PR
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:
Paste this into Claude Code or Codex from your app's repository:
```text
Set up this app for Expo Explore CI reviews. Follow
@@ -141,45 +124,45 @@ what to merge and how to start the first review.
```
<details>
<summary id="hosted-previews"><strong>Hosted previews</strong></summary>
<summary><strong>Requirements</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.
- 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).
- 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>
<details>
<summary><strong>Manual setup</strong></summary>
<summary><strong>After setup: your first review</strong></summary>
The prompt above walks through these steps with you. To do them yourself:
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.
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.
```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
expo-explore capture:review # or see a whole review of your branch on this machine first
```
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>Capture modes: deterministic or agent</strong></summary>
<summary><strong>Set up without a coding agent</strong></summary>
```sh
npx @expo/explore setup # writes .expo-explore/config.yaml and the 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>
| | **Deterministic** (recommended to start) | **Agent** |
| --- | --- | --- |
@@ -190,7 +173,10 @@ A failed run shows an error code and a next action in the PR comment; see [CI tr
Both modes use the same comparison rules and report. You can change modes later.
**To use agent mode:**
</details>
<details>
<summary><strong>Configure agent mode</strong></summary>
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.
@@ -202,7 +188,15 @@ The model navigates and recovers on each uncaptured revision; see [agent usage](
</details>
<details>
<summary id="platforms"><strong>iOS, Android, or both</strong></summary>
<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>
`app.platform` names the primary platform, and a `platforms` map adds the other. Each entry can set its own `device`, `bundleId`, and `easProfile`.
@@ -228,36 +222,28 @@ platforms:
</details>
<details>
<summary><strong>Keep your setup current</strong></summary>
<summary id="hosted-previews"><strong>Hosted previews</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. It also adds `explore-compare.yml` if you don't have it, and `doctor` warns when it is missing.
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) 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>
### 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>
<summary id="compare"><strong>Review any two commits: releases, nightlies, any event</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.
@@ -294,12 +280,21 @@ jobs:
- 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.
- `setup --workflows` installs it. 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>
<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. It also adds `explore-compare.yml` if you don't have it, and `doctor` warns when it is missing.
</details>
## Sign-in and other app state
Each run starts on a fresh install. Tell Explore how to get past what the app needs: with `--hints` when running without source, or with [setup steps or agent instructions](docs/quickstart-ci.md#when-the-config-needs-setup-steps) in CI.
@@ -397,7 +392,7 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
</details>
## Additional information
## More
<details>
<summary><strong>How it works</strong></summary>
@@ -408,7 +403,7 @@ 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.
The same review runs for any two commits without a PR ([`explore-compare.yml`](#compare), 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).
+3 -3
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 | Unchanged (not counted as a change) | Needs review |
| Screen source changed | Modified | Needs review | 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,10 +172,10 @@ 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 and the comparison could not tell whether it looks different; a review target |
| Needs review | The screen's source changed but no visible difference was captured, or its evidence is inconclusive; still 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, 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 |
| Unchanged | No visible difference and no screen-specific source change |
| Not compared | No comparison was performed |
A difference that rounds to 0.00% of pixels is rendering noise and counts as no difference.
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "@expo/explore",
"version": "0.19.1",
"version": "0.19.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@expo/explore",
"version": "0.19.1",
"version": "0.19.0",
"license": "MIT",
"dependencies": {
"@expo/repack-app": "0.10.1",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.19.1",
"version": "0.19.0",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
-10
View File
@@ -170,16 +170,6 @@ npx @expo/explore capture:review --base v1.3.0 --head v1.4.0 --scope all
- 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.
+3 -3
View File
@@ -60,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. 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).
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. Under it, **Review a change before you push it**: one sentence and a prompt that runs `capture:review` locally (the explore-setup skill's "Review a change on this machine" section) on a set-up app.
3. **Set up CI: reviews on every PR**: one sentence and the setup prompt.
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, 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).
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).
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;
+1 -8
View File
@@ -8,13 +8,12 @@ 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", "unchanged"],
screen: ["modified", "needs-review"],
"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. */
@@ -208,12 +207,6 @@ 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;
+3 -16
View File
@@ -98,8 +98,7 @@ 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: verdictOf(surface),
sourceStatus: verdictOf(surface) === str(surface.status) ? undefined : str(surface.status), colorScheme: str(surface.colorScheme),
id, route: str(route.route), kind: str(route.kind), routeFile: str(route.routeFile), status: 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),
@@ -121,22 +120,10 @@ 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".
*/
function verdictOf(surface: Json): string | undefined {
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";
return status ?? str(surface.status);
}
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 = verdictOf(surface) ?? "unknown"; counts[status] = (counts[status] ?? 0) + 1; }
for (const surface of surfaces) { const status = str(surface.status) ?? "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),
@@ -352,7 +339,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(verdictOf(s) ?? "")).map(s => reviewSurfaceItem(context, s));
const items = surfaces.filter(s => !statuses || statuses.includes(str(s.status) ?? "")).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);
+1 -2
View File
@@ -10,7 +10,6 @@ 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";
@@ -204,7 +203,7 @@ export async function readReportZip(zip: Uint8Array): Promise<ReportZipSummary>
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 changes = reviewChangeCount({ 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,
+1 -2
View File
@@ -6,7 +6,6 @@ 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 type { ChangeGroup } from "./pr-comment-record.js";
import { readZipDirectory, readZipEntry } from "./zip-reader.js";
@@ -102,7 +101,7 @@ export async function describeReports(reports: SavedReport[], extra: { subjects?
if (!review || !pr) throw new Error("Not an Explore review report");
// One surface changed on two platforms is one change, under the first platform's group, as the PR comment lists it.
const merged = new Map<string, ChangeGroup>();
for (const each of reviews) if (each) for (const [id, group] of reviewChanges(normalizePublicReviewForReading(each))) if (!merged.has(id)) merged.set(id, group);
for (const each of reviews) if (each) for (const [id, group] of reviewChanges(each)) if (!merged.has(id)) merged.set(id, 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 ?? "",
+7 -6
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 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.
* 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.
*/
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,7 +303,8 @@ export function decideReview(scope: SurfaceSourceScope, visual: PublicVisualVerd
if (inconclusive) {
return { status: "needs-review", description: truncate(visual.verdict === "needs-review" ? visualReasonText(visual) : issue ?? "Needs review") };
}
return { status: "unchanged", description: "No visible change" };
if (scope === "app-wide") return { status: "unchanged", description: "No visible change" };
return { status: "needs-review", description: "Source changed; no visible difference was captured." };
}
function captureDiagnostic(surface: PlanSurface, side: "base" | "head", evidence: PublicEvidenceSide, surfaceId: string = surface.id): PublicEvidenceDiagnostic | undefined {
+3 -2
View File
@@ -210,9 +210,10 @@ 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: not a visible change, so Unchanged and not counted.
// Screen-specific source change, identical evidence: still a review target.
let result = await assess({});
assert.deepEqual(result.surfaces.pixels.review, { status: "unchanged", description: "No visible change" });
assert.equal(result.surfaces.pixels.review.status, "needs-review");
assert.equal(result.surfaces.pixels.review.description, "Source changed; no visible difference was captured.");
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"] },
+1 -8
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", "unchanged"], "app-wide": ["modified", "needs-review", "unchanged"], none: ["unchanged", "variant"] };
const allowed = { screen: ["modified", "needs-review"], "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,13 +194,6 @@ 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", () => {
+1 -21
View File
@@ -4,7 +4,7 @@ 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 { agentApiReply, loadReport, prefersHtml, prefersMarkdown } from "../../src/report/agent-api";
import { loadReport, prefersHtml, prefersMarkdown } from "../../src/report/agent-api";
import { readZipDirectory } from "../../src/report/zip-reader";
const subtle = webcrypto.subtle as SubtleCrypto;
@@ -286,23 +286,3 @@ 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");
});