docs-quality.yml

name: Docs Quality
on:
  pull_request:
  workflow_dispatch:
jobs:
  typos:
    name: Spelling (typos-cli)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - uses: crate-ci/typos@master

  harper:
    name: Grammar and Style Check
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Cache Harper CLI
        id: cache-harper
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/bin/harper-cli
            ~/.cargo/registry
            ~/.cargo/git
          key: ${{ runner.os }}-harper-cli
          restore-keys: |
            ${{ runner.os }}-harper-cli
      - name: Report cache status
        run: |
          echo "cache-hit output: '${{ steps.cache-harper.outputs.cache-hit }}'"
          ls -la ~/.cargo/bin/ 2>&1 || echo "~/.cargo/bin does not exist"
          if [ -x ~/.cargo/bin/harper-cli ]; then
            echo "RESULT: harper-cli binary present and executable"
            ~/.cargo/bin/harper-cli --version || true
          else
            echo "RESULT: harper-cli binary NOT present -- full reinstall will run"
          fi
      - name: Install Harper CLI
        if: steps.cache-harper.outputs.cache-hit != 'true'
        run: cargo install --locked --git https://github.com/Automattic/harper.git harper-cli
      - name: Lint docs with Harper
        run: |
          set -uo pipefail
          ONLY_RULES=(
            UseTitleCase
            RepeatedWords
            MergeWords
            ItsContraction
          )
          ONLY_ARG="--only $(IFS=,; echo "${ONLY_RULES[*]}")"
          mdxtmp="$(mktemp -d)"
          out="$(mktemp)"
          total=0
          bad=0
          while IFS= read -r -d '' file; do
            total=$((total+1))
            case "$file" in
              *.mdx)
                target="$mdxtmp/${file}.md"
                mkdir -p "$(dirname "$target")"
                cp "$file" "$target"
                ;;
              *)
                target="$file"
                ;;
            esac
            echo "::group::$file"
            if harper-cli lint $ONLY_ARG "$target" 2>&1 | tee -a "$out"; then
              :
            else
              bad=$((bad+1))
            fi
            echo "::endgroup::"
          done < <(
            find docs src/pages \
              -type f \( -name "*.md" -o -name "*.mdx" \) \
              -print0 2>/dev/null
          )
          titlecase=$(grep -c 'Capitalization::UseTitleCase' "$out" || true)
          {
            echo "### Harper summary"
            echo "- Files scanned: $total"
            echo "- Files with issues: $bad"
            echo "- Heading title case violations: $titlecase"
            echo ""
            echo "### Violations by rule"
            echo '```'
            grep -oE '\[[A-Za-z]+::[A-Za-z]+\]' "$out" | sort | uniq -c | sort -rn || true
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"
          echo "== Harper: $bad/$total files with issues; $titlecase UseTitleCase violations =="
          [ "$bad" -eq 0 ]
      - name: Annotate PR with Harper warnings
        if: always()
        run: |
          set -uo pipefail
          ONLY_RULES=(
            UseTitleCase
            RepeatedWords
            MergeWords
            ItsContraction
          )
          ONLY_ARG="--only $(IFS=,; echo "${ONLY_RULES[*]}")"
          mdxtmp="$(mktemp -d)"
          while IFS= read -r -d '' file; do
            case "$file" in
              *.mdx)
                target="$mdxtmp/${file}.md"
                mkdir -p "$(dirname "$target")"
                cp "$file" "$target"
                ;;
              *)
                target="$file"
                ;;
            esac
            if json_out="$(harper-cli lint $ONLY_ARG --format json "$target" 2>/dev/null)"; then
              :
            else
              printf '%s' "$json_out" | FILE="$file" python3 -c "import json,sys,os;d=json.load(sys.stdin);fp=os.environ['FILE'];esc=lambda s: s.replace('%','%25').replace('\r','%0D').replace('\n','%0A');[print('::warning file='+esc(fp)+',line='+str(l.get('line',1))+',col='+str(l.get('column',1))+',title='+esc(l.get('rule','?'))+'::'+esc(l.get('message',''))) for f in d for l in f.get('lints',[])]" || true
            fi
          done < <(
            find docs src/pages \
              -type f \( -name "*.md" -o -name "*.mdx" \) \
              -print0 2>/dev/null
          )