From d56cbfa1e5bbaf72d29d8c4316adaf7febd97e10 Mon Sep 17 00:00:00 2001
From: DemchaAV <demchaav@gmail.com>
Date: Sun, 31 May 2026 12:51:44 +0100
Subject: [PATCH] test(build): add no-poi Maven profile to validate poi-ooxml
 stays optional (I1)

Wires up Track I1 from the readiness taskboard. poi-ooxml is declared optional in pom.xml; this PR adds the regression gate that proves the rest of the canonical suite runs without it.

Profile: -P no-poi excludes poi-ooxml + poi + poi-ooxml-lite from surefire classpath via classpathDependencyExcludes and sets no.poi=true system property. DocxSemanticBackendTest (whole class) and DocumentSessionTest#semanticBackendsShouldExportManifestsFromDocumentGraph carry @DisabledIfSystemProperty so they skip cleanly. New no-poi-suite CI job runs the profile on every PR.

Local run: 1029 tests, 0 failures, 4 skipped under -P no-poi.
---
 .github/workflows/ci.yml                      | 28 ++++++++++++++++
 CHANGELOG.md                                  | 12 +++++++
 pom.xml                                       | 33 +++++++++++++++++++
 .../document/api/DocumentSessionTest.java     |  3 ++
 .../semantic/DocxSemanticBackendTest.java     | 10 ++++++
 5 files changed, 86 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 224c468e..c631504e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -118,6 +118,34 @@ jobs:
           path: examples/target/generated-pdfs/**
           if-no-files-found: error
 
+  no-poi-suite:
+    name: Test suite without poi-ooxml (optional-deps regression)
+    if: github.event_name == 'pull_request'
+    needs: architecture-and-documentation-guards
+    runs-on: ubuntu-latest
+    env:
+      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Temurin JDK 17
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      - name: Run suite under -P no-poi
+        # poi-ooxml is declared <optional>true</optional>; this job
+        # validates that callers who don't render DOCX still get a
+        # green suite without the POI footprint. Tests that require
+        # poi (DocxSemanticBackend output) carry
+        # @DisabledIfSystemProperty(named = "no.poi", matches = "true")
+        # and skip cleanly. See Track I1 in the readiness taskboard.
+        run: ./mvnw -B -ntp test -pl . -P no-poi
+
   binary-compat:
     name: Binary Compatibility (japicmp vs v1.6.5)
     if: github.event_name == 'pull_request'
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae820fab..d2e8350b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,18 @@ JitPack continue to resolve through the existing coordinates.
   excluded by convention (`InternalAnnotationCoverageTest` covers those).
   Method-level `@since` backfill for the ~380 public methods in these
   packages is intentionally out of scope here and tracked separately.
+- **`no-poi` Maven profile + CI job** (Track I1). The `poi-ooxml`
+  dependency is declared `<optional>true</optional>` so callers that
+  render only PDFs don't pay the ~10 MB POI footprint; this PR adds a
+  regression gate that proves it. Running `./mvnw -P no-poi test -pl .`
+  excludes `poi-ooxml` (and its `poi` / `poi-ooxml-lite` transitives)
+  from the surefire test classpath and sets the system property
+  `no.poi=true`. DOCX-specific tests (`DocxSemanticBackendTest` and the
+  one DOCX export in `DocumentSessionTest`) now carry
+  `@DisabledIfSystemProperty(named = "no.poi", matches = "true")` and
+  skip cleanly. The rest of the canonical suite (1029 tests, 4 skipped
+  under `-P no-poi`) runs green without POI on the classpath. A new
+  `no-poi-suite` CI job exercises the profile on every pull request.
 
 ### Public API
 
diff --git a/pom.xml b/pom.xml
index 7242a31c..9428937b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -361,6 +361,39 @@
     </build>
 
     <profiles>
+        <!--
+            Optional-deps regression: runs the canonical suite with
+            `poi-ooxml` (and its transitives) excluded from the test
+            classpath, so callers that don't render DOCX validate that
+            our DocxSemanticBackend is genuinely optional. Tests that
+            require POI carry @DisabledIfSystemProperty(named = "no.poi",
+            matches = "true") and skip cleanly under this profile.
+            Activate with `-P no-poi`. Tracked in v1.6.6 stabilization
+            (Track I1).
+        -->
+        <profile>
+            <id>no-poi</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-surefire-plugin</artifactId>
+                        <version>${maven.surefire.plugin.version}</version>
+                        <configuration>
+                            <classpathDependencyExcludes>
+                                <classpathDependencyExclude>org.apache.poi:poi-ooxml</classpathDependencyExclude>
+                                <classpathDependencyExclude>org.apache.poi:poi</classpathDependencyExclude>
+                                <classpathDependencyExclude>org.apache.poi:poi-ooxml-lite</classpathDependencyExclude>
+                            </classpathDependencyExcludes>
+                            <systemPropertyVariables>
+                                <no.poi>true</no.poi>
+                            </systemPropertyVariables>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+
         <!--
             Binary-compatibility baseline against the last published
             release. Activated with `-P japicmp`. Resolves the baseline
diff --git a/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java b/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java
index e829b0fd..f6c755dd 100644
--- a/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java
+++ b/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java
@@ -73,6 +73,7 @@
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.common.PDRectangle;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledIfSystemProperty;
 import org.apache.pdfbox.rendering.PDFRenderer;
 import org.apache.pdfbox.text.PDFTextStripper;
 
@@ -681,6 +682,8 @@ public List<String> render(LayoutGraph graph, FixedLayoutRenderContext context)
     }
 
     @Test
+    @DisabledIfSystemProperty(named = "no.poi", matches = "true",
+            disabledReason = "Exercises DocxSemanticBackend; skipped under the no-poi profile that excludes poi-ooxml from the test classpath")
     void semanticBackendsShouldExportManifestsFromDocumentGraph() throws Exception {
         try (DocumentSession session = GraphCompose.document()
                 .pageSize(200, 200)
diff --git a/src/test/java/com/demcha/compose/document/backend/semantic/DocxSemanticBackendTest.java b/src/test/java/com/demcha/compose/document/backend/semantic/DocxSemanticBackendTest.java
index 71f45855..f111f668 100644
--- a/src/test/java/com/demcha/compose/document/backend/semantic/DocxSemanticBackendTest.java
+++ b/src/test/java/com/demcha/compose/document/backend/semantic/DocxSemanticBackendTest.java
@@ -14,12 +14,22 @@
 import org.apache.poi.xwpf.usermodel.XWPFParagraph;
 import org.apache.poi.xwpf.usermodel.XWPFTable;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledIfSystemProperty;
 
 import java.io.ByteArrayInputStream;
 import java.util.List;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+/**
+ * DOCX semantic backend output. Skipped under the {@code -P no-poi}
+ * profile, where {@code poi-ooxml} is intentionally absent from the
+ * test classpath to validate that consumers who don't render DOCX can
+ * still build and run the canonical suite without the optional POI
+ * footprint (Track I1).
+ */
+@DisabledIfSystemProperty(named = "no.poi", matches = "true",
+        disabledReason = "DocxSemanticBackend requires poi-ooxml; the no-poi profile validates the rest of the suite without it")
 class DocxSemanticBackendTest {
 
     @Test