docs-dispatch.yml

name: Docs Dispatch

# Docs on automem.ai follow published releases, so this runs once per release:
# release-please.yml calls it after creating one. A manual run documents a
# release tag (the latest release by default), which also covers a release
# published by hand, since that never sets release_created.

on:
  workflow_call:
    inputs:
      release_tag:
        description: "Release tag to document."
        required: true
        type: string
      reason:
        description: "Why docs should be audited."
        required: false
        type: string
  workflow_dispatch:
    inputs:
      release_tag:
        description: "Release tag to document. Defaults to the latest release."
        required: false
      reason:
        description: "Why docs should be audited."
        required: false

permissions:
  contents: read

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed
        env:
          GH_TOKEN: ${{ github.token }}
          INPUT_RELEASE_TAG: ${{ inputs.release_tag }}
          INPUT_REASON: ${{ inputs.reason }}
        run: |
          RELEASE_TAG="$INPUT_RELEASE_TAG"
          if [ -z "$RELEASE_TAG" ]; then
            RELEASE_TAG=$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" -q '.tag_name')
          fi
          git fetch --tags --force origin

          HEAD_SHA=$(git rev-parse "${RELEASE_TAG}^{commit}")
          # Diff against the previous release so the docs audit sees the whole release.
          if PREVIOUS_TAG=$(git describe --tags --abbrev=0 --match 'v*' "${HEAD_SHA}^" 2>/dev/null); then
            BASE_SHA=$(git rev-parse "${PREVIOUS_TAG}^{commit}")
          else
            echo "::warning::No previous release tag found, diffing against first commit"
            BASE_SHA=$(git rev-list --max-parents=0 --max-count=1 "$HEAD_SHA")
          fi
          REASON="${INPUT_REASON:-Release ${RELEASE_TAG}}"

          COMPARE_URL="https://github.com/${GITHUB_REPOSITORY}/compare/${BASE_SHA}...${HEAD_SHA}"
          FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" | jq -R -s -c 'split("\n") | map(select(. != ""))')

          {
            echo "release_tag=$RELEASE_TAG"
            echo "release_version=${RELEASE_TAG##*v}"
            echo "base_sha=$BASE_SHA"
            echo "head_sha=$HEAD_SHA"
            echo "files=$FILES"
            echo "compare_url=$COMPARE_URL"
            echo "reason<<EOF"
            echo "$REASON"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Check file-doc mapping
        id: check
        env:
          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
          CHANGED_FILES: ${{ steps.changed.outputs.files }}
        run: |
          if ! MAP=$(curl -fsSL --connect-timeout 10 --max-time 30 --retry 2 --retry-connrefused \
            -H "Authorization: Bearer $GH_TOKEN" \
            -H "Accept: application/vnd.github.raw" \
            "https://api.github.com/repos/verygoodplugins/automem-website/contents/scripts/file-doc-map.json"); then
            echo "::warning::Failed to fetch file-doc-map.json, dispatching anyway"
            echo "affected=[]" >> "$GITHUB_OUTPUT"
            echo "mapping_status=unknown" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          REPO_KEY="${GITHUB_REPOSITORY#*/}"

          AFFECTED=$(echo "$MAP" | jq -r --arg repo "$REPO_KEY" --argjson changed "$CHANGED_FILES" '
            def matches_pattern($file; $pattern):
              if ($pattern | endswith("/**")) then
                ($file | startswith($pattern[0:-2]))
              else
                $file == $pattern
              end;

            .[$repo] // {} | to_entries | map(
              select(.key as $pattern | $changed | any(. as $file | matches_pattern($file; $pattern)))
            ) | map(.value) | flatten | unique | .[]
          ')

          if [ -z "$AFFECTED" ]; then
            echo "No doc pages affected by this change"
            echo "affected=[]" >> "$GITHUB_OUTPUT"
            echo "mapping_status=none" >> "$GITHUB_OUTPUT"
          else
            AFFECTED_JSON=$(echo "$AFFECTED" | jq -R -s -c 'split("\n") | map(select(. != ""))')
            echo "Affected doc pages: $AFFECTED_JSON"
            echo "affected=$AFFECTED_JSON" >> "$GITHUB_OUTPUT"
            echo "mapping_status=matched" >> "$GITHUB_OUTPUT"
          fi

      - name: Dispatch to automem-website
        if: steps.check.outputs.mapping_status != 'none'
        env:
          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
          SOURCE_REPO: ${{ github.repository }}
          RELEASE_TAG: ${{ steps.changed.outputs.release_tag }}
          RELEASE_VERSION: ${{ steps.changed.outputs.release_version }}
          HEAD_SHA: ${{ steps.changed.outputs.head_sha }}
          BASE_SHA: ${{ steps.changed.outputs.base_sha }}
          CHANGED_FILES: ${{ steps.changed.outputs.files }}
          AFFECTED_DOCS: ${{ steps.check.outputs.affected }}
          MAPPING_STATUS: ${{ steps.check.outputs.mapping_status }}
          REASON: ${{ steps.changed.outputs.reason }}
          COMPARE_URL: ${{ steps.changed.outputs.compare_url }}
        run: |
          # client_payload allows at most 10 top-level properties; source_sha is
          # the release commit, so there is no separate head_sha or commit_url.
          jq -n \
            --arg event_type "docs-update" \
            --arg source_repo "$SOURCE_REPO" \
            --arg source_sha "$HEAD_SHA" \
            --arg release_tag "$RELEASE_TAG" \
            --arg release_version "$RELEASE_VERSION" \
            --arg base_sha "$BASE_SHA" \
            --arg changed_files "$CHANGED_FILES" \
            --arg affected_docs "$AFFECTED_DOCS" \
            --arg mapping_status "$MAPPING_STATUS" \
            --arg reason "$REASON" \
            --arg compare_url "$COMPARE_URL" \
            '{
              event_type: $event_type,
              client_payload: {
                source_repo: $source_repo,
                source_sha: $source_sha,
                release_tag: $release_tag,
                release_version: $release_version,
                base_sha: $base_sha,
                changed_files: ($changed_files | fromjson),
                affected_docs: ($affected_docs | fromjson),
                mapping_status: $mapping_status,
                reason: $reason,
                compare_url: $compare_url
              }
            }' | gh api repos/verygoodplugins/automem-website/dispatches --input -