chore: add matchCount method

Author: zepfred

core/src/main/java/ai/timefold/solver/core/api/score/analysis/ConstraintAnalysis.java

@@ -3,7 +3,6 @@
 import static ai.timefold.solver.core.api.score.analysis.ScoreAnalysis.DEFAULT_SUMMARY_CONSTRAINT_MATCH_LIMIT;
 import static java.util.Comparator.comparing;
 
-import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashSet;
 import java.util.List;
@@ -61,6 +60,16 @@ static <Score_ extends Score<Score_>> ConstraintAnalysis<Score_> of(ConstraintRe
         Objects.requireNonNull(score);
     }
 
+    public int matchCount() {
+        if (matches == null) {
+            throw new IllegalArgumentException("""
+                    The constraint matches must be non-null.
+                    Maybe use ScoreAnalysisFetchPolicy.FETCH_ALL to request the score analysis
+                    """);
+        }
+        return matches.size();
+    }
+
     ConstraintAnalysis<Score_> negate() {
         if (matches == null) {
             return ConstraintAnalysis.of(constraintRef, weight.negate(), score.negate());
@@ -176,7 +185,10 @@ Explanation of score (%s):
 
         var constraintMatches = matches();
         if (constraintMatches == null) {
-            constraintMatches = Collections.emptyList();
+            throw new IllegalArgumentException("""
+                    The constraint matches must be non-null.
+                    Maybe use ScoreAnalysisFetchPolicy.FETCH_ALL to request the score analysis
+                    """);
         }
         summary.append("""
                         %s: constraint (%s) has %s matches:

core/src/main/java/ai/timefold/solver/core/api/score/analysis/ScoreAnalysis.java

@@ -173,7 +173,10 @@ Explanation of score (%s):
                 .forEach(constraint -> {
                     var matches = constraint.matches();
                     if (matches == null) {
-                        matches = Collections.emptyList();
+                        throw new IllegalArgumentException("""
+                                The constraint matches must be non-null.
+                                Maybe use ScoreAnalysisFetchPolicy.FETCH_ALL to request the score analysis
+                                """);
                     }
                     summary.append("""
                                     %s: constraint (%s) has %s matches:

core/src/test/java/ai/timefold/solver/core/api/score/analysis/ScoreAnalysisTest.java

@@ -2,6 +2,7 @@
 
 import static ai.timefold.solver.core.impl.score.director.InnerScoreDirector.getConstraintAnalysis;
 import static org.assertj.core.api.AssertionsForClassTypes.assertThat;
+import static org.assertj.core.api.AssertionsForClassTypes.assertThatThrownBy;
 import static org.assertj.core.api.SoftAssertions.assertSoftly;
 
 import java.util.Arrays;
@@ -31,9 +32,9 @@ void empty() {
         var summary = scoreAnalysis.summarize();
         assertThat(summary)
                 .isEqualTo("""
-                            Explanation of score (0):
-                                Constraint matches:
-                            """);
+                        Explanation of score (0):
+                            Constraint matches:
+                        """);
     }
 
     @Test
@@ -62,7 +63,7 @@ void summarize() {
         var constraintAnalysisMap = Map.of(
                 constraintMatchTotal.getConstraintRef(), getConstraintAnalysis(constraintMatchTotal, true),
                 constraintMatchTotal2.getConstraintRef(), getConstraintAnalysis(constraintMatchTotal2, true),
-                emptyConstraintMatchTotal1.getConstraintRef(), getConstraintAnalysis(emptyConstraintMatchTotal1, false));
+                emptyConstraintMatchTotal1.getConstraintRef(), getConstraintAnalysis(emptyConstraintMatchTotal1, true));
         var scoreAnalysis = new ScoreAnalysis<>(SimpleScore.of(67), constraintAnalysisMap);
 
         // Single constraint analysis
@@ -80,6 +81,7 @@ Explanation of score (27):
 
         // Complete score analysis
         var summary = scoreAnalysis.summarize();
+        assertThat(scoreAnalysis.getConstraintAnalysis(constraintPackage, constraintName1).matchCount()).isEqualTo(5);
         assertThat(summary)
                 .isEqualTo("""
                         Explanation of score (67):
@@ -98,6 +100,25 @@ Explanation of score (67):
                         """);
     }
 
+    @Test
+    void failFastSummarize() {
+        var constraintPackage = "constraintPackage";
+        var constraintName1 = "constraint1";
+        var constraintId1 = ConstraintRef.of(constraintPackage, constraintName1);
+
+        var constraintMatchTotal = new DefaultConstraintMatchTotal<>(constraintId1, SimpleScore.of(1));
+        addConstraintMatch(constraintMatchTotal, SimpleScore.of(2), "A", "B", "C");
+        var constraintAnalysisMap = Map.of(
+                constraintMatchTotal.getConstraintRef(), getConstraintAnalysis(constraintMatchTotal, false));
+        var scoreAnalysis = new ScoreAnalysis<>(SimpleScore.of(3), constraintAnalysisMap);
+
+        assertThatThrownBy(scoreAnalysis::summarize)
+                .hasMessageContaining("The constraint matches must be non-null");
+
+        assertThatThrownBy(() -> constraintAnalysisMap.values().stream().findFirst().get().matchCount())
+                .hasMessageContaining("The constraint matches must be non-null");
+    }
+
     @Test
     void compareWithConstraintMatchesWithoutMatchAnalysis() {
         var constraintPackage = "constraintPackage";