docs.yml

name: docs

on:
    pull_request:
        branches: [main]
        paths:
            - '**.ts'
            - '**.tsx'
            - '**.js'
            - '**.jsx'
            - '.github/workflows/docs.yml'
    workflow_dispatch:

concurrency:
    group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
    cancel-in-progress: true

env:
    CARGO_TERM_COLOR: always
    ENVIRONMENT: development
    GH_TOKEN: ${{ github.token }}

jobs:
    check:
        runs-on: ubuntu-latest
        steps:
            - name: Print contexts
              env:
                  GITHUB_CONTEXT: ${{ toJson(github) }}
                  ENV_CONTEXT: ${{ toJson(env) }}
                  VARS_CONTEXT: ${{ toJson(vars) }}
                  JOB_CONTEXT: ${{ toJson(job) }}
                  STEPS_CONTEXT: ${{ toJson(steps) }}
                  RUNNER_CONTEXT: ${{ toJson(runner) }}
                  SECRETS_CONTEXT: ${{ toJson(secrets) }}
                  STRATEGY_CONTEXT: ${{ toJson(strategy) }}
                  MATRIX_CONTEXT: ${{ toJson(matrix) }}
                  NEEDS_CONTEXT: ${{ toJson(needs) }}
                  INPUTS_CONTEXT: ${{ toJson(inputs) }}
              run: |
                  echo "******************************"
                  echo "github:" "$GITHUB_CONTEXT"
                  echo "******************************"
                  echo "env:" "$ENV_CONTEXT"
                  echo "******************************"
                  echo "vars:" "$VARS_CONTEXT"
                  echo "******************************"
                  echo "job:" "$JOB_CONTEXT"
                  echo "******************************"
                  echo "steps:" "$STEPS_CONTEXT"
                  echo "******************************"
                  echo "runner:" "$RUNNER_CONTEXT"
                  echo "******************************"
                  echo "secrets:" "$SECRETS_CONTEXT"
                  echo "******************************"
                  echo "strategy:" "$STRATEGY_CONTEXT"
                  echo "******************************"
                  echo "matrix:" "$MATRIX_CONTEXT"
                  echo "******************************"
                  echo "needs:" "$NEEDS_CONTEXT"
                  echo "******************************"
                  echo "inputs:" "$INPUTS_CONTEXT"
                  echo "******************************"

            # Checkout the repo
            - uses: actions/checkout@v3
            - uses: actions/setup-node@v3
              with:
                  node-version-file: '.nvmrc'
            - name: Install npm
              run: npm i -g npm@$(cat package.json | jq -r .engines.npm)

            - run: mkdir -p protocol/cargo-cache
            - run: mkdir -p protocol/target
            - run: mkdir -p node_modules
            - run: mkdir -p ~/.cache/Cypress

            - name: Restore cache
              uses: actions/cache/restore@v3
              with:
                  path: |
                      protocol/cargo-cache
                      protocol/target
                      node_modules
                      ~/.cache/Cypress
                  # note that restoring a cache in github is a pain. The trailing '-' matches any string after the '-', therefore 'abc-' would match a cache named 'abc-1234' or 'abc-5678', etc.
                  # the problem is 'abc-' will not match a cache named 'abc'! So if you're using wildcard cache name selectors like this, you need a field that changes as the suffix to become the wildcard
                  # here we're setting the key to an unused cache key so it falls back to the wildcard selector in `restore-keys`
                  key: some-unused-cache-key
                  restore-keys: |
                      project-cache-${{ runner.os }}-${{ runner.arch }}-

            - run: npm ci
            - run: npm run build:all
            - run: npm run build:all:cjs

            - name: Check typedoc is up-to-date
              run: |
                  # the docs contains the short git commit hash from when the docs were generated. This makes it difficult to check if the docs are up-to-date, as regenerating the docs uses the current commit's hash, not the hash from when the docs were generated.
                  # Therefore, we're going to detect the hash from the docs, then regenerate the docs, replace the current commit's hash in the docs with the hash from when the docs were generated, then check if the docs have changed - convoluted, I know.

                  # get the current commit's hash
                  CURRENT_COMMIT_HASH=$(git rev-parse --short HEAD)
                  # get the hash from the docs
                  # this finds all html files in the docs, then greps for the commit hash, then takes the first hash, then removes the 'blob/' prefix. The docs put the commit hash in urls with the 'blob/' prefix, e.g. 'github.com/prosopo/captcha/blob/abcd1234/...'
                  DOCS_COMMIT_HASH=$(find docs -type f -name "*.html" -exec grep -oE 'blob/([[:alnum:]]{8})' {} + 2>/dev/null | head -n 1 | cut -d ':' -f 2 | sed 's/blob\///')

                  # now regenerate the docs
                  npm run docs

                  # replace the current commit's hash in the docs with the hash from when the docs were originally created
                  find docs -type f -name "*.html" -exec sed -i "s/blob\/$CURRENT_COMMIT_HASH/blob\/$DOCS_COMMIT_HASH/g" {} +

                  # check if there are any changes to the docs
                  # if there are changes, then the docs are not up-to-date and the most recent commit did not update the docs and only the docs
                  git diff --exit-code -- 'docs/**/*.html'