@gfxlabs/third-eye-cli 3.23.2 → 3.24.0

package/dist/bin.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import path, { join, normalize } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -25,6 +26,9 @@ import { createORPCClient } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
 import { execa } from "execa";
 import { XMLParser } from "fast-xml-parser";
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
 //#region src/log.ts
 const logMemory = [];
 const serializeError = (error) => ({
@@ -860,7 +864,7 @@ const collectLadleStories = async (ladleUrl) => {
 };
 //#endregion
 //#region src/crawler/storybook.ts
-const kebabCase = (str) => (str ?? "").replace(/([a-z\d])([A-Z])/g, "$1-$2").replace(/[\s_/]+/g, "-").toLowerCase();
+const kebabCase$1 = (str) => (str ?? "").replace(/([a-z\d])([A-Z])/g, "$1-$2").replace(/[\s_/]+/g, "-").toLowerCase();
 const getStoryBookUrl = (url) => {
 	if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("file://")) return url;
 	if (url.startsWith("/")) return `file://${url}`;
@@ -996,9 +1000,9 @@ const generateStoryUrl = (iframeUrl, storyId, args, breakpoint) => {
 const generateFilename = (kind, story, prefix, suffix) => {
 	return [
 		prefix,
-		kebabCase(kind),
-		kebabCase(story),
-		kebabCase(suffix)
+		kebabCase$1(kind),
+		kebabCase$1(story),
+		kebabCase$1(suffix)
 	].filter(Boolean).join("--");
 };
 const generateStorybookShotItems = (baseUrl, stories, mask, modeBreakpoints, browser) => {
@@ -1496,7 +1500,12 @@ const collectHistoireStories = async (histoireUrl) => {
 };
 //#endregion
 //#region src/createShots.ts
-const createShots = async () => {
+/**
+* @param turboSnapFilter - When provided, only stories whose shotName is in this set
+*   will be screenshotted. Stories not in the set are skipped entirely (no Playwright
+*   navigation), which is the main performance win of TurboSnap.
+*/
+const createShots = async (turboSnapFilter) => {
 	const { ladleShots, histoireShots, storybookShots, pageShots, customShots, imagePathCurrent } = config;
 	let storybookShotItems = [];
 	let ladleShotItems = [];
@@ -1580,10 +1589,12 @@ const createShots = async () => {
 			await mapLimit(browsers, 1, async (browser) => {
 				const shotItems = generateStorybookShotItems(storybookWebUrl, collection.stories, mask, storybookShots.breakpoints, browsers.length > 1 ? browser : void 0);
 				const filterItemsToCheck = "filterItemsToCheck" in config ? config.filterItemsToCheck : void 0;
-				const filteredShotItems = filterItemsToCheck ? shotItems.filter((item) => filterItemsToCheck(item)) : shotItems;
+				let filteredShotItems = filterItemsToCheck ? shotItems.filter((item) => filterItemsToCheck(item)) : shotItems;
+				if (turboSnapFilter) filteredShotItems = filteredShotItems.filter((item) => turboSnapFilter.has(item.shotName) || turboSnapFilter.has(`${item.shotMode}/${item.shotName}`));
 				storybookShotItems = shotItems;
-				log.process("info", "general", `Prepared ${filteredShotItems.length} stories for screenshots on ${browser.name()}`);
-				await takeScreenShots(filteredShotItems, browser);
+				const capturedItems = filteredShotItems;
+				log.process("info", "general", turboSnapFilter ? `Prepared ${capturedItems.length}/${shotItems.length} stories for screenshots on ${browser.name()} (TurboSnap: ${shotItems.length - capturedItems.length} skipped)` : `Prepared ${capturedItems.length} stories for screenshots on ${browser.name()}`);
+				await takeScreenShots(capturedItems, browser);
 			});
 			localServer?.close();
 		} catch (error) {
@@ -1626,6 +1637,76 @@ const createShots = async () => {
 	];
 };
 //#endregion
+//#region src/git.ts
+const INITIAL_BATCH_SIZE = 20;
+/**
+* Execute a git command and return the trimmed output.
+*/
+const execGit = (command) => {
+	try {
+		return execSync(command, {
+			encoding: "utf-8",
+			timeout: 1e4
+		}).trim();
+	} catch {
+		return "";
+	}
+};
+/**
+* Find the "covering" set of ancestor commits that have builds on the server.
+*
+* This mirrors Chromatic's approach:
+* 1. Walk git history with `git rev-list`
+* 2. Ask the server which commits have builds
+* 3. Use `--not` to exclude ancestors of commits with builds
+* 4. Repeat with exponentially larger batches until no more uncovered commits
+*
+* The result is the minimal set of ancestor commits with builds such that
+* every ancestor of HEAD either has a build or is an ancestor of a commit
+* with a build.
+*/
+const getParentCommits = async (hasBuildsWithCommits) => {
+	if (!execGit("git rev-parse HEAD")) {
+		log.process("info", "general", "Not a git repository, skipping ancestor detection");
+		return [];
+	}
+	if (!execGit("git --no-pager log -n 1 --skip=1 --format=\"%H\"")) {
+		log.process("info", "general", "Initial commit, no ancestors");
+		return [];
+	}
+	let commitsWithBuilds = [];
+	let commitsWithoutBuilds = [];
+	let limit = INITIAL_BATCH_SIZE;
+	for (;;) {
+		const notArgs = commitsWithBuilds.map((c) => c.trim()).join(" ");
+		const output = execGit(`git rev-list HEAD -n ${limit + commitsWithoutBuilds.length}${notArgs ? ` --not ${notArgs}` : ""}`);
+		const candidates = (output ? output.split("\n").filter(Boolean) : []).filter((c) => !commitsWithBuilds.includes(c)).filter((c) => !commitsWithoutBuilds.includes(c)).slice(0, limit);
+		if (candidates.length === 0) break;
+		log.process("info", "general", `🔍 Checking ${candidates.length} commits for builds (batch size ${limit})`);
+		const newCommitsWithBuilds = await hasBuildsWithCommits(candidates);
+		const newCommitsWithoutBuilds = candidates.filter((c) => !newCommitsWithBuilds.includes(c));
+		commitsWithBuilds = [...commitsWithBuilds, ...newCommitsWithBuilds];
+		commitsWithoutBuilds = [...commitsWithoutBuilds, ...newCommitsWithoutBuilds];
+		limit *= 2;
+		if (commitsWithoutBuilds.length > 1e4) {
+			log.process("info", "general", "Reached max history depth (10000 commits)");
+			break;
+		}
+	}
+	if (commitsWithBuilds.length === 0) {
+		log.process("info", "general", "No ancestor builds found — this may be the first build");
+		return [];
+	}
+	if (commitsWithBuilds.length > 1) {
+		const parentArgs = commitsWithBuilds.map((c) => `"${c}^@"`).join(" ");
+		const maxOutput = execGit(`git rev-list ${commitsWithBuilds.join(" ")} --not ${parentArgs}`);
+		const maxCommits = maxOutput ? maxOutput.split("\n").filter(Boolean) : [];
+		if (maxCommits.length > 0) commitsWithBuilds = maxCommits;
+	}
+	log.process("info", "general", `📌 Found ${commitsWithBuilds.length} ancestor build(s): ${commitsWithBuilds.map((c) => c.slice(0, 7)).join(", ")}`);
+	return commitsWithBuilds;
+};
+//#endregion
 //#region ../shared/dist/client.js
 /**
 * Typed oRPC client factory.
@@ -1694,7 +1775,7 @@ const getApiToken = async (config) => {
 		process.exit(1);
 	}
 };
-const sendInitToAPI = async (config, apiToken) => {
+const sendInitToAPI = async (config, apiToken, parentCommits) => {
 	const client = createClient(config.thirdEyePlatform, void 0, apiToken);
 	return withRetry("init", () => client.orgs.projects.builds.init({
 		orgId: config.thirdEyeOrgId,
@@ -1703,9 +1784,18 @@ const sendInitToAPI = async (config, apiToken) => {
 		branchName: config.commitRefName,
 		buildNumber: config.ciBuildNumber,
 		baseBranch: config.baseBranch || void 0,
-		prNumber: config.prNumber
+		prNumber: config.prNumber,
+		parentCommits
 	}));
 };
+const sendHasBuildsWithCommitsToAPI = async (config, apiToken, commits) => {
+	const client = createClient(config.thirdEyePlatform, void 0, apiToken);
+	return (await withRetry("hasBuildsWithCommits", () => client.orgs.projects.builds.hasBuildsWithCommits({
+		orgId: config.thirdEyeOrgId,
+		projectId: config.thirdEyeProjectId,
+		commits
+	}))).commits;
+};
 const sendFinalizeToAPI = async (config, apiToken) => {
 	const client = createClient(config.thirdEyePlatform, void 0, apiToken);
 	return withRetry("finalize", () => client.orgs.projects.builds.finalize({
@@ -1795,7 +1885,7 @@ const uploadStorybookArchive = async (config, apiToken, projectId, buildId, arch
 };
 //#endregion
 //#region src/upload.ts
-const uploadRequiredShots = async ({ config, apiToken, uploadToken, requiredFileHashes, extendedShotItems }) => {
+const uploadRequiredShots = async ({ config, apiToken, uploadToken, requiredFileHashes, extendedShotItems, dependencyMap }) => {
 	if (requiredFileHashes.length > 0) {
 		log.process("info", "api", "Uploading shots");
 		const uploadStart = process.hrtime();
@@ -1825,7 +1915,8 @@ const uploadRequiredShots = async ({ config, apiToken, uploadToken, requiredFile
 					...shotItem.tags ? { tags: shotItem.tags } : {},
 					...shotItem.viewport ? { viewport: shotItem.viewport } : {},
 					...shotItem.breakpoint !== void 0 ? { breakpoint: shotItem.breakpoint } : {},
-					...domHtml ? { dom_html: domHtml } : {}
+					...domHtml ? { dom_html: domHtml } : {},
+					...dependencyMap && shotItem.importPath && dependencyMap.has(shotItem.importPath) ? { dependencies: dependencyMap.get(shotItem.importPath) } : {}
 				},
 				logger
 			});
@@ -1836,7 +1927,168 @@ const uploadRequiredShots = async ({ config, apiToken, uploadToken, requiredFile
 	return true;
 };
 //#endregion
+//#region src/turbosnap.ts
+/**
+* TurboSnap: static import tracer for determining which stories are affected by code changes.
+*
+* Given a list of changed files (from git diff) and the storybook index (importPath per story),
+* this module traces each story file's transitive imports to determine which stories need
+* re-screenshotting. Stories whose dependency tree does not overlap with any changed file are
+* skipped entirely — they never get launched in Playwright, saving the majority of run time.
+*
+* The import tracer is intentionally simple: it parses `import`/`require` statements with a
+* regex, resolves relative and aliased paths, and follows them recursively with cycle detection.
+* It does not evaluate dynamic imports or re-exports — those are rare in component code and the
+* fallback is always "capture the story" (safe default).
+*/
+const RESOLVE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+];
+const INDEX_FILES = RESOLVE_EXTENSIONS.map((ext) => `index${ext}`);
+/**
+* Regex that captures the string literal from import/require statements.
+* Handles:
+*   import ... from 'foo'
+*   import ... from "foo"
+*   import 'foo'
+*   export ... from 'foo'
+*   require('foo')
+*/
+const IMPORT_RE = /(?:import\s+(?:[\s\S]*?\s+from\s+)?|export\s+(?:[\s\S]*?\s+from\s+)?|require\s*\()["']([^"']+)["']/g;
+/**
+* Parse tsconfig-style path aliases into a simple prefix → directory map.
+* E.g. `{ "#/*": ["./src/app/*"] }` → `{ "#/": "/abs/path/src/app/" }`
+*/
+const parsePathAliases = (tsconfigPath, projectRoot) => {
+	const aliases = {};
+	try {
+		const stripped = readFileSync(tsconfigPath, "utf-8").replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/,(\s*[}\]])/g, "$1");
+		const paths = JSON.parse(stripped).compilerOptions?.paths;
+		if (paths) {
+			for (const [pattern, targets] of Object.entries(paths)) if (targets.length > 0) {
+				const prefix = pattern.replace(/\*$/, "");
+				const target = targets[0].replace(/\*$/, "");
+				aliases[prefix] = path.resolve(projectRoot, target);
+			}
+		}
+	} catch {}
+	return aliases;
+};
+/**
+* Resolve a single import specifier to an absolute file path.
+* Returns undefined if the import is external (node_modules) or unresolvable.
+*/
+const resolveImport = (specifier, fromFile, aliases) => {
+	if (!specifier.startsWith(".") && !specifier.startsWith("/") && !Object.keys(aliases).some((prefix) => specifier.startsWith(prefix))) return;
+	let resolved;
+	const matchingAlias = Object.entries(aliases).find(([prefix]) => specifier.startsWith(prefix));
+	if (matchingAlias) {
+		const [prefix, target] = matchingAlias;
+		resolved = path.join(target, specifier.slice(prefix.length));
+	} else resolved = path.resolve(path.dirname(fromFile), specifier);
+	if (existsSync(resolved) && !isDirectory(resolved)) return resolved;
+	for (const ext of RESOLVE_EXTENSIONS) {
+		const withExt = resolved + ext;
+		if (existsSync(withExt)) return withExt;
+	}
+	for (const indexFile of INDEX_FILES) {
+		const withIndex = path.join(resolved, indexFile);
+		if (existsSync(withIndex)) return withIndex;
+	}
+};
+const isDirectory = (p) => {
+	try {
+		const { statSync } = __require("node:fs");
+		return statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+};
+/**
+* Extract all import specifiers from a source file.
+*/
+const extractImports = (filePath) => {
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		const imports = [];
+		let match;
+		IMPORT_RE.lastIndex = 0;
+		while ((match = IMPORT_RE.exec(content)) !== null) if (match[1]) imports.push(match[1]);
+		return imports;
+	} catch {
+		return [];
+	}
+};
+/**
+* Trace all transitive dependencies of a file recursively.
+* Returns a Set of absolute file paths that the file depends on (including itself).
+*/
+const traceDependencies = (entryFile, projectRoot, aliases, _cache) => {
+	const cache = _cache ?? /* @__PURE__ */ new Map();
+	const absEntry = path.isAbsolute(entryFile) ? entryFile : path.resolve(projectRoot, entryFile);
+	if (cache.has(absEntry)) return cache.get(absEntry);
+	const deps = new Set([absEntry]);
+	cache.set(absEntry, deps);
+	if (!existsSync(absEntry)) return deps;
+	const importSpecifiers = extractImports(absEntry);
+	for (const spec of importSpecifiers) {
+		const resolved = resolveImport(spec, absEntry, aliases);
+		if (resolved && !deps.has(resolved)) {
+			deps.add(resolved);
+			const transitiveDeps = traceDependencies(resolved, projectRoot, aliases, cache);
+			for (const d of transitiveDeps) deps.add(d);
+		}
+	}
+	return deps;
+};
+/**
+* Determine which stories are affected by a set of changed files.
+*
+* @param stories - Array of { shotName, importPath } from the storybook index
+* @param changedFiles - Relative file paths from `git diff --name-only`
+* @param projectRoot - Absolute path to the project root (for resolving imports)
+* @returns Which stories to capture and which to skip
+*/
+const getAffectedStoriesLocal = (stories, changedFiles, projectRoot) => {
+	const aliases = parsePathAliases(path.join(projectRoot, "tsconfig.json"), projectRoot);
+	const changedAbsolute = new Set(changedFiles.map((f) => path.resolve(projectRoot, f)));
+	const affected = [];
+	const skipped = [];
+	const dependencyMap = /* @__PURE__ */ new Map();
+	const depCache = /* @__PURE__ */ new Map();
+	for (const story of stories) {
+		if (!story.importPath) {
+			affected.push(story.shotName);
+			continue;
+		}
+		const deps = traceDependencies(path.resolve(projectRoot, story.importPath), projectRoot, aliases, depCache);
+		const relativeDeps = [...deps].map((d) => path.relative(projectRoot, d));
+		dependencyMap.set(story.importPath, relativeDeps);
+		let isAffected = false;
+		for (const dep of deps) if (changedAbsolute.has(dep)) {
+			isAffected = true;
+			break;
+		}
+		if (isAffected) affected.push(story.shotName);
+		else skipped.push(story.shotName);
+	}
+	return {
+		affected,
+		skipped,
+		total: stories.length,
+		dependencyMap
+	};
+};
+//#endregion
 //#region src/runner.ts
+const kebabCase = (str) => (str ?? "").replace(/([a-z\d])([A-Z])/g, "$1-$2").replace(/[\s_/]+/g, "-").toLowerCase();
+/** Generate the shot name from a storybook title and story name, matching the crawler's logic. */
+const generateShotName = (title, name) => [kebabCase(title), kebabCase(name)].filter(Boolean).join("--");
 /**
 * Get the list of files changed between the current HEAD and a base ref
 * using git diff. Returns an empty array if git is unavailable or fails.
@@ -1941,30 +2193,46 @@ const platformRunner = async (config, apiToken) => {
 			`commitRefName = ${config.commitRefName}`,
 			`commitHash = ${config.commitHash}`
 		].join("\n   - "));
-		await sendInitToAPI(config, apiToken);
+		log.process("info", "general", "🔍 Resolving ancestor builds from git history...");
+		await sendInitToAPI(config, apiToken, await getParentCommits((commits) => sendHasBuildsWithCommitsToAPI(config, apiToken, commits)));
 		if (!await checkForCachedBuild(config, apiToken)) {
 			log.process("info", "general", "📂 Creating shot folders");
 			const createShotsStart = process.hrtime();
 			createShotsFolders();
-			log.process("info", "general", "📸 Creating shots");
-			let shotItems = await createShots();
+			let turboSnapFilter;
+			let turboSnapDependencyMap;
 			if (config.turboSnap && config.baseBranch) {
 				log.process("info", "general", `⚡ TurboSnap enabled, checking changed files against ${config.baseBranch}`);
 				const changedFiles = getChangedFiles(config.baseBranch);
 				if (changedFiles.length > 0) {
 					log.process("info", "general", `Found ${changedFiles.length} changed file(s)`);
 					try {
-						const turboResult = await getAffectedStories(config, apiToken, changedFiles);
-						log.process("info", "general", `TurboSnap: ${turboResult.affectedCount} affected, ${turboResult.skippedCount} skipped`);
-						if (turboResult.affected.length > 0) {
-							const affectedSet = new Set(turboResult.affected);
-							shotItems = shotItems.filter((item) => affectedSet.has(item.shotName) || affectedSet.has(`${item.shotMode}/${item.shotName}`));
+						const storybookPath = config.storybookShots?.storybookUrl ?? "";
+						const indexJsonPath = path.join(storybookPath.startsWith("http") ? "" : storybookPath, "index.json");
+						if (existsSync(indexJsonPath)) {
+							const indexJson = JSON.parse(fs.readFileSync(indexJsonPath, "utf-8"));
+							const entries = indexJson.entries ?? indexJson.stories ?? {};
+							const turboResult = getAffectedStoriesLocal(Object.values(entries).filter((e) => e.type !== "docs").map((e) => ({
+								shotName: generateShotName(e.title, e.name),
+								importPath: e.importPath
+							})), changedFiles, process.cwd());
+							log.process("info", "general", `⚡ TurboSnap: ${turboResult.affected.length} affected, ${turboResult.skipped.length} skipped out of ${turboResult.total} stories`);
+							turboSnapFilter = new Set(turboResult.affected);
+							turboSnapDependencyMap = turboResult.dependencyMap;
+						} else try {
+							const serverResult = await getAffectedStories(config, apiToken, changedFiles);
+							log.process("info", "general", `⚡ TurboSnap (server): ${serverResult.affectedCount} affected, ${serverResult.skippedCount} skipped`);
+							if (serverResult.affected.length > 0) turboSnapFilter = new Set(serverResult.affected);
+						} catch (error) {
+							if (error instanceof Error) log.process("warn", "general", `TurboSnap server query failed, capturing all stories: ${error.message}`);
 						}
 					} catch (error) {
 						if (error instanceof Error) log.process("warn", "general", `TurboSnap filtering failed, capturing all stories: ${error.message}`);
 					}
 				} else log.process("info", "general", "TurboSnap: no changed files detected, capturing all stories");
 			}
+			log.process("info", "general", "📸 Creating shots");
+			let shotItems = await createShots(turboSnapFilter);
 			const shotNames = shotItems.map((shotItem) => shotItem.shotName);
 			const uniqueShotNames = new Set(shotNames);
 			if (shotNames.length !== uniqueShotNames.size) {
@@ -2000,7 +2268,8 @@ const platformRunner = async (config, apiToken) => {
 				apiToken,
 				uploadToken,
 				requiredFileHashes,
-				extendedShotItems
+				extendedShotItems,
+				dependencyMap: turboSnapDependencyMap
 			});
 			await processShots(config, apiToken, uploadToken, shotItems.map((shotItem) => ({
 				name: `${shotItem.shotMode}/${shotItem.shotName}`,