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

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-for-test --target-branch ...
+//     jq ... | node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build --version-number 0.99
 //
 // 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/CHANGELOG.md

@@ -10,12 +10,17 @@ All notable changes to this project will be documented in this file.
 - **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)
+- **get-affected-actors:** Three-dot diff, narrowed per Actor with --since ([#204](https://github.com/apify/apify-test-tools/pull/204)) ([fa9a0e7](https://github.com/apify/apify-test-tools/commit/fa9a0e7518764dd4722ec9ecbf67b2a26a5a062e)) by [@metalwarrior665](https://github.com/metalwarrior665)
 
 ### 🐛 Bug Fixes
 
 - **toBeObject:** Reject null ([#191](https://github.com/apify/apify-test-tools/pull/191)) ([6bdae49](https://github.com/apify/apify-test-tools/commit/6bdae4905756e0ae8dd6146942e6fc04dbead48e)) by [@JuanGalilea](https://github.com/JuanGalilea), closes [#88](https://github.com/apify/apify-test-tools/issues/88)
 - Build and test on test-only changes even when .dockerignore lists the tests ([#177](https://github.com/apify/apify-test-tools/pull/177)) ([5cb1b5a](https://github.com/apify/apify-test-tools/commit/5cb1b5ab5f6f43ec279f9624b402e73d55a5974a)) by [@artogahr](https://github.com/artogahr), closes [#145](https://github.com/apify/apify-test-tools/issues/145)
 
+### 🚜 Refactor
+
+- [**breaking**] Remove build-for-test and release composite commands ([#203](https://github.com/apify/apify-test-tools/pull/203)) ([85efc54](https://github.com/apify/apify-test-tools/commit/85efc54697e98208c827c4f450906e00eebcd9ca)) by [@metalwarrior665](https://github.com/metalwarrior665)
+
 
 <!-- git-cliff-unreleased-end -->
 ## [0.10.1](https://github.com/apify/apify-test-tools/releases/tag/v0.10.1) (2026-10-13)

package/CONTRIBUTING.md

@@ -94,9 +94,12 @@ npm release relate — the short version:
 - the CLI runs from `.github/cli/apify-test-tools.mjs`, a bundle the pre-commit hook rebuilds with
   `npm run bundle`. If you commit with `--no-verify`, run it yourself: the `CLI bundle` check fails
   on a stale bundle, and a stale bundle would hold the tag.
-- `npm test` covers the bundle without network (`test/bundle/`). `npm run test:e2e` runs it against two
+- `npm test` covers the bundle without network (`test/bundle/`). `npm run test:e2e` runs it against
   dummy Actors in an isolated sandbox account (`test/e2e/`) and skips itself unless
   `E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR` is set. CI passes that secret only to the `E2E tests` job.
+  The git `build` and release pipeline tests clone
+  [testing-repo-for-github-actions](https://github.com/apify-store/testing-repo-for-github-actions) and
+  use its `e2e/base` and `e2e/feature` branches as fixtures, so never rebase or delete those.
 
 `npm run lint` and `actionlint` (via the `Code checks` workflow) both gate master, so run them before
 pushing workflow changes.

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-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.
+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: `get-affected-actors --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`; `get-affected-actors` 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,8 @@ jobs:
         secrets: inherit
 ```
 
-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
+This workflow runs 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) for how the
 released range is determined and what to pass if you call the CLI from somewhere else.
 
 ### `claude-review.yaml`
@@ -274,11 +273,13 @@ secrets to pass on:
 
 ```yaml
 - name: Build
+  shell: bash
   env:
       ALL_SECRETS: ${{ toJSON(secrets) }}
   run: |
-      node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-        npx apify-test-tools build-for-test --target-branch ...
+      jq '{ actors: .functionallyChangedActors }' affected.json \
+        | node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
+          npx apify-test-tools build --version-number 0.99
 ```
 
 The wrapper passes only the tokens the config declares and drops `ALL_SECRETS`, so neither `npx` nor
@@ -569,12 +570,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-for-test`, `build-from-local`, `release`, `notify-release`, `delete-old-builds`, `report-tests`) takes `--dry-run`. A dry run:
+Every command that changes something (`build`, `build-from-local`, `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`, `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.
+- **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.
 
 ### Running locally
 
@@ -599,16 +600,15 @@ If you want to test vs existing src code, you can skip this and instead construc
 Requires `APIFY_TOKEN_<USERNAME>` for all Apify users that own your Actors (e.g. `apify`, `compass`, `lukaskrivka` users). The username is derived from the actor name — uppercased with non-word chars replaced by `_` (e.g. Actor `john.doe/my-actor` needs `APIFY_TOKEN_JOHN_DOE`).
 
 ```bash
-APIFY_TOKEN_JOHN_DOE=<token> \
-  npx apify-test-tools build-for-test \
-    --target-branch origin/master \
-    --dry-run
+npx apify-test-tools get-affected-actors --base origin/master \
+  | jq '{ actors: .functionallyChangedActors }' \
+  | APIFY_TOKEN_JOHN_DOE=<token> npx apify-test-tools build --version-number 0.99 --dry-run
 ```
 
-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:
+Run it with your dummy branch checked out: it builds the Actors that branch changed functionally, from the branch
+as it is on the remote, into the test version `0.99`. 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 `--base` to the branch
+you compare against. `build` outputs a JSON array of build objects to stdout:
 
 ```json
 [{ "buildId": "...", "actorRawId": "...", "buildNumber": "...", "actorFullName": "john.doe/my-actor" }]
@@ -647,14 +647,13 @@ TESTER_APIFY_TOKEN=<token> \
 
 #### Full example
 
-Tests only run for Actors in `ACTOR_BUILDS`, so a custom workflow has to build (and pass) the Actors even when only tests changed. Pass `--test-files-glob` so test changes count even when `.dockerignore` lists them.
+Tests only run for Actors in `ACTOR_BUILDS`, so a custom workflow has to build (and pass) the Actors even when only tests changed. Pass `--test-files-glob` to `get-affected-actors` so test changes count even when `.dockerignore` lists them.
 
 ```bash
 # Build and capture output
-BUILDS=$(APIFY_TOKEN_JOHN_DOE=apify_api_xxx \
-    npx apify-test-tools build-for-test \
-    --target-branch origin/master \
-    --test-files-glob 'test/platform/**')
+BUILDS=$(npx apify-test-tools get-affected-actors --base origin/master --test-files-glob 'test/platform/**' \
+    | jq '{ actors: .functionallyChangedActors }' \
+    | APIFY_TOKEN_JOHN_DOE=apify_api_xxx npx apify-test-tools build --version-number 0.99)
 
 # Run tests with the builds
 ACTOR_BUILDS="$BUILDS" \
@@ -669,7 +668,7 @@ TESTER_APIFY_TOKEN=apify_api_yyy \
 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
+# A PR: the branch's own changes, narrowed to the Actors that changed since its last validated commit
 npx apify-test-tools get-affected-actors --base origin/master --since <sha>
 
 # A release: everything after the last released commit
@@ -678,23 +677,31 @@ 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)                                                                                              |
+| `--base`            |         | Only what `HEAD` changes compared to this branch counts, like `git diff <base>...HEAD`                                                     |
+| `--since`           |         | Only changes after this commit 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.
+- **`--base` only** inspects what the branch changes, the same files GitHub's "Files changed" tab shows: the diff
+  from where the branch forked from `--base`, or the last commit of `--base` it merged in. What it merged in from
+  `--base` is already validated there, so it doesn't count.
+- **`--base` and `--since`** also inspects what changed after the branch's last validated commit, and reports only
+  the Actors that changed in both. An Actor in only one of them is already validated, by this branch or on `--base`.
+  When both changed an Actor, the changes can interact, so it is reported, but as functional only when both changes
+  are functional. A validated functional change followed by README edits is cosmetic, and so is a functional
+  change merged in from `--base` that meets only cosmetic changes of the branch. `--since` doesn't have to be on
+  the branch, so a rebase only re-checks the Actors that `--base` changed too. If `--since` is not in the local
+  history (a force-push), or it is `HEAD` (a rerun), it is ignored and the whole branch is checked.
 - **`--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
+  otherwise, see [Releasing Actors](#releasing-actors). If `HEAD` is `--since`, nothing is
   reported.
 
+`commits`, `changedFiles` and `changelog` describe the whole range, `--base...HEAD` or `--since..HEAD`: `--since`
+together with `--base` only narrows the Actor lists.
+
 The output is a JSON document:
 
 ```json
@@ -711,25 +718,23 @@ The output is a JSON document:
 
 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.
+[Change detection](#change-detection)), so they need a new build only when released: the PR workflow builds
+`functionallyChangedActors`, the release workflow builds both.
 
 ### 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
+prints the builds as the same JSON array `build-from-local` prints. 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
+# A PR: 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
+# A release: 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
@@ -751,39 +756,33 @@ Actions, give such a step `shell: bash` so the pipe also fails on its own (the d
 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
 
-### Releasing Actors (`release`)
-
-`release` builds the `latest` (default) version of every Actor changed since the last release and
-posts release notes to Slack. It reads everything else from git: the branch from the checked-out
-`HEAD`, the commits and changed files from the range `<base-commit>..HEAD`, and the repository from
-the `origin` remote.
+A release is three commands: find what changed since the last released commit, build those Actors into
+their default version (the one users run), and announce it.
 
 ```bash
-npx apify-test-tools release --base-commit <sha> --release-slack-channel "#releases" --dry-run
-```
+npx apify-test-tools get-affected-actors --since <sha> > affected.json
 
-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`.
+jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' affected.json \
+  | npx apify-test-tools build --version-number default --dry-run
 
-```bash
-npx apify-test-tools get-affected-actors --since <sha> \
-  | npx apify-test-tools notify-release --release-slack-channel "#releases" --dry-run
+npx apify-test-tools notify-release --release-slack-channel "#releases" --dry-run < affected.json
 ```
 
-#### `--base-commit`
+`notify-release` 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 names the release after the `origin` remote (or `--repo-url`) and the author of the
+newest commit, and needs `SLACK_TOKEN_RELEASES_BOT`.
+
+#### The last released commit (`--since`)
 
-The last commit that is **already released**. Everything after it, up to `HEAD`, is released. It is
-required: git alone can't tell which commits a push brought, and guessing wrong silently leaves Actors
-on old code.
+The last commit that is **already released**. Everything after it, up to `HEAD`, is released. Git alone
+can't tell which commits a push brought, and guessing wrong silently leaves Actors on old code, so it has
+to be passed.
 
-The changed files come from diffing `<base-commit>` and `HEAD` directly, so this works for every
-merge strategy as long as the base commit is the branch tip from **before** the push:
+The changed files come from diffing `--since` and `HEAD` directly, so this works for every merge strategy as
+long as `--since` is the branch tip from **before** the push:
 
 | Merge strategy                 | What lands on the branch          | What to pass                                                           |
 | ------------------------------ | --------------------------------- | ---------------------------------------------------------------------- |
@@ -793,26 +792,25 @@ merge strategy as long as the base commit is the branch tip from **before** the
 
 On GitHub, the push's "before" commit is `${{ github.event.before }}`, which the reusable workflow
 passes for you. On other CIs use the equivalent, e.g. `$CI_COMMIT_BEFORE_SHA` on GitLab. The checkout
-needs the full history (`fetch-depth: 0` in `actions/checkout`) so the base commit is available locally.
+needs the full history (`fetch-depth: 0` in `actions/checkout`) so the commit is available locally.
 
-`release` fails instead of guessing when:
+`get-affected-actors --since` without `--base` fails instead of guessing when:
 
-- the base commit is all zeros (GitHub sends this for a push that created the branch)
-- the base commit isn't in the local history (shallow checkout) or isn't an ancestor of `HEAD`
+- the commit is all zeros (GitHub sends this for a push that created the branch)
+- the commit isn't in the local history (shallow checkout) or isn't an ancestor of `HEAD`
   (the branch was force-pushed)
 
-In those cases, rerun `release` with a `--base-commit` you pick yourself: an ancestor of `HEAD` from
-before the changes you want to release (for a shallow checkout, fetch the full history instead).
-`--actors` only narrows which of the changed Actors get released; it never forces a build, so on its
-own it doesn't get past these errors.
-If `HEAD` is the base commit, there is nothing to release and the command exits successfully.
+In those cases, rerun it with a `--since` you pick yourself: an ancestor of `HEAD` from before the changes
+you want to release (for a shallow checkout, fetch the full history instead). `--actors` only narrows which
+of the changed Actors are reported; it never forces a build, so on its own it doesn't get past these errors.
+If `HEAD` is `--since`, nothing is reported, so nothing is built or announced.
 
 A failed release isn't retried by the next push: that push's base commit is the failed one's head, so
 its changes are skipped. Re-run the failed workflow run, or release the Actors manually.
 
 #### Repository check
 
-`release` and `build` point each Actor's version at the `origin` remote. Because a build overwrites the
+`build` points each Actor's version at the `origin` remote. Because a build overwrites the
 version's Git URL, building from a fork or a mirror would repoint the Actor. So, before building, the
 remote is compared with the Git URL of the Actor's default version (the one its default build tag
 points to), and the command fails if they differ or if the default version isn't built from a Git

package/bin/affected-actors.ts

@@ -1,27 +1,31 @@
 import { type ChangedActors, getChangedActors } from './diff-changes.js';
 import {
-    getBranchOnlyChangedFiles,
+    findCommitSha,
     getChangedFilesBetween,
     getChangelogAdditions,
-    getCommits,
     getCommitsBetween,
-    hasMergeFromTarget,
+    getMergeBase,
     resolveCommitSha,
     resolveReleaseBaseCommit,
 } from './git.js';
 import { logger } from './logger.js';
-import type { ActorConfig, Commit } from './types.js';
+import type { ActorConfig, Commit, GitRange } 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 usually points to the master branch
+     * Only what HEAD changes compared to base counts, like `git diff base...HEAD` or GitHub's "Files changed" tab:
+     * the branch's own changes, not what it merged in from base.
+     */
     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).
+     * With `base` it's the last validated commit of the branch: Actors that didn't change after it are left out.
+     * It's ignored when it is HEAD (a rerun) or isn't in the local history. Without `base` everything after it
+     * counts, and 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. */
@@ -30,77 +34,113 @@ interface AffectedActorsOptions {
     ignore: string[];
 }
 
+/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
 interface AffectedActors {
-    headSha: string;
+    version: 1;
+    head: string;
+    /** The commits, changed files and changelog describe the whole range, `--since` with `--base` only narrows the Actors. */
     commits: Commit[];
     changedFiles: string[];
     changelog: string | null;
-    /** Actors with at least one functional change. They need a new build and tests. */
-    functionallyChangedActors: ActorConfig[];
+    /**
+     * Actors with at least one functional change. They need a new build and tests. Only the names: the config file
+     * stays the source of truth for the rest.
+     */
+    functionallyChangedActors: { actorFullName: string }[];
     /** 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;
+    cosmeticallyChangedActors: { actorFullName: 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 };
-};
+const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
 
-/** 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 };
+/** The branch's last validated commit, unless it can't narrow anything down. */
+const findValidatedSha = async (since: string, headSha: string): Promise<string | undefined> => {
+    const sinceSha = await findCommitSha(since);
+    if (!sinceSha) {
+        logger.info(
+            `Last validated commit ${since} is not in the local history (force-push?), checking the whole branch`,
+        );
+        return undefined;
+    }
+    if (sinceSha === headSha) {
+        logger.info('Last validated commit is HEAD, so this is a rerun: checking the whole branch from scratch');
+        return undefined;
+    }
+    return sinceSha;
 };
 
 /**
- * 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.
+ * This is Juan's magical algorithm where we need just 2 git diffs to determine functional changes on Actors.
+ *
+ * Naively, we could just check branch HEAD changes vs base or parent of first commit and be done but
+ * we do this jiu-jitsu code to apply 2 optimizations:
+ * 1. On our PR branch, we track last validated commit (since) that was tested and so we only need to test new commits.
+ * 2. We also merge changes from the base branch (usually master) and we can consider those already validated as well.
+ *
+ * But there is annoying problem: even if both our branch and base are validated, they could have novel interactions and
+ * we need to retest those.
+ *
+ * So we look at:
+ * 1. The changes introduced by our branch since the last validated commit (`since..HEAD`).
+ * 2. The changes introduced by the branch compared to the base branch (`base...HEAD`). The important part is that this
+ * diff does check the whole branch, discarding the last validated commit (since) so it checks those novel interactions problem.
+ *
+ * The magic is that both need to contain changes for an Actor to be retested:
+ * 1. If we have changes only in since..HEAD (and not in base...HEAD), it means those changes came from merging the base alone
+ * which is already validated and there were actually no real changes introduced by our branch alone.
+ * 2. If we have changes only in base...HEAD (and not in since..HEAD), it means there are no new changes on our branch
+ * since it was last validated. base...HEAD has changes that we already validated.
+ *
+ * This enables to simply do those 2 diffs for each Actor's context separately and only Actors that have changes
+ * in both diffs need to be retested.
  *
- * 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.
+ * THIS ASSUMES BRANCH IS UP TO DATE WITH BASE WHEN IT MERGES, which we currently require. Only then is HEAD what lands on
+ * base, and base's commits validated. Otherwise what lands is HEAD combined with base's newer commits, which nobody
+ * tested, however the Actors are picked.
+ *
+ * In each example the branch's functional change to Actor A was validated at `since`, then one more push follows:
+ *
+ * Example scenarios:
+ * - Our own branch only: a commit changes A's README and B's code.
+ *   `since..HEAD`: A cosmetic, B functional. `base...HEAD`: A and B functional.
+ *   → A cosmetic, B functional: only B is tested, A's code is still the validated one.
+ * - Cosmetic merge: the branch merges base, which only changed READMEs and the CHANGELOG.
+ *   `since..HEAD`: every Actor cosmetic (CHANGELOG counts for all). `base...HEAD`: A functional, since the merged
+ *   files now match base and drop out of it.
+ *   → A cosmetic, the other Actors left out: nothing is tested.
+ * - Functional merge: the branch merges base, which changed code of A and of C.
+ *   `since..HEAD`: A and C functional. `base...HEAD`: A functional.
+ *   → A functional, C left out: A is tested, since base's change can interact with the branch's, while C only has
+ *   base's change, which base already validated.
  */
-const getOwnChangesIfMergedFromBase = async (
-    base: string,
-    actorConfigs: ActorConfig[],
-    testFilesGlob: string | undefined,
-): Promise<ChangedActors | undefined> => {
-    if (!(await hasMergeFromTarget(HEAD, base))) return undefined;
+const intersectChangedInBranchVsSince = (branch: ChangedActors, sinceValidated: ChangedActors): ChangedActors => {
+    const narrowed: ChangedActors = { functional: [], cosmetic: [] };
+    // All checks are done for each Actor separately, that's cleanest and most accurate
+    for (const actor of [...branch.functional, ...branch.cosmetic]) {
+        // base...HEAD
+        const changedFunctionallyOnBranch = branch.functional.includes(actor);
+        // since..HEAD
+        const changedFunctionallySince = sinceValidated.functional.includes(actor);
+
+        // changedSince is used for release. Release cares also about cosmetic.
+        const changedSince = changedFunctionallySince || sinceValidated.cosmetic.includes(actor);
+
+        // Nothing changed since the last validation, so the branch's change to this Actor is already validated
+        if (!changedSince) continue;
 
-    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;
+        // As we said, only intersection counts as functional, otherwise it's cosmetic
+        if (changedFunctionallyOnBranch && changedFunctionallySince) {
+            narrowed.functional.push(actor);
+        } else {
+            narrowed.cosmetic.push(actor);
+        }
+    }
+    return narrowed;
 };
 
 /**
- * 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).
+ * Finds the Actors whose context changed in the given range. `base` selects the branch's own changes
+ * (a PR), `since` the changes after a known commit (a release, or the last validated commit of a PR).
  */
 export const getAffectedActors = async ({
     base,
@@ -115,43 +155,44 @@ export const getAffectedActors = async ({
         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 });
+    const getChangedInRange = async (range: GitRange) => {
+        const changedFiles = await getChangedFilesBetween(range.fromRef, range.toRef);
+        return {
+            changedFiles,
+            changedActors: await getChangedActors({
+                filepathsChanged: changedFiles,
+                actorConfigs,
+                range,
+                testFilesGlob,
+            }),
+        };
+    };
 
-    // 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,
+    const headSha = await resolveCommitSha(HEAD);
+    const rangeVsBase: GitRange = {
+        // merge base = PR, release base = push to master (release)
+        fromRef: base ? await getMergeBase(base, HEAD) : await resolveReleaseBaseCommit(since!),
+        toRef: headSha,
     };
-};
 
-/** 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 }));
+    // Falls back to rangeVsBase.fromRef when there's no (usable) last validated commit — same as
+    // intersecting the branch's changes with themselves, which is a no-op (see this function's docs).
+    const validatedSha = base && since ? await findValidatedSha(since, headSha) : undefined;
+    const sinceFromRef = validatedSha ?? rangeVsBase.fromRef;
+
+    const { changedFiles, changedActors: changedVsBase } = await getChangedInRange(rangeVsBase);
+    const { changedActors: changedSinceActors } = await getChangedInRange({ fromRef: sinceFromRef, toRef: headSha });
+    // See this function's docs to understand the algorithm: only intersection counts as functional, otherwise it's cosmetic.
+    const changedActors = intersectChangedInBranchVsSince(changedVsBase, changedSinceActors);
+
     return {
         version: 1,
         head: headSha,
-        commits,
+        commits: await getCommitsBetween(rangeVsBase.fromRef, rangeVsBase.toRef),
         changedFiles,
-        changelog,
-        functionallyChangedActors: names(functionallyChangedActors),
-        cosmeticallyChangedActors: names(cosmeticallyChangedActors),
+        changelog: await getChangelogAdditions(rangeVsBase.fromRef, rangeVsBase.toRef, changedFiles),
+        functionallyChangedActors: names(changedActors.functional),
+        cosmeticallyChangedActors: names(changedActors.cosmetic),
     };
 };

package/bin/build.ts

@@ -14,8 +14,6 @@ type BuildPrActorOptions = {
 
 // Fixed version number used to build from local source files, since there is no real version to track.
 export const LOCAL_SOURCE_VERSION_NUMBER = '0.98';
-// Version that build-for-test builds, so tests never touch the version users run
-export const TEST_VERSION_NUMBER = '0.99';
 // Stands for each Actor's default version: the one its default build tag points to
 export const DEFAULT_VERSION_KEYWORD = 'default';