First version

.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - 22
+          - 20
+          - 18
+        os:
+          - ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npx ava

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+node_modules

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.formatOnSave": true
+}

README.md

@@ -1,2 +1,3 @@
 # eslint-plugin-throw
+
 ESLint plugin to enforce function naming and JSDoc annotations for functions that throw

eslint.config.js

@@ -0,0 +1,18 @@
+import eslintPlugin from "eslint-plugin-eslint-plugin";
+import nodePlugin from "eslint-plugin-n";
+
+/** @type import("eslint").Linter.Config[] */
+export default [
+  eslintPlugin.configs["flat/recommended"],
+  nodePlugin.configs["flat/recommended-script"],
+  {
+    parserOptions: {
+      ecmaVersion: 2021,
+      sourceType: "module",
+    },
+    rules: {
+      "eslint-plugin/require-meta-docs-description": "error",
+      "n/exports-style": ["error", "module.exports"],
+    },
+  },
+];

lib/index.mjs

@@ -0,0 +1,49 @@
+import fs from "fs";
+
+const pkg = JSON.parse(
+  fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")
+);
+
+/**
+ * @type {import("eslint").ESLint.Plugin}
+ */
+const plugin = {
+  meta: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  configs: {},
+  rules: {
+    "throw-documentation": {
+      create(context) {
+        // rule implementation ...
+      },
+    },
+  },
+  processors: {},
+};
+
+Object.assign(plugin.configs, {
+  recommended: [
+    {
+      plugins: {
+        "eslint-plugin-throw": plugin,
+      },
+      rules: {
+        "eslint-plugin-throw/throw-documentation": "error",
+      },
+      languageOptions: {
+        globals: {
+          myGlobal: "readonly",
+        },
+        parserOptions: {
+          ecmaFeatures: {
+            jsx: true,
+          },
+        },
+      },
+    },
+  ],
+});
+
+export default plugin;

lib/rules/throw-documentation.mjs

@@ -0,0 +1,52 @@
+/**
+ * @type {import("eslint").Rule.RuleModule}
+ */
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Enforce JSDoc @throws tag for functions that throw exceptions",
+      category: "Best Practices",
+      recommended: "error",
+    },
+    messages: {
+      missingThrows:
+        "Function throws an exception but lacks a @throws tag in JSDoc.",
+    },
+    schema: [], // no options
+  },
+  create(context) {
+    return {
+      FunctionDeclaration(node) {
+        const sourceCode = context.sourceCode;
+        const jsDocComment = sourceCode.getJSDocComment(node);
+
+        // if (!jsDocComment) return; // If there's no JSDoc, skip
+
+        const hasThrow = node.body.body.some(
+          (statement) => statement.type === "ThrowStatement"
+        );
+
+        if (hasThrow) {
+          // Missing JSDoc @throws
+          if (!jsDocComment) {
+            context.report({
+              node: node,
+              messageId: "missingThrows",
+            });
+            return;
+          }
+
+          const throwsTag = jsDocComment.value.includes("@throws");
+          if (!throwsTag) {
+            context.report({
+              node: node,
+              messageId: "missingThrows",
+            });
+          }
+        }
+      },
+    };
+  },
+};

lib/tests/throw-documentation.test.mjs

@@ -0,0 +1,32 @@
+import test from "ava";
+import AvaRuleTester from "eslint-ava-rule-tester";
+import rule from "../rules/throw-documentation.mjs";
+
+const ruleTester = new AvaRuleTester(test, {
+  languageOptions: { ecmaVersion: 2021, sourceType: "module" },
+});
+
+ruleTester.run("throw-documentation", rule, {
+  valid: [
+    {
+      code: `
+      /**
+       * @throws {Error}
+       */
+      function test() {
+        throw new Error('test');
+      }
+      `,
+    },
+  ],
+  invalid: [
+    {
+      code: `
+      function test() {
+        throw new Error('test');
+      }
+      `,
+      errors: [{ messageId: "missingThrows" }],
+    },
+  ],
+});