fix: cascade-layer order

CSS cascade-layer priority is locked in by the first mention of each
layer name. With the order statement living at the top of
`shell/style.scss`, other shell SCSS files reached earlier by webpack's
import traversal were registering `shell` before `paragon` and inverting
the intended order. Move the declaration to its own
`shell/layer-order.scss`, loaded first via a dedicated webpack entry.

Also classify named packages by package.json name, where possible.
This makes it more flexible (so that it applies to workspaces, for
instance).

Fixes #246.

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

Author: arbrandes

docs/decisions/0008-stylesheet-import-in-site-config.md

@@ -34,7 +34,7 @@ The build pipeline wraps each stylesheet in a CSS cascade layer based on the res
 | `site`    | stylesheets outside `node_modules` (the composing site's source)  |
 | `brand`   | `@(open)?edx/brand*` packages                                     |
 
-The order declared at the top of `shell/style.scss` is `@layer paragon, shell, app, site, brand;` so the cascade resolves in that order: `brand` wins over `site`, `site` wins over `app`, `app` wins over `shell`, and `shell` wins over `paragon`.
+The order is declared in `shell/layer-order.scss` as `@layer paragon, shell, app, site, brand;`, so the cascade resolves in that order: `brand` wins over `site`, `site` wins over `app`, `app` wins over `shell`, and `shell` wins over `paragon`.
 
 `brand` is last because, in production, brand CSS is injected at runtime via `<link>` tags that bypass webpack entirely and therefore land **unlayered**. Unlayered rules beat every layered rule regardless of declared order, so runtime brand wins over the site's own CSS. Putting build-time brand imports (e.g. a dev harness that `@use`s a brand package directly) in the last layer keeps dev harness behavior consistent with production: brand overrides apply on top of everything the site declares.
 

package.json

@@ -9,6 +9,7 @@
     ".": "./dist/index.js",
     "./tools": "./dist/tools/index.js",
     "./tools/tsconfig.json": "./dist/tools/typescript/tsconfig.json",
+    "./shell/layer-order.scss": "./dist/shell/layer-order.scss",
     "./shell/style": "./dist/shell/style.js",
     "./shell/site": "./dist/shell/site.js"
   },

shell/layer-order.scss

@@ -0,0 +1 @@
+@layer paragon, shell, app, site, brand;

shell/style.scss

@@ -1,5 +1,3 @@
-@layer paragon, shell, app, site, brand;
-
 .flex-basis-0 {
   flex-basis: 0 !important;
 }

tools/webpack/common-config/all/getStylesheetRule.test.ts

@@ -0,0 +1,41 @@
+import {
+  APP_RESOURCE,
+  BRAND_PACKAGE,
+} from './getStylesheetRule';
+
+describe('stylesheet classification', () => {
+  describe('BRAND_PACKAGE', () => {
+    const re = BRAND_PACKAGE.name as RegExp;
+
+    it('matches @openedx/brand-*', () => {
+      expect(re.test('@openedx/brand-openedx')).toBe(true);
+    });
+
+    it('matches @edx/brand-*', () => {
+      expect(re.test('@edx/brand-foo')).toBe(true);
+    });
+
+    it('matches bare @openedx/brand', () => {
+      expect(re.test('@openedx/brand')).toBe(true);
+    });
+
+    it('does not match unrelated scoped packages', () => {
+      expect(re.test('@openedx/paragon')).toBe(false);
+      expect(re.test('@openedx/branding')).toBe(false);
+    });
+  });
+
+  describe('APP_RESOURCE', () => {
+    it('matches a node_modules path', () => {
+      expect(APP_RESOURCE.test('/site/node_modules/some-pkg/index.js')).toBe(true);
+    });
+
+    it('matches an npm-workspace packages path', () => {
+      expect(APP_RESOURCE.test('/site/packages/some-pkg/index.js')).toBe(true);
+    });
+
+    it('does not match a site source path', () => {
+      expect(APP_RESOURCE.test('/site/src/component.scss')).toBe(false);
+    });
+  });
+});

tools/webpack/common-config/all/getStylesheetRule.ts

@@ -21,10 +21,11 @@ import postcssWrapLayer from './postcssWrapLayer';
  *            precedence of runtime brand CSS (which is injected unlayered via
  *            <link> tags and thus beats every layered rule).
  */
-const PARAGON_RESOURCE = /@openedx[\\/]paragon[\\/]/;
-const SHELL_RESOURCE = /(@openedx[\\/]frontend-base|frontend-base[\\/]shell)[\\/]/;
-const BRAND_RESOURCE = /@(open)?edx[\\/]brand(-[^\\/]+)?[\\/]/;
-const NODE_MODULES = /[\\/]node_modules[\\/]/;
+export const PARAGON_PACKAGE = { name: '@openedx/paragon' };
+export const SHELL_PACKAGE = { name: '@openedx/frontend-base' };
+export const BRAND_PACKAGE = { name: /^@(open)?edx\/brand(-.+)?$/ };
+// The site/app split is positional (my project vs. a dep), so it is path-based.
+export const APP_RESOURCE = /[\\/](node_modules|packages)[\\/]/;
 
 /*
  * There are a few things we need to do here.
@@ -40,7 +41,7 @@ export default function getStylesheetRule(mode: 'dev' | 'production'): RuleSetRu
     test: /(.scss|.css)$/,
     oneOf: [
       {
-        resource: PARAGON_RESOURCE,
+        descriptionData: PARAGON_PACKAGE,
         // We need Paragon to not elide CSS: we have to be able to import it
         // directly from shell/style.ts
         sideEffects: true,
@@ -50,21 +51,21 @@ export default function getStylesheetRule(mode: 'dev' | 'production'): RuleSetRu
         ],
       },
       {
-        resource: SHELL_RESOURCE,
+        descriptionData: SHELL_PACKAGE,
         use: [
           MiniCssExtractPlugin.loader,
           ...getStyleUseConfig(mode, 'shell'),
         ],
       },
       {
-        resource: BRAND_RESOURCE,
+        descriptionData: BRAND_PACKAGE,
         use: [
           MiniCssExtractPlugin.loader,
           ...getStyleUseConfig(mode, 'brand'),
         ],
       },
       {
-        resource: { not: [NODE_MODULES] },
+        resource: { not: [APP_RESOURCE] },
         use: [
           getFirstLoader(mode),
           ...getStyleUseConfig(mode, 'site'),

tools/webpack/common-config/site/getHtmlWebpackPlugin.ts

@@ -1,11 +1,19 @@
 import HtmlWebpackPlugin from 'html-webpack-plugin';
 import path from 'path';
 
-// Generates an HTML file in the output directory.
+/*
+ * Generates an HTML file in the output directory.
+ *
+ * `layerOrder` is listed first so its <link> is injected before any other
+ * stylesheet. That file contains the `@layer paragon, shell, app, site, brand;`
+ * statement, which locks in cascade-layer priority before any layer name is
+ * mentioned by the rest of the CSS the browser parses.
+ */
 export default function getHtmlWebpackPlugin() {
   return new HtmlWebpackPlugin({
-    inject: true, // Appends script tags linking to the webpack bundles at the end of the body
+    inject: true,
     template: path.resolve(process.cwd(), 'public/index.html'),
-    chunks: ['app'],
+    chunks: ['layerOrder', 'app'],
+    chunksSortMode: 'manual',
   });
 }

tools/webpack/webpack.config.build.ts

@@ -26,6 +26,7 @@ const config: Configuration = {
   mode: 'production',
   devtool: 'source-map',
   entry: {
+    layerOrder: '@openedx/frontend-base/shell/layer-order.scss',
     app: '@openedx/frontend-base/shell/site',
   },
   output: {

tools/webpack/webpack.config.dev.shell.ts

@@ -24,6 +24,7 @@ const resolvedSiteI18nPath = getResolvedSiteI18nPath('test-site/src/i18n');
 
 const config: Configuration = {
   entry: {
+    layerOrder: path.resolve(process.cwd(), 'shell/layer-order.scss'),
     app: path.resolve(process.cwd(), 'shell/site'),
   },
   output: {
@@ -90,9 +91,10 @@ const config: Configuration = {
       filename: '[name].css',
     }),
     new HtmlWebpackPlugin({
-      inject: true, // Appends script tags linking to the webpack bundles at the end of the body
+      inject: true,
       template: path.resolve(process.cwd(), 'shell/public/index.html'),
-      chunks: ['app'],
+      chunks: ['layerOrder', 'app'],
+      chunksSortMode: 'manual',
     }),
     new ReactRefreshWebpackPlugin(),
     new ForkTsCheckerWebpackPlugin(),

tools/webpack/webpack.config.dev.ts

@@ -25,6 +25,7 @@ const resolvedSiteI18nPath = getResolvedSiteI18nPath('src/i18n');
 
 const config: Configuration = {
   entry: {
+    layerOrder: '@openedx/frontend-base/shell/layer-order.scss',
     app: '@openedx/frontend-base/shell/site',
   },
   output: {