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/11_agents/**/*.md
              docs/agent-sdk/**/*.md
              docs/blockchain/**/*.md
              docs/deployment/**/*.md
              docs/development/**/*.md
              docs/general/**/*.md
              docs/governance/**/*.md
              docs/implementation/**/*.md
              docs/infrastructure/**/*.md
              docs/openclaw/**/*.md
              docs/policies/**/*.md
              docs/security/**/*.md
              docs/workflows/**/*.md
            )

            if [[ ${#targets[@]} -eq 0 ]]; then
              echo "⚠️ No curated Markdown targets matched"
            else
              echo "Curated advisory scope: ${#targets[@]} Markdown files"
              echo "Excluded high-noise areas: about, advanced, archive, backend, beginner, completed, expert, intermediate, project, reports, summaries, trail"
              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 ==="
          for f in docs/README.md docs/MASTER_INDEX.md; do
            if [[ -f "$f" ]]; then
              echo "  ✅ $f exists"
            else
              echo "  ❌ $f missing"
            fi
          done

      - 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