api: loadSources function (#1957)

* make support stuff optional when doing paths

* install gherkin-utils

* refactor a bit

* refactor runCucumber internals, add docs

* revert breaking change to parseGherkinMessageStream

* add documentation

* normalise uris because windows

* deprecate parseGherkinMessageStream

* add missing export!

* add missing export!

* api report/docs update

CHANGELOG.md

@@ -27,6 +27,10 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
 ### Changed
 - Switch from `colors` to `chalk` for terminal coloring ([#1895](https://github.com/cucumber/cucumber-js/pull/1895))
 
+### Deprecated
+
+- `parseGherkinMessageStream` is deprecated in favour of `loadSources` ([#1957](https://github.com/cucumber/cucumber-js/pull/1957))
+
 ## [8.0.0-rc.2] - 2022-01-10
 ### Added
 - Export cucumber version number. It is now possible to retrieve the current version

docs/api/cucumber.iloadsourcesresult.errors.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadSourcesResult](./cucumber.iloadsourcesresult.md) &gt; [errors](./cucumber.iloadsourcesresult.errors.md)
+
+## ILoadSourcesResult.errors property
+
+<b>Signature:</b>
+
+```typescript
+errors: ISourcesError[];
+```

docs/api/cucumber.iloadsourcesresult.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadSourcesResult](./cucumber.iloadsourcesresult.md)
+
+## ILoadSourcesResult interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface ILoadSourcesResult 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [errors](./cucumber.iloadsourcesresult.errors.md) | [ISourcesError](./cucumber.isourceserror.md)<!-- -->\[\] |  |
+|  [plan](./cucumber.iloadsourcesresult.plan.md) | [IPlannedPickle](./cucumber.iplannedpickle.md)<!-- -->\[\] |  |
+

docs/api/cucumber.iloadsourcesresult.plan.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadSourcesResult](./cucumber.iloadsourcesresult.md) &gt; [plan](./cucumber.iloadsourcesresult.plan.md)
+
+## ILoadSourcesResult.plan property
+
+<b>Signature:</b>
+
+```typescript
+plan: IPlannedPickle[];
+```

docs/api/cucumber.iplannedpickle.location.md

@@ -0,0 +1,14 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IPlannedPickle](./cucumber.iplannedpickle.md) &gt; [location](./cucumber.iplannedpickle.location.md)
+
+## IPlannedPickle.location property
+
+<b>Signature:</b>
+
+```typescript
+location: {
+        line: number;
+        column?: number;
+    };
+```

docs/api/cucumber.iplannedpickle.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IPlannedPickle](./cucumber.iplannedpickle.md)
+
+## IPlannedPickle interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface IPlannedPickle 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [location](./cucumber.iplannedpickle.location.md) | { line: number; column?: number; } |  |
+|  [name](./cucumber.iplannedpickle.name.md) | string |  |
+|  [uri](./cucumber.iplannedpickle.uri.md) | string |  |
+

docs/api/cucumber.iplannedpickle.name.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IPlannedPickle](./cucumber.iplannedpickle.md) &gt; [name](./cucumber.iplannedpickle.name.md)
+
+## IPlannedPickle.name property
+
+<b>Signature:</b>
+
+```typescript
+name: string;
+```

docs/api/cucumber.iplannedpickle.uri.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IPlannedPickle](./cucumber.iplannedpickle.md) &gt; [uri](./cucumber.iplannedpickle.uri.md)
+
+## IPlannedPickle.uri property
+
+<b>Signature:</b>
+
+```typescript
+uri: string;
+```

docs/api/cucumber.isourceserror.location.md

@@ -0,0 +1,14 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ISourcesError](./cucumber.isourceserror.md) &gt; [location](./cucumber.isourceserror.location.md)
+
+## ISourcesError.location property
+
+<b>Signature:</b>
+
+```typescript
+location: {
+        line: number;
+        column?: number;
+    };
+```

docs/api/cucumber.isourceserror.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ISourcesError](./cucumber.isourceserror.md)
+
+## ISourcesError interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface ISourcesError 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [location](./cucumber.isourceserror.location.md) | { line: number; column?: number; } |  |
+|  [message](./cucumber.isourceserror.message.md) | string |  |
+|  [uri](./cucumber.isourceserror.uri.md) | string |  |
+

docs/api/cucumber.isourceserror.message.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ISourcesError](./cucumber.isourceserror.md) &gt; [message](./cucumber.isourceserror.message.md)
+
+## ISourcesError.message property
+
+<b>Signature:</b>
+
+```typescript
+message: string;
+```

docs/api/cucumber.isourceserror.uri.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ISourcesError](./cucumber.isourceserror.md) &gt; [uri](./cucumber.isourceserror.uri.md)
+
+## ISourcesError.uri property
+
+<b>Signature:</b>
+
+```typescript
+uri: string;
+```

docs/api/cucumber.loadsources.md

@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [loadSources](./cucumber.loadsources.md)
+
+## loadSources() function
+
+Load and parse features, produce a filtered and ordered test plan and/or parse errors.
+
+<b>Signature:</b>
+
+```typescript
+export declare function loadSources(coordinates: ISourcesCoordinates, environment?: IRunEnvironment): Promise<ILoadSourcesResult>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  coordinates | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | Coordinates required to find features |
+|  environment | [IRunEnvironment](./cucumber.irunenvironment.md) | Project environment. |
+
+<b>Returns:</b>
+
+Promise&lt;[ILoadSourcesResult](./cucumber.iloadsourcesresult.md)<!-- -->&gt;
+

docs/api/cucumber.md

@@ -15,6 +15,7 @@ These docs cover the API used for running Cucumber programmatically. The entry p
 |  Function | Description |
 |  --- | --- |
 |  [loadConfiguration(options, environment)](./cucumber.loadconfiguration.md) | Load user-authored configuration to be used in a test run. |
+|  [loadSources(coordinates, environment)](./cucumber.loadsources.md) | Load and parse features, produce a filtered and ordered test plan and/or parse errors. |
 |  [loadSupport(options, environment)](./cucumber.loadsupport.md) | Load support code for use in test runs. |
 |  [runCucumber(configuration, environment, onMessage)](./cucumber.runcucumber.md) | Execute a Cucumber test run. |
 
@@ -23,7 +24,9 @@ These docs cover the API used for running Cucumber programmatically. The entry p
 |  Interface | Description |
 |  --- | --- |
 |  [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) |  |
+|  [ILoadSourcesResult](./cucumber.iloadsourcesresult.md) |  |
 |  [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) |  |
+|  [IPlannedPickle](./cucumber.iplannedpickle.md) |  |
 |  [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) |  |
 |  [IRunConfiguration](./cucumber.irunconfiguration.md) |  |
 |  [IRunEnvironment](./cucumber.irunenvironment.md) | Contextual data about the project environment. |
@@ -32,6 +35,7 @@ These docs cover the API used for running Cucumber programmatically. The entry p
 |  [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) |  |
 |  [IRunResult](./cucumber.irunresult.md) | Result of a Cucumber test run. |
 |  [ISourcesCoordinates](./cucumber.isourcescoordinates.md) |  |
+|  [ISourcesError](./cucumber.isourceserror.md) |  |
 |  [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) |  |
 
 ## Type Aliases

docs/javascript_api.md

@@ -35,3 +35,17 @@ export async function runTests(directory, configFile, failFast) {
   return success
 }
 ```
+
+## Sources example
+
+You can use the `loadSources` function to load and parse your feature files, calculate the test plan (accounting for filtering and ordering) and report any parse errors:
+
+```javascript
+import { loadConfiguration, loadSources } from '@cucumber/cucumber/api'
+
+export async function calculatePlan() {
+  const { runConfiguration } = await loadConfiguration()
+  const { plan } = await loadSources(runConfiguration.sources)
+  return plan
+}
+```

package.json

@@ -194,6 +194,7 @@
     "@cucumber/cucumber-expressions": "15.0.2",
     "@cucumber/gherkin": "22.0.0",
     "@cucumber/gherkin-streams": "4.0.0",
+    "@cucumber/gherkin-utils": "^7.0.0",
     "@cucumber/html-formatter": "18.0.0",
     "@cucumber/messages": "17.1.1",
     "@cucumber/tag-expressions": "4.1.0",

reports/cucumber.api.md

@@ -24,6 +24,14 @@ export interface ILoadConfigurationOptions {
     provided?: Partial<IConfiguration>;
 }
 
+// @public (undocumented)
+export interface ILoadSourcesResult {
+    // (undocumented)
+    errors: ISourcesError[];
+    // (undocumented)
+    plan: IPlannedPickle[];
+}
+
 // @public (undocumented)
 export interface ILoadSupportOptions {
     // (undocumented)
@@ -32,6 +40,19 @@ export interface ILoadSupportOptions {
     support: ISupportCodeCoordinates;
 }
 
+// @public (undocumented)
+export interface IPlannedPickle {
+    // (undocumented)
+    location: {
+        line: number;
+        column?: number;
+    };
+    // (undocumented)
+    name: string;
+    // (undocumented)
+    uri: string;
+}
+
 // @public (undocumented)
 export interface IResolvedConfiguration {
     runConfiguration: IRunConfiguration;
@@ -119,6 +140,19 @@ export interface ISourcesCoordinates {
     tagExpression: string;
 }
 
+// @public (undocumented)
+export interface ISourcesError {
+    // (undocumented)
+    location: {
+        line: number;
+        column?: number;
+    };
+    // (undocumented)
+    message: string;
+    // (undocumented)
+    uri: string;
+}
+
 // @public (undocumented)
 export interface ISupportCodeCoordinates {
     // (undocumented)
@@ -135,6 +169,9 @@ export type ISupportCodeCoordinatesOrLibrary = ISupportCodeCoordinates | ISuppor
 // @public
 export function loadConfiguration(options?: ILoadConfigurationOptions, environment?: IRunEnvironment): Promise<IResolvedConfiguration>;
 
+// @public
+export function loadSources(coordinates: ISourcesCoordinates, environment?: IRunEnvironment): Promise<ILoadSourcesResult>;
+
 // @public
 export function loadSupport(options: ILoadSupportOptions, environment?: IRunEnvironment): Promise<ISupportCodeLibrary>;