homelab/.github/workflows/documentation.yml

name: Documentation Checks

on:
  pull_request:
    paths:
      - '**.md'
      - 'compose/**/*.yaml'
      - '.github/workflows/documentation.yml'
  push:
    branches:
      - main

jobs:
  markdown-lint:
    name: Markdown Linting
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Lint Markdown files
        uses: nosborn/github-action-markdown-cli@v3.3.0
        with:
          files: .
          config_file: .markdownlint.json
          ignore_files: node_modules/
        continue-on-error: true  # Don't fail CI on markdown issues

  link-check:
    name: Check Links in Documentation
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Check links in README
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'
          config-file: '.markdown-link-check.json'
        continue-on-error: true

  readme-sync:
    name: Validate README is up-to-date
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Check README completeness
        run: |
          echo "Checking if README.md documents all services..."

          # Extract service names from compose files
          services=$(find compose -name "compose.yaml" -exec dirname {} \; | \
            sed 's|compose/||' | \
            sort -u)

          echo "Services found in repository:"
          echo "$services"

          missing_services=""

          # Check if each service is mentioned in README
          while IFS= read -r service; do
            service_name=$(basename "$service")

            if ! grep -qi "$service_name" README.md; then
              echo "⚠️  Service '$service_name' not found in README.md"
              missing_services="${missing_services}${service}\n"
            fi
          done <<< "$services"

          if [ -n "$missing_services" ]; then
            echo ""
            echo "⚠️  The following services are not documented in README.md:"
            echo -e "$missing_services"
            echo ""
            echo "This is a warning. Consider updating the README."
          else
            echo "✅ All services are documented in README.md"
          fi          

      - name: Check for required sections
        run: |
          echo "Checking for required README sections..."

          required_sections=(
            "Infrastructure"
            "Directory Structure"
            "Domains"
            "Deployment"
            "Security"
          )

          missing_sections=""

          for section in "${required_sections[@]}"; do
            if ! grep -qi "$section" README.md; then
              echo "❌ Missing section: $section"
              missing_sections="${missing_sections}${section}\n"
            else
              echo "✅ Found section: $section"
            fi
          done

          if [ -n "$missing_sections" ]; then
            echo ""
            echo "❌ Missing required sections in README.md:"
            echo -e "$missing_sections"
            exit 1
          fi          

  service-documentation:
    name: Check Service Documentation
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Check for service-level documentation
        run: |
          echo "Checking that compose files have documentation comments..."

          compose_files=$(find compose -name "compose.yaml" -type f)

          for file in $compose_files; do
            # Check if file has a comment at the top
            if head -n 1 "$file" | grep -q "^#"; then
              echo "✅ $file has documentation"
            else
              echo "⚠️  $file missing documentation header"
            fi

            # Check for docs URLs
            if grep -q "# Docs:" "$file"; then
              echo "  ✅ Has docs link"
            fi
          done          

      - name: Validate domain URLs in README
        run: |
          echo "Validating service URLs in README match compose files..."

          # Extract URLs from README (simple check)
          readme_domains=$(grep -oP '\b\w+\.fig\.systems\b' README.md | sort -u)

          echo "Domains in README:"
          echo "$readme_domains"

          # Extract domains from compose files
          compose_domains=$(grep -h "rule: Host" compose/**/compose.yaml | \
            grep -oP '\b\w+\.fig\.systems\b' | \
            sort -u)

          echo ""
          echo "Domains in compose files:"
          echo "$compose_domains"

          # Basic comparison
          readme_count=$(echo "$readme_domains" | wc -l)
          compose_count=$(echo "$compose_domains" | wc -l)

          echo ""
          echo "README domains: $readme_count"
          echo "Compose domains: $compose_count"

          if [ "$readme_count" -ne "$compose_count" ]; then
            echo "⚠️  Domain count mismatch between README and compose files"
            echo "This may indicate outdated documentation."
          else
            echo "✅ Domain counts match"
          fi