@dloizides/frontend-devtools 1.3.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.
@@ -84,11 +84,27 @@ function removeSuggestion(sourceCode, comment) {
84
84
  // src/rules/doc-comment-max-lines.js
85
85
  var DEFAULT_MAX = 3;
86
86
  var DEFAULT_ALLOWED_TAGS = ["param", "returns"];
87
+ var DEFAULT_SUMMARY_MAX_LINES = 1;
88
+ var DEFAULT_LINE_MAX_CHARS = 120;
89
+ var CALL_CHAIN = /(→|->|^Flow\s*:)/i;
90
+ var PARAM_LINE = /^@(param|returns?)\b/i;
91
+ function firstShapeProblem(lines, limits) {
92
+ if (lines.length > limits.max)
93
+ return { messageId: "tooLong", data: { actual: String(lines.length), max: String(limits.max) } };
94
+ if (lines.some((line) => CALL_CHAIN.test(line))) return { messageId: "callChain", data: {} };
95
+ const summary = lines.filter((line) => !PARAM_LINE.test(line)).length;
96
+ if (summary > limits.summaryMaxLines)
97
+ return { messageId: "summaryTooLong", data: { actual: String(summary), max: String(limits.summaryMaxLines) } };
98
+ const long = lines.find((line) => line.length > limits.lineMaxChars);
99
+ if (long !== void 0)
100
+ return { messageId: "lineTooLong", data: { actual: String(long.length), max: String(limits.lineMaxChars) } };
101
+ return null;
102
+ }
87
103
  var docCommentMaxLinesRule = {
88
104
  meta: {
89
105
  type: "suggestion",
90
106
  docs: {
91
- description: "Cap a doc comment at a few lines and allow only @param / @returns block tags (RV-1, D-CMT-3)"
107
+ 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)"
92
108
  },
93
109
  schema: [
94
110
  {
@@ -96,20 +112,29 @@ var docCommentMaxLinesRule = {
96
112
  properties: {
97
113
  max: { type: "integer", minimum: 1 },
98
114
  allowedTags: { type: "array", items: { type: "string" } },
99
- bannedTags: { type: "array", items: { type: "string" } }
115
+ bannedTags: { type: "array", items: { type: "string" } },
116
+ summaryMaxLines: { type: "integer", minimum: 1 },
117
+ lineMaxChars: { type: "integer", minimum: 1 }
100
118
  },
101
119
  additionalProperties: false
102
120
  }
103
121
  ],
104
122
  messages: {
105
123
  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}})."
124
+ bannedTag: "RV-1: @{{tag}} is not allowed in a doc comment (allowed: {{allowed}}).",
125
+ summaryTooLong: "RV-1: doc summary is {{actual}} lines; it must be one line saying what the member is for.",
126
+ callChain: "RV-1: no call chain or Flow: in a doc comment; say what the member is for, not how it runs.",
127
+ lineTooLong: "RV-1: doc line is {{actual}} chars; the cap is {{max}}."
107
128
  }
108
129
  },
109
130
  create(context) {
110
131
  const sourceCode = context.sourceCode ?? context.getSourceCode();
111
132
  const options = context.options[0] ?? {};
112
- const max = options.max ?? DEFAULT_MAX;
133
+ const limits = {
134
+ max: options.max ?? DEFAULT_MAX,
135
+ summaryMaxLines: options.summaryMaxLines ?? DEFAULT_SUMMARY_MAX_LINES,
136
+ lineMaxChars: options.lineMaxChars ?? DEFAULT_LINE_MAX_CHARS
137
+ };
113
138
  const allowed = new Set(options.allowedTags ?? DEFAULT_ALLOWED_TAGS);
114
139
  for (const tag of options.bannedTags ?? []) allowed.delete(tag);
115
140
  const allowedText = [...allowed].map((tag) => `@${tag}`).join(", ") || "none";
@@ -118,19 +143,12 @@ var docCommentMaxLinesRule = {
118
143
  for (const comment of sourceCode.getAllComments()) {
119
144
  if (!isDocBlock(comment) || isTypeAnnotationDoc(comment)) continue;
120
145
  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
- });
146
+ const banned = blockTags(lines).filter((tag) => !allowed.has(tag));
147
+ for (const tag of banned)
148
+ context.report({ loc: comment.loc, messageId: "bannedTag", data: { tag, allowed: allowedText } });
149
+ if (banned.length > 0) continue;
150
+ const problem = firstShapeProblem(lines, limits);
151
+ if (problem) context.report({ loc: comment.loc, ...problem });
134
152
  }
135
153
  }
136
154
  };