Bump NodeJS to version 20 (#1513)

* Create .node-version file

* Fix `gl` build error via dependency resolution

Also bumps the version of `node-gyp` transitive dependency to address a
security vulnerability.

* Bump `gpu.js`, `gl` dependencies in ./sicp_publish

* Update CI workflows

Bumps dependency versions, as well as remove manual caching.

* Fix workflow errors due to missing libraries

* Bump NodeJS to v20.11.0

* Update README

* Update Node version
* Remove duplicate header
* Change H1s to H2s for better hierarchy

* Reformat README

* Remove soft breaks
* Add syntax highlighting for commands
* Fix license line break

Author: RichDom2185

.github/workflows/deploy-docs.yml

@@ -7,27 +7,20 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@master
+      - name: Checkout repository
+        uses: actions/checkout@v4
       - name: Use Node.js
-        uses: actions/setup-node@v2-beta
+        uses: actions/setup-node@v4
         with:
-          node-version: '16'
+          node-version: 20
+          cache: yarn
       - name: Install TeX Live
         run: |
           sudo apt-get update -y
           sudo apt-get install -y texlive texlive-fonts-extra texlive-lang-cjk latexmk
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
-      - uses: actions/cache@v2
-        id: yarn-cache
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
+          sudo apt-get install -y --no-install-recommends libxi-dev libgl1-mesa-dev
       - name: Fetch Yarn dependencies
-        run: yarn install
+        run: yarn install --frozen-lockfile
       - name: Build
         run: |
           yarn run jsdoc prepare

.github/workflows/nodejs.yml

@@ -5,37 +5,36 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ master ]
+    branches:
+      - master
   pull_request:
-    branches: [ master ]
+    branches:
+      - master
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [16.x]
-
     steps:
-    - uses: actions/checkout@v2
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
     - name: Check for package-lock.json
       run: |
         if [ -e package-lock.json ]; then
           echo "package-lock.json found; please do not use NPM! This project uses Yarn!"
           exit 1
         fi
         exit 0
-    - name: Checkout code
-      uses: actions/checkout@v2
-      with:
-        submodules: recursive
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+    - name: Install dependencies (apt)
+      run: |
+        sudo apt-get install -y --no-install-recommends libxi-dev libgl1-mesa-dev
+    - name: Setup Node
+      uses: actions/setup-node@v4
       with:
-        node-version: ${{ matrix.node-version }}
-    - run: yarn
+        node-version: 20
+        cache: yarn
+    - run: yarn install --frozen-lockfile
     - run: yarn build
     - run: yarn format:ci
     - run: yarn eslint

.github/workflows/publish-npm.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           ref: master
           submodules: recursive
@@ -33,14 +33,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           ref: master
           submodules: recursive
+      - name: Install dependencies (apt)
+        run: |
+          sudo apt-get install -y --no-install-recommends libxi-dev libgl1-mesa-dev
       - name: Setup Node.js
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version: 20
       - name: Install dependencies
         run: yarn install --frozen-lockfile
       - name: Publish to npm

.node-version

@@ -0,0 +1 @@
+20.11.0

README.md

@@ -1,17 +1,13 @@
 # js-slang
 
-Open-source implementations of the programming language _Source_. Source is a
-series of small subsets of JavaScript, designed for teaching university-level
-programming courses for computer science majors, following Structure and
-Interpretation of Computer Programs, JavaScript Adaptation
-(<https://sourceacademy.org/sicpjs/>).
+Open-source implementations of the programming language _Source_. Source is a series of small subsets of JavaScript, designed for teaching university-level programming courses for computer science majors, following Structure and Interpretation of Computer Programs, JavaScript Adaptation (<https://sourceacademy.org/sicpjs/>).
 
-# Table of Contents
+## Table of Contents
 
-- [Requirements](#requirements)
+- [Prerequisites](#prerequisites)
 - [Usage](#usage)
 - [Documentation](#documentation)
-- [Requirements](#requirements-1)
+- [Requirements](#requirements)
 - [Testing](#testing)
 - [Error messages](#error-messages)
 - [Using your js-slang in Source Academy](#using-your-js-slang-in-source-academy)
@@ -20,18 +16,16 @@ Interpretation of Computer Programs, JavaScript Adaptation
 - [Talks and Presentations](#talks-and-presentations)
 - [License](#license)
 
-# Requirements
+## Prerequisites
 
-- node: known working version: v16.14.0
+- NodeJS v20
+- Python: On MacBook Pro with chip Apple M1 Pro, use python 3.10.12. Here is [the correct way to set Python 3 as default on a Mac](https://opensource.com/article/19/5/python-3-default-mac).
 
-- python: On MacBook Pro with chip Apple M1 Pro, use python 3.10.12. Here is
-[the correct way to set Python 3 as default on a Mac](https://opensource.com/article/19/5/python-3-default-mac).
-
-# Usage
+## Usage
 
 To build,
 
-```{.}
+```bash
 $ git clone --recurse-submodules https://github.com/source-academy/js-slang.git
 $ cd js-slang
 $ yarn
@@ -40,27 +34,25 @@ $ yarn build
 
 This repository uses git submodules. To update existing repositories with a submodule,
 
-```{.}
+```bash
 # Init is only required on the very first time.
 $ git submodule update --init --recursive
 # Required subsequently every time you want to update the submodules.
 $ git submodule update --recursive --remote
 ```
 
-To add \"js-slang\" to your PATH, build it as per the above instructions, then
-run
+To add \"js-slang\" to your PATH, build it as per the above instructions, then run
 
-```{.}
+```bash
 $ cd dist
 $ npm link
 ```
 
-If you do not wish to add \"js-slang\" to your PATH, replace \"js-slang\" with
-\"node dist/repl/repl.js\" in the following examples.
+If you do not wish to add \"js-slang\" to your PATH, replace \"js-slang\" with \"node dist/repl/repl.js\" in the following examples.
 
 To try out _Source_ in a REPL, run
 
-```{.}
+```bash
 $ js-slang -c [chapter] # default: 1
 ```
 
@@ -99,15 +91,15 @@ Currently, valid CHAPTER/VARIANT combinations are:
 
 Hint: In `bash` you can take the `PROGRAM_STRING` out of a file as follows:
 
-```{.}
+```bash
 $ js-slang -n --chapter=1 -e "$(< my_source_program.js)"
 ```
 
-# Documentation
+## Documentation
 
 Source is documented here: <https://docs.sourceacademy.org/>
 
-# Requirements
+### Requirements
 
 - `bash`: known working version: GNU bash, version 5.0.16
 - `latexmk`: Version 4.52c
@@ -116,7 +108,7 @@ Source is documented here: <https://docs.sourceacademy.org/>
 
 To build the documentation, run
 
-```{.}
+```bash
 $ git clone https://github.com/source-academy/js-slang.git
 $ cd js-slang
 $ yarn
@@ -126,117 +118,84 @@ $ cd docs/specs
 $ make        # to make the PDF documents using LaTeX
 ```
 
-Note: The documentation may not build on Windows, depending on your bash setup,
-[see above](https://github.com/source-academy/js-slang#requirements).
+**Note:** The documentation may not build on Windows, depending on your bash setup, [see above](https://github.com/source-academy/js-slang#requirements).
 
-Documentation on the Source libraries are generated from inline documentation in
-the library sources, a copy of which are kept in `docs/lib/*.js`. The command
-`yarn jsdoc` generates the documentation and places it in the folder
-`docs/source`. You can test the documentation using a local server:
+Documentation on the Source libraries are generated from inline documentation in the library sources, a copy of which are kept in `docs/lib/*.js`. The command `yarn jsdoc` generates the documentation and places it in the folder `docs/source`. You can test the documentation using a local server:
 
-```{.}
+```bash
 $ cd docs/source;  python -m http.server 8000
 ```
 
-Documentation of libraries is displayed in autocomplete in the frontend. This
-documentation is generated by `./scripts/updateAutocompleteDocs.py` and placed
-in `src/editors/ace/docTooltip/*.json` files. This script is run by
-`yarn build`prior to`tsc`. To add a Source variant to the frontend autocomplete,
-edit `src/editors/ace/docTooltip/index.ts`
-and`./scripts/updateAutocompleteDocs.py`.
+Documentation of libraries is displayed in autocomplete in the frontend. This documentation is generated by `./scripts/updateAutocompleteDocs.py` and placed in `src/editors/ace/docTooltip/*.json` files. This script is run by `yarn build`prior to`tsc`. To add a Source variant to the frontend autocomplete, edit `src/editors/ace/docTooltip/index.ts` and`./scripts/updateAutocompleteDocs.py`.
 
-# Testing
+## Testing
 
-`js-slang` comes with an extensive test suite. To run the tests after you made
-your modifications, run `yarn test`. Regression tests are run automatically when
-you want to push changes to this repository. The regression tests are generated
-using `jest` and stored as snapshots in `src/\_\_tests\_\_`. After modifying
-`js-slang`, carefully inspect any failing regression tests reported in red in
-the command line. If you are convinced that the regression tests and not your
-changes are at fault, you can update the regression tests as follows:
+`js-slang` comes with an extensive test suite. To run the tests after you made your modifications, run `yarn test`. Regression tests are run automatically when you want to push changes to this repository. The regression tests are generated using `jest` and stored as snapshots in `src/\_\_tests\_\_`. After modifying `js-slang`, carefully inspect any failing regression tests reported in red in the command line. If you are convinced that the regression tests and not your changes are at fault, you can update the regression tests as follows:
 
-```{.}
+```bash
 $ yarn test -- --updateSnapshot
 ```
 
-# Error messages
+## Error messages
 
-To enable verbose messages, have the statement `"enable verbose";` as the first
-line of your program. This also causes the program to be run by the interpreter.
+To enable verbose messages, have the statement `"enable verbose";` as the first line of your program. This also causes the program to be run by the interpreter.
 
-There are two main kinds of error messages: those that occur at runtime and
-those that occur at parse time. The first can be found in
-`interpreter-errors.ts`, while the second can be found in `rules/`.
+There are two main kinds of error messages: those that occur at runtime and those that occur at parse time. The first can be found in `interpreter-errors.ts`, while the second can be found in `rules/`.
 
-Each error subclass will have `explain()` and `elaborate()`. Displaying the
-error will always cause the first to be called; the second is only called when
-verbose mode is enabled. As such, `explain()` should be made to return a string
-containing the most basic information about what the error entails. Any
-additional details about the error message, including specifics and correction
-guides, should be left to `elaborate()`.
+Each error subclass will have `explain()` and `elaborate()`. Displaying the error will always cause the first to be called; the second is only called when verbose mode is enabled. As such, `explain()` should be made to return a string containing the most basic information about what the error entails. Any additional details about the error message, including specifics and correction guides, should be left to `elaborate()`.
 
-Please remember to write test cases to reflect your added functionalities. The
-god of this repository is self-professed to be very particular about test cases.
+Please remember to write test cases to reflect your added functionalities. The god of this repository is self-professed to be very particular about test cases.
 
-# Using your js-slang in Source Academy
+## Using your js-slang in Source Academy
 
-js-slang is used by the [Source Academy](https://sourceacademy.org), the
-immersive online experiential environment for learning programming. For this,
-js-slang is
-[deployed as an NPM package](https://www.npmjs.com/package/js-slang). The
-frontend of the Source Academy then includes the js-slang package in its
-deployment bundle.
+js-slang is used by the [Source Academy](https://sourceacademy.org), the immersive online experiential environment for learning programming. For this, js-slang is [deployed as an NPM package](https://www.npmjs.com/package/js-slang). The frontend of the Source Academy then includes the js-slang package in its deployment bundle.
 
-# Using your js-slang in your local Source Academy
+## Using your js-slang in your local Source Academy
 
-A common issue when developing modifications to js-slang is how to test it using
-your own local frontend. Assume that you have built your own frontend locally,
-here is how you can make it use your own js-slang, instead of the one that the
-Source Academy team has deployed to npm.
+A common issue when developing modifications to js-slang is how to test it using your own local frontend. Assume that you have built your own frontend locally, here is how you can make it use your own js-slang, instead of the one that the Source Academy team has deployed to npm.
 
 First, build and link your local js-slang:
 
-```{.}
+```bash
 $ cd js-slang
 $ yarn build
 $ yarn link
 ```
 
 Then, from your local copy of frontend:
 
-```{.}
+```bash
 $ cd frontend
 $ yarn link "js-slang"
 ```
 
 Then start the frontend and the new js-slang will be used.
 
-# Building and publishing SICP package
+## Building and publishing SICP package
 
 To build SICP package
 
-```{.}
+```bash
 $ cd js-slang
 $ yarn
 $ yarn build_sicp_package
 ```
 
 To publish SICP package, update version number in `sicp_publish/package.json`
 
-```{.}
+```bash
 $ cd js-slang/sicp_publish
 $ npm publish
 ```
 
-# Talks and Presentations
+## Talks and Presentations
 
-- **How `js-slang` works under the hood** [17th Jan 2023][The
-  Gathering][[slides](https://docs.google.com/presentation/d/1GFR39iznBZxWv948zUsmcbCSSDasm4xYs3Jc5GF7A3I/edit?usp=sharing)]
+- **How `js-slang` works under the hood** (17th Jan 2023 – The Gathering) ([slides](https://docs.google.com/presentation/d/1GFR39iznBZxWv948zUsmcbCSSDasm4xYs3Jc5GF7A3I/edit?usp=sharing))
 
-# License
+## License
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-All sources in this repository are licensed under the
-[Apache License Version 2][apache2].
+
+All sources in this repository are licensed under the [Apache License Version 2][apache2].
 
 [apache2]: https://www.apache.org/licenses/LICENSE-2.0.txt

package.json

@@ -47,6 +47,9 @@
     "source-map": "0.7.3",
     "xmlhttprequest-ts": "^1.0.1"
   },
+  "resolutions": {
+    "**/gl": "^6.0.2"
+  },
   "scripts": {
     "build": "yarn docs && tsc --build --force",
     "build:slang": "tsc --build --force",

sicp_publish/package.json

@@ -20,11 +20,14 @@
     "acorn-loose": "^8.0.0",
     "acorn-walk": "^8.0.0",
     "astring": "^1.4.3",
-    "gpu.js": "^2.10.4",
+    "gpu.js": "^2.16.0",
     "lodash": "^4.17.20",
     "source-map": "^0.7.3",
     "xmlhttprequest-ts": "^1.0.1"
   },
+  "resolutions": {
+    "**/gl": "^6.0.2"
+  },
   "main": "dist/sicp",
   "types": "dist/sicp",
   "files": [