@jupyter/eslint-plugin 0.0.2 → 0.0.3

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
@@ -10,7 +10,7 @@ npm install --save-dev @jupyter/eslint-plugin
10
10
 
11
11
  ## Usage
12
12
 
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>.
13
+ Add `@jupyter/eslint-plugin` to the plugins section of your ESLint configuration. For detailed usage instructions and available rules, see the [documentation](https://eslint-plugin.readthedocs.io/en/latest/).
14
14
 
15
15
  ## License
16
16
 
package/lib/index.d.ts CHANGED
@@ -1,8 +1,16 @@
1
1
  declare const plugin: {
2
2
  rules: {
3
- 'plugin-activation-args': import("eslint").Rule.RuleModule;
4
- 'command-described-by': import("eslint").Rule.RuleModule;
5
- 'plugin-description': import("eslint").Rule.RuleModule;
3
+ 'plugin-activation-args': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"mismatchedOrder" | "missingArgument" | "extraArgument" | "appNotFirst" | "serviceManagerFirstArgNotNull" | "invalidAppType" | "wrongArgumentCount" | "unresolvableTokenType", [{
4
+ allowedFirstArgumentNames: string[];
5
+ }], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
6
+ name: string;
7
+ };
8
+ 'command-described-by': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingDescribedBy", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
9
+ name: string;
10
+ };
11
+ 'plugin-description': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingDescription" | "emptyDescription", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
12
+ name: string;
13
+ };
6
14
  };
7
15
  configs: {
8
16
  recommended: {
@@ -1,3 +1,4 @@
1
- import { Rule } from 'eslint';
2
- declare const jupyterCommandDescribedBy: Rule.RuleModule;
1
+ declare const jupyterCommandDescribedBy: import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingDescribedBy", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
2
+ name: string;
3
+ };
3
4
  export = jupyterCommandDescribedBy;
@@ -5,33 +5,34 @@
5
5
  */
6
6
  const plugin_utils_1 = require("../utils/plugin-utils");
7
7
  const commands_1 = require("../utils/commands");
8
- const jupyterCommandDescribedBy = {
8
+ const create_rule_1 = require("../utils/create-rule");
9
+ const jupyterCommandDescribedBy = (0, create_rule_1.createRule)({
10
+ name: 'command-described-by',
9
11
  meta: {
10
12
  type: 'problem',
11
13
  docs: {
12
14
  description: 'Ensure JupyterLab commands include describedBy property',
13
- recommended: 'recommended',
14
- url: 'https://github.com/jupyterlab/eslint-plugin'
15
+ url: 'https://eslint-plugin.readthedocs.io/en/latest/rules/command-described-by/'
15
16
  },
16
17
  messages: {
17
18
  missingDescribedBy: 'Command "{{ commandId }}" is missing the "describedBy" property.'
18
19
  },
19
20
  schema: []
20
21
  },
22
+ defaultOptions: [],
21
23
  create(context) {
22
24
  return {
23
25
  CallExpression(node) {
24
- const callExpr = node;
25
26
  // Check if this is <something>.addCommand()
26
- if (!(0, commands_1.isAddCommandCall)(callExpr)) {
27
+ if (!(0, commands_1.isAddCommandCall)(node)) {
27
28
  return;
28
29
  }
29
30
  // Get the command ID and options
30
- if (callExpr.arguments.length < 2) {
31
+ if (node.arguments.length < 2) {
31
32
  return;
32
33
  }
33
- const commandIdArg = callExpr.arguments[0];
34
- const optionsArg = callExpr.arguments[1];
34
+ const commandIdArg = node.arguments[0];
35
+ const optionsArg = node.arguments[1];
35
36
  // Extract command ID for error message
36
37
  let commandId = 'unknown';
37
38
  if (commandIdArg.type === 'Literal' &&
@@ -51,8 +52,7 @@ const jupyterCommandDescribedBy = {
51
52
  if (optionsArg.type !== 'ObjectExpression') {
52
53
  return;
53
54
  }
54
- const options = optionsArg;
55
- const properties = (0, plugin_utils_1.getObjectProperties)(options);
55
+ const properties = (0, plugin_utils_1.getObjectProperties)(optionsArg);
56
56
  // Check if execute function exists and has parameters
57
57
  const executeProp = properties.get('execute');
58
58
  if (!executeProp || executeProp.value.type === 'Literal') {
@@ -61,7 +61,7 @@ const jupyterCommandDescribedBy = {
61
61
  const describedByProp = properties.get('describedBy');
62
62
  if (!describedByProp) {
63
63
  context.report({
64
- node: callExpr,
64
+ node,
65
65
  messageId: 'missingDescribedBy',
66
66
  data: { commandId }
67
67
  });
@@ -73,5 +73,5 @@ const jupyterCommandDescribedBy = {
73
73
  }
74
74
  };
75
75
  }
76
- };
76
+ });
77
77
  module.exports = jupyterCommandDescribedBy;
@@ -1,3 +1,7 @@
1
- import { Rule } from 'eslint';
2
- declare const jupyterPluginActivationArgs: Rule.RuleModule;
1
+ import { ESLintUtils } from '@typescript-eslint/utils';
2
+ declare const jupyterPluginActivationArgs: ESLintUtils.RuleModule<"mismatchedOrder" | "missingArgument" | "extraArgument" | "appNotFirst" | "serviceManagerFirstArgNotNull" | "invalidAppType" | "wrongArgumentCount" | "unresolvableTokenType", [{
3
+ allowedFirstArgumentNames: string[];
4
+ }], unknown, ESLintUtils.RuleListener> & {
5
+ name: string;
6
+ };
3
7
  export = jupyterPluginActivationArgs;
@@ -3,33 +3,68 @@
3
3
  * Copyright (c) Jupyter Development Team.
4
4
  * Distributed under the terms of the Modified BSD License.
5
5
  */
6
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
7
+ if (k2 === undefined) k2 = k;
8
+ var desc = Object.getOwnPropertyDescriptor(m, k);
9
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
10
+ desc = { enumerable: true, get: function() { return m[k]; } };
11
+ }
12
+ Object.defineProperty(o, k2, desc);
13
+ }) : (function(o, m, k, k2) {
14
+ if (k2 === undefined) k2 = k;
15
+ o[k2] = m[k];
16
+ }));
17
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
18
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
19
+ }) : function(o, v) {
20
+ o["default"] = v;
21
+ });
22
+ var __importStar = (this && this.__importStar) || (function () {
23
+ var ownKeys = function(o) {
24
+ ownKeys = Object.getOwnPropertyNames || function (o) {
25
+ var ar = [];
26
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
27
+ return ar;
28
+ };
29
+ return ownKeys(o);
30
+ };
31
+ return function (mod) {
32
+ if (mod && mod.__esModule) return mod;
33
+ var result = {};
34
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
35
+ __setModuleDefault(result, mod);
36
+ return result;
37
+ };
38
+ })();
39
+ const utils_1 = require("@typescript-eslint/utils");
40
+ const ts = __importStar(require("typescript"));
6
41
  const plugin_utils_1 = require("../utils/plugin-utils");
42
+ const create_rule_1 = require("../utils/create-rule");
7
43
  const DEFAULT_ALLOWED_FIRST_ARGUMENT_NAMES = ['app', '_app', '_'];
8
44
  /**
9
45
  * Finds the activate function in the plugin object
10
46
  */
11
47
  function findActivateFunction(node) {
12
- const activateProp = node.properties.find(prop => ((prop.type === 'Property' || prop.type === 'SpreadElement') &&
13
- prop.type === 'Property' &&
48
+ const activateProp = node.properties.find((prop) => prop.type === 'Property' &&
14
49
  ((prop.key.type === 'Identifier' && prop.key.name === 'activate') ||
15
- (prop.key.type === 'Literal' && prop.key.value === 'activate'))) ||
16
- prop.type === 'SpreadElement');
17
- if (!activateProp || activateProp.type !== 'Property') {
50
+ (prop.key.type === 'Literal' && prop.key.value === 'activate')));
51
+ if (!activateProp) {
18
52
  return null;
19
53
  }
20
54
  const activateValue = activateProp.value;
21
55
  // Handle both arrow functions and regular functions
22
- if ((activateValue.type === 'ArrowFunctionExpression' ||
23
- activateValue.type === 'FunctionExpression') &&
24
- activateValue.params) {
56
+ if (activateValue.type === 'ArrowFunctionExpression' ||
57
+ activateValue.type === 'FunctionExpression') {
25
58
  const params = activateValue.params
26
59
  .filter((param) => param.type === 'Identifier')
27
60
  .map(param => param.name);
28
61
  const paramTypes = activateValue.params.map(param => param.type === 'Identifier' ? (0, plugin_utils_1.extractParameterType)(param) : null);
62
+ const paramNodes = activateValue.params.map(param => param.type === 'Identifier' ? param : null);
29
63
  return {
30
64
  node: activateProp,
31
65
  params,
32
66
  paramTypes,
67
+ paramNodes
33
68
  };
34
69
  }
35
70
  return null;
@@ -42,8 +77,7 @@ function extractRequiresOptional(node) {
42
77
  requires: [],
43
78
  optional: []
44
79
  };
45
- const props = node.properties;
46
- for (const prop of props) {
80
+ for (const prop of node.properties) {
47
81
  if (prop.type !== 'Property')
48
82
  continue;
49
83
  let keyName = null;
@@ -55,11 +89,11 @@ function extractRequiresOptional(node) {
55
89
  keyName = prop.key.value;
56
90
  }
57
91
  if (keyName === 'requires' && prop.value.type === 'ArrayExpression') {
58
- result.requires = (0, plugin_utils_1.extractArrayElements)(prop.value);
92
+ result.requires = (0, plugin_utils_1.extractArrayTokens)(prop.value);
59
93
  }
60
94
  else if (keyName === 'optional' &&
61
95
  prop.value.type === 'ArrayExpression') {
62
- result.optional = (0, plugin_utils_1.extractArrayElements)(prop.value);
96
+ result.optional = (0, plugin_utils_1.extractArrayTokens)(prop.value);
63
97
  }
64
98
  }
65
99
  return result;
@@ -71,20 +105,16 @@ function isCompatibleWithJupyterFrontEnd(typeName) {
71
105
  if (!typeName) {
72
106
  return true; // If we can't check, we allow it
73
107
  }
74
- const compatibleTypes = [
75
- 'JupyterFrontEnd',
76
- 'JupyterLab',
77
- 'Application'
78
- ];
108
+ const compatibleTypes = ['JupyterFrontEnd', 'JupyterLab', 'Application'];
79
109
  return compatibleTypes.includes(typeName);
80
110
  }
81
- const jupyterPluginActivationArgs = {
111
+ const jupyterPluginActivationArgs = (0, create_rule_1.createRule)({
112
+ name: 'plugin-activation-args',
82
113
  meta: {
83
114
  type: 'problem',
84
115
  docs: {
85
116
  description: 'Ensure JupyterLab plugin activation function arguments match requires and optional tokens in order',
86
- recommended: 'recommended',
87
- url: 'https://github.com/jupyterlab/eslint-plugin'
117
+ url: 'https://eslint-plugin.readthedocs.io/en/latest/rules/plugin-activation-args/'
88
118
  },
89
119
  messages: {
90
120
  mismatchedOrder: 'Activation argument "{{ arg }}" does not match the order of requires/optional tokens.',
@@ -93,7 +123,8 @@ const jupyterPluginActivationArgs = {
93
123
  appNotFirst: 'First activation argument must be one of [{{ allowedNames }}] (JupyterFrontEnd), got "{{ arg }}".',
94
124
  serviceManagerFirstArgNotNull: 'First activation argument for ServiceManagerPlugin must be null, got "{{ arg }}".',
95
125
  invalidAppType: 'First activation argument "{{ arg }}" has invalid type "{{ type }}". Expected JupyterFrontEnd, JupyterLab, or Application.',
96
- wrongArgumentCount: 'Expected {{ expected }} activation arguments (app + {{ tokenCount }} tokens), got {{ actual }}.'
126
+ wrongArgumentCount: 'Expected {{ expected }} activation arguments (app + {{ tokenCount }} tokens), got {{ actual }}.',
127
+ unresolvableTokenType: 'Token "{{ token }}" type could not be resolved — package may be unbuilt. Build it for accurate type checking.'
97
128
  },
98
129
  fixable: 'code',
99
130
  schema: [
@@ -113,25 +144,130 @@ const jupyterPluginActivationArgs = {
113
144
  }
114
145
  ]
115
146
  },
116
- create(context) {
117
- // Get configuration options
118
- const options = context.options[0] || {};
147
+ defaultOptions: [
148
+ {
149
+ allowedFirstArgumentNames: DEFAULT_ALLOWED_FIRST_ARGUMENT_NAMES
150
+ }
151
+ ],
152
+ create(context, [options]) {
119
153
  const allowedFirstArgumentNames = options.allowedFirstArgumentNames || DEFAULT_ALLOWED_FIRST_ARGUMENT_NAMES;
154
+ // Try to obtain the TypeScript type checker for type-aware comparisons.
155
+ let services = null;
156
+ let checker = null;
157
+ try {
158
+ services = utils_1.ESLintUtils.getParserServices(context, true);
159
+ checker = services.program ? services.program.getTypeChecker() : null;
160
+ }
161
+ catch {
162
+ // Parser services unavailable (e.g., non-TS file or misconfigured parser)
163
+ services = null;
164
+ }
165
+ /**
166
+ * Given the AST node for a token in requires/optional, uses the TypeScript checker to extract T from
167
+ * `Token<T>` and returns the TypeScript type object for T.
168
+ * Returns null when type information is unavailable or extraction fails.
169
+ */
170
+ function resolveTokenInnerType(tokenNode) {
171
+ if (!checker) {
172
+ return null;
173
+ }
174
+ try {
175
+ const tsNode = services?.esTreeNodeToTSNodeMap.get(tokenNode);
176
+ if (!tsNode) {
177
+ return null;
178
+ }
179
+ const tokenType = checker.getTypeAtLocation(tsNode);
180
+ const typeArgs = checker.getTypeArguments(tokenType);
181
+ if (typeArgs && typeArgs.length > 0) {
182
+ return typeArgs[0];
183
+ }
184
+ }
185
+ catch {
186
+ // Fall through
187
+ }
188
+ return null;
189
+ }
190
+ /**
191
+ * Given the AST node for an activate parameter identifier, uses the
192
+ * TypeScript checker to get its type.
193
+ * Returns null when type information is unavailable or extraction fails.
194
+ */
195
+ function resolveParamType(paramNode) {
196
+ if (!checker)
197
+ return null;
198
+ try {
199
+ const tsNode = services?.esTreeNodeToTSNodeMap.get(paramNode);
200
+ if (!tsNode)
201
+ return null;
202
+ const type = checker.getTypeAtLocation(tsNode);
203
+ // Handle `T | null/undefined` (optional token pattern)
204
+ if (type.isUnion()) {
205
+ const nonNullTypes = type.types.filter(t => !(t.flags & ts.TypeFlags.Null) &&
206
+ !(t.flags & ts.TypeFlags.Undefined));
207
+ if (nonNullTypes.length === 1) {
208
+ return nonNullTypes[0];
209
+ }
210
+ }
211
+ return type;
212
+ }
213
+ catch {
214
+ // Fall through
215
+ }
216
+ return null;
217
+ }
218
+ /**
219
+ * Returns true when two TypeScript types refer to the same type.
220
+ */
221
+ function isSameType(a, b) {
222
+ if (a === b)
223
+ return true;
224
+ if (a.symbol && b.symbol && a.symbol === b.symbol)
225
+ return true;
226
+ return checker.typeToString(a) === checker.typeToString(b);
227
+ }
228
+ /**
229
+ * Returns [matches, tokenUnresolved] where:
230
+ * - matches: true when the activate parameter type is compatible with the token's type.
231
+ * - tokenUnresolved: true when the token's inner type could not be resolved (null, undefined, or any),
232
+ * meaning the result is inconclusive (e.g. package is unbuilt).
233
+ */
234
+ function tokenMatchesParam(token, paramType, paramNode) {
235
+ // For most cases this check is sufficient
236
+ if (paramType === token.name)
237
+ return [true, false];
238
+ if (checker && paramNode) {
239
+ const resolvedToken = resolveTokenInnerType(token.node);
240
+ const tokenUnresolved = resolvedToken === null ||
241
+ resolvedToken === undefined ||
242
+ !!(resolvedToken.flags & ts.TypeFlags.Any);
243
+ if (tokenUnresolved) {
244
+ return [true, true];
245
+ }
246
+ const resolvedParam = resolveParamType(paramNode);
247
+ if (resolvedParam !== null) {
248
+ return [isSameType(resolvedToken, resolvedParam), false];
249
+ }
250
+ }
251
+ // Without a checker we cannot resolve namespace patterns like
252
+ // `IDebugger.ISidebar` ↔ `IDebuggerSidebar`.
253
+ if (!checker && paramType && paramType.includes('.'))
254
+ return [true, false];
255
+ return [false, false];
256
+ }
120
257
  return {
121
258
  VariableDeclarator(node) {
122
- const varDecl = node;
123
- const pluginKind = (0, plugin_utils_1.getJupyterPluginKind)(varDecl);
259
+ const pluginKind = (0, plugin_utils_1.getJupyterPluginKind)(node);
124
260
  if (!pluginKind) {
125
261
  return;
126
262
  }
127
- if (varDecl.init && varDecl.init.type === 'ObjectExpression') {
128
- const pluginObj = varDecl.init;
263
+ if (node.init && node.init.type === 'ObjectExpression') {
264
+ const pluginObj = node.init;
129
265
  const { requires, optional } = extractRequiresOptional(pluginObj);
130
266
  const activateInfo = findActivateFunction(pluginObj);
131
267
  if (!activateInfo) {
132
268
  return;
133
269
  }
134
- const { params, paramTypes } = activateInfo;
270
+ const { params, paramTypes, paramNodes } = activateInfo;
135
271
  const expectedCount = 1 + requires.length + optional.length;
136
272
  const expectedTokensWithoutApp = [...requires, ...optional];
137
273
  if (expectedCount === 1 && params.length === 0) {
@@ -141,7 +277,7 @@ const jupyterPluginActivationArgs = {
141
277
  if (pluginKind === 'frontend') {
142
278
  // Validation 1a: Check if first argument is one of the allowed names
143
279
  if (params.length > 0 &&
144
- (params[0] === null || !allowedFirstArgumentNames.includes(params[0]))) {
280
+ !allowedFirstArgumentNames.includes(params[0])) {
145
281
  context.report({
146
282
  node: activateInfo.node,
147
283
  messageId: 'appNotFirst',
@@ -173,27 +309,11 @@ const jupyterPluginActivationArgs = {
173
309
  else if (pluginKind === 'service-manager') {
174
310
  // Validation 1: First argument must be literal null
175
311
  if (params.length === 0 || paramTypes[0] !== null) {
176
- const firstArg = params[0] ?? 'missing';
177
312
  context.report({
178
313
  node: activateInfo.node,
179
314
  messageId: 'serviceManagerFirstArgNotNull',
180
315
  data: {
181
- arg: firstArg
182
- }
183
- });
184
- return;
185
- }
186
- }
187
- // Validation 1b: Check if first argument type is compatible with JupyterFrontEnd
188
- if (params.length > 0 && paramTypes.length > 0) {
189
- const firstParamType = paramTypes[0];
190
- if (!isCompatibleWithJupyterFrontEnd(firstParamType)) {
191
- context.report({
192
- node: activateInfo.node,
193
- messageId: 'invalidAppType',
194
- data: {
195
- arg: params[0],
196
- type: firstParamType || 'unknown'
316
+ arg: paramTypes[0]
197
317
  }
198
318
  });
199
319
  return;
@@ -213,11 +333,13 @@ const jupyterPluginActivationArgs = {
213
333
  }
214
334
  // Validation 3: If parameters have type annotations, validate order
215
335
  const actualParamTypes = paramTypes.slice(1); // First arg already validated above
216
- const hasTypeInfo = actualParamTypes.some((t) => t !== null);
336
+ const actualParamNodes = paramNodes.slice(1);
337
+ const hasTypeInfo = actualParamTypes.some(t => t !== null);
217
338
  if (hasTypeInfo) {
218
339
  // Validate that parameter types match expected token types in order
219
340
  for (let i = 0; i < actualParamTypes.length; i++) {
220
341
  const paramType = actualParamTypes[i];
342
+ const paramNode = actualParamNodes[i];
221
343
  const expectedToken = expectedTokensWithoutApp[i];
222
344
  if (expectedToken === undefined) {
223
345
  // Extra argument
@@ -229,13 +351,22 @@ const jupyterPluginActivationArgs = {
229
351
  });
230
352
  }
231
353
  }
232
- else if (paramType !== expectedToken) {
233
- // Type mismatch
234
- context.report({
235
- node: activateInfo.node,
236
- messageId: 'mismatchedOrder',
237
- data: { arg: params[i + 1] }
238
- });
354
+ else {
355
+ const [matches, tokenUnresolved] = tokenMatchesParam(expectedToken, paramType, paramNode);
356
+ if (tokenUnresolved) {
357
+ context.report({
358
+ node: activateInfo.node,
359
+ messageId: 'unresolvableTokenType',
360
+ data: { token: expectedToken.name }
361
+ });
362
+ }
363
+ else if (!matches) {
364
+ context.report({
365
+ node: activateInfo.node,
366
+ messageId: 'mismatchedOrder',
367
+ data: { arg: params[i + 1] }
368
+ });
369
+ }
239
370
  }
240
371
  }
241
372
  }
@@ -246,18 +377,18 @@ const jupyterPluginActivationArgs = {
246
377
  context.report({
247
378
  node: activateInfo.node,
248
379
  messageId: 'extraArgument',
249
- data: { arg: actualParams[i + 1] }
380
+ data: { arg: actualParams[i] }
250
381
  });
251
382
  }
252
383
  }
253
384
  // Validation 4: Check for missing arguments (only if counts don't match)
254
385
  if (params.length < expectedCount) {
255
- for (let i = params.length - 1; i < expectedTokensWithoutApp.length; i++) {
386
+ for (let i = Math.max(params.length - 1, 0); i < expectedTokensWithoutApp.length; i++) {
256
387
  const missingToken = expectedTokensWithoutApp[i];
257
388
  context.report({
258
389
  node: activateInfo.node,
259
390
  messageId: 'missingArgument',
260
- data: { token: missingToken }
391
+ data: { token: missingToken.name }
261
392
  });
262
393
  }
263
394
  }
@@ -265,5 +396,5 @@ const jupyterPluginActivationArgs = {
265
396
  }
266
397
  };
267
398
  }
268
- };
399
+ });
269
400
  module.exports = jupyterPluginActivationArgs;
@@ -1,3 +1,4 @@
1
- import { Rule } from 'eslint';
2
- declare const jupyterPluginDescription: Rule.RuleModule;
1
+ declare const jupyterPluginDescription: import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingDescription" | "emptyDescription", [], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> & {
2
+ name: string;
3
+ };
3
4
  export = jupyterPluginDescription;
@@ -3,6 +3,7 @@
3
3
  * Copyright (c) Jupyter Development Team.
4
4
  * Distributed under the terms of the Modified BSD License.
5
5
  */
6
+ const create_rule_1 = require("../utils/create-rule");
6
7
  const plugin_utils_1 = require("../utils/plugin-utils");
7
8
  /**
8
9
  * Checks if an object expression has a description property
@@ -30,13 +31,13 @@ function hasDescriptionProperty(obj) {
30
31
  }
31
32
  return false;
32
33
  }
33
- const jupyterPluginDescription = {
34
+ const jupyterPluginDescription = (0, create_rule_1.createRule)({
35
+ name: 'plugin-description',
34
36
  meta: {
35
37
  type: 'problem',
36
38
  docs: {
37
39
  description: 'Ensure all JupyterLab plugins have a description property',
38
- recommended: 'recommended',
39
- url: 'https://github.com/jupyterlab/eslint-plugin'
40
+ url: 'https://eslint-plugin.readthedocs.io/en/latest/rules/plugin-description/'
40
41
  },
41
42
  messages: {
42
43
  missingDescription: 'JupyterLab plugin{{ pluginId }} is missing a "description" property.',
@@ -44,10 +45,10 @@ const jupyterPluginDescription = {
44
45
  },
45
46
  schema: []
46
47
  },
48
+ defaultOptions: [],
47
49
  create(context) {
48
50
  return {
49
- VariableDeclarator(node) {
50
- const varDecl = node;
51
+ VariableDeclarator(varDecl) {
51
52
  // Check if this has a JupyterFrontEndPlugin type annotation
52
53
  if (!(0, plugin_utils_1.getJupyterPluginKind)(varDecl)) {
53
54
  return;
@@ -56,13 +57,12 @@ const jupyterPluginDescription = {
56
57
  if (!varDecl.init || varDecl.init.type !== 'ObjectExpression') {
57
58
  return;
58
59
  }
59
- const pluginObj = varDecl.init;
60
- const pluginId = (0, plugin_utils_1.getPluginId)(pluginObj);
60
+ const pluginId = (0, plugin_utils_1.getPluginId)(varDecl.init);
61
61
  const pluginIdSuffix = pluginId ? ` "${pluginId}"` : '';
62
62
  // Check if description property exists
63
- if (!hasDescriptionProperty(pluginObj)) {
63
+ if (!hasDescriptionProperty(varDecl.init)) {
64
64
  context.report({
65
- node: pluginObj,
65
+ node: varDecl.init,
66
66
  messageId: 'missingDescription',
67
67
  data: { pluginId: pluginIdSuffix }
68
68
  });
@@ -70,5 +70,5 @@ const jupyterPluginDescription = {
70
70
  }
71
71
  };
72
72
  }
73
- };
73
+ });
74
74
  module.exports = jupyterPluginDescription;
@@ -1,5 +1,5 @@
1
- import * as ESTree from 'estree';
1
+ import { TSESTree } from '@typescript-eslint/types';
2
2
  /**
3
3
  * Checks if a node represents *.addCommand()
4
4
  */
5
- export declare function isAddCommandCall(node: ESTree.CallExpression): boolean;
5
+ export declare function isAddCommandCall(node: TSESTree.CallExpression): boolean;
@@ -0,0 +1,4 @@
1
+ import { ESLintUtils } from '@typescript-eslint/utils';
2
+ export declare const createRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
3
+ name: string;
4
+ };
@@ -0,0 +1,9 @@
1
+ "use strict";
2
+ /*
3
+ * Copyright (c) Jupyter Development Team.
4
+ * Distributed under the terms of the Modified BSD License.
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.createRule = void 0;
8
+ const utils_1 = require("@typescript-eslint/utils");
9
+ exports.createRule = utils_1.ESLintUtils.RuleCreator(name => `https://eslint-plugin.readthedocs.io/en/latest/rules/${name}/`);
@@ -1,19 +1,23 @@
1
- import * as ESTree from 'estree';
1
+ import { TSESTree } from '@typescript-eslint/types';
2
2
  export type JupyterPluginKind = 'frontend' | 'service-manager';
3
3
  /**
4
4
  * Gets plugin kind from a variable declaration type annotation.
5
5
  */
6
- export declare function getJupyterPluginKind(node: ESTree.VariableDeclarator): JupyterPluginKind | null;
6
+ export declare function getJupyterPluginKind(node: TSESTree.VariableDeclarator): JupyterPluginKind | null;
7
7
  /**
8
8
  * Extracts properties from an object expression
9
9
  */
10
- export declare function getObjectProperties(obj: ESTree.ObjectExpression): Map<string, ESTree.Property>;
10
+ export declare function getObjectProperties(obj: TSESTree.ObjectExpression): Map<string, TSESTree.Property>;
11
11
  /**
12
12
  * Gets the plugin ID from an object expression
13
13
  */
14
- export declare function getPluginId(obj: ESTree.ObjectExpression): string | null;
14
+ export declare function getPluginId(obj: TSESTree.ObjectExpression): string | null;
15
+ export interface TokenEntry {
16
+ name: string;
17
+ node: TSESTree.Node;
18
+ }
15
19
  /**
16
- * Extracts element names from an array, including member expressions like JupyterFrontEnd.IPaths
20
+ * Extracts token names and nodes from an array, including member expressions like JupyterFrontEnd.IPaths
17
21
  */
18
- export declare function extractArrayElements(arrayExpr: ESTree.ArrayExpression): string[];
19
- export declare function extractParameterType(param: ESTree.Identifier): string | null;
22
+ export declare function extractArrayTokens(arrayExpr: TSESTree.ArrayExpression): TokenEntry[];
23
+ export declare function extractParameterType(param: TSESTree.Identifier): string | null;
@@ -7,30 +7,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
7
7
  exports.getJupyterPluginKind = getJupyterPluginKind;
8
8
  exports.getObjectProperties = getObjectProperties;
9
9
  exports.getPluginId = getPluginId;
10
- exports.extractArrayElements = extractArrayElements;
10
+ exports.extractArrayTokens = extractArrayTokens;
11
11
  exports.extractParameterType = extractParameterType;
12
12
  /**
13
13
  * Gets plugin kind from a variable declaration type annotation.
14
14
  */
15
15
  function getJupyterPluginKind(node) {
16
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
- }
17
+ if (id.type !== 'Identifier' || !id.typeAnnotation) {
18
+ return null;
19
+ }
20
+ const typeNode = id.typeAnnotation.typeAnnotation;
21
+ if (typeNode.type !== 'TSTypeReference') {
22
+ return null;
23
+ }
24
+ const pluginTypeName = extractTypeName(typeNode.typeName);
25
+ if (pluginTypeName === 'JupyterFrontEndPlugin') {
26
+ return 'frontend';
27
+ }
28
+ if (pluginTypeName === 'ServiceManagerPlugin') {
29
+ return 'service-manager';
34
30
  }
35
31
  return null;
36
32
  }
@@ -81,47 +77,41 @@ function getPluginId(obj) {
81
77
  return null;
82
78
  }
83
79
  /**
84
- * Extracts element names from an array, including member expressions like JupyterFrontEnd.IPaths
80
+ * Extracts token names and nodes from an array, including member expressions like JupyterFrontEnd.IPaths
85
81
  */
86
- function extractArrayElements(arrayExpr) {
87
- const names = [];
82
+ function extractArrayTokens(arrayExpr) {
83
+ const entries = [];
88
84
  for (const element of arrayExpr.elements) {
89
85
  if (element === null)
90
86
  continue;
91
87
  if (element.type === 'Identifier') {
92
- names.push(element.name);
88
+ entries.push({ name: element.name, node: element });
93
89
  }
94
90
  else if (element.type === 'MemberExpression') {
95
91
  if (element.object.type === 'Identifier' &&
96
92
  element.property.type === 'Identifier') {
97
- names.push(`${element.object.name}.${element.property.name}`);
93
+ entries.push({
94
+ name: `${element.object.name}.${element.property.name}`,
95
+ node: element
96
+ });
98
97
  }
99
98
  }
100
99
  }
101
- return names;
100
+ return entries;
102
101
  }
103
102
  function extractParameterType(param) {
104
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
105
- if (param.typeAnnotation) {
106
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
107
- const annotation = param.typeAnnotation;
108
- if (annotation && annotation.typeAnnotation) {
109
- const typeNode = annotation.typeAnnotation;
110
- // Handle TSTypeReference (like JupyterFrontEnd.IPaths)
111
- if (typeNode.type === 'TSTypeReference' && typeNode.typeName) {
112
- return extractTypeName(typeNode.typeName);
113
- }
114
- if (typeNode.type === 'TSUnionType') {
115
- const types = typeNode.types;
116
- if (Array.isArray(types) && types.length > 0) {
117
- const nonNullType = types.find(
118
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
119
- (t) => t.type !== 'TSNullKeyword');
120
- if (nonNullType && nonNullType.type === 'TSTypeReference') {
121
- return extractTypeName(nonNullType.typeName);
122
- }
123
- }
124
- }
103
+ if (!param.typeAnnotation) {
104
+ return null;
105
+ }
106
+ const typeNode = param.typeAnnotation.typeAnnotation;
107
+ // Handle TSTypeReference (like JupyterFrontEnd.IPaths)
108
+ if (typeNode.type === 'TSTypeReference') {
109
+ return extractTypeName(typeNode.typeName);
110
+ }
111
+ if (typeNode.type === 'TSUnionType') {
112
+ const nonNullType = typeNode.types.find(t => t.type !== 'TSNullKeyword');
113
+ if (nonNullType && nonNullType.type === 'TSTypeReference') {
114
+ return extractTypeName(nonNullType.typeName);
125
115
  }
126
116
  }
127
117
  return null;
@@ -131,10 +121,7 @@ function extractParameterType(param) {
131
121
  * handling both simple Identifiers and qualified names (TSQualifiedName)
132
122
  * e.g. `IType` -> "IType", `JupyterFrontEnd.IPaths` -> "JupyterFrontEnd.IPaths"
133
123
  */
134
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
135
124
  function extractTypeName(typeName) {
136
- if (!typeName)
137
- return null;
138
125
  if (typeName.type === 'Identifier') {
139
126
  return typeName.name;
140
127
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jupyter/eslint-plugin",
3
- "version": "0.0.2",
3
+ "version": "0.0.3",
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",
@@ -55,7 +55,7 @@
55
55
  "@types/node": "^25.3.5",
56
56
  "@typescript-eslint/eslint-plugin": "^8.54.0",
57
57
  "@typescript-eslint/parser": "^8.54.0",
58
- "@typescript-eslint/utils": "^8.54.0",
58
+ "@typescript-eslint/rule-tester": "^8.57.0",
59
59
  "eslint": "^9.39.2",
60
60
  "eslint-plugin": "^1.0.1",
61
61
  "jest": "^30.2.0",
@@ -64,6 +64,9 @@
64
64
  "ts-jest": "^29.4.6",
65
65
  "typescript": "^5.9.3"
66
66
  },
67
+ "dependencies": {
68
+ "@typescript-eslint/utils": "^8.54.0"
69
+ },
67
70
  "peerDependencies": {
68
71
  "eslint": ">=9.0.0"
69
72
  },