Eclipse Theia vs VS Code API Comparator

Overview

The repository contains the source code to generate a status report regarding the compatibility between the Eclipse Theia framework, and the VS Code Extension API.

Prerequisites

The environment variable GITHUB_TOKEN must be defined with a valid GitHub token. The tool grabs files remotely, and checks the latest versions using the GraphQL GitHub API.

Creating the Report

Install dependencies:

npm install

Build the tool:

npm run build

Generate the report (requires GITHUB_TOKEN to be set):

npm run generate

Example output:

 $ node lib/index.js
 🔍 Searching on GitHub for tagged Theia versions...
 🗂  The Theia versions to compare will be master, v1.29.0, v1.28.0
 🗃  Grabbing content...✔️
 🔍 Searching on GitHub for tagged VSCode versions...
 🗂  The VSCode versions to compare will be main, 1.71.0, 1.70.2, 1.69.2, 1.68.1, 1.55.2, 1.53.2
 🗃  Grabbing content...✔️
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/theia-master.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/theia-v1.29.0.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/theia-v1.28.0.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/vscode-1.71.0.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/vscode-1.70.2.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/vscode-1.69.2.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/vscode-1.68.1.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/vscode-1.55.2.d.ts...
 ⚙️  Analyzing /home/user/Git/vscode-theia-comparator/lib/vscode-1.53.2.d.ts...
 ⚙️  Parsing additional information from infos.yml...
 ⚙️  Generating HTML report...
 ✍️  HTML status written at /home/user/Git/vscode-theia-comparator/out/status.html
 🔗 Open in browser: file:///home/user/Git/vscode-theia-comparator/out/status.html

The generated report is written to out/status.html. The tool prints a clickable file:// URI you can open directly in your browser.

Additional CLI options

Using a local repository

In order to compare the state of local repositories, you may use the theia-path and vscode-path options. If these options are provided and no additional versions are provided on the command line, only the local states will be compared.

npm run generate -- theia-path=/path/to/theia vscode-path=/path/to/vscode

In this case, only your local Theia and VSCode repositories will be compared.

npm run generate -- theia-path=/path/to/theia

With these arguments, your local Theia will be compared with the default set of VSCode versions fetched from GitHub.

npm run generate -- theia-path=/path/to/theia theia-versions=v1.27.0

With this input, the local copy of Theia as well as version 1.27.0 fetched from GitHub will be compared with the default set of VSCode versions fetched from GitHub.

Defining versions for comparison

In order to control the versions used for comparison, you can pass a list of comma-separated commit references (tags, branch names, SHA's) as theia-versions or vscode-versions. At present, the references must be found in the main repository (i.e. not a fork) for each comparandum.

npm run generate -- theia-versions=v1.27.0,v1.26.0,master vscode-versions=main,1.0.0

This input will compare the master branch and (tagged) versions 1.27.0 and 1.26.0 of Theia with the main branch and (tagged) version 1.0.0 of VSCode.

Provide additional information

The generator can add notes for any namespace, element or sub element. Notes are read from conf/infos.yml. An example on how these are configured is given in conf/infos.example.yml.