chore: deprecate things from the entry point (#2136)

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CONTRIBUTING.md) on how to contribute to Cucumber.
 
 ## [Unreleased]
+### Deprecated
+- `Cli`, `PickleFilter` and `Runtime` deprecated in favour of new API functions (see [documentation](./docs/deprecations.md)) ([#2136](https://github.com/cucumber/cucumber-js/pull/2136))
 
 ## [8.6.0] - 2022-09-20
 ### Added

docs/deprecations.md

@@ -0,0 +1,57 @@
+# Deprecations
+
+From time to time, we'll deprecate and then remove functionality. This is not done lightly, and is normally a means to help move the project forward in a way that the old functionality is at odds with. We do this in a controlled way, to minimise disruption and give users plenty of time to adapt to the change.
+
+Assuming a current major version of `N`:
+
+1. A minor version (e.g. `N.x.x`) is released with the deprecation. This will normally involve:
+   - A `@deprecated` comment in our code and types, which IDEs and other tools will recognise
+   - A runtime warning the first time the deprecated functionality is invoked, where possible
+2. Later, a major version (e.g. `N+1.0.0`) is released; the deprecation is highlighted in the release notes
+3. Later still, another major version (e.g. `N+2.0.0`) is released with the deprecated functionality removed
+
+## Current deprecations
+
+### `Cli`
+
+Deprecated in `8.7.0`, will be removed in `10.0.0`.
+
+The `Cli` class is used internally to represent an instance of the command-line program invoked via `cucumber-js`. It can be used to run Cucumber programmatically, but is poorly suited for this.
+
+To adapt, pivot to the `runCucumber` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.
+
+### `defineStep`
+
+Deprecated in `8.3.0`, will be removed in `10.0.0`.
+
+`defineStep` is a way to generically define a step without tying it to any of the `Given`, `When` or `Then` keywords. This leads to ambiguity in the business language and is considered an antipattern; steps should be clearly applicable to one of those keywords, being a context, action or outcome respectively.
+
+To adapt, review your steps and define them with the appropriate keyword, or just switch to `Given` as a starting point. We're working on adding [an opt-in "strict mode" for keywords](https://github.com/cucumber/cucumber-js/issues/2043) which will yield an error when the keyword in the Gherkin text doesn't match that of the step definition, and could be used to pinpoint such issues in your project.
+
+### `parseGherkinMessageStream`
+
+Deprecated in `8.0.0`, will be removed in `10.0.0`.
+
+`parseGherkinMessageStream` is a way to process a stream of envelopes from Gherkin and resolve to an array of filtered, ordered pickle Ids. Its interface includes internal implementation details from Cucumber which are difficult to assemble.
+
+To adapt, pivot to the `loadSources` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.
+
+### `PickleFilter`
+
+Deprecated in `8.7.0`, will be removed in `10.0.0`.
+
+The `PickleFilter` class is used to provide a filter to the `parseGherkinMessageStream` function above.
+
+To adapt, pivot to the `loadSources` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.
+
+### `Runtime`
+
+Deprecated in `8.7.0`, will be removed in `10.0.0`.
+
+The `Runtime` class is used internally to represent an instance of the serial test case runner. Its interface includes internal implementation details from Cucumber which are difficult to assemble.
+
+To adapt, pivot to the `runCucumber` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.
+
+## Previous deprecations
+
+For deprecations that have been completed (i.e. the functionality removed), see [UPGRADING.md](../UPGRADING.md).

src/cli/helpers.ts

@@ -29,8 +29,6 @@ interface IParseGherkinMessageStreamRequest {
 /**
  * Process a stream of envelopes from Gherkin and resolve to an array of filtered, ordered pickle Ids
  *
- * @deprecated use `loadSources` instead
- *
  * @param eventBroadcaster
  * @param eventDataCollector
  * @param gherkinMessageStream

src/index.ts

@@ -1,17 +1,14 @@
+import { default as _Cli } from './cli'
+import * as cliHelpers from './cli/helpers'
 import * as formatterHelpers from './formatter/helpers'
+import { default as _PickleFilter } from './pickle_filter'
 import * as parallelCanAssignHelpers from './support_code_library_builder/parallel_can_assign_helpers'
+import { default as _Runtime } from './runtime'
 import supportCodeLibraryBuilder from './support_code_library_builder'
 import * as messages from '@cucumber/messages'
+import { deprecate } from 'util'
 
 // Top level
-export { default as Cli } from './cli'
-export { parseGherkinMessageStream } from './cli/helpers'
-export { default as PickleFilter } from './pickle_filter'
-export {
-  default as Runtime,
-  INewRuntimeOptions,
-  IRuntimeOptions,
-} from './runtime'
 export { default as supportCodeLibraryBuilder } from './support_code_library_builder'
 export { default as DataTable } from './models/data_table'
 export { default as TestCaseHookDefinition } from './models/test_case_hook_definition'
@@ -38,10 +35,6 @@ export const Before = methods.Before
 export const BeforeAll = methods.BeforeAll
 export const BeforeStep = methods.BeforeStep
 export const defineParameterType = methods.defineParameterType
-/**
- * @deprecated use `Given`, `When` or `Then` instead; see <https://github.com/cucumber/cucumber-js/issues/2043>
- */
-export const defineStep = methods.defineStep
 export const Given = methods.Given
 export const setDefaultTimeout = methods.setDefaultTimeout
 export const setDefinitionFunctionWrapper = methods.setDefinitionFunctionWrapper
@@ -64,3 +57,41 @@ export const Status = messages.TestStepResultStatus
 
 // Time helpers
 export { wrapPromiseWithTimeout } from './time'
+
+// Deprecated
+/**
+ * @deprecated use `runCucumber` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
+ */
+export const Cli = deprecate(
+  _Cli,
+  '`Cli` is deprecated, use `runCucumber` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
+)
+/**
+ * @deprecated use `Given`, `When` or `Then` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
+ */
+export const defineStep = deprecate(
+  methods.defineStep,
+  '`defineStep` is deprecated, use `Given`, `When` or `Then` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
+)
+/**
+ * @deprecated use `loadSources` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
+ */
+export const parseGherkinMessageStream = deprecate(
+  cliHelpers.parseGherkinMessageStream,
+  '`parseGherkinMessageStream` is deprecated, use `loadSources` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
+)
+/**
+ * @deprecated use `loadSources` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
+ */
+export const PickleFilter = deprecate(
+  _PickleFilter,
+  '`PickleFilter` is deprecated, use `loadSources` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
+)
+/**
+ * @deprecated use `loadSources` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
+ */
+export const Runtime = deprecate(
+  _Runtime,
+  '`Runtime` is deprecated, use `runCucumber` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
+)
+export { INewRuntimeOptions, IRuntimeOptions } from './runtime'

src/support_code_library_builder/index.ts

@@ -8,7 +8,6 @@ import TestRunHookDefinition from '../models/test_run_hook_definition'
 import StepDefinition from '../models/step_definition'
 import { formatLocation } from '../formatter/helpers'
 import validateArguments from './validate_arguments'
-import { deprecate } from 'util'
 import arity from 'util-arity'
 
 import {
@@ -120,10 +119,7 @@ export class SupportCodeLibraryBuilder {
         () => this.beforeTestStepHookDefinitionConfigs
       ),
       defineParameterType: this.defineParameterType.bind(this),
-      defineStep: deprecate(
-        this.defineStep('Unknown', () => this.stepDefinitionConfigs),
-        '`defineStep` is deprecated, use `Given`, `When` or `Then` instead; see https://github.com/cucumber/cucumber-js/issues/2043'
-      ),
+      defineStep: this.defineStep('Unknown', () => this.stepDefinitionConfigs),
       Given: this.defineStep('Given', () => this.stepDefinitionConfigs),
       setDefaultTimeout: (milliseconds) => {
         this.defaultTimeout = milliseconds

src/wrapper.mjs

@@ -1,9 +1,5 @@
 import cucumber from './index.js'
 
-export const Cli = cucumber.Cli
-export const parseGherkinMessageStream = cucumber.parseGherkinMessageStream
-export const PickleFilter = cucumber.PickleFilter
-export const Runtime = cucumber.Runtime
 export const supportCodeLibraryBuilder = cucumber.supportCodeLibraryBuilder
 export const Status = cucumber.Status
 export const DataTable = cucumber.DataTable
@@ -28,10 +24,6 @@ export const Before = cucumber.Before
 export const BeforeAll = cucumber.BeforeAll
 export const BeforeStep = cucumber.BeforeStep
 export const defineParameterType = cucumber.defineParameterType
-/**
- * @deprecated use `Given`, `When` or `Then` instead; see <https://github.com/cucumber/cucumber-js/issues/2043>
- */
-export const defineStep = cucumber.defineStep
 export const Given = cucumber.Given
 export const setDefaultTimeout = cucumber.setDefaultTimeout
 export const setDefinitionFunctionWrapper = cucumber.setDefinitionFunctionWrapper
@@ -43,3 +35,9 @@ export const parallelCanAssignHelpers = cucumber.parallelCanAssignHelpers
 
 export const wrapPromiseWithTimeout = cucumber.wrapPromiseWithTimeout
 
+// Deprecated
+export const Cli = cucumber.Cli
+export const defineStep = cucumber.defineStep
+export const parseGherkinMessageStream = cucumber.parseGherkinMessageStream
+export const PickleFilter = cucumber.PickleFilter
+export const Runtime = cucumber.Runtime