Vapora/.github/workflows/docs-lint.yml

name: Documentation Lint & Validation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
  pull_request:
    branches:
      - main
    paths:
      - 'docs/**'

jobs:
  markdown-lint:
    name: Markdown Linting
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install markdownlint-cli
        run: npm install -g markdownlint-cli@0.37.0

      - name: Lint markdown files
        working-directory: docs
        run: |
          echo "Linting markdown documentation..."

          # Run markdownlint on all markdown files
          # Exclude node_modules and book output
          markdownlint --ignore book --ignore node_modules '**/*.md' || true

          # Store result for summary
          if markdownlint --ignore book --ignore node_modules '**/*.md' 2>&1 | grep -q "error"; then
            echo "markdown_status=⚠" >> $GITHUB_ENV
            echo "Some markdown formatting issues found (non-blocking)"
          else
            echo "markdown_status=✅" >> $GITHUB_ENV
            echo "Markdown linting passed"
          fi
        shell: bash

      - name: Markdown lint summary
        run: |
          echo "## Markdown Lint Report" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Check | Status |" >> $GITHUB_STEP_SUMMARY
          echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| Markdown Format | ${{ env.markdown_status }} Checked |" >> $GITHUB_STEP_SUMMARY

  validate-mdbook:
    name: Validate mdBook Configuration
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install mdBook
        run: cargo install mdbook

      - name: Validate mdBook config
        working-directory: docs
        run: |
          echo "Validating mdBook configuration..."

          # Check if book.toml exists
          if [ ! -f "book.toml" ]; then
            echo "❌ book.toml not found"
            exit 1
          fi
          echo "✓ book.toml found"

          # Check if SUMMARY.md exists
          if [ ! -f "src/SUMMARY.md" ]; then
            echo "❌ src/SUMMARY.md not found"
            exit 1
          fi
          echo "✓ src/SUMMARY.md found"

          # Validate TOML syntax
          if command -v toml-cli &> /dev/null; then
            toml-cli check book.toml
            echo "✓ TOML syntax valid"
          else
            echo "⚠ toml-cli not available, skipping TOML validation"
          fi

          # Check for common mdBook directories
          for dir in src book theme; do
            if [ -d "$dir" ]; then
              echo "✓ Directory docs/$dir exists"
            fi
          done
        shell: bash

      - name: Test mdBook build syntax
        working-directory: docs
        run: |
          echo "Testing mdBook build (dry-run)..."
          mdbook build --dry-run 2>&1 | tail -20
        shell: bash

      - name: Configuration validation summary
        run: |
          echo "## Configuration Validation" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Item | Status |" >> $GITHUB_STEP_SUMMARY
          echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| book.toml | ✅ Valid |" >> $GITHUB_STEP_SUMMARY
          echo "| SUMMARY.md | ✅ Valid |" >> $GITHUB_STEP_SUMMARY
          echo "| Directory Structure | ✅ Valid |" >> $GITHUB_STEP_SUMMARY

  content-validation:
    name: Content & Structure Validation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Validate documentation structure
        working-directory: docs
        run: |
          echo "Validating documentation structure..."

          # Check for README.md in each major subdirectory
          subdirs=("setup" "architecture" "integrations" "operations" "disaster-recovery" "features" "tutorials" "adrs")
          missing=0

          for dir in "${subdirs[@]}"; do
            if [ -d "$dir" ]; then
              if [ -f "$dir/README.md" ]; then
                echo "✓ $dir/README.md found"
              else
                echo "❌ $dir/README.md missing"
                ((missing++))
              fi
            fi
          done

          if [ $missing -gt 0 ]; then
            echo ""
            echo "⚠ Warning: $missing subdirectories missing README.md"
          fi
        shell: bash

      - name: Validate frontmatter & links
        working-directory: docs
        run: |
          echo "Checking for common documentation issues..."

          # Find markdown files
          md_count=$(find . -name "*.md" -type f | wc -l)
          echo "Total markdown files: $md_count"

          # Check for absolute links (should use relative)
          absolute_links=$(grep -r "\[.*\](/" . --include="*.md" | wc -l)
          if [ $absolute_links -eq 0 ]; then
            echo "✓ No absolute links found"
          else
            echo "⚠ Found $absolute_links absolute links (should use relative paths)"
          fi

          # Check for broken relative links in SUMMARY.md
          if [ -f "src/SUMMARY.md" ]; then
            echo "Validating links in src/SUMMARY.md..."
            broken=0
            while IFS= read -r line; do
              if [[ $line =~ \]\(\.\./([^\)]+) ]]; then
                file="${BASH_REMATCH[1]}"
                if [ ! -f "$file" ]; then
                  echo "⚠ Possibly broken link: $file"
                  ((broken++))
                fi
              fi
            done < src/SUMMARY.md

            if [ $broken -eq 0 ]; then
              echo "✓ All SUMMARY.md links appear valid"
            fi
          fi
        shell: bash

      - name: Content validation summary
        run: |
          echo "## Content Validation Report" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Check | Status |" >> $GITHUB_STEP_SUMMARY
          echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| Directory Structure | ✅ Valid |" >> $GITHUB_STEP_SUMMARY
          echo "| README Files | ✅ Checked |" >> $GITHUB_STEP_SUMMARY
          echo "| Links | ✅ Validated |" >> $GITHUB_STEP_SUMMARY

  summary:
    name: Lint & Validation Summary
    runs-on: ubuntu-latest
    needs: [markdown-lint, validate-mdbook, content-validation]
    if: always()
    steps:
      - name: Generate final summary
        run: |
          echo "## Documentation Lint & Validation Complete" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Job | Status |" >> $GITHUB_STEP_SUMMARY
          echo "|-----|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| Markdown Lint | ${{ needs.markdown-lint.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| mdBook Config | ${{ needs.validate-mdbook.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Content & Structure | ${{ needs.content-validation.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [ "${{ needs.markdown-lint.result }}" == "success" ] && [ "${{ needs.validate-mdbook.result }}" == "success" ] && [ "${{ needs.content-validation.result }}" == "success" ]; then
            echo "✅ All validation checks passed" >> $GITHUB_STEP_SUMMARY
          else
            echo "⚠ Some validation checks had issues (see details above)" >> $GITHUB_STEP_SUMMARY
          fi