Phase 2: convert lib/, index.js and tests to native ES modules (#1530)

**Overview:** 189 files changed, +957 / −1162. Converts `lib/`, `index.js`, `bin/`, `rosocket/` and the full test suite to native ES modules; keeps build/codegen tooling as `.cjs`; updates CI to ROS 2 Lyrical (Ubuntu 26.04); and fixes a native-addon debug-build compile error.

### Core ESM conversion
- **`index.js`** — converted to ESM entrypoint (`import`/`export`), module wiring reworked.
- **`lib/**`** — all library modules converted from `require`/`module.exports` to `import`/`export` (node, client, service, publisher, subscription, action/*, clock*, parameter*, logging*, runtime/*, serialization, time*, timer, qos*, utils, validator, native_loader, etc.).
- **`bin/rclnodejs-web.js`**, **`rosocket/index.js`**, **`rosocket/cli.js`** — converted to ESM.

### ESM/CJS boundary fixes (from Copilot review)
- **`lib/native_loader.js`** — load the CommonJS `bindings` helper via `createRequire`'s `require('bindings')` instead of `import bindings from 'bindings'`, preserving CJS caller context for addon resolution.
- **`lib/type_description_service.js`** — corrected sibling import from `'../lib/parameter.js'` to `'./parameter.js'`.

### CommonJS files kept as `.cjs`
- **`rosidl_gen/*.cjs`** (deallocator, idl_generator, index, primitive_types, templates/message-template), **`rostsd_gen/index.cjs`**, **`scripts/ros_distro.cjs`**, **`scripts/run_test.cjs`** — build/codegen tooling stays CJS (loads ESM helpers via supported `require(esm)` / `.default`).
- **`third_party/ref-napi/`** — `lib/ref.js` and `package.json` tweaks for module resolution.

### Tooling / config
- **`package.json`** — `"type": "module"` and script adjustments.
- **`eslint.config.mjs`** — ESM lint rules.
- **`.c8rc.json`** added, **`.nycrc.yml`** removed — switch coverage from nyc to c8.

### CI
- **`.github/workflows/linux-x64-asan-test.yml`**, **`.github/workflows/linux-x64-build-and-test.yml`** — migrated from ROS 2 Jazzy to Lyrical (Ubuntu 26.04).
- **`.github/actions/setup-ros2-apt/action.yml`** (new) — composite action to install Lyrical from apt (setup-ros doesn't support it yet).

### Native addon fix
- **`src/macros.h`** — replaced removed internal rcutils macros (`RCUTILS_LOG_COND_NAMED` / `RCUTILS_LOG_CONDITION_EMPTY`) in `RCLNODEJS_DEBUG` with the stable public `RCUTILS_LOG_DEBUG_NAMED`, fixing the ASan debug-build compile failure under Lyrical.

### Tests
- All `test/test-*.js` converted to ESM; `tutorials/.../test_usability.js` renamed to `.cjs`; `test/utils.js` updated.

Fix: #1358

Author: minggangw

.c8rc.json

@@ -0,0 +1,6 @@
+{
+  "extension": [".js"],
+  "include": ["lib/**", "index.js"],
+  "reporter": ["lcov"],
+  "report-dir": "./coverage"
+}

.github/actions/setup-ros2-apt/action.yml

@@ -0,0 +1,46 @@
+name: 'Setup ROS2 apt repository'
+description: >-
+  Enable the official ros-apt-source repository (and common build deps) on
+  Ubuntu, and optionally install the Lyrical Luth desktop. Shared by the
+  build-and-test and ASan workflows so the lyrical/rolling apt setup lives in
+  one place.
+
+inputs:
+  install-desktop:
+    description: >-
+      When 'true' (default) install ros-lyrical-desktop. Set to 'false' to only
+      enable the apt repository and build deps (e.g. the rolling lane installs
+      ROS2 from a binary tarball after this action runs).
+    required: false
+    default: 'true'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Enable ROS2 apt repository
+      shell: bash
+      run: |
+        apt-get update
+        apt-get install -y sudo software-properties-common curl
+
+        # Enable required repositories. The same setup applies to both the
+        # rolling nightly tarball and the lyrical apt-deb install; see the
+        # per-distro install docs for reference:
+        #   rolling: https://docs.ros.org/en/rolling/Installation/Alternatives/Ubuntu-Install-Binary.html
+        #   lyrical: https://docs.ros.org/en/lyrical/Installation/Ubuntu-Install-Debs.html
+        add-apt-repository universe
+        ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
+        curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
+        dpkg -i /tmp/ros2-apt-source.deb
+        apt-get update
+        # Common build deps for both rolling and lyrical. Rolling-only tarball
+        # tooling (tar, bzip2, python3-rosdep) is installed by the caller so the
+        # lyrical lane stays minimal.
+        apt-get install -y build-essential cmake python3 python3-colcon-common-extensions
+
+    - name: Install ROS2 from apt (lyrical)
+      if: ${{ inputs.install-desktop == 'true' }}
+      shell: bash
+      run: |
+        # Per https://docs.ros.org/en/lyrical/Installation/Ubuntu-Install-Debs.html
+        apt-get install -y ros-lyrical-desktop

.github/workflows/linux-x64-asan-test.yml

@@ -17,28 +17,30 @@ jobs:
   asan:
     runs-on: ubuntu-latest
     container:
-      image: ubuntu:noble
+      # Lyrical Luth is the latest ROS2 LTS and targets Ubuntu 26.04.
+      image: ubuntu:26.04
     steps:
     - name: Setup Node.js 24.X
       uses: actions/setup-node@v6
       with:
         node-version: 24.X
         architecture: x64
 
-    - name: Setup ROS2 Jazzy
-      uses: ros-tooling/setup-ros@v0.7
-      with:
-        required-ros-distributions: jazzy
+    - uses: actions/checkout@v6
+
+    - name: Setup ROS2 Lyrical from apt
+      # ros-tooling/setup-ros does not support lyrical yet, so the shared
+      # composite action installs it from the official apt repo. See
+      # https://docs.ros.org/en/lyrical/Installation/Ubuntu-Install-Debs.html
+      uses: ./.github/actions/setup-ros2-apt
 
     - name: Install test dependencies
       run: |
-        sudo apt install -y ros-jazzy-test-msgs ros-jazzy-mrpt-msgs
-
-    - uses: actions/checkout@v6
+        sudo apt install -y ros-lyrical-test-msgs ros-lyrical-mrpt-msgs
 
     - name: Install npm dependencies
       run: |
-        source /opt/ros/jazzy/setup.bash
+        source /opt/ros/lyrical/setup.bash
         npm i
 
     # Wrap the asan test step in nick-fields/retry@v4 to absorb transient
@@ -52,5 +54,5 @@ jobs:
         retry_wait_seconds: 10
         timeout_minutes: 60
         command: |
-          source /opt/ros/jazzy/setup.bash
+          source /opt/ros/lyrical/setup.bash
           npm run test:asan

.github/workflows/linux-x64-build-and-test.yml

@@ -54,6 +54,10 @@ jobs:
         node-version: ${{ matrix.node-version }}
         architecture: ${{ matrix.architecture }}
 
+    # Checkout early so the local composite action under .github/actions is
+    # available to the rolling / lyrical apt setup step below.
+    - uses: actions/checkout@v6
+
     - name: Setup ROS2
       if: ${{ matrix.ros_distribution != 'rolling' && matrix.ros_distribution != 'lyrical' }}
       uses: ros-tooling/setup-ros@v0.7
@@ -62,30 +66,11 @@ jobs:
 
     - name: Enable ROS2 apt repository (rolling / lyrical)
       if: ${{ matrix.ros_distribution == 'rolling' || matrix.ros_distribution == 'lyrical' }}
-      run: |
-        apt-get update
-        apt-get install -y sudo software-properties-common curl
-
-        # Enable required repositories. The same setup applies to both the
-        # rolling nightly tarball and the lyrical apt-deb install; see the
-        # per-distro install docs for reference:
-        #   rolling: https://docs.ros.org/en/rolling/Installation/Alternatives/Ubuntu-Install-Binary.html
-        #   lyrical: https://docs.ros.org/en/lyrical/Installation/Ubuntu-Install-Debs.html
-        add-apt-repository universe
-        ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
-        curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
-        dpkg -i /tmp/ros2-apt-source.deb
-        apt-get update
-        # Common build deps for both rolling and lyrical. Rolling-only tarball
-        # tooling (tar, bzip2, python3-rosdep) is installed in the rolling step
-        # below so the lyrical lane stays minimal.
-        apt-get install -y build-essential cmake python3 python3-colcon-common-extensions
-
-    - name: Install ROS2 from apt (lyrical)
-      if: ${{ matrix.ros_distribution == 'lyrical' }}
-      run: |
-        # Per https://docs.ros.org/en/lyrical/Installation/Ubuntu-Install-Debs.html
-        apt-get install -y ros-lyrical-desktop
+      uses: ./.github/actions/setup-ros2-apt
+      with:
+        # Lyrical installs the desktop from apt here; rolling only needs the
+        # repository enabled and installs ROS2 from a tarball in the next step.
+        install-desktop: ${{ matrix.ros_distribution == 'lyrical' }}
 
     - name: Install ROS2 from binary tarball (rolling)
       if: ${{ matrix.ros_distribution == 'rolling' }}
@@ -121,8 +106,6 @@ jobs:
         fi
         sudo apt install -y xvfb libgtk-3-0 libnss3 $LIBASOUND_PKG libgbm-dev
 
-    - uses: actions/checkout@v6
-
     # The mocha suite and the Electron postinstall (extract-zip 2.0.1) are
     # known to be intermittently flaky on this runner. Wrap both test
     # invocations in nick-fields/retry@v4 so a single transient failure does
@@ -140,7 +123,15 @@ jobs:
           source /opt/ros/${{ matrix.ros_distribution }}/setup.bash
           npm i
           npm run lint
-          npm test
+          # c8 (coverage) depends on yargs 17, whose extensionless `yargs/yargs`
+          # entry fails to load under `require()` on Node 26. Coverage is only
+          # uploaded from the Node 24.X leg, so wrap with c8 there and run the
+          # plain suite everywhere else to keep the Node 26 lane green.
+          if [ "${{ matrix.node-version }}" = "24.X" ]; then
+            npm run test:coverage
+          else
+            npm test
+          fi
           npm run clean
 
     - name: Test with IDL ROS messages (rolling / lyrical)

.nycrc.yml

@@ -11,20 +11,20 @@
 //
 // For frontend developers who don't want to write a Node.js server.
 // Run `rclnodejs-web --help` or `npx rclnodejs-web web.json` to start
-// the runtime. See demo/web/javascript/README.md for the full demo.
+// the runtime.
 
-'use strict';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
-const path = require('node:path');
-const fs = require('node:fs');
-
-const {
+import {
   parseArgv,
   loadConfigFile,
   mergeConfig,
-  CliError,
   HELP,
-} = require('../lib/runtime/cli-config.js');
+} from '../lib/runtime/cli-config.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const argv = process.argv.slice(2);
 
@@ -55,14 +55,11 @@ const argv = process.argv.slice(2);
     fail(e);
   }
 
-  // Defer the rclnodejs require until after argv parsing so --help / --version
+  // Defer the rclnodejs import until after argv parsing so --help / --version
   // never pay the (slow, native) load cost.
-  const rclnodejs = require('../index.js');
-  const {
-    createRuntime,
-    WebSocketTransport,
-    HttpTransport,
-  } = require('../lib/runtime');
+  const rclnodejs = (await import('../index.js')).default;
+  const { createRuntime, WebSocketTransport, HttpTransport } =
+    await import('../lib/runtime/index.js');
 
   // Track partial init so the catch block can clean up native handles before
   // process.exit() — without this, a startup failure (e.g. EADDRINUSE on the

bin/rclnodejs-web.js

@@ -16,6 +16,10 @@ export default [
             "**/benchmark/",
             "**/docs/",
             "**/demo/electron/",
+            "**/coverage/",
+            "**/dist/",
+            "**/prebuilds/",
+            "**/build/",
         ],
     },
     {
@@ -46,6 +50,22 @@ export default [
             "@typescript-eslint/triple-slash-reference": "off",
         },
     },
+    {
+        plugins: {
+            prettier,
+        },
+        languageOptions: {
+            globals: {
+                ...globals.node,
+            },
+            ecmaVersion: "latest",
+            sourceType: "module",
+        },
+        files: ["lib/**/*.js", "test/**/*.js", "bin/**/*.js", "rosocket/**/*.js", "index.js"],
+        rules: {
+            ...eslintPluginPrettierRecommended.rules,
+        },
+    },
     {
         plugins: {
             prettier,
@@ -57,8 +77,8 @@ export default [
             ecmaVersion: "latest",
             sourceType: "commonjs",
         },
-        files: ["lib/**/*.js", "rosidl_parser/**/*.{js,cjs}", "rosidl_gen/**/*.{js,cjs}",
-            "rostsd_gen/**/*.{js,cjs}", "test/**/*.js", "example/**/*.js", "index.js"],
+        files: ["rosidl_parser/**/*.{js,cjs}", "rosidl_gen/**/*.{js,cjs}",
+            "rostsd_gen/**/*.{js,cjs}", "example/**/*.js"],
         rules: {
             ...eslintPluginPrettierRecommended.rules,
         },