Develop stylelint rules from zero (plug-ins)

This article , We develop a custom... From scratch Stylelint Plug in project .
For the full project address, see

One 、 Preparation stage

1. PostCss Official website (Stylelint Use PostCss First the css The content is parsed into AST Abstract syntax tree , Pass again AST Perform analytical processing , Achieve desired results . you 're right Eslint In the same way );
2. Stylelint Official website ( Want to learn a technology , First look at its official website )
3. StylelintGitHub ( Copy sth. without catching its spirit )
4. development environment ：macOs-12.1 Apple M1 Pro（ Less important , It may be related to later plug-ins ）

Two 、 The development phase

1. Create directory

Open the terminal tool ( I am using iterm),cd To the directory where items are normally stored ;
type mkdir stylelint-plugin Create a file called stylelint-plugin Folder ;

2. npm initialization

cd Into the stylelint-plugin Catalog , type npm init , Then all the way back , According to the prompt Just enter the content ;
After this step , There will be a new package.json file ;

3. Construct the project structure

Modelled on the StylelintGitHub The structure of the construction project is as follows ：

├── lib  //  The relevant contents of the rules are put in `lib` Catalog 
│   ├── index.js
│   ├── rules
│   │   ├── index.js
│   │   └── selector-class-no-elements  //  Under each folder is a rule , The folder name is the rule name 
│   │       └── index.js   //  The content of the rules 
│   └── utils
├── package.json
└── README.md

4. The installation part depends on

npm install stylelint postcss-selector-parser -D

6. We develop selector-class-no-elements Rule as an example , Write code .
   The meaning of this rule is ：class Selectors cannot be in the form of ’elements-' start
   Because third-party component libraries (ElementUI、Ant Design etc. ), The component name starts with ’elements-' start , Do not override styles for these three-party components during development , So as not to cause unpredictable bug.

======================================

Let's plug in here , Have a look first css What is the parsed content

step 4 in Installed postcss-selector-parser plug-in unit , It's parsing css Selector in ,

First create a in the root directory test.js file , The contents are as follows ：

const SelectorParser = require('postcss-selector-parser');

const transform = selectors => {
    
  selectors.walk(node => {
    
    console.log(node);
  })
}

SelectorParser(transform).processSync('#app');

And then run node test.js, log give the result as follows ：

The former “Selector” type Express Selectors ;
the latter “ID” type Express ID Selectors

======================================

5. Formal development ：

lib/rules/selector-class-no-elements/index.js The contents are as follows ：

/* * @Desc: class Selectors cannot be in the form of "elements-"  start  * @Author:  Front end Kakashi  * @Date: 2022-06-25 17:10:14 */

const {
     nameSpace, newMessage, validateOptions, report } = require('../../utils');
const parseSelector = require("../../utils/parseSelector");

const ruleName = nameSpace('selector-class-no-elements');
const messages = newMessage(ruleName, {
    
  expected: (selector => `Expected CLASS selector ".${
      selector}" not to contain "elements-"`)
})

const rule = primary => {
    

  return (postcssRoot, postcssResult) => {
    
    const validOptions = validateOptions(postcssRoot, postcssResult, {
    
      actual: primary
    })

    if (!validOptions) return;

    // walkRules  To traverse all  Rule Types of nodes 
    postcssRoot.walkRules(ruleNode => {
    

      const selector = ruleNode.selector;

      parseSelector(selector, postcssResult, ruleNode, (fullSelector) => {
    
        // walk Is traversal , Same as forEach
        fullSelector.walk(selectorNode => {
    
          //  Screening class Selectors 
          if (selectorNode.type !== 'class') return;

          const {
    value, sourceIndex} = selectorNode;

          //  Filter to  "elements-"  The opening selector 
          if (value.indexOf('elements') !== 0) return;

          //  Mark the end of the prompt 
          const endIndex = sourceIndex + value.length;

          //  Prompt user information 
          report({
    
            result: postcssResult,
            ruleName,
            message: messages.expected(value),
            node: ruleNode,
            index: sourceIndex,
            endIndex
          })
        })
      })
    })
  }
}

rule.ruleName = ruleName;
rule.messages = messages;

module.exports = rule;

lib/utils/index.js The contents are as follows

const stylelint = require("stylelint")

function nameSpace(ruleName) {
    
  //  The prefix depends on the individual 
  return `stylelint-plugin/${
      ruleName}`;
}

function newMessage(ruleName, options) {
    
  return stylelint.utils.ruleMessages(ruleName, options);
}

function validateOptions(result, ruleName, options) {
    
  return stylelint.utils.validateOptions(result, ruleName, options);
}

function report(problem) {
    
  console.log({
    problem});
  return stylelint.utils.report(problem);
}

module.exports = {
    
  nameSpace,
  newMessage,
  validateOptions,
  report
}

lib/utils/parseSelector.js The contents are as follows ：

const SelectorParser = require("postcss-selector-parser");

module.exports = function parseSelector(selector, result, node, callback) {
    
  try {
    
    return SelectorParser(callback).processSync(selector);
  } catch(err) {
    
    result.warn(`Cannot parse selector (${
      err})`, {
     node, stylelintType: 'parseError' });

    return undefined;
  }
}

lib/rules/index.js The contents are as follows ：

const selectorClassNoElements = require('./selector-class-no-elements');

const rules = {
    
  "selector-class-no-elements": selectorClassNoElements
}

module.exports = rules;

lib/index.js The contents are as follows ：

const {
     createPlugin } = require("stylelint");
const {
     nameSpace } = require("./utils");

const rules = require("./rules");

//  adopt createPlugin  establish  plugin
const rulesPlugins = Object.keys(rules).map(ruleName => {
    
  return createPlugin(nameSpace(ruleName), rules[ruleName])
})

module.exports = rulesPlugins;

6. Write test cases

The test case With the help of jest Tools .

1. Install the corresponding dependencies first ：

npm i jest jest-preset-stylelint -D

2. To configure jest, stay package.json The following configuration is added in ：

...
 "jest": {
    
    "clearMocks": true,
    "collectCoverage": false,
    "collectCoverageFrom": [
      "lib/**/*.js"
    ],
    "coverageDirectory": "./.coverage/",
    "coverageReporters": [
      "lcov",
      "text"
    ],
    "coverageThreshold": {
    
      "global": {
    
        "branches": 75,
        "functions": 75,
        "lines": 75,
        "statements": 75
      }
    },
    "setupFiles": [
      "./jest-setup.js"
    ],
    "testEnvironment": "node",
    "roots": [
      "lib"
    ],
    "testRegex": ".*\\.test\\.js$|lib/.*/__tests__/.*\\.js$"
  },
...

3. Created in the root directory jest-setup.js file , The contents are as follows ：

const getTestRule = require('jest-preset-stylelint/getTestRule');

global.testRule = getTestRule({
     plugins: ["./lib"] });

4. lib/rules/selector-class-no-elements/__tests__/index.js Write test code in ：( Add one under each rule __tests__/index.js Test case file )

const {
     messages, ruleName} = require("..");

testRule({
    
  ruleName,
  config: true,

  //  Use cases can be used 
  accept: [
    {
     code: '.app {}' }
  ],
  //  Not through use cases 
  reject: [
    {
     code: '.elements-app {}',
      message: messages.expected('elements-app'),
      line: 1, //  Prompt to start line 
      column: 1, //  Prompt start position 
      endLine: 1, //  Prompt end line 
      endColumn: 13 //  Prompt end position 
    }
  ]
})

7. npm run test

package.json To configure ：

...
"scripts": {
    
    "test": "jest"
},
...

function npm run test

The result is as follows. , Be accomplished .

8. The final directory structure

├── jest-setup.js
├── lib
│   ├── index.js
│   ├── rules
│   │   ├── index.js
│   │   └── selector-class-no-elements
│   │       ├── __tests__
│   │       │   └── index.js
│   │       └── index.js
│   └── utils
│       ├── index.js
│       └── parseSelector.js
├── package-lock.json
├── package.json
├── test.js
└── README.md

3、 ... and 、 Project coverage testing

Rule development is complete , You need to find a project for coverage testing . Generally, this kind of tool project is directly published to NPM Warehouse , Use through npm install xxx install .

To not publish npm package , Local testing Can pass npm link command , At the local node_modules Generate a soft link in , Link to the Development Directory .

1. Execute... In the directory above npm link Generate soft links
   

If npm link Later error reporting ：npm ERR! Error: EACCES: permission denied, Because of permission , You can use sudo npm link retry .

2. cd To test engineering ,“ install ” stylelint-plugin rely on
   
   Open the node_modules, You can see ：
   

3. Configure the test project .stylelintrc.js

module.exports = {
    
  ...
  "plugins":[
  	"stylelint-plugin"
  	...
  ],
  rules: {
    
    'stylelint-plugin/selector-class-no-elements': true,
    ...
  },
};