tools: move update-acorn.sh to dep_updaters and create maintaining md

PR-URL: #47382
Refs: nodejs/security-wg#828
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

.github/workflows/tools.yml

@@ -95,22 +95,18 @@ jobs:
             subsystem: deps
             label: dependencies
             run: |
-              NEW_VERSION=$(npm view acorn dist-tags.latest)
-              CURRENT_VERSION=$(node -p "require('./deps/acorn/acorn/package.json').version")
-              if [ "$NEW_VERSION" != "$CURRENT_VERSION" ]; then
-                echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
-                ./tools/update-acorn.sh
-              fi
+              ./tools/dep_updaters/update-acorn.sh > temp-output
+              cat temp-output
+              tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
+              rm temp-output
           - id: acorn-walk
             subsystem: deps
             label: dependencies
             run: |
-              NEW_VERSION=$(npm view acorn-walk dist-tags.latest)
-              CURRENT_VERSION=$(node -p "require('./deps/acorn/acorn-walk/package.json').version")
-              if [ "$NEW_VERSION" != "$CURRENT_VERSION" ]; then
-                echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
-                ./tools/update-acorn-walk.sh
-              fi
+              ./tools/dep_updaters/update-acorn-walk.sh > temp-output
+              cat temp-output
+              tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
+              rm temp-output
           - id: libuv
             subsystem: deps
             label: dependencies

doc/contributing/maintaining-acorn.md

@@ -0,0 +1,47 @@
+# Maintaining acorn
+
+The [acorn](https://github.com/acornjs/acorn) dependency is a JavaScript parser.
+[acorn-walk](https://github.com/acornjs/acorn/tree/master/acorn-walk) is
+an abstract syntax tree walker for the ESTree format.
+
+## Updating acorn
+
+The `tools/dep_updaters/update-acorn.sh` script automates the update of the
+acorn source files.
+
+Check that Node.js still builds and tests.
+
+## Committing acorn
+
+1. Add acorn:
+   ```console
+   $ git add deps/acorn
+   ```
+2. Commit the changes: `git commit`.
+3. Add a message like:
+   ```text
+   deps: update acorn to <version>
+
+   Updated as described in doc/contributing/maintaining-acorn.md.
+   ```
+
+## Updating acorn-walk
+
+The `tools/dep_updaters/update-acorn-walk.sh` script automates the update of the
+acorn-walk source files.
+
+Check that Node.js still builds and tests.
+
+## Committing acorn-walk
+
+1. Add acorn-walk:
+   ```console
+   $ git add deps/acorn-walk
+   ```
+2. Commit the changes: `git commit`.
+3. Add a message like:
+   ```text
+   deps: update acorn-walk to <version>
+
+   Updated as described in doc/contributing/maintaining-acorn.md.
+   ```

tools/dep_updaters/update-acorn-walk.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+
+# Shell script to update acorn-walk in the source tree to the latest release.
+
+# This script must be in the tools directory when it runs because it uses the
+# script source file path to determine directories to work in.
+
+set -ex
+
+ROOT=$(cd "$(dirname "$0")/../.." && pwd)
+[ -z "$NODE" ] && NODE="$ROOT/out/Release/node"
+[ -x "$NODE" ] || NODE=$(command -v node)
+NPM="$ROOT/deps/npm/bin/npm-cli.js"
+
+NEW_VERSION=$("$NODE" "$NPM" view acorn-walk dist-tags.latest)
+CURRENT_VERSION=$("$NODE" -p "require('./deps/acorn/acorn-walk/package.json').version")
+
+echo "Comparing $NEW_VERSION with $CURRENT_VERSION"
+
+if [ "$NEW_VERSION" = "$CURRENT_VERSION" ]; then
+  echo "Skipped because Acorn-walk is on the latest version."
+  exit 0
+fi
+
+cd "$( dirname "$0" )/../.." || exit
+
+rm -rf deps/acorn/acorn-walk
+
+(
+    rm -rf acorn-walk-tmp
+    mkdir acorn-walk-tmp
+    cd acorn-walk-tmp || exit
+
+    "$NODE" "$NPM" init --yes
+
+    "$NODE" "$NPM" install --global-style --no-bin-links --ignore-scripts acorn-walk
+)
+
+mv acorn-walk-tmp/node_modules/acorn-walk deps/acorn
+
+rm -rf acorn-walk-tmp/
+
+echo "All done!"
+echo ""
+echo "Please git add acorn-walk, commit the new version:"
+echo ""
+echo "$ git add -A deps/acorn-walk"
+echo "$ git commit -m \"deps: update acorn-walk to $NEW_VERSION\""
+echo ""
+
+# The last line of the script should always print the new version,
+# as we need to add it to $GITHUB_ENV variable.
+echo "NEW_VERSION=$NEW_VERSION"

tools/update-acorn.sh → tools/dep_updaters/update-acorn.sh

@@ -7,35 +7,56 @@
 
 set -ex
 
-cd "$( dirname "$0" )/.." || exit
+ROOT=$(cd "$(dirname "$0")/../.." && pwd)
+[ -z "$NODE" ] && NODE="$ROOT/out/Release/node"
+[ -x "$NODE" ] || NODE=$(command -v node)
+NPM="$ROOT/deps/npm/bin/npm-cli.js"
+
+NEW_VERSION=$("$NODE" "$NPM" view acorn dist-tags.latest)
+CURRENT_VERSION=$("$NODE" -p "require('./deps/acorn/acorn/package.json').version")
+
+echo "Comparing $NEW_VERSION with $CURRENT_VERSION"
+
+if [ "$NEW_VERSION" = "$CURRENT_VERSION" ]; then
+  echo "Skipped because Acorn is on the latest version."
+  exit 0
+fi
+
+cd "$( dirname "$0" )/../.." || exit
+
 rm -rf deps/acorn/acorn
 
 (
     rm -rf acorn-tmp
     mkdir acorn-tmp
     cd acorn-tmp || exit
 
-    ROOT="$PWD/.."
-    [ -z "$NODE" ] && NODE="$ROOT/out/Release/node"
-    [ -x "$NODE" ] || NODE=$(command -v node)
-    NPM="$ROOT/deps/npm/bin/npm-cli.js"
-
     "$NODE" "$NPM" init --yes
 
     "$NODE" "$NPM" install --global-style --no-bin-links --ignore-scripts acorn
     cd node_modules/acorn
-    # get acorn version
-    ACORN_VERSION=$("$NODE" -p "require('./package.json').version")
     # update this version information in src/acorn_version.h
     FILE_PATH="$ROOT/src/acorn_version.h"
     echo "// This is an auto generated file, please do not edit." > "$FILE_PATH"
     echo "// Refer to tools/update-acorn.sh" >> "$FILE_PATH"
     echo "#ifndef SRC_ACORN_VERSION_H_" >> "$FILE_PATH"
     echo "#define SRC_ACORN_VERSION_H_" >> "$FILE_PATH"
-    echo "#define ACORN_VERSION \"$ACORN_VERSION\"" >> "$FILE_PATH"
+    echo "#define ACORN_VERSION \"$NEW_VERSION\"" >> "$FILE_PATH"
     echo "#endif  // SRC_ACORN_VERSION_H_" >> "$FILE_PATH"
 )
 
 mv acorn-tmp/node_modules/acorn deps/acorn
 
 rm -rf acorn-tmp/
+
+echo "All done!"
+echo ""
+echo "Please git add acorn, commit the new version:"
+echo ""
+echo "$ git add -A deps/acorn"
+echo "$ git commit -m \"deps: update acorn to $NEW_VERSION\""
+echo ""
+
+# The last line of the script should always print the new version,
+# as we need to add it to $GITHUB_ENV variable.
+echo "NEW_VERSION=$NEW_VERSION"