@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,332 @@
1
+ "use strict";
2
+ /*
3
+ * Copyright (c) Jupyter Development Team.
4
+ * Distributed under the terms of the Modified BSD License.
5
+ */
6
+ const create_rule_1 = require("../utils/create-rule");
7
+ const playwright_selectors_1 = require("../utils/playwright-selectors");
8
+ // Keyed by the start of the caption the widget puts in `title.caption`, which
9
+ // is what Lumino renders into the `title` attribute of the tab. Five of the six
10
+ // captions are exactly the key; the file browser appends its keyboard shortcut,
11
+ // so its caption reads `File Browser (Ctrl+Shift+F)`.
12
+ const SIDEBAR_TITLE_TO_TAB = new Map([
13
+ ['Debugger', { id: 'jp-debugger-sidebar', side: 'right' }],
14
+ ['Extension Manager', { id: 'extensionmanager.main-view', side: 'left' }],
15
+ ['File Browser', { id: 'filebrowser', side: 'left' }],
16
+ ['Property Inspector', { id: 'jp-property-inspector', side: 'right' }],
17
+ [
18
+ 'Running Terminals and Kernels',
19
+ { id: 'jp-running-sessions', side: 'left' }
20
+ ],
21
+ ['Table of Contents', { id: 'table-of-contents', side: 'left' }]
22
+ ]);
23
+ // Options that change only how long Playwright waits, never what the gesture
24
+ // does, so the helper still reproduces it. Every other key changes it:
25
+ // `button` opens a context menu, `clickCount` opens and then closes the tab,
26
+ // `modifiers` makes a different gesture, `force` skips the actionability
27
+ // checks `openTab` relies on, and `position` aims at a point inside the tab.
28
+ const NEUTRAL_OPTION_KEYS = new Set([
29
+ 'timeout',
30
+ 'noWaitAfter',
31
+ 'delay'
32
+ ]);
33
+ /**
34
+ * True when the click carries an option the sidebar and activity helpers
35
+ * cannot reproduce, so that only the plain gesture is ever reported. A
36
+ * computed key or a spread could carry any of them, so both count as
37
+ * unsupported.
38
+ */
39
+ function hasUnsupportedOptions(node) {
40
+ for (const arg of node.arguments) {
41
+ if (arg.type !== 'ObjectExpression') {
42
+ continue;
43
+ }
44
+ for (const prop of arg.properties) {
45
+ if (prop.type === 'SpreadElement' || prop.computed) {
46
+ return true;
47
+ }
48
+ const key = prop.key.type === 'Identifier'
49
+ ? prop.key.name
50
+ : prop.key.type === 'Literal'
51
+ ? prop.key.value
52
+ : null;
53
+ if (typeof key !== 'string' || !NEUTRAL_OPTION_KEYS.has(key)) {
54
+ return true;
55
+ }
56
+ }
57
+ }
58
+ return false;
59
+ }
60
+ // Galata's own `buildTabSelector` picks a sidebar tab by `data-id`, so a test
61
+ // written against it names the id rather than the caption.
62
+ const SIDEBAR_ID_TO_TAB = new Map([...SIDEBAR_TITLE_TO_TAB].map(([title, tab]) => [tab.id, { title, ...tab }]));
63
+ const DATA_ID_ATTRIBUTE_PATTERN = /\[\s*data-id\s*=\s*(?:"([^"]+)"|'([^']+)')\s*\]/g;
64
+ // The operator is captured so that `[title^="File Browser"]`, which is how the
65
+ // file browser tab has to be selected once its caption carries the shortcut, is
66
+ // read as well as the exact form.
67
+ const TITLE_ATTRIBUTE_PATTERN = /\[\s*title\s*([~^$*|]?=)\s*(?:"([^"]+)"|'([^']+)')\s*\]/g;
68
+ const MAIN_AREA_PATTERN = /(?:^|[\s>])(?:div)?\s*\[\s*role\s*=\s*(?:"main"|'main'|main)\s*\]/;
69
+ // The main area and the down area are Lumino tab bars too, so a widget moved
70
+ // out of the sidebar carries the same title attribute on its new tab. A
71
+ // selector that names one of those areas is not selecting a sidebar tab, and it
72
+ // can name one either by the stack node id or by the class the owning panel adds
73
+ // to its own tab bar: `DockPanel` adds `lm-DockPanel-tabBar` and `TabPanel`,
74
+ // which the down area is, adds `lm-TabPanel-tabBar`. The side bars are bare
75
+ // `TabBar` widgets and carry neither.
76
+ const DOCK_AREA_PATTERN = /#jp-main-dock-panel|#jp-down-stack|\.lm-DockPanel-tabBar|\.lm-TabPanel-tabBar/;
77
+ const TEXT_SELECTOR_PATTERN = /(?:^|>>)\s*text\s*=\s*(?:"([^"]+)"|'([^']+)'|(.+?))\s*(?:$|>>)/;
78
+ const TEXT_IS_PATTERN = /:text-is\(\s*(?:"([^"]+)"|'([^']+)')\s*\)/;
79
+ // A Lumino tab bar class only ever sits on a tab bar, so it proves the target
80
+ // is a tab wherever it is written. `role="tab"` is the generic ARIA role, which
81
+ // the settings editor plugin list carries on every `.jp-PluginList-entry`, so it
82
+ // proves one only once the main area is named as well.
83
+ const LUMINO_TAB_CLASS_PATTERN = /\.lm-TabBar-tab(?:\b|[.:[\s>])|\.lm-TabBar-tabLabel(?:\b|[.:[\s>])/;
84
+ const TAB_ROLE_PATTERN = /\[\s*role\s*=\s*(?:"tab"|'tab'|tab)\s*\]/;
85
+ const FILE_LIKE_ACTIVITY_NAME_PATTERN = /\.[A-Za-z0-9][\w-]*(?:\s*\*)?$/;
86
+ // The sidebar and the down area are Lumino tab bars too, so a tab token alone
87
+ // only proves a main area tab once these are ruled out. `page.activity` reaches
88
+ // only what sits under `[role="main"]`, which neither of them does, and the down
89
+ // area is named by its stack node id or by its `TabPanel` tab bar class.
90
+ const SIDE_TABBAR_PATTERN = /\.jp-SideBar|#jp-left-stack|#jp-right-stack|#jp-down-stack|\.lm-TabPanel-tabBar/;
91
+ // The attribute each `getByX` locator matches on. Playwright compares them by
92
+ // substring, so `*=` is the operator that says the same thing.
93
+ const LOCATOR_METHOD_ATTRIBUTE = new Map([
94
+ ['getByTitle', 'title'],
95
+ ['getByLabel', 'aria-label'],
96
+ ['getByPlaceholder', 'placeholder'],
97
+ ['getByAltText', 'alt'],
98
+ ['getByTestId', 'data-testid']
99
+ ]);
100
+ /**
101
+ * One link of a locator chain, written as the selector that picks the same
102
+ * element, or null when its argument is not static.
103
+ *
104
+ * A `getByRole` link keeps only its role: the accessible name is not an
105
+ * attribute, and folding it into `text=` would let a bare
106
+ * `getByRole('tab', { name })` look like a main area tab when the same call
107
+ * selects a sidebar tab just as well.
108
+ */
109
+ function foldSelectorPart(part) {
110
+ const text = (0, playwright_selectors_1.extractStaticSelectorText)(part.argNode, {
111
+ allowPartialTemplate: false
112
+ });
113
+ if (text === null) {
114
+ return null;
115
+ }
116
+ if (part.method === 'getByRole') {
117
+ return `[role="${text}"]`;
118
+ }
119
+ if (part.method === 'getByText') {
120
+ return `text=${text}`;
121
+ }
122
+ const attribute = LOCATOR_METHOD_ATTRIBUTE.get(part.method);
123
+ // Anything left is `locator(selector)` or the selector `page.click` takes,
124
+ // both of which are already Playwright selectors.
125
+ return attribute ? `[${attribute}*="${text.trim()}"]` : text;
126
+ }
127
+ /**
128
+ * The accessible name a `getByRole('tab', { name })` tip matches on.
129
+ *
130
+ * Lumino renders a tab as `<li role="tab" title="{caption}">`, and a sidebar
131
+ * widget sets `title.caption` but no `title.label`, so the accessible name
132
+ * falls back to that same caption.
133
+ */
134
+ function tabRoleNameOf(part) {
135
+ if (part.method !== 'getByRole' || !part.nameArgNode) {
136
+ return null;
137
+ }
138
+ const role = (0, playwright_selectors_1.extractStaticSelectorText)(part.argNode, {
139
+ allowPartialTemplate: false
140
+ });
141
+ if (role !== 'tab') {
142
+ return null;
143
+ }
144
+ // `getByRole(..., { name })` matches a substring of normalized whitespace,
145
+ // so a caller may pad the name.
146
+ const name = (0, playwright_selectors_1.extractStaticSelectorText)(part.nameArgNode, {
147
+ allowPartialTemplate: false
148
+ });
149
+ return name === null ? null : name.trim();
150
+ }
151
+ function getSelectorSource(match) {
152
+ if (match.interactionMethod !== 'click' ||
153
+ hasUnsupportedOptions(match.callNode)) {
154
+ return null;
155
+ }
156
+ const parts = [];
157
+ for (const part of match.selectorParts) {
158
+ const folded = foldSelectorPart(part);
159
+ // A link that cannot be read could carry the very token that rules the tab
160
+ // out, so a chain is read only when every link of it is static.
161
+ if (folded === null) {
162
+ return null;
163
+ }
164
+ parts.push(folded);
165
+ }
166
+ return {
167
+ node: match.callNode,
168
+ selector: parts.join(' >> '),
169
+ tabRoleName: tabRoleNameOf(match.selectorParts[match.selectorParts.length - 1])
170
+ };
171
+ }
172
+ /**
173
+ * True when `[title <operator> "<value>"]` names the tab whose caption starts
174
+ * with `title`.
175
+ *
176
+ * Only the three operators that the start of the caption settles are read.
177
+ * `$=`, `~=` and `|=` are matched against its end, which the file browser
178
+ * shortcut leaves unknown, so a selector using one of them is left alone. The
179
+ * value has to fit inside the caption, never the other way round: a title such
180
+ * as `Close Debugger` contains a caption without naming the tab that holds it.
181
+ */
182
+ function titleValueNamesTab(operator, value, title) {
183
+ switch (operator) {
184
+ case '=':
185
+ return value === title;
186
+ case '^=':
187
+ return title.startsWith(value);
188
+ case '*=':
189
+ return title.includes(value);
190
+ default:
191
+ return false;
192
+ }
193
+ }
194
+ /**
195
+ * The single sidebar tab an attribute value names, or null when it names none
196
+ * or more than one. A short prefix such as `[title^="P"]` fits one caption and
197
+ * is taken; one that fits two is dropped rather than resolved arbitrarily.
198
+ */
199
+ function findTabByTitleAttribute(operator, value) {
200
+ let found = null;
201
+ for (const [title, tab] of SIDEBAR_TITLE_TO_TAB) {
202
+ if (!titleValueNamesTab(operator, value, title)) {
203
+ continue;
204
+ }
205
+ if (found) {
206
+ return null;
207
+ }
208
+ found = { title, ...tab };
209
+ }
210
+ return found;
211
+ }
212
+ function findSidebarTitle(source) {
213
+ // Every way a selector can name a sidebar tab spells one of these out, and
214
+ // most interactions in a Galata suite spell out neither, so the substring
215
+ // test keeps the pattern scans off the common path.
216
+ if (source.tabRoleName === null &&
217
+ !source.selector.includes('title') &&
218
+ !source.selector.includes('data-id')) {
219
+ return null;
220
+ }
221
+ if (MAIN_AREA_PATTERN.test(source.selector) ||
222
+ DOCK_AREA_PATTERN.test(source.selector)) {
223
+ return null;
224
+ }
225
+ if (source.tabRoleName !== null) {
226
+ const tab = SIDEBAR_TITLE_TO_TAB.get(source.tabRoleName);
227
+ if (tab) {
228
+ return { title: source.tabRoleName, ...tab };
229
+ }
230
+ }
231
+ for (const match of source.selector.matchAll(TITLE_ATTRIBUTE_PATTERN)) {
232
+ const tab = findTabByTitleAttribute(match[1], match[2] ?? match[3]);
233
+ if (tab) {
234
+ return tab;
235
+ }
236
+ }
237
+ for (const match of source.selector.matchAll(DATA_ID_ATTRIBUTE_PATTERN)) {
238
+ const tab = SIDEBAR_ID_TO_TAB.get(match[1] ?? match[2]);
239
+ if (tab) {
240
+ return tab;
241
+ }
242
+ }
243
+ return null;
244
+ }
245
+ /** The text a selector matches on, written as `text=` or as `:text-is()`. */
246
+ function activityTextFrom(selector) {
247
+ const text = TEXT_SELECTOR_PATTERN.exec(selector);
248
+ if (text) {
249
+ return (text[1] ?? text[2] ?? text[3]).trim();
250
+ }
251
+ const exact = TEXT_IS_PATTERN.exec(selector);
252
+ return exact ? (exact[1] ?? exact[2]).trim() : null;
253
+ }
254
+ function getActivityTabName(source) {
255
+ const { selector } = source;
256
+ // The name comes from `text=`, from `:text-is()` or from the role name, so
257
+ // without either there is nothing to put in the message. Same reason as the
258
+ // guard in `findSidebarTitle`.
259
+ if (source.tabRoleName === null && !selector.includes('text')) {
260
+ return null;
261
+ }
262
+ if (SIDE_TABBAR_PATTERN.test(selector)) {
263
+ return null;
264
+ }
265
+ const inMainArea = MAIN_AREA_PATTERN.test(selector);
266
+ // A tab token proves the target is a tab wherever it is written. Without one
267
+ // the only evidence is the main area plus a name shaped like a file, which
268
+ // the dock panel node also covers the widget content with, so that path
269
+ // stays the fallback.
270
+ const namesTab = LUMINO_TAB_CLASS_PATTERN.test(selector) ||
271
+ (TAB_ROLE_PATTERN.test(selector) && inMainArea);
272
+ // Galata builds its own tab locator as
273
+ // `page.getByRole('main').getByRole('tab', { name })`, so a chain written
274
+ // that way names the activity outright.
275
+ const tabName = activityTextFrom(selector) ?? (inMainArea ? source.tabRoleName : null);
276
+ if (tabName === null || tabName.length === 0) {
277
+ return null;
278
+ }
279
+ const looksLikeADocumentInTheMainArea = inMainArea && FILE_LIKE_ACTIVITY_NAME_PATTERN.test(tabName);
280
+ return namesTab || looksLikeADocumentInTheMainArea ? tabName : null;
281
+ }
282
+ const galataPreferSidebarActivityHelper = (0, create_rule_1.createRule)({
283
+ name: 'galata-prefer-sidebar-activity-helper',
284
+ meta: {
285
+ type: 'suggestion',
286
+ docs: {
287
+ description: 'Prefer Galata sidebar and activity helpers over raw Playwright tab selectors'
288
+ },
289
+ messages: {
290
+ preferSidebarHelper: 'Use page.sidebar.openTab("{{ id }}") to open the "{{ title }}" sidebar tab, or page.sidebar.close("{{ side }}"), its default side, if this click is closing the sidebar.',
291
+ preferActivityHelper: 'Use page.activity.activateTab("{{ tabName }}") instead of clicking a main area tab by text.'
292
+ },
293
+ schema: []
294
+ },
295
+ defaultOptions: [],
296
+ create(context) {
297
+ function reportSelectorSource(source) {
298
+ const sidebar = findSidebarTitle(source);
299
+ if (sidebar) {
300
+ context.report({
301
+ node: source.node,
302
+ messageId: 'preferSidebarHelper',
303
+ data: { title: sidebar.title, id: sidebar.id, side: sidebar.side }
304
+ });
305
+ return;
306
+ }
307
+ const tabName = getActivityTabName(source);
308
+ if (tabName) {
309
+ context.report({
310
+ node: source.node,
311
+ messageId: 'preferActivityHelper',
312
+ data: { tabName }
313
+ });
314
+ }
315
+ }
316
+ return {
317
+ CallExpression(node) {
318
+ // Most call expressions are not interactions at all, and
319
+ // `matchSelectorInteraction` rejects them on the callee alone, so the
320
+ // scope is looked up only once something actually needs it.
321
+ let scope = null;
322
+ const currentScope = () => (scope ?? (scope = context.sourceCode.getScope(node)));
323
+ const match = (0, playwright_selectors_1.matchSelectorInteraction)(node, identifier => (0, playwright_selectors_1.resolveLocatorBinding)(identifier, currentScope()));
324
+ const source = match ? getSelectorSource(match) : null;
325
+ if (source) {
326
+ reportSelectorSource(source);
327
+ }
328
+ }
329
+ };
330
+ }
331
+ });
332
+ module.exports = galataPreferSidebarActivityHelper;
@@ -1,4 +1,4 @@
1
- declare const noSchemaEnum: import("@typescript-eslint/utils/ts-eslint").RuleModule<"forbidEnum", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
1
+ declare const noSchemaEnum: import("@typescript-eslint/utils/ts-eslint").RuleModule<"forbidEnum" | "requireStringType", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
2
2
  name: string;
3
3
  };
4
4
  export = noSchemaEnum;
@@ -7,16 +7,52 @@ const create_rule_1 = require("../utils/create-rule");
7
7
  function isSchemaJsonFile(filename) {
8
8
  return /[/\\]schema[/\\][^/\\]*\.json$/.test(filename);
9
9
  }
10
+ function getProperty(node, name) {
11
+ return node.properties.find(property => {
12
+ if (property.key.type === 'JSONLiteral') {
13
+ return property.key.value === name;
14
+ }
15
+ return property.key.name === name;
16
+ });
17
+ }
18
+ function hasOnlyStringConstChoices(node) {
19
+ return (node.elements.length > 0 &&
20
+ node.elements.every(element => {
21
+ if (element.type !== 'JSONObjectExpression') {
22
+ return false;
23
+ }
24
+ const constProperty = getProperty(element, 'const');
25
+ return (constProperty !== undefined &&
26
+ constProperty.value.type === 'JSONLiteral' &&
27
+ typeof constProperty.value.value === 'string');
28
+ }));
29
+ }
30
+ function getStringTypeInsertion(sourceCode, node) {
31
+ const beforeNode = sourceCode.text.slice(0, node.range[0]);
32
+ const lastNewline = beforeNode.lastIndexOf('\n');
33
+ const lineStart = beforeNode.slice(lastNewline + 1);
34
+ if (lastNewline !== -1 && /^[ \t]*$/.test(lineStart)) {
35
+ const lineBreak = sourceCode.text.includes('\r\n') ? '\r\n' : '\n';
36
+ return `"type": "string",${lineBreak}${lineStart}`;
37
+ }
38
+ // The property shares its line with an earlier token, so the new property has
39
+ // to go on that line too. Repeat the spacing that already separates the
40
+ // properties, which keeps a Prettier-formatted single-line object formatted.
41
+ const spacing = /[ \t]*$/.exec(beforeNode)?.[0] ?? '';
42
+ return spacing ? `"type": "string",${spacing}` : '"type":"string",';
43
+ }
10
44
  const noSchemaEnum = (0, create_rule_1.createRule)({
11
45
  name: 'no-schema-enum',
12
46
  meta: {
13
47
  type: 'suggestion',
14
48
  docs: {
15
- description: 'Disallow `enum` in settings JSON schema files; use `oneOf` with `const` and `title` instead'
49
+ description: 'Disallow `enum` in settings JSON schema files; use `oneOf` with `const`, `title`, and `type` instead'
16
50
  },
17
51
  messages: {
18
- forbidEnum: 'Avoid `enum` in settings schema. Use `oneOf` with `const` and `title` per entry to support user-facing labels and translations.'
52
+ forbidEnum: 'Avoid `enum` in settings schema. Use `oneOf` with `const` and `title` per entry to support user-facing labels and translations.',
53
+ requireStringType: 'Add `type: "string"` next to `oneOf`; React JSON Schema Form may not render string choices without it.'
19
54
  },
55
+ fixable: 'code',
20
56
  schema: []
21
57
  },
22
58
  defaultOptions: [],
@@ -30,6 +66,22 @@ const noSchemaEnum = (0, create_rule_1.createRule)({
30
66
  if (keyValue === 'enum' && node.value.type === 'JSONArrayExpression') {
31
67
  context.report({ loc: node.loc, messageId: 'forbidEnum' });
32
68
  }
69
+ if (keyValue !== 'oneOf' || node.value.type !== 'JSONArrayExpression') {
70
+ return;
71
+ }
72
+ const schemaNode = node.parent?.type === 'JSONObjectExpression'
73
+ ? node.parent
74
+ : undefined;
75
+ if (!schemaNode ||
76
+ getProperty(schemaNode, 'type') ||
77
+ !hasOnlyStringConstChoices(node.value)) {
78
+ return;
79
+ }
80
+ context.report({
81
+ loc: node.loc,
82
+ messageId: 'requireStringType',
83
+ fix: fixer => fixer.insertTextBeforeRange([node.range[0], node.range[0]], getStringTypeInsertion(context.sourceCode, node))
84
+ });
33
85
  }
34
86
  };
35
87
  }
@@ -0,0 +1,6 @@
1
+ import { ESLintUtils } from '@typescript-eslint/utils';
2
+ import { LazyImportOptions } from '../utils/lazy-imports';
3
+ declare const jupyterPreferLazyImports: ESLintUtils.RuleModule<string, [LazyImportOptions], unknown, ESLintUtils.RuleListener> & {
4
+ name: string;
5
+ };
6
+ export = jupyterPreferLazyImports;