eslint-plugin-crisp 1.7.24 → 1.7.25
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/.github/workflows/build.yml +1 -1
- package/README.md +1 -0
- package/index.js +2 -0
- package/package.json +1 -1
- package/recommended-vue.js +1 -0
- package/recommended.js +2 -1
- package/rules/jsdoc-typedef-align.js +163 -0
- package/tests/rules/jsdoc-typedef-align.test.js +110 -0
package/README.md
CHANGED
|
@@ -186,6 +186,7 @@ Each item has emojis denoting:
|
|
|
186
186
|
| [crisp/jsdoc-enforce-classdesc](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-enforce-classdesc.js) | Ensures JSDoc for class headers to include a non-empty `@classdesc` | 🟠 | 🟢 |
|
|
187
187
|
| [crisp/jsdoc-require-description-uppercase](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-require-description-uppercase.js) | Requires descriptions to start with an uppercase character | 🟠 | 🟢 |
|
|
188
188
|
| [crisp/jsdoc-description-length](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-description-length.js) | Enforces a maximum length for JSDoc descriptions | 🟠 | 🟢 | 🟣 |
|
|
189
|
+
| [crisp/jsdoc-typedef-align](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-typedef-align.js) | Enforces alignment of multiline `@typedef` and `@property` definitions | 🟠 | 🟢 |
|
|
189
190
|
| [crisp/jsdoc-no-param-return](https://github.com/crisp-oss/eslint-plugin-crisp/blob/master/rules/jsdoc-no-param-return.js) | Forbids `@param` and `@return` tags in JSDoc, relying on the TypeScript signature instead | | | 🟣 |
|
|
190
191
|
|
|
191
192
|
#### General Vue rules
|
package/index.js
CHANGED
|
@@ -21,6 +21,7 @@ import ruleJsdocEnforceClassdesc from "./rules/jsdoc-enforce-classdesc.js";
|
|
|
21
21
|
import ruleJsdocNoParamReturn from "./rules/jsdoc-no-param-return.js";
|
|
22
22
|
import ruleJsdocRequireDescriptionUppercase from "./rules/jsdoc-require-description-uppercase.js";
|
|
23
23
|
import ruleJsdocDescriptionLength from "./rules/jsdoc-description-length.js";
|
|
24
|
+
import ruleJsdocTypedefAlign from "./rules/jsdoc-typedef-align.js";
|
|
24
25
|
import ruleLoggerArguments from "./rules/logger-arguments.js";
|
|
25
26
|
import ruleMethodsNaming from "./rules/methods-naming.js";
|
|
26
27
|
import ruleMethodsOrdering from "./rules/methods-ordering.js";
|
|
@@ -99,6 +100,7 @@ const plugin = {
|
|
|
99
100
|
"jsdoc-no-param-return": ruleJsdocNoParamReturn,
|
|
100
101
|
"jsdoc-require-description-uppercase": ruleJsdocRequireDescriptionUppercase,
|
|
101
102
|
"jsdoc-description-length": ruleJsdocDescriptionLength,
|
|
103
|
+
"jsdoc-typedef-align": ruleJsdocTypedefAlign,
|
|
102
104
|
"logger-arguments": ruleLoggerArguments,
|
|
103
105
|
"methods-naming": ruleMethodsNaming,
|
|
104
106
|
"methods-ordering": ruleMethodsOrdering,
|
package/package.json
CHANGED
package/recommended-vue.js
CHANGED
|
@@ -256,6 +256,7 @@ export default function configRecommendedVue(pluginCrisp) {
|
|
|
256
256
|
"crisp/jsdoc-enforce-classdesc": "error",
|
|
257
257
|
"crisp/jsdoc-require-description-uppercase": "error",
|
|
258
258
|
"crisp/jsdoc-description-length": "error",
|
|
259
|
+
"crisp/jsdoc-typedef-align": "error",
|
|
259
260
|
|
|
260
261
|
// General Vue rules
|
|
261
262
|
"vue/attributes-order": [
|
package/recommended.js
CHANGED
|
@@ -247,7 +247,8 @@ export default function configRecommended(pluginCrisp) {
|
|
|
247
247
|
"crisp/jsdoc-check-indentation": "error",
|
|
248
248
|
"crisp/jsdoc-enforce-classdesc": "error",
|
|
249
249
|
"crisp/jsdoc-require-description-uppercase": "error",
|
|
250
|
-
"crisp/jsdoc-description-length": "error"
|
|
250
|
+
"crisp/jsdoc-description-length": "error",
|
|
251
|
+
"crisp/jsdoc-typedef-align": "error"
|
|
251
252
|
}
|
|
252
253
|
}
|
|
253
254
|
];
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
const TAG_REGEX = /^(\s*\*\s)@(typedef|property|prop)(\s+)/;
|
|
2
|
+
const NAME_REGEX = /^(\s+)(\S+)/;
|
|
3
|
+
|
|
4
|
+
// Find the end index (exclusive) of a balanced "{...}" type, or -1
|
|
5
|
+
function findTypeEnd(line, start) {
|
|
6
|
+
if (line[start] !== "{") {
|
|
7
|
+
return -1;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
let depth = 0;
|
|
11
|
+
|
|
12
|
+
for (let i = start; i < line.length; i++) {
|
|
13
|
+
if (line[i] === "{") {
|
|
14
|
+
depth++;
|
|
15
|
+
} else if (line[i] === "}") {
|
|
16
|
+
depth--;
|
|
17
|
+
|
|
18
|
+
if (depth === 0) {
|
|
19
|
+
return i + 1;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
return -1;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
// Parse a typedef or property tag line, returns null if not a tag, false if unsupported
|
|
28
|
+
function parseTagLine(line) {
|
|
29
|
+
const tagMatch = line.match(TAG_REGEX);
|
|
30
|
+
|
|
31
|
+
if (!tagMatch) {
|
|
32
|
+
return null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const tag = tagMatch[2];
|
|
36
|
+
const tagEnd = tagMatch[1].length + 1 + tag.length;
|
|
37
|
+
const typeStart = tagMatch[0].length;
|
|
38
|
+
const typeEnd = findTypeEnd(line, typeStart);
|
|
39
|
+
|
|
40
|
+
// Multiline or malformed type, not supported
|
|
41
|
+
if (typeEnd === -1) {
|
|
42
|
+
return false;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const nameMatch = line.slice(typeEnd).match(NAME_REGEX);
|
|
46
|
+
|
|
47
|
+
if (!nameMatch) {
|
|
48
|
+
return false;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
return {
|
|
52
|
+
tag,
|
|
53
|
+
tagEnd,
|
|
54
|
+
typeStart,
|
|
55
|
+
typeEnd,
|
|
56
|
+
type: line.slice(typeStart, typeEnd),
|
|
57
|
+
nameGap: nameMatch[1].length,
|
|
58
|
+
nameStart: typeEnd + nameMatch[1].length
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export default {
|
|
63
|
+
meta: {
|
|
64
|
+
type: "layout",
|
|
65
|
+
docs: {
|
|
66
|
+
description: "enforce alignment of multiline @typedef definitions",
|
|
67
|
+
category: "Stylistic Issues",
|
|
68
|
+
recommended: false
|
|
69
|
+
},
|
|
70
|
+
fixable: "whitespace",
|
|
71
|
+
schema: [],
|
|
72
|
+
messages: {
|
|
73
|
+
typedefAlignment: "@typedef must be aligned with the @property definitions",
|
|
74
|
+
propertyAlignment: "@property names must be aligned in one column, one space after the longest type"
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
|
|
78
|
+
create: function(context) {
|
|
79
|
+
const sourceCode = context.sourceCode;
|
|
80
|
+
|
|
81
|
+
return {
|
|
82
|
+
Program: function(node) {
|
|
83
|
+
const comments = sourceCode.getAllComments(node);
|
|
84
|
+
|
|
85
|
+
comments
|
|
86
|
+
.filter(comment => comment.type === "Block" && comment.value.startsWith("*"))
|
|
87
|
+
.forEach(comment => {
|
|
88
|
+
const lines = comment.value.split("\n");
|
|
89
|
+
const entries = [];
|
|
90
|
+
let offset = 0;
|
|
91
|
+
let supported = true;
|
|
92
|
+
|
|
93
|
+
// Offset of the comment value in the source code (after "/*")
|
|
94
|
+
const base = comment.range[0] + 2;
|
|
95
|
+
|
|
96
|
+
for (const line of lines) {
|
|
97
|
+
const parsed = parseTagLine(line);
|
|
98
|
+
|
|
99
|
+
if (parsed === false) {
|
|
100
|
+
supported = false;
|
|
101
|
+
} else if (parsed) {
|
|
102
|
+
entries.push({ ...parsed, offset });
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
offset += line.length + 1;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const typedefs = entries.filter(entry => entry.tag === "typedef");
|
|
109
|
+
const properties = entries.filter(entry => entry.tag !== "typedef");
|
|
110
|
+
|
|
111
|
+
if (!supported || typedefs.length !== 1 || properties.length === 0) {
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
const tagWidth = Math.max(...entries.map(entry => entry.tag.length));
|
|
116
|
+
|
|
117
|
+
// A typedef name is aligned with the property names when padded or already in their column
|
|
118
|
+
const typedefNameAligned = typedefs[0].nameGap > 1
|
|
119
|
+
|| properties.every(entry => entry.nameStart === typedefs[0].nameStart);
|
|
120
|
+
|
|
121
|
+
const typeWidth = Math.max(
|
|
122
|
+
...properties.map(entry => entry.type.length),
|
|
123
|
+
...(typedefNameAligned ? [typedefs[0].type.length] : [])
|
|
124
|
+
);
|
|
125
|
+
|
|
126
|
+
for (const entry of entries) {
|
|
127
|
+
const isTypedef = entry.tag === "typedef";
|
|
128
|
+
const alignName = !isTypedef || typedefNameAligned;
|
|
129
|
+
const tagSpaces = " ".repeat(tagWidth - entry.tag.length + 1);
|
|
130
|
+
|
|
131
|
+
// Typedef only aligns its type, unless its name is aligned too
|
|
132
|
+
const expected = alignName
|
|
133
|
+
? tagSpaces + entry.type + " ".repeat(typeWidth - entry.type.length + 1)
|
|
134
|
+
: tagSpaces;
|
|
135
|
+
|
|
136
|
+
const start = entry.tagEnd;
|
|
137
|
+
const end = alignName ? entry.nameStart : entry.typeStart;
|
|
138
|
+
const current = comment.value.slice(entry.offset + start, entry.offset + end);
|
|
139
|
+
|
|
140
|
+
if (current === expected) {
|
|
141
|
+
continue;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
context.report({
|
|
145
|
+
loc: {
|
|
146
|
+
start: sourceCode.getLocFromIndex(base + entry.offset + start),
|
|
147
|
+
end: sourceCode.getLocFromIndex(base + entry.offset + end)
|
|
148
|
+
},
|
|
149
|
+
messageId: isTypedef ? "typedefAlignment" : "propertyAlignment",
|
|
150
|
+
|
|
151
|
+
fix(fixer) {
|
|
152
|
+
return fixer.replaceTextRange(
|
|
153
|
+
[base + entry.offset + start, base + entry.offset + end],
|
|
154
|
+
expected
|
|
155
|
+
);
|
|
156
|
+
}
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
};
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import rule from "../../rules/jsdoc-typedef-align.js";
|
|
2
|
+
import createRuleTester from "../rule-tester.js";
|
|
3
|
+
|
|
4
|
+
const ruleTester = createRuleTester();
|
|
5
|
+
|
|
6
|
+
ruleTester.run("jsdoc-typedef-align", rule, {
|
|
7
|
+
valid: [
|
|
8
|
+
// Aligned typedef and properties
|
|
9
|
+
"/**\n * @typedef {object} MapParams\n * @property {number} concurrency\n * @property {Website[]} websites\n */",
|
|
10
|
+
|
|
11
|
+
// Optional and nested properties
|
|
12
|
+
"/**\n * @typedef {object} Params\n * @property {object} [package]\n * @property {string} package.name\n */",
|
|
13
|
+
|
|
14
|
+
// Description line before the typedef
|
|
15
|
+
"/**\n * NotificationAttributes\n * @typedef {object} NotificationAttributes\n * @property {string} id\n * @property {User | undefined} user\n */",
|
|
16
|
+
|
|
17
|
+
// Typedef name aligned with the property names is left untouched
|
|
18
|
+
"/**\n * @typedef {object} ContentWriteData\n * @property {helpdesk_content_path} path\n * @property {string} [content]\n */",
|
|
19
|
+
|
|
20
|
+
// Typedef name aligned, widest type is a property
|
|
21
|
+
"/**\n * @typedef {object} MessageOptionsExtra\n * @property {object} [options]\n * @property {boolean} [options.resolve]\n */",
|
|
22
|
+
|
|
23
|
+
// Typedef name aligned, widest type is the typedef itself
|
|
24
|
+
"/**\n * @typedef {object} Params\n * @property {any} value\n */",
|
|
25
|
+
|
|
26
|
+
// Indented block
|
|
27
|
+
"class A {\n /**\n * @typedef {object} Params\n * @property {string} name\n */\n}",
|
|
28
|
+
|
|
29
|
+
// Single line typedef is ignored
|
|
30
|
+
"/** @typedef {string} Name */",
|
|
31
|
+
|
|
32
|
+
// Typedef without properties is ignored
|
|
33
|
+
"/**\n * @typedef {Model & Attributes} Notification\n */",
|
|
34
|
+
|
|
35
|
+
// Multiline property types are ignored
|
|
36
|
+
"/**\n * @typedef {object} AppInterface\n * @property {{\n amqp?: string;\n }} managers\n * @property {string} path\n */",
|
|
37
|
+
|
|
38
|
+
// Regular comments are ignored
|
|
39
|
+
"/*\n * @typedef {object} Params\n * @property {string} name\n */"
|
|
40
|
+
],
|
|
41
|
+
|
|
42
|
+
invalid: [
|
|
43
|
+
// Typedef not aligned with properties and property names not aligned
|
|
44
|
+
{
|
|
45
|
+
code: "/**\n * @typedef {object} MapParams\n * @property {number} concurrency\n * @property {Billing} card\n * @property {Website[]} websites\n */",
|
|
46
|
+
output: "/**\n * @typedef {object} MapParams\n * @property {number} concurrency\n * @property {Billing} card\n * @property {Website[]} websites\n */",
|
|
47
|
+
errors: [
|
|
48
|
+
{ messageId: "typedefAlignment" },
|
|
49
|
+
{ messageId: "propertyAlignment" },
|
|
50
|
+
{ messageId: "propertyAlignment" }
|
|
51
|
+
]
|
|
52
|
+
},
|
|
53
|
+
|
|
54
|
+
// Only the typedef is misaligned
|
|
55
|
+
{
|
|
56
|
+
code: "/**\n * @typedef {object} Params\n * @property {string} name\n */",
|
|
57
|
+
output: "/**\n * @typedef {object} Params\n * @property {string} name\n */",
|
|
58
|
+
errors: [{ messageId: "typedefAlignment" }]
|
|
59
|
+
},
|
|
60
|
+
|
|
61
|
+
// A property was added with a longer type and others were not realigned
|
|
62
|
+
{
|
|
63
|
+
code: "/**\n * @typedef {object} Website\n * @property {string} id\n * @property {\"auto\" | \"dark\"} mode\n */",
|
|
64
|
+
output: "/**\n * @typedef {object} Website\n * @property {string} id\n * @property {\"auto\" | \"dark\"} mode\n */",
|
|
65
|
+
errors: [{ messageId: "propertyAlignment" }]
|
|
66
|
+
},
|
|
67
|
+
|
|
68
|
+
// Stale padding left after removing the longest property
|
|
69
|
+
{
|
|
70
|
+
code: "/**\n * @typedef {object} Params\n * @property {any} params\n * @property {string} [method]\n */",
|
|
71
|
+
output: "/**\n * @typedef {object} Params\n * @property {any} params\n * @property {string} [method]\n */",
|
|
72
|
+
errors: [
|
|
73
|
+
{ messageId: "propertyAlignment" },
|
|
74
|
+
{ messageId: "propertyAlignment" }
|
|
75
|
+
]
|
|
76
|
+
},
|
|
77
|
+
|
|
78
|
+
// Typedef name aligned on a stale column is realigned with the properties
|
|
79
|
+
{
|
|
80
|
+
code: "/**\n * @typedef {object} QuickTourStep\n * @property {string} id\n * @property {string} [label]\n * @property {boolean} [hidden]\n */",
|
|
81
|
+
output: "/**\n * @typedef {object} QuickTourStep\n * @property {string} id\n * @property {string} [label]\n * @property {boolean} [hidden]\n */",
|
|
82
|
+
errors: [{ messageId: "typedefAlignment" }]
|
|
83
|
+
},
|
|
84
|
+
|
|
85
|
+
// Typedef name aligned, properties padded too much
|
|
86
|
+
{
|
|
87
|
+
code: "/**\n * @typedef {object} APIRequest\n * @property {any} params\n * @property {string} [method]\n */",
|
|
88
|
+
output: "/**\n * @typedef {object} APIRequest\n * @property {any} params\n * @property {string} [method]\n */",
|
|
89
|
+
errors: [
|
|
90
|
+
{ messageId: "typedefAlignment" },
|
|
91
|
+
{ messageId: "propertyAlignment" },
|
|
92
|
+
{ messageId: "propertyAlignment" }
|
|
93
|
+
]
|
|
94
|
+
},
|
|
95
|
+
|
|
96
|
+
// Description after the name is preserved
|
|
97
|
+
{
|
|
98
|
+
code: "/**\n * @typedef {object} Params\n * @property {string} name The name\n * @property {number} age The age\n */",
|
|
99
|
+
output: "/**\n * @typedef {object} Params\n * @property {string} name The name\n * @property {number} age The age\n */",
|
|
100
|
+
errors: [{ messageId: "typedefAlignment" }]
|
|
101
|
+
},
|
|
102
|
+
|
|
103
|
+
// Indented block
|
|
104
|
+
{
|
|
105
|
+
code: "class A {\n /**\n * @typedef {object} Params\n * @property {number} id\n * @property {string} name\n */\n}",
|
|
106
|
+
output: "class A {\n /**\n * @typedef {object} Params\n * @property {number} id\n * @property {string} name\n */\n}",
|
|
107
|
+
errors: [{ messageId: "typedefAlignment" }]
|
|
108
|
+
}
|
|
109
|
+
]
|
|
110
|
+
});
|