@wsxjs/eslint-plugin-wsx 0.0.11 → 0.0.12

package/README.md

@@ -2,6 +2,192 @@
 
 ESLint plugin for WSX Framework - enforces best practices and framework-specific rules for Web Components with JSX.
 
+## Installation
+
+```bash
+npm install --save-dev @wsxjs/eslint-plugin-wsx
+# or
+pnpm add -D @wsxjs/eslint-plugin-wsx
+# or
+yarn add -D @wsxjs/eslint-plugin-wsx
+```
+
+## Setup
+
+### ESLint 9+ (Flat Config)
+
+Create or update `eslint.config.js` (or `eslint.config.mjs`):
+
+```javascript
+import js from "@eslint/js";
+import typescript from "@typescript-eslint/eslint-plugin";
+import typescriptParser from "@typescript-eslint/parser";
+import wsxPlugin from "@wsxjs/eslint-plugin-wsx";
+import globals from "globals";
+
+export default [
+    {
+        ignores: ["**/dist/", "**/node_modules/"],
+    },
+    js.configs.recommended,
+    {
+        files: ["**/*.{ts,tsx,js,jsx,wsx}"],
+        languageOptions: {
+            parser: typescriptParser,
+            parserOptions: {
+                ecmaVersion: "latest",
+                sourceType: "module",
+                ecmaFeatures: {
+                    jsx: true,
+                },
+                jsxPragma: "h",
+                jsxFragmentName: "Fragment",
+                experimentalDecorators: true, // Required for @state decorator
+                extraFileExtensions: [".wsx"],
+            },
+            globals: {
+                ...globals.browser,
+                ...globals.es2021,
+                h: "readonly",
+                Fragment: "readonly",
+            },
+        },
+        plugins: {
+            "@typescript-eslint": typescript,
+            wsx: wsxPlugin,
+        },
+        rules: {
+            ...typescript.configs.recommended.rules,
+            // WSX plugin rules
+            "wsx/render-method-required": "error",
+            "wsx/no-react-imports": "error",
+            "wsx/web-component-naming": "warn",
+            "wsx/state-requires-initial-value": "error",
+        },
+    },
+];
+```
+
+### Required Dependencies
+
+Make sure you have these peer dependencies installed:
+
+```bash
+npm install --save-dev eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser globals
+```
+
+## Rules
+
+### `wsx/render-method-required`
+
+**Error level**: `error`
+
+Ensures WSX components implement the required `render()` method.
+
+**Invalid**:
+```typescript
+class MyComponent extends WebComponent {
+    // Missing render() method
+}
+```
+
+**Valid**:
+```typescript
+class MyComponent extends WebComponent {
+    render() {
+        return <div>Hello</div>;
+    }
+}
+```
+
+### `wsx/no-react-imports`
+
+**Error level**: `error`
+
+Prevents React imports in WSX files. WSX uses its own JSX runtime.
+
+**Invalid**:
+```typescript
+import React from "react"; // ❌
+import { useState } from "react"; // ❌
+```
+
+**Valid**:
+```typescript
+import { WebComponent, state } from "@wsxjs/wsx-core"; // ✅
+```
+
+### `wsx/web-component-naming`
+
+**Error level**: `warn`
+
+Enforces proper Web Component tag naming conventions (kebab-case with at least one hyphen).
+
+**Invalid**:
+```typescript
+@autoRegister({ tagName: "mycomponent" }) // ❌ Missing hyphen
+@autoRegister({ tagName: "MyComponent" }) // ❌ Not kebab-case
+```
+
+**Valid**:
+```typescript
+@autoRegister({ tagName: "my-component" }) // ✅
+@autoRegister({ tagName: "wsx-button" }) // ✅
+```
+
+### `wsx/state-requires-initial-value`
+
+**Error level**: `error`
+
+Requires `@state` decorator properties to have initial values. This is mandatory because we need the initial value to determine if it's a primitive or object/array.
+
+**Invalid**:
+```typescript
+class MyComponent extends WebComponent {
+    @state private maskStrokeColor?: string; // ❌ Missing initial value
+}
+```
+
+**Valid**:
+```typescript
+class MyComponent extends WebComponent {
+    @state private maskStrokeColor = ""; // ✅ String
+    @state private count = 0; // ✅ Number
+    @state private user = { name: "John" }; // ✅ Object
+    @state private items = []; // ✅ Array
+    @state private optional?: string = undefined; // ✅ Optional with explicit undefined
+}
+```
+
+## Configuration Options
+
+### Disable Specific Rules
+
+If you need to disable a specific rule:
+
+```javascript
+{
+    rules: {
+        "wsx/web-component-naming": "off", // Disable naming rule
+        "wsx/state-requires-initial-value": "warn", // Change to warning
+    },
+}
+```
+
+### File-Specific Rules
+
+Apply rules only to `.wsx` files:
+
+```javascript
+{
+    files: ["**/*.wsx"],
+    rules: {
+        "wsx/render-method-required": "error",
+        "wsx/no-react-imports": "error",
+    },
+}
+```
+
 ## Testing Results
 
 ✅ **38 tests passed** with **100% code coverage**
@@ -38,6 +224,7 @@ This plugin now uses industry-standard testing practices:
 - 🔍 **render-method-required**: Ensures WSX components implement the required `render()` method
 - 🚫 **no-react-imports**: Prevents React imports in WSX files 
 - 🏷️ **web-component-naming**: Enforces proper Web Component tag naming conventions
+- ✅ **state-requires-initial-value**: Requires `@state` decorator properties to have initial values
 
 ## Framework Integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wsxjs/eslint-plugin-wsx",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "ESLint plugin for WSX Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -25,7 +25,7 @@
     "web-components"
   ],
   "dependencies": {
-    "@wsxjs/wsx-core": "0.0.11"
+    "@wsxjs/wsx-core": "0.0.12"
   },
   "devDependencies": {
     "tsup": "^8.0.0",

package/src/configs/recommended.ts

@@ -16,6 +16,7 @@ export const recommendedConfig: WSXConfig = {
         },
         jsxPragma: "h",
         jsxFragmentName: "Fragment",
+        experimentalDecorators: true, // Required to parse @state decorators
     },
     plugins: ["wsx"],
     rules: {
@@ -23,6 +24,7 @@ export const recommendedConfig: WSXConfig = {
         "wsx/render-method-required": "error",
         "wsx/no-react-imports": "error",
         "wsx/web-component-naming": "warn",
+        "wsx/state-requires-initial-value": "error",
 
         // TypeScript 规则（推荐）
         "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],

package/src/index.ts

@@ -8,6 +8,7 @@
 import { renderMethodRequired } from "./rules/render-method-required";
 import { noReactImports } from "./rules/no-react-imports";
 import { webComponentNaming } from "./rules/web-component-naming";
+import { stateRequiresInitialValue } from "./rules/state-requires-initial-value";
 import { recommendedConfig } from "./configs/recommended";
 import { createFlatConfig } from "./configs/flat";
 import { WSXPlugin } from "./types";
@@ -24,6 +25,7 @@ const plugin: WSXPlugin = {
         "render-method-required": renderMethodRequired,
         "no-react-imports": noReactImports,
         "web-component-naming": webComponentNaming,
+        "state-requires-initial-value": stateRequiresInitialValue,
     },
 
     // 配置预设

package/src/rules/state-requires-initial-value.ts

@@ -0,0 +1,136 @@
+/**
+ * ESLint 规则：state-requires-initial-value
+ *
+ * 确保 @state 装饰器的属性必须有初始值
+ * 这是强制性的，因为我们需要初始值来判断是 primitive 还是 object/array
+ */
+
+import { Rule } from "eslint";
+import { WSXRuleModule } from "../types";
+
+export const stateRequiresInitialValue: WSXRuleModule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "require @state decorator properties to have initial values",
+            category: "Possible Errors",
+            recommended: true,
+        },
+        messages: {
+            missingInitialValue:
+                "@state decorator on property '{{propertyName}}' requires an initial value.\n" +
+                "\n" +
+                "Examples:\n" +
+                "  @state private {{propertyName}} = '';  // for string\n" +
+                "  @state private {{propertyName}} = 0;  // for number\n" +
+                "  @state private {{propertyName}} = {};  // for object\n" +
+                "  @state private {{propertyName}} = [];  // for array\n" +
+                "  @state private {{propertyName}} = undefined;  // for optional",
+        },
+        schema: [],
+    },
+    create(context: Rule.RuleContext) {
+        // Track imported 'state' identifiers from @wsxjs/wsx-core
+        const stateImports = new Set<string>();
+
+        return {
+            // Track imports to identify @state decorator
+            ImportDeclaration(node) {
+                if (
+                    node.source.type === "Literal" &&
+                    typeof node.source.value === "string" &&
+                    node.source.value === "@wsxjs/wsx-core"
+                ) {
+                    node.specifiers.forEach((specifier) => {
+                        if (specifier.type === "ImportSpecifier") {
+                            if (
+                                specifier.imported.type === "Identifier" &&
+                                specifier.imported.name === "state"
+                            ) {
+                                // Track both the imported name and any alias
+                                const localName =
+                                    specifier.local.type === "Identifier"
+                                        ? specifier.local.name
+                                        : null;
+                                if (localName) {
+                                    stateImports.add(localName);
+                                }
+                            }
+                        } else if (specifier.type === "ImportDefaultSpecifier") {
+                            // Handle default import (less common but possible)
+                            const localName =
+                                specifier.local.type === "Identifier" ? specifier.local.name : null;
+                            if (localName) {
+                                stateImports.add(localName);
+                            }
+                        } else if (specifier.type === "ImportNamespaceSpecifier") {
+                            // Handle namespace import: import * as wsx from '@wsxjs/wsx-core'
+                            // In this case, @state would be wsx.state, which is harder to detect
+                            // We'll check for both 'state' and namespace.state patterns
+                            const localName =
+                                specifier.local.type === "Identifier" ? specifier.local.name : null;
+                            if (localName) {
+                                // For namespace imports, we'd need to check member expressions
+                                // This is more complex, so we'll also check for plain 'state'
+                                stateImports.add("state");
+                            }
+                        }
+                    });
+                }
+            },
+
+            // Check class properties for @state decorator
+            // Support both ClassProperty (older) and PropertyDefinition (newer TypeScript ESLint)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            "ClassProperty, ClassPrivateProperty, PropertyDefinition"(node: any) {
+                if (!node.decorators || node.decorators.length === 0) {
+                    return;
+                }
+
+                // Check if any decorator is @state
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const hasStateDecorator = node.decorators.some((decorator: any) => {
+                    if (decorator.expression.type === "Identifier") {
+                        // Direct identifier: @state
+                        return (
+                            decorator.expression.name === "state" ||
+                            stateImports.has(decorator.expression.name)
+                        );
+                    } else if (decorator.expression.type === "CallExpression") {
+                        // Call expression: @state()
+                        if (decorator.expression.callee.type === "Identifier") {
+                            return (
+                                decorator.expression.callee.name === "state" ||
+                                stateImports.has(decorator.expression.callee.name)
+                            );
+                        }
+                    } else if (decorator.expression.type === "MemberExpression") {
+                        // Member expression: @namespace.state
+                        if (
+                            decorator.expression.property.type === "Identifier" &&
+                            decorator.expression.property.name === "state"
+                        ) {
+                            return true;
+                        }
+                    }
+                    return false;
+                });
+
+                if (hasStateDecorator && !node.value) {
+                    const propertyName =
+                        node.key.type === "Identifier"
+                            ? node.key.name
+                            : node.key.type === "PrivateIdentifier"
+                              ? node.key.name
+                              : "unknown";
+
+                    context.report({
+                        node,
+                        messageId: "missingInitialValue",
+                        data: { propertyName },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/types.ts

@@ -24,6 +24,7 @@ export interface WSXConfig {
         };
         jsxPragma?: string;
         jsxFragmentName?: string;
+        experimentalDecorators?: boolean; // Required for @state decorator support
     };
     plugins?: string[];
     rules?: Record<string, unknown>;