nodejs.yml

# docs: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

name: Node CI

on:
  push:
    branches: [ main ]
    tags: [ "v*" ]  # have tools scan this stable version
  pull_request:
  workflow_dispatch:
  schedule:
    # schedule daily tests, since dependencies are not intended to be locked
    # this means: at 23:42 every day
    - cron: '42 23 * * *'

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions: {}

env:
  NODE_ACTIVE_LTS: "24" # see https://nodejs.org/en/about/releases/
  REPORTS_DIR: "CI_reports"
  TESTS_REPORTS_ARTIFACT: tests-reports
  STANDARD_REPORTS_ARTIFACT: cs-reports
  CJL_TEST_UPDATE_SNAPSHOTS: '' # set to a string that nodeJS would not evaluate to TRUE - which can only be an empty string

jobs:
  build:
    name: "build: ${{ matrix.target }}"
    runs-on: "ubuntu-latest"
    strategy:
      fail-fast: false
      matrix:
        target:
          - node
          - web
          - d
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: setup project
        run: npm install --ignore-scripts --include=optional --loglevel=silly
      - name: build ${{ matrix.target }}
        run: npm run build:${{ matrix.target }}
      - name: artifact build result
        # see https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: dist.${{ matrix.target }}
          path: dist.${{ matrix.target }}
          if-no-files-found: error

  test-lint:
    name: test lint
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: setup project
        run: npm install --ignore-scripts --include=optional --loglevel=silly
      - name: test
        run: npm run test:lint

  test-standard:
    needs: [ 'build' ]
    name: test standard
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: fetch build artifact
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.d
          path: dist.d
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: update npm
        run: npm install -g npm@latest # zizmor: ignore[adhoc-packages] -- global npm
      - name: setup project
        run: |
          npm install --ignore-scripts --loglevel=silly
      - name: setup tools
        run: |
          echo "::group::install docs-gen deps"
          npm run -- dev-setup:tools:docs-gen   --ignore-scripts --loglevel=silly
          echo "::endgroup::"
          echo "::group::install code-style deps"
          npm run -- dev-setup:tools:code-style --ignore-scripts --loglevel=silly
          echo "::endgroup::"
      - name: make reports dir
        run: mkdir -p "$REPORTS_DIR"
      - name: test
        run: >
          npm run -- test:standard
          --format json
          --output-file "$PWD/$REPORTS_DIR/eslint.json"
      - name: Annotate Code
        if: ${{ failure() || success() }}
        # see https://github.com/DerLev/eslint-annotations
        uses: DerLev/eslint-annotations@a79ea65c1b45a649c48bcc6efc0103b6fd2e4c5f # v2.1.0
        with:
          eslint-report: ${{ env.REPORTS_DIR }}/eslint.json
      - name: artifact eslint result
        # see https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        if: ${{ failure() }}
        with:
          name: ${{ env.STANDARD_REPORTS_ARTIFACT }}
          path: ${{ env.REPORTS_DIR }}
          if-no-files-found: error

  test-dependencies:
    name: test dependencies
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: update npm
        run: npm install -g npm@latest  # zizmor: ignore[adhoc-packages] -- global npm
      - name: setup project
        run: npm install --ignore-scripts --loglevel=silly
      - name: setup tool
        run: npm run -- dev-setup:tools:test-dependencies --ignore-scripts --loglevel=silly
      - name: test
        run: npm run -- test:dependencies -d

  test-node:
    needs: [ 'build' ]
    name: >
      test node
      ${{ matrix.node-version }}
      ${{ matrix.os }}
      ${{ (matrix.experimental == true) && '[experimental]' || '' }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        node-version:
          # action based on https://github.com/actions/node-versions/releases
          # see also: https://nodejs.org/en/about/releases/
          - "26"      # current
          - "24"      # active LTS
          - "22"
          - "20"
          - "20.18.0" # lowest supported
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
        #include:
        #  - node-version: "27"
        #    experimental: true
    continue-on-error: ${{ matrix.experimental == true }}
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ matrix.node-version }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ matrix.node-version }}
          package-manager-cache: false
          # do not use caching, use fresh version always, since some deps are not pinned -- since this is a library.
      - name: bump npm
        shell: bash
        env:
          NODE_VERSION: '${{ matrix.node-version }}'
        run: |  # zizmor: ignore[adhoc-packages] # no lock modifications wanted - the respective components are locked already
          case "$NODE_VERSION" in
          '26' )
            npm install --loglevel=silly -g npm@latest
            ;;
          '24' )
            npm install --loglevel=silly -g npm@^11
            ;;
          '22' )
            ;;
          '20' | '20.18.0')
            npm install --loglevel=silly -g npm@^10
            ;;
          esac
      - name: setup project
        shell: bash
        env:
          NODE_VERSION: '${{ matrix.node-version }}'
        run: |
          set -ex
          echo "::group::install project"
          npm install --ignore-scripts --include=optional --include=dev --loglevel=silly
          echo "::endgroup::"
          ## rebuild deps for which scripts were ignored, or partially installed - since "ignore-scripts" was used
          echo "::group::rebuild libxmljs2"
          npm rebuild --loglevel=silly libxmljs2 || npm uninstall --no-save libxmljs2 || true
          echo "::endgroup::"
      - name: fetch build artifact
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.node
          path: dist.node
      - name: test
        run: npm run -- test:node
      - name: collect coverage
        if: ${{ failure() || success() }}
        run: >
          node -- node_modules/c8/bin/c8.js
          report
          --reporter clover
          --reports-dir '${{ env.REPORTS_DIR }}/coverage/${{ matrix.os }}_node${{ matrix.node-version }}'
      - name: artifact test reports
        if: ${{ ! cancelled() }}
        # see https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: '${{ env.TESTS_REPORTS_ARTIFACT }}_regular_${{ matrix.os }}_node${{ matrix.node-version }}'
          path: ${{ env.REPORTS_DIR }}
    # test-web:
    # TODO via https://github.com/CycloneDX/cyclonedx-javascript-library/issues/51

  # TODO: west-web

  test-omit-optional-deps:
    needs: [ 'build' ]
    name: test w/o optional dependencies
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: setup library
        run: |  # zizmor: ignore[adhoc-packages] # no lock modifications wanted - the respective components are locked already
          set -ex
          dev_constraints=' npm-run-all2 c8 mocha fast-glob memfs rimraf '
          echo "::group::install prod"
          npm install --ignore-scripts --omit=optional --omit=dev --loglevel=silly
          echo "::endgroup::"
          echo "::group::install dev"
          ## install the needed dev-deps
          npm install --ignore-scripts --omit=optional --no-save --loglevel=silly $dev_constraints
          echo "::endgroup::"
      - name: fetch build artifact
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.node
          path: dist.node
      - name: test
        run: npm run test:node
      - name: collect coverage
        if: ${{ failure() || success() }}
        run: >
          npm exec -- c8 report
          --reporter clover
          --reports-dir '${{ env.REPORTS_DIR }}/coverage/no-optional-deps'
      - name: artifact test reports
        if: ${{ ! cancelled() }}
        # see https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: '${{ env.TESTS_REPORTS_ARTIFACT }}_no-opt_${{ matrix.os }}_node${{ matrix.node-version }}'
          path: ${{ env.REPORTS_DIR }}

  report-coverage:
    name: Publish test coverage
    needs:
      - test-node
      - test-omit-optional-deps
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: fetch test artifacts
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: '${{ env.TESTS_REPORTS_ARTIFACT }}_*'
          merge-multiple: true
          path: ${{ env.REPORTS_DIR }}
      - name: Run codacy-coverage-reporter
        env:
          CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
        ## see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-using-secrets
        if: ${{ env.CODACY_PROJECT_TOKEN != '' }}
        # see https://github.com/codacy/codacy-coverage-reporter-action
        uses: codacy/codacy-coverage-reporter-action@89d6c85cfafaec52c72b6c5e8b2878d33104c699 # v1.3.0
        with:
          project-token: ${{ env.CODACY_PROJECT_TOKEN }}
          coverage-reports: ${{ env.REPORTS_DIR }}/coverage/*/*

  examples-JS:
    needs: [ 'build' ]
    name: example JS ${{ matrix.js-type }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        js-type: [ 'cjs', 'mjs' ]
    env:
      EXAMPLE_DIR: examples/node/javascript
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: fetch build artifact 'node'
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.node
          path: dist.node
      - name: setup library
        run: |
          set -ex
          echo "::group::install"
          npm install --ignore-scripts --omit=dev --include=optional --loglevel=silly
          echo "::endgroup::"
          echo "::group::setup libxml2"
          ## rebuild deps for which scripts were ignored, or partially installed - since "ignore-scripts" was used
          npm rebuild --loglevel=silly libxmljs2 || npm uninstall --no-save libxmljs2
          echo "::endgroup::"
      - name: setup example project
        run: npm install --no-save --loglevel=silly
        working-directory: ${{ env.EXAMPLE_DIR }}
      - name: run example
        run: node -- 'example.${{ matrix.js-type }}'
        working-directory: ${{ env.EXAMPLE_DIR }}

  example-TS:
    needs: [ 'build' ]
    name: example TS${{ matrix.typescript-version }} ${{ matrix.js-type }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        typescript-version:
          - '^5'      # latest 5.X
          - '^4'      # latest 4.X
        js-type: [ 'cjs', 'mjs' ]
        include:
          - # lowest reasonable number that works
            typescript-version: '^4.0'
            nodeTypes-version: '^20'
            js-type: 'cjs'
    env:
      EXAMPLE_DIR: examples/node/typescript/example.${{ matrix.js-type }}
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: fetch build artifact 'd'
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.d
          path: dist.d
      - name: fetch build artifact 'node'
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.node
          path: dist.node
      - name: setup library
        run: |
          set -ex
          echo "::group::install"
          npm install --ignore-scripts --omit=dev --include=optional --loglevel=silly
          echo "::endgroup::"
          echo "::group::setup libxml2"
          ## rebuild deps for which scripts were ignored, or partially installed - since "ignore-scripts" was used
          npm rebuild --loglevel=silly libxmljs2 || npm uninstall --no-save libxmljs2
          echo "::endgroup::"
      - name: setup example project
        run: >-  # zizmor: ignore[adhoc-packages] # no lock modifications wanted - the respective components are locked already
          npm install
          --no-save
          --loglevel=silly
          'typescript@${{ matrix.typescript-version }}'
        working-directory: ${{ env.EXAMPLE_DIR }}
      - name: get TS-version
        id: ts_version
        run: node -p '`v=ts${require("typescript").version.split(".",2).join(".")}`' >> "$GITHUB_OUTPUT"
        working-directory: ${{ env.EXAMPLE_DIR }}
      - name: adjust @types/node version
        env:
          NODETYPES_VERSION: '${{ matrix.nodeTypes-version || steps.ts_version.outputs.v}}'
        run: >-  # zizmor: ignore[adhoc-packages] # no lock modifications wanted - the respective components are locked already
          npm install
          --no-save
          --loglevel=silly
          "@types/node@${NODETYPES_VERSION}"
        working-directory: ${{ env.EXAMPLE_DIR }}
      - name: build example
        run: npm run build
        working-directory: ${{ env.EXAMPLE_DIR }}
      - name: run example
        run: npm run example
        working-directory: ${{ env.EXAMPLE_DIR }}

  examples-Web:
    needs: [ 'build' ]
    name: example Web ${{ matrix.packer }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        packer:
          - parcel
          - webpack
    env:
      EXAMPLE_DIR: examples/web/${{ matrix.packer }}
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: fetch build artifact 'node'
        # see https://github.com/actions/download-artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: dist.web
          path: dist.web
      - name: setup library
        run: npm install --ignore-scripts --omit=dev --include=optional --loglevel=silly
      - name: setup example project
        run: npm install --no-save --loglevel=silly
        working-directory: ${{ env.EXAMPLE_DIR }}
      - name: build example
        run: npm run build
        working-directory: ${{ env.EXAMPLE_DIR }}

  api-doc:
    name: "api-doc: ${{ matrix.target }}"
    runs-on: "ubuntu-latest"
    strategy:
      fail-fast: false
      matrix:
        target:
          - node
          - web
    timeout-minutes: 10
    steps:
      - name: Checkout
        # see https://github.com/actions/checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #  v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
        # see https://github.com/actions/setup-node
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: ${{ env.NODE_ACTIVE_LTS }}
          package-manager-cache: false
      - name: update npm
        run: npm install -g npm@latest  # zizmor: ignore[adhoc-packages] -- global npm
      - name: setup project
        run: |
          set -ex
          echo "::group::install project"
          npm install --ignore-scripts --loglevel=silly
          echo "::endgroup::"
          echo "::group::install docs-gen deps"
          npm run -- dev-setup:tools:docs-gen --ignore-scripts --loglevel=silly
          echo "::endgroup::"
      - name: api-doc ${{ matrix.target }}
        run: npm run api-doc:${{ matrix.target }}