@elliemae/ds-monorepo-devops 3.70.0-next.6 → 3.70.0-next.60

package/configs/jest/testing/jest.config.base.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import normalizePath from 'normalize-path';
 import { swcrcConfig } from './swcrc.config.cjs';
 import { findMonoRepoRoot } from './utils.cjs';
+import { resolvePinnedStyledComponents } from '../../resolve-pinned-styled-components.cjs';
 
 const __filename = fileURLToPath(import.meta.url); // get the resolved path to the file
 const __dirname = path.dirname(__filename); // get the name of the directory
@@ -19,6 +20,14 @@ const getNodeModulesPath = (fileName) => {
   );
 };
 
+// See configs/resolve-pinned-styled-components.cjs for the full rationale. In short:
+// styled-components@5.3.11 resolves to two pnpm instances (pnpm/pnpm#11834), which means two
+// ThemeContext objects, which means themeProviderHOC's ThemeProvider is invisible to styled()
+// calls resolved through the other instance. Both packages must be aliased onto one instance.
+// This intentionally throws rather than degrading: a missing pin surfaces as dozens of
+// "Cannot read properties of undefined" render errors, a long way from the cause.
+const pinnedStyledComponentsPaths = resolvePinnedStyledComponents(process.cwd());
+
 const configuredJestConfig = {
   coverageThreshold: {},
   coverageProvider: 'v8',
@@ -39,6 +48,9 @@ const configuredJestConfig = {
     '@elliemae/pui-diagnostics': getMockFilePath('pui-diagnostics.js'),
     'react-spring/web': getNodeModulesPath('react-spring/web.cjs.js'),
     'react-spring/renderprops': getNodeModulesPath('react-spring/renderprops.cjs.js'),
+    // See resolve-pinned-styled-components.cjs for why these two are needed.
+    '^styled-components$': normalizePath(pinnedStyledComponentsPaths.styledComponentsPath),
+    '^@xstyled/styled-components$': normalizePath(pinnedStyledComponentsPaths.xstyledStyledComponentsPath),
   },
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   setupFilesAfterEnv: [path.resolve(__dirname, './setup-tests.js'), path.resolve(__dirname, './setup-react-env.js')],

package/configs/playwright/ci-image-contract.mjs

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const localRequire = createRequire(import.meta.url);
+
+/**
+ * The Playwright version pre-installed in the Jenkins CI image. This is the *image's* value, not a
+ * second copy of ours — the catalog pins in `pnpm-workspace.yaml` say what this workspace uses, and
+ * this says what CI can actually run. The check below exists to prove the two agree.
+ *
+ * Jenkins runs component tests inside `docker-local/nodejs22pnpm10` (built from
+ * `pui-nodejs-docker@22.x-pnpm10`). That image copies browser binaries out of a pinned
+ * `playwright:v<version>-noble` image and sets `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`, because the DC4
+ * proxy blocks `cdn.playwright.dev`. CI therefore cannot fetch a browser it was not built with, and
+ * Playwright resolves browsers by revision-stamped directory (`chromium-<revision>`) with one exact
+ * revision per release — so a version difference of any size, including a patch, is a hard failure.
+ *
+ * Changing the Playwright version is a coordinated, ordered change:
+ *   1. bump `ARG PLAYWRIGHT_VERSION` in `pui-nodejs-docker@22.x-pnpm10`
+ *   2. merge it and let Jenkins publish the image
+ *   3. bump the catalog pins and this constant together, in one commit
+ *
+ * Step 1 is also the availability constraint: the Artifactory docker mirror for the Playwright base
+ * image is curated rather than pull-through, so only tags already mirrored there can be built
+ * against, which can lag npm by several releases.
+ */
+export const CI_IMAGE_PLAYWRIGHT_VERSION = '1.61.1';
+
+export const CI_IMAGE_NAME = 'docker-local/nodejs22pnpm10';
+export const CI_IMAGE_SOURCE = 'pui-nodejs-docker@22.x-pnpm10';
+
+/** Set to any truthy value to downgrade the mismatch to a warning. Ignored under CI, where a
+ * mismatch is not a judgement call — the browsers genuinely are not in the image. */
+export const OVERRIDE_ENV_VAR = 'DS_PLAYWRIGHT_ALLOW_CI_IMAGE_MISMATCH';
+
+const readResolvedPlaywrightVersion = () => localRequire('@playwright/experimental-ct-react/package.json').version;
+
+// browsers.json is not in playwright-core's exports map, so resolve the package and read alongside.
+const readResolvedChromiumRevision = () => {
+  try {
+    const coreDir = path.dirname(localRequire.resolve('playwright-core/package.json'));
+    const { browsers } = JSON.parse(fs.readFileSync(path.join(coreDir, 'browsers.json'), 'utf8'));
+    return browsers.find(({ name }) => name === 'chromium')?.revision ?? null;
+  } catch {
+    return null;
+  }
+};
+
+const buildMismatchMessage = (resolvedVersion) => {
+  const revision = readResolvedChromiumRevision();
+  const resolvedDetail = revision ? `${resolvedVersion} (chromium-${revision})` : resolvedVersion;
+  return [
+    'Playwright is out of contract with the CI image.',
+    '',
+    `  this workspace resolves   ${resolvedDetail}`,
+    `  ${CI_IMAGE_NAME} pre-installs ${CI_IMAGE_PLAYWRIGHT_VERSION}`,
+    '',
+    'The Playwright version must match the CI image exactly or Jenkins will fail. Component tests',
+    'run inside that image with PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 and cannot download browsers, so',
+    'this passes locally and fails in CI. Patch differences count: each release expects one exact',
+    'browser revision.',
+    '',
+    'Changing the Playwright version requires coordination with the docker image, in this order:',
+    `  1. bump ARG PLAYWRIGHT_VERSION in ${CI_IMAGE_SOURCE}`,
+    '  2. merge it and let Jenkins publish the image',
+    '  3. bump the catalog pins in pnpm-workspace.yaml and CI_IMAGE_PLAYWRIGHT_VERSION together',
+    '',
+    'Note that the Artifactory docker mirror for the Playwright base image is curated, not',
+    'pull-through, so the newest version on npm may not be buildable yet.',
+    '',
+    `To proceed anyway on this machine: ${OVERRIDE_ENV_VAR}=1 (has no effect under CI).`,
+  ].join('\n');
+};
+
+/**
+ * Throws when the resolved Playwright version differs from the one the CI image ships.
+ *
+ * Deliberately unconditional rather than gated on "are the browsers missing?". The Playwright
+ * browser cache is machine-global and accumulates revisions forever, so a developer who bumps the
+ * version usually already has the new revision cached — an install-triggered check would stay
+ * silent for exactly the person about to break CI.
+ */
+export function assertPlaywrightMatchesCiImage() {
+  const resolvedVersion = readResolvedPlaywrightVersion();
+  if (resolvedVersion === CI_IMAGE_PLAYWRIGHT_VERSION) return;
+
+  const message = buildMismatchMessage(resolvedVersion);
+  if (process.env[OVERRIDE_ENV_VAR] && !process.env.CI) {
+    console.warn(message);
+    return;
+  }
+  const error = new Error(message);
+  // Playwright prints the stack of a config-load failure verbatim. The frames are noise here — the
+  // fault is a version pin, not a code path — and they push the instructions off a short terminal.
+  error.stack = message;
+  throw error;
+}

package/configs/playwright/playwright-component-testing-config.mjs

@@ -1,10 +1,35 @@
 import { defineConfig, devices } from '@playwright/experimental-ct-react';
-// import { defineConfig as viteDefineConfig } from 'vite';
-// import react from '@vitejs/plugin-react';
+import { findMonoRepoRoot } from '../jest/testing/utils.cjs';
+import { assertPlaywrightMatchesCiImage } from './ci-image-contract.mjs';
+
+// Every component-testing package re-exports this config, so this is the one place every `playwright
+// test` invocation passes through. Skipped when SKIP_PLAYWRIGHT=1 disables testMatch below: no tests
+// run, so no browser is needed and the contract does not apply.
+if (process.env.SKIP_PLAYWRIGHT !== '1') assertPlaywrightMatchesCiImage();
+import { resolvePinnedStyledComponents } from '../resolve-pinned-styled-components.cjs';
+
+// Shared with the Jest base config and .storybook/main.jsx — see
+// configs/resolve-pinned-styled-components.cjs for the full rationale. Short version:
+// styled-components@5.3.11 resolves to two pnpm store instances (pnpm/pnpm#11834), which means
+// two ThemeContext objects, which means ThemeProvider from one instance is invisible to styled()
+// calls resolved through the other. This is the Playwright component-testing runtime's own
+// internal Vite instance, which neither the Jest moduleNameMapper nor the Storybook/Portal/
+// react-18-vite resolve.alias entries cover — it needs its own alias.
+//
+// NOTE: Playwright CT caches its built bundle in `playwright/.cache`, and changing this alias
+// does NOT invalidate that cache. Clear it (`pnpm run clean`, or rimraf **/playwright/.cache)
+// or a change here will silently do nothing.
+const resolvePinnedStyledComponentsAliases = () => {
+  const { styledComponentsPath, xstyledStyledComponentsPath } = resolvePinnedStyledComponents(process.cwd());
+  return {
+    'styled-components': styledComponentsPath,
+    '@xstyled/styled-components': xstyledStyledComponentsPath,
+  };
+};
 
 export const config = defineConfig({
   testDir: './src/tests',
-  testMatch: '**/*.test.playwright.@(js|jsx|ts|tsx)',
+  testMatch: process.env.SKIP_PLAYWRIGHT === '1' ? [] : '**/*.test.playwright.@(js|jsx|ts|tsx)',
   snapshotDir: './__snapshots__',
   timeout: 10 * 1000,
   fullyParallel: process.env.CI ? false : true,
@@ -15,13 +40,21 @@ export const config = defineConfig({
   workers: process.env.CI ? 1 : undefined,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
   reporter: 'list',
-  // ctViteConfig: viteDefineConfig({ logLevel: 'info', plugins: [react()] }),
   use: {
     ctPort: 31500,
     headless: process.env.CI || process.env.PW_HEADLESS ? true : false,
     launchOptions: {
       devtools: process.env.CI || process.env.PW_HEADLESS ? false : true,
     },
+    // Note: ctViteConfig deep-merges with Playwright's own base/framework Vite config (see
+    // experimental-ct-core/lib/viteUtils.js — mergeConfig, then frameworkOverrides applied after).
+    // Do not add a `plugins` entry here — the React plugin is injected separately via
+    // frameworkOverrides regardless of what's passed here, so re-adding it would register it twice.
+    ctViteConfig: {
+      resolve: {
+        alias: resolvePinnedStyledComponentsAliases(),
+      },
+    },
   },
   projects: [
     {

package/configs/resolve-pinned-styled-components.cjs

@@ -0,0 +1,106 @@
+/**
+ * Single source of truth for the styled-components / @xstyled/styled-components pinning.
+ *
+ * WHY THIS EXISTS
+ * styled-components@5.3.11 currently resolves to two different pnpm store instances (one paired
+ * with react-is@18.3.1, one with react-is@19.2.8 — see pnpm/pnpm#11834:
+ * dedupePeerDependents fails to collapse peer-cyclic packages like
+ * styled-components <-> babel-plugin-styled-components). @xstyled/styled-components (used by
+ * ds-system's styled() wrapper and by themeProviderHOC for theme merging) inherits that split
+ * per-consumer. Two module instances means two separate Context objects, so ThemeProvider from
+ * one instance is invisible to styled() calls resolved through the other — which is what
+ * actually breaks theme merging (not react-is itself). Every consumer (Jest, Storybook/Vite,
+ * Playwright CT, the portal, react-18-vite) must alias both packages onto the single instance
+ * built against react-is@18.3.1.
+ *
+ * WHY IT IS SHARED
+ * This logic previously existed as five hand-copied duplicates. They drifted in lockstep and all
+ * five broke on Windows in the same way (see below), which is exactly the failure mode a shared
+ * module prevents.
+ *
+ * WHY IT MATCHES ON REALPATH, NOT ON DIRECTORY NAMES
+ * The previous implementation matched on the *name* of the pnpm virtual-store directory:
+ * `e.includes('_react-is@18.3.1_')` and `e.startsWith('@xstyled+styled-components@3.8.1')`.
+ * pnpm defaults `virtual-store-dir-max-length` to 120 on Linux/macOS but **60 on Windows**
+ * (to stay under MAX_PATH). At 60 characters the peer suffix is truncated away and replaced by
+ * a hash — `styled-components@5.3.11_@b_0a4e3f58…`, `@xstyled+styled-components@_7aca0cfd…` —
+ * so both predicates matched zero entries, the resolver returned null, the aliases were
+ * silently dropped, and every themed component rendered with `theme = {}`.
+ * Resolving through `fs.realpathSync` instead is immune to how pnpm names its directories.
+ *
+ * WHY IT THROWS
+ * Returning null on failure turns a broken workaround into a silent behaviour change: the
+ * symptom is dozens of confusing "Cannot read properties of undefined (reading 'small')"
+ * render errors, a long way from the cause. Failing loudly here is the whole point.
+ */
+const fs = require('fs');
+const path = require('path');
+const { findMonoRepoRoot } = require('./jest/testing/utils.cjs');
+
+const STYLED_COMPONENTS_PREFIX = 'styled-components@5.3.11';
+const XSTYLED_PREFIX = '@xstyled+styled-components@';
+const PINNED_REACT_IS = 'react-is@18.3.1';
+
+/** `fs.realpathSync` that returns null instead of throwing on a missing path. */
+const realpathOrNull = (target) => {
+  try {
+    return fs.realpathSync(target);
+  } catch (_) {
+    return null;
+  }
+};
+
+/**
+ * Resolve the single styled-components / @xstyled-styled-components pair that both build
+ * against react-is@18.3.1.
+ *
+ * @param {string} [cwd] directory to start the monorepo-root search from
+ * @returns {{styledComponentsPath: string, xstyledStyledComponentsPath: string}}
+ * @throws if the pair cannot be resolved — never returns a partial or empty result
+ */
+const resolvePinnedStyledComponents = (cwd = process.cwd()) => {
+  const monorepoRoot = findMonoRepoRoot(cwd);
+  if (!monorepoRoot) throw new Error(`Could not locate the monorepo root from "${cwd}"`);
+
+  const pnpmDir = path.join(monorepoRoot, 'node_modules', '.pnpm');
+  if (!fs.existsSync(pnpmDir)) throw new Error(`pnpm virtual store not found at "${pnpmDir}" — run \`pnpm i\` first`);
+
+  const entries = fs.readdirSync(pnpmDir);
+
+  // Match on what the directory *is* (which react-is it links to), not on what it is *named* —
+  // pnpm truncates these names to 60 characters on Windows.
+  const scEntry = entries.find((entry) => {
+    if (!entry.startsWith(STYLED_COMPONENTS_PREFIX)) return false;
+    const reactIs = realpathOrNull(path.join(pnpmDir, entry, 'node_modules', 'react-is'));
+    return Boolean(reactIs) && reactIs.includes(PINNED_REACT_IS);
+  });
+  if (!scEntry) {
+    throw new Error(
+      `Could not find a ${STYLED_COMPONENTS_PREFIX} instance built against ${PINNED_REACT_IS} in "${pnpmDir}".\n` +
+        `  candidates: ${entries.filter((e) => e.startsWith(STYLED_COMPONENTS_PREFIX)).join(', ') || '(none)'}\n` +
+        `  Without this pin, ThemeProvider and styled() resolve to different module instances ` +
+        `and every themed component renders with an empty theme.`,
+    );
+  }
+
+  const styledComponentsPath = path.join(pnpmDir, scEntry, 'node_modules', 'styled-components');
+  const scRealPath = fs.realpathSync(styledComponentsPath);
+
+  const xscEntry = entries
+    .filter((entry) => entry.startsWith(XSTYLED_PREFIX))
+    .find((entry) => realpathOrNull(path.join(pnpmDir, entry, 'node_modules', 'styled-components')) === scRealPath);
+  if (!xscEntry) {
+    throw new Error(
+      `Found ${scEntry} but no ${XSTYLED_PREFIX}* instance bundling the same styled-components copy.\n` +
+        `  looking for a nested styled-components resolving to: ${scRealPath}\n` +
+        `  candidates: ${entries.filter((e) => e.startsWith(XSTYLED_PREFIX)).join(', ') || '(none)'}`,
+    );
+  }
+
+  return {
+    styledComponentsPath,
+    xstyledStyledComponentsPath: path.join(pnpmDir, xscEntry, 'node_modules', '@xstyled', 'styled-components'),
+  };
+};
+
+module.exports = { resolvePinnedStyledComponents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-monorepo-devops",
-  "version": "3.70.0-next.6",
+  "version": "3.70.0-next.60",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Monorepo Devops",
   "type": "module",
@@ -24,6 +24,14 @@
     "./configs/playwright/playwright-component-testing-config": {
       "import": "./configs/playwright/playwright-component-testing-config.mjs",
       "require": "./configs/playwright/playwright-component-testing-config.mjs"
+    },
+    "./configs/playwright/ci-image-contract": {
+      "import": "./configs/playwright/ci-image-contract.mjs",
+      "require": "./configs/playwright/ci-image-contract.mjs"
+    },
+    "./configs/resolve-pinned-styled-components": {
+      "import": "./configs/resolve-pinned-styled-components.cjs",
+      "require": "./configs/resolve-pinned-styled-components.cjs"
     }
   },
   "sideEffects": [],
@@ -93,7 +101,7 @@
     "typeSafety": false
   },
   "dependencies": {
-    "@playwright/experimental-ct-react": "^1.51.1"
+    "@playwright/experimental-ct-react": "1.61.1"
   },
   "scripts": {}
-}
+}