@lms5400/eslint-plugin-rsx 1.0.0

package/README.md

@@ -0,0 +1,191 @@
+# @lms5400/eslint-plugin-rsx
+
+ESLint rules for **RSX components**.
+
+RSX files use JSX syntax but **do not follow React’s runtime or hook model**.  
+This plugin enforces RSX-specific semantics while remaining compatible with React projects.
+
+See https://github.com/LMS007/babel-plugin-rsx
+
+---
+
+## What this plugin enforces
+
+RSX components are **not React components**. This plugin helps enforce that distinction by:
+
+- Disallowing React hooks (`useState`, `useEffect`, etc.)
+- Disallowing `useRef`
+- Requiring RSX context destructuring
+- Allowing JSX syntax
+
+---
+
+## Requirements
+
+- **ESLint ≥ 8.57** (flat config)
+- Node.js ≥ 18
+- [babel-plugin-rsx](https://www.npmjs.com/package/@lms5400/babel-plugin-rsx/)
+
+---
+
+## Installation
+npm
+```bash
+npm install --save-dev eslint @lms5400/eslint-plugin-rsx
+```
+Or yarn
+```bash
+yarn add -D eslint @lms5400/eslint-plugin-rsx
+```
+
+---
+
+## Basic setup (React + RSX)
+
+This setup assumes:
+- `.jsx / .tsx` files use normal React rules
+- `.rsx` files use RSX rules
+- ESLint flat config is enabled
+
+### eslint.config.js (or eslint.config.cjs)
+
+```js
+import js from "@eslint/js";
+import globals from "globals";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import rsx from "@lms5400/eslint-plugin-rsx";
+
+export default [
+  js.configs.recommended,
+
+  // ----------------------------------------
+  // React JSX / TSX files
+  // ----------------------------------------
+  {
+    files: ["**/*.{jsx,tsx}"],
+    plugins: {
+      react,
+      "react-hooks": reactHooks,
+    },
+    rules: {
+      // React + hooks rules
+    },
+  },
+
+  // ----------------------------------------
+  // RSX files
+  // ----------------------------------------
+  {
+    files: ["**/*.rsx"],
+    plugins: {
+      rsx,
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
+    },
+    rules: {
+      "rsx/no-react-hooks": "error",
+      "rsx/no-use-ref": "warn",
+      "rsx/require-ctx-destructure": "error",
+    },
+  },
+];
+```
+
+---
+
+## Why React rules are not applied to `.rsx`
+
+RSX files:
+- may contain JSX
+- do **not** use React hooks
+- do **not** rely on React reconciliation
+- have explicit lifecycle management
+
+Applying `eslint-plugin-react` rules to `.rsx` files often produces **incorrect or misleading errors**.
+
+If you want minimal JSX hygiene, you may selectively enable rules like:
+- `react/jsx-no-undef`
+- `react/jsx-uses-vars`
+
+Full React recommended rules are **not advised** for RSX.
+
+---
+
+## VS Code setup (required)
+
+The ESLint VS Code extension does **not** automatically lint custom extensions like `.rsx`.
+
+Add the following to your workspace settings.
+
+### .vscode/settings.json
+
+```json
+{
+  "eslint.useFlatConfig": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "rsx"
+  ],
+  "files.associations": {
+    "*.rsx": "javascriptreact"
+  },
+  "eslint.nodePath": "./node_modules"
+}
+```
+
+After changing settings:
+1. Open Command Palette
+2. Run **“ESLint: Restart ESLint Server”**
+3. Reload the window if needed
+
+---
+
+## Verifying the setup
+
+Create a test RSX file:
+
+```js
+export default function Test(ctx) {
+  useState(0);
+}
+```
+
+Expected:
+- ❌ ESLint error
+- Rule: `rsx/no-react-hooks`
+- Visible inline and in the Problems panel
+
+---
+
+## Rules
+
+| Rule | Description |
+|------|-------------|
+| `rsx/no-react-hooks` | Disallow React hooks in RSX |
+| `rsx/no-use-ref` | Disallow `useRef` |
+| `rsx/require-ctx-destructure` | Require RSX context destructuring |
+
+---
+
+## Design philosophy
+
+- RSX is explicit and lifecycle-driven
+- JSX is syntax, not a runtime commitment
+- Linting should enforce RSX semantics, not React assumptions
+
+---
+
+## License
+
+MIT

package/index.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  rules: {
+    "no-react-hooks": require("./rules/no-react-hooks.cjs"),
+    "no-use-ref": require("./rules/no-use-ref.cjs"),
+    "require-ctx-destructure": require("./rules/require-ctx-destructure.cjs"),
+  },
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@lms5400/eslint-plugin-rsx",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LMS007/eslint-plugin-rsx.git"
+  },
+  "version": "1.0.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "description": "ESLint rules for RSX components",
+  "main": "index.cjs",
+  "type": "commonjs",
+  "files": [
+    "index.cjs",
+    "rules"
+  ],
+  "peerDependencies": {
+    "eslint": "^8.0.0 || ^9.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "eslint-rule-tester": "^2.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "rsx",
+    "react",
+    "lint"]
+}

package/rules/allow-unused-ctx-vars.cjs

@@ -0,0 +1,44 @@
+"use strict";
+
+const ALLOWED_ARGS = /^(ctx|view|render|update|destroy|props)$/;
+const ALLOWED_VARS = /^(view|render|update|destroy|props)$/;
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Ignore unused RSX context lifecycle variables",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    function isIgnored(variable) {
+      const name = variable.name;
+
+      // Function parameters (destructured ctx)
+      if (variable.defs.some(d => d.type === "Parameter")) {
+        return ALLOWED_ARGS.test(name);
+      }
+
+      // Local variables
+      return ALLOWED_VARS.test(name);
+    }
+
+    return {
+      "Program:exit"() {
+        const scope = context.getScope();
+
+        for (const variable of scope.variables) {
+          if (isIgnored(variable)) continue;
+          if (variable.references.length === 0) {
+            context.report({
+              node: variable.identifiers[0],
+              message: `'${variable.name}' is defined but never used.`,
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-react-hooks.cjs

@@ -0,0 +1,34 @@
+const BANNED = new Set([
+  "useState",
+  "useEffect",
+  "useLayoutEffect",
+  "useReducer",
+  "useCallback",
+  "useMemo",
+  "useContext"
+]);
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow React hooks in RSX files"
+    }
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          BANNED.has(node.callee.name)
+        ) {
+          context.report({
+            node,
+            message: `${node.callee.name} is not allowed in RSX components`
+          });
+        }
+      }
+    };
+  }
+};

package/rules/no-use-ref.cjs

@@ -0,0 +1,26 @@
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow useRef in RSX components"
+    }
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "useRef"
+        ) {
+          context.report({
+            node,
+            message:
+              "useRef is not allowed in RSX components. " +
+              "Use regular variables instead."
+          });
+        }
+      }
+    };
+  }
+};

package/rules/require-ctx-destructure.cjs

@@ -0,0 +1,39 @@
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require RSX context parameter to be destructured"
+    }
+  },
+
+  create(context) {
+    function check(node) {
+      if (!node.params || node.params.length !== 1) return;
+
+      const param = node.params[0];
+
+      if (param.type === "Identifier") {
+        context.report({
+          node: param,
+          message:
+            "RSX components must destructure the context parameter. " +
+            "Use: function Component({ view, update, render, destroy, props }) { ... }"
+        });
+      }
+    }
+
+    return {
+      ExportDefaultDeclaration(node) {
+        const decl = node.declaration;
+        if (
+          decl &&
+          (decl.type === "FunctionDeclaration" ||
+           decl.type === "FunctionExpression" ||
+           decl.type === "ArrowFunctionExpression")
+        ) {
+          check(decl);
+        }
+      }
+    };
+  }
+};