@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 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 `jupyter` to the plugins section of your ESLint configuration:
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': 'error',
24
- 'jupyter/plugin-description': 'error'
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
- // Extract type annotations if available
29
- const paramTypes = activateValue.params
30
- .filter((param) => param.type === 'Identifier')
31
- .map(param => (0, plugin_utils_1.extractParameterType)(param));
32
- return { node: activateProp, params, paramTypes };
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.extractIdentifierNames)(prop.value);
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.extractIdentifierNames)(prop.value);
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
- if (!(0, plugin_utils_1.hasJupyterPluginType)(varDecl)) {
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
- // Validation 1a: Check if first argument is one of the allowed names
139
- if (params.length > 0 && !allowedFirstArgumentNames.includes(params[0])) {
140
- context.report({
141
- node: activateInfo.node,
142
- messageId: 'appNotFirst',
143
- data: {
144
- arg: params[0],
145
- allowedNames: allowedFirstArgumentNames.map(name => `"${name}"`).join(', ')
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
- return;
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); // Already validated above
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 !== null && paramType !== expectedToken) {
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.hasJupyterPluginType)(varDecl)) {
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
- * Extracts properties from an object expression
4
+ * Gets plugin kind from a variable declaration type annotation.
4
5
  */
5
- export declare function getObjectProperties(obj: ESTree.ObjectExpression): Map<string, ESTree.Property>;
6
+ export declare function getJupyterPluginKind(node: ESTree.VariableDeclarator): JupyterPluginKind | null;
6
7
  /**
7
- * Checks if a variable declaration has a JupyterFrontEndPlugin type annotation
8
+ * Extracts properties from an object expression
8
9
  */
9
- export declare function hasJupyterPluginType(node: ESTree.VariableDeclarator): boolean;
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 identifier names from an array expression
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.extractIdentifierNames = extractIdentifierNames;
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 identifier names from an array expression
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 extractIdentifierNames(arrayNode) {
84
- return arrayNode.elements
85
- .filter((elem) => {
86
- return elem !== null && elem.type === 'Identifier';
87
- })
88
- .map(id => id.name);
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 (e.g., type: IType)
110
+ // Handle TSTypeReference (like JupyterFrontEnd.IPaths)
102
111
  if (typeNode.type === 'TSTypeReference' && typeNode.typeName) {
103
- if (typeNode.typeName.type === 'Identifier') {
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
- if (nonNullType.typeName &&
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.1",
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.2.0",
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",