ci.yml

name: CI

on:
  push:
    branches:
      - main
      - develop
      - 2.0-dev
  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

# Collapse superseded runs. On a pull request, a new push cancels the still-
# running CI for the previous commit on the same PR — the common case where
# rapid iteration would otherwise queue several full matrix builds. Pushes to
# the integration branches (main / develop / 2.0-dev) are never cancelled, so
# every merged commit keeps a complete, recorded CI run.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

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@v7

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

      - name: Run core architecture and documentation guards
        # Every name here must live in graph-compose-core: the run is scoped to
        # that module, and Surefire only fails on an empty selection — a name
        # that matches nothing while its siblings match is dropped in silence.
        # CiGuardListGuardTest asserts each name resolves under core/src/test.
        # Guards owned by other modules (PdfRenderInterfaceGuardTest in
        # render-pdf, DocumentationExamplesTest and DocumentationSnippetCompileTest
        # in qa) run in build-and-test below, which now also covers docs-only PRs.
        run: |
          ./mvnw -B -ntp clean \
            "-Dtest=EnginePdfBoundaryTest,DocumentationCoverageTest,CanonicalSurfaceGuardTest,PackageMapGuardTest,VersionConsistencyGuardTest" \
            test -pl :graph-compose-core

  changes:
    # Path-based change detection for selective CI on pull requests. Emits the
    # reverse-dependency flags the heavy jobs gate on: `code` (any build input),
    # `docs` (markdown the guard suites read and compile), `core` (the root
    # graph-compose-core module — drives japicmp), `perf`
    # (modules the smoke benchmark exercises), and `jvm` (published library modules
    # + toolchain — drives the JDK matrix width). Pushes/dispatch bypass these gates.
    name: Detect changed paths
    if: github.event_name != 'schedule'
    runs-on: ubuntu-latest
    outputs:
      code: ${{ steps.filter.outputs.code }}
      docs: ${{ steps.filter.outputs.docs }}
      core: ${{ steps.filter.outputs.core }}
      perf: ${{ steps.filter.outputs.perf }}
      jvm: ${{ steps.filter.outputs.jvm }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Detect changed module paths
        uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            code:
              - '**/*.java'
              - '**/pom.xml'
              - '**/src/main/resources/**'
              - '**/src/test/resources/**'
              # The examples module renders figures from the committed perf
              # baseline, so a baseline-only refresh changes generated output.
              - 'baselines/**'
              - '.mvn/**'
              - 'mvnw'
              - 'mvnw.cmd'
              - '.github/workflows/ci.yml'
            # Markdown is a build input even though it compiles nothing:
            # DocumentationSnippetCompileTest compiles the literal java fences in
            # docs/, and the guard suites read README / CONTRIBUTING / docs. Kept
            # separate from `code` so a docs-only change runs the reactor (which
            # carries those guards) without also running examples-generation,
            # which installs eight modules and renders the full example catalogue
            # to prove nothing about prose. Deliberately absent from `jvm` too, so
            # a docs-only PR uses the baseline JDK alone rather than the matrix.
            docs:
              - '**/*.md'
            core:
              - 'core/src/**'
              - 'core/pom.xml'
            perf:
              - 'core/src/**'
              - 'render-pdf/**'
              - 'templates/**'
              - 'benchmarks/**'
              - 'core/pom.xml'
            # Published library modules + build toolchain. A change here runs the
            # full JDK matrix (it ships to users across JVMs); a PR touching only
            # the non-published test/build infra (qa, coverage, examples,
            # benchmarks, docs) runs the baseline JDK alone.
            jvm:
              - 'core/src/**'
              - 'render-pdf/**'
              - 'render-docx/**'
              - 'render-pptx/**'
              - 'templates/**'
              - 'wrapper/**'
              - 'testing/**'
              - 'fonts/**'
              - 'emoji/**'
              - 'bundle/**'
              - 'core/pom.xml'
              - '.mvn/**'
              - 'mvnw'
              - 'mvnw.cmd'
              - '.github/workflows/ci.yml'

  build-and-test:
    name: Build and run tests (JDK ${{ matrix.java }})
    # Selective CI: on a pull request, skip the heavy reactor build + JDK matrix
    # when nothing this reactor slice can check has changed. Markdown counts —
    # this slice carries the qa guards that compile the published snippets, so a
    # docs-only PR runs here (on the baseline JDK alone, since `jvm` stays false)
    # rather than merging without any compiler having read the change. Pushes to
    # the integration branches and manual dispatch always run the full gate.
    if: github.event_name != 'schedule' && (github.event_name != 'pull_request' || needs.changes.outputs.code == 'true' || needs.changes.outputs.docs == 'true')
    needs: [architecture-and-documentation-guards, changes]
    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).
        # Full three-JDK matrix on a push/dispatch or when a published library
        # module / the toolchain changed (`jvm`); a PR that touches only the
        # non-published test/build infra runs the baseline JDK alone.
        java: ${{ fromJSON((github.event_name != 'pull_request' || needs.changes.outputs.jvm == 'true') && '["17","21","25"]' || '["17"]') }}
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

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

      - 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
        # Reactor slice: the engine, the render-docx semantic backend, the
        # render-pptx fixed-layout backend,
        # the graph-compose wrapper + graph-compose-bundle (the published empty-jar
        # aggregates — covered here so a packaging break is caught on every push, not
        # only via the examples job), the extracted graph-compose-testing module, the
        # graph-compose-qa cross-module suites (which need the testing module + the
        # engine test-jar on the classpath and so cannot live in the engine's own test
        # scope — this is where DocumentationSnippetCompileTest, the guard that
        # compiles the literal markdown fences in docs/, and DocumentationExamplesTest
        # actually run), and the graph-compose-coverage aggregator (JaCoCo over core +
        # render-pdf + templates, counting the qa exec, now with a NON-REGRESSION
        # RATCHET — this step fails if aggregate INSTRUCTION or BRANCH coverage drops
        # below the floor in coverage/pom.xml). -am pulls the fonts / emoji upstreams;
        # only examples / benchmarks are excluded (their own CI jobs cover them).
        run: ./mvnw -B -ntp clean verify -pl :graph-compose-core,:graph-compose-render-pdf,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-templates,:graph-compose-testing,:graph-compose,:graph-compose-bundle,:graph-compose-qa,:graph-compose-coverage -am

      - 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. Scoped to the engine (its public API is the doclint
        # gate); a bare reactor pass would also lint the dev-only benchmarks.
        if: matrix.java == '17'
        run: ./mvnw -B -ntp javadoc:javadoc -pl :graph-compose-core

      - name: Upload aggregate coverage report
        # The cross-module JaCoCo report (core + render-pdf + templates coverage,
        # counting the qa suites) is published as an artifact for inspection. The
        # non-regression gate itself is enforced by the `verify` step above; this just
        # captures the numbers. One JDK is enough — coverage is identical across JVMs.
        if: matrix.java == '17'
        uses: actions/upload-artifact@v7
        with:
          # Cross-module aggregate (core + render-pdf + templates, counting the qa
          # suites). The artifact name is kept for continuity with earlier runs.
          name: coverage-core-aggregate-${{ github.run_id }}
          path: coverage/target/site/jacoco-aggregate/**
          if-no-files-found: error

  examples-generation:
    name: Examples Generation Smoke Test
    # Gated on `code` alone, deliberately narrower than build-and-test above:
    # rendering the example catalogue costs eight module installs and proves
    # nothing about a markdown change, so a docs-only PR skips it.
    if: github.event_name != 'schedule' && (github.event_name != 'pull_request' || needs.changes.outputs.code == 'true')
    needs: [build-and-test, changes]
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

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

      - 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 graph-compose-emoji (consumed by the examples module)
        # The emoji example renders colour emoji from the bundled Noto SVG set.
        # Like graph-compose-fonts it carries its own version line, so the reactor
        # slice never builds it; installing from source pins the examples to this
        # tree's asset set rather than the cached jar at the same coordinate.
        run: ./mvnw -B -ntp -f emoji/pom.xml -DskipTests install

      - name: Install root artifact (graph-compose-core)
        run: ./mvnw -B -ntp -DskipTests install -pl :graph-compose-core

      - name: Install graph-compose-render-pdf (the PDF backend the wrapper brings)
        # The graph-compose wrapper depends on render-pdf so a bare graph-compose
        # renders PDF; install it after the core (its only dependency) and before
        # the wrapper.
        run: ./mvnw -B -ntp -f render-pdf/pom.xml -DskipTests install

      - name: Install graph-compose (the compat wrapper, consumed by the examples module)
        # examples depends on the graph-compose coordinate — the empty jar wrapper
        # over graph-compose-core + render-pdf. Install it after those so the
        # examples build resolves it (and the engine + PDF backend transitively).
        run: ./mvnw -B -ntp -f wrapper/pom.xml -DskipTests install

      - name: Install graph-compose-render-docx (consumed by the examples module)
        # The DOCX export example depends on the render-docx backend module at
        # ${graphcompose.version} — the reactor's -SNAPSHOT, which no repository
        # can supply. Install it after the engine (its graph-compose dependency)
        # so the examples build resolves it.
        run: ./mvnw -B -ntp -f render-docx/pom.xml -DskipTests install

      - name: Install graph-compose-testing (consumed by the examples module)
        # LayoutSnapshotRegressionExample uses LayoutSnapshotJson and EngineDeckData
        # reads benchmark JSON through the jackson it brings; the examples pin the
        # testing module to the reactor's -SNAPSHOT, so install it after the engine
        # (its graph-compose dependency) before the examples build resolves it.
        run: ./mvnw -B -ntp -f testing/pom.xml -DskipTests install

      - name: Install graph-compose-render-pptx (consumed by the examples module)
        # The Engine Deck PPTX example renders the flagship deck through the
        # fixed-layout PPTX backend, pinned to the reactor's -SNAPSHOT version.
        # Install it after the wrapper (its core + render-pdf compile dependencies) AND the
        # testing module — -DskipTests skips execution but Maven still
        # resolves render-pptx's test-scope graph-compose-testing dependency.
        run: ./mvnw -B -ntp -f render-pptx/pom.xml -DskipTests install

      - name: Install graph-compose-templates (consumed by the examples module)
        # The flagship + template examples render the built-in CV/invoice/proposal
        # presets, which now ship in graph-compose-templates.
        run: ./mvnw -B -ntp -f templates/pom.xml -DskipTests install

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

      - name: Run examples tests
        # The examples module carries its own tests (flagship layout-snapshot
        # baselines, the examples-local theme helpers, the README banner
        # renderer). Run them here so a change that shifts a flagship render
        # cannot land with a stale committed baseline.
        run: ./mvnw -B -ntp -f examples/pom.xml test

      - 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

  binary-compat:
    name: Binary Compatibility (japicmp vs pom baseline)
    # japicmp diffs the graph-compose-core public surface, so it only matters
    # when the core module (`core/src/**` or `core/pom.xml`) changed.
    if: github.event_name == 'pull_request' && needs.changes.outputs.core == 'true'
    needs: [architecture-and-documentation-guards, changes]
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

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

      - 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 core/pom.xml (the
        # published graph-compose-core on Maven Central) 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).
        run: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl :graph-compose-core

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

  perf-smoke:
    name: Performance Smoke Check
    # The smoke benchmark only exercises core + render-pdf + templates (built via
    # the benchmarks module), so skip it when none of those changed.
    if: github.event_name == 'pull_request' && needs.changes.outputs.perf == 'true'
    needs: [architecture-and-documentation-guards, changes]
    runs-on: ubuntu-latest
    env:
      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

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

      - 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 :graph-compose-core

      - name: Install graph-compose-render-pdf (consumed by the benchmarks module)
        # benchmarks call buildPdf and reference the PDF backend types directly, so
        # it depends on render-pdf; install it after the core, before the benchmarks
        # build resolves it.
        run: ./mvnw -B -ntp -f render-pdf/pom.xml -DskipTests install

      - name: Install graph-compose-templates (consumed by the benchmarks module)
        run: ./mvnw -B -ntp -f templates/pom.xml -DskipTests install

      - 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, measurement counts, scenario/threshold
        # coverage, diff tooling). Catches structural regressions the timing
        # smoke run cannot: these are exact integers, so unlike a millisecond
        # ceiling they separate a slower engine from a slower machine.
        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

  ci-gate:
    name: CI Gate
    # Single stable status check aggregating the selective jobs above. Green when
    # every job that ran succeeded; a job legitimately skipped by the path filter
    # counts as success. Point branch protection at "CI Gate" (plus the always-run
    # "Architecture and Documentation Guards") instead of the individual, sometimes
    # -skipped matrix legs so a docs-only PR is never left waiting on a check that
    # never reports.
    if: always() && github.event_name != 'schedule'
    needs: [architecture-and-documentation-guards, build-and-test, examples-generation, binary-compat, perf-smoke]
    runs-on: ubuntu-latest
    steps:
      - name: Fail if any required job failed
        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
        run: |
          echo "A required CI job failed or was cancelled: ${{ join(needs.*.result, ', ') }}"
          exit 1

  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@v7

      - 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@v6
        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 :graph-compose-core

      - name: Install graph-compose-render-pdf (consumed by the benchmarks module)
        # benchmarks call buildPdf and reference the PDF backend types directly, so
        # it depends on render-pdf; install it after the core, before the benchmarks
        # build resolves it.
        run: ./mvnw -B -ntp -f render-pdf/pom.xml -DskipTests install

      - name: Install graph-compose-templates (consumed by the benchmarks module)
        run: ./mvnw -B -ntp -f templates/pom.xml -DskipTests install

      - 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