api: clean up, add docs, add entry point

CHANGELOG.md

@@ -18,6 +18,7 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
   ([#1136](https://github.com/cucumber/cucumber-js/issues/1136)
   [#1721](https://github.com/cucumber/cucumber-js/pull/1721))
 - Support for configuration to be objects instead of argv strings, and for configuration files in ESM and JSON formats ([#1952](https://github.com/cucumber/cucumber-js/pull/1952))
+- New API for running Cucumber programmatically ([#1955](https://github.com/cucumber/cucumber-js/pull/1955))
 
 ### Fixed
 - Warn users who are on an unsupported node version ([#1922](https://github.com/cucumber/cucumber-js/pull/1922))

CONTRIBUTING.md

@@ -41,14 +41,22 @@ Type `npm run` or see the `package.json` scripts section for how to run each cat
 * feature tests - `npm run feature-test`
   * cucumber-js tests itself
 
+## API Documentation
+
+The functionality exposed under the `@cucumber/cucumber/api` entry point is analysed and has documentation generated by [API Extractor](https://api-extractor.com/). If you make a change that affects the public API surface, you'll need to run `npm run docs:local` to run the analysis and regenerate the docs, and commit the changes. If you forget to do this locally, the CI build will fail and remind you. 
+
 ## Internals
 
 ### Project Structure
 
 ```
 └── src
     │
-    ├── cli                   # argv parsing, reading files
+    ├── api                   # main runCucumber function etc
+    │
+    ├── cli                   # executing from argv
+    │
+    ├── configuration         # loading, merging, validating configuration
     │
     ├── formatter             # displaying the results
     │

api-extractor.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/lib/api/index.d.ts",
+  "compiler": {
+  },
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/reports/",
+    "reportTempFolder": "<projectFolder>/tmp/api-extractor/"
+  },
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/tmp/api-extractor/<unscopedPackageName>.api.json"
+  },
+  "dtsRollup": {
+    "enabled": false
+  },
+  "messages": {
+    "extractorMessageReporting": {
+      "ae-forgotten-export": {
+        "logLevel": "none"
+      }
+    }
+  }
+}

dependency-lint.yml

@@ -5,6 +5,8 @@ executedModules:
   npmScripts:
     dev:
       - build
+      - docs:ci
+      - docs:local
       - lint
       - publish
       - test

docs/api/cucumber.iloadconfigurationoptions.file.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) &gt; [file](./cucumber.iloadconfigurationoptions.file.md)
+
+## ILoadConfigurationOptions.file property
+
+Path to load configuration file from (defaults to `cucumber.(js|cjs|mjs|json)` if omitted).
+
+<b>Signature:</b>
+
+```typescript
+file?: string;
+```

docs/api/cucumber.iloadconfigurationoptions.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; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md)
+
+## ILoadConfigurationOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface ILoadConfigurationOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [file?](./cucumber.iloadconfigurationoptions.file.md) | string | <i>(Optional)</i> Path to load configuration file from (defaults to <code>cucumber.(js&#124;cjs&#124;mjs&#124;json)</code> if omitted). |
+|  [profiles?](./cucumber.iloadconfigurationoptions.profiles.md) | string\[\] | <i>(Optional)</i> Zero or more profile names from which to source configuration (if omitted or empty, the <code>default</code> profile will be used). |
+|  [provided?](./cucumber.iloadconfigurationoptions.provided.md) | Partial&lt;IConfiguration&gt; | <i>(Optional)</i> Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles. |
+

docs/api/cucumber.iloadconfigurationoptions.profiles.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) &gt; [profiles](./cucumber.iloadconfigurationoptions.profiles.md)
+
+## ILoadConfigurationOptions.profiles property
+
+Zero or more profile names from which to source configuration (if omitted or empty, the `default` profile will be used).
+
+<b>Signature:</b>
+
+```typescript
+profiles?: string[];
+```

docs/api/cucumber.iloadconfigurationoptions.provided.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) &gt; [provided](./cucumber.iloadconfigurationoptions.provided.md)
+
+## ILoadConfigurationOptions.provided property
+
+Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles.
+
+<b>Signature:</b>
+
+```typescript
+provided?: Partial<IConfiguration>;
+```

docs/api/cucumber.iloadsupportoptions.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; [ILoadSupportOptions](./cucumber.iloadsupportoptions.md)
+
+## ILoadSupportOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface ILoadSupportOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [sources](./cucumber.iloadsupportoptions.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) |  |
+|  [support](./cucumber.iloadsupportoptions.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) |  |
+

docs/api/cucumber.iloadsupportoptions.sources.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; [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) &gt; [sources](./cucumber.iloadsupportoptions.sources.md)
+
+## ILoadSupportOptions.sources property
+
+<b>Signature:</b>
+
+```typescript
+sources: ISourcesCoordinates;
+```

docs/api/cucumber.iloadsupportoptions.support.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; [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) &gt; [support](./cucumber.iloadsupportoptions.support.md)
+
+## ILoadSupportOptions.support property
+
+<b>Signature:</b>
+
+```typescript
+support: ISupportCodeCoordinates;
+```

docs/api/cucumber.iresolvedconfiguration.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; [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md)
+
+## IResolvedConfiguration interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface IResolvedConfiguration 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [original](./cucumber.iresolvedconfiguration.original.md) | IConfiguration | The final flat configuration object resolved from the configuration file/profiles plus any extra provided. |
+|  [runnable](./cucumber.iresolvedconfiguration.runnable.md) | [IRunnableConfiguration](./cucumber.irunnableconfiguration.md) | The format that can be passed into <code>runCucumber</code>. |
+

docs/api/cucumber.iresolvedconfiguration.original.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) &gt; [original](./cucumber.iresolvedconfiguration.original.md)
+
+## IResolvedConfiguration.original property
+
+The final flat configuration object resolved from the configuration file/profiles plus any extra provided.
+
+<b>Signature:</b>
+
+```typescript
+original: IConfiguration;
+```

docs/api/cucumber.iresolvedconfiguration.runnable.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) &gt; [runnable](./cucumber.iresolvedconfiguration.runnable.md)
+
+## IResolvedConfiguration.runnable property
+
+The format that can be passed into `runCucumber`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+runnable: IRunnableConfiguration;
+```

docs/api/cucumber.irunenvironment.cwd.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [cwd](./cucumber.irunenvironment.cwd.md)
+
+## IRunEnvironment.cwd property
+
+Working directory for the project (defaults to `process.cwd()` if omitted).
+
+<b>Signature:</b>
+
+```typescript
+cwd?: string;
+```

docs/api/cucumber.irunenvironment.env.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [env](./cucumber.irunenvironment.env.md)
+
+## IRunEnvironment.env property
+
+Environment variables (defaults to `process.env` if omitted).
+
+<b>Signature:</b>
+
+```typescript
+env?: NodeJS.ProcessEnv;
+```

docs/api/cucumber.irunenvironment.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md)
+
+## IRunEnvironment interface
+
+Contextual data about the project environment.
+
+<b>Signature:</b>
+
+```typescript
+export interface IRunEnvironment 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [cwd?](./cucumber.irunenvironment.cwd.md) | string | <i>(Optional)</i> Working directory for the project (defaults to <code>process.cwd()</code> if omitted). |
+|  [env?](./cucumber.irunenvironment.env.md) | NodeJS.ProcessEnv | <i>(Optional)</i> Environment variables (defaults to <code>process.env</code> if omitted). |
+|  [stderr?](./cucumber.irunenvironment.stderr.md) | IFormatterStream | <i>(Optional)</i> Writable stream where the test run's warning/error output is written (defaults to <code>process.stderr</code> if omitted). |
+|  [stdout?](./cucumber.irunenvironment.stdout.md) | IFormatterStream | <i>(Optional)</i> Writable stream where the test run's main output is written (defaults to <code>process.stdout</code> if omitted). |
+

docs/api/cucumber.irunenvironment.stderr.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [stderr](./cucumber.irunenvironment.stderr.md)
+
+## IRunEnvironment.stderr property
+
+Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted).
+
+<b>Signature:</b>
+
+```typescript
+stderr?: IFormatterStream;
+```

docs/api/cucumber.irunenvironment.stdout.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [stdout](./cucumber.irunenvironment.stdout.md)
+
+## IRunEnvironment.stdout property
+
+Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted).
+
+<b>Signature:</b>
+
+```typescript
+stdout?: IFormatterStream;
+```

docs/api/cucumber.irunnableconfiguration.formats.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; [IRunnableConfiguration](./cucumber.irunnableconfiguration.md) &gt; [formats](./cucumber.irunnableconfiguration.formats.md)
+
+## IRunnableConfiguration.formats property
+
+<b>Signature:</b>
+
+```typescript
+formats: IRunOptionsFormats;
+```

docs/api/cucumber.irunnableconfiguration.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunnableConfiguration](./cucumber.irunnableconfiguration.md)
+
+## IRunnableConfiguration interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface IRunnableConfiguration 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [formats](./cucumber.irunnableconfiguration.formats.md) | [IRunOptionsFormats](./cucumber.irunoptionsformats.md) |  |
+|  [runtime](./cucumber.irunnableconfiguration.runtime.md) | [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) |  |
+|  [sources](./cucumber.irunnableconfiguration.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) |  |
+|  [support](./cucumber.irunnableconfiguration.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) |  |
+

docs/api/cucumber.irunnableconfiguration.runtime.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; [IRunnableConfiguration](./cucumber.irunnableconfiguration.md) &gt; [runtime](./cucumber.irunnableconfiguration.runtime.md)
+
+## IRunnableConfiguration.runtime property
+
+<b>Signature:</b>
+
+```typescript
+runtime: IRunOptionsRuntime;
+```

docs/api/cucumber.irunnableconfiguration.sources.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; [IRunnableConfiguration](./cucumber.irunnableconfiguration.md) &gt; [sources](./cucumber.irunnableconfiguration.sources.md)
+
+## IRunnableConfiguration.sources property
+
+<b>Signature:</b>
+
+```typescript
+sources: ISourcesCoordinates;
+```

docs/api/cucumber.irunnableconfiguration.support.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; [IRunnableConfiguration](./cucumber.irunnableconfiguration.md) &gt; [support](./cucumber.irunnableconfiguration.support.md)
+
+## IRunnableConfiguration.support property
+
+<b>Signature:</b>
+
+```typescript
+support: ISupportCodeCoordinates;
+```

docs/api/cucumber.irunoptions.formats.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; [IRunOptions](./cucumber.irunoptions.md) &gt; [formats](./cucumber.irunoptions.formats.md)
+
+## IRunOptions.formats property
+
+<b>Signature:</b>
+
+```typescript
+formats: IRunOptionsFormats;
+```