@primer/stylelint-config 13.0.0-rc.22bf91a → 13.0.0-rc.27facf3

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@primer/stylelint-config",
-  "version": "13.0.0-rc.22bf91a",
+  "version": "13.0.0-rc.27facf3",
   "description": "Sharable stylelint config used by GitHub's CSS",
   "author": "GitHub, Inc.",
   "license": "MIT",
   "type": "module",
+  "main": "dist/index.cjs",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
+      "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     }
   },
@@ -32,39 +33,48 @@
     "node": ">16.0.0"
   },
   "scripts": {
+    "pretest": "npm run build",
     "build": "rollup -c",
     "clean": "rimraf dist",
-    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --coverage false",
-    "test:stylelint": "stylelint __tests__/__fixtures__/uses-vars.scss",
+    "test": "npm run test:jest && npm run test:stylelint",
+    "test:jest": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --coverage false",
+    "test:stylelint": "stylelint __tests__/__fixtures__/good/",
     "lint": "eslint .",
     "release": "changeset publish"
   },
   "dependencies": {
     "@github/browserslist-config": "^1.0.0",
     "@primer/css": "^21.0.8",
-    "@primer/primitives": "^7.16.0",
+    "@primer/primitives": "^8.2.0",
     "anymatch": "^3.1.1",
-    "globby": "^11.0.1",
     "postcss-scss": "^4.0.2",
+    "postcss-styled-syntax": "^0.6.4",
     "postcss-value-parser": "^4.0.2",
     "string.prototype.matchall": "^4.0.2",
     "stylelint": "^16.3.1",
     "stylelint-config-standard": "^36.0.0",
+    "stylelint-css-modules-no-global-scoped-selector": "^1.0.2",
     "stylelint-no-unsupported-browser-features": "^8.0.0",
     "stylelint-order": "^6.0.4",
     "stylelint-scss": "^6.2.0",
+    "stylelint-value-no-unknown-custom-properties": "^6.0.1",
     "tap-map": "^1.0.0"
   },
+  "overrides": {
+    "stylelint-css-modules-no-global-scoped-selector": {
+      "stylelint": "$stylelint"
+    }
+  },
   "prettier": "@github/prettier-config",
   "devDependencies": {
-    "@changesets/changelog-github": "0.4.7",
-    "@changesets/cli": "2.26.1",
+    "@changesets/changelog-github": "^0.5.0",
+    "@changesets/cli": "2.27.1",
     "@github/prettier-config": "^0.0.6",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@typescript-eslint/parser": "^7.7.0",
-    "dedent": "1.5.1",
+    "dedent": "^1.5.3",
     "eslint": "^8.0.1",
     "eslint-plugin-github": "^4.10.2",
     "eslint-plugin-jest": "^28.2.0",
@@ -88,7 +98,8 @@
     ],
     "testPathIgnorePatterns": [
       "/node_modules/",
-      "__tests__/utils"
+      "__tests__/utils",
+      "__tests__/__fixtures__"
     ]
   }
 }

package/plugins/README.md

@@ -7,18 +7,12 @@ This directory contains all of our custom stylelint plugins, each of which provi
 - [Primer stylelint plugins](#primer-stylelint-plugins)
     - [Rules](#rules)
   - [Usage](#usage)
-  - [`primer/no-override`](#primerno-override)
-  - [`primer/no-unused-vars`](#primerno-unused-vars)
-  - [`primer/no-deprecated-colors`](#primerno-deprecated-colors)
-  - [`primer/no-undefined-vars`](#primerno-undefined-vars)
-  - [`primer/no-scale-colors`](#primerno-scale-colors)
   - [`primer/colors`](#primercolors)
   - [`primer/spacing`](#primerspacing)
   - [`primer/typography`](#primertypography)
   - [`primer/borders`](#primerborders)
   - [`primer/box-shadow`](#primerbox-shadow)
   - [`primer/responsive-widths`](#primerresponsive-widths)
-  - [`primer/utilities`](#primerutilities)
   - [Variable rules](#variable-rules)
     - [Variable rule options](#variable-rule-options)
 
@@ -33,131 +27,7 @@ If you're _not_ using or extending `@primer/stylelint-config`, you can still ref
 ```js
 // stylelint.config.js
 module.exports = {
-  plugins: ['@primer/stylelint-config/plugins/no-override', '@primer/stylelint-config/plugins/no-unused-vars']
-}
-```
-
-## `primer/no-override`
-
-This rule prohibits "overriding" class selectors defined in [Primer CSS]. By default, it will only fail selectors that target utility classes:
-
-```scss
-// FAIL
-.mt-0 {
-  /* literally anything */
-}
-```
-
-You can further constrain overrides to exclude _any_ class selector in Primer by providing additional names in the `bundles` option:
-
-```js
-// stylelint.config.js
-module.exports = {
-  // ...
-  rules: {
-    'primer/no-override': [
-      true,
-      {
-        bundles: ['utilities', core', 'product', 'marketing']
-      }
-    ]
-  }
-}
-```
-
-## `primer/no-unused-vars`
-
-This rule helps you find SCSS variables that _may_ not be used, and can be safely deleted. It works by scanning all of the SCSS files in your project and looking for anything that appears to be either a Sass variable declaration or reference:
-
-```scss
-    $name: value;
-/**      ↑
- *  The colon is what makes this a declaration */
-
-/* Anything starting with a $ and followed by word chars or hyphens
- * and _not_ followed by a colon is considered a reference: */
-
-    margin: $value;
-/**               ↑
- *                Not a colon */
-    padding: $value 1px;
-/**                ↑
- *                 Not a colon */
-
-@media screen and (max-width: $break-lg) {
-/**                                    ↑
- *                                     Also not a colon */
-```
-
-Equipped with a list of all the variable declarations and references, the linting rule walks all of the declarations in the
-file being linted, finds any that look like declarations (using the same pattern as the project-wide scan), and generates a warning for any that have zero references in the files it's scanned.
-
-Because there isn't any good way for a stylelint plugin to know all of the files being linted, it needs to be told where to find all of the declarations and references in its options:
-
-- `files` is a single path, glob, or array of paths and globs, that tells the plugin which files to scan relative to the current working directory. The default is `['**/*.scss', '!node_modules']`, which tells [globby] to find all the `.scss` files recursively and ignore the `node_modules` directory.
-
-- `variablePattern` is a regular expression that matches a single variable in either a source file string or the `prop` of a postcss Declaration node (`{type: 'decl'}`). The default matches Sass/SCSS variables: `/\$[-\w]/g`. Note that the `g` ("global") flag is _required_ to match multiple variable references on a single line.
-
-- `verbose` is a boolean that enables chatty `console.warn()` messages telling you what the plugin found, which can aid in debugging more complicated project layouts.
-
-## `primer/no-deprecated-colors`
-
-This rule identifies deprecated color variables from [primer/primitives]](https://github.com/primer/primitives) deprecated.json file and suggests replacements.
-
-```scss
-body {
-  color: var(--color-fg-default);
-}
-/**          ↑
- *           OK: --color-text-primary is defined */
-
-body {
-  color: var(--color-text-primary);
-}
-/**          ↑
- *           FAIL: --color-text-primary is deprecated. */
-```
-
-## `primer/no-undefined-vars`
-
-This rule prohibits any usages of undefined CSS variables.
-
-```scss
-:root {
-  --color-text-primary: #000;
-}
-
-body {
-  color: var(--color-text-primary);
-}
-/**          ↑
- *           OK: --color-text-primary is defined */
-
-body {
-  color: var(--color-foo);
-}
-/**          ↑
- *           FAIL: --color-foo is not defined */
-```
-
-For the purposes of this rule, a CSS variable declaration is any text starting with `--` and immediately followed by a colon.
-
-Because there isn't a good way for a stylelint plugin to know what CSS variables are defined, it needs to be told where to look for declarations in its options:
-
-- `files` is a single path, glob, or array of paths and globs, that tells the plugin which files (relative to the current working directory) to scan for CSS variable declarations. The default is `['**/*.scss', '!node_modules']`, which tells [globby] to find all the `.scss` files recursively and ignore the `node_modules` directory.
-- `verbose` is a boolean that enables chatty `console.warn()` messages telling you what the plugin found, which can aid in debugging more complicated project layouts.
-
-## `primer/no-scale-colors`
-
-This rule prohibits the use of [non-functional scale CSS variables](https://primer.style/css/support/color-system#color-palette) like `var(--color-scale-blue-1)` in all cases except the `color-variables` mixin.
-
-```scss
-// Okay; using scale colors while defining new variables
-@include color-scale-var('new-var-name', var(--color-scale-blue-1), var(--color-scale-blue-2))
-
-// Fail; using scale colors directly as a property value
-.selector {
-  color: var(--color-scale-blue-1)
+  plugins: ['@primer/stylelint-config/plugins/colors']
 }
 ```
 
@@ -213,31 +83,6 @@ This [variable rule](#variable-rules) enforces the use of `$box-shadow*` variabl
 
 This plugin checks for `width` and `min-width` declarations that use a value less than the minimum browser size. `320px`
 
-## `primer/utilities`
-
-Checks for selectors with single declarations that can be replaced with [primer/css utilities](https://primer.style/css/utilities/).
-
-```scss
-.foo {
-  color: var(--color-fg-default);
-}
-/**          ↑
- *           FAIL: --color-fg-default can be replaced with .color-fg-default */
-
-.foo {
-  color: #custom;
-}
-/**          ↑
- *           OK: Color value doesn't match a utility. */
-
-.foo {
-  color: var(--color-fg-default);
-  padding: 0;
-}
-/**          ↑
- *           OK: Has more than one declaration, not considered */
-```
-
 ## Variable rules
 
 Variable rules are created using a general-purpose helper that can validate constraints for matching CSS properties and values. In general, the Primer CSS variable rules enforce two basic principles for custom CSS:
@@ -377,5 +222,4 @@ module.exports = {
 - `disableFix` is a boolean that can disable auto-fixing of this rule when running `stylelint --fix` to auto-fix other rules.
 
 [primer css]: https://primer.style/css
-[globby]: https://www.npmjs.com/package/globby
 [glob patterns]: http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm

package/plugins/borders.js

@@ -1,64 +1,197 @@
-import {createVariableRule} from './lib/variable-rules.js'
-
-export default createVariableRule(
-  'primer/borders',
-  {
-    border: {
-      expects: 'a border variable',
-      props: 'border{,-top,-right,-bottom,-left}',
-      values: ['$border', 'none', '0'],
-      components: ['border-width', 'border-style', 'border-color'],
-      replacements: {
-        // because shorthand border properties ¯\_(ツ)_/¯
-        '$border-width $border-style $border-gray': '$border',
-        '$border-width $border-gray $border-style': '$border',
-        '$border-style $border-width $border-gray': '$border',
-        '$border-style $border-gray $border-width': '$border',
-        '$border-gray $border-width $border-style': '$border',
-        '$border-gray $border-style $border-width': '$border',
-        '$border-width $border-style $border-color': '$border',
-        '$border-width $border-color $border-style': '$border',
-        '$border-style $border-width $border-color': '$border',
-        '$border-style $border-color $border-width': '$border',
-        '$border-color $border-width $border-style': '$border',
-        '$border-color $border-style $border-width': '$border',
-      },
-    },
-    'border color': {
-      expects: 'a border color variable',
-      props: 'border{,-top,-right,-bottom,-left}-color',
-      values: [
-        '$border-*',
-        'transparent',
-        'currentColor',
-        // Match variables in any of the following formats: --color-border-*, --color-*-border-*, --color-*-border, --borderColor-, *borderColor*
-        /var\(--color-(.+-)*border(-.+)*\)/,
-        /var\(--color-[^)]+\)/,
-        /var\(--borderColor-[^)]+\)/,
-        /var\((.+-)*borderColor(-.+)*\)/,
-      ],
-      replacements: {
-        '$border-gray': '$border-color',
-      },
-    },
-    'border style': {
-      expects: 'a border style variable',
-      props: 'border{,-top,-right,-bottom,-left}-style',
-      values: ['$border-style', 'none'],
-    },
-    'border width': {
-      expects: 'a border width variable',
-      props: 'border{,-top,-right,-bottom,-left}-width',
-      values: ['$border-width*', '0'],
-    },
-    'border radius': {
-      expects: 'a border radius variable',
-      props: 'border{,-{top,bottom}-{left,right}}-radius',
-      values: ['$border-radius', '0', '50%', 'inherit'],
-      replacements: {
-        '100%': '50%',
-      },
-    },
+import stylelint from 'stylelint'
+import declarationValueIndex from 'stylelint/lib/utils/declarationValueIndex.cjs'
+import valueParser from 'postcss-value-parser'
+import {walkGroups, primitivesVariables} from './lib/utils.js'
+
+const {
+  createPlugin,
+  utils: {report, ruleMessages, validateOptions},
+} = stylelint
+
+export const ruleName = 'primer/borders'
+export const messages = ruleMessages(ruleName, {
+  rejected: (value, replacement, propName) => {
+    if (propName && propName.includes('radius') && value.includes('borderWidth')) {
+      return `Border radius variables can not be used for border widths`
+    }
+
+    if ((propName && propName.includes('width')) || (borderShorthand(propName) && value.includes('borderRadius'))) {
+      return `Border width variables can not be used for border radii`
+    }
+
+    if (!replacement) {
+      return `Please use a Primer border variable instead of '${value}'. Consult the primer docs for a suitable replacement. https://primer.style/foundations/primitives/size#border`
+    }
+
+    return `Please replace '${value}' with a Primer border variable '${replacement['name']}'. https://primer.style/foundations/primitives/size#border`
   },
-  'https://primer.style/css/utilities/borders',
-)
+})
+
+const variables = primitivesVariables('border')
+const sizes = []
+const radii = []
+
+// Props that we want to check
+const propList = ['border', 'border-width', 'border-radius']
+// Values that we want to ignore
+const valueList = ['${']
+
+const borderShorthand = prop =>
+  /^border(-(top|right|bottom|left|block-start|block-end|inline-start|inline-end))?$/.test(prop)
+
+for (const variable of variables) {
+  const name = variable['name']
+
+  if (name.includes('borderWidth')) {
+    const value = variable['values']
+      .pop()
+      .replace(/max|\(|\)/g, '')
+      .split(',')[0]
+    sizes.push({
+      name,
+      values: [value],
+    })
+  }
+
+  if (name.includes('borderRadius')) {
+    radii.push(variable)
+  }
+}
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = (primary, secondaryOptions, context) => {
+  return (root, result) => {
+    const validOptions = validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    })
+
+    if (!validOptions) return
+
+    root.walkDecls(declNode => {
+      const {prop, value} = declNode
+
+      if (!propList.some(borderProp => prop.startsWith(borderProp))) return
+      if (/^border(-(top|right|bottom|left|block-start|block-end|inline-start|inline-end))?-color$/.test(prop)) return
+      if (valueList.some(valueToIgnore => value.includes(valueToIgnore))) return
+
+      const problems = []
+
+      const parsedValue = walkGroups(valueParser(value), node => {
+        const checkForVariable = (vars, nodeValue) =>
+          vars.some(variable =>
+            new RegExp(`${variable['name'].replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(nodeValue),
+          )
+
+        // Only check word types. https://github.com/TrySound/postcss-value-parser#word
+        if (node.type !== 'word') {
+          return
+        }
+
+        // Exact values to ignore.
+        if (
+          [
+            '*',
+            '+',
+            '-',
+            '/',
+            '0',
+            'none',
+            'inherit',
+            'initial',
+            'revert',
+            'revert-layer',
+            'unset',
+            'solid',
+            'dashed',
+            'dotted',
+            'transparent',
+          ].includes(node.value)
+        ) {
+          return
+        }
+
+        const valueUnit = valueParser.unit(node.value)
+
+        if (valueUnit && (valueUnit.unit === '' || !/^-?[0-9.]+$/.test(valueUnit.number))) {
+          return
+        }
+
+        // Skip if the value unit isn't a supported unit.
+        if (valueUnit && !['px', 'rem', 'em'].includes(valueUnit.unit)) {
+          return
+        }
+
+        // if we're looking at the border property that sets color in shorthand, don't bother checking the color
+        if (
+          // using border shorthand
+          borderShorthand(prop) &&
+          // includes a color as a third space-separated value
+          value.split(' ').length > 2 &&
+          // the color in the third space-separated value includes `node.value`
+          value
+            .split(' ')
+            .slice(2)
+            .some(color => color.includes(node.value))
+        ) {
+          return
+        }
+
+        // If the variable is found in the value, skip it.
+        if (prop.includes('width') || borderShorthand(prop)) {
+          if (checkForVariable(sizes, node.value)) {
+            return
+          }
+        }
+
+        if (prop.includes('radius')) {
+          if (checkForVariable(radii, node.value)) {
+            return
+          }
+        }
+
+        const replacement = (prop.includes('radius') ? radii : sizes).find(variable =>
+          variable.values.includes(node.value.replace('-', '')),
+        )
+        const fixable = replacement && valueUnit && !valueUnit.number.includes('-')
+
+        if (fixable && context.fix) {
+          node.value = node.value.replace(node.value, `var(${replacement['name']})`)
+        } else {
+          problems.push({
+            index: declarationValueIndex(declNode) + node.sourceIndex,
+            endIndex: declarationValueIndex(declNode) + node.sourceIndex + node.value.length,
+            message: messages.rejected(node.value, replacement, prop),
+          })
+        }
+
+        return
+      })
+
+      if (context.fix) {
+        declNode.value = parsedValue.toString()
+      }
+
+      if (problems.length) {
+        for (const err of problems) {
+          report({
+            index: err.index,
+            endIndex: err.endIndex,
+            message: err.message,
+            node: declNode,
+            result,
+            ruleName,
+          })
+        }
+      }
+    })
+  }
+}
+
+ruleFunction.ruleName = ruleName
+ruleFunction.messages = messages
+ruleFunction.meta = {
+  fixable: true,
+}
+
+export default createPlugin(ruleName, ruleFunction)

package/plugins/lib/utils.js

@@ -0,0 +1,45 @@
+import {createRequire} from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+export function primitivesVariables(type) {
+  const variables = []
+
+  const files = []
+  switch (type) {
+    case 'spacing':
+      files.push('base/size/size.json')
+      break
+    case 'border':
+      files.push('functional/size/border.json')
+      break
+  }
+
+  for (const file of files) {
+    // eslint-disable-next-line import/no-dynamic-require
+    const data = require(`@primer/primitives/dist/styleLint/${file}`)
+
+    for (const key of Object.keys(data)) {
+      const size = data[key]
+      const values = typeof size['value'] === 'string' ? [size['value']] : size['value']
+
+      variables.push({
+        name: `--${size['name']}`,
+        values,
+      })
+    }
+  }
+
+  return variables
+}
+
+export function walkGroups(root, validate) {
+  for (const node of root.nodes) {
+    if (node.type === 'function') {
+      walkGroups(node, validate)
+    } else {
+      validate(node)
+    }
+  }
+  return root
+}