Merge pull request #254 from Hack23/dependabot/github_actions/actions… #51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: JSDoc Documentation Validation | |
| # Trigger on changes to JavaScript files in key directories | |
| on: | |
| push: | |
| branches: [main, develop, 'copilot/**'] | |
| paths: | |
| - 'js/**/*.js' | |
| - 'dashboard/**/*.js' | |
| - 'scripts/**/*.js' | |
| - 'jsdoc.json' | |
| - 'tests/jsdoc-validation.test.js' | |
| - '.github/workflows/jsdoc-validation.yml' | |
| pull_request: | |
| branches: [main, develop] | |
| paths: | |
| - 'js/**/*.js' | |
| - 'dashboard/**/*.js' | |
| - 'scripts/**/*.js' | |
| - 'jsdoc.json' | |
| - 'tests/jsdoc-validation.test.js' | |
| workflow_dispatch: # Allow manual trigger | |
| permissions: | |
| contents: write # Allow committing generated API docs | |
| pull-requests: read | |
| jobs: | |
| jsdoc-generation: | |
| name: Generate & Validate JSDoc | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 | |
| steps: | |
| - name: Harden Runner | |
| uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 | |
| with: | |
| egress-policy: audit | |
| - name: Checkout Repository | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| - name: Setup Node.js 24 | |
| uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0 | |
| with: | |
| node-version: '24' | |
| cache: 'npm' | |
| - name: Install Dependencies | |
| run: | | |
| npm ci | |
| npm list jsdoc || echo "JSDoc not yet installed" | |
| - name: Generate JSDoc Documentation | |
| id: generate | |
| run: | | |
| echo "🔍 Generating JSDoc API documentation..." | |
| npm run jsdoc | |
| echo "✅ JSDoc 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 JSDoc API documentation and sitemap.xml [skip ci] | |
| - Generated from latest JavaScript source code | |
| - Updated sitemap.xml with API documentation URLs | |
| - Includes intelligence operative perspective | |
| - 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 JSDoc" | |
| 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 "✅ JSDoc generated sufficient documentation files" | |
| - name: List Generated Documentation | |
| run: | | |
| echo "📋 Generated JSDoc 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 JSDoc Validation Tests | |
| run: | | |
| echo "🧪 Running JSDoc validation test suite..." | |
| npm run jsdoc:validate || npm run test tests/jsdoc-validation.test.js | |
| - name: Check JSDoc Coverage in Source Files | |
| run: | | |
| echo "📊 Checking JSDoc coverage in source files..." | |
| # Count JavaScript files | |
| TOTAL_JS=$(find js dashboard scripts -name "*.js" ! -name "*.min.js" ! -path "*/lib/*" | wc -l) | |
| # Count files with JSDoc (/** */) | |
| FILES_WITH_JSDOC=$(find js dashboard scripts -name "*.js" ! -name "*.min.js" ! -path "*/lib/*" -exec grep -l "/\*\*" {} \; | wc -l) | |
| echo "📈 JSDoc Coverage: $FILES_WITH_JSDOC / $TOTAL_JS files" | |
| if [ "$TOTAL_JS" -gt 0 ]; then | |
| COVERAGE_PERCENT=$((FILES_WITH_JSDOC * 100 / TOTAL_JS)) | |
| 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 JSDoc Artifacts | |
| uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0 | |
| if: always() | |
| with: | |
| name: jsdoc-api-docs | |
| path: api/ | |
| retention-days: 30 | |
| - name: Generate Summary | |
| if: always() | |
| run: | | |
| echo "## 📚 JSDoc 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 "✅ **JSDoc Generation**: Success" >> $GITHUB_STEP_SUMMARY | |
| echo "📄 **Generated Files**: $HTML_COUNT HTML documents" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "❌ **JSDoc 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 |