fix(examples): guard the baseline resource and repair what the extraction left behind

Removing majorMinor from the deck deleted the method but not its javadoc, so
the block was left heading logo() and documenting an @param version that
method does not take.

The showcase javadoc promised "three pages of designed content"; the document
renders two.

The examples job gates on the `code` path filter, which did not list
baselines/. Now that the module renders figures from the committed baseline, a
baseline-only refresh would have changed generated output while skipping the
job that checks it.

PerfBaseline degraded inconsistently: a missing resource was swallowed while a
malformed one threw from a static initializer and would have taken down every
example in the module, not just the one quoting a figure. Loading now never
throws, and a scenario whose figures are absent or non-numeric is treated as
absent rather than read as 0.0 - which would have rendered a plausible
"0.0 ms avg, 0 docs/sec" instead of admitting nothing was measured.

That fallback is honest at render time and wrong to discover in a published
PDF, so PerfBaselineTest asserts the resource really is on the classpath with
the scenarios the showcase quotes. Verified by pointing the pom entry at a
filename that does not exist: on a clean build two of its three tests fail with
the intended message.

Author: DemchaAV

.github/workflows/ci.yml

@@ -79,6 +79,9 @@ jobs:
               - '**/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'

examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java

@@ -909,15 +909,6 @@ private static String snapshotDate(EngineDeckData.BenchRun bench) {
         return timestamp.substring(0, Math.min(10, timestamp.length()));
     }
 
-    /**
-     * Reduces a version to its {@code major.minor} line for display.
-     *
-     * @param version the resolved build version, possibly a qualifier or {@code "dev"}
-     * @return {@code "2.1"} for {@code "2.1.0"} / {@code "2.1.0-SNAPSHOT"}; the input
-     *         unchanged when it carries no dotted numeric prefix
-     */
-
-
     private static SvgIcon logo() {
         return icon("logo");
     }

examples/src/main/java/com/demcha/examples/flagships/MasterShowcaseExample.java

@@ -37,7 +37,7 @@
  * QR + Code 128 barcodes, document metadata, and header / footer chrome.
  *
  * <p>The rendered PDF reads like a fictional "GraphCompose Q2 Sample
- * Report" — three pages of designed content meant to look at a glance
+ * Report" — designed content meant to look at a glance
  * like the kind of business document GraphCompose was built to
  * generate, not a feature checklist. Use it as a reference when
  * composing your own multi-page documents.</p>

examples/src/main/java/com/demcha/examples/support/PerfBaseline.java

@@ -3,8 +3,8 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+import java.io.IOException;
 import java.io.InputStream;
-import java.io.UncheckedIOException;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
@@ -21,11 +21,19 @@
  * <p>The figures are one machine's median over several runs. Absolute
  * milliseconds do not travel between machines, so anything rendering them
  * should show {@link #capturedOn()} beside them and let the reader judge.</p>
+ *
+ * <p>Loading never throws: a resource that is missing, unreadable or malformed
+ * yields an empty baseline, and callers render a plain "not measured" rather
+ * than a number nobody measured. {@code PerfBaselineTest} keeps that fallback
+ * from becoming the normal case by asserting the resource really is on the
+ * classpath with the scenarios the examples quote.</p>
  */
 public final class PerfBaseline {
 
     private static final String RESOURCE = "/baselines/current-speed-full.json";
 
+    private static final PerfBaseline EMPTY = new PerfBaseline("undated", Map.of());
+
     private static final PerfBaseline INSTANCE = load();
 
     private final String capturedOn;
@@ -74,23 +82,36 @@ public Optional<Scenario> scenario(String scenario) {
     }
 
     private static PerfBaseline load() {
+        // Never throws. This runs in a static initializer, so a malformed file
+        // would otherwise fail class-load and take down every example in the
+        // module, not just the one quoting a figure. Absent and unreadable
+        // degrade the same way, and the caller renders the honest fallback.
         try (InputStream in = PerfBaseline.class.getResourceAsStream(RESOURCE)) {
             if (in == null) {
-                return new PerfBaseline("undated", Map.of());
+                return EMPTY;
             }
             JsonNode root = new ObjectMapper().readTree(in);
             Map<String, Scenario> scenarios = new HashMap<>();
             for (JsonNode row : root.path("latency")) {
-                scenarios.put(row.path("scenario").asText(),
-                        new Scenario(row.path("avgMillis").asDouble(),
-                                row.path("docsPerSecond").asDouble()));
+                String name = row.path("scenario").asText("");
+                // Require both figures to be present and numeric: a renamed or
+                // dropped field would otherwise read as 0.0 and render a
+                // plausible "0.0 ms avg, 0 docs/sec" instead of admitting the
+                // measurement is missing.
+                if (name.isEmpty()
+                    || !row.path("avgMillis").isNumber()
+                    || !row.path("docsPerSecond").isNumber()) {
+                    continue;
+                }
+                scenarios.put(name, new Scenario(row.path("avgMillis").asDouble(),
+                        row.path("docsPerSecond").asDouble()));
             }
             String timestamp = root.path("timestamp").asText("");
             return new PerfBaseline(
                     timestamp.length() >= 10 ? timestamp.substring(0, 10) : "undated",
                     Map.copyOf(scenarios));
-        } catch (java.io.IOException e) {
-            throw new UncheckedIOException("Cannot read " + RESOURCE, e);
+        } catch (IOException | RuntimeException e) {
+            return EMPTY;
         }
     }
 }

examples/src/test/java/com/demcha/examples/support/PerfBaselineTest.java

@@ -0,0 +1,48 @@
+package com.demcha.examples.support;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Keeps the honest fallback from quietly becoming the normal case.
+ *
+ * <p>{@link PerfBaseline} degrades to "not measured" when its resource is
+ * absent, which is the right behaviour at render time and the wrong thing to
+ * discover in a published PDF. The baseline reaches the classpath through a
+ * resource directory in {@code examples/pom.xml} that points outside the
+ * module; rename the file, move the directory, or drop that pom entry and every
+ * figure in the master showcase silently turns into a placeholder while the
+ * build stays green. This is the test that would go red instead.</p>
+ */
+class PerfBaselineTest {
+
+    @Test
+    void theCommittedBaselineIsOnTheClasspath() {
+        assertThat(PerfBaseline.get().capturedOn())
+                .describedAs("baseline resource missing from the examples classpath - "
+                             + "check the baselines resource entry in examples/pom.xml")
+                .matches("\\d{4}-\\d{2}-\\d{2}");
+    }
+
+    @Test
+    void itCarriesTheScenariosTheShowcaseQuotes() {
+        for (String scenario : new String[] {"invoice-template", "feature-rich"}) {
+            assertThat(PerfBaseline.get().scenario(scenario))
+                    .describedAs("MasterShowcaseExample renders '%s', so the baseline must carry it",
+                            scenario)
+                    .hasValueSatisfying(measured -> {
+                        assertThat(measured.avgMillis()).isPositive();
+                        assertThat(measured.docsPerSecond()).isPositive();
+                    });
+        }
+    }
+
+    @Test
+    void anUnknownScenarioIsAbsentRatherThanZero() {
+        assertThat(PerfBaseline.get().scenario("no-such-scenario"))
+                .describedAs("an unknown scenario must be empty so the caller can say "
+                             + "'not measured' instead of rendering 0.0 ms")
+                .isEmpty();
+    }
+}