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@v6
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Set up Node for the showcase site scripts
        uses: actions/setup-node@v7
        with:
          node-version: '20'

      - name: Showcase site script tests
        # web/ is published exactly as committed — its generated pages are built into
        # it by scripts/site/build.mjs and committed from there — and web/** matches none
        # of the path filters below, so the viewer's address and navigation logic, and the
        # check that the committed pages are the ones web-src/ builds, are tested here, in
        # the job every pull request runs. Every harness in the folder runs: naming one
        # file is how a second suite comes to sit there never running.
        run: |
          for suite in scripts/site/*.test.mjs; do
            echo "--- $suite"
            node "$suite"
          done

      - name: Install graph-compose-fonts (resolved at test scope by core)
        # The guards run scoped to core alone, and without `-am` core's test-scope
        # assets come from Maven Central. Both carry their own version lines, so the
        # tree can legitimately pin a version that is not published yet — which fails
        # this job at dependency resolution, before a single guard runs. Building
        # them from source keeps the job independent of Central for them.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install graph-compose-emoji (resolved at test scope by core)
        run: ./mvnw -B -ntp -f emoji/pom.xml -DskipTests install

      - 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,ShowcaseSiteGuardTest,CiGuardListGuardTest,CiGateCoverageGuardTest,BinaryCompatibilityGateGuardTest,CodeQlScopeGuardTest,AgentsGuideGuardTest,BenchmarkDependencyInstallGuardTest" \
            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` and `templates`
    # (the graph-compose-core / graph-compose-templates sources + pom — the two
    # modules under the japicmp gate), `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 }}
      templates: ${{ steps.filter.outputs.templates }}
      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/**'
              # The committed previews are compared against a fresh render
              # (CommittedAssetDriftTest), so editing one is a change the
              # examples job has to check — otherwise a hand-edited or
              # hand-reverted preview lands with nothing looking at it.
              - 'assets/readme/**'
              - '.mvn/**'
              - 'mvnw'
              - 'mvnw.cmd'
              - '.github/workflows/ci.yml'
              # The knowledge pack is generated from the compiled classes and
              # gated in build-and-test. Without this a PR touching only the
              # extractor, the classification rules or a generated surface
              # matches no filter, skips build-and-test, and skips the gate with
              # it — the gate would be absent on exactly the PRs that change the
              # gate. Deliberately NOT added to `jvm`: the check is
              # JDK-independent, so a knowledge-only PR wants one JDK 17 job
              # rather than the full matrix.
              - 'knowledge/**'
            # 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'
            templates:
              - 'templates/src/**'
              - 'templates/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@v6
        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

      # The knowledge pack describes the public API of the tree being built, so
      # it is checked here rather than in a job of its own: every job gets a
      # fresh runner, and a separate one would have no */target/classes to read.
      # Guarded to the baseline JDK because the surface is JDK-independent —
      # running it three times would only triple the chance of a flake.
      - name: Set up Node for the knowledge pack
        if: matrix.java == '17'
        uses: actions/setup-node@v7
        with:
          node-version: '20'

      # Every fixture suite the knowledge tools ship, discovered and then held to
      # a declared list. Neither half is enough on its own: naming them one step
      # each meant a new suite ran only if someone remembered to edit this file,
      # and discovery alone meant a suite renamed out of the glob stopped running
      # with nothing to notice. A suite that never runs looks exactly like one
      # that passes.
      #
      # So the set is compared, not counted. Add, rename or delete a suite and
      # this step goes red until the list below says so too — which is the point:
      # the change becomes deliberate instead of silent.
      - name: Knowledge pack — tool fixtures
        if: matrix.java == '17'
        run: |
          expected=$(printf '%s\n' \
            knowledge/tools/api-surface/test/classifier.test.mjs \
            knowledge/tools/api-surface/test/stability-doc.test.mjs \
            knowledge/tools/claims/test/claims.test.mjs \
            knowledge/tools/routing/test/anchors.test.mjs \
            knowledge/tools/routing/test/pack-version.test.mjs)
          found=$(find knowledge/tools -type f -name '*.test.mjs' | sort)
          if [ "$found" != "$expected" ]; then
            echo "the fixture suites on disk are not the ones this step declares:" >&2
            diff <(printf '%s\n' "$expected") <(printf '%s\n' "$found") >&2 || true
            exit 1
          fi
          # Not piped into `while read`: that runs the loop in a subshell, where
          # a failing suite could not fail the step. The paths hold no spaces, so
          # word splitting is safe and `bash -e` aborts on the first non-zero.
          for suite in $found; do
            echo "--- $suite"
            node "$suite"
          done

      # Blocking, and blocking from the first run. A warn-only gate is one
      # nobody reads, which is the failure mode this pack exists to remove: the
      # allow-list drifted through an entire major because nothing was watching.
      # Treat a failure here as a lockfile that was not regenerated.
      - name: Knowledge pack — API surface is current
        if: matrix.java == '17'
        run: node knowledge/tools/api-surface/extract-api.mjs --from-reactor --check

      # docs/api-stability.md is where a reader asks "what is still moving", and
      # nothing was checking that it still names what carries @Beta. The test it
      # cites as its guard examines the annotation type, never what is annotated.
      - name: Knowledge pack — the stability document names every @Beta
        if: matrix.java == '17'
        run: node knowledge/tools/api-surface/check-stability-doc.mjs

      # A claim is a promise a published page makes to a reader. This fails when
      # a page names API that no surface has — which a reader would discover by
      # trying to compile it — and when a proof points at a test that has since
      # been renamed away. Missing claims are only ever reported, never failed.
      - name: Knowledge pack — documentation claims hold
        if: matrix.java == '17'
        run: node knowledge/tools/claims/check-claims.mjs --check

      # A wrong route does not fail to compile — it sends every reader down the
      # wrong path with the authority of a generated artifact. So a route is only
      # served once its anchor resolves, its symbols exist, and its constraints
      # name a documented behaviour that some test actually holds up.
      - name: Knowledge pack — routing table holds up
        if: matrix.java == '17'
        run: node knowledge/tools/routing/check-routes.mjs

      - 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: Published Javadoc artefact is not empty
        # The step above lints the engine's sources. It cannot see whether the
        # artefact Maven Central serves has anything in it — and that is the
        # failure that actually happened: `graph-compose` carries no sources of
        # its own, so the javadoc goal found nothing to archive and attached an
        # artefact with no pages. Every 2.x release shipped that way, and
        # javadoc.io kept rendering 1.9.1 because it was the newest version that
        # carried an API reference at all. Nothing was red.
        #
        # Configuration is guarded by PublishedJavadocCoordinateGuardTest. This
        # guards the output: build the jar the release profile builds and look
        # inside it. Three pages stand in for the whole reference — the index the
        # reader lands on, the entry point every snippet starts from, and the type
        # they spend the rest of their time in.
        #
        # Three passes, mirroring the order publish.yml deploys in — and the order
        # is the whole point, because getting it wrong is silent.
        #
        # The wrapper's javadoc jar is configured in its `release` profile with
        # includeDependencySources, so it needs the ENGINE'S SOURCES JAR in the
        # local repository. Without it the goal logs "No Javadoc in project.
        # Archive not created", attaches nothing, and reports BUILD SUCCESS — the
        # empty-artefact failure all over again, now wearing a green tick.
        #
        # That sources jar is itself release-profile-only, and `release` also sets
        # core's attach-test-jar to phase `none` (the tests jar is deliberately not
        # published), which render-pdf needs at test scope. So: build the reactor
        # profile-free to get every module including that tests jar, re-install the
        # engine under `release` to add its sources jar, then build the wrapper.
        # publish.yml gets there by deploying the engine before the wrapper.
        if: matrix.java == '17'
        run: |
          set -euo pipefail
          ./mvnw -B -ntp install -DskipTests -pl :graph-compose -am
          ./mvnw -B -ntp install -DskipTests -pl :graph-compose-core -Prelease -Dgpg.skip=true
          ./mvnw -B -ntp package -DskipTests -pl :graph-compose -Prelease -Dgpg.skip=true
          jar=$(ls wrapper/target/graph-compose-*-javadoc.jar 2>/dev/null || true)
          if [ -z "$jar" ]; then
            echo "::error::No Javadoc jar was attached at all. Maven reports success in" \
                 "this case — 'No Javadoc in project. Archive not created' — which is how" \
                 "the empty artefact reached Central unnoticed. The usual cause is the" \
                 "engine's sources jar missing from the local repository, since" \
                 "includeDependencySources has nothing to read without it."
            exit 1
          fi
          echo "inspecting $jar"
          missing=0
          for page in index.html \
                      com/demcha/compose/GraphCompose.html \
                      com/demcha/compose/document/api/DocumentSession.html; do
            if unzip -l "$jar" | grep -qF " $page"; then
              echo "  ok      $page"
            else
              echo "  MISSING $page"
              missing=1
            fi
          done
          if [ "$missing" -ne 0 ]; then
            echo "::error::The published Javadoc jar is missing pages a reader needs." \
                 "This is what an empty API reference looks like before it reaches Central:" \
                 "check wrapper/pom.xml still sets includeDependencySources and" \
                 "dependencySourceInclude for the engine."
            exit 1
          fi

      - 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
          # ~3 MB of HTML per run, on every build-and-test run: the second-largest
          # consumer of the account-wide artifact quota after examples-pdfs. Nothing
          # downstream reads it — the non-regression gate is the `verify` step above,
          # and this copy exists only so a human can open the report while reviewing
          # the change that produced it. That need expires with the review, so keep
          # the same 7 days as the PDFs rather than the 90-day default.
          retention-days: 7

  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@v6
        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
          # The whole example catalogue, ~7.5 MB per run and the single largest
          # consumer of the account-wide artifact quota (7.5 GB of the 10 GB that
          # exhausted it and broke uploads in unrelated repositories). The bundle is
          # for eyeballing a render while the change is in review; a week covers
          # that, and the committed layout-snapshot and visual baselines — not this
          # artifact — are what prove a render later on.
          retention-days: 7

  binary-compat:
    name: Binary Compatibility (japicmp vs pom baseline)
    # japicmp diffs the graph-compose-core and graph-compose-templates public
    # surfaces (each module carries a `japicmp` profile), so it only matters when
    # one of them changed (`core/src/**`, `core/pom.xml`, `templates/src/**` or
    # `templates/pom.xml`). Both are diffed in one reactor invocation: templates
    # compiles against the core built in the same run, and a core change can move
    # the surface templates exposes.
    if: github.event_name == 'pull_request' && (needs.changes.outputs.core == 'true' || needs.changes.outputs.templates == '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@v6
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Install graph-compose-fonts (resolved at test scope by core)
        # Same reason as in the guards job: scoped to core without `-am`, and
        # `-DskipTests` still compiles the tests, so core's test-scope assets are
        # resolved — from Central unless they are built here first.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install graph-compose-emoji (resolved at test scope by core)
        run: ./mvnw -B -ntp -f emoji/pom.xml -DskipTests install

      - name: Drop cached GraphCompose artifacts before the gate resolves
        # The gate must diff against the PUBLISHED baselines. Anything of ours
        # already in the runner's cached repository could stand in for one, so
        # the pinned coordinates are fetched from Central for this run. The
        # modules under test come from the reactor, never from the repository.
        run: |
          rm -rf ~/.m2/repository/io/github/demchaav/graph-compose-core
          rm -rf ~/.m2/repository/io/github/demchaav/graph-compose-templates

      - name: Compare public API against baseline
        # Each module's `japicmp` profile resolves the published releases its
        # pom pins from Maven Central and diffs them against the freshly-built
        # artifact: graph-compose-core against `japicmp.baseline` (the 2.x
        # floor), graph-compose-templates against `japicmp.baseline.floor` and
        # `japicmp.baseline.previous` (the floor and the latest release). Fails
        # the job on any binary-incompatible modification to either public
        # surface. Source-incompatible changes are reported only (phased policy).
        run: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl :graph-compose-core,:graph-compose-templates

      - name: Prove every japicmp execution ran
        # A japicmp execution that does not run — switched off, unbound from the
        # lifecycle, or left out of the reactor — writes no report and fails
        # nothing, so the step above can pass having diffed nothing. Each execution
        # the gate relies on must have left its XML report;
        # BinaryCompatibilityGateGuardTest keeps this list in step with the poms.
        # (A baseline japicmp cannot resolve still leaves a report; the templates
        # gate fails on it through ignoreMissingOldVersion=false.)
        run: |
          ls -l core/target/japicmp templates/target/japicmp
          test -s core/target/japicmp/japicmp-against-baseline.xml
          test -s templates/target/japicmp/japicmp-against-major-floor.xml
          test -s templates/target/japicmp/japicmp-against-previous-release.xml

      - name: Upload japicmp report
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: japicmp-report-${{ github.run_id }}
          path: |
            core/target/japicmp/**
            templates/target/japicmp/**
          if-no-files-found: ignore
          # ~130 KB of XML — the whole live population is under 60 MB, so retention
          # here is about usefulness, not bytes. These reports answer "when did this
          # signature move, and against which baseline" weeks after the fact, during
          # release prep rather than during the PR. Keep a month.
          retention-days: 30

  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@v6
        with:
          distribution: temurin
          java-version: '17'
          cache: maven

      - name: Install graph-compose-fonts (the benchmarks render with the bundled families)
        # The core install below also resolves both assets at test scope. They carry
        # their own version lines, so the tree can pin a version that is not published
        # yet — building them here keeps the job independent of Central for them.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install graph-compose-emoji (resolved at test scope by core)
        run: ./mvnw -B -ntp -f emoji/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
          # Tens of KB of JSON. Two weeks so a perf claim can still be checked
          # against the runs that supported it after a round of review, without
          # keeping per-PR smoke numbers that the next push supersedes anyway.
          retention-days: 14

      - 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
          # ~40 KB of surefire XML, and the other half of the evidence for the same
          # job: the gate verdict here explains the numbers in benchmark-smoke above.
          # Kept at the same 14 days deliberately — a shorter window would leave an
          # investigation holding one half of a pair.
          retention-days: 14

  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.
    #
    # `changes` is in the list even though it decides rather than builds. When its
    # fetch fails the heavy jobs downstream resolve to `skipped`, not `failure`, so
    # a gate that watched only them stayed green over a run where nothing was built.
    # Every job that can run on a pull request belongs here; only the schedule-only
    # benchmark job is outside, and CiGateCoverageGuardTest holds that line.
    if: always() && github.event_name != 'schedule'
    needs: [architecture-and-documentation-guards, changes, 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@v6
        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 (the benchmarks render with the bundled families)
        # The core install below also resolves both assets at test scope. They carry
        # their own version lines, so the tree can pin a version that is not published
        # yet — building them here keeps the job independent of Central for them.
        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install

      - name: Install graph-compose-emoji (resolved at test scope by core)
        run: ./mvnw -B -ntp -f emoji/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
          # The weekly trend series, and the one artifact here whose value grows with
          # age: a cadence of one run per week means a short window would hold one or
          # two points and show no trend at all. It costs tens of KB a week, so keep
          # the full 90 days — roughly thirteen points — rather than trimming it.
          retention-days: 90