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.
@@ -20,7 +20,7 @@ jobs:
20
20
  - name: Install NodeJS
21
21
  uses: actions/setup-node@v1
22
22
  with:
23
- node-version: 24.x
23
+ node-version: 26.x
24
24
  registry-url: https://registry.npmjs.org
25
25
 
26
26
  - name: Verify versions
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "eslint-plugin-crisp",
3
- "version": "1.7.24",
3
+ "version": "1.7.25",
4
4
  "description": "Custom ESLint Rules for Crisp",
5
5
  "author": "Crisp IM SAS",
6
6
  "main": "index.js",
@@ -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
+ });