Expose current branch and version to config deprecation providers (…

…elastic#113600)

* Expose deprecation context to config deprecations

* fix import

* add correct doc annotations

* fix another test file

* update generated doc

* fix yet another test file

* fix more types

* add proper mock

* fix import

docs/development/core/public/kibana-plugin-core-public.md

@@ -60,7 +60,6 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [CoreStart](./kibana-plugin-core-public.corestart.md) | Core services exposed to the <code>Plugin</code> start lifecycle |
 |  [DeprecationsServiceStart](./kibana-plugin-core-public.deprecationsservicestart.md) | DeprecationsService provides methods to fetch domain deprecation details from the Kibana server. |
 |  [DocLinksStart](./kibana-plugin-core-public.doclinksstart.md) |  |
-|  [DomainDeprecationDetails](./kibana-plugin-core-public.domaindeprecationdetails.md) |  |
 |  [ErrorToastOptions](./kibana-plugin-core-public.errortoastoptions.md) | Options available for [IToasts](./kibana-plugin-core-public.itoasts.md) error APIs. |
 |  [FatalErrorInfo](./kibana-plugin-core-public.fatalerrorinfo.md) | Represents the <code>message</code> and <code>stack</code> of a fatal Error |
 |  [FatalErrorsSetup](./kibana-plugin-core-public.fatalerrorssetup.md) | FatalErrors stop the Kibana Public Core and displays a fatal error screen with details about the Kibana build and the error. |

docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.correctiveactions.md

@@ -4,6 +4,8 @@
 
 ## DeprecationsDetails.correctiveActions property
 
+corrective action needed to fix this deprecation.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.documentationurl.md

@@ -4,6 +4,8 @@
 
 ## DeprecationsDetails.documentationUrl property
 
+(optional) link to the documentation for more details on the deprecation.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md

@@ -4,6 +4,7 @@
 
 ## DeprecationsDetails interface
 
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,11 +15,11 @@ export interface DeprecationsDetails
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [correctiveActions](./kibana-plugin-core-server.deprecationsdetails.correctiveactions.md) | <code>{</code><br/><code>        api?: {</code><br/><code>            path: string;</code><br/><code>            method: 'POST' &#124; 'PUT';</code><br/><code>            body?: {</code><br/><code>                [key: string]: any;</code><br/><code>            };</code><br/><code>        };</code><br/><code>        manualSteps: string[];</code><br/><code>    }</code> |  |
+|  [correctiveActions](./kibana-plugin-core-server.deprecationsdetails.correctiveactions.md) | <code>{</code><br/><code>        api?: {</code><br/><code>            path: string;</code><br/><code>            method: 'POST' &#124; 'PUT';</code><br/><code>            body?: {</code><br/><code>                [key: string]: any;</code><br/><code>            };</code><br/><code>        };</code><br/><code>        manualSteps: string[];</code><br/><code>    }</code> | corrective action needed to fix this deprecation. |
 |  [deprecationType](./kibana-plugin-core-server.deprecationsdetails.deprecationtype.md) | <code>'config' &#124; 'feature'</code> | (optional) Used to identify between different deprecation types. Example use case: in Upgrade Assistant, we may want to allow the user to sort by deprecation type or show each type in a separate tab.<!-- -->Feel free to add new types if necessary. Predefined types are necessary to reduce having similar definitions with different keywords across kibana deprecations. |
-|  [documentationUrl](./kibana-plugin-core-server.deprecationsdetails.documentationurl.md) | <code>string</code> |  |
+|  [documentationUrl](./kibana-plugin-core-server.deprecationsdetails.documentationurl.md) | <code>string</code> | (optional) link to the documentation for more details on the deprecation. |
 |  [level](./kibana-plugin-core-server.deprecationsdetails.level.md) | <code>'warning' &#124; 'critical' &#124; 'fetch_error'</code> | levels: - warning: will not break deployment upon upgrade - critical: needs to be addressed before upgrade. - fetch\_error: Deprecations service failed to grab the deprecation details for the domain. |
 |  [message](./kibana-plugin-core-server.deprecationsdetails.message.md) | <code>string</code> | The description message to be displayed for the deprecation. Check the README for writing deprecations in <code>src/core/server/deprecations/README.mdx</code> |
-|  [requireRestart](./kibana-plugin-core-server.deprecationsdetails.requirerestart.md) | <code>boolean</code> |  |
+|  [requireRestart](./kibana-plugin-core-server.deprecationsdetails.requirerestart.md) | <code>boolean</code> | (optional) specify the fix for this deprecation requires a full kibana restart. |
 |  [title](./kibana-plugin-core-server.deprecationsdetails.title.md) | <code>string</code> | The title of the deprecation. Check the README for writing deprecations in <code>src/core/server/deprecations/README.mdx</code> |
 

docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.requirerestart.md

@@ -4,6 +4,8 @@
 
 ## DeprecationsDetails.requireRestart property
 
+(optional) specify the fix for this deprecation requires a full kibana restart.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-core-server.deprecationsservicesetup.md

@@ -27,7 +27,6 @@ async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecations
   const deprecations: DeprecationsDetails[] = [];
   const count = await getFooCount(savedObjectsClient);
   if (count > 0) {
-    // Example of a manual correctiveAction
     deprecations.push({
       title: i18n.translate('xpack.foo.deprecations.title', {
         defaultMessage: `Foo's are deprecated`

docs/development/core/server/kibana-plugin-core-server.getdeprecationscontext.md

@@ -4,6 +4,7 @@
 
 ## GetDeprecationsContext interface
 
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-core-server.registerdeprecationsconfig.md

@@ -4,6 +4,7 @@
 
 ## RegisterDeprecationsConfig interface
 
+
 <b>Signature:</b>
 
 ```typescript

packages/kbn-config/src/config_service.test.ts

@@ -15,6 +15,7 @@ import { rawConfigServiceMock } from './raw/raw_config_service.mock';
 import { schema } from '@kbn/config-schema';
 import { MockedLogger, loggerMock } from '@kbn/logging/mocks';
 
+import type { ConfigDeprecationContext } from './deprecation';
 import { ConfigService, Env, RawPackageInfo } from '.';
 
 import { getEnvOptions } from './__mocks__/env';
@@ -475,6 +476,43 @@ test('logs deprecation warning during validation', async () => {
   `);
 });
 
+test('calls `applyDeprecations` with the correct parameters', async () => {
+  const cfg = { foo: { bar: 1 } };
+  const rawConfig = getRawConfigProvider(cfg);
+  const configService = new ConfigService(rawConfig, defaultEnv, logger);
+
+  const context: ConfigDeprecationContext = {
+    branch: defaultEnv.packageInfo.branch,
+    version: defaultEnv.packageInfo.version,
+  };
+
+  const deprecationA = jest.fn();
+  const deprecationB = jest.fn();
+
+  configService.addDeprecationProvider('foo', () => [deprecationA]);
+  configService.addDeprecationProvider('bar', () => [deprecationB]);
+
+  await configService.validate();
+
+  expect(mockApplyDeprecations).toHaveBeenCalledTimes(1);
+  expect(mockApplyDeprecations).toHaveBeenCalledWith(
+    cfg,
+    [
+      {
+        deprecation: deprecationA,
+        path: 'foo',
+        context,
+      },
+      {
+        deprecation: deprecationB,
+        path: 'bar',
+        context,
+      },
+    ],
+    expect.any(Function)
+  );
+});
+
 test('does not log warnings for silent deprecations during validation', async () => {
   const rawConfig = getRawConfigProvider({});
   const configService = new ConfigService(rawConfig, defaultEnv, logger);

packages/kbn-config/src/config_service.ts

@@ -19,6 +19,7 @@ import { RawConfigurationProvider } from './raw/raw_config_service';
 import {
   applyDeprecations,
   ConfigDeprecationWithContext,
+  ConfigDeprecationContext,
   ConfigDeprecationProvider,
   configDeprecationFactory,
   DeprecatedConfigDetails,
@@ -103,6 +104,7 @@ export class ConfigService {
       ...provider(configDeprecationFactory).map((deprecation) => ({
         deprecation,
         path: flatPath,
+        context: createDeprecationContext(this.env),
       })),
     ]);
   }
@@ -298,3 +300,10 @@ const pathToString = (path: ConfigPath) => (Array.isArray(path) ? path.join('.')
  */
 const isPathHandled = (path: string, handledPaths: string[]) =>
   handledPaths.some((handledPath) => hasConfigPathIntersection(path, handledPath));
+
+const createDeprecationContext = (env: Env): ConfigDeprecationContext => {
+  return {
+    branch: env.packageInfo.branch,
+    version: env.packageInfo.version,
+  };
+};

packages/kbn-config/src/deprecation/apply_deprecations.test.ts

@@ -7,18 +7,24 @@
  */
 
 import { applyDeprecations } from './apply_deprecations';
-import { ConfigDeprecation, ConfigDeprecationWithContext } from './types';
+import { ConfigDeprecation, ConfigDeprecationContext, ConfigDeprecationWithContext } from './types';
 import { configDeprecationFactory as deprecations } from './deprecation_factory';
 
-const wrapHandler = (
-  handler: ConfigDeprecation,
-  path: string = ''
-): ConfigDeprecationWithContext => ({
-  deprecation: handler,
-  path,
-});
-
 describe('applyDeprecations', () => {
+  const context: ConfigDeprecationContext = {
+    version: '7.16.2',
+    branch: '7.16',
+  };
+
+  const wrapHandler = (
+    handler: ConfigDeprecation,
+    path: string = ''
+  ): ConfigDeprecationWithContext => ({
+    deprecation: handler,
+    path,
+    context,
+  });
+
   it('calls all deprecations handlers once', () => {
     const handlerA = jest.fn();
     const handlerB = jest.fn();
@@ -32,6 +38,26 @@ describe('applyDeprecations', () => {
     expect(handlerC).toHaveBeenCalledTimes(1);
   });
 
+  it('calls deprecations handlers with the correct parameters', () => {
+    const config = { foo: 'bar' };
+    const addDeprecation = jest.fn();
+    const createAddDeprecation = jest.fn().mockReturnValue(addDeprecation);
+
+    const handlerA = jest.fn();
+    const handlerB = jest.fn();
+    applyDeprecations(
+      config,
+      [wrapHandler(handlerA, 'pathA'), wrapHandler(handlerB, 'pathB')],
+      createAddDeprecation
+    );
+
+    expect(handlerA).toHaveBeenCalledTimes(1);
+    expect(handlerA).toHaveBeenCalledWith(config, 'pathA', addDeprecation, context);
+
+    expect(handlerB).toHaveBeenCalledTimes(1);
+    expect(handlerB).toHaveBeenCalledWith(config, 'pathB', addDeprecation, context);
+  });
+
   it('passes path to addDeprecation factory', () => {
     const addDeprecation = jest.fn();
     const createAddDeprecation = jest.fn().mockReturnValue(addDeprecation);
@@ -51,7 +77,7 @@ describe('applyDeprecations', () => {
     expect(createAddDeprecation).toHaveBeenNthCalledWith(2, 'pathB');
   });
 
-  it('calls handlers with correct arguments', () => {
+  it('calls handlers with correct config argument', () => {
     const addDeprecation = jest.fn();
     const createAddDeprecation = jest.fn().mockReturnValue(addDeprecation);
     const initialConfig = { foo: 'bar', deprecated: 'deprecated' };

packages/kbn-config/src/deprecation/apply_deprecations.ts

@@ -15,6 +15,7 @@ import type {
 } from './types';
 
 const noopAddDeprecationFactory: () => AddConfigDeprecation = () => () => undefined;
+
 /**
  * Applies deprecations on given configuration and passes addDeprecation hook.
  * This hook is used for logging any deprecation warning using provided logger.
@@ -32,8 +33,8 @@ export const applyDeprecations = (
     set: [],
     unset: [],
   };
-  deprecations.forEach(({ deprecation, path }) => {
-    const commands = deprecation(result, path, createAddDeprecation(path));
+  deprecations.forEach(({ deprecation, path, context }) => {
+    const commands = deprecation(result, path, createAddDeprecation(path), context);
     if (commands) {
       if (commands.set) {
         changedPaths.set.push(...commands.set.map((c) => c.path));