@kazupon/eslint-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @kazupon/eslint-plugin
+
+ESLint plugin for @kazupon
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!WARNING]
+> This eslint-plugin is a rule that I’ve made as I needed it to advance the open-source project.
+> Therefore, updates are often made, and sometimes there are also destructive changes.
+> This eslint-plugin is open-source, so you can use it for your own projects, but please keep in mind that this plugin is specialized for my own use.
+> Of course, since it is open-source, you are free to fork it and use it yourself 😉.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save-dev @kazupon/eslint-plugin
+
+## yarn
+yarn add -D @kazupon/eslint-plugin
+
+## pnpm
+pnpm add -D @kazupon/eslint-plugin
+
+## bum
+bun add -D @kazupon/eslint-plugin
+```
+
+## 📋 Requirements
+
+- **ESLint**: v9 or later
+- **Configuration**: flat config style `eslint.config.[js|ts]`, not support legacy config style `.eslintrc`
+- **Node.js**: v20 or later
+
+## 🚀 Usage
+
+Example `eslint.config.js`:
+
+```js
+import { defineConfig } from 'eslint/config'
+import kazupon from '@kazupon/eslint-plugin'
+
+export default defineConfig(
+  ...kazupon.configs.recommended,
+  {
+    // ...
+  }
+  // ... something other configurations
+)
+```
+
+## ✅ Rules
+
+The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) automatically fixes problems reported by rules which have a wrench 🔧 below.
+The rules with the following star ⭐ are included in the configs.
+
+<!--RULES_TABLE_START-->
+
+### @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  |         |     ⭐      |
+
+<!--RULES_TABLE_END-->
+
+## 🙌 Contributing guidelines
+
+If you are interested in contributing to `gunshi`, I highly recommend checking out [the contributing guidelines](/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](/CONTRIBUTING.md#development-setup)) etc., there.
+
+## 💖 Credits
+
+This project is inspired by:
+
+- `README.md` and `docs/**/*.md`, inspired by [ota-meshi](https://github.com/ota-meshi)
+
+Thank you!
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+import { ESLint } from "eslint";
+
+//#region lib/.tsdown-types-es/index.d.ts
+/** @alias */
+declare const plugin: ESLint.Plugin;
+/** @alias */
+declare const configs: ESLint.Plugin["configs"];
+
+//#endregion
+export { configs, plugin as default, plugin };

package/lib/index.js

@@ -0,0 +1,215 @@
+import { parseComment } from "@es-joy/jsdoccomment";
+import fs from "node:fs";
+
+//#region src/utils/package.ts
+function readPackageJson(path) {
+	return JSON.parse(fs.readFileSync(path, "utf8"));
+}
+
+//#endregion
+//#region src/utils/meta.ts
+const pkg = readPackageJson(new URL("../../package.json", import.meta.url));
+const name = pkg.name;
+const version = pkg.version;
+const namespace = pkg.name.split("/")[0];
+
+//#endregion
+//#region src/utils/rule.ts
+const blobUrl = "https://github.com/kazupon/eslint-plugin/tree/main/src/rules";
+/**
+* Creates reusable function to create rules with default options and docs URLs.
+*
+* @param urlCreator Creates a documentation URL for a given rule name.
+* @returns Function to create a rule with the docs URL format.
+*/
+function RuleCreator(urlCreator, namespace$1 = "") {
+	return function createNamedRule({ meta, name: name$1,...rule$1 }) {
+		const ruleId = namespace$1 ? `${namespace$1}/${name$1}` : name$1;
+		return _createRule({
+			meta: {
+				...meta,
+				docs: {
+					...meta.docs,
+					url: urlCreator(name$1),
+					ruleId,
+					ruleName: name$1
+				}
+			},
+			...rule$1
+		});
+	};
+}
+function _createRule({ create, defaultOptions, meta }) {
+	return {
+		create: (context) => {
+			const optionsWithDefault = context.options.map((options, index) => {
+				return {
+					...defaultOptions[index],
+					...options
+				};
+			});
+			return create(context, optionsWithDefault);
+		},
+		defaultOptions,
+		meta
+	};
+}
+const createRule = RuleCreator((ruleName) => {
+	return `${blobUrl}/${ruleName}.ts`;
+}, namespace);
+
+//#endregion
+//#region src/rules/enforce-header-comment.ts
+const ENFORCED_TAGS = ["author", "license"];
+function initializeTagDiagnosis(tags) {
+	const tagDiagnosis = {};
+	for (const tag of tags) tagDiagnosis[tag] = "require";
+	return tagDiagnosis;
+}
+function validTagDiagnosis(tagDiagnosis) {
+	return Object.keys(tagDiagnosis).every((tag) => tagDiagnosis[tag] === "ok");
+}
+const rule = createRule({
+	name: "enforce-header-comment",
+	meta: {
+		type: "suggestion",
+		hasSuggestions: true,
+		docs: {
+			description: "Enforce heading the comment in source code file",
+			category: "Comment",
+			recommended: true,
+			defaultSeverity: "error"
+		},
+		messages: {
+			headerCommentEnforce: "Header comment is enforced",
+			headerCommentNeedTag: "Header comment need `@{{tag}}` tag",
+			headerCommentNeedTagValue: "Header `@{{tag}}` tag need a value"
+		},
+		schema: []
+	},
+	defaultOptions: [{}],
+	create(ctx) {
+		/**
+		* Report the tag diagnosis
+		* @param comment - A target comment node
+		* @param tags - A list of tags to check
+		* @param tagDiagnosis - A map of tag diagnosis
+		* @returns true if the comment has all required tags, false otherwise
+		*/
+		function reportTagDiagnosis(comment, tags, tagDiagnosis) {
+			let reported = false;
+			for (const tag of tags) {
+				if (tagDiagnosis[tag] === "ok") continue;
+				ctx.report({
+					loc: comment.loc,
+					messageId: tagDiagnosis[tag] === "require" ? "headerCommentNeedTag" : "headerCommentNeedTagValue",
+					data: { tag }
+				});
+				reported = true;
+			}
+			return reported;
+		}
+		/**
+		* The target comments, which is able to lint
+		*/
+		let taregetComments = [];
+		return {
+			Program: (node) => {
+				taregetComments.length = 0;
+				const hasCommentOnly = node.body.length === 0;
+				const start = hasCommentOnly ? node.range[1] : node.range[0];
+				const comments = ctx.sourceCode.getAllComments().filter((comment) => comment.range[1] <= start).filter((comment) => comment.type === "Block").filter((comment) => comment.value.startsWith("*"));
+				if (comments.length === 0) {
+					taregetComments = [];
+					return;
+				}
+				if (hasCommentOnly) taregetComments = comments;
+				else {
+					const lastComment = comments.at(-1);
+					const firstNode = node.body[0];
+					const distance = Math.abs(lastComment.range[1] - firstNode.range[0]);
+					taregetComments = distance > 1 ? comments : comments.slice(0, -1);
+				}
+			},
+			"Program:exit": (node) => {
+				const comments = taregetComments;
+				if (comments.length === 0) {
+					const topLoc = {
+						start: {
+							line: node.loc.start.line - 1,
+							column: node.loc.start.column
+						},
+						end: {
+							line: node.loc.end.line - 1,
+							column: node.loc.end.column
+						}
+					};
+					ctx.report({
+						loc: topLoc,
+						messageId: "headerCommentEnforce"
+					});
+					ctx.report({
+						loc: topLoc,
+						messageId: "headerCommentNeedTag",
+						data: { tag: "author" }
+					});
+					ctx.report({
+						loc: topLoc,
+						messageId: "headerCommentNeedTag",
+						data: { tag: "license" }
+					});
+					return;
+				}
+				const commentWithAstNodes = comments.map((comment) => ({
+					comment,
+					ast: parseComment(comment)
+				}));
+				let reported = false;
+				for (const { comment, ast } of commentWithAstNodes) {
+					if (reported) break;
+					const found = ast.tags.some((tag) => ENFORCED_TAGS.includes(tag.tag));
+					if (ast.tags.length > 0 && !found) continue;
+					const tagDiagnosis = initializeTagDiagnosis(ENFORCED_TAGS);
+					for (const tag of ast.tags) if (tagDiagnosis[tag.tag]) tagDiagnosis[tag.tag] = tag.description ? "ok" : "enforce";
+					if (validTagDiagnosis(tagDiagnosis)) break;
+					reported = reportTagDiagnosis(comment, ENFORCED_TAGS, tagDiagnosis);
+				}
+			}
+		};
+	}
+});
+var enforce_header_comment_default = rule;
+
+//#endregion
+//#region src/rules/index.ts
+const rules = { "enforce-header-comment": enforce_header_comment_default };
+
+//#endregion
+//#region src/index.ts
+const plugin = {
+	meta: {
+		name,
+		version
+	},
+	rules
+};
+const commentConfig = [{
+	name: "@kazupon/eslint-plugin/comment",
+	files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
+	ignores: ["**/*.md", "**/*.md/**/*.{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";
+		return rules$1;
+	}, Object.create(null))
+}];
+const configs = {
+	recommended: [...commentConfig],
+	comment: commentConfig
+};
+plugin.configs = configs;
+var src_default = plugin;
+
+//#endregion
+export { configs, src_default as default, plugin };

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@kazupon/eslint-plugin",
+  "description": "ESLint plugin for @kazupon",
+  "version": "0.1.0",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/eslint-plugin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/eslint-plugin.git"
+  },
+  "keywords": [
+    "eslint",
+    "plugin",
+    "lint"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@es-joy/jsdoccomment": "^0.50.0"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0",
+    "typescript-eslint": "^8.29.1"
+  },
+  "devDependencies": {
+    "@eslint/markdown": "^6.3.0",
+    "@kazupon/eslint-config": "^0.27.0",
+    "@kazupon/prettier-config": "^0.1.1",
+    "@shikijs/vitepress-twoslash": "^3.2.2",
+    "@types/node": "^22.14.1",
+    "@typescript-eslint/utils": "^8.29.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",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsonc": "^2.20.0",
+    "eslint-plugin-module-interop": "^0.3.1",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-unicorn": "^58.0.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "eslint-plugin-yml": "^1.17.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",
+    "prettier": "^3.5.3",
+    "publint": "^0.3.11",
+    "tsdown": "^0.7.5",
+    "tsx": "^4.19.3",
+    "twoslash-eslint": "^0.3.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.1",
+    "vite-plugin-eslint4b": "^0.5.1",
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-group-icons": "^1.4.1",
+    "vitest": "^3.1.1"
+  },
+  "prettier": "@kazupon/prettier-config",
+  "lint-staged": {
+    "*.ts?(x)": [
+      "prettier --parser=typescript --write",
+      "eslint --fix"
+    ],
+    "*.{js,mjs,cjs}": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "*.{json,jsonc,json5,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "changelog": "gh-changelogen --repo=kazupon/eslint-plugin",
+    "clean": "git clean -df",
+    "dev": "pnpx @eslint/config-inspector --config eslint.config.ts",
+    "dev:eslint": "pnpx @eslint/config-inspector --config eslint.config.ts",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:readme": "tsx scripts/update-readme.ts",
+    "docs:rules": "tsx scripts/update-docs.ts",
+    "fix": "pnpm run --stream --color \"/^fix:/\"",
+    "fix:eslint": "eslint . --fix",
+    "fix:knip": "knip --fix --no-exit-code",
+    "fix:prettier": "prettier . --write",
+    "lint": "pnpm run --stream --color \"/^lint:/\"",
+    "lint:eslint": "eslint .",
+    "lint:knip": "knip",
+    "lint:prettier": "prettier . --check",
+    "release": "bumpp --commit \"release: v%s\" --all --push --tag",
+    "test": "vitest run",
+    "typecheck": "pnpm run --stream --color \"/^typecheck:/\"",
+    "typecheck:tsc": "tsc --noEmit"
+  }
+}