Add npm project for Python API

.eslintignore

@@ -1,3 +1,5 @@
+pythonExtensionApi/out/
+
 # The following files were grandfathered out of eslint. They can be removed as time permits.
 
 src/test/analysisEngineTest.ts

.gitignore

@@ -23,6 +23,7 @@ cucumber-report.json
 port.txt
 precommit.hook
 pythonFiles/lib/**
+pythonFiles/get_pip.py
 debug_coverage*/**
 languageServer/**
 languageServer.*/**

build/azure-pipelines/pipeline.yml

@@ -0,0 +1,56 @@
+###############################################################################################
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License. See License.txt in the project root for license information.
+###############################################################################################
+name: $(Date:yyyyMMdd)$(Rev:.r)
+
+pr: none
+
+resources:
+  repositories:
+    - repository: templates
+      type: github
+      name: microsoft/vscode-engineering
+      ref: main
+      endpoint: Monaco
+
+parameters:
+  - name: quality
+    displayName: Quality
+    type: string
+    default: latest
+    values:
+      - latest
+      - next
+  - name: publishPythonApi
+    displayName: 🚀 Publish pythonExtensionApi
+    type: boolean
+    default: false
+
+extends:
+  template: azure-pipelines/npm-package/pipeline.yml@templates
+  parameters:
+    npmPackages:
+      - name: pythonExtensionApi
+        testPlatforms:
+          - name: Linux
+            nodeVersions:
+              - 16.17.1
+          - name: MacOS
+            nodeVersions:
+              - 16.17.1
+          - name: Windows
+            nodeVersions:
+              - 16.17.1
+        testSteps:
+          - template: /build/azure-pipelines/templates/test-steps.yml@self
+            parameters:
+              package: pythonExtensionApi
+        buildSteps:
+          - template: /build/azure-pipelines/templates/pack-steps.yml@self
+            parameters:
+              package: pythonExtensionApi
+        ghTagPrefix: release/pythonExtensionApi/
+        tag: ${{ parameters.quality }}
+        publishPackage: ${{ parameters.publishPythonApi }}
+        workingDirectory: $(Build.SourcesDirectory)/pythonExtensionApi

build/azure-pipelines/templates/pack-steps.yml

@@ -0,0 +1,14 @@
+###############################################################################################
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License. See License.txt in the project root for license information.
+###############################################################################################
+parameters:
+- name: package
+
+steps:
+  - script: npm install --root-only
+    workingDirectory: $(Build.SourcesDirectory)
+    displayName: Install root dependencies
+  - script: npm install
+    workingDirectory: $(Build.SourcesDirectory)/${{ parameters.package }}
+    displayName: Install package dependencies

build/azure-pipelines/templates/test-steps.yml

@@ -0,0 +1,23 @@
+###############################################################################################
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License. See License.txt in the project root for license information.
+###############################################################################################
+parameters:
+- name: package
+  type: string
+- name: script
+  type: string
+  default: 'all:publish'
+
+steps:
+  - script: npm install --root-only
+    workingDirectory: $(Build.SourcesDirectory)
+    displayName: Install root dependencies
+  - bash: |
+      /usr/bin/Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+      echo ">>> Started xvfb"
+    displayName: Start xvfb
+    condition: eq(variables['Agent.OS'], 'Linux')
+  - script: npm run ${{ parameters.script }}
+    workingDirectory: $(Build.SourcesDirectory)/${{ parameters.package }}
+    displayName: Verify package

build/fail.js

@@ -0,0 +1,6 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+process.exitCode = 1;

gulpfile.js

@@ -27,7 +27,7 @@ const tsProject = ts.createProject('./tsconfig.json', { typescript });
 
 const isCI = process.env.TRAVIS === 'true' || process.env.TF_BUILD !== undefined;
 
-gulp.task('compile', (done) => {
+gulp.task('compileCore', (done) => {
     let failed = false;
     tsProject
         .src()
@@ -39,6 +39,22 @@ gulp.task('compile', (done) => {
         .on('finish', () => (failed ? done(new Error('TypeScript compilation errors')) : done()));
 });
 
+const apiTsProject = ts.createProject('./pythonExtensionApi/tsconfig.json', { typescript });
+
+gulp.task('compileApi', (done) => {
+    let failed = false;
+    apiTsProject
+        .src()
+        .pipe(apiTsProject())
+        .on('error', () => {
+            failed = true;
+        })
+        .js.pipe(gulp.dest('./pythonExtensionApi/out'))
+        .on('finish', () => (failed ? done(new Error('TypeScript compilation errors')) : done()));
+});
+
+gulp.task('compile', gulp.series('compileCore', 'compileApi'));
+
 gulp.task('precommit', (done) => run({ exitOnError: true, mode: 'staged' }, done));
 
 gulp.task('output:clean', () => del(['coverage']));

package.json

@@ -1968,8 +1968,8 @@
         "testSmoke": "cross-env INSTALL_JUPYTER_EXTENSION=true \"node ./out/test/smokeTest.js\"",
         "testInsiders": "cross-env VSC_PYTHON_CI_TEST_VSC_CHANNEL=insiders INSTALL_PYLANCE_EXTENSION=true TEST_FILES_SUFFIX=insiders.test CODE_TESTS_WORKSPACE=src/testMultiRootWkspc/smokeTests \"node ./out/test/standardTest.js\"",
         "lint-staged": "node gulpfile.js",
-        "lint": "eslint --ext .ts,.js src build",
-        "lint-fix": "eslint --fix --ext .ts,.js src build gulpfile.js",
+        "lint": "eslint --ext .ts,.js src build pythonExtensionApi",
+        "lint-fix": "eslint --fix --ext .ts,.js src build pythonExtensionApi gulpfile.js",
         "format-check": "prettier --check 'src/**/*.ts' 'build/**/*.js' '.github/**/*.yml' gulpfile.js",
         "format-fix": "prettier --write 'src/**/*.ts' 'build/**/*.js' '.github/**/*.yml' gulpfile.js",
         "clean": "gulp clean",

pythonExtensionApi/.npmignore

@@ -0,0 +1,8 @@
+example/**
+dist/
+out/**/*.map
+out/**/*.tsbuildInfo
+src/
+.eslintrc*
+.eslintignore
+tsconfig*.json

pythonExtensionApi/LICENSE.md

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythonExtensionApi/README.md

@@ -0,0 +1,31 @@
+# Python extension's API
+
+This npm module implements an API facade for the Python extension in VS Code.
+
+## Example
+
+The source code of the example can be found [here](TODO Update example extension link here)
+
+First we need to define a `package.json` for the extension that wants to use the API:
+
+```jsonc
+{
+	"name": "...",
+	...
+	// depend on the Python extension
+	"extensionDependencies": [
+		"ms-python.python"
+	],
+	// Depend on the Python extension facade npm module to get easier API access to the
+	// core extension.
+	"dependencies": {
+		"@vscode/python-extension": "..."
+	},
+}
+```
+
+TODO insert example here
+
+```typescript
+TODO
+```

pythonExtensionApi/SECURITY.md

@@ -0,0 +1,41 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.5 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
+
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
+
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://microsoft.com/msrc/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

pythonExtensionApi/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@vscode/python-extension",
+    "description": "An API facade for the Python extension in VS Code",
+    "version": "1.0.0",
+    "author": {
+      "name": "Microsoft Corporation"
+    },
+    "keywords": [
+        "Python",
+		"VSCode",
+		"API"
+	],
+	"main": "./out/main.js",
+	"types": "./out/main.d.ts",
+	"engines": {
+		"node": ">=16.17.1",
+		"vscode": "^1.78.0"
+	},
+    "license": "MIT",
+    "homepage": "https://github.com/Microsoft/vscode-python",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Microsoft/vscode-python"
+    },
+    "bugs": {
+        "url": "https://github.com/Microsoft/vscode-python/issues"
+    },
+    "dependencies": {
+        "@types/vscode": "^1.78.0"
+    },
+    "scripts": {
+        "prepublishOnly": "echo \"⛔ Can only publish from a secure pipeline ⛔\" && node ../build/fail",
+		"prepack": "npm run all:publish",
+		"compile": "node ../node_modules/typescript/lib/tsc.js -b ./tsconfig.json",
+		"clean": "node ../node_modules/rimraf/bin.js out",
+		"lint": "node ../node_modules/eslint/bin/eslint.js --ext ts src",
+		"all": "npm run clean && npm run compile",
+		"all:publish": "git clean -xfd . && npm install && npm run compile"
+    }
+}

pythonExtensionApi/tsconfig.json

@@ -0,0 +1,34 @@
+{
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "*": ["types/*"]
+        },
+        "module": "commonjs",
+        "target": "es2018",
+        "outDir": "./out",
+        "lib": [
+            "es6",
+            "es2018",
+            "dom",
+            "ES2019",
+            "ES2020"
+        ],
+        "sourceMap": true,
+        "rootDir": "src",
+        "experimentalDecorators": true,
+        "allowSyntheticDefaultImports": true,
+        "strict": true,
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true,
+        "resolveJsonModule": true,
+        "removeComments": true
+    },
+    "exclude": [
+        "node_modules",
+        "out"
+    ]
+}

src/client/api.ts

@@ -10,7 +10,7 @@ import { BaseLanguageClient, LanguageClientOptions } from 'vscode-languageclient
 import { LanguageClient } from 'vscode-languageclient/node';
 import { PYLANCE_NAME } from './activation/node/languageClientFactory';
 import { ILanguageServerOutputChannel } from './activation/types';
-import { PythonExtension } from './api/main';
+import { PythonExtension } from './api/types';
 import { isTestExecution, PYTHON_LANGUAGE } from './common/constants';
 import { IConfigurationService, Resource } from './common/types';
 import { getDebugpyLauncherArgs, getDebugpyPackagePath } from './debugger/extension/adapter/remoteLaunchers';