eslint-plugin-crisp 1.4.8 → 1.4.10

package/README.md

@@ -115,6 +115,7 @@ Each item has emojis denoting:
 | Name | Description | 🟠 | 🟢 | 🟣 |
 | :- | :- | :- | :- | :- |
 | [crisp/align-comments](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/align-comments.js) | Enforces alignment of comments compared to the previous line (the `indent` rule doesn't check this case) | 🟠 | 🟢 | 🟣 |
+| [crisp/consecutive-line-comments](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/consecutive-line-comments.js) | Enforces consecutive single-line comments to form a single multi-line continuation block | 🟠 | 🟢 | 🟣 |
 | [crisp/align-consecutive-class-assignements](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/align-consecutive-class-assignements.js) | Enforces alignment of consecutive assignment statements in a class constructor | 🟠 |
 | [crisp/align-one-var](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/align-one-var.js) | Enforces alignment of variables in 'one-var' statements | 🟠 |
 | [crisp/align-requires](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/align-requires.js) | Enforces alignment of require statements | 🟠 |
@@ -146,12 +147,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 +172,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

@@ -6,6 +6,7 @@ import ruleAlignComments from "./rules/align-comments.js";
 import ruleAlignConsecutiveClassAssignements from "./rules/align-consecutive-class-assignements.js";
 import ruleAlignOneVar from "./rules/align-one-var.js";
 import ruleAlignRequires from "./rules/align-requires.js";
+import ruleConsecutiveLineComments from "./rules/consecutive-line-comments.js";
 import ruleConst from "./rules/const.js";
 import ruleConstructorVariables from "./rules/constructor-variables.js";
 import ruleEnforceOptional from "./rules/enforce-optional.js";
@@ -18,6 +19,7 @@ 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";
@@ -69,6 +71,7 @@ const plugin = {
     "align-consecutive-class-assignements": ruleAlignConsecutiveClassAssignements,
     "align-one-var": ruleAlignOneVar,
     "align-requires": ruleAlignRequires,
+    "consecutive-line-comments": ruleConsecutiveLineComments,
     "const": ruleConst,
     "constructor-variables": ruleConstructorVariables,
     "enforce-optional": ruleEnforceOptional,
@@ -81,6 +84,7 @@ 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,

package/package.json

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

package/recommended-ts.js

@@ -151,6 +151,7 @@ export default function configRecommendedTS(pluginCrisp) {
 
         // Crisp JS rules
         "crisp/align-comments": "error",
+        "crisp/consecutive-line-comments": "error",
         "crisp/enforce-optional": "error",
         "crisp/header-check": "error",
         "crisp/header-comments-check": "error",
@@ -183,14 +184,21 @@ export default function configRecommendedTS(pluginCrisp) {
 
         // 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

@@ -162,6 +162,7 @@ export default function configRecommendedVue(pluginCrisp) {
 
         // Crisp JS rules
         "crisp/align-comments": "error",
+        "crisp/consecutive-line-comments": "error",
         "crisp/enforce-optional": "error",
         "crisp/header-check": "error",
         "crisp/header-comments-check": "error",
@@ -247,6 +248,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

@@ -156,6 +156,7 @@ export default function configRecommended(pluginCrisp) {
 
         // Crisp JS rules
         "crisp/align-comments": "error",
+        "crisp/consecutive-line-comments": "error",
         "crisp/align-consecutive-class-assignements": "error",
         "crisp/align-one-var": "error",
         "crisp/align-requires": "error",
@@ -232,7 +233,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/consecutive-line-comments.js

@@ -0,0 +1,250 @@
+const DIRECTIVE_REGEX = /^(eslint|ts-|@ts|prettier-|global |globals |istanbul|c8 |v8 |jshint|jslint)/;
+
+// A short capitalized label followed by a colon (e.g. 'Notice:', 'Important:',
+// 'Source:') introduces a new logical comment, so the previous comment does not
+// need to be merged into a continuation block with it. The label is kept short
+// (up to ~40 chars) to avoid matching a regular sentence that contains a colon
+const BOUNDARY_REGEX = /^[A-Z][^:]{0,39}:/;
+
+function getCore(comment) {
+  // Strip the trailing continuation backslash and surrounding whitespace
+  return comment.value.replace(/\\\s*$/, "").trim();
+}
+
+function isDirective(core) {
+  return DIRECTIVE_REGEX.test(core);
+}
+
+function isBoundary(core) {
+  return BOUNDARY_REGEX.test(core);
+}
+
+function isContinuationLine(comment) {
+  // Continuation lines use at least three spaces after '//'
+  return /^ {3,}/.test(comment.value);
+}
+
+function isBoundaryComment(comment) {
+  // Labels such as 'Notice:' only split groups on first lines, not mid-block
+  // prose like '//   In other words: …'
+  return !isContinuationLine(comment) && isBoundary(getCore(comment));
+}
+
+function endsWithContinuation(comment) {
+  return /\\\s*$/.test(comment.value);
+}
+
+function isBlankSeparatorLine(comment) {
+  // A line that only contains '\' (e.g. '// \' or '//   \') is a visual separator
+  return (
+    comment.type === "Line" &&
+    endsWithContinuation(comment) &&
+    getCore(comment).length === 0
+  );
+}
+
+export default {
+  meta: {
+    type: "layout",
+    docs: {
+      description:
+        "Enforce that consecutive single-line comments are written as a " +
+        "single multi-line continuation block.",
+      category: "Stylistic Issues",
+      recommended: false,
+    },
+    fixable: "whitespace",
+    schema: [],
+    messages: {
+      format:
+        "Consecutive single-line comments must form a continuation block: " +
+        "each line ends with '\\' (except the last) and continuation lines " +
+        "are indented with at least three spaces after '//'.",
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    function isStandalone(comment) {
+      const lineText = sourceCode.lines[comment.loc.start.line - 1] || "";
+      const before = lineText.slice(0, comment.loc.start.column);
+
+      return before.trim() === "";
+    }
+
+    function getCanonicalCommentText(comment, index, groupLength) {
+      const core = getCore(comment);
+      const isLast = index === groupLength - 1;
+      const suffix = isLast ? "" : " \\";
+
+      if (index === 0) {
+        return `// ${core}${suffix}`;
+      }
+
+      return `//   ${core}${suffix}`;
+    }
+
+    function commentMatchesCanonical(comment, index, groupLength) {
+      const core = getCore(comment);
+      const isLast = index === groupLength - 1;
+      const line = sourceCode.lines[comment.loc.start.line - 1] || "";
+      const actual = line.slice(comment.loc.start.column);
+
+      if (isBlankSeparatorLine(comment) && index < groupLength - 1) {
+        return /^\/\/\s*\\$/.test(actual);
+      }
+
+      if (index === 0) {
+        const expected = `// ${core}${isLast ? "" : " \\"}`;
+
+        return actual === expected;
+      }
+
+      const match = actual.match(/^\/\/(\s+)(.*)$/);
+
+      if (!match || match[1].length < 3) {
+        return false;
+      }
+
+      let body = match[2];
+
+      if (!isLast) {
+        if (!/\\\s*$/.test(body)) {
+          return false;
+        }
+
+        body = body.replace(/\\\s*$/, "");
+      }
+
+      return body.trim() === core;
+    }
+
+    function checkGroup(group) {
+      if (group.length < 2) {
+        return;
+      }
+
+      const indent = " ".repeat(group[0].loc.start.column);
+
+      const canonicalLines = group.map((comment, index) => {
+        return getCanonicalCommentText(comment, index, group.length);
+      });
+
+      const canonical = canonicalLines.join(`\n${indent}`);
+
+      const allMatch = group.every((comment, index) => {
+        return commentMatchesCanonical(comment, index, group.length);
+      });
+
+      if (allMatch) {
+        return;
+      }
+
+      context.report({
+        loc: {
+          start: group[0].loc.start,
+          end: group[group.length - 1].loc.end,
+        },
+        messageId: "format",
+
+        fix(fixer) {
+          return fixer.replaceTextRange(
+            [group[0].range[0], group[group.length - 1].range[1]],
+            canonical
+          );
+        },
+      });
+    }
+
+    return {
+      Program() {
+        const comments = sourceCode.getAllComments();
+
+        let group = [];
+        let skipDirectiveContinuation = false;
+        let skipColumn = 0;
+        let skipLine = 0;
+
+        const flush = () => {
+          checkGroup(group);
+
+          group = [];
+        };
+
+        for (const comment of comments) {
+          if (
+            skipDirectiveContinuation &&
+            comment.type === "Line" &&
+            isStandalone(comment) &&
+            comment.loc.start.line === skipLine + 1 &&
+            comment.loc.start.column === skipColumn
+          ) {
+            skipLine = comment.loc.start.line;
+
+            if (!endsWithContinuation(comment)) {
+              skipDirectiveContinuation = false;
+            }
+
+            continue;
+          }
+
+          skipDirectiveContinuation = false;
+
+          const core = getCore(comment);
+          const isGroupable =
+            comment.type === "Line" &&
+            isStandalone(comment) &&
+            !isDirective(core) &&
+            (core.length > 0 || isBlankSeparatorLine(comment));
+
+          if (!isGroupable) {
+            flush();
+
+            if (
+              comment.type === "Line" &&
+              isStandalone(comment) &&
+              isDirective(core) &&
+              endsWithContinuation(comment)
+            ) {
+              skipDirectiveContinuation = true;
+              skipColumn = comment.loc.start.column;
+              skipLine = comment.loc.start.line;
+            }
+
+            continue;
+          }
+
+          if (group.length > 0) {
+            const previous = group[group.length - 1];
+            const isConsecutive =
+              comment.loc.start.line === previous.loc.start.line + 1 &&
+              comment.loc.start.column === previous.loc.start.column;
+
+            // A completed block (no trailing '\') must not absorb the next line
+            if (!endsWithContinuation(previous)) {
+              flush();
+            }
+
+            if (group.length > 0) {
+              const last = group[group.length - 1];
+              const stillConsecutive =
+                comment.loc.start.line === last.loc.start.line + 1 &&
+                comment.loc.start.column === last.loc.start.column;
+
+              // A boundary marker (e.g. 'Notice:') always starts a fresh group,
+              // so the previous comment is left untouched
+              if (!stillConsecutive || isBoundaryComment(comment)) {
+                flush();
+              }
+            }
+          }
+
+          group.push(comment);
+        }
+
+        flush();
+      },
+    };
+  },
+};

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);
+        }
+      },
+    };
+  },
+};