lightningcss 1.33.0: Reject top-level un-scoped selectors with SyntaxError when pure mode is enabled in Lightning CSS modules configuration

# Lightning CSS Modules Pure Mode Configuration

## Prior Network Search

A search of known solutions returned sample `sha256:a455d54bcaffa5c281b8a4ec09e90a4b4a92e87c79ee4e8cc2cfaa97c5165127` which demonstrated inline style attribute transformation and minification with target browsers. This sample investigates a different feature: configuration of pure CSS modules validation in `transform()` and its selector enforcement behavior.

## Pinned Version

- `lightningcss`: `1.33.0`

## Observed Behavior

1. **Pure Selector Validation**: When `cssModules` is configured with `{ pure: true }`, Lightning CSS enforces that every rule selector must contain at least one class or ID selector. If a stylesheet contains un-scoped element selectors (such as `div { margin: 0; }`), universal selectors (`* { box-sizing: border-box; }`), or attribute selectors (`[hidden] { display: none; }`), `transform()` throws a `SyntaxError` with the message:
   `A selector in CSS modules should contain at least one class or ID selector`
   
2. **Default Impure Tolerance**: When `cssModules` is enabled via `cssModules: true` (or `{ pure: false }`), `pure` defaults to `false`. Top-level element and universal selectors compile without error and are emitted directly into the output stylesheet, while class selectors in the same file are scoped.

3. **Compound and Nested Pure Selectors**: When `cssModules.pure` is `true`, compound or combinator selectors containing at least one class or ID (such as `.card > div` or `#primary-nav li`) pass validation and compile successfully. The class and ID components are scoped in the output CSS and registered in `exports`.

4. **Exports Object Structure**: The `exports` dictionary produced by `transform()` maps class and ID names to structured metadata objects of shape `{ name: string, composes: any[], isReferenced: boolean }`, rather than bare string names.

## Failure Mode

When developers or tooling configure `cssModules: { pure: true }` expecting un-scoped rules to be silently stripped or emitted without errors, the failure mode is **loud**: `transform()` throws a compile-time `SyntaxError`.

{"case":{"believed":"compiling pure CSS modules silently drops top-level element selectors or emits them unchanged as global styles without error","caseId":"case:sha256:7ff628d0e56f53e4ab58bd539f5c7c5ea003a5ac4df3a87adb892c70b4bfc542","contract":["transform with cssModules.pure set to true throws a SyntaxError stating that a selector in CSS modules should contain at least one class or ID selector when encountering impure element selectors","transform with cssModules.pure set to true compiles successfully when every selector contains at least one class or ID selector","transform with default cssModules configuration (pure: false) compiles impure element selectors without throwing an error","exports maps each scoped class and ID to an object containing name, composes, and isReferenced rather than a bare string"],"goal":"Reject top-level un-scoped selectors with SyntaxError when pure mode is enabled in Lightning CSS modules configuration","kind":"HOW","packages":["pkg:npm/lightningcss@1.33.0"],"schemaVersion":1,"symbols":["transform"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/lightningcss@1.33.0"],"schemaVersion":1,"symbols":["transform"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-lightningcss-config",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-lightningcss-config",
      "version": "1.0.0",
      "dependencies": {
        "lightningcss": "1.33.0"
      }
    },
    "node_modules/detect-libc": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
      "license": "Apache-2.0",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/lightningcss": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",
      "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==",
      "license": "MPL-2.0",
      "dependencies": {
        "detect-libc": "^2.0.3"
      },
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      },
      "optionalDependencies": {
        "lightningcss-android-arm64": "1.33.0",
        "lightningcss-darwin-arm64": "1.33.0",
        "lightningcss-darwin-x64": "1.33.0",
        "lightningcss-freebsd-x64": "1.33.0",
        "lightningcss-linux-arm-gnueabihf": "1.33.0",
        "lightningcss-linux-arm64-gnu": "1.33.0",
        "lightningcss-linux-arm64-musl": "1.33.0",
        "lightningcss-linux-x64-gnu": "1.33.0",
        "lightningcss-linux-x64-musl": "1.33.0",
        "lightningcss-win32-arm64-msvc": "1.33.0",
        "lightningcss-win32-x64-msvc": "1.33.0"
      }
    },
    "node_modules/lightningcss-android-arm64": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.33.0.tgz",
      "integrity": "sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==",
      "cpu": [
        "arm64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "android"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-darwin-arm64": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.33.0.tgz",
      "integrity": "sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==",
      "cpu": [
        "arm64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "darwin"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-darwin-x64": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.33.0.tgz",
      "integrity": "sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==",
      "cpu": [
        "x64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "darwin"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-freebsd-x64": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.33.0.tgz",
      "integrity": "sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==",
      "cpu": [
        "x64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "freebsd"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-linux-arm-gnueabihf": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.33.0.tgz",
      "integrity": "sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==",
      "cpu": [
        "arm"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "linux"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-linux-arm64-gnu": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.33.0.tgz",
      "integrity": "sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==",
      "cpu": [
        "arm64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "linux"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-linux-arm64-musl": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.33.0.tgz",
      "integrity": "sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==",
      "cpu": [
        "arm64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "linux"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-linux-x64-gnu": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.33.0.tgz",
      "integrity": "sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==",
      "cpu": [
        "x64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "linux"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-linux-x64-musl": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.33.0.tgz",
      "integrity": "sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==",
      "cpu": [
        "x64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "linux"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-win32-arm64-msvc": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.33.0.tgz",
      "integrity": "sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==",
      "cpu": [
        "arm64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "win32"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    },
    "node_modules/lightningcss-win32-x64-msvc": {
      "version": "1.33.0",
      "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.33.0.tgz",
      "integrity": "sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==",
      "cpu": [
        "x64"
      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
        "win32"
      ],
      "engines": {
        "node": ">= 12.0.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/parcel"
      }
    }
  }
}

{
  "name": "npm-lightningcss-config",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "lightningcss": "1.33.0"
  }
}

import assert from 'node:assert/strict';
import { transform } from 'lightningcss';

// 1. transform with cssModules.pure set to true throws a SyntaxError stating that a selector in CSS modules should contain at least one class or ID selector when encountering impure element selectors
{
  const impureElementCss = Buffer.from('div { margin: 0; }');
  assert.throws(
    () => {
      transform({
        filename: 'widget.module.css',
        code: impureElementCss,
        cssModules: { pure: true },
      });
    },
    (err) => {
      assert.strictEqual(err.name, 'SyntaxError');
      assert.match(err.message, /A selector in CSS modules should contain at least one class or ID selector/);
      assert.strictEqual(err.fileName, 'widget.module.css');
      return true;
    }
  );

  const impureUniversalCss = Buffer.from('* { box-sizing: border-box; }');
  assert.throws(
    () => {
      transform({
        filename: 'widget.module.css',
        code: impureUniversalCss,
        cssModules: { pure: true },
      });
    },
    (err) => {
      assert.strictEqual(err.name, 'SyntaxError');
      assert.match(err.message, /A selector in CSS modules should contain at least one class or ID selector/);
      return true;
    }
  );
}

// 2. transform with cssModules.pure set to true compiles successfully when every selector contains at least one class or ID selector
{
  const pureModuleCss = Buffer.from(`
    .card > div {
      padding: 16px;
    }
    #primary-nav li {
      list-style: none;
    }
  `);

  const result = transform({
    filename: 'widget.module.css',
    code: pureModuleCss,
    cssModules: { pure: true },
  });

  const outputCss = result.code.toString();
  assert.ok(result.exports, 'exports object should be populated');
  assert.ok('card' in result.exports, 'class "card" must be exported');
  assert.ok('primary-nav' in result.exports, 'id "primary-nav" must be exported');
  assert.ok(!outputCss.includes('.card > div'), 'class selector should be scoped/hashed');
  assert.ok(!outputCss.includes('#primary-nav li'), 'id selector should be scoped/hashed');
  assert.match(outputCss, /padding:\s*16px/);
}

// 3. transform with default cssModules configuration (pure: false) compiles impure element selectors without throwing an error
{
  const mixedCss = Buffer.from(`
    body {
      margin: 0;
    }
    .container {
      width: 100%;
    }
  `);

  const result = transform({
    filename: 'widget.module.css',
    code: mixedCss,
    cssModules: true, // pure defaults to false
  });

  const outputCss = result.code.toString();
  assert.ok(outputCss.includes('body {'), 'top-level element selector is preserved when pure is false');
  assert.ok(!outputCss.includes('.container {'), 'class selector is scoped');
  assert.ok('container' in result.exports, 'container class is exported');
  assert.strictEqual('body' in result.exports, false, 'element selectors are not in exports');
}

// 4. exports maps each scoped class and ID to an object containing name, composes, and isReferenced rather than a bare string
{
  const css = Buffer.from(`
    .button {
      color: blue;
    }
  `);

  const result = transform({
    filename: 'widget.module.css',
    code: css,
    cssModules: { pure: true },
  });

  const btnExport = result.exports.button;
  assert.strictEqual(typeof btnExport, 'object', 'export entry must be an object');
  assert.strictEqual(typeof btnExport.name, 'string', 'export.name must be a string');
  assert.ok(btnExport.name.length > 0, 'export.name must not be empty');
  assert.ok(Array.isArray(btnExport.composes), 'export.composes must be an array');
  assert.strictEqual(typeof btnExport.isReferenced, 'boolean', 'export.isReferenced must be a boolean');
  assert.notStrictEqual(btnExport, btnExport.name, 'export is not a bare string value');
}