docs-check.yml

# Documentation Quality Check
# Validates documentation links, examples, and structure

name: docs-check

on:
  push:
    branches: [main, fix/*, feat/*]
    paths:
      - 'README.md'
      - 'docs/**.md'
      - 'CLAUDE.md'
      - 'AGENTS.md'
      - 'CONTRIBUTING.md'
      - '.github/workflows/docs-check.yml'
  pull_request:
    branches: [main]
    paths:
      - 'README.md'
      - 'docs/**.md'
      - 'CLAUDE.md'
      - 'AGENTS.md'
      - 'CONTRIBUTING.md'

permissions:
  contents: read

jobs:
  markdown-link-check:
    name: Check Documentation Links
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Link Checker
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'
          use-verbose-mode: 'yes'
          config-file: '.markdown-link-check.json'
          folder-path: 'docs'
          file-extension: '.md'
          check-modified-files-only: 'no'

  docs-structure:
    name: Validate Documentation Structure
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Check DOCUMENTATION_INDEX.md exists
        run: |
          if [ ! -f "docs/DOCUMENTATION_INDEX.md" ]; then
            echo "❌ DOCUMENTATION_INDEX.md not found"
            exit 1
          fi
          echo "✅ DOCUMENTATION_INDEX.md exists"

      - name: Check key documentation files
        run: |
          for file in \
            "README.md" \
            "CLAUDE.md" \
            "AGENTS.md" \
            "CONTRIBUTING.md" \
            "docs/ARCHITECTURE.md" \
            "docs/command_registry.md" \
            "docs/tri27/README.md"
          do
            if [ -f "$file" ]; then
              echo "✅ $file exists"
            else
              echo "❌ $file not found"
              exit 1
            fi
          done

      - name: Check MEMORY.md size
        run: |
          MEMORY_FILE=".claude/projects/-Users-playra-trinity-w1/memory/MEMORY.md"
          if [ -f "$MEMORY_FILE" ]; then
            LINES=$(wc -l < "$MEMORY_FILE")
            echo "MEMORY.md: $LINES lines"
            if [ "$LINES" -gt 250 ]; then
              echo "⚠️ MEMORY.md is $LINES lines (should be <200)"
              echo "Consider moving content to topic files"
            else
              echo "✅ MEMORY.md size OK"
            fi
          fi

  command-examples:
    name: Validate README Command Examples
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Zig
        uses: goto-bus-stop/setup-zig@v2
        with:
          version: 0.15.0

      - name: Build tri CLI
        run: |
          zig build tri

      - name: Test basic commands from README
        run: |
          echo "Testing basic commands..."
          ./zig-out/bin/tri --version || true
          ./zig-out/bin/tri help || true
          ./zig-out/bin/tri constants || true
          echo "✅ Basic commands work"

  docs-index-updated:
    name: Check Documentation Index
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Check DOCUMENTATION_INDEX.md timestamp
        run: |
          if grep -q "Last updated: 2026-03-2[0-9]" docs/DOCUMENTATION_INDEX.md; then
            echo "✅ DOCUMENTATION_INDEX.md timestamp is current (March 2026)"
          else
            echo "⚠️ DOCUMENTATION_INDEX.md may need update"
            echo "Last updated date should be recent"
          fi

      - name: Check for broken section links
        run: |
          cd docs
          for section in $(grep -oP '(?<=^\[)[^\]]+(?=\])' DOCUMENTATION_INDEX.md 2>/dev/null | tr '[:upper:]' '[:lower:]'); do
            if grep -q "^## $section" *.md 2>/dev/null || \
               grep -q "^## $section" DOCUMENTATION_INDEX.md 2>/dev/null; then
              echo "✅ Section: $section"
            else
              echo "⚠️ Section link may be broken: $section"
            fi
          done

  consistency-check:
    name: Documentation Consistency
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Check T-JEPA status consistency
        run: |
          echo "Checking T-JEPA implementation status across docs..."
          TJEPA_FILES="src/hslm/tjepa.zig src/hslm/tjepa_trainer.zig"

          for file in $TJEPA_FILES; do
            if [ -f "$file" ]; then
              echo "✅ $file exists (T-JEPA implemented)"
            else
              echo "❌ $file not found"
              exit 1
            fi
          done

          echo "Note: If T-JEPA files exist, docs should reflect 'implemented' status"

      - name: Check version consistency
        run: |
          VERSION=$(grep -oP 'v\d+\.\d+\.\d+' README.md | head -1)
          if [ -n "$VERSION" ]; then
            echo "Found version: $VERSION"
            echo "✅ Version declared in README.md"
          else
            echo "⚠️ No version found in README.md"
          fi

  summary:
    name: Documentation Check Summary
    runs-on: ubuntu-latest
    needs: [markdown-link-check, docs-structure, command-examples, docs-index-updated, consistency-check]
    if: always()
    steps:
      - name: Summary
        run: |
          echo "# Documentation Check Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Job | Status |" >> $GITHUB_STEP_SUMMARY
          echo "|-----|--------|" >> $GITHUB_STEP_SUMMARY
          echo "| Link Check | ${{ needs.markdown-link-check.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Structure | ${{ needs.docs-structure.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Examples | ${{ needs.command-examples.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Index | ${{ needs.docs-index-updated.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Consistency | ${{ needs.consistency-check.result }} |" >> $GITHUB_STEP_SUMMARY