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

package/README.md

@@ -308,48 +308,35 @@ Slack credentials in scope, so a postinstall script in the dependency tree canno
 
 ## Versioning and releases
 
-The workflows and the npm package live in one repo but ship on their own schedules. Two pointers
-decide what a consumer repo actually runs:
-
-| Pointer                             | What it selects                                | Moves when                                               |
-| ----------------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
-| the `@workflows-v0` tag in `uses:`  | which workflows run                            | a master push, once the version below is published       |
-| `.github/workflows-package-version` | which `apify-test-tools` the workflows install | a stable release writes it; you may set it ahead of time |
-
-The setup action installs that **exact** version — not a range. A tag is therefore a complete
-statement: these workflows _and_ this library. The stable release writes the file into the same
-commit that bumps `package.json` and `CHANGELOG.md`, so a released commit always names the version
-it published, and rollout latency is unchanged: the release publishes and moves the tag in one run.
-
-Prereleases are excluded. Master pushes publish a `-beta` that consumer repos must never install, so
-the pin only moves on a stable release; betas stay reachable through the lockfile path in the setup
-action, which is how branch testing works.
-
-Nothing is coupled that doesn't need to be:
-
-- **Workflow-only change** — merge it. `workflows-v0` moves, it goes live, no release needed.
-- **Package-only change** — merge it, then cut a release when you want it out. The workflows are
-  unchanged, so consumers see nothing until the release lands.
-- **A workflow that calls a new CLI feature** — the one case that can break consumers, and the only
-  one with any ceremony. Put the package change, the workflow change, and the new pin in one PR. On
-  merge the tag is **held**: the CI job reports that the pinned version isn't on npm and leaves `workflows-v0`
-  where it is, so consumers keep running the previous workflows. Cut a stable release, and the tag
-  moves on its own. Run **Move major version tag** if you don't want to wait for the next master
-  push.
+The workflows and the npm package live in one repo but ship on their own schedules:
+
+| What                                         | Consumers get it through                   | Ships when              |
+| -------------------------------------------- | ------------------------------------------ | ----------------------- |
+| the workflows and the CLI they call          | the `@workflows-v0` tag in `uses:`         | every master push       |
+| the lib (`testActor`, `describe`, matchers…) | `apify-test-tools` in their `package.json` | a stable release on npm |
+
+The CLI is bundled with its dependencies into `.github/cli/apify-test-tools.mjs` (`npm run bundle`,
+run by the pre-commit hook and checked in CI), and the setup action runs it from there. Nothing is
+installed for it, so a tag is a complete statement: these workflows and this CLI, with the exact
+dependency versions from `package-lock.json` at that commit. The consumer's own `node_modules` is
+left alone, so their tests keep the lib version they locked.
+
+- **Workflow or CLI change** — merge it. `workflows-v0` moves once checks and tests pass, and it goes
+  live. No release needed, even when a workflow starts using a new CLI feature: both are in the
+  same commit.
+- **Lib change** — merge it, then cut a release when you want it out. Consumers pick it up when
+  they update `apify-test-tools`.
+
+The CLI and the lib in one job can be different versions now, so the formats between them are a
+contract: the `ACTOR_BUILDS` JSON that `build` writes and the lib reads, and the vitest JSON report
+`report-tests` reads. Add fields freely; renaming or removing one needs a new major tag.
 
 `workflows-v0` moving on every master push means `@workflows-v0` is as live as `@master` was —
-there's no staging step, just a gate on the package version. What the tag buys you is a
-`workflows-v1` for breaking workflow changes, so repos migrate one at a time instead of all at once,
-and a way to roll back by pointing the tag at an earlier commit. Bump `MAJOR_TAG` in
+there's no staging step. What the tag buys you is a `workflows-v1` for breaking workflow changes,
+so repos migrate one at a time instead of all at once, and a way to roll back by pointing the tag at
+an earlier commit (**Move major version tag** workflow). Bump `MAJOR_TAG` in
 `.github/workflows/_move_major_tag.yaml` to cut the next major; the old tag then freezes where it is
-and keeps working.
-
-Freezing is real, which is the whole reason the version is pinned rather than a floor. A frozen `workflows-v0`
-points at a commit whose pinned version never changes, so it keeps installing the library it was
-tested against no matter how far the package moves on. Had the workflows installed `>=<floor>`, a
-frozen `workflows-v0` would still resolve to whatever is newest — and since the release that enables
-`workflows-v1` is usually the same release that breaks `workflows-v0`, the migration window would
-have been zero.
+and keeps working, CLI included, since the bundle is part of the frozen commit.
 
 The tag tracks the **workflows'** contract, not the npm package version. They move independently on
 purpose, so `@workflows-v0` is expected to stay `@workflows-v0` after the package reaches 1.0 —
@@ -360,9 +347,8 @@ and those refs disagree, which is the mistake that would otherwise ship silently
 ### Testing workflow changes
 
 - Point [testing-repo-for-github-actions](https://github.com/apify-store/testing-repo-for-github-actions)
-  at your branch (`uses: ...@your-branch`). It has real attached Actors and tests. Because the
-  package lives here too, a master push publishes a `beta`, and the lockfile-beta path in the setup
-  action installs that exact version — so one branch tests both halves of a change together.
+  at your branch (`uses: ...@your-branch`). It has real attached Actors and tests. The branch carries
+  its own CLI bundle, so one branch tests the workflows and the CLI together.
 - To change the composite action itself, repoint the `uses:` refs inside the reusable workflows at
   your branch as well, and change them back before merging.
 - Make sure the shell code actually works on your laptop first.
@@ -580,6 +566,15 @@ describe('standby tests', () => {
 
 The package includes a CLI binary used by CI workflows to build Actors, detect changes, and report test results. You can also run it locally.
 
+### 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:
+
+- **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.
+
 ### Running locally
 
 Running the testing library locally is useful when you only want to update the testing code in /test because you can iterate on it without pushing new code to the remote.
@@ -610,7 +605,7 @@ APIFY_TOKEN_JOHN_DOE=<token> \
     --dry-run
 ```
 
-Remove `--dry-run` to actually trigger builds and update the branch names/ The command outputs a JSON array of build objects to stdout:
+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:
 
 ```json
 [{ "buildId": "...", "actorRawId": "...", "buildNumber": "...", "actorFullName": "john.doe/my-actor" }]
@@ -625,7 +620,7 @@ APIFY_TOKEN_JOHN_DOE=<token> \
   npx apify-test-tools build-from-local --actors john.doe/my-actor
 ```
 
-Pass a hardcoded actor name via `--actors` to build only that Actor (comma-separate multiple names). Omit `--actors` to build all Actors in the repo, or add `--dry-run` to preview without building. It outputs the same JSON build array as `build`, so you run tests against it the same way as in step 5 below:
+Pass a hardcoded actor name via `--actors` to build only that Actor (comma-separate multiple names). Omit `--actors` to build all Actors in the repo, or add `--dry-run` to check the token, the Actor and the zipped sources without uploading or building. It outputs the same JSON build array as `build`, so you run tests against it the same way as in step 5 below:
 
 ```bash
 # Build from local source and capture output
@@ -665,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/build-from-local.ts

@@ -6,11 +6,11 @@ import AdmZip from 'adm-zip';
 import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType } from 'apify-client';
 
-import { dryRunBuildData, LOCAL_SOURCE_VERSION_NUMBER, runAndSummarizeBuilds } from './build.js';
+import { ApifyBuilder, LOCAL_SOURCE_VERSION_NUMBER, runAndSummarizeBuilds } from './build.js';
 import { loadDockerIgnore } from './dockerignore.js';
 import { logger } from './logger.js';
 import { isPathWithinScope } from './path-utils.js';
-import type { ActorConfig, BuildData } from './types.js';
+import type { ActorConfig, BuildData, DryRunPlan } from './types.js';
 import type { SourceFile } from './utils.js';
 import { getGitignoredPaths, isOutsideDir, listRepoFilePaths, readSourceFile } from './utils.js';
 import type { RelativeDir } from './utils/path/repo-relative.js';
@@ -179,32 +179,66 @@ export const rewriteActorJsonPaths = async (
     await fs.writeFile(path.join(newActorDir, 'actor.json'), JSON.stringify(rewritten, null, 4));
 };
 
+type LocalBuildPlan = {
+    actorFullName: string;
+    versionNumber: string;
+    folder: string;
+    fileCount: number;
+    zipSizeBytes: number;
+};
+
 export const runBuildsFromLocal = async ({
     actorConfigs,
     dryRun,
 }: {
     actorConfigs: ActorConfig[];
     dryRun: boolean;
-}): Promise<BuildData[]> => {
+}): Promise<BuildData[] | DryRunPlan<LocalBuildPlan>> => {
+    // Read-only preparation shared with the real build, so a dry run fails on a missing token, an unknown
+    // Actor or unreadable sources just like the build would
+    const preparedBuilds = await Promise.all(
+        actorConfigs.map(async (actorConfig) => {
+            const actorInfo = await ApifyBuilder.fromActorConfig(actorConfig).getActorInfo();
+            // Zipped and uploaded like `apify push` does, since inline SOURCE_FILES are capped at ~9 MB.
+            const zip = new AdmZip();
+            const sourceFiles = await collectSourceFiles(actorConfig);
+            for (const { name, content } of sourceFiles) {
+                zip.addFile(name, content);
+            }
+            return { actorConfig, actorInfo, fileCount: sourceFiles.length, zipBuffer: zip.toBuffer() };
+        }),
+    );
+
     if (dryRun) {
         logger.info('[DRY RUN] Would build from local source:');
-        for (const { actorFullName, folder } of actorConfigs) {
-            logger.info(`  ${actorFullName} (${folder})`);
+        for (const { actorConfig, fileCount, zipBuffer } of preparedBuilds) {
+            logger.info(
+                `  ${actorConfig.actorFullName} (${actorConfig.folder}): ${fileCount} files, ${zipBuffer.length} bytes zipped`,
+            );
         }
-        return actorConfigs.map(({ actorFullName }) => dryRunBuildData(actorFullName, LOCAL_SOURCE_VERSION_NUMBER));
+        return {
+            dryRun: true,
+            builds: preparedBuilds.map(({ actorConfig, fileCount, zipBuffer }) => ({
+                actorFullName: actorConfig.actorFullName,
+                versionNumber: LOCAL_SOURCE_VERSION_NUMBER,
+                folder: actorConfig.folder.path,
+                fileCount,
+                zipSizeBytes: zipBuffer.length,
+            })),
+        };
     }
 
+    const preparedByActorFullName = new Map(
+        preparedBuilds.map((prepared) => [prepared.actorConfig.actorFullName, prepared]),
+    );
+
     return runAndSummarizeBuilds(actorConfigs, 'LOCAL BUILDS', async (actorConfig, builder) => {
-        // Zipped and uploaded like `apify push` does, since inline SOURCE_FILES are capped at ~9 MB.
-        const zip = new AdmZip();
-        for (const { name, content } of await collectSourceFiles(actorConfig)) {
-            zip.addFile(name, content);
-        }
+        const { actorInfo, zipBuffer } = preparedByActorFullName.get(actorConfig.actorFullName)!;
         const actorVersion: ApifyClientTypes.ActorVersion = {
             versionNumber: LOCAL_SOURCE_VERSION_NUMBER,
-            tarballUrl: await builder.uploadSourceZip(LOCAL_SOURCE_VERSION_NUMBER, zip.toBuffer()),
+            tarballUrl: await builder.uploadSourceZip(LOCAL_SOURCE_VERSION_NUMBER, zipBuffer),
             sourceType: ActorSourceType.Tarball,
         };
-        return builder.createVersionAndBuild(LOCAL_SOURCE_VERSION_NUMBER, actorVersion, false);
+        return builder.createVersionAndBuild(LOCAL_SOURCE_VERSION_NUMBER, actorVersion, false, actorInfo);
     });
 };

package/bin/build.ts

@@ -3,7 +3,7 @@ import { ActorSourceType, ApifyClient } from 'apify-client';
 
 import { normalizeRepoUrl } from './git.js';
 import { logger } from './logger.js';
-import type { ActorConfig, BuildData } from './types.js';
+import type { ActorConfig, BuildData, DryRunPlan } from './types.js';
 
 type BuildPrActorOptions = {
     buildTag?: string;
@@ -179,7 +179,7 @@ export class ApifyBuilder {
      * Deletes build of all versions. Apify API doesn't allow to delete default build and we explicitly skip it
      * We delete devel builds faster because we used the for every PR until recently so just to get rid of them faster
      */
-    async deleteOldBuilds(): Promise<void> {
+    async deleteOldBuilds({ dryRun }: { dryRun: boolean }): Promise<void> {
         // Even though we don't version our current Actors, if we ever such Actors to GitHub CI, we would accidentally delete old supported versions
         // This hardcoded solution is not ideal, but it should prevent most imaginable cases
         // All currently popular versioned Actors use `version-${number}` format
@@ -258,9 +258,15 @@ export class ApifyBuilder {
         });
 
         logger.info(
-            `[DELETE OLD BUILDS][${this.actorFullName}]: Deleting ${buildsToDelete.length} old builds that are non-default and ` +
-                `older than 30 days from total ${items.length}`,
+            `[DELETE OLD BUILDS][${this.actorFullName}]: ${dryRun ? '[DRY RUN] Would delete' : 'Deleting'} ${buildsToDelete.length} ` +
+                `old builds that are non-default and older than 30 days from total ${items.length}`,
         );
+        if (dryRun) {
+            for (const build of buildsToDelete) {
+                logger.info(`  ${build.buildNumber} (${build.id}, started ${build.startedAt.toISOString()})`);
+            }
+            return;
+        }
         for (const build of buildsToDelete) {
             await this.apifyClient.build(build.id).delete();
         }
@@ -310,13 +316,13 @@ export const runAndSummarizeBuilds = async (
     return waitAndSummarizeBuilds(startedBuilds, buildersByActorFullName, label);
 };
 
-// Placeholder BuildData for dry runs, since no real build was triggered.
-export const dryRunBuildData = (actorFullName: string, versionNumber: string): BuildData => ({
-    buildId: 'dry-run',
-    actorRawId: 'dry-run',
-    buildNumber: versionNumber,
-    actorFullName,
-});
+type GitBuildPlan = {
+    actorFullName: string;
+    versionNumber: string;
+    buildTag?: string;
+    gitRepoUrl: string;
+    useDockerCache: boolean;
+};
 
 type RunBuildsOptions = {
     actorConfigs: ActorConfig[];
@@ -337,7 +343,7 @@ export const runBuilds = async ({
     isLatest = false,
     dryRun,
     useDockerCache,
-}: RunBuildsOptions): Promise<BuildData[]> => {
+}: RunBuildsOptions): Promise<BuildData[] | DryRunPlan<GitBuildPlan>> => {
     // Fetched once per Actor and reused for the checks, the version numbers and the build itself
     const buildConfigs: BuildPrActorOptions[] = await Promise.all(
         actorConfigs.map(async (actorConfig) => {
@@ -366,14 +372,24 @@ export const runBuilds = async ({
         }),
     );
 
+    // Everything above only reads, so a dry run has checked what the real run would, short of writing
     if (dryRun) {
         logger.info('[DRY RUN] Would build:');
-        for (const { actorConfig, versionNumber } of buildConfigs) {
-            logger.info(`  ${actorConfig.actorFullName} (${versionNumber})`);
+        for (const { actorConfig, versionNumber, gitRepoUrl } of buildConfigs) {
+            logger.info(`  ${actorConfig.actorFullName} (${versionNumber}) from ${gitRepoUrl}`);
         }
-        return buildConfigs.map(({ actorConfig, versionNumber }) =>
-            dryRunBuildData(actorConfig.actorFullName, versionNumber),
-        );
+        return {
+            dryRun: true,
+            builds: buildConfigs.map(
+                ({ actorConfig, versionNumber, buildTag, gitRepoUrl, useDockerCache: useCache }) => ({
+                    actorFullName: actorConfig.actorFullName,
+                    versionNumber,
+                    buildTag,
+                    gitRepoUrl,
+                    useDockerCache: useCache,
+                }),
+            ),
+        };
     }
 
     const buildConfigsByActorFullName = new Map(
@@ -398,8 +414,8 @@ export const runBuilds = async ({
     });
 };
 
-export const deleteOldBuilds = async (actorConfigs: ActorConfig[]) => {
+export const deleteOldBuilds = async (actorConfigs: ActorConfig[], { dryRun }: { dryRun: boolean }) => {
     for (const actorConfig of actorConfigs) {
-        await ApifyBuilder.fromActorConfig(actorConfig).deleteOldBuilds();
+        await ApifyBuilder.fromActorConfig(actorConfig).deleteOldBuilds({ dryRun });
     }
 };

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 };
 };