@kazupon/eslint-plugin 0.3.0 → 0.5.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.5.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 = /* @__PURE__ */ 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,271 @@ 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
+		* Report a tag comment violation
 		*/
-		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;
+		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
+			});
+		}
+		/**
+		* Check a comment for tag violations
+		*/
+		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 null;
 		}
+		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 DEFAULT_DIRECTIVES = [
+	"eslint-disable",
+	"eslint-disable-next-line",
+	"eslint-disable-line",
+	"@ts-expect-error",
+	"@ts-ignore",
+	"@ts-nocheck"
+];
+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
+				},
+				directives: {
+					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 directives = options.directives || DEFAULT_DIRECTIVES;
+		const sourceCode = ctx.sourceCode;
 		/**
-		* Report a tag comment violation
+		* Report a missing scope violation
 		*/
-		function reportTag(comment, tag) {
-			ctx.report({
-				messageId: "avoidTagComment",
+		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
 			});
 		}
 		/**
-		* Process a single line of text for tags
+		* Check if comment starts with a directive and extract the description
+		* @returns Object with directive match info or null
 		*/
-		function checkLine(text, comment) {
-			const tag = hasTag(text);
-			if (tag) {
-				reportTag(comment, tag);
-				return true;
+		function parseDirectiveComment(text) {
+			const trimmedText = text.trim();
+			for (const directive of directives) if (trimmedText.startsWith(directive)) {
+				const afterDirective = trimmedText.slice(directive.length);
+				const separatorIndex = afterDirective.indexOf("--");
+				if (separatorIndex !== -1) {
+					const description = afterDirective.slice(separatorIndex + 2).trim();
+					const separatorPos = text.indexOf("--");
+					const afterSeparator = text.slice(separatorPos + 2);
+					const descriptionStart = separatorPos + 2 + (afterSeparator.length - afterSeparator.trimStart().length);
+					return {
+						directive,
+						description,
+						descriptionStart
+					};
+				}
+				if (afterDirective.trim()) {
+					const spaceMatch = afterDirective.match(/^\s+/);
+					if (spaceMatch) {
+						const description = afterDirective.trim();
+						const directiveIndex = text.indexOf(directive);
+						const descriptionStart = directiveIndex + directive.length + spaceMatch[0].length;
+						return {
+							directive,
+							description,
+							descriptionStart
+						};
+					}
+				}
 			}
-			return false;
+			return null;
 		}
 		/**
-		* Check a comment for tag violations
+		* Check a comment for missing scope
 		*/
 		function checkComment(comment) {
 			const { value, type } = comment;
 			if (type === "Line") {
-				checkLine(value.trim(), comment);
+				const directiveInfo$1 = parseDirectiveComment(value);
+				if (directiveInfo$1) {
+					const tagInfo$1 = detectTag(directiveInfo$1.description, tags);
+					if (tagInfo$1 && !tagInfo$1.hasScope) {
+						const tagIndex = directiveInfo$1.description.indexOf(tagInfo$1.tag);
+						if (tagIndex !== -1) reportMissingScope(comment, tagInfo$1.tag, {
+							line: comment.loc.start.line,
+							column: comment.loc.start.column + 2 + directiveInfo$1.descriptionStart + tagIndex
+						});
+					}
+					return;
+				}
+				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);
+			const directiveInfo = parseDirectiveComment(value);
+			if (directiveInfo) {
+				const tagInfo = detectTag(directiveInfo.description, tags);
+				if (tagInfo && !tagInfo.hasScope) if (lines.length === 1) {
+					const tagIndexInDesc = directiveInfo.description.indexOf(tagInfo.tag);
+					if (tagIndexInDesc !== -1) {
+						const tagIndexInValue = directiveInfo.descriptionStart + tagIndexInDesc;
+						const location = {
+							line: comment.loc.start.line,
+							column: comment.loc.start.column + 2 + tagIndexInValue
+						};
+						reportMissingScope(comment, tagInfo.tag, location);
+					}
+				} else {
+					const descLines = directiveInfo.description.split("\n");
+					for (const [descLineIndex, descLine] of descLines.entries()) {
+						const lineTagInfo = detectTag(descLine.trim(), tags);
+						if (lineTagInfo && !lineTagInfo.hasScope) {
+							const descStartInComment = value.indexOf(directiveInfo.description);
+							const linesBeforeDesc = value.slice(0, descStartInComment).split("\n").length - 1;
+							const actualLineIndex = linesBeforeDesc + descLineIndex;
+							if (actualLineIndex < lines.length) {
+								const actualLine = lines[actualLineIndex];
+								const tagIndex = actualLine.indexOf(lineTagInfo.tag);
+								if (tagIndex !== -1) {
+									const location = {
+										line: comment.loc.start.line + actualLineIndex,
+										column: actualLineIndex === 0 ? comment.loc.start.column + 2 + tagIndex : tagIndex
+									};
+									reportMissingScope(comment, lineTagInfo.tag, location);
+									break;
+								}
+							}
+						}
+					}
+				}
 				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 +548,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 +568,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 +594,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.5.0",
   "license": "MIT",
   "funding": "https://github.com/sponsors/kazupon",
   "bugs": {
@@ -47,47 +47,48 @@
     }
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "^0.50.2",
-    "@eslint/core": "^0.14.0"
+    "@es-joy/jsdoccomment": "^0.52.0",
+    "@eslint/core": "^0.15.1"
   },
   "peerDependencies": {
     "eslint": "^9.0.0"
   },
   "devDependencies": {
-    "@eslint/compat": "^1.2.9",
-    "@eslint/markdown": "^6.5.0",
-    "@kazupon/eslint-config": "^0.30.0",
+    "@eslint/compat": "^1.3.1",
+    "@eslint/markdown": "^7.0.0",
+    "@kazupon/eslint-config": "^0.32.0",
     "@kazupon/prettier-config": "^0.1.1",
-    "@shikijs/vitepress-twoslash": "^3.6.0",
-    "@types/node": "^22.15.30",
-    "@vitest/eslint-plugin": "^1.2.1",
-    "bumpp": "^10.1.1",
-    "eslint": "^9.28.0",
-    "eslint-config-prettier": "^10.1.5",
-    "eslint-import-resolver-typescript": "^4.4.3",
-    "eslint-plugin-import": "^2.31.0",
+    "@shikijs/vitepress-twoslash": "^3.8.1",
+    "@types/node": "^22.16.5",
+    "@vitest/eslint-plugin": "^1.3.4",
+    "bumpp": "^10.2.0",
+    "eslint": "^9.32.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
     "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.9.0",
+    "eslint-plugin-unicorn": "^60.0.0",
     "eslint-plugin-unused-imports": "^4.1.4",
     "eslint-plugin-yml": "^1.18.0",
     "eslint-vitest-rule-tester": "^2.2.0",
     "gh-changelogen": "^0.2.8",
-    "knip": "^5.60.2",
-    "lint-staged": "^16.0.0",
-    "pkg-pr-new": "^0.0.51",
-    "prettier": "^3.5.3",
+    "knip": "^5.62.0",
+    "lint-staged": "^16.1.2",
+    "pkg-pr-new": "^0.0.54",
+    "prettier": "^3.6.2",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.7",
-    "tsx": "^4.19.4",
-    "twoslash-eslint": "^0.3.1",
+    "tsdown": "^0.13.0",
+    "tsx": "^4.20.3",
+    "twoslash-eslint": "^0.3.3",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.33.1",
-    "vite-plugin-eslint4b": "^0.5.1",
+    "typescript-eslint": "^8.38.0",
+    "vite-plugin-eslint4b": "^0.6.0",
     "vitepress": "^1.6.3",
-    "vitepress-plugin-group-icons": "^1.6.0",
-    "vitest": "^3.2.2"
+    "vitepress-plugin-group-icons": "^1.6.1",
+    "vitest": "^3.2.4"
   },
   "prettier": "@kazupon/prettier-config",
   "lint-staged": {
@@ -117,11 +118,11 @@
     "fix": "pnpm run --stream --color \"/^fix:/\"",
     "fix:eslint": "eslint . --fix",
     "fix:knip": "knip --fix --no-exit-code",
-    "fix:prettier": "prettier . --write",
+    "fix:prettier": "prettier . --write --experimental-cli",
     "lint": "pnpm run --stream --color \"/^lint:/\"",
     "lint:eslint": "eslint .",
     "lint:knip": "knip",
-    "lint:prettier": "prettier . --check",
+    "lint:prettier": "prettier . --check --experimental-cli",
     "release": "bumpp --commit \"release: v%s\" --all --push --tag",
     "test": "vitest run",
     "typecheck": "pnpm run --stream --color \"/^typecheck:/\"",