[get-nodejs-versions-array-action] New Feature

[sounisi5011]

I would like to add the following new feature to get-nodejs-versions-array-action.

jobs:
  detect-supported-node:
    runs-on: ubuntu-latest
    outputs:
      versions-json: ${{ steps.detector.outputs.versions-json }}
      versions-matrix-json: ${{ steps.detector.outputs.versions-matrix-json }} # new output
    steps:
      # Checkout is optional
      # If "package.json" files and ".git" directories are not detected, use the GitHub API to fetch the "package.json" files
      # Users can choose to use the "actions/checkout" action if they wish to avoid using the GitHub API
      #- name: Checkout
      #  uses: actions/checkout@v3
      - id: detector
        uses: sounisi5011/npm-packages@actions/get-nodejs-versions-array-v0
        with:
          include-versions: |
            # Specify versions to be added to the output
            12.17.0
            12.20.0
            14.1.0
            14.13.0
            14.18.0
            # Versions not in the range of the "engines.node" field need to be excluded
            8.0.1

            # Comments can be used here
            All non-version strings are ignored
            14.18.0 // The string after the version is also ignored
            18.0.0<!-- Users can use comments in the format of the language they are familiar with -->

          exclude-versions: |
            # Specify versions to exclude from output
            14.0.0

          # If using the versions-matrix-json output, this option allows the user to change the variable name
          # Default: node-version
          matrix-variable-name: node-version

          additional-matrix-variables-yaml: |
            # This option specifies YAML for which if statements can be used

            # Fields written here will be added to each matrix
            detect-supported-node: true

            # Using if statements, users can define variables to be added only if the Node.js version satisfies the semver range
            if node-version satisfies <14.14.0
              corepack-version-range: <0.11

            # Of course, NOT conditions can also be used
            if node-version not satisfies *
              never-add: this
  unit-test:
    needs: detect-supported-node
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJson(needs.detect-supported-node.outputs.versions-matrix-json) }}
    steps:
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

[sounisi5011]

Some features could be substituted with GitHub Actions jobs.<job_id>.strategy.matrix.include and jobs.<job_id>.strategy.matrix.exclude.

jobs:
  detect-supported-node:
    runs-on: ubuntu-latest
    outputs:
      versions-json: ${{ steps.detector.outputs.versions-json }}
    steps:
      - id: detector
        uses: sounisi5011/npm-packages@actions/get-nodejs-versions-array-v0
  unit-test:
    needs: detect-supported-node
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: ${{ fromJson(needs.detect-supported-node.outputs.versions-json) }}
        include:
          - node-version: 12.17.0
          - node-version: 12.20.0
          - node-version: 14.1.0
          - node-version: 14.13.0
          - node-version: 14.18.0
          - node-version: 18.0.0
          - detect-supported-node: true
        exclude:
          - node-version: 14.0.0
    steps:
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

This feature is attractive because it allows users to consolidate definitions in one place, but at the expense of increasing our maintenance costs.

[sounisi5011]

Yes. However, any matrix added using jobs.<job_id>.strategy.matrix.include will be added last.

Also, versions not included in the range of the engines.node field are not automatically excluded.

[sounisi5011]

The parser for the additional-matrix-variables-yaml option is complex. Perhaps we need to rewrite the YAML parser.

Also, the definition of the node-version satisfies <14.14.0 condition is unclear. node-version is the semver range. 14.x satisfies <14.14.0 is true or false?
We mean 14.x to be the latest version of Node.js 14. Since Node.js 14.21.3 has already been released, this condition should now be false.
However, get-nodejs-versions-array-action does not know that Node.js 14.21.3 has already been released.

Instead, it is better to use a custom action that sets the output based on a semver range. For example:

jobs:
  detect-supported-node:
    runs-on: ubuntu-latest
    outputs:
      versions-json: ${{ steps.detector.outputs.versions-json }}
    steps:
      - id: detector
        uses: sounisi5011/npm-packages@actions/get-nodejs-versions-array-v0
  unit-test:
    needs: detect-supported-node
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: ${{ fromJson(needs.detect-supported-node.outputs.versions-json) }}
    steps:
      - name: Setup Node.js ${{ matrix.node-version }}
        id: setup-node
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - uses: madhead/semver-utils@latest
        id: use-old-corepack
        with:
          # Instead of using "matrix.node-version", use the "node-version" output of the "actions/setup-node".
          # Because the value of "matrix.node-version" is not a version. It is a semver range.
          version: ${{ steps.setup-node.outputs.node-version }}
          satisfies: <14.14.0

      - name: Use old Corepack
        if: steps.use-old-corepack.outputs.satisfies
        run: npm install --global "corepack@<0.11"

[sounisi5011]

This works! But the conditional expression needs to be rewritten like this:

- name: Use old Corepack
  if: steps.use-old-corepack.outputs.satisfies && steps.use-old-corepack.outputs.satisfies != 'false'
  run: npm install --global "corepack@<0.11"

see #682

[sounisi5011]

I think the working-directory option is also needed.
This already exists in GitHub Actions, but it only works with jobs.<job_id>.steps[*].run.

jobs:
  detect-supported-node:
    runs-on: ubuntu-latest
    outputs:
      versions-json: ${{ steps.detector.outputs.versions-json }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          path: path/to
      - id: detector
        uses: sounisi5011/npm-packages@actions/get-nodejs-versions-array-v0
        with:
          working-directory: path/to