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

package/bin/diff-changes.ts

@@ -1,4 +1,6 @@
 import { isCosmeticOnlyJsonSchemaChange } from './diff-json-schema.js';
+import { type DockerIgnoreMatcher, loadDockerIgnore } from './dockerignore.js';
+import { findContainingScope, hoistPath, isPathWithinScope } from './path-utils.js';
 import type { ActorConfig, Commit } from './types.js';
 
 interface ShouldBuildAndTestOptions {
@@ -8,89 +10,160 @@ interface ShouldBuildAndTestOptions {
     commits: Commit[];
 }
 
-export const maybeParseActorFolder = (
-    lowercaseFilePath: string,
-): { isActorFolder: true; actorName: string } | { isActorFolder: false } => {
-    const match = lowercaseFilePath.match(/^(?:standalone-)?actors\/([^/]+)\/.+/);
-    if (match) {
-        // Some usernames weirdly use underscores, e.g. google_maps_email_extractor_standby-contact-details-scraper so we only need replace the last one
-        return { isActorFolder: true, actorName: match[1].replace(/_(?=[^_]*$)/, '/') };
-    }
-    return { isActorFolder: false };
-};
+const IGNORED_TOP_LEVEL_FILES = [
+    '.vscode/',
+    '.gitignore',
+    '.husky/',
+    '.eslintrc',
+    'eslint.config.mjs',
+    '.prettierrc',
+    '.editorconfig',
+];
+
+// Expects an already-hoisted path (relative to the matched context entry, see findContainingScope).
+const isIgnoredTopLevelFile = (hoistedLowercaseFilePath: string): boolean =>
+    IGNORED_TOP_LEVEL_FILES.some((pattern) => hoistedLowercaseFilePath.startsWith(pattern));
+
+type FileChangeForActor =
+    | { impact: 'ignored' }
+    | { impact: 'outside-context' }
+    | { impact: 'cosmetic'; semanticallyVerified: boolean }
+    | { impact: 'functional' };
 
 /**
- * Also works for folders
+ * Classify a single file change for a single actor.
+ *
+ * Steps (in order):
+ * 1. CHANGELOG.md, by filename, anywhere → cosmetic. There is a single repo-wide shared changelog,
+ *    not one per actor, so it applies to every actor regardless of context/folder.
+ * 2. Context matching (actorConfig.contextPaths) → outside-context if no match
+ * 3. Hardcoded ignore list, checked against the path hoisted relative to the matched context entry → ignored
+ * 4. .dockerignore filtering (patterns relative to dockerContextDir), skipped for the actor's own `.actor/`
+ *    dir → ignored if matched
+ * 5. README.md by filename → cosmetic if inside the actor's own folder, otherwise ignored
+ * 6. .json inside the actor's own `.actor/` dir with only cosmetic schema diffs → cosmetic (semantically verified)
+ * 7. Everything else → functional
  */
-const isIgnoredTopLevelFile = (lowercaseFilePath: string) => {
-    // On top level, we should only have dev-only readme and .actor/ is just for apify push CLI (real Actor configs are in /actors)
-    const IGNORED_TOP_LEVEL_FILES = [
-        '.vscode/',
-        '.gitignore',
-        'readme.md',
-        '.husky/',
-        '.eslintrc',
-        'eslint.config.mjs',
-        '.prettierrc',
-        '.editorconfig',
-        '.actor/',
-    ];
-    // Strip out deprecated /code and /shared folders, treat them as top-level code
-    const sanitizedLowercaseFilePath = lowercaseFilePath.replace(/^code\//, '').replace(/^shared\//, '');
-
-    return IGNORED_TOP_LEVEL_FILES.some((ignoredFile) => sanitizedLowercaseFilePath.startsWith(ignoredFile));
-};
-
-type FileChange =
-    | { impact: 'ignored' }
-    // Only things that influence how the Actor looks - e.g. README and CHANGELOG files, schema titles, descriptions, reordering, etc. We only need to rebuild on release
-    | { impact: 'cosmetic'; semanticallyVerified: boolean; includes: 'all-actors' | ActorConfig }
-    // Influences how the Actor works - we need to run tests
-    | {
-          impact: 'functional';
-          includes: 'all-actors' | ActorConfig;
-      };
-
-const classifyFileChange = (originalFilePath: string, actorConfigs: ActorConfig[], commits: Commit[]): FileChange => {
-    // Lowercase for case-insensitive matching; keep original for git show (case-sensitive on Linux)
+const classifyFileChange = (
+    originalFilePath: string,
+    actorConfig: ActorConfig,
+    commits: Commit[],
+    dockerIgnoreMatcher: DockerIgnoreMatcher,
+): FileChangeForActor => {
     const lowercaseFilePath = originalFilePath.toLowerCase();
-    if (isIgnoredTopLevelFile(lowercaseFilePath)) {
+
+    // TODO: hardcodes that there's a single repo-wide changelog belonging to every actor. Should instead
+    // be derived from parsing actor.json (readme, changelog, schema paths), see
+    // https://github.com/apify/apify-test-tools/issues/106
+    if (lowercaseFilePath.endsWith('changelog.md')) {
+        return { impact: 'cosmetic', semanticallyVerified: false };
+    }
+
+    const lowercaseContextPaths = actorConfig.contextPaths.map((contextPath) => contextPath.toLowerCase());
+
+    const matchedContext = findContainingScope(lowercaseFilePath, lowercaseContextPaths);
+    if (matchedContext === undefined) {
+        return { impact: 'outside-context' };
+    }
+
+    const hoistedFilePath = hoistPath(lowercaseFilePath, matchedContext);
+    if (isIgnoredTopLevelFile(hoistedFilePath)) {
         return { impact: 'ignored' };
     }
 
-    if (lowercaseFilePath.endsWith('changelog.md')) {
-        return { impact: 'cosmetic', semanticallyVerified: false, includes: 'all-actors' };
+    const lowercaseFolder = actorConfig.folder.toLowerCase();
+    const actorDotDir = lowercaseFolder ? `${lowercaseFolder}/.actor` : '.actor';
+    const isUnderActorDotDir = isPathWithinScope(lowercaseFilePath, actorDotDir);
+
+    // .actor/ can legitimately be listed in .dockerignore (the Apify platform evaluates it before
+    // the Docker build, so excluding it from the build context is a valid caching optimization) —
+    // that shouldn't cause changes to .actor/ itself to be ignored here.
+    if (!isUnderActorDotDir && dockerIgnoreMatcher(originalFilePath)) {
+        return { impact: 'ignored' };
     }
 
-    const actorFolderInfo = maybeParseActorFolder(lowercaseFilePath);
-    if (actorFolderInfo.isActorFolder) {
-        const actorConfigChanged = actorConfigs.find(
-            ({ actorName }) => actorName.toLowerCase() === actorFolderInfo.actorName,
-        );
-        // This is some super weird case that happened once in the past but I don't remember the context anymore
-        if (actorConfigChanged === undefined) {
-            console.error(
-                'SHOULD NEVER HAPPEN: changes was found in an actor folder which no longer exists in the current commit, skipping this file',
-                {
-                    actorName: actorFolderInfo.actorName,
-                    lowercaseFilePath,
-                },
-            );
-            return { impact: 'ignored' };
-        }
-        if (lowercaseFilePath.endsWith('readme.md')) {
-            return { impact: 'cosmetic', semanticallyVerified: false, includes: actorConfigChanged };
+    const isInActorFolder = isPathWithinScope(lowercaseFilePath, lowercaseFolder);
+
+    if (lowercaseFilePath.endsWith('readme.md')) {
+        return isInActorFolder ? { impact: 'cosmetic', semanticallyVerified: false } : { impact: 'ignored' };
+    }
+
+    if (lowercaseFilePath.endsWith('.json') && isUnderActorDotDir) {
+        const isCosmetic = isCosmeticOnlyJsonSchemaChange(commits, originalFilePath);
+        if (isCosmetic) {
+            return { impact: 'cosmetic', semanticallyVerified: true };
         }
-        // originalFilePath must be used here (not lowercaseFilePath) — git show is case-sensitive on Linux
-        if (lowercaseFilePath.endsWith('.json') && isCosmeticOnlyJsonSchemaChange(commits, originalFilePath)) {
-            return { impact: 'cosmetic', semanticallyVerified: true, includes: actorConfigChanged };
+    }
+
+    return { impact: 'functional' };
+};
+
+/**
+ * Check if a file falls inside another actor's folder.
+ * Root actors (folder === "") never exclude files from siblings.
+ */
+const isExcludedBySibling = (lowercaseFilePath: string, actor: ActorConfig, allActors: ActorConfig[]): boolean => {
+    return allActors.some(
+        (other) =>
+            other.folder !== actor.folder &&
+            other.folder !== '' &&
+            isPathWithinScope(lowercaseFilePath, other.folder.toLowerCase()),
+    );
+};
+
+type ActorChangeEntry = {
+    actorConfig: ActorConfig;
+    files: string[];
+};
+
+type ChangeGroup = { actors: string[]; files: string[] };
+
+/**
+ * Maps each changed file to the set of actor names it triggered a change for.
+ */
+const buildFileToActorsMap = (actorsChangedMap: Map<string, ActorChangeEntry>): Map<string, Set<string>> => {
+    const fileToActors = new Map<string, Set<string>>();
+    for (const { actorConfig, files } of actorsChangedMap.values()) {
+        for (const file of files) {
+            const actors = fileToActors.get(file) ?? new Set<string>();
+            actors.add(actorConfig.actorFullName);
+            fileToActors.set(file, actors);
         }
+    }
+    return fileToActors;
+};
 
-        return { impact: 'functional', includes: actorConfigChanged };
+/**
+ * Groups files by their identical actor-set (files triggering a change for the exact same
+ * actors are grouped together), then orders the groups by descending actor-set size
+ * (most-shared groups first), breaking ties alphabetically by actor names.
+ */
+const groupFilesByActorSet = (fileToActors: Map<string, Set<string>>): ChangeGroup[] => {
+    const groupsByKey = new Map<string, ChangeGroup>();
+    for (const [file, actorsSet] of fileToActors) {
+        const actors = Array.from(actorsSet).sort();
+        const key = actors.join(',');
+        const group = groupsByKey.get(key) ?? { actors, files: [] };
+        group.files.push(file);
+        groupsByKey.set(key, group);
     }
 
-    // For any other files, we assume they can interact with the code
-    return { impact: 'functional', includes: 'all-actors' };
+    return Array.from(groupsByKey.values()).sort((groupA, groupB) => {
+        if (groupB.actors.length !== groupA.actors.length) {
+            return groupB.actors.length - groupA.actors.length;
+        }
+        return groupA.actors.join(',').localeCompare(groupB.actors.join(','));
+    });
+};
+
+const logChangeGroups = (groups: ChangeGroup[]): void => {
+    for (const { actors, files } of groups) {
+        if (actors.length > 1) {
+            console.error(`[DIFF]: Shared changes for actors ${actors.join(', ')}: ${files.join(', ')}`);
+        } else {
+            console.error(`[DIFF]: Changes specific to actor ${actors[0]}: ${files.join(', ')}`);
+        }
+    }
 };
 
 export const getChangedActors = ({
@@ -99,72 +172,40 @@ export const getChangedActors = ({
     isLatest = false,
     commits,
 }: ShouldBuildAndTestOptions): ActorConfig[] => {
-    // folder -> ActorConfig
-    const actorsChangedMap = new Map<string, ActorConfig>();
-
-    const actorConfigsWithoutStandalone = actorConfigs.filter(({ isStandalone }) => !isStandalone);
+    const actorsChangedMap = new Map<string, ActorChangeEntry>();
 
-    for (const originalFilePath of filepathsChanged) {
-        const fileChange = classifyFileChange(originalFilePath, actorConfigs, commits);
-        if (fileChange.impact === 'ignored') {
-            continue;
-        }
+    for (const actorConfig of actorConfigs) {
+        const dockerIgnoreMatcher = loadDockerIgnore(actorConfig.dockerContextDir);
 
-        if (fileChange.impact === 'cosmetic' && !isLatest) {
-            continue;
-        }
+        for (const originalFilePath of filepathsChanged) {
+            const lowercaseFilePath = originalFilePath.toLowerCase();
 
-        if (fileChange.includes !== 'all-actors') {
-            actorsChangedMap.set(fileChange.includes.folder, fileChange.includes);
-        } else if (fileChange.includes === 'all-actors') {
-            // Standalone Actors are handled always via specific actors change, not all-actors
-            for (const actorConfig of actorConfigsWithoutStandalone) {
-                actorsChangedMap.set(actorConfig.folder, actorConfig);
+            if (isExcludedBySibling(lowercaseFilePath, actorConfig, actorConfigs)) {
+                continue;
             }
-        }
-    }
 
-    const actorsChanged = Array.from(actorsChangedMap.values());
+            const change = classifyFileChange(originalFilePath, actorConfig, commits, dockerIgnoreMatcher);
 
-    // All below here is just for logging
-    const formatFiles = (files: string[]) => (files.length > 0 ? files.join(', ') : '<no files>');
+            if (change.impact === 'ignored' || change.impact === 'outside-context') continue;
+            if (change.impact === 'cosmetic' && !isLatest) continue;
 
-    const ignoredFilesChanged = filepathsChanged.filter(
-        (file) => classifyFileChange(file, actorConfigs, commits).impact === 'ignored',
-    );
-    console.error(`[DIFF]: Ignored files (don't trigger test or build): ${formatFiles(ignoredFilesChanged)}`);
-
-    const cosmeticChanges = filepathsChanged
-        .map((file) => ({ file, change: classifyFileChange(file, actorConfigs, commits) }))
-        .filter(({ change }) => change.impact === 'cosmetic') as {
-        file: string;
-        change: Extract<FileChange, { impact: 'cosmetic' }>;
-    }[];
-    const semanticallyVerifiedFiles = cosmeticChanges
-        .filter(({ change }) => change.semanticallyVerified)
-        .map(({ file }) => file);
-    const inherentlyCosmeticFiles = cosmeticChanges
-        .filter(({ change }) => !change.semanticallyVerified)
-        .map(({ file }) => file);
-    console.error(
-        `[DIFF]: Cosmetic-only JSON schema changes (semantically verified, only trigger release build): ${formatFiles(semanticallyVerifiedFiles)}`,
-    );
-    console.error(
-        `[DIFF]: Inherently cosmetic files (README, CHANGELOG — only trigger release build): ${formatFiles(inherentlyCosmeticFiles)}`,
-    );
+            const entry = actorsChangedMap.get(actorConfig.folder) ?? { actorConfig, files: [] };
+            entry.files.push(originalFilePath);
+            actorsChangedMap.set(actorConfig.folder, entry);
+        }
+    }
 
-    const functionalFilesChanged = filepathsChanged.filter(
-        (file) => classifyFileChange(file, actorConfigs, commits).impact === 'functional',
-    );
-    console.error(`[DIFF]: Functional files (trigger test & release build): ${formatFiles(functionalFilesChanged)}`);
+    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);
 
     if (actorsChanged.length > 0) {
-        const miniactors = actorsChanged.filter((config) => !config.isStandalone).map((config) => config.actorName);
-        const standaloneActors = actorsChanged
-            .filter((config) => config.isStandalone)
-            .map((config) => config.actorName);
-        console.error(`[DIFF]: MiniActors to be built and tested: ${miniactors.join(', ')}`);
-        console.error(`[DIFF]: Standalone Actors to be built and tested: ${standaloneActors.join(', ')}`);
+        const actors = actorsChanged.map((config) => config.actorFullName);
+        console.error(`[DIFF]: Actors to be built and tested: ${actors.join(', ')}`);
     } else {
         console.error(`[DIFF]: No relevant files changed, skipping builds and tests`);
     }

package/bin/dockerignore.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import ignore from 'ignore';
+
+import { hoistPath, isPathWithinScope } from './path-utils.js';
+
+export type DockerIgnoreMatcher = (repoRelativePath: string) => boolean;
+
+// Docker normalizes each pattern before matching, so a leading "./" (as in the common "./node_modules"
+// style) is a no-op for Docker. The `ignore` package has no such normalization — it treats "./" as
+// literal pattern text that can never match a real path, so a .dockerignore written in that style
+// would otherwise silently match nothing. Strip it here (after any negation prefix) so the pattern
+// behaves the way Docker itself would apply it.
+const normalizeDockerignorePattern = (line: string): string => line.replace(/^(!?)(?:\.\/)+/, '$1');
+
+/**
+ * Reads `.dockerignore` from `absoluteRootDir` and returns a matcher for paths relative to
+ * `hoistFrom`. `hoistFrom` defaults to '', meaning callers already pass paths relative to
+ * `absoluteRootDir` directly — isPathWithinScope/hoistPath both treat '' as "matches everything" /
+ * identity, so the scope-check and hoist collapse to a no-op in that case, not via a branch.
+ *
+ * Returns a no-op matcher (always returns false) when the file is absent.
+ */
+export const buildDockerIgnoreMatcher = (absoluteRootDir: string, hoistFrom = ''): DockerIgnoreMatcher => {
+    let content: string;
+    try {
+        content = fs.readFileSync(path.join(absoluteRootDir, '.dockerignore'), 'utf-8');
+    } catch {
+        return () => false;
+    }
+
+    const matcher = ignore().add(content.split('\n').map(normalizeDockerignorePattern).join('\n'));
+
+    return (filePath: string): boolean => {
+        if (!isPathWithinScope(filePath.toLowerCase(), hoistFrom.toLowerCase())) {
+            return false;
+        }
+
+        return matcher.ignores(hoistPath(filePath, hoistFrom));
+    };
+};
+
+/**
+ * Load .dockerignore from the root of an actor's dockerContextDir and return a matcher
+ * that accepts repo-root-relative file paths. Patterns are resolved relative to
+ * dockerContextDir, matching Docker's own behavior.
+ */
+export const loadDockerIgnore = (dockerContextDir: string): DockerIgnoreMatcher =>
+    buildDockerIgnoreMatcher(path.resolve(dockerContextDir), dockerContextDir);

package/bin/git.ts

@@ -94,7 +94,11 @@ const fetchAllBranchCommits = (sourceBranch: string, targetBranch: string): Comm
  * Gets the commits between sourceBranch and targetBranch (exclusive).
  * - If baseCommit is provided, only returns commits after the baseCommit.
  */
-export const getCommits = ({ sourceBranch, targetBranch, baseCommit }: Config): Commit[] => {
+export const getCommits = ({
+    sourceBranch,
+    targetBranch,
+    baseCommit,
+}: Pick<Config, 'sourceBranch' | 'targetBranch' | 'baseCommit'>): Commit[] => {
     const baseCommitSha = parseBaseCommit(baseCommit);
     const commits = fetchAllBranchCommits(sourceBranch, targetBranch);
 

package/bin/main.ts

@@ -14,14 +14,14 @@ import { getPushData } from './github.js';
 import { notifyToSlack } from './slack.js';
 import { reportTestResults } from './test-report.js';
 import type { Config } from './types.js';
-import { getRepoActors, setCwd, spawnCommandInGhWorkspace } from './utils.js';
+import { readConfigFile, setCwd, spawnCommandInGhWorkspace } from './utils.js';
 
 /**
  * Middlewares to be run before every command execution
  */
 const middlewares = [setCwd];
 
-const buildOptions = (y: Argv) => {
+export const buildOptions = <T>(y: Argv<T>) => {
     return y
         .option('target-branch', {
             type: 'string',
@@ -37,27 +37,44 @@ const buildOptions = (y: Argv) => {
         })
         .option('base-commit', {
             type: 'string',
+            demandOption: false,
         });
 };
 
-const resolveChangedActors = async (
-    { targetBranch, sourceBranch, baseCommit }: Config,
-    { isLatest }: { isLatest: boolean },
-) => {
-    const actorConfigs = await getRepoActors();
+/**
+ * Actor-selection flags, applied to every command that reads the actor config so a caller can
+ * narrow the set it operates on (e.g. two-stage releases: `--ignore X`, then `--actors X`).
+ * Kept separate from `buildOptions` so the read-only git commands don't advertise flags they ignore.
+ */
+export const actorSelectionOptions = <T>(y: Argv<T>) => {
+    return y
+        .option('actors', {
+            type: 'string',
+            array: true,
+            default: [] as string[],
+        })
+        .option('ignore', {
+            type: 'string',
+            array: true,
+            default: [] as string[],
+        });
+};
+
+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 merge in
+    // 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 (hasMergeFromTarget(sourceBranch, targetBranch)) {
+    if (hasMergeFromTarget(config.sourceBranch, config.targetBranch)) {
         console.error(
             '[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 = getBranchOnlyChangedFiles(sourceBranch, targetBranch);
+        const branchOnlyFiles = getBranchOnlyChangedFiles(config.sourceBranch, config.targetBranch);
         // Omit baseCommit to get full branch history. Validated functional commits can still interact with merged ones
-        const allBranchCommits = getCommits({ sourceBranch, targetBranch, baseCommit: undefined });
+        const allBranchCommits = getCommits({ ...config, baseCommit: undefined });
         const branchOnlyActorsChanged = getChangedActors({
             filepathsChanged: branchOnlyFiles,
             actorConfigs,
@@ -73,7 +90,7 @@ const resolveChangedActors = async (
     }
 
     // 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 = getCommits({ targetBranch, sourceBranch, baseCommit });
+    const commits = getCommits(config);
     const changedFiles = getChangedFiles(commits);
     return getChangedActors({ filepathsChanged: changedFiles, actorConfigs, isLatest, commits });
 };
@@ -103,22 +120,19 @@ await yargs()
         const changedFiles = getChangedFiles(commits);
         console.log(JSON.stringify(changedFiles));
     })
+    .command('get-actor-configs', '', actorSelectionOptions, async ({ actors, ignore }) => {
+        const actorConfigs = await readConfigFile({ actors, ignore });
+        console.log(JSON.stringify(actorConfigs));
+    })
     .command(
-        'get-actor-configs',
+        'get-affected-actors',
         '',
-        (_) => _,
-        async () => {
-            const actorConfigs = await getRepoActors();
-            console.log(JSON.stringify(actorConfigs));
+        (args) => actorSelectionOptions(buildOptions(args)),
+        async (config) => {
+            const actorsChanged = await resolveChangedActors(config, { isLatest: false });
+            console.log(JSON.stringify(actorsChanged));
         },
     )
-    .command('get-affected-actors', '', buildOptions, async ({ targetBranch, sourceBranch, baseCommit }) => {
-        const actorsChanged = await resolveChangedActors(
-            { targetBranch, sourceBranch, baseCommit },
-            { isLatest: false },
-        );
-        console.log(JSON.stringify(actorsChanged));
-    })
     .command(
         'report-tests',
         '',
@@ -135,12 +149,9 @@ await yargs()
     .command(
         'build',
         '',
-        (args) => buildOptions(args).option('dry-run', { type: 'boolean', default: false }),
-        async ({ targetBranch, sourceBranch, baseCommit, dryRun, useDockerCache }) => {
-            const actorsChanged = await resolveChangedActors(
-                { targetBranch, sourceBranch, baseCommit },
-                { isLatest: false },
-            );
+        (args) => actorSelectionOptions(buildOptions(args)).option('dry-run', { type: 'boolean', default: false }),
+        async (config) => {
+            const actorsChanged = await resolveChangedActors(config, { isLatest: false });
             // https://github.com/apify-store/google-maps#:actors/lukaskrivka_google-maps-with-contact-details
             // git@github.com:apify-store/google-maps#:actors/lukaskrivka_google-maps-with-contact-details
             const repoUrl = spawnCommandInGhWorkspace(`git remote get-url origin`).replace(
@@ -151,9 +162,9 @@ await yargs()
             const builds = await runBuilds({
                 repoUrl,
                 actorConfigs: actorsChanged,
-                branch: sourceBranch.replace('origin/', ''),
-                dryRun,
-                useDockerCache,
+                branch: config.sourceBranch.replace('origin/', ''),
+                dryRun: config.dryRun,
+                useDockerCache: config.useDockerCache,
             });
             console.log(JSON.stringify(builds));
         },
@@ -162,7 +173,7 @@ await yargs()
         'release',
         '',
         (args) =>
-            args
+            actorSelectionOptions(args)
                 .option('push-event-path', { type: 'string', demandOption: true })
                 .option('dry-run', { type: 'boolean', default: false })
                 .option('report-slack-channel', { type: 'string' })
@@ -173,7 +184,7 @@ await yargs()
                 args.pushEventPath,
             );
             const isLatest = true;
-            const actorConfigs = await getRepoActors();
+            const actorConfigs = await readConfigFile(args);
             const actorsChanged = getChangedActors({
                 filepathsChanged: changedFiles,
                 actorConfigs,
@@ -206,37 +217,30 @@ await yargs()
     .command(
         'build-from-local',
         '',
-        (args) =>
-            args
-                .option('actors', {
-                    type: 'string',
-                    description:
-                        'Comma-separated actor names (owner/name) to build. Defaults to all actors in the repo.',
-                })
-                .option('dry-run', { type: 'boolean', default: false }),
-        async ({ actors, dryRun }) => {
-            const allActorConfigs = await getRepoActors();
-            const actorConfigs = actors
-                ? actors.split(',').map((name) => {
-                      const trimmed = name.trim();
-                      const config = allActorConfigs.find((c) => c.actorName === trimmed);
-                      if (!config) throw new Error(`Actor "${trimmed}" not found in repo`);
-                      return config;
-                  })
-                : allActorConfigs;
+        (args) => actorSelectionOptions(args).option('dry-run', { type: 'boolean', default: false }),
+        async ({ actors, ignore, dryRun }) => {
+            const actorConfigs = await readConfigFile({ actors, ignore });
             const builds = await runBuildsFromLocal({ actorConfigs, dryRun });
             console.log(JSON.stringify(builds));
         },
     )
-    .command(
-        'delete-old-builds',
-        '',
-        (_) => _,
-        async () => {
-            const actorConfigs = await getRepoActors();
-            await deleteOldBuilds(actorConfigs);
-        },
-    )
+    .command('delete-old-builds', '', actorSelectionOptions, async ({ actors, ignore }) => {
+        const actorConfigs = await readConfigFile({ actors, ignore });
+        await deleteOldBuilds(actorConfigs);
+    })
     .strictCommands()
     .demandCommand(1, 'Command is required')
+    .fail((msg, err, yargsInstance) => {
+        // Errors thrown from a command handler (e.g. an unknown actor passed to --actors/--ignore,
+        // or a missing config file) arrive here as `err`. A malformed selection must fail loudly
+        // rather than silently operate on the wrong set of actors — print the message, no stack.
+        if (err) {
+            console.error(`[ERROR]: ${err.message}`);
+        } else {
+            // Argument-parsing/validation failure — keep yargs' usage output.
+            console.error(yargsInstance.help());
+            console.error(`\n${msg}`);
+        }
+        process.exit(1);
+    })
     .parse(hideBin(process.argv));

package/bin/path-utils.ts

@@ -0,0 +1,13 @@
+// filePath and scopePath are both repo-root-relative POSIX paths, already normalized (no trailing slashes).
+// scopePath === '' means "matches everything" — the caller's own scope (a context path, an actor's folder,
+// a sibling's folder, a docker context dir), not necessarily the repo root.
+export const isPathWithinScope = (filePath: string, scopePath: string): boolean =>
+    scopePath === '' || filePath === scopePath || filePath.startsWith(`${scopePath}/`);
+
+// Returns the single scopePaths entry filePath falls under, if any.
+export const findContainingScope = (filePath: string, scopePaths: string[]): string | undefined =>
+    scopePaths.find((scopePath) => isPathWithinScope(filePath, scopePath));
+
+// Returns filePath relative to scopePath (assumes isPathWithinScope(filePath, scopePath) is already true).
+export const hoistPath = (filePath: string, scopePath: string): string =>
+    scopePath === '' ? filePath : filePath.slice(scopePath.length + 1);