@applitools/core 4.53.1 → 4.54.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [4.54.0](https://github.com/Applitools-Dev/sdk/compare/js/core@4.53.2...js/core@4.54.0) (2025-12-14)
+
+
+### Features
+
+* Baseline branch fallback list | FLD-3837 ([#3373](https://github.com/Applitools-Dev/sdk/issues/3373)) ([e94bb10](https://github.com/Applitools-Dev/sdk/commit/e94bb10ad6b49322a56e4ce6dfde560b237e9ac0))
+
+
+### Dependencies
+
+* @applitools/nml-client bumped to 1.11.13
+
+* @applitools/core-base bumped to 1.31.0
+  #### Features
+
+  * Baseline branch fallback list | FLD-3837 ([#3373](https://github.com/Applitools-Dev/sdk/issues/3373)) ([e94bb10](https://github.com/Applitools-Dev/sdk/commit/e94bb10ad6b49322a56e4ce6dfde560b237e9ac0))
+* @applitools/ec-client bumped to 1.12.15
+
+
+## [4.53.2](https://github.com/Applitools-Dev/sdk/compare/js/core@4.53.1...js/core@4.53.2) (2025-12-07)
+
+
+### Bug Fixes
+
+* Upgrade core version ([#3398](https://github.com/Applitools-Dev/sdk/issues/3398)) ([68858c7](https://github.com/Applitools-Dev/sdk/commit/68858c7024e0413c1cc6af68752b1c3a9a04bb0b))
+
+
+### Dependencies
+
+* @applitools/dom-snapshot bumped to 4.15.3
+  #### Bug Fixes
+
+  * capture JavaScript-modified CSS selectors in nested [@layer](https://github.com/layer) rules ([#3391](https://github.com/Applitools-Dev/sdk/issues/3391)) ([b3bceb5](https://github.com/Applitools-Dev/sdk/commit/b3bceb5bfe894f3548173d23942e09d0e04b7e04))
+
 ## [4.53.1](https://github.com/Applitools-Dev/sdk/compare/js/core@4.53.0...js/core@4.53.1) (2025-12-01)
 
 

package/dist/offline/run-offline-snapshots.js

@@ -326,6 +326,7 @@ async function runOfflineSnapshots(options) {
         const checkLogger = logger.extend({ tags: ['open-check-and-close'] });
         const { mergedCheckSettings, baseTarget } = await throttledRender(target, checkLogger);
         const settings = (0, merge_configs_1.mergeConfigs)(target.settings, mergedCheckSettings);
+        const processId = utils.general.guid();
         return core.base.openCheckAndCloseEyes({
             target: { ...baseTarget, isTransformed: true },
             settings: {
@@ -338,9 +339,10 @@ async function runOfflineSnapshots(options) {
             },
             logger: checkLogger,
             heartbeat: {
-                processId: '',
+                processId: processId,
                 acquire(settings) {
                     logger.log('acquire | heartbeat is not used (offline)', settings);
+                    return processId;
                 },
                 release() {
                     logger.log('release | heartbeat is not used (offline)');

package/dist/open-eyes.js

@@ -44,6 +44,7 @@ function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDup
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0;
         var _1, _2, _3, _4, _5;
         logger = logger.extend(mainLogger, { tags: [`eyes-${type}-${utils.general.shortid()}`] });
+        logger.log(`Opening Eyes in directory "${cwd}"`);
         const settings = { environments: config === null || config === void 0 ? void 0 : config.check.environments, ...config === null || config === void 0 ? void 0 : config.open, ...openSettings };
         const eyesServerSettings = (0, populate_eyes_server_settings_1.populateEyesServerSettings)(settings);
         logger.mask(eyesServerSettings.apiKey);
@@ -104,6 +105,7 @@ function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDup
             }
         }
         const account = await core.getAccountInfo({ settings: eyesServerSettings, logger });
+        await handleBranchFallbackList(account, settings, logger);
         const componentConcurrency = account.serverConcurrency.componentConcurrency;
         settings.sessionConcurrency = handleConcurrency({
             userConcurrency: concurrency,
@@ -192,6 +194,35 @@ function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDup
             }
         }
     };
+    async function handleBranchFallbackList(account, settings, logger) {
+        var _a, _b;
+        const scm = getScmSettings(account.scmSettings);
+        // Extract gitBranchName (the actual git branch name)
+        if (!settings.ignoreGitBranching && scm.lookupFallbackList) {
+            logger.log(`Extracting git branch name, ${cwd}`);
+            settings.gitBranchName = await (0, extract_git_info_1.extractGitBranch)({
+                execOptions: { cwd },
+                logger,
+                ignoreGitBranching: settings.ignoreGitBranching,
+            });
+            logger.log(`Extracted git branch name: ${settings.gitBranchName}`);
+            (_a = settings.branchName) !== null && _a !== void 0 ? _a : (settings.branchName = settings.gitBranchName);
+            // logger.log(`Using branch name: ${settings.branchName}`)
+        }
+        else {
+            logger.log(`Skipping extraction of git branch name as ignoreGitBranching is set to true`);
+        }
+        if (settings.gitBranchName && !settings.ignoreGitBranching && scm.lookupFallbackList) {
+            logger.log(`Extracting branch lookup fallback list for branch "${settings.gitBranchName}, ${cwd}"`);
+            // add write to coralogix before and after
+            settings.branchLookupFallbackList = await (0, extract_git_info_1.extractBranchLookupFallbackList)({
+                gitBranchName: `${settings.gitBranchName}`,
+                enableShallowClone: (_b = scm.enableShallowClone) !== null && _b !== void 0 ? _b : false,
+                execOptions: { cwd },
+                logger,
+            });
+        }
+    }
 }
 exports.makeOpenEyes = makeOpenEyes;
 function refineMissingApiKeyException(error, sdk) {
@@ -213,7 +244,6 @@ function refineMissingApiKeyException(error, sdk) {
                     eyes_selenium: undefined,
                     eyes_universal: undefined,
                     eyes_capybara: undefined,
-                    eyes_calabash: undefined,
                 },
                 java: {
                     java_appium: undefined,
@@ -269,6 +299,24 @@ exports.getLatestCommitInfoFromEnvVars = getLatestCommitInfoFromEnvVars;
 function isRealBatchId(batchId) {
     return !!batchId && !batchId.startsWith('generated');
 }
+function getScmSettings(scmSettings) {
+    var _a, _b;
+    // shallow clone is enabled by default and is currently not sent from the server
+    let enableShallowClone = (_a = scmSettings.isShallowCloneEnabled) !== null && _a !== void 0 ? _a : true;
+    let lookupFallbackList = (_b = scmSettings.isFallbackBranchListEnabled) !== null && _b !== void 0 ? _b : false;
+    const envLookupFallbackList = utils.general.getEnvValue('ENABLE_BRANCH_LOOKUP_FALLBACK_LIST', 'boolean');
+    const envShallowClone = utils.general.getEnvValue('SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE', 'boolean');
+    if (envLookupFallbackList !== undefined) {
+        lookupFallbackList = envLookupFallbackList;
+    }
+    if (envShallowClone !== undefined) {
+        enableShallowClone = !envShallowClone;
+    }
+    return {
+        lookupFallbackList,
+        enableShallowClone,
+    };
+}
 function handleConcurrency({ userConcurrency, componentConcurrency, useServerConcurrency, shouldPrintConcurrencyWarning, logger, }) {
     let sessionConcurrency;
     // if user concurrency is 0 or negative, we ignore it and use server concurrency or default

package/dist/utils/extract-git-info.js

@@ -26,12 +26,34 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isISODate = exports.extractBranchingTimestamp = exports.extractBuildIdFromCI = exports.extractGitRepo = exports.extractGitBranch = exports.extractLatestCommitInfo = exports.cacheKey = void 0;
+exports.extractBranchLookupFallbackList = exports.isISODate = exports.extractBranchingTimestamp = exports.extractBuildIdFromCI = exports.extractGitRepo = exports.extractGitBranch = exports.extractLatestCommitInfo = exports.getPrimaryRemoteName = exports.cacheKey = void 0;
 const utils = __importStar(require("@applitools/utils"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("@applitools/logger");
+// Check if debug mode is enabled for verbose git info logging
+const isDebugMode = () => process.env.RUNNER_DEBUG === '1';
 exports.cacheKey = 'default';
+/**
+ * Get the primary remote name (cached for performance)
+ * Prefers 'origin' if it exists, otherwise uses the first available remote
+ */
+exports.getPrimaryRemoteName = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)() }) {
+    const result = await executeWithLog('git remote show', { execOptions, logger });
+    if (result.stderr) {
+        logger.log(`Error during extracting remotes from git`, result.stderr);
+        return 'origin'; // Fallback to 'origin' if we can't determine remotes
+    }
+    const remotes = result.stdout.trim().split(/\s+/);
+    const remote = remotes.includes('origin') ? 'origin' : remotes[0] || 'origin';
+    logger.log(`Primary remote name: ${remote}`);
+    return remote;
+}, args => {
+    var _a;
+    return ({
+        cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd,
+    });
+});
 exports.extractLatestCommitInfo = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)(), }) {
     let result;
     try {
@@ -59,7 +81,8 @@ exports.extractLatestCommitInfo = utils.general.cachify(async function ({ execOp
     async function extractGithubPullRequestLastCommitSha() {
         var _a, _b, _c;
         if (((_a = process.env.GITHUB_EVENT_NAME) === null || _a === void 0 ? void 0 : _a.startsWith('pull_request')) && process.env.GITHUB_EVENT_PATH) {
-            await executeWithLog(`git fetch origin --depth=2`, { execOptions, logger });
+            const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+            await executeWithLog(`git fetch ${remoteName} --depth=2`, { execOptions, logger });
             const event = await fs_1.default.promises.readFile(process.env.GITHUB_EVENT_PATH, 'utf-8').then(JSON.parse);
             return (_c = (_b = event === null || event === void 0 ? void 0 : event.pull_request) === null || _b === void 0 ? void 0 : _b.head) === null || _c === void 0 ? void 0 : _c.sha;
         }
@@ -70,7 +93,7 @@ exports.extractGitBranch = utils.general.cachify(async function ({ execOptions,
         return process.env.GITHUB_HEAD_REF;
     }
     if (process.env.GITHUB_REF) {
-        return process.env.GITHUB_REF.split('/').splice(2).join('/'); // refs/heads/<branch_name>
+        return process.env.GITHUB_REF.split('/').splice(2).join('/');
     }
     const result = await executeWithLog('git branch --show-current', { execOptions, logger });
     if (result.stderr) {
@@ -81,7 +104,7 @@ exports.extractGitBranch = utils.general.cachify(async function ({ execOptions,
         logger.log(`Extracted current git branch: "${branch}"`);
         return branch;
     }
-}, () => exports.cacheKey);
+}, args => { var _a, _b, _c; return ({ cwd: (_b = (_a = args[0]) === null || _a === void 0 ? void 0 : _a.execOptions) === null || _b === void 0 ? void 0 : _b.cwd, ignoreGitBranching: (_c = args[0]) === null || _c === void 0 ? void 0 : _c.ignoreGitBranching }); });
 exports.extractGitRepo = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)() }) {
     const remotes = await extractRemotes();
     logger.log(`Extracted remotes from git: ${remotes}`);
@@ -125,22 +148,55 @@ exports.extractBuildIdFromCI = extractBuildIdFromCI;
 exports.extractBranchingTimestamp = utils.general.cachify(async function ({ branchName, parentBranchName, execOptions, logger = (0, logger_1.makeLogger)(), }) {
     var _a;
     logger = logger.extend({ tags: [`extract-branching-timestamp-${utils.general.shortid()}`] });
+    // Get the primary remote name (cached)
+    const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+    // Step 1: Try with remote refs first (fast path - uses already-fetched remote data)
     const command = `HASH=$(git merge-base ${branchName} ${parentBranchName}) && git show -q --format=%aI $HASH`;
     let result = await executeWithLog(command, { execOptions, logger });
-    // both parent and current branches could be missing, that's why we have to iterate the missing branches check check twice
-    for (let i = 0; i < 2; i++) {
-        if (result.stderr) {
-            const [, missingBranch] = (_a = result.stderr.match(/Not a valid object name ([^\s]+)/)) !== null && _a !== void 0 ? _a : [];
-            if (missingBranch) {
-                result = await executeWithLog(`git fetch origin ${missingBranch}:${missingBranch} && ${command}`, {
-                    execOptions,
-                    logger,
-                });
+    // Step 2: If remote refs failed, try local refs
+    if (result.stderr) {
+        const commandWithRemoteRefs = `HASH=$(git merge-base ${remoteName}/${branchName} ${remoteName}/${parentBranchName}) && git show -q --format=%aI $HASH`;
+        result = await executeWithLog(commandWithRemoteRefs, { execOptions, logger });
+    }
+    // Step 3: Handle missing branches with smart fetch (check remote existence first)
+    // Fetch remote branches list once if there's an error (cached call - virtually free)
+    if (result.stderr) {
+        const remoteBranches = await getAllRemoteBranches({ execOptions, logger });
+        // Both parent and current branches could be missing, iterate up to twice
+        for (let i = 0; i < 2; i++) {
+            if (result.stderr) {
+                const [, missingBranch] = (_a = result.stderr.match(/Not a valid object name ([^\s]+)/)) !== null && _a !== void 0 ? _a : [];
+                if (missingBranch) {
+                    // Normalize branch name by removing remote prefix
+                    const normalizedBranchName = missingBranch.replace(new RegExp(`^${remoteName}/`), '');
+                    if (!remoteBranches.has(normalizedBranchName)) {
+                        logger.log(`Branch ${missingBranch} not found on remote, skipping fetch`);
+                        return undefined; // Exit early - no point in fetching non-existent branch
+                    }
+                    // Branch exists on remote, proceed with fetch
+                    logger.log(`Fetching missing branch ${missingBranch} from remote`);
+                    const command = `HASH=$(git merge-base ${branchName} ${parentBranchName}) && git show -q --format=%aI $HASH`;
+                    /*
+                    // --filter=tree:0 creates a treeless clone.
+                    // These clones download all reachable commits while fetching trees and blobs on-demand.
+                    // These clones are best for build environments where the repository will be deleted
+                    // after a single build, but you still need access to commit history.
+                    */
+                    result = await executeWithLog(`git fetch ${remoteName} ${normalizedBranchName}:${normalizedBranchName} --filter=tree:0 && ${command}`, {
+                        execOptions,
+                        logger,
+                    });
+                }
             }
         }
     }
+    // Step 4: Fallback to unshallow if still no result
     if (!result.stdout) {
-        result = await executeWithLog(`git fetch origin --unshallow && ${command}`, { execOptions, logger });
+        const command = `HASH=$(git merge-base ${branchName} ${parentBranchName}) && git show -q --format=%aI $HASH`;
+        result = await executeWithLog(`git fetch ${remoteName} --unshallow --filter=tree:0 && ${command}`, {
+            execOptions,
+            logger,
+        });
     }
     const timestamp = result.stdout.replace(/\s/g, '');
     if (isISODate(timestamp)) {
@@ -150,7 +206,14 @@ exports.extractBranchingTimestamp = utils.general.cachify(async function ({ bran
     else {
         logger.log(`Error during extracting merge timestamp: git branching timestamp is an invalid ISO date string: ${timestamp}. stderr: ${result.stderr}, stdout: ${result.stdout}`);
     }
-}, () => exports.cacheKey);
+}, args => {
+    var _a;
+    return ({
+        branchName: args[0].branchName,
+        parentBranchName: args[0].parentBranchName,
+        cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd,
+    });
+});
 async function executeWithLog(command, { execOptions, logger = (0, logger_1.makeLogger)() } = {
     execOptions: {},
     logger: (0, logger_1.makeLogger)(),
@@ -166,3 +229,469 @@ function isISODate(str) {
     return /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\+\d{2}:\d{2})?/.test(str);
 }
 exports.isISODate = isISODate;
+/**
+ * Execute operations in parallel with a concurrency limit to avoid overwhelming system resources
+ * @param items - Array of items to process
+ * @param concurrency - Maximum number of concurrent operations
+ * @param fn - Async function to execute for each item
+ * @returns Array of results in the same order as input items
+ */
+async function parallelWithLimit(items, concurrency, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += concurrency) {
+        const batch = items.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Get all remote branches from the primary remote (cached for performance)
+ * Uses git ls-remote which is fast and doesn't require fetching data
+ * Cache TTL: 5 minutes (remote branches don't change frequently during a test run)
+ */
+const getAllRemoteBranches = utils.general.cachify(async function ({ execOptions, logger }) {
+    var _a;
+    if (isDebugMode()) {
+        logger.log('[getAllRemoteBranches] Starting git ls-remote to fetch all remote branches...');
+        logger.log('[getAllRemoteBranches] execOptions.cwd:', (execOptions === null || execOptions === void 0 ? void 0 : execOptions.cwd) || 'undefined');
+    }
+    try {
+        // Get the primary remote name (cached)
+        const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+        const startTime = Date.now();
+        const result = await executeWithLog(`git ls-remote --heads ${remoteName}`, {
+            execOptions,
+            logger,
+        });
+        if (isDebugMode()) {
+            logger.log(`[getAllRemoteBranches] git ls-remote completed in ${Date.now() - startTime}ms`);
+            logger.log('[getAllRemoteBranches] stdout length:', ((_a = result.stdout) === null || _a === void 0 ? void 0 : _a.length) || 0);
+            logger.log('[getAllRemoteBranches] stderr:', result.stderr || '(empty)');
+            logger.log('[getAllRemoteBranches] exit code:', result.code);
+        }
+        const branches = new Set();
+        if (result.stdout.trim()) {
+            const lines = result.stdout.split('\n');
+            if (isDebugMode()) {
+                logger.log(`[getAllRemoteBranches] Processing ${lines.length} lines from git ls-remote output`);
+            }
+            lines.forEach((line, index) => {
+                // Line format: "commit_sha\trefs/heads/branch-name"
+                const match = line.match(/refs\/heads\/(.+)$/);
+                if (match) {
+                    const branchName = match[1];
+                    branches.add(branchName);
+                    if (isDebugMode() && index < 5) {
+                        // Log first 5 branches for debugging
+                        logger.log(`[getAllRemoteBranches] Found branch: ${branchName}`);
+                    }
+                }
+            });
+            if (isDebugMode() && lines.length > 5) {
+                logger.log(`[getAllRemoteBranches] ... and ${lines.length - 5} more branches`);
+            }
+        }
+        else {
+            logger.log('[getAllRemoteBranches] WARNING: git ls-remote returned empty output');
+        }
+        logger.log(`[getAllRemoteBranches] ✓ Found ${branches.size} remote branches via git ls-remote`);
+        if (isDebugMode()) {
+            const branchList = Array.from(branches).slice(0, 20);
+            logger.log('[getAllRemoteBranches] Branch list:', branchList.join(', ') + (branches.size > 20 ? ` ... and ${branches.size - 20} more` : ''));
+        }
+        return branches;
+    }
+    catch (err) {
+        logger.log('[getAllRemoteBranches] ✗ ERROR: Could not fetch remote branches list');
+        logger.log('[getAllRemoteBranches] Error details:', err);
+        logger.log('[getAllRemoteBranches] Error type:', typeof err);
+        if (err instanceof Error) {
+            logger.log('[getAllRemoteBranches] Error message:', err.message);
+            logger.log('[getAllRemoteBranches] Error stack:', err.stack);
+        }
+        return new Set();
+    }
+}, 
+// Custom cache key generator - only cache by cwd, not by logger instance
+args => { var _a; return ({ cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd }); }, 5 * 60 * 1000);
+/**
+ * Determine fetch strategy and execute appropriate fetch operation
+ */
+async function executeFetchStrategy(isShallow, execOptions, logger) {
+    const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+    if (isShallow) {
+        // Shallow clone needs full unshallow for initial topology discovery
+        logger.log(`Shallow repository detected, unshallowing to enable topology discovery...`);
+        await executeWithLog(`git fetch ${remoteName} --unshallow --filter=tree:0`, {
+            execOptions,
+            logger,
+        });
+        logger.log(`Repository unshallowed successfully`);
+    }
+    else {
+        // Non-shallow clone (e.g., single-branch clone) needs to fetch all remote branches for topology discovery
+        logger.log(`Non-shallow clone detected, fetching all remote branches for topology discovery...`);
+        await executeWithLog(`git fetch ${remoteName} --filter=tree:0`, {
+            execOptions,
+            logger,
+        });
+        logger.log(`All remote branches fetched successfully`);
+    }
+}
+/**
+ * Helper function to check if we're dealing with a remote branch scenario
+ * and fetch specific remote branches if needed for complete ancestor checking
+ *
+ * @param branchName - The current branch being analyzed
+ * @param branchesToFetch - Array of ancestor branch names that need to be fetched (empty = fetch all)
+ * @param isShallow - Whether the repository is a shallow clone
+ * @param execOptions - Git execution options
+ * @param logger - Logger instance
+ */
+async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions, logger) {
+    try {
+        // Get the primary remote name (cached)
+        const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+        // Check if current branch tracks a remote branch
+        const symbolicResult = await executeWithLog(`git rev-parse --abbrev-ref ${branchName}@{upstream} `, {
+            execOptions,
+            logger,
+        });
+        const isRemoteBranch = symbolicResult.stdout.trim().startsWith(`${remoteName}/`);
+        if (!isRemoteBranch) {
+            return;
+        }
+        logger.log(`Detected remote branch scenario, fetching ancestor branches...`);
+        // Configure fetch to get all remote branches
+        await executeWithLog(`git config remote.${remoteName}.fetch "+refs/heads/*:refs/remotes/${remoteName}/*"`, {
+            execOptions,
+            logger,
+        });
+        // Execute appropriate fetch strategy
+        await executeFetchStrategy(isShallow, execOptions, logger);
+        logger.log(`Remote branches fetched successfully for complete ancestor check`);
+    }
+    catch (err) {
+        logger.log('Note: Could not determine if branch is remote, continuing with topology discovery', err);
+    }
+}
+/**
+ * Extracts a list of ancestor branches for the given branch, ordered by most recent commit timestamp.
+ *
+ * Algorithm:
+ * 1. Check if shallow clone and should skip (via APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE)
+ * 2. Ensure remote branches are available (fetch if needed for single-branch/shallow clones)
+ * 3. Use git topology to discover ancestor branches efficiently (O(log N) via --first-parent --simplify-by-decoration)
+ * 4. For each discovered branch, extract the branching timestamp (latest viable commit where branch existed)
+ * 5. Sort results by timestamp descending (most recent first)
+ * 6. Return cached results (5-minute TTL) to avoid redundant git operations
+ *
+ * @param gitBranchName - The branch to analyze
+ * @param execOptions - Git execution options (e.g., cwd)
+ * @param logger - Logger instance for debugging
+ * @returns Array of ancestor branches with timestamps, or undefined if skipped
+ */
+exports.extractBranchLookupFallbackList = utils.general.cachify(async function ({ gitBranchName, execOptions, logger = (0, logger_1.makeLogger)(), enableShallowClone = true, }) {
+    const functionStartTime = Date.now();
+    logger = logger.extend({ tags: [`extract-branch-fallback-list-${utils.general.shortid()}`] });
+    logger.log(`[PERF] extractBranchLookupFallbackList started for branch: ${gitBranchName}`);
+    try {
+        // 1. Check if this is a shallow clone and if we should skip based on env var
+        // add this to control of the user
+        const shallowCheckStartTime = Date.now();
+        const shallowCheckResult = await executeWithLog('git rev-parse --is-shallow-repository', {
+            execOptions,
+            logger,
+        });
+        logger.log(`[PERF] Shallow check took ${Date.now() - shallowCheckStartTime}ms`);
+        const isShallow = shallowCheckResult.stdout.trim() === 'true';
+        if (!enableShallowClone && isShallow) {
+            logger.log('Shallow clone detected and APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE is enabled, skipping branch lookup');
+            return undefined;
+        }
+        // 2. Ensure remote branches are available BEFORE topology discovery
+        // This is necessary for single-branch clones and shallow clones where branches don't exist locally
+        const ensureRemoteStartTime = Date.now();
+        await ensureRemoteBranchesAvailable(gitBranchName, isShallow, execOptions, logger);
+        logger.log(`[PERF] ensureRemoteBranchesAvailable took ${Date.now() - ensureRemoteStartTime}ms`);
+        // 3. OPTIMIZATION: Use git topology to discover only ancestor branches (O(log N) instead of O(N))
+        // Instead of listing all remote branches and checking each one, we walk the git graph
+        // only along the current branch's history using --first-parent and --simplify-by-decoration
+        const topologyStartTime = Date.now();
+        logger.log(`Discovering ancestor branches using git topology for ${gitBranchName}...`);
+        // Get the primary remote name (cached)
+        const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+        const logResult = await executeWithLog(`git log --first-parent --simplify-by-decoration --format="%D" ${gitBranchName}`, { execOptions, logger });
+        const foundBranches = new Set();
+        if (!logResult.stderr && logResult.stdout.trim()) {
+            const rawLines = logResult.stdout.split('\n');
+            for (const line of rawLines) {
+                // Parse refs like: "HEAD -> feat, origin/feat, tag: v1, origin/main"
+                const refs = line.split(',').map(r => r.trim());
+                for (const ref of refs) {
+                    if (ref.includes('tag:'))
+                        continue; // Ignore tags
+                    const cleanRef = ref.replace('HEAD -> ', '').replace(new RegExp(`^${remoteName}/`), ''); // Normalize
+                    if (cleanRef && cleanRef !== gitBranchName && cleanRef !== 'HEAD')
+                        foundBranches.add(cleanRef);
+                }
+            }
+        }
+        let allBranches = Array.from(foundBranches);
+        logger.log(`[PERF] Topology discovery took ${Date.now() - topologyStartTime}ms`);
+        if (isDebugMode()) {
+            logger.log(`Topology discovered ${allBranches.length} potential ancestor branches: ${allBranches.join(', ')}`);
+        }
+        else {
+            logger.log(`Topology discovered ${allBranches.length} potential ancestor branches`);
+        }
+        // 3. Filter out branches that don't exist on remote (if we can determine remote branches)
+        // This prevents unnecessary ancestor checks and fetch attempts for missing branches
+        const remoteBranchesStartTime = Date.now();
+        if (isDebugMode()) {
+            logger.log('[Remote Filtering] ========================================');
+            logger.log('[Remote Filtering] Starting remote branch filtering...');
+            logger.log('[Remote Filtering] Branches to check:', allBranches.join(', '));
+            logger.log('[Remote Filtering] Number of branches before filtering:', allBranches.length);
+        }
+        try {
+            if (isDebugMode()) {
+                logger.log('[Remote Filtering] Calling getAllRemoteBranches...');
+            }
+            const remoteBranches = await getAllRemoteBranches({ execOptions, logger });
+            if (isDebugMode()) {
+                logger.log('[Remote Filtering] getAllRemoteBranches returned');
+                logger.log('[Remote Filtering] Remote branches size:', remoteBranches.size);
+                const remoteBranchList = Array.from(remoteBranches).slice(0, 20);
+                logger.log('[Remote Filtering] Remote branches:', remoteBranchList.join(', ') + (remoteBranches.size > 20 ? ` ... and ${remoteBranches.size - 20} more` : ''));
+            }
+            if (remoteBranches.size > 0) {
+                const beforeFilter = allBranches.length;
+                if (isDebugMode()) {
+                    logger.log('[Remote Filtering] Filtering branches against remote...');
+                    // Log each branch check only in debug mode
+                    allBranches.forEach(branch => {
+                        const exists = remoteBranches.has(branch);
+                        logger.log(`[Remote Filtering] Branch "${branch}": ${exists ? '✓ EXISTS' : '✗ MISSING'} on remote`);
+                    });
+                }
+                allBranches = allBranches.filter(branch => remoteBranches.has(branch));
+                const filtered = beforeFilter - allBranches.length;
+                if (isDebugMode()) {
+                    logger.log('[Remote Filtering] Branches after filtering:', allBranches.join(', '));
+                    logger.log('[Remote Filtering] Number of branches after filtering:', allBranches.length);
+                }
+                if (filtered > 0) {
+                    logger.log(`[Remote Filtering] ✓ Filtered out ${filtered} branches not found on remote`);
+                }
+                else if (isDebugMode()) {
+                    logger.log('[Remote Filtering] No branches were filtered out (all exist on remote)');
+                }
+            }
+            else {
+                logger.log('[Remote Filtering] WARNING: No remote branches found, skipping filter');
+            }
+        }
+        catch (err) {
+            logger.log('[Remote Filtering] ✗ ERROR: Could not filter by remote branches');
+            if (isDebugMode()) {
+                logger.log('[Remote Filtering] Error details:', err);
+                logger.log('[Remote Filtering] Continuing with all discovered branches');
+            }
+        }
+        logger.log(`[Remote Filtering] [PERF] Remote branch filtering took ${Date.now() - remoteBranchesStartTime}ms`);
+        if (isDebugMode()) {
+            logger.log('[Remote Filtering] ========================================');
+        }
+        // 4. Filter out sibling branches - keep only TRUE ancestors
+        // A branch is a true ancestor if it's in the ancestry path of the current branch
+        // Use git merge-base --is-ancestor to check if candidate is an ancestor of current branch
+        const filteringStartTime = Date.now();
+        logger.log(`Filtering out sibling branches to keep only true ancestors...`);
+        // PERFORMANCE: Check ancestors in parallel with concurrency limit to avoid overwhelming git
+        const ANCESTOR_CHECK_CONCURRENCY = 10;
+        const ancestorChecks = await parallelWithLimit(allBranches, ANCESTOR_CHECK_CONCURRENCY, async (candidateBranch) => {
+            try {
+                // Check if candidate branch is an ancestor of current branch
+                // git merge-base --is-ancestor <commit> <commit> exits with status 0 if true, 1 if false
+                const isAncestorResult = await executeWithLog(`git merge-base --is-ancestor ${candidateBranch} ${gitBranchName}`, {
+                    execOptions,
+                    logger,
+                });
+                // Exit code 0 means it's an ancestor, exit code 1 means it's not
+                if (isAncestorResult.code === 0) {
+                    logger.log(`✓ ${candidateBranch} is a true ancestor`);
+                    return { branch: candidateBranch, isAncestor: true };
+                }
+                else if (isAncestorResult.code === 1) {
+                    logger.log(`✗ ${candidateBranch} is a sibling, not an ancestor`);
+                    return { branch: candidateBranch, isAncestor: false };
+                }
+                else {
+                    logger.log(`⚠ Could not determine if ${candidateBranch} is an ancestor (exit code: ${isAncestorResult.code}), including it to be safe`);
+                    return { branch: candidateBranch, isAncestor: true };
+                }
+            }
+            catch (err) {
+                logger.log(`Error checking if ${candidateBranch} is a true ancestor:`, err);
+                // If we can't determine, include it to be safe (better to have false positives than miss ancestors)
+                return { branch: candidateBranch, isAncestor: true };
+            }
+        });
+        const trueAncestors = ancestorChecks.filter(result => result.isAncestor).map(result => result.branch);
+        logger.log(`[PERF] Sibling filtering took ${Date.now() - filteringStartTime}ms`);
+        logger.log(`Filtered to ${trueAncestors.length} true ancestors: ${trueAncestors.join(', ')}`);
+        // 5. For each true ancestor branch, calculate the branching timestamp
+        const timestampStartTime = Date.now();
+        const branchesWithTimestamps = await Promise.all(trueAncestors.map(async (ancestorBranch) => {
+            const timestamp = await (0, exports.extractBranchingTimestamp)({
+                branchName: gitBranchName,
+                parentBranchName: ancestorBranch,
+                execOptions,
+                logger,
+            });
+            return timestamp ? { branchName: ancestorBranch, latestViableTimestamp: timestamp } : null;
+        }));
+        logger.log(`[PERF] Timestamp extraction took ${Date.now() - timestampStartTime}ms`);
+        // 6. Filter out null results and sort by timestamp (most recent first), then by branch name
+        const validBranches = branchesWithTimestamps
+            .filter((item) => item !== null)
+            .sort((a, b) => {
+            // Sort descending by timestamp (newest first)
+            const timeDiff = new Date(b.latestViableTimestamp).getTime() - new Date(a.latestViableTimestamp).getTime();
+            // If timestamps are equal, sort alphabetically by branch name
+            if (timeDiff === 0) {
+                return a.branchName.localeCompare(b.branchName);
+            }
+            return timeDiff;
+        });
+        // 7. Root branch fallback (safety net if no branches were found)
+        // The root branch is the branch that contains the first commit in the repository
+        try {
+            // Find the first commit (root commit)
+            const firstCommitResult = await executeWithLog('git rev-list --max-parents=0 HEAD', {
+                execOptions,
+                logger,
+            });
+            if (firstCommitResult.stdout.trim()) {
+                const firstCommitHash = firstCommitResult.stdout.trim().split('\n')[0];
+                logger.log(`Found root commit: ${firstCommitHash}`);
+                // Find which branches contain this root commit
+                // Try remote branches first, then fall back to local branches
+                let branchesContainingRootResult = await executeWithLog(`git branch -r --contains ${firstCommitHash}`, {
+                    execOptions,
+                    logger,
+                });
+                // If no remote branches found, try local branches
+                if (!branchesContainingRootResult.stdout.trim()) {
+                    logger.log('No remote branches contain root commit, trying local branches');
+                    branchesContainingRootResult = await executeWithLog(`git branch --contains ${firstCommitHash}`, {
+                        execOptions,
+                        logger,
+                    });
+                }
+                if (branchesContainingRootResult.stdout.trim()) {
+                    const branchesContainingRoot = branchesContainingRootResult.stdout
+                        .split('\n')
+                        .map(line => line.trim())
+                        .filter(line => line && !line.includes('->') && !line.includes('HEAD'))
+                        .map(line => line.replace(new RegExp(`^${remoteName}/`), '').replace(/^\* /, '')); // Remove remote prefix and '* ' prefix
+                    // Try common root branch names first: main, master, develop
+                    const commonRootNames = ['main', 'master', 'develop', 'trunk'];
+                    let rootBranch = null;
+                    for (const commonName of commonRootNames) {
+                        if (branchesContainingRoot.includes(commonName)) {
+                            rootBranch = commonName;
+                            logger.log(`Found root branch using common name: ${rootBranch}`);
+                            break;
+                        }
+                    }
+                    // If no common name found, use the oldest branch (most likely the root)
+                    if (!rootBranch && branchesContainingRoot.length > 0) {
+                        // Find the branch with the oldest creation timestamp among those containing root commit
+                        const branchTimestamps = await Promise.all(branchesContainingRoot.slice(0, 10).map(async (branch) => {
+                            try {
+                                const branchTimestampResult = await executeWithLog(`git log -1 --format=%aI ${branch}`, {
+                                    execOptions,
+                                    logger,
+                                });
+                                return {
+                                    branch,
+                                    timestamp: branchTimestampResult.stdout.trim(),
+                                };
+                            }
+                            catch {
+                                return null;
+                            }
+                        }));
+                        const validTimestamps = branchTimestamps
+                            .filter((item) => item !== null && isISODate(item.timestamp))
+                            .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+                        if (validTimestamps.length > 0) {
+                            rootBranch = validTimestamps[0].branch;
+                            logger.log(`Found root branch by oldest timestamp: ${rootBranch}`);
+                        }
+                    }
+                    // Add root branch if found and not already in the list
+                    if (rootBranch && rootBranch !== gitBranchName) {
+                        const alreadyIncluded = validBranches.some(b => b.branchName === rootBranch);
+                        if (!alreadyIncluded) {
+                            // Verify that root branch is actually an ancestor before adding it
+                            // This prevents adding sibling branches that happen to contain the root commit
+                            try {
+                                const isAncestorResult = await executeWithLog(`git merge-base --is-ancestor ${rootBranch} ${gitBranchName}`, {
+                                    execOptions,
+                                    logger,
+                                });
+                                if (isAncestorResult.code === 0) {
+                                    logger.log(`Root branch ${rootBranch} is a true ancestor, adding it as final fallback`);
+                                    // Get the timestamp of the root commit (merge-base between current branch and root branch)
+                                    const rootTimestamp = await (0, exports.extractBranchingTimestamp)({
+                                        branchName: gitBranchName,
+                                        parentBranchName: rootBranch,
+                                        execOptions,
+                                        logger,
+                                    });
+                                    if (rootTimestamp) {
+                                        validBranches.push({
+                                            branchName: rootBranch,
+                                            latestViableTimestamp: rootTimestamp,
+                                        });
+                                        logger.log(`Added root branch ${rootBranch} with timestamp ${rootTimestamp}`);
+                                    }
+                                }
+                                else {
+                                    logger.log(`Root branch ${rootBranch} is not an ancestor of ${gitBranchName}, skipping`);
+                                }
+                            }
+                            catch (err) {
+                                logger.log(`Error checking if root branch ${rootBranch} is an ancestor:`, err);
+                                // If we can't determine, don't add it (better to be conservative)
+                            }
+                        }
+                        else {
+                            logger.log(`Root branch ${rootBranch} already included in the list`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            logger.log('Failed to detect and add root branch, continuing without it', err);
+        }
+        logger.log(`[PERF] extractBranchLookupFallbackList completed in ${Date.now() - functionStartTime}ms total`);
+        logger.log('Successfully extracted branch lookup fallback list', JSON.stringify(validBranches));
+        return validBranches.length > 0 ? validBranches : undefined;
+    }
+    catch (err) {
+        logger.log('Error during extracting branch lookup fallback list', err);
+        return undefined;
+    }
+}, args => {
+    var _a;
+    return ({
+        gitBranchName: args[0].gitBranchName,
+        cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd,
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/core",
-  "version": "4.53.1",
+  "version": "4.54.0",
   "homepage": "https://applitools.com",
   "bugs": {
     "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
@@ -51,12 +51,13 @@
     "build:bin": "yarn build && sea",
     "build:bin:zip": "zip -j ./bin/core.zip $(find ./bin -type f -not -name '*.zip' -not -name '*.tar.gz' | xargs)",
     "build:bin:tgz": "tar -czf ./bin/core.tar.gz $(find ./bin -type f -not -name '*.zip' -not -name '*.tar.gz' | xargs)",
-    "test": "run --top-level mocha './test/**/*.spec.ts' --exclude './test/bin/**' --parallel --jobs ${MOCHA_JOBS:-15} --exit --require ./test/mocha-global-setup.js",
+    "test": "run --top-level mocha './test/**/*.spec.ts' --exclude './test/bin/**' --exclude './test/e2e/mocha-sync/**' --parallel --jobs ${MOCHA_JOBS:-15} --exit --require ./test/mocha-global-setup.js",
     "test:local": "MOCHA_OMIT_TAGS=sauce,browserstack run test",
     "test:sauce": "MOCHA_ONLY_TAGS=sauce,browserstack run test",
     "test:bin": "MOCHA_GROUP=bin run --top-level mocha './test/bin/**/*.spec.ts' --parallel --jobs ${MOCHA_JOBS:-15} --require ./test/mocha-global-setup.js",
-    "test:e2e": "MOCHA_GROUP=e2e run --top-level mocha './test/e2e/**/*.spec.ts' --parallel --jobs ${MOCHA_JOBS:-15} --exit --require ./test/mocha-global-setup.js",
+    "test:e2e": "MOCHA_GROUP=e2e run --top-level mocha './test/e2e/**/*.spec.ts' --exclude './test/e2e/mocha-sync/**' --parallel --jobs ${MOCHA_JOBS:-15} --exit --require ./test/mocha-global-setup.js",
     "test:it": "MOCHA_GROUP=it run --top-level mocha './test/it/**/*.spec.ts' --require ./test/mocha-global-setup.js",
+    "test:e2e:sync": "MOCHA_GROUP=e2e SYNC=true run --top-level mocha './test/e2e/mocha-sync/**/*.spec.ts' --exit --require ./test/mocha-global-setup.js",
     "test:unit": "MOCHA_GROUP=unit run --top-level mocha './test/unit/**/*.spec.ts' --require ./test/mocha-global-setup.js",
     "setup": "run --top-level browsers:setup && run --top-level xvfb:setup",
     "setup:standalone": "sh -c 'yarn chromedriver --port=4444 --verbose &'"
@@ -79,13 +80,13 @@
     }
   },
   "dependencies": {
-    "@applitools/core-base": "1.30.1",
+    "@applitools/core-base": "1.31.0",
     "@applitools/dom-capture": "11.6.7",
-    "@applitools/dom-snapshot": "4.15.2",
+    "@applitools/dom-snapshot": "4.15.3",
     "@applitools/driver": "1.24.3",
-    "@applitools/ec-client": "1.12.14",
+    "@applitools/ec-client": "1.12.15",
     "@applitools/logger": "2.2.7",
-    "@applitools/nml-client": "1.11.12",
+    "@applitools/nml-client": "1.11.13",
     "@applitools/req": "1.8.7",
     "@applitools/screenshoter": "3.12.10",
     "@applitools/snippets": "2.7.0",

package/types/utils/extract-git-info.d.ts

@@ -4,6 +4,7 @@ import { type Logger } from '@applitools/logger';
 type Options = {
     execOptions?: ExecOptions;
     logger: Logger;
+    ignoreGitBranching?: boolean;
 };
 type ExtractGitBranchingTimestampOptions = {
     branchName: string;
@@ -16,6 +17,19 @@ type ExtractCurrentCommitTimestampOptions = {
     logger?: Logger;
 };
 export declare const cacheKey = "default";
+/**
+ * Get the primary remote name (cached for performance)
+ * Prefers 'origin' if it exists, otherwise uses the first available remote
+ */
+export declare const getPrimaryRemoteName: (({ execOptions, logger }: {
+    execOptions?: ExecOptions | undefined;
+    logger?: Logger | undefined;
+}) => Promise<string>) & {
+    getCachedValues(): Promise<string>[];
+    setCachedValue(key: any, value: Promise<string>): void;
+    clearCache(): void;
+    TTL?: number | undefined;
+};
 export declare const extractLatestCommitInfo: (({ execOptions, logger, }: ExtractCurrentCommitTimestampOptions) => Promise<{
     timestamp: string;
     sha: string;
@@ -60,4 +74,40 @@ export declare const extractBranchingTimestamp: (({ branchName, parentBranchName
     TTL?: number | undefined;
 };
 export declare function isISODate(str: string): boolean;
+/**
+ * Extracts a list of ancestor branches for the given branch, ordered by most recent commit timestamp.
+ *
+ * Algorithm:
+ * 1. Check if shallow clone and should skip (via APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE)
+ * 2. Ensure remote branches are available (fetch if needed for single-branch/shallow clones)
+ * 3. Use git topology to discover ancestor branches efficiently (O(log N) via --first-parent --simplify-by-decoration)
+ * 4. For each discovered branch, extract the branching timestamp (latest viable commit where branch existed)
+ * 5. Sort results by timestamp descending (most recent first)
+ * 6. Return cached results (5-minute TTL) to avoid redundant git operations
+ *
+ * @param gitBranchName - The branch to analyze
+ * @param execOptions - Git execution options (e.g., cwd)
+ * @param logger - Logger instance for debugging
+ * @returns Array of ancestor branches with timestamps, or undefined if skipped
+ */
+export declare const extractBranchLookupFallbackList: (({ gitBranchName, execOptions, logger, enableShallowClone, }: {
+    gitBranchName: string;
+    execOptions?: ExecOptions | undefined;
+    logger?: Logger | undefined;
+    enableShallowClone: boolean;
+}) => Promise<Array<{
+    branchName: string;
+    latestViableTimestamp: string;
+}> | undefined>) & {
+    getCachedValues(): Promise<{
+        branchName: string;
+        latestViableTimestamp: string;
+    }[] | undefined>[];
+    setCachedValue(key: any, value: Promise<{
+        branchName: string;
+        latestViableTimestamp: string;
+    }[] | undefined>): void;
+    clearCache(): void;
+    TTL?: number | undefined;
+};
 export {};