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

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,36 @@ 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
+ * read-only ones are enough. Read-only commands don't take it since they have nothing to skip.
+ */
+const dryRunOptions = {
+    'dry-run': {
+        type: 'boolean',
+        default: false,
+        describe: 'Do every read and check (tokens included) but change nothing; print what would be done',
+    },
+} as const satisfies Record<string, Options>;
+
 /** Flags for commands that trigger Apify builds. */
 const buildOptions = {
     'use-docker-cache': { type: 'boolean', default: false },
@@ -77,51 +96,8 @@ const globalOptions = {
         default: 'info',
         describe: 'Minimum diagnostic level written to stderr; silent disables logging',
     },
-    'dry-run': { type: 'boolean', default: false },
 } 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)
@@ -167,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(
@@ -179,6 +154,7 @@ await yargs()
         '',
         (y) =>
             y
+                .options(dryRunOptions)
                 .option('report-file', { type: 'string', demandOption: true })
                 .option('report-slack-channel', { type: 'string' })
                 .option('job-url', { type: 'string' })
@@ -196,9 +172,18 @@ await yargs()
                 .options(actorSelectionOptions)
                 .options(buildOptions)
                 .options(repoUrlOptions)
+                .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,
@@ -217,30 +202,30 @@ await yargs()
                 .options(actorSelectionOptions)
                 .options(buildOptions)
                 .options(repoUrlOptions)
+                .options(dryRunOptions)
                 // The last commit that is already released, everything after it up to HEAD gets released.
                 // Required, see the README section "Releasing Actors" for how to set it for each merge strategy.
                 .option('base-commit', { type: 'string', demandOption: true })
                 .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,
@@ -269,7 +254,7 @@ await yargs()
     .command(
         'build-from-local',
         '',
-        (y) => y.options(actorSelectionOptions),
+        (y) => y.options(actorSelectionOptions).options(dryRunOptions),
         async ({ actors, ignore, dryRun }) => {
             const actorConfigs = await readConfigFile({ actors, ignore });
             const builds = await runBuildsFromLocal({ actorConfigs, dryRun });
@@ -279,10 +264,10 @@ await yargs()
     .command(
         'delete-old-builds',
         '',
-        (y) => y.options(actorSelectionOptions),
-        async ({ actors, ignore }) => {
+        (y) => y.options(actorSelectionOptions).options(dryRunOptions),
+        async ({ actors, ignore, dryRun }) => {
             const actorConfigs = await readConfigFile({ actors, ignore });
-            await deleteOldBuilds(actorConfigs);
+            await deleteOldBuilds(actorConfigs, { dryRun });
         },
     )
     .strictCommands()

package/bin/slack.ts

@@ -15,6 +15,25 @@ type NotifyToSlackOptions = {
     reportSlackChannel?: string;
 };
 
+/**
+ * Creates the client the real run posts with. A dry run posts nothing but still requires the token and checks
+ * Slack accepts it (`auth.test` is read-only), so it fails wherever the real run would.
+ */
+export const getSlackClient = async (tokenEnvVar: string, dryRun: boolean): Promise<WebClient> => {
+    const slack = new WebClient(getEnvVar(tokenEnvVar));
+    if (dryRun) {
+        try {
+            await slack.auth.test();
+        } catch (err) {
+            throw new Error(`${tokenEnvVar} was rejected by Slack: ${(err as Error).message}`);
+        }
+        logger.info(`[DRY RUN] ${tokenEnvVar} is valid`);
+    }
+    return slack;
+};
+
+export const sendingLabel = (dryRun: boolean) => (dryRun ? '[DRY RUN] Would send' : 'Sending');
+
 // Git authors come as "Name<email>", Slack only needs the name
 const displayName = (author: string) => author.replace(/\s*<[^>]*>$/, '');
 
@@ -28,19 +47,23 @@ export const notifyToSlack = async ({
     releaseSlackChannel,
     reportSlackChannel,
 }: NotifyToSlackOptions) => {
-    const slack = new WebClient(getEnvVar('SLACK_TOKEN_RELEASES_BOT'));
-
     if (!changelog) {
         logger.warn('No new changelog entries found, did you forget to update it?');
     }
 
+    if (!releaseSlackChannel && !reportSlackChannel) {
+        logger.info('Skipping slack notification, no --release-slack-channel or --report-slack-channel passed');
+        return;
+    }
+    const slack = await getSlackClient('SLACK_TOKEN_RELEASES_BOT', dryRun);
+
     let shortMessage = `*${repository}* – New release (by ${displayName(author)}):\n\n`;
 
     // This one is just for broader public that only cares about public facing changes
     if (changelog && releaseSlackChannel) {
         shortMessage += `*Additions to the changelog*:\n\n${changelog}\n`;
         logger.info(`=========================================`);
-        logger.info(`**Sending slack message to channel**: ${releaseSlackChannel}.\n\n${shortMessage}`);
+        logger.info(`**${sendingLabel(dryRun)} slack message to channel**: ${releaseSlackChannel}.\n\n${shortMessage}`);
         logger.info(`=========================================`);
         if (!dryRun) {
             await slack.chat.postMessage({
@@ -62,7 +85,7 @@ export const notifyToSlack = async ({
     // This one is for devs and project managers that need to know more details
     if (reportSlackChannel) {
         logger.info(`=========================================`);
-        logger.info(`Sending slack message to channel: ${reportSlackChannel}.\n\n${longMessage}`);
+        logger.info(`${sendingLabel(dryRun)} slack message to channel: ${reportSlackChannel}.\n\n${longMessage}`);
         logger.info(`=========================================`);
         if (!dryRun) {
             await slack.chat.postMessage({
@@ -73,8 +96,7 @@ export const notifyToSlack = async ({
     }
 };
 
-export const sendSlackMessage = async (channel: string, text: string, blocks: string[], token: string) => {
-    const slack = new WebClient(token);
+export const sendSlackMessage = async (slack: WebClient, channel: string, text: string, blocks: string[]) => {
     const { ts } = await slack.chat.postMessage({ text, channel });
     if (blocks.length > 0 && ts) {
         await slack.chat.postMessage({

package/bin/test-report.ts

@@ -1,8 +1,7 @@
 import fs from 'node:fs/promises';
 
 import { logger } from './logger.js';
-import { sendSlackMessage } from './slack.js';
-import { getEnvVar } from './utils.js';
+import { getSlackClient, sendingLabel, sendSlackMessage } from './slack.js';
 
 interface ReportTestResultsOptions {
     reportFile: string;
@@ -80,6 +79,9 @@ export const reportTestResults = async ({
         );
         return;
     }
+    // Checked before knowing if there's anything to send, so a broken token shows up on a green run
+    // (and in dry runs) rather than on the day tests fail
+    const slack = await getSlackClient('SLACK_TOKEN_TESTS_BOT', dryRun);
 
     if (failedAssertions.length === 0) {
         return;
@@ -95,16 +97,11 @@ export const reportTestResults = async ({
         .slice(1)
         .map(({ message, runLink, actorId }) => `• ${message} --- <${runLink}|${actorId}>`);
 
-    logger.info('SLACK:', slackMessage);
+    logger.info(`${sendingLabel(dryRun)} slack message to channel ${reportSlackChannel}:`, slackMessage);
     logger.info('\tblocks:', blocks.join('\n\t\t'));
 
-    if (!reportSlackChannel) {
-        return;
-    }
-
     if (!dryRun) {
-        const slackToken = getEnvVar('SLACK_TOKEN_TESTS_BOT');
-        await sendSlackMessage(reportSlackChannel, slackMessage, blocks, slackToken);
+        await sendSlackMessage(slack, reportSlackChannel, slackMessage, blocks);
     }
 };
 

package/bin/types.ts

@@ -24,6 +24,15 @@ export interface BuildData {
     buildNumber: string;
 }
 
+/**
+ * What a dry run writes to stdout instead of the command's real result. It's an object, not an array, so
+ * it can't be mistaken for real builds: `ACTOR_BUILDS` rejects it before any test runs.
+ */
+export interface DryRunPlan<T> {
+    dryRun: true;
+    builds: T[];
+}
+
 export interface ActorConfig {
     actorFullName: string;
     folder: ExistingDir;

package/dist/bin/affected-actors.d.ts

@@ -0,0 +1,50 @@
+import type { ActorConfig, Commit } from './types.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[];
+}
+/**
+ * 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 declare const getAffectedActors: ({ head, base, since: sinceOption, testFilesGlob, actors, ignore, }: AffectedActorsOptions) => Promise<AffectedActors>;
+/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
+export declare const toAffectedActorsDocument: ({ headSha, ref, commits, changedFiles, changelog, functionallyChangedActors, cosmeticallyChangedActors, }: AffectedActors) => {
+    version: number;
+    ref: string | null;
+    head: string;
+    commits: Commit[];
+    changedFiles: string[];
+    changelog: string | null;
+    functionallyChangedActors: {
+        actorFullName: string;
+    }[];
+    cosmeticallyChangedActors: {
+        actorFullName: string;
+    }[];
+};
+export {};
+//# sourceMappingURL=affected-actors.d.ts.map

package/dist/bin/affected-actors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"affected-actors.d.ts","sourceRoot":"","sources":["../../bin/affected-actors.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGtD,UAAU,qBAAqB;IAC3B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,UAAU,cAAc;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mFAAmF;IACnF,yBAAyB,EAAE,WAAW,EAAE,CAAC;IACzC,uHAAuH;IACvH,yBAAyB,EAAE,WAAW,EAAE,CAAC;CAC5C;AA4DD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAU,oEAOrC,qBAAqB,KAAG,OAAO,CAAC,cAAc,CA4BhD,CAAC;AAEF,gHAAgH;AAChH,eAAO,MAAM,wBAAwB,GAAI,2GAQtC,cAAc;;;;;;;;;;;;;CAYhB,CAAC"}

package/dist/bin/affected-actors.js

@@ -0,0 +1,89 @@
+import { getChangedActors } from './diff-changes.js';
+import { getBranchOnlyChangedFiles, getChangedFilesBetween, getChangelogAdditions, getCommits, getCommitsBetween, hasMergeFromTarget, resolveBranchName, resolveCommitSha, resolveReleaseBaseCommit, } from './git.js';
+import { logger } from './logger.js';
+import { readConfigFile } from './utils/config/load-config.js';
+/** The branch's own commits, after `since` when it is on the branch (see getCommits). */
+const getBranchRange = async (head, base, since) => {
+    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, headSha, since) => {
+    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, base, actorConfigs, testFilesGlob) => {
+    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, }) => {
+    // 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, }) => {
+    const names = (configs) => configs.map(({ actorFullName }) => ({ actorFullName }));
+    return {
+        version: 1,
+        ref,
+        head: headSha,
+        commits,
+        changedFiles,
+        changelog,
+        functionallyChangedActors: names(functionallyChangedActors),
+        cosmeticallyChangedActors: names(cosmeticallyChangedActors),
+    };
+};
+//# sourceMappingURL=affected-actors.js.map