@kazupon/eslint-plugin 0.2.2 → 0.4.0

package/README.md

@@ -61,9 +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  |         |     ⭐      |
+| 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

@@ -2,17 +2,19 @@ import { ESLint, Linter } from "eslint";
 
 //#region src/index.d.ts
 type PluginConfigs = {
-	recommended: Linter.Config<Linter.RulesRecord>[]
-	comment: Linter.Config<Linter.RulesRecord>[]
+  recommended: Linter.Config<Linter.RulesRecord>[];
+  comment: Linter.Config<Linter.RulesRecord>[];
 };
 declare const plugin: Omit<ESLint.Plugin, "configs"> & {
-	configs: PluginConfigs
+  configs: PluginConfigs;
 };
+declare const recommendedConfig: Linter.Config[];
 declare const commentConfig: Linter.Config[];
 declare const configs: {
-	recommended: typeof commentConfig
-	comment: typeof commentConfig
+  recommended: typeof recommendedConfig;
+  comment: typeof commentConfig;
 };
+/** @alias */
 
 //#endregion
 export { configs, plugin as default, plugin };

package/lib/index.js

@@ -1,15 +1,28 @@
 import { parseComment } from "@es-joy/jsdoccomment";
 
 //#region src/utils/constants.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* The plugin name.
+*/
 const name = "@kazupon/eslint-plugin";
-const version = "0.2.2";
+/**
+* The plugin version.
+*/
+const version = "0.4.0";
+/**
+* The namespace for rules
+*/
 const namespace = "@kazupon";
 
 //#endregion
 //#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$1 }) {
+	return function createNamedRule({ meta, name: name$1,...rule$3 }) {
 		const ruleId = namespace$1 ? `${namespace$1}/${name$1}` : name$1;
 		return {
 			meta: {
@@ -21,7 +34,7 @@ function RuleCreator(urlCreator, namespace$1 = "") {
 					ruleId
 				}
 			},
-			...rule$1
+			...rule$3
 		};
 	};
 }
@@ -40,7 +53,7 @@ function initializeTagDiagnosis(tags) {
 function validTagDiagnosis(tagDiagnosis) {
 	return Object.keys(tagDiagnosis).every((tag) => tagDiagnosis[tag] === "ok");
 }
-const rule = createRule({
+const rule$2 = createRule({
 	name: "enforce-header-comment",
 	meta: {
 		type: "suggestion",
@@ -168,11 +181,279 @@ const rule = createRule({
 		};
 	}
 });
-var enforce_header_comment_default = rule;
+var enforce_header_comment_default = rule$2;
+
+//#endregion
+//#region src/utils/comment.ts
+/**
+* Remove JSDoc asterisk prefix if present
+*/
+function stripJSDocPrefix(line) {
+	const trimmed = line.trim();
+	return trimmed.startsWith("*") ? trimmed.slice(1).trim() : trimmed;
+}
+/**
+* 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: true,
+			defaultSeverity: "warn"
+		},
+		messages: { tagComment: "Exist '{{tag}}' tag comment" },
+		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$1 };
+		const tags = options.tags || DEFAULT_TAGS$1;
+		const sourceCode = ctx.sourceCode;
+		/**
+		* Report a tag comment violation
+		*/
+		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 { 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;
+		/**
+		* 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") {
+				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");
+			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 && !tagInfo.hasScope) {
+					const location = calculateTagLocation(comment, line, i, tagInfo.tag);
+					if (location) {
+						reportMissingScope(comment, tagInfo.tag, location);
+						break;
+					}
+				}
+			}
+		}
+		return { Program() {
+			const comments = sourceCode.getAllComments();
+			for (const comment of comments) checkComment(comment);
+		} };
+	}
+});
+var prefer_scope_on_tag_comment_default = rule;
 
 //#endregion
 //#region src/rules/index.ts
-const rules = { "enforce-header-comment": enforce_header_comment_default };
+const rules = {
+	"enforce-header-comment": enforce_header_comment_default,
+	"no-tag-comments": no_tag_comments_default,
+	"prefer-scope-on-tag-comment": prefer_scope_on_tag_comment_default
+};
 
 //#endregion
 //#region src/index.ts
@@ -184,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}"],
@@ -193,17 +491,18 @@ const commentConfig = [{
 		"**/*.config.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"
 	],
 	plugins: { [namespace]: plugin },
-	rules: Object.entries(rules).reduce((rules$1, [ruleName, rule$1]) => {
-		const ruleId = rule$1.meta?.docs?.ruleId || (namespace ? `${namespace}/${ruleName}` : ruleName);
-		rules$1[ruleId] = rule$1.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;
+/** @alias */
 var src_default = plugin;
 
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kazupon/eslint-plugin",
   "description": "ESLint plugin for @kazupon",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "license": "MIT",
   "funding": "https://github.com/sponsors/kazupon",
   "bugs": {
@@ -47,46 +47,48 @@
     }
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "^0.50.0",
-    "@eslint/core": "^0.13.0"
+    "@es-joy/jsdoccomment": "^0.50.2",
+    "@eslint/core": "^0.14.0"
   },
   "peerDependencies": {
     "eslint": "^9.0.0"
   },
   "devDependencies": {
-    "@eslint/markdown": "^6.3.0",
-    "@kazupon/eslint-config": "^0.28.0",
+    "@eslint/compat": "^1.2.9",
+    "@eslint/markdown": "^6.5.0",
+    "@kazupon/eslint-config": "^0.31.0",
     "@kazupon/prettier-config": "^0.1.1",
-    "@shikijs/vitepress-twoslash": "^3.2.2",
-    "@types/node": "^22.14.1",
-    "@vitest/eslint-plugin": "^1.1.42",
-    "bumpp": "^10.1.0",
-    "eslint": "^9.24.0",
-    "eslint-config-prettier": "^10.1.2",
-    "eslint-import-resolver-typescript": "^4.3.2",
+    "@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",
-    "eslint-plugin-jsonc": "^2.20.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.8.0",
+    "eslint-plugin-unicorn": "^59.0.0",
     "eslint-plugin-unused-imports": "^4.1.4",
-    "eslint-plugin-yml": "^1.17.0",
+    "eslint-plugin-yml": "^1.18.0",
     "eslint-vitest-rule-tester": "^2.2.0",
     "gh-changelogen": "^0.2.8",
-    "knip": "^5.50.2",
-    "lint-staged": "^15.5.1",
-    "pkg-pr-new": "^0.0.42",
+    "knip": "^5.60.2",
+    "lint-staged": "^16.0.0",
+    "pkg-pr-new": "^0.0.51",
     "prettier": "^3.5.3",
-    "publint": "^0.3.11",
-    "tsdown": "^0.8.0-beta.2",
-    "tsx": "^4.19.3",
+    "publint": "^0.3.12",
+    "tsdown": "^0.12.7",
+    "tsx": "^4.19.4",
     "twoslash-eslint": "^0.3.1",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.29.1",
+    "typescript-eslint": "^8.33.1",
     "vite-plugin-eslint4b": "^0.5.1",
     "vitepress": "^1.6.3",
-    "vitepress-plugin-group-icons": "^1.4.1",
-    "vitest": "^3.1.1"
+    "vitepress-plugin-group-icons": "^1.6.0",
+    "vitest": "^3.2.2"
   },
   "prettier": "@kazupon/prettier-config",
   "lint-staged": {