@kazupon/eslint-plugin 0.3.0 → 0.4.0

package/README.md

@@ -61,10 +61,11 @@ The rules with the following star ⭐ are included in the configs.
 
 ### @kazupon/eslint-plugin Rules
 
-| Rule ID                                                                                                | Description                                     | Category | Fixable | RECOMMENDED |
-| :----------------------------------------------------------------------------------------------------- | :---------------------------------------------- | :------- | :-----: | :---------: |
-| [@kazupon/enforce-header-comment](https://eslint-plugin.kazupon.dev/rules/enforce-header-comment.html) | Enforce heading the comment in source code file | Comment  |         |     ⭐      |
-| [@kazupon/no-tag-comments](https://eslint-plugin.kazupon.dev/rules/no-tag-comments.html)               | disallow tag comments                           | Comment  |         |             |
+| Rule ID                                                                                                          | Description                                     | Category | Fixable | RECOMMENDED |
+| :--------------------------------------------------------------------------------------------------------------- | :---------------------------------------------- | :------- | :-----: | :---------: |
+| [@kazupon/enforce-header-comment](https://eslint-plugin.kazupon.dev/rules/enforce-header-comment.html)           | Enforce heading the comment in source code file | Comment  |         |     ⭐      |
+| [@kazupon/no-tag-comments](https://eslint-plugin.kazupon.dev/rules/no-tag-comments.html)                         | disallow tag comments                           | Comment  |         |     ⭐      |
+| [@kazupon/prefer-scope-on-tag-comment](https://eslint-plugin.kazupon.dev/rules/prefer-scope-on-tag-comment.html) | enforce adding a scope to tag comments          | Comment  |         |     ⭐      |
 
 <!--RULES_TABLE_END-->
 

package/lib/index.d.ts

@@ -8,9 +8,10 @@ type PluginConfigs = {
 declare const plugin: Omit<ESLint.Plugin, "configs"> & {
   configs: PluginConfigs;
 };
+declare const recommendedConfig: Linter.Config[];
 declare const commentConfig: Linter.Config[];
 declare const configs: {
-  recommended: typeof commentConfig;
+  recommended: typeof recommendedConfig;
   comment: typeof commentConfig;
 };
 /** @alias */

package/lib/index.js

@@ -12,7 +12,7 @@ const name = "@kazupon/eslint-plugin";
 /**
 * The plugin version.
 */
-const version = "0.3.0";
+const version = "0.4.0";
 /**
 * The namespace for rules
 */
@@ -22,7 +22,7 @@ const namespace = "@kazupon";
 //#region src/utils/rule.ts
 const BLOB_URL = "https://eslint-plugin.kazupon.dev/rules";
 function RuleCreator(urlCreator, namespace$1 = "") {
-	return function createNamedRule({ meta, name: name$1,...rule$2 }) {
+	return function createNamedRule({ meta, name: name$1,...rule$3 }) {
 		const ruleId = namespace$1 ? `${namespace$1}/${name$1}` : name$1;
 		return {
 			meta: {
@@ -34,7 +34,7 @@ function RuleCreator(urlCreator, namespace$1 = "") {
 					ruleId
 				}
 			},
-			...rule$2
+			...rule$3
 		};
 	};
 }
@@ -53,7 +53,7 @@ function initializeTagDiagnosis(tags) {
 function validTagDiagnosis(tagDiagnosis) {
 	return Object.keys(tagDiagnosis).every((tag) => tagDiagnosis[tag] === "ok");
 }
-const rule$1 = createRule({
+const rule$2 = createRule({
 	name: "enforce-header-comment",
 	meta: {
 		type: "suggestion",
@@ -181,11 +181,10 @@ const rule$1 = createRule({
 		};
 	}
 });
-var enforce_header_comment_default = rule$1;
+var enforce_header_comment_default = rule$2;
 
 //#endregion
-//#region src/rules/no-tag-comments.ts
-const DEFAULT_TAGS = ["FIXME", "BUG"];
+//#region src/utils/comment.ts
 /**
 * Remove JSDoc asterisk prefix if present
 */
@@ -193,17 +192,77 @@ function stripJSDocPrefix(line) {
 	const trimmed = line.trim();
 	return trimmed.startsWith("*") ? trimmed.slice(1).trim() : trimmed;
 }
-const rule = createRule({
+/**
+* Check if the text starts with any of the given tags
+* @param text The text to check
+* @param tags Array of tags to search for
+* @returns Tag detection result or null if no tag found
+*/
+function detectTag(text, tags) {
+	for (const tag of tags) {
+		const tagRegex = new RegExp(`^${tag}\\b`);
+		const match = text.match(tagRegex);
+		if (match) {
+			const afterTag = text.slice(tag.length);
+			if (afterTag.startsWith("(")) {
+				const closingParenIndex = afterTag.indexOf(")");
+				if (closingParenIndex > 0) {
+					const scope = afterTag.slice(1, closingParenIndex).trim();
+					return {
+						tag,
+						hasScope: scope.length > 0
+					};
+				}
+				return {
+					tag,
+					hasScope: false
+				};
+			}
+			if (afterTag === "" || afterTag.startsWith(":") || afterTag.startsWith(" ")) return {
+				tag,
+				hasScope: false
+			};
+		}
+	}
+	return null;
+}
+/**
+* Calculate the exact location of a tag in a comment
+* @param comment The comment containing the tag
+* @param line The line of text containing the tag
+* @param lineIndex The index of the line within the comment
+* @param tag The tag to locate
+* @returns Location with line and column, or null if not found
+*/
+function calculateTagLocation(comment, line, lineIndex, tag) {
+	const tagIndex = line.indexOf(tag);
+	if (tagIndex === -1) return null;
+	if (lineIndex === 0) {
+		const tagIndexInValue = comment.value.indexOf(tag);
+		return tagIndexInValue === -1 ? null : {
+			line: comment.loc.start.line,
+			column: comment.loc.start.column + 2 + tagIndexInValue
+		};
+	} else return {
+		line: comment.loc.start.line + lineIndex,
+		column: tagIndex
+	};
+}
+
+//#endregion
+//#region src/rules/no-tag-comments.ts
+const DEFAULT_TAGS$1 = ["FIXME", "BUG"];
+const rule$1 = createRule({
 	name: "no-tag-comments",
 	meta: {
 		type: "problem",
 		docs: {
 			description: "disallow tag comments",
 			category: "Comment",
-			recommended: false,
+			recommended: true,
 			defaultSeverity: "warn"
 		},
-		messages: { avoidTagComment: "Fix '{{tag}}' tag comment" },
+		messages: { tagComment: "Exist '{{tag}}' tag comment" },
 		schema: [{
 			type: "object",
 			properties: { tags: {
@@ -216,59 +275,168 @@ const rule = createRule({
 		}]
 	},
 	create(ctx) {
-		const options = ctx.options[0] || { tags: DEFAULT_TAGS };
-		const tags = options.tags || DEFAULT_TAGS;
+		const options = ctx.options[0] || { tags: DEFAULT_TAGS$1 };
+		const tags = options.tags || DEFAULT_TAGS$1;
 		const sourceCode = ctx.sourceCode;
 		/**
-		* Check if the text starts with a tag followed by valid delimiter
-		*/
-		function hasTag(text) {
-			for (const tag of tags) if (text.startsWith(tag)) {
-				const afterTag = text.slice(tag.length);
-				if (afterTag === "" || afterTag.startsWith(":") || afterTag.startsWith(" ")) return tag;
-			}
-			return null;
-		}
-		/**
 		* Report a tag comment violation
 		*/
-		function reportTag(comment, tag) {
-			ctx.report({
-				messageId: "avoidTagComment",
+		function reportTag(comment, tag, loc) {
+			if (loc && comment.loc) ctx.report({
+				messageId: "tagComment",
+				data: { tag },
+				loc: {
+					start: {
+						line: loc.line,
+						column: loc.column
+					},
+					end: {
+						line: loc.line,
+						column: loc.column + tag.length
+					}
+				}
+			});
+			else ctx.report({
+				messageId: "tagComment",
 				data: { tag },
 				loc: comment.loc
 			});
 		}
 		/**
-		* Process a single line of text for tags
+		* Check a comment for tag violations
 		*/
-		function checkLine(text, comment) {
-			const tag = hasTag(text);
-			if (tag) {
-				reportTag(comment, tag);
-				return true;
+		function checkComment(comment) {
+			const { value, type } = comment;
+			if (type === "Line") {
+				const tagInfo = detectTag(value.trim(), tags);
+				if (tagInfo) {
+					const tagIndex = value.indexOf(tagInfo.tag);
+					if (tagIndex !== -1) reportTag(comment, tagInfo.tag, {
+						line: comment.loc.start.line,
+						column: comment.loc.start.column + 2 + tagIndex
+					});
+				}
+				return;
+			}
+			const lines = value.split("\n");
+			for (const [i, line] of lines.entries()) {
+				const trimmedLine = line.trim();
+				if (!trimmedLine) continue;
+				const contentToCheck = stripJSDocPrefix(line);
+				const tagInfo = detectTag(contentToCheck, tags);
+				if (tagInfo) {
+					const location = calculateTagLocation(comment, line, i, tagInfo.tag);
+					if (location) {
+						reportTag(comment, tagInfo.tag, location);
+						break;
+					}
+				}
 			}
-			return false;
 		}
+		return { Program() {
+			const comments = sourceCode.getAllComments();
+			for (const comment of comments) checkComment(comment);
+		} };
+	}
+});
+var no_tag_comments_default = rule$1;
+
+//#endregion
+//#region src/rules/prefer-scope-on-tag-comment.ts
+const DEFAULT_TAGS = [
+	"TODO",
+	"FIXME",
+	"HACK",
+	"BUG",
+	"NOTE"
+];
+const rule = createRule({
+	name: "prefer-scope-on-tag-comment",
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "enforce adding a scope to tag comments",
+			category: "Comment",
+			recommended: true,
+			defaultSeverity: "warn"
+		},
+		messages: { missingScope: "Tag comment '{{tag}}' is missing a scope. Use format: {{tag}}(scope)" },
+		schema: [{
+			type: "object",
+			properties: { tags: {
+				type: "array",
+				items: { type: "string" },
+				minItems: 1,
+				uniqueItems: true
+			} },
+			additionalProperties: false
+		}]
+	},
+	create(ctx) {
+		const options = ctx.options[0] || { tags: DEFAULT_TAGS };
+		const tags = options.tags || DEFAULT_TAGS;
+		const sourceCode = ctx.sourceCode;
 		/**
-		* Check a comment for tag violations
+		* Report a missing scope violation
+		*/
+		function reportMissingScope(comment, tag, loc) {
+			if (!comment.loc) {
+				ctx.report({
+					messageId: "missingScope",
+					data: { tag },
+					node: ctx.sourceCode.ast
+				});
+				return;
+			}
+			if (loc && comment.loc) ctx.report({
+				messageId: "missingScope",
+				data: { tag },
+				loc: {
+					start: {
+						line: loc.line,
+						column: loc.column
+					},
+					end: {
+						line: loc.line,
+						column: loc.column + tag.length
+					}
+				}
+			});
+			else ctx.report({
+				messageId: "missingScope",
+				data: { tag },
+				loc: comment.loc
+			});
+		}
+		/**
+		* Check a comment for missing scope
 		*/
 		function checkComment(comment) {
 			const { value, type } = comment;
 			if (type === "Line") {
-				checkLine(value.trim(), comment);
+				const tagInfo = detectTag(value.trim(), tags);
+				if (tagInfo && !tagInfo.hasScope) {
+					const tagIndex = value.indexOf(tagInfo.tag);
+					if (tagIndex !== -1) reportMissingScope(comment, tagInfo.tag, {
+						line: comment.loc.start.line,
+						column: comment.loc.start.column + 2 + tagIndex
+					});
+				}
 				return;
 			}
 			const lines = value.split("\n");
-			if (lines.length === 1) {
-				checkLine(value.trim(), comment);
-				return;
-			}
-			for (const line of lines) {
+			for (const [i, line] of lines.entries()) {
 				const trimmedLine = line.trim();
 				if (!trimmedLine) continue;
 				const contentToCheck = stripJSDocPrefix(line);
-				if (checkLine(contentToCheck, comment)) break;
+				const tagInfo = detectTag(contentToCheck, tags);
+				if (tagInfo && !tagInfo.hasScope) {
+					const location = calculateTagLocation(comment, line, i, tagInfo.tag);
+					if (location) {
+						reportMissingScope(comment, tagInfo.tag, location);
+						break;
+					}
+				}
 			}
 		}
 		return { Program() {
@@ -277,13 +445,14 @@ const rule = createRule({
 		} };
 	}
 });
-var no_tag_comments_default = rule;
+var prefer_scope_on_tag_comment_default = rule;
 
 //#endregion
 //#region src/rules/index.ts
 const rules = {
 	"enforce-header-comment": enforce_header_comment_default,
-	"no-tag-comments": no_tag_comments_default
+	"no-tag-comments": no_tag_comments_default,
+	"prefer-scope-on-tag-comment": prefer_scope_on_tag_comment_default
 };
 
 //#endregion
@@ -296,6 +465,23 @@ const plugin = {
 	rules,
 	configs: {}
 };
+const recommendedConfig = [{
+	name: "@kazupon/eslint-plugin/recommended",
+	files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
+	ignores: [
+		"**/*.md",
+		"**/*.md/**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}",
+		"**/*.config.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"
+	],
+	plugins: { [namespace]: plugin },
+	rules: Object.entries(rules).reduce((acc, [ruleName, rule$3]) => {
+		if (rule$3.meta?.docs?.recommended) {
+			const ruleId = rule$3.meta?.docs?.ruleId || (namespace ? `${namespace}/${ruleName}` : ruleName);
+			acc[ruleId] = rule$3.meta?.docs?.defaultSeverity || "warn";
+		}
+		return acc;
+	}, Object.create(null))
+}];
 const commentConfig = [{
 	name: "@kazupon/eslint-plugin/comment",
 	files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
@@ -305,14 +491,14 @@ const commentConfig = [{
 		"**/*.config.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"
 	],
 	plugins: { [namespace]: plugin },
-	rules: Object.entries(rules).reduce((rules$1, [ruleName, rule$2]) => {
-		const ruleId = rule$2.meta?.docs?.ruleId || (namespace ? `${namespace}/${ruleName}` : ruleName);
-		rules$1[ruleId] = rule$2.meta?.docs?.defaultSeverity || "warn";
+	rules: Object.entries(rules).reduce((rules$1, [ruleName, rule$3]) => {
+		const ruleId = rule$3.meta?.docs?.ruleId || (namespace ? `${namespace}/${ruleName}` : ruleName);
+		rules$1[ruleId] = rule$3.meta?.docs?.defaultSeverity || "warn";
 		return rules$1;
 	}, Object.create(null))
 }];
 const configs = {
-	recommended: [...commentConfig],
+	recommended: recommendedConfig,
 	comment: commentConfig
 };
 plugin.configs = configs;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kazupon/eslint-plugin",
   "description": "ESLint plugin for @kazupon",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "funding": "https://github.com/sponsors/kazupon",
   "bugs": {
@@ -56,7 +56,7 @@
   "devDependencies": {
     "@eslint/compat": "^1.2.9",
     "@eslint/markdown": "^6.5.0",
-    "@kazupon/eslint-config": "^0.30.0",
+    "@kazupon/eslint-config": "^0.31.0",
     "@kazupon/prettier-config": "^0.1.1",
     "@shikijs/vitepress-twoslash": "^3.6.0",
     "@types/node": "^22.15.30",
@@ -69,7 +69,8 @@
     "eslint-plugin-jsonc": "^2.20.1",
     "eslint-plugin-module-interop": "^0.3.1",
     "eslint-plugin-promise": "^7.2.1",
-    "eslint-plugin-unicorn": "^58.0.0",
+    "eslint-plugin-regexp": "^2.8.0",
+    "eslint-plugin-unicorn": "^59.0.0",
     "eslint-plugin-unused-imports": "^4.1.4",
     "eslint-plugin-yml": "^1.18.0",
     "eslint-vitest-rule-tester": "^2.2.0",