aitbc/.gitea/workflows/docs-validation.yml

name: Documentation Validation

on:
  push:
    branches: [main, develop]
    paths:
      - 'docs/**'
      - '*.md'
      - '.gitea/workflows/docs-validation.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'docs/**'
      - '*.md'
      - '.gitea/workflows/docs-validation.yml'
  workflow_dispatch:

concurrency:
  group: docs-validation-${{ github.ref }}
  cancel-in-progress: true

jobs:
  validate-docs:
    runs-on: debian
    timeout-minutes: 10

    steps:
      - name: Clone repository
        run: |
          WORKSPACE="/var/lib/aitbc-workspaces/docs-validation"
          rm -rf "$WORKSPACE"
          mkdir -p "$WORKSPACE"
          cd "$WORKSPACE"
          git clone --depth 1 http://gitea.bubuit.net:3000/oib/aitbc.git repo

      - name: Initialize job logging
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation/repo
          bash scripts/ci/setup-job-logging.sh

      - name: Install tools
        run: |
          npm install -g markdownlint-cli 2>/dev/null || echo "⚠️ markdownlint not installed"

      - name: Lint Markdown files
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation/repo
          
          # Ensure standard directories exist
          mkdir -p /var/lib/aitbc/data /var/lib/aitbc/keystore /etc/aitbc /var/log/aitbc
          
          echo "=== Linting Markdown ==="
          if command -v markdownlint >/dev/null 2>&1; then
            shopt -s globstar nullglob
            targets=(
              *.md
              docs/*.md
              docs/about/**/*.md
              docs/agents/**/*.md
              docs/agent-sdk/**/*.md
              docs/advanced/**/*.md
              docs/analytics/**/*.md
              docs/apps/**/*.md
              docs/archive/**/*.md
              docs/backend/**/*.md
              docs/beginner/**/*.md
              docs/blockchain/**/*.md
              docs/completed/**/*.md
              docs/contracts/**/*.md
              docs/cli-technical/README.md
              docs/deployment/**/*.md
              docs/development/**/*.md
              docs/exchange/**/*.md
              docs/expert/**/*.md
              docs/general/**/*.md
              docs/governance/**/*.md
              docs/guides/**/*.md
              docs/implementation/**/*.md
              docs/infrastructure/**/*.md
              docs/intermediate/**/*.md
              docs/mobile/**/*.md
              docs/nodes/**/*.md
              docs/maintenance/**/*.md
              docs/openclaw/**/*.md
              docs/policies/**/*.md
              docs/reference/**/*.md
              docs/releases/**/*.md
              docs/reports/**/*.md
              docs/project/**/*.md
              docs/security/**/*.md
              docs/summaries/**/*.md
              docs/trail/**/*.md
              docs/testing/README.md
              docs/website/**/*.md
              docs/workflows/**/*.md
            )

            if [[ ${#targets[@]} -eq 0 ]]; then
              echo "⚠️ No curated Markdown targets matched"
            else
              echo "Curated advisory scope: ${#targets[@]} Markdown files"
              echo "Included the docs home, about hub, learning paths, and the top-level operational hubs added during remediation"
              markdownlint "${targets[@]}" --ignore "node_modules/**" || echo "⚠️ Markdown linting warnings in curated docs scope"
            fi
          else
            echo "⚠️ markdownlint not available, skipping"
          fi
          echo "✅ Markdown linting completed"

      - name: Check documentation structure
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation/repo
          echo "=== Documentation Structure ==="
          required_files=(
            docs/README.md
            docs/MASTER_INDEX.md
            docs/about/README.md
            docs/agents/README.md
            docs/advanced/README.md
            docs/analytics/README.md
            docs/agent-sdk/README.md
            docs/apps/README.md
            docs/archive/README.md
            docs/archive/completed/README.md
            docs/archive/summaries/README.md
            docs/backend/README.md
            docs/beginner/README.md
            docs/blockchain/README.md
            docs/contracts/README.md
            docs/cli-technical/README.md
            docs/deployment/README.md
            docs/development/README.md
            docs/exchange/README.md
            docs/expert/README.md
            docs/general/README.md
            docs/guides/README.md
            docs/governance/README.md
            docs/implementation/README.md
            docs/infrastructure/README.md
            docs/intermediate/README.md
            docs/maintenance/README.md
            docs/mobile/README.md
            docs/nodes/README.md
            docs/openclaw/README.md
            docs/packages/README.md
            docs/policies/README.md
            docs/project/README.md
            docs/reference/README.md
            docs/releases/README.md
            docs/reports/README.md
            docs/security/README.md
            docs/trail/README.md
            docs/testing/README.md
            docs/website/README.md
            docs/workflows/README.md
          )

          for f in "${required_files[@]}"; do
            if [[ -f "$f" ]]; then
              echo "  $f exists"
            else
              echo "  $f missing"
              echo "  ❌ $f missing"
              exit 1
            fi
          done

      - name: Validate master index structure
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation/repo
          echo "=== Master Index Structure ==="

          master_index_markers=(
            "## 📦 **Applications Documentation**"
            "## 🏠 **Main Documentation**"
            "## 🔗 **External Documentation (Symlinks)**"
            "## 🎯 **Topic-Specific Areas**"
          )

          for marker in "${master_index_markers[@]}"; do
            if ! grep -qF "$marker" docs/MASTER_INDEX.md; then
              echo "  ❌ docs/MASTER_INDEX.md missing required marker: $marker"
              exit 1
            fi
          done

          echo "✅ Master index structure validated"

      - name: Validate priority docs metadata
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation/repo
          echo "=== Priority Documentation Metadata ==="

          priority_docs=(
            docs/README.md
            docs/about/README.md
            docs/beginner/README.md
            docs/intermediate/README.md
            docs/expert/README.md
            docs/project/README.md
            docs/apps/README.md
            docs/cli-technical/README.md
            docs/testing/README.md
          )

          required_markers=(
            "## 🧭 **Navigation Path:**"
            "## 🎯 **See Also:**"
            "**Level**:"
            "**Prerequisites**:"
            "**Estimated Time**:"
            "**Last Updated**:"
            "**Version**:"
          )

          for f in "${priority_docs[@]}"; do
            if [[ ! -f "$f" ]]; then
              echo "  ❌ $f missing"
              exit 1
            fi

            for marker in "${required_markers[@]}"; do
              if ! grep -qF "$marker" "$f"; then
                echo "  ❌ $f missing required marker: $marker"
                exit 1
              fi
            done
          done

          echo "✅ Priority documentation metadata validated"

      - name: Documentation stats
        if: always()
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation/repo
          echo "=== Documentation Statistics ==="
          echo "  Markdown files: $(find docs -name '*.md' 2>/dev/null | wc -l)"
          echo "  Total size: $(du -sh docs 2>/dev/null | cut -f1)"
          echo "  Categories: $(ls -1 docs 2>/dev/null | wc -l)"

      - name: Cleanup
        if: always()
        run: rm -rf /var/lib/aitbc-workspaces/docs-validation

  validate-policies-strict:
    runs-on: debian
    timeout-minutes: 10

    steps:
      - name: Clone repository
        run: |
          WORKSPACE="/var/lib/aitbc-workspaces/docs-validation-policies"
          rm -rf "$WORKSPACE"
          mkdir -p "$WORKSPACE"
          cd "$WORKSPACE"
          git clone --depth 1 http://gitea.bubuit.net:3000/oib/aitbc.git repo

      - name: Initialize job logging
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation-policies/repo
          bash scripts/ci/setup-job-logging.sh

      - name: Install markdownlint
        run: |
          npm install -g markdownlint-cli

      - name: Strict lint policy docs
        run: |
          cd /var/lib/aitbc-workspaces/docs-validation-policies/repo

          # Ensure standard directories exist
          mkdir -p /var/lib/aitbc/data /var/lib/aitbc/keystore /etc/aitbc /var/log/aitbc

          shopt -s globstar nullglob
          mapfile -t targets < <(printf '%s\n' docs/policies/*.md docs/policies/**/*.md | awk '!seen[$0]++')

          if [[ ${#targets[@]} -eq 0 ]]; then
            echo "❌ No policy Markdown files found"
            exit 1
          fi

          echo "Strict docs scope: ${#targets[@]} policy Markdown files"
          markdownlint "${targets[@]}"
          echo "✅ Policy docs lint passed"

      - name: Cleanup
        if: always()
        run: rm -rf /var/lib/aitbc-workspaces/docs-validation-policies