@jupyter/eslint-plugin 0.0.1 → 0.0.2
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/README.md +1 -26
- package/lib/index.d.ts +7 -0
- package/lib/index.js +9 -2
- package/lib/rules/plugin-activation-args.js +58 -21
- package/lib/rules/plugin-description.js +1 -1
- package/lib/utils/plugin-utils.d.ts +7 -11
- package/lib/utils/plugin-utils.js +68 -44
- package/package.json +7 -3
package/README.md
CHANGED
|
@@ -8,34 +8,9 @@ ESLint plugin for Jupyter core and extensions with early error catching and best
|
|
|
8
8
|
npm install --save-dev @jupyter/eslint-plugin
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
## Rules
|
|
12
|
-
|
|
13
|
-
- `command-described-by` - Ensure JupyterLab commands include describedBy property
|
|
14
|
-
- `plugin-activation-args` - Ensure JupyterLab plugin activation function arguments match requires and optional tokens in order
|
|
15
|
-
- `plugin-description` - Ensure JupyterLab plugins have a description property
|
|
16
|
-
|
|
17
11
|
## Usage
|
|
18
12
|
|
|
19
|
-
Add
|
|
20
|
-
|
|
21
|
-
```javascript
|
|
22
|
-
// eslint.config.js
|
|
23
|
-
import jupyterPlugin from '@jupyter/eslint-plugin';
|
|
24
|
-
|
|
25
|
-
export default [
|
|
26
|
-
{
|
|
27
|
-
files: ['**/*.ts', '**/*.tsx'],
|
|
28
|
-
plugins: {
|
|
29
|
-
jupyter: jupyterPlugin
|
|
30
|
-
},
|
|
31
|
-
rules: {
|
|
32
|
-
'jupyter/command-described-by': 'warn',
|
|
33
|
-
'jupyter/plugin-activation-args': 'warn',
|
|
34
|
-
'jupyter/plugin-description': 'warn'
|
|
35
|
-
}
|
|
36
|
-
}
|
|
37
|
-
];
|
|
38
|
-
```
|
|
13
|
+
Add `@jupyter/eslint-plugin` to the plugins section of your ESLint configuration. For detailed usage instructions and available rules, see the <link>documentation website</link>.
|
|
39
14
|
|
|
40
15
|
## License
|
|
41
16
|
|
package/lib/index.d.ts
CHANGED
|
@@ -13,6 +13,13 @@ declare const plugin: {
|
|
|
13
13
|
'jupyter/plugin-description': string;
|
|
14
14
|
};
|
|
15
15
|
};
|
|
16
|
+
'recommended-legacy': {
|
|
17
|
+
rules: {
|
|
18
|
+
'jupyter/plugin-activation-args': string;
|
|
19
|
+
'jupyter/command-described-by': string;
|
|
20
|
+
'jupyter/plugin-description': string;
|
|
21
|
+
};
|
|
22
|
+
};
|
|
16
23
|
};
|
|
17
24
|
};
|
|
18
25
|
export = plugin;
|
package/lib/index.js
CHANGED
|
@@ -20,8 +20,15 @@ const plugin = {
|
|
|
20
20
|
files: ['**/*.js', '**/*.ts', '**/*.jsx', '**/*.tsx'],
|
|
21
21
|
rules: {
|
|
22
22
|
'jupyter/plugin-activation-args': 'error',
|
|
23
|
-
'jupyter/command-described-by': '
|
|
24
|
-
'jupyter/plugin-description': '
|
|
23
|
+
'jupyter/command-described-by': 'warn',
|
|
24
|
+
'jupyter/plugin-description': 'warn'
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
'recommended-legacy': {
|
|
28
|
+
rules: {
|
|
29
|
+
'jupyter/plugin-activation-args': 'error',
|
|
30
|
+
'jupyter/command-described-by': 'warn',
|
|
31
|
+
'jupyter/plugin-description': 'warn'
|
|
25
32
|
}
|
|
26
33
|
}
|
|
27
34
|
}
|
|
@@ -25,11 +25,12 @@ function findActivateFunction(node) {
|
|
|
25
25
|
const params = activateValue.params
|
|
26
26
|
.filter((param) => param.type === 'Identifier')
|
|
27
27
|
.map(param => param.name);
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
28
|
+
const paramTypes = activateValue.params.map(param => param.type === 'Identifier' ? (0, plugin_utils_1.extractParameterType)(param) : null);
|
|
29
|
+
return {
|
|
30
|
+
node: activateProp,
|
|
31
|
+
params,
|
|
32
|
+
paramTypes,
|
|
33
|
+
};
|
|
33
34
|
}
|
|
34
35
|
return null;
|
|
35
36
|
}
|
|
@@ -54,11 +55,11 @@ function extractRequiresOptional(node) {
|
|
|
54
55
|
keyName = prop.key.value;
|
|
55
56
|
}
|
|
56
57
|
if (keyName === 'requires' && prop.value.type === 'ArrayExpression') {
|
|
57
|
-
result.requires = (0, plugin_utils_1.
|
|
58
|
+
result.requires = (0, plugin_utils_1.extractArrayElements)(prop.value);
|
|
58
59
|
}
|
|
59
60
|
else if (keyName === 'optional' &&
|
|
60
61
|
prop.value.type === 'ArrayExpression') {
|
|
61
|
-
result.optional = (0, plugin_utils_1.
|
|
62
|
+
result.optional = (0, plugin_utils_1.extractArrayElements)(prop.value);
|
|
62
63
|
}
|
|
63
64
|
}
|
|
64
65
|
return result;
|
|
@@ -90,6 +91,7 @@ const jupyterPluginActivationArgs = {
|
|
|
90
91
|
missingArgument: 'Token "{{ token }}" from requires/optional is missing in activation arguments.',
|
|
91
92
|
extraArgument: 'Activation argument "{{ arg }}" is not in requires/optional tokens.',
|
|
92
93
|
appNotFirst: 'First activation argument must be one of [{{ allowedNames }}] (JupyterFrontEnd), got "{{ arg }}".',
|
|
94
|
+
serviceManagerFirstArgNotNull: 'First activation argument for ServiceManagerPlugin must be null, got "{{ arg }}".',
|
|
93
95
|
invalidAppType: 'First activation argument "{{ arg }}" has invalid type "{{ type }}". Expected JupyterFrontEnd, JupyterLab, or Application.',
|
|
94
96
|
wrongArgumentCount: 'Expected {{ expected }} activation arguments (app + {{ tokenCount }} tokens), got {{ actual }}.'
|
|
95
97
|
},
|
|
@@ -118,7 +120,8 @@ const jupyterPluginActivationArgs = {
|
|
|
118
120
|
return {
|
|
119
121
|
VariableDeclarator(node) {
|
|
120
122
|
const varDecl = node;
|
|
121
|
-
|
|
123
|
+
const pluginKind = (0, plugin_utils_1.getJupyterPluginKind)(varDecl);
|
|
124
|
+
if (!pluginKind) {
|
|
122
125
|
return;
|
|
123
126
|
}
|
|
124
127
|
if (varDecl.init && varDecl.init.type === 'ObjectExpression') {
|
|
@@ -135,17 +138,51 @@ const jupyterPluginActivationArgs = {
|
|
|
135
138
|
// Special case, not invalid
|
|
136
139
|
return;
|
|
137
140
|
}
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
141
|
+
if (pluginKind === 'frontend') {
|
|
142
|
+
// Validation 1a: Check if first argument is one of the allowed names
|
|
143
|
+
if (params.length > 0 &&
|
|
144
|
+
(params[0] === null || !allowedFirstArgumentNames.includes(params[0]))) {
|
|
145
|
+
context.report({
|
|
146
|
+
node: activateInfo.node,
|
|
147
|
+
messageId: 'appNotFirst',
|
|
148
|
+
data: {
|
|
149
|
+
arg: params[0],
|
|
150
|
+
allowedNames: allowedFirstArgumentNames
|
|
151
|
+
.map(name => `"${name}"`)
|
|
152
|
+
.join(', ')
|
|
153
|
+
}
|
|
154
|
+
});
|
|
155
|
+
return;
|
|
156
|
+
}
|
|
157
|
+
// Validation 1b: Check if first argument type is compatible with JupyterFrontEnd
|
|
158
|
+
if (params.length > 0 && paramTypes.length > 0) {
|
|
159
|
+
const firstParamType = paramTypes[0];
|
|
160
|
+
if (!isCompatibleWithJupyterFrontEnd(firstParamType)) {
|
|
161
|
+
context.report({
|
|
162
|
+
node: activateInfo.node,
|
|
163
|
+
messageId: 'invalidAppType',
|
|
164
|
+
data: {
|
|
165
|
+
arg: params[0],
|
|
166
|
+
type: firstParamType || 'unknown'
|
|
167
|
+
}
|
|
168
|
+
});
|
|
169
|
+
return;
|
|
146
170
|
}
|
|
147
|
-
}
|
|
148
|
-
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
else if (pluginKind === 'service-manager') {
|
|
174
|
+
// Validation 1: First argument must be literal null
|
|
175
|
+
if (params.length === 0 || paramTypes[0] !== null) {
|
|
176
|
+
const firstArg = params[0] ?? 'missing';
|
|
177
|
+
context.report({
|
|
178
|
+
node: activateInfo.node,
|
|
179
|
+
messageId: 'serviceManagerFirstArgNotNull',
|
|
180
|
+
data: {
|
|
181
|
+
arg: firstArg
|
|
182
|
+
}
|
|
183
|
+
});
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
149
186
|
}
|
|
150
187
|
// Validation 1b: Check if first argument type is compatible with JupyterFrontEnd
|
|
151
188
|
if (params.length > 0 && paramTypes.length > 0) {
|
|
@@ -175,7 +212,7 @@ const jupyterPluginActivationArgs = {
|
|
|
175
212
|
});
|
|
176
213
|
}
|
|
177
214
|
// Validation 3: If parameters have type annotations, validate order
|
|
178
|
-
const actualParamTypes = paramTypes.slice(1); //
|
|
215
|
+
const actualParamTypes = paramTypes.slice(1); // First arg already validated above
|
|
179
216
|
const hasTypeInfo = actualParamTypes.some((t) => t !== null);
|
|
180
217
|
if (hasTypeInfo) {
|
|
181
218
|
// Validate that parameter types match expected token types in order
|
|
@@ -192,7 +229,7 @@ const jupyterPluginActivationArgs = {
|
|
|
192
229
|
});
|
|
193
230
|
}
|
|
194
231
|
}
|
|
195
|
-
else if (paramType !==
|
|
232
|
+
else if (paramType !== expectedToken) {
|
|
196
233
|
// Type mismatch
|
|
197
234
|
context.report({
|
|
198
235
|
node: activateInfo.node,
|
|
@@ -209,7 +246,7 @@ const jupyterPluginActivationArgs = {
|
|
|
209
246
|
context.report({
|
|
210
247
|
node: activateInfo.node,
|
|
211
248
|
messageId: 'extraArgument',
|
|
212
|
-
data: { arg: actualParams[i] }
|
|
249
|
+
data: { arg: actualParams[i + 1] }
|
|
213
250
|
});
|
|
214
251
|
}
|
|
215
252
|
}
|
|
@@ -49,7 +49,7 @@ const jupyterPluginDescription = {
|
|
|
49
49
|
VariableDeclarator(node) {
|
|
50
50
|
const varDecl = node;
|
|
51
51
|
// Check if this has a JupyterFrontEndPlugin type annotation
|
|
52
|
-
if (!(0, plugin_utils_1.
|
|
52
|
+
if (!(0, plugin_utils_1.getJupyterPluginKind)(varDecl)) {
|
|
53
53
|
return;
|
|
54
54
|
}
|
|
55
55
|
// Check if init is an object expression
|
|
@@ -1,23 +1,19 @@
|
|
|
1
1
|
import * as ESTree from 'estree';
|
|
2
|
+
export type JupyterPluginKind = 'frontend' | 'service-manager';
|
|
2
3
|
/**
|
|
3
|
-
*
|
|
4
|
+
* Gets plugin kind from a variable declaration type annotation.
|
|
4
5
|
*/
|
|
5
|
-
export declare function
|
|
6
|
+
export declare function getJupyterPluginKind(node: ESTree.VariableDeclarator): JupyterPluginKind | null;
|
|
6
7
|
/**
|
|
7
|
-
*
|
|
8
|
+
* Extracts properties from an object expression
|
|
8
9
|
*/
|
|
9
|
-
export declare function
|
|
10
|
+
export declare function getObjectProperties(obj: ESTree.ObjectExpression): Map<string, ESTree.Property>;
|
|
10
11
|
/**
|
|
11
12
|
* Gets the plugin ID from an object expression
|
|
12
13
|
*/
|
|
13
14
|
export declare function getPluginId(obj: ESTree.ObjectExpression): string | null;
|
|
14
15
|
/**
|
|
15
|
-
* Extracts
|
|
16
|
-
* Useful for extracting token names from requires/optional arrays
|
|
17
|
-
*/
|
|
18
|
-
export declare function extractIdentifierNames(arrayNode: ESTree.ArrayExpression): string[];
|
|
19
|
-
/**
|
|
20
|
-
* Extracts type annotation from a function parameter
|
|
21
|
-
* Returns the type name if it has a type annotation, null otherwise
|
|
16
|
+
* Extracts element names from an array, including member expressions like JupyterFrontEnd.IPaths
|
|
22
17
|
*/
|
|
18
|
+
export declare function extractArrayElements(arrayExpr: ESTree.ArrayExpression): string[];
|
|
23
19
|
export declare function extractParameterType(param: ESTree.Identifier): string | null;
|
|
@@ -4,11 +4,36 @@
|
|
|
4
4
|
* Distributed under the terms of the Modified BSD License.
|
|
5
5
|
*/
|
|
6
6
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
7
|
+
exports.getJupyterPluginKind = getJupyterPluginKind;
|
|
7
8
|
exports.getObjectProperties = getObjectProperties;
|
|
8
|
-
exports.hasJupyterPluginType = hasJupyterPluginType;
|
|
9
9
|
exports.getPluginId = getPluginId;
|
|
10
|
-
exports.
|
|
10
|
+
exports.extractArrayElements = extractArrayElements;
|
|
11
11
|
exports.extractParameterType = extractParameterType;
|
|
12
|
+
/**
|
|
13
|
+
* Gets plugin kind from a variable declaration type annotation.
|
|
14
|
+
*/
|
|
15
|
+
function getJupyterPluginKind(node) {
|
|
16
|
+
const id = node.id;
|
|
17
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
18
|
+
if (id.typeAnnotation) {
|
|
19
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
20
|
+
const typeAnnotation = id.typeAnnotation;
|
|
21
|
+
if (typeAnnotation.typeAnnotation) {
|
|
22
|
+
const typeNode = typeAnnotation.typeAnnotation;
|
|
23
|
+
if (typeNode.type === 'TSTypeReference' && typeNode.typeName) {
|
|
24
|
+
if (typeNode.typeName.type === 'Identifier') {
|
|
25
|
+
if (typeNode.typeName.name === 'JupyterFrontEndPlugin') {
|
|
26
|
+
return 'frontend';
|
|
27
|
+
}
|
|
28
|
+
if (typeNode.typeName.name === 'ServiceManagerPlugin') {
|
|
29
|
+
return 'service-manager';
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
12
37
|
/**
|
|
13
38
|
* Extracts properties from an object expression
|
|
14
39
|
*/
|
|
@@ -31,27 +56,6 @@ function getObjectProperties(obj) {
|
|
|
31
56
|
}
|
|
32
57
|
return props;
|
|
33
58
|
}
|
|
34
|
-
/**
|
|
35
|
-
* Checks if a variable declaration has a JupyterFrontEndPlugin type annotation
|
|
36
|
-
*/
|
|
37
|
-
function hasJupyterPluginType(node) {
|
|
38
|
-
// Check if the variable declarator has a type annotation
|
|
39
|
-
const id = node.id;
|
|
40
|
-
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
41
|
-
if (id.typeAnnotation) {
|
|
42
|
-
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
43
|
-
const typeAnnotation = id.typeAnnotation;
|
|
44
|
-
if (typeAnnotation.typeAnnotation) {
|
|
45
|
-
const typeNode = typeAnnotation.typeAnnotation;
|
|
46
|
-
if (typeNode.type === 'TSTypeReference' && typeNode.typeName) {
|
|
47
|
-
if (typeNode.typeName.type === 'Identifier') {
|
|
48
|
-
return typeNode.typeName.name === 'JupyterFrontEndPlugin';
|
|
49
|
-
}
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
return false;
|
|
54
|
-
}
|
|
55
59
|
/**
|
|
56
60
|
* Gets the plugin ID from an object expression
|
|
57
61
|
*/
|
|
@@ -77,20 +81,25 @@ function getPluginId(obj) {
|
|
|
77
81
|
return null;
|
|
78
82
|
}
|
|
79
83
|
/**
|
|
80
|
-
* Extracts
|
|
81
|
-
* Useful for extracting token names from requires/optional arrays
|
|
84
|
+
* Extracts element names from an array, including member expressions like JupyterFrontEnd.IPaths
|
|
82
85
|
*/
|
|
83
|
-
function
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
.
|
|
86
|
+
function extractArrayElements(arrayExpr) {
|
|
87
|
+
const names = [];
|
|
88
|
+
for (const element of arrayExpr.elements) {
|
|
89
|
+
if (element === null)
|
|
90
|
+
continue;
|
|
91
|
+
if (element.type === 'Identifier') {
|
|
92
|
+
names.push(element.name);
|
|
93
|
+
}
|
|
94
|
+
else if (element.type === 'MemberExpression') {
|
|
95
|
+
if (element.object.type === 'Identifier' &&
|
|
96
|
+
element.property.type === 'Identifier') {
|
|
97
|
+
names.push(`${element.object.name}.${element.property.name}`);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return names;
|
|
89
102
|
}
|
|
90
|
-
/**
|
|
91
|
-
* Extracts type annotation from a function parameter
|
|
92
|
-
* Returns the type name if it has a type annotation, null otherwise
|
|
93
|
-
*/
|
|
94
103
|
function extractParameterType(param) {
|
|
95
104
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
96
105
|
if (param.typeAnnotation) {
|
|
@@ -98,13 +107,10 @@ function extractParameterType(param) {
|
|
|
98
107
|
const annotation = param.typeAnnotation;
|
|
99
108
|
if (annotation && annotation.typeAnnotation) {
|
|
100
109
|
const typeNode = annotation.typeAnnotation;
|
|
101
|
-
// Handle TSTypeReference (
|
|
110
|
+
// Handle TSTypeReference (like JupyterFrontEnd.IPaths)
|
|
102
111
|
if (typeNode.type === 'TSTypeReference' && typeNode.typeName) {
|
|
103
|
-
|
|
104
|
-
return typeNode.typeName.name;
|
|
105
|
-
}
|
|
112
|
+
return extractTypeName(typeNode.typeName);
|
|
106
113
|
}
|
|
107
|
-
// Handle TSUnionType (e.g., type: IType | null)
|
|
108
114
|
if (typeNode.type === 'TSUnionType') {
|
|
109
115
|
const types = typeNode.types;
|
|
110
116
|
if (Array.isArray(types) && types.length > 0) {
|
|
@@ -112,10 +118,7 @@ function extractParameterType(param) {
|
|
|
112
118
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
113
119
|
(t) => t.type !== 'TSNullKeyword');
|
|
114
120
|
if (nonNullType && nonNullType.type === 'TSTypeReference') {
|
|
115
|
-
|
|
116
|
-
nonNullType.typeName.type === 'Identifier') {
|
|
117
|
-
return nonNullType.typeName.name;
|
|
118
|
-
}
|
|
121
|
+
return extractTypeName(nonNullType.typeName);
|
|
119
122
|
}
|
|
120
123
|
}
|
|
121
124
|
}
|
|
@@ -123,3 +126,24 @@ function extractParameterType(param) {
|
|
|
123
126
|
}
|
|
124
127
|
return null;
|
|
125
128
|
}
|
|
129
|
+
/**
|
|
130
|
+
* Recursively extracts the full name from a TSTypeReference typeName node,
|
|
131
|
+
* handling both simple Identifiers and qualified names (TSQualifiedName)
|
|
132
|
+
* e.g. `IType` -> "IType", `JupyterFrontEnd.IPaths` -> "JupyterFrontEnd.IPaths"
|
|
133
|
+
*/
|
|
134
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
135
|
+
function extractTypeName(typeName) {
|
|
136
|
+
if (!typeName)
|
|
137
|
+
return null;
|
|
138
|
+
if (typeName.type === 'Identifier') {
|
|
139
|
+
return typeName.name;
|
|
140
|
+
}
|
|
141
|
+
if (typeName.type === 'TSQualifiedName') {
|
|
142
|
+
const left = extractTypeName(typeName.left);
|
|
143
|
+
const right = typeName.right?.name;
|
|
144
|
+
if (left && right) {
|
|
145
|
+
return `${left}.${right}`;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
return null;
|
|
149
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jupyter/eslint-plugin",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.2",
|
|
4
4
|
"description": "ESLint plugin for Jupyter core and extensions with early error catching and best practices enforcement",
|
|
5
5
|
"main": "lib/index.js",
|
|
6
6
|
"types": "lib/index.d.ts",
|
|
@@ -15,7 +15,11 @@
|
|
|
15
15
|
"lint": "eslint",
|
|
16
16
|
"lint:fix": "eslint --fix",
|
|
17
17
|
"format": "prettier --write .",
|
|
18
|
-
"format:check": "prettier --check ."
|
|
18
|
+
"format:check": "prettier --check .",
|
|
19
|
+
"docs:start": "npm --prefix website run start",
|
|
20
|
+
"docs:build": "npm --prefix website run build",
|
|
21
|
+
"docs:serve": "npm --prefix website run serve",
|
|
22
|
+
"docs:clear": "npm --prefix website run clear"
|
|
19
23
|
},
|
|
20
24
|
"keywords": [
|
|
21
25
|
"eslint",
|
|
@@ -48,7 +52,7 @@
|
|
|
48
52
|
"@types/eslint": "^9.6.1",
|
|
49
53
|
"@types/estree": "^1.0.8",
|
|
50
54
|
"@types/jest": "^30.0.0",
|
|
51
|
-
"@types/node": "^25.
|
|
55
|
+
"@types/node": "^25.3.5",
|
|
52
56
|
"@typescript-eslint/eslint-plugin": "^8.54.0",
|
|
53
57
|
"@typescript-eslint/parser": "^8.54.0",
|
|
54
58
|
"@typescript-eslint/utils": "^8.54.0",
|