eslint-plugin-tyrant 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# eslint-plugin-tyrant
+
+Pure TypeScript ESLint plugin with a rule that requires a TSDoc file comment at the top of each TypeScript module.
+
+## Rule
+
+- `tyrant/require-file-tsdoc`: require every `.ts`, `.tsx`, `.mts`, and `.cts` file to begin with a `/** ... */` TSDoc comment.
+- Accepted preamble before that TSDoc: UTF-8 BOM, a single shebang line, and optional empty lines after the shebang.
+- `tyrant/require-empty-line-after-file-tsdoc`: require at least one empty line after the top-level file TSDoc comment.
+- `tyrant/require-tsdoc-style-comments-before-exports`: if a comment block exists immediately before an export, every comment in that block must use `/** ... */` TSDoc style.
+- This rule is not auto-fixable. If a file does not need module-level docs, disable the rule in that file explicitly.
+
+## Usage
+
+```ts
+import tyrant from "eslint-plugin-tyrant";
+
+export default [
+  {
+    files: ["**/*.{ts,tsx,mts,cts}"],
+    plugins: { tyrant },
+    rules: {
+      "tyrant/require-file-tsdoc": "error"
+    }
+  }
+];
+```

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+export declare const rules: {
+    readonly "require-empty-line-after-file-tsdoc": import("eslint").Rule.RuleModule;
+    readonly "require-file-tsdoc": import("eslint").Rule.RuleModule;
+    readonly "require-tsdoc-style-comments-before-exports": import("eslint").Rule.RuleModule;
+};
+export declare const configs: {
+    recommended: {
+        files: string[];
+        plugins: {
+            tyrant: {
+                meta: {
+                    readonly name: "eslint-plugin-tyrant";
+                    readonly version: "0.1.0";
+                };
+                rules: {
+                    readonly "require-empty-line-after-file-tsdoc": import("eslint").Rule.RuleModule;
+                    readonly "require-file-tsdoc": import("eslint").Rule.RuleModule;
+                    readonly "require-tsdoc-style-comments-before-exports": import("eslint").Rule.RuleModule;
+                };
+            };
+        };
+        rules: {
+            "tyrant/require-empty-line-after-file-tsdoc": "error";
+            "tyrant/require-file-tsdoc": "error";
+            "tyrant/require-tsdoc-style-comments-before-exports": "error";
+        };
+    }[];
+    recommendedTypeScript: {
+        files: string[];
+        plugins: {
+            tyrant: {
+                meta: {
+                    readonly name: "eslint-plugin-tyrant";
+                    readonly version: "0.1.0";
+                };
+                rules: {
+                    readonly "require-empty-line-after-file-tsdoc": import("eslint").Rule.RuleModule;
+                    readonly "require-file-tsdoc": import("eslint").Rule.RuleModule;
+                    readonly "require-tsdoc-style-comments-before-exports": import("eslint").Rule.RuleModule;
+                };
+            };
+        };
+        rules: {
+            "tyrant/require-empty-line-after-file-tsdoc": "error";
+            "tyrant/require-file-tsdoc": "error";
+            "tyrant/require-tsdoc-style-comments-before-exports": "error";
+        };
+    }[];
+};
+declare const plugin: {
+    meta: {
+        readonly name: "eslint-plugin-tyrant";
+        readonly version: "0.1.0";
+    };
+    rules: {
+        readonly "require-empty-line-after-file-tsdoc": import("eslint").Rule.RuleModule;
+        readonly "require-file-tsdoc": import("eslint").Rule.RuleModule;
+        readonly "require-tsdoc-style-comments-before-exports": import("eslint").Rule.RuleModule;
+    };
+    configs: {
+        recommended: {
+            files: string[];
+            plugins: {
+                tyrant: {
+                    meta: {
+                        readonly name: "eslint-plugin-tyrant";
+                        readonly version: "0.1.0";
+                    };
+                    rules: {
+                        readonly "require-empty-line-after-file-tsdoc": import("eslint").Rule.RuleModule;
+                        readonly "require-file-tsdoc": import("eslint").Rule.RuleModule;
+                        readonly "require-tsdoc-style-comments-before-exports": import("eslint").Rule.RuleModule;
+                    };
+                };
+            };
+            rules: {
+                "tyrant/require-empty-line-after-file-tsdoc": "error";
+                "tyrant/require-file-tsdoc": "error";
+                "tyrant/require-tsdoc-style-comments-before-exports": "error";
+            };
+        }[];
+        recommendedTypeScript: {
+            files: string[];
+            plugins: {
+                tyrant: {
+                    meta: {
+                        readonly name: "eslint-plugin-tyrant";
+                        readonly version: "0.1.0";
+                    };
+                    rules: {
+                        readonly "require-empty-line-after-file-tsdoc": import("eslint").Rule.RuleModule;
+                        readonly "require-file-tsdoc": import("eslint").Rule.RuleModule;
+                        readonly "require-tsdoc-style-comments-before-exports": import("eslint").Rule.RuleModule;
+                    };
+                };
+            };
+            rules: {
+                "tyrant/require-empty-line-after-file-tsdoc": "error";
+                "tyrant/require-file-tsdoc": "error";
+                "tyrant/require-tsdoc-style-comments-before-exports": "error";
+            };
+        }[];
+    };
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,50 @@
+import { requireEmptyLineAfterFileTSDocRule } from "./rules/require-empty-line-after-file-tsdoc.js";
+import { requireFileTSDocRule } from "./rules/require-file-tsdoc.js";
+import { requireTSDocStyleCommentsBeforeExportsRule } from "./rules/require-tsdoc-style-comments-before-exports.js";
+export const rules = {
+    "require-empty-line-after-file-tsdoc": requireEmptyLineAfterFileTSDocRule,
+    "require-file-tsdoc": requireFileTSDocRule,
+    "require-tsdoc-style-comments-before-exports": requireTSDocStyleCommentsBeforeExportsRule
+};
+const pluginMeta = {
+    name: "eslint-plugin-tyrant",
+    version: "0.1.0"
+};
+const pluginObject = {
+    meta: pluginMeta,
+    rules
+};
+export const configs = {
+    recommended: [
+        {
+            files: ["**/*.{ts,tsx,mts,cts}"],
+            plugins: {
+                tyrant: pluginObject
+            },
+            rules: {
+                "tyrant/require-empty-line-after-file-tsdoc": "error",
+                "tyrant/require-file-tsdoc": "error",
+                "tyrant/require-tsdoc-style-comments-before-exports": "error"
+            }
+        }
+    ],
+    recommendedTypeScript: [
+        {
+            files: ["**/*.{ts,tsx,mts,cts}"],
+            plugins: {
+                tyrant: pluginObject
+            },
+            rules: {
+                "tyrant/require-empty-line-after-file-tsdoc": "error",
+                "tyrant/require-file-tsdoc": "error",
+                "tyrant/require-tsdoc-style-comments-before-exports": "error"
+            }
+        }
+    ]
+};
+const plugin = {
+    meta: pluginMeta,
+    rules,
+    configs
+};
+export default plugin;

package/dist/rules/file-tsdoc-utils.d.ts

@@ -0,0 +1,7 @@
+import type { SourceCode } from "eslint";
+export interface FileTSDocComment {
+    end: number;
+    start: number;
+}
+export declare function isTypeScriptFilename(filename: string): boolean;
+export declare function getTopLevelTSDocComment(sourceCode: Readonly<SourceCode>): FileTSDocComment | null;

package/dist/rules/file-tsdoc-utils.js

@@ -0,0 +1,33 @@
+const TS_FILE_PATTERN = /\.(?:[cm]?ts|tsx)$/i;
+export function isTypeScriptFilename(filename) {
+    return filename !== "<input>" && TS_FILE_PATTERN.test(filename);
+}
+function getFileBodyStart(text) {
+    let index = text.charCodeAt(0) === 0xfeff ? 1 : 0;
+    if (text.startsWith("#!", index)) {
+        const shebangEnd = text.indexOf("\n", index);
+        if (shebangEnd === -1) {
+            return text.length;
+        }
+        index = shebangEnd + 1;
+    }
+    while (index < text.length && text.slice(index, index + 1).trim() === "") {
+        index += 1;
+    }
+    return index;
+}
+export function getTopLevelTSDocComment(sourceCode) {
+    const text = sourceCode.getText();
+    const expectedStart = getFileBodyStart(text);
+    const firstComment = sourceCode
+        .getAllComments()
+        .find((comment) => comment.range?.[0] !== 0 || !text.startsWith("#!"));
+    const [start, end] = firstComment?.range ?? [];
+    if (!firstComment || start === undefined || end === undefined || start !== expectedStart) {
+        return null;
+    }
+    if (firstComment.type !== "Block" || !text.slice(start, end).startsWith("/**")) {
+        return null;
+    }
+    return { end, start };
+}

package/dist/rules/require-empty-line-after-file-tsdoc.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "eslint";
+export declare const requireEmptyLineAfterFileTSDocRule: Rule.RuleModule;

package/dist/rules/require-empty-line-after-file-tsdoc.js

@@ -0,0 +1,37 @@
+import { getTopLevelTSDocComment, isTypeScriptFilename } from "./file-tsdoc-utils.js";
+const MESSAGE_ID = "missingEmptyLineAfterFileTSDoc";
+export const requireEmptyLineAfterFileTSDocRule = {
+    meta: {
+        type: "layout",
+        docs: {
+            description: "Require an empty line after the top-level file TSDoc comment."
+        },
+        hasSuggestions: false,
+        schema: [],
+        messages: {
+            [MESSAGE_ID]: "There should be at least one empty line after the top-level file TSDoc comment."
+        }
+    },
+    create(context) {
+        if (!isTypeScriptFilename(context.filename)) {
+            return {};
+        }
+        return {
+            Program(node) {
+                const fileTSDocComment = getTopLevelTSDocComment(context.sourceCode);
+                if (!fileTSDocComment) {
+                    return;
+                }
+                const textAfterComment = context.sourceCode.getText().slice(fileTSDocComment.end);
+                if (textAfterComment.startsWith("\n\n") || textAfterComment.startsWith("\r\n\r\n")) {
+                    return;
+                }
+                context.report({
+                    node,
+                    loc: context.sourceCode.getLocFromIndex(fileTSDocComment.end),
+                    messageId: MESSAGE_ID
+                });
+            }
+        };
+    }
+};

package/dist/rules/require-file-tsdoc.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "eslint";
+export declare const requireFileTSDocRule: Rule.RuleModule;

package/dist/rules/require-file-tsdoc.js

@@ -0,0 +1,33 @@
+import { getTopLevelTSDocComment, isTypeScriptFilename } from "./file-tsdoc-utils.js";
+const MESSAGE_ID = "missingFileTSDoc";
+export const requireFileTSDocRule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Require a TSDoc block comment at the start of every TypeScript file."
+        },
+        hasSuggestions: false,
+        schema: [],
+        messages: {
+            [MESSAGE_ID]: "Missing a top-level /** ... */ TSDoc block as a file comment. You can disable this rule in the file if it is not necessary."
+        }
+    },
+    create(context) {
+        const filename = context.filename;
+        if (!isTypeScriptFilename(filename)) {
+            return {};
+        }
+        return {
+            Program(node) {
+                if (getTopLevelTSDocComment(context.sourceCode)) {
+                    return;
+                }
+                context.report({
+                    node,
+                    loc: { line: 1, column: 0 },
+                    messageId: MESSAGE_ID
+                });
+            }
+        };
+    }
+};

package/dist/rules/require-tsdoc-style-comments-before-exports.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "eslint";
+export declare const requireTSDocStyleCommentsBeforeExportsRule: Rule.RuleModule;

package/dist/rules/require-tsdoc-style-comments-before-exports.js

@@ -0,0 +1,92 @@
+import { isTypeScriptFilename } from "./file-tsdoc-utils.js";
+const MESSAGE_ID = "nonTSDocCommentBeforeExport";
+function hasOnlyWhitespaceBetween(sourceCode, start, end) {
+    return sourceCode.getText().slice(start, end).trim() === "";
+}
+function getLeadingCommentBlock(sourceCode, node) {
+    if (!node.range) {
+        return [];
+    }
+    const comments = sourceCode.getCommentsBefore(node);
+    if (comments.length === 0) {
+        return [];
+    }
+    const relevantComments = [];
+    let nextStart = node.range[0];
+    for (let index = comments.length - 1; index >= 0; index -= 1) {
+        const comment = comments[index];
+        const [start, end] = comment.range ?? [];
+        if (start === undefined || end === undefined) {
+            continue;
+        }
+        if (!hasOnlyWhitespaceBetween(sourceCode, end, nextStart)) {
+            break;
+        }
+        relevantComments.unshift(comment);
+        nextStart = start;
+    }
+    return relevantComments;
+}
+function isTSDocStyleComment(sourceCode, comment) {
+    const [start, end] = comment.range ?? [];
+    if (start === undefined || end === undefined) {
+        return false;
+    }
+    if (comment.type !== "Block") {
+        return false;
+    }
+    return sourceCode.getText().slice(start, end).startsWith("/**");
+}
+export const requireTSDocStyleCommentsBeforeExportsRule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Require existing comments before exports to use TSDoc block comment style."
+        },
+        hasSuggestions: false,
+        schema: [],
+        messages: {
+            [MESSAGE_ID]: "Comments immediately before exported declarations must use TSDoc /** ... */ style."
+        }
+    },
+    create(context) {
+        if (!isTypeScriptFilename(context.filename)) {
+            return {};
+        }
+        return {
+            ExportAllDeclaration(node) {
+                for (const comment of getLeadingCommentBlock(context.sourceCode, node)) {
+                    if (isTSDocStyleComment(context.sourceCode, comment)) {
+                        continue;
+                    }
+                    context.report({
+                        messageId: MESSAGE_ID,
+                        node
+                    });
+                }
+            },
+            ExportDefaultDeclaration(node) {
+                for (const comment of getLeadingCommentBlock(context.sourceCode, node)) {
+                    if (isTSDocStyleComment(context.sourceCode, comment)) {
+                        continue;
+                    }
+                    context.report({
+                        messageId: MESSAGE_ID,
+                        node
+                    });
+                }
+            },
+            ExportNamedDeclaration(node) {
+                for (const comment of getLeadingCommentBlock(context.sourceCode, node)) {
+                    if (isTSDocStyleComment(context.sourceCode, comment)) {
+                        continue;
+                    }
+                    context.report({
+                        messageId: MESSAGE_ID,
+                        node
+                    });
+                }
+            }
+        };
+    }
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "eslint-plugin-tyrant",
+  "version": "0.1.0",
+  "description": "ESLint plugin with TypeScript-focused rules.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "format": "prettier --check .",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "node --import tsx --test tests/**/*.test.ts"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "typescript",
+    "tsdoc"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@types/node": "^24.5.2",
+    "@typescript-eslint/parser": "^8.43.0",
+    "eslint": "^9.35.0",
+    "eslint-plugin-tsdoc": "^0.4.0",
+    "globals": "^16.4.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.6.2",
+    "prettier-plugin-package": "^2.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.43.0"
+  }
+}