generate.yml

name: Generate and Compare Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

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

permissions:
  contents: read

jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      sha: ${{ steps.push.outputs.sha || steps.pr.outputs.sha }}
      base-run: ${{ steps.main.outputs.run_id }}
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@a90bcbc6539c36a85cdfeb73f7e2f433735f215b # v2.15.0
        with:
          egress-policy: audit

      # If we are running from the main branch (a non-pull_request event), we
      # want the latest SHA from nodejs/node
      - id: push
        if: ${{ github.event_name != 'pull_request' }}
        run: |
          SHA=$(git ls-remote https://github.com/nodejs/node.git HEAD | awk '{print $1}')
          echo "$SHA" > commit
          echo "sha=$SHA" >> "$GITHUB_OUTPUT"

      - name: Upload metadata artifact
        if: ${{ github.event_name != 'pull_request' }}
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: commit
          path: commit

      # If we are running from a PR (a pull_request event), we
      # want the SHA used by the most recent `push` run
      - name: Get latest `main` run
        if: ${{ github.event_name == 'pull_request' }}
        id: main
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          GH_TOKEN: ${{ github.token }}
        run: |
          # `174604400` refers to `generate.yml`'s workflow ID, available at https://api.github.com/repos/nodejs/doc-kit/actions/workflows/generate.yml
          # The `databaseId` is a given runs run ID (Ref: https://docs.github.com/en/enterprise-cloud@latest/graphql/reference/objects#workflowrun)
          ID=$(gh run list --repo $GITHUB_REPOSITORY -c $BASE_SHA -w 174604400 -L 1 --json databaseId --jq ".[].databaseId")
          echo "run_id=$ID" >> $GITHUB_OUTPUT

      - name: Download metadata artifact
        if: ${{ github.event_name == 'pull_request' }}
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
        with:
          name: commit
          run-id: ${{ steps.main.outputs.run_id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - id: pr
        if: ${{ github.event_name == 'pull_request' }}
        run: |
          SHA=$(cat commit)
          echo "sha=$SHA" >> "$GITHUB_OUTPUT"

  generate:
    runs-on: ubuntu-latest
    needs: prepare
    strategy:
      fail-fast: false
      matrix:
        include:
          - target: man-page
            input: './node/doc/api/cli.md'

          - target: addon-verify
            input: './node/doc/api/addons.md'

          - target: api-links
            input: './node/lib/*.js'
            compare: object-assertion

          - target: orama-db
            input: './node/doc/api/*.md'
            compare: file-size

          - target: json-simple
            input: './node/doc/api/*.md'

          - target: legacy-json
            input: './node/doc/api/*.md'
            compare: object-assertion

          - target: legacy-html
            input: './node/doc/api/*.md'
            compare: file-size

          - target: web
            input: './node/doc/api/*.md'
            compare: file-size

          - target: llms-txt
            input: './node/doc/api/*.md'
            compare: file-size
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@a90bcbc6539c36a85cdfeb73f7e2f433735f215b # v2.15.0
        with:
          egress-policy: audit

      - name: Git Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Git Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
          repository: nodejs/node
          ref: ${{ needs.prepare.outputs.sha }}
          sparse-checkout: |
            doc/api
            lib
            .
          path: node

      - name: Setup Node.js
        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
        with:
          node-version-file: '.nvmrc'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Create output directory
        run: mkdir -p out/${{ matrix.target }}

      - name: Generate ${{ matrix.target }}
        run: |
          node bin/cli.mjs generate \
            -t ${{ matrix.target }} \
            -i "${{ matrix.input }}" \
            -o out \
            -c ./node/CHANGELOG.md \
            --index ./node/doc/api/index.md \
            --log-level debug

      - name: Download base branch artifact
        if: ${{ matrix.compare && needs.prepare.outputs.base-run }}
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
        with:
          name: ${{ matrix.target }}
          path: base
          run-id: ${{ needs.prepare.outputs.base-run }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Compare to base branch
        if: ${{ matrix.compare && needs.prepare.outputs.base-run }}
        env:
          GENERATOR: ${{ matrix.target }}
        run: |
          node scripts/comparators/${{ matrix.compare }}.mjs > out/comparison.txt

      - name: Upload ${{ matrix.target }} artifacts
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: ${{ matrix.target }}
          path: out