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.mjsindex 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.mjsindex 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.mjsindex 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);