@asd14/eslint-plugin 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Dumitrescu
+
+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,109 @@
+[![npm version](https://badge.fury.io/js/%40asd14%2Feslint-plugin.svg)](https://badge.fury.io/js/%40asd14%2Feslint-plugin)
+![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+
+# @asd14/eslint-plugin
+
+> ESLint rules for opinionated DX not covered by existing plugins.
+
+<!-- vim-markdown-toc GFM -->
+
+- [Install](#install)
+- [Rules](#rules)
+  - [`@asd14/error-message-format`](#asd14error-message-format)
+- [Develop](#develop)
+
+<!-- vim-markdown-toc -->
+
+## Install
+
+```bash
+npm install @asd14/eslint-plugin --save-dev
+```
+
+> NOTE: requires peerDependency `eslint^9` or `eslint^10`
+
+## Rules
+
+### `@asd14/error-message-format`
+
+Enforce consistent error message format in `throw` statements.
+
+- Per error class: `Error`, `TypeError` or custom `DBError`
+- Each is an array of `RegExp` patterns
+- `OR` matching, first match wins
+
+```js
+// eslint.config.js
+import asd14Plugin from "@asd14/eslint-plugin"
+
+export default [
+  {
+    plugins: { "@asd14": asd14Plugin },
+    rules: {
+      "@asd14/error-message-format": [
+        "error",
+        {
+          TypeError: [
+            {
+              pattern:
+                "^@asd14/m/\\w+: expected '\\w+' to be '\\w+' or '\\w+', got '\\w+'",
+              message:
+                "Format: @asd14/m/<fn>: expected '<param>' to be '<Type>' or '<Type>', got '<Actual>'"
+            },
+            {
+              pattern:
+                "^@asd14/m/\\w+: expected '\\w+' to be '\\w+', got '\\w+'",
+              message:
+                "Format: @asd14/m/<fn>: expected '<param>' to be '<Type>', got '<Actual>'"
+            }
+          ]
+        }
+      ]
+    }
+  }
+]
+```
+
+Examples of **correct** code:
+
+```js
+// Template literal with interpolation
+throw new TypeError(
+  `@asd14/m/sort: expected 'input' to be 'Array', got '${type(input)}'`
+)
+
+// String concatenation
+throw new TypeError(
+  "@asd14/m/sort: expected 'input' to be 'Array', got '" + type(input) + "'"
+)
+
+// "or" variant - multiple expected types
+throw new TypeError(
+  `@asd14/m/all: expected 'fn' to be 'Function' or 'Array', got '${type(fn)}'`
+)
+
+// Unconfigured error classes are ignored
+throw new Error("something went wrong")
+```
+
+Examples of **incorrect** code:
+
+```js
+// Missing @asd14/m/ prefix
+throw new TypeError("expected 'input' to be 'Array', got '" + type(x) + "'")
+
+// Unquoted types
+throw new TypeError(`@asd14/m/sort: expected Array, got ${type(input)}`)
+
+// Can't statically evaluate
+throw new TypeError(message)
+```
+
+## Develop
+
+```bash
+npm run lint        # eslint
+npm run typecheck   # tsc --noEmit
+npm run test        # node:test runner
+npm run coverage    # c8 --100
+```

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { errorMessageFormat } from "./rules/error-message-format/error-message-format.js";
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        "error-message-format": import("eslint").Rule.RuleModule;
+    };
+};
+export default plugin;
+export { errorMessageFormat };

package/dist/index.js

@@ -0,0 +1,15 @@
+import packageJSON from "../package.json" with {
+    type: "json"
+};
+import { errorMessageFormat } from "./rules/error-message-format/error-message-format.js";
+const plugin = {
+    meta: {
+        name: packageJSON.name,
+        version: packageJSON.version
+    },
+    rules: {
+        "error-message-format": errorMessageFormat
+    }
+};
+export default plugin;
+export { errorMessageFormat };

package/dist/rules/error-message-format/error-message-format.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const errorMessageFormat: Rule.RuleModule;
+export { errorMessageFormat };

package/dist/rules/error-message-format/error-message-format.js

@@ -0,0 +1,92 @@
+import { flattenExpression } from "./utils/flatten-expression.js";
+const errorMessageFormat = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Enforce consistent error message format in throw statements"
+        },
+        messages: {
+            formatViolation: "{{message}}",
+            cannotEvaluate: "Cannot statically evaluate error message. Use a string literal or template literal"
+        },
+        schema: [
+            {
+                type: "object",
+                additionalProperties: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            pattern: {
+                                type: "string"
+                            },
+                            message: {
+                                type: "string"
+                            }
+                        },
+                        required: [
+                            "pattern",
+                            "message"
+                        ],
+                        additionalProperties: false
+                    }
+                }
+            }
+        ]
+    },
+    create (context) {
+        const ruleOptions = context.options[0] ?? {};
+        const errorClasses = Object.keys(ruleOptions);
+        if (errorClasses.length === 0) {
+            return {};
+        }
+        return {
+            ThrowStatement (node) {
+                // Only matching `throw new Error(...)`
+                const argument = node.argument;
+                if (argument.type !== "NewExpression") {
+                    return;
+                }
+                const callee = argument.callee;
+                if (callee.type !== "Identifier") {
+                    return;
+                }
+                const checks = ruleOptions[callee.name];
+                if (!checks || checks.length === 0) {
+                    return;
+                }
+                const firstArgument = argument.arguments[0];
+                if (!firstArgument) {
+                    return;
+                }
+                // Turn AST -> string representation which we can match against the
+                // user's RegExps
+                const fullMessage = flattenExpression(firstArgument);
+                // Can't validate entirely opaque variable, function call, etc.
+                if (fullMessage === "EXPR") {
+                    context.report({
+                        node: firstArgument,
+                        messageId: "cannotEvaluate"
+                    });
+                    return;
+                }
+                // If ANY pattern matches, the message is valid.
+                // Report the first check's message if none match.
+                for (const check of checks){
+                    const re = new RegExp(check.pattern);
+                    if (re.test(fullMessage)) {
+                        return;
+                    }
+                }
+                context.report({
+                    node: firstArgument,
+                    messageId: "formatViolation",
+                    data: {
+                        message: checks[0]?.message
+                    }
+                });
+            }
+        };
+    }
+};
+export { errorMessageFormat };

package/dist/rules/error-message-format/utils/flatten-expression.d.ts

@@ -0,0 +1,8 @@
+import type { Expression } from "acorn";
+/**
+ * Flatten an AST expression node into a plain string, replacing all
+ * non-literal parts (interpolations, function calls, identifiers) with
+ * the placeholder "EXPR".
+ */
+declare const flattenExpression: (node: Expression) => string;
+export { flattenExpression };

package/dist/rules/error-message-format/utils/flatten-expression.js

@@ -0,0 +1,34 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion -- loop bounds guarantee valid indices */ /**
+ * Flatten an AST expression node into a plain string, replacing all
+ * non-literal parts (interpolations, function calls, identifiers) with
+ * the placeholder "EXPR".
+ */ const flattenExpression = (node)=>{
+    // String literals: "hello" → "hello"
+    if (node.type === "Literal" && typeof node.value === "string") {
+        return node.value;
+    }
+    // Template literals: `got '${type(x)}'` → `got 'EXPR'`
+    if (node.type === "TemplateLiteral") {
+        let result = "";
+        for(let i = 0; i < node.quasis.length; i++){
+            result += node.quasis[i].value.raw;
+            if (i < node.quasis.length - 1) {
+                result += "EXPR";
+            }
+        }
+        return result;
+    }
+    // Binary `+` chains: `"a" + expr + "b"` → "aEXPRb"
+    if (node.type === "BinaryExpression" && node.operator === "+") {
+        // Acorn types `left` as `Expression | PrivateIdentifier` because
+        // BinaryExpression covers `a in #field` (the `in` operator can have
+        // a PrivateIdentifier on the right). For `+` this can never happen.
+        const left = flattenExpression(node.left);
+        const right = flattenExpression(node.right);
+        return left + right;
+    }
+    // Any unrecognized node (call expressions, identifiers, etc.)
+    // is treated as an opaque interpolation.
+    return "EXPR";
+};
+export { flattenExpression };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@asd14/eslint-plugin",
+  "version": "0.1.0",
+  "description": "ESLint rules for opinionated DX not covered by existing plugins",
+  "license": "MIT",
+  "author": {
+    "name": "Andrei Dumitrescu",
+    "url": "https://github.com/andreidmt"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "/dist"
+  ],
+  "nx": {
+    "projectType": "library",
+    "tags": [
+      "type:library",
+      "target:node"
+    ]
+  },
+  "scripts": {
+    "----BUNDLE": "",
+    "build:code": "swc src -d dist --ignore '**/*.test.ts' --strip-leading-paths",
+    "build:types": "tsc --declaration --emitDeclarationOnly --project ./.tsconfig/code.json",
+    "prebuild": "rm -rf dist/* node_modules/.tmp/*.tsbuildinfo",
+    "build": "npm run build:code && npm run build:types",
+    "----LINT": "",
+    "lint": "eslint --quiet .",
+    "typecheck:code": "tsc --noEmit --project ./.tsconfig/code.json",
+    "typecheck:config": "tsc --noEmit --project ./.tsconfig/config.json",
+    "typecheck:tests": "tsc --noEmit --project ./.tsconfig/tests.json",
+    "typecheck": "npm run typecheck:code && npm run typecheck:config && npm run typecheck:tests",
+    "----TEST": "",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "coverage": "c8 --100 --exclude='src/**/*.test.ts' node --import tsx --test 'src/**/*.test.ts'",
+    "----PUBLISH": "",
+    "release": "semantic-release"
+  },
+  "dependencies": {
+    "acorn": "^8.16.0"
+  },
+  "devDependencies": {
+    "@asd14/eslint-config": "^15.2.0",
+    "@asd14/prettier-config": "^1.2.0",
+    "@asd14/ts-config": "^1.3.0",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@semantic-release/git": "^10.0.1",
+    "@swc/cli": "^0.5.0",
+    "@swc/core": "^1.15.18",
+    "c8": "^11.0.0",
+    "conventional-changelog-conventionalcommits": "^9.3.0",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "semantic-release": "^24.2.9",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "eslint": "^9 || ^10"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}