continuous-integration.yml

# Workflow to performs continuous integration steps against a Node.js project:
#
# - CodeQL analysis
# - Linting
# - Build
# - Test

name: Node.js Continuous Integration

on:
  workflow_call:
    inputs:
      runs-on:
        description: |
          JSON array of runner(s) to use.
          See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
        type: string
        default: '["ubuntu-latest"]'
        required: false
      build:
        description: |
          Build parameters. Must be a string or a JSON object.
          For string, provide a list of commands to run during the build step, one per line.
          For JSON object, provide the following properties:

          - `commands`: Array of commands to run during the build step.
          - `env`: Object of environment variables to set during the build step.
          - `artifact`: String or array of strings specifying paths to artifacts to upload after the build

          Example:
          ```json
          {
            "commands": [
              "build",
              "generate-artifacts"
            ],
            "env": {
              "CUSTOM_ENV_VAR": "value"
            },
            "artifact": [
              "dist/",
              "packages/package-a/build/"
            ]
          }
          ```
        type: string
        required: false
        default: "build"
      checks:
        description: "Optional flag to enable check steps."
        type: boolean
        required: false
        default: true
      lint:
        description: |
          Whether to enable linting.
          Set to `null` or empty to disable.
          Accepts a JSON object for lint options. See [lint action](../../actions/lint/README.md).
          It should generate lint reports in standard formats.

          Example:

          ```json:package.json
          {
            "lint:ci": "eslint . --output-file eslint-report.json --format json"
          }
          ```
        type: string
        required: false
        default: "true"
      code-ql:
        description: |
          CodeQL analysis language, or a JSON object with `languages` and optional `config-file`.
          Set to an empty string to disable CodeQL.
          In JSON form, `languages` must be a nonempty string and `config-file` must be a string.
          Omitting or leaving `config-file` empty keeps CodeQL's default configuration behavior.
          Unknown JSON properties and invalid field types fail before CodeQL initialization.
          Local configuration paths are relative to the caller repository root, not `working-directory`.
          See https://github.com/github/codeql-action.

          Example:
          ```json
          {
            "languages": "javascript-typescript",
            "config-file": ".github/codeql/config.yml"
          }
          ```
        type: string
        required: false
        default: "typescript"
      dependency-review:
        description: |
          Enable dependency review scan.
          Works with public repositories and private repositories with a GitHub Advanced Security license.
          See https://github.com/actions/dependency-review-action.
        type: boolean
        required: false
        default: true
      test:
        description: |
          Whether to enable testing.
          Set to `null` or empty to disable.
          Accepts a JSON object for test options. See [test action](../../actions/test/README.md).
          If coverage is enabled, it should generate test and coverage reports in standard formats.

          Example:

          ```json:package.json
          {
            "test:ci": "vitest run --reporter=default --reporter=junit --outputFile=junit.xml --coverage.enabled --coverage.reporter=lcov --coverage.reporter=text"
          }
          ```
        type: string
        required: false
        default: "true"
      working-directory:
        description: "Working directory where the dependencies are installed."
        type: string
        required: false
        default: "."
      container:
        description: |
          Container configuration to run CI steps in.
          Accepts either a string (container image name) or a JSON object with container options.

          String format (simple):

          ```yml
          container: "node:18"
          ```

          JSON object format (advanced):

          ```json
          {
            "image": "node:18",
            "env": {
              "NODE_ENV": "production"
            },
            "options": "--cpus 2",
            "ports": [8080, 3000],
            "volumes": ["/tmp:/tmp", "/cache:/cache"],
            "credentials": {
              "username": "myusername"
            },
            "pathMapping": {
              "/app": "./relative/path/to/app"
            }
          }
          ```

          Supported properties:

          - `image` (required)
          - `env` (object)
          - `options` (string)
          - `ports` (array)
          - `volumes` (array)
          - `credentials` (object with `username`).
          - `pathMapping` (object) path mapping from container paths to repository paths. Defaults is working directory is mapped with repository root.

          See https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/run-jobs-in-a-container.

          When specified, steps will execute inside this container instead of checking out code.
          The container should have the project code and dependencies pre-installed.
        type: string
        required: false
        default: ""
    secrets:
      build-secrets:
        description: |
          Secrets to be used during the build step.
          Must be a multi-line env formatted string.
          Example:
          ```txt
          SECRET_EXAMPLE=$\{{ secrets.SECRET_EXAMPLE }}
          ```
        required: false
      container-password:
        description: |
          Password for container registry authentication, if required.
          Used when the container image is hosted in a private registry.
          See https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/run-jobs-in-a-container#defining-credentials-for-a-container-registry.
        required: false
      github-token:
        description: |
          GitHub token to use for authentication.
          Defaults to `GITHUB_TOKEN` if not provided.
        required: false
    outputs:
      build-artifact-id:
        description: "ID of the build artifact) uploaded during the build step."
        value: ${{ jobs.build.outputs.artifact-id }}

permissions: {}

jobs:
  prepare:
    name: 📦 Prepare configuration
    runs-on: &ci-runner ${{ inputs.runs-on && fromJson(inputs.runs-on) || 'ubuntu-latest' }}
    permissions: {}
    outputs:
      container-image: ${{ steps.parse.outputs.container-image }}
      container-env: ${{ steps.parse.outputs.container-env }}
      container-options: ${{ steps.parse.outputs.container-options }}
      container-ports: ${{ steps.parse.outputs.container-ports }}
      container-volumes: ${{ steps.parse.outputs.container-volumes }}
      container-username: ${{ steps.parse.outputs.container-username }}
      path-mapping: ${{ steps.parse.outputs.path-mapping }}
    steps:
      - id: parse
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          CONTAINER_INPUT: ${{ inputs.container }}
          CONTAINER_PASSWORD: ${{ secrets.container-password }}
          WORKING_DIRECTORY: ${{ inputs.working-directory }}
        with:
          script: |
            const containerInput = process.env.CONTAINER_INPUT.trim();
            if (!containerInput) {
              return;
            }
            core.debug(`Container input: ${containerInput}`);

            // Check if input is a JSON object or a simple string
            const isJson = containerInput.startsWith('{');

            let container = {
              options: '--user root:root'
            };

            let pathMapping = {
              [process.env.WORKING_DIRECTORY || '.']: process.env.GITHUB_WORKSPACE,
            };

            if (isJson) {
              try {
                const {pathMapping: parsedPathMapping, ...parsedContainer} = JSON.parse(containerInput);
                core.debug(`Parsed container input as JSON: ${JSON.stringify(parsedContainer)}`);

                container = {
                  ...container,
                  ...parsedContainer,
                  options: `${container.options} ${parsedContainer.options || ''}`.trim()
                };

                core.debug(`Parsed path mapping: ${JSON.stringify(parsedPathMapping)}`);
                if (parsedPathMapping){
                  pathMapping = parsedPathMapping;
                }

              } catch (error) {
                return core.setFailed(`Failed to parse container input as JSON: ${error.message}`,{ cause: error });
              }
            } else {
              // Simple string format - just the image name
              container.image = containerInput;
            }

            core.debug(`Parsed container configuration: ${JSON.stringify(container)}`);

            if (!container.image) {
              return core.setFailed('Container image must be specified in the container input.');
            }
            core.setOutput('container-image', container.image);

            if (container.env) {
              core.setOutput('container-env', JSON.stringify(container.env));
            }

            if (container.options) {
              core.setOutput('container-options', container.options);
            }

            if (container.ports) {
              core.setOutput('container-ports', JSON.stringify(container.ports));
            }

            if (container.volumes) {
              core.setOutput('container-volumes', JSON.stringify(container.volumes));
            }

            if (container.credentials?.username) {
              core.setOutput('container-username', container.credentials.username);
              if (!process.env.CONTAINER_PASSWORD) {
                return core.setFailed('Container password must be provided when container credentials username is specified.');
              }
            } else if (process.env.CONTAINER_PASSWORD) {
              return core.setFailed('Container credentials username must be provided when container password is specified.');
            }

            core.debug(`Parsed path mapping: ${JSON.stringify(pathMapping)}`);
            if (!pathMapping || typeof pathMapping !== 'object' || Object.keys(pathMapping).length === 0){
              return core.setFailed('At least one path mapping must be specified in the container configuration.');
            }

            core.setOutput('path-mapping', Object.entries(pathMapping).reduce((acc, [containerPath, repoPath]) => {
              acc += `${acc?',' : ''}${containerPath}:${repoPath}`;
              return acc;
            }, ""));

  code-ql:
    name: 🛡️ CodeQL Analysis
    if: inputs.checks == true && inputs.code-ql != ''
    permissions:
      security-events: write
    runs-on: *ci-runner
    steps:
      - uses: hoverkraft-tech/ci-github-common/actions/checkout@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1
      - id: code-ql-options
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          CODE_QL: ${{ inputs.code-ql }}
        with:
          script: |
            const input = process.env.CODE_QL.trim();
            let options = { languages: input };

            if (input.startsWith('{')) {
              try {
                options = JSON.parse(input);
              } catch {
                return core.setFailed('code-ql must be a language string or a valid JSON object.');
              }
            }

            if (Object.keys(options).some(key => !['languages', 'config-file'].includes(key))) {
              return core.setFailed('code-ql supports only languages and config-file.');
            }
            if (typeof options.languages !== 'string' || !options.languages.trim()) {
              return core.setFailed('code-ql.languages must be a nonempty string.');
            }
            if (options['config-file'] !== undefined && typeof options['config-file'] !== 'string') {
              return core.setFailed('code-ql.config-file must be a string.');
            }

            core.setOutput('languages', options.languages);
            core.setOutput('config-file', options['config-file'] ?? '');
      - uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
        with:
          languages: ${{ steps.code-ql-options.outputs.languages }}
          config-file: ${{ steps.code-ql-options.outputs.config-file }}
      - uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1

  dependency-review:
    name: 🛡️ Dependency Review
    if: github.event_name == 'pull_request' && inputs.checks == true && inputs.dependency-review
    permissions:
      contents: read
    runs-on: *ci-runner
    steps:
      - uses: hoverkraft-tech/ci-github-common/actions/checkout@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1
      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0

  setup:
    name: ⚙️ Setup
    runs-on: *ci-runner
    needs:
      - prepare
    permissions:
      contents: read
      packages: read
    container: &ci-container
      image: ${{ needs.prepare.outputs.container-image || '' }}
      env: ${{ fromJSON(needs.prepare.outputs.container-env || '{}') }}
      options: ${{ needs.prepare.outputs.container-options || ' ' }}
      ports: ${{ fromJSON(needs.prepare.outputs.container-ports || '[]') }}
      volumes: ${{ fromJSON(needs.prepare.outputs.container-volumes || '[]') }}
      credentials: ${{ fromJSON(needs.prepare.outputs.container-username && format('{{"username":{0},"password":{1}}}',toJSON(needs.prepare.outputs.container-username),toJSON(secrets.container-password)) || '{}') }}
    outputs:
      working-directory: ${{ steps.working-directory.outputs.absolute-path }}
      build-env: ${{ steps.build-variables.outputs.env }}
      build-commands: ${{ steps.build-variables.outputs.commands }}
      build-artifact: ${{ steps.build-variables.outputs.artifact }}
    steps:
      - name: Checkout repository
        if: inputs.container == ''
        uses: hoverkraft-tech/ci-github-common/actions/checkout@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1

      - id: working-directory
        uses: hoverkraft-tech/ci-github-common/actions/working-directory@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1
        with:
          working-directory: ${{ inputs.working-directory }}
          enforce-path-in-workspace: ${{ inputs.container && 'false' || 'true' }}

      - id: build-variables
        if: inputs.build != ''
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          WORKING_DIRECTORY: ${{ steps.working-directory.outputs.absolute-path }}
          BUILD_INPUT: ${{ inputs.build }}
        with:
          script: |
            const path = require('node:path');

            const workingDirectory = process.env.WORKING_DIRECTORY;
            const buildInput = process.env.BUILD_INPUT.trim();

            let commands = [];
            let env = {};

            // Build commands is a list of command(s), one per line.
            const buildCommandsIsList = !buildInput.trim().startsWith('{') && !buildInput.trim().startsWith('[');
            if (buildCommandsIsList) {
              commands = buildInput.split('\n').map(command => command.trim()).filter(Boolean);
            } else {
              let build;
              try {
                build = JSON.parse(buildInput);
              } catch (error) {
                core.setFailed(`Failed to parse build input as JSON: ${error.message}`);
                return;
              }

              // Build commands is a JSON array of commands
              if (Array.isArray(build)) {
                commands = build;
              }
              // Build commands is a JSON object
              else {
                commands = build.commands ?? ["build"];
                env = build.env ?? {};

                if (build.artifact) {
                  buildArtifact = build.artifact;

                  if (typeof buildArtifact === 'string' || Array.isArray(buildArtifact)) {
                    buildArtifact = {
                      paths: buildArtifact
                    };
                  }

                  if (typeof buildArtifact.paths === 'string') {
                    buildArtifact.paths = buildArtifact.paths.split('\n');
                  } else if (!Array.isArray(buildArtifact.paths)) {
                    return core.setFailed('Build artifact paths must be a string or an array of strings');
                  }

                  buildArtifact.paths = buildArtifact.paths
                    .map(artifact => artifact.trim())
                    .filter(Boolean)
                    .map(artifact => {
                      // FIXME: Workaround to preserve full path to artifact
                      const fullpath = artifact.startsWith('/') ? artifact : path.join(workingDirectory, artifact);

                      // Add a wildcard to the first folder of the path
                      return fullpath.replace(/\/([^/]+)/, '/*$1');
                    }).join('\n');

                  if (!buildArtifact.paths) {
                    return core.setFailed('No valid build artifact paths found');
                  }

                  // Generate a unique name for the artifact
                  buildArtifact.name = `${process.env.GITHUB_JOB}-build-${process.env.GITHUB_RUN_ID}-${Math.random().toString(36).substring(2, 8)}`;

                  core.setOutput('artifact', JSON.stringify(buildArtifact));
                }
              }
            }

            if (commands.some(command => typeof command !== 'string')) {
              core.setFailed('Build commands array must only contain strings');
              return;
            }

            const sanitizedCommands = commands.map(command => command.trim()).filter(Boolean);
            if (!sanitizedCommands.length) {
              core.setFailed('No build commands found');
            }

            core.setOutput('commands', sanitizedCommands.join('\n'));
            core.setOutput('env', JSON.stringify(env));

  lint:
    if: inputs.checks == true && inputs.lint
    name: 👕 Lint
    runs-on: *ci-runner
    container: *ci-container
    needs:
      - prepare
      - setup
    permissions:
      contents: read
      packages: read
    steps:
      - uses: hoverkraft-tech/ci-github-common/actions/checkout@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1
        if: inputs.container == ''

      - id: preparel-lint-options
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          LINT_INPUT: ${{ inputs.lint }}
        with:
          script: |
            const lintInput = process.env.LINT_INPUT.trim();

            let lintOptions = {};
            if (lintInput && lintInput !== 'true') {
              try {
                const parsed = JSON.parse(lintInput);
                lintOptions = { ...lintOptions, ...parsed };
              } catch (error) {
                core.setFailed(`Failed to parse lint input as JSON: ${error.message}`);
                return;
              }
            }

            core.setOutput('command', lintOptions.command || 'lint:ci');
            core.setOutput('report-file', lintOptions['report-file'] || '');

      - name: Run lint
        uses: $/actions/lint
        with:
          working-directory: ${{ needs.setup.outputs.working-directory }}
          container: ${{ inputs.container != '' && 'true' || 'false' }}
          command: ${{ steps.preparel-lint-options.outputs.command }}
          report-file: ${{ steps.preparel-lint-options.outputs.report-file }}
          path-mapping: ${{ needs.prepare.outputs.path-mapping || '' }}

  build:
    if: inputs.checks == true
    name: 🏗️ Build
    runs-on: *ci-runner
    container: *ci-container
    needs:
      - prepare
      - setup
    permissions:
      contents: read
      packages: read
    outputs:
      artifact-id: ${{ steps.build.outputs.artifact-id }}
    steps:
      - uses: hoverkraft-tech/ci-github-common/actions/checkout@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1
        if: needs.setup.outputs.build-commands && inputs.container == ''

      - id: build
        if: needs.setup.outputs.build-commands
        uses: $/actions/build
        with:
          container: ${{ inputs.container != '' && 'true' || 'false' }}
          working-directory: ${{ needs.setup.outputs.working-directory }}
          build-secrets: ${{ secrets.build-secrets }}
          build-commands: ${{ needs.setup.outputs.build-commands }}
          build-env: ${{ needs.setup.outputs.build-env }}
          build-artifact: ${{ needs.setup.outputs.build-artifact }}

  test:
    if: inputs.checks == true && inputs.test
    name: 🧪 Test
    runs-on: *ci-runner
    container: *ci-container
    needs:
      - prepare
      - setup
      - build
    permissions:
      contents: read
      id-token: write # Required for Codecov uploads with OIDC authentication
      packages: read
      pull-requests: write
    steps:
      - uses: hoverkraft-tech/ci-github-common/actions/checkout@44f6108cef0e9884ea7735f3d62932c2310745d4 # 0.39.1
        if: inputs.container == ''

      - if: needs.build.outputs.artifact-id && inputs.container == ''
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          artifact-ids: ${{ needs.build.outputs.artifact-id }}
          path: "/"

      - id: prepare-test-options
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          TEST_INPUT: ${{ inputs.test }}
        with:
          script: |
            const testInput = process.env.TEST_INPUT.trim();

            let testOptions = {};
            if (testInput && testInput !== 'true') {
              try {
                const parsed = JSON.parse(testInput);
                testOptions = { ...testOptions, ...parsed };
              } catch (error) {
                core.setFailed(`Failed to parse test input as JSON: ${error.message}`);
                return;
              }
            }

            if (testOptions.coverage === undefined) {
              testOptions.coverage = 'github';
            }
            core.setOutput('coverage', testOptions.coverage );
            core.setOutput('report-file', testOptions['report-file'] || '');
            core.setOutput('command', testOptions.command || 'test:ci');

      - name: Run tests
        uses: $/actions/test
        with:
          working-directory: ${{ needs.setup.outputs.working-directory }}
          container: ${{ inputs.container != '' && 'true' || 'false' }}
          command: ${{ steps.prepare-test-options.outputs.command }}
          coverage: ${{ steps.prepare-test-options.outputs.coverage }}
          report-file: ${{ steps.prepare-test-options.outputs.report-file }}
          path-mapping: ${{ needs.prepare.outputs.path-mapping || '' }}
          github-token: ${{ secrets.github-token || github.token }}