Extract per-doc assertion helpers in QueryUtils (#16258)

Move the 70-line assertion+diagnostic block from `checkSkipTo`'s collect()
into `assertDocAndScore()`, and the advance-check for-loop body from
`checkFirstSkipTo`'s collect() into `assertAdvanceTo()`. No behaviour change.

Author: javanna

lucene/CHANGES.txt

@@ -654,6 +654,8 @@ Other
 
 * GITHUB#16215: Extract segment-boundary check into helper in QueryUtils (Luca Cavanna)
 
+* GITHUB#16258: Extract per-doc assertion helpers in QueryUtils (Luca Cavanna)
+
 ======================= Lucene 10.4.0 =======================
 
 API Changes

lucene/test-framework/src/java/org/apache/lucene/tests/search/QueryUtils.java

@@ -380,74 +380,7 @@ public void collect(int doc) throws IOException {
                     op == skip_op
                         ? iterator.advance(scorer.docID() + 1) != DocIdSetIterator.NO_MORE_DOCS
                         : iterator.nextDoc() != DocIdSetIterator.NO_MORE_DOCS;
-                int scorerDoc = scorer.docID();
-                float scorerScore = scorer.score();
-                float scorerScore2 = scorer.score();
-                float scoreDiff = Math.abs(score - scorerScore);
-                float scorerDiff = Math.abs(scorerScore2 - scorerScore);
-
-                boolean success = false;
-                try {
-                  assertTrue(more);
-                  assertEquals("scorerDoc=" + scorerDoc + ",doc=" + doc, scorerDoc, doc);
-                  assertTrue(
-                      "score=" + score + ", scorerScore=" + scorerScore, scoreDiff <= maxDiff);
-                  assertTrue(
-                      "scorerScorer=" + scorerScore + ", scorerScore2=" + scorerScore2,
-                      scorerDiff <= maxDiff);
-                  success = true;
-                } finally {
-                  if (!success) {
-                    if (LuceneTestCase.VERBOSE) {
-                      StringBuilder sbord = new StringBuilder();
-                      for (int i = 0; i < order.length; i++) {
-                        sbord.append(order[i] == skip_op ? " skip()" : " next()");
-                      }
-                      System.out.println(
-                          "ERROR matching docs:"
-                              + "\n\t"
-                              + (doc != scorerDoc ? "--> " : "")
-                              + "doc="
-                              + doc
-                              + ", scorerDoc="
-                              + scorerDoc
-                              + "\n\t"
-                              + (!more ? "--> " : "")
-                              + "tscorer.more="
-                              + more
-                              + "\n\t"
-                              + (scoreDiff > maxDiff ? "--> " : "")
-                              + "scorerScore="
-                              + scorerScore
-                              + " scoreDiff="
-                              + scoreDiff
-                              + " maxDiff="
-                              + maxDiff
-                              + "\n\t"
-                              + (scorerDiff > maxDiff ? "--> " : "")
-                              + "scorerScore2="
-                              + scorerScore2
-                              + " scorerDiff="
-                              + scorerDiff
-                              + "\n\thitCollector.doc="
-                              + doc
-                              + " score="
-                              + score
-                              + "\n\t Scorer="
-                              + scorer
-                              + "\n\t Query="
-                              + q
-                              + "  "
-                              + q.getClass().getName()
-                              + "\n\t Searcher="
-                              + s
-                              + "\n\t Order="
-                              + sbord
-                              + "\n\t Op="
-                              + (op == skip_op ? " skip()" : " next()"));
-                    }
-                  }
-                }
+                assertDocAndScore(doc, score, more, scorer, maxDiff, order, op, skip_op, q, s);
               } catch (IOException e) {
                 throw new RuntimeException(e);
               }
@@ -508,31 +441,7 @@ public void collect(int doc) throws IOException {
               // The intervalTimes32 trick helps contain the runtime of this check: first we check
               // every single doc in the interval, then after 32 docs we check every 2 docs, etc.
               for (int i = lastDoc[0] + 1; i <= doc; i += intervalTimes32++ / 1024) {
-                ScorerSupplier supplier = w.scorerSupplier(context.get(leafPtr));
-                Scorer scorer = supplier.get(1L); // only checking one doc, so leadCost = 1
-                assertTrue(
-                    "query collected " + doc + " but advance(" + i + ") says no more docs!",
-                    scorer.iterator().advance(i) != DocIdSetIterator.NO_MORE_DOCS);
-                assertEquals(
-                    "query collected " + doc + " but advance(" + i + ") got to " + scorer.docID(),
-                    doc,
-                    scorer.docID());
-                float advanceScore = scorer.score();
-                assertEquals(
-                    "unstable advance(" + i + ") score!", advanceScore, scorer.score(), maxDiff);
-                assertEquals(
-                    "query assigned doc "
-                        + doc
-                        + " a score of <"
-                        + score
-                        + "> but advance("
-                        + i
-                        + ") has <"
-                        + advanceScore
-                        + ">!",
-                    score,
-                    advanceScore,
-                    maxDiff);
+                assertAdvanceTo(doc, i, score, w, context.get(leafPtr), maxDiff);
               }
               lastDoc[0] = doc;
             } catch (IOException e) {
@@ -600,6 +509,119 @@ private static void assertNoPastSegmentEnd(
     }
   }
 
+  /**
+   * Verifies that the shadow scorer's position and score match the outer scorer's for {@code doc}.
+   * Prints a detailed diagnostic on failure when {@link LuceneTestCase#VERBOSE} is set.
+   */
+  private static void assertDocAndScore(
+      int doc,
+      float score,
+      boolean more,
+      Scorer scorer,
+      float maxDiff,
+      int[] order,
+      int op,
+      int skipOp,
+      Query q,
+      IndexSearcher s)
+      throws IOException {
+    int scorerDoc = scorer.docID();
+    float scorerScore = scorer.score();
+    float scorerScore2 = scorer.score();
+    float scoreDiff = Math.abs(score - scorerScore);
+    float scorerDiff = Math.abs(scorerScore2 - scorerScore);
+    boolean success = false;
+    try {
+      assertTrue(more);
+      assertEquals("scorerDoc=" + scorerDoc + ",doc=" + doc, scorerDoc, doc);
+      assertTrue("score=" + score + ", scorerScore=" + scorerScore, scoreDiff <= maxDiff);
+      assertTrue(
+          "scorerScorer=" + scorerScore + ", scorerScore2=" + scorerScore2, scorerDiff <= maxDiff);
+      success = true;
+    } finally {
+      if (!success) {
+        if (LuceneTestCase.VERBOSE) {
+          StringBuilder sbord = new StringBuilder();
+          for (int i = 0; i < order.length; i++) {
+            sbord.append(order[i] == skipOp ? " skip()" : " next()");
+          }
+          System.out.println(
+              "ERROR matching docs:"
+                  + "\n\t"
+                  + (doc != scorerDoc ? "--> " : "")
+                  + "doc="
+                  + doc
+                  + ", scorerDoc="
+                  + scorerDoc
+                  + "\n\t"
+                  + (!more ? "--> " : "")
+                  + "tscorer.more="
+                  + more
+                  + "\n\t"
+                  + (scoreDiff > maxDiff ? "--> " : "")
+                  + "scorerScore="
+                  + scorerScore
+                  + " scoreDiff="
+                  + scoreDiff
+                  + " maxDiff="
+                  + maxDiff
+                  + "\n\t"
+                  + (scorerDiff > maxDiff ? "--> " : "")
+                  + "scorerScore2="
+                  + scorerScore2
+                  + " scorerDiff="
+                  + scorerDiff
+                  + "\n\thitCollector.doc="
+                  + doc
+                  + " score="
+                  + score
+                  + "\n\t Scorer="
+                  + scorer
+                  + "\n\t Query="
+                  + q
+                  + "  "
+                  + q.getClass().getName()
+                  + "\n\t Searcher="
+                  + s
+                  + "\n\t Order="
+                  + sbord
+                  + "\n\t Op="
+                  + (op == skipOp ? " skip()" : " next()"));
+        }
+      }
+    }
+  }
+
+  /** Verifies that a freshly created scorer can advance to {@code doc} from position {@code i}. */
+  private static void assertAdvanceTo(
+      int doc, int i, float score, Weight w, LeafReaderContext leafContext, float maxDiff)
+      throws IOException {
+    ScorerSupplier supplier = w.scorerSupplier(leafContext);
+    Scorer scorer = supplier.get(1L); // only checking one doc, so leadCost = 1
+    assertTrue(
+        "query collected " + doc + " but advance(" + i + ") says no more docs!",
+        scorer.iterator().advance(i) != DocIdSetIterator.NO_MORE_DOCS);
+    assertEquals(
+        "query collected " + doc + " but advance(" + i + ") got to " + scorer.docID(),
+        doc,
+        scorer.docID());
+    float advanceScore = scorer.score();
+    assertEquals("unstable advance(" + i + ") score!", advanceScore, scorer.score(), maxDiff);
+    assertEquals(
+        "query assigned doc "
+            + doc
+            + " a score of <"
+            + score
+            + "> but advance("
+            + i
+            + ") has <"
+            + advanceScore
+            + ">!",
+        score,
+        advanceScore,
+        maxDiff);
+  }
+
   /** Check that the scorer and bulk scorer advance consistently. */
   public static void checkBulkScorerSkipTo(Random r, Query query, IndexSearcher searcher)
       throws IOException {