關(guān)于Eslint-plugin的研究，今天主要談兩點(diǎn)：

實(shí)現(xiàn)一個(gè)簡(jiǎn)單的plugin插件。

eslint如何處理plugin插件。

接著上一篇《Eslint源碼探索》，今天探索一下plugin。今天是研究課。

實(shí)現(xiàn)一個(gè)簡(jiǎn)單的plugin插件

關(guān)于Plugin官方文檔說(shuō)的比較詳細(xì)，但是內(nèi)容太多，這里羅列了幾條關(guān)鍵的步驟：

• 生成plugin模版
• 生成rule規(guī)則
• rule規(guī)則對(duì)象配置屬性說(shuō)明
• 單元測(cè)試

這里以生成一個(gè)單行注釋不允許出現(xiàn)的字段為例。展開(kāi)對(duì)plugin的探索。

官方提供了模版生成的工具Yeoman。這里一樣：

// 下載
pnpm install -g yo generator-eslint

// 生產(chǎn)模版 
yo eslint:plugin

// 生成rule
yo eslint:rule

模版的結(jié)構(gòu)也比較簡(jiǎn)單，提供了三個(gè)功能，這三個(gè)功能都可以通過(guò)yo eslint：rule自動(dòng)生成。

• docs文檔說(shuō)明。每一個(gè)rule都有各自的md。
• lib核心庫(kù)，包含每一個(gè)rule。
• tests測(cè)試用例。每一個(gè)rule都是單獨(dú)的用例。

依賴第三方包如下：eslint相關(guān)和測(cè)試相關(guān)的。

requireindex這個(gè)包，會(huì)把lib下的所有rules打包成一個(gè)對(duì)象。比較實(shí)用，以后在其他項(xiàng)目中也會(huì)用到。

// requireIndex 把多文件包裝成對(duì)象
const  requireIndex  =  require("requireindex");
module.exports.rules =  requireIndex(__dirname +  "/rules");

// 打印一下，包裝的rules
{
   // ...
  'notes-keys': {
    meta: {
      type: 'suggestion',
      docs: [Object],
      fixable: 'code',
      schema: [Array]
    },
    create: [Function: create]
  }
}

mocha主要用于測(cè)試。

接下來(lái)進(jìn)入rules，了解一下rules詳細(xì)的配置：

在meta中，type較為關(guān)鍵，表示此規(guī)則的必要性：

• problem，表示此代碼會(huì)導(dǎo)致錯(cuò)誤和異常行為，是優(yōu)先要處理的。
• suggestion，表示此代碼只是建議，可以有更好的方式來(lái)完成。
• layout，表示代碼的美觀性，比如空格、逗號(hào)、封號(hào)等。

  meta: {
    type: 'suggestion', // `problem`, `suggestion`, or `layout`
    docs: {
      description: "校驗(yàn)注釋中是否包含指定關(guān)鍵詞",
      category: "Stylistic Issues", // 規(guī)則分類
      recommended: true, // 配置文件中的 "extends":"eslint:recommended"屬性是否啟用該規(guī)則，當(dāng)創(chuàng)建的規(guī)則push到eslint核心規(guī)則才生效
      url: null, // URL to the documentation page for this rule
    },
    fixable: 'code', // Or `code` or `whitespace`
    // 如fixable主要用于fix功能，如果不設(shè)置fixable，eslint將默認(rèn)此規(guī)則不可修復(fù)
    schema: [
      {
        "keyWords": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    ], // Add a schema if the rule has options
  },

fixable主要用于修復(fù)規(guī)則，在eslint-plugin包中此處為必填，官方推薦此處必須配置。與之相對(duì)應(yīng)的在create中context.report中fix函數(shù)相對(duì)應(yīng)，修復(fù)函數(shù)的回調(diào)。

在schema中定義的字段，主要用于傳入的配置，例如上面的例子，要想指定某些字段在注釋中禁用，這些自定義禁用的字段需要傳入到context中。此處用于限定傳入字段的屬性。當(dāng)我使用此rule的時(shí)候，可以這樣處理：

rules: {
    // foo表示在注釋中禁用的字段
    "foo/notes-keys": [2, { keyWords: ['foo'] }]
}

create返回一個(gè)對(duì)象，包含eslint在遍歷語(yǔ)法樹(shù)時(shí)，用來(lái)訪問(wèn)節(jié)點(diǎn)的方法。這些訪問(wèn)節(jié)點(diǎn)的方法很多。這也是生成插件比較難的地方，因?yàn)樽叩竭@里你需要了解AST的節(jié)點(diǎn)類型相關(guān)的知識(shí)。

上圖是針對(duì)AST節(jié)點(diǎn)類型的一些簡(jiǎn)單的總結(jié)，在eslint源碼中定義的訪問(wèn)NodeType的如下圖。除了源碼中定義的，還有第三方定義，比如在react中就有JSXAttribute和JSXElement等自定義AST節(jié)點(diǎn)。

這里先把create的代碼放在這里，圖中的Program就是AST節(jié)點(diǎn)訪問(wèn)的方法。

接下來(lái)，開(kāi)始講講context，context顧名思義，在這里幾乎是無(wú)所不能的，它主要能幫我們做的事情，有以下幾點(diǎn)：

• 獲取配置中的信息，如settings、parser相關(guān)的屬性。
• 獲取遍歷節(jié)點(diǎn)的數(shù)組，比如聲明的變量、參數(shù)的變量、函數(shù)的變量、說(shuō)明符的變量等。
• 獲取與源文件關(guān)聯(lián)的文件名。
• 獲取源碼。
• 獲取作用域中所有的變量和引用。
• 報(bào)告有問(wèn)題的代碼。

create中的邏輯比較簡(jiǎn)單，獲取到單行注釋，然后判斷是否有配置中的字段，如果有就report。此插件已發(fā)布到npm上，供大家學(xué)習(xí)參考。在npm上直接搜eslint-plugin-foo，只有一個(gè)rule。也可點(diǎn)擊文章底部原文鏈接查看github上源碼。

使用也簡(jiǎn)單，

// .eslintrc.js
plugins: ['foo'],
rules: {
    "foo/notes-keys": [2, { keyWords: ['foo'] }]
}

在發(fā)布之前，我們還得寫一下單元測(cè)試，這個(gè)也簡(jiǎn)單，eslint提供了RuleTester方法，我們只需寫幾個(gè)簡(jiǎn)單的實(shí)例就行。

const rule = require("../../../lib/rules/notes-keys"),
  RuleTester = require("eslint").RuleTester;

const ruleTester = new RuleTester();
const errMsg = (msg) => `注釋中含有不被允許的字符${msg}`;
ruleTester.run("notes-keys", rule, {
  valid: ['// sssss', '// attr'], //生效的， 失效的

  invalid: [
    {
      code: `// xxx:測(cè)試內(nèi)容`,
      errors: [{ message: errMsg('xxx') }],
      options: [{ // 通過(guò)options 配置自定義參數(shù)
        keyWords: ['xxx']
      }],
      // 添加fix修復(fù)必須添加output，output輸出的內(nèi)容要和rule中fix返回的結(jié)果一致
      output: `// :測(cè)試內(nèi)容`,
    },
    {
      code: `// str11: const s='測(cè)試內(nèi)容'`,
      errors: [{ message: errMsg('str') }],
      options: [{ // 通過(guò)options 配置自定義參數(shù)
        keyWords: ['str']
      }],
      // 添加fix修復(fù)必須添加output，output輸出的內(nèi)容要和rule中fix返回的結(jié)果一致
      output: `// 11: const s='測(cè)試內(nèi)容'`,
    }
  ],
});

運(yùn)行一下

eslint如何加載plugin插件

關(guān)于plugin的處理沒(méi)在eslint庫(kù)里，而是引用了另一個(gè)庫(kù)@eslint/eslintrc中，這里需要注意一點(diǎn)node在v14版本之后就支持了ES模塊的書(shū)寫，簡(jiǎn)而言之，我們可以在node文件中使用import/export。然后通過(guò)命令行執(zhí)行node命令即可。

接著上一篇，我們聊到關(guān)于plugin、extends和parser的處理在ConfigArrayFactory中。

這里的探索過(guò)程也簡(jiǎn)單，下載@eslint/eslintrc的源碼，npm install就緒之后，我們創(chuàng)建一個(gè)demo.js的文件。順便下載我們發(fā)布的插件eslint-plugin-foo，在配置文件中加入。

demo中的代碼如下，我們固定一個(gè)path來(lái)讓它向下流轉(zhuǎn)，通過(guò)node命令執(zhí)行，方便我們查看它執(zhí)行的步驟。

plugin的大致加載流程，和在源碼中的位置，如下：

在loadInDirectory中，我們可查看當(dāng)前的配置文件對(duì)象，也就是我們配置foo的地方。這個(gè)時(shí)候，還沒(méi)有加載plugin。

在_loadPlugin中，能獲取到foo配置的數(shù)據(jù)。

最后在configArray中收集生效的規(guī)則。

最后在demo.js中打印config。已經(jīng)把foo插件變成一個(gè)對(duì)象，把rule也放在了rules中。

關(guān)于plugin的了解，先到這里。