⚠️ This repository is no longer maintained. Since we have ported all the features to the ESMeta framework, please use it instead.

JSSpecVis is a tool that visualizes the JavaScript language specification (ECMA-262). It extends ESMeta tool-chain to extract the mechanized specification from ECMA-262 and visualize it in a web browser.

We explain how to install JSSpecVis with the necessary environment settings from scratch. Our framework is developed in Scala, which works on JDK 17+. So before installation, please install JDK 17+ and sbt, an interactive build tool for Scala. And, you need npm to run the program visualizer and client-side of double debugger.

git clone https://github.com/ku-plrg/js-spec-vis.git

Insert the following commands to ~/.bashrc (or ~/.zshrc):

# for JSSpecVis
export ESMETA_HOME="<path to JSSpecVis>" # IMPORTANT!!!
export PATH="$ESMETA_HOME/bin:$PATH" # for executables `js-spec-vis` and etc.
source $ESMETA_HOME/.completion # for auto-completion

The <path to JSSpecVis> should be the absolute path of the JSSpecVis repository.

Please type the following command to 1) update the git submodules, 2) generate binary file bin/js-spec-vis, and 3) apply the .completion for auto-completion.

git submodule update --init && sbt assembly && source .completion

If you see the following message, JSSpecVis is successfully installed:

js-spec-vis
# Welcome to JSSpecVis v1.0.0 - A JavaScript Language Specification Visualization Tool.
# Please type `js-spec-vis help` to see the help message.

JSSpecVis consists of three main components: 1) Program Collector as a preprocessor, 2) Program Visualizer for browsing the collected programs, and 3) Double Debugger for interactive execution of JavaScript programs on the specification.

First, you need to collect example programs from the mechanized specification of ES2024. It consists of three phases: 1) fuzzing, 2) executing test262, 3) collecting the programs.

However, fuzzing require tens of hours to collect the programs, and executing test262 require more than 10 minutes. So, we provide three options to collect the programs.

The easiest way to use JSSpecVis is to use the pre-collected dataset. First, unzip the resources.tar.gz file:

tar -xzvf resources.tar.gz

Then, move the resources directory to the visualizer public directory:

mv resources visualizer/public/

tar -xzvf fuzz-data.tar.gz

rm -f logs/fuzz/recent && mv fuzz-data logs/fuzz/recent

js-spec-vis test262-test -test262-test:progress -test262-test:log -test262-test:concurrent=0 -test262-test:total-coverage

js-spec-vis construct

mv logs/fuzz/recent/json-dump visualizer/public/resources
mv static-data/* visualizer/public/resources

js-spec-vis fuzz -fuzz:log -fuzz:cp -fuzz:k-fs=1

js-spec-vis test262-test -test262-test:progress -test262-test:log -test262-test:concurrent=0 -test262-test:total-coverage

js-spec-vis construct

mv logs/fuzz/recent/json-dump visualizer/public/resources
mv static-data/* visualizer/public/resources

Enter the visualizer directory:

cd visualizer

Then, run the following command to build the visualizer:

npm install && npm run build

And follow the instructions below to install the visualizer extension:

1. Open the Chrome browser and enter chrome://extensions/.
2. Turn on the Developer mode on the top right corner.
3. Click the Load unpacked button and select the visualizer/dist directory.

It works on ES2024 web page: https://tc39.es/ecma262/2024/.

It requires two steps to run the double debugger. First, you need to turn on the server using js-spec-vis:

js-spec-vis web

For the client side, enter the client directory:

cd client

Then, run the following command to start the client:

npm install && npm start

Then, open the browser and enter http://localhost:3000 to use the double debugger.