Add more queries

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+### Added
+- Made `Lineage` APIs public ([#76](https://github.com/cucumber/query/pull/76))
+- New method `findPickleBy(TestStepStarted)`  ([#76](https://github.com/cucumber/query/pull/76))
+- New method `findTestCaseBy(TestStepStarted)` ([#76](https://github.com/cucumber/query/pull/76))
+- New method `findTestCaseStartedBy(TestStepStarted)` ([#76](https://github.com/cucumber/query/pull/76))
+- New method `findTestStepBy(TestStepStarted)` ([#76](https://github.com/cucumber/query/pull/76))
+- New method `findTestStepsStartedBy(TestCaseStarted)` ([#76](https://github.com/cucumber/query/pull/76)) 
+
+### Fixed
+- `Query.findAllTestCaseStarted` orders events by `timestamp` and `id` ([#76](https://github.com/cucumber/query/pull/76))
 
 ## [13.2.0] - 2025-02-02
 ### Changed

README.md

@@ -32,44 +32,9 @@ using `id` fields. It's a bit similar to rows in a relational database, with
 primary and foreign keys.
 
 Consumers of these messages may want to *query* the messages for certain information.
-For example, [cucumber-react](https://github.com/cucumber/cucumber-react) needs to know the status of
-a [Step](../cucumber-messages/messages.md#io.cucumber.messages.GherkinDocument.Feature.Step) as it
-is rendering the [GherkinDocument](../cucumber-messages/messages.md#io.cucumber.messages.GherkinDocument)
+For example, [@cucumber/react-components](https://github.com/cucumber/react-components) needs to know the status of
+a [Step](https://github.com/cucumber/messages/blob/main/messages.md#step) as it
+is rendering the [GherkinDocument](https://github.com/cucumber/messages/blob/main/messages.md#gherkindocument)
 
 The Query library makes this easy by providing a function to look up the
 status of a step, a scenario or an entire file.
-
-## API
-
-| Query function                                                                                | .NET | Go  | Java | Ruby | TypeScript |
-|-----------------------------------------------------------------------------------------------|------|-----|------|------|------------|
-| `getStepResults(uri: string, lineNumber: number): messages.ITestResult[]`                     |      |     |      |      | ✓          |
-| `getScenarioResults(uri: string, lineNumber: number): messages.ITestResult[]`                 |      |     |      |      | ✓          |
-| `getDocumentResults(uri: string): messages.ITestResult[]`                                     |      |     |      |      | ✓          |
-| `getStepMatchArguments(uri: string, lineNumber: number): messages.IStepMatchArgument[]`       |      |     |      |      | ✓          |
-| `getGherkinStep(gherkinStepId: string): messages.GherkinDocument.Feature.IStep`               |      |     |      |      | ✓          |
-| `countMostSevereTestStepResultStatus(): Map<TestStepResultStatus, Long>`                      |      |     | ✓    |      | ✓          |
-| `countTestCasesStarted(): int`                                                                |      |     | ✓    |      | ✓          |
-| `findAllPickles(): List<Pickle>`                                                              |      |     | ✓    |      | ✓          |
-| `findAllPickleSteps(): List<PickleStep>`                                                      |      |     | ✓    |      | ✓          |
-| `findAllTestCaseStarted(): List<TestCaseStarted>`                                             |      |     | ✓    |      | ✓          |
-| `findAllTestCaseStartedGroupedByFeature(): Map<Optional<Feature>, List<TestCaseStarted>>`     |      |     | ✓    |      | ✓          |
-| `findAllTestSteps(): List<TestStep>`                                                          |      |     | ✓    |      | ✓          |
-| `findAttachmentsBy(TestStepFinished): List<Attachment>`                                       |      |     | ✓    |      | ✓          |
-| `findFeatureBy(TestCaseStarted): Optional<Feature>`                                           |      |     | ✓    |      | ✓          |
-| `findHookBy(TestStep): Optional<Hook>`                                                        |      |     | ✓    |      | ✓          |
-| `findMeta(): Optional<Meta>`                                                                  |      |     | ✓    |      | ✓          |
-| `findMostSevereTestStepResulBy(TestCaseStarted): Optional<TestStepResult>`                    |      |     | ✓    |      | ✓          |
-| `findNameOf(Pickle, NamingStrategy): String`                                                  |      |     | ✓    |      | ✓          |
-| `findPickleBy(TestCaseStarted): Optional<Pickle>`                                             |      |     | ✓    |      | ✓          |
-| `findPickleStepBy(TestStep testStep): Optional<PickleStep>`                                   |      |     | ✓    |      | ✓          |
-| `findStepBy(PickleStep pickleStep): Optional<Step>`                                           |      |     | ✓    |      | ✓          |
-| `findTestCaseBy(TestCaseStarted): Optional<TestCase>`                                         |      |     | ✓    |      | ✓          |
-| `findTestCaseDurationBy(TestCaseStarted): Optional<Duration>`                                 |      |     | ✓    |      | ✓          |
-| `findTestCaseFinishedBy(TestCaseStarted): Optional<TestCaseFinished>`                         |      |     | ✓    |      | ✓          |
-| `findTestRunDuration(): Optional<Duration>`                                                   |      |     | ✓    |      | ✓          |
-| `findTestRunFinished(): Optional<TestRunFinished>`                                            |      |     | ✓    |      | ✓          |
-| `findTestRunStarted(): Optional<TestRunStarted>`                                              |      |     | ✓    |      | ✓          |
-| `findTestStepBy(TestStepFinished): Optional<TestStep>`                                        |      |     | ✓    |      | ✓          |
-| `findTestStepsFinishedBy(TestCaseStarted): List<TestStepFinished>`                            |      |     | ✓    |      | ✓          |
-| `findTestStepFinishedAndTestStepBy(TestCaseStarted): List<Entry<TestStepFinished, TestStep>>` |      |     | ✓    |      | ✓          |

java/src/main/java/io/cucumber/query/Lineage.java

@@ -9,7 +9,6 @@
 
 import java.util.Objects;
 import java.util.Optional;
-import java.util.function.Supplier;
 
 import static java.util.Objects.requireNonNull;
 
@@ -21,7 +20,7 @@
  *
  * @see LineageReducer
  */
-class Lineage {
+public final class Lineage {
 
     private final GherkinDocument document;
     private final Feature feature;
@@ -67,42 +66,38 @@ private Lineage(GherkinDocument document, Feature feature, Rule rule, Scenario s
         this.exampleIndex = exampleIndex;
     }
 
-    GherkinDocument document() {
+    public GherkinDocument document() {
         return document;
     }
 
-    Optional<Feature> feature() {
+    public Optional<Feature> feature() {
         return Optional.ofNullable(feature);
     }
 
-    Optional<Rule> rule() {
+    public Optional<Rule> rule() {
         return Optional.ofNullable(rule);
     }
 
-    Optional<Scenario> scenario() {
+    public Optional<Scenario> scenario() {
         return Optional.ofNullable(scenario);
     }
 
-    Optional<Examples> examples() {
+    public Optional<Examples> examples() {
         return Optional.ofNullable(examples);
     }
 
-    Optional<TableRow> example() {
+    public Optional<TableRow> example() {
         return Optional.ofNullable(example);
     }
 
-    Optional<Integer> examplesIndex() {
+    public Optional<Integer> examplesIndex() {
         return Optional.ofNullable(examplesIndex);
     }
 
-    Optional<Integer> exampleIndex() {
+    public Optional<Integer> exampleIndex() {
         return Optional.ofNullable(exampleIndex);
     }
 
-    <T> LineageReducer reduce(Supplier<LineageCollector<T>> collector) {
-        return new LineageReducerDescending(collector);
-    }
-
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

java/src/main/java/io/cucumber/query/LineageReducer.java

@@ -1,11 +1,15 @@
 package io.cucumber.query;
 
+import io.cucumber.messages.types.Examples;
+import io.cucumber.messages.types.Feature;
+import io.cucumber.messages.types.GherkinDocument;
 import io.cucumber.messages.types.Pickle;
+import io.cucumber.messages.types.Rule;
+import io.cucumber.messages.types.Scenario;
+import io.cucumber.messages.types.TableRow;
 
 import java.util.function.Supplier;
 
-import static java.util.Objects.requireNonNull;
-
 /**
  * Visit the {@link Lineage} of a {@linkplain io.cucumber.messages.types.GherkinDocument GherkinDocument element}
  * or {@link Pickle} and reduce it.
@@ -17,14 +21,53 @@
  *
  * @param <T> the type reduced to.
  */
-interface LineageReducer<T> {
+public interface LineageReducer<T> {
 
-    static <T> LineageReducer<T> descending(Supplier<? extends LineageCollector<T>> collector) {
+    static <T> LineageReducer<T> descending(Supplier<? extends Collector<T>> collector) {
         return new LineageReducerDescending<>(collector);
     }
+
+    static <T> LineageReducer<T> ascending(Supplier<? extends Collector<T>> collector) {
+        return new LineageReducerAscending<>(collector);
+    }
 
     T reduce(Lineage lineage);
 
     T reduce(Lineage lineage, Pickle pickle);
 
+    /**
+     * Collect the {@link Lineage} of a
+     * {@linkplain io.cucumber.messages.types.GherkinDocument GherkinDocument element}
+     * or {@link Pickle} and reduce it to a single result.
+     *
+     * @param <T> the type reduced to.
+     */
+    interface Collector<T> {
+        default void add(GherkinDocument document) {
+
+        }
+
+        default void add(Feature feature) {
+
+        }
+
+        default void add(Rule rule) {
+
+        }
+
+        default void add(Scenario scenario) {
+
+        }
+
+        default void add(Examples examples, int index) {
+        }
+
+        default void add(TableRow example, int index) {
+        }
+
+        default void add(Pickle pickle) {
+        }
+
+        T finish();
+    }
 }

java/src/main/java/io/cucumber/query/LineageReducerAscending.java

@@ -0,0 +1,45 @@
+package io.cucumber.query;
+
+import io.cucumber.messages.types.Pickle;
+
+import java.util.function.Supplier;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Reduces the lineage of a Gherkin document element in ascending order.
+ *
+ * @param <T> type to which the lineage is reduced.
+ */
+class LineageReducerAscending<T> implements LineageReducer<T> {
+
+    private final Supplier<? extends Collector<T>> collectorSupplier;
+
+    LineageReducerAscending(Supplier<? extends Collector<T>> collectorSupplier) {
+        this.collectorSupplier = requireNonNull(collectorSupplier);
+    }
+
+    @Override
+    public T reduce(Lineage lineage) {
+        Collector<T> collector = collectorSupplier.get();
+        reduceAddLineage(collector, lineage);
+        return collector.finish();
+    }
+
+    @Override
+    public T reduce(Lineage lineage, Pickle pickle) {
+        Collector<T> collector = collectorSupplier.get();
+        collector.add(pickle);
+        reduceAddLineage(collector, lineage);
+        return collector.finish();
+    }
+
+    private static <T> void reduceAddLineage(Collector<T> reducer, Lineage lineage) {
+        lineage.example().ifPresent(example -> reducer.add(example, lineage.exampleIndex().orElse(0)));
+        lineage.examples().ifPresent(examples -> reducer.add(examples, lineage.examplesIndex().orElse(0)));
+        lineage.scenario().ifPresent(reducer::add);
+        lineage.rule().ifPresent(reducer::add);
+        lineage.feature().ifPresent(reducer::add);
+        reducer.add(lineage.document());
+    }
+}

java/src/main/java/io/cucumber/query/LineageReducerDescending.java

@@ -13,33 +13,33 @@
  */
 class LineageReducerDescending<T> implements LineageReducer<T> {
 
-    private final Supplier<? extends LineageCollector<T>> reducerSupplier;
+    private final Supplier<? extends Collector<T>> collectorSupplier;
 
-    LineageReducerDescending(Supplier<? extends LineageCollector<T>> reducerSupplier) {
-        this.reducerSupplier = requireNonNull(reducerSupplier);
+    LineageReducerDescending(Supplier<? extends Collector<T>> collectorSupplier) {
+        this.collectorSupplier = requireNonNull(collectorSupplier);
     }
 
     @Override
     public T reduce(Lineage lineage) {
-        LineageCollector<T> reducer = reducerSupplier.get();
-        reduceAddLineage(reducer, lineage);
-        return reducer.finish();
+        Collector<T> collector = collectorSupplier.get();
+        reduceAddLineage(collector, lineage);
+        return collector.finish();
     }
 
     @Override
     public T reduce(Lineage lineage, Pickle pickle) {
-        LineageCollector<T> reducer = reducerSupplier.get();
-        reduceAddLineage(reducer, lineage);
-        reducer.add(pickle);
-        return reducer.finish();
+        Collector<T> collector = collectorSupplier.get();
+        reduceAddLineage(collector, lineage);
+        collector.add(pickle);
+        return collector.finish();
     }
 
-    private static <T> void reduceAddLineage(LineageCollector<T> reducer, Lineage lineage) {
-        reducer.add(lineage.document());
-        lineage.feature().ifPresent(reducer::add);
-        lineage.rule().ifPresent(reducer::add);
-        lineage.scenario().ifPresent(reducer::add);
-        lineage.examples().ifPresent(examples -> reducer.add(examples, lineage.examplesIndex().orElse(0)));
-        lineage.example().ifPresent(example -> reducer.add(example, lineage.exampleIndex().orElse(0)));
+    private static <T> void reduceAddLineage(Collector<T> collector, Lineage lineage) {
+        collector.add(lineage.document());
+        lineage.feature().ifPresent(collector::add);
+        lineage.rule().ifPresent(collector::add);
+        lineage.scenario().ifPresent(collector::add);
+        lineage.examples().ifPresent(examples -> collector.add(examples, lineage.examplesIndex().orElse(0)));
+        lineage.example().ifPresent(example -> collector.add(example, lineage.exampleIndex().orElse(0)));
     }
 }

java/src/main/java/io/cucumber/query/NamingCollector.java

@@ -6,6 +6,7 @@
 import io.cucumber.messages.types.Rule;
 import io.cucumber.messages.types.Scenario;
 import io.cucumber.messages.types.TableRow;
+import io.cucumber.query.LineageReducer.Collector;
 import io.cucumber.query.NamingStrategy.ExampleName;
 import io.cucumber.query.NamingStrategy.FeatureName;
 import io.cucumber.query.NamingStrategy.Strategy;
@@ -24,9 +25,10 @@
  *
  * @see NamingStrategy
  */
-class NamingCollector implements LineageCollector<String> {
+class NamingCollector implements Collector<String> {
 
-    private final Deque<String> parts = new ArrayDeque<>();
+    // There are at most 5 levels to a feature file.
+    private final Deque<String> parts = new ArrayDeque<>(5);
     private final CharSequence delimiter = " - ";
     private final Strategy strategy;
     private final FeatureName featureName;