# @wsxjs/eslint-plugin-wsx

ESLint plugin for WSXJS - 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,
            "@typescript-eslint/no-explicit-any": "warn",
            "@typescript-eslint/no-unused-vars": [
                "error",
                {
                    argsIgnorePattern: "^_",
                    varsIgnorePattern: "^_",
                },
            ],
            // WSX plugin rules
            "wsx/render-method-required": "error",
            "wsx/no-react-imports": "error",
            "wsx/web-component-naming": "warn",
            "wsx/state-requires-initial-value": "error",
            "no-undef": "off", // TypeScript handles this
        },
    },
];
```

### Required Dependencies

Make sure you have these peer dependencies installed:

```bash
npm install --save-dev eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser globals
```

**Important**: The `experimentalDecorators: true` option in `parserOptions` is **required** for the `wsx/state-requires-initial-value` rule to work correctly. Without it, ESLint cannot parse `@state` decorators and the rule will not detect violations.

## 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:
1. The Babel plugin needs the initial value to determine if it's a primitive (uses `useState`) or object/array (uses `reactive`)
2. Without an initial value, the decorator cannot be properly transformed at compile time
3. The runtime fallback also requires an initial value to set up reactive state correctly

**Invalid**:
```typescript
class MyComponent extends WebComponent {
    @state private maskStrokeColor?: string; // ❌ Missing initial value
    @state private count; // ❌ Missing initial value
    @state private user; // ❌ Missing initial value
}
```

**Valid**:
```typescript
class MyComponent extends WebComponent {
    @state private maskStrokeColor = ""; // ✅ String
    @state private count = 0; // ✅ Number
    @state private enabled = false; // ✅ Boolean
    @state private user = { name: "John" }; // ✅ Object
    @state private items = []; // ✅ Array
    @state private optional: string | undefined = undefined; // ✅ Optional with explicit undefined
    @state private size?: number = 32; // ✅ Optional with default value
}
```

**Error Message Example**:
```
@state decorator on property 'size' requires an initial value.

Examples:
  @state private size = '';  // for string
  @state private size = 0;  // for number
  @state private size = {};  // for object
  @state private size = [];  // for array
  @state private size = undefined;  // for optional
```

## 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**
✅ **Professional test suite** using Jest and ESLint RuleTester
✅ **Integration tests** verify real-world usage scenarios

## Test Coverage Summary
- **Statements**: 100%
- **Branches**: 96.96%
- **Functions**: 100% 
- **Lines**: 100%

## Better Testing Approach

This plugin now uses industry-standard testing practices:

### 1. Unit Tests with RuleTester
- Each rule has dedicated test files
- Valid/invalid code examples with expected errors
- Proper AST node testing

### 2. Integration Tests
- Full plugin functionality testing
- Real ESLint configuration scenarios
- Complex component examples

### 3. Comprehensive Coverage
- All rules tested with edge cases
- Error messages and fix suggestions verified
- Plugin structure and exports validated

## Features

- 🔍 **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

The examples package serves as a **real-world testing environment** where:
1. The ESLint plugin is properly configured and tested
2. All WSX components demonstrate correct framework usage
3. Plugin rules catch actual coding errors in development
4. Framework developers can validate plugin effectiveness

This approach ensures the plugin works correctly in production environments, not just in isolated tests.