eslint-plugin-comment-policy 0.1.0

package/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md — adopting eslint-plugin-comment-policy
+
+Five ESLint 9 (flat-config) rules enforcing a comment policy, namespace
+`comment-policy/`:
+
+- `comment-policy/max-comment-lines` — prose-line cap per comment block
+  (default `max` 4, `anchoredMax` 3).
+- `comment-policy/no-comment-narrative` — change-narrative / history prose.
+- `comment-policy/no-comment-code-snippet` — code snippet inside a comment.
+- `comment-policy/no-decorative-comment` — decorative / section markers.
+- `comment-policy/no-line-comment` — `//` forbidden, `/* */` required.
+
+## Adopt in a repo
+
+1. `npm install --save-dev eslint-plugin-comment-policy`.
+2. In `eslint.config.mjs`, use a bundled config or register rules explicitly:
+
+   ```js
+   import commentPolicy from "eslint-plugin-comment-policy";
+   export default [commentPolicy.configs.recommended];
+   ```
+
+   `recommended` turns **all five rules on at `error`** with defaults. `sdd`
+   adds default `protectedPatterns` for spec-driven projects.
+
+## Rule behavior an agent must know
+
+- A **comment block** is a run of consecutive full-line `//` separated only by
+  whitespace (no blank line); they are linted and fixed as one unit.
+- **Protected** blocks (matching `protectedPatterns`) get the lower cap in
+  `max-comment-lines` and are exempt from narrative / snippet / decorative
+  checks. Marker/anchor-only lines never count as prose.
+- Fixable: `no-comment-code-snippet` (delete only when the block is entirely
+  code), `no-decorative-comment` (drop the line), `no-line-comment` (convert and
+  merge `//` into one `/* */`; skipped when the prose contains `*/`).
+  `max-comment-lines` and `no-comment-narrative` are judgment calls, so no fix.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyberash
+
+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,126 @@
+# eslint-plugin-comment-policy
+
+[Русская версия](./README.ru.md)
+
+ESLint 9 (flat-config) rules that enforce a **comment policy** in the editor and
+in CI: cap prose, keep change-history out of comments, ban code snippets and
+decorative markers, and require block comments. The policy shows up as you type
+instead of only on a separate review pass.
+
+Namespace: `comment-policy/`. Plugin scope (`meta.name`): `cyberash`.
+
+## Rules
+
+| Rule | What it flags | Fixable |
+|---|---|---|
+| `comment-policy/max-comment-lines` | a comment block with more prose lines than the cap (lower cap for anchored blocks) | no |
+| `comment-policy/no-comment-narrative` | change-narrative / history prose (`renamed from`, `previously`, `v1.2`, bare ISO dates, …) | no |
+| `comment-policy/no-comment-code-snippet` | a code snippet (usage example) inside a comment | yes (only when the block is entirely code) |
+| `comment-policy/no-decorative-comment` | decorative / section markers (`=====`, `#region`, `===text===`) | yes |
+| `comment-policy/no-line-comment` | any `//` comment; requires `/* */` | yes (converts and merges runs of `//`) |
+
+A **comment block** is a run of consecutive full-line `//` comments separated
+only by whitespace (no blank line). A **prose line** is a comment line that
+still has a real word (≥3 letters) after comment markers and protected markers
+are stripped, so anchor/marker-only lines do not count toward the cap.
+
+## Install
+
+```sh
+npm install --save-dev eslint-plugin-comment-policy
+```
+
+## Usage
+
+`eslint.config.mjs` — bundled config:
+
+```js
+import commentPolicy from "eslint-plugin-comment-policy";
+
+export default [commentPolicy.configs.recommended];
+```
+
+`recommended` turns all five rules on at `error` with defaults. There is also an
+`sdd` config that ships default `protectedPatterns` for spec-driven projects
+(anchors `partition:TYPE-NNN`, `@covers`, short ids, milestones):
+
+```js
+import commentPolicy from "eslint-plugin-comment-policy";
+
+export default [commentPolicy.configs.sdd];
+```
+
+Or register the plugin and enable rules explicitly:
+
+```js
+import commentPolicy from "eslint-plugin-comment-policy";
+
+export default [
+	{
+		plugins: { "comment-policy": commentPolicy },
+		rules: {
+			"comment-policy/max-comment-lines": ["error", { max: 4, anchoredMax: 3 }],
+			"comment-policy/no-comment-narrative": "error",
+			"comment-policy/no-comment-code-snippet": "error",
+			"comment-policy/no-decorative-comment": "error",
+			"comment-policy/no-line-comment": "error",
+		},
+	},
+];
+```
+
+## Options
+
+### `protectedPatterns`
+
+Shared across `max-comment-lines`, `no-comment-narrative`,
+`no-comment-code-snippet`, `no-decorative-comment`, and `no-line-comment`. An
+array of regular-expression **source strings**. A block that matches any pattern
+is "protected": it gets the lower cap in `max-comment-lines` and is exempt from
+`no-comment-narrative` / `no-comment-code-snippet` / `no-decorative-comment`.
+
+Order matters: put the longer/more specific pattern first so a marker is fully
+stripped before a shorter pattern that is its suffix.
+
+### `max-comment-lines`
+
+```js
+["error", { max: 4, anchoredMax: 3, protectedPatterns: [] }]
+```
+
+- `max` (default `4`) — prose-line cap for an ordinary block.
+- `anchoredMax` (default `3`) — prose-line cap for a protected (anchored) block.
+
+### `no-comment-narrative`
+
+```js
+["error", { protectedPatterns: [], extraPatterns: [] }]
+```
+
+- `extraPatterns` — extra narrative patterns (source strings) added to the
+  built-in set.
+
+### `no-comment-code-snippet`, `no-decorative-comment`, `no-line-comment`
+
+```js
+["error", { protectedPatterns: [] }]
+```
+
+`no-comment-code-snippet` auto-deletes a block only when it is entirely code
+(every non-empty line is code-ish) and occupies whole lines. `no-line-comment`
+converts a run of `//` into one `/* */` block; it leaves a comment untouched
+when its prose contains `*/` (which would terminate the block early).
+
+## Notes
+
+- `no-decorative-comment` detects markers by content in both `//` and `/* */`
+  comment forms.
+- ESLint applies non-overlapping fixes per pass and re-lints, so a block that is
+  both a code snippet and a line comment is resolved across passes.
+
+## Develop
+
+- `npm run build` — tsdown, dual ESM + CJS + `.d.ts` into `dist/` (git-ignored).
+- `npm test` — `RuleTester` suites via `tsx` (no build needed).
+- `npm run typecheck` — `tsc --noEmit`.
+- `npm run lint` — dogfoods `typescript-eslint` on the source.

package/README.ru.md

@@ -0,0 +1,128 @@
+# eslint-plugin-comment-policy
+
+[English version](./README.md)
+
+Правила ESLint 9 (flat-config), которые применяют **политику комментариев** в
+редакторе и в CI: ограничивают прозу, не пускают историю изменений в
+комментарии, запрещают код-сниппеты и декоративные маркеры, требуют блочные
+комментарии. Политика видна по мере набора, а не только при отдельном прогоне.
+
+Неймспейс: `comment-policy/`. Scope плагина (`meta.name`): `cyberash`.
+
+## Правила
+
+| Правило | Что ловит | Автофикс |
+|---|---|---|
+| `comment-policy/max-comment-lines` | блок комментария, где прозаических строк больше капа (для анкорных блоков кап ниже) | нет |
+| `comment-policy/no-comment-narrative` | change-narrative / историю (`renamed from`, `previously`, `v1.2`, голые ISO-даты, …) | нет |
+| `comment-policy/no-comment-code-snippet` | код-сниппет (пример использования) внутри комментария | да (только если блок целиком код) |
+| `comment-policy/no-decorative-comment` | декоративные / секционные маркеры (`=====`, `#region`, `===text===`) | да |
+| `comment-policy/no-line-comment` | любой `//`; требует `/* */` | да (конвертация и склейка подряд идущих `//`) |
+
+**Блок комментария** — подряд идущие full-line `//`, разделённые только
+пробелами (без пустой строки). **Прозаическая строка** — строка комментария, в
+которой после снятия маркеров комментария и protected-маркеров остаётся реальное
+слово (≥3 букв); поэтому чисто анкорные/маркерные строки в кап не идут.
+
+## Установка
+
+```sh
+npm install --save-dev eslint-plugin-comment-policy
+```
+
+## Использование
+
+`eslint.config.mjs` — готовый конфиг:
+
+```js
+import commentPolicy from "eslint-plugin-comment-policy";
+
+export default [commentPolicy.configs.recommended];
+```
+
+`recommended` включает все пять правил на `error` с дефолтами. Есть также конфиг
+`sdd` с дефолтными `protectedPatterns` для spec-driven проектов (анкоры
+`partition:TYPE-NNN`, `@covers`, short-id, milestone):
+
+```js
+import commentPolicy from "eslint-plugin-comment-policy";
+
+export default [commentPolicy.configs.sdd];
+```
+
+Либо подключить плагин и включить правила вручную:
+
+```js
+import commentPolicy from "eslint-plugin-comment-policy";
+
+export default [
+	{
+		plugins: { "comment-policy": commentPolicy },
+		rules: {
+			"comment-policy/max-comment-lines": ["error", { max: 4, anchoredMax: 3 }],
+			"comment-policy/no-comment-narrative": "error",
+			"comment-policy/no-comment-code-snippet": "error",
+			"comment-policy/no-decorative-comment": "error",
+			"comment-policy/no-line-comment": "error",
+		},
+	},
+];
+```
+
+## Опции
+
+### `protectedPatterns`
+
+Общая для `max-comment-lines`, `no-comment-narrative`,
+`no-comment-code-snippet`, `no-decorative-comment` и `no-line-comment`. Массив
+**строк-исходников** регулярных выражений. Блок, совпавший с любым паттерном,
+считается «защищённым»: получает пониженный кап в `max-comment-lines` и
+исключается из `no-comment-narrative` / `no-comment-code-snippet` /
+`no-decorative-comment`.
+
+Порядок важен: более длинный/специфичный паттерн ставьте раньше, чтобы маркер
+снимался целиком до более короткого паттерна, который является его суффиксом.
+
+### `max-comment-lines`
+
+```js
+["error", { max: 4, anchoredMax: 3, protectedPatterns: [] }]
+```
+
+- `max` (деф. `4`) — кап прозаических строк для обычного блока.
+- `anchoredMax` (деф. `3`) — кап для защищённого (анкорного) блока.
+
+### `no-comment-narrative`
+
+```js
+["error", { protectedPatterns: [], extraPatterns: [] }]
+```
+
+- `extraPatterns` — дополнительные narrative-паттерны (строки-исходники) к
+  встроенному набору.
+
+### `no-comment-code-snippet`, `no-decorative-comment`, `no-line-comment`
+
+```js
+["error", { protectedPatterns: [] }]
+```
+
+`no-comment-code-snippet` удаляет блок автофиксом только если он целиком код
+(каждая непустая строка код-подобна) и занимает целые строки. `no-line-comment`
+конвертирует подряд идущие `//` в один блок `/* */`; комментарий остаётся
+нетронутым, если его проза содержит `*/` (это преждевременно закрыло бы блок).
+
+## Замечания
+
+- `no-decorative-comment` детектит маркеры по содержимому в обеих формах
+  (`//` и `/* */`).
+- ESLint применяет непересекающиеся фиксы за проход и перезапускает линт, поэтому
+  блок, который одновременно код-сниппет и line-комментарий, разрешается за
+  несколько проходов.
+
+## Разработка
+
+- `npm run build` — tsdown, dual ESM + CJS + `.d.ts` в `dist/` (в gitignore).
+- `npm test` — наборы `RuleTester` через `tsx` (сборка не нужна).
+- `npm run typecheck` — `tsc --noEmit`.
+- `npm run lint` — self-lint `typescript-eslint` по исходникам.

package/dist/index.cjs

@@ -0,0 +1,446 @@
+//#region src/lib/protected.ts
+function compileProtected(patterns) {
+	return {
+		detect: patterns.map((source) => new RegExp(source)),
+		strip: patterns.map((source) => new RegExp(source, "g"))
+	};
+}
+function hasProtectedToken(text, detect) {
+	return detect.some((re) => re.test(text));
+}
+function strippedLine(rawLine) {
+	return rawLine.replace(/^\s*\/\//, "").replace(/^\s*\/\*+/, "").replace(/\*+\/\s*$/, "").replace(/^\s*\*/, "").trim();
+}
+function isProseLine(rawLine, strip) {
+	let content = strippedLine(rawLine);
+	for (const re of strip) content = content.replace(re, " ");
+	return /[A-Za-z]{3,}/.test(content);
+}
+//#endregion
+//#region src/lib/comment-blocks.ts
+function lineStarts(text) {
+	const starts = [0];
+	for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) starts.push(i + 1);
+	return starts;
+}
+function makeLineIndex(text) {
+	const starts = lineStarts(text);
+	return {
+		lineStart: (lineNo) => starts[lineNo - 1],
+		lineEnd: (lineNo) => lineNo < starts.length ? starts[lineNo] : text.length
+	};
+}
+function onlyWhitespaceNoBlank(between) {
+	return /^[ \t]*\r?\n[ \t]*$/.test(between);
+}
+function commentBlocks(sourceCode, detect) {
+	const text = sourceCode.text;
+	const isFullLine = (c) => {
+		const lineText = sourceCode.lines[c.loc.start.line - 1] ?? "";
+		return /^\s*$/.test(lineText.slice(0, c.loc.start.column));
+	};
+	const blocks = [];
+	let cur = null;
+	for (const c of sourceCode.getAllComments()) {
+		const kind = c.type === "Line" ? "line" : "block";
+		const fullLine = isFullLine(c);
+		if (cur !== null && cur.kind === "line" && kind === "line" && cur.fullLine && fullLine && onlyWhitespaceNoBlank(text.slice(cur.end, c.range[0])) && cur) {
+			cur.end = c.range[1];
+			cur.comments.push(c);
+			continue;
+		}
+		if (cur) blocks.push(finalize(cur, text, detect));
+		cur = {
+			kind,
+			start: c.range[0],
+			end: c.range[1],
+			fullLine,
+			comments: [c]
+		};
+	}
+	if (cur) blocks.push(finalize(cur, text, detect));
+	return blocks;
+}
+function finalize(b, text, detect) {
+	const raw = text.slice(b.start, b.end);
+	const startLine = b.comments[0].loc.start.line;
+	const endLine = b.comments[b.comments.length - 1].loc.end.line;
+	return {
+		kind: b.kind,
+		start: b.start,
+		end: b.end,
+		fullLine: b.fullLine,
+		raw,
+		startLine,
+		endLine,
+		lineCount: endLine - startLine + 1,
+		hasProtected: hasProtectedToken(raw, detect),
+		comments: b.comments
+	};
+}
+function blockLoc(block) {
+	return {
+		start: block.comments[0].loc.start,
+		end: block.comments[block.comments.length - 1].loc.end
+	};
+}
+//#endregion
+//#region src/rules/max-comment-lines.ts
+const DEFAULT_MAX = 4;
+const DEFAULT_ANCHORED_MAX = 3;
+const rule$4 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Cap the number of prose lines in a comment block (anchored blocks get a lower cap).",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#max-comment-lines"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				max: {
+					type: "integer",
+					minimum: 0
+				},
+				anchoredMax: {
+					type: "integer",
+					minimum: 0
+				},
+				protectedPatterns: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		messages: {
+			tooManyProse: "comment block has {{count}} prose lines (> {{max}}); keep it to a short why or move it into a spec record",
+			tooManyProseAnchored: "anchored comment has {{count}} prose lines (> {{max}}); the rationale belongs in the spec record — keep the marker plus at most a one-line pointer"
+		}
+	},
+	create(context) {
+		const option = context.options[0] ?? {};
+		const max = option.max ?? DEFAULT_MAX;
+		const anchoredMax = option.anchoredMax ?? DEFAULT_ANCHORED_MAX;
+		const { detect, strip } = compileProtected(option.protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				const proseLineCount = block.raw.split("\n").filter((line) => isProseLine(line, strip)).length;
+				const cap = block.hasProtected ? anchoredMax : max;
+				if (proseLineCount > cap) context.report({
+					loc: blockLoc(block),
+					messageId: block.hasProtected ? "tooManyProseAnchored" : "tooManyProse",
+					data: {
+						count: proseLineCount,
+						max: cap
+					}
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-comment-code-snippet.ts
+const CODEISH = [
+	/^(?:import|export|const|let|var|function|class|return|await|async|if|for|while|switch)\b/,
+	/=>/,
+	/^[\w.$]+\([^)]*\)\s*;?$/,
+	/^[}{]/,
+	/;\s*$/
+];
+function isCodeish(content) {
+	return content.length > 0 && CODEISH.some((re) => re.test(content));
+}
+function snippetInfo(block) {
+	if (block.hasProtected) return {
+		isSnippet: false,
+		pure: false
+	};
+	const nonEmpty = block.raw.split("\n").map(strippedLine).filter((c) => c.length > 0);
+	const codeish = nonEmpty.filter(isCodeish);
+	return {
+		isSnippet: codeish.length >= 2,
+		pure: nonEmpty.length >= 2 && codeish.length === nonEmpty.length
+	};
+}
+const rule$3 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Forbid code snippets (usage examples) inside comments; auto-removable only when the block is entirely code.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-comment-code-snippet"
+		},
+		schema: [{
+			type: "object",
+			properties: { protectedPatterns: {
+				type: "array",
+				items: { type: "string" }
+			} },
+			additionalProperties: false
+		}],
+		messages: { codeSnippet: "code snippet inside comment (usage example)" }
+	},
+	create(context) {
+		const { detect } = compileProtected((context.options[0] ?? {}).protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		const lineIndex = makeLineIndex(sourceCode.text);
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				const info = snippetInfo(block);
+				if (!info.isSnippet) continue;
+				const deletable = info.pure && block.fullLine;
+				context.report({
+					loc: blockLoc(block),
+					messageId: "codeSnippet",
+					fix: deletable ? (fixer) => fixer.removeRange([lineIndex.lineStart(block.startLine), lineIndex.lineEnd(block.endLine)]) : null
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-comment-narrative.ts
+const NARRATIVE = [
+	/\brenamed?\s+from\b/i,
+	/\bformerly\b/i,
+	/\bpreviously\b/i,
+	/\bas before\b/i,
+	/\bused to\b/i,
+	/\badded\s+(?:for|to|because)\b/i,
+	/\bfix(?:es|ed)?\s+(?:bug|issue)\b/i,
+	/\bslice\s+\d+\b/i,
+	/\bv\d+\.\d+\b/i,
+	/\b\d{4}-\d{2}-\d{2}\b/
+];
+const rule$2 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Forbid change-narrative / history prose in comments (it belongs in the commit message or a spec record).",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-comment-narrative"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				protectedPatterns: {
+					type: "array",
+					items: { type: "string" }
+				},
+				extraPatterns: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		messages: { changeNarrative: "change-narrative / history prose (belongs in commit message or spec record)" }
+	},
+	create(context) {
+		const option = context.options[0] ?? {};
+		const { detect } = compileProtected(option.protectedPatterns ?? []);
+		const extra = (option.extraPatterns ?? []).map((source) => new RegExp(source));
+		const patterns = [...NARRATIVE, ...extra];
+		const sourceCode = context.sourceCode;
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				if (block.hasProtected) continue;
+				if (patterns.some((re) => re.test(block.raw))) context.report({
+					loc: blockLoc(block),
+					messageId: "changeNarrative"
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/lib/decorative.ts
+const DECORATIVE = [
+	/^[=*#_-]{3,}$/,
+	/^#?\s*(?:region|endregion)\b/i,
+	/^[=*#_-]{2,}.*[=*#_-]{2,}$/
+];
+function isDecorativeLine(content) {
+	return content.length > 0 && DECORATIVE.some((re) => re.test(content));
+}
+//#endregion
+//#region src/rules/no-decorative-comment.ts
+const schema$1 = [{
+	type: "object",
+	properties: { protectedPatterns: {
+		type: "array",
+		items: { type: "string" }
+	} },
+	additionalProperties: false
+}];
+function lineLoc(lineNo, text) {
+	return {
+		start: {
+			line: lineNo,
+			column: 0
+		},
+		end: {
+			line: lineNo,
+			column: text.length
+		}
+	};
+}
+const rule$1 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Forbid decorative / section-marker comments (e.g. =====, #region, ===text===), in both // and /* */ forms.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-decorative-comment"
+		},
+		schema: schema$1,
+		messages: { decorativeComment: "decorative / section-marker comment" }
+	},
+	create(context) {
+		const { detect } = compileProtected((context.options[0] ?? {}).protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		const lineIndex = makeLineIndex(sourceCode.text);
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) for (const comment of block.comments) {
+				const rawText = sourceCode.getText(comment);
+				if (comment.type === "Line") {
+					if (!isDecorativeLine(strippedLine(rawText)) || hasProtectedToken(rawText, detect)) continue;
+					const line = comment.loc.start.line;
+					context.report({
+						loc: comment.loc,
+						messageId: "decorativeComment",
+						fix: block.fullLine ? (fixer) => fixer.removeRange([lineIndex.lineStart(line), lineIndex.lineEnd(line)]) : null
+					});
+					continue;
+				}
+				rawText.split("\n").forEach((rawLine, i) => {
+					if (!isDecorativeLine(strippedLine(rawLine)) || hasProtectedToken(rawLine, detect)) return;
+					const line = comment.loc.start.line + i;
+					context.report({
+						loc: lineLoc(line, rawLine),
+						messageId: "decorativeComment"
+					});
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-line-comment.ts
+const schema = [{
+	type: "object",
+	properties: { protectedPatterns: {
+		type: "array",
+		items: { type: "string" }
+	} },
+	additionalProperties: false
+}];
+function buildConversion(block, text, detect, lineIndex) {
+	const indent = text.slice(lineIndex.lineStart(block.startLine), block.start);
+	const kept = [];
+	for (const rawLine of block.raw.split("\n")) {
+		const content = strippedLine(rawLine);
+		if (block.fullLine && isDecorativeLine(content) && !hasProtectedToken(rawLine, detect)) continue;
+		kept.push(content);
+	}
+	if (kept.some((c) => c.includes("*/"))) return null;
+	if (block.fullLine && kept.every((c) => c.length === 0)) return {
+		range: [lineIndex.lineStart(block.startLine), lineIndex.lineEnd(block.endLine)],
+		text: ""
+	};
+	const body = kept.length === 1 ? `/* ${kept[0]} */` : `/*\n${kept.map((c) => c ? `${indent} * ${c}` : `${indent} *`).join("\n")}\n${indent} */`;
+	return {
+		range: [block.start, block.end],
+		text: body
+	};
+}
+const rule = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Forbid line comments (`//`); require block `/* */` comments. Auto-fix converts and merges runs of `//`.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-line-comment"
+		},
+		schema,
+		messages: { lineComment: "line comment; use a block /* */ comment" }
+	},
+	create(context) {
+		const { detect } = compileProtected((context.options[0] ?? {}).protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		const lineIndex = makeLineIndex(sourceCode.text);
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				if (block.kind !== "line") continue;
+				const conv = buildConversion(block, sourceCode.text, detect, lineIndex);
+				context.report({
+					loc: blockLoc(block),
+					messageId: "lineComment",
+					fix: conv ? (fixer) => fixer.replaceTextRange(conv.range, conv.text) : null
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/lib/sdd-patterns.ts
+const TYPES = "BL|SUR|CON|INV|POL|DEL|DLT|NFR|REQ|MIG|CST|SCN|LCN|GAR|EXT";
+const SDD_PROTECTED_PATTERNS = [
+	"@covers\\s+\\S+(?:\\s+\\w+=\\S+)*",
+	`\\b[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?::[a-z0-9]+(?:-[a-z0-9]+)*)*:(?:${TYPES})-\\d+\\b`,
+	`\\b(?:${TYPES})-\\d+\\b`,
+	"\\bM\\d+[A-Z]+-\\d+\\b"
+];
+//#endregion
+//#region src/index.ts
+const configs = {};
+const plugin = {
+	meta: {
+		name: "cyberash",
+		version: "0.1.0"
+	},
+	rules: {
+		"max-comment-lines": rule$4,
+		"no-comment-narrative": rule$2,
+		"no-comment-code-snippet": rule$3,
+		"no-decorative-comment": rule$1,
+		"no-line-comment": rule
+	},
+	configs
+};
+configs.recommended = {
+	plugins: { "comment-policy": plugin },
+	rules: {
+		"comment-policy/max-comment-lines": ["error", {
+			max: 4,
+			anchoredMax: 3
+		}],
+		"comment-policy/no-comment-narrative": ["error"],
+		"comment-policy/no-comment-code-snippet": ["error"],
+		"comment-policy/no-decorative-comment": ["error"],
+		"comment-policy/no-line-comment": ["error"]
+	}
+};
+const sddProtected = [...SDD_PROTECTED_PATTERNS];
+configs.sdd = {
+	plugins: { "comment-policy": plugin },
+	rules: {
+		"comment-policy/max-comment-lines": ["error", {
+			max: 4,
+			anchoredMax: 3,
+			protectedPatterns: sddProtected
+		}],
+		"comment-policy/no-comment-narrative": ["error", { protectedPatterns: sddProtected }],
+		"comment-policy/no-comment-code-snippet": ["error", { protectedPatterns: sddProtected }],
+		"comment-policy/no-decorative-comment": ["error", { protectedPatterns: sddProtected }],
+		"comment-policy/no-line-comment": ["error", { protectedPatterns: sddProtected }]
+	}
+};
+//#endregion
+module.exports = plugin;

package/dist/index.d.cts

@@ -0,0 +1,5 @@
+import { TSESLint } from "@typescript-eslint/utils";
+
+//#region src/index.d.ts
+declare const plugin: TSESLint.FlatConfig.Plugin;
+export = plugin;

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+import { TSESLint } from "@typescript-eslint/utils";
+
+//#region src/index.d.ts
+declare const plugin: TSESLint.FlatConfig.Plugin;
+//#endregion
+export { plugin as default };

package/dist/index.mjs

@@ -0,0 +1,446 @@
+//#region src/lib/protected.ts
+function compileProtected(patterns) {
+	return {
+		detect: patterns.map((source) => new RegExp(source)),
+		strip: patterns.map((source) => new RegExp(source, "g"))
+	};
+}
+function hasProtectedToken(text, detect) {
+	return detect.some((re) => re.test(text));
+}
+function strippedLine(rawLine) {
+	return rawLine.replace(/^\s*\/\//, "").replace(/^\s*\/\*+/, "").replace(/\*+\/\s*$/, "").replace(/^\s*\*/, "").trim();
+}
+function isProseLine(rawLine, strip) {
+	let content = strippedLine(rawLine);
+	for (const re of strip) content = content.replace(re, " ");
+	return /[A-Za-z]{3,}/.test(content);
+}
+//#endregion
+//#region src/lib/comment-blocks.ts
+function lineStarts(text) {
+	const starts = [0];
+	for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) starts.push(i + 1);
+	return starts;
+}
+function makeLineIndex(text) {
+	const starts = lineStarts(text);
+	return {
+		lineStart: (lineNo) => starts[lineNo - 1],
+		lineEnd: (lineNo) => lineNo < starts.length ? starts[lineNo] : text.length
+	};
+}
+function onlyWhitespaceNoBlank(between) {
+	return /^[ \t]*\r?\n[ \t]*$/.test(between);
+}
+function commentBlocks(sourceCode, detect) {
+	const text = sourceCode.text;
+	const isFullLine = (c) => {
+		const lineText = sourceCode.lines[c.loc.start.line - 1] ?? "";
+		return /^\s*$/.test(lineText.slice(0, c.loc.start.column));
+	};
+	const blocks = [];
+	let cur = null;
+	for (const c of sourceCode.getAllComments()) {
+		const kind = c.type === "Line" ? "line" : "block";
+		const fullLine = isFullLine(c);
+		if (cur !== null && cur.kind === "line" && kind === "line" && cur.fullLine && fullLine && onlyWhitespaceNoBlank(text.slice(cur.end, c.range[0])) && cur) {
+			cur.end = c.range[1];
+			cur.comments.push(c);
+			continue;
+		}
+		if (cur) blocks.push(finalize(cur, text, detect));
+		cur = {
+			kind,
+			start: c.range[0],
+			end: c.range[1],
+			fullLine,
+			comments: [c]
+		};
+	}
+	if (cur) blocks.push(finalize(cur, text, detect));
+	return blocks;
+}
+function finalize(b, text, detect) {
+	const raw = text.slice(b.start, b.end);
+	const startLine = b.comments[0].loc.start.line;
+	const endLine = b.comments[b.comments.length - 1].loc.end.line;
+	return {
+		kind: b.kind,
+		start: b.start,
+		end: b.end,
+		fullLine: b.fullLine,
+		raw,
+		startLine,
+		endLine,
+		lineCount: endLine - startLine + 1,
+		hasProtected: hasProtectedToken(raw, detect),
+		comments: b.comments
+	};
+}
+function blockLoc(block) {
+	return {
+		start: block.comments[0].loc.start,
+		end: block.comments[block.comments.length - 1].loc.end
+	};
+}
+//#endregion
+//#region src/rules/max-comment-lines.ts
+const DEFAULT_MAX = 4;
+const DEFAULT_ANCHORED_MAX = 3;
+const rule$4 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Cap the number of prose lines in a comment block (anchored blocks get a lower cap).",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#max-comment-lines"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				max: {
+					type: "integer",
+					minimum: 0
+				},
+				anchoredMax: {
+					type: "integer",
+					minimum: 0
+				},
+				protectedPatterns: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		messages: {
+			tooManyProse: "comment block has {{count}} prose lines (> {{max}}); keep it to a short why or move it into a spec record",
+			tooManyProseAnchored: "anchored comment has {{count}} prose lines (> {{max}}); the rationale belongs in the spec record — keep the marker plus at most a one-line pointer"
+		}
+	},
+	create(context) {
+		const option = context.options[0] ?? {};
+		const max = option.max ?? DEFAULT_MAX;
+		const anchoredMax = option.anchoredMax ?? DEFAULT_ANCHORED_MAX;
+		const { detect, strip } = compileProtected(option.protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				const proseLineCount = block.raw.split("\n").filter((line) => isProseLine(line, strip)).length;
+				const cap = block.hasProtected ? anchoredMax : max;
+				if (proseLineCount > cap) context.report({
+					loc: blockLoc(block),
+					messageId: block.hasProtected ? "tooManyProseAnchored" : "tooManyProse",
+					data: {
+						count: proseLineCount,
+						max: cap
+					}
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-comment-code-snippet.ts
+const CODEISH = [
+	/^(?:import|export|const|let|var|function|class|return|await|async|if|for|while|switch)\b/,
+	/=>/,
+	/^[\w.$]+\([^)]*\)\s*;?$/,
+	/^[}{]/,
+	/;\s*$/
+];
+function isCodeish(content) {
+	return content.length > 0 && CODEISH.some((re) => re.test(content));
+}
+function snippetInfo(block) {
+	if (block.hasProtected) return {
+		isSnippet: false,
+		pure: false
+	};
+	const nonEmpty = block.raw.split("\n").map(strippedLine).filter((c) => c.length > 0);
+	const codeish = nonEmpty.filter(isCodeish);
+	return {
+		isSnippet: codeish.length >= 2,
+		pure: nonEmpty.length >= 2 && codeish.length === nonEmpty.length
+	};
+}
+const rule$3 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Forbid code snippets (usage examples) inside comments; auto-removable only when the block is entirely code.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-comment-code-snippet"
+		},
+		schema: [{
+			type: "object",
+			properties: { protectedPatterns: {
+				type: "array",
+				items: { type: "string" }
+			} },
+			additionalProperties: false
+		}],
+		messages: { codeSnippet: "code snippet inside comment (usage example)" }
+	},
+	create(context) {
+		const { detect } = compileProtected((context.options[0] ?? {}).protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		const lineIndex = makeLineIndex(sourceCode.text);
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				const info = snippetInfo(block);
+				if (!info.isSnippet) continue;
+				const deletable = info.pure && block.fullLine;
+				context.report({
+					loc: blockLoc(block),
+					messageId: "codeSnippet",
+					fix: deletable ? (fixer) => fixer.removeRange([lineIndex.lineStart(block.startLine), lineIndex.lineEnd(block.endLine)]) : null
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-comment-narrative.ts
+const NARRATIVE = [
+	/\brenamed?\s+from\b/i,
+	/\bformerly\b/i,
+	/\bpreviously\b/i,
+	/\bas before\b/i,
+	/\bused to\b/i,
+	/\badded\s+(?:for|to|because)\b/i,
+	/\bfix(?:es|ed)?\s+(?:bug|issue)\b/i,
+	/\bslice\s+\d+\b/i,
+	/\bv\d+\.\d+\b/i,
+	/\b\d{4}-\d{2}-\d{2}\b/
+];
+const rule$2 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Forbid change-narrative / history prose in comments (it belongs in the commit message or a spec record).",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-comment-narrative"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				protectedPatterns: {
+					type: "array",
+					items: { type: "string" }
+				},
+				extraPatterns: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		messages: { changeNarrative: "change-narrative / history prose (belongs in commit message or spec record)" }
+	},
+	create(context) {
+		const option = context.options[0] ?? {};
+		const { detect } = compileProtected(option.protectedPatterns ?? []);
+		const extra = (option.extraPatterns ?? []).map((source) => new RegExp(source));
+		const patterns = [...NARRATIVE, ...extra];
+		const sourceCode = context.sourceCode;
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				if (block.hasProtected) continue;
+				if (patterns.some((re) => re.test(block.raw))) context.report({
+					loc: blockLoc(block),
+					messageId: "changeNarrative"
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/lib/decorative.ts
+const DECORATIVE = [
+	/^[=*#_-]{3,}$/,
+	/^#?\s*(?:region|endregion)\b/i,
+	/^[=*#_-]{2,}.*[=*#_-]{2,}$/
+];
+function isDecorativeLine(content) {
+	return content.length > 0 && DECORATIVE.some((re) => re.test(content));
+}
+//#endregion
+//#region src/rules/no-decorative-comment.ts
+const schema$1 = [{
+	type: "object",
+	properties: { protectedPatterns: {
+		type: "array",
+		items: { type: "string" }
+	} },
+	additionalProperties: false
+}];
+function lineLoc(lineNo, text) {
+	return {
+		start: {
+			line: lineNo,
+			column: 0
+		},
+		end: {
+			line: lineNo,
+			column: text.length
+		}
+	};
+}
+const rule$1 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Forbid decorative / section-marker comments (e.g. =====, #region, ===text===), in both // and /* */ forms.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-decorative-comment"
+		},
+		schema: schema$1,
+		messages: { decorativeComment: "decorative / section-marker comment" }
+	},
+	create(context) {
+		const { detect } = compileProtected((context.options[0] ?? {}).protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		const lineIndex = makeLineIndex(sourceCode.text);
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) for (const comment of block.comments) {
+				const rawText = sourceCode.getText(comment);
+				if (comment.type === "Line") {
+					if (!isDecorativeLine(strippedLine(rawText)) || hasProtectedToken(rawText, detect)) continue;
+					const line = comment.loc.start.line;
+					context.report({
+						loc: comment.loc,
+						messageId: "decorativeComment",
+						fix: block.fullLine ? (fixer) => fixer.removeRange([lineIndex.lineStart(line), lineIndex.lineEnd(line)]) : null
+					});
+					continue;
+				}
+				rawText.split("\n").forEach((rawLine, i) => {
+					if (!isDecorativeLine(strippedLine(rawLine)) || hasProtectedToken(rawLine, detect)) return;
+					const line = comment.loc.start.line + i;
+					context.report({
+						loc: lineLoc(line, rawLine),
+						messageId: "decorativeComment"
+					});
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/rules/no-line-comment.ts
+const schema = [{
+	type: "object",
+	properties: { protectedPatterns: {
+		type: "array",
+		items: { type: "string" }
+	} },
+	additionalProperties: false
+}];
+function buildConversion(block, text, detect, lineIndex) {
+	const indent = text.slice(lineIndex.lineStart(block.startLine), block.start);
+	const kept = [];
+	for (const rawLine of block.raw.split("\n")) {
+		const content = strippedLine(rawLine);
+		if (block.fullLine && isDecorativeLine(content) && !hasProtectedToken(rawLine, detect)) continue;
+		kept.push(content);
+	}
+	if (kept.some((c) => c.includes("*/"))) return null;
+	if (block.fullLine && kept.every((c) => c.length === 0)) return {
+		range: [lineIndex.lineStart(block.startLine), lineIndex.lineEnd(block.endLine)],
+		text: ""
+	};
+	const body = kept.length === 1 ? `/* ${kept[0]} */` : `/*\n${kept.map((c) => c ? `${indent} * ${c}` : `${indent} *`).join("\n")}\n${indent} */`;
+	return {
+		range: [block.start, block.end],
+		text: body
+	};
+}
+const rule = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: {
+			description: "Forbid line comments (`//`); require block `/* */` comments. Auto-fix converts and merges runs of `//`.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-line-comment"
+		},
+		schema,
+		messages: { lineComment: "line comment; use a block /* */ comment" }
+	},
+	create(context) {
+		const { detect } = compileProtected((context.options[0] ?? {}).protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		const lineIndex = makeLineIndex(sourceCode.text);
+		return { "Program:exit"() {
+			for (const block of commentBlocks(sourceCode, detect)) {
+				if (block.kind !== "line") continue;
+				const conv = buildConversion(block, sourceCode.text, detect, lineIndex);
+				context.report({
+					loc: blockLoc(block),
+					messageId: "lineComment",
+					fix: conv ? (fixer) => fixer.replaceTextRange(conv.range, conv.text) : null
+				});
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/lib/sdd-patterns.ts
+const TYPES = "BL|SUR|CON|INV|POL|DEL|DLT|NFR|REQ|MIG|CST|SCN|LCN|GAR|EXT";
+const SDD_PROTECTED_PATTERNS = [
+	"@covers\\s+\\S+(?:\\s+\\w+=\\S+)*",
+	`\\b[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?::[a-z0-9]+(?:-[a-z0-9]+)*)*:(?:${TYPES})-\\d+\\b`,
+	`\\b(?:${TYPES})-\\d+\\b`,
+	"\\bM\\d+[A-Z]+-\\d+\\b"
+];
+//#endregion
+//#region src/index.ts
+const configs = {};
+const plugin = {
+	meta: {
+		name: "cyberash",
+		version: "0.1.0"
+	},
+	rules: {
+		"max-comment-lines": rule$4,
+		"no-comment-narrative": rule$2,
+		"no-comment-code-snippet": rule$3,
+		"no-decorative-comment": rule$1,
+		"no-line-comment": rule
+	},
+	configs
+};
+configs.recommended = {
+	plugins: { "comment-policy": plugin },
+	rules: {
+		"comment-policy/max-comment-lines": ["error", {
+			max: 4,
+			anchoredMax: 3
+		}],
+		"comment-policy/no-comment-narrative": ["error"],
+		"comment-policy/no-comment-code-snippet": ["error"],
+		"comment-policy/no-decorative-comment": ["error"],
+		"comment-policy/no-line-comment": ["error"]
+	}
+};
+const sddProtected = [...SDD_PROTECTED_PATTERNS];
+configs.sdd = {
+	plugins: { "comment-policy": plugin },
+	rules: {
+		"comment-policy/max-comment-lines": ["error", {
+			max: 4,
+			anchoredMax: 3,
+			protectedPatterns: sddProtected
+		}],
+		"comment-policy/no-comment-narrative": ["error", { protectedPatterns: sddProtected }],
+		"comment-policy/no-comment-code-snippet": ["error", { protectedPatterns: sddProtected }],
+		"comment-policy/no-decorative-comment": ["error", { protectedPatterns: sddProtected }],
+		"comment-policy/no-line-comment": ["error", { protectedPatterns: sddProtected }]
+	}
+};
+//#endregion
+export { plugin as default };

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "eslint-plugin-comment-policy",
+	"version": "0.1.0",
+	"description": "ESLint rules enforcing a per-file comment policy: prose-line caps, no change-narrative, no code snippets, no decorative markers, block comments only (JS + TS).",
+	"type": "module",
+	"license": "MIT",
+	"author": "cyberash <mail@cyberash.dev>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cyberash-dev/eslint-plugin-comment-policy.git"
+	},
+	"bugs": {
+		"url": "https://github.com/cyberash-dev/eslint-plugin-comment-policy/issues"
+	},
+	"homepage": "https://github.com/cyberash-dev/eslint-plugin-comment-policy#readme",
+	"keywords": [
+		"eslint",
+		"eslint-plugin",
+		"eslintplugin",
+		"comments",
+		"comment-policy",
+		"typescript"
+	],
+	"sideEffects": false,
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"files": [
+		"dist",
+		"AGENTS.md"
+	],
+	"scripts": {
+		"build": "tsdown",
+		"test": "tsx tests/run-all.ts",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint .",
+		"prepublishOnly": "npm run build && npm test"
+	},
+	"peerDependencies": {
+		"eslint": ">=9"
+	},
+	"dependencies": {
+		"@typescript-eslint/types": "8.60.0",
+		"@typescript-eslint/utils": "8.60.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "9.39.4",
+		"@types/node": "22.19.19",
+		"eslint": "9.39.4",
+		"globals": "15.15.0",
+		"tsdown": "0.22.1",
+		"tsx": "4.22.3",
+		"typescript": "5.9.3",
+		"typescript-eslint": "8.60.0"
+	},
+	"engines": {
+		"node": ">=20"
+	}
+}