eslint-plugin-code-style 1.0.34 → 1.0.39

package/AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md
+
+Instructions for AI coding agents working with this codebase.
+
+## Project Overview
+
+**eslint-plugin-code-style** is an ESLint plugin providing 47 custom auto-fixable formatting rules for React/JSX projects. It's designed for ESLint v9+ flat config system.
+
+- **Main entry:** `index.js` - Contains all 47 rules in a single file
+- **Type definitions:** `index.d.ts` - TypeScript declarations for IDE support
+- **Recommended configs:** `recommended-configs/` - Ready-to-use ESLint configurations
+- **Test apps:** `_tests_/` - Sample apps for testing rules
+
+### Available Configurations
+
+| Config | Folder | Status |
+|--------|--------|--------|
+| React (JS) | `react/` | Available |
+| React + TypeScript | `react-ts/` | Coming Soon |
+| React + TS + Tailwind | `react-ts-tw/` | Coming Soon |
+
+## Build & Test Commands
+
+```bash
+# No build step required - plain JavaScript ES modules
+
+# Test rules against a test app (e.g., react, react-ts, react-ts-tw)
+cd _tests_/<config-name>
+npm install
+npm run lint        # Check for errors
+npm run lint:fix    # Auto-fix issues
+
+# Publish (from root folder only)
+npm publish
+```
+
+## Code Structure
+
+All rules are defined in `index.js` with this structure:
+
+```
+index.js
+├── imports (fs, path, url)
+├── Rule 1 definition (const ruleName = { create(), meta: {} })
+├── Rule 2 definition
+├── ... (47 rules total)
+└── export default { meta: {}, rules: {} }
+```
+
+## Rule Implementation Pattern
+
+Every rule follows this exact structure:
+
+```javascript
+/**
+ * ───────────────────────────────────────────────────────────────
+ * Rule: Rule Name Here
+ * ───────────────────────────────────────────────────────────────
+ *
+ * Description:
+ *   Brief description of what the rule does.
+ *
+ * Options:
+ *   { optionName: defaultValue } - Description of option
+ *
+ * ✓ Good:
+ *   // Example of correct code
+ *
+ * ✗ Bad:
+ *   // Example of incorrect code
+ */
+const ruleName = {
+    create(context) {
+        const sourceCode = context.sourceCode || context.getSourceCode();
+        const options = context.options[0] || {};
+        const optionName = options.optionName !== undefined ? options.optionName : defaultValue;
+
+        return {
+            NodeType(node) {
+                // Rule logic here
+
+                // Report issues with auto-fix
+                context.report({
+                    fix: (fixer) => fixer.replaceText(node, "fixed code"),
+                    message: "Error message describing the issue",
+                    node,
+                });
+            },
+        };
+    },
+    meta: {
+        docs: { description: "Short description for documentation" },
+        fixable: "code",  // Required for auto-fix rules
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    optionName: {
+                        default: 3,
+                        description: "Option description",
+                        minimum: 1,
+                        type: "integer",
+                    },
+                },
+                type: "object",
+            },
+        ],
+        type: "layout",  // "layout" for formatting, "suggestion" for conventions
+    },
+};
+```
+
+### Adding a New Rule
+
+1. Add the rule definition (const) following the pattern above
+2. Add to the `rules` object in the default export (keep alphabetical within categories)
+3. Update `index.d.ts` to add the rule name to the `RuleNames` type
+4. Update `README.md`:
+   - Add to the Rules Summary table
+   - Add detailed description with examples
+5. Add to relevant recommended configs in `recommended-configs/`
+
+## Key Patterns & Conventions
+
+### Source Code Access
+```javascript
+const sourceCode = context.sourceCode || context.getSourceCode();
+```
+
+### Options with Defaults
+```javascript
+const options = context.options[0] || {};
+const maxItems = options.maxItems !== undefined ? options.maxItems : 3;
+```
+
+### Getting Tokens
+```javascript
+const openBracket = sourceCode.getFirstToken(node);
+const closeBracket = sourceCode.getLastToken(node);
+const tokenBefore = sourceCode.getTokenBefore(node);
+const tokenAfter = sourceCode.getTokenAfter(node);
+```
+
+### Getting Text
+```javascript
+const text = sourceCode.getText(node);
+const lines = sourceCode.lines;  // Array of all lines
+```
+
+### Indentation Calculation
+```javascript
+const lineText = sourceCode.lines[node.loc.start.line - 1];
+const baseIndent = lineText.match(/^\s*/)[0];
+const itemIndent = baseIndent + "    ";  // 4 spaces
+```
+
+### Fixer Methods
+```javascript
+fixer.replaceText(node, "new text")
+fixer.replaceTextRange([start, end], "new text")
+fixer.insertTextBefore(node, "text")
+fixer.insertTextAfter(node, "text")
+fixer.remove(node)
+fixer.removeRange([start, end])
+```
+
+### Common Node Type Checks
+```javascript
+// Check parent type
+if (node.parent && node.parent.type === "Property") { }
+
+// Check for specific patterns
+if (node.type === "ArrowFunctionExpression") { }
+if (node.type === "JSXElement") { }
+if (node.type === "ObjectExpression") { }
+
+// React hooks detection
+if (/^use[A-Z]/.test(node.callee.name)) { }
+```
+
+### Skip Conditions (Common Patterns)
+```javascript
+// Skip empty structures
+if (elements.length === 0) return;
+
+// Skip complex elements
+const hasComplexElement = elements.some((el) =>
+    el.type === "SpreadElement" ||
+    el.type === "ObjectExpression" ||
+    el.type === "ArrowFunctionExpression"
+);
+if (hasComplexElement) return;
+
+// Skip specific parent contexts
+if (node.parent?.type === "CallExpression") return;
+```
+
+## Rule Categories
+
+Rules are organized in these categories (see default export):
+
+- **Array rules:** `array-*`
+- **Arrow function rules:** `arrow-function-*`, `curried-arrow-*`
+- **Assignment rules:** `assignment-*`
+- **Block statement rules:** `block-statement-*`
+- **Comment rules:** `comment-*`
+- **Function rules:** `function-*`
+- **Hook rules:** `hook-*`
+- **If statement rules:** `if-statement-*`, `multiline-if-*`
+- **Import/Export rules:** `absolute-imports-*`, `export-*`, `import-*`, `index-export-*`, `module-index-*`
+- **JSX rules:** `jsx-*`
+- **Member expression rules:** `member-expression-*`
+- **Nested call rules:** `nested-call-*`
+- **No empty lines rules:** `no-empty-lines-*`
+- **Object property rules:** `object-property-*`
+- **Opening brackets rules:** `opening-brackets-*`
+- **Simple call rules:** `simple-call-*`, `single-argument-*`
+- **String property rules:** `string-property-*`
+- **Variable rules:** `variable-*`
+
+## Naming Conventions
+
+- **Rule names:** kebab-case (e.g., `array-items-per-line`)
+- **Internal variables:** camelCase (e.g., `arrayItemsPerLine`)
+- **Handler functions:** end with `Handler` (e.g., `checkPatternHandler`)
+- **Options:** camelCase (e.g., `maxItems`, `minProperties`)
+
+## Meta Types
+
+- `type: "layout"` - Formatting/whitespace rules (most rules)
+- `type: "suggestion"` - Code convention rules (naming conventions)
+
+## Documentation Files
+
+- `README.md` - Main documentation with all 47 rules
+- `recommended-configs/<config-name>/README.md` - Config-specific documentation (references main README for rule details)
+- `index.d.ts` - TypeScript types for IDE autocomplete
+
+## Important Notes
+
+- All rules must be auto-fixable (`fixable: "code"` in meta)
+- Use 4-space indentation throughout
+- Object properties in `context.report()` must be alphabetically sorted
+- Keep rules self-sufficient (no dependencies on other ESLint rules)
+- Test with relevant test app in `_tests_/` before publishing

package/README.md

@@ -17,7 +17,7 @@
 
 **A powerful ESLint plugin for enforcing consistent code formatting and style rules in React/JSX projects.**
 
-*48 auto-fixable rules to keep your codebase clean and consistent*
+*47 auto-fixable rules to keep your codebase clean and consistent*
 
 </div>
 
@@ -25,15 +25,18 @@
 
 ## 🎯 Why This Plugin?
 
-This plugin provides **48 custom auto-fixable rules** for code formatting. Built for **ESLint v9 flat configs**.
+This plugin provides **47 custom auto-fixable rules** for code formatting. Built for **ESLint v9 flat configs**.
 
 > **Note:** ESLint [deprecated 79 formatting rules](https://eslint.org/blog/2023/10/deprecating-formatting-rules/) in v8.53.0. Our recommended configs use `@stylistic/eslint-plugin` as the replacement for these deprecated rules.
 
 **Key Benefits:**
 - **Fills the gaps** — Provides formatting rules not available in other plugins
+- **Works alongside existing tools** — Complements ESLint's built-in rules and packages like eslint-plugin-react, eslint-plugin-import, etc
 - **Self-sufficient rules** — Each rule handles complete formatting independently
-- **Consistency at scale** — Reduces code-style differences between team members by ~95%
-- **Fully automated** — All 48 rules support auto-fix, eliminating manual style reviews
+- **Consistency at scale** — Reduces code-style differences between team members by enforcing uniform formatting across your projects
+- **Fully automated** — All 47 rules support auto-fix, eliminating manual style reviews
+
+When combined with ESLint's native rules and other popular plugins, this package helps create a complete code style solution that keeps your codebase clean and consistent.
 
 <div align="center">
 
@@ -55,7 +58,7 @@ We provide **ready-to-use ESLint flat configuration files** that combine `eslint
 
 ### 💡 Why Use These Configs?
 
-- **Complete Coverage** — Combines ESLint built-in rules, third-party plugins, and all 48 code-style rules
+- **Complete Coverage** — Combines ESLint built-in rules, third-party plugins, and all 47 code-style rules
 - **Ready-to-Use** — Copy the config file and start linting immediately
 - **Battle-Tested** — These configurations have been refined through real-world usage
 - **Fully Documented** — Each config includes detailed instructions and explanations
@@ -65,8 +68,8 @@ We provide **ready-to-use ESLint flat configuration files** that combine `eslint
 | Configuration | Description | Link |
 |---------------|-------------|------|
 | **React** | React.js projects (JavaScript, JSX) | [View Config](./recommended-configs/react/) |
+| **React + TypeScript** | React + TypeScript | *Coming Soon* |
 | **React + TS + Tailwind** | React + TypeScript + Tailwind CSS | *Coming Soon* |
-| **Next.js + TS + Tailwind** | Next.js + TypeScript + Tailwind CSS | *Coming Soon* |
 
 ### ⚡ Quick Start with Recommended Config
 
@@ -91,7 +94,7 @@ We provide **ready-to-use ESLint flat configuration files** that combine `eslint
 <td width="50%">
 
 ### 🔧 Auto-Fixable Rules
-All **48 rules** support automatic fixing with `eslint --fix`. No manual code changes needed.
+All **47 rules** support automatic fixing with `eslint --fix`. No manual code changes needed.
 
 </td>
 <td width="50%">
@@ -183,7 +186,7 @@ rules: {
     "code-style/curried-arrow-same-line": "error",
     "code-style/assignment-value-same-line": "error",
     "code-style/block-statement-newlines": "error",
-    "code-style/comment-spacing": "error",
+    "code-style/comment-format": "error",
     "code-style/function-call-spacing": "error",
     "code-style/function-naming-convention": "error",
     "code-style/function-params-per-line": "error",
@@ -231,7 +234,7 @@ rules: {
 
 ## 📖 Rules Summary
 
-> All **48 rules** are auto-fixable. See detailed examples for each rule in the [Rules Reference](#-rules-reference) section below.
+> All **47 rules** are auto-fixable. See detailed examples for each rule in the [Rules Reference](#-rules-reference) section below.
 >
 > Rules marked with ⚙️ support customization options (e.g., extending default folder lists).
 
@@ -245,7 +248,7 @@ rules: {
 | `curried-arrow-same-line` | Curried arrow functions start on same line as `=>`, not on new line |
 | `assignment-value-same-line` | Assignment values start on same line as `=`, not on new line |
 | `block-statement-newlines` | Newline after `{` and before `}` in if/for/while/function blocks |
-| `comment-spacing` | Space after `//`, space inside `/* */`, convert single-line blocks to `//`, no blank lines between file-top comments |
+| `comment-format` | Space after `//`, space inside `/* */`, convert single-line blocks to `//`, no blank lines between file-top comments |
 | `function-call-spacing` | No space between function name and `(`: `fn()` not `fn ()` |
 | `function-naming-convention` | Functions use camelCase, start with verb (get/set/handle/is/has), handlers end with Handler |
 | `function-params-per-line` | When multiline, each param on own line with consistent indentation |
@@ -551,7 +554,7 @@ for (const item of items) { process(item);
 
 ---
 
-### `comment-spacing`
+### `comment-format`
 
 **What it does:** Enforces proper comment formatting:
 - Space after `//` in line comments

package/index.d.ts

@@ -12,9 +12,10 @@ export type RuleNames =
     | "code-style/arrow-function-simplify"
     | "code-style/assignment-value-same-line"
     | "code-style/block-statement-newlines"
-    | "code-style/comment-spacing"
+    | "code-style/comment-format"
     | "code-style/curried-arrow-same-line"
     | "code-style/export-format"
+    | "code-style/function-arguments-format"
     | "code-style/function-call-spacing"
     | "code-style/function-naming-convention"
     | "code-style/function-params-per-line"
@@ -23,6 +24,7 @@ export type RuleNames =
     | "code-style/if-statement-format"
     | "code-style/import-format"
     | "code-style/import-source-spacing"
+    | "code-style/index-export-style"
     | "code-style/jsx-children-on-new-line"
     | "code-style/jsx-closing-bracket-spacing"
     | "code-style/jsx-element-child-new-line"
@@ -34,9 +36,7 @@ export type RuleNames =
     | "code-style/jsx-ternary-format"
     | "code-style/member-expression-bracket-spacing"
     | "code-style/module-index-exports"
-    | "code-style/multiline-argument-newline"
     | "code-style/multiline-if-conditions"
-    | "code-style/multiple-arguments-per-line"
     | "code-style/nested-call-closing-brackets"
     | "code-style/no-empty-lines-in-function-calls"
     | "code-style/no-empty-lines-in-function-params"
@@ -81,9 +81,10 @@ interface PluginRules {
     "arrow-function-simplify": Rule.RuleModule;
     "assignment-value-same-line": Rule.RuleModule;
     "block-statement-newlines": Rule.RuleModule;
-    "comment-spacing": Rule.RuleModule;
+    "comment-format": Rule.RuleModule;
     "curried-arrow-same-line": Rule.RuleModule;
     "export-format": Rule.RuleModule;
+    "function-arguments-format": Rule.RuleModule;
     "function-call-spacing": Rule.RuleModule;
     "function-naming-convention": Rule.RuleModule;
     "function-params-per-line": Rule.RuleModule;
@@ -92,6 +93,7 @@ interface PluginRules {
     "if-statement-format": Rule.RuleModule;
     "import-format": Rule.RuleModule;
     "import-source-spacing": Rule.RuleModule;
+    "index-export-style": Rule.RuleModule;
     "jsx-children-on-new-line": Rule.RuleModule;
     "jsx-closing-bracket-spacing": Rule.RuleModule;
     "jsx-element-child-new-line": Rule.RuleModule;
@@ -103,9 +105,7 @@ interface PluginRules {
     "jsx-ternary-format": Rule.RuleModule;
     "member-expression-bracket-spacing": Rule.RuleModule;
     "module-index-exports": Rule.RuleModule;
-    "multiline-argument-newline": Rule.RuleModule;
     "multiline-if-conditions": Rule.RuleModule;
-    "multiple-arguments-per-line": Rule.RuleModule;
     "nested-call-closing-brackets": Rule.RuleModule;
     "no-empty-lines-in-function-calls": Rule.RuleModule;
     "no-empty-lines-in-function-params": Rule.RuleModule;
@@ -117,7 +117,7 @@ interface PluginRules {
     "object-property-value-format": Rule.RuleModule;
     "opening-brackets-same-line": Rule.RuleModule;
     "simple-call-single-line": Rule.RuleModule;
-    "single-argument-on-line": Rule.RuleModule;
+    "single-argument-on-one-line": Rule.RuleModule;
     "string-property-spacing": Rule.RuleModule;
     "variable-naming-convention": Rule.RuleModule;
 }

package/index.js

@@ -1138,7 +1138,7 @@ const blockStatementNewlines = {
  *   //This is a comment (missing space)
  *   [block]No space after opener[/block]
  */
-const commentSpacing = {
+const commentFormat = {
     create(context) {
         const sourceCode = context.sourceCode || context.getSourceCode();
 
@@ -6446,10 +6446,30 @@ const objectPropertyPerLine = {
             if (!valueNode) return true;
 
             // Simple values can always be collapsed
-            if (["Literal", "Identifier", "TemplateLiteral", "MemberExpression", "UnaryExpression"].includes(valueNode.type)) {
+            if (["Literal", "Identifier", "MemberExpression", "UnaryExpression"].includes(valueNode.type)) {
                 return true;
             }
 
+            // Template literals: can only collapse if single-line (multi-line templates would break)
+            if (valueNode.type === "TemplateLiteral") {
+                return valueNode.loc.start.line === valueNode.loc.end.line;
+            }
+
+            // Call expressions: can only collapse if already on single line
+            if (valueNode.type === "CallExpression") {
+                return valueNode.loc.start.line === valueNode.loc.end.line;
+            }
+
+            // Arrow functions: can only collapse if already on single line
+            if (valueNode.type === "ArrowFunctionExpression") {
+                return valueNode.loc.start.line === valueNode.loc.end.line;
+            }
+
+            // Spread elements: check if the argument can be collapsed
+            if (valueNode.type === "SpreadElement") {
+                return canCollapse(valueNode.argument);
+            }
+
             // Arrays: can collapse only if already on single line (let array-items-per-line handle it)
             if (valueNode.type === "ArrayExpression") {
                 const isAlreadySingleLine = valueNode.loc.start.line === valueNode.loc.end.line;
@@ -6465,11 +6485,15 @@ const objectPropertyPerLine = {
 
                 if (properties.length >= minProperties) return false;
 
-                // Check all property values can be collapsed
-                return properties.every((prop) => canCollapse(prop.value));
+                // Check all property values can be collapsed (handle SpreadElement)
+                return properties.every((prop) => {
+                    if (prop.type === "SpreadElement") return canCollapse(prop.argument);
+
+                    return canCollapse(prop.value);
+                });
             }
 
-            // Other complex types (functions, calls, etc.) cannot be collapsed
+            // Other complex types (functions, etc.) cannot be collapsed
             return false;
         };
 
@@ -6488,6 +6512,11 @@ const objectPropertyPerLine = {
                 if (properties.length === 0) return "{}";
 
                 const propsText = properties.map((prop) => {
+                    // Handle SpreadElement (e.g., ...obj)
+                    if (prop.type === "SpreadElement") {
+                        return `...${getCollapsedText(prop.argument)}`;
+                    }
+
                     const keyText = prop.computed ? `[${sourceCode.getText(prop.key)}]` : sourceCode.getText(prop.key);
                     const valueText = getCollapsedText(prop.value);
 
@@ -6517,12 +6546,21 @@ const objectPropertyPerLine = {
             if (properties.length < minProperties) {
                 const isMultiline = openBrace.loc.start.line !== closeBrace.loc.end.line;
 
-                // Check if all property values can be collapsed
-                const allCanCollapse = properties.every((prop) => canCollapse(prop.value));
+                // Check if all property values can be collapsed (handle SpreadElement)
+                const allCanCollapse = properties.every((prop) => {
+                    if (prop.type === "SpreadElement") return canCollapse(prop.argument);
+
+                    return canCollapse(prop.value);
+                });
 
                 if (isMultiline && allCanCollapse) {
                     // Generate collapsed text for all properties
                     const propertiesText = properties.map((prop) => {
+                        // Handle SpreadElement (e.g., ...obj)
+                        if (prop.type === "SpreadElement") {
+                            return `...${getCollapsedText(prop.argument)}`;
+                        }
+
                         const keyText = prop.computed ? `[${sourceCode.getText(prop.key)}]` : sourceCode.getText(prop.key);
                         const valueText = getCollapsedText(prop.value);
 
@@ -8372,7 +8410,7 @@ export default {
         "block-statement-newlines": blockStatementNewlines,
 
         // Comment rules
-        "comment-spacing": commentSpacing,
+        "comment-format": commentFormat,
 
         // Function rules
         "function-call-spacing": functionCallSpacing,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-code-style",
-    "version": "1.0.34",
+    "version": "1.0.39",
     "description": "A custom ESLint plugin for enforcing consistent code formatting and style rules in React/JSX projects",
     "main": "index.js",
     "types": "index.d.ts",
@@ -15,6 +15,7 @@
     "files": [
         "index.js",
         "index.d.ts",
+        "AGENTS.md",
         "README.md",
         "LICENSE"
     ],