documentation-ci.yml

name: Development Documentation CI/CD

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  documentation-quality:
    runs-on: ubuntu-latest
    name: Documentation Quality Assurance
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Python 3.9
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'
    
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install jsonschema
    
    - name: ASCII Compliance Test
      run: |
        echo "Testing ASCII compliance across all files..."
        python validate_ascii.py
        if [ $? -eq 0 ]; then
          echo "[PASS] All files are ASCII-compliant"
        else
          echo "[FAIL] ASCII compliance test failed"
          exit 1
        fi
    
    - name: Development Blog Validation
      run: |
        echo "Validating development blog completeness..."
        
        # Check DEVBLOG.md exists and has recent updates
        if [ ! -f "DEVBLOG.md" ]; then
          echo "[FAIL] DEVBLOG.md is missing"
          exit 1
        fi
        
        # Check version file exists
        if [ ! -f "VERSION" ]; then
          echo "[FAIL] VERSION file is missing"
          exit 1
        fi
        
        # Verify DEVBLOG has current version
        CURRENT_VERSION=$(cat VERSION)
        if ! grep -q "$CURRENT_VERSION" DEVBLOG.md; then
          echo "[FAIL] DEVBLOG.md does not reference current version $CURRENT_VERSION"
          exit 1
        fi
        
        echo "[PASS] Development blog validation successful"
    
    - name: Documentation Permanence Test
      run: |
        echo "Testing documentation permanence and accessibility..."
        
        # Required documentation files
        REQUIRED_DOCS=(
          "README.md"
          "DEVBLOG.md" 
          "CROSS_REPO_INTEGRATION.md"
          "REPO_NAVIGATION.md"
          "ASCII_CODING_STANDARDS.md"
        )
        
        for doc in "${REQUIRED_DOCS[@]}"; do
          if [ ! -f "$doc" ]; then
            echo "[FAIL] Required documentation file missing: $doc"
            exit 1
          fi
          
          # Check file is not empty
          if [ ! -s "$doc" ]; then
            echo "[FAIL] Documentation file is empty: $doc"
            exit 1
          fi
        done
        
        echo "[PASS] All required documentation is present and accessible"
    
    - name: Version Consistency Check
      run: |
        echo "Checking version consistency across files..."
        
        CURRENT_VERSION=$(cat VERSION)
        
        # Check setup script has matching version
        if ! grep -q "$CURRENT_VERSION" setup_clean.py; then
          echo "[WARNING] setup_clean.py may need version update"
        fi
        
        # Check integration docs reference current version  
        if ! grep -q "$CURRENT_VERSION" CROSS_REPO_INTEGRATION.md; then
          echo "[WARNING] CROSS_REPO_INTEGRATION.md may need version update"
        fi
        
        echo "[PASS] Version consistency check completed"
    
    - name: JSON Schema Validation
      run: |
        echo "Validating JSON data exports..."
        
        # Test all JSON files are valid
        for json_file in data/events/*.json; do
          if [ -f "$json_file" ]; then
            python -m json.tool "$json_file" > /dev/null
            if [ $? -eq 0 ]; then
              echo "[PASS] Valid JSON: $json_file"
            else
              echo "[FAIL] Invalid JSON: $json_file"
              exit 1
            fi
          fi
        done
        
        echo "[PASS] All JSON exports are valid"
    
    - name: Behavioral Documentation Test
      run: |
        echo "Testing behavioral requirements for documentation..."
        
        # Test 1: Documentation is permanently stored (in git)
        git log --oneline --grep="doc" --grep="documentation" | head -5
        echo "[PASS] Documentation changes are tracked in git history"
        
        # Test 2: Documentation is accessible through GitHub
        echo "Documentation files accessible via GitHub:"
        echo "- README.md: https://github.com/PipFoweraker/pdoom-data/blob/main/README.md"
        echo "- DEVBLOG.md: https://github.com/PipFoweraker/pdoom-data/blob/main/DEVBLOG.md"
        echo "- Integration docs: https://github.com/PipFoweraker/pdoom-data/tree/main/templates"
        echo "[PASS] Documentation is GitHub-accessible"
        
        # Test 3: Documentation follows our quality standards
        WORD_COUNT=$(wc -w < README.md)
        if [ $WORD_COUNT -lt 50 ]; then
          echo "[FAIL] README.md is too brief (less than 50 words)"
          exit 1
        fi
        echo "[PASS] Documentation meets minimum quality standards"
        
        echo "[PASS] All behavioral documentation tests passed"

  version-increment-check:
    runs-on: ubuntu-latest
    name: Version Increment Validation
    if: github.event_name == 'push'
    
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    
    - name: Check Version Increment
      run: |
        echo "Checking if version should be incremented..."
        
        # Get current version
        CURRENT_VERSION=$(cat VERSION)
        echo "Current version: $CURRENT_VERSION"
        
        # Check if this is a significant change requiring version bump
        CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD)
        echo "Changed files: $CHANGED_FILES"
        
        # Check for significant changes
        SIGNIFICANT_CHANGES=0
        
        # New features or major changes
        if echo "$CHANGED_FILES" | grep -E "\.(py|md)$" | grep -v "DEVBLOG.md"; then
          SIGNIFICANT_CHANGES=1
        fi
        
        # If significant changes detected, ensure DEVBLOG was updated
        if [ $SIGNIFICANT_CHANGES -eq 1 ]; then
          if ! echo "$CHANGED_FILES" | grep -q "DEVBLOG.md"; then
            echo "[WARNING] Significant changes detected but DEVBLOG.md not updated"
            echo "Consider updating DEVBLOG.md to document these changes"
          else
            echo "[PASS] DEVBLOG.md updated with significant changes"
          fi
        fi
        
        echo "[PASS] Version increment check completed"

  documentation-publish:
    runs-on: ubuntu-latest
    name: Publish Development Notes
    if: github.ref == 'refs/heads/main'
    needs: [documentation-quality, version-increment-check]
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Generate Build Timestamp
      run: |
        echo "BUILD_TIME=$(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_ENV
        echo "BUILD_SHA=$(git rev-parse --short HEAD)" >> $GITHUB_ENV
    
    - name: Update Build Info
      run: |
        echo "" >> DEVBLOG.md
        echo "---" >> DEVBLOG.md
        echo "**Build Info**: $BUILD_TIME | SHA: $BUILD_SHA" >> DEVBLOG.md
        echo "**CI Status**: All documentation tests passed" >> DEVBLOG.md
        echo "**Permanent URL**: https://github.com/PipFoweraker/pdoom-data/blob/$BUILD_SHA/DEVBLOG.md" >> DEVBLOG.md
    
    - name: Commit Updated Documentation
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add DEVBLOG.md
        if git diff --staged --quiet; then
          echo "No documentation changes to commit"
        else
          git commit -m "docs: Update build info and permanent links [skip ci]"
          git push
        fi