@applitools/core 4.65.2 → 4.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/core",
-  "version": "4.65.2",
+  "version": "4.66.0",
   "homepage": "https://applitools.com",
   "bugs": {
     "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
@@ -61,39 +61,41 @@
     "setup:standalone": "sh -c 'yarn chromedriver --port=4444 --verbose &'"
   },
   "dependencies": {
-    "@applitools/core-base": "1.35.3",
-    "@applitools/dom-capture": "11.8.2",
-    "@applitools/dom-snapshot": "4.17.4",
-    "@applitools/driver": "1.26.4",
-    "@applitools/ec-client": "1.12.35",
-    "@applitools/logger": "2.2.13",
-    "@applitools/nml-client": "1.11.33",
-    "@applitools/req": "1.11.1",
-    "@applitools/screenshoter": "3.12.23",
+    "@applitools/core-base": "1.36.0",
+    "@applitools/dom-capture": "11.8.3",
+    "@applitools/dom-snapshot": "4.17.5",
+    "@applitools/driver": "1.26.5",
+    "@applitools/ec-client": "1.12.36",
+    "@applitools/logger": "2.3.0",
+    "@applitools/nml-client": "1.11.34",
+    "@applitools/req": "1.11.2",
+    "@applitools/screenshoter": "3.12.24",
     "@applitools/snippets": "2.9.3",
-    "@applitools/socket": "1.3.14",
-    "@applitools/ufg-client": "1.22.4",
-    "@applitools/utils": "1.15.0",
+    "@applitools/socket": "1.3.15",
+    "@applitools/ufg-client": "1.22.5",
+    "@applitools/utils": "1.15.1",
     "abort-controller": "3.0.0",
     "chalk": "4.1.2",
     "node-fetch": "2.6.7",
     "semver": "7.6.2",
+    "shell-quote": "^1.8.4",
     "throat": "6.0.2"
   },
   "devDependencies": {
     "@applitools/bongo": "^5.10.0",
-    "@applitools/spec-driver-playwright": "^1.9.4",
-    "@applitools/spec-driver-puppeteer": "^1.8.4",
-    "@applitools/spec-driver-selenium": "^1.8.4",
-    "@applitools/spec-driver-webdriver": "^1.6.4",
-    "@applitools/test-server": "^1.4.5",
+    "@applitools/spec-driver-playwright": "^1.9.5",
+    "@applitools/spec-driver-puppeteer": "^1.8.5",
+    "@applitools/spec-driver-selenium": "^1.8.5",
+    "@applitools/spec-driver-webdriver": "^1.6.5",
+    "@applitools/test-server": "^1.4.6",
     "@applitools/test-utils": "^1.5.17",
-    "@applitools/tunnel-client": "^1.12.1",
+    "@applitools/tunnel-client": "^1.12.2",
     "@swc-node/register": "^1.6.8",
     "@types/mocha": "^10.0.7",
     "@types/node": "^12.20.55",
     "@types/selenium-webdriver": "^4.1.2",
     "@types/semver": "^7.5.8",
+    "@types/shell-quote": "^1",
     "chai": "^4.2.0",
     "chromedriver": "^131.0.5",
     "crypto": "^1.0.1",

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

@@ -17,11 +17,92 @@ type ExtractCurrentCommitTimestampOptions = {
     logger?: Logger;
 };
 export declare const cacheKey = "default";
+/** Primary remote name (cached). Prefers `origin`, else the first 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;
+};
 /**
- * Get the primary remote name (cached for performance)
- * Prefers 'origin' if it exists, otherwise uses the first available remote
+ * Resolve `branchName` to a local bare ref so later `git merge-base`/`rev-parse`
+ * calls don't fatal in single-branch/shallow clones where the branch lives only
+ * on the remote.
+ *
+ * Resolution order (cheap → expensive):
+ *   1. `refs/heads/<name>` — already a local branch.
+ *   2. `refs/remotes/<remote>/<name>` — remote-tracking ref; alias it locally
+ *      via `git branch <name> <remote>/<name>`.
+ *   3. `git ls-remote --heads <remote> <name>` — remote-only; fetch it in as
+ *      a local-branch ref.
+ *   4. `undefined` — unknown branch.
+ *
+ * Never throws. NOT cachified — it has filesystem side-effects.
  */
-export declare const getPrimaryRemoteName: (({ execOptions, logger }: {
+export declare function resolveBranchToLocalRef({ branchName, remoteName, execOptions, logger, }: {
+    branchName: string;
+    remoteName: string;
+    execOptions?: ExecOptions;
+    logger?: Logger;
+}): Promise<string | 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 of the sub-checks; used in skip-logs. */
+    reason: string;
+    /** Resolved primary remote name, when one is configured. */
+    remoteName?: string;
+};
+/**
+ * One-shot, cached probe of the git environment, staged cheap → expensive:
+ *   1. git installed?                 (`git --version`)
+ *   2. inside a work tree?            (`git rev-parse --is-inside-work-tree`)
+ *   3. remote configured?            (`git remote`)
+ *   4. remote reachable?             (`git ls-remote <r> HEAD`)
+ *
+ * Outermost guard for any path that shells out to git; each step short-circuits
+ * the rest. Callers consult `ok` for local-only features, `remoteAccessible`
+ * for network ops. Cached per `cwd`; first call emits a grep-friendly
+ * `APPLITOOLS GIT ENVIRONMENT CHECK` banner, later calls return 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;
+};
+/**
+ * Detect the repo's default branch. Fallback chain (short-circuits on success;
+ * never throws):
+ *   1. `APPLITOOLS_DEFAULT_BRANCH` — explicit override.
+ *   2. `git symbolic-ref --short refs/remotes/<remote>/HEAD` — authoritative
+ *      once fetched; `<remote>/` prefix stripped.
+ *   3. `git ls-remote --symref <remote> HEAD` — works when the local symref was
+ *      never set up (single-branch clones, older CI git).
+ *   4. `git config --get init.defaultBranch` — user-global preference.
+ *   5. Literal `'main'` — last resort.
+ *
+ * Steps 2-3 catch non-standard defaults (e.g. `team/.../v1.x-rc`).
+ * Cached per `cwd`.
+ */
+export declare const extractDefaultBranch: (({ execOptions, logger }: {
     execOptions?: ExecOptions | undefined;
     logger?: Logger | undefined;
 }) => Promise<string>) & {
@@ -68,6 +149,20 @@ 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
+ * `parentBranchName`. Steps short-circuit on success; returns `undefined` on
+ * total failure — never throws.
+ *   1. Shallow clone → unshallow so topology is visible to `git merge-base`.
+ *   2. `git merge-base <remote>/<branch> <remote>/<parent>` — remote refs first
+ *      (CI usually only has these).
+ *   3. Local refs fallback (`git merge-base <branch> <parent>`).
+ *   4. Still none → if the parent is on the remote, fetch it by name and retry;
+ *      else give up (branch exists nowhere).
+ *   5. Resolve the hash's 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,21 +170,64 @@ 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 MERGE_BASE..gitBranchName by walking each
+ * commit in the window and unioning the branches that contain it. Returns a
+ * sorted, deduped list (no `refs/` prefix). Never throws — `[]` on git failure.
+ *
+ * Inclusion contract (fork-depth — shares semantics with
+ * {@link getBranchAncestryByLocalBranches}):
+ * - `gitBranchName` is **always excluded** by the self check.
+ * - `defaultBranch` is **always kept** as the base: it defines the floor
+ *   (`merge-base(HEAD, defaultBranch)`), so its own merge-base with HEAD equals
+ *   the floor and would fail the strict fork-depth test by construction.
+ * - Descendants of HEAD are dropped (built on top of us; cannot be baselines).
+ * - A candidate `C` is kept iff it forked from HEAD's history **strictly later**
+ *   than the default branch did — i.e. some `merge-base(HEAD, C)` is a strict
+ *   descendant of the floor. Cousins that share only the floor (diverged no
+ *   later than the default branch) are dropped. This prunes the over-inclusive
+ *   candidate seed (the per-commit `--contains` walk pulls in cousins via
+ *   criss-cross/ghost merges).
+ *
+ * Use {@link getBranchAncestryByLocalBranches} if you need both refs pinned.
+ */
+export declare function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOptions, logger, }: BranchAncestryOptions): Promise<string[]>;
+/**
+ * Enumerate ancestor branches by iterating every branch ref and applying
+ * Rule 1 (fork-depth: candidate must have forked from HEAD strictly later than
+ * the default branch did — some merge-base with HEAD is a strict descendant of
+ * the primary MERGE_BASE) and Rule 2 (HEAD must not be an ancestor of the
+ * candidate). Rule 1 shares the fork-depth semantics of
+ * {@link getBranchAncestryByCommits}: cousins sharing only the floor are dropped
+ * in BOTH strategies, while the default branch and genuine lineage points are
+ * kept in both.
+ *
+ * Walks `refs/heads/` AND `refs/remotes/<remote>/` (stripping the prefix), since
+ * CI typically has one local branch and dozens of remote refs.
+ *
+ * Returns a sorted, deduped list. Never throws — `[]` 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.
+ * List ancestor branches for `gitBranchName`, ordered by most-recent 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. Shallow-clone gate (skip via `enableShallowClone`, from server account-info).
+ * 2. Fetch remote branches if needed (single-branch/shallow clones).
+ * 3. Detect the actual default branch (`extractDefaultBranch` — non-standard names).
+ * 4. Discover ancestors via `APPLITOOLS_BRANCH_ANCESTRY_STRATEGY`:
+ *    `commits` (default, walks MERGE_BASE..HEAD) | `local` (iterates refs).
+ * 5. Extract each branch's branching timestamp.
+ * 6. Sort by timestamp desc, tie-break by name.
+ * 7. Root-branch safety net: fall back to the detected default branch.
  *
- * @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
+ * @returns ancestor branches with timestamps, or undefined if skipped.
  */
 export declare const extractBranchLookupFallbackList: (({ gitBranchName, execOptions, logger, enableShallowClone, }: {
     gitBranchName: string;