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

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

The "Architecture and Documentation Guards" job selected eight test classes
while scoping the reactor to graph-compose-core. Two had been deleted months
earlier; two live in graph-compose-qa and graph-compose-render-pdf. Surefire
aborts only when a selection is entirely empty, so the four names that did
match kept the job green while it ran half of what it advertised.

The list is now the five guards that live in the engine module, and
CiGuardListGuardTest parses the workflow and fails the job when a name in it
stops resolving under core/src/test/java — inside the very job it protects.

Markdown was also missing from change detection, so a pull request touching
only .md skipped the reactor build entirely and merged without
DocumentationSnippetCompileTest ever compiling the java fences it publishes.
A separate `docs` filter routes those changes into the reactor slice that
carries the qa guards, on the baseline JDK; example generation stays gated on
`code`, since rendering the catalogue proves nothing about prose.

PackageMapGuardTest scanned gitignored docs/private/, where a local note
routinely names a retired package in order to record that it is retired. A hit
there fails the release runbook's local verify gate for a reason CI can never
reproduce, so the directory is excluded — as CanonicalSurfaceGuardTest already
excludes it.

Three workflow comments claimed things that are not true: that render-docx,
render-pptx and graph-compose-testing are absent from Maven Central (they are
published; the examples pin them to the reactor's -SNAPSHOT), that the pptx
module is a semantic backend (its primary backend is fixed-layout), and that
the CodeQL scope matches the canonical verify gate (it is narrower, and the
render backends ship unscanned).

graph-compose-render-pptx compiles against org.apache.pdfbox types while
declaring only fontbox; the dependency is now explicit. Both modules pin
pdfbox.version to 3.0.8, so the resolved version is unchanged.

* ci(guards): run the guard-list tripwire in the job it guards, and resolve wildcards

CiGuardListGuardTest asserted that every name in the workflow's -Dtest list
resolves under core/src/test/java, and its own Javadoc claimed it "runs inside
the very job it protects". It was not in that list. It ran only in the full
reactor build, so a phantom name added to the guard step would still have
passed the guard step. Adding the test to the list makes the claim true and
costs nothing — it is core-resident like the other five.

Wildcard selectors were accepted without resolving them. A pattern that matches
nothing is the same silent skip as a deleted class name: Surefire drops it as
long as a sibling matches. Every accepted form is now resolved against the tree
— plain name, package-qualified name, #method suffix and glob alike — by
translating the selector to a regex (** spans packages, * and ? stay inside one
segment) and matching it against both the simple name and the package path of
each test source.

Exercising that surfaced a defect in the parser itself: the character class
reading the -Dtest value omitted '?', so a selector containing one was silently
truncated and the guard then checked a name nobody wrote. '?', '/', '!' and '+'
are now admitted, and a leading '!' marks an exclusion — it subtracts from the
selection rather than claiming coverage, so it is skipped rather than required
to resolve.

Author: DemchaAV

.github/workflows/ci.yml

@@ -45,23 +45,32 @@ jobs:
           java-version: '17'
           cache: maven
 
-      - name: Run guards
+      - 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,CanonicalTemplateComposerPdfBoundaryTest,PdfRenderInterfaceGuardTest,DocumentationCoverageTest,DocumentationExamplesTest,CanonicalSurfaceGuardTest,TemplateComposeApiTest,VersionConsistencyGuardTest" \
+            "-Dtest=EnginePdfBoundaryTest,DocumentationCoverageTest,CanonicalSurfaceGuardTest,PackageMapGuardTest,VersionConsistencyGuardTest,CiGuardListGuardTest" \
             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),
-    # `core` (the root graph-compose-core module — drives japicmp), `perf`
+    # `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 }}
@@ -86,6 +95,16 @@ jobs:
               - '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'
@@ -119,9 +138,12 @@ jobs:
   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 only docs / non-build files changed (`code` is false). 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')
+    # 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:
@@ -158,7 +180,9 @@ jobs:
         # 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), and the graph-compose-coverage aggregator (JaCoCo over core +
+        # 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;
@@ -189,7 +213,9 @@ jobs:
 
   examples-generation:
     name: Examples Generation Smoke Test
-    # Follows build-and-test: skipped for a docs-only PR, runs otherwise.
+    # 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
@@ -214,9 +240,10 @@ jobs:
         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 is a standalone artifact not on Maven
-        # Central, so install it into the local repo before building examples.
+        # 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)
@@ -235,22 +262,23 @@ jobs:
         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, which
-        # is not on Central. Install it after the engine (its graph-compose
-        # dependency) so the examples build resolves it.
+        # 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 testing module is
-        # not on Central, so install it after the engine (its graph-compose
-        # dependency) before the examples build resolves it.
+        # 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, which is not on Central. Install it after
-        # the wrapper (its core + render-pdf compile dependencies) AND 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

.github/workflows/codeql.yml

@@ -50,10 +50,14 @@ jobs:
           languages: ${{ matrix.language }}
           queries: security-and-quality
 
-      - name: Build (library module only)
-        # `-pl :graph-compose-core` scopes the analysis to the published artifact and matches
-        # the canonical verify gate. Examples/benchmarks are intentionally
-        # excluded — they ship no production code.
+      - name: Build (engine module)
+        # Scoped to the engine module alone: no `-am`, so nothing but core is built
+        # and nothing but core reaches the extractor. Since the 2.0 split
+        # graph-compose-core is one of several artifacts published to Maven Central,
+        # which makes this narrower than both the publish train and the canonical
+        # verify gate in ci.yml — the render backends and templates ship unscanned.
+        # Widening it to the code-bearing published modules is tracked for 2.2,
+        # together with a triage pass on the standing alert set.
         run: ./mvnw -B -ntp -DskipTests -pl :graph-compose-core package
 
       - name: Perform CodeQL analysis

.github/workflows/publish.yml

@@ -226,8 +226,10 @@ jobs:
 
       - name: Publish render-pptx to Maven Central
         if: steps.plan.outputs.run_render_pptx == 'true'
-        # The semantic PPTX backend, lockstep-versioned with the engine (ships on
-        # the same v* tag). graph-compose-core resolves from the local repo installed
+        # The PPTX render backend — a fixed-layout POI XSLF backend consuming the
+        # same resolved LayoutGraph as the PDF one, alongside the older semantic
+        # manifest skeleton. Lockstep-versioned with the engine (ships on the same
+        # v* tag). graph-compose-core resolves from the local repo installed
         # by the engine deploy above.
         run: ./mvnw -B -ntp -f render-pptx/pom.xml -P release -DskipTests -Dgpg.skip=false deploy
         env:

CHANGELOG.md

@@ -5,6 +5,24 @@ follow semantic versioning; release dates are ISO 8601.
 
 ## v2.1.1 — Planned
 
+### Build
+
+- **The CI guard job runs every guard it names.** It selected eight test classes
+  while scoping the reactor to `graph-compose-core`: two had been deleted months
+  earlier and two live in `graph-compose-qa` and `graph-compose-render-pdf`, so
+  four never ran. Surefire aborts only when a selection is entirely empty, so the
+  four that did match kept the job green. The list is now the five guards that
+  live in the engine module, and `CiGuardListGuardTest` fails the job if a name in
+  it stops resolving.
+- **A documentation-only pull request is compiled.** Markdown was not a
+  change-detection input, so a PR touching only `.md` skipped the reactor build
+  and merged without `DocumentationSnippetCompileTest` ever compiling the java
+  fences it publishes. Markdown now routes to the reactor slice that carries those
+  guards, on the baseline JDK, and still skips example generation.
+- **`graph-compose-render-pptx` declares PDFBox.** It compiles against
+  `org.apache.pdfbox` types while declaring only `fontbox`, taking the rest
+  transitively; the resolved version is unchanged.
+
 ### Fixed
 
 - **A heading no longer strands above a block that was asked to stay whole.**