ci(guards): run every guard the job names, and compile docs-only pull requests #1211

Workflow file for this run

	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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci(guards): run every guard the job names, and compile docs-only pull requests #1211

Workflow file

ci(guards): run every guard the job names, and compile docs-only pull requests #1211

Uh oh!

Workflow file for this run