@jupyter/eslint-plugin 1.0.0 → 1.1.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 (35) hide show
  1. package/lib/index.d.ts +68 -0
  2. package/lib/index.js +42 -11
  3. package/lib/rules/galata-prefer-filebrowser-helper.d.ts +5 -0
  4. package/lib/rules/galata-prefer-filebrowser-helper.js +105 -0
  5. package/lib/rules/incorrect-translator-usage.d.ts +4 -0
  6. package/lib/rules/incorrect-translator-usage.js +208 -0
  7. package/lib/rules/no-dynamic-translation.d.ts +4 -0
  8. package/lib/rules/no-dynamic-translation.js +92 -0
  9. package/lib/rules/no-pageconfig-base-url.d.ts +4 -0
  10. package/lib/rules/no-pageconfig-base-url.js +37 -0
  11. package/lib/rules/no-translation-concatenation.js +46 -84
  12. package/lib/rules/no-untranslated-string.js +7 -4
  13. package/lib/rules/plugin-activation-args.js +6 -2
  14. package/lib/rules/prefer-signal-this-arg.d.ts +7 -0
  15. package/lib/rules/prefer-signal-this-arg.js +196 -0
  16. package/lib/rules/require-disposable-ownership.d.ts +5 -0
  17. package/lib/rules/require-disposable-ownership.js +120 -0
  18. package/lib/rules/require-disposable-transfer.d.ts +5 -0
  19. package/lib/rules/require-disposable-transfer.js +223 -0
  20. package/lib/rules/require-signal-cleanup.d.ts +8 -0
  21. package/lib/rules/require-signal-cleanup.js +164 -0
  22. package/lib/rules/require-signal-this-arg.d.ts +5 -0
  23. package/lib/rules/require-signal-this-arg.js +74 -0
  24. package/lib/rules/token-format.js +1 -2
  25. package/lib/utils/disposables.d.ts +64 -0
  26. package/lib/utils/disposables.js +1723 -0
  27. package/lib/utils/playwright-selectors.d.ts +66 -0
  28. package/lib/utils/playwright-selectors.js +193 -0
  29. package/lib/utils/signal-lifetime.d.ts +158 -0
  30. package/lib/utils/signal-lifetime.js +755 -0
  31. package/lib/utils/signals.d.ts +143 -0
  32. package/lib/utils/signals.js +601 -0
  33. package/lib/utils/translation.d.ts +45 -0
  34. package/lib/utils/translation.js +122 -0
  35. package/package.json +11 -4
@@ -0,0 +1,66 @@
1
+ import { TSESTree } from '@typescript-eslint/utils';
2
+ /**
3
+ * Playwright locator-producing methods.
4
+ */
5
+ export declare const LOCATOR_METHODS: ReadonlySet<string>;
6
+ /**
7
+ * Playwright interaction methods. Called directly on `page` they take a
8
+ * selector as first argument (`page.click(sel)`); called on a locator they
9
+ * act on the already-selected element (`page.locator(sel).click()`).
10
+ */
11
+ export declare const INTERACTION_METHODS: ReadonlySet<string>;
12
+ export interface SelectorPart {
13
+ /**
14
+ * The method that received the argument: a locator method for chains, or
15
+ * the interaction method itself for direct calls (`page.click(sel)`).
16
+ */
17
+ method: string;
18
+ /** The selector or text argument. */
19
+ argNode: TSESTree.Expression;
20
+ }
21
+ export interface SelectorInteractionMatch {
22
+ /** The outer CallExpression performing the interaction (report anchor). */
23
+ callNode: TSESTree.CallExpression;
24
+ /**
25
+ * The selector arguments, root-to-tip: one for a direct call, one per
26
+ * locator call in a chain (`page.locator(a).getByText(b).click()` → [a, b]).
27
+ */
28
+ selectorParts: SelectorPart[];
29
+ /** true for `page.locator(sel).click()`, false for `page.click(sel)`. */
30
+ viaLocatorChain: boolean;
31
+ /** Name of the interaction method, e.g. 'click', 'dblclick', 'fill'. */
32
+ interactionMethod: string;
33
+ /** true when the call passes `{ button: 'right' }` (context menu open). */
34
+ isRightClick: boolean;
35
+ }
36
+ /**
37
+ * True when an interaction call passes `{ button: 'right' }` option.
38
+ */
39
+ export declare function isRightClick(node: TSESTree.CallExpression): boolean;
40
+ /**
41
+ * Matches raw Playwright selector interactions on the Galata `page` fixture:
42
+ *
43
+ * - `page.<interaction>(selector, ...)` e.g. `page.dblclick('text=a.ipynb')`
44
+ * - `page.<locatorMethod>(selector)[...].<interaction>(...)` e.g.
45
+ * `page.locator('.jp-DirListing-item').click()` or chained locators like
46
+ * `page.locator('#filebrowser').getByText('notebooks').dblclick()`
47
+ *
48
+ * Returns null for any other shape
49
+ */
50
+ export declare function matchSelectorInteraction(node: TSESTree.CallExpression): SelectorInteractionMatch | null;
51
+ /**
52
+ * Extracts a best-effort static string from a selector argument so it can be
53
+ * matched against known patterns. String literals return their value;
54
+ * template literals return their static parts joined by a space, so
55
+ * `` `.jp-DirListing-item span:has-text("${name}")` `` still exposes its
56
+ * static prefix. Fully dynamic expressions return null.
57
+ */
58
+ export declare function extractStaticSelectorText(node: TSESTree.Expression): string | null;
59
+ /**
60
+ * Joins the statically extractable selector parts of a match into a single
61
+ * pattern-matchable string. Arguments of text-matching locators (`getByText`,
62
+ * `getByTitle`, …) are normalized to the `text=` selector form, so patterns
63
+ * written against `text=` selectors also match the locator-method shape.
64
+ * Returns null when no part is static.
65
+ */
66
+ export declare function combineStaticSelectorText(match: SelectorInteractionMatch): string | null;
@@ -0,0 +1,193 @@
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.INTERACTION_METHODS = exports.LOCATOR_METHODS = void 0;
8
+ exports.isRightClick = isRightClick;
9
+ exports.matchSelectorInteraction = matchSelectorInteraction;
10
+ exports.extractStaticSelectorText = extractStaticSelectorText;
11
+ exports.combineStaticSelectorText = combineStaticSelectorText;
12
+ /**
13
+ * Playwright locator-producing methods.
14
+ */
15
+ exports.LOCATOR_METHODS = new Set([
16
+ 'locator',
17
+ 'getByText',
18
+ 'getByTitle',
19
+ 'getByLabel',
20
+ 'getByTestId',
21
+ 'getByPlaceholder',
22
+ 'getByAltText'
23
+ ]);
24
+ /**
25
+ * Playwright interaction methods. Called directly on `page` they take a
26
+ * selector as first argument (`page.click(sel)`); called on a locator they
27
+ * act on the already-selected element (`page.locator(sel).click()`).
28
+ */
29
+ exports.INTERACTION_METHODS = new Set([
30
+ 'click',
31
+ 'dblclick',
32
+ 'hover',
33
+ 'tap',
34
+ 'fill',
35
+ 'check',
36
+ 'uncheck',
37
+ 'selectOption',
38
+ 'focus',
39
+ 'waitForSelector',
40
+ 'press'
41
+ ]);
42
+ /**
43
+ * Locator methods that pass the locator through without adding a selector,
44
+ * e.g. `page.locator(sel).first().click()`.
45
+ */
46
+ const CHAIN_PASSTHROUGH_METHODS = new Set([
47
+ 'first',
48
+ 'last',
49
+ 'nth'
50
+ ]);
51
+ /**
52
+ * Locator methods whose argument is matched against element text rather
53
+ * than being a CSS selector.
54
+ */
55
+ const TEXT_MATCH_METHODS = new Set([
56
+ 'getByText',
57
+ 'getByTitle',
58
+ 'getByLabel',
59
+ 'getByPlaceholder',
60
+ 'getByAltText'
61
+ ]);
62
+ function isPageIdentifier(node) {
63
+ return node.type === 'Identifier' && node.name === 'page';
64
+ }
65
+ function firstArgument(node) {
66
+ const arg = node.arguments[0];
67
+ return arg && arg.type !== 'SpreadElement' ? arg : null;
68
+ }
69
+ /**
70
+ * True when an interaction call passes `{ button: 'right' }` option.
71
+ */
72
+ function isRightClick(node) {
73
+ return node.arguments.some(arg => arg.type === 'ObjectExpression' &&
74
+ arg.properties.some(prop => prop.type === 'Property' &&
75
+ !prop.computed &&
76
+ ((prop.key.type === 'Identifier' && prop.key.name === 'button') ||
77
+ (prop.key.type === 'Literal' && prop.key.value === 'button')) &&
78
+ prop.value.type === 'Literal' &&
79
+ prop.value.value === 'right'));
80
+ }
81
+ /**
82
+ * Walks a locator-producing chain rooted at `page`, e.g.
83
+ * `page.locator(a).getByText(b).first()`, and returns the selector arguments
84
+ * in root-to-tip order. Returns null when the chain is not rooted at `page`,
85
+ * contains a non-locator call, or carries no selector argument at all.
86
+ */
87
+ function collectLocatorChainSelectors(node) {
88
+ const selectors = [];
89
+ let current = node;
90
+ for (;;) {
91
+ if (current.type !== 'CallExpression') {
92
+ return null;
93
+ }
94
+ const callee = current.callee;
95
+ if (callee.type !== 'MemberExpression' ||
96
+ callee.computed ||
97
+ callee.property.type !== 'Identifier') {
98
+ return null;
99
+ }
100
+ if (exports.LOCATOR_METHODS.has(callee.property.name)) {
101
+ const arg = firstArgument(current);
102
+ if (arg) {
103
+ selectors.unshift({ method: callee.property.name, argNode: arg });
104
+ }
105
+ }
106
+ else if (!CHAIN_PASSTHROUGH_METHODS.has(callee.property.name)) {
107
+ return null;
108
+ }
109
+ if (isPageIdentifier(callee.object)) {
110
+ return selectors.length > 0 ? selectors : null;
111
+ }
112
+ current = callee.object;
113
+ }
114
+ }
115
+ /**
116
+ * Matches raw Playwright selector interactions on the Galata `page` fixture:
117
+ *
118
+ * - `page.<interaction>(selector, ...)` e.g. `page.dblclick('text=a.ipynb')`
119
+ * - `page.<locatorMethod>(selector)[...].<interaction>(...)` e.g.
120
+ * `page.locator('.jp-DirListing-item').click()` or chained locators like
121
+ * `page.locator('#filebrowser').getByText('notebooks').dblclick()`
122
+ *
123
+ * Returns null for any other shape
124
+ */
125
+ function matchSelectorInteraction(node) {
126
+ const { callee } = node;
127
+ if (callee.type !== 'MemberExpression' || callee.computed) {
128
+ return null;
129
+ }
130
+ const property = callee.property;
131
+ if (property.type !== 'Identifier' ||
132
+ !exports.INTERACTION_METHODS.has(property.name)) {
133
+ return null;
134
+ }
135
+ // page.click(selector, ...)
136
+ if (isPageIdentifier(callee.object)) {
137
+ const selectorArgNode = firstArgument(node);
138
+ return selectorArgNode
139
+ ? {
140
+ callNode: node,
141
+ selectorParts: [{ method: property.name, argNode: selectorArgNode }],
142
+ viaLocatorChain: false,
143
+ interactionMethod: property.name,
144
+ isRightClick: isRightClick(node)
145
+ }
146
+ : null;
147
+ }
148
+ // page.locator(selector).getByText(...).click(...)
149
+ const selectorParts = collectLocatorChainSelectors(callee.object);
150
+ return selectorParts
151
+ ? {
152
+ callNode: node,
153
+ selectorParts,
154
+ viaLocatorChain: true,
155
+ interactionMethod: property.name,
156
+ isRightClick: isRightClick(node)
157
+ }
158
+ : null;
159
+ }
160
+ /**
161
+ * Extracts a best-effort static string from a selector argument so it can be
162
+ * matched against known patterns. String literals return their value;
163
+ * template literals return their static parts joined by a space, so
164
+ * `` `.jp-DirListing-item span:has-text("${name}")` `` still exposes its
165
+ * static prefix. Fully dynamic expressions return null.
166
+ */
167
+ function extractStaticSelectorText(node) {
168
+ if (node.type === 'Literal') {
169
+ return typeof node.value === 'string' ? node.value : null;
170
+ }
171
+ if (node.type === 'TemplateLiteral') {
172
+ return node.quasis.map(quasi => quasi.value.cooked ?? '').join(' ');
173
+ }
174
+ return null;
175
+ }
176
+ /**
177
+ * Joins the statically extractable selector parts of a match into a single
178
+ * pattern-matchable string. Arguments of text-matching locators (`getByText`,
179
+ * `getByTitle`, …) are normalized to the `text=` selector form, so patterns
180
+ * written against `text=` selectors also match the locator-method shape.
181
+ * Returns null when no part is static.
182
+ */
183
+ function combineStaticSelectorText(match) {
184
+ const parts = [];
185
+ for (const { method, argNode } of match.selectorParts) {
186
+ const text = extractStaticSelectorText(argNode);
187
+ if (text === null) {
188
+ continue;
189
+ }
190
+ parts.push(TEXT_MATCH_METHODS.has(method) ? `text=${text}` : text);
191
+ }
192
+ return parts.length > 0 ? parts.join(' ') : null;
193
+ }
@@ -0,0 +1,158 @@
1
+ import { TSESTree } from '@typescript-eslint/types';
2
+ import { ParserServices, TSESLint } from '@typescript-eslint/utils';
3
+ import * as ts from 'typescript';
4
+ import { ClassLike } from './signals';
5
+ /**
6
+ * A Lumino connection leaks if and only if the **sender outlives the
7
+ * receiver**. Connections are stored in `WeakMap`s keyed by both sender and
8
+ * receiver, so a sender+receiver island that becomes unreachable together is
9
+ * collected whether or not a `thisArg` was passed.
10
+ *
11
+ * The helpers in this module therefore classify the *sender* rather than
12
+ * looking for absent cleanup on the receiver. Everything defaults to
13
+ * `'unknown'` — the rules only report senders that are positively proven to
14
+ * outlive their receiver.
15
+ */
16
+ export type SenderLifetime =
17
+ /** The sender is the enclosing instance itself (or something it intrinsically owns). */
18
+ 'self'
19
+ /** The enclosing class constructs, adopts, or disposes the sender. */
20
+ | 'owned'
21
+ /** A model/context in an MVC pair whose view is the enclosing class. */
22
+ | 'long-lived-model'
23
+ /** An injected application service from the configured allowlist. */
24
+ | 'long-lived-service'
25
+ /** Not provably anything — never reported. */
26
+ | 'unknown';
27
+ /**
28
+ * Application-lifetime service types. A connection to a signal owned by one of
29
+ * these outlives any per-document or per-widget receiver.
30
+ *
31
+ * Deliberately short and curated. Notably absent: `DocumentRegistry.Context`
32
+ * and `JupyterFrontEnd` — both are routinely *shorter*-lived than the objects
33
+ * that hold them, and including them re-introduces false positives.
34
+ */
35
+ export declare const DEFAULT_LONG_LIVED_TYPES: readonly string[];
36
+ export interface SenderChain {
37
+ /** The expression owning the signal — `a.b` in `a.b.changed.connect(...)`. */
38
+ sender: TSESTree.Expression;
39
+ /** Sub-expressions from the root outward, ending with `sender`. */
40
+ prefixes: TSESTree.Expression[];
41
+ /** Base of the chain, or null when it is not a plain object path. */
42
+ root: TSESTree.ThisExpression | TSESTree.Identifier | null;
43
+ /** Property names from the root to the sender; null for computed access. */
44
+ path: (string | null)[];
45
+ /** True when a call appears in the chain — not a stable object path. */
46
+ hasCall: boolean;
47
+ /** The signal's own property name (`changed`), when statically known. */
48
+ signalName: string | null;
49
+ }
50
+ /**
51
+ * Splits the receiver of a `.connect()` call into the signal name and the
52
+ * object path that owns it. Returns null when the receiver is not a
53
+ * `<object>.<signal>` member expression (a bare `signal.connect(cb)` on a
54
+ * local has no identifiable sender).
55
+ */
56
+ export declare function buildSenderChain(signalExpr: TSESTree.Expression): SenderChain | null;
57
+ /**
58
+ * Per-class facts about member fields, gathered in one pass over the class
59
+ * body. Nested classes are opaque.
60
+ */
61
+ /**
62
+ * One expression the class tears down sender-side. The node is kept alongside
63
+ * its text because names are not unique across scopes: `@jupyterlab/outputarea`
64
+ * has an `output` that is an `IOutputModel` in one loop and an adopted `Widget`
65
+ * in another method, and matching on text alone conflates them.
66
+ */
67
+ export interface TeardownRecord {
68
+ text: string;
69
+ node: TSESTree.Node;
70
+ }
71
+ export interface ClassOwnershipFacts {
72
+ /** Field names (without `#`) the class constructs, adopts, or disposes. */
73
+ ownedFields: Set<string>;
74
+ /**
75
+ * Expressions the class tears down sender-side: `x.dispose()`,
76
+ * `Signal.clearData(x)`, `Signal.disconnectSender(x)`, `parent.addWidget(x)`.
77
+ */
78
+ torndownSenders: TeardownRecord[];
79
+ /** Getter name → the field it forwards to, for `get editor() { return this._editor; }`. */
80
+ getterAliases: Map<string, string>;
81
+ }
82
+ /**
83
+ * Collects, for one class body, which fields it owns and which senders it
84
+ * tears down. Both are *suppression* evidence: any hit means a connection to
85
+ * that sender cannot outlive the receiver, so nothing is reported.
86
+ */
87
+ export declare function collectClassOwnershipFacts(classNode: ClassLike, sourceCode: Readonly<TSESLint.SourceCode>, signalLocalNames: ReadonlySet<string>): ClassOwnershipFacts;
88
+ /**
89
+ * Does this class have somewhere to put a disconnect at all — a `dispose()`
90
+ * method, an `isDisposed` member, or an `implements ...Disposable` clause?
91
+ *
92
+ * A class with no teardown protocol whatsoever is almost always a plugin-scope
93
+ * singleton (`MermaidManager`, `ThemeManager`, `LayoutRestorer`): it is created
94
+ * once in an `activate()` and lives as long as the services it connects to, so
95
+ * the connection never leaks and there is no `dispose()` in which to write the
96
+ * fix. It is indistinguishable, from inside the file, from a genuinely
97
+ * short-lived class that forgot to implement disposal — so both stay silent.
98
+ */
99
+ export declare function classHasDisposalProtocol(classNode: ClassLike): boolean;
100
+ export interface LifetimeContext {
101
+ classNode: ClassLike;
102
+ facts: ClassOwnershipFacts;
103
+ sourceCode: Readonly<TSESLint.SourceCode>;
104
+ scope: TSESLint.Scope.Scope;
105
+ checker: ts.TypeChecker | null;
106
+ services: ParserServices | null;
107
+ longLivedTypes: ReadonlySet<string>;
108
+ }
109
+ export interface SenderAnalysis {
110
+ lifetime: SenderLifetime;
111
+ /** Source text of the sender, for the diagnostic message. */
112
+ senderText: string;
113
+ /** Allowlisted service type name, when `lifetime` is `long-lived-service`. */
114
+ typeName: string | null;
115
+ }
116
+ /**
117
+ * Classifies the sender of a `.connect()` call. Everything that cannot be
118
+ * proven long-lived comes back as `'unknown'`, `'self'`, or `'owned'` — all of
119
+ * which the rules treat as silence.
120
+ */
121
+ export declare function analyzeSender(signalExpr: TSESTree.Expression, context: LifetimeContext): SenderAnalysis;
122
+ export type CallbackShape = 'bound' | 'inline' | 'referenced' | 'opaque';
123
+ /**
124
+ * How a connected callback can be removed later.
125
+ *
126
+ * - `bound`: `fn.bind(this)` allocates a fresh function, so no
127
+ * `disconnect(callback, ...)` can ever match it by identity.
128
+ * - `inline`: an arrow or function expression — same problem, unless the
129
+ * connection carries a `thisArg` that receiver-side cleanup can match.
130
+ * - `referenced`: a stable identifier or member expression, removable by a
131
+ * matching `disconnect()`.
132
+ */
133
+ export declare function classifyCallbackShape(callback: TSESTree.CallExpressionArgument): CallbackShape;
134
+ /**
135
+ * Measure C: is there a `.disconnect()` anywhere in the file that removes this
136
+ * callback?
137
+ *
138
+ * Searches the whole `Program` — including nested arrow functions, returned
139
+ * `DisposableDelegate` bodies and helper closures — and matches on the
140
+ * normalized text of the callback expression rather than on the sender chain.
141
+ * `@jupyterlab/lsp`'s `registerProvider` connects
142
+ * `registration.provider.sessionsChanged` and disconnects
143
+ * `provider.sessionsChanged` with the same `registration.onSessionsChanged`
144
+ * callback; comparing senders misses it, comparing callbacks does not.
145
+ *
146
+ * `arity` is the argument count the disconnect must have to match the connect:
147
+ * Lumino matches on the exact `(signal, slot, thisArg)` triple, so a
148
+ * one-argument `connect(cb)` is only undone by a one-argument
149
+ * `disconnect(cb)`.
150
+ */
151
+ export declare function hasMatchingDisconnect(program: TSESTree.Program, callback: TSESTree.CallExpressionArgument, sourceCode: Readonly<TSESLint.SourceCode>, arity: 1 | 2): boolean;
152
+ /**
153
+ * Measure E: `disposed`-style wiring is cleaned up sender-side — the signal
154
+ * fires exactly as its sender is torn down, and Lumino's own
155
+ * `Widget.dispose()` clears the connection immediately afterwards. This is the
156
+ * pattern the docs recommend, so neither rule may flag it.
157
+ */
158
+ export declare function isSelfTerminatingSignal(chain: SenderChain | null): boolean;