Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

visual gate: the probe cover keeps a baselined story on a tie, so baseline syncs converge (#10597)

Cindy Zhang90be12dd4404
diff --git a/.github/scripts/visual-gate/gate.mjs b/.github/scripts/visual-gate/gate.mjs
index d1ba318473..8d53c66c16 100644
--- a/.github/scripts/visual-gate/gate.mjs
+++ b/.github/scripts/visual-gate/gate.mjs
@@ -53,6 +53,7 @@ import {
emptyVisualPlanMessage,
exceedsPrVisualShotLimit,
existingComponentBaselinePlan,
+ probeBaselineStories,
readStoryIndex,
readThemeCatalog,
resolvePrVisualTotalShotLimit,
@@ -330,6 +331,7 @@ async function plan({scoutOnly = false} = {}) {
matrixThemes,
themeStories,
probeTheme: config.probeTheme,
+ baselineStories: probeBaselineStories(baselineManifest, config.probeTheme),
});
if (tiers.includes('component')) {
shots = existingComponentBaselinePlan(shots, baselineManifest);
diff --git a/.github/scripts/visual-gate/lib/plan.mjs b/.github/scripts/visual-gate/lib/plan.mjs
index f7f7f62b77..ded161c901 100644
--- a/.github/scripts/visual-gate/lib/plan.mjs
+++ b/.github/scripts/visual-gate/lib/plan.mjs
@@ -543,6 +543,21 @@ export function acceptedVisualThemes(manifest, themes, defaultTheme) {
return [...accepted].sort();
}
+/**
+ * Ids of the stories the accepted baseline holds probe-theme shots for. The
+ * probe cover keeps them when another story would cover as many targets.
+ * @param {{shots?: Record<string, {storyId?: string, theme?: string}>}} manifest
+ * @param {string} probeTheme
+ * @returns {Set<string>}
+ */
+export function probeBaselineStories(manifest, probeTheme) {
+ return new Set(
+ Object.values(manifest?.shots ?? {})
+ .filter(shot => shot.theme === probeTheme && typeof shot.storyId === 'string')
+ .map(shot => shot.storyId),
+ );
+}
+
/** Current stable stories that own at least one accepted baseline contract. */
export function baselineVisualStories(stories, manifest) {
const indexed = new Map(stories.map(story => [story.id, story]));
@@ -626,6 +641,7 @@ function rank(name) {
* @param {string[]} [options.matrixThemes] - restrict theme-matrix to changed shipped themes
* @param {ReturnType<typeof readStoryIndex>} [options.themeStories] - accepted stories to render for changed themes
* @param {string} [options.probeTheme] - name of the generated coverage theme
+ * @param {Set<string>} [options.baselineStories] - ids of stories the accepted baseline already holds probe shots for
* @returns {Shot[]}
*/
export function buildPlan({
@@ -640,6 +656,7 @@ export function buildPlan({
matrixThemes = [],
themeStories = [],
probeTheme = 'probe',
+ baselineStories = new Set(),
}) {
/** @type {Map<string, Shot>} */
const shots = new Map();
@@ -733,6 +750,7 @@ export function buildPlan({
targets,
observations,
probeTheme,
+ baselineStories,
})) {
add(shot, reason);
}
@@ -756,13 +774,19 @@ export function buildPlan({
* verifies all of them at once. Without observations there is nothing to aim
* at — the probe tier needs the scout.
*
+ * Between stories that would cover the same number of targets, the cover keeps
+ * a story the accepted baseline already holds, then takes the smallest story
+ * id. So the choice does not move when an unrelated story is added or the
+ * story index changes order, and a baseline sync does not chase it.
+ *
* @param {object} options
* @param {ReturnType<typeof readStoryIndex>} options.stories
* @param {Array<{key: string, component: string}>} options.targets
* @param {Record<string, Record<string, string[]>>} [options.observations]
* @param {string} options.probeTheme
+ * @param {Set<string>} options.baselineStories
*/
-function probeShots({stories, targets, observations, probeTheme}) {
+function probeShots({stories, targets, observations, probeTheme, baselineStories}) {
if (!observations) return [];
const wanted = new Set(targets.map(target => target.key));
@@ -780,7 +804,7 @@ function probeShots({stories, targets, observations, probeTheme}) {
let bestCount = 0;
for (const [story, rendered] of byStory) {
const count = [...rendered].filter(key => uncovered.has(key)).length;
- if (count > bestCount) {
+ if (count > bestCount || (count > 0 && count === bestCount && keepsTie(story, best, baselineStories))) {
best = story;
bestCount = count;
}
@@ -795,6 +819,20 @@ function probeShots({stories, targets, observations, probeTheme}) {
return planned;
}
+/**
+ * Whether `story` wins a tie in the probe cover over `current`: a story the
+ * baseline already holds first, then the smaller story id.
+ * @param {{id: string}} story
+ * @param {{id: string}} current
+ * @param {Set<string>} baselineStories
+ * @returns {boolean}
+ */
+function keepsTie(story, current, baselineStories) {
+ const held = baselineStories.has(story.id);
+ if (held !== baselineStories.has(current.id)) return held;
+ return story.id < current.id;
+}
+
/**
* The targeted net: for every selector a theme overrides, one story that
* actually renders it.
diff --git a/.github/scripts/visual-gate/lib/plan.test.mjs b/.github/scripts/visual-gate/lib/plan.test.mjs
index e85636d78f..5129bbad1e 100644
--- a/.github/scripts/visual-gate/lib/plan.test.mjs
+++ b/.github/scripts/visual-gate/lib/plan.test.mjs
@@ -16,6 +16,7 @@ import {
emptyVisualPlanMessage,
exceedsPrVisualShotLimit,
existingComponentBaselinePlan,
+ probeBaselineStories,
readStoryIndex,
readThemeCatalog,
representativeStories,
@@ -349,6 +350,69 @@ describe('buildPlan', () => {
]);
});
+ describe('the probe cover between stories that tie', () => {
+ const badgeTarget = [{key: 'badge', className: 'astryx-badge', component: 'Badge', props: [], states: []}];
+ const solid = story({id: 'core-badge--solid', title: 'Core/Badge', name: 'Solid', component: 'Badge'});
+ // A story added later that renders the same targets as the one already
+ // in the baseline, and comes first in the story index.
+ const added = story({id: 'core-badge--added-later', title: 'Core/Badge', name: 'Added Later', component: 'Badge'});
+ const observations = {
+ 'core-badge--solid': {badge: ['base']},
+ 'core-badge--added-later': {badge: ['base']},
+ };
+ const probeKeys = (list, extra = {}) =>
+ buildPlan({
+ stories: list,
+ targets: badgeTarget,
+ themeOverrides: {},
+ observations,
+ defaultTheme: 'neutral',
+ tiers: ['probe'],
+ probeTheme: 'probe',
+ ...extra,
+ }).map(shot => shot.key);
+
+ it('keeps the story already in the baseline when a new story ties with it', () => {
+ const baselineStories = new Set(['core-badge--solid']);
+ const kept = ['core-badge--solid__probe-dark', 'core-badge--solid__probe-light'];
+ expect(probeKeys([added, solid], {baselineStories})).toEqual(kept);
+ expect(probeKeys([solid, added], {baselineStories})).toEqual(kept);
+ });
+
+ it('picks the same story whatever the story index order, with no baseline', () => {
+ const first = ['core-badge--added-later__probe-dark', 'core-badge--added-later__probe-light'];
+ expect(probeKeys([solid, added])).toEqual(first);
+ expect(probeKeys([added, solid])).toEqual(first);
+ });
+
+ it('reads the baselined probe stories from the accepted manifest', () => {
+ const manifest = {
+ shots: {
+ 'core-badge--solid__probe-dark': {storyId: 'core-badge--solid', theme: 'probe'},
+ 'core-badge--solid__neutral-dark': {storyId: 'core-badge--solid', theme: 'neutral'},
+ 'core-button--primary__neutral-light': {storyId: 'core-button--primary', theme: 'neutral'},
+ },
+ };
+ expect(probeBaselineStories(manifest, 'probe')).toEqual(new Set(['core-badge--solid']));
+ expect(probeBaselineStories({}, 'probe')).toEqual(new Set());
+ });
+
+ it('still prefers the story that covers more targets over a baselined one', () => {
+ const wide = story({id: 'core-badge--wide', title: 'Core/Badge', name: 'Wide', component: 'Badge'});
+ const keys = buildPlan({
+ stories: [solid, wide],
+ targets: [...badgeTarget, {key: 'tooltip', className: 'astryx-tooltip', component: 'Tooltip', props: [], states: []}],
+ themeOverrides: {},
+ observations: {'core-badge--solid': {badge: ['base']}, 'core-badge--wide': {badge: ['base'], tooltip: ['base']}},
+ defaultTheme: 'neutral',
+ tiers: ['probe'],
+ probeTheme: 'probe',
+ baselineStories: new Set(['core-badge--solid']),
+ }).map(shot => shot.key);
+ expect(keys).toEqual(['core-badge--wide__probe-dark', 'core-badge--wide__probe-light']);
+ });
+ });
+
it('adds a shot for every theme that overrides a component the story renders', () => {
const plan = buildPlan({stories, targets, themeOverrides, defaultTheme: 'neutral', tiers: ['theme-matrix']});
const y2k = plan.filter(shot => shot.theme === 'y2k').map(shot => shot.key);