@jupyter/eslint-plugin 1.1.0 → 1.2.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.
@@ -0,0 +1,515 @@
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.ALWAYS_IGNORED_IMPORTS = exports.DEFAULT_ALLOWED_PACKAGES = exports.DEFAULT_MINIMUM_SIZE = void 0;
8
+ exports.matchesPatterns = matchesPatterns;
9
+ exports.isEagerlyReached = isEagerlyReached;
10
+ exports.isInInteractionCallback = isInInteractionCallback;
11
+ exports.isInPluginTokenList = isInPluginTokenList;
12
+ exports.buildDeferredImportSnippet = buildDeferredImportSnippet;
13
+ const plugin_utils_1 = require("./plugin-utils");
14
+ /**
15
+ * An async chunk carries a few hundred bytes of bundler runtime, so around one
16
+ * kilobyte of code the saving cancels out. The default sits well above that
17
+ * break-even point: across the Jupyter extensions this rule was measured on,
18
+ * four kilobytes reports half as many imports as one kilobyte while still
19
+ * covering 95% of the code which could be deferred.
20
+ */
21
+ exports.DEFAULT_MINIMUM_SIZE = 4096;
22
+ /**
23
+ * Packages shared through Module Federation, which the application therefore
24
+ * loads whether or not a plugin module imports them at the top.
25
+ *
26
+ * This is the singleton list from `jupyterlab/staging/package.json`, minus
27
+ * `@lumino/datagrid` which core itself defers (see `packages/csvviewer`).
28
+ * Entries prefixed with `!` are denied even when another pattern allows them.
29
+ */
30
+ exports.DEFAULT_ALLOWED_PACKAGES = [
31
+ '@jupyterlab/*',
32
+ '@lumino/*',
33
+ '!@lumino/datagrid',
34
+ '@jupyter/ydoc',
35
+ '@jupyter/react-components',
36
+ '@jupyter/web-components',
37
+ '@codemirror/language',
38
+ '@codemirror/state',
39
+ '@codemirror/view',
40
+ '@lezer/common',
41
+ '@lezer/highlight',
42
+ '@microsoft/fast-element',
43
+ '@microsoft/fast-foundation',
44
+ 'react',
45
+ 'react-dom',
46
+ 'yjs'
47
+ ];
48
+ /**
49
+ * Assets which a bundler turns into a URL or a style side effect rather than
50
+ * into bundled bytes, so deferring the import saves nothing.
51
+ *
52
+ * Images and fonts are `asset/resource` in the builder configuration, so they
53
+ * are always emitted as separate files and the browser fetches them only when
54
+ * they are used. A stylesheet goes through `style-loader`, which applies it
55
+ * when it is imported, so deferring it would change when the styles take
56
+ * effect rather than only what is downloaded.
57
+ *
58
+ * Assets which are inlined into the bundle as text are deliberately absent:
59
+ * `.svg` imported from JavaScript, `.raw.css`, `.md`, `.txt` and `.json` all
60
+ * add their full size to the startup chunk, so they are measured like any
61
+ * other module.
62
+ */
63
+ exports.ALWAYS_IGNORED_IMPORTS = [
64
+ '*.css',
65
+ // A raw stylesheet is inlined as text, not applied as a style.
66
+ '!*.raw.css',
67
+ '*.scss',
68
+ '*.sass',
69
+ '*.less',
70
+ '*.png',
71
+ '*.jpg',
72
+ '*.jpeg',
73
+ '*.gif',
74
+ '*.webp',
75
+ '*.ico',
76
+ '*.avif',
77
+ '*.woff',
78
+ '*.woff2',
79
+ '*.ttf',
80
+ '*.eot',
81
+ '*.otf',
82
+ '*.wasm',
83
+ '*.html'
84
+ ];
85
+ /**
86
+ * Array and iterable methods which call their callback right away, so a
87
+ * reference inside such a callback still runs at module load.
88
+ */
89
+ const IMMEDIATE_CALLBACK_METHODS = new Set([
90
+ 'map',
91
+ 'forEach',
92
+ 'filter',
93
+ 'reduce',
94
+ 'reduceRight',
95
+ 'some',
96
+ 'every',
97
+ 'find',
98
+ 'findIndex',
99
+ 'findLast',
100
+ 'findLastIndex',
101
+ 'flatMap',
102
+ 'sort'
103
+ ]);
104
+ const globCache = new Map();
105
+ /**
106
+ * Compiles a pattern where `*` matches any run of characters. Everything else
107
+ * is matched literally.
108
+ */
109
+ function compileGlob(pattern) {
110
+ let regexp = globCache.get(pattern);
111
+ if (!regexp) {
112
+ const escaped = pattern.replace(/[.+^${}()|[\]\\?]/g, '\\$&');
113
+ regexp = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
114
+ globCache.set(pattern, regexp);
115
+ }
116
+ return regexp;
117
+ }
118
+ /**
119
+ * Extracts the package name from an import specifier, or null for a relative
120
+ * or absolute path. Subpath imports resolve to their owning package, so
121
+ * `@jupyterlab/services/lib/kernel` gives `@jupyterlab/services`.
122
+ */
123
+ function getPackageName(specifier) {
124
+ if (specifier.startsWith('.') || specifier.startsWith('/')) {
125
+ return null;
126
+ }
127
+ const parts = specifier.split('/');
128
+ if (specifier.startsWith('@')) {
129
+ return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
130
+ }
131
+ return parts[0] || null;
132
+ }
133
+ /**
134
+ * Matches an import specifier against a list of glob patterns. The specifier is
135
+ * tested both as written and as its owning package name. A matching `!` pattern
136
+ * denies the specifier regardless of any other match.
137
+ */
138
+ function matchesPatterns(specifier, patterns) {
139
+ const packageName = getPackageName(specifier);
140
+ const candidates = packageName && packageName !== specifier
141
+ ? [specifier, packageName]
142
+ : [specifier];
143
+ let allowed = false;
144
+ for (const pattern of patterns) {
145
+ const denied = pattern.startsWith('!');
146
+ const regexp = compileGlob(denied ? pattern.slice(1) : pattern);
147
+ if (candidates.some(candidate => regexp.test(candidate))) {
148
+ if (denied) {
149
+ return false;
150
+ }
151
+ allowed = true;
152
+ }
153
+ }
154
+ return allowed;
155
+ }
156
+ /**
157
+ * Returns true when a call runs its callback argument before returning, as
158
+ * `list.map(fn)`, `Array.from(items, fn)` and `new Promise(fn)` all do.
159
+ */
160
+ function invokesItsCallback(call) {
161
+ const callee = call.callee;
162
+ if (call.type === 'NewExpression') {
163
+ return callee.type === 'Identifier' && callee.name === 'Promise';
164
+ }
165
+ if (callee.type !== 'MemberExpression' || callee.computed) {
166
+ return false;
167
+ }
168
+ if (callee.property.type !== 'Identifier') {
169
+ return false;
170
+ }
171
+ if (callee.object.type === 'Identifier' &&
172
+ callee.object.name === 'Array' &&
173
+ callee.property.name === 'from') {
174
+ return true;
175
+ }
176
+ return IMMEDIATE_CALLBACK_METHODS.has(callee.property.name);
177
+ }
178
+ /**
179
+ * Returns true when the function is called right away where it appears, so its
180
+ * body runs at module load rather than later.
181
+ */
182
+ function isImmediatelyInvoked(fn) {
183
+ const parent = fn.parent;
184
+ if (!parent) {
185
+ return false;
186
+ }
187
+ if ((parent.type === 'CallExpression' || parent.type === 'NewExpression') &&
188
+ parent.callee === fn) {
189
+ return true;
190
+ }
191
+ return ((parent.type === 'CallExpression' || parent.type === 'NewExpression') &&
192
+ parent.arguments.includes(fn) &&
193
+ invokesItsCallback(parent));
194
+ }
195
+ /**
196
+ * Finds the innermost construct which delays the node until after module
197
+ * evaluation: a function which is not called on the spot, or an instance field
198
+ * initializer which waits for construction. Returns null when the node runs
199
+ * while the module is evaluated.
200
+ */
201
+ function findDeferringBoundary(node) {
202
+ let child = undefined;
203
+ let current = node;
204
+ while (current) {
205
+ switch (current.type) {
206
+ case 'FunctionDeclaration':
207
+ case 'FunctionExpression':
208
+ case 'ArrowFunctionExpression':
209
+ if (!isImmediatelyInvoked(current)) {
210
+ return current;
211
+ }
212
+ break;
213
+ case 'PropertyDefinition':
214
+ case 'AccessorProperty':
215
+ // An instance field initializer runs on construction; a static one runs
216
+ // when the class is defined, which is at module load.
217
+ if (!current.static && child === current.value) {
218
+ return 'field';
219
+ }
220
+ break;
221
+ case 'Program':
222
+ return null;
223
+ }
224
+ child = current;
225
+ current = current.parent;
226
+ }
227
+ return null;
228
+ }
229
+ /**
230
+ * Returns the variable holding a function, for a declaration such as
231
+ * `function run() {}` or `const run = () => {}`. Returns null for a function
232
+ * which is never bound to a name, such as a callback or an object property.
233
+ */
234
+ function getFunctionVariable(fn, sourceCode) {
235
+ if (fn.type === 'FunctionDeclaration' && fn.id) {
236
+ return sourceCode.getDeclaredVariables(fn)[0] ?? null;
237
+ }
238
+ const parent = fn.parent;
239
+ if (parent?.type === 'VariableDeclarator' &&
240
+ parent.init === fn &&
241
+ parent.id.type === 'Identifier') {
242
+ return sourceCode.getDeclaredVariables(parent)[0] ?? null;
243
+ }
244
+ return null;
245
+ }
246
+ const MAX_CALL_DEPTH = 6;
247
+ /**
248
+ * Returns true when the node runs while the module is evaluated, either
249
+ * directly or through a named function which is called at module level.
250
+ */
251
+ function isEagerlyReached(node, sourceCode, seen = new Set(), depth = 0) {
252
+ const boundary = findDeferringBoundary(node);
253
+ if (boundary === null) {
254
+ return true;
255
+ }
256
+ if (boundary === 'field' || depth >= MAX_CALL_DEPTH || seen.has(boundary)) {
257
+ return false;
258
+ }
259
+ seen.add(boundary);
260
+ const variable = getFunctionVariable(boundary, sourceCode);
261
+ if (!variable) {
262
+ return false;
263
+ }
264
+ return variable.references.some(reference => {
265
+ const identifier = reference.identifier;
266
+ const parent = identifier.parent;
267
+ if (!parent) {
268
+ return false;
269
+ }
270
+ // `run()` and `new Runner()` reach the body directly.
271
+ if ((parent.type === 'CallExpression' || parent.type === 'NewExpression') &&
272
+ parent.callee === identifier) {
273
+ return isEagerlyReached(identifier, sourceCode, seen, depth + 1);
274
+ }
275
+ // `run.call(...)` and `run.apply(...)` reach it as well.
276
+ if (parent.type === 'MemberExpression' &&
277
+ parent.object === identifier &&
278
+ !parent.computed &&
279
+ parent.property.type === 'Identifier' &&
280
+ (parent.property.name === 'call' || parent.property.name === 'apply') &&
281
+ parent.parent?.type === 'CallExpression' &&
282
+ parent.parent.callee === parent) {
283
+ return isEagerlyReached(parent.parent, sourceCode, seen, depth + 1);
284
+ }
285
+ // `list.map(run)` passes it to something which calls it straight away.
286
+ if ((parent.type === 'CallExpression' || parent.type === 'NewExpression') &&
287
+ parent.arguments.includes(identifier) &&
288
+ invokesItsCallback(parent)) {
289
+ return isEagerlyReached(identifier, sourceCode, seen, depth + 1);
290
+ }
291
+ // Passing the function anywhere else does not say when, or whether, it runs.
292
+ return false;
293
+ });
294
+ }
295
+ /**
296
+ * DOM events which only fire on a user action, so a listener for one of them
297
+ * cannot run while the application starts.
298
+ */
299
+ const INTERACTION_EVENTS = new Set([
300
+ 'auxclick',
301
+ 'click',
302
+ 'contextmenu',
303
+ 'dblclick',
304
+ 'mousedown',
305
+ 'mouseup',
306
+ 'pointerdown',
307
+ 'pointerup',
308
+ 'touchstart',
309
+ 'touchend',
310
+ 'keydown',
311
+ 'keypress',
312
+ 'keyup',
313
+ 'change',
314
+ 'input',
315
+ 'submit',
316
+ 'copy',
317
+ 'cut',
318
+ 'paste',
319
+ 'drop',
320
+ 'wheel'
321
+ ]);
322
+ /** The same events assigned as DOM `on*` properties. */
323
+ const INTERACTION_ON_PROPERTIES = new Set([...INTERACTION_EVENTS].map(event => `on${event}`));
324
+ /** The same events as JSX handler props. */
325
+ const JSX_INTERACTION_HANDLERS = new Set([
326
+ 'onAuxClick',
327
+ 'onClick',
328
+ 'onContextMenu',
329
+ 'onDoubleClick',
330
+ 'onMouseDown',
331
+ 'onMouseUp',
332
+ 'onPointerDown',
333
+ 'onPointerUp',
334
+ 'onTouchStart',
335
+ 'onTouchEnd',
336
+ 'onKeyDown',
337
+ 'onKeyPress',
338
+ 'onKeyUp',
339
+ 'onChange',
340
+ 'onInput',
341
+ 'onSubmit',
342
+ 'onCopy',
343
+ 'onCut',
344
+ 'onPaste',
345
+ 'onDrop',
346
+ 'onWheel'
347
+ ]);
348
+ /**
349
+ * Returns true when a function's own position marks it as a user-interaction
350
+ * handler: a command `execute` implementation, a listener for an interaction
351
+ * event, or a JSX interaction handler prop. Each position requires the
352
+ * function to be the direct value, so a call producing a handler never counts.
353
+ */
354
+ function isInteractionHandler(fn) {
355
+ const parent = fn.parent;
356
+ if (!parent) {
357
+ return false;
358
+ }
359
+ // `execute: () => {}` and `execute() {}` in command options.
360
+ if (parent.type === 'Property' &&
361
+ !parent.computed &&
362
+ parent.value === fn &&
363
+ ((parent.key.type === 'Identifier' && parent.key.name === 'execute') ||
364
+ (parent.key.type === 'Literal' && parent.key.value === 'execute'))) {
365
+ return true;
366
+ }
367
+ // `node.addEventListener('click', () => {})`
368
+ if (parent.type === 'CallExpression' &&
369
+ parent.callee.type === 'MemberExpression' &&
370
+ !parent.callee.computed &&
371
+ parent.callee.property.type === 'Identifier' &&
372
+ parent.callee.property.name === 'addEventListener' &&
373
+ parent.arguments[1] === fn &&
374
+ parent.arguments[0]?.type === 'Literal' &&
375
+ typeof parent.arguments[0].value === 'string' &&
376
+ INTERACTION_EVENTS.has(parent.arguments[0].value)) {
377
+ return true;
378
+ }
379
+ // `element.onclick = () => {}`
380
+ if (parent.type === 'AssignmentExpression' &&
381
+ parent.operator === '=' &&
382
+ parent.right === fn &&
383
+ parent.left.type === 'MemberExpression' &&
384
+ !parent.left.computed &&
385
+ parent.left.property.type === 'Identifier' &&
386
+ INTERACTION_ON_PROPERTIES.has(parent.left.property.name)) {
387
+ return true;
388
+ }
389
+ // `<button onClick={() => {}} />`
390
+ if (parent.type === 'JSXExpressionContainer' &&
391
+ parent.parent?.type === 'JSXAttribute' &&
392
+ parent.parent.name.type === 'JSXIdentifier' &&
393
+ JSX_INTERACTION_HANDLERS.has(parent.parent.name.name)) {
394
+ return true;
395
+ }
396
+ return false;
397
+ }
398
+ /**
399
+ * Returns true when the node sits inside a user-interaction handler, so it
400
+ * cannot run until the user acts, however the module itself is loaded. The
401
+ * closure only exists once the enclosing handler runs, so anything nested
402
+ * deeper inside it waits for the user as well.
403
+ */
404
+ function isInInteractionCallback(node) {
405
+ let current = node;
406
+ while (current && current.type !== 'Program') {
407
+ if ((current.type === 'FunctionDeclaration' ||
408
+ current.type === 'FunctionExpression' ||
409
+ current.type === 'ArrowFunctionExpression') &&
410
+ isInteractionHandler(current)) {
411
+ return true;
412
+ }
413
+ current = current.parent;
414
+ }
415
+ return false;
416
+ }
417
+ const PLUGIN_LIST_PROPERTIES = new Set(['requires', 'optional', 'provides']);
418
+ /**
419
+ * Returns true when an object literal carrying `requires`, `optional` or
420
+ * `provides` is a plugin rather than an unrelated options bag which happens to
421
+ * use one of those names.
422
+ */
423
+ function looksLikePluginList(node) {
424
+ const properties = (0, plugin_utils_1.getObjectProperties)(node);
425
+ if ((0, plugin_utils_1.isCallableProperty)(properties.get('activate'))) {
426
+ return true;
427
+ }
428
+ const id = properties.get('id');
429
+ return (!!id && id.value.type === 'Literal' && typeof id.value.value === 'string');
430
+ }
431
+ /**
432
+ * Returns true when the node sits in a plugin's `requires`, `optional` or
433
+ * `provides` entry, where a token has to be referenced at module load.
434
+ */
435
+ function isInPluginTokenList(node) {
436
+ let child = undefined;
437
+ let current = node;
438
+ while (current) {
439
+ if (current.type === 'Property' &&
440
+ !current.computed &&
441
+ child === current.value) {
442
+ const key = current.key;
443
+ const name = key.type === 'Identifier'
444
+ ? key.name
445
+ : key.type === 'Literal' && typeof key.value === 'string'
446
+ ? key.value
447
+ : null;
448
+ if (name &&
449
+ PLUGIN_LIST_PROPERTIES.has(name) &&
450
+ current.parent?.type === 'ObjectExpression' &&
451
+ looksLikePluginList(current.parent)) {
452
+ return true;
453
+ }
454
+ }
455
+ if (current.type === 'Program') {
456
+ return false;
457
+ }
458
+ child = current;
459
+ current = current.parent;
460
+ }
461
+ return false;
462
+ }
463
+ /**
464
+ * Builds the deferred import snippet suggested in the report message, merging
465
+ * every declaration which imports the same source.
466
+ */
467
+ function buildDeferredImportSnippet(declarations) {
468
+ const source = declarations[0].source.value;
469
+ const named = [];
470
+ let defaultName = null;
471
+ let namespaceName = null;
472
+ // A name which is not a plain identifier cannot be destructured as written.
473
+ let unquotable = false;
474
+ for (const declaration of declarations) {
475
+ for (const specifier of declaration.specifiers) {
476
+ if (specifier.type === 'ImportSpecifier') {
477
+ if (specifier.importKind === 'type') {
478
+ continue;
479
+ }
480
+ if (specifier.imported.type !== 'Identifier') {
481
+ unquotable = true;
482
+ continue;
483
+ }
484
+ const imported = specifier.imported.name;
485
+ const entry = imported === specifier.local.name
486
+ ? imported
487
+ : `${imported}: ${specifier.local.name}`;
488
+ if (!named.includes(entry)) {
489
+ named.push(entry);
490
+ }
491
+ }
492
+ else if (specifier.type === 'ImportDefaultSpecifier') {
493
+ defaultName = specifier.local.name;
494
+ }
495
+ else if (specifier.type === 'ImportNamespaceSpecifier') {
496
+ namespaceName = specifier.local.name;
497
+ }
498
+ }
499
+ }
500
+ // A namespace next to other bindings, or a name needing quotes, has no
501
+ // single-line form, so suggest the import itself rather than broken code.
502
+ if (unquotable || (namespaceName && (defaultName || named.length > 0))) {
503
+ return `await import('${source}')`;
504
+ }
505
+ if (namespaceName) {
506
+ return `const ${namespaceName} = await import('${source}');`;
507
+ }
508
+ if (defaultName) {
509
+ named.unshift(`default: ${defaultName}`);
510
+ }
511
+ if (named.length === 0) {
512
+ return `await import('${source}');`;
513
+ }
514
+ return `const { ${named.join(', ')} } = await import('${source}');`;
515
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Resolves a relative import specifier to a file, trying the usual extensions
3
+ * and an `index` file inside a directory. A specifier written for ESM output,
4
+ * such as `./widget.js`, also resolves to the source it was compiled from.
5
+ * Returns null for a bare package specifier, or when nothing matches.
6
+ */
7
+ export declare function resolveRelativeModule(specifier: string, fromFile: string): string | null;
8
+ /**
9
+ * Sums the code size of a module and of every relative module it statically
10
+ * imports. Returns null when the file cannot be read.
11
+ */
12
+ export declare function getTransitiveCodeSize(entry: string): number | null;