api: clean up, add docs, add entry point (#1955)

* test generated docs

* add metadata to entry point, regenerate

* add tooling

* bump cucumber-expressions to fix issue

* combine in a single `docs` script and tell dependency-lint.yml

* regenerate docs

* rework directories

* improve docs

* add entry point at /api

* runtime options to extend

* get the docs in reasonable shape; make naming consistent, split out some types/interfaces as needed

* get the docs in reasonable shape; make naming consistent, split out some types/interfaces as needed

* refactor scripts, add a ci one

* fix api-extractor warning for now

* use @public

* rework tooling, add guidance to CONTRIBUTING.md

* write some docs, make some stuff optional where possible

* simplify dir structure

* add changelog entry

* link to new doc in changelog entry

* rename interfaces and properties per review feedback

* fix hand-written doc

* Update docs/javascript_api.md

Co-authored-by: Aurélien Reeves <aurelien.reeves@smartbear.com>

* Update javascript_api.md

Co-authored-by: Aurélien Reeves <aurelien.reeves@smartbear.com>

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 (see [documentation](./docs/javascript_api.md)) ([#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"
+      }
+    }
+  }
+}

compatibility/cck_spec.ts

@@ -9,7 +9,7 @@ import { ignorableKeys } from '../features/support/formatter_output_helpers'
 import * as messages from '@cucumber/messages'
 import * as messageStreams from '@cucumber/message-streams'
 import util from 'util'
-import { runCucumber, IRunnableConfiguration } from '../src/api'
+import { runCucumber, IRunConfiguration } from '../src/api'
 import { Envelope } from '@cucumber/messages'
 
 const asyncPipeline = util.promisify(pipeline)
@@ -29,7 +29,7 @@ describe('Cucumber Compatibility Kit', () => {
       const actualMessages: Envelope[] = []
       const stdout = new PassThrough()
       const stderr = new PassThrough()
-      const runConfiguration: IRunnableConfiguration = {
+      const runConfiguration: IRunConfiguration = {
         sources: {
           defaultDialect: 'en',
           paths: [`${CCK_FEATURES_PATH}/${suiteName}/${suiteName}${extension}`],

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 |
+|  --- | --- | --- |
+|  [runConfiguration](./cucumber.iresolvedconfiguration.runconfiguration.md) | [IRunConfiguration](./cucumber.irunconfiguration.md) | The format that can be passed into <code>runCucumber</code>. |
+|  [useConfiguration](./cucumber.iresolvedconfiguration.useconfiguration.md) | IConfiguration | The final flat configuration object resolved from the configuration file/profiles plus any extra provided. |
+

docs/api/cucumber.iresolvedconfiguration.runconfiguration.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; [runConfiguration](./cucumber.iresolvedconfiguration.runconfiguration.md)
+
+## IResolvedConfiguration.runConfiguration property
+
+The format that can be passed into `runCucumber`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+runConfiguration: IRunConfiguration;
+```

docs/api/cucumber.iresolvedconfiguration.useconfiguration.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; [useConfiguration](./cucumber.iresolvedconfiguration.useconfiguration.md)
+
+## IResolvedConfiguration.useConfiguration property
+
+The final flat configuration object resolved from the configuration file/profiles plus any extra provided.
+
+<b>Signature:</b>
+
+```typescript
+useConfiguration: IConfiguration;
+```

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

docs/api/cucumber.irunconfiguration.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; [IRunConfiguration](./cucumber.irunconfiguration.md)
+
+## IRunConfiguration interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface IRunConfiguration 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [formats](./cucumber.irunconfiguration.formats.md) | [IRunOptionsFormats](./cucumber.irunoptionsformats.md) |  |
+|  [runtime](./cucumber.irunconfiguration.runtime.md) | [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) |  |
+|  [sources](./cucumber.irunconfiguration.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) |  |
+|  [support](./cucumber.irunconfiguration.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) |  |
+

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

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

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

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;
+```