Migrate to NodeJS 16 LTS

.drone.yml

@@ -7,21 +7,23 @@ platform:
 
 steps:
     - name: build_test
-      image: node:12
+      image: node:16.14.0
       environment:
           CODECOV_TOKEN:
               from_secret: CODECOV_TOKEN
           SOL_AST_COMPILER_CACHE: /.compiler_cache
       commands:
-          # pre-download compilers
+          # pre-download compilers from historical builds archive
+          # see https://github.com/ethereum/solc-bin
+          # see https://binaries.soliditylang.org/
           - apt-get -qq update && apt-get -qq install jq
-          - ./docker/download.sh 'linux-amd64'
-          - ./docker/download.sh 'bin'
+          - ./docker/download.sh 'linux-amd64' $SOL_AST_COMPILER_CACHE
+          - ./docker/download.sh 'wasm' $SOL_AST_COMPILER_CACHE
           # remove list and one rarely used compiler to still test downloading on-demand
-          - rm /.compiler_cache/linux-amd64/list.json
-          - rm /.compiler_cache/linux-amd64/solc-linux-amd64-v0.5.17+commit.d19bba13
-          - rm /.compiler_cache/bin/list.json
-          - rm /.compiler_cache/bin/soljson-v0.5.17+commit.d19bba13.js
+          - rm $SOL_AST_COMPILER_CACHE/linux-amd64/list.json
+          - rm $SOL_AST_COMPILER_CACHE/linux-amd64/solc-linux-amd64-v0.5.17+commit.d19bba13
+          - rm $SOL_AST_COMPILER_CACHE/wasm/list.json
+          - rm $SOL_AST_COMPILER_CACHE/wasm/soljson-v0.5.17+commit.d19bba13.js
           # perform testing
           - npm install --unsafe-perm
           - npm link --unsafe-perm

README.md

@@ -11,7 +11,7 @@ A TypeScript package providing a normalized typed Solidity AST along with the ut
 
 ## Features
 
--   Various [solc-js](https://www.npmjs.com/package/solc) compiler versions support, starting from **0.4.13**.
+-   Various [Solidity](https://github.com/ethereum/solidity) compiler versions support, starting from **0.4.13**.
 -   Various compiler selection strategies, including compiler auto-detection via `pragma solidity` directives in Solidity sources with possible fallback options.
 -   Interaction with AST nodes, using type definitions.
 -   Compensation of differences between legacy and compact Solidity AST.
@@ -68,16 +68,34 @@ console.log(result);
 
 The second argument with the `"auto"` value specifies a compiler selection strategy. If `"auto"` is specified and source code contains valid `pragma solidity` directive, then compiler version will be automatically picked from it. If compile process will not succedd, the execution will fall back to _"compiler guessing"_: trying to compile source with a few different versions of the new and old Solidity compilers. The other option would be to specify a concrete supported compiler version string, like `"0.7.0"` for example. There is also a support for various compiler selection strategies, including used-defined custom ones (`CompilerVersionSelectionStrategy` interface implementations).
 
-**NOTE:** We want to notify that **the package preinstalls 50+ versions of Solc compilers** (since 0.4.13), so be ready that it will occupy fair amount of free space. At some point we may consider to move compilers away from this package. It will mostly depend on users feedback.
+### Used compilers
 
-### Native compilers
+Package supports switching between native binary Solc compilers and its WASM versions. The CLI option `--compiler-kind` and `kind` argument of `compile*()` functions family may be used for that purpose. Compilers **are downloaded on-demand** to the directory `.compiler_cache` at the package installation directory (by default). The compiler cache location may be customized by setting `SOL_AST_COMPILER_CACHE` environment variable to a custom path. For example:
 
-Package supports switching between native binary Solc compilers and its WASM versions. The CLI option `--compiler-kind` and `kind` argument of `compile*()` functions family may be used for that purpose. Native binary compilers are downloaded on demand to the directory `.compiler_cache` at the package installation directory (by default). The compiler cache location may be customized by setting `SOL_AST_COMPILER_CACHE` environment variable to a custom path. For example:
+```bash
+SOL_AST_COMPILER_CACHE=~/.compiler_cache sol-ast-compile sample.sol --compiler-kind native --tree
+```
+
+or
 
 ```bash
-SOL_AST_COMPILER_CACHE=~/.compiler_cache solc-ast-compile sample.sol --compiler-kind native --tree
+export SOL_AST_COMPILER_CACHE=~/.compiler_cache
+
+sol-ast-compile sample.sol --compiler-kind native --tree
 ```
 
+#### Invalidation of downloaded compler cache
+
+If there is a need to invalidate the downloaded compiler cache, then follow next steps:
+
+1. Locate `.compiler_cache` directory:
+
+```bash
+sol-ast-compile --locate-compiler-cache
+```
+
+2. Manually remove `list.json` files to invalidate list of available compilers, remove certain compilers, or remove entire directory. Missing pieces will be downloaded again.
+
 ### Typed universal AST
 
 After the source is compiled and original compiler has provided the raw AST, the `ASTReader` could be used to read the typed universal AST:
@@ -138,7 +156,7 @@ Use `--help` to see all available features.
 The project have following directory structure:
 
 ```
-├── .compiler_cache             # Cache of downloaded native compilers.
+├── .compiler_cache             # Cache of downloaded compilers (by default, if not configured by SOL_AST_COMPILER_CACHE).
 ├── coverage                    # Test coverage report, produced by "npm test" command.
 ├── dist                        # Generated JavaScript sources for package distribution (produced by "npm run build" and published by "npm publish" commands).
 ├── docs                        # Project documentation and API reference, produced by "npm run docs:render" or "npm run docs:refresh" commands.
@@ -174,24 +192,30 @@ A key points for better understanding:
 
 ## Development installation
 
-Install prerequisites:
+### Prerequisites
 
--   NodeJS version **12.x** or newer.
--   NPM version **6.9.0** or newer.
+We suggest to use latest NodeJS LTS release `lts/gallium` (v16.14.0) and associated version of NPM. If there is a need to run different NodeJS versions, consider using [NVM](https://github.com/nvm-sh/nvm) or similar tool, that is available for your platform.
 
-Clone repository:
+### Clone and build
+
+Clone repository, install and link:
 
 ```bash
 git clone https://github.com/ConsenSys/solc-typed-ast.git
+cd solc-typed-ast/
+npm install
+npm link
 ```
 
-Install and link:
+Prior to running tests the compiler pre-downloading script `docker/download.sh` may be used to setup local compiler cache:
 
 ```bash
-npm install
-npm link
+docker/download.sh 'linux-amd64' '.compiler_cache'  # platform-dependent native compiler builds
+docker/download.sh 'wasm' '.compiler_cache'         # cross-platform WASM compiler builds
 ```
 
+Supported platforms are listed here: https://github.com/ethereum/solc-bin
+
 ## Project documentation and API reference
 
 The project documentation is contained in the `docs/` directory. It could be built via following command:

docker/Dockerfile

@@ -1,13 +1,13 @@
-FROM node:12.22.9 as build
+FROM node:16.14.0 as build
 
 RUN apt-get update && \
     apt-get install jq -y
 
 COPY download.sh /download.sh
 
-RUN ./download.sh 'linux-amd64'
-RUN ./download.sh 'bin'
+RUN ./download.sh 'linux-amd64' /.compiler_cache
+RUN ./download.sh 'bin' /.compiler_cache
 
-FROM node:12.22.9
+FROM node:16.14.0
 COPY --from=build /.compiler_cache /.compiler_cache
 ENV SOL_AST_COMPILER_CACHE=/.compiler_cache

docker/download.sh

@@ -1,7 +1,28 @@
 #!/bin/bash
 
+if [[ $# -ne 2 ]] ; then 
+    echo "The $0 utility requires two input arguments:"
+    echo "- Arch for compilers to download. See https://github.com/ethereum/solc-bin for available archs."
+    echo "- Target directory to store the downloaded compilers."
+    echo ""
+    echo "Note that to use custom compiler cache path, the env variable SOL_AST_COMPILER_CACHE should be set."
+    echo "See README.md for the details."
+    echo ""
+    echo "Example:"
+    echo ""
+    echo "$0 'wasm' path/to/compiler/cache"
+    echo "export SOL_AST_COMPILER_CACHE=path/to/compiler/cache"
+    echo "sol-ast-compile --locate-compiler-cache"
+
+    exit 1;
+fi
+
 ARCH="${1}"
-TARGET_DIR="/.compiler_cache/$ARCH"
+CACHE_DIR="${2}"
+TARGET_DIR="$CACHE_DIR/$ARCH"
+
+echo "Pre-downloading compilers to $TARGET_DIR"
+
 mkdir -p $TARGET_DIR
 
 curl -s https://binaries.soliditylang.org/$ARCH/list.json --output $TARGET_DIR/list.json