apify-test-tools 0.10.2-beta.2 → 0.10.2-beta.4

package/.github/scripts/run-with-apify-tokens.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Runs apify-test-tools and passes it only secrets needed for the Actors, no other secrets are leaked.
 //
-//     node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build --target-branch ...
+//     node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build-for-test --target-branch ...
 //
 // The step passes the whole secrets map as ALL_SECRETS. The token names come from `tokenEnvVar` in
 // the repo's apify-test-tools.config.json, which is the same file apify-test-tools itself reads, so

package/.github/workflows/public_pr-build-test.yaml

@@ -41,31 +41,39 @@ jobs:
                   # This is needed to force overriding the cache with new entry at the end
                   restore-keys: base_commit-
 
-            # run-with-apify-tokens.mjs reads the token names from in apify-test-tools.config.json
-            # and hands the build those secrets and nothing else, so the tokens stay in this one command instead of the whole job.
-            # The library never sees secrets it doesn't need
-            - name: Build
-              id: build
+            # Needs no tokens, it only reads git and apify-test-tools.config.json. The setup action checks out
+            # the PR branch itself (not GitHub's merge commit), so the range ends at the branch's HEAD.
+            - name: Find affected Actors
               env:
-                  ALL_SECRETS: ${{ toJSON(secrets) }}
                   # Branch names are attacker-controlled on fork PRs, so they reach the script as
                   # environment variables rather than being interpolated into it.
-                  HEAD_REF: ${{ github.head_ref }}
                   BASE_REF: ${{ github.base_ref }}
-                  SCRIPTS_PATH: ${{ steps.setup.outputs.scripts-path }}
               run: |
                   base_commit=$(cat base_commit.txt 2>/dev/null || echo "")
                   echo "Last validated (base) commit to be used for build & test: $base_commit"
                   args=(
-                    --source-branch "origin/$HEAD_REF"
-                    --target-branch "origin/$BASE_REF"
+                    --base "origin/$BASE_REF"
                     # TODO: Temporary hotfix until build glob matching aligns with Vitest's test selection glob.
                     --test-files-glob 'test/platform/**'
-                    --use-docker-cache
                   )
-                  [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
-                  actor_builds=$(node "$SCRIPTS_PATH/run-with-apify-tokens.mjs" \
-                    apify-test-tools build "${args[@]}")
+                  [ -n "$base_commit" ] && args+=(--since "$base_commit")
+                  apify-test-tools get-affected-actors "${args[@]}" > affected.json
+
+            # Cosmetic-only changes need no tests, so only the functionally changed Actors are built, into the
+            # test version 0.99 that users never run.
+            # run-with-apify-tokens.mjs reads the token names from in apify-test-tools.config.json
+            # and hands the build those secrets and nothing else, so the tokens stay in this one command instead of the whole job.
+            # The library never sees secrets it doesn't need
+            - name: Build
+              id: build
+              # bash rather than the default shell, for pipefail
+              shell: bash
+              env:
+                  ALL_SECRETS: ${{ toJSON(secrets) }}
+                  SCRIPTS_PATH: ${{ steps.setup.outputs.scripts-path }}
+              run: |
+                  actor_builds=$(jq '{ actors: .functionallyChangedActors }' affected.json \
+                    | node "$SCRIPTS_PATH/run-with-apify-tokens.mjs" apify-test-tools build --version-number 0.99)
                   echo "actor_builds=$actor_builds" | tee -a "$GITHUB_OUTPUT"
 
             # Runs the repo's test code and its whole import graph, so it gets the tester token only.
@@ -77,18 +85,10 @@ jobs:
 
             # NOTE: This is an optimization that if we did functional changes and later only cosmetic changes (e.g. dev readme), we will compare changes files only for the last commit. This must run after tests because we want to cache the latest commit only if the tests are successful
             - name: Store last validated commit to cache
-              env:
-                  HEAD_REF: ${{ github.head_ref }}
-                  BASE_REF: ${{ github.base_ref }}
               run: |
-                  base_commit=$(cat base_commit.txt 2>/dev/null || echo "")
-                  echo "Old last validated (base) commit: $base_commit"
-                  args=(
-                    --source-branch "origin/$HEAD_REF"
-                    --target-branch "origin/$BASE_REF"
-                  )
-                  [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
-                  apify-test-tools get-latest-commit "${args[@]}" > ./base_commit.txt
+                  echo "Old last validated (base) commit: $(cat base_commit.txt 2>/dev/null || echo "")"
+                  # The HEAD that was just built and tested
+                  jq -r .head affected.json > base_commit.txt
                   echo "New last validated (base) commit: $(cat base_commit.txt)"
 
     # Pure static checks against the repo. Needs no Apify or Slack credentials, only the npm

package/.github/workflows/public_push-build-latest.yaml

@@ -25,18 +25,34 @@ jobs:
               with:
                   npm-token: ${{ secrets.NPM_TOKEN }}
 
-            # --base-commit is the last commit that is already released: the push's "before" commit.
+            # --since is the last commit that is already released: the push's "before" commit.
             # Everything after it up to HEAD gets released. See the "Releasing Actors" section of the README.
+            # Needs no tokens, it only reads git and apify-test-tools.config.json.
+            - name: Find changes since the last release
+              run: |
+                  apify-test-tools get-affected-actors --since ${{ github.event.before }} > affected.json
+
+            # A release ships cosmetic changes too (README, input schema descriptions), so both lists are built,
+            # into each Actor's default version: the one its default build tag points to, which users run.
             # run-with-apify-tokens.mjs reads the token names from in apify-test-tools.config.json
             # and hands the build those secrets and nothing else, so the tokens stay in this one command instead of the whole job.
             # The library never sees secrets it doesn't need
-            - name: Release Actors and notify
+            - name: Build the default versions
+              # bash rather than the default shell, for pipefail
+              shell: bash
               env:
                   ALL_SECRETS: ${{ toJSON(secrets) }}
+              run: |
+                  jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' affected.json \
+                    | node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
+                        apify-test-tools build --version-number default
+
+            # Skips the announcement when the push brought no new commits
+            - name: Announce the release on Slack
+              env:
                   SLACK_TOKEN_RELEASES_BOT: ${{ secrets.SLACK_TOKEN_RELEASES_BOT }}
               run: |
-                  node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-                    apify-test-tools release --base-commit ${{ github.event.before }} --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" --use-docker-cache
+                  apify-test-tools notify-release --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" < affected.json
 
             - name: Delete old builds
               env:

package/CHANGELOG.md

@@ -8,6 +8,8 @@ All notable changes to this project will be documented in this file.
 ### 🚀 Features
 
 - **ci:** Ship the workflows' CLI as a bundle in the action instead of installing it ([#200](https://github.com/apify/apify-test-tools/pull/200)) ([a0ef975](https://github.com/apify/apify-test-tools/commit/a0ef9756123a30a8210590b080a2a289c6a9c17c)) by [@metalwarrior665](https://github.com/metalwarrior665)
+- [**breaking**] Revamp get-affected-actors to be a core logic command ([#190](https://github.com/apify/apify-test-tools/pull/190)) ([ea5f244](https://github.com/apify/apify-test-tools/commit/ea5f244cfd42bf3fa9ffd38cd2ad499dde2e83f8)) by [@metalwarrior665](https://github.com/metalwarrior665)
+- [**breaking**] Add logic-less build command and use command chaining in workflows ([#193](https://github.com/apify/apify-test-tools/pull/193)) ([e5b0b86](https://github.com/apify/apify-test-tools/commit/e5b0b86ee06fca51d4be0ddc81b0a4a469d31603)) by [@metalwarrior665](https://github.com/metalwarrior665)
 
 ### 🐛 Bug Fixes
 

package/README.md

@@ -57,7 +57,7 @@ When a PR is opened or code is pushed, the tool determines which actors need to
 2. **CHANGELOG classification** — a `CHANGELOG.md` file is always `cosmetic` (only triggers a release build, not tests), for every actor, regardless of context or folder. (See [issue #106](https://github.com/apify/apify-test-tools/issues/106).)
 3. **Context matching** — the file must fall within one of the actor's context paths (`dockerContextDir` from `actor.json` by default, or `overrideActorContext` from config if set). Files outside every context path are skipped.
 4. **Hardcoded ignore list, context-aware** — the file path is first "hoisted" relative to the context path it matched (e.g. a standalone actor's own `.eslintrc` is checked as just `.eslintrc`, not the full repo-root-relative path), then checked against repo-level dev file patterns (`.vscode/`, `.gitignore`, `.husky/`, `.eslintrc`, `eslint.config.mjs`, `.prettierrc`, `.editorconfig`). There's no hardcoded special-casing for legacy `code/`/`shared/` layouts — repos that need those directories treated as top-level must list them explicitly in `overrideActorContext`.
-5. **`.dockerignore` filtering** — if a `.dockerignore` exists at the root of the actor's `dockerContextDir`, matching files are ignored. Patterns are resolved relative to `dockerContextDir`, matching Docker's own behavior. Test files are the exception: `build --test-files-glob <glob>` (relative to the repo root) skips this check for matching files, so a changed test triggers a build, and with it its tests, even when `.dockerignore` lists it. The PR workflow passes `test/platform/**`. Context matching still applies, so tests outside an actor's `dockerContextDir` (e.g. a root `test/` with standalone actors) need to be listed in its `overrideActorContext`; `build` logs a warning for changed test files outside every actor's context.
+5. **`.dockerignore` filtering** — if a `.dockerignore` exists at the root of the actor's `dockerContextDir`, matching files are ignored. Patterns are resolved relative to `dockerContextDir`, matching Docker's own behavior. Test files are the exception: `build-for-test --test-files-glob <glob>` (relative to the repo root, also taken by `get-affected-actors`) skips this check for matching files, so a changed test triggers a build, and with it its tests, even when `.dockerignore` lists it. The PR workflow passes `test/platform/**`. Context matching still applies, so tests outside an actor's `dockerContextDir` (e.g. a root `test/` with standalone actors) need to be listed in its `overrideActorContext`; `build-for-test` logs a warning for changed test files outside every actor's context.
 6. **README classification** — a `README.md` file is `cosmetic` (only triggers a release build, not tests) if it lives inside the actor's own `folder`; otherwise it's ignored entirely, since it isn't documentation for this actor.
 7. **Cosmetic JSON classification** — `.json` files inside the actor's own `.actor/` directory with only cosmetic schema changes (whitespace, key ordering) only trigger a release build.
 8. **Functional** — everything else triggers both build and tests.
@@ -226,9 +226,10 @@ jobs:
         secrets: inherit
 ```
 
-This workflow runs `apify-test-tools release --base-commit ${{ github.event.before }}`. See
-[Releasing Actors](#releasing-actors-release) for how the released range is determined and what to
-pass if you call the CLI from somewhere else.
+This workflow does what `apify-test-tools release --base-commit ${{ github.event.before }}` does, one
+step per command: `get-affected-actors --since ${{ github.event.before }}`, then `build --version-number default`
+on every changed Actor, then `notify-release`. See [Releasing Actors](#releasing-actors-release) for how the
+released range is determined and what to pass if you call the CLI from somewhere else.
 
 ### `claude-review.yaml`
 
@@ -261,9 +262,9 @@ environment variables, so a secret is only visible to the step that needs it:
 | Secret                                                                    | Reaches                                                                                                                                                                                                                      |
 | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `NPM_TOKEN`                                                               | dependency install steps only, as both `NPM_TOKEN` and `NODE_AUTH_TOKEN`. Use a read-only token: npm granular tokens can be read-only, classic automation tokens can publish.                                                |
-| the Actor tokens named by `tokenEnvVar` in `apify-test-tools.config.json` | the `build`, `release`, and `delete-old-builds` steps only                                                                                                                                                                   |
+| the Actor tokens named by `tokenEnvVar` in `apify-test-tools.config.json` | the build and `delete-old-builds` steps only                                                                                                                                                                                 |
 | `TESTER_APIFY_TOKEN`                                                      | the vitest step, and the Claude investigation step: the Apify MCP server's bearer token for reading the failing run, its log and its storages, and Claude's token for re-running it to measure how often the failure happens |
-| `SLACK_TOKEN_TESTS_BOT` / `SLACK_TOKEN_RELEASES_BOT`                      | the reporting and release steps only                                                                                                                                                                                         |
+| `SLACK_TOKEN_TESTS_BOT` / `SLACK_TOKEN_RELEASES_BOT`                      | the reporting and announcement steps only                                                                                                                                                                                    |
 
 The Actor tokens are the one set that cannot be listed in the workflow, because each Actor names its
 own token via `tokenEnvVar` in `apify-test-tools.config.json`. Those steps pass
@@ -277,7 +278,7 @@ secrets to pass on:
       ALL_SECRETS: ${{ toJSON(secrets) }}
   run: |
       node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-        npx apify-test-tools build --target-branch ...
+        npx apify-test-tools build-for-test --target-branch ...
 ```
 
 The wrapper passes only the tokens the config declares and drops `ALL_SECRETS`, so neither `npx` nor
@@ -568,12 +569,12 @@ The package includes a CLI binary used by CI workflows to build Actors, detect c
 
 ### Dry runs (`--dry-run`)
 
-Every command that changes something (`build`, `build-from-local`, `release`, `delete-old-builds`, `report-tests`) takes `--dry-run`. A dry run:
+Every command that changes something (`build`, `build-for-test`, `build-from-local`, `release`, `notify-release`, `delete-old-builds`, `report-tests`) takes `--dry-run`. A dry run:
 
 - **Changes nothing.** No versions or builds are created, nothing is uploaded or deleted, and no Slack message is posted.
 - **Does every read and check the real run does**, so it fails wherever the real run would: change detection, the Apify token and Actor lookup, the [repository check](#repository-check), collecting and zipping local sources, and the Slack token (verified with Slack's read-only `auth.test`).
 - **Needs the same tokens as the real run.** Read-only tokens are enough, since nothing is written. A dry run can't tell whether a token is also allowed to write, because the Apify API has no dry-run mode of its own.
-- **Prints a plan, not results.** Logs start with `[DRY RUN] Would …`. `build` and `build-from-local` write `{ "dryRun": true, "builds": [...] }` to stdout instead of the build array, so the plan can't be passed to tests as `ACTOR_BUILDS` by mistake.
+- **Prints a plan, not results.** Logs start with `[DRY RUN] Would …`. `build`, `build-for-test` and `build-from-local` write `{ "dryRun": true, "builds": [...] }` to stdout instead of the build array, so the plan can't be passed to tests as `ACTOR_BUILDS` by mistake.
 
 ### Running locally
 
@@ -599,13 +600,15 @@ Requires `APIFY_TOKEN_<USERNAME>` for all Apify users that own your Actors (e.g.
 
 ```bash
 APIFY_TOKEN_JOHN_DOE=<token> \
-  npx apify-test-tools build \
+  npx apify-test-tools build-for-test \
     --target-branch origin/master \
-    --source-branch origin/my-dummy-branch \
     --dry-run
 ```
 
-With `--dry-run`, it prints the plan (the version and Git URL each Actor would be built from). Remove `--dry-run` to actually trigger builds and update the branch names. The command outputs a JSON array of build objects to stdout:
+Run it with your dummy branch checked out: it builds the Actors that branch changed, from the branch as it is on
+the remote. With `--dry-run`, it prints the plan (the version and Git URL each Actor would be built from). Remove
+`--dry-run` to actually trigger builds and update the target branch name. The command outputs a JSON array of build
+objects to stdout:
 
 ```json
 [{ "buildId": "...", "actorRawId": "...", "buildNumber": "...", "actorFullName": "john.doe/my-actor" }]
@@ -649,9 +652,8 @@ Tests only run for Actors in `ACTOR_BUILDS`, so a custom workflow has to build (
 ```bash
 # Build and capture output
 BUILDS=$(APIFY_TOKEN_JOHN_DOE=apify_api_xxx \
-    npx apify-test-tools build \
+    npx apify-test-tools build-for-test \
     --target-branch origin/master \
-    --source-branch origin/my-dummy-branch \
     --test-files-glob 'test/platform/**')
 
 # Run tests with the builds
@@ -660,6 +662,100 @@ TESTER_APIFY_TOKEN=apify_api_yyy \
   npx vitest --run --maxConcurrency 20 --fileParallelism=true --maxWorkers 100 test/platform
 ```
 
+### Finding affected Actors (`get-affected-actors`)
+
+`get-affected-actors` lists the Actors whose context changed in a commit range, using the rules in
+[Change detection](#change-detection). It only reads git and the config file, so it needs no tokens.
+The range always ends at the checked-out `HEAD`, so check out the branch you want to inspect first.
+
+```bash
+# A PR: the branch's own commits, after its last validated commit
+npx apify-test-tools get-affected-actors --base origin/master --since <sha>
+
+# A release: everything after the last released commit
+npx apify-test-tools get-affected-actors --since <sha>
+```
+
+| Flag                | Default | Meaning                                                                                                                                    |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--base`            |         | Only commits on `HEAD` that are not on this branch count                                                                                   |
+| `--since`           |         | Only commits after this one count (see below)                                                                                              |
+| `--test-files-glob` |         | Test files (glob from the repo root) that count as changes even when `.dockerignore` lists them, see [Change detection](#change-detection) |
+| `--actors`          | all     | Only report these Actors                                                                                                                   |
+| `--ignore`          | none    | Never report these Actors                                                                                                                  |
+
+Pass `--base`, `--since`, or both:
+
+- **`--base` only** inspects the whole branch. If the branch merged `--base` in and has no functional changes
+  of its own, no Actor is reported as functional, since `--base` is already validated (and none as cosmetic
+  either, if the branch has no changes of its own at all).
+- **`--base` and `--since`** inspects the branch after its last validated commit. If `--since` is not on the
+  branch (force-push), or it is the head (a rerun), the whole branch is inspected instead.
+- **`--since` only** inspects everything after it up to `HEAD`. It must be an ancestor of `HEAD` and fails
+  otherwise, exactly like [`--base-commit` of `release`](#--base-commit). If `HEAD` is `--since`, nothing is
+  reported.
+
+The output is a JSON document:
+
+```json
+{
+    "version": 1,
+    "head": "<sha of HEAD>",
+    "commits": [{ "sha": "…", "author": "…", "date": "…", "message": "…" }],
+    "changedFiles": ["src/main.ts", "CHANGELOG.md"],
+    "changelog": "Lines added to CHANGELOG.md, or null",
+    "functionallyChangedActors": [{ "actorFullName": "john.doe/my-actor" }],
+    "cosmeticallyChangedActors": [{ "actorFullName": "john.doe/other-actor" }]
+}
+```
+
+Each changed Actor is in exactly one of the lists. `functionallyChangedActors` have at least one functional change, so
+they need a new build and tests. `cosmeticallyChangedActors` only have cosmetic changes (see
+[Change detection](#change-detection)), so they need a new build only when released: `build-for-test` builds
+`functionallyChangedActors`, `release` builds both.
+
+`build-for-test` and `release` use the same detection internally.
+
+### Building Actors (`build`)
+
+`build` builds exactly the Actors it is given on stdin, from the checked-out branch as it is on the remote, and
+prints the builds as the same JSON array `build-for-test` and `build-from-local` print. A detached HEAD is an
+error, since there is no branch to build from. It doesn't look at git history: which Actors to build is
+up to you, usually picked from the output of [`get-affected-actors`](#finding-affected-actors-get-affected-actors).
+
+```bash
+# What build-for-test does: the Actors a branch changed functionally, built into the test version
+npx apify-test-tools get-affected-actors --base origin/master \
+  | jq '{ actors: .functionallyChangedActors }' \
+  | npx apify-test-tools build --version-number 0.99
+
+# What release builds: every Actor changed since the last release, into the version users run
+npx apify-test-tools get-affected-actors --since <sha> \
+  | jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' \
+  | npx apify-test-tools build --version-number default
+
+# One Actor, whatever changed
+echo '{ "actors": [{ "actorFullName": "john.doe/my-actor" }] }' | npx apify-test-tools build --version-number 0.99
+```
+
+The input is `{ "actors": [{ "actorFullName": "<owner/name>" }] }`; other fields are ignored. An empty `actors` list builds nothing and prints `[]`. Empty or invalid input is an error,
+so a failed command earlier in the pipe can't turn into a successful run that built nothing. In GitHub
+Actions, give such a step `shell: bash` so the pipe also fails on its own (the default shell has no `pipefail`).
+
+| Flag               | Default             | Meaning                                                                                                                |
+| ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `--version-number` | required            | Version to build, like `0.99`, or `default` for each Actor's default version (the one its default build tag points to) |
+| `--repo-url`       | the `origin` remote | Repository to build from, see [Repository check](#repository-check)                                                    |
+
+`build` never sets or changes build tags. A build gets the tag its version is configured with on the platform,
+so building the default version moves its tag (usually `latest`) to the new build, and building a version
+without a tag leaves every tag where it is. Builds always use the Docker cache.
+
+`build-for-test` and `release` are shortcuts for the two pipelines above, with the flags they always had.
+`build-for-test` takes `--target-branch`, `--base-commit` and `--test-files-glob`, inspects and builds the
+checked-out branch, and builds into version `0.99`. `release` takes `--base-commit`, and announces the release on Slack after building, the same
+way `notify-release` does.
+
 ### Releasing Actors (`release`)
 
 `release` builds the `latest` (default) version of every Actor changed since the last release and
@@ -671,6 +767,15 @@ the `origin` remote.
 npx apify-test-tools release --base-commit <sha> --release-slack-channel "#releases" --dry-run
 ```
 
+The announcement is also its own command, `notify-release`, which reads the output of `get-affected-actors` on
+stdin. It posts the changelog additions to `--release-slack-channel` and the commits and changed files to
+`--report-slack-channel`, and posts nothing when there are no new commits. It needs `SLACK_TOKEN_RELEASES_BOT`.
+
+```bash
+npx apify-test-tools get-affected-actors --since <sha> \
+  | npx apify-test-tools notify-release --release-slack-channel "#releases" --dry-run
+```
+
 #### `--base-commit`
 
 The last commit that is **already released**. Everything after it, up to `HEAD`, is released. It is

package/bin/affected-actors.ts

@@ -0,0 +1,157 @@
+import { type ChangedActors, getChangedActors } from './diff-changes.js';
+import {
+    getBranchOnlyChangedFiles,
+    getChangedFilesBetween,
+    getChangelogAdditions,
+    getCommits,
+    getCommitsBetween,
+    hasMergeFromTarget,
+    resolveCommitSha,
+    resolveReleaseBaseCommit,
+} from './git.js';
+import { logger } from './logger.js';
+import type { ActorConfig, Commit } from './types.js';
+import { readConfigFile } from './utils/config/load-config.js';
+
+// The range always ends at the checked-out commit: check out what you want to inspect
+const HEAD = 'HEAD';
+
+interface AffectedActorsOptions {
+    /** Only the commits on HEAD that are not on base count, i.e. the branch's own changes. */
+    base?: string;
+    /**
+     * Only changes after this commit count. With `base` it's the last validated commit of the branch and is
+     * ignored when it isn't on the branch. Without `base` it must be an ancestor of HEAD (e.g. the last release).
+     */
+    since?: string;
+    /** Glob relative to the repo root. Matching files count as changes even when .dockerignore lists them. */
+    testFilesGlob?: string;
+    actors: string[];
+    ignore: string[];
+}
+
+interface AffectedActors {
+    headSha: string;
+    commits: Commit[];
+    changedFiles: string[];
+    changelog: string | null;
+    /** Actors with at least one functional change. They need a new build and tests. */
+    functionallyChangedActors: ActorConfig[];
+    /** Actors whose changes are all cosmetic (README, CHANGELOG, cosmetic .actor JSON). They only need a release build. */
+    cosmeticallyChangedActors: ActorConfig[];
+}
+
+interface CommitRange {
+    commits: Commit[];
+    fromRef: string;
+    toRef: string;
+}
+
+/** The branch's own commits, after `since` when it is on the branch (see getCommits). */
+const getBranchRange = async (base: string, since: string | undefined): Promise<CommitRange> => {
+    const commits = await getCommits({ sourceBranch: HEAD, targetBranch: base, baseCommit: since });
+    return { commits, fromRef: `${commits[0].sha}~`, toRef: commits[commits.length - 1].sha };
+};
+
+/** Everything after `since` up to HEAD. Unlike on a branch, `since` must be an ancestor of HEAD. */
+const getRangeSince = async (headSha: string, since: string): Promise<CommitRange> => {
+    const sinceSha = await resolveReleaseBaseCommit(since);
+    const commits = sinceSha === headSha ? [] : await getCommitsBetween(sinceSha, headSha);
+    return { commits, fromRef: sinceSha, toRef: headSha };
+};
+
+/**
+ * This is an optimization for the common case where a branch only has cosmetic changes but had to merge in
+ * functional changes from base (being up-to-date is a CI requirement). Base is already validated, and
+ * since the branch has no functional changes of its own, there is nothing new to validate.
+ * Exception: if the branch has any functional changes alongside the merge, we must re-test — even
+ * individually validated changes can have novel interactions when combined.
+ * Returns the Actors the branch's own commits changed, or undefined when it didn't merge base in.
+ *
+ * TODO: Apply this per Actor instead of to the whole branch. Changes merged in from base only interact with the
+ * branch's own changes in Actors whose context both touch, so an Actor that only base changed is already validated
+ * and can be skipped even when the branch changes other Actors functionally. Today any functional change of the
+ * branch's own keeps every Actor, and the log messages below describe the whole branch.
+ */
+const getOwnChangesIfMergedFromBase = async (
+    base: string,
+    actorConfigs: ActorConfig[],
+    testFilesGlob: string | undefined,
+): Promise<ChangedActors | undefined> => {
+    if (!(await hasMergeFromTarget(HEAD, base))) return undefined;
+
+    logger.info(
+        '[MERGE-FROM-TARGET-OPTIMIZATION]: There is merge from target branch, checking if there are no functional changes in our own branch. If so, we can skip tests',
+    );
+    const own = await getChangedActors({
+        filepathsChanged: await getBranchOnlyChangedFiles(HEAD, base),
+        actorConfigs,
+        // Omit since to get full branch history. Validated functional commits can still interact with merged ones
+        commits: await getCommits({ sourceBranch: HEAD, targetBranch: base }),
+        testFilesGlob,
+    });
+    logger.info(
+        own.functional.length > 0
+            ? `[MERGE-FROM-TARGET-OPTIMIZATION]: Branch has ${own.functional.length} functional changes, cannot optimize, we continue with full check`
+            : '[MERGE-FROM-TARGET-OPTIMIZATION]: Branch itself has no functional changes, skipping tests',
+    );
+    return own;
+};
+
+/**
+ * Finds the Actors whose context changed in the given range. `base` selects the branch's own commits
+ * (a PR), `since` the commits after a known one (a release, or the last validated commit of a PR).
+ */
+export const getAffectedActors = async ({
+    base,
+    since: sinceOption,
+    testFilesGlob,
+    actors,
+    ignore,
+}: AffectedActorsOptions): Promise<AffectedActors> => {
+    // An empty --since (e.g. an empty cache file) means the same as not passing it
+    const since = sinceOption || undefined;
+    if (!base && !since) {
+        throw new Error('Pass --base, --since, or both to select the commits to inspect.');
+    }
+
+    const headSha = await resolveCommitSha(HEAD);
+    const { commits, fromRef, toRef } = base ? await getBranchRange(base, since) : await getRangeSince(headSha, since!);
+    const actorConfigs = await readConfigFile({ actors, ignore });
+
+    // What the branch only merged in from base is already validated. Without functional changes of its own
+    // the branch has nothing to test, and without any changes of its own nothing to release either.
+    const own = base ? await getOwnChangesIfMergedFromBase(base, actorConfigs, testFilesGlob) : undefined;
+    const changedFiles = await getChangedFilesBetween(fromRef, toRef);
+    const changed = await getChangedActors({ filepathsChanged: changedFiles, actorConfigs, commits, testFilesGlob });
+
+    return {
+        headSha,
+        commits,
+        changedFiles,
+        changelog: await getChangelogAdditions(fromRef, toRef, changedFiles),
+        functionallyChangedActors: own && own.functional.length === 0 ? [] : changed.functional,
+        cosmeticallyChangedActors: own && own.functional.length + own.cosmetic.length === 0 ? [] : changed.cosmetic,
+    };
+};
+
+/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
+export const toAffectedActorsDocument = ({
+    headSha,
+    commits,
+    changedFiles,
+    changelog,
+    functionallyChangedActors,
+    cosmeticallyChangedActors,
+}: AffectedActors) => {
+    const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
+    return {
+        version: 1,
+        head: headSha,
+        commits,
+        changedFiles,
+        changelog,
+        functionallyChangedActors: names(functionallyChangedActors),
+        cosmeticallyChangedActors: names(cosmeticallyChangedActors),
+    };
+};