test(shadow-styles): enforce import list sync + soft-fail optional peers

Add a regression script that diffs SHADOW_STYLE_IMPORTS against
non-relative *.css imports under packages/editor/src/**, so a future
extension addition cannot silently leave shadow-styles cssText stale
behind a green CI. Wired as a separate ci:test:shadow-styles job
mirroring the circular-deps check.

Wrap require.resolve() for shadow-styles externals in a try/catch:
optional peer packages (per peerDependenciesMeta) are skipped with a
warning instead of crashing the build for consumers that don't install
them. Required peers still throw.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: makhnatkin

.github/workflows/ci.yml

@@ -77,3 +77,25 @@ jobs:
 
       - name: Check circular dependencies
         run: pnpm ci:test:circular-deps
+
+  check_shadow_styles_imports:
+    name: Check Shadow Styles Imports
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm run ci:deps
+
+      - name: Check shadow styles imports
+        run: pnpm ci:test:shadow-styles

package.json

@@ -25,11 +25,12 @@
     "ci:test:unit": "nx run-many -t test --verbose",
     "ci:test:esbuild": "nx run-many -t test:esbuild --verbose",
     "ci:test:circular-deps": "nx run-many -t test:circular-deps --verbose",
+    "ci:test:shadow-styles": "nx run-many -t test:shadow-styles --verbose",
     "start": "nx sb:start @markdown-editor/demo",
     "clean": "nx run-many -t clean",
     "build": "nx run-many -t build",
     "typecheck": "nx run-many -t typecheck",
-    "test": "nx run-many -t test,test:esbuild,test:circular-deps",
+    "test": "nx run-many -t test,test:esbuild,test:circular-deps,test:shadow-styles",
     "test:e2e": "nx playwright:docker @markdown-editor/demo",
     "test:e2e:report": "nx playwright:docker:report @markdown-editor/demo",
     "lint": "run-p -cs lint:*",

packages/editor/gulpfile.mjs

@@ -14,7 +14,8 @@ const require = createRequire(import.meta.url);
 const BUILD_DIR = resolve('build');
 const NODE_MODULES_DIR = resolve(__dirname, 'node_modules');
 // Keep this list aligned with non-relative CSS imports required by the default editor setup.
-const SHADOW_STYLE_IMPORTS = Object.freeze([
+// Drift is enforced by scripts/check-shadow-styles-imports.js.
+export const SHADOW_STYLE_IMPORTS = Object.freeze([
     '@diplodoc/transform/dist/css/base.css',
     '@diplodoc/transform/dist/css/_yfm-only.css',
     '@diplodoc/cut-extension/runtime/styles.css',
@@ -24,6 +25,12 @@ const SHADOW_STYLE_IMPORTS = Object.freeze([
     '@diplodoc/folding-headings-extension/runtime/styles.css',
 ]);
 
+const OPTIONAL_PEERS = new Set(
+    Object.entries(pkg.peerDependenciesMeta ?? {})
+        .filter(([, meta]) => meta?.optional)
+        .map(([name]) => name),
+);
+
 registerBuildTasks({
     version: pkg.version,
     buildDir: BUILD_DIR,
@@ -53,9 +60,28 @@ task('build', series(parallel('ts', 'json', 'scss'), 'shadow-styles'));
 task('default', series('clean', 'build'));
 
 function readExternalShadowStyles() {
-    return SHADOW_STYLE_IMPORTS.map((cssImport) =>
-        readFileSync(require.resolve(cssImport), 'utf8'),
-    ).join('\n');
+    return SHADOW_STYLE_IMPORTS.map((cssImport) => {
+        try {
+            return readFileSync(require.resolve(cssImport), 'utf8');
+        } catch (err) {
+            if (err?.code === 'MODULE_NOT_FOUND' && isOptionalPeerImport(cssImport)) {
+                console.warn(
+                    `[shadow-styles] Skipping optional peer CSS '${cssImport}' (package not installed).`,
+                );
+                return '';
+            }
+            throw err;
+        }
+    })
+        .filter(Boolean)
+        .join('\n');
+}
+
+function isOptionalPeerImport(cssImport) {
+    const pkgName = cssImport.startsWith('@')
+        ? cssImport.split('/', 2).join('/')
+        : cssImport.split('/', 1)[0];
+    return OPTIONAL_PEERS.has(pkgName);
 }
 
 function createShadowStylesModule(value) {

packages/editor/package.json

@@ -27,6 +27,7 @@
     "test:watch": "jest --watchAll",
     "test:esbuild": "node tests/esbuild-test/esbuild-tester.js",
     "test:circular-deps": "node scripts/check-circular-deps.js 0",
+    "test:shadow-styles": "node scripts/check-shadow-styles-imports.js",
     "prepack": "cp ../../README.md ./README.md",
     "postpack": "rm -f ./README.md",
     "prepublishOnly": "pnpm run lint && pnpm run clean && pnpm run build"

packages/editor/scripts/check-shadow-styles-imports.js

@@ -0,0 +1,70 @@
+/* eslint-disable no-console, no-undef */
+const fs = require('node:fs');
+const path = require('node:path');
+const {pathToFileURL} = require('node:url');
+
+const SRC_DIR = path.resolve(__dirname, '..', 'src');
+const GULPFILE_URL = pathToFileURL(path.resolve(__dirname, '..', 'gulpfile.mjs')).href;
+
+// Bare `import 'pkg/path/file.css';` — non-relative, scoped or unscoped, ending in .css.
+const CSS_IMPORT_RE = /(?:^|\s)import\s+['"]((?:@[^'"\s/]+\/)?[^'"\s.][^'"\s]*\.css)['"]/gm;
+
+const EXCLUDED_SCOPES = ['@gravity-ui/'];
+
+async function main() {
+    const {SHADOW_STYLE_IMPORTS} = await import(GULPFILE_URL);
+    if (!Array.isArray(SHADOW_STYLE_IMPORTS)) {
+        console.error('Failed to import SHADOW_STYLE_IMPORTS from gulpfile.mjs');
+        process.exit(1);
+    }
+
+    const declared = new Set(SHADOW_STYLE_IMPORTS);
+    const actual = collectCssImports(SRC_DIR);
+
+    const missing = [...actual].filter((x) => !declared.has(x)).sort();
+    const stale = [...declared].filter((x) => !actual.has(x)).sort();
+
+    if (missing.length || stale.length) {
+        console.error('Shadow styles imports drift detected:');
+        if (missing.length) {
+            console.error('  Missing in SHADOW_STYLE_IMPORTS (found in src, not in list):');
+            for (const item of missing) console.error(`    + ${item}`);
+        }
+        if (stale.length) {
+            console.error('  Stale in SHADOW_STYLE_IMPORTS (in list, not used in src):');
+            for (const item of stale) console.error(`    - ${item}`);
+        }
+        console.error('Update SHADOW_STYLE_IMPORTS in packages/editor/gulpfile.mjs.');
+        process.exit(1);
+    }
+
+    console.log(`Shadow styles imports check passed (count: ${declared.size})`);
+    process.exit(0);
+}
+
+function collectCssImports(dir) {
+    const result = new Set();
+    walk(dir, (filePath) => {
+        if (!/\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(filePath)) return;
+        const content = fs.readFileSync(filePath, 'utf8');
+        for (const match of content.matchAll(CSS_IMPORT_RE)) {
+            const spec = match[1];
+            if (EXCLUDED_SCOPES.some((scope) => spec.startsWith(scope))) continue;
+            result.add(spec);
+        }
+    });
+    return result;
+}
+
+function walk(dir, visit) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full, visit);
+        else if (entry.isFile()) visit(full);
+    }
+}
+
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});