eslint-plugin-solodev 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julian Wagner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# eslint-plugin-solodev
+
+10 ESLint rules that replace code review for solo developers.
+
+When there's no one to catch your `throw new Error()` or your empty `catch {}`, these rules do it for you. Built from real patterns that caused production bugs in a one-person SaaS.
+
+## Install
+
+```bash
+npm install eslint-plugin-solodev --save-dev
+```
+
+## Setup (flat config)
+
+```js
+// eslint.config.mjs
+import solodev from 'eslint-plugin-solodev'
+
+export default [
+  // All 7 framework-agnostic rules
+  solodev.configs.recommended,
+
+  // OR: all 10 rules including Next.js server action rules
+  solodev.configs.nextjs,
+]
+```
+
+Or pick individual rules:
+
+```js
+import solodev from 'eslint-plugin-solodev'
+
+export default [
+  {
+    plugins: { solodev },
+    rules: {
+      'solodev/no-plain-error-throw': 'error',
+      'solodev/no-schema-parse': 'error',
+    }
+  }
+]
+```
+
+## Rules
+
+| Rule | Category | Description |
+|---|---|---|
+| [no-plain-error-throw](#no-plain-error-throw) | Error handling | Ban `throw new Error()` — force typed subclasses |
+| [no-silent-catch](#no-silent-catch) | Error handling | Ban empty catch + log-only catch blocks |
+| [no-schema-parse](#no-schema-parse) | Zod safety | Ban `schema.parse()` — force `safeParse()` |
+| [no-unsafe-type-assertions](#no-unsafe-type-assertions) | Type safety | Ban `as unknown as Type` double-casts |
+| [no-unvalidated-formdata](#no-unvalidated-formdata) | Type safety | Ban `formData.get('x') as string` |
+| [no-loose-status-type](#no-loose-status-type) | Type safety | Ban `status: string` — force union types |
+| [one-export-per-file](#one-export-per-file) | Code organization | One exported function per file |
+| [action-must-return](#action-must-return) | Server actions | Actions must return via response helpers |
+| [require-use-server](#require-use-server) | Server actions | `.action.ts` files must start with `"use server"` |
+| [prefer-server-actions](#prefer-server-actions) | Server actions | Flag `fetch('/api/...')` — use server actions |
+
+---
+
+### no-plain-error-throw
+
+A plain `Error` tells you nothing at 3am. Was it a network timeout you should retry? A validation failure you should surface? A bug you should page yourself for? Typed error subclasses encode this directly.
+
+```js
+// Bad
+throw new Error('Payment failed')
+reject(new Error('Timed out'))
+
+// Good
+throw new TransientError('Payment gateway timeout', { cause: error })
+throw new FatalError('Invalid card number')
+```
+
+### no-silent-catch
+
+Most linters catch empty `catch {}`. This rule also catches the more insidious pattern: logging the error and continuing as if nothing happened.
+
+```js
+// Bad
+catch (e) {}
+catch (e) { console.error(e) }
+promise.catch(() => {})
+promise.catch(e => console.log(e))
+
+// Good
+catch (e) { logger.error(e); throw e }
+catch (e) { return fallbackValue }
+```
+
+### no-schema-parse
+
+Zod's `.parse()` throws a `ZodError` on failure. In a server action, that's an uncontrolled exception with a useless stack trace. `safeParse()` returns a discriminated union you can handle gracefully.
+
+```js
+// Bad
+const data = userSchema.parse(input)
+z.array(schema).parse(items)
+
+// Good
+const result = userSchema.safeParse(input)
+if (!result.success) return failed(result.error)
+const data = result.data
+```
+
+Skips test files automatically.
+
+### no-unsafe-type-assertions
+
+`as unknown as Type` is TypeScript's escape hatch. It silently breaks every type guarantee. If you need to convert between types, validate with a schema or write a type guard.
+
+```js
+// Bad
+const user = data as unknown as User
+
+// Good
+const result = userSchema.safeParse(data)
+```
+
+### no-unvalidated-formdata
+
+`FormData.get()` returns `FormDataEntryValue | null`. Casting to `string` hides a null that will blow up at runtime.
+
+```js
+// Bad
+const email = formData.get('email') as string
+
+// Good
+const email = formData.get('email')
+if (!email || typeof email !== 'string') throw new Error('Missing email')
+```
+
+### no-loose-status-type
+
+`status: string` accepts any string. A typo like `"actve"` compiles fine and silently corrupts your data.
+
+```js
+// Bad
+type Order = { status: string }
+type Order = { status: string | null }
+
+// Good
+type Order = { status: 'pending' | 'paid' | 'shipped' }
+```
+
+### one-export-per-file
+
+When you're solo, discoverability IS your architecture. One function per file means the filename tells you everything.
+
+```js
+// Bad — two-exports.ts
+export function createUser() { ... }
+export function deleteUser() { ... }
+
+// Good — create-user.ts
+export function createUser() { ... }
+```
+
+**Options:**
+
+```js
+'solodev/one-export-per-file': ['error', { max: 2 }]
+```
+
+### action-must-return
+
+A server action that doesn't return a typed response is invisible to the client. Did it succeed? Fail? The caller will never know.
+
+```js
+// Bad — silent success
+export async function updateProfile(data: FormData) {
+  await db.update(data)
+}
+
+// Good
+export async function updateProfile(data: FormData) {
+  await db.update(data)
+  return actionSuccessResponse('Profile updated')
+}
+```
+
+**Options:**
+
+```js
+'solodev/action-must-return': ['error', {
+  returnFunctions: ['actionSuccessResponse', 'actionFailureResponse'],
+  filePattern: '.action.ts'
+}]
+```
+
+### require-use-server
+
+Without the `"use server"` directive, Next.js silently treats your action file as a regular module. It works in dev, breaks in prod.
+
+```js
+// Bad — missing directive
+export async function createUser() { ... }
+
+// Good
+"use server"
+export async function createUser() { ... }
+```
+
+**Options:**
+
+```js
+'solodev/require-use-server': ['error', { filePattern: '.server.ts' }]
+```
+
+### prefer-server-actions
+
+`fetch('/api/users')` gives you untyped JSON and string URL typos. Server actions give you end-to-end TypeScript safety.
+
+```js
+// Bad
+const res = await fetch('/api/users')
+const data = await res.json() // untyped
+
+// Good
+const result = await getUsers() // fully typed input + output
+```
+
+**Options:**
+
+```js
+'solodev/prefer-server-actions': ['error', {
+  internalPatterns: ['/api/', '/trpc/']
+}]
+```
+
+Skips external URLs and test files automatically.
+
+---
+
+## Companion rules
+
+These patterns are useful but don't need a custom plugin — use built-in ESLint config:
+
+### Prefer safe JSON parse
+
+```js
+// eslint.config.mjs
+{
+  rules: {
+    'no-restricted-syntax': ['error', {
+      selector: "CallExpression[callee.object.name='JSON'][callee.property.name='parse']:not([arguments.1])",
+      message: 'Use safeJsonParse() or pass a reviver to JSON.parse().'
+    }]
+  }
+}
+```
+
+### Prefer Promise.allSettled
+
+```js
+{
+  rules: {
+    'no-restricted-syntax': ['error', {
+      selector: "CallExpression[callee.object.name='Promise'][callee.property.name='all']",
+      message: 'Prefer Promise.allSettled() — Promise.all() rejects on first failure and loses other results.'
+    }]
+  }
+}
+```
+
+### No direct process.env
+
+Use the [`n/no-process-env`](https://github.com/eslint-community/eslint-plugin-n/blob/master/docs/rules/no-process-env.md) rule from `eslint-plugin-n`.
+
+### Consistent logging (no console)
+
+```js
+{
+  rules: {
+    'no-console': ['error', { allow: ['warn'] }]
+  }
+}
+```
+
+### Typographic quotes
+
+Use [`eslint-plugin-human`](https://www.npmjs.com/package/eslint-plugin-human) — auto-fixes straight quotes to curly in JSX.
+
+---
+
+## Philosophy
+
+These rules exist because solo developers don't get code review. Every pattern here caused a real production bug that would have been caught by a second pair of eyes:
+
+- A `throw new Error()` that should have been retried
+- A `catch (e) { console.log(e) }` that silently broke a payment flow
+- A `.parse()` that crashed a server action with an unreadable ZodError
+- An `as unknown as` that passed TypeScript but failed at runtime
+- A `status: string` that accepted a typo and corrupted 200 records
+
+If you work with a team, you probably don't need all of these. If you work alone, turn them all on and never look back.
+
+## License
+
+MIT

package/index.mjs

@@ -0,0 +1,57 @@
+import { rule as noPlainErrorThrow } from './rules/no-plain-error-throw.mjs'
+import { rule as noSilentCatch } from './rules/no-silent-catch.mjs'
+import { rule as noSchemaParse } from './rules/no-schema-parse.mjs'
+import { rule as noUnsafeTypeAssertions } from './rules/no-unsafe-type-assertions.mjs'
+import { rule as noUnvalidatedFormdata } from './rules/no-unvalidated-formdata.mjs'
+import { rule as noLooseStatusType } from './rules/no-loose-status-type.mjs'
+import { rule as oneExportPerFile } from './rules/one-export-per-file.mjs'
+import { rule as actionMustReturn } from './rules/action-must-return.mjs'
+import { rule as requireUseServer } from './rules/require-use-server.mjs'
+import { rule as preferServerActions } from './rules/prefer-server-actions.mjs'
+
+const plugin = {
+  rules: {
+    'no-plain-error-throw': noPlainErrorThrow,
+    'no-silent-catch': noSilentCatch,
+    'no-schema-parse': noSchemaParse,
+    'no-unsafe-type-assertions': noUnsafeTypeAssertions,
+    'no-unvalidated-formdata': noUnvalidatedFormdata,
+    'no-loose-status-type': noLooseStatusType,
+    'one-export-per-file': oneExportPerFile,
+    'action-must-return': actionMustReturn,
+    'require-use-server': requireUseServer,
+    'prefer-server-actions': preferServerActions,
+  }
+}
+
+plugin.configs = {
+  recommended: {
+    plugins: { solodev: plugin },
+    rules: {
+      'solodev/no-plain-error-throw': 'error',
+      'solodev/no-silent-catch': 'error',
+      'solodev/no-schema-parse': 'error',
+      'solodev/no-unsafe-type-assertions': 'error',
+      'solodev/no-unvalidated-formdata': 'error',
+      'solodev/no-loose-status-type': 'error',
+      'solodev/one-export-per-file': 'error',
+    }
+  },
+  nextjs: {
+    plugins: { solodev: plugin },
+    rules: {
+      'solodev/no-plain-error-throw': 'error',
+      'solodev/no-silent-catch': 'error',
+      'solodev/no-schema-parse': 'error',
+      'solodev/no-unsafe-type-assertions': 'error',
+      'solodev/no-unvalidated-formdata': 'error',
+      'solodev/no-loose-status-type': 'error',
+      'solodev/one-export-per-file': 'error',
+      'solodev/action-must-return': 'error',
+      'solodev/require-use-server': 'error',
+      'solodev/prefer-server-actions': 'error',
+    }
+  }
+}
+
+export default plugin

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "eslint-plugin-solodev",
+  "version": "1.0.0",
+  "description": "10 ESLint rules that replace code review for solo developers. Typed errors, safe Zod parsing, server action contracts, and more.",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./rules/*": "./rules/*.mjs"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "typescript",
+    "solo-dev",
+    "strict",
+    "zod",
+    "server-actions",
+    "nextjs",
+    "code-review"
+  ],
+  "author": "Julian Wagner",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JWPapi/eslint-plugin-solodev"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "files": [
+    "index.mjs",
+    "rules/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/rules/action-must-return.mjs

@@ -0,0 +1,106 @@
+/**
+ * ESLint rule: action-must-return
+ *
+ * Server actions must return via standard response helpers.
+ *
+ * A server action that doesn't return a typed response is invisible
+ * to the client. Did it succeed? Fail? You'll never know. This rule
+ * ensures every action returns through your response utilities.
+ *
+ * Options:
+ *   {
+ *     returnFunctions: ['actionSuccessResponse', 'actionFailureResponse'],
+ *     filePattern: '.action.ts'
+ *   }
+ *
+ * Good:
+ *   return actionSuccessResponse('Done', data)
+ *   return actionFailureResponse('Something broke')
+ *
+ * Bad:
+ *   await doSomething()  // function ends without return
+ *   return { success: true, data }  // custom response object
+ */
+export const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Server actions must return via standard response helpers',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#action-must-return'
+    },
+    messages: {
+      mustReturnResponse:
+        'Server action must return via a standard response helper. Silent success/failure is not allowed.',
+      useStandardResponse:
+        'Use a standard response helper instead of a custom response object.'
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          returnFunctions: {
+            type: 'array',
+            items: { type: 'string' }
+          },
+          filePattern: {
+            type: 'string'
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  create(context) {
+    const options = context.options[0] || {}
+    const returnFunctions = options.returnFunctions || ['actionSuccessResponse', 'actionFailureResponse']
+    const filePattern = options.filePattern || '.action.ts'
+
+    const filename = context.filename || context.getFilename()
+    if (!filename.endsWith(filePattern)) {
+      return {}
+    }
+
+    let hasStandardReturn = false
+    let hasAnyReturn = false
+    let currentFunction = null
+
+    function checkReturnStatement(node) {
+      if (!currentFunction) return
+
+      hasAnyReturn = true
+
+      if (!node.argument) return
+
+      const arg = node.argument
+
+      if (arg.type === 'CallExpression' && arg.callee.type === 'Identifier') {
+        if (returnFunctions.includes(arg.callee.name)) {
+          hasStandardReturn = true
+          return
+        }
+      }
+
+      if (arg.type === 'ObjectExpression') {
+        const hasSuccessProperty = arg.properties.some(
+          prop => prop.type === 'Property' && prop.key.type === 'Identifier' && prop.key.name === 'success'
+        )
+        if (hasSuccessProperty) {
+          context.report({ node, messageId: 'useStandardResponse' })
+        }
+      }
+    }
+
+    return {
+      'ExportNamedDeclaration > FunctionDeclaration[async=true]'(node) {
+        currentFunction = node
+        hasStandardReturn = false
+        hasAnyReturn = false
+      },
+      'ExportNamedDeclaration > FunctionDeclaration[async=true]:exit'() {
+        currentFunction = null
+      },
+
+      ReturnStatement: checkReturnStatement
+    }
+  }
+}

package/rules/no-loose-status-type.mjs

@@ -0,0 +1,73 @@
+/**
+ * ESLint rule: no-loose-status-type
+ *
+ * Ban `status: string` — force union types.
+ *
+ * A `status: string` accepts any string. A typo like "actve" compiles
+ * fine and silently corrupts your data. Union types or enums catch it
+ * at compile time.
+ *
+ * Good:
+ *   status: 'active' | 'paused' | 'error'
+ *   status: StatusEnum
+ *   status: z.enum(['active', 'paused'])
+ *
+ * Bad:
+ *   status: string
+ *   status: string | null
+ */
+export const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow loose `status: string` — use union types or enums',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#no-loose-status-type'
+    },
+    messages: {
+      useUnionType:
+        'Avoid "status: string". Use a specific union type or enum to catch invalid values at compile time.'
+    },
+    schema: []
+  },
+  create(context) {
+    function isLooseStringType(typeAnnotation) {
+      if (!typeAnnotation) return false
+
+      if (typeAnnotation.type === 'TSStringKeyword') return true
+
+      if (typeAnnotation.type === 'TSUnionType') {
+        return typeAnnotation.types.some(
+          t =>
+            t.type === 'TSStringKeyword' ||
+            (t.type === 'TSTypeReference' && t.typeName.type === 'Identifier' && t.typeName.name === 'string')
+        )
+      }
+
+      return false
+    }
+
+    return {
+      TSPropertySignature(node) {
+        if (
+          node.key.type === 'Identifier' &&
+          node.key.name === 'status' &&
+          node.typeAnnotation?.typeAnnotation &&
+          isLooseStringType(node.typeAnnotation.typeAnnotation)
+        ) {
+          context.report({ node, messageId: 'useUnionType' })
+        }
+      },
+
+      PropertyDefinition(node) {
+        if (
+          node.key.type === 'Identifier' &&
+          node.key.name === 'status' &&
+          node.typeAnnotation?.typeAnnotation &&
+          isLooseStringType(node.typeAnnotation.typeAnnotation)
+        ) {
+          context.report({ node, messageId: 'useUnionType' })
+        }
+      }
+    }
+  }
+}

package/rules/no-plain-error-throw.mjs

@@ -0,0 +1,65 @@
+/**
+ * ESLint rule: no-plain-error-throw
+ *
+ * Ban `throw new Error()` — force typed error subclasses.
+ *
+ * When you're the only reviewer, a plain Error tells you nothing.
+ * Typed subclasses (TransientError, FatalError, etc.) encode retry
+ * semantics, severity, and intent directly in the type system.
+ *
+ * Good:
+ *   throw new TransientError('Network failed', { cause: error })
+ *   throw new FatalError('Invalid config')
+ *   reject(new TransientError('Timed out'))
+ *
+ * Bad:
+ *   throw new Error('Something failed')
+ *   reject(new Error('Timed out'))
+ */
+export const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow plain Error — use typed error subclasses for proper classification',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#no-plain-error-throw'
+    },
+    messages: {
+      useTypedError:
+        'Use a typed error subclass instead of plain Error. Typed errors enable retry logic, severity classification, and better debugging.',
+      useTypedErrorInReject:
+        'Use a typed error subclass instead of plain Error in reject(). Typed errors enable retry logic, severity classification, and better debugging.'
+    },
+    schema: []
+  },
+  create(context) {
+    function isPlainNewError(node) {
+      return (
+        node && node.type === 'NewExpression' && node.callee.type === 'Identifier' && node.callee.name === 'Error'
+      )
+    }
+
+    return {
+      ThrowStatement(node) {
+        if (isPlainNewError(node.argument)) {
+          context.report({
+            node,
+            messageId: 'useTypedError'
+          })
+        }
+      },
+      CallExpression(node) {
+        if (
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'reject' &&
+          node.arguments.length > 0 &&
+          isPlainNewError(node.arguments[0])
+        ) {
+          context.report({
+            node,
+            messageId: 'useTypedErrorInReject'
+          })
+        }
+      }
+    }
+  }
+}

package/rules/no-schema-parse.mjs

@@ -0,0 +1,91 @@
+/**
+ * ESLint rule: no-schema-parse
+ *
+ * Ban schema.parse() — force safeParse().
+ *
+ * Zod's .parse() throws a ZodError on failure. In a server action or
+ * API route, that crashes the process with an unhelpful stack trace.
+ * safeParse() returns a discriminated union you can handle gracefully.
+ *
+ * Good:
+ *   const result = schema.safeParse(input)
+ *   if (!result.success) return failed(result.error)
+ *
+ * Bad:
+ *   schema.parse(input)
+ *   z.array(schema).parse(data)
+ *   schema.partial().parse(data)
+ *
+ * Skips test files automatically (*.test.*, *.spec.*).
+ */
+export const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow schema.parse() — use safeParse() for controlled validation',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#no-schema-parse'
+    },
+    messages: {
+      noSchemaParse:
+        'Avoid schema.parse() — it throws uncontrolled ZodErrors. Use safeParse() and handle the result.',
+      noPartialParse: 'Avoid schema.partial().parse(). Use safeParse() instead.',
+      noArrayParse: 'Avoid z.array(schema).parse(). Use safeParse() instead.'
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    if (filename.includes('.test.') || filename.includes('.spec.')) {
+      return {}
+    }
+
+    function isSchemaLikeName(name) {
+      const lowerName = name.toLowerCase()
+      return lowerName === 'schema' || lowerName.endsWith('schema')
+    }
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.property.type !== 'Identifier' ||
+          node.callee.property.name !== 'parse'
+        ) {
+          return
+        }
+
+        const object = node.callee.object
+
+        // schema.partial().parse()
+        if (
+          object.type === 'CallExpression' &&
+          object.callee.type === 'MemberExpression' &&
+          object.callee.property.type === 'Identifier' &&
+          object.callee.property.name === 'partial'
+        ) {
+          context.report({ node, messageId: 'noPartialParse' })
+          return
+        }
+
+        // z.array(schema).parse()
+        if (
+          object.type === 'CallExpression' &&
+          object.callee.type === 'MemberExpression' &&
+          object.callee.object.type === 'Identifier' &&
+          object.callee.object.name === 'z' &&
+          object.callee.property.type === 'Identifier' &&
+          object.callee.property.name === 'array'
+        ) {
+          context.report({ node, messageId: 'noArrayParse' })
+          return
+        }
+
+        // schema.parse() where name matches
+        if (object.type === 'Identifier' && isSchemaLikeName(object.name)) {
+          context.report({ node, messageId: 'noSchemaParse' })
+        }
+      }
+    }
+  }
+}

package/rules/no-silent-catch.mjs

@@ -0,0 +1,111 @@
+/**
+ * ESLint rule: no-silent-catch
+ *
+ * Ban catch blocks that swallow errors silently:
+ * - Empty catch blocks: catch {}
+ * - Catch blocks that only log: catch (e) { console.log(e) }
+ * - .catch(() => {}) callbacks
+ * - .catch(e => console.log(e)) callbacks
+ *
+ * The novel bit: detecting log-only catch blocks. Most linters catch
+ * empty catches, but a console.error() with no rethrow is equally
+ * dangerous — the app continues in a broken state.
+ *
+ * Good:
+ *   catch (e) { logger.error(e); throw e }
+ *   catch (e) { return fallbackValue }
+ *
+ * Bad:
+ *   catch {}
+ *   catch (e) { console.error(e) }
+ *   .catch(() => {})
+ */
+export const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow catch blocks that silently swallow errors',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#no-silent-catch'
+    },
+    messages: {
+      emptyCatch: 'Empty catch block swallows errors silently. Either rethrow or handle the error properly.',
+      logOnlyCatch:
+        'Catch block only logs the error and continues execution. Either rethrow after logging or handle the error properly.',
+      emptyCatchCallback: '.catch(() => {}) swallows errors silently. Either rethrow or handle the error properly.',
+      logOnlyCatchCallback:
+        '.catch() only logs the error and continues execution. Either rethrow after logging or handle the error properly.'
+    },
+    schema: []
+  },
+  create(context) {
+    function isLogOnlyBlock(body) {
+      if (!body || body.length === 0) return false
+
+      return body.every(statement => {
+        if (statement.type === 'ExpressionStatement') {
+          const expr = statement.expression
+          if (
+            expr.type === 'CallExpression' &&
+            expr.callee.type === 'MemberExpression' &&
+            expr.callee.object.type === 'Identifier' &&
+            expr.callee.object.name === 'console'
+          ) {
+            return true
+          }
+        }
+        return false
+      })
+    }
+
+    function isEmptyOrLogOnlyArrow(node) {
+      if (node.body.type === 'BlockStatement') {
+        if (node.body.body.length === 0) return 'empty'
+        if (isLogOnlyBlock(node.body.body)) return 'logOnly'
+      }
+      if (
+        node.body.type === 'CallExpression' &&
+        node.body.callee.type === 'MemberExpression' &&
+        node.body.callee.object.type === 'Identifier' &&
+        node.body.callee.object.name === 'console'
+      ) {
+        return 'logOnly'
+      }
+      return false
+    }
+
+    return {
+      CatchClause(node) {
+        const body = node.body.body
+
+        if (body.length === 0) {
+          context.report({ node, messageId: 'emptyCatch' })
+          return
+        }
+
+        if (isLogOnlyBlock(body)) {
+          context.report({ node, messageId: 'logOnlyCatch' })
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'catch' &&
+          node.arguments.length > 0
+        ) {
+          const callback = node.arguments[0]
+
+          if (callback.type === 'ArrowFunctionExpression' || callback.type === 'FunctionExpression') {
+            const result = isEmptyOrLogOnlyArrow(callback)
+            if (result === 'empty') {
+              context.report({ node, messageId: 'emptyCatchCallback' })
+            } else if (result === 'logOnly') {
+              context.report({ node, messageId: 'logOnlyCatchCallback' })
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/rules/no-unsafe-type-assertions.mjs

@@ -0,0 +1,50 @@
+/**
+ * ESLint rule: no-unsafe-type-assertions
+ *
+ * Ban `as unknown as Type` double-casts.
+ *
+ * Double-casting is a type-system escape hatch that silently breaks
+ * every guarantee TypeScript gives you. If you need to convert between
+ * types, validate with Zod or write a proper type guard.
+ *
+ * Good:
+ *   const parsed = schema.safeParse(data)
+ *   if (isUser(data)) { ... }
+ *
+ * Bad:
+ *   data as unknown as User
+ */
+export const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow unsafe `as unknown as Type` double-cast assertions',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#no-unsafe-type-assertions'
+    },
+    messages: {
+      asUnknownAs: 'Avoid "as unknown as Type". Use schema validation or a type guard instead.'
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      TSAsExpression(node) {
+        if (
+          node.typeAnnotation.type === 'TSUnknownKeyword' ||
+          (node.typeAnnotation.type === 'TSTypeReference' &&
+            node.typeAnnotation.typeName.type === 'Identifier' &&
+            node.typeAnnotation.typeName.name === 'unknown')
+        ) {
+          const ancestors = context.sourceCode.getAncestors(node)
+          const parent = ancestors[ancestors.length - 1]
+          if (parent && parent.type === 'TSAsExpression') {
+            context.report({
+              node: parent,
+              messageId: 'asUnknownAs'
+            })
+          }
+        }
+      }
+    }
+  }
+}

package/rules/no-unvalidated-formdata.mjs

@@ -0,0 +1,63 @@
+/**
+ * ESLint rule: no-unvalidated-formdata
+ *
+ * Ban `formData.get('x') as string` without null checks.
+ *
+ * FormData.get() returns FormDataEntryValue | null. Casting directly
+ * to string hides a potential null that will blow up at runtime.
+ *
+ * Good:
+ *   const email = formData.get('email')
+ *   if (!email || typeof email !== 'string') throw new Error('Missing')
+ *
+ * Bad:
+ *   const email = formData.get('email') as string
+ */
+export const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow casting formData.get() directly to string without validation',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#no-unvalidated-formdata'
+    },
+    messages: {
+      validateFormData:
+        'Avoid "formData.get(...) as string". FormData.get() can return null. Validate the value before using it.'
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      TSAsExpression(node) {
+        const expression = node.expression
+
+        if (expression.type !== 'CallExpression') return
+        if (expression.callee.type !== 'MemberExpression') return
+
+        const callee = expression.callee
+
+        if (callee.property.type !== 'Identifier' || callee.property.name !== 'get') return
+
+        const objectName = callee.object.type === 'Identifier' ? callee.object.name : null
+        if (!objectName) return
+
+        const formDataNames = ['formData', 'form', 'data', 'fd']
+        const isLikelyFormData =
+          formDataNames.some(name => objectName.toLowerCase().includes(name.toLowerCase())) ||
+          objectName === 'formData'
+
+        if (!isLikelyFormData) return
+
+        const typeAnnotation = node.typeAnnotation
+        if (
+          typeAnnotation.type === 'TSStringKeyword' ||
+          (typeAnnotation.type === 'TSTypeReference' &&
+            typeAnnotation.typeName.type === 'Identifier' &&
+            typeAnnotation.typeName.name === 'string')
+        ) {
+          context.report({ node, messageId: 'validateFormData' })
+        }
+      }
+    }
+  }
+}

package/rules/one-export-per-file.mjs

@@ -0,0 +1,117 @@
+/**
+ * ESLint rule: one-export-per-file
+ *
+ * Enforce one exported function per file.
+ *
+ * When you're solo, discoverability IS your architecture. If a file
+ * exports 5 functions, you'll forget 3 of them exist. One function
+ * per file means the filename tells you everything.
+ *
+ * Counts as exported function:
+ *   export function foo() {}
+ *   export default function() {}
+ *   export const foo = () => {}
+ *
+ * Does NOT count:
+ *   Type/interface exports, non-function const exports, re-exports
+ *
+ * Options:
+ *   { max: 1 }  — configurable max (default: 1)
+ *
+ * Exempt file patterns via ESLint config overrides:
+ *   index.ts, *.schema.ts, *.types.ts, *.constants.ts
+ */
+export const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Enforce one exported function per file for discoverability',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#one-export-per-file'
+    },
+    messages: {
+      tooManyExports:
+        'File exports {{count}} functions ({{names}}). Split into one function per file for better discoverability.'
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          max: {
+            type: 'integer',
+            minimum: 1
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  create(context) {
+    const max = (context.options[0] && context.options[0].max) || 1
+    const exportedFunctions = []
+
+    function isFunctionInit(init) {
+      if (!init) return false
+      if (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') return true
+      return false
+    }
+
+    return {
+      ExportNamedDeclaration(node) {
+        if (!node.declaration) return
+
+        if (node.declaration.type === 'FunctionDeclaration' || node.declaration.type === 'TSDeclareFunction') {
+          exportedFunctions.push({
+            node: node.declaration,
+            name: node.declaration.id ? node.declaration.id.name : '<anonymous>'
+          })
+        }
+
+        if (node.declaration.type === 'VariableDeclaration') {
+          for (const declarator of node.declaration.declarations) {
+            if (isFunctionInit(declarator.init)) {
+              exportedFunctions.push({
+                node: declarator,
+                name: declarator.id ? declarator.id.name : '<anonymous>'
+              })
+            }
+          }
+        }
+      },
+
+      ExportDefaultDeclaration(node) {
+        const decl = node.declaration
+        if (
+          decl.type === 'FunctionDeclaration' ||
+          decl.type === 'ArrowFunctionExpression' ||
+          decl.type === 'FunctionExpression'
+        ) {
+          exportedFunctions.push({
+            node: decl,
+            name: decl.id ? decl.id.name : 'default'
+          })
+        }
+      },
+
+      'Program:exit'() {
+        const seen = new Set()
+        const unique = exportedFunctions.filter(f => {
+          if (seen.has(f.name)) return false
+          seen.add(f.name)
+          return true
+        })
+
+        if (unique.length > max) {
+          const names = unique.map(f => f.name).join(', ')
+          context.report({
+            node: unique[0].node,
+            messageId: 'tooManyExports',
+            data: {
+              count: String(unique.length),
+              names
+            }
+          })
+        }
+      }
+    }
+  }
+}

package/rules/prefer-server-actions.mjs

@@ -0,0 +1,84 @@
+/**
+ * ESLint rule: prefer-server-actions
+ *
+ * Flag fetch() calls to internal API routes.
+ *
+ * Server actions give you end-to-end type safety — TypeScript checks
+ * both input and output. fetch('/api/...') gives you untyped JSON
+ * and string URL typos.
+ *
+ * Options:
+ *   { internalPatterns: ['/api/', '/app/'] }
+ *
+ * Detected:
+ *   fetch('/api/users')
+ *   fetch(`/api/users/${id}`)
+ *
+ * Not flagged:
+ *   fetch('https://external.com/api')
+ *   Test files (*.test.*, *.spec.*)
+ */
+export const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Prefer server actions over fetch() to internal API routes',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#prefer-server-actions'
+    },
+    messages: {
+      preferAction:
+        "Prefer a server action over fetch('{{url}}'). Server actions provide end-to-end type safety."
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          internalPatterns: {
+            type: 'array',
+            items: { type: 'string' }
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    if (filename.includes('.test.') || filename.includes('.spec.')) {
+      return {}
+    }
+
+    const options = context.options[0] || {}
+    const internalPatterns = options.internalPatterns || ['/api/', '/app/']
+
+    function extractUrl(node) {
+      if (node.type === 'Literal' && typeof node.value === 'string') return node.value
+      if (node.type === 'TemplateLiteral' && node.quasis.length > 0) return node.quasis[0].value.raw
+      return null
+    }
+
+    function isInternalApiRoute(url) {
+      if (!url) return false
+      if (url.startsWith('http://') || url.startsWith('https://')) return false
+      return internalPatterns.some(pattern => url.includes(pattern))
+    }
+
+    return {
+      CallExpression(node) {
+        if (node.callee.type === 'Identifier' && node.callee.name === 'fetch' && node.arguments.length > 0) {
+          const url = extractUrl(node.arguments[0])
+
+          if (isInternalApiRoute(url)) {
+            const displayUrl = url.length > 50 ? url.substring(0, 50) + '...' : url
+            context.report({
+              node,
+              messageId: 'preferAction',
+              data: { url: displayUrl }
+            })
+          }
+        }
+      }
+    }
+  }
+}

package/rules/require-use-server.mjs

@@ -0,0 +1,57 @@
+/**
+ * ESLint rule: require-use-server
+ *
+ * Server action files must start with "use server".
+ *
+ * Without the directive, Next.js silently treats your action as a
+ * regular function. It works in dev, breaks in prod. This rule
+ * catches it before deploy.
+ *
+ * Options:
+ *   { filePattern: '.action.ts' }
+ *
+ * Some projects use .server.ts — configure via options.
+ */
+export const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require "use server" directive in server action files',
+      url: 'https://github.com/JWPapi/eslint-plugin-solodev#require-use-server'
+    },
+    messages: {
+      missingUseServer: 'Server action files must start with "use server".'
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          filePattern: {
+            type: 'string'
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  create(context) {
+    const options = context.options[0] || {}
+    const filePattern = options.filePattern || '.action.ts'
+
+    const filename = context.filename || context.getFilename()
+    if (!filename.endsWith(filePattern)) {
+      return {}
+    }
+
+    return {
+      Program(node) {
+        const sourceCode = context.sourceCode || context.getSourceCode()
+        const text = sourceCode.getText()
+
+        if (!text.startsWith('"use server"') && !text.startsWith("'use server'")) {
+          context.report({ node, messageId: 'missingUseServer' })
+        }
+      }
+    }
+  }
+}