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

1. Build the tool:

   $ yarn
   

2. Generate the report:

   $ yarn 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
   

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.

yarn 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.

yarn 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.

yarn 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.

yarn 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.