feat: @lexical/eslint-plugin - add a rules-of-lexical linter to help …

…with $function rules

.eslintrc.js

@@ -19,6 +19,7 @@ module.exports = {
     'fbjs',
     'plugin:react-hooks/recommended',
     'plugin:lexical/all',
+    'plugin:@lexical/all',
     'prettier',
   ],
 
@@ -79,8 +80,13 @@ module.exports = {
       },
     },
     {
-      // These aren't compiled, but they're written in module JS
-      files: ['packages/lexical-playground/esm/*.mjs'],
+      files: [
+        // These aren't compiled, but they're written in module JS
+        'packages/lexical-playground/esm/*.mjs',
+        // These are written in module JS for bootstrapping reasons, so we
+        // can use the plugin without compiling it first
+        'packages/lexical-eslint-plugin/**/*.mjs',
+      ],
       parserOptions: {
         sourceType: 'module',
       },
@@ -119,6 +125,7 @@ module.exports = {
     'react',
     'no-only-tests',
     'lexical',
+    '@lexical',
   ],
 
   // Stop ESLint from looking for a configuration file in parent folders

.flowconfig

@@ -24,6 +24,7 @@ module.name_mapper='^@lexical/clipboard$' -> '<PROJECT_ROOT>/packages/lexical-cl
 module.name_mapper='^@lexical/code$' -> '<PROJECT_ROOT>/packages/lexical-code/flow/LexicalCode.js.flow'
 module.name_mapper='^@lexical/devtools-core$' -> '<PROJECT_ROOT>/packages/lexical-devtools-core/flow/LexicalDevtoolsCore.js.flow'
 module.name_mapper='^@lexical/dragon$' -> '<PROJECT_ROOT>/packages/lexical-dragon/flow/LexicalDragon.js.flow'
+module.name_mapper='^@lexical/eslint-plugin$' -> '<PROJECT_ROOT>/packages/lexical-eslint-plugin/flow/LexicalEslintPlugin.js.flow'
 module.name_mapper='^@lexical/file$' -> '<PROJECT_ROOT>/packages/lexical-file/flow/LexicalFile.js.flow'
 module.name_mapper='^@lexical/hashtag$' -> '<PROJECT_ROOT>/packages/lexical-hashtag/flow/LexicalHashtag.js.flow'
 module.name_mapper='^@lexical/headless$' -> '<PROJECT_ROOT>/packages/lexical-headless/flow/LexicalHeadless.js.flow'

eslint-plugin/package.json

@@ -4,6 +4,6 @@
   "description": "ESLint plugin for lexical",
   "main": "src/index.js",
   "peerDependencies": {
-    "eslint": ">=4.19.1"
+    "eslint": "^7.31.0 || ^8.0.0"
   }
 }

package.json

@@ -114,6 +114,7 @@
     "@babel/preset-flow": "^7.14.5",
     "@babel/preset-react": "^7.14.5",
     "@babel/preset-typescript": "^7.16.7",
+    "@lexical/eslint-plugin": "file:./packages/lexical-eslint-plugin",
     "@playwright/test": "^1.41.2",
     "@rollup/plugin-alias": "^3.1.4",
     "@rollup/plugin-babel": "^5.3.0",

packages/lexical-devtools/tsconfig.json

@@ -14,6 +14,7 @@
       "@lexical/code": ["../lexical-code/src/index.ts"],
       "@lexical/devtools-core": ["../lexical-devtools-core/src/index.ts"],
       "@lexical/dragon": ["../lexical-dragon/src/index.ts"],
+      "@lexical/eslint-plugin": ["../lexical-eslint-plugin/src/index.ts"],
       "@lexical/file": ["../lexical-file/src/index.ts"],
       "@lexical/hashtag": ["../lexical-hashtag/src/index.ts"],
       "@lexical/headless": ["../lexical-headless/src/index.ts"],

packages/lexical-eslint-plugin/LexicalEslintPlugin.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+/**
+ * This file is here for bootstrapping reasons so we can use it without
+ * building anything
+ */
+module.exports = require('./src/LexicalEslintPlugin.js');

packages/lexical-eslint-plugin/README.md

@@ -0,0 +1,138 @@
+# `@lexical/eslint-plugin`
+
+This ESLint plugin enforces the [Lexical $function convention](https://lexical.dev/docs/intro#reading-and-updating-editor-state).
+
+## Installation
+
+Assuming you already have ESLint installed, run:
+
+```sh
+npm install @lexical/eslint-plugin --save-dev
+```
+
+Then extend the recommended eslint config:
+
+```js
+{
+  "extends": [
+    // ...
+    "plugin:@lexical/recommended"
+  ]
+}
+```
+
+### Custom Configuration
+
+If you want more fine-grained configuration, you can instead add a snippet like this to your ESLint configuration file:
+
+```js
+{
+  "plugins": [
+    // ...
+    "@lexical"
+  ],
+  "rules": {
+    // ...
+    "@lexical/rules-of-lexical": "error"
+  }
+}
+```
+
+
+## Valid and Invalid Examples
+
+### Valid Examples
+
+\$functions may be called by other \$functions
+
+```js
+function $namedCorrectly() {
+  return $getRoot();
+}
+```
+
+\$functions may be called in `editor.update` or `editorState.read`
+
+```js
+function validUsesEditorOrState(editor) {
+  editor.update(() => $getRoot());
+  editor.getLatestState().read(() => $getRoot());
+}
+```
+
+\$functions may be called from class methods
+
+```js
+class CustomNode extends ElementNode {
+  appendText(string) {
+    this.appendChild($createTextNode(string));
+  }
+}
+```
+
+### Invalid Examples
+
+#### Rename autofix
+
+```js
+function invalidFunction() {
+  return $getRoot();
+}
+function $callsInvalidFunction() {
+  return invalidFunction();
+}
+```
+
+*Autofix:* The function is renamed with a $ prefix. Any references to this
+name in this module are also always renamed.
+
+```js
+function $invalidFunction() {
+  return $getRoot();
+}
+function $callsInvalidFunction() {
+  return $invalidFunction();
+}
+```
+
+#### Rename & deprecate autofix
+
+```js
+export function exportedInvalidFunction() {
+  return $getRoot();
+}
+```
+
+*Autofix:* The exported function is renamed with a $ prefix. The previous name
+is also exported and marked deprecated, because automatic renaming of
+references to that name is limited to the module's scope.
+
+```js
+export function $exportedInvalidFunction() {
+  return $getRoot();
+}
+/** @deprecated renamed to $exportedInvalidFunction by @lexical/eslint-plugin rules-of-lexical */
+export const exportedInvalidFunction = $exportedInvalidFunction;
+```
+
+#### Rename scope conflict
+
+```js
+import {$getRoot} from 'lexical';
+function InvalidComponent({editor}) {
+  const [editor] = useLexicalComposerContext();
+  const getRoot = useCallback(() => $getRoot(), []);
+  return (<button onClick={() => editor.update(() => getRoot())} />);
+}
+```
+
+*Autofix:* The function is renamed with a $ prefix and _ suffix since the suggested name was already in scope.
+
+```js
+import {$getRoot} from 'lexical';
+function InvalidComponent({editor}) {
+  const [editor] = useLexicalComposerContext();
+  const $getRoot_ = useCallback(() => $getRoot(), []);
+  return (<button onClick={() => editor.update(() => $getRoot_())} />);
+}
+```

packages/lexical-eslint-plugin/flow/LexicalEslintPlugin.js.flow

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * LexicalEslintPlugin
+ */

packages/lexical-eslint-plugin/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lexical/eslint-plugin",
+  "description": "Lexical specific linting rules for ESLint",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "eslintplugin",
+    "lexical",
+    "editor"
+  ],
+  "version": "0.14.5",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facebook/lexical.git",
+    "directory": "packages/lexical-eslint-plugin"
+  },
+  "main": "LexicalEslintPlugin.js",
+  "types": "index.d.ts",
+  "bugs": {
+    "url": "https://github.com/facebook/lexical/issues"
+  },
+  "homepage": "https://github.com/facebook/lexical#readme",
+  "sideEffects": false,
+  "peerDependencies": {
+    "eslint": ">=7.31.0 || ^8.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "development": "./LexicalEslintPlugin.dev.mjs",
+        "production": "./LexicalEslintPlugin.prod.mjs",
+        "node": "./LexicalEslintPlugin.node.mjs",
+        "default": "./LexicalEslintPlugin.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "development": "./LexicalEslintPlugin.dev.js",
+        "production": "./LexicalEslintPlugin.prod.js",
+        "default": "./LexicalEslintPlugin.js"
+      }
+    }
+  },
+  "devDependencies": {
+    "@types/eslint": "^8.56.9"
+  },
+  "module": "LexicalEslintPlugin.mjs"
+}

packages/lexical-eslint-plugin/src/LexicalEslintPlugin.js

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+// @ts-check
+
+const {name, version} = require('../package.json');
+const rulesOfLexical = require('./rules/rules-of-lexical.js');
+
+const all = {
+  plugins: ['@lexical'],
+  rules: {
+    '@lexical/rules-of-lexical': 'warn',
+  },
+};
+
+const plugin = {
+  configs: {
+    all,
+    recommended: all,
+  },
+  meta: {name, version},
+  rules: {
+    'rules-of-lexical': rulesOfLexical,
+  },
+};
+
+module.exports = plugin;