docs.yml

# Documentation Validation Workflow
#
# Validates documentation quality and link integrity.
# Runs on documentation changes and periodically to catch stale links.
#
# Jobs:
# 1. markdown-lint - Check Markdown formatting
# 2. link-check - Validate internal and external links
# 3. spell-check - Check for common spelling errors

name: Documentation

on:
  push:
    branches: [main, develop]
    paths:
      - 'docs/**'
      - '*.md'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: [main]
    paths:
      - 'docs/**'
      - '*.md'
  schedule:
    # Run weekly to catch stale external links
    - cron: '0 6 * * 1'
  workflow_dispatch:

jobs:
  #############################################################################
  # Markdown Linting
  #############################################################################
  markdown-lint:
    name: Markdown Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: markdownlint
        uses: DavidAnson/markdownlint-cli2-action@v22
        with:
          globs: |
            **/*.md
            !target/**
            !node_modules/**
        continue-on-error: true

  #############################################################################
  # Link Checking
  #############################################################################
  link-check:
    name: Link Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Check for broken links
        uses: lycheeverse/lychee-action@v2
        with:
          args: >-
            --verbose
            --no-progress
            --accept 200,204,301,302,403,429
            --exclude-mail
            --exclude '^https://github\.com/.*/(commit|compare)/'
            --exclude '^https://crates\.io/crates/'
            --exclude '^https://docs\.rs/'
            --exclude 'localhost'
            --exclude '127\.0\.0\.1'
            --exclude '\.local$'
            --timeout 30
            --max-retries 3
            --max-concurrency 10
            './**/*.md'
            './README.md'
          fail: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload link check report
        uses: actions/upload-artifact@v6
        if: always()
        with:
          name: link-check-report
          path: ./lychee/out.md
          retention-days: 30

  #############################################################################
  # Documentation Build Verification
  #############################################################################
  doc-build:
    name: Documentation Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install system dependencies (Ubuntu)
        run: |
          sudo apt-get update
          sudo apt-get install -y libglib2.0-dev libwebkit2gtk-4.1-dev librsvg2-dev patchelf libgtk-3-dev libayatana-appindicator3-dev libsqlcipher-dev

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache cargo registry
        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-cargo-docs-
            ${{ runner.os }}-cargo-

      - name: Build documentation
        run: cargo doc --workspace --no-deps --exclude wraith-transfer
        env:
          RUSTDOCFLAGS: -Dwarnings

      - name: Check for missing documentation
        run: |
          # Count documented vs undocumented items
          echo "Checking documentation coverage..."
          cargo doc --workspace --no-deps --exclude wraith-transfer 2>&1 | grep -c "warning: missing documentation" || echo "0 missing documentation warnings"

  #############################################################################
  # Table of Contents Validation
  #############################################################################
  toc-check:
    name: Table of Contents Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Verify documentation structure
        run: |
          echo "Checking documentation structure..."

          # Required top-level docs
          required_docs=(
            "README.md"
            "CHANGELOG.md"
            "CONTRIBUTING.md"
            "SECURITY.md"
            "LICENSE"
          )

          missing=0
          for doc in "${required_docs[@]}"; do
            if [[ ! -f "$doc" ]]; then
              echo "::error::Missing required file: $doc"
              missing=$((missing + 1))
            else
              echo "Found: $doc"
            fi
          done

          # Check docs directory structure
          required_dirs=(
            "docs/architecture"
            "docs/security"
            "docs/technical"
          )

          for dir in "${required_dirs[@]}"; do
            if [[ ! -d "$dir" ]]; then
              echo "::warning::Missing docs directory: $dir"
            else
              echo "Found: $dir/"
            fi
          done

          if [[ $missing -gt 0 ]]; then
            exit 1
          fi

      - name: Count documentation files
        run: |
          echo "Documentation statistics:"
          echo "========================="
          echo "Markdown files: $(find . -name '*.md' -not -path './target/*' | wc -l)"
          echo "Total lines: $(find . -name '*.md' -not -path './target/*' -exec cat {} + | wc -l)"
          echo ""
          echo "By directory:"
          find docs -type f -name '*.md' | cut -d/ -f2 | sort | uniq -c | sort -rn