@dloizides/frontend-devtools 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,35 @@ All notable changes to `@dloizides/frontend-devtools` are documented here.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.4.0] - 2026-10-07
9
+
10
+ COMMENTS-1 "No code comments; only short doc comments on public members", decision D-CMT-4 "One-line summary, no call chains".
11
+
12
+ ### Changed
13
+
14
+ - `doc-comment-max-lines`: the description (lines other than `@param` / `@returns`) is capped at ONE line
15
+ (`summaryMaxLines`, default 1), every doc line at 120 chars (`lineMaxChars`), and a line containing an arrow
16
+ (U+2192 or `->`) or starting `Flow:` is reported (`callChain`). Matches `.claude/hooks/review-violations.js` docBlock().
17
+ The 3-line total cap is unchanged. One report per block; banned tags take precedence.
18
+
19
+ ## [1.3.0] - 2026-10-06
20
+
21
+ COMMENTS-1 "No code comments; only short doc comments on public members" (decisions D-CMT-1, D-CMT-3).
22
+
23
+ ### Added
24
+
25
+ - `no-comments`: reports every comment that is not a `/**` doc block and not a tool directive
26
+ (`eslint-*`, `@ts-*`, `prettier-ignore`, `istanbul`/`c8`, `/// <reference>`, `#__PURE__`,
27
+ `webpackChunkName`, shebang). `allow: string[]` adds directive regexes. Suggestion only, no autofix.
28
+ - `doc-comment-public-only`: a doc block must sit on an exported declaration (incl. `export { x }`,
29
+ `export default x`, `module.exports`, ambient `declare module`) or a public member of one;
30
+ `private` / `protected` / `#` members and local declarations are reported.
31
+ - `doc-comment-max-lines`: doc body capped at `max` (default 3) content lines; block tags other than
32
+ `allowedTags` (default `@param`, `@returns`) are reported. JSDoc type-annotation blocks
33
+ (`@type`, `@typedef`, ...) are exempt from both doc rules.
34
+ - `commentsConfig` flat-config block (the three rules at `error`) and `COMMENT_RULE_NAMES`, exported
35
+ from `/eslint`. Not adopted by any app yet: each repo opts in as step 1 of its COMMENTS-CLEAN sweep.
36
+
8
37
  ## [1.1.0] - 2026-07-13
9
38
 
10
39
  Both changes come out of the ES-04 (agora-web) build, which surfaced two ways the
@@ -74,4 +74,8 @@ declare const ruleNames: readonly string[];
74
74
  */
75
75
  declare const legacyPlugins: Record<string, FlatConfigPlugin>;
76
76
 
77
- export { type CustomRule, type FlatConfig, type FlatConfigPlugin, type SingleRulePlugin, legacyPlugins, plugin, ruleNames, rules };
77
+ declare const COMMENT_RULE_NAMES: readonly string[];
78
+ /** Flat-config block for COMMENTS-1: no code comments, short doc comments on public members only. */
79
+ declare const commentsConfig: FlatConfig;
80
+
81
+ export { COMMENT_RULE_NAMES, type CustomRule, type FlatConfig, type FlatConfigPlugin, type SingleRulePlugin, commentsConfig, legacyPlugins, plugin, ruleNames, rules };
@@ -74,4 +74,8 @@ declare const ruleNames: readonly string[];
74
74
  */
75
75
  declare const legacyPlugins: Record<string, FlatConfigPlugin>;
76
76
 
77
- export { type CustomRule, type FlatConfig, type FlatConfigPlugin, type SingleRulePlugin, legacyPlugins, plugin, ruleNames, rules };
77
+ declare const COMMENT_RULE_NAMES: readonly string[];
78
+ /** Flat-config block for COMMENTS-1: no code comments, short doc comments on public members only. */
79
+ declare const commentsConfig: FlatConfig;
80
+
81
+ export { COMMENT_RULE_NAMES, type CustomRule, type FlatConfig, type FlatConfigPlugin, type SingleRulePlugin, commentsConfig, legacyPlugins, plugin, ruleNames, rules };
@@ -8,6 +8,292 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
8
8
  var fs__default = /*#__PURE__*/_interopDefault(fs);
9
9
  var path__default = /*#__PURE__*/_interopDefault(path);
10
10
 
11
+ // src/rules/comment-utils.js
12
+ var DIRECTIVE_PATTERNS = [
13
+ /^\s*eslint(-disable|-enable|-env)?(-next-line|-line)?(\s|$)/,
14
+ /^\s*eslint\s/,
15
+ /^\s*globals?\s/,
16
+ /^\s*exported\s/,
17
+ /^\s*@ts-(expect-error|ignore|nocheck|check)\b/,
18
+ /^\s*prettier-ignore\b/,
19
+ /^\s*(istanbul|c8|v8)\s+ignore\b/,
20
+ /^\s*webpack[A-Z]\w*\s*:/,
21
+ /^\s*@vite-ignore\b/,
22
+ /^\s*[#@]__(PURE|NO_SIDE_EFFECTS)__\s*$/,
23
+ /^\s*@(jest|vitest)-environment\b/,
24
+ /^\s*jscpd:/,
25
+ /^\s*biome-ignore\b/,
26
+ /^\/\s*<(reference|amd-module)\b/
27
+ ];
28
+ var JSDOC_TYPE_TAGS = /* @__PURE__ */ new Set([
29
+ "type",
30
+ "typedef",
31
+ "satisfies",
32
+ "import",
33
+ "callback",
34
+ "template",
35
+ "property",
36
+ "jsx",
37
+ "jsxImportSource",
38
+ "jsxFrag",
39
+ "jsxRuntime"
40
+ ]);
41
+ var BLOCK_TAG = /^@([A-Za-z][\w-]*)/;
42
+ function isDocBlock(comment) {
43
+ return comment.type === "Block" && comment.value.startsWith("*") && comment.value !== "*";
44
+ }
45
+ function docBodyLines(comment) {
46
+ return comment.value.slice(1).split(/\r?\n/).map((line) => line.trim().replace(/^\*+\s?/, "").trim()).filter((line) => line.length > 0);
47
+ }
48
+ function blockTags(lines) {
49
+ const tags = [];
50
+ for (const line of lines) {
51
+ const match = BLOCK_TAG.exec(line);
52
+ if (match) tags.push(match[1]);
53
+ }
54
+ return tags;
55
+ }
56
+ function isTypeAnnotationDoc(comment) {
57
+ if (!isDocBlock(comment)) return false;
58
+ const lines = docBodyLines(comment);
59
+ if (lines.length === 0) return false;
60
+ const allTagged = lines.every((line) => BLOCK_TAG.test(line));
61
+ const tags = blockTags(lines);
62
+ return allTagged && tags.every((tag) => JSDOC_TYPE_TAGS.has(tag));
63
+ }
64
+ function compileAllow(allow) {
65
+ return (allow ?? []).map((source) => new RegExp(source));
66
+ }
67
+ function isDirective(comment, extraPatterns) {
68
+ if (comment.type === "Shebang") return true;
69
+ const patterns = extraPatterns ? DIRECTIVE_PATTERNS.concat(extraPatterns) : DIRECTIVE_PATTERNS;
70
+ return patterns.some((pattern) => pattern.test(comment.value));
71
+ }
72
+ function removalRange(sourceCode, comment) {
73
+ const text = sourceCode.text;
74
+ let start = comment.range[0];
75
+ let end = comment.range[1];
76
+ while (start > 0 && (text[start - 1] === " " || text[start - 1] === " ")) start--;
77
+ const ownLine = start === 0 || text[start - 1] === "\n";
78
+ if (ownLine) {
79
+ if (text[end] === "\r") end++;
80
+ if (text[end] === "\n") end++;
81
+ }
82
+ return [start, end];
83
+ }
84
+ function removeSuggestion(sourceCode, comment) {
85
+ return {
86
+ messageId: "removeComment",
87
+ fix: (fixer) => fixer.removeRange(removalRange(sourceCode, comment))
88
+ };
89
+ }
90
+
91
+ // src/rules/doc-comment-max-lines.js
92
+ var DEFAULT_MAX = 3;
93
+ var DEFAULT_ALLOWED_TAGS = ["param", "returns"];
94
+ var DEFAULT_SUMMARY_MAX_LINES = 1;
95
+ var DEFAULT_LINE_MAX_CHARS = 120;
96
+ var CALL_CHAIN = /(→|->|^Flow\s*:)/i;
97
+ var PARAM_LINE = /^@(param|returns?)\b/i;
98
+ function firstShapeProblem(lines, limits) {
99
+ if (lines.length > limits.max)
100
+ return { messageId: "tooLong", data: { actual: String(lines.length), max: String(limits.max) } };
101
+ if (lines.some((line) => CALL_CHAIN.test(line))) return { messageId: "callChain", data: {} };
102
+ const summary = lines.filter((line) => !PARAM_LINE.test(line)).length;
103
+ if (summary > limits.summaryMaxLines)
104
+ return { messageId: "summaryTooLong", data: { actual: String(summary), max: String(limits.summaryMaxLines) } };
105
+ const long = lines.find((line) => line.length > limits.lineMaxChars);
106
+ if (long !== void 0)
107
+ return { messageId: "lineTooLong", data: { actual: String(long.length), max: String(limits.lineMaxChars) } };
108
+ return null;
109
+ }
110
+ var docCommentMaxLinesRule = {
111
+ meta: {
112
+ type: "suggestion",
113
+ docs: {
114
+ description: "Cap a doc comment at a few lines, a one-line summary with no call chain, and only @param / @returns tags (RV-1, D-CMT-3, D-CMT-4)"
115
+ },
116
+ schema: [
117
+ {
118
+ type: "object",
119
+ properties: {
120
+ max: { type: "integer", minimum: 1 },
121
+ allowedTags: { type: "array", items: { type: "string" } },
122
+ bannedTags: { type: "array", items: { type: "string" } },
123
+ summaryMaxLines: { type: "integer", minimum: 1 },
124
+ lineMaxChars: { type: "integer", minimum: 1 }
125
+ },
126
+ additionalProperties: false
127
+ }
128
+ ],
129
+ messages: {
130
+ tooLong: "RV-1: doc comment is {{actual}} lines; the cap is {{max}}.",
131
+ bannedTag: "RV-1: @{{tag}} is not allowed in a doc comment (allowed: {{allowed}}).",
132
+ summaryTooLong: "RV-1: doc summary is {{actual}} lines; it must be one line saying what the member is for.",
133
+ callChain: "RV-1: no call chain or Flow: in a doc comment; say what the member is for, not how it runs.",
134
+ lineTooLong: "RV-1: doc line is {{actual}} chars; the cap is {{max}}."
135
+ }
136
+ },
137
+ create(context) {
138
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
139
+ const options = context.options[0] ?? {};
140
+ const limits = {
141
+ max: options.max ?? DEFAULT_MAX,
142
+ summaryMaxLines: options.summaryMaxLines ?? DEFAULT_SUMMARY_MAX_LINES,
143
+ lineMaxChars: options.lineMaxChars ?? DEFAULT_LINE_MAX_CHARS
144
+ };
145
+ const allowed = new Set(options.allowedTags ?? DEFAULT_ALLOWED_TAGS);
146
+ for (const tag of options.bannedTags ?? []) allowed.delete(tag);
147
+ const allowedText = [...allowed].map((tag) => `@${tag}`).join(", ") || "none";
148
+ return {
149
+ Program() {
150
+ for (const comment of sourceCode.getAllComments()) {
151
+ if (!isDocBlock(comment) || isTypeAnnotationDoc(comment)) continue;
152
+ const lines = docBodyLines(comment);
153
+ const banned = blockTags(lines).filter((tag) => !allowed.has(tag));
154
+ for (const tag of banned)
155
+ context.report({ loc: comment.loc, messageId: "bannedTag", data: { tag, allowed: allowedText } });
156
+ if (banned.length > 0) continue;
157
+ const problem = firstShapeProblem(lines, limits);
158
+ if (problem) context.report({ loc: comment.loc, ...problem });
159
+ }
160
+ }
161
+ };
162
+ }
163
+ };
164
+ var doc_comment_max_lines_default = { rules: { "doc-comment-max-lines": docCommentMaxLinesRule } };
165
+
166
+ // src/rules/doc-comment-public-only.js
167
+ var EXPORT_TYPES = /* @__PURE__ */ new Set([
168
+ "ExportNamedDeclaration",
169
+ "ExportDefaultDeclaration",
170
+ "ExportAllDeclaration",
171
+ "TSExportAssignment"
172
+ ]);
173
+ var PASS_THROUGH = /* @__PURE__ */ new Set([
174
+ "MethodDefinition",
175
+ "PropertyDefinition",
176
+ "AccessorProperty",
177
+ "TSAbstractMethodDefinition",
178
+ "TSAbstractPropertyDefinition",
179
+ "TSAbstractAccessorProperty",
180
+ "TSIndexSignature",
181
+ "ClassBody",
182
+ "ClassDeclaration",
183
+ "ClassExpression",
184
+ "TSInterfaceBody",
185
+ "TSInterfaceDeclaration",
186
+ "TSPropertySignature",
187
+ "TSMethodSignature",
188
+ "TSTypeLiteral",
189
+ "TSTypeAnnotation",
190
+ "TSTypeAliasDeclaration",
191
+ "TSIntersectionType",
192
+ "TSUnionType",
193
+ "TSEnumDeclaration",
194
+ "TSEnumBody",
195
+ "TSEnumMember",
196
+ "TSModuleBlock",
197
+ "TSModuleDeclaration",
198
+ "TSDeclareFunction",
199
+ "VariableDeclaration",
200
+ "VariableDeclarator",
201
+ "ObjectExpression",
202
+ "Property",
203
+ "TSAsExpression",
204
+ "TSSatisfiesExpression"
205
+ ]);
206
+ var HIDDEN_ACCESSIBILITY = /* @__PURE__ */ new Set(["private", "protected"]);
207
+ function isHiddenMember(node) {
208
+ if (HIDDEN_ACCESSIBILITY.has(node.accessibility)) return true;
209
+ return node.key?.type === "PrivateIdentifier";
210
+ }
211
+ function isAmbientModule(node) {
212
+ return node.type === "TSModuleDeclaration" && (node.declare === true || node.global === true);
213
+ }
214
+ function isNamed(node, name) {
215
+ return node?.type === "Identifier" && node.name === name;
216
+ }
217
+ function isCommonJsExport(node) {
218
+ if (node.type !== "ExpressionStatement") return false;
219
+ const expr = node.expression;
220
+ if (expr.type !== "AssignmentExpression" || expr.left.type !== "MemberExpression") return false;
221
+ const target = expr.left.object;
222
+ const isModuleExports = isNamed(target, "module") && isNamed(expr.left.property, "exports");
223
+ const isModuleExportsMember = target.type === "MemberExpression" && isNamed(target.object, "module") && isNamed(target.property, "exports");
224
+ return isNamed(target, "exports") || isModuleExports || isModuleExportsMember;
225
+ }
226
+ function declaredNames(node) {
227
+ if (node.type === "VariableDeclaration")
228
+ return node.declarations.filter((d) => d.id.type === "Identifier").map((d) => d.id.name);
229
+ if (node.id?.type === "Identifier") return [node.id.name];
230
+ return [];
231
+ }
232
+ function collectExportedNames(program) {
233
+ const names = /* @__PURE__ */ new Set();
234
+ for (const statement of program.body) {
235
+ if (statement.type === "ExportNamedDeclaration" && !statement.source) {
236
+ for (const spec of statement.specifiers) if (spec.local.type === "Identifier") names.add(spec.local.name);
237
+ }
238
+ if (statement.type === "ExportDefaultDeclaration" && statement.declaration.type === "Identifier")
239
+ names.add(statement.declaration.name);
240
+ if (statement.type === "TSExportAssignment" && statement.expression.type === "Identifier")
241
+ names.add(statement.expression.name);
242
+ }
243
+ return names;
244
+ }
245
+ function isTopLevelPublic(node, exportedNames) {
246
+ if (EXPORT_TYPES.has(node.type) || isAmbientModule(node) || isCommonJsExport(node)) return true;
247
+ return declaredNames(node).some((name) => exportedNames.has(name));
248
+ }
249
+ function isPublic(start, exportedNames) {
250
+ let current = start;
251
+ while (current.parent && current.parent.type !== "Program") {
252
+ if (isHiddenMember(current)) return false;
253
+ const parent = current.parent;
254
+ if (EXPORT_TYPES.has(parent.type) || isAmbientModule(parent)) return true;
255
+ if (!PASS_THROUGH.has(parent.type)) return false;
256
+ current = parent;
257
+ }
258
+ if (isHiddenMember(current)) return false;
259
+ return isTopLevelPublic(current, exportedNames);
260
+ }
261
+ function documentedNode(sourceCode, comment) {
262
+ const token = sourceCode.getTokenAfter(comment, { includeComments: false });
263
+ if (!token) return null;
264
+ let node = sourceCode.getNodeByRangeIndex(token.range[0]);
265
+ while (node?.parent && node.parent.type !== "Program" && node.parent.range[0] === node.range[0])
266
+ node = node.parent;
267
+ return node && node.type !== "Program" ? node : null;
268
+ }
269
+ var docCommentPublicOnlyRule = {
270
+ meta: {
271
+ type: "suggestion",
272
+ docs: {
273
+ description: "Allow a doc comment only on an exported declaration or a public member of one (RV-1)"
274
+ },
275
+ schema: [],
276
+ messages: {
277
+ notPublic: "RV-1: a doc comment is allowed only on an exported declaration or a public member of one. Move the intent into the name."
278
+ }
279
+ },
280
+ create(context) {
281
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
282
+ return {
283
+ Program(program) {
284
+ const exportedNames = collectExportedNames(program);
285
+ for (const comment of sourceCode.getAllComments()) {
286
+ if (!isDocBlock(comment) || isTypeAnnotationDoc(comment)) continue;
287
+ const node = documentedNode(sourceCode, comment);
288
+ if (node && isPublic(node, exportedNames)) continue;
289
+ context.report({ loc: comment.loc, messageId: "notPublic" });
290
+ }
291
+ }
292
+ };
293
+ }
294
+ };
295
+ var doc_comment_public_only_default = { rules: { "doc-comment-public-only": docCommentPublicOnlyRule } };
296
+
11
297
  // src/rules/enforce-function-style.js
12
298
  function isJSX(node) {
13
299
  return node && (node.type === "JSXElement" || node.type === "JSXFragment");
@@ -861,6 +1147,45 @@ var i18n_param_names_default = {
861
1147
  "i18n-param-names": rule2
862
1148
  }
863
1149
  };
1150
+
1151
+ // src/rules/no-comments.js
1152
+ var noCommentsRule = {
1153
+ meta: {
1154
+ type: "suggestion",
1155
+ hasSuggestions: true,
1156
+ docs: {
1157
+ description: "Disallow code comments: intent goes in names, rules in test names, context in the task doc and commit (RV-2)"
1158
+ },
1159
+ schema: [
1160
+ {
1161
+ type: "object",
1162
+ properties: { allow: { type: "array", items: { type: "string" } } },
1163
+ additionalProperties: false
1164
+ }
1165
+ ],
1166
+ messages: {
1167
+ noComment: "RV-2: no code comments. Put intent in names, business rules in test names, context in the task doc or commit message.",
1168
+ removeComment: "Remove this comment."
1169
+ }
1170
+ },
1171
+ create(context) {
1172
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
1173
+ const extra = compileAllow(context.options[0]?.allow);
1174
+ return {
1175
+ Program() {
1176
+ for (const comment of sourceCode.getAllComments()) {
1177
+ if (isDocBlock(comment) || isDirective(comment, extra)) continue;
1178
+ context.report({
1179
+ loc: comment.loc,
1180
+ messageId: "noComment",
1181
+ suggest: [removeSuggestion(sourceCode, comment)]
1182
+ });
1183
+ }
1184
+ }
1185
+ };
1186
+ }
1187
+ };
1188
+ var no_comments_default = { rules: { "no-comments": noCommentsRule } };
864
1189
  function isPureReExportFile(programNode) {
865
1190
  const { body } = programNode;
866
1191
  if (body.length === 0) return false;
@@ -2072,6 +2397,8 @@ var smart_max_lines_default = {
2072
2397
  // src/eslint/plugin.ts
2073
2398
  var PLUGIN_VERSION = "1.0.0";
2074
2399
  var ruleModules = [
2400
+ doc_comment_max_lines_default,
2401
+ doc_comment_public_only_default,
2075
2402
  enforce_function_style_default,
2076
2403
  enforce_module_structure_default,
2077
2404
  enforce_route_preload_default,
@@ -2080,6 +2407,7 @@ var ruleModules = [
2080
2407
  i18n_interpolation_default,
2081
2408
  i18n_param_names_default,
2082
2409
  no_barrel_companion_file_default,
2410
+ no_comments_default,
2083
2411
  no_duplicate_nav_prefix_default,
2084
2412
  no_duplicate_shared_patterns_default,
2085
2413
  no_generated_models_barrel_value_import_default,
@@ -2126,6 +2454,24 @@ function oneRulePlugin(name, rule3) {
2126
2454
  };
2127
2455
  }
2128
2456
 
2457
+ // src/eslint/configs.ts
2458
+ var DOC_COMMENT_MAX_LINES = 3;
2459
+ var COMMENT_RULE_NAMES = [
2460
+ "no-comments",
2461
+ "doc-comment-public-only",
2462
+ "doc-comment-max-lines"
2463
+ ];
2464
+ var commentsConfig = {
2465
+ plugins: { "@dloizides": plugin },
2466
+ rules: {
2467
+ "@dloizides/no-comments": "error",
2468
+ "@dloizides/doc-comment-public-only": "error",
2469
+ "@dloizides/doc-comment-max-lines": ["error", { max: DOC_COMMENT_MAX_LINES }]
2470
+ }
2471
+ };
2472
+
2473
+ exports.COMMENT_RULE_NAMES = COMMENT_RULE_NAMES;
2474
+ exports.commentsConfig = commentsConfig;
2129
2475
  exports.legacyPlugins = legacyPlugins;
2130
2476
  exports.plugin = plugin;
2131
2477
  exports.ruleNames = ruleNames;