---
name: 🔄 Continuous Integration
"on":
push:
branches: [main, develop, "feat/**"]
pull_request:
branches: [main, develop]
workflow_dispatch:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
# ============================================================================
# PRE-FLIGHT CHECKS
# ============================================================================
pre-flight:
name: 🚀 Pre-flight Checks
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
should-run-tests: ${{ steps.changes.outputs.should-run-tests }}
should-run-security: ${{ steps.changes.outputs.should-run-security }}
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: 🔍 Detect Changes
id: changes
run: |
# Check if we should run tests based on file changes
# Handle cases where github.event.before might be null
# (new branch, force push, etc.)
BEFORE="${{ github.event.before }}"
if [[ "$BEFORE" == \
"0000000000000000000000000000000000000000" ]] || \
[[ -z "$BEFORE" ]]; then
echo "🔄 New branch or force push detected - running all tests"
echo "should-run-tests=true" >> $GITHUB_OUTPUT
else
# Check for relevant file changes
PATTERN='\.(ts|js|json)$|package\.json|\.github/workflows|scripts/'
if git diff --name-only "$BEFORE" "${{ github.sha }}" | \
grep -E "$PATTERN"; then
echo "📝 Code changes detected - running tests"
echo "should-run-tests=true" >> $GITHUB_OUTPUT
else
echo "📄 Only documentation changes detected - skipping tests"
echo "should-run-tests=false" >> $GITHUB_OUTPUT
fi
fi
# Always run security checks on main/develop, or if package.json
# changed
REF="${{ github.ref }}"
if [[ "$REF" == "refs/heads/main" || \
"$REF" == "refs/heads/develop" ]]; then
echo "should-run-security=true" >> $GITHUB_OUTPUT
elif [[ "$BEFORE" != \
"0000000000000000000000000000000000000000" ]] && \
[[ -n "$BEFORE" ]]; then
PKG_PATTERN='package\.json|package-lock\.json'
if git diff --name-only "$BEFORE" "${{ github.sha }}" | \
grep -E "$PKG_PATTERN"; then
echo "📦 Pkg deps changed, run security"
echo "should-run-security=true" >> $GITHUB_OUTPUT
else
echo "should-run-security=false" >> $GITHUB_OUTPUT
fi
else
echo "should-run-security=false" >> $GITHUB_OUTPUT
fi
- name: 🎯 Pre-flight Check
run: |
echo "✅ Repository checked out successfully"
echo "📊${{ steps.changes.outputs.should-run-tests }}"
echo "🔒 ${{ steps.changes.outputs.should-run-security }}"
dependency-sync:
name: 🔄 Dependency Sync Check
runs-on: ubuntu-latest
needs: pre-flight
if: needs.pre-flight.outputs.should-run-tests == 'true'
timeout-minutes: 5
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
- name: 🟢 Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: 📦 Install Dependencies
run: npm ci --prefer-offline --no-audit
- name: 🔄 Check Package Lock Sync
run: |
echo "🔍 Checking if package.json and package-lock.json are in sync..."
if npm ci --dry-run --prefer-offline --no-audit --ignore-scripts; then
echo "✅ Package files are in sync"
else
echo "⚠️ Package files are out of sync - attempting to fix..."
echo "📦 Running npm install to update lock file..."
npm install --package-lock-only --ignore-scripts
# Check if there are changes to commit
if git diff --exit-code package-lock.json; then
echo "✅ No changes needed to package-lock.json"
else
echo "❌ package-lock.json needs to be updated"
echo "Please run 'npm install' locally and commit the" \
"updated package-lock.json"
git diff package-lock.json
exit 1
fi
fi
# ============================================================================
# QUALITY GATES
# ============================================================================
quality-gates:
name: 🔍 Quality Gates
runs-on: ubuntu-latest
needs: [pre-flight, dependency-sync]
if: needs.pre-flight.outputs.should-run-tests == 'true'
timeout-minutes: 10
strategy:
matrix:
node-version: [18, 20, 22]
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
- name: 🟢 Setup Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: "npm"
registry-url: "https://registry.npmjs.org"
- name: 📦 Install Dependencies
run: |
# Use npm install if ci fails due to sync issues
if ! npm ci --prefer-offline --no-audit --ignore-scripts; then
echo "⚠️ npm ci failed, falling back to npm install..."
npm install --prefer-offline --no-audit --ignore-scripts
fi
echo "✅ Dependencies installed for Node.js ${{ matrix.node-version }}"
- name: 🔨 Build Project
run: |
npm run build
echo "✅ TypeScript compilation successful"
- name: 🧹 ESLint Check
run: |
npm run lint:check
echo "✅ ESLint validation passed"
- name: 💅 Prettier Check
run: |
npm run format:check
echo "✅ Code formatting validated"
- name: 🔍 TypeScript Check
run: |
npm run type-check
echo "✅ TypeScript type checking passed"
- name: ✅ Unit Tests
timeout-minutes: 5
run: |
npm run test:unit:fast
echo "✅ Unit tests completed successfully"
- name: 📋 Package Validation
run: |
npm run validate-package
echo "✅ Package validation completed"
# ============================================================================
# SECURITY SCANNING
# ============================================================================
security-scan:
name: 🔒 Security Scanning
runs-on: ubuntu-latest
needs: [pre-flight, dependency-sync]
if: needs.pre-flight.outputs.should-run-security == 'true'
timeout-minutes: 10
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
- name: 🟢 Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: 📦 Install Dependencies
run: |
# Use npm install if ci fails due to sync issues
if ! npm ci --prefer-offline --no-audit --ignore-scripts; then
echo "⚠️ npm ci failed, falling back to npm install..."
npm install --prefer-offline --no-audit --ignore-scripts
fi
- name: 🔍 Security Audit
run: |
npm run security:check
echo "✅ Security audit completed"
- name: 🔐 Dependency Vulnerability Scan
run: |
npx audit-ci --config .audit-ci.json || \
echo "⚠️ Vulnerabilities found but not blocking"
echo "✅ Dependency scan completed"
# ============================================================================
# INTEGRATION VALIDATION
# ============================================================================
integration-validation:
name: 🔗 Integration Validation
runs-on: ubuntu-latest
needs: [quality-gates]
timeout-minutes: 15
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
- name: 🟢 Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: 📦 Install Dependencies
run: |
# Use npm install if ci fails due to sync issues
if ! npm ci --prefer-offline --no-audit --ignore-scripts; then
echo "⚠️ npm ci failed, falling back to npm install..."
npm install --prefer-offline --no-audit --ignore-scripts
fi
- name: 🔨 Build Project
run: npm run build
- name: 🧪 Run unit tests
run: npm run test:unit
- name: 📊 Generate coverage report
run: npm run test:coverage
- name: 📤 Upload coverage to Codecov
uses: codecov/codecov-action@v4
with:
token: ${{ secrets.CODECOV_TOKEN }}
file: ./coverage/lcov.info
flags: unittests
name: codecov-umbrella
- name: ✅ Check coverage threshold
run: npm run test:coverage:check
# ============================================================================
# DOCUMENTATION & EXAMPLES
# ============================================================================
documentation:
name: 📚 Documentation & Examples
runs-on: ubuntu-latest
needs: [quality-gates]
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
timeout-minutes: 15
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
- name: 🟢 Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: 📦 Install Dependencies
run: |
# Use npm install if ci fails due to sync issues
if ! npm ci --prefer-offline --no-audit --ignore-scripts; then
echo "⚠️ npm ci failed, falling back to npm install..."
npm install --prefer-offline --no-audit --ignore-scripts
fi
- name: 🔨 Build Project
run: npm run build
- name: 🚀 Pre-flight System Check
run: |
npm run pre-flight
echo "✅ Pre-flight checks completed"
- name: 📚 API Documentation Generation
run: |
npm run docs:api
echo "✅ API documentation generated with TypeDoc"
- name: 📖 Interactive Documentation Generation
run: |
npm run docs:generate
echo "✅ Interactive documentation generated successfully"
- name: 🔗 Documentation Link Validation
run: |
npm run docs:test-links
echo "✅ Documentation links validated"
- name: 📋 Example Configuration Validation
run: |
npm run validate:examples
echo "✅ Example configurations validated"
- name: 📤 Upload Documentation Artifacts
uses: actions/upload-artifact@v4
with:
name: documentation-${{ github.sha }}
path: |
docs/api/
docs/api-interactive.html
docs/API_AUTO_GENERATED.md
docs/examples/
retention-days: 30
# ============================================================================
# BUILD ARTIFACTS
# ============================================================================
build-artifacts:
name: 📦 Build Artifacts
runs-on: ubuntu-latest
needs: [quality-gates, security-scan]
if: github.ref == 'refs/heads/main'
timeout-minutes: 10
steps:
- name: 📥 Checkout Repository
uses: actions/checkout@v4
- name: 🟢 Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: 📦 Install Dependencies
run: |
# Use npm install if ci fails due to sync issues
if ! npm ci --prefer-offline --no-audit --ignore-scripts; then
echo "⚠️ npm ci failed, falling back to npm install..."
npm install --prefer-offline --no-audit --ignore-scripts
fi
- name: 🔨 Build Production Assets
run: |
npm run build:clean
npm run build:standalone
npm run build:templates
echo "✅ Production build completed"
- name: 📋 Enhanced Package Validation
run: |
echo "🔍 Running comprehensive package validation..."
npm run validate-package
npm pack --dry-run
echo "✅ Package validation completed"
- name: 📦 Create Distribution Package
run: |
mkdir -p dist/packages
npm pack --pack-destination=dist/packages
echo "✅ Distribution package created"
- name: 📊 Generate Build Report
run: |
echo "# Build Artifacts Report" > build-report.md
echo "" >> build-report.md
echo "## Build Information" >> build-report.md
echo "- **Commit:** ${{ github.sha }}" >> build-report.md
echo "- **Branch:** ${{ github.ref_name }}" >> build-report.md
echo "- **Build Date:** $(date -u)" >> build-report.md
echo "- **Node Version:** $(node --version)" >> build-report.md
echo "- **NPM Version:** $(npm --version)" >> build-report.md
echo "" >> build-report.md
echo "## Artifacts Generated" >> build-report.md
echo "- Standalone distribution in \`dist/\`" >> build-report.md
echo "- Configuration templates in \`templates/\`" >> build-report.md
echo "- API documentation in \`docs/api/\`" >> build-report.md
echo "- NPM package in \`dist/packages/\`" >> build-report.md
echo "" >> build-report.md
echo "## File Sizes" >> build-report.md
if [ -d "dist" ]; then
du -sh dist/* >> build-report.md 2>/dev/null || \
echo "No dist files" >> build-report.md
fi
echo "✅ Build report generated"
- name: 💾 Upload Build Artifacts
uses: actions/upload-artifact@v4
with:
name: build-artifacts-${{ github.sha }}
path: |
build/
dist/
templates/
docs/api/
docs/api-interactive.html
docs/API_AUTO_GENERATED.md
build-report.md
retention-days: 30
compression-level: 6
- name: 💾 Upload Release Assets
if: github.ref == 'refs/heads/main'
uses: actions/upload-artifact@v4
with:
name: release-assets-${{ github.sha }}
path: |
dist/packages/*.tgz
dist/distribution-manifest.json
dist/README-STANDALONE.md
build-report.md
retention-days: 90
# ============================================================================
# CI STATUS SUMMARY
# ============================================================================
ci-status:
name: ✅ CI Status Summary
runs-on: ubuntu-latest
needs:
- pre-flight
- dependency-sync
- quality-gates
- security-scan
- integration-validation
- documentation
- build-artifacts
if: always()
steps:
- name: 📊 CI Results Summary
run: |
echo "## 🔄 CI Pipeline Results" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "| Job | Status |" >> $GITHUB_STEP_SUMMARY
echo "|-----|--------|" >> $GITHUB_STEP_SUMMARY
# Job arrays split for readability
jobs=("pre-flight" "dependency-sync" "quality-gates" \
"security-scan" "integration-validation" \
"documentation" "build-artifacts")
names=("Pre-flight" "Dependency Sync" "Quality Gates" \
"Security Scan" "Integration" "Documentation" \
"Build Artifacts")
# Results array split for readability
results=(
"${{ needs.pre-flight.result }}"
"${{ needs.dependency-sync.result }}"
"${{ needs.quality-gates.result }}"
"${{ needs.security-scan.result }}"
"${{ needs.integration-validation.result }}"
"${{ needs.documentation.result }}"
"${{ needs.build-artifacts.result }}"
)
for i in "${!jobs[@]}"; do
case "${results[$i]}" in
"success")
echo "| ${names[$i]} | ✅ Passed |" >> $GITHUB_STEP_SUMMARY
;;
"skipped")
echo "| ${names[$i]} | ⏭️ Skipped |" >> $GITHUB_STEP_SUMMARY
;;
*)
echo "| ${names[$i]} | ❌ Failed |" >> $GITHUB_STEP_SUMMARY
;;
esac
done
echo "" >> $GITHUB_STEP_SUMMARY
# Check critical jobs status
critical_jobs=(
"${{ needs.pre-flight.result }}"
"${{ needs.dependency-sync.result }}"
"${{ needs.quality-gates.result }}"
"${{ needs.security-scan.result }}"
)
all_critical_ok=true
for result in "${critical_jobs[@]}"; do
if [[ "$result" != "success" && "$result" != "skipped" ]]; then
all_critical_ok=false
break
fi
done
if [[ "$all_critical_ok" == "true" ]]; then
echo "🎉 **CI Pipeline Successful!**" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### 🚀 Next Steps" >> $GITHUB_STEP_SUMMARY
echo "- Run \`npm run pre-push\` locally" >> $GITHUB_STEP_SUMMARY
echo "- Use \`npm run ci-cd:validate\` for release" \
>> $GITHUB_STEP_SUMMARY
else
echo "❌ **CI Pipeline Failed!**" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### 🔧 Troubleshooting" >> $GITHUB_STEP_SUMMARY
echo "- Run \`npm run pre-push\` locally" >> $GITHUB_STEP_SUMMARY
echo "- Check package.json sync" >> $GITHUB_STEP_SUMMARY
exit 1
fi
