From f382758096ddcd1be99576bd99eb6b402fe768fb Mon Sep 17 00:00:00 2001
From: Aleh Zasypkin <aleh.zasypkin@gmail.com>
Date: Tue, 16 Oct 2018 12:14:56 +0200
Subject: [PATCH] [6.x] Add Kibana bootstrap step to generate types exposed by
 the core and its plugins. (#23888)

---
 package.json                               |  5 +-
 packages/kbn-config-schema/tsconfig.json   |  3 +-
 src/core/server/logging/index.ts           |  2 +
 src/core/server/logging/logging_service.ts |  1 +
 src/type_exports.ts                        | 53 ++++++++++++++++++++++
 tsconfig.types.json                        | 13 ++++++
 6 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100644 src/type_exports.ts
 create mode 100644 tsconfig.types.json

diff --git a/package.json b/package.json
index 4e54e1f8c8f24..39225694cfd71 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
   "private": false,
   "version": "6.5.0",
   "branch": "6.x",
+  "types": "./target/types/type_exports.d.ts",
   "build": {
     "number": 8467,
     "sha": "6cb7fec4e154faa0a4a3fee4b33dfef91b9870d9"
@@ -68,7 +69,9 @@
     "uiFramework:build": "cd packages/kbn-ui-framework && yarn docSiteBuild",
     "uiFramework:createComponent": "cd packages/kbn-ui-framework && yarn createComponent",
     "uiFramework:documentComponent": "cd packages/kbn-ui-framework && yarn documentComponent",
-    "kbn:watch": "node scripts/kibana --dev --logging.json=false"
+    "kbn:watch": "node scripts/kibana --dev --logging.json=false",
+    "build:types": "tsc --p tsconfig.types.json",
+    "kbn:bootstrap": "yarn build:types"
   },
   "repository": {
     "type": "git",
diff --git a/packages/kbn-config-schema/tsconfig.json b/packages/kbn-config-schema/tsconfig.json
index 6d228baba0667..7a250509cf435 100644
--- a/packages/kbn-config-schema/tsconfig.json
+++ b/packages/kbn-config-schema/tsconfig.json
@@ -4,7 +4,8 @@
     "declaration": true,
     "declarationDir": "./target/types",
     "outDir": "./target/out",
-    "stripInternal": true
+    "stripInternal": true,
+    "declarationMap": true
   },
   "include": [
     "./types/joi.d.ts",
diff --git a/src/core/server/logging/index.ts b/src/core/server/logging/index.ts
index eb31691028e1c..51268cb646288 100644
--- a/src/core/server/logging/index.ts
+++ b/src/core/server/logging/index.ts
@@ -19,5 +19,7 @@
 
 export { Logger } from './logger';
 export { LoggerFactory } from './logger_factory';
+/** @internal */
 export { LoggingConfig } from './logging_config';
+/** @internal */
 export { LoggingService } from './logging_service';
diff --git a/src/core/server/logging/logging_service.ts b/src/core/server/logging/logging_service.ts
index 966bd74a0df41..7934ed4afe76e 100644
--- a/src/core/server/logging/logging_service.ts
+++ b/src/core/server/logging/logging_service.ts
@@ -26,6 +26,7 @@ import { LoggerConfigType, LoggingConfig } from './logging_config';
 
 /**
  * Service that is responsible for maintaining loggers and logger appenders.
+ * @internal
  */
 export class LoggingService implements LoggerFactory {
   private config?: LoggingConfig;
diff --git a/src/type_exports.ts b/src/type_exports.ts
new file mode 100644
index 0000000000000..976f0bd6a16b1
--- /dev/null
+++ b/src/type_exports.ts
@@ -0,0 +1,53 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * This file re-exports only those Kibana types that we'd like plugins to have access to.
+ *
+ * Generated types are referenced from the `types` field of the Kibana's `package.json`, so
+ * that plugins can just reference Kibana root folder to access all required types.
+ *
+ * Here is an example of how plugin can use these types assuming it is located
+ * in one of the known plugin locations (kibana/plugins/* or kibana-extra/*):
+ *
+ * ```ts
+ * import { KibanaPlugin } from '../../kibana';
+ *
+ * export interface SomePluginContract {
+ *   setValue: (val: string) => void;
+ * }
+ *
+ * class SomePlugin extends KibanaPlugin<SomePluginContract> {
+ *   start(core) {
+ *     let value = 'Hello World!';
+ *
+ *     const router = core.http.createAndRegisterRouter('/some-path');
+ *     router.get('/some-value', (req, res) => res.ok(value));
+ *
+ *     return { setValue: (val: string) => { value = val; } };
+ *   }
+ * }
+ * ```
+ *
+ * **NOTE:** If the code is not needed in plugins, we can add a `at_internal` JSDoc
+ * annotation to that code. And since we've specified the `stripInternal` compiler
+ * option TypeScript will not emit declarations for this code.
+ */
+
+export { Logger, LoggerFactory } from './core/server/logging';
diff --git a/tsconfig.types.json b/tsconfig.types.json
new file mode 100644
index 0000000000000..91029bdae57a6
--- /dev/null
+++ b/tsconfig.types.json
@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "./target/types",
+    "stripInternal": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true
+  },
+  "include": [
+    "./src/type_exports.ts"
+  ]
+}