@dloizides/frontend-devtools 1.1.1 → 1.3.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.
@@ -1,6 +1,274 @@
1
1
  import fs, { existsSync, readdirSync } from 'fs';
2
2
  import path, { basename, dirname, sep, posix, join } from 'path';
3
3
 
4
+ // src/rules/comment-utils.js
5
+ var DIRECTIVE_PATTERNS = [
6
+ /^\s*eslint(-disable|-enable|-env)?(-next-line|-line)?(\s|$)/,
7
+ /^\s*eslint\s/,
8
+ /^\s*globals?\s/,
9
+ /^\s*exported\s/,
10
+ /^\s*@ts-(expect-error|ignore|nocheck|check)\b/,
11
+ /^\s*prettier-ignore\b/,
12
+ /^\s*(istanbul|c8|v8)\s+ignore\b/,
13
+ /^\s*webpack[A-Z]\w*\s*:/,
14
+ /^\s*@vite-ignore\b/,
15
+ /^\s*[#@]__(PURE|NO_SIDE_EFFECTS)__\s*$/,
16
+ /^\s*@(jest|vitest)-environment\b/,
17
+ /^\s*jscpd:/,
18
+ /^\s*biome-ignore\b/,
19
+ /^\/\s*<(reference|amd-module)\b/
20
+ ];
21
+ var JSDOC_TYPE_TAGS = /* @__PURE__ */ new Set([
22
+ "type",
23
+ "typedef",
24
+ "satisfies",
25
+ "import",
26
+ "callback",
27
+ "template",
28
+ "property",
29
+ "jsx",
30
+ "jsxImportSource",
31
+ "jsxFrag",
32
+ "jsxRuntime"
33
+ ]);
34
+ var BLOCK_TAG = /^@([A-Za-z][\w-]*)/;
35
+ function isDocBlock(comment) {
36
+ return comment.type === "Block" && comment.value.startsWith("*") && comment.value !== "*";
37
+ }
38
+ function docBodyLines(comment) {
39
+ return comment.value.slice(1).split(/\r?\n/).map((line) => line.trim().replace(/^\*+\s?/, "").trim()).filter((line) => line.length > 0);
40
+ }
41
+ function blockTags(lines) {
42
+ const tags = [];
43
+ for (const line of lines) {
44
+ const match = BLOCK_TAG.exec(line);
45
+ if (match) tags.push(match[1]);
46
+ }
47
+ return tags;
48
+ }
49
+ function isTypeAnnotationDoc(comment) {
50
+ if (!isDocBlock(comment)) return false;
51
+ const lines = docBodyLines(comment);
52
+ if (lines.length === 0) return false;
53
+ const allTagged = lines.every((line) => BLOCK_TAG.test(line));
54
+ const tags = blockTags(lines);
55
+ return allTagged && tags.every((tag) => JSDOC_TYPE_TAGS.has(tag));
56
+ }
57
+ function compileAllow(allow) {
58
+ return (allow ?? []).map((source) => new RegExp(source));
59
+ }
60
+ function isDirective(comment, extraPatterns) {
61
+ if (comment.type === "Shebang") return true;
62
+ const patterns = extraPatterns ? DIRECTIVE_PATTERNS.concat(extraPatterns) : DIRECTIVE_PATTERNS;
63
+ return patterns.some((pattern) => pattern.test(comment.value));
64
+ }
65
+ function removalRange(sourceCode, comment) {
66
+ const text = sourceCode.text;
67
+ let start = comment.range[0];
68
+ let end = comment.range[1];
69
+ while (start > 0 && (text[start - 1] === " " || text[start - 1] === " ")) start--;
70
+ const ownLine = start === 0 || text[start - 1] === "\n";
71
+ if (ownLine) {
72
+ if (text[end] === "\r") end++;
73
+ if (text[end] === "\n") end++;
74
+ }
75
+ return [start, end];
76
+ }
77
+ function removeSuggestion(sourceCode, comment) {
78
+ return {
79
+ messageId: "removeComment",
80
+ fix: (fixer) => fixer.removeRange(removalRange(sourceCode, comment))
81
+ };
82
+ }
83
+
84
+ // src/rules/doc-comment-max-lines.js
85
+ var DEFAULT_MAX = 3;
86
+ var DEFAULT_ALLOWED_TAGS = ["param", "returns"];
87
+ var docCommentMaxLinesRule = {
88
+ meta: {
89
+ type: "suggestion",
90
+ docs: {
91
+ description: "Cap a doc comment at a few lines and allow only @param / @returns block tags (RV-1, D-CMT-3)"
92
+ },
93
+ schema: [
94
+ {
95
+ type: "object",
96
+ properties: {
97
+ max: { type: "integer", minimum: 1 },
98
+ allowedTags: { type: "array", items: { type: "string" } },
99
+ bannedTags: { type: "array", items: { type: "string" } }
100
+ },
101
+ additionalProperties: false
102
+ }
103
+ ],
104
+ messages: {
105
+ tooLong: "RV-1: doc comment is {{actual}} lines; the cap is {{max}}.",
106
+ bannedTag: "RV-1: @{{tag}} is not allowed in a doc comment (allowed: {{allowed}})."
107
+ }
108
+ },
109
+ create(context) {
110
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
111
+ const options = context.options[0] ?? {};
112
+ const max = options.max ?? DEFAULT_MAX;
113
+ const allowed = new Set(options.allowedTags ?? DEFAULT_ALLOWED_TAGS);
114
+ for (const tag of options.bannedTags ?? []) allowed.delete(tag);
115
+ const allowedText = [...allowed].map((tag) => `@${tag}`).join(", ") || "none";
116
+ return {
117
+ Program() {
118
+ for (const comment of sourceCode.getAllComments()) {
119
+ if (!isDocBlock(comment) || isTypeAnnotationDoc(comment)) continue;
120
+ const lines = docBodyLines(comment);
121
+ if (lines.length > max)
122
+ context.report({
123
+ loc: comment.loc,
124
+ messageId: "tooLong",
125
+ data: { actual: String(lines.length), max: String(max) }
126
+ });
127
+ for (const tag of blockTags(lines))
128
+ if (!allowed.has(tag))
129
+ context.report({
130
+ loc: comment.loc,
131
+ messageId: "bannedTag",
132
+ data: { tag, allowed: allowedText }
133
+ });
134
+ }
135
+ }
136
+ };
137
+ }
138
+ };
139
+ var doc_comment_max_lines_default = { rules: { "doc-comment-max-lines": docCommentMaxLinesRule } };
140
+
141
+ // src/rules/doc-comment-public-only.js
142
+ var EXPORT_TYPES = /* @__PURE__ */ new Set([
143
+ "ExportNamedDeclaration",
144
+ "ExportDefaultDeclaration",
145
+ "ExportAllDeclaration",
146
+ "TSExportAssignment"
147
+ ]);
148
+ var PASS_THROUGH = /* @__PURE__ */ new Set([
149
+ "MethodDefinition",
150
+ "PropertyDefinition",
151
+ "AccessorProperty",
152
+ "TSAbstractMethodDefinition",
153
+ "TSAbstractPropertyDefinition",
154
+ "TSAbstractAccessorProperty",
155
+ "TSIndexSignature",
156
+ "ClassBody",
157
+ "ClassDeclaration",
158
+ "ClassExpression",
159
+ "TSInterfaceBody",
160
+ "TSInterfaceDeclaration",
161
+ "TSPropertySignature",
162
+ "TSMethodSignature",
163
+ "TSTypeLiteral",
164
+ "TSTypeAnnotation",
165
+ "TSTypeAliasDeclaration",
166
+ "TSIntersectionType",
167
+ "TSUnionType",
168
+ "TSEnumDeclaration",
169
+ "TSEnumBody",
170
+ "TSEnumMember",
171
+ "TSModuleBlock",
172
+ "TSModuleDeclaration",
173
+ "TSDeclareFunction",
174
+ "VariableDeclaration",
175
+ "VariableDeclarator",
176
+ "ObjectExpression",
177
+ "Property",
178
+ "TSAsExpression",
179
+ "TSSatisfiesExpression"
180
+ ]);
181
+ var HIDDEN_ACCESSIBILITY = /* @__PURE__ */ new Set(["private", "protected"]);
182
+ function isHiddenMember(node) {
183
+ if (HIDDEN_ACCESSIBILITY.has(node.accessibility)) return true;
184
+ return node.key?.type === "PrivateIdentifier";
185
+ }
186
+ function isAmbientModule(node) {
187
+ return node.type === "TSModuleDeclaration" && (node.declare === true || node.global === true);
188
+ }
189
+ function isNamed(node, name) {
190
+ return node?.type === "Identifier" && node.name === name;
191
+ }
192
+ function isCommonJsExport(node) {
193
+ if (node.type !== "ExpressionStatement") return false;
194
+ const expr = node.expression;
195
+ if (expr.type !== "AssignmentExpression" || expr.left.type !== "MemberExpression") return false;
196
+ const target = expr.left.object;
197
+ const isModuleExports = isNamed(target, "module") && isNamed(expr.left.property, "exports");
198
+ const isModuleExportsMember = target.type === "MemberExpression" && isNamed(target.object, "module") && isNamed(target.property, "exports");
199
+ return isNamed(target, "exports") || isModuleExports || isModuleExportsMember;
200
+ }
201
+ function declaredNames(node) {
202
+ if (node.type === "VariableDeclaration")
203
+ return node.declarations.filter((d) => d.id.type === "Identifier").map((d) => d.id.name);
204
+ if (node.id?.type === "Identifier") return [node.id.name];
205
+ return [];
206
+ }
207
+ function collectExportedNames(program) {
208
+ const names = /* @__PURE__ */ new Set();
209
+ for (const statement of program.body) {
210
+ if (statement.type === "ExportNamedDeclaration" && !statement.source) {
211
+ for (const spec of statement.specifiers) if (spec.local.type === "Identifier") names.add(spec.local.name);
212
+ }
213
+ if (statement.type === "ExportDefaultDeclaration" && statement.declaration.type === "Identifier")
214
+ names.add(statement.declaration.name);
215
+ if (statement.type === "TSExportAssignment" && statement.expression.type === "Identifier")
216
+ names.add(statement.expression.name);
217
+ }
218
+ return names;
219
+ }
220
+ function isTopLevelPublic(node, exportedNames) {
221
+ if (EXPORT_TYPES.has(node.type) || isAmbientModule(node) || isCommonJsExport(node)) return true;
222
+ return declaredNames(node).some((name) => exportedNames.has(name));
223
+ }
224
+ function isPublic(start, exportedNames) {
225
+ let current = start;
226
+ while (current.parent && current.parent.type !== "Program") {
227
+ if (isHiddenMember(current)) return false;
228
+ const parent = current.parent;
229
+ if (EXPORT_TYPES.has(parent.type) || isAmbientModule(parent)) return true;
230
+ if (!PASS_THROUGH.has(parent.type)) return false;
231
+ current = parent;
232
+ }
233
+ if (isHiddenMember(current)) return false;
234
+ return isTopLevelPublic(current, exportedNames);
235
+ }
236
+ function documentedNode(sourceCode, comment) {
237
+ const token = sourceCode.getTokenAfter(comment, { includeComments: false });
238
+ if (!token) return null;
239
+ let node = sourceCode.getNodeByRangeIndex(token.range[0]);
240
+ while (node?.parent && node.parent.type !== "Program" && node.parent.range[0] === node.range[0])
241
+ node = node.parent;
242
+ return node && node.type !== "Program" ? node : null;
243
+ }
244
+ var docCommentPublicOnlyRule = {
245
+ meta: {
246
+ type: "suggestion",
247
+ docs: {
248
+ description: "Allow a doc comment only on an exported declaration or a public member of one (RV-1)"
249
+ },
250
+ schema: [],
251
+ messages: {
252
+ 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."
253
+ }
254
+ },
255
+ create(context) {
256
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
257
+ return {
258
+ Program(program) {
259
+ const exportedNames = collectExportedNames(program);
260
+ for (const comment of sourceCode.getAllComments()) {
261
+ if (!isDocBlock(comment) || isTypeAnnotationDoc(comment)) continue;
262
+ const node = documentedNode(sourceCode, comment);
263
+ if (node && isPublic(node, exportedNames)) continue;
264
+ context.report({ loc: comment.loc, messageId: "notPublic" });
265
+ }
266
+ }
267
+ };
268
+ }
269
+ };
270
+ var doc_comment_public_only_default = { rules: { "doc-comment-public-only": docCommentPublicOnlyRule } };
271
+
4
272
  // src/rules/enforce-function-style.js
5
273
  function isJSX(node) {
6
274
  return node && (node.type === "JSXElement" || node.type === "JSXFragment");
@@ -854,6 +1122,45 @@ var i18n_param_names_default = {
854
1122
  "i18n-param-names": rule2
855
1123
  }
856
1124
  };
1125
+
1126
+ // src/rules/no-comments.js
1127
+ var noCommentsRule = {
1128
+ meta: {
1129
+ type: "suggestion",
1130
+ hasSuggestions: true,
1131
+ docs: {
1132
+ description: "Disallow code comments: intent goes in names, rules in test names, context in the task doc and commit (RV-2)"
1133
+ },
1134
+ schema: [
1135
+ {
1136
+ type: "object",
1137
+ properties: { allow: { type: "array", items: { type: "string" } } },
1138
+ additionalProperties: false
1139
+ }
1140
+ ],
1141
+ messages: {
1142
+ noComment: "RV-2: no code comments. Put intent in names, business rules in test names, context in the task doc or commit message.",
1143
+ removeComment: "Remove this comment."
1144
+ }
1145
+ },
1146
+ create(context) {
1147
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
1148
+ const extra = compileAllow(context.options[0]?.allow);
1149
+ return {
1150
+ Program() {
1151
+ for (const comment of sourceCode.getAllComments()) {
1152
+ if (isDocBlock(comment) || isDirective(comment, extra)) continue;
1153
+ context.report({
1154
+ loc: comment.loc,
1155
+ messageId: "noComment",
1156
+ suggest: [removeSuggestion(sourceCode, comment)]
1157
+ });
1158
+ }
1159
+ }
1160
+ };
1161
+ }
1162
+ };
1163
+ var no_comments_default = { rules: { "no-comments": noCommentsRule } };
857
1164
  function isPureReExportFile(programNode) {
858
1165
  const { body } = programNode;
859
1166
  if (body.length === 0) return false;
@@ -1430,6 +1737,75 @@ var no_product_imports_in_shared_default = {
1430
1737
  }
1431
1738
  };
1432
1739
 
1740
+ // src/rules/no-raw-color-literal.js
1741
+ var FULL_HEX_COLOR = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
1742
+ var FUNCTIONAL_COLOR = /\b(?:rgba?|hsla?)\s*\(/;
1743
+ function containsRawColor(text) {
1744
+ if (typeof text !== "string" || text.length === 0) return false;
1745
+ if (FULL_HEX_COLOR.test(text.trim())) return true;
1746
+ return FUNCTIONAL_COLOR.test(text);
1747
+ }
1748
+ function isAllowedFile(filename, allow) {
1749
+ if (typeof filename !== "string") return false;
1750
+ const normalised = filename.split("\\").join("/");
1751
+ return allow.some((fragment) => normalised.includes(fragment));
1752
+ }
1753
+ var noRawColorLiteralRule = {
1754
+ meta: {
1755
+ type: "problem",
1756
+ docs: {
1757
+ description: "Disallow raw colour literals (hex / rgb() / hsl()) in app code. Colours belong in @dloizides/design-tokens and reach components through the theme.",
1758
+ category: "Best Practices",
1759
+ recommended: true
1760
+ },
1761
+ schema: [
1762
+ {
1763
+ type: "object",
1764
+ properties: {
1765
+ allow: {
1766
+ type: "array",
1767
+ items: { type: "string" }
1768
+ }
1769
+ },
1770
+ additionalProperties: false
1771
+ }
1772
+ ],
1773
+ messages: {
1774
+ rawColor: 'Raw colour literal "{{value}}" \u2014 use a design token instead (@dloizides/design-tokens via the theme). Hardcoded colours make a rebrand a find-and-replace across every file.'
1775
+ }
1776
+ },
1777
+ create(context) {
1778
+ const options = context.options[0] ?? {};
1779
+ const allow = Array.isArray(options.allow) ? options.allow : [];
1780
+ const filename = typeof context.getFilename === "function" ? context.getFilename() : context.filename;
1781
+ if (isAllowedFile(filename, allow)) return {};
1782
+ const report = (node, rawValue) => {
1783
+ const value = rawValue.trim();
1784
+ const display = value.length > 40 ? `${value.slice(0, 40)}\u2026` : value;
1785
+ context.report({ node, messageId: "rawColor", data: { value: display } });
1786
+ };
1787
+ return {
1788
+ Literal(node) {
1789
+ if (typeof node.value !== "string") return;
1790
+ if (!containsRawColor(node.value)) return;
1791
+ report(node, node.value);
1792
+ },
1793
+ // Template literals: check each static chunk, so an interpolated value
1794
+ // (`${primary}`) is fine but a baked-in rgba(...) chunk is not.
1795
+ TemplateElement(node) {
1796
+ const raw = node.value?.raw;
1797
+ if (!containsRawColor(raw)) return;
1798
+ report(node, raw);
1799
+ }
1800
+ };
1801
+ }
1802
+ };
1803
+ var no_raw_color_literal_default = {
1804
+ rules: {
1805
+ "no-raw-color-literal": noRawColorLiteralRule
1806
+ }
1807
+ };
1808
+
1433
1809
  // src/rules/prefer-const-enum.js
1434
1810
  function toPascalCase(value) {
1435
1811
  const words = value.replace(/([a-z])([A-Z])/g, "$1 $2").split(/[-_\s]+/).filter((w) => w.length > 0);
@@ -1996,6 +2372,8 @@ var smart_max_lines_default = {
1996
2372
  // src/eslint/plugin.ts
1997
2373
  var PLUGIN_VERSION = "1.0.0";
1998
2374
  var ruleModules = [
2375
+ doc_comment_max_lines_default,
2376
+ doc_comment_public_only_default,
1999
2377
  enforce_function_style_default,
2000
2378
  enforce_module_structure_default,
2001
2379
  enforce_route_preload_default,
@@ -2004,12 +2382,14 @@ var ruleModules = [
2004
2382
  i18n_interpolation_default,
2005
2383
  i18n_param_names_default,
2006
2384
  no_barrel_companion_file_default,
2385
+ no_comments_default,
2007
2386
  no_duplicate_nav_prefix_default,
2008
2387
  no_duplicate_shared_patterns_default,
2009
2388
  no_generated_models_barrel_value_import_default,
2010
2389
  no_null_check_default,
2011
2390
  no_optional_undefined_default,
2012
2391
  no_product_imports_in_shared_default,
2392
+ no_raw_color_literal_default,
2013
2393
  prefer_const_enum_default,
2014
2394
  require_stable_hook_args_default,
2015
2395
  smart_max_lines_default
@@ -2049,6 +2429,22 @@ function oneRulePlugin(name, rule3) {
2049
2429
  };
2050
2430
  }
2051
2431
 
2052
- export { legacyPlugins, plugin, ruleNames, rules };
2432
+ // src/eslint/configs.ts
2433
+ var DOC_COMMENT_MAX_LINES = 3;
2434
+ var COMMENT_RULE_NAMES = [
2435
+ "no-comments",
2436
+ "doc-comment-public-only",
2437
+ "doc-comment-max-lines"
2438
+ ];
2439
+ var commentsConfig = {
2440
+ plugins: { "@dloizides": plugin },
2441
+ rules: {
2442
+ "@dloizides/no-comments": "error",
2443
+ "@dloizides/doc-comment-public-only": "error",
2444
+ "@dloizides/doc-comment-max-lines": ["error", { max: DOC_COMMENT_MAX_LINES }]
2445
+ }
2446
+ };
2447
+
2448
+ export { COMMENT_RULE_NAMES, commentsConfig, legacyPlugins, plugin, ruleNames, rules };
2053
2449
  //# sourceMappingURL=index.mjs.map
2054
2450
  //# sourceMappingURL=index.mjs.map