ci.yml

name: CI

on:
  push:
    branches:
      - main
      - develop
  pull_request:
    # Run CI for any incoming PR regardless of the base branch so
    # feature branches targeting `develop` (e.g. v1.7 prep) also
    # exercise the full pipeline.
  workflow_dispatch:
  schedule:
    - cron: '0 5 * * 1'

permissions:
  contents: read

jobs:
  architecture-and-documentation-guards:
    name: Architecture and Documentation Guards
    if: github.event_name != 'schedule'
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK 17
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Run guards
        run: |
          ./mvnw -B -ntp clean \
            "-Dtest=EnginePdfBoundaryTest,CanonicalTemplateComposerPdfBoundaryTest,PdfRenderInterfaceGuardTest,PdfRenderingSystemECSDispatchTest,DocumentationCoverageTest,DocumentationExamplesTest,CanonicalSurfaceGuardTest,TemplateComposeApiTest,VersionConsistencyGuardTest" \
            test

  build-and-test:
    name: Build and run tests (JDK ${{ matrix.java }})
    if: github.event_name != 'schedule'
    needs: architecture-and-documentation-guards
    runs-on: ubuntu-latest
    strategy:
      # Don't cancel sibling matrix jobs on the first failure — a
      # regression on one JDK is informative even if other JDKs are
      # still running.
      fail-fast: false
      matrix:
        # 17 = baseline, 21 = previous baseline still supported,
        # 25 = current LTS, validates the byte-buddy / Mockito 5.23
        # bumps that #10 motivated.
        java: ['17', '21', '25']
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK ${{ matrix.java }}
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: ${{ matrix.java }}
          cache: maven

      - name: Build and run tests
        run: ./mvnw -B -ntp clean verify

      - name: Generate Javadoc
        # Run only on the baseline JDK — Javadoc output is identical
        # across JVMs and one pass is enough to catch broken @link
        # references.
        if: matrix.java == '17'
        run: ./mvnw -B -ntp javadoc:javadoc

  examples-generation:
    name: Examples Generation Smoke Test
    if: github.event_name != 'schedule'
    needs: build-and-test
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK 17
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Install graph-compose-fonts (consumed by the examples / benchmarks modules)
        # The engine itself does not depend on the fonts artifact, but the
        # examples and benchmarks modules render with the bundled families, so
        # install graph-compose-fonts into the local repo before building them.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install root artifact
        run: ./mvnw -B -ntp -DskipTests install -pl .

      - name: Compile examples module
        run: ./mvnw -B -ntp -f examples/pom.xml clean compile

      - name: Run GenerateAllExamples
        run: |
          ./mvnw -B -ntp -f examples/pom.xml exec:java \
            "-Dexec.mainClass=com.demcha.examples.GenerateAllExamples"

      - name: Upload generated PDFs
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: examples-pdfs-${{ github.run_id }}
          path: examples/target/generated-pdfs/**
          if-no-files-found: error

  no-poi-suite:
    name: Test suite without poi-ooxml (optional-deps regression)
    if: github.event_name == 'pull_request'
    needs: architecture-and-documentation-guards
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK 17
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Run suite under -P no-poi
        # poi-ooxml is declared <optional>true</optional>; this job
        # validates that callers who don't render DOCX still get a
        # green suite without the POI footprint. Tests that require
        # poi (DocxSemanticBackend output) carry
        # @DisabledIfSystemProperty(named = "no.poi", matches = "true")
        # and skip cleanly. See Track I1 in the readiness taskboard.
        run: ./mvnw -B -ntp test -pl . -P no-poi

  binary-compat:
    name: Binary Compatibility (japicmp vs pom baseline)
    if: github.event_name == 'pull_request'
    needs: architecture-and-documentation-guards
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK 17
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Compare public API against baseline
        # The `japicmp` profile resolves the baseline release pinned
        # by the `japicmp.baseline` property in pom.xml (via the
        # profile-local JitPack repository) and diffs it against the
        # freshly-built artifact. Fails the job on any binary-
        # incompatible modification to the public surface. Source-
        # incompatible changes are reported only (phased policy).
        # See CHANGELOG v1.6.6 "Build" notes for the policy rationale.
        run: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl .

      - name: Upload japicmp report
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: japicmp-report-${{ github.run_id }}
          path: target/japicmp/**
          if-no-files-found: ignore

  perf-smoke:
    name: Performance Smoke Check
    if: github.event_name == 'pull_request'
    needs: architecture-and-documentation-guards
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK 17
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Install graph-compose-fonts (consumed by the examples / benchmarks modules)
        # The engine itself does not depend on the fonts artifact, but the
        # examples and benchmarks modules render with the bundled families, so
        # install graph-compose-fonts into the local repo before building them.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install root artifact
        run: ./mvnw -B -ntp -DskipTests install -pl .

      - name: Compile benchmarks module
        run: ./mvnw -B -ntp -f benchmarks/pom.xml clean compile

      - name: Run deterministic benchmark gates
        # Fast, machine-independent unit/gate tests (image-cache reuse,
        # render-operator coalescing, scenario/threshold coverage, diff tooling).
        # Catches structural regressions the timing smoke run cannot.
        run: ./mvnw -B -ntp -f benchmarks/pom.xml test

      - name: Run coarse performance smoke benchmark
        run: |
          ./mvnw -B -ntp -f benchmarks/pom.xml -DskipTests \
            exec:java \
            "-Dexec.mainClass=com.demcha.compose.CurrentSpeedBenchmark" \
            "-Dgraphcompose.benchmark.profile=smoke"

      - name: Upload smoke benchmark artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: benchmark-smoke-${{ github.run_id }}
          path: benchmarks/target/benchmarks/current-speed/**
          if-no-files-found: ignore

      - name: Upload benchmark gate reports
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: benchmark-gate-reports-${{ github.run_id }}
          path: benchmarks/target/surefire-reports/**
          if-no-files-found: ignore

  benchmark-diff:
    name: Weekly Benchmark Diff
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Temurin JDK 17
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Restore benchmark history cache
        uses: actions/cache@v5
        with:
          path: benchmarks/target/benchmarks/current-speed
          key: benchmark-current-speed-${{ github.ref_name }}-${{ github.run_id }}
          restore-keys: |
            benchmark-current-speed-${{ github.ref_name }}-
            benchmark-current-speed-

      - name: Install graph-compose-fonts (consumed by the examples / benchmarks modules)
        # The engine itself does not depend on the fonts artifact, but the
        # examples and benchmarks modules render with the bundled families, so
        # install graph-compose-fonts into the local repo before building them.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install root artifact
        run: ./mvnw -B -ntp -DskipTests install -pl .

      - name: Compile benchmarks module
        run: ./mvnw -B -ntp -f benchmarks/pom.xml clean compile

      - name: Run full benchmark suite
        run: |
          ./mvnw -B -ntp -f benchmarks/pom.xml -DskipTests \
            exec:java \
            "-Dexec.mainClass=com.demcha.compose.CurrentSpeedBenchmark" \
            "-Dgraphcompose.benchmark.profile=full" \
            "-Dgraphcompose.benchmark.enforceGate=false"

      - name: Count available benchmark runs
        id: benchmark-runs
        run: |
          count=0
          if [ -d benchmarks/target/benchmarks/current-speed ]; then
            count=$(find benchmarks/target/benchmarks/current-speed -maxdepth 1 -name 'run-*.json' | wc -l | tr -d ' ')
          fi
          echo "count=$count" >> "$GITHUB_OUTPUT"

      - name: Diff newest benchmark reports
        if: steps.benchmark-runs.outputs.count != '0' && steps.benchmark-runs.outputs.count != '1'
        run: |
          ./mvnw -B -ntp -f benchmarks/pom.xml -DskipTests \
            exec:java \
            "-Dexec.mainClass=com.demcha.compose.BenchmarkDiffTool" \
            "-Dexec.args=current-speed"

      - name: Upload benchmark artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: benchmark-full-${{ github.run_id }}
          path: |
            benchmarks/target/benchmarks/current-speed/**
            benchmarks/target/benchmarks/diffs/current-speed/**
          if-no-files-found: ignore