eslint-plugin-jsdoc 52.0.2 → 52.0.3

package/dist/rules/requireHyphenBeforeParamDescription.js

@@ -0,0 +1,89 @@
+import iterateJsdoc from "../iterateJsdoc.js";
+
+//#region src/rules/requireHyphenBeforeParamDescription.js
+var requireHyphenBeforeParamDescription_default = iterateJsdoc(({ context, jsdoc, utils }) => {
+	const [mainCircumstance, { tags = null } = {}] = context.options;
+	const tgs = tags;
+	/**
+	* @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag
+	* @param {string} targetTagName
+	* @param {"always"|"never"} [circumstance]
+	* @returns {void}
+	*/
+	const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {
+		const always = !circumstance || circumstance === "always";
+		const desc = utils.getTagDescription(jsdocTag);
+		if (!desc.trim()) return;
+		const startsWithHyphen = /^\s*-/v.test(desc);
+		let lines = 0;
+		for (const { tokens } of jsdocTag.source) {
+			if (tokens.description) break;
+			lines++;
+		}
+		if (always) {
+			if (!startsWithHyphen) utils.reportJSDoc(`There must be a hyphen before @${targetTagName} description.`, { line: jsdocTag.source[0].number + lines }, () => {
+				for (const { tokens } of jsdocTag.source) if (tokens.description) {
+					tokens.description = tokens.description.replace(/^(\s*)/v, "$1- ");
+					break;
+				}
+			});
+		} else if (startsWithHyphen) utils.reportJSDoc(`There must be no hyphen before @${targetTagName} description.`, { line: jsdocTag.source[0].number + lines }, () => {
+			for (const { tokens } of jsdocTag.source) if (tokens.description) {
+				tokens.description = tokens.description.replace(/^\s*-\s*/v, "");
+				break;
+			}
+		}, true);
+	};
+	utils.forEachPreferredTag("param", checkHyphens);
+	if (tgs) {
+		const tagEntries = Object.entries(tgs);
+		for (const [tagName, circumstance] of tagEntries) {
+			if (tagName === "*") {
+				const preferredParamTag = utils.getPreferredTagName({ tagName: "param" });
+				for (const { tag } of jsdoc.tags) {
+					if (tag === preferredParamTag || tagEntries.some(([tagNme]) => {
+						return tagNme !== "*" && tagNme === tag;
+					})) continue;
+					utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {
+						checkHyphens(jsdocTag, targetTagName, circumstance);
+					});
+				}
+				continue;
+			}
+			utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {
+				checkHyphens(jsdocTag, targetTagName, circumstance);
+			});
+		}
+	}
+}, {
+	iterateAllJsdocs: true,
+	meta: {
+		docs: {
+			description: "Requires a hyphen before the `@param` description.",
+			url: "https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header"
+		},
+		fixable: "code",
+		schema: [{
+			enum: ["always", "never"],
+			type: "string"
+		}, {
+			additionalProperties: false,
+			properties: { tags: { anyOf: [{
+				patternProperties: { ".*": {
+					enum: ["always", "never"],
+					type: "string"
+				} },
+				type: "object"
+			}, {
+				enum: ["any"],
+				type: "string"
+			}] } },
+			type: "object"
+		}],
+		type: "layout"
+	}
+});
+
+//#endregion
+export { requireHyphenBeforeParamDescription_default as default };
+//# sourceMappingURL=requireHyphenBeforeParamDescription.js.map

package/dist/rules/requireHyphenBeforeParamDescription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireHyphenBeforeParamDescription.js","names":[],"sources":["../../src/rules/requireHyphenBeforeParamDescription.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  utils,\n}) => {\n  const [\n    mainCircumstance,\n    {\n      tags = null,\n    } = {},\n  ] = context.options;\n\n  const tgs = /**\n               * @type {null|\"any\"|{[key: string]: \"always\"|\"never\"}}\n               */ (tags);\n\n  /**\n   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag\n   * @param {string} targetTagName\n   * @param {\"always\"|\"never\"} [circumstance]\n   * @returns {void}\n   */\n  const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {\n    const always = !circumstance || circumstance === 'always';\n    const desc = /** @type {string} */ (utils.getTagDescription(jsdocTag));\n    if (!desc.trim()) {\n      return;\n    }\n\n    const startsWithHyphen = (/^\\s*-/v).test(desc);\n    let lines = 0;\n    for (const {\n      tokens,\n    } of jsdocTag.source) {\n      if (tokens.description) {\n        break;\n      }\n\n      lines++;\n    }\n\n    if (always) {\n      if (!startsWithHyphen) {\n        utils.reportJSDoc(\n          `There must be a hyphen before @${targetTagName} description.`,\n          {\n            line: jsdocTag.source[0].number + lines,\n          },\n          () => {\n            for (const {\n              tokens,\n            } of jsdocTag.source) {\n              if (tokens.description) {\n                tokens.description = tokens.description.replace(\n                  /^(\\s*)/v, '$1- ',\n                );\n                break;\n              }\n            }\n          },\n        );\n      }\n    } else if (startsWithHyphen) {\n      utils.reportJSDoc(\n        `There must be no hyphen before @${targetTagName} description.`,\n        {\n          line: jsdocTag.source[0].number + lines,\n        },\n        () => {\n          for (const {\n            tokens,\n          } of jsdocTag.source) {\n            if (tokens.description) {\n              tokens.description = tokens.description.replace(\n                /^\\s*-\\s*/v, '',\n              );\n              break;\n            }\n          }\n        },\n        true,\n      );\n    }\n  };\n\n  utils.forEachPreferredTag('param', checkHyphens);\n  if (tgs) {\n    const tagEntries = Object.entries(tgs);\n    for (const [\n      tagName,\n      circumstance,\n    ] of tagEntries) {\n      if (tagName === '*') {\n        const preferredParamTag = utils.getPreferredTagName({\n          tagName: 'param',\n        });\n        for (const {\n          tag,\n        } of jsdoc.tags) {\n          if (tag === preferredParamTag || tagEntries.some(([\n            tagNme,\n          ]) => {\n            return tagNme !== '*' && tagNme === tag;\n          })) {\n            continue;\n          }\n\n          utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {\n            checkHyphens(\n              jsdocTag,\n              targetTagName,\n              /** @type {\"always\"|\"never\"} */ (circumstance),\n            );\n          });\n        }\n\n        continue;\n      }\n\n      utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {\n        checkHyphens(\n          jsdocTag,\n          targetTagName,\n          /** @type {\"always\"|\"never\"} */ (circumstance),\n        );\n      });\n    }\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires a hyphen before the `@param` description.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        enum: [\n          'always', 'never',\n        ],\n        type: 'string',\n      },\n      {\n        additionalProperties: false,\n        properties: {\n          tags: {\n            anyOf: [\n              {\n                patternProperties: {\n                  '.*': {\n                    enum: [\n                      'always', 'never',\n                    ],\n                    type: 'string',\n                  },\n                },\n                type: 'object',\n              },\n              {\n                enum: [\n                  'any',\n                ],\n                type: 'string',\n              },\n            ],\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'layout',\n  },\n});\n"],"mappings":";;;AAEA,kDAAe,aAAa,CAAC,EAC3B,SACA,OACA,OACD,KAAK;CACJ,MAAM,CACJ,kBACA,EACE,OAAO,MACR,GAAG,CAAE,EACP,GAAG,QAAQ;CAEZ,MAAM,MAEW;;;;;;;CAQjB,MAAM,eAAe,CAAC,UAAU,eAAe,eAAe,qBAAqB;EACjF,MAAM,SAAS,CAAC,gBAAgB,iBAAiB;EACjD,MAAM,OAA8B,MAAM,kBAAkB,SAAS;AACrE,MAAI,CAAC,KAAK,MAAM,CACd;EAGF,MAAM,mBAAoB,SAAU,KAAK,KAAK;EAC9C,IAAI,QAAQ;AACZ,OAAK,MAAM,EACT,QACD,IAAI,SAAS,QAAQ;AACpB,OAAI,OAAO,YACT;GAGF;EACD;AAED,MAAI,QACF;OAAI,CAAC,kBACH,MAAM,YACJ,CAAC,+BAA+B,EAAE,cAAc,aAAa,CAAC,EAC9D,EACE,MAAM,SAAS,OAAO,GAAG,SAAS,MACnC,GACD,MAAM;AACJ,SAAK,MAAM,EACT,QACD,IAAI,SAAS,OACZ,KAAI,OAAO,aAAa;KACtB,OAAO,cAAc,OAAO,YAAY,QACtC,WAAW,OACZ;AACD;IACD;GAEJ,EACF;EACF,WACQ,kBACT,MAAM,YACJ,CAAC,gCAAgC,EAAE,cAAc,aAAa,CAAC,EAC/D,EACE,MAAM,SAAS,OAAO,GAAG,SAAS,MACnC,GACD,MAAM;AACJ,QAAK,MAAM,EACT,QACD,IAAI,SAAS,OACZ,KAAI,OAAO,aAAa;IACtB,OAAO,cAAc,OAAO,YAAY,QACtC,aAAa,GACd;AACD;GACD;EAEJ,GACD,KACD;CAEJ;CAED,MAAM,oBAAoB,SAAS,aAAa;AAChD,KAAI,KAAK;EACP,MAAM,aAAa,OAAO,QAAQ,IAAI;AACtC,OAAK,MAAM,CACT,SACA,aACD,IAAI,YAAY;AACf,OAAI,YAAY,KAAK;IACnB,MAAM,oBAAoB,MAAM,oBAAoB,EAClD,SAAS,QACV,EAAC;AACF,SAAK,MAAM,EACT,KACD,IAAI,MAAM,MAAM;AACf,SAAI,QAAQ,qBAAqB,WAAW,KAAK,CAAC,CAChD,OACD,KAAK;AACJ,aAAO,WAAW,OAAO,WAAW;KACrC,EAAC,CACA;KAGF,MAAM,oBAAoB,KAAK,CAAC,UAAU,kBAAkB;MAC1D,aACE,UACA,eACiC,aAClC;KACF,EAAC;IACH;AAED;GACD;GAED,MAAM,oBAAoB,SAAS,CAAC,UAAU,kBAAkB;IAC9D,aACE,UACA,eACiC,aAClC;GACF,EAAC;EACH;CACF;AACF,GAAE;CACD,kBAAkB;CAClB,MAAM;EACJ,MAAM;GACJ,aAAa;GACb,KAAK;EACN;EACD,SAAS;EACT,QAAQ,CACN;GACE,MAAM,CACJ,UAAU,OACX;GACD,MAAM;EACP,GACD;GACE,sBAAsB;GACtB,YAAY,EACV,MAAM,EACJ,OAAO,CACL;IACE,mBAAmB,EACjB,MAAM;KACJ,MAAM,CACJ,UAAU,OACX;KACD,MAAM;IACP,EACF;IACD,MAAM;GACP,GACD;IACE,MAAM,CACJ,KACD;IACD,MAAM;GACP,CACF,EACF,EACF;GACD,MAAM;EACP,CACF;EACD,MAAM;CACP;AACF,EAAC"}