@jupyter/eslint-plugin 1.3.0 → 1.4.0

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.
@@ -44,11 +44,16 @@ exports.resolveStaticString = resolveStaticString;
44
44
  exports.extractArrayTokens = extractArrayTokens;
45
45
  exports.isNullableAnnotation = isNullableAnnotation;
46
46
  exports.extractParameterType = extractParameterType;
47
+ exports.isPluginTypeName = isPluginTypeName;
48
+ exports.getPluginKindFromTypeName = getPluginKindFromTypeName;
49
+ exports.getPluginKindFromTsType = getPluginKindFromTsType;
47
50
  exports.typeMentionsJupyterPlugin = typeMentionsJupyterPlugin;
48
- exports.typeMentionsMimeExtension = typeMentionsMimeExtension;
49
51
  exports.isCallableProperty = isCallableProperty;
50
52
  exports.looksLikePluginObject = looksLikePluginObject;
51
53
  exports.looksLikeMimeExtensionObject = looksLikeMimeExtensionObject;
54
+ exports.getEnclosingFunction = getEnclosingFunction;
55
+ exports.getPluginKindFromType = getPluginKindFromType;
56
+ exports.getPluginObjectKind = getPluginObjectKind;
52
57
  const utils_1 = require("@typescript-eslint/utils");
53
58
  const ts = __importStar(require("typescript"));
54
59
  /**
@@ -65,22 +70,18 @@ function getJupyterPluginKind(node, checker, getTSNode) {
65
70
  if (typeNode.type !== 'TSTypeReference') {
66
71
  return null;
67
72
  }
68
- // Fast path: direct string match (no alias).
73
+ // Fast path: direct string match (no alias), including namespaced like Private.JupyterFrontEndPlugin.
69
74
  const pluginTypeName = extractTypeName(typeNode.typeName);
70
- if (pluginTypeName === 'JupyterFrontEndPlugin') {
71
- return 'frontend';
72
- }
73
- if (pluginTypeName === 'ServiceManagerPlugin') {
74
- return 'service-manager';
75
+ const fastKind = getPluginKindFromTypeName(pluginTypeName);
76
+ if (fastKind) {
77
+ return fastKind;
75
78
  }
76
79
  // Slow path: resolve import aliases via the TS checker.
77
80
  if (checker && getTSNode && typeNode.typeName.type === 'Identifier') {
78
81
  const resolvedName = resolveTypeAlias(typeNode.typeName, checker, getTSNode);
79
- if (resolvedName === 'JupyterFrontEndPlugin') {
80
- return 'frontend';
81
- }
82
- if (resolvedName === 'ServiceManagerPlugin') {
83
- return 'service-manager';
82
+ const resolvedKind = getPluginKindFromTypeName(resolvedName);
83
+ if (resolvedKind) {
84
+ return resolvedKind;
84
85
  }
85
86
  }
86
87
  return null;
@@ -215,18 +216,129 @@ function extractTypeName(typeName) {
215
216
  }
216
217
  return null;
217
218
  }
218
- const PLUGIN_TYPE_NAMES = ['JupyterFrontEndPlugin', 'ServiceManagerPlugin'];
219
219
  /**
220
220
  * Returns true when a type name refers to a JupyterLab plugin type. Only the
221
221
  * last segment is compared, so a namespaced spelling such as
222
- * `Private.JupyterFrontEndPlugin` matches too.
222
+ * `Private.JupyterFrontEndPlugin` or `app.JupyterFrontEndPlugin` matches too.
223
223
  */
224
224
  function isPluginTypeName(name) {
225
+ return getPluginKindFromTypeName(name) !== null;
226
+ }
227
+ /**
228
+ * Resolves the plugin kind ('frontend' or 'service-manager') from a type name.
229
+ * Compares the last segment so qualified names like `app.JupyterFrontEndPlugin` match.
230
+ */
231
+ function getPluginKindFromTypeName(name) {
225
232
  if (!name) {
226
- return false;
233
+ return null;
227
234
  }
228
235
  const lastSegment = name.split('.').pop() ?? name;
229
- return PLUGIN_TYPE_NAMES.includes(lastSegment);
236
+ if (lastSegment === 'JupyterFrontEndPlugin') {
237
+ return 'frontend';
238
+ }
239
+ if (lastSegment === 'ServiceManagerPlugin') {
240
+ return 'service-manager';
241
+ }
242
+ return null;
243
+ }
244
+ /**
245
+ * Generic types whose first type argument is unwrapped when resolving a plugin
246
+ * kind. Arbitrary wrappers such as `Wrapper<T>` or `Omit<T, 'description'>`
247
+ * are deliberately left out, since they need not describe a plugin object.
248
+ */
249
+ const ALLOWED_GENERIC_WRAPPERS = new Set([
250
+ 'Array',
251
+ 'ReadonlyArray',
252
+ 'Partial',
253
+ 'Promise',
254
+ 'Readonly',
255
+ 'Required'
256
+ ]);
257
+ /**
258
+ * The application types which make a Lumino `IPlugin<T, U>` a JupyterLab
259
+ * frontend plugin. A bare Lumino `Application` is left out, so plain Lumino
260
+ * plugins are not held to JupyterLab's conventions.
261
+ */
262
+ const FRONTEND_APPLICATION_TYPES = new Set(['JupyterFrontEnd', 'JupyterLab']);
263
+ /**
264
+ * Collapses the kinds found in the members of a union, intersection or tuple:
265
+ * the single kind when they agree, 'ambiguous' when they differ.
266
+ */
267
+ function mergeKinds(kinds) {
268
+ const found = new Set();
269
+ for (const kind of kinds) {
270
+ if (kind) {
271
+ found.add(kind);
272
+ }
273
+ }
274
+ if (found.size > 1) {
275
+ return 'ambiguous';
276
+ }
277
+ return found.size === 1 ? Array.from(found)[0] : null;
278
+ }
279
+ /**
280
+ * Resolves the plugin kind ('frontend' or 'service-manager') from a TypeScript Type.
281
+ */
282
+ function getPluginKindFromTsType(type, checker, depth = 0) {
283
+ if (depth > 6) {
284
+ return null;
285
+ }
286
+ if (type.isUnion() || type.isIntersection()) {
287
+ return mergeKinds(type.types.map(t => getPluginKindFromTsType(t, checker, depth + 1)));
288
+ }
289
+ // Mapped wrappers such as `Partial<T>` and `Readonly<T>` only keep their
290
+ // argument as an alias type argument.
291
+ const aliasName = type.aliasSymbol?.getName();
292
+ const aliasArg = type.aliasTypeArguments?.[0];
293
+ if (aliasName && aliasArg && ALLOWED_GENERIC_WRAPPERS.has(aliasName)) {
294
+ return getPluginKindFromTsType(aliasArg, checker, depth + 1);
295
+ }
296
+ let symbol = type.aliasSymbol ?? type.getSymbol();
297
+ if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
298
+ try {
299
+ symbol = checker.getAliasedSymbol(symbol);
300
+ }
301
+ catch {
302
+ // ignore
303
+ }
304
+ }
305
+ const name = symbol?.getName();
306
+ if (name) {
307
+ const kind = getPluginKindFromTypeName(name);
308
+ if (kind) {
309
+ return kind;
310
+ }
311
+ }
312
+ const targetSymbol = type.getSymbol();
313
+ const targetName = targetSymbol?.getName();
314
+ if (targetName && targetName !== name) {
315
+ const kind = getPluginKindFromTypeName(targetName);
316
+ if (kind) {
317
+ return kind;
318
+ }
319
+ }
320
+ // Handle IPlugin<T, ...> interface from @lumino/application
321
+ if (name === 'IPlugin' || targetName === 'IPlugin') {
322
+ try {
323
+ const typeRef = type;
324
+ const typeArgs = checker.getTypeArguments(typeRef);
325
+ if (typeArgs && typeArgs.length > 0) {
326
+ const firstArg = typeArgs[0];
327
+ const firstArgSymbol = firstArg.aliasSymbol ?? firstArg.getSymbol();
328
+ const firstArgName = firstArgSymbol?.getName();
329
+ if (firstArgName && FRONTEND_APPLICATION_TYPES.has(firstArgName)) {
330
+ return 'frontend';
331
+ }
332
+ if (firstArg.flags & ts.TypeFlags.Null) {
333
+ return 'service-manager';
334
+ }
335
+ }
336
+ }
337
+ catch {
338
+ // ignore
339
+ }
340
+ }
341
+ return null;
230
342
  }
231
343
  /**
232
344
  * Returns true when `matches` accepts a type reference found at any depth of
@@ -303,15 +415,6 @@ function isMimeExtensionReference(reference, checker, getTSNode) {
303
415
  resolveTypeAlias(typeName.left, checker, getTSNode) ===
304
416
  MIME_EXTENSION_NAMESPACE);
305
417
  }
306
- /**
307
- * Returns true when a type annotation mentions the MIME renderer extension
308
- * entry type at any depth, with the same wrappers as
309
- * `typeMentionsJupyterPlugin`. JupyterLab registers each entry as a plugin
310
- * whose ID is the entry's `id`, so the entry follows the plugin ID convention.
311
- */
312
- function typeMentionsMimeExtension(typeNode, checker, getTSNode) {
313
- return typeMentions(typeNode, reference => isMimeExtensionReference(reference, checker, getTSNode));
314
- }
315
418
  /**
316
419
  * Resolves an identifier through the TypeScript checker to the name it aliases,
317
420
  * e.g. `import { JupyterFrontEndPlugin as JFEP }` gives back the original name.
@@ -387,3 +490,251 @@ function looksLikeMimeExtensionObject(node, hasId = getPluginId(node) !== null)
387
490
  const properties = getObjectProperties(node);
388
491
  return hasId && properties.has('id') && properties.has('rendererFactory');
389
492
  }
493
+ /**
494
+ * Finds the function that owns a return statement.
495
+ */
496
+ function getEnclosingFunction(node) {
497
+ let current = node.parent;
498
+ while (current) {
499
+ if (current.type === 'FunctionDeclaration' ||
500
+ current.type === 'FunctionExpression' ||
501
+ current.type === 'ArrowFunctionExpression') {
502
+ return current;
503
+ }
504
+ current = current.parent;
505
+ }
506
+ return null;
507
+ }
508
+ /**
509
+ * Resolves the plugin kind from a TypeScript type annotation node, unwrapping
510
+ * arrays, tuples, type operators (readonly), unions, and allowed generic containers.
511
+ * Returns 'ambiguous' if types are mixed (e.g. union or tuple containing multiple distinct plugin kinds).
512
+ */
513
+ function getPluginKindFromType(typeNode, checker, getTSNode, options, depth = 0) {
514
+ if (!typeNode || depth > 6) {
515
+ return null;
516
+ }
517
+ if (typeNode.type === 'TSTypeReference') {
518
+ const name = extractTypeName(typeNode.typeName);
519
+ const directKind = getPluginKindFromTypeName(name);
520
+ if (directKind) {
521
+ return directKind;
522
+ }
523
+ if (options?.matchMime &&
524
+ isMimeExtensionReference(typeNode, checker, getTSNode)) {
525
+ return 'mime-renderer';
526
+ }
527
+ if (checker && getTSNode && typeNode.typeName.type === 'Identifier') {
528
+ const resolved = resolveTypeAlias(typeNode.typeName, checker, getTSNode);
529
+ const aliasKind = getPluginKindFromTypeName(resolved);
530
+ if (aliasKind) {
531
+ return aliasKind;
532
+ }
533
+ }
534
+ // Handle IPlugin<T, ...> in AST
535
+ const baseName = name ? name.split('.').pop() ?? name : null;
536
+ if (baseName === 'IPlugin') {
537
+ const firstParam = typeNode.typeArguments?.params?.[0];
538
+ if (firstParam) {
539
+ if (firstParam.type === 'TSTypeReference') {
540
+ const firstParamName = extractTypeName(firstParam.typeName);
541
+ const firstBase = firstParamName
542
+ ? firstParamName.split('.').pop() ?? firstParamName
543
+ : null;
544
+ if (firstBase && FRONTEND_APPLICATION_TYPES.has(firstBase)) {
545
+ return 'frontend';
546
+ }
547
+ }
548
+ else if (firstParam.type === 'TSNullKeyword') {
549
+ return 'service-manager';
550
+ }
551
+ }
552
+ }
553
+ // Only unwrap generic containers in the allowed set; arbitrary wrappers
554
+ // such as Wrapper<T> or Omit<T, 'description'> are not plugins.
555
+ if (baseName &&
556
+ ALLOWED_GENERIC_WRAPPERS.has(baseName) &&
557
+ typeNode.typeArguments?.params &&
558
+ typeNode.typeArguments.params.length > 0) {
559
+ return getPluginKindFromType(typeNode.typeArguments.params[0], checker, getTSNode, options, depth + 1);
560
+ }
561
+ return null;
562
+ }
563
+ if (typeNode.type === 'TSArrayType') {
564
+ return getPluginKindFromType(typeNode.elementType, checker, getTSNode, options, depth + 1);
565
+ }
566
+ if (typeNode.type === 'TSTupleType') {
567
+ return mergeKinds(typeNode.elementTypes.map(member => getPluginKindFromType(unwrapTupleMember(member), checker, getTSNode, options, depth + 1)));
568
+ }
569
+ if (typeNode.type === 'TSTypeOperator' && typeNode.operator === 'readonly') {
570
+ return getPluginKindFromType(typeNode.typeAnnotation, checker, getTSNode, options, depth + 1);
571
+ }
572
+ if (typeNode.type === 'TSUnionType' ||
573
+ typeNode.type === 'TSIntersectionType') {
574
+ return mergeKinds(typeNode.types.map(t => getPluginKindFromType(t, checker, getTSNode, options, depth + 1)));
575
+ }
576
+ return null;
577
+ }
578
+ function getEnclosingFunctionReturnType(expr) {
579
+ const parent = expr.parent;
580
+ if (parent?.type === 'ReturnStatement' && parent.argument === expr) {
581
+ const fn = getEnclosingFunction(parent);
582
+ return fn?.returnType?.typeAnnotation ?? null;
583
+ }
584
+ if (parent?.type === 'ArrowFunctionExpression' && parent.body === expr) {
585
+ return parent.returnType?.typeAnnotation ?? null;
586
+ }
587
+ return null;
588
+ }
589
+ function getKindFromEnclosingFunctionReturn(expr, checker, getTSNode, options) {
590
+ const returnType = getEnclosingFunctionReturnType(expr);
591
+ if (returnType) {
592
+ return getPluginKindFromType(returnType, checker, getTSNode, options);
593
+ }
594
+ return null;
595
+ }
596
+ function getTupleElementKind(typeNode, elementIndex, checker, getTSNode, options) {
597
+ if (!typeNode || elementIndex < 0) {
598
+ return null;
599
+ }
600
+ if (typeNode.type === 'TSTypeOperator' && typeNode.operator === 'readonly') {
601
+ return getTupleElementKind(typeNode.typeAnnotation, elementIndex, checker, getTSNode, options);
602
+ }
603
+ if (typeNode.type === 'TSTupleType') {
604
+ const members = typeNode.elementTypes;
605
+ if (elementIndex < members.length) {
606
+ return getPluginKindFromType(unwrapTupleMember(members[elementIndex]), checker, getTSNode, options);
607
+ }
608
+ // Past the fixed members, elements take the type of a trailing rest member.
609
+ const last = members[members.length - 1];
610
+ const lastType = last?.type === 'TSNamedTupleMember' ? last.elementType : last;
611
+ if (lastType?.type === 'TSRestType') {
612
+ return getPluginKindFromType(lastType.typeAnnotation, checker, getTSNode, options);
613
+ }
614
+ }
615
+ return null;
616
+ }
617
+ /**
618
+ * Returns the element type of a tuple member, looking through labels,
619
+ * optional markers and rest spreads.
620
+ */
621
+ function unwrapTupleMember(member) {
622
+ let elementType = member.type === 'TSNamedTupleMember' ? member.elementType : member;
623
+ if (elementType.type === 'TSOptionalType') {
624
+ elementType = elementType.typeAnnotation;
625
+ }
626
+ if (elementType.type === 'TSRestType') {
627
+ elementType = elementType.typeAnnotation;
628
+ }
629
+ return elementType;
630
+ }
631
+ /**
632
+ * Returns the plugin kind ('frontend', 'service-manager', or 'mime-renderer')
633
+ * for an object literal expression by inspecting its type annotation, type cast,
634
+ * enclosing array/tuple, factory function return type, or shape (when allowUntyped is true).
635
+ */
636
+ function getPluginObjectKind(node, checker, getTSNode, options) {
637
+ // 0. If checker is available, resolve contextual type per element.
638
+ if (checker && getTSNode) {
639
+ const tsNode = getTSNode(node);
640
+ if (tsNode) {
641
+ try {
642
+ const contextualType = checker.getContextualType(tsNode);
643
+ if (contextualType) {
644
+ const kind = getPluginKindFromTsType(contextualType, checker);
645
+ if (kind) {
646
+ return kind;
647
+ }
648
+ }
649
+ }
650
+ catch {
651
+ // ignore
652
+ }
653
+ }
654
+ }
655
+ // 1. Unwrap any type assertions directly wrapping the object expression.
656
+ let current = node;
657
+ while (current.parent &&
658
+ (current.parent.type === 'TSAsExpression' ||
659
+ current.parent.type === 'TSSatisfiesExpression' ||
660
+ current.parent.type === 'TSTypeAssertion')) {
661
+ const castNode = current.parent;
662
+ const kind = getPluginKindFromType(castNode.typeAnnotation, checker, getTSNode, options);
663
+ if (kind) {
664
+ return kind;
665
+ }
666
+ current = castNode;
667
+ }
668
+ // 2. Check if current is directly assigned to a typed variable declarator.
669
+ if (current.parent?.type === 'VariableDeclarator') {
670
+ const varDecl = current.parent;
671
+ if (varDecl.id.type === 'Identifier' && varDecl.id.typeAnnotation) {
672
+ const kind = getPluginKindFromType(varDecl.id.typeAnnotation.typeAnnotation, checker, getTSNode, options);
673
+ if (kind) {
674
+ return kind;
675
+ }
676
+ }
677
+ }
678
+ // 3. Check if current is returned from a function with an explicit return type.
679
+ const returnedKind = getKindFromEnclosingFunctionReturn(current, checker, getTSNode, options);
680
+ if (returnedKind) {
681
+ return returnedKind;
682
+ }
683
+ // 4. Check if current is an element of an ArrayExpression.
684
+ if (current.parent?.type === 'ArrayExpression') {
685
+ const arrayElements = current.parent.elements;
686
+ const elementIndex = arrayElements.indexOf(current);
687
+ let arrayNode = current.parent;
688
+ while (arrayNode.parent &&
689
+ (arrayNode.parent.type === 'TSAsExpression' ||
690
+ arrayNode.parent.type === 'TSSatisfiesExpression' ||
691
+ arrayNode.parent.type === 'TSTypeAssertion')) {
692
+ const castNode = arrayNode.parent;
693
+ const tupleKind = getTupleElementKind(castNode.typeAnnotation, elementIndex, checker, getTSNode, options);
694
+ if (tupleKind) {
695
+ return tupleKind;
696
+ }
697
+ const kind = getPluginKindFromType(castNode.typeAnnotation, checker, getTSNode, options);
698
+ if (kind) {
699
+ return kind;
700
+ }
701
+ arrayNode = castNode;
702
+ }
703
+ if (arrayNode.parent?.type === 'VariableDeclarator') {
704
+ const varDecl = arrayNode.parent;
705
+ if (varDecl.id.type === 'Identifier' && varDecl.id.typeAnnotation) {
706
+ const typeAnnotation = varDecl.id.typeAnnotation.typeAnnotation;
707
+ const tupleKind = getTupleElementKind(typeAnnotation, elementIndex, checker, getTSNode, options);
708
+ if (tupleKind) {
709
+ return tupleKind;
710
+ }
711
+ const kind = getPluginKindFromType(typeAnnotation, checker, getTSNode, options);
712
+ if (kind) {
713
+ return kind;
714
+ }
715
+ }
716
+ }
717
+ const enclosingFnType = getEnclosingFunctionReturnType(arrayNode);
718
+ if (enclosingFnType) {
719
+ const tupleKind = getTupleElementKind(enclosingFnType, elementIndex, checker, getTSNode, options);
720
+ if (tupleKind) {
721
+ return tupleKind;
722
+ }
723
+ }
724
+ const returnedArrayKind = getKindFromEnclosingFunctionReturn(arrayNode, checker, getTSNode, options);
725
+ if (returnedArrayKind) {
726
+ return returnedArrayKind;
727
+ }
728
+ }
729
+ // 5. If untyped plugin detection is enabled, check shape.
730
+ if (options?.allowUntyped) {
731
+ const hasId = getObjectProperties(node).has('id');
732
+ if (looksLikePluginObject(node, hasId)) {
733
+ return 'frontend';
734
+ }
735
+ if (options.matchMime && looksLikeMimeExtensionObject(node, hasId)) {
736
+ return 'mime-renderer';
737
+ }
738
+ }
739
+ return null;
740
+ }
@@ -0,0 +1,13 @@
1
+ import { TSESTree } from '@typescript-eslint/types';
2
+ import { ParserServices, TSESLint } from '@typescript-eslint/utils';
3
+ import * as ts from 'typescript';
4
+ export interface TypeServices {
5
+ services: ParserServices | null;
6
+ checker: ts.TypeChecker | null;
7
+ getTSNode: ((node: TSESTree.Node) => ts.Node | undefined) | null;
8
+ }
9
+ /**
10
+ * Retrieves the TypeScript parser services, type checker, and node mapper
11
+ * from the rule context, falling back gracefully if type information is unavailable.
12
+ */
13
+ export declare function getTypeServices(context: TSESLint.RuleContext<string, readonly unknown[]>): TypeServices;
@@ -0,0 +1,27 @@
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.getTypeServices = getTypeServices;
8
+ const utils_1 = require("@typescript-eslint/utils");
9
+ /**
10
+ * Retrieves the TypeScript parser services, type checker, and node mapper
11
+ * from the rule context, falling back gracefully if type information is unavailable.
12
+ */
13
+ function getTypeServices(context) {
14
+ let services = null;
15
+ let checker = null;
16
+ try {
17
+ services = utils_1.ESLintUtils.getParserServices(context, true);
18
+ checker = services.program ? services.program.getTypeChecker() : null;
19
+ }
20
+ catch {
21
+ services = null;
22
+ }
23
+ const getTSNode = services
24
+ ? (node) => services?.esTreeNodeToTSNodeMap.get(node)
25
+ : null;
26
+ return { services, checker, getTSNode };
27
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jupyter/eslint-plugin",
3
- "version": "1.3.0",
3
+ "version": "1.4.0",
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",