@jupyter/eslint-plugin 1.1.0 → 1.3.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.
Files changed (40) hide show
  1. package/lib/index.d.ts +49 -2
  2. package/lib/index.js +35 -5
  3. package/lib/rules/galata-prefer-context-menu-helper.d.ts +6 -0
  4. package/lib/rules/galata-prefer-context-menu-helper.js +394 -0
  5. package/lib/rules/galata-prefer-menu-helper.d.ts +6 -0
  6. package/lib/rules/galata-prefer-menu-helper.js +394 -0
  7. package/lib/rules/galata-prefer-notebook-cell-helper.d.ts +6 -0
  8. package/lib/rules/galata-prefer-notebook-cell-helper.js +403 -0
  9. package/lib/rules/galata-prefer-sidebar-activity-helper.d.ts +6 -0
  10. package/lib/rules/galata-prefer-sidebar-activity-helper.js +332 -0
  11. package/lib/rules/no-schema-enum.d.ts +1 -1
  12. package/lib/rules/no-schema-enum.js +54 -2
  13. package/lib/rules/no-untranslated-string.d.ts +2 -1
  14. package/lib/rules/no-untranslated-string.js +191 -113
  15. package/lib/rules/plugin-id-convention.d.ts +7 -0
  16. package/lib/rules/plugin-id-convention.js +296 -0
  17. package/lib/rules/prefer-lazy-imports.d.ts +6 -0
  18. package/lib/rules/prefer-lazy-imports.js +476 -0
  19. package/lib/rules/require-disposable-ownership.js +1 -16
  20. package/lib/rules/require-disposable-transfer.js +7 -2
  21. package/lib/utils/ast.d.ts +12 -0
  22. package/lib/utils/ast.js +49 -0
  23. package/lib/utils/disposables.d.ts +12 -0
  24. package/lib/utils/disposables.js +101 -10
  25. package/lib/utils/lazy-imports.d.ts +93 -0
  26. package/lib/utils/lazy-imports.js +600 -0
  27. package/lib/utils/module-size.d.ts +18 -0
  28. package/lib/utils/module-size.js +249 -0
  29. package/lib/utils/package-json.d.ts +8 -0
  30. package/lib/utils/package-json.js +76 -0
  31. package/lib/utils/playwright-selectors.d.ts +56 -5
  32. package/lib/utils/playwright-selectors.js +205 -12
  33. package/lib/utils/plugin-utils.d.ts +50 -2
  34. package/lib/utils/plugin-utils.js +221 -38
  35. package/lib/utils/shared-packages.d.ts +9 -0
  36. package/lib/utils/shared-packages.js +128 -0
  37. package/lib/utils/signal-lifetime.js +66 -5
  38. package/lib/utils/signals.d.ts +2 -8
  39. package/lib/utils/signals.js +7 -42
  40. package/package.json +1 -1
@@ -5,15 +5,20 @@
5
5
  */
6
6
  Object.defineProperty(exports, "__esModule", { value: true });
7
7
  exports.INTERACTION_METHODS = exports.LOCATOR_METHODS = void 0;
8
+ exports.resolveLocatorBinding = resolveLocatorBinding;
8
9
  exports.isRightClick = isRightClick;
9
10
  exports.matchSelectorInteraction = matchSelectorInteraction;
10
11
  exports.extractStaticSelectorText = extractStaticSelectorText;
11
12
  exports.combineStaticSelectorText = combineStaticSelectorText;
13
+ exports.isTestScopeBoundary = isTestScopeBoundary;
14
+ exports.enclosingTestScope = enclosingTestScope;
15
+ const utils_1 = require("@typescript-eslint/utils");
12
16
  /**
13
17
  * Playwright locator-producing methods.
14
18
  */
15
19
  exports.LOCATOR_METHODS = new Set([
16
20
  'locator',
21
+ 'getByRole',
17
22
  'getByText',
18
23
  'getByTitle',
19
24
  'getByLabel',
@@ -32,6 +37,8 @@ exports.INTERACTION_METHODS = new Set([
32
37
  'hover',
33
38
  'tap',
34
39
  'fill',
40
+ 'type',
41
+ 'pressSequentially',
35
42
  'check',
36
43
  'uncheck',
37
44
  'selectOption',
@@ -59,9 +66,50 @@ const TEXT_MATCH_METHODS = new Set([
59
66
  'getByPlaceholder',
60
67
  'getByAltText'
61
68
  ]);
69
+ /**
70
+ * The expression a locator-holding identifier was assigned, or null when the
71
+ * binding must not be followed. A locator held in a variable then reaches the
72
+ * same `page` root as the inline chain.
73
+ *
74
+ * Only a `const` declared with an initializer is followed. `const` is what
75
+ * makes the assignment the single write, so the expression read here is the
76
+ * one the gesture acts on; a `let` could hold a different locator by then.
77
+ *
78
+ * This is the resolver a rule normally passes as the `resolveBinding`
79
+ * argument of {@link matchSelectorInteraction}.
80
+ */
81
+ function resolveLocatorBinding(node, scope) {
82
+ const variable = utils_1.ASTUtils.findVariable(scope, node);
83
+ if (!variable || variable.defs.length !== 1) {
84
+ return null;
85
+ }
86
+ const declarator = variable.defs[0].node;
87
+ if (declarator.type !== 'VariableDeclarator' || !declarator.init) {
88
+ return null;
89
+ }
90
+ const declaration = declarator.parent;
91
+ if (declaration?.type !== 'VariableDeclaration' ||
92
+ declaration.kind !== 'const') {
93
+ return null;
94
+ }
95
+ return declarator.init;
96
+ }
62
97
  function isPageIdentifier(node) {
63
98
  return node.type === 'Identifier' && node.name === 'page';
64
99
  }
100
+ /** Strips the `!` and `as T` wrappers a locator expression may carry. */
101
+ function unwrapAssertions(node) {
102
+ let current = node;
103
+ while (current.type === 'TSNonNullExpression' ||
104
+ current.type === 'TSAsExpression' ||
105
+ current.type === 'AwaitExpression') {
106
+ current =
107
+ current.type === 'AwaitExpression'
108
+ ? current.argument
109
+ : current.expression;
110
+ }
111
+ return current;
112
+ }
65
113
  function firstArgument(node) {
66
114
  const arg = node.arguments[0];
67
115
  return arg && arg.type !== 'SpreadElement' ? arg : null;
@@ -78,16 +126,51 @@ function isRightClick(node) {
78
126
  prop.value.type === 'Literal' &&
79
127
  prop.value.value === 'right'));
80
128
  }
129
+ /**
130
+ * Reads the static `name` option of a `getByRole(role, { name })` call.
131
+ */
132
+ function roleNameArgument(node) {
133
+ const options = node.arguments[1];
134
+ if (!options || options.type !== 'ObjectExpression') {
135
+ return undefined;
136
+ }
137
+ for (const prop of options.properties) {
138
+ if (prop.type === 'Property' &&
139
+ !prop.computed &&
140
+ ((prop.key.type === 'Identifier' && prop.key.name === 'name') ||
141
+ (prop.key.type === 'Literal' && prop.key.value === 'name')) &&
142
+ prop.value.type !== 'AssignmentPattern' &&
143
+ prop.value.type !== 'TSEmptyBodyFunctionExpression') {
144
+ return prop.value;
145
+ }
146
+ }
147
+ return undefined;
148
+ }
81
149
  /**
82
150
  * Walks a locator-producing chain rooted at `page`, e.g.
83
151
  * `page.locator(a).getByText(b).first()`, and returns the selector arguments
84
152
  * in root-to-tip order. Returns null when the chain is not rooted at `page`,
85
153
  * contains a non-locator call, or carries no selector argument at all.
154
+ *
155
+ * With a `resolveBinding` callback the walk also steps through an identifier
156
+ * holding a locator, so that `const cell = page.locator(a); cell.click();`
157
+ * reaches the same `page` root as the inline form.
86
158
  */
87
- function collectLocatorChainSelectors(node) {
159
+ function collectLocatorChainSelectors(node, resolveBinding) {
88
160
  const selectors = [];
89
- let current = node;
90
- for (;;) {
161
+ let current = unwrapAssertions(node);
162
+ // A binding may itself be assigned from another binding, so the walk can
163
+ // alternate between resolving a name and stepping down a call. The bound
164
+ // stops a cycle such as `const a = b, b = a` from looping.
165
+ for (let steps = 0; steps < 32; steps++) {
166
+ if (current.type === 'Identifier') {
167
+ const resolved = resolveBinding ? resolveBinding(current) : null;
168
+ if (!resolved) {
169
+ return null;
170
+ }
171
+ current = unwrapAssertions(resolved);
172
+ continue;
173
+ }
91
174
  if (current.type !== 'CallExpression') {
92
175
  return null;
93
176
  }
@@ -100,17 +183,25 @@ function collectLocatorChainSelectors(node) {
100
183
  if (exports.LOCATOR_METHODS.has(callee.property.name)) {
101
184
  const arg = firstArgument(current);
102
185
  if (arg) {
103
- selectors.unshift({ method: callee.property.name, argNode: arg });
186
+ selectors.unshift({
187
+ method: callee.property.name,
188
+ argNode: arg,
189
+ ...(callee.property.name === 'getByRole'
190
+ ? { nameArgNode: roleNameArgument(current) }
191
+ : {})
192
+ });
104
193
  }
105
194
  }
106
195
  else if (!CHAIN_PASSTHROUGH_METHODS.has(callee.property.name)) {
107
196
  return null;
108
197
  }
109
- if (isPageIdentifier(callee.object)) {
198
+ const object = unwrapAssertions(callee.object);
199
+ if (isPageIdentifier(object)) {
110
200
  return selectors.length > 0 ? selectors : null;
111
201
  }
112
- current = callee.object;
202
+ current = object;
113
203
  }
204
+ return null;
114
205
  }
115
206
  /**
116
207
  * Matches raw Playwright selector interactions on the Galata `page` fixture:
@@ -121,8 +212,12 @@ function collectLocatorChainSelectors(node) {
121
212
  * `page.locator('#filebrowser').getByText('notebooks').dblclick()`
122
213
  *
123
214
  * Returns null for any other shape
215
+ *
216
+ * `resolveBinding` is optional. Without it a chain has to be written inline
217
+ * from `page`; with it a locator held in a variable is followed to its
218
+ * assignment first.
124
219
  */
125
- function matchSelectorInteraction(node) {
220
+ function matchSelectorInteraction(node, resolveBinding) {
126
221
  const { callee } = node;
127
222
  if (callee.type !== 'MemberExpression' || callee.computed) {
128
223
  return null;
@@ -146,7 +241,7 @@ function matchSelectorInteraction(node) {
146
241
  : null;
147
242
  }
148
243
  // page.locator(selector).getByText(...).click(...)
149
- const selectorParts = collectLocatorChainSelectors(callee.object);
244
+ const selectorParts = collectLocatorChainSelectors(callee.object, resolveBinding);
150
245
  return selectorParts
151
246
  ? {
152
247
  callNode: node,
@@ -162,13 +257,23 @@ function matchSelectorInteraction(node) {
162
257
  * matched against known patterns. String literals return their value;
163
258
  * template literals return their static parts joined by a space, so
164
259
  * `` `.jp-DirListing-item span:has-text("${name}")` `` still exposes its
165
- * static prefix. Fully dynamic expressions return null.
260
+ * static prefix. Pass `allowPartialTemplate: false` when interpolated
261
+ * templates should be treated as dynamic. Fully dynamic expressions return
262
+ * null.
166
263
  */
167
- function extractStaticSelectorText(node) {
264
+ function extractStaticSelectorText(node, options = {}) {
168
265
  if (node.type === 'Literal') {
169
266
  return typeof node.value === 'string' ? node.value : null;
170
267
  }
268
+ const allowPartialTemplate = options.allowPartialTemplate !== false;
171
269
  if (node.type === 'TemplateLiteral') {
270
+ if (!allowPartialTemplate) {
271
+ return node.expressions.length > 0
272
+ ? null
273
+ : node.quasis
274
+ .map(quasi => quasi.value.cooked ?? quasi.value.raw)
275
+ .join('');
276
+ }
172
277
  return node.quasis.map(quasi => quasi.value.cooked ?? '').join(' ');
173
278
  }
174
279
  return null;
@@ -178,16 +283,104 @@ function extractStaticSelectorText(node) {
178
283
  * pattern-matchable string. Arguments of text-matching locators (`getByText`,
179
284
  * `getByTitle`, …) are normalized to the `text=` selector form, so patterns
180
285
  * written against `text=` selectors also match the locator-method shape.
181
- * Returns null when no part is static.
286
+ * `getByRole(role, { name })` is normalized to the CSS-attribute form
287
+ * `[role="<role>"] text=<name>` for the same reason. Returns null when no part
288
+ * is static.
182
289
  */
183
290
  function combineStaticSelectorText(match) {
184
291
  const parts = [];
185
- for (const { method, argNode } of match.selectorParts) {
292
+ for (const { method, argNode, nameArgNode } of match.selectorParts) {
186
293
  const text = extractStaticSelectorText(argNode);
187
294
  if (text === null) {
188
295
  continue;
189
296
  }
297
+ if (method === 'getByRole') {
298
+ // The role is emitted even without a name, but a name is never emitted
299
+ // without its role: a bare `text=File` from a dynamic role would look
300
+ // like an unscoped label and could be mistaken for a menu bar item.
301
+ const name = nameArgNode ? extractStaticSelectorText(nameArgNode) : null;
302
+ parts.push(name === null ? `[role="${text}"]` : `[role="${text}"] text=${name}`);
303
+ continue;
304
+ }
190
305
  parts.push(TEXT_MATCH_METHODS.has(method) ? `text=${text}` : text);
191
306
  }
192
307
  return parts.length > 0 ? parts.join(' ') : null;
193
308
  }
309
+ /**
310
+ * Calls whose callback is stored and run later. Statements next to such a call
311
+ * say nothing about the state its body starts in.
312
+ */
313
+ const DEFERRED_CALLBACK_CALLEES = new Set([
314
+ 'test',
315
+ 'it',
316
+ 'describe',
317
+ 'suite',
318
+ 'beforeAll',
319
+ 'beforeEach',
320
+ 'afterAll',
321
+ 'afterEach'
322
+ ]);
323
+ /**
324
+ * The expression a callee is written on, or null once the name itself is
325
+ * reached. A parameterized test is called twice, `test.each(cases)('name',
326
+ * cb)`, and the table form tags a template first, `` test.each`a | b`('name',
327
+ * cb) ``. Stopping at the inner call would read no name and leave `cb` outside
328
+ * any test scope, so one test's state would reach the next.
329
+ */
330
+ function calleeReceiver(node) {
331
+ switch (node.type) {
332
+ case 'MemberExpression':
333
+ return node.object;
334
+ case 'CallExpression':
335
+ return node.callee;
336
+ case 'TaggedTemplateExpression':
337
+ return node.tag;
338
+ default:
339
+ return null;
340
+ }
341
+ }
342
+ function rootCalleeName(node) {
343
+ let current = node;
344
+ let receiver = calleeReceiver(current);
345
+ while (receiver) {
346
+ current = receiver;
347
+ receiver = calleeReceiver(current);
348
+ }
349
+ return current.type === 'Identifier' ? current.name : null;
350
+ }
351
+ /**
352
+ * Whether `node` bounds the statements a rule may read as "what ran before".
353
+ *
354
+ * A rule that reasons about UI state — which menu is open, what was selected —
355
+ * reads the statements preceding a gesture. That reading has to stop somewhere,
356
+ * and the boundary is the unit that runs as one: a test callback or a named
357
+ * function.
358
+ */
359
+ function isTestScopeBoundary(node) {
360
+ if (node.type === 'FunctionDeclaration') {
361
+ return true;
362
+ }
363
+ if (node.type !== 'FunctionExpression' &&
364
+ node.type !== 'ArrowFunctionExpression') {
365
+ return false;
366
+ }
367
+ const parent = node.parent;
368
+ if (parent?.type === 'VariableDeclarator' || parent?.type === 'Property') {
369
+ return true;
370
+ }
371
+ return (parent?.type === 'CallExpression' &&
372
+ parent.arguments.includes(node) &&
373
+ DEFERRED_CALLBACK_CALLEES.has(rootCalleeName(parent.callee) ?? ''));
374
+ }
375
+ /**
376
+ * The innermost test callback or named function containing `node`, which is
377
+ * where a lookback over preceding statements has to stop. Falls back to the
378
+ * `Program` for a gesture written at the top level of a file.
379
+ */
380
+ function enclosingTestScope(node) {
381
+ let scope = node;
382
+ while (scope.parent && !isTestScopeBoundary(scope)) {
383
+ scope = scope.parent;
384
+ }
385
+ return scope;
386
+ }
@@ -1,4 +1,5 @@
1
1
  import { TSESTree } from '@typescript-eslint/types';
2
+ import { TSESLint } from '@typescript-eslint/utils';
2
3
  import * as ts from 'typescript';
3
4
  export type JupyterPluginKind = 'frontend' | 'service-manager';
4
5
  /**
@@ -12,9 +13,23 @@ export declare function getJupyterPluginKind(node: TSESTree.VariableDeclarator,
12
13
  */
13
14
  export declare function getObjectProperties(obj: TSESTree.ObjectExpression): Map<string, TSESTree.Property>;
14
15
  /**
15
- * Gets the plugin ID from an object expression
16
+ * Gets the plugin ID from an object expression. Without a scope only a
17
+ * literal, a template literal without substitutions or a `+` chain of literals
18
+ * resolves. With a scope, a `const` string and a member of a `const` object
19
+ * resolve too, and with a checker so does anything with a string literal
20
+ * type, such as a `const` imported from another module.
16
21
  */
17
- export declare function getPluginId(obj: TSESTree.ObjectExpression): string | null;
22
+ export declare function getPluginId(obj: TSESTree.ObjectExpression, scope?: TSESLint.Scope.Scope | null, checker?: ts.TypeChecker | null, getTSNode?: ((n: TSESTree.Node) => ts.Node | undefined) | null): string | null;
23
+ /**
24
+ * Resolves an expression to the string it holds at lint time.
25
+ * `getStaticValue` folds the plain JavaScript part: a literal, a template
26
+ * literal, a `+` chain, a variable that is never reassigned and a member of an
27
+ * object literal that is never mutated, with TypeScript casts stripped. The
28
+ * checker then answers for the TypeScript part: a `const` imported from
29
+ * another module, a namespace member, an enum member or a `static readonly`
30
+ * class property.
31
+ */
32
+ export declare function resolveStaticString(node: TSESTree.Node, scope?: TSESLint.Scope.Scope | null, checker?: ts.TypeChecker | null, getTSNode?: ((n: TSESTree.Node) => ts.Node | undefined) | null): string | null;
18
33
  export interface TokenEntry {
19
34
  name: string;
20
35
  node: TSESTree.Node;
@@ -25,3 +40,36 @@ export interface TokenEntry {
25
40
  export declare function extractArrayTokens(arrayExpr: TSESTree.ArrayExpression): TokenEntry[];
26
41
  export declare function isNullableAnnotation(param: TSESTree.Identifier): boolean;
27
42
  export declare function extractParameterType(param: TSESTree.Identifier): string | null;
43
+ /**
44
+ * Returns true when a type annotation mentions a JupyterLab plugin type at any
45
+ * depth, so arrays, unions and wrappers such as `Promise<...>` are recognised.
46
+ * Resolves import aliases through the TypeScript checker when it is available.
47
+ */
48
+ export declare function typeMentionsJupyterPlugin(typeNode: TSESTree.TypeNode | undefined | null, checker?: ts.TypeChecker | null, getTSNode?: ((n: TSESTree.Node) => ts.Node | undefined) | null): boolean;
49
+ /**
50
+ * Returns true when a type annotation mentions the MIME renderer extension
51
+ * entry type at any depth, with the same wrappers as
52
+ * `typeMentionsJupyterPlugin`. JupyterLab registers each entry as a plugin
53
+ * whose ID is the entry's `id`, so the entry follows the plugin ID convention.
54
+ */
55
+ export declare function typeMentionsMimeExtension(typeNode: TSESTree.TypeNode | undefined | null, checker?: ts.TypeChecker | null, getTSNode?: ((n: TSESTree.Node) => ts.Node | undefined) | null): boolean;
56
+ /**
57
+ * Returns true when a property holds something callable: a function written in
58
+ * place, or a name referring to one declared elsewhere.
59
+ */
60
+ export declare function isCallableProperty(property: TSESTree.Property | undefined): boolean;
61
+ /**
62
+ * Returns true when an object literal has the shape of a JupyterLab plugin:
63
+ * a string `id`, an `activate` function, and at least one of the properties
64
+ * which only plugins carry. Used for plugin objects written without a type
65
+ * annotation. A caller that resolves the ID itself passes whether one is
66
+ * present, so this check needs no type information.
67
+ */
68
+ export declare function looksLikePluginObject(node: TSESTree.ObjectExpression, hasId?: boolean): boolean;
69
+ /**
70
+ * Returns true when an object literal has the shape of a MIME renderer
71
+ * extension entry: a string `id` and a `rendererFactory`. Used for entries
72
+ * written without a type annotation. A caller that resolves the ID itself
73
+ * passes whether one is present.
74
+ */
75
+ export declare function looksLikeMimeExtensionObject(node: TSESTree.ObjectExpression, hasId?: boolean): boolean;
@@ -40,9 +40,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
40
40
  exports.getJupyterPluginKind = getJupyterPluginKind;
41
41
  exports.getObjectProperties = getObjectProperties;
42
42
  exports.getPluginId = getPluginId;
43
+ exports.resolveStaticString = resolveStaticString;
43
44
  exports.extractArrayTokens = extractArrayTokens;
44
45
  exports.isNullableAnnotation = isNullableAnnotation;
45
46
  exports.extractParameterType = extractParameterType;
47
+ exports.typeMentionsJupyterPlugin = typeMentionsJupyterPlugin;
48
+ exports.typeMentionsMimeExtension = typeMentionsMimeExtension;
49
+ exports.isCallableProperty = isCallableProperty;
50
+ exports.looksLikePluginObject = looksLikePluginObject;
51
+ exports.looksLikeMimeExtensionObject = looksLikeMimeExtensionObject;
52
+ const utils_1 = require("@typescript-eslint/utils");
46
53
  const ts = __importStar(require("typescript"));
47
54
  /**
48
55
  * Gets plugin kind from a variable declaration type annotation.
@@ -68,26 +75,12 @@ function getJupyterPluginKind(node, checker, getTSNode) {
68
75
  }
69
76
  // Slow path: resolve import aliases via the TS checker.
70
77
  if (checker && getTSNode && typeNode.typeName.type === 'Identifier') {
71
- try {
72
- const tsNameNode = getTSNode(typeNode.typeName);
73
- if (tsNameNode) {
74
- const symbol = checker.getSymbolAtLocation(tsNameNode);
75
- if (symbol) {
76
- const resolved = symbol.flags & ts.SymbolFlags.Alias
77
- ? checker.getAliasedSymbol(symbol)
78
- : symbol;
79
- const resolvedName = resolved.getName();
80
- if (resolvedName === 'JupyterFrontEndPlugin') {
81
- return 'frontend';
82
- }
83
- if (resolvedName === 'ServiceManagerPlugin') {
84
- return 'service-manager';
85
- }
86
- }
87
- }
78
+ const resolvedName = resolveTypeAlias(typeNode.typeName, checker, getTSNode);
79
+ if (resolvedName === 'JupyterFrontEndPlugin') {
80
+ return 'frontend';
88
81
  }
89
- catch {
90
- // Fall through if checker/mapper unavailable
82
+ if (resolvedName === 'ServiceManagerPlugin') {
83
+ return 'service-manager';
91
84
  }
92
85
  }
93
86
  return null;
@@ -115,28 +108,46 @@ function getObjectProperties(obj) {
115
108
  return props;
116
109
  }
117
110
  /**
118
- * Gets the plugin ID from an object expression
111
+ * Gets the plugin ID from an object expression. Without a scope only a
112
+ * literal, a template literal without substitutions or a `+` chain of literals
113
+ * resolves. With a scope, a `const` string and a member of a `const` object
114
+ * resolve too, and with a checker so does anything with a string literal
115
+ * type, such as a `const` imported from another module.
119
116
  */
120
- function getPluginId(obj) {
121
- for (const prop of obj.properties) {
122
- if (prop.type === 'Property') {
123
- let keyName = null;
124
- if (prop.key.type === 'Identifier') {
125
- keyName = prop.key.name;
126
- }
127
- else if (prop.key.type === 'Literal' &&
128
- typeof prop.key.value === 'string') {
129
- keyName = prop.key.value;
130
- }
131
- if (keyName === 'id' && prop.value.type === 'Literal') {
132
- const value = prop.value.value;
133
- if (typeof value === 'string') {
134
- return value;
135
- }
136
- }
117
+ function getPluginId(obj, scope, checker, getTSNode) {
118
+ const idProperty = getObjectProperties(obj).get('id');
119
+ return idProperty
120
+ ? resolveStaticString(idProperty.value, scope, checker, getTSNode)
121
+ : null;
122
+ }
123
+ /**
124
+ * Resolves an expression to the string it holds at lint time.
125
+ * `getStaticValue` folds the plain JavaScript part: a literal, a template
126
+ * literal, a `+` chain, a variable that is never reassigned and a member of an
127
+ * object literal that is never mutated, with TypeScript casts stripped. The
128
+ * checker then answers for the TypeScript part: a `const` imported from
129
+ * another module, a namespace member, an enum member or a `static readonly`
130
+ * class property.
131
+ */
132
+ function resolveStaticString(node, scope, checker, getTSNode) {
133
+ const folded = utils_1.ASTUtils.getStaticValue(node, scope ?? undefined);
134
+ if (typeof folded?.value === 'string') {
135
+ return folded.value;
136
+ }
137
+ if (!checker || !getTSNode) {
138
+ return null;
139
+ }
140
+ try {
141
+ const tsNode = getTSNode(node);
142
+ if (!tsNode) {
143
+ return null;
137
144
  }
145
+ const type = checker.getTypeAtLocation(tsNode);
146
+ return type.isStringLiteral() ? type.value : null;
147
+ }
148
+ catch {
149
+ return null;
138
150
  }
139
- return null;
140
151
  }
141
152
  /**
142
153
  * Extracts token names and nodes from an array, including member expressions like JupyterFrontEnd.IPaths
@@ -204,3 +215,175 @@ function extractTypeName(typeName) {
204
215
  }
205
216
  return null;
206
217
  }
218
+ const PLUGIN_TYPE_NAMES = ['JupyterFrontEndPlugin', 'ServiceManagerPlugin'];
219
+ /**
220
+ * Returns true when a type name refers to a JupyterLab plugin type. Only the
221
+ * last segment is compared, so a namespaced spelling such as
222
+ * `Private.JupyterFrontEndPlugin` matches too.
223
+ */
224
+ function isPluginTypeName(name) {
225
+ if (!name) {
226
+ return false;
227
+ }
228
+ const lastSegment = name.split('.').pop() ?? name;
229
+ return PLUGIN_TYPE_NAMES.includes(lastSegment);
230
+ }
231
+ /**
232
+ * Returns true when `matches` accepts a type reference found at any depth of
233
+ * a type annotation, so arrays, unions and wrappers such as `Promise<...>` are
234
+ * recognised.
235
+ */
236
+ function typeMentions(typeNode, matches, depth = 0) {
237
+ if (!typeNode || depth > 6) {
238
+ return false;
239
+ }
240
+ switch (typeNode.type) {
241
+ case 'TSTypeReference':
242
+ if (matches(typeNode)) {
243
+ return true;
244
+ }
245
+ return (typeNode.typeArguments?.params ?? []).some(param => typeMentions(param, matches, depth + 1));
246
+ case 'TSArrayType':
247
+ return typeMentions(typeNode.elementType, matches, depth + 1);
248
+ case 'TSUnionType':
249
+ case 'TSIntersectionType':
250
+ return typeNode.types.some(type => typeMentions(type, matches, depth + 1));
251
+ case 'TSTupleType':
252
+ return typeNode.elementTypes.some(type => typeMentions(type, matches, depth + 1));
253
+ case 'TSTypeOperator':
254
+ case 'TSRestType':
255
+ case 'TSOptionalType':
256
+ return typeMentions(typeNode.typeAnnotation ?? null, matches, depth + 1);
257
+ case 'TSNamedTupleMember':
258
+ return typeMentions(typeNode.elementType, matches, depth + 1);
259
+ default:
260
+ return false;
261
+ }
262
+ }
263
+ /**
264
+ * Returns true when a type annotation mentions a JupyterLab plugin type at any
265
+ * depth, so arrays, unions and wrappers such as `Promise<...>` are recognised.
266
+ * Resolves import aliases through the TypeScript checker when it is available.
267
+ */
268
+ function typeMentionsJupyterPlugin(typeNode, checker, getTSNode) {
269
+ return typeMentions(typeNode, reference => {
270
+ if (isPluginTypeName(extractTypeName(reference.typeName))) {
271
+ return true;
272
+ }
273
+ return (!!checker &&
274
+ !!getTSNode &&
275
+ reference.typeName.type === 'Identifier' &&
276
+ isPluginTypeName(resolveTypeAlias(reference.typeName, checker, getTSNode)));
277
+ });
278
+ }
279
+ /** The namespace and interface which type a MIME renderer extension entry. */
280
+ const MIME_EXTENSION_NAMESPACE = 'IRenderMime';
281
+ const MIME_EXTENSION_TYPE_NAME = 'IExtension';
282
+ /**
283
+ * Returns true when a type reference is `IRenderMime.IExtension`. Only the
284
+ * qualified spelling counts, because a bare `IExtension` is too common a name
285
+ * to mean anything on its own. The namespace may sit behind a module import
286
+ * (`Interfaces.IRenderMime.IExtension`), and a renamed import such as
287
+ * `import { IRenderMime as RM }` is resolved through the TypeScript checker
288
+ * when it is available.
289
+ */
290
+ function isMimeExtensionReference(reference, checker, getTSNode) {
291
+ const typeName = reference.typeName;
292
+ if (typeName.type !== 'TSQualifiedName' ||
293
+ typeName.right.name !== MIME_EXTENSION_TYPE_NAME) {
294
+ return false;
295
+ }
296
+ const namespace = extractTypeName(typeName.left)?.split('.').pop();
297
+ if (namespace === MIME_EXTENSION_NAMESPACE) {
298
+ return true;
299
+ }
300
+ return (!!checker &&
301
+ !!getTSNode &&
302
+ typeName.left.type === 'Identifier' &&
303
+ resolveTypeAlias(typeName.left, checker, getTSNode) ===
304
+ MIME_EXTENSION_NAMESPACE);
305
+ }
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
+ /**
316
+ * Resolves an identifier through the TypeScript checker to the name it aliases,
317
+ * e.g. `import { JupyterFrontEndPlugin as JFEP }` gives back the original name.
318
+ */
319
+ function resolveTypeAlias(identifier, checker, getTSNode) {
320
+ try {
321
+ const tsNode = getTSNode(identifier);
322
+ if (!tsNode) {
323
+ return null;
324
+ }
325
+ const symbol = checker.getSymbolAtLocation(tsNode);
326
+ if (!symbol) {
327
+ return null;
328
+ }
329
+ const resolved = symbol.flags & ts.SymbolFlags.Alias
330
+ ? checker.getAliasedSymbol(symbol)
331
+ : symbol;
332
+ return resolved.getName();
333
+ }
334
+ catch {
335
+ return null;
336
+ }
337
+ }
338
+ const PLUGIN_SHAPE_PROPERTIES = [
339
+ 'autoStart',
340
+ 'requires',
341
+ 'optional',
342
+ 'provides',
343
+ 'description'
344
+ ];
345
+ /**
346
+ * Returns true when a property holds something callable: a function written in
347
+ * place, or a name referring to one declared elsewhere.
348
+ */
349
+ function isCallableProperty(property) {
350
+ if (!property) {
351
+ return false;
352
+ }
353
+ switch (property.value.type) {
354
+ case 'FunctionExpression':
355
+ case 'ArrowFunctionExpression':
356
+ case 'Identifier':
357
+ case 'MemberExpression':
358
+ return true;
359
+ default:
360
+ return false;
361
+ }
362
+ }
363
+ /**
364
+ * Returns true when an object literal has the shape of a JupyterLab plugin:
365
+ * a string `id`, an `activate` function, and at least one of the properties
366
+ * which only plugins carry. Used for plugin objects written without a type
367
+ * annotation. A caller that resolves the ID itself passes whether one is
368
+ * present, so this check needs no type information.
369
+ */
370
+ function looksLikePluginObject(node, hasId = getPluginId(node) !== null) {
371
+ const properties = getObjectProperties(node);
372
+ if (!hasId || !properties.has('id')) {
373
+ return false;
374
+ }
375
+ if (!isCallableProperty(properties.get('activate'))) {
376
+ return false;
377
+ }
378
+ return PLUGIN_SHAPE_PROPERTIES.some(name => properties.has(name));
379
+ }
380
+ /**
381
+ * Returns true when an object literal has the shape of a MIME renderer
382
+ * extension entry: a string `id` and a `rendererFactory`. Used for entries
383
+ * written without a type annotation. A caller that resolves the ID itself
384
+ * passes whether one is present.
385
+ */
386
+ function looksLikeMimeExtensionObject(node, hasId = getPluginId(node) !== null) {
387
+ const properties = getObjectProperties(node);
388
+ return hasId && properties.has('id') && properties.has('rendererFactory');
389
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Walks up from a linted file to its labextension manifest and returns the
3
+ * packages the application provides at runtime. Importing one of those at the
4
+ * top of a plugin module adds nothing to the extension's own bundle.
5
+ *
6
+ * Returns an empty list when no manifest declares any, which is the common
7
+ * case outside a monorepo sharing packages between its extensions.
8
+ */
9
+ export declare function getHostProvidedPackages(fromFile: string): string[];