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

package/CHANGELOG.md

@@ -8,6 +8,7 @@ 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)
 
 ### 🐛 Bug Fixes
 

package/README.md

@@ -660,6 +660,61 @@ 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,
+    "ref": "my-branch",
+    "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` builds
+`functionallyChangedActors`, `release` builds both.
+
+`ref` is the checked-out branch, or `null` for a detached HEAD. `build` and `release` use the same detection internally.
+
 ### Releasing Actors (`release`)
 
 `release` builds the `latest` (default) version of every Actor changed since the last release and

package/bin/affected-actors.ts

@@ -0,0 +1,166 @@
+import { type ChangedActors, getChangedActors } from './diff-changes.js';
+import {
+    getBranchOnlyChangedFiles,
+    getChangedFilesBetween,
+    getChangelogAdditions,
+    getCommits,
+    getCommitsBetween,
+    hasMergeFromTarget,
+    resolveBranchName,
+    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';
+
+interface AffectedActorsOptions {
+    /** End of the range. */
+    head: string;
+    /** 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;
+    /** Branch head points to, which is what git builds are made from. Null for a SHA or a detached HEAD. */
+    ref: string | null;
+    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 (head: string, 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 (head: string, headSha: string, since: string): Promise<CommitRange> => {
+    const sinceSha = await resolveReleaseBaseCommit(since, head);
+    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 (
+    head: string,
+    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 ({
+    head,
+    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(head, base, since)
+        : await getRangeSince(head, 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(head, base, actorConfigs, testFilesGlob) : undefined;
+    const changedFiles = await getChangedFilesBetween(fromRef, toRef);
+    const changed = await getChangedActors({ filepathsChanged: changedFiles, actorConfigs, commits, testFilesGlob });
+
+    return {
+        headSha,
+        ref: await resolveBranchName(head),
+        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,
+    ref,
+    commits,
+    changedFiles,
+    changelog,
+    functionallyChangedActors,
+    cosmeticallyChangedActors,
+}: AffectedActors) => {
+    const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
+    return {
+        version: 1,
+        ref,
+        head: headSha,
+        commits,
+        changedFiles,
+        changelog,
+        functionallyChangedActors: names(functionallyChangedActors),
+        cosmeticallyChangedActors: names(cosmeticallyChangedActors),
+    };
+};

package/bin/diff-changes.ts

@@ -9,7 +9,6 @@ import { type RelativeDir, RelativeFile } from './utils/path/repo-relative.js';
 interface ShouldBuildAndTestOptions {
     filepathsChanged: string[];
     actorConfigs: ActorConfig[];
-    isLatest?: boolean;
     commits: Commit[];
     // Glob relative to the repo root. Matching files count as changes even when .dockerignore lists them.
     testFilesGlob?: string;
@@ -112,6 +111,7 @@ const isExcludedBySibling = (filePath: RelativeFile, actor: ActorConfig, allActo
 type ActorChangeEntry = {
     actorConfig: ActorConfig;
     files: string[];
+    hasFunctionalChange: boolean;
 };
 
 type ChangeGroup = { actors: string[]; files: string[] };
@@ -164,13 +164,20 @@ const logChangeGroups = (groups: ChangeGroup[]): void => {
     }
 };
 
+export interface ChangedActors {
+    /** Actors with at least one functional change. They need a new build and tests. */
+    functional: ActorConfig[];
+    /** Actors whose changes are all cosmetic. They only need a new build when released. */
+    cosmetic: ActorConfig[];
+}
+
+/** Finds the Actors the changed files belong to, split by the most impactful change each Actor has. */
 export const getChangedActors = async ({
     filepathsChanged,
     actorConfigs,
-    isLatest = false,
     commits,
     testFilesGlob,
-}: ShouldBuildAndTestOptions): Promise<ActorConfig[]> => {
+}: ShouldBuildAndTestOptions): Promise<ChangedActors> => {
     const actorsChangedMap = new Map<string, ActorChangeEntry>();
     const testFilesInContext = new Set<string>();
     const isTestFile = testFilesGlob ? picomatch(testFilesGlob, { nocase: true, dot: true }) : () => false;
@@ -191,21 +198,21 @@ export const getChangedActors = async ({
             }
 
             if (change.impact === 'ignored' || change.impact === 'outside-context') continue;
-            if (change.impact === 'cosmetic' && !isLatest) continue;
 
-            const entry = actorsChangedMap.get(actorConfig.folder.path) ?? { actorConfig, files: [] };
+            const entry = actorsChangedMap.get(actorConfig.folder.path) ?? {
+                actorConfig,
+                files: [],
+                hasFunctionalChange: false,
+            };
             entry.files.push(originalFilePath);
+            entry.hasFunctionalChange ||= change.impact === 'functional';
             actorsChangedMap.set(actorConfig.folder.path, entry);
         }
     }
 
-    const actorsChanged = Array.from(actorsChangedMap.values()).map((entry) => entry.actorConfig);
-
     // Log changes grouped by actor set, so changes shared across actors are logged once
     // instead of being repeated per actor.
-    const fileToActors = buildFileToActorsMap(actorsChangedMap);
-    const groups = groupFilesByActorSet(fileToActors);
-    logChangeGroups(groups);
+    logChangeGroups(groupFilesByActorSet(buildFileToActorsMap(actorsChangedMap)));
 
     for (const testFile of filepathsChanged.filter(
         (filePath) => isTestFile(filePath) && !testFilesInContext.has(filePath),
@@ -216,12 +223,13 @@ export const getChangedActors = async ({
         );
     }
 
-    if (actorsChanged.length > 0) {
-        const actors = actorsChanged.map((config) => config.actorFullName);
-        logger.info(`[DIFF]: Actors to be built and tested: ${actors.join(', ')}`);
-    } else {
-        logger.info(`[DIFF]: No relevant files changed, skipping builds and tests`);
-    }
+    const entries = Array.from(actorsChangedMap.values());
+    const functional = entries.filter((entry) => entry.hasFunctionalChange).map((entry) => entry.actorConfig);
+    const cosmetic = entries.filter((entry) => !entry.hasFunctionalChange).map((entry) => entry.actorConfig);
+
+    const names = (configs: ActorConfig[]) => configs.map((config) => config.actorFullName).join(', ') || 'none';
+    logger.info(`[DIFF]: Actors with functional changes: ${names(functional)}`);
+    logger.info(`[DIFF]: Actors with only cosmetic changes: ${names(cosmetic)}`);
 
-    return actorsChanged;
+    return { functional, cosmetic };
 };

package/bin/git.ts

@@ -6,7 +6,7 @@ export const GIT_FORMAT_SEPARATOR = '»¦«';
 const GIT_LOG_FORMAT = ['%H', '%aN<%aE>', '%aD', '%s'].join(GIT_FORMAT_SEPARATOR);
 
 /**
- * Gets the list of changed files between the given commits (inclusive).
+ * Gets the list of changed files between the given commits (inclusive), so it diffs from the parent of the oldest.
  */
 export const getChangedFiles = async (commits: Commit[]) => {
     // getCommits never returns an empty list (the rerun check returns all commits when the base commit
@@ -15,10 +15,19 @@ export const getChangedFiles = async (commits: Commit[]) => {
         throw new Error('Cannot get changed files: the commit list is empty. This should never happen.');
     }
 
-    const changedFilesString = await runGitCommand(
-        ['diff', '--name-only', `${commits[0].sha}~..${commits[commits.length - 1].sha}`],
-        { operation: 'get the list of changed files between commits' },
-    );
+    return getChangedFilesBetween(`${commits[0].sha}~`, commits[commits.length - 1].sha);
+};
+
+/**
+ * Files that differ between two commits, i.e. changed by the commits in the range (fromRef, toRef]. fromRef's own
+ * changes are not included: to include them, pass its parent, `${sha}~` (as getChangedFiles does).
+ * Diffing the endpoints, rather than walking a commit list, is what keeps merges right: the oldest commit of a
+ * merged branch can predate fromRef, and its changes are already in fromRef.
+ */
+export const getChangedFilesBetween = async (fromRef: string, toRef: string) => {
+    const changedFilesString = await runGitCommand(['diff', '--name-only', `${fromRef}..${toRef}`], {
+        operation: 'get the list of changed files between commits',
+    });
 
     const changedFiles = changedFilesString.split('\n').filter(Boolean);
     logger.info(`Changed files (up to 50): ${changedFiles.slice(0, 50).join(', ')}`);
@@ -103,11 +112,14 @@ export const parseBaseCommit = (shaOrCommit: string | undefined): string | undef
     return sha;
 };
 
-const fetchAllBranchCommits = async (sourceBranch: string, targetBranch: string): Promise<Commit[]> => {
-    const output = await runGitCommand(
-        ['log', `--pretty=format:${GIT_LOG_FORMAT}`, `${targetBranch}..${sourceBranch}`],
-        { operation: 'list commits reachable from the source ref but absent from the target ref' },
-    );
+/**
+ * Commits reachable from toRef but not from fromRef, oldest first: the range (fromRef, toRef], so fromRef itself is
+ * not included. To include it, pass its parent, `${sha}~`.
+ */
+export const getCommitsBetween = async (fromRef: string, toRef: string): Promise<Commit[]> => {
+    const output = await runGitCommand(['log', `--pretty=format:${GIT_LOG_FORMAT}`, `${fromRef}..${toRef}`], {
+        operation: 'list commits reachable from the source ref but absent from the target ref',
+    });
     const commitsStrings = output.split('\n');
     const commits = commitsStrings.map((commitString) => parseCommit(commitString));
     commits.reverse();
@@ -124,7 +136,7 @@ export const getCommits = async ({
     baseCommit,
 }: Pick<Config, 'sourceBranch' | 'targetBranch' | 'baseCommit'>): Promise<Commit[]> => {
     const baseCommitSha = parseBaseCommit(baseCommit);
-    const commits = await fetchAllBranchCommits(sourceBranch, targetBranch);
+    const commits = await getCommitsBetween(targetBranch, sourceBranch);
 
     // The last validated (base) commit being the branch HEAD means nothing new was pushed since the last
     // validation — the dev reran the workflow (or force-pushed to the same state) to trigger a clean test
@@ -184,6 +196,21 @@ export const getCurrentBranch = async (): Promise<string> => {
     return branch;
 };
 
+/** Resolves a ref (branch, remote branch, SHA, HEAD, ...) to the full SHA of the commit it points to. */
+export const resolveCommitSha = async (ref: string): Promise<string> =>
+    runGitCommand(['rev-parse', '--verify', `${ref}^{commit}`], { operation: `resolve ${ref} to a commit` });
+
+/**
+ * Branch name a ref points to, without the remote: `origin/foo` and `foo` both give `foo`, and `HEAD`
+ * gives the checked-out branch. Null when there is no branch to point at (a SHA, a tag, a detached HEAD).
+ */
+export const resolveBranchName = async (ref: string): Promise<string | null> => {
+    const fullName = await runGitCommand(['rev-parse', '--symbolic-full-name', ref], {
+        operation: `resolve the branch name of ${ref}`,
+    });
+    return fullName.match(/^refs\/(?:heads|remotes\/[^/]+)\/(.+)$/)?.[1] ?? null;
+};
+
 /**
  * Reads the repository URL from the `origin` remote, rewritten to the SSH form the Apify platform
  * uses for Git repo sources, e.g. git@github.com:apify-store/google-maps
@@ -236,15 +263,15 @@ const ZERO_SHA_REGEX = /^0{40}$/;
  * Unlike the PR path (getCommits), there is no lenient fallback. Falling back to "everything"
  * would rebuild the latest build of every Actor and post it to Slack, so every problem is an error.
  */
-export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<string> => {
+export const resolveReleaseBaseCommit = async (baseCommit: string, head = 'HEAD'): Promise<string> => {
     const sha = parseBaseCommit(baseCommit);
     if (!sha) {
-        throw new Error('--base-commit is required for release. See the README section "Releasing Actors".');
+        throw new Error('A base commit is required for release. See the README section "Releasing Actors".');
     }
     if (ZERO_SHA_REGEX.test(sha)) {
         throw new Error(
             `Base commit is ${sha}, which means the branch was just created and there is no previous release to diff against. ` +
-                `Rerun with --base-commit set to the last commit before the changes you want to release.`,
+                `Rerun with the base commit set to the last commit before the changes you want to release.`,
         );
     }
     // --quiet suppresses Git's error text for a missing commit, but Git still exits with code 1.
@@ -261,16 +288,16 @@ export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<stri
         );
     }
     // git merge-base A B outputs the common ancestor. If that equals A, then A is an ancestor of B.
-    const mergeBase = await runGitCommand(['merge-base', verifiedSha, 'HEAD'], {
-        operation: 'check whether the release base commit is an ancestor of HEAD',
+    const mergeBase = await runGitCommand(['merge-base', verifiedSha, head], {
+        operation: `check whether the release base commit is an ancestor of ${head}`,
     }).catch((error: unknown) => {
         if (error instanceof GitCommandError && error.exitCode === 1) return '';
         throw error;
     });
     if (mergeBase !== sha) {
         throw new Error(
-            `Base commit ${sha} is not an ancestor of HEAD, most likely because the branch was force-pushed. ` +
-                `The changed files cannot be determined reliably. Rerun with --base-commit set to an ancestor of HEAD ` +
+            `Base commit ${sha} is not an ancestor of ${head}, most likely because the branch was force-pushed. ` +
+                `The changed files cannot be determined reliably. Rerun with the base commit set to an ancestor of ${head} ` +
                 `from before the changes you want to release.`,
         );
     }
@@ -279,12 +306,16 @@ export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<stri
 
 const CHANGELOG_PATH = 'CHANGELOG.md';
 
-/** Returns the lines added to the root CHANGELOG.md between baseSha and HEAD, or null if it didn't change. */
-const getChangelogAdditions = async (baseSha: string, changedFiles: string[]): Promise<string | null> => {
+/** Returns the lines added to the root CHANGELOG.md between fromRef and toRef, or null if it didn't change. */
+export const getChangelogAdditions = async (
+    fromRef: string,
+    toRef: string,
+    changedFiles: string[],
+): Promise<string | null> => {
     if (!changedFiles.includes(CHANGELOG_PATH)) {
         return null;
     }
-    const diff = await runGitCommand(['diff', baseSha, 'HEAD', '--', CHANGELOG_PATH], {
+    const diff = await runGitCommand(['diff', fromRef, toRef, '--', CHANGELOG_PATH], {
         operation: 'read changelog changes since the last release',
     });
 
@@ -307,23 +338,3 @@ const getChangelogAdditions = async (baseSha: string, changedFiles: string[]): P
     }
     return added.join('\n').trim();
 };
-
-/**
- * Everything that changed since the last release (baseSha, exclusive) up to HEAD, or null when there
- * are no new commits. Changed files come from diffing the range directly instead of from the commit
- * list: with a merge commit, the oldest commit of the merged branch can be older than baseSha, and
- * diffing from its parent would pull in already-released changes.
- */
-export const getReleaseChanges = async (baseSha: string) => {
-    if (
-        (await runGitCommand(['rev-parse', 'HEAD'], { operation: 'identify the current release commit' })) === baseSha
-    ) {
-        return null;
-    }
-    const commits = await fetchAllBranchCommits('HEAD', baseSha);
-    const changedFiles = await runGitCommand(['diff', '--name-only', baseSha, 'HEAD'], {
-        operation: 'list files changed since the last release',
-    }).then((output) => output.split('\n').filter(Boolean));
-    const changelog = await getChangelogAdditions(baseSha, changedFiles);
-    return { commits, changedFiles, changelog };
-};

package/bin/main.ts

@@ -6,25 +6,14 @@ import yargs, { type Options } from 'yargs';
 // eslint-disable-next-line import/extensions --- With .js, it cannot find types
 import { hideBin } from 'yargs/helpers';
 
+import { getAffectedActors, toAffectedActorsDocument } from './affected-actors.js';
 import { deleteOldBuilds, runBuilds } from './build.js';
 import { runBuildsFromLocal } from './build-from-local.js';
-import { getChangedActors } from './diff-changes.js';
-import {
-    getBranchOnlyChangedFiles,
-    getChangedFiles,
-    getCommits,
-    getCurrentBranch,
-    getReleaseChanges,
-    getRepoName,
-    hasMergeFromTarget,
-    resolveReleaseBaseCommit,
-    resolveRepoUrl,
-} from './git.js';
+import { getChangedFiles, getCommits, getCurrentBranch, getRepoName, resolveRepoUrl } from './git.js';
 import { logger, logLevels } from './logger.js';
 import { writeJson } from './output.js';
 import { notifyToSlack } from './slack.js';
 import { reportTestResults } from './test-report.js';
-import type { Config } from './types.js';
 import { readConfigFile } from './utils/config/load-config.js';
 
 /**
@@ -64,6 +53,23 @@ const actorSelectionOptions = {
     ignore: { type: 'string', array: true, default: [] as string[] },
 } as const satisfies Record<string, Options>;
 
+/**
+ * Commit range for get-affected-actors, which always ends at the checked-out HEAD. `base` and `since` combine:
+ * `base` alone is a branch's own commits (a PR), `since` alone is everything after a commit (a release), both is
+ * a branch after its last validated commit.
+ */
+const affectedRangeOptions = {
+    base: { type: 'string', describe: 'Only count commits on HEAD that are not on this branch' },
+    since: {
+        type: 'string',
+        describe: 'Only count commits after this one. Ignored with --base if it is not on the branch',
+    },
+    'test-files-glob': {
+        type: 'string',
+        describe: 'Glob (from the repo root) of test files that count as changes even when .dockerignore lists them',
+    },
+} as const satisfies Record<string, Options>;
+
 /**
  * For commands that change something (builds, deletes, Slack posts). A dry run still does every read and check
  * the real run does, credentials included, and only skips the writes. So it needs the same tokens, though
@@ -92,48 +98,6 @@ const globalOptions = {
     },
 } as const satisfies Record<string, Options>;
 
-const resolveChangedActors = async (config: Config, { isLatest }: { isLatest: boolean }) => {
-    const actorConfigs = await readConfigFile(config);
-
-    // This is an optimization for the common case where a branch only has cosmetic changes but had to smerge in
-    // functional changes from master (being up-to-date is a CI requirement). Master 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.
-    if (await hasMergeFromTarget(config.sourceBranch, config.targetBranch)) {
-        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 branchOnlyFiles = await getBranchOnlyChangedFiles(config.sourceBranch, config.targetBranch);
-        // Omit baseCommit to get full branch history. Validated functional commits can still interact with merged ones
-        const allBranchCommits = await getCommits({ ...config, baseCommit: undefined });
-        const branchOnlyActorsChanged = await getChangedActors({
-            filepathsChanged: branchOnlyFiles,
-            actorConfigs,
-            commits: allBranchCommits,
-            testFilesGlob: config.testFilesGlob,
-        });
-        if (branchOnlyActorsChanged.length === 0) {
-            logger.info('[MERGE-FROM-TARGET-OPTIMIZATION]: Branch itself has no functional changes, skipping tests');
-            return [];
-        }
-        logger.info(
-            `[MERGE-FROM-TARGET-OPTIMIZATION]: Branch has ${branchOnlyActorsChanged.length} functional changes, cannot optimize, we continue with full check`,
-        );
-    }
-
-    // If the optimization doesn't apply, we check all branch commits including merges for full coverage. We don't reuse the merge optimization results because here we can apply baseCommit and check merge commits (they might be functional or just cosmetic)
-    const commits = await getCommits(config);
-    const changedFiles = await getChangedFiles(commits);
-    return getChangedActors({
-        filepathsChanged: changedFiles,
-        actorConfigs,
-        isLatest,
-        commits,
-        testFilesGlob: config.testFilesGlob,
-    });
-};
-
 await yargs()
     .scriptName('public-actors-utils')
     .options(globalOptions)
@@ -179,11 +143,10 @@ await yargs()
     )
     .command(
         'get-affected-actors',
-        '',
-        (y) => y.options(gitRangeOptions).options(actorSelectionOptions),
-        async (config) => {
-            const actorsChanged = await resolveChangedActors(config, { isLatest: false });
-            writeJson(actorsChanged);
+        'Find the Actors whose context changed in a commit range ending at the checked-out HEAD',
+        (y) => y.options(affectedRangeOptions).options(actorSelectionOptions),
+        async (args) => {
+            writeJson(toAffectedActorsDocument(await getAffectedActors({ ...args, head: 'HEAD' })));
         },
     )
     .command(
@@ -212,7 +175,15 @@ await yargs()
                 .options(dryRunOptions)
                 .option('test-files-glob', { type: 'string' }),
         async (config) => {
-            const actorsChanged = await resolveChangedActors(config, { isLatest: false });
+            // Cosmetic-only changes don't need testing, so they don't need a build either
+            const { functionallyChangedActors: actorsChanged } = await getAffectedActors({
+                head: config.sourceBranch,
+                base: config.targetBranch,
+                since: config.baseCommit,
+                testFilesGlob: config.testFilesGlob,
+                actors: config.actors,
+                ignore: config.ignore,
+            });
             const builds = await runBuilds({
                 ...(await resolveRepoUrl(config.repoUrl)),
                 actorConfigs: actorsChanged,
@@ -238,24 +209,23 @@ await yargs()
                 .option('report-slack-channel', { type: 'string' })
                 .option('release-slack-channel', { type: 'string' }),
         async (args) => {
-            const baseSha = await resolveReleaseBaseCommit(args.baseCommit);
             const branch = await getCurrentBranch();
-            const changes = await getReleaseChanges(baseSha);
-            if (!changes) {
-                logger.info(`HEAD is the base commit ${baseSha}, there is nothing new to release`);
+            const { commits, changedFiles, changelog, functionallyChangedActors, cosmeticallyChangedActors } =
+                await getAffectedActors({
+                    head: 'HEAD',
+                    since: args.baseCommit,
+                    actors: args.actors,
+                    ignore: args.ignore,
+                });
+            // A release ships cosmetic changes (README, input schema descriptions, ...) too
+            const actorsChanged = [...functionallyChangedActors, ...cosmeticallyChangedActors];
+            if (commits.length === 0) {
+                logger.info(`HEAD is the base commit ${args.baseCommit}, there is nothing new to release`);
                 return;
             }
-            const { commits, changedFiles, changelog } = changes;
             const { repoUrl, shouldVerifyRepoUrl } = await resolveRepoUrl(args.repoUrl);
 
             const isLatest = true;
-            const actorConfigs = await readConfigFile(args);
-            const actorsChanged = await getChangedActors({
-                filepathsChanged: changedFiles,
-                actorConfigs,
-                isLatest,
-                commits,
-            });
             const { dryRun, reportSlackChannel, releaseSlackChannel } = args;
             const builds = await runBuilds({
                 isLatest,