Address code review feedback

Author: andreiltd

.github/workflows/docs.yml

@@ -9,64 +9,49 @@ on:
 
 jobs:
   changes:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     outputs:
-      dirs: ${{ steps.filter.outputs.changes }}
+      docs-changed: ${{ steps.filter.outputs.docs == 'true' }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: dorny/paths-filter@v3
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 #v3.0.2
         id: filter
         with:
           filters: |
             docs: docs/**
 
   deploy:
     needs: [changes]
-    if: ${{ !contains(needs.changes.outputs.dirs, '[]') }}
-    runs-on: ubuntu-22.04
+    if: ${{ !contains(needs.changes.outputs.docs-changed, '[]') }}
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     concurrency:
       group: ${{ github.workflow }}-${{ github.ref }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: taiki-e/cache-cargo-install-action@4d586f211d9b0bca9e7b59e57e2a0febf36c0929 # v2.1.1
+        with:
+          tool: "mdbook@0.4.48"
+
+      - uses: taiki-e/cache-cargo-install-action@4d586f211d9b0bca9e7b59e57e2a0febf36c0929 # v2.1.1
+        with:
+          tool: "mdbook-alerts@0.7.0"
 
-      - name: Install latest mdbook
-        run: |
-          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook
-          curl -sSL $url | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
+      - uses: taiki-e/cache-cargo-install-action@4d586f211d9b0bca9e7b59e57e2a0febf36c0929 # v2.1.1
+        with:
+          tool: "mdbook-linkcheck@0.7.7"
 
       - name: Build mdbook
         working-directory: ./docs
         run: mdbook build
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4
-        if: ${{ github.ref == 'refs/heads/main' }}
+        # if: ${{ github.ref == 'refs/heads/main' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/book
           keep_files: true
-
-  link_check:
-    name: verify-doc-links
-    needs: [deploy]
-    if: ${{ github.ref == 'refs/heads/main' }}
-    permissions:
-      contents: read
-      issues: write
-    timeout-minutes: 15
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Link Checker
-        id: lychee
-        uses: lycheeverse/lychee-action@v2
-        with:
-          args: ./docs --exclude-all-private --verbose
-          fail: false

README.md

@@ -50,60 +50,60 @@ With sufficiently new versions of `cmake` and `rustup` installed, the build proc
 
 1. Clone the repo
 
-```bash
-$ git clone https://github.com/bytecodealliance/StarlingMonkey
-$ cd StarlingMonkey
+```console
+git clone https://github.com/bytecodealliance/StarlingMonkey
+cd StarlingMonkey
 ```
 
 2. Run the configuration script
 
 For a release configuration, run
 
-```bash
-$ cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
+```console
+cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
 ```
 
 For a debug configuration, run
 
-```bash
-$ cmake -S . -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug
+```console
+cmake -S . -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug
 ```
 
 3. Build the runtime
 
 Building the runtime is done in two phases: first, cmake is used to build a raw version as a
 WebAssembly core module. Then, that module is turned into a [WebAssembly Component][wasm-component]
-using the `componentize.sh` script.
+using the `componentize.sh` script generated by the build.
 
 The following command will build the `starling-raw.wasm` runtime module in the `cmake-build-release`
 directory:
 
-```bash
+```console
 # Use cmake-build-debug for the debug build
 # Change the value for `--parallel` to match the number of CPU cores in your system
-$ cmake --build cmake-build-release --parallel 8
+cmake --build cmake-build-release --parallel 8
 ```
 
 Then, the `starling-raw.wasm` module can be turned into a component with the following command:
 
-```bash
-$ cd cmake-build-release
-$ ./componentize.sh -o starling.wasm
+```console
+cd cmake-build-release
+./componentize.sh -o starling.wasm
 ```
 
 The resulting runtime can be used to load and evaluate JS code dynamically:
 
-```bash
-$ wasmtime -S http starling.wasm -e "console.log('hello world')"
+```console
+wasmtime -S http starling.wasm -e "console.log('hello world')"
 # or, to load a file:
-$ wasmtime -S http --dir . starling.wasm index.js
+wasmtime -S http --dir . starling.wasm index.js
 ```
 
 Alternatively, a JS file can be provided during componentization:
 
-```bash
-$ cd cmake-build-release
-$ ./componentize.sh index.js -o starling.wasm
+```console
+cd cmake-build-release
+./componentize.sh index.js -o starling.wasm
 ```
 
 This way, the JS file will be loaded during componentization, and the top-level code will be

docs/book.toml

@@ -6,9 +6,11 @@ src = "src"
 title = "StarlingMonkey Developer Documentation"
 description = "Documentation for StarlingMonkey"
 
-[preprocessor]
+[preprocessor.alerts]
+renderers = ["html", "linkcheck"]
 
-[output]
+[output.linkcheck]
+traverse-parent-directories = true
 
 [output.html]
 git-repository-url = "https://github.com/bytecodealliance/StarlingMonkey"
@@ -17,7 +19,7 @@ default-theme = "light"
 preferred-dark-theme = "navy"
 copy-fonts = true
 no-section-label = false
-curly-quotes = true
+smart-punctuation = true
 
 [output.html.fold]
 enable = true

docs/src/developer/builtins-cpp.md

@@ -56,9 +56,7 @@ convenience, here is a brief recap of the main rooting rules from the referenced
 The `builtin` API provided by StarlingMonkey is built on top of SpiderMonkey's
 [`jsapi`][spidermonkey-jsapi], Mozilla's C++ interface for embedding JavaScript. It simplifies the
 creation and management of native JavaScript classes and objects by abstracting common patterns and
-boilerplate code required by the underlying SpiderMonkey engine. This allows developers to
-efficiently implement native functionality while leveraging SpiderMonkey's robust JavaScript runtime
-environment.
+boilerplate code required by the underlying SpiderMonkey engine. 
 
 See also SpiderMonkey documentation on [Custom Objects][spidermonkey-objects].
 
@@ -297,16 +295,14 @@ void initialize_builtins(api::Engine *engine) {
 
 ## Providing a custom host API implementation
 
-The [host-apis][host-api] directory can contain implementations of the host API for different
+The `host-apis` directory can contain implementations of the host API for different
 versions of WASI—or in theory any other host interface. Those can be selected by setting the
 `HOST_API` environment variable to the name of one of the directories. Currently, only an
-implementation in terms of [wasi-0.2.0][wasi-api] is provided, and used by default.
+implementation in terms of `host-apis/wasi-0.2.0` is provided, and used by default.
 
 To provide a custom host API implementation, you can set `HOST_API` to the (absolute) path of a
 directory containing that implementation.
 
-[host-api]: ../../../../host-apis
-[wasi-api]: ../../../../host-apis/wasi-0.2.0
 [spidermonkey-rooting]:
   https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/blob/next/docs/GC%20Rooting%20Guide.md
 [spidermonkey-jsapi]:

docs/src/developer/builtins-rust.md

@@ -1,3 +1,3 @@
 # Devoloping Builtins in Rust
 
-[TODO]
+[TODO]: https://github.com/bytecodealliance/StarlingMonkey/pull/103

docs/src/developer/just.md

@@ -9,39 +9,37 @@ refer to the official [installation instructions][just-install] for your specifi
 Once installed, navigate to the project directory and run `just` commands as needed. For instance,
 the following commands will configure a default `cmake-build-debug` directory and build the project.
 
-```shell
-$ just build
+```console
+just build
 ```
 
 To load a JS script during componentization and serve its output using `Wasmtime`, run:
 
-```shell
-$ just serve <filename>.js
+```console
+just serve <filename>.js
 ```
 
 To build and run integration tests run:
 
-```shell
-$ just test
+```console
+just test
 ```
 
 To build and run Web Platform Tests run:
 
-```shell
-$ just wpt-setup # prepare WPT hosts
-$ just wpt-test # run all tests
-$ just wpt-test console/console-log-symbol.any.js # run specific test
+```console
+just wpt-setup # prepare WPT hosts
+just wpt-test # run all tests
+just wpt-test console/console-log-symbol.any.js # run specific test
 ```
 
 To view a complete list of available recipes, run:
 
-```shell
-$ just --list
-
+```console
+just --list
 ```
 
-> **Note**
->
+> [!NOTE]
 > By default, the CMake configuration step is skipped if the build directory already exists.
 > However, this can sometimes cause issues if the existing build directory was configured for a
 > different target. For instance:
@@ -53,7 +51,7 @@ $ just --list
 > To resolve this, you can force cmake to reconfigure the build directory by adding the
 > `reconfigure=true` parameter. For example:
 >
-> ```shell
+> ```console
 > just reconfigure=true wpt-build
 > ```
 
@@ -63,17 +61,17 @@ The default build mode is debug, which automatically configures the build direct
 `cmake-build-debug`. You can switch to a different build mode, such as release, by specifying the
 mode parameter. For example:
 
-```shell
-$ just mode=release build
+```console
+just mode=release build
 ```
 
 This command will set the build mode to release, and the build directory will automatically change
 to `cmake-build-release`.
 
 If you want to override the default build directory, you can use the `builddir` parameter.
 
-```shell
-$ just builddir=mybuilddir mode=release build
+```console
+just builddir=mybuilddir mode=release build
 ```
 
 This command configures CMake to use `mybuilddir` as the build directory and sets the build mode to
@@ -83,15 +81,15 @@ This command configures CMake to use `mybuilddir` as the build directory and set
 
 You can also start a Web Platform Tests (WPT) server with:
 
-```shell
-$ just wpt-server
+```console
+just wpt-server
 ```
 
 After starting the server, individual tests can be run by sending a request with the test name to
 the server instance. For example:
 
-```shell
-$ curl http://127.0.0.1:7676/console/console-log-symbol.any.js
+```console
+curl http://127.0.0.1:7676/console/console-log-symbol.any.js
 
 ```
 

docs/src/developer/spidermonkey.md

@@ -2,7 +2,7 @@
 
 StarlingMonkey uses SpiderMonkey as its underlying JS engine, and by default, downloads build
 artifacts from [a wrapper repository][wasi-embedding] around [our local SpiderMonkey
-tree][geck-dev]. That wrapper repository contains a SpiderMonkey commit-hash in a file, and its CI
+tree][gecko-dev]. That wrapper repository contains a SpiderMonkey commit-hash in a file, and its CI
 jobs build the artifacts that StarlingMonkey downloads during its build.
 
 This flow is optimized for ease of development of StarlingMonkey, and avoiding the need to build
@@ -13,38 +13,38 @@ make fixes or optimize performance.
 In order to do so, first clone the above two repositories, with `gecko-dev` (SpiderMonkey itself) as
 a subdirectory to `spidermonkey-wasi-embedding`:
 
-```shell
-$ git clone https://github.com/bytecodealliance/spidermonkey-wasi-embedding
-$ cd spidermonkey-wasi-embedding/
-$ git clone https://github.com/bytecodealliance/gecko-dev
+```console
+git clone https://github.com/bytecodealliance/spidermonkey-wasi-embedding
+cd spidermonkey-wasi-embedding/
+git clone https://github.com/bytecodealliance/gecko-dev
 ```
 
 and switch to the commit that we are currently using:
 
-```shell
-$ git checkout `cat ../gecko-revision`
+```console
+git checkout `cat ../gecko-revision`
 # now edit the source
 ```
 
 Then make changes as necessary, eventually rebuilding from the `spidermonkey-wasi-embedding` root:
 
-```shell
+```console
 cd ../ # back to spidermonkey-wasi-embedding
-$ ./rebuild.sh release
+./rebuild.sh release
 ```
 
 This will produce a `release/` directory with artifacts of the same form normally downloaded by
 StarlingMonkey. So, finally, from within StarlingMonkey, set an environment variable
 `SPIDERMONKEY_BINARIES`:
 
-```shell
-$ export SPIDERMONKEY_BINARIES=/path/to/spidermonkey-wasi-embedding/release
-$ cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
-$ cmake --build cmake-build-release --parallel 8
+```console
+export SPIDERMONKEY_BINARIES=/path/to/spidermonkey-wasi-embedding/release
+cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
+cmake --build cmake-build-release --parallel 8
 ```
 
 and use/test as described in [testing][testing] section.
 
-[testing]: ../getting/started/tesing.md
+[testing]: ../getting-started/testing.md
 [wasi-embedding]: https://github.com/bytecodealliance/spidermonkey-wasi-embedding
-[geck-dev]: https://github.com/bytecodealliance/gecko-dev
+[gecko-dev]: https://github.com/bytecodealliance/gecko-dev