eslint-plugin-comment-policy 0.2.0 → 0.3.0

package/AGENTS.md

@@ -1,12 +1,14 @@
 # AGENTS.md — adopting eslint-plugin-comment-policy
 
-Five ESLint 9 (flat-config) rules enforcing a comment policy, namespace
+Six 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-consecutive-comments` — several stand-alone comments in a
+  row (default `max` 1, `types` line+block, `skipBlankLines` true).
 - `comment-policy/no-decorative-comment` — decorative / section markers.
 - `comment-policy/no-line-comment` — `//` forbidden, `/* */` required.
 
@@ -20,7 +22,7 @@ Five ESLint 9 (flat-config) rules enforcing a comment policy, namespace
    export default [commentPolicy.configs.recommended];
    ```
 
-   `recommended` turns **all five rules on at `error`** with defaults.
+   `recommended` turns **all six rules on at `error`** with defaults.
 
 ## Rule behavior an agent must know
 

package/README.md

@@ -16,13 +16,18 @@ Namespace: `comment-policy/`. Plugin scope (`meta.name`): `cyberash`.
 | `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-consecutive-comments` | several stand-alone comments stacked one after another (more than `max`) | no |
 | `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.
+are stripped, so anchor/marker-only lines do not count toward the cap. A
+**comment run** (used by `no-consecutive-comments`) is a sequence of full-line
+comments of an enabled kind separated only by whitespace; a multi-line `/* */`
+counts as one comment, and code or a comment of a non-enabled kind breaks the
+run.
 
 ## Install
 
@@ -40,7 +45,7 @@ import commentPolicy from "eslint-plugin-comment-policy";
 export default [commentPolicy.configs.recommended];
 ```
 
-`recommended` turns all five rules on at `error` with defaults.
+`recommended` turns all six rules on at `error` with defaults.
 
 Or register the plugin and enable rules explicitly:
 
@@ -54,6 +59,7 @@ export default [
 			"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-consecutive-comments": "error",
 			"comment-policy/no-decorative-comment": "error",
 			"comment-policy/no-line-comment": "error",
 		},
@@ -66,10 +72,12 @@ export default [
 ### `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`.
+`no-comment-code-snippet`, `no-consecutive-comments`, `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`, is exempt from `no-comment-narrative` /
+`no-comment-code-snippet` / `no-decorative-comment`, and is excluded from
+`no-consecutive-comments` runs.
 
 Order matters: put the longer/more specific pattern first so a marker is fully
 stripped before a shorter pattern that is its suffix.
@@ -92,6 +100,21 @@ stripped before a shorter pattern that is its suffix.
 - `extraPatterns` — extra narrative patterns (source strings) added to the
   built-in set.
 
+### `no-consecutive-comments`
+
+```js
+["error", { types: ["line", "block"], max: 1, skipBlankLines: true, protectedPatterns: [] }]
+```
+
+- `types` (default `["line", "block"]`) — which comment kinds participate in a
+  run: `line` (`//`) and/or `block` (`/* */`). A comment of a kind not listed
+  breaks the run.
+- `max` (default `1`) — how many consecutive comments are allowed; a run longer
+  than `max` is reported (with `max: 1`, any second comment in a row is flagged).
+- `skipBlankLines` (default `true`) — when `true`, comments separated only by
+  blank lines still count as consecutive; set `false` to let a blank line break
+  the run.
+
 ### `no-comment-code-snippet`, `no-decorative-comment`, `no-line-comment`
 
 ```js

package/README.ru.md

@@ -16,13 +16,18 @@
 | `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-consecutive-comments` | несколько отдельных комментариев подряд (больше `max`) | нет |
 | `comment-policy/no-decorative-comment` | декоративные / секционные маркеры (`=====`, `#region`, `===text===`) | да |
 | `comment-policy/no-line-comment` | любой `//`; требует `/* */` | да (конвертация и склейка подряд идущих `//`) |
 
 **Блок комментария** — подряд идущие full-line `//`, разделённые только
 пробелами (без пустой строки). **Прозаическая строка** — строка комментария, в
 которой после снятия маркеров комментария и protected-маркеров остаётся реальное
-слово (≥3 букв); поэтому чисто анкорные/маркерные строки в кап не идут.
+слово (≥3 букв); поэтому чисто анкорные/маркерные строки в кап не идут. **Серия
+комментариев** (для `no-consecutive-comments`) — последовательность full-line
+комментариев включённого типа, разделённых только пробелами; многострочный
+`/* */` считается одним комментарием, а код или комментарий невключённого типа
+разрывает серию.
 
 ## Установка
 
@@ -40,7 +45,7 @@ import commentPolicy from "eslint-plugin-comment-policy";
 export default [commentPolicy.configs.recommended];
 ```
 
-`recommended` включает все пять правил на `error` с дефолтами.
+`recommended` включает все шесть правил на `error` с дефолтами.
 
 Либо подключить плагин и включить правила вручную:
 
@@ -54,6 +59,7 @@ export default [
 			"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-consecutive-comments": "error",
 			"comment-policy/no-decorative-comment": "error",
 			"comment-policy/no-line-comment": "error",
 		},
@@ -66,11 +72,12 @@ export default [
 ### `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`.
+`no-comment-code-snippet`, `no-consecutive-comments`, `no-decorative-comment` и
+`no-line-comment`. Массив **строк-исходников** регулярных выражений. Блок,
+совпавший с любым паттерном, считается «защищённым»: получает пониженный кап в
+`max-comment-lines`, исключается из `no-comment-narrative` /
+`no-comment-code-snippet` / `no-decorative-comment` и не учитывается в сериях
+`no-consecutive-comments`.
 
 Порядок важен: более длинный/специфичный паттерн ставьте раньше, чтобы маркер
 снимался целиком до более короткого паттерна, который является его суффиксом.
@@ -93,6 +100,21 @@ export default [
 - `extraPatterns` — дополнительные narrative-паттерны (строки-исходники) к
   встроенному набору.
 
+### `no-consecutive-comments`
+
+```js
+["error", { types: ["line", "block"], max: 1, skipBlankLines: true, protectedPatterns: [] }]
+```
+
+- `types` (деф. `["line", "block"]`) — какие типы комментариев участвуют в серии:
+  `line` (`//`) и/или `block` (`/* */`). Комментарий типа не из списка разрывает
+  серию.
+- `max` (деф. `1`) — сколько комментариев подряд допустимо; серия длиннее `max`
+  репортится (при `max: 1` ловится любой второй комментарий подряд).
+- `skipBlankLines` (деф. `true`) — при `true` комментарии, разделённые только
+  пустыми строками, всё равно считаются подряд идущими; `false` — пустая строка
+  разрывает серию.
+
 ### `no-comment-code-snippet`, `no-decorative-comment`, `no-line-comment`
 
 ```js

package/dist/index.cjs

@@ -86,9 +86,9 @@ function blockLoc(block) {
 }
 //#endregion
 //#region src/rules/max-comment-lines.ts
-const DEFAULT_MAX = 4;
+const DEFAULT_MAX$1 = 4;
 const DEFAULT_ANCHORED_MAX = 3;
-const rule$4 = {
+const rule$5 = {
 	defaultOptions: [{}],
 	meta: {
 		type: "suggestion",
@@ -121,7 +121,7 @@ const rule$4 = {
 	},
 	create(context) {
 		const option = context.options[0] ?? {};
-		const max = option.max ?? DEFAULT_MAX;
+		const max = option.max ?? DEFAULT_MAX$1;
 		const anchoredMax = option.anchoredMax ?? DEFAULT_ANCHORED_MAX;
 		const { detect, strip } = compileProtected(option.protectedPatterns ?? []);
 		const sourceCode = context.sourceCode;
@@ -165,7 +165,7 @@ function snippetInfo(block) {
 		pure: nonEmpty.length >= 2 && codeish.length === nonEmpty.length
 	};
 }
-const rule$3 = {
+const rule$4 = {
 	defaultOptions: [{}],
 	meta: {
 		type: "suggestion",
@@ -216,7 +216,7 @@ const NARRATIVE = [
 	/\bv\d+\.\d+\b/i,
 	/\b\d{4}-\d{2}-\d{2}\b/
 ];
-const rule$2 = {
+const rule$3 = {
 	defaultOptions: [{}],
 	meta: {
 		type: "suggestion",
@@ -258,6 +258,105 @@ const rule$2 = {
 	}
 };
 //#endregion
+//#region src/lib/comment-runs.ts
+function commentRuns(sourceCode, options) {
+	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 isCounted = (c) => {
+		const kind = c.type === "Line" ? "line" : "block";
+		return options.types.has(kind) && isFullLine(c) && !hasProtectedToken(sourceCode.getText(c), options.detect);
+	};
+	const isAdjacent = (prev, curr) => {
+		const between = text.slice(prev.range[1], curr.range[0]);
+		return options.skipBlankLines ? /^\s*$/.test(between) : onlyWhitespaceNoBlank(between);
+	};
+	const runs = [];
+	let current = [];
+	const flush = () => {
+		if (current.length === 0) return;
+		runs.push({
+			comments: current,
+			loc: {
+				start: current[0].loc.start,
+				end: current[current.length - 1].loc.end
+			}
+		});
+		current = [];
+	};
+	for (const c of sourceCode.getAllComments()) {
+		if (!isCounted(c)) {
+			flush();
+			continue;
+		}
+		if (current.length > 0 && !isAdjacent(current[current.length - 1], c)) flush();
+		current.push(c);
+	}
+	flush();
+	return runs;
+}
+//#endregion
+//#region src/rules/no-consecutive-comments.ts
+const DEFAULT_MAX = 1;
+const DEFAULT_TYPES = ["line", "block"];
+const rule$2 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Forbid several stand-alone comments stacked one after another; merge or remove the extras.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-consecutive-comments"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				types: {
+					type: "array",
+					items: {
+						type: "string",
+						enum: ["line", "block"]
+					}
+				},
+				max: {
+					type: "integer",
+					minimum: 1
+				},
+				skipBlankLines: { type: "boolean" },
+				protectedPatterns: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		messages: { consecutiveComments: "{{count}} consecutive comments (> {{max}}); merge them into one or remove the extras" }
+	},
+	create(context) {
+		const option = context.options[0] ?? {};
+		const max = option.max ?? DEFAULT_MAX;
+		const skipBlankLines = option.skipBlankLines ?? true;
+		const types = new Set(option.types ?? DEFAULT_TYPES);
+		const { detect } = compileProtected(option.protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		return { "Program:exit"() {
+			for (const run of commentRuns(sourceCode, {
+				types,
+				skipBlankLines,
+				detect
+			})) if (run.comments.length > max) context.report({
+				loc: run.loc,
+				messageId: "consecutiveComments",
+				data: {
+					count: run.comments.length,
+					max
+				}
+			});
+		} };
+	}
+};
+//#endregion
 //#region src/lib/decorative.ts
 const DECORATIVE = [
 	/^[=*#_-]{3,}$/,
@@ -394,12 +493,13 @@ const configs = {};
 const plugin = {
 	meta: {
 		name: "cyberash",
-		version: "0.2.0"
+		version: "0.3.0"
 	},
 	rules: {
-		"max-comment-lines": rule$4,
-		"no-comment-narrative": rule$2,
-		"no-comment-code-snippet": rule$3,
+		"max-comment-lines": rule$5,
+		"no-comment-narrative": rule$3,
+		"no-comment-code-snippet": rule$4,
+		"no-consecutive-comments": rule$2,
 		"no-decorative-comment": rule$1,
 		"no-line-comment": rule
 	},
@@ -414,6 +514,7 @@ configs.recommended = {
 		}],
 		"comment-policy/no-comment-narrative": ["error"],
 		"comment-policy/no-comment-code-snippet": ["error"],
+		"comment-policy/no-consecutive-comments": ["error"],
 		"comment-policy/no-decorative-comment": ["error"],
 		"comment-policy/no-line-comment": ["error"]
 	}

package/dist/index.mjs

@@ -86,9 +86,9 @@ function blockLoc(block) {
 }
 //#endregion
 //#region src/rules/max-comment-lines.ts
-const DEFAULT_MAX = 4;
+const DEFAULT_MAX$1 = 4;
 const DEFAULT_ANCHORED_MAX = 3;
-const rule$4 = {
+const rule$5 = {
 	defaultOptions: [{}],
 	meta: {
 		type: "suggestion",
@@ -121,7 +121,7 @@ const rule$4 = {
 	},
 	create(context) {
 		const option = context.options[0] ?? {};
-		const max = option.max ?? DEFAULT_MAX;
+		const max = option.max ?? DEFAULT_MAX$1;
 		const anchoredMax = option.anchoredMax ?? DEFAULT_ANCHORED_MAX;
 		const { detect, strip } = compileProtected(option.protectedPatterns ?? []);
 		const sourceCode = context.sourceCode;
@@ -165,7 +165,7 @@ function snippetInfo(block) {
 		pure: nonEmpty.length >= 2 && codeish.length === nonEmpty.length
 	};
 }
-const rule$3 = {
+const rule$4 = {
 	defaultOptions: [{}],
 	meta: {
 		type: "suggestion",
@@ -216,7 +216,7 @@ const NARRATIVE = [
 	/\bv\d+\.\d+\b/i,
 	/\b\d{4}-\d{2}-\d{2}\b/
 ];
-const rule$2 = {
+const rule$3 = {
 	defaultOptions: [{}],
 	meta: {
 		type: "suggestion",
@@ -258,6 +258,105 @@ const rule$2 = {
 	}
 };
 //#endregion
+//#region src/lib/comment-runs.ts
+function commentRuns(sourceCode, options) {
+	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 isCounted = (c) => {
+		const kind = c.type === "Line" ? "line" : "block";
+		return options.types.has(kind) && isFullLine(c) && !hasProtectedToken(sourceCode.getText(c), options.detect);
+	};
+	const isAdjacent = (prev, curr) => {
+		const between = text.slice(prev.range[1], curr.range[0]);
+		return options.skipBlankLines ? /^\s*$/.test(between) : onlyWhitespaceNoBlank(between);
+	};
+	const runs = [];
+	let current = [];
+	const flush = () => {
+		if (current.length === 0) return;
+		runs.push({
+			comments: current,
+			loc: {
+				start: current[0].loc.start,
+				end: current[current.length - 1].loc.end
+			}
+		});
+		current = [];
+	};
+	for (const c of sourceCode.getAllComments()) {
+		if (!isCounted(c)) {
+			flush();
+			continue;
+		}
+		if (current.length > 0 && !isAdjacent(current[current.length - 1], c)) flush();
+		current.push(c);
+	}
+	flush();
+	return runs;
+}
+//#endregion
+//#region src/rules/no-consecutive-comments.ts
+const DEFAULT_MAX = 1;
+const DEFAULT_TYPES = ["line", "block"];
+const rule$2 = {
+	defaultOptions: [{}],
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Forbid several stand-alone comments stacked one after another; merge or remove the extras.",
+			url: "https://github.com/cyberash-dev/eslint-plugin-comment-policy#no-consecutive-comments"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				types: {
+					type: "array",
+					items: {
+						type: "string",
+						enum: ["line", "block"]
+					}
+				},
+				max: {
+					type: "integer",
+					minimum: 1
+				},
+				skipBlankLines: { type: "boolean" },
+				protectedPatterns: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		messages: { consecutiveComments: "{{count}} consecutive comments (> {{max}}); merge them into one or remove the extras" }
+	},
+	create(context) {
+		const option = context.options[0] ?? {};
+		const max = option.max ?? DEFAULT_MAX;
+		const skipBlankLines = option.skipBlankLines ?? true;
+		const types = new Set(option.types ?? DEFAULT_TYPES);
+		const { detect } = compileProtected(option.protectedPatterns ?? []);
+		const sourceCode = context.sourceCode;
+		return { "Program:exit"() {
+			for (const run of commentRuns(sourceCode, {
+				types,
+				skipBlankLines,
+				detect
+			})) if (run.comments.length > max) context.report({
+				loc: run.loc,
+				messageId: "consecutiveComments",
+				data: {
+					count: run.comments.length,
+					max
+				}
+			});
+		} };
+	}
+};
+//#endregion
 //#region src/lib/decorative.ts
 const DECORATIVE = [
 	/^[=*#_-]{3,}$/,
@@ -394,12 +493,13 @@ const configs = {};
 const plugin = {
 	meta: {
 		name: "cyberash",
-		version: "0.2.0"
+		version: "0.3.0"
 	},
 	rules: {
-		"max-comment-lines": rule$4,
-		"no-comment-narrative": rule$2,
-		"no-comment-code-snippet": rule$3,
+		"max-comment-lines": rule$5,
+		"no-comment-narrative": rule$3,
+		"no-comment-code-snippet": rule$4,
+		"no-consecutive-comments": rule$2,
 		"no-decorative-comment": rule$1,
 		"no-line-comment": rule
 	},
@@ -414,6 +514,7 @@ configs.recommended = {
 		}],
 		"comment-policy/no-comment-narrative": ["error"],
 		"comment-policy/no-comment-code-snippet": ["error"],
+		"comment-policy/no-consecutive-comments": ["error"],
 		"comment-policy/no-decorative-comment": ["error"],
 		"comment-policy/no-line-comment": ["error"]
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-plugin-comment-policy",
-	"version": "0.2.0",
+	"version": "0.3.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",