mattermost/.github/workflows/docs-gap.yml

name: Docs Gap Analysis

# Owns Docs/Needed. No paths: filter — must run on docs-only pushes that close a gap.
# analyze (model, read-only) and report (label/comment writer) are separate jobs.

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches:
      - master

permissions:
  contents: read

concurrency:
  group: docs-gap-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  analyze:
    name: Analyze documentation impact
    # Skip forks (no key/token) and human opt-outs.
    if: >-
      github.event.pull_request.draft == false &&
      github.event.pull_request.head.repo.full_name == github.repository &&
      !startsWith(github.event.pull_request.user.login, 'unified-ci-app') &&
      !contains(github.event.pull_request.labels.*.name, 'Docs/Not Needed') &&
      !contains(github.event.pull_request.labels.*.name, 'Docs/Done')
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      pull-requests: read
    outputs:
      analyzable: ${{ steps.diff.outputs.analyzable }}
      result: ${{ steps.gap.outputs.structured_output }}
      outcome: ${{ steps.gap.outcome }}
    env:
      HAS_ANTHROPIC_KEY: ${{ secrets.ANTHROPIC_API_KEY != '' }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 2
          persist-credentials: false

      # Job-level if cannot read secrets; fold the key check into analyzable so
      # report skips when unset.
      - name: Collect both sides of the diff
        id: diff
        run: |
          set -euo pipefail
          mkdir -p .docs-ai/gap

          DOCS_PATHSPEC=(
            docs/main docs/develop
            ':(exclude)docs/main/agents/docs'
          )

          git diff --name-only HEAD^1 HEAD > .docs-ai/gap/files.raw
          git diff HEAD^1 HEAD -- . ':(exclude)docs' > .docs-ai/gap/code.raw
          git diff HEAD^1 HEAD -- "${DOCS_PATHSPEC[@]}" > .docs-ai/gap/docs.raw

          COUNT=$(wc -l < .docs-ai/gap/files.raw | tr -d ' ')
          echo "Changed files: ${COUNT}"

          if [ "${COUNT}" -eq 0 ]; then
            echo "Nothing changed; skipping gap analysis." >> "$GITHUB_STEP_SUMMARY"
            echo "analyzable=false" >> "$GITHUB_OUTPUT"
          elif [ "$HAS_ANTHROPIC_KEY" != "true" ]; then
            echo "ANTHROPIC_API_KEY is not configured; skipping gap analysis." >> "$GITHUB_STEP_SUMMARY"
            echo "analyzable=false" >> "$GITHUB_OUTPUT"
          else
            echo "analyzable=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Set up Node
        if: steps.diff.outputs.analyzable == 'true'
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: .nvmrc
          cache: "npm"
          cache-dependency-path: .github/scripts/docs-ai/package-lock.json

      - name: Install dependencies
        if: steps.diff.outputs.analyzable == 'true'
        working-directory: .github/scripts/docs-ai
        run: npm ci --ignore-scripts

      - name: Build the prompt
        id: prompt
        if: steps.diff.outputs.analyzable == 'true'
        run: |
          node .github/scripts/docs-ai/gap/prepare.mjs \
            --files .docs-ai/gap/files.raw \
            --code-diff .docs-ai/gap/code.raw \
            --docs-diff .docs-ai/gap/docs.raw \
            --out-dir .docs-ai/gap

      # Soft-fail so report can leave the label alone on outage.
      - name: Assess the gap
        id: gap
        if: steps.diff.outputs.analyzable == 'true'
        continue-on-error: true
        uses: anthropics/claude-code-action@756cc22e19660d20e8cc9496b4f242475a7f7790 # v1.0.235
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Without this the action uses Claude App via OIDC (needs id-token: write).
          github_token: ${{ secrets.GITHUB_TOKEN }}
          allowed_bots: "cursor,claude"
          prompt: ${{ steps.prompt.outputs.prompt }}
          claude_args: |
            --model ${{ vars.DOCS_AI_GAP_MODEL || 'claude-sonnet-4-6' }}
            --max-turns 30
            --allowedTools "Read,Glob,Grep"
            --json-schema '${{ steps.prompt.outputs.schema }}'

  report:
    name: Post comment and manage label
    needs: analyze
    # !cancelled (not always): skip superseded concurrency cancels; still run after soft-fail.
    if: ${{ !cancelled() && needs.analyze.outputs.analyzable == 'true' }}
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Set up Node
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: .nvmrc

      - name: Report
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          GAP_RESULT: ${{ needs.analyze.outputs.result }}
          GAP_OUTCOME: ${{ needs.analyze.outputs.outcome }}
        run: node .github/scripts/docs-ai/gap/report.mjs