🚀 Fix GitHub Actions workflows and enhance code quality #4
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: Documentation | |
| on: | |
| push: | |
| branches: [master, develop] | |
| paths: | |
| - "README.md" | |
| - "CHANGELOG.md" | |
| - "docs/**" | |
| - "src/**/*.php" | |
| - ".github/workflows/docs.yml" | |
| pull_request: | |
| branches: [master, develop] | |
| paths: | |
| - "README.md" | |
| - "CHANGELOG.md" | |
| - "docs/**" | |
| - "src/**/*.php" | |
| - ".github/workflows/docs.yml" | |
| workflow_dispatch: | |
| jobs: | |
| validate-markdown: | |
| name: Validate Markdown | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: "18" | |
| - name: Install markdown tools | |
| run: | | |
| npm install -g markdownlint-cli | |
| continue-on-error: true | |
| - name: Lint Markdown files | |
| run: | | |
| echo "## 📝 Markdown Validation" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| # Create basic markdownlint config | |
| cat > .markdownlint.json << 'EOF' | |
| { | |
| "MD013": false, | |
| "MD033": false, | |
| "MD041": false | |
| } | |
| EOF | |
| if command -v markdownlint >/dev/null 2>&1; then | |
| if markdownlint README.md CHANGELOG.md 2>/dev/null; then | |
| echo "✅ All markdown files are valid" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "⚠️ Some markdown issues found (non-blocking)" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| else | |
| echo "⏭️ Markdownlint not available, skipping check" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| continue-on-error: true | |
| validate-readme: | |
| name: Validate README Structure | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Check README structure | |
| run: | | |
| echo "## 📖 README Structure Validation" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| if [ ! -f README.md ]; then | |
| echo "❌ README.md not found" >> $GITHUB_STEP_SUMMARY | |
| exit 1 | |
| fi | |
| # Check for required sections | |
| REQUIRED_SECTIONS=("Installation" "Configuration" "Usage") | |
| MISSING_SECTIONS=() | |
| for section in "${REQUIRED_SECTIONS[@]}"; do | |
| if ! grep -qi "## .*$section\|# .*$section" README.md; then | |
| MISSING_SECTIONS+=("$section") | |
| fi | |
| done | |
| if [ ${#MISSING_SECTIONS[@]} -eq 0 ]; then | |
| echo "✅ All required sections found in README" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "⚠️ Missing sections in README:" >> $GITHUB_STEP_SUMMARY | |
| for section in "${MISSING_SECTIONS[@]}"; do | |
| echo "- $section" >> $GITHUB_STEP_SUMMARY | |
| done | |
| fi | |
| # Count documentation metrics | |
| README_LINES=$(wc -l < README.md) | |
| CODE_BLOCKS=$(grep -c '```' README.md || echo 0) | |
| IMAGES=$(grep -c '!\[' README.md || echo 0) | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "### 📊 Documentation Metrics" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Lines**: $README_LINES" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Code examples**: $((CODE_BLOCKS / 2))" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Images/badges**: $IMAGES" >> $GITHUB_STEP_SUMMARY | |
| check-changelog: | |
| name: Check Changelog | |
| runs-on: ubuntu-latest | |
| if: github.event_name == 'pull_request' | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Check if CHANGELOG.md was updated | |
| run: | | |
| echo "## 📋 Changelog Check" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| if git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "CHANGELOG.md"; then | |
| echo "✅ CHANGELOG.md has been updated" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "⚠️ CHANGELOG.md was not updated in this PR" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "Consider adding an entry if this PR includes:" >> $GITHUB_STEP_SUMMARY | |
| echo "- New features" >> $GITHUB_STEP_SUMMARY | |
| echo "- Bug fixes" >> $GITHUB_STEP_SUMMARY | |
| echo "- Breaking changes" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| validate-changelog-format: | |
| name: Validate Changelog Format | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Validate changelog format | |
| run: | | |
| echo "## 📄 Changelog Format Validation" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| if [ ! -f CHANGELOG.md ]; then | |
| echo "❌ CHANGELOG.md file not found" >> $GITHUB_STEP_SUMMARY | |
| exit 1 | |
| fi | |
| # Check for "Unreleased" section | |
| if grep -q "## \[Unreleased\]\|## Unreleased" CHANGELOG.md; then | |
| echo "✅ Unreleased section found" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "⚠️ No Unreleased section found" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| # Check for version entries | |
| VERSION_COUNT=$(grep -c "## \[[0-9]\+\.[0-9]\+\.[0-9]\+\]\|## [0-9]\+\.[0-9]\+\.[0-9]\+" CHANGELOG.md || echo 0) | |
| echo "📋 Found $VERSION_COUNT versioned entries" >> $GITHUB_STEP_SUMMARY | |
| # Check for dates | |
| DATED_ENTRIES=$(grep -c "[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}" CHANGELOG.md || echo 0) | |
| echo "📅 Found $DATED_ENTRIES entries with dates" >> $GITHUB_STEP_SUMMARY | |
| generate-api-docs: | |
| name: Generate API Documentation | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Setup PHP | |
| uses: shivammathur/setup-php@v2 | |
| with: | |
| php-version: "8.1" | |
| - name: Generate simple API documentation | |
| run: | | |
| mkdir -p docs/api | |
| echo "## 🔧 API Documentation Generation" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| # Create a simple API documentation | |
| cat > docs/api/README.md << 'EOF' | |
| # API Documentation | |
| This document provides an overview of the Magento 2 Prometheus Exporter API. | |
| ## Classes Overview | |
| EOF | |
| # Find PHP classes and generate basic documentation | |
| find src/ -name "*.php" -type f | while read file; do | |
| class_name=$(grep -o "class [A-Za-z0-9_]*" "$file" | head -1 | cut -d' ' -f2) | |
| if [ -n "$class_name" ]; then | |
| echo "### $class_name" >> docs/api/README.md | |
| echo "" >> docs/api/README.md | |
| echo "**File**: \`$file\`" >> docs/api/README.md | |
| echo "" >> docs/api/README.md | |
| # Extract class comment if exists | |
| if grep -B 10 "class $class_name" "$file" | grep -q "/\*\*"; then | |
| echo "**Description**: Available in source code" >> docs/api/README.md | |
| fi | |
| echo "" >> docs/api/README.md | |
| fi | |
| done | |
| echo "*Generated automatically by GitHub Actions*" >> docs/api/README.md | |
| echo "✅ API documentation generated" >> $GITHUB_STEP_SUMMARY | |
| - name: Upload API docs artifact | |
| uses: actions/upload-artifact@v3 | |
| with: | |
| name: api-documentation | |
| path: docs/ | |
| retention-days: 30 | |
| spell-check: | |
| name: Basic Spell Check | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Install aspell | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y aspell aspell-en | |
| continue-on-error: true | |
| - name: Create technical dictionary | |
| run: | | |
| cat > .aspell.en.pws << 'EOF' | |
| personal_ws-1.1 en 50 | |
| Magento | |
| magento | |
| Prometheus | |
| prometheus | |
| exporter | |
| PHPUnit | |
| phpunit | |
| Packagist | |
| packagist | |
| Codecov | |
| GitHub | |
| workflow | |
| API | |
| APIs | |
| JSON | |
| YAML | |
| HTTP | |
| HTTPS | |
| URL | |
| URLs | |
| cron | |
| cronjob | |
| admin | |
| PSR | |
| autoloader | |
| EOF | |
| - name: Check spelling | |
| run: | | |
| echo "## 🔤 Spell Check Results" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| MISSPELLED_COUNT=0 | |
| # Check README.md if aspell is available | |
| if command -v aspell >/dev/null 2>&1 && [ -f README.md ]; then | |
| cat README.md | \ | |
| sed '/```/,/```/d' | \ | |
| sed 's/http[s]\?:\/\/[^ ]*//g' | \ | |
| sed 's/`[^`]*`//g' | \ | |
| aspell --personal=./.aspell.en.pws --mode=markdown list > readme.misspelled 2>/dev/null || true | |
| if [ -s readme.misspelled ]; then | |
| MISSPELLED_COUNT=$((MISSPELLED_COUNT + $(wc -l < readme.misspelled))) | |
| fi | |
| rm -f readme.misspelled | |
| if [ $MISSPELLED_COUNT -eq 0 ]; then | |
| echo "✅ No obvious spelling issues found" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "⚠️ Possible spelling issues found (review recommended)" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| else | |
| echo "⏭️ Spell check skipped (aspell not available or no README)" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| continue-on-error: true | |
| generate-metrics-docs: | |
| name: Generate Metrics Documentation | |
| runs-on: ubuntu-latest | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/master' | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Generate metrics documentation | |
| run: | | |
| mkdir -p docs/metrics | |
| cat > docs/metrics/available-metrics.md << 'EOF' | |
| # Available Metrics | |
| This document lists metrics available in the Magento 2 Prometheus Exporter. | |
| ## Metric Categories | |
| ### Order Metrics | |
| - Order counts by status | |
| - Revenue metrics | |
| - Order item counts | |
| ### Product Metrics | |
| - Product counts by type | |
| - Category metrics | |
| - Inventory levels | |
| ### Customer Metrics | |
| - Customer registration counts | |
| - Customer activity | |
| ### System Metrics | |
| - Cron job status | |
| - Indexer status | |
| - Cache metrics | |
| ### CMS Metrics | |
| - CMS page counts | |
| - CMS block counts | |
| ## Metric Collection | |
| Metrics are collected via cron jobs and aggregated for performance. | |
| The `/metrics` endpoint serves data in Prometheus format. | |
| EOF | |
| # Find aggregator classes and document them | |
| if [ -d "src/" ]; then | |
| echo "## Aggregator Classes" >> docs/metrics/available-metrics.md | |
| echo "" >> docs/metrics/available-metrics.md | |
| find src/ -name "*Aggregator.php" -type f | while read file; do | |
| class_name=$(basename "$file" .php) | |
| echo "### $class_name" >> docs/metrics/available-metrics.md | |
| echo "**Source**: \`$file\`" >> docs/metrics/available-metrics.md | |
| echo "" >> docs/metrics/available-metrics.md | |
| done | |
| fi | |
| echo "" >> docs/metrics/available-metrics.md | |
| echo "*Last updated: $(date)*" >> docs/metrics/available-metrics.md | |
| echo "✅ Metrics documentation generated" >> $GITHUB_STEP_SUMMARY | |
| - name: Commit documentation updates | |
| run: | | |
| git config --local user.email "[email protected]" | |
| git config --local user.name "GitHub Action" | |
| if [ -d "docs/" ]; then | |
| git add docs/ | |
| if ! git diff --staged --quiet; then | |
| git commit -m "docs: auto-update generated documentation [skip ci]" | |
| git push | |
| echo "✅ Documentation updated and committed" >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "ℹ️ No documentation changes to commit" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| fi | |
| documentation-summary: | |
| name: Documentation Summary | |
| runs-on: ubuntu-latest | |
| needs: | |
| [ | |
| validate-markdown, | |
| validate-readme, | |
| check-changelog, | |
| validate-changelog-format, | |
| generate-api-docs, | |
| spell-check, | |
| ] | |
| if: always() | |
| steps: | |
| - name: Generate summary | |
| run: | | |
| echo "## 📚 Documentation Workflow Summary" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "| Check | Status |" >> $GITHUB_STEP_SUMMARY | |
| echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY | |
| echo "| Markdown Validation | ${{ needs.validate-markdown.result == 'success' && '✅ Pass' || '⚠️ Issues' }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| README Structure | ${{ needs.validate-readme.result == 'success' && '✅ Pass' || '❌ Fail' }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Changelog Check | ${{ needs.check-changelog.result == 'success' && '✅ Updated' || needs.check-changelog.result == 'skipped' && '⏭️ Skipped' || '⚠️ Not Updated' }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Changelog Format | ${{ needs.validate-changelog-format.result == 'success' && '✅ Valid' || '❌ Invalid' }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| API Documentation | ${{ needs.generate-api-docs.result == 'success' && '✅ Generated' || '❌ Failed' }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "| Spell Check | ${{ needs.spell-check.result == 'success' && '✅ Pass' || '⚠️ Issues' }} |" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| # Count critical failures | |
| CRITICAL_FAILURES=0 | |
| if [[ "${{ needs.validate-readme.result }}" != "success" ]]; then | |
| CRITICAL_FAILURES=$((CRITICAL_FAILURES + 1)) | |
| fi | |
| if [[ "${{ needs.validate-changelog-format.result }}" != "success" ]]; then | |
| CRITICAL_FAILURES=$((CRITICAL_FAILURES + 1)) | |
| fi | |
| if [ $CRITICAL_FAILURES -eq 0 ]; then | |
| echo "### ✅ Documentation Status: GOOD" >> $GITHUB_STEP_SUMMARY | |
| echo "All critical documentation checks passed." >> $GITHUB_STEP_SUMMARY | |
| else | |
| echo "### ❌ Documentation Status: NEEDS ATTENTION" >> $GITHUB_STEP_SUMMARY | |
| echo "$CRITICAL_FAILURES critical documentation issue(s) found." >> $GITHUB_STEP_SUMMARY | |
| fi | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "### 📝 Quick Fix Tips" >> $GITHUB_STEP_SUMMARY | |
| echo "- Ensure README.md has Installation, Configuration, and Usage sections" >> $GITHUB_STEP_SUMMARY | |
| echo "- Keep CHANGELOG.md updated with version entries" >> $GITHUB_STEP_SUMMARY | |
| echo "- Use proper Markdown formatting" >> $GITHUB_STEP_SUMMARY | |
| echo "- Include code examples in documentation" >> $GITHUB_STEP_SUMMARY |