Skip to content

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

TypeScript

ci: the interaction and accessibility-contract lanes ask for an updated branch when the head is older than their environment (#10075)

Cindy Zhang8c0e95bf3b08
diff --git a/.github/lane-environments.json b/.github/lane-environments.json
new file mode 100644
index 0000000000..8f515aed7c
--- /dev/null
+++ b/.github/lane-environments.json
@@ -0,0 +1,14 @@
+{
+ "interaction-chromium": {
+ "version": 1,
+ "environments": ["4a2d86799445"]
+ },
+ "interaction-webkit": {
+ "version": 1,
+ "environments": ["77ffb4fb39da"]
+ },
+ "a11y-contracts": {
+ "version": 1,
+ "environments": ["4a2d86799445"]
+ }
+}
diff --git a/.github/scripts/lane-environment.mjs b/.github/scripts/lane-environment.mjs
new file mode 100644
index 0000000000..9acd8c1996
--- /dev/null
+++ b/.github/scripts/lane-environment.mjs
@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file lane-environment.mjs
+ * @description Fails a CI lane early, with a plain message, when the pull
+ * request's head is older than the lane's environment. The workflow comes
+ * from the merge commit but some lanes run the head's own specs, so a head
+ * cut before an environment change can fail for reasons that are not its
+ * own.
+ * @input `check`: the lane's key, the workflow commit's marker file and the
+ * head's marker file (`.github/lane-environments.json`).
+ * @output Exit 0, or an `::error` annotation and exit 1.
+ * @position The interaction proof legs and the touched components'
+ * accessibility contracts in ci.yml; `lane-environment.test.mjs` keeps the
+ * marker equal to each lane's environment.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/** The jobs whose environment each marker key stands for. */
+export const LANES = {
+ 'interaction-chromium': ['pr-interaction'],
+ 'interaction-webkit': ['pr-interaction-webkit'],
+ 'a11y-contracts': ['pr-component-a11y-contracts'],
+};
+
+/**
+ * A short hash of what a lane's specs run in: each job's runner, container
+ * and browser install. Other workflow edits leave it unchanged.
+ */
+export function environmentOf(jobs) {
+ const parts = jobs.map(job => ({
+ runsOn: job['runs-on'] ?? null,
+ container: job.container ?? null,
+ install:
+ job.steps?.find(step => /^Install Playwright/.test(step.name ?? ''))
+ ?.run ?? null,
+ }));
+ return crypto
+ .createHash('sha256')
+ .update(JSON.stringify(parts))
+ .digest('hex')
+ .slice(0, 12);
+}
+
+/**
+ * The lane's version in a marker file. A head with no file, or no entry for
+ * the lane, predates the markers and counts as version 1.
+ */
+export function versionIn(file, lane) {
+ if (!fs.existsSync(file)) return 1;
+ const entry = JSON.parse(fs.readFileSync(file, 'utf8'))[lane];
+ return entry?.version ?? 1;
+}
+
+/** The error for a head older than the lane, or null when it is current. */
+export function staleHead(lane, workflowVersion, headVersion) {
+ if (headVersion >= workflowVersion) return null;
+ return `The ${lane} lane's environment changed on main (version ${workflowVersion}; this branch has ${headVersion}). Update this branch onto main, then re-run.`;
+}
+
+function option(args, name) {
+ const index = args.indexOf(name);
+ return index === -1 ? undefined : args[index + 1];
+}
+
+if (
+ process.argv[1] &&
+ path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+ const [command, ...args] = process.argv.slice(2);
+ const lane = option(args, '--lane');
+ const workflow = option(args, '--workflow');
+ const head = option(args, '--head');
+ if (command !== 'check' || !LANES[lane] || !workflow || !head) {
+ console.error(
+ `usage: lane-environment.mjs check --lane <${Object.keys(LANES).join('|')}> --workflow <file> --head <file>`,
+ );
+ process.exitCode = 1;
+ } else {
+ const error = staleHead(
+ lane,
+ versionIn(workflow, lane),
+ versionIn(head, lane),
+ );
+ if (error) {
+ console.log(`::error title=Update your branch::${error}`);
+ process.exitCode = 1;
+ } else {
+ console.log(`This branch has the ${lane} lane's current environment.`);
+ }
+ }
+}
diff --git a/.github/scripts/lane-environment.test.mjs b/.github/scripts/lane-environment.test.mjs
new file mode 100644
index 0000000000..fa4c3a4146
--- /dev/null
+++ b/.github/scripts/lane-environment.test.mjs
@@ -0,0 +1,260 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file lane-environment.test.mjs
+ * @description Keeps `.github/lane-environments.json` equal to each lane's
+ * environment in ci.yml, and proves that a head older than the environment
+ * stops early with a plain message.
+ * @input ci.yml, the marker file and the check script.
+ * @output Vitest assertions.
+ * @position .github/scripts tests.
+ */
+
+import {execFileSync, spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {describe, expect, it} from 'vitest';
+import yaml from 'yaml';
+
+import {
+ LANES,
+ environmentOf,
+ staleHead,
+ versionIn,
+} from './lane-environment.mjs';
+
+const root = path.resolve(import.meta.dirname, '../..');
+const ci = yaml.parse(
+ fs.readFileSync(path.join(root, '.github/workflows/ci.yml'), 'utf8'),
+);
+const markers = JSON.parse(
+ fs.readFileSync(path.join(root, '.github/lane-environments.json'), 'utf8'),
+);
+const CHECK = "Require this lane's environment in the branch";
+const step = (job, name) => job.steps.find(each => each.name === name);
+
+describe('the lane environment markers', () => {
+ it('record each lane’s current environment, one version per environment', () => {
+ expect(Object.keys(markers).sort()).toEqual(Object.keys(LANES).sort());
+ for (const [lane, jobs] of Object.entries(LANES)) {
+ const {version, environments} = markers[lane];
+ const current = environmentOf(jobs.map(id => ci.jobs[id]));
+ // A change to a lane's runner, container or browser install appends its
+ // new hash here, which raises the version, so an older head stops with
+ // "update your branch" instead of failing in a spec. Other edits to the
+ // lane leave the hash, and every open pull request, alone.
+ expect(
+ environments.at(-1),
+ `${lane}: append ${current} to environments and set version to ${environments.length + 1}`,
+ ).toBe(current);
+ expect(version, lane).toBe(environments.length);
+ // A rollback appends an earlier hash again; only a repeat in a row is
+ // not a change.
+ for (let i = 1; i < environments.length; i++)
+ expect(environments[i], `${lane} entry ${i + 1}`).not.toBe(
+ environments[i - 1],
+ );
+ }
+ });
+
+ it('hash only the runner, the container and the browser install', () => {
+ const job = structuredClone(ci.jobs['pr-interaction-webkit']);
+ const before = environmentOf([job]);
+ const run = job.steps.find(each => /^Run /.test(each.name ?? ''));
+ run.run += '\necho other';
+ job['timeout-minutes'] = 14;
+ expect(environmentOf([job])).toBe(before);
+ for (const change of [
+ each => (each['runs-on'] = 'ubuntu-24.04'),
+ each =>
+ (each.container.image = 'mcr.microsoft.com/playwright:v9.9.9-noble'),
+ each => {
+ each.steps.find(s => /^Install Playwright/.test(s.name)).run +=
+ ' firefox';
+ },
+ ]) {
+ const changed = structuredClone(job);
+ change(changed);
+ expect(environmentOf([changed])).not.toBe(before);
+ }
+ });
+});
+
+describe('the lanes that copy the marker', () => {
+ it('run on a change to the marker or its check', () => {
+ for (const id of ['pr-interaction', 'pr-interaction-webkit']) {
+ const scope = ci.jobs[id].steps.find(each => each.id === 'scope');
+ const pattern = new RegExp(scope.with.paths);
+ for (const file of [
+ '.github/scripts/lane-environment.mjs',
+ '.github/lane-environments.json',
+ ])
+ expect(pattern.test(file), `${id} ${file}`).toBe(true);
+ }
+ });
+});
+
+describe('the check', () => {
+ it('passes a head at or past the lane’s version, and a head with no marker at version 1', () => {
+ expect(staleHead('interaction-webkit', 1, 1)).toBeNull();
+ expect(staleHead('interaction-webkit', 2, 3)).toBeNull();
+ expect(staleHead('interaction-webkit', 2, 1)).toBe(
+ "The interaction-webkit lane's environment changed on main (version 2; this branch has 1). Update this branch onto main, then re-run.",
+ );
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lane-env-'));
+ try {
+ expect(versionIn(path.join(dir, 'missing.json'), 'a11y-contracts')).toBe(
+ 1,
+ );
+ const file = path.join(dir, 'markers.json');
+ fs.writeFileSync(file, JSON.stringify({'a11y-contracts': {version: 3}}));
+ expect(versionIn(file, 'a11y-contracts')).toBe(3);
+ expect(versionIn(file, 'interaction-webkit')).toBe(1);
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+ });
+
+ const lanes = [
+ {
+ lane: 'interaction-chromium',
+ job: 'pr-interaction',
+ keep: "Keep the leg planner from the workflow's commit",
+ after: 'Verify evidence checkout',
+ dir: '$RUNNER_TEMP/interaction-legs',
+ },
+ {
+ lane: 'interaction-webkit',
+ job: 'pr-interaction-webkit',
+ keep: "Keep the leg planner from the workflow's commit",
+ after: 'Verify evidence checkout',
+ dir: '$RUNNER_TEMP/interaction-legs',
+ },
+ {
+ lane: 'a11y-contracts',
+ job: 'pr-component-a11y-contracts',
+ keep: "Keep this lane's environment marker from the workflow's commit",
+ after: 'Check out the head that built the Storybook',
+ dir: '$RUNNER_TEMP/lane-environment',
+ },
+ ];
+
+ for (const {lane, job: id, keep, after, dir} of lanes) {
+ it(`stops ${id} right after its head checkout, before any setup, when the head is older`, () => {
+ const job = ci.jobs[id];
+ const check = step(job, CHECK);
+ const headCheckout = job.steps.findIndex(
+ each =>
+ each.uses?.startsWith('actions/checkout@') &&
+ String(each.with?.ref).includes('pull_request.head.sha'),
+ );
+ const at = job.steps.indexOf(check);
+ // The marker and the script come from the workflow's commit, kept
+ // outside the workspace before the head checkout replaces it.
+ const kept = step(job, keep);
+ expect(job.steps.indexOf(kept)).toBeLessThan(headCheckout);
+ expect(kept.run).toContain(`"${dir}/.github/scripts/"`);
+ expect(kept.run).toMatch(/lane-environment\.mjs/);
+ expect(kept.run).toMatch(/lane-environments\.json/);
+ expect(at).toBe(job.steps.indexOf(step(job, after)) + 1);
+ expect(at).toBeGreaterThan(headCheckout);
+ expect(at).toBeLessThan(
+ job.steps.indexOf(step(job, 'Setup Node and pnpm')),
+ );
+ expect(check.if).toBe(job.steps[headCheckout].if);
+ expect(check.run).toBe(
+ `node "${dir}/.github/scripts/lane-environment.mjs" check --lane ${lane} --workflow "${dir}/.github/lane-environments.json" --head .github/lane-environments.json`,
+ );
+ });
+ }
+
+ // Runs a lane's check step against a workflow marker and a head marker.
+ function runCheck(lane, workflowVersion, headMarker) {
+ const {job: id, dir} = lanes.find(each => each.lane === lane);
+ const temp = fs.realpathSync(
+ fs.mkdtempSync(path.join(os.tmpdir(), 'lane-check-')),
+ );
+ try {
+ const kept = path.join(temp, dir.replace('$RUNNER_TEMP/', ''));
+ fs.mkdirSync(path.join(kept, '.github/scripts'), {recursive: true});
+ fs.copyFileSync(
+ path.join(root, '.github/scripts/lane-environment.mjs'),
+ path.join(kept, '.github/scripts/lane-environment.mjs'),
+ );
+ fs.writeFileSync(
+ path.join(kept, '.github/lane-environments.json'),
+ JSON.stringify({[lane]: {version: workflowVersion}}),
+ );
+ const head = path.join(temp, 'head');
+ fs.mkdirSync(path.join(head, '.github'), {recursive: true});
+ if (headMarker)
+ fs.writeFileSync(
+ path.join(head, '.github/lane-environments.json'),
+ JSON.stringify(headMarker),
+ );
+ return spawnSync('bash', ['-e', '-c', step(ci.jobs[id], CHECK).run], {
+ cwd: head,
+ encoding: 'utf8',
+ env: {...process.env, RUNNER_TEMP: temp},
+ });
+ } finally {
+ fs.rmSync(temp, {recursive: true, force: true});
+ }
+ }
+
+ it('fails with "Update your branch" for a head older than the lane', () => {
+ const stale = runCheck('interaction-webkit', 2, null);
+ expect(stale.status).toBe(1);
+ expect(stale.stdout).toContain(
+ "::error title=Update your branch::The interaction-webkit lane's environment changed on main (version 2; this branch has 1).",
+ );
+ const older = runCheck('a11y-contracts', 3, {
+ 'a11y-contracts': {version: 2},
+ });
+ expect(older.status).toBe(1);
+ });
+
+ it('passes a head that has the lane’s environment, and every head at version 1', () => {
+ expect(runCheck('interaction-chromium', 1, null).status).toBe(0);
+ expect(
+ runCheck('interaction-chromium', 2, {
+ 'interaction-chromium': {version: 2},
+ }).status,
+ ).toBe(0);
+ });
+
+ it('runs from the command line with the usage on a bad lane', () => {
+ const out = spawnSync(
+ process.execPath,
+ [
+ path.join(root, '.github/scripts/lane-environment.mjs'),
+ 'check',
+ '--lane',
+ 'nope',
+ ],
+ {encoding: 'utf8'},
+ );
+ expect(out.status).toBe(1);
+ expect(out.stderr).toContain('usage: lane-environment.mjs check');
+ expect(
+ execFileSync(
+ process.execPath,
+ [
+ path.join(root, '.github/scripts/lane-environment.mjs'),
+ 'check',
+ '--lane',
+ 'a11y-contracts',
+ '--workflow',
+ path.join(root, '.github/lane-environments.json'),
+ '--head',
+ path.join(root, '.github/lane-environments.json'),
+ ],
+ {encoding: 'utf8'},
+ ),
+ ).toContain(
+ "This branch has the a11y-contracts lane's current environment.",
+ );
+ });
+});
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index eb17e2aa10..774c955dc3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2509,7 +2509,7 @@ jobs:
id: scope
uses: ./.test-scope/.github/actions/test-scope
with:
- paths: '^(internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/[^/]+/src/|packages/themes/[^/]+/src/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts)\.mjs$|scripts/lib/duration-split\.mjs$|\.github/playwright-leg-durations\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
+ paths: '^(internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/[^/]+/src/|packages/themes/[^/]+/src/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
outside-pull-request: skip
requires-head-file: playwright.interaction.config.ts
@@ -2535,6 +2535,8 @@ jobs:
cp .test-scope/scripts/lib/duration-split.mjs "$RUNNER_TEMP/interaction-legs/scripts/lib/"
cp .test-scope/.github/scripts/a11y-pr-contracts.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
cp .test-scope/.github/playwright-leg-durations.json "$RUNNER_TEMP/interaction-legs/.github/"
+ cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
+ cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/interaction-legs/.github/"
# The caps step comes from the merge commit, not the pull request's
# head: a head that predates the step does not have it. The head
@@ -2568,6 +2570,15 @@ jobs:
EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"
+ # The head's specs run in this lane's environment, which comes from the
+ # merge commit. A head older than that environment stops here.
+ - name: Require this lane's environment in the branch
+ if: steps.scope.outputs.applies == 'true'
+ run: >-
+ node "$RUNNER_TEMP/interaction-legs/.github/scripts/lane-environment.mjs" check --lane interaction-chromium
+ --workflow "$RUNNER_TEMP/interaction-legs/.github/lane-environments.json"
+ --head .github/lane-environments.json
+
- name: Setup Node and pnpm
if: steps.scope.outputs.applies == 'true'
uses: ./.github/actions/setup
@@ -2681,7 +2692,7 @@ jobs:
id: scope
uses: ./.test-scope/.github/actions/test-scope
with:
- paths: '^(packages/core/src/gestures/|packages/core/src/motion/|packages/core/src/internal/touch|packages/core/src/utils/(press|touch|primaryClick|isApplePlatform|flatTree|inputStream|clickGuard|selectionLock|coarsePointer|sharedResizeObserver|scrollView)|packages/core/src/privateAttributes/(hapticSwitch|reducedMotion)\.stylex\.ts$|packages/core/src/Layer/(inputHold|modalOutlet)\.ts$|packages/core/src/hooks/(useMenuPress|menuPress|useLongPress|usePressFeedback|isRtlElement|useIsomorphicLayoutEffect|useAttachment|usePager|__tests__/(usePager|pagerBundle))|internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/themes/[^/]+/src/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts)\.mjs$|scripts/lib/duration-split\.mjs$|\.github/playwright-leg-durations\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
+ paths: '^(packages/core/src/gestures/|packages/core/src/motion/|packages/core/src/internal/touch|packages/core/src/utils/(press|touch|primaryClick|isApplePlatform|flatTree|inputStream|clickGuard|selectionLock|coarsePointer|sharedResizeObserver|scrollView)|packages/core/src/privateAttributes/(hapticSwitch|reducedMotion)\.stylex\.ts$|packages/core/src/Layer/(inputHold|modalOutlet)\.ts$|packages/core/src/hooks/(useMenuPress|menuPress|useLongPress|usePressFeedback|isRtlElement|useIsomorphicLayoutEffect|useAttachment|usePager|__tests__/(usePager|pagerBundle))|internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/themes/[^/]+/src/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
outside-pull-request: skip
requires-head-file: playwright.interaction.config.ts
# Lists the changed files, so the planner adds a changed spec.
@@ -2709,6 +2720,8 @@ jobs:
cp .test-scope/scripts/lib/duration-split.mjs "$RUNNER_TEMP/interaction-legs/scripts/lib/"
cp .test-scope/.github/scripts/a11y-pr-contracts.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
cp .test-scope/.github/playwright-leg-durations.json "$RUNNER_TEMP/interaction-legs/.github/"
+ cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
+ cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/interaction-legs/.github/"
# The caps step comes from the merge commit, not the pull request's
# head: a head that predates the step does not have it. The head
@@ -2748,6 +2761,15 @@ jobs:
EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"
+ # The head's specs run in this lane's environment, which comes from the
+ # merge commit. A head older than that environment stops here.
+ - name: Require this lane's environment in the branch
+ if: steps.scope.outputs.applies == 'true'
+ run: >-
+ node "$RUNNER_TEMP/interaction-legs/.github/scripts/lane-environment.mjs" check --lane interaction-webkit
+ --workflow "$RUNNER_TEMP/interaction-legs/.github/lane-environments.json"
+ --head .github/lane-environments.json
+
- name: Setup Node and pnpm
if: steps.scope.outputs.applies == 'true'
uses: ./.github/actions/setup
@@ -4037,10 +4059,15 @@ jobs:
contents: read
pull-requests: read
steps:
+ # The workflow's own commit: the scope action, and this lane's
+ # environment marker and its check (in .github, a parent of the scripts,
+ # so the checkout's cone holds the marker).
- name: Check out the scope action
uses: actions/checkout@v7
with:
- sparse-checkout: .github/actions/test-scope
+ sparse-checkout: |
+ .github/actions/test-scope
+ .github/scripts
path: .test-scope
persist-credentials: false
@@ -4062,6 +4089,15 @@ jobs:
if: steps.scope.outputs.applies != 'true'
run: echo "No component or browser accessibility spec changed; no contract to run."
+ # The checkouts below replace the workspace, scope checkout included, so
+ # the marker of this lane's environment, and its check, move out first.
+ - name: Keep this lane's environment marker from the workflow's commit
+ if: steps.scope.outputs.applies == 'true'
+ run: |
+ mkdir -p "$RUNNER_TEMP/lane-environment/.github/scripts"
+ cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/lane-environment/.github/scripts/"
+ cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/lane-environment/.github/"
+
# The tested merge commit, as the touched-components job checks out: a
# head that predates these scripts does not have them. The specs run at
# the head (see "Check out the head that built the Storybook").
@@ -4147,6 +4183,15 @@ jobs:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
persist-credentials: false
+ # The head's specs run in this lane's environment, which comes from the
+ # merge commit. A head older than that environment stops here.
+ - name: Require this lane's environment in the branch
+ if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'
+ run: >-
+ node "$RUNNER_TEMP/lane-environment/.github/scripts/lane-environment.mjs" check --lane a11y-contracts
+ --workflow "$RUNNER_TEMP/lane-environment/.github/lane-environments.json"
+ --head .github/lane-environments.json
+
- name: Setup Node and pnpm
if: steps.touched.outputs.has_components == 'true' || steps.specs.outputs.has_specs == 'true'
uses: ./.github/actions/setup