Merge pull request #89777 from microsoft/joh/api-lint

Lint rules that enforce our api-guidelines

.eslintrc.json

@@ -26,7 +26,17 @@
         "no-throw-literal": "warn",
         "no-unsafe-finally": "warn",
         "no-unused-labels": "warn",
-        "no-restricted-globals": ["warn", "name", "length", "event", "closed", "external", "status", "origin", "orientation"], // non-complete list of globals that are easy to access unintentionally
+        "no-restricted-globals": [
+            "warn",
+            "name",
+            "length",
+            "event",
+            "closed",
+            "external",
+            "status",
+            "origin",
+            "orientation"
+        ], // non-complete list of globals that are easy to access unintentionally
         "no-var": "warn",
         "jsdoc/no-types": "warn",
         "semi": "off",
@@ -622,6 +632,50 @@
             "rules": {
                 "jsdoc/no-types": "off"
             }
+        },
+        {
+            "files": [
+                "**/vscode.d.ts",
+                "**/vscode.proposed.d.ts"
+            ],
+            "rules": {
+                "vscode-dts-create-func": "warn",
+                "vscode-dts-literal-or-types": "warn",
+                "vscode-dts-interface-naming": "warn",
+                "vscode-dts-event-naming": [
+                    "warn",
+                    {
+                        "allowed": [
+                            "onCancellationRequested",
+                            "event"
+                        ],
+                        "verbs": [
+                            "accept",
+                            "change",
+                            "close",
+                            "collapse",
+                            "create",
+                            "delete",
+                            "dispose",
+                            "end",
+                            "expand",
+                            "hide",
+                            "open",
+                            "override",
+                            "receive",
+                            "register",
+                            "rename",
+                            "save",
+                            "send",
+                            "start",
+                            "terminate",
+                            "trigger",
+                            "unregister",
+                            "write"
+                        ]
+                    }
+                ]
+            }
         }
     ]
 }

build/lib/eslint/vscode-dts-create-func.js

+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+const experimental_utils_1 = require("@typescript-eslint/experimental-utils");
+module.exports = new class ApiLiteralOrTypes {
+    constructor() {
+        this.meta = {
+            docs: { url: 'https://github.com/microsoft/vscode/wiki/Extension-API-guidelines#creating-objects' },
+            messages: { sync: '`createXYZ`-functions are constructor-replacements and therefore must return sync', }
+        };
+    }
+    create(context) {
+        return {
+            ['TSDeclareFunction Identifier[name=/create.*/]']: (node) => {
+                var _a;
+                const decl = node.parent;
+                if (((_a = decl.returnType) === null || _a === void 0 ? void 0 : _a.typeAnnotation.type) !== experimental_utils_1.AST_NODE_TYPES.TSTypeReference) {
+                    return;
+                }
+                if (decl.returnType.typeAnnotation.typeName.type !== experimental_utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                const ident = decl.returnType.typeAnnotation.typeName.name;
+                if (ident === 'Promise' || ident === 'Thenable') {
+                    context.report({
+                        node,
+                        messageId: 'sync'
+                    });
+                }
+            }
+        };
+    }
+};

build/lib/eslint/vscode-dts-create-func.ts

+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as eslint from 'eslint';
+import { TSESTree, AST_NODE_TYPES } from '@typescript-eslint/experimental-utils';
+
+export = new class ApiLiteralOrTypes implements eslint.Rule.RuleModule {
+
+	readonly meta: eslint.Rule.RuleMetaData = {
+		docs: { url: 'https://github.com/microsoft/vscode/wiki/Extension-API-guidelines#creating-objects' },
+		messages: { sync: '`createXYZ`-functions are constructor-replacements and therefore must return sync', }
+	};
+
+	create(context: eslint.Rule.RuleContext): eslint.Rule.RuleListener {
+
+		return {
+			['TSDeclareFunction Identifier[name=/create.*/]']: (node: any) => {
+
+				const decl = <TSESTree.FunctionDeclaration>(<TSESTree.Identifier>node).parent;
+
+				if (decl.returnType?.typeAnnotation.type !== AST_NODE_TYPES.TSTypeReference) {
+					return;
+				}
+				if (decl.returnType.typeAnnotation.typeName.type !== AST_NODE_TYPES.Identifier) {
+					return;
+				}
+
+				const ident = decl.returnType.typeAnnotation.typeName.name;
+				if (ident === 'Promise' || ident === 'Thenable') {
+					context.report({
+						node,
+						messageId: 'sync'
+					});
+				}
+			}
+		};
+	}
+};

build/lib/eslint/vscode-dts-event-naming.js

+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+var _a;
+const experimental_utils_1 = require("@typescript-eslint/experimental-utils");
+module.exports = new (_a = class ApiEventNaming {
+        constructor() {
+            this.meta = {
+                docs: {
+                    url: 'https://github.com/microsoft/vscode/wiki/Extension-API-guidelines#event-naming'
+                },
+                messages: {
+                    naming: 'Event names must follow this patten: `on[Did|Will]<Verb><Subject>`',
+                    verb: 'Unknown verb \'{{verb}}\' - is this really a verb? Iff so, then add this verb to the configuration',
+                    subject: 'Unknown subject \'{{subject}}\' - This subject has not been used before but it should refer to something in the API',
+                    unknown: 'UNKNOWN event declaration, lint-rule needs tweaking'
+                }
+            };
+        }
+        create(context) {
+            const config = context.options[0];
+            const allowed = new Set(config.allowed);
+            const verbs = new Set(config.verbs);
+            return {
+                ['TSTypeAnnotation TSTypeReference Identifier[name="Event"]']: (node) => {
+                    var _a, _b;
+                    const def = (_b = (_a = node.parent) === null || _a === void 0 ? void 0 : _a.parent) === null || _b === void 0 ? void 0 : _b.parent;
+                    let ident;
+                    if ((def === null || def === void 0 ? void 0 : def.type) === experimental_utils_1.AST_NODE_TYPES.Identifier) {
+                        ident = def;
+                    }
+                    else if (((def === null || def === void 0 ? void 0 : def.type) === experimental_utils_1.AST_NODE_TYPES.TSPropertySignature || (def === null || def === void 0 ? void 0 : def.type) === experimental_utils_1.AST_NODE_TYPES.ClassProperty) && def.key.type === experimental_utils_1.AST_NODE_TYPES.Identifier) {
+                        ident = def.key;
+                    }
+                    if (!ident) {
+                        // event on unknown structure...
+                        return context.report({
+                            node,
+                            message: 'unknown'
+                        });
+                    }
+                    if (allowed.has(ident.name)) {
+                        // configured exception
+                        return;
+                    }
+                    const match = ApiEventNaming._nameRegExp.exec(ident.name);
+                    if (!match) {
+                        context.report({
+                            node: ident,
+                            messageId: 'naming'
+                        });
+                        return;
+                    }
+                    // check that <verb> is spelled out (configured) as verb
+                    if (!verbs.has(match[2].toLowerCase())) {
+                        context.report({
+                            node: ident,
+                            messageId: 'verb',
+                            data: { verb: match[2] }
+                        });
+                    }
+                    // check that a subject (if present) has occurred
+                    if (match[3]) {
+                        const regex = new RegExp(match[3], 'ig');
+                        const parts = context.getSourceCode().getText().split(regex);
+                        if (parts.length < 3) {
+                            context.report({
+                                node: ident,
+                                messageId: 'subject',
+                                data: { subject: match[3] }
+                            });
+                        }
+                    }
+                }
+            };
+        }
+    },
+    _a._nameRegExp = /on(Did|Will)([A-Z][a-z]+)([A-Z][a-z]+)?/,
+    _a);

build/lib/eslint/vscode-dts-event-naming.ts

+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as eslint from 'eslint';
+import { TSESTree, AST_NODE_TYPES } from '@typescript-eslint/experimental-utils';
+
+export = new class ApiEventNaming implements eslint.Rule.RuleModule {
+
+	private static _nameRegExp = /on(Did|Will)([A-Z][a-z]+)([A-Z][a-z]+)?/;
+
+	readonly meta: eslint.Rule.RuleMetaData = {
+		docs: {
+			url: 'https://github.com/microsoft/vscode/wiki/Extension-API-guidelines#event-naming'
+		},
+		messages: {
+			naming: 'Event names must follow this patten: `on[Did|Will]<Verb><Subject>`',
+			verb: 'Unknown verb \'{{verb}}\' - is this really a verb? Iff so, then add this verb to the configuration',
+			subject: 'Unknown subject \'{{subject}}\' - This subject has not been used before but it should refer to something in the API',
+			unknown: 'UNKNOWN event declaration, lint-rule needs tweaking'
+		}
+	};
+
+	create(context: eslint.Rule.RuleContext): eslint.Rule.RuleListener {
+
+		const config = <{ allowed: string[], verbs: string[] }>context.options[0];
+		const allowed = new Set(config.allowed);
+		const verbs = new Set(config.verbs);
+
+		return {
+			['TSTypeAnnotation TSTypeReference Identifier[name="Event"]']: (node: any) => {
+
+				const def = (<TSESTree.Identifier>node).parent?.parent?.parent;
+				let ident: TSESTree.Identifier | undefined;
+
+				if (def?.type === AST_NODE_TYPES.Identifier) {
+					ident = def;
+
+				} else if ((def?.type === AST_NODE_TYPES.TSPropertySignature || def?.type === AST_NODE_TYPES.ClassProperty) && def.key.type === AST_NODE_TYPES.Identifier) {
+					ident = def.key;
+				}
+
+				if (!ident) {
+					// event on unknown structure...
+					return context.report({
+						node,
+						message: 'unknown'
+					});
+				}
+
+				if (allowed.has(ident.name)) {
+					// configured exception
+					return;
+				}
+
+				const match = ApiEventNaming._nameRegExp.exec(ident.name);
+				if (!match) {
+					context.report({
+						node: ident,
+						messageId: 'naming'
+					});
+					return;
+				}
+
+				// check that <verb> is spelled out (configured) as verb
+				if (!verbs.has(match[2].toLowerCase())) {
+					context.report({
+						node: ident,
+						messageId: 'verb',
+						data: { verb: match[2] }
+					});
+				}
+
+				// check that a subject (if present) has occurred
+				if (match[3]) {
+					const regex = new RegExp(match[3], 'ig');
+					const parts = context.getSourceCode().getText().split(regex);
+					if (parts.length < 3) {
+						context.report({
+							node: ident,
+							messageId: 'subject',
+							data: { subject: match[3] }
+						});
+					}
+				}
+			}
+		};
+	}
+};
+

build/lib/eslint/vscode-dts-interface-naming.js

+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+var _a;
+module.exports = new (_a = class ApiInterfaceNaming {
+        constructor() {
+            this.meta = {
+                messages: {
+                    naming: 'Interfaces must not be prefixed with uppercase `I`',
+                }
+            };
+        }
+        create(context) {
+            return {
+                ['TSInterfaceDeclaration Identifier']: (node) => {
+                    const name = node.name;
+                    if (ApiInterfaceNaming._nameRegExp.test(name)) {
+                        context.report({
+                            node,
+                            messageId: 'naming'
+                        });
+                    }
+                }
+            };
+        }
+    },
+    _a._nameRegExp = /I[A-Z]/,
+    _a);

build/lib/eslint/vscode-dts-interface-naming.ts

+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as eslint from 'eslint';
+import { TSESTree } from '@typescript-eslint/experimental-utils';
+
+export = new class ApiInterfaceNaming implements eslint.Rule.RuleModule {
+
+	private static _nameRegExp = /I[A-Z]/;
+
+	readonly meta: eslint.Rule.RuleMetaData = {
+		messages: {
+			naming: 'Interfaces must not be prefixed with uppercase `I`',
+		}
+	};
+
+	create(context: eslint.Rule.RuleContext): eslint.Rule.RuleListener {
+
+		return {
+			['TSInterfaceDeclaration Identifier']: (node: any) => {
+
+				const name = (<TSESTree.Identifier>node).name;
+				if (ApiInterfaceNaming._nameRegExp.test(name)) {
+					context.report({
+						node,
+						messageId: 'naming'
+					});
+				}
+			}
+		};
+	}
+};
+

build/lib/eslint/vscode-dts-literal-or-types.js

+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+module.exports = new class ApiLiteralOrTypes {
+    constructor() {
+        this.meta = {
+            docs: { url: 'https://github.com/microsoft/vscode/wiki/Extension-API-guidelines#enums' },
+            messages: { useEnum: 'Use enums, not literal-or-types', }
+        };
+    }
+    create(context) {
+        return {
+            ['TSTypeAnnotation TSUnionType TSLiteralType']: (node) => {
+                context.report({
+                    node: node,
+                    messageId: 'useEnum'
+                });
+            }
+        };
+    }
+};

build/lib/eslint/vscode-dts-literal-or-types.ts

+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as eslint from 'eslint';
+
+export = new class ApiLiteralOrTypes implements eslint.Rule.RuleModule {
+
+	readonly meta: eslint.Rule.RuleMetaData = {
+		docs: { url: 'https://github.com/microsoft/vscode/wiki/Extension-API-guidelines#enums' },
+		messages: { useEnum: 'Use enums, not literal-or-types', }
+	};
+
+	create(context: eslint.Rule.RuleContext): eslint.Rule.RuleListener {
+		return {
+			['TSTypeAnnotation TSUnionType TSLiteralType']: (node: any) => {
+				context.report({
+					node: node,
+					messageId: 'useEnum'
+				});
+			}
+		};
+	}
+};

src/vs/vscode.proposed.d.ts

@@ -171,6 +171,8 @@ declare module 'vscode' {
 		/**
 		 * Fired when the list of tunnels has changed.
 		 */
+		// TODO@alexr
+		// eslint-disable-next-line vscode-dts-event-naming
 		export const onDidTunnelsChange: Event<void>;
 	}
 
@@ -182,6 +184,8 @@ declare module 'vscode' {
 
 	export interface ResourceLabelFormatting {
 		label: string; // myLabel:/${path}
+		// TODO@isi
+		// eslint-disable-next-line vscode-dts-literal-or-types
 		separator: '/' | '\\' | '';
 		tildify?: boolean;
 		normalizeDriveLetter?: boolean;
@@ -1241,6 +1245,8 @@ declare module 'vscode' {
 		/**
 		 * Event triggered by extensions to signal to VS Code that an edit has occurred.
 		 */
+		// TODO@matt
+		// eslint-disable-next-line vscode-dts-event-naming
 		readonly onEdit: Event<{ readonly resource: Uri, readonly edit: EditType }>;
 
 		/**