@openmrs/carbon-css-guard 10.0.1-pre.5378

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A webpack/rspack plugin that fails a build whose emitted CSS restyles the page as a whole rather
+ * than the module's own markup.
+ *
+ * Carbon's stylesheet is delivered exactly once, by the app shell (frontend RFC 0033). What separates
+ * a supported override from a page-wide one is the selector's anchor. `.myThing :global(.cds--btn)`
+ * scopes the override to this module and is how a visual fix through Carbon's classes gets made; a
+ * selector anchored on Carbon alone — `:global(.cds--btn)`, `[dir=rtl] :global(.cds--css-grid-column)`
+ * — reaches every Carbon component on the page, including other modules'. A selector with no class or
+ * id to anchor it at all, such as the `html, body, div { … }` of Carbon's reset, is broader still.
+ *
+ * These arrive by `@use`-ing `@carbon/styles`, one of its resets, or an individual component's
+ * stylesheet, rather than just Carbon's tokens, mixins, and functions, which emit no CSS.
+ *
+ * The scanner reads emitted, minified CSS rather than source, because that is what actually ships and
+ * because the many valid ways to import a Carbon token defeat checking imports at the source level.
+ */
+/**
+ * The subset of a compilation this plugin needs. Declaring it structurally, rather than importing
+ * either bundler's types, is what lets one implementation serve both — and makes a bundler that stops
+ * supplying these a compile error here rather than a guard that silently sees nothing.
+ */
+interface Compilation {
+    errors: Array<Error>;
+    hooks: {
+        processAssets: {
+            tap(options: {
+                name: string;
+                stage: number;
+            }, callback: (assets: Record<string, Source>) => void): void;
+        };
+    };
+}
+interface Source {
+    source(): string | Buffer;
+}
+interface Compiler {
+    /** Both bundlers expose their own namespace here; rspack sets `webpack` too, for compatibility. */
+    rspack?: {
+        Compilation: {
+            PROCESS_ASSETS_STAGE_REPORT: number;
+        };
+    };
+    webpack?: {
+        Compilation: {
+            PROCESS_ASSETS_STAGE_REPORT: number;
+        };
+    };
+    hooks: {
+        compilation: {
+            tap(name: string, callback: (compilation: Compilation) => void): void;
+        };
+    };
+}
+/**
+ * Returns the distinct selectors in `css` that restyle the page rather than the module's own markup.
+ *
+ * Only rules that aren't nested inside another style rule are considered: native CSS nesting puts the
+ * scoping class on the parent, so `.myThing { .cds--btn { … } }` is a correctly scoped override even
+ * though the inner selector reads as a bare Carbon one. Rules nested in an at-rule — `@media`,
+ * `@supports`, `@layer` — are considered, since those don't scope anything; those inside `@scope`,
+ * which does, are not.
+ *
+ * @param css The contents of an emitted stylesheet
+ */
+export declare function findGlobalCarbonRules(css: string): Array<string>;
+/**
+ * Builds the failure reported to the developer.
+ *
+ * @param appName The module being built, named as it appears in its `package.json`
+ * @param offences The offending selectors found, keyed by the asset each was found in
+ */
+export declare function buildGlobalCarbonRuleError(appName: string, offences: Map<string, Array<string>>): Error;
+/**
+ * Fails the build if any emitted stylesheet restyles the page as a whole. Runs at the reporting stage,
+ * late enough to see minified output, so it checks the CSS that actually ships.
+ *
+ * Only meaningful in a build that extracts CSS: under `style-loader` there are no `.css` assets to
+ * read, so the shared configs add this in production only.
+ */
+export declare class CarbonCssGuardPlugin {
+    private readonly appName;
+    /**
+     * @param appName The module being built, named as it appears in its `package.json`
+     */
+    constructor(appName: string);
+    apply(compiler: Compiler): void;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * A webpack/rspack plugin that fails a build whose emitted CSS restyles the page as a whole rather
+ * than the module's own markup.
+ *
+ * Carbon's stylesheet is delivered exactly once, by the app shell (frontend RFC 0033). What separates
+ * a supported override from a page-wide one is the selector's anchor. `.myThing :global(.cds--btn)`
+ * scopes the override to this module and is how a visual fix through Carbon's classes gets made; a
+ * selector anchored on Carbon alone — `:global(.cds--btn)`, `[dir=rtl] :global(.cds--css-grid-column)`
+ * — reaches every Carbon component on the page, including other modules'. A selector with no class or
+ * id to anchor it at all, such as the `html, body, div { … }` of Carbon's reset, is broader still.
+ *
+ * These arrive by `@use`-ing `@carbon/styles`, one of its resets, or an individual component's
+ * stylesheet, rather than just Carbon's tokens, mixins, and functions, which emit no CSS.
+ *
+ * The scanner reads emitted, minified CSS rather than source, because that is what actually ships and
+ * because the many valid ways to import a Carbon token defeat checking imports at the source level.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CarbonCssGuardPlugin = void 0;
+exports.findGlobalCarbonRules = findGlobalCarbonRules;
+exports.buildGlobalCarbonRuleError = buildGlobalCarbonRuleError;
+/**
+ * What can confine a rule to markup this module owns: class and id tokens (`.cds--btn`, `#main`,
+ * `.a\\:b`), plus an attribute selector naming a specific extension or slot
+ * (`[data-extension-id='my-thing']`).
+ *
+ * Extension wrappers are rendered by the framework, so an app has nowhere to put a class of its own on
+ * them; the attribute's value is what makes the rule specific, exactly as a class would. It has to be a
+ * value test — a bare `[data-extension-id]` matches every extension on the page and anchors nothing.
+ */
+const anchorPattern = /[.#](?:[-\w]|\\.)+|\[data-extension-[\w-]*[~^|*$]?=[^\]]*\]/g;
+/**
+ * Carbon's class prefix, matched only where a selector starts with it. The shared configs run every
+ * stylesheet through CSS Modules, so a Carbon class reaches the page verbatim only when the module
+ * wrote it inside `:global`; anything else is renamed to `.-esm-login__footer__cds--btn___1a2b3` and
+ * can no longer restyle the shell's Carbon.
+ */
+const carbonPrefix = '.cds--';
+/**
+ * Exempt from the anchorless rule. `:root` and `:host` carry custom properties, which add to the
+ * cascade rather than restyling anything, and are how a module contributes its own design tokens.
+ */
+const anchorlessExemptPattern = /^:(?:root|host)\b/;
+/** Ceiling on the `:is(…)`/`:where(…)` cross product, so a pathological selector can't stall a build. */
+const maxSelectorExpansions = 256;
+/**
+ * Blanks out comments and string literals so that braces, semicolons, and class-like text inside them
+ * can't be mistaken for CSS syntax by the (deliberately hand-rolled) scanner below.
+ */
+function stripNoise(css) {
+    let out = '';
+    let i = 0;
+    while (i < css.length) {
+        const char = css[i];
+        if (char === '/' && css[i + 1] === '*') {
+            const end = css.indexOf('*/', i + 2);
+            i = end === -1 ? css.length : end + 2;
+            out += ' ';
+        }
+        else if (char === '"' || char === "'") {
+            i += 1;
+            while (i < css.length && css[i] !== char) {
+                i += css[i] === '\\' ? 2 : 1;
+            }
+            i += 1;
+            out += '""';
+        }
+        else {
+            out += char;
+            i += 1;
+        }
+    }
+    return out;
+}
+/** Splits a selector list on its top-level commas, leaving those nested in `:not(…)` & friends alone. */
+function splitSelectorList(list) {
+    const selectors = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < list.length; i++) {
+        const char = list[i];
+        if (char === '(' || char === '[') {
+            depth += 1;
+        }
+        else if (char === ')' || char === ']') {
+            depth -= 1;
+        }
+        else if (char === ',' && depth === 0) {
+            selectors.push(list.slice(start, i));
+            start = i + 1;
+        }
+    }
+    selectors.push(list.slice(start));
+    return selectors;
+}
+/** The first `:is(…)` or `:where(…)` in `selector`, or `undefined` if it holds none. */
+function findSelectorListGroup(selector) {
+    const match = /:(?:is|where)\(/.exec(selector);
+    if (!match) {
+        return undefined;
+    }
+    let depth = 0;
+    for (let i = match.index + match[0].length - 1; i < selector.length; i++) {
+        if (selector[i] === '(') {
+            depth += 1;
+        }
+        else if (selector[i] === ')' && (depth -= 1) === 0) {
+            return { start: match.index, end: i + 1, inner: selector.slice(match.index + match[0].length, i) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Rewrites `:is(…)`/`:where(…)` into the plain selectors they stand for, so `.a:is(.b,.c)` becomes
+ * `.a.b` and `.a.c`.
+ *
+ * Without this a single anchored branch covers for the rest: `:is(.cds--btn, .myThing)` would read as
+ * anchored even though its first branch restyles every Carbon button on the page, while the equivalent
+ * `.cds--btn, .myThing` is caught. It matters for what gets built as much as for what gets written —
+ * Lightning CSS lowers native CSS nesting into `:is()` when the browserslist targets call for it, and
+ * this scanner reads minified output.
+ *
+ * The expansion is a cross product, so it is bounded. No selector in real stylesheets comes close; one
+ * that did would be left partly expanded and read as it is today, which is the behaviour this replaces.
+ */
+function expandSelectorLists(selector, budget = { left: maxSelectorExpansions }) {
+    const group = findSelectorListGroup(selector);
+    if (!group || budget.left <= 0) {
+        return [selector];
+    }
+    const branches = splitSelectorList(group.inner);
+    budget.left -= branches.length;
+    return branches.flatMap((branch) => expandSelectorLists(selector.slice(0, group.start) + branch.trim() + selector.slice(group.end), budget));
+}
+/**
+ * Removes `:not(…)` groups. A class inside a negation narrows which elements the rule skips; it never
+ * confines the rule to this module's markup, so `.cds--btn:not(.myThing)` is still a page-wide rule.
+ */
+function stripNegations(selector) {
+    let out = '';
+    for (let i = 0; i < selector.length; i++) {
+        if (!selector.startsWith(':not(', i)) {
+            out += selector[i];
+            continue;
+        }
+        let depth = 0;
+        for (i += 4; i < selector.length; i++) {
+            if (selector[i] === '(') {
+                depth += 1;
+            }
+            else if (selector[i] === ')' && (depth -= 1) === 0) {
+                break;
+            }
+        }
+    }
+    return out;
+}
+function classify(prelude) {
+    if (!prelude.startsWith('@')) {
+        return 'style';
+    }
+    if (/^@(?:-\w+-)?keyframes\b/.test(prelude)) {
+        return 'keyframes';
+    }
+    // `@scope (.card) { … }` confines everything inside it to the subtree its root selects, so its rules
+    // are local by definition however they read. The scoping root itself is not checked: an app that
+    // scopes to Carbon's own markup would still be reaching page-wide, which this does not catch.
+    return /^@scope\b/.test(prelude) ? 'scope' : 'at-rule';
+}
+/** Whether this single (comma-free) selector restyles the page rather than the module's own markup. */
+function isGlobal(selector) {
+    var _a;
+    const trimmed = selector.trim();
+    if (trimmed.length === 0) {
+        return false;
+    }
+    const anchors = (_a = stripNegations(trimmed).match(anchorPattern)) !== null && _a !== void 0 ? _a : [];
+    return anchors.length > 0
+        ? anchors.every((anchor) => anchor.startsWith(carbonPrefix))
+        : !anchorlessExemptPattern.test(trimmed);
+}
+/**
+ * Returns the distinct selectors in `css` that restyle the page rather than the module's own markup.
+ *
+ * Only rules that aren't nested inside another style rule are considered: native CSS nesting puts the
+ * scoping class on the parent, so `.myThing { .cds--btn { … } }` is a correctly scoped override even
+ * though the inner selector reads as a bare Carbon one. Rules nested in an at-rule — `@media`,
+ * `@supports`, `@layer` — are considered, since those don't scope anything; those inside `@scope`,
+ * which does, are not.
+ *
+ * @param css The contents of an emitted stylesheet
+ */
+function findGlobalCarbonRules(css) {
+    const globals = new Set();
+    const blocks = [];
+    let prelude = '';
+    for (const char of stripNoise(css)) {
+        if (char === '{') {
+            const kind = classify(prelude.trim());
+            if (kind === 'style' && !blocks.some((block) => block !== 'at-rule')) {
+                for (const selector of splitSelectorList(prelude)) {
+                    // Reported as written, not as expanded, so the message names something findable in the source.
+                    if (expandSelectorLists(selector).some(isGlobal)) {
+                        globals.add(selector.trim());
+                    }
+                }
+            }
+            blocks.push(kind);
+            prelude = '';
+        }
+        else if (char === '}') {
+            blocks.pop();
+            prelude = '';
+        }
+        else if (char === ';') {
+            // A declaration, or a statement at-rule such as `@import`; neither introduces a selector.
+            prelude = '';
+        }
+        else {
+            prelude += char;
+        }
+    }
+    return [...globals];
+}
+const pluginName = 'CarbonCssGuardPlugin';
+const maxReportedSelectors = 10;
+/**
+ * Builds the failure reported to the developer.
+ *
+ * @param appName The module being built, named as it appears in its `package.json`
+ * @param offences The offending selectors found, keyed by the asset each was found in
+ */
+function buildGlobalCarbonRuleError(appName, offences) {
+    const total = [...offences.values()].reduce((count, selectors) => count + selectors.length, 0);
+    const detail = [...offences]
+        .map(([asset, selectors]) => {
+        const shown = selectors.slice(0, maxReportedSelectors).map((selector) => `    ${selector}`);
+        const rest = selectors.length - shown.length;
+        return [`  ${asset}`, ...shown, ...(rest > 0 ? [`    …and ${rest} more`] : [])].join('\n');
+    })
+        .join('\n');
+    // The two cases have nothing to do with each other, and pointing someone who wrote `body { margin: 0 }`
+    // at their Carbon imports sends them looking in the wrong place entirely.
+    const selectors = [...offences.values()].flat();
+    const remedy = [
+        selectors.some((selector) => selector.includes(carbonPrefix))
+            ? 'Selectors naming Carbon classes usually come from SCSS that `@use`s `@carbon/styles`, one of its ' +
+                'resets, or an individual component stylesheet, instead of only its tokens, mixins, and functions, ' +
+                "which emit no CSS. To override Carbon from this module, anchor the selector to one of the module's " +
+                'own classes — `.myThing :global(.cds--btn)` rather than `:global(.cds--btn)`.'
+            : undefined,
+        selectors.some((selector) => !selector.includes(carbonPrefix))
+            ? 'Selectors with no class or id of their own — element, universal, or attribute selectors — apply to ' +
+                'the whole page, including other modules. Scope them to this module, e.g. `.myThing p` rather than ' +
+                '`p`, or move them to the app shell if they really are meant to be global.'
+            : undefined,
+    ].filter(Boolean);
+    return new Error(`${appName} emits ${total} global CSS rule(s). Carbon's CSS is delivered once, by the app shell, so ` +
+        `frontend modules must not restyle the page as a whole.\n\n${detail}\n\n${remedy.join('\n\n')}`);
+}
+/**
+ * Fails the build if any emitted stylesheet restyles the page as a whole. Runs at the reporting stage,
+ * late enough to see minified output, so it checks the CSS that actually ships.
+ *
+ * Only meaningful in a build that extracts CSS: under `style-loader` there are no `.css` assets to
+ * read, so the shared configs add this in production only.
+ */
+class CarbonCssGuardPlugin {
+    /**
+     * @param appName The module being built, named as it appears in its `package.json`
+     */
+    constructor(appName) {
+        this.appName = appName;
+    }
+    apply(compiler) {
+        var _a, _b, _c;
+        // Read off the compiler rather than imported, so this package needs a dependency on neither bundler.
+        const stage = (_c = (_b = ((_a = compiler.rspack) !== null && _a !== void 0 ? _a : compiler.webpack)) === null || _b === void 0 ? void 0 : _b.Compilation) === null || _c === void 0 ? void 0 : _c.PROCESS_ASSETS_STAGE_REPORT;
+        if (stage === undefined) {
+            throw new Error(`${pluginName} could not determine the asset-processing stage to run at: the compiler exposes ` +
+                'neither `rspack` nor `webpack`. Refusing to register, rather than silently checking nothing.');
+        }
+        compiler.hooks.compilation.tap(pluginName, (compilation) => {
+            compilation.hooks.processAssets.tap({ name: pluginName, stage }, (assets) => {
+                const offences = new Map();
+                for (const [name, source] of Object.entries(assets)) {
+                    if (!name.endsWith('.css')) {
+                        continue;
+                    }
+                    const globals = findGlobalCarbonRules(source.source().toString());
+                    if (globals.length > 0) {
+                        offences.set(name, globals);
+                    }
+                }
+                if (offences.size > 0) {
+                    compilation.errors.push(buildGlobalCarbonRuleError(this.appName, offences));
+                }
+            });
+        });
+    }
+}
+exports.CarbonCssGuardPlugin = CarbonCssGuardPlugin;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@openmrs/carbon-css-guard",
+  "version": "10.0.1-pre.5378",
+  "license": "MPL-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">= 20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:development": "tsc",
+    "clean": "git clean -fdX -- dist",
+    "lint": "eslint src",
+    "test": "cross-env TZ=UTC vitest run",
+    "test:watch": "cross-env TZ=UTC vitest watch --passWithNoTests",
+    "coverage": "cross-env TZ=UTC vitest run --coverage",
+    "typescript": "tsc --noEmit --project tsconfig.test.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openmrs/openmrs-esm-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openmrs/openmrs-esm-core/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "openmrs",
+    "microfrontends",
+    "webpack",
+    "rspack",
+    "config"
+  ],
+  "homepage": "https://github.com/openmrs/openmrs-esm-core#readme",
+  "devDependencies": {
+    "cross-env": "^10.1.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.2"
+  },
+  "stableVersion": "10.0.0"
+}

package/src/index.test.ts

@@ -0,0 +1,254 @@
+// The Carbon CSS guard fails a module's production build when its emitted stylesheets restyle the page
+// as a whole (RFC 0033). It reads minified CSS with a hand-rolled scanner, and it is a hard build error
+// for every module in the ecosystem, so a false positive is as costly as a miss.
+import { describe, expect, it } from 'vitest';
+import { buildGlobalCarbonRuleError, CarbonCssGuardPlugin, findGlobalCarbonRules } from './index';
+
+// A module's own classes always reach the emitted CSS in this shape, since both configs set
+// `localIdentName` to `${ident}__[name]__[local]___[hash:base64:5]`.
+const scoped = '.-esm-login__login__inputGroup___VWJgx';
+
+const cases: Array<{ label: string; css: string; expected: Array<string> }> = [
+  // Nesting: the scoping class sits on the parent, so the inner selector reads bare but is not global.
+  // Sass flattens this away, but a module can ship a plain `.css` file that uses native nesting.
+  { label: 'nested override, declarations first', css: `${scoped}{color:red;.cds--btn{color:blue}}`, expected: [] },
+  { label: 'nested override, no declarations', css: `${scoped}{.cds--btn{color:blue}}`, expected: [] },
+  { label: 'nested override using &', css: `${scoped}{color:red;& .cds--btn{color:blue}}`, expected: [] },
+  { label: 'nested override after url(#id)', css: `${scoped}{fill:url(#g);.cds--btn{color:red}}`, expected: [] },
+  { label: 'nested reset inside an override', css: `${scoped}{color:red;div{margin:0}}`, expected: [] },
+
+  // At-rules scope nothing, so a global rule inside one is still global.
+  { label: 'global inside @media', css: '@media (min-width:1px){.cds--btn{color:red}}', expected: ['.cds--btn'] },
+  { label: 'global inside @supports', css: '@supports (a:b){.cds--btn{color:red}}', expected: ['.cds--btn'] },
+  { label: 'global inside @layer', css: '@layer overrides{.cds--btn{color:red}}', expected: ['.cds--btn'] },
+  {
+    label: 'scoped override inside @media',
+    css: `@media (min-width:1px){${scoped} .cds--btn{color:red}}`,
+    expected: [],
+  },
+
+  // Carbon-anchored selectors.
+  { label: 'bare Carbon class', css: '.cds--btn{color:red}', expected: ['.cds--btn'] },
+  {
+    label: 'Carbon-only descendant chain',
+    css: '.cds--modal .cds--btn--primary{color:red}',
+    expected: ['.cds--modal .cds--btn--primary'],
+  },
+  {
+    label: ':not() narrows but does not scope',
+    css: '.cds--btn:not(.myLocal___a1){color:red}',
+    expected: ['.cds--btn:not(.myLocal___a1)'],
+  },
+  { label: 'module-scoped Carbon override', css: `${scoped} .cds--btn{color:red}`, expected: [] },
+  { label: 'id-scoped Carbon override', css: '#myAppRoot .cds--btn{color:red}', expected: [] },
+  {
+    label: 'a non-Carbon class anchors the override',
+    css: '.omrs-breakpoint-gt-tablet .cds--side-nav__link{color:red}',
+    expected: [],
+  },
+  {
+    label: 'css-loader-scoped Carbon classes are inert, not global',
+    css: '.-esm-login__datepicker-module__cds--layout--size-xs___rHkV0{block-size:1rem}',
+    expected: [],
+  },
+
+  // Selectors with nothing to anchor them, such as Carbon's reset.
+  { label: 'element-selector reset', css: 'html,body,div{margin:0}', expected: ['html', 'body', 'div'] },
+  { label: 'universal reset', css: '*{box-sizing:border-box}', expected: ['*'] },
+  { label: 'attribute-only selector', css: '[dir=rtl]{text-align:right}', expected: ['[dir=rtl]'] },
+  { label: ':root carries custom properties', css: ':root{--omrs-x:1}', expected: [] },
+
+  // `:is()`/`:where()` hold selector lists, so one anchored branch must not cover for an unanchored one.
+  // Lightning CSS also lowers native nesting into `:is()`, so these turn up in output as well as source.
+  {
+    label: ':is() with one page-wide branch',
+    css: `:is(.cds--btn,${scoped}){color:red}`,
+    expected: [`:is(.cds--btn,${scoped})`],
+  },
+  {
+    label: ':where() with one page-wide branch',
+    css: `:where(.cds--btn,${scoped}){color:red}`,
+    expected: [`:where(.cds--btn,${scoped})`],
+  },
+  {
+    label: ':is() with an anchorless branch',
+    css: `:is(body,${scoped}){margin:0}`,
+    expected: [`:is(body,${scoped})`],
+  },
+  {
+    label: ':is() of Carbon classes only',
+    css: ':is(.cds--btn,.cds--tag){color:red}',
+    expected: [':is(.cds--btn,.cds--tag)'],
+  },
+  { label: ':is() with every branch anchored', css: `${scoped} :is(.a___a1,.b___b2){color:red}`, expected: [] },
+  {
+    label: ':is() of pseudo-classes anchors nothing away',
+    css: `${scoped}:is(:hover,:focus){color:red}`,
+    expected: [],
+  },
+  { label: 'a scoped :is() of Carbon classes', css: `${scoped} :is(.cds--btn,.cds--tag){color:red}`, expected: [] },
+
+  // `@scope` confines its contents to a subtree, so rules inside it are local however they read.
+  { label: '@scope makes a bare Carbon rule local', css: `@scope (${scoped}){.cds--btn{color:red}}`, expected: [] },
+  { label: '@scope with a limit', css: `@scope (${scoped}) to (.inner___b2){img{border:0}}`, expected: [] },
+  { label: '@scope makes a bare element rule local', css: `@scope (${scoped}){p{margin:0}}`, expected: [] },
+  {
+    label: 'a rule after a @scope block is judged normally',
+    css: `@scope (${scoped}){p{margin:0}}body{margin:0}`,
+    expected: ['body'],
+  },
+
+  // Extension wrappers are the framework's markup, so an app has no class of its own to hang on them.
+  // A named extension or slot is as specific as a class; a valueless one matches every extension there is.
+  {
+    label: 'a named extension wrapper anchors the rule',
+    css: "[data-extension-id='sticky-notes-button']:empty{display:none}",
+    expected: [],
+  },
+  {
+    label: 'a named extension wrapper anchors a Carbon override',
+    css: "[data-extension-slot-name='my-slot'] .cds--btn{min-width:7rem}",
+    expected: [],
+  },
+  {
+    label: 'quotes stripped by minification still anchor',
+    css: '[data-extension-id=clinical-views-summary]{display:block}',
+    expected: [],
+  },
+  {
+    label: 'a valueless extension attribute anchors nothing',
+    css: '[data-extension-id]{display:block}',
+    expected: ['[data-extension-id]'],
+  },
+  {
+    label: 'a non-extension attribute still anchors nothing',
+    css: 'html[dir=rtl] .cds--side-nav{margin:0}',
+    expected: ['html[dir=rtl] .cds--side-nav'],
+  },
+  { label: ':host carries custom properties', css: ':host{--omrs-x:1}', expected: [] },
+
+  // Keyframe steps read like element selectors but select nothing.
+  {
+    label: 'keyframe steps',
+    css: '@keyframes spin{from{opacity:0}50%{opacity:.5}to{transform:rotate(1turn)}}',
+    expected: [],
+  },
+  {
+    label: 'vendor-prefixed keyframe steps',
+    css: '@-webkit-keyframes spin{to{opacity:1}}',
+    expected: [],
+  },
+
+  // Lexical hazards in minified output.
+  {
+    label: 'braces and semicolons inside a string',
+    css: `${scoped}{content:"}{;"}.cds--btn{color:red}`,
+    expected: ['.cds--btn'],
+  },
+  { label: 'statement at-rule', css: '@import url(x);.cds--btn{color:red}', expected: ['.cds--btn'] },
+  { label: 'comment between rules', css: '/* }{ .cds--x */.cds--btn{color:red}', expected: ['.cds--btn'] },
+  { label: '@font-face declarations', css: '@font-face{font-family:x;src:url(y)}', expected: [] },
+  { label: 'empty stylesheet', css: '', expected: [] },
+];
+
+describe('the Carbon CSS guard', () => {
+  it.each(cases)('reports $label', ({ css, expected }) => {
+    expect(findGlobalCarbonRules(css)).toEqual(expected);
+  });
+
+  // Without this, a change that makes the scanner return nothing at all would leave every case above
+  // passing on the empty expectations, and the guard would become a silent no-op.
+  it('still fires on the case the guard exists for', () => {
+    const wholesaleCarbon = Array.from({ length: 50 }, (_, i) => `.cds--component-${i}{color:red}`).join('');
+
+    expect(findGlobalCarbonRules(wholesaleCarbon)).toHaveLength(50);
+  });
+
+  // The two ways to fail this guard have unrelated causes, so the advice can't be one-size-fits-all.
+  describe('the error it raises', () => {
+    const carbonAdvice = /`@use`s `@carbon\/styles`/;
+    const anchorlessAdvice = /no class or id of their own/;
+
+    it('explains Carbon imports when the offending selectors name Carbon classes', () => {
+      const message = buildGlobalCarbonRuleError('app', new Map([['a.css', ['.cds--btn']]])).message;
+
+      expect(message).toMatch(carbonAdvice);
+      expect(message).not.toMatch(anchorlessAdvice);
+    });
+
+    it('explains scoping when the offending selectors have no anchor of their own', () => {
+      const message = buildGlobalCarbonRuleError('app', new Map([['a.css', ['body']]])).message;
+
+      expect(message).toMatch(anchorlessAdvice);
+      expect(message).not.toMatch(carbonAdvice);
+    });
+
+    it('explains both when both occur', () => {
+      const message = buildGlobalCarbonRuleError('app', new Map([['a.css', ['.cds--btn', 'body']]])).message;
+
+      expect(message).toMatch(carbonAdvice);
+      expect(message).toMatch(anchorlessAdvice);
+    });
+  });
+
+  // The scanner is covered above; this is the wiring around it. The integration tests exercise the same
+  // path against today's bundlers, so what's worth unit-testing here is what they can't reach: the asset
+  // filter, and the refusal to register against a compiler exposing neither bundler's namespace.
+  describe('the plugin', () => {
+    function fakeCompiler(namespace: 'rspack' | 'webpack' | 'neither', assets: Record<string, string>) {
+      const compilation = {
+        errors: [] as Array<Error>,
+        hooks: {
+          processAssets: {
+            tap: (_options: unknown, callback: (a: Record<string, { source(): string }>) => void) =>
+              callback(Object.fromEntries(Object.entries(assets).map(([name, css]) => [name, { source: () => css }]))),
+          },
+        },
+      };
+      const bundler = { Compilation: { PROCESS_ASSETS_STAGE_REPORT: 5000 } };
+
+      return {
+        compilation,
+        compiler: {
+          ...(namespace === 'neither' ? {} : { [namespace]: bundler }),
+          hooks: { compilation: { tap: (_name: string, cb: (c: typeof compilation) => void) => cb(compilation) } },
+        },
+      };
+    }
+
+    it.each(['rspack', 'webpack'] as const)('reports offences found in a %s build', (namespace) => {
+      const { compiler, compilation } = fakeCompiler(namespace, { 'a.css': '.cds--btn{color:red}' });
+
+      new CarbonCssGuardPlugin('@openmrs/esm-x-app').apply(compiler as never);
+
+      expect(compilation.errors).toHaveLength(1);
+      expect(compilation.errors[0].message).toContain('.cds--btn');
+      expect(compilation.errors[0].message).toContain('@openmrs/esm-x-app');
+    });
+
+    it('reads stylesheets only, not the JavaScript or source maps that carry the same text', () => {
+      const { compiler, compilation } = fakeCompiler('rspack', {
+        'a.js': '.cds--btn{color:red}',
+        'a.css.map': '.cds--btn{color:red}',
+      });
+
+      new CarbonCssGuardPlugin('app').apply(compiler as never);
+
+      expect(compilation.errors).toEqual([]);
+    });
+
+    it('stays quiet when nothing is global', () => {
+      const { compiler, compilation } = fakeCompiler('rspack', { 'a.css': `${scoped} .cds--btn{color:red}` });
+
+      new CarbonCssGuardPlugin('app').apply(compiler as never);
+
+      expect(compilation.errors).toEqual([]);
+    });
+
+    it('refuses to register against a compiler exposing neither bundler, rather than checking nothing', () => {
+      const { compiler } = fakeCompiler('neither', { 'a.css': '.cds--btn{color:red}' });
+
+      expect(() => new CarbonCssGuardPlugin('app').apply(compiler as never)).toThrow(/neither `rspack` nor `webpack`/);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,369 @@
+/**
+ * A webpack/rspack plugin that fails a build whose emitted CSS restyles the page as a whole rather
+ * than the module's own markup.
+ *
+ * Carbon's stylesheet is delivered exactly once, by the app shell (frontend RFC 0033). What separates
+ * a supported override from a page-wide one is the selector's anchor. `.myThing :global(.cds--btn)`
+ * scopes the override to this module and is how a visual fix through Carbon's classes gets made; a
+ * selector anchored on Carbon alone — `:global(.cds--btn)`, `[dir=rtl] :global(.cds--css-grid-column)`
+ * — reaches every Carbon component on the page, including other modules'. A selector with no class or
+ * id to anchor it at all, such as the `html, body, div { … }` of Carbon's reset, is broader still.
+ *
+ * These arrive by `@use`-ing `@carbon/styles`, one of its resets, or an individual component's
+ * stylesheet, rather than just Carbon's tokens, mixins, and functions, which emit no CSS.
+ *
+ * The scanner reads emitted, minified CSS rather than source, because that is what actually ships and
+ * because the many valid ways to import a Carbon token defeat checking imports at the source level.
+ */
+
+/**
+ * What can confine a rule to markup this module owns: class and id tokens (`.cds--btn`, `#main`,
+ * `.a\\:b`), plus an attribute selector naming a specific extension or slot
+ * (`[data-extension-id='my-thing']`).
+ *
+ * Extension wrappers are rendered by the framework, so an app has nowhere to put a class of its own on
+ * them; the attribute's value is what makes the rule specific, exactly as a class would. It has to be a
+ * value test — a bare `[data-extension-id]` matches every extension on the page and anchors nothing.
+ */
+const anchorPattern = /[.#](?:[-\w]|\\.)+|\[data-extension-[\w-]*[~^|*$]?=[^\]]*\]/g;
+
+/**
+ * Carbon's class prefix, matched only where a selector starts with it. The shared configs run every
+ * stylesheet through CSS Modules, so a Carbon class reaches the page verbatim only when the module
+ * wrote it inside `:global`; anything else is renamed to `.-esm-login__footer__cds--btn___1a2b3` and
+ * can no longer restyle the shell's Carbon.
+ */
+const carbonPrefix = '.cds--';
+
+/**
+ * Exempt from the anchorless rule. `:root` and `:host` carry custom properties, which add to the
+ * cascade rather than restyling anything, and are how a module contributes its own design tokens.
+ */
+const anchorlessExemptPattern = /^:(?:root|host)\b/;
+
+/** Ceiling on the `:is(…)`/`:where(…)` cross product, so a pathological selector can't stall a build. */
+const maxSelectorExpansions = 256;
+
+type BlockKind = 'style' | 'at-rule' | 'keyframes' | 'scope';
+
+/**
+ * The subset of a compilation this plugin needs. Declaring it structurally, rather than importing
+ * either bundler's types, is what lets one implementation serve both — and makes a bundler that stops
+ * supplying these a compile error here rather than a guard that silently sees nothing.
+ */
+interface Compilation {
+  errors: Array<Error>;
+  hooks: {
+    processAssets: {
+      tap(options: { name: string; stage: number }, callback: (assets: Record<string, Source>) => void): void;
+    };
+  };
+}
+
+interface Source {
+  source(): string | Buffer;
+}
+
+interface Compiler {
+  /** Both bundlers expose their own namespace here; rspack sets `webpack` too, for compatibility. */
+  rspack?: { Compilation: { PROCESS_ASSETS_STAGE_REPORT: number } };
+  webpack?: { Compilation: { PROCESS_ASSETS_STAGE_REPORT: number } };
+  hooks: {
+    compilation: { tap(name: string, callback: (compilation: Compilation) => void): void };
+  };
+}
+
+/**
+ * Blanks out comments and string literals so that braces, semicolons, and class-like text inside them
+ * can't be mistaken for CSS syntax by the (deliberately hand-rolled) scanner below.
+ */
+function stripNoise(css: string): string {
+  let out = '';
+  let i = 0;
+
+  while (i < css.length) {
+    const char = css[i];
+
+    if (char === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      i = end === -1 ? css.length : end + 2;
+      out += ' ';
+    } else if (char === '"' || char === "'") {
+      i += 1;
+      while (i < css.length && css[i] !== char) {
+        i += css[i] === '\\' ? 2 : 1;
+      }
+      i += 1;
+      out += '""';
+    } else {
+      out += char;
+      i += 1;
+    }
+  }
+
+  return out;
+}
+
+/** Splits a selector list on its top-level commas, leaving those nested in `:not(…)` & friends alone. */
+function splitSelectorList(list: string): Array<string> {
+  const selectors: Array<string> = [];
+  let depth = 0;
+  let start = 0;
+
+  for (let i = 0; i < list.length; i++) {
+    const char = list[i];
+
+    if (char === '(' || char === '[') {
+      depth += 1;
+    } else if (char === ')' || char === ']') {
+      depth -= 1;
+    } else if (char === ',' && depth === 0) {
+      selectors.push(list.slice(start, i));
+      start = i + 1;
+    }
+  }
+
+  selectors.push(list.slice(start));
+  return selectors;
+}
+
+/** The first `:is(…)` or `:where(…)` in `selector`, or `undefined` if it holds none. */
+function findSelectorListGroup(selector: string) {
+  const match = /:(?:is|where)\(/.exec(selector);
+
+  if (!match) {
+    return undefined;
+  }
+
+  let depth = 0;
+
+  for (let i = match.index + match[0].length - 1; i < selector.length; i++) {
+    if (selector[i] === '(') {
+      depth += 1;
+    } else if (selector[i] === ')' && (depth -= 1) === 0) {
+      return { start: match.index, end: i + 1, inner: selector.slice(match.index + match[0].length, i) };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Rewrites `:is(…)`/`:where(…)` into the plain selectors they stand for, so `.a:is(.b,.c)` becomes
+ * `.a.b` and `.a.c`.
+ *
+ * Without this a single anchored branch covers for the rest: `:is(.cds--btn, .myThing)` would read as
+ * anchored even though its first branch restyles every Carbon button on the page, while the equivalent
+ * `.cds--btn, .myThing` is caught. It matters for what gets built as much as for what gets written —
+ * Lightning CSS lowers native CSS nesting into `:is()` when the browserslist targets call for it, and
+ * this scanner reads minified output.
+ *
+ * The expansion is a cross product, so it is bounded. No selector in real stylesheets comes close; one
+ * that did would be left partly expanded and read as it is today, which is the behaviour this replaces.
+ */
+function expandSelectorLists(selector: string, budget = { left: maxSelectorExpansions }): Array<string> {
+  const group = findSelectorListGroup(selector);
+
+  if (!group || budget.left <= 0) {
+    return [selector];
+  }
+
+  const branches = splitSelectorList(group.inner);
+  budget.left -= branches.length;
+
+  return branches.flatMap((branch) =>
+    expandSelectorLists(selector.slice(0, group.start) + branch.trim() + selector.slice(group.end), budget),
+  );
+}
+
+/**
+ * Removes `:not(…)` groups. A class inside a negation narrows which elements the rule skips; it never
+ * confines the rule to this module's markup, so `.cds--btn:not(.myThing)` is still a page-wide rule.
+ */
+function stripNegations(selector: string): string {
+  let out = '';
+
+  for (let i = 0; i < selector.length; i++) {
+    if (!selector.startsWith(':not(', i)) {
+      out += selector[i];
+      continue;
+    }
+
+    let depth = 0;
+
+    for (i += 4; i < selector.length; i++) {
+      if (selector[i] === '(') {
+        depth += 1;
+      } else if (selector[i] === ')' && (depth -= 1) === 0) {
+        break;
+      }
+    }
+  }
+
+  return out;
+}
+
+function classify(prelude: string): BlockKind {
+  if (!prelude.startsWith('@')) {
+    return 'style';
+  }
+
+  if (/^@(?:-\w+-)?keyframes\b/.test(prelude)) {
+    return 'keyframes';
+  }
+
+  // `@scope (.card) { … }` confines everything inside it to the subtree its root selects, so its rules
+  // are local by definition however they read. The scoping root itself is not checked: an app that
+  // scopes to Carbon's own markup would still be reaching page-wide, which this does not catch.
+  return /^@scope\b/.test(prelude) ? 'scope' : 'at-rule';
+}
+
+/** Whether this single (comma-free) selector restyles the page rather than the module's own markup. */
+function isGlobal(selector: string): boolean {
+  const trimmed = selector.trim();
+
+  if (trimmed.length === 0) {
+    return false;
+  }
+
+  const anchors = stripNegations(trimmed).match(anchorPattern) ?? [];
+
+  return anchors.length > 0
+    ? anchors.every((anchor) => anchor.startsWith(carbonPrefix))
+    : !anchorlessExemptPattern.test(trimmed);
+}
+
+/**
+ * Returns the distinct selectors in `css` that restyle the page rather than the module's own markup.
+ *
+ * Only rules that aren't nested inside another style rule are considered: native CSS nesting puts the
+ * scoping class on the parent, so `.myThing { .cds--btn { … } }` is a correctly scoped override even
+ * though the inner selector reads as a bare Carbon one. Rules nested in an at-rule — `@media`,
+ * `@supports`, `@layer` — are considered, since those don't scope anything; those inside `@scope`,
+ * which does, are not.
+ *
+ * @param css The contents of an emitted stylesheet
+ */
+export function findGlobalCarbonRules(css: string): Array<string> {
+  const globals = new Set<string>();
+  const blocks: Array<BlockKind> = [];
+  let prelude = '';
+
+  for (const char of stripNoise(css)) {
+    if (char === '{') {
+      const kind = classify(prelude.trim());
+
+      if (kind === 'style' && !blocks.some((block) => block !== 'at-rule')) {
+        for (const selector of splitSelectorList(prelude)) {
+          // Reported as written, not as expanded, so the message names something findable in the source.
+          if (expandSelectorLists(selector).some(isGlobal)) {
+            globals.add(selector.trim());
+          }
+        }
+      }
+
+      blocks.push(kind);
+      prelude = '';
+    } else if (char === '}') {
+      blocks.pop();
+      prelude = '';
+    } else if (char === ';') {
+      // A declaration, or a statement at-rule such as `@import`; neither introduces a selector.
+      prelude = '';
+    } else {
+      prelude += char;
+    }
+  }
+
+  return [...globals];
+}
+
+const pluginName = 'CarbonCssGuardPlugin';
+const maxReportedSelectors = 10;
+
+/**
+ * Builds the failure reported to the developer.
+ *
+ * @param appName The module being built, named as it appears in its `package.json`
+ * @param offences The offending selectors found, keyed by the asset each was found in
+ */
+export function buildGlobalCarbonRuleError(appName: string, offences: Map<string, Array<string>>): Error {
+  const total = [...offences.values()].reduce((count, selectors) => count + selectors.length, 0);
+  const detail = [...offences]
+    .map(([asset, selectors]) => {
+      const shown = selectors.slice(0, maxReportedSelectors).map((selector) => `    ${selector}`);
+      const rest = selectors.length - shown.length;
+      return [`  ${asset}`, ...shown, ...(rest > 0 ? [`    …and ${rest} more`] : [])].join('\n');
+    })
+    .join('\n');
+
+  // The two cases have nothing to do with each other, and pointing someone who wrote `body { margin: 0 }`
+  // at their Carbon imports sends them looking in the wrong place entirely.
+  const selectors = [...offences.values()].flat();
+  const remedy = [
+    selectors.some((selector) => selector.includes(carbonPrefix))
+      ? 'Selectors naming Carbon classes usually come from SCSS that `@use`s `@carbon/styles`, one of its ' +
+        'resets, or an individual component stylesheet, instead of only its tokens, mixins, and functions, ' +
+        "which emit no CSS. To override Carbon from this module, anchor the selector to one of the module's " +
+        'own classes — `.myThing :global(.cds--btn)` rather than `:global(.cds--btn)`.'
+      : undefined,
+    selectors.some((selector) => !selector.includes(carbonPrefix))
+      ? 'Selectors with no class or id of their own — element, universal, or attribute selectors — apply to ' +
+        'the whole page, including other modules. Scope them to this module, e.g. `.myThing p` rather than ' +
+        '`p`, or move them to the app shell if they really are meant to be global.'
+      : undefined,
+  ].filter(Boolean);
+
+  return new Error(
+    `${appName} emits ${total} global CSS rule(s). Carbon's CSS is delivered once, by the app shell, so ` +
+      `frontend modules must not restyle the page as a whole.\n\n${detail}\n\n${remedy.join('\n\n')}`,
+  );
+}
+
+/**
+ * Fails the build if any emitted stylesheet restyles the page as a whole. Runs at the reporting stage,
+ * late enough to see minified output, so it checks the CSS that actually ships.
+ *
+ * Only meaningful in a build that extracts CSS: under `style-loader` there are no `.css` assets to
+ * read, so the shared configs add this in production only.
+ */
+export class CarbonCssGuardPlugin {
+  /**
+   * @param appName The module being built, named as it appears in its `package.json`
+   */
+  constructor(private readonly appName: string) {}
+
+  apply(compiler: Compiler) {
+    // Read off the compiler rather than imported, so this package needs a dependency on neither bundler.
+    const stage = (compiler.rspack ?? compiler.webpack)?.Compilation?.PROCESS_ASSETS_STAGE_REPORT;
+
+    if (stage === undefined) {
+      throw new Error(
+        `${pluginName} could not determine the asset-processing stage to run at: the compiler exposes ` +
+          'neither `rspack` nor `webpack`. Refusing to register, rather than silently checking nothing.',
+      );
+    }
+
+    compiler.hooks.compilation.tap(pluginName, (compilation) => {
+      compilation.hooks.processAssets.tap({ name: pluginName, stage }, (assets) => {
+        const offences = new Map<string, Array<string>>();
+
+        for (const [name, source] of Object.entries(assets)) {
+          if (!name.endsWith('.css')) {
+            continue;
+          }
+
+          const globals = findGlobalCarbonRules(source.source().toString());
+
+          if (globals.length > 0) {
+            offences.set(name, globals);
+          }
+        }
+
+        if (offences.size > 0) {
+          compilation.errors.push(buildGlobalCarbonRuleError(this.appName, offences));
+        }
+      });
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "esModuleInterop": true,
+    "module": "CommonJS",
+    "target": "es2015",
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "outDir": "dist",
+    "lib": ["es5", "es2015", "es2015.promise", "es2016.array.include", "es2018"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    mockReset: true,
+  },
+});