@applitools/core 4.61.0 → 4.61.1-debug.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/core",
-  "version": "4.61.0",
+  "version": "4.61.1-debug.0",
   "homepage": "https://applitools.com",
   "bugs": {
     "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
@@ -56,20 +56,21 @@
     "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": "run --top-level browsers:setup && run --top-level xvfb:setup && run playwright:setup",
+    "playwright:setup": "node -e \"var v=parseInt(process.version.slice(1));if(v>=18){require('child_process').execSync('yarn playwright install --with-deps firefox',{stdio:'inherit'})}else{console.log('Skipping playwright install (Node '+process.version+')')}\"",
     "setup:standalone": "sh -c 'yarn chromedriver --port=4444 --verbose &'"
   },
   "dependencies": {
     "@applitools/core-base": "1.33.0",
-    "@applitools/dom-capture": "11.7.1",
-    "@applitools/dom-snapshot": "4.16.4",
-    "@applitools/driver": "1.25.5",
-    "@applitools/ec-client": "1.12.26",
+    "@applitools/dom-capture": "11.8.0",
+    "@applitools/dom-snapshot": "4.17.0",
+    "@applitools/driver": "1.26.0",
+    "@applitools/ec-client": "1.12.28",
     "@applitools/logger": "2.2.11",
-    "@applitools/nml-client": "1.11.25",
+    "@applitools/nml-client": "1.11.26",
     "@applitools/req": "1.10.0",
-    "@applitools/screenshoter": "3.12.18",
-    "@applitools/snippets": "2.8.2",
+    "@applitools/screenshoter": "3.12.19",
+    "@applitools/snippets": "2.9.0",
     "@applitools/socket": "1.3.12",
     "@applitools/ufg-client": "1.22.0",
     "@applitools/utils": "1.14.4",
@@ -81,11 +82,12 @@
   },
   "devDependencies": {
     "@applitools/bongo": "^5.10.0",
-    "@applitools/spec-driver-puppeteer": "^1.7.5",
-    "@applitools/spec-driver-selenium": "^1.7.16",
+    "@applitools/spec-driver-playwright": "^1.9.0",
+    "@applitools/spec-driver-puppeteer": "^1.8.0",
+    "@applitools/spec-driver-selenium": "^1.8.0",
     "@applitools/test-server": "^1.4.3",
     "@applitools/test-utils": "^1.5.17",
-    "@applitools/tunnel-client": "^1.11.11",
+    "@applitools/tunnel-client": "^1.11.12",
     "@types/mocha": "^10.0.7",
     "@types/node": "^12.20.55",
     "@types/selenium-webdriver": "^4.1.2",
@@ -93,6 +95,7 @@
     "chromedriver": "^131.0.5",
     "crypto": "^1.0.1",
     "nock": "^13.3.2",
+    "playwright": "1.47.0",
     "png-async": "^0.9.4",
     "puppeteer": "^24.11.1",
     "selenium-webdriver": "^4.15.0"

package/types/automation/types.d.ts

@@ -179,4 +179,5 @@ export type TestResult = BaseCore.TestResult & {
 export type OpenSettings = BaseCore.OpenSettings & {
     disableBrokerUrlCache?: boolean;
     environments?: Environment[];
+    bypassCSP?: boolean;
 };

package/types/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/universal/core-server-process.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="node" />
+import { type Options } from './core-server';
+import { type ForkOptions } from 'child_process';
+export declare function makeCoreServerProcess(options: Options & {
+    forkOptions?: ForkOptions;
+}): Promise<{
+    port: number;
+    close: () => void;
+}>;

package/types/universal/core-server.d.ts

@@ -0,0 +1,18 @@
+import { type ServerOptions } from './ws-server';
+import { type Logger } from '@applitools/logger';
+export type Options = ServerOptions & {
+    environment?: Record<string, any>;
+    agentIdPrefix?: string;
+    debug?: boolean;
+    shutdownMode?: 'lazy' | 'stdin';
+    idleTimeout?: number;
+    printStdout?: boolean;
+    isProcess?: boolean;
+    maskLog?: boolean;
+    logger?: Logger;
+};
+export declare function makeCoreServer({ environment: defaultEnvironment, agentIdPrefix, debug, shutdownMode, idleTimeout, // 15min
+printStdout, isProcess, maskLog, logger, ...handlerOptions }?: Options): Promise<{
+    port: number;
+    close?: () => void;
+}>;

package/types/universal/history.d.ts

@@ -0,0 +1,2 @@
+import { type Socket } from '@applitools/socket';
+export declare function withHistory<TSocket extends Socket>(socket: TSocket): () => Record<string, any>;

package/types/universal/refer.d.ts

@@ -0,0 +1,8 @@
+import type { Ref } from './types';
+export interface Refer {
+    isRef<TValue = any>(ref: any): ref is Ref<TValue>;
+    ref<TValue>(value: TValue, parentRef?: Ref<unknown>): Ref<TValue>;
+    deref<TValue>(ref: Ref<TValue>): TValue;
+    destroy(ref: Ref<any>): void;
+}
+export declare function makeRefer(): Refer;

package/types/universal/spec-driver.d.ts

@@ -0,0 +1,15 @@
+import type { Ref, ServerSocket, UniversalSpecDriver } from './types';
+import type { SpecType, SpecDriver as BaseSpecDriver, CommonSelector } from '@applitools/driver';
+export type Driver = Ref;
+export type Context = Ref;
+export type Element = Ref;
+export type Selector = string | CommonSelector | Ref;
+export type UserFunction = Ref;
+export type PrimarySpecType = SpecType<Driver, Context, Element, Selector, never, UserFunction>;
+export type SpecDriver = BaseSpecDriver<PrimarySpecType>;
+type CommandName = keyof UniversalSpecDriver<PrimarySpecType>;
+export declare function makeSpec({ socket, spec, }: {
+    socket: ServerSocket<PrimarySpecType, any>;
+    spec: CommandName[];
+}): SpecDriver;
+export {};

package/types/universal/types.d.ts

@@ -0,0 +1,205 @@
+import type { Size, Region } from '@applitools/utils';
+import type { Emitter, Listener, Client, Server } from '@applitools/socket';
+import type { SpecType, DriverInfo, Cookie, WaitOptions } from '@applitools/driver';
+import type * as MainCore from '../types';
+/**
+ * Wraps the type with a ref if it vas to be refed
+ */
+type Refify<TValue> = TValue extends string | number | boolean | null | undefined ? TValue : TValue extends Array<infer TItem> ? Refify<TItem>[] : Extract<TValue[keyof TValue], (...args: any) => any> extends never ? TValue : Ref<TValue>;
+/**
+ * Creates universalized object out of an ordinary interface:
+ * - Filters out properties that are not of async function type
+ * - Adds domain to the method names (`Domain.methodName`)
+ * - Keep only first (`options`) argument of the methods
+ * - Introduces additional option to the methods with a ref of the current instance
+ * - Refifies return values of the methods
+ */
+type Universalize<TTarget extends Record<string, any>, TDomain extends string, TRefKey extends string = never> = {
+    [TKey in keyof TTarget as NonNullable<TTarget[TKey]> extends (...args: any[]) => Promise<any> ? `${TDomain}.${TKey & string}` : never]: NonNullable<TTarget[TKey]> extends (options: infer TOptions) => Promise<infer TResult> ? (options: TOptions & {
+        [TKey in TRefKey]: Ref<TTarget>;
+    }) => Promise<Refify<TResult>> : never;
+};
+export type Ref<TValue = never> = {
+    'applitools-ref-id': string;
+    type?: string;
+};
+export type ClientSocket<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = unknown & Emitter<Universalize<UniversalCore<TSpec, TType>, 'Core'>> & Client<Universalize<MainCore.Core<TSpec, TType>, 'Core'>> & Client<Universalize<MainCore.EyesManager<TSpec, TType>, 'EyesManager', 'manager'>> & Client<Universalize<MainCore.Eyes<TSpec, TType>, 'Eyes', 'eyes'>> & Client<Universalize<UniversalDebug<TSpec>, 'Debug'>> & Server<Universalize<UniversalSpecDriver<TSpec>, 'Driver'>>;
+export type ServerSocket<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = unknown & Listener<Universalize<UniversalCore<TSpec, TType>, 'Core'>> & Emitter<Universalize<UniversalLogger, 'Logger'>> & Server<Universalize<MainCore.Core<TSpec, TType>, 'Core'>> & Server<Universalize<MainCore.EyesManager<TSpec, TType>, 'EyesManager', 'manager'>> & Server<Universalize<MainCore.Eyes<TSpec, TType>, 'Eyes', 'eyes'>> & Server<Universalize<UniversalDebug<TSpec>, 'Debug'>> & Client<Universalize<UniversalSpecDriver<TSpec>, 'Driver'>>;
+export interface UniversalCore<TSpec extends SpecType, TType extends 'classic' | 'ufg'> {
+    makeCore(options: {
+        spec: 'webdriver' | (keyof UniversalSpecDriver<TSpec>)[];
+        agentId: string;
+        environment?: Record<string, any>;
+        cwd: string;
+    }): Promise<MainCore.Core<TSpec, TType>>;
+}
+export interface UniversalLogger {
+    log(options: {
+        level: string;
+        message: string;
+    }): Promise<void>;
+}
+export interface UniversalDebug<TSpec extends SpecType> {
+    getHistory(): Promise<any>;
+    checkSpecDriver(options: {
+        driver: TSpec['driver'];
+        commands: (keyof UniversalSpecDriver<TSpec>)[];
+    }): Promise<any>;
+}
+/**
+ * Ideally would be transform SpecDriver type to the type with single object argument
+ * but typescript doesn't have a possibility to convert named tuples to object types at the moment
+ */
+export interface UniversalSpecDriver<T extends SpecType> {
+    isEqualElements(options: {
+        context: T['context'];
+        element1: T['element'];
+        element2: T['element'];
+    }): Promise<boolean>;
+    executeScript(options: {
+        context: T['context'];
+        script: string;
+        arg?: any;
+    }): Promise<any>;
+    findElement(options: {
+        context: T['context'];
+        selector: T['selector'];
+        parent?: T['element'];
+    }): Promise<T['element'] | null>;
+    findElements(options: {
+        context: T['context'];
+        selector: T['selector'];
+        parent?: T['element'];
+    }): Promise<T['element'][]>;
+    waitForSelector(options: {
+        context: T['context'];
+        selector: T['selector'];
+        parent?: T['element'];
+        options?: WaitOptions;
+    }): Promise<T['element'] | null>;
+    getElementRegion(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<Region>;
+    getElementAttribute(options: {
+        context: T['context'];
+        element: T['element'];
+        attr: string;
+    }): Promise<string>;
+    setElementText(options: {
+        context: T['context'];
+        element: T['element'];
+        text: string;
+    }): Promise<void>;
+    getElementText(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<string>;
+    hover(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<void>;
+    click(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<void>;
+    mainContext(options: {
+        context: T['context'];
+    }): Promise<T['context']>;
+    parentContext(options: {
+        context: T['context'];
+    }): Promise<T['context']>;
+    childContext(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<T['context']>;
+    getDriverInfo(options: {
+        driver: T['driver'];
+    }): Promise<DriverInfo>;
+    getCapabilities(options: {
+        driver: T['driver'];
+    }): Promise<Record<string, any>>;
+    setWindowSize(options: {
+        driver: T['driver'];
+        size: Size;
+    }): Promise<void>;
+    getWindowSize(options: {
+        driver: T['driver'];
+    }): Promise<Size>;
+    setViewportSize(options: {
+        driver: T['driver'];
+        size: Size;
+    }): Promise<void>;
+    getViewportSize(options: {
+        driver: T['driver'];
+    }): Promise<Size>;
+    getSystemBars(options: {
+        driver: T['driver'];
+    }): Promise<{
+        statusBar: {
+            visible: boolean;
+            x: number;
+            y: number;
+            height: number;
+            width: number;
+        };
+        navigationBar: {
+            visible: boolean;
+            x: number;
+            y: number;
+            height: number;
+            width: number;
+        };
+    }>;
+    getOrientation(options: {
+        driver: T['driver'];
+    }): Promise<'portrait' | 'landscape' | 'portrait-secondary' | 'landscape-secondary'>;
+    setOrientation(options: {
+        driver: T['driver'];
+        orientation: 'portrait' | 'landscape' | 'portrait-secondary' | 'landscape-secondary';
+    }): Promise<void>;
+    getCookies(options: {
+        driver: T['driver'] | T['context'];
+        context?: boolean;
+    }): Promise<Cookie[]>;
+    getTitle(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    getUrl(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    takeScreenshot(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    performAction(options: {
+        driver: T['driver'];
+        steps: any[];
+    }): Promise<void>;
+    visit(options: {
+        driver: T['driver'];
+        url: string;
+    }): Promise<void>;
+    getCurrentWorld(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    getWorlds(options: {
+        driver: T['driver'];
+    }): Promise<string[]>;
+    switchWorld(options: {
+        driver: T['driver'];
+        name: string;
+    }): Promise<void>;
+    reload(options: {
+        driver: T['driver'];
+    }): Promise<void>;
+    isUserFunction(ref: any): Promise<boolean>;
+    executeUserFunction(userFunction: Ref): Promise<any>;
+    executeBrowserCommands(options: {
+        driver?: T['driver'];
+        commands: any[];
+    }): Promise<any>;
+    bringToFront(options: {
+        driver: T['driver'];
+    }): Promise<void>;
+}
+export {};

package/types/universal/ws-server.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+import { Server as WsServer } from 'ws';
+import { Logger } from '@applitools/logger';
+export type ServerOptions = {
+    port?: number;
+    singleton?: boolean;
+    portResolutionMode?: 'next' | 'random' | 'lazy';
+    debug?: boolean;
+    key?: string | Buffer;
+    cert?: string | Buffer;
+};
+export declare function makeServer(options: ServerOptions | undefined, logger: Logger): Promise<{
+    server?: WsServer;
+    port: number;
+}>;

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

@@ -30,6 +30,81 @@ export declare const getPrimaryRemoteName: (({ execOptions, logger }: {
     clearCache(): void;
     TTL?: number | undefined;
 };
+export type GitEnvironmentResult = {
+    /** `git` binary is on PATH and executable. */
+    gitInstalled: boolean;
+    /** Current working directory is inside a git work tree. */
+    insideRepo: boolean;
+    /** A primary remote is configured AND reachable. */
+    remoteAccessible: boolean;
+    /**
+     * `gitInstalled && insideRepo` — sufficient for local-only git operations
+     * (commit lookups, local branch detection, local merge-base). Does NOT
+     * imply remote ops will succeed — callers that need the remote must
+     * additionally check `remoteAccessible`.
+     */
+    ok: boolean;
+    /** Human-readable explanation covering every sub-check; used in skip-logs. */
+    reason: string;
+    /** Resolved primary remote name, when one is configured. */
+    remoteName?: string;
+};
+/**
+ * One-shot, cached probe of the full git environment, staged from cheapest
+ * to most expensive:
+ *   1. is `git` installed and on PATH?                       (`git --version`)
+ *   2. are we inside a git work tree?     (`git rev-parse --is-inside-work-tree`)
+ *   3. is a primary remote configured?                       (`git remote`)
+ *   4. is that remote reachable?                       (`git ls-remote <r> HEAD`)
+ *
+ * Use this as the outermost guard for any code path that shells out to git.
+ * Each step short-circuits later ones: missing binary skips repo/remote
+ * checks; non-repo skips remote checks; no remote configured skips the
+ * reachability probe. Callers should consult `ok` for local-only git
+ * features and `remoteAccessible` for anything that talks to the network.
+ *
+ * Cached per `cwd`. The first invocation emits a clearly-visible banner so
+ * support can grep one distinctive line — `APPLITOOLS GIT ENVIRONMENT CHECK`
+ * — and immediately tell which sub-check failed. Subsequent invocations
+ * return the cached verdict silently.
+ */
+export declare const checkGitEnvironment: (({ execOptions, logger, }: {
+    execOptions?: ExecOptions | undefined;
+    logger?: Logger | undefined;
+}) => Promise<GitEnvironmentResult>) & {
+    getCachedValues(): Promise<GitEnvironmentResult>[];
+    setCachedValue(key: any, value: Promise<GitEnvironmentResult>): void;
+    clearCache(): void;
+    TTL?: number | undefined;
+};
+/**
+ * Programmatically detect the default branch of the current repository.
+ *
+ * Fallback chain (each step short-circuits on success; never throws):
+ *   1. `APPLITOOLS_DEFAULT_BRANCH` env var — explicit user override.
+ *   2. `git symbolic-ref --short refs/remotes/<remote>/HEAD` — authoritative
+ *      source on any clone that has fetched at least once. Returns e.g.
+ *      `origin/master`; the `<remote>/` prefix is stripped.
+ *   3. `git ls-remote --symref <remote> HEAD` — works even when the local
+ *      `refs/remotes/<remote>/HEAD` symref was never set up (single-branch
+ *      clones, older git on CI).
+ *   4. `git config --get init.defaultBranch` — honors a user-global preference
+ *      if everything else fails.
+ *   5. Literal `'main'` — last resort.
+ *
+ * Steps 2 and 3 catch non-standard defaults (e.g. JFrog's
+ * `JFROG/artifactory-mfe/preRelease/jfmfe-1.995.x-rc`). Cached per `cwd`
+ * to match `getPrimaryRemoteName`.
+ */
+export declare const extractDefaultBranch: (({ 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;
@@ -68,6 +143,31 @@ export declare const extractGitRepo: (({ execOptions, logger }: Options) => Prom
 };
 export declare function extractCIBranchName(): string | undefined;
 export declare function extractBuildIdFromCI(): Promise<string | undefined>;
+/**
+ * Extract the ISO-8601 timestamp at which `branchName` branched off from
+ * `parentBranchName`.
+ *
+ * Algorithm (each step short-circuits on success; returns `undefined` on
+ * total failure — never throws):
+ *   1. If the repo is a shallow clone, unshallow (or treeless-fetch) so the
+ *      branch topology is visible to `git merge-base`.
+ *   2. `git merge-base <remote>/<branch> <remote>/<parent>` — CI typically
+ *      operates on remote refs only, so try those first.
+ *   3. Fall back to local refs (`git merge-base <branch> <parent>`).
+ *   4. If still no merge-base, see if the parent exists on the remote and,
+ *      if so, fetch it by name (`--filter=tree:0`) and retry. If the parent
+ *      isn't on the remote at all, give up — we can't compute a branching
+ *      point for a branch that doesn't exist anywhere.
+ *   5. Direct-ancestor refinement: if the merge-base equals the parent
+ *      branch's tip, the parent hasn't diverged from `branchName` yet
+ *      (parent is a strict ancestor). The "branching point" is then the
+ *      parent commit of the first child-only commit — not the merge-base
+ *      itself, which would be the parent's tip and produce a too-recent
+ *      timestamp.
+ *   6. Resolve the final hash's committer-date via `git show -s --format=%aI`.
+ *
+ * Cached per (branchName, parentBranchName, cwd).
+ */
 export declare const extractBranchingTimestamp: (({ branchName, parentBranchName, execOptions, logger, }: ExtractGitBranchingTimestampOptions) => Promise<string | undefined>) & {
     getCachedValues(): Promise<string | undefined>[];
     setCachedValue(key: any, value: Promise<string | undefined>): void;
@@ -75,16 +175,56 @@ export declare const extractBranchingTimestamp: (({ branchName, parentBranchName
     TTL?: number | undefined;
 };
 export declare function isISODate(str: string): boolean;
+type BranchAncestryOptions = {
+    gitBranchName: string;
+    defaultBranch: string;
+    execOptions?: ExecOptions;
+    logger?: Logger;
+};
+/**
+ * Enumerate ancestor branches in the window MERGE_BASE..gitBranchName by
+ * walking the commits in that window and asking which branches contain each.
+ *
+ * Mirrors the reference shell algorithm in
+ * `.team-lead/scripts-byCommits.sh`. Returns a sorted, deduplicated list
+ * of branch names (no `refs/` prefix). Never throws — returns `[]` on git
+ * failure. Always includes `defaultBranch` and `gitBranchName`.
+ */
+export declare function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOptions, logger, }: BranchAncestryOptions): Promise<string[]>;
+/**
+ * Enumerate ancestor branches by iterating every branch ref and applying
+ * Rule 1 (the candidate's merge-base with HEAD must not lie before the
+ * primary MERGE_BASE) and Rule 2 (HEAD must not be an ancestor of the
+ * candidate).
+ *
+ * Mirrors the reference shell algorithm in
+ * `.team-lead/scripts-byLocalBranches.sh`, with one deliberate extension:
+ * the shell script reads `refs/heads/` only, but in CI we typically have
+ * exactly one local branch checked out and dozens of remote refs. To make
+ * this method useful in CI we ALSO walk `refs/remotes/<remote>/` and strip
+ * the remote prefix. The function name is preserved for fidelity to the
+ * reference algorithm.
+ *
+ * Returns a sorted, deduplicated list of branch names. Never throws —
+ * returns `[]` on git failure. Always includes `defaultBranch` and
+ * `gitBranchName`.
+ */
+export declare function getBranchAncestryByLocalBranches({ gitBranchName, defaultBranch, execOptions, logger, }: BranchAncestryOptions): Promise<string[]>;
 /**
  * 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
+ * 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. Detect the repo's actual default branch via `extractDefaultBranch()` (handles non-standard
+ *    defaults like JFrog's `JFROG/.../...-rc`).
+ * 4. Discover ancestor branches using the strategy selected by
+ *    `APPLITOOLS_BRANCH_ANCESTRY_STRATEGY` (`commits` (default) or `local`):
+ *      - `getBranchAncestryByCommits` walks the MERGE_BASE..HEAD commit window;
+ *      - `getBranchAncestryByLocalBranches` iterates `refs/heads/` + `refs/remotes/<remote>/`.
+ * 5. For each discovered branch, extract the branching timestamp.
+ * 6. Sort results by timestamp descending (most recent first), tie-break by branch name.
+ * 7. Root-branch safety net: if nothing survived, fall back to the detected default branch.
  *
  * @param gitBranchName - The branch to analyze
  * @param execOptions - Git execution options (e.g., cwd)