jsdoc-validation.yml

name: TypeDoc Documentation Validation

# Trigger on changes to source files in key directories
on:
  workflow_dispatch: # Allow manual trigger

permissions:
  contents: write  # Allow committing generated API docs
  pull-requests: read

jobs:
  typedoc-generation:
    name: Generate & Validate TypeDoc
    runs-on: ubuntu-latest
    timeout-minutes: 10
    
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
        with:
          egress-policy: audit
          
      - name: Checkout Repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        
      - name: Setup Node.js 26
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: '26'
          cache: 'npm'
          cache-dependency-path: |
            package-lock.json
            .github/workflows/jsdoc-validation.yml
          
      - name: Install Dependencies
        run: |
          npm ci
          
      - name: Generate TypeDoc Documentation
        id: generate
        run: |
          echo "🔍 Generating TypeDoc API documentation..."
          npm run typedoc
          echo "✅ TypeDoc generation complete"
          
      - name: Update Sitemap
        id: update_sitemap
        run: |
          echo "🗺️ Updating sitemap.xml with API documentation..."
          npm run generate-sitemap
          echo "✅ Sitemap updated"
          
      - name: Commit API Documentation and Sitemap
        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/copilot/'))
        run: |
          # Configure git
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          
          # Check if there are changes to commit
          git add api/ sitemap.xml
          
          if git diff --staged --quiet; then
            echo "📝 No changes to API documentation or sitemap"
          else
            echo "📝 Committing updated API documentation and sitemap..."
            git commit -m "docs: Update TypeDoc API documentation and sitemap.xml [skip ci]
            
            - Generated from latest TypeScript/JavaScript source code
            - Updated sitemap.xml with API documentation URLs
            - Full type-aware documentation with MDN links
            - Deployed via GitHub Pages
            
            Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>"
            
            git push
            echo "✅ API documentation and sitemap committed and pushed"
          fi
          
      - name: Verify api/ Directory Created
        run: |
          if [ ! -d "api" ]; then
            echo "❌ ERROR: api/ directory not created by TypeDoc"
            exit 1
          fi
          echo "✅ api/ directory exists"
          
          # Count generated files
          HTML_COUNT=$(find api -name "*.html" | wc -l)
          echo "📄 Generated $HTML_COUNT HTML documentation files"
          
          if [ "$HTML_COUNT" -lt 5 ]; then
            echo "⚠️ WARNING: Expected at least 5 HTML files, found $HTML_COUNT"
            exit 1
          fi
          
          echo "✅ TypeDoc generated sufficient documentation files"
          
      - name: List Generated Documentation
        run: |
          echo "📝 Generated TypeDoc Files:"
          ls -lh api/ | head -20
          
      - name: Check for index.html
        run: |
          if [ ! -f "api/index.html" ]; then
            echo "❌ ERROR: api/index.html not found"
            exit 1
          fi
          
          FILE_SIZE=$(stat -f%z "api/index.html" 2>/dev/null || stat -c%s "api/index.html")
          echo "✅ api/index.html exists (${FILE_SIZE} bytes)"
          
      - name: Validate Intelligence Terminology
        run: |
          echo "🔍 Validating intelligence operative perspective in docs..."
          
          # Check for key intelligence terms in index.html
          INTELLIGENCE_FOUND=false
          OSINT_FOUND=false
          RISK_FOUND=false
          
          if grep -qi "intelligence" api/index.html; then
            INTELLIGENCE_FOUND=true
            echo "✅ Found 'intelligence' terminology"
          fi
          
          if grep -qi "osint\|open-source intelligence" api/index.html; then
            OSINT_FOUND=true
            echo "✅ Found 'OSINT' terminology"
          fi
          
          if grep -qi "risk assessment\|risk analysis" api/index.html; then
            RISK_FOUND=true
            echo "✅ Found 'risk assessment' terminology"
          fi
          
          if [ "$INTELLIGENCE_FOUND" = false ] && [ "$OSINT_FOUND" = false ]; then
            echo "⚠️ WARNING: Intelligence terminology not prominent in documentation"
          fi
          
      - name: Run TypeDoc Validation Tests
        run: |
          echo "🧪 Running TypeDoc validation test suite..."
          npm run typedoc:validate || npm run test tests/jsdoc-validation.test.js
          
      - name: Check Documentation Coverage in Source Files
        run: |
          echo "📊 Checking documentation coverage in source files..."
          
          # Count source files (JS + TS) across all source directories
          TOTAL_SOURCE_FILES=$(find src/browser scripts \( -name "*.js" -o -name "*.ts" \) | grep -v node_modules | grep -v lib/ | grep -v ".min." | grep -v ".d.ts" | wc -l)
          
          # Count files with doc comments (/** */)
          FILES_WITH_DOC_COMMENTS=$(find src/browser scripts \( -name "*.js" -o -name "*.ts" \) ! -name "*.min.*" ! -name "*.d.ts" ! -path "*/lib/*" -exec grep -l "/\*\*" {} \; | wc -l)
          
          echo "📈 Documentation Coverage: $FILES_WITH_DOC_COMMENTS / $TOTAL_SOURCE_FILES files"
          
          if [ "$TOTAL_SOURCE_FILES" -gt 0 ]; then
            COVERAGE_PERCENT=$((FILES_WITH_DOC_COMMENTS * 100 / TOTAL_SOURCE_FILES))
            echo "📊 Coverage: ${COVERAGE_PERCENT}%"
            
            if [ "$COVERAGE_PERCENT" -lt 50 ]; then
              echo "⚠️ WARNING: JSDoc coverage below 50%"
            elif [ "$COVERAGE_PERCENT" -ge 80 ]; then
              echo "✅ Excellent JSDoc coverage (≥80%)"
            else
              echo "✓ Acceptable JSDoc coverage (≥50%)"
            fi
          fi
          
      - name: Upload TypeDoc Artifacts
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
        with:
          name: typedoc-api-docs
          path: api/
          retention-days: 30
          
      - name: Generate Summary
        if: always()
        run: |
          echo "## 📚 TypeDoc Documentation Validation Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Generation Status" >> $GITHUB_STEP_SUMMARY
          
          if [ -d "api" ]; then
            HTML_COUNT=$(find api -name "*.html" | wc -l)
            echo "✅ **TypeDoc Generation**: Success" >> $GITHUB_STEP_SUMMARY
            echo "📄 **Generated Files**: $HTML_COUNT HTML documents" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ **TypeDoc Generation**: Failed" >> $GITHUB_STEP_SUMMARY
          fi
          
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Intelligence Perspective" >> $GITHUB_STEP_SUMMARY
          echo "Documentation reflects political analyst and intelligence operative perspective." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Artifacts" >> $GITHUB_STEP_SUMMARY
          echo "📦 Generated documentation uploaded as workflow artifact (30-day retention)" >> $GITHUB_STEP_SUMMARY
          
  # Optional: Deploy to GitHub Pages (requires separate branch setup)
  # deploy-docs:
  #   name: Deploy to GitHub Pages
  #   needs: jsdoc-generation
  #   runs-on: ubuntu-latest
  #   if: github.ref == 'refs/heads/main'
  #   steps:
  #     - uses: actions/download-artifact@v4
  #       with:
  #         name: jsdoc-api-docs
  #         path: api/
  #     - uses: peaceiris/actions-gh-pages@v4
  #       with:
  #         github_token: ${{ secrets.GITHUB_TOKEN }}
  #         publish_dir: ./api
  #         destination_dir: api