eslint-plugin-crisp 1.4.7 → 1.4.9

package/README.md

@@ -146,12 +146,18 @@ Each item has emojis denoting:
 | Name | Description | 🟠 | 🟢 | 🟣 |
 | :- | :- | :- | :- | :- |
 | [jsdoc/no-undefined-types](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md) | Rule is **disabled** to allow some undefined types | 🟠 |
+| [jsdoc/no-types](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-types.md) | Disallows types in JSDoc tags, relying on the TypeScript signature instead |  |  | 🟣 |
 | [jsdoc/require-description](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description.md) | Requires all functions to have a description in their JSDoc |  | 🟢 | 🟣 |
 | [jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md) | Rule is **disabled** as TS functions are self documented |  |  | 🟣 |
+| [jsdoc/require-param-type](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-type.md) | Rule is **disabled** as types come from the TypeScript signature |  |  | 🟣 |
 | [jsdoc/require-param-description](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-description.md) | Rule is **disabled** as we don't write any description for `@param` tags | 🟠 | 🟢 | 🟣 |
-| [jsdoc/require-property-description](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-description.md) | Rule is **disabled** as we don't write any description for `@property` tags | 🟠 | 🟢 | 🟣 |
-| [jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md) | Rule is **disabled** as TS functions are self documented |  |  | 🟣 |
-| [jsdoc/require-param](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md) | Rule is **disabled** as TS functions are self documented |  |  | 🟣 |
+| [jsdoc/check-param-names](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-param-names.md) | Rule is **disabled** as TS functions are self documented |  |  | 🟣 |
+| [jsdoc/require-property-description](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-description.md) | Rule is **disabled** as we don't write any description for `@property` tags | 🟠 | 🟢 | 🟣 |
+| [jsdoc/require-returns](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md) | Rule is **disabled** as TS functions are self documented |  |  | 🟣 |
+| [jsdoc/require-returns-type](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md) | Rule is **disabled** as types come from the TypeScript signature |  |  | 🟣 |
+| [jsdoc/require-returns-check](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md) | Rule is **disabled** as we don't write `@returns` tags |  |  | 🟣 |
+| [jsdoc/require-yields](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md) | Rule is **disabled** as TS functions are self documented |  |  | 🟣 |
+| [jsdoc/require-yields-check](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-check.md) | Rule is **disabled** as we don't write `@yields` tags |  |  | 🟣 |
 | [jsdoc/require-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-jsdoc.md) | Enforces JSDoc comments on functions and classes | 🟠 | 🟢 | 🟣 |
 | [jsdoc/sort-tags](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/sort-tags.md) | Enforces specific order for tags | 🟠 | 🟢 | 🟣 |
 
@@ -165,6 +171,8 @@ Each item has emojis denoting:
 | [crisp/jsdoc-enforce-access](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-enforce-access.js) | Requires one of `@public`, `@private`, or `@protected` for functions |  | 🟢 |
 | [crisp/jsdoc-enforce-classdesc](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-enforce-classdesc.js) | Ensures JSDoc for class headers to include a non-empty `@classdesc` | 🟠 | 🟢 |
 | [crisp/jsdoc-require-description-uppercase](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-require-description-uppercase.js) | Requires descriptions to start with an uppercase character | 🟠 | 🟢 |
+| [crisp/jsdoc-description-length](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-description-length.js) | Enforces a maximum length for JSDoc descriptions | 🟠 | 🟢 | 🟣 |
+| [crisp/jsdoc-no-param-return](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-no-param-return.js) | Forbids `@param` and `@return` tags in JSDoc, relying on the TypeScript signature instead |  |  | 🟣 |
 
 #### General Vue rules
 

package/index.js

@@ -18,7 +18,9 @@ import ruleJsdocCheckIndentation from "./rules/jsdoc-check-indentation.js";
 import ruleJsdocCheckOptionalParams from "./rules/jsdoc-check-optional-params.js";
 import ruleJsdocEnforceAccess from "./rules/jsdoc-enforce-access.js";
 import ruleJsdocEnforceClassdesc from "./rules/jsdoc-enforce-classdesc.js";
+import ruleJsdocNoParamReturn from "./rules/jsdoc-no-param-return.js";
 import ruleJsdocRequireDescriptionUppercase from "./rules/jsdoc-require-description-uppercase.js";
+import ruleJsdocDescriptionLength from "./rules/jsdoc-description-length.js";
 import ruleMethodsNaming from "./rules/methods-naming.js";
 import ruleMethodsOrdering from "./rules/methods-ordering.js";
 import ruleMultilineCommentEndBackslash from "./rules/multiline-comment-end-backslash.js";
@@ -80,7 +82,9 @@ const plugin = {
     "jsdoc-check-optional-params": ruleJsdocCheckOptionalParams,
     "jsdoc-enforce-access": ruleJsdocEnforceAccess,
     "jsdoc-enforce-classdesc": ruleJsdocEnforceClassdesc,
+    "jsdoc-no-param-return": ruleJsdocNoParamReturn,
     "jsdoc-require-description-uppercase": ruleJsdocRequireDescriptionUppercase,
+    "jsdoc-description-length": ruleJsdocDescriptionLength,
     "methods-naming": ruleMethodsNaming,
     "methods-ordering": ruleMethodsOrdering,
     "multiline-comment-end-backslash": ruleMultilineCommentEndBackslash,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-crisp",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "Custom ESLint Rules for Crisp",
   "author": "Crisp IM SAS",
   "main": "index.js",

package/recommended-ts.js

@@ -181,13 +181,23 @@ export default function configRecommendedTS(pluginCrisp) {
         "crisp/regex-in-constructor": "error",
         "crisp/ternary-parenthesis": "error",
 
+        // Crisp JSDoc rules
+        "crisp/jsdoc-description-length": "error",
+        "crisp/jsdoc-no-param-return": "error",
+
         // General JSDoc rules
+        "jsdoc/no-types": "error",
         "jsdoc/require-description": "error",
         "jsdoc/require-param": "off",
+        "jsdoc/require-param-type": "off",
         "jsdoc/require-param-description": "off",
+        "jsdoc/check-param-names": "off",
         "jsdoc/require-property-description": "off",
         "jsdoc/require-returns": "off",
+        "jsdoc/require-returns-type": "off",
+        "jsdoc/require-returns-check": "off",
         "jsdoc/require-yields": "off",
+        "jsdoc/require-yields-check": "off",
         "jsdoc/require-jsdoc": [
           "error",
 

package/recommended-vue.js

@@ -247,6 +247,7 @@ export default function configRecommendedVue(pluginCrisp) {
         "crisp/jsdoc-enforce-access": "error",
         "crisp/jsdoc-enforce-classdesc": "error",
         "crisp/jsdoc-require-description-uppercase": "error",
+        "crisp/jsdoc-description-length": "error",
 
         // General Vue rules
         "vue/attributes-order": [

package/recommended.js

@@ -232,7 +232,8 @@ export default function configRecommended(pluginCrisp) {
         "crisp/jsdoc-align-params": "error",
         "crisp/jsdoc-check-indentation": "error",
         "crisp/jsdoc-enforce-classdesc": "error",
-        "crisp/jsdoc-require-description-uppercase": "error"
+        "crisp/jsdoc-require-description-uppercase": "error",
+        "crisp/jsdoc-description-length": "error"
       }
     }
   ];

package/rules/jsdoc-description-length.js

@@ -0,0 +1,113 @@
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Enforce JSDoc description line limits and continuation format.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          maxLines: {
+            type: "integer",
+            minimum: 1,
+            default: 2,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context) {
+    const options = context.options[0] || {};
+    const maxLines = options.maxLines || 2;
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    function checkComment(comment) {
+      if (comment.type !== "Block" || !comment.value.startsWith("*")) {
+        return;
+      }
+
+      // Skip section headers (lines full of asterisks)
+      if (/\*{10,}/.test(comment.value)) {
+        return;
+      }
+
+      const rawLines = comment.value.split("\n").slice(1);
+
+      // Extract description lines (before any @tag)
+      const descLines = [];
+
+      for (const line of rawLines) {
+        const content = line.replace(/^\s*\*\s?/, "");
+
+        if (content.trimStart().startsWith("@")) {
+          break;
+        }
+
+        if (content.trim().length > 0) {
+          descLines.push({ raw: line, content: content });
+        }
+      }
+
+      if (descLines.length <= 1) {
+        return;
+      }
+
+      if (descLines.length > maxLines) {
+        context.report({
+          loc: comment.loc,
+          message:
+            "JSDoc description must not exceed {{ maxLines }} line(s).",
+          data: { maxLines: String(maxLines) },
+        });
+
+        return;
+      }
+
+      // Multi-line is allowed, check continuation format
+      for (let i = 0; i < descLines.length - 1; i++) {
+        const trimmed = descLines[i].content.trimEnd();
+
+        if (!trimmed.endsWith("\\")) {
+          context.report({
+            loc: comment.loc,
+            message:
+              "Multi-line JSDoc description must end with '\\' before " +
+              "each continuation.",
+          });
+
+          return;
+        }
+      }
+
+      // Check indentation on continuation lines (3 spaces after *)
+      for (let i = 1; i < descLines.length; i++) {
+        const match = descLines[i].raw.match(/^\s*\*( *)/);
+
+        if (!match || match[1].length !== 3) {
+          context.report({
+            loc: comment.loc,
+            message:
+              "Continuation lines in JSDoc description must be indented " +
+              "with 3 spaces after '*'.",
+          });
+
+          return;
+        }
+      }
+    }
+
+    return {
+      "Program:exit"() {
+        const comments = sourceCode.getAllComments();
+
+        for (const comment of comments) {
+          checkComment(comment);
+        }
+      },
+    };
+  },
+};

package/rules/jsdoc-no-param-return.js

@@ -0,0 +1,63 @@
+const FORBIDDEN_TAG_REGEX = /^\s*\*\s*@(param|arg|argument|returns?|yields?)\b/;
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Forbid @param and @return tags (and their descriptions) in JSDoc, " +
+        "rely on the TypeScript signature instead.",
+    },
+    fixable: "code",
+    schema: [],
+    messages: {
+      noParamReturn:
+        "@param and @return tags are not permitted in JSDoc, rely on the " +
+        "TypeScript signature instead.",
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    function checkComment(comment) {
+      if (comment.type !== "Block" || !comment.value.startsWith("*")) {
+        return;
+      }
+
+      const lines = comment.value.split("\n");
+
+      // Detect whether at least one forbidden tag line is present
+      const hasForbidden = lines.some((line) => {
+        return FORBIDDEN_TAG_REGEX.test(line);
+      });
+
+      if (!hasForbidden) {
+        return;
+      }
+
+      context.report({
+        node: comment,
+        messageId: "noParamReturn",
+
+        fix(fixer) {
+          const kept = lines.filter((line) => {
+            return !FORBIDDEN_TAG_REGEX.test(line);
+          });
+
+          return fixer.replaceText(comment, `/*${kept.join("\n")}*/`);
+        },
+      });
+    }
+
+    return {
+      "Program:exit"() {
+        const comments = sourceCode.getAllComments();
+
+        for (const comment of comments) {
+          checkComment(comment);
+        }
+      },
+    };
+  },
+};