@sarj/eslint-plugin 0.2.1 → 1.0.0

package/README.md

@@ -1,9 +1,138 @@
-# sarj-eslint
+# @sarj/eslint-plugin
 
-Collection of custom ESLint rules.
+Custom ESLint rules collection for Sarj projects. Supports ESLint 9+ flat config format.
 
 ## Installation
 
 ```bash
-npm install sarj-eslint --save-dev
+yarn add -D @sarj/eslint-plugin eslint
 ```
+
+## Usage (ESLint 9+ Flat Config)
+
+```js
+// eslint.config.js
+import sarj, { configs } from "@sarj/eslint-plugin";
+
+export default [
+  // Use a preset config
+  ...configs.recommended,
+
+  // Or configure manually
+  {
+    plugins: {
+      "@sarj": sarj,
+    },
+    rules: {
+      "@sarj/zod-naming-convention": "warn",
+      "@sarj/require-assert-never": "error",
+    },
+  },
+];
+```
+
+## Available Configs
+
+| Config | Description |
+|--------|-------------|
+| `configs.recommended` | Basic sarj rules for everyday use |
+| `configs.strict` | All sarj rules at error level |
+| `configs.style-guide` | Comprehensive rules (sarj + core ESLint) |
+
+## Rules
+
+| Rule | Description | Recommended |
+|------|-------------|-------------|
+| `@sarj/zod-naming-convention` | Enforce Zod schemas to be named with a Z prefix | warn |
+| `@sarj/require-assert-never` | Require assertNever in switch default cases | error |
+| `@sarj/require-zod-form-validation` | Require Zod validation when parsing FormData | error |
+| `@sarj/enforce-file-structure` | Enforce consistent file structure | warn |
+| `@sarj/no-raw-env` | Disallow direct process.env access | - |
+| `@sarj/prefer-shadcn` | Prefer shadcn/ui components over native HTML | - |
+| `@sarj/no-enum` | Disallow TypeScript enums | - |
+
+## Rule Details
+
+### `zod-naming-convention`
+
+Ensures Zod schemas are named with a Z prefix for consistency.
+
+```ts
+// Bad
+const userSchema = z.object({ name: z.string() });
+
+// Good
+const ZUserSchema = z.object({ name: z.string() });
+```
+
+### `require-assert-never`
+
+Ensures switch statements with default cases use assertNever for exhaustive type checking.
+
+```ts
+// Bad
+switch (status) {
+  case "active":
+    return 1;
+  default:
+    return 0;
+}
+
+// Good
+switch (status) {
+  case "active":
+    return 1;
+  default:
+    assertNever(status);
+}
+```
+
+### `no-raw-env`
+
+Disallows direct access to process.env. Use a Zod-validated env schema instead.
+
+```ts
+// Bad
+const apiKey = process.env.API_KEY;
+
+// Good
+const apiKey = env.API_KEY; // from validated schema
+```
+
+### `prefer-shadcn`
+
+Encourages use of shadcn/ui components instead of native HTML elements.
+
+```tsx
+// Bad
+<button onClick={handleClick}>Submit</button>
+
+// Good
+<Button onClick={handleClick}>Submit</Button>
+```
+
+### `no-enum`
+
+Discourages TypeScript enums in favor of union types or const objects.
+
+```ts
+// Bad
+enum Status {
+  Active,
+  Inactive,
+}
+
+// Good
+type Status = "active" | "inactive";
+// or
+const Status = { ACTIVE: "active", INACTIVE: "inactive" } as const;
+```
+
+## Requirements
+
+- ESLint >= 9.0.0
+- Node.js >= 18.0.0
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { ESLint, Linter, Rule } from "eslint";
+/**
+ * @sarj/eslint-plugin
+ *
+ * Custom ESLint rules collection for Sarj projects.
+ * Supports ESLint 9+ flat config format.
+ */
+declare const rules: Record<string, Rule.RuleModule>;
+declare const plugin: ESLint.Plugin;
+declare const configs: Record<string, Linter.Config[]>;
+export { plugin as default, configs, rules };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAUnD;;;;;GAKG;AAEH,QAAA,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,CAQ1C,CAAC;AAEF,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,MAMpB,CAAC;AAGF,QAAA,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAsE5C,CAAC;AAEF,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,98 @@
+import { zodNamingConvention } from "./rules/zod-naming-convention.js";
+import { requireAssertNever } from "./rules/require-assert-never.js";
+import { requireZodFormValidation } from "./rules/require-zod-form-validation.js";
+import { enforceFileStructure } from "./rules/enforce-file-structure.js";
+import { noRawEnv } from "./rules/no-raw-env.js";
+import { preferShadcn } from "./rules/prefer-shadcn.js";
+import { noEnum } from "./rules/no-enum.js";
+/**
+ * @sarj/eslint-plugin
+ *
+ * Custom ESLint rules collection for Sarj projects.
+ * Supports ESLint 9+ flat config format.
+ */
+const rules = {
+    "zod-naming-convention": zodNamingConvention,
+    "require-assert-never": requireAssertNever,
+    "require-zod-form-validation": requireZodFormValidation,
+    "enforce-file-structure": enforceFileStructure,
+    "no-raw-env": noRawEnv,
+    "prefer-shadcn": preferShadcn,
+    "no-enum": noEnum,
+};
+const plugin = {
+    meta: {
+        name: "@sarj/eslint-plugin",
+        version: "1.0.0",
+    },
+    rules,
+};
+// ESLint 9 flat configs
+const configs = {
+    // Basic sarj rules only
+    recommended: [
+        {
+            plugins: {
+                "@sarj": plugin,
+            },
+            rules: {
+                "@sarj/zod-naming-convention": "warn",
+                "@sarj/require-assert-never": "error",
+                "@sarj/require-zod-form-validation": "error",
+                "@sarj/enforce-file-structure": "warn",
+            },
+        },
+    ],
+    // All sarj rules at error level
+    strict: [
+        {
+            plugins: {
+                "@sarj": plugin,
+            },
+            rules: {
+                "@sarj/zod-naming-convention": "error",
+                "@sarj/require-assert-never": "error",
+                "@sarj/require-zod-form-validation": "error",
+                "@sarj/enforce-file-structure": "error",
+                "@sarj/no-raw-env": "error",
+                "@sarj/prefer-shadcn": "error",
+                "@sarj/no-enum": "error",
+            },
+        },
+    ],
+    // Comprehensive style guide rules (sarj + external)
+    "style-guide": [
+        {
+            plugins: {
+                "@sarj": plugin,
+            },
+            rules: {
+                // === Sarj custom rules ===
+                "@sarj/zod-naming-convention": "error",
+                "@sarj/require-assert-never": "error",
+                "@sarj/require-zod-form-validation": "error",
+                "@sarj/enforce-file-structure": "error",
+                "@sarj/no-raw-env": "error",
+                "@sarj/prefer-shadcn": "error",
+                "@sarj/no-enum": "error",
+                // === Core ESLint rules ===
+                "no-var": "error",
+                "prefer-const": "error",
+                "object-shorthand": ["error", "always"],
+                "no-nested-ternary": "error",
+                "no-console": ["warn", { allow: ["warn", "error"] }],
+                eqeqeq: ["error", "always"],
+                "no-param-reassign": "error",
+                "no-return-await": "error",
+                "prefer-template": "error",
+                "array-callback-return": "error",
+                // === Complexity limits ===
+                complexity: ["warn", { max: 15 }],
+                "max-depth": ["warn", { max: 4 }],
+                "max-nested-callbacks": ["warn", { max: 3 }],
+                "max-params": ["error", { max: 5 }],
+            },
+        },
+    ],
+};
+export { plugin as default, configs, rules };

package/dist/rules/enforce-file-structure.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+export declare const enforceFileStructure: Rule.RuleModule;
+export default enforceFileStructure;
+//# sourceMappingURL=enforce-file-structure.d.ts.map

package/dist/rules/enforce-file-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce-file-structure.d.ts","sourceRoot":"","sources":["../../src/rules/enforce-file-structure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAgDnC,eAAO,MAAM,oBAAoB,EAAE,IAAI,CAAC,UA8DvC,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/dist/rules/enforce-file-structure.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Enforce consistent file structure
+ * @description Enforces: imports -> types -> constants -> functions -> exports
+ */
+const SECTIONS = ["imports", "types", "constants", "functions", "exports"];
+function getStatementSection(statement) {
+    const type = statement.type;
+    switch (type) {
+        case "ImportDeclaration":
+            return 0; // imports
+        case "TSTypeAliasDeclaration":
+        case "TSInterfaceDeclaration":
+        case "TSEnumDeclaration":
+            return 1; // types
+        case "VariableDeclaration": {
+            // Check if it's a constant (const with UPPER_CASE or simple values)
+            const varDecl = statement;
+            if (varDecl.kind === "const") {
+                const declarator = varDecl.declarations[0];
+                if (declarator?.id.type === "Identifier" &&
+                    declarator.id.name === declarator.id.name.toUpperCase()) {
+                    return 2; // constants
+                }
+            }
+            return 3; // functions (const fn = ...)
+        }
+        case "FunctionDeclaration":
+            return 3; // functions
+        case "ExportNamedDeclaration":
+        case "ExportDefaultDeclaration":
+            return 4; // exports
+        default:
+            return 3; // default to functions
+    }
+}
+export const enforceFileStructure = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Enforce consistent file structure: imports -> types -> constants -> functions -> exports",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            incorrectOrder: "File structure violation: {{current}} should come after {{expected}}",
+            useServerDirective: "Server action files must start with 'use server' directive",
+        },
+    },
+    create(context) {
+        const filename = context.filename;
+        const isServerAction = filename.includes("/actions/") || filename.includes("action");
+        return {
+            Program(node) {
+                const program = node;
+                const body = program.body;
+                let currentSection = 0;
+                // Check for "use server" directive in server action files
+                if (isServerAction) {
+                    const firstNode = body[0];
+                    if (!firstNode ||
+                        firstNode.type !== "ExpressionStatement" ||
+                        firstNode.expression.type !== "Literal" ||
+                        firstNode.expression.value !== "use server") {
+                        context.report({
+                            node,
+                            messageId: "useServerDirective",
+                        });
+                    }
+                }
+                for (const statement of body) {
+                    const statementSection = getStatementSection(statement);
+                    if (statementSection < currentSection) {
+                        context.report({
+                            node: statement,
+                            messageId: "incorrectOrder",
+                            data: {
+                                current: SECTIONS[statementSection],
+                                expected: SECTIONS[currentSection],
+                            },
+                        });
+                    }
+                    else {
+                        currentSection = Math.max(currentSection, statementSection);
+                    }
+                }
+            },
+        };
+    },
+};
+export default enforceFileStructure;

package/dist/rules/no-enum.d.ts

@@ -0,0 +1,8 @@
+import type { Rule } from "eslint";
+/**
+ * @fileoverview Disallow TypeScript enums, prefer union types
+ * @description Enums add runtime code and have unintuitive behavior. Use union types instead.
+ */
+export declare const noEnum: Rule.RuleModule;
+export default noEnum;
+//# sourceMappingURL=no-enum.d.ts.map

package/dist/rules/no-enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-enum.d.ts","sourceRoot":"","sources":["../../src/rules/no-enum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;GAGG;AAEH,eAAO,MAAM,MAAM,EAAE,IAAI,CAAC,UAyBzB,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/rules/no-enum.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Disallow TypeScript enums, prefer union types
+ * @description Enums add runtime code and have unintuitive behavior. Use union types instead.
+ */
+export const noEnum = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Disallow TypeScript enums, prefer union types or const objects",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            noEnum: 'Enums are discouraged. Use union types (\'type Status = "active" | "inactive"\') or const objects instead.',
+        },
+    },
+    create(context) {
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            TSEnumDeclaration(node) {
+                context.report({
+                    node,
+                    messageId: "noEnum",
+                });
+            },
+        };
+    },
+};
+export default noEnum;

package/dist/rules/no-enum.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=no-enum.test.d.ts.map

package/dist/rules/no-enum.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-enum.test.d.ts","sourceRoot":"","sources":["../../src/rules/no-enum.test.ts"],"names":[],"mappings":""}

package/dist/rules/no-enum.test.js

@@ -0,0 +1,44 @@
+import { RuleTester } from "eslint";
+import { describe, it } from "vitest";
+import { noEnum } from "./no-enum.js";
+// Note: This test requires @typescript-eslint/parser to work properly
+// For now, we'll skip the actual test execution and just verify the rule exports correctly
+describe("no-enum", () => {
+    it("should export a valid rule module", () => {
+        if (!noEnum.meta || !noEnum.create) {
+            throw new Error("Rule is not properly exported");
+        }
+        if (noEnum.meta.type !== "suggestion") {
+            throw new Error("Expected rule type to be 'suggestion'");
+        }
+        if (!noEnum.meta.messages?.noEnum) {
+            throw new Error("Expected noEnum message to be defined");
+        }
+    });
+    // Full test requires TypeScript parser
+    it("should work with TypeScript parser", async () => {
+        const parser = await import("@typescript-eslint/parser");
+        const ruleTester = new RuleTester({
+            languageOptions: {
+                ecmaVersion: 2022,
+                sourceType: "module",
+                parser,
+            },
+        });
+        ruleTester.run("no-enum", noEnum, {
+            valid: [
+                // Union types are OK
+                { code: 'type Status = "active" | "inactive";' },
+                // Const objects are OK
+                { code: 'const Status = { ACTIVE: "active", INACTIVE: "inactive" } as const;' },
+            ],
+            invalid: [
+                // Regular enum
+                {
+                    code: "enum Status { Active, Inactive }",
+                    errors: [{ messageId: "noEnum" }],
+                },
+            ],
+        });
+    });
+});

package/dist/rules/no-raw-env.d.ts

@@ -0,0 +1,8 @@
+import type { Rule } from "eslint";
+/**
+ * @fileoverview Disallow direct process.env access
+ * @description Use Zod-validated env schema instead of process.env
+ */
+export declare const noRawEnv: Rule.RuleModule;
+export default noRawEnv;
+//# sourceMappingURL=no-raw-env.d.ts.map

package/dist/rules/no-raw-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-raw-env.d.ts","sourceRoot":"","sources":["../../src/rules/no-raw-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnC;;;GAGG;AAEH,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,UA8B3B,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/rules/no-raw-env.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Disallow direct process.env access
+ * @description Use Zod-validated env schema instead of process.env
+ */
+export const noRawEnv = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow direct process.env access",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            noRawEnv: "Use Zod-validated env schema instead of process.env directly",
+        },
+    },
+    create(context) {
+        return {
+            MemberExpression(node) {
+                if (node.object.type === "Identifier" &&
+                    node.object.name === "process" &&
+                    node.property.type === "Identifier" &&
+                    node.property.name === "env") {
+                    context.report({
+                        node,
+                        messageId: "noRawEnv",
+                    });
+                }
+            },
+        };
+    },
+};
+export default noRawEnv;

package/dist/rules/no-raw-env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=no-raw-env.test.d.ts.map

package/dist/rules/no-raw-env.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-raw-env.test.d.ts","sourceRoot":"","sources":["../../src/rules/no-raw-env.test.ts"],"names":[],"mappings":""}

package/dist/rules/no-raw-env.test.js

@@ -0,0 +1,36 @@
+import { RuleTester } from "eslint";
+import { describe, it } from "vitest";
+import { noRawEnv } from "./no-raw-env.js";
+const ruleTester = new RuleTester({
+    languageOptions: {
+        ecmaVersion: 2022,
+        sourceType: "module",
+    },
+});
+describe("no-raw-env", () => {
+    it("should pass valid and fail invalid cases", () => {
+        ruleTester.run("no-raw-env", noRawEnv, {
+            valid: [
+                // Using validated env schema
+                { code: 'const apiKey = env.API_KEY;' },
+                { code: 'const dbUrl = config.databaseUrl;' },
+                { code: 'const { NODE_ENV } = validatedEnv;' },
+            ],
+            invalid: [
+                // Direct process.env access
+                {
+                    code: 'const apiKey = process.env.API_KEY;',
+                    errors: [{ messageId: "noRawEnv" }],
+                },
+                {
+                    code: 'if (process.env.NODE_ENV === "production") {}',
+                    errors: [{ messageId: "noRawEnv" }],
+                },
+                {
+                    code: 'console.log(process.env.DEBUG);',
+                    errors: [{ messageId: "noRawEnv" }],
+                },
+            ],
+        });
+    });
+});

package/dist/rules/prefer-shadcn.d.ts

@@ -0,0 +1,4 @@
+import type { Rule } from "eslint";
+export declare const preferShadcn: Rule.RuleModule;
+export default preferShadcn;
+//# sourceMappingURL=prefer-shadcn.d.ts.map

package/dist/rules/prefer-shadcn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefer-shadcn.d.ts","sourceRoot":"","sources":["../../src/rules/prefer-shadcn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAgBnC,eAAO,MAAM,YAAY,EAAE,IAAI,CAAC,UAwC/B,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/rules/prefer-shadcn.js

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Prefer shadcn/ui components over native HTML elements
+ * @description Use shadcn components for consistent design system
+ */
+const REPLACEMENTS = {
+    button: "Button",
+    input: "Input",
+    select: "Select",
+    textarea: "Textarea",
+    table: "Table",
+    dialog: "Dialog",
+};
+export const preferShadcn = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Prefer shadcn/ui components over native HTML elements",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            preferShadcn: "Use shadcn <{{replacement}}> component from @/components/ui/{{lowercase}} instead of native <{{element}}>",
+        },
+    },
+    create(context) {
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXOpeningElement(node) {
+                // Only check lowercase element names (native HTML)
+                if (!node.name || node.name.type !== "JSXIdentifier") {
+                    return;
+                }
+                const elementName = node.name.name;
+                const replacement = REPLACEMENTS[elementName];
+                if (replacement) {
+                    context.report({
+                        node,
+                        messageId: "preferShadcn",
+                        data: {
+                            element: elementName,
+                            replacement,
+                            lowercase: elementName,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+export default preferShadcn;

package/dist/rules/prefer-shadcn.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prefer-shadcn.test.d.ts.map

package/dist/rules/prefer-shadcn.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefer-shadcn.test.d.ts","sourceRoot":"","sources":["../../src/rules/prefer-shadcn.test.ts"],"names":[],"mappings":""}

package/dist/rules/prefer-shadcn.test.js

@@ -0,0 +1,58 @@
+import { RuleTester } from "eslint";
+import { describe, it } from "vitest";
+import { preferShadcn } from "./prefer-shadcn.js";
+const ruleTester = new RuleTester({
+    languageOptions: {
+        ecmaVersion: 2022,
+        sourceType: "module",
+        parserOptions: {
+            ecmaFeatures: {
+                jsx: true,
+            },
+        },
+    },
+});
+describe("prefer-shadcn", () => {
+    it("should pass valid and fail invalid cases", () => {
+        ruleTester.run("prefer-shadcn", preferShadcn, {
+            valid: [
+                // shadcn components are OK
+                { code: '<Button onClick={handleClick}>Click me</Button>' },
+                { code: '<Input type="text" placeholder="Enter name" />' },
+                { code: '<Select value={value} onValueChange={setValue} />' },
+                { code: '<Table><TableBody /></Table>' },
+                // Other elements are OK
+                { code: '<div className="container">Content</div>' },
+                { code: '<span>Text</span>' },
+                { code: '<form onSubmit={handleSubmit}></form>' },
+            ],
+            invalid: [
+                // Native button
+                {
+                    code: '<button onClick={handleClick}>Click me</button>',
+                    errors: [{ messageId: "preferShadcn" }],
+                },
+                // Native input
+                {
+                    code: '<input type="text" placeholder="Enter name" />',
+                    errors: [{ messageId: "preferShadcn" }],
+                },
+                // Native select
+                {
+                    code: '<select value={value} onChange={handleChange}><option>A</option></select>',
+                    errors: [{ messageId: "preferShadcn" }],
+                },
+                // Native textarea
+                {
+                    code: '<textarea rows={5} />',
+                    errors: [{ messageId: "preferShadcn" }],
+                },
+                // Native table
+                {
+                    code: '<table><tbody /></table>',
+                    errors: [{ messageId: "preferShadcn" }],
+                },
+            ],
+        });
+    });
+});