elastic · mistic · Nov 30, 2020 · Sep 23, 2020 · Sep 23, 2020 · Oct 6, 2020
diff --git a/docs/developer/best-practices/typescript.asciidoc b/docs/developer/best-practices/typescript.asciidoc
@@ -19,7 +19,7 @@ More details are available in the https://www.typescriptlang.org/docs/handbook/p
 ==== Caveats
 This architecture imposes several limitations to which we must comply:
 
-- Projects cannot have circular dependencies. Even though the Kibana platform doesn't support circular dependencies between Kibana plugins, TypeScript (and ES6 modules) does allow circular imports between files. So in theory, you may face a problem when migrating to the TS project references and you will have to resolve this circular dependency. https://github.com/elastic/kibana/issues/78162 is going to provide a tool to find such problem places.
+- Projects cannot have circular dependencies. Even though the Kibana platform doesn't support circular dependencies between Kibana plugins, TypeScript (and ES6 modules) does allow circular imports between files. So in theory, you may face a problem when migrating to the TS project references and you will have to resolve this circular dependency. We've built a tool that can be used to find such problems. Please read the prerequisites section below to know how to use it.
 - A project must emit its type declaration. It's not always possible to generate a type declaration if the compiler cannot infer a type. There are two basic cases:
 
 1. Your plugin exports a type inferring an internal type declared in Kibana codebase. In this case, you'll have to either export an internal type or to declare an exported type explicitly.
@@ -30,6 +30,8 @@ This architecture imposes several limitations to which we must comply:
 Since project refs rely on generated `d.ts` files, the migration order does matter. You can migrate your plugin only when all the plugin dependencies already have migrated. It creates a situation where commonly used plugins (such as `data` or `kibana_react`) have to migrate first.
 Run `node scripts/find_plugins_without_ts_refs.js --id your_plugin_id` to get a list of plugins that should be switched to TS project refs to unblock your plugin migration.
 
+Additionally, in order to migrate into project refs, you also need to make sure your plugin doesn't have circular dependencies with other plugins. We run a job in the CI for each PR trying to find if new circular dependencies are being added which runs our tool with `node scripts/find_plugins_with_circular_deps`. However there are also a couple of circular dependencies already identified and that are in an allowed list to be solved. You also need to make sure your plugin don't rely in any other plugin into that allowed list. For a complete overview of the circular dependencies both found and in the allowed list as well as the complete circular dependencies path please run the following script locally with the debug flag `node scripts/find_plugins_with_circular_deps --debug` .
+
 [discrete]
 ==== Implementation
 - Make sure all the plugins listed as dependencies in *requiredPlugins*, *optionalPlugins* & *requiredBundles* properties of `kibana.json` manifest file have migrated to TS project references.

diff --git a/package.json b/package.json
@@ -621,6 +621,7 @@
     "delete-empty": "^2.0.0",
     "dependency-check": "^4.1.0",
     "diff": "^4.0.1",
+    "dpdm": "3.5.0",
     "ejs": "^3.1.5",
     "enzyme": "^3.11.0",
     "enzyme-adapter-react-16": "^1.15.2",

diff --git a/scripts/find_plugin_circular_deps.js → scripts/find_plugins_with_circular_deps.js b/scripts/find_plugin_circular_deps.js → scripts/find_plugins_with_circular_deps.js
@@ -18,4 +18,4 @@
  */
 
 require('../src/setup_node_env');
-require('../src/dev/run_find_plugin_circular_deps');
+require('../src/dev/run_find_plugins_with_circular_deps');
diff --git a/src/dev/plugin_discovery/find_plugins.ts b/src/dev/plugin_discovery/find_plugins.ts
@@ -17,9 +17,12 @@
  * under the License.
  */
 import Path from 'path';
-import { REPO_ROOT } from '@kbn/dev-utils';
 import { getPluginSearchPaths } from '@kbn/config';
-import { KibanaPlatformPlugin, simpleKibanaPlatformPluginDiscovery } from '@kbn/dev-utils';
+import {
+  KibanaPlatformPlugin,
+  REPO_ROOT,
+  simpleKibanaPlatformPluginDiscovery,
+} from '@kbn/dev-utils';
 
 export interface SearchOptions {
   oss: boolean;

diff --git a/src/dev/run_find_plugin_circular_deps.ts b/src/dev/run_find_plugin_circular_deps.ts
diff --git a/src/dev/run_find_plugins_with_circular_deps.ts b/src/dev/run_find_plugins_with_circular_deps.ts
@@ -0,0 +1,171 @@
+/*
+ * 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.
+ */
+
+import dedent from 'dedent';
+import { parseDependencyTree, parseCircular, prettyCircular } from 'dpdm';
+import { relative } from 'path';
+import { getPluginSearchPaths } from '@kbn/config';
+import { REPO_ROOT, run } from '@kbn/dev-utils';
+
+interface Options {
+  debug?: boolean;
+}
+
+type CircularDepList = Set<string>;
+
+const allowedList: CircularDepList = new Set([
+  'src/plugins/charts -> src/plugins/expressions',
+  'src/plugins/charts -> src/plugins/vis_default_editor',
+  'src/plugins/data -> src/plugins/embeddable',
+  'src/plugins/data -> src/plugins/expressions',
+  'src/plugins/data -> src/plugins/ui_actions',
+  'src/plugins/embeddable -> src/plugins/ui_actions',
+  'src/plugins/expressions -> src/plugins/visualizations',
+  'src/plugins/vis_default_editor -> src/plugins/visualizations',
+  'src/plugins/vis_default_editor -> src/plugins/visualize',
+  'src/plugins/visualizations -> src/plugins/visualize',
+  'x-pack/plugins/actions -> x-pack/plugins/case',
+  'x-pack/plugins/apm -> x-pack/plugins/infra',
+  'x-pack/plugins/lists -> x-pack/plugins/security_solution',
+  'x-pack/plugins/security -> x-pack/plugins/spaces',
+]);
+
+run(
+  async ({ flags, log }) => {
+    const { debug = false } = flags as Options;
+    const foundList: CircularDepList = new Set();
+
+    const pluginSearchPathGlobs = getPluginSearchPaths({
+      rootDir: REPO_ROOT,
+      oss: false,
+      examples: true,
+    }).map((pluginFolderPath) => `${relative(REPO_ROOT, pluginFolderPath)}/**/*`);
+
+    const depTree = await parseDependencyTree(pluginSearchPathGlobs, {
+      context: REPO_ROOT,
+    });
+
+    // Build list of circular dependencies as well as the circular dependencies full paths
+    const circularDependenciesFullPaths = parseCircular(depTree).filter((circularDeps) => {
+      const first = circularDeps[0];
+      const last = circularDeps[circularDeps.length - 1];
+      const matchRegex = /((src|x-pack)\/plugins|examples|x-pack\/examples)\/([^\/]*)\/.*/;
+      const firstMatch = first.match(matchRegex);
+      const lastMatch = last.match(matchRegex);
+
+      if (firstMatch && lastMatch && firstMatch.length === 4 && lastMatch.length === 4) {
+        const firstPlugin = `${firstMatch[1]}/${firstMatch[3]}`;
+        const lastPlugin = `${lastMatch[1]}/${lastMatch[3]}`;
+        const sortedPlugins = [firstPlugin, lastPlugin].sort();
+
+        if (firstPlugin !== lastPlugin) {
+          foundList.add(`${sortedPlugins[0]} -> ${sortedPlugins[1]}`);
+          return true;
+        }
+      }
+
+      return false;
+    });
+
+    // Log the full circular dependencies path if we are under debug flag
+    if (debug && circularDependenciesFullPaths.length > 0) {
+      log.debug(
+        dedent(`
+      !!!!!!!!!!!!!! CIRCULAR DEPENDENCIES FOUND !!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      ! Circular dependencies were found, you can find below  !
+      ! all the paths involved.                               !
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      `)
+      );
+      log.debug(`${prettyCircular(circularDependenciesFullPaths)}\n`);
+    }
+
+    // Always log the result of comparing the found list with the allowed list
+    const diffSet = (first: CircularDepList, second: CircularDepList) =>
+      new Set([...first].filter((circularDep) => !second.has(circularDep)));
+
+    const printList = (list: CircularDepList) => {
+      return Array.from(list)
+        .sort()
+        .reduce((listStr, entry) => {
+          return listStr ? `${listStr}\n'${entry}',` : `'${entry}',`;
+        }, '');
+    };
+
+    const foundDifferences = diffSet(foundList, allowedList);
+
+    if (debug && !foundDifferences.size) {
+      log.debug(
+        dedent(`
+      !!!!!!!!!!!!!!!!! UP TO DATE ALLOWED LIST !!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      ! The declared circular dependencies allowed list is up    !
+      ! to date and includes every plugin listed in above paths. !
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+      The allowed circular dependencies list is (#${allowedList.size}):
+      ${printList(allowedList)}
+      `)
+      );
+    }
+
+    if (foundDifferences.size > 0) {
+      log.error(
+        dedent(`
+      !!!!!!!!!!!!!!!!! OUT OF DATE ALLOWED LIST !!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      ! The declared circular dependencies allowed list is out   !
+      ! of date. Please run the following locally to know more:  !
+      !                                                          !
+      ! 'node scripts/find_plugins_with_circular_deps --debug'   !
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+      The allowed circular dependencies list is (#${allowedList.size}):
+      ${printList(allowedList)}
+
+      The found circular dependencies list is (#${foundList.size}):
+      ${printList(foundList)}
+
+      The differences between both are (#${foundDifferences.size}):
+      ${printList(foundDifferences)}
+
+      FAILED: circular dependencies in the allowed list declared on the file '${__filename}' did not match the found ones.
+      `)
+      );
+
+      process.exit(1);
+    }
+
+    log.success('None non allowed circular dependencies were found');
+  },
+  {
+    description:
+      'Searches circular dependencies between plugins located under src/plugins, x-pack/plugins, examples and x-pack/examples',
+    flags: {
+      boolean: ['debug'],
+      default: {
+        debug: false,
+      },
+      help: `
+        --debug            Run the script in debug mode which enables detailed path logs for circular dependencies
+      `,
+    },
+  }
+);
diff --git a/test/scripts/checks/plugins_with_circular_deps.sh b/test/scripts/checks/plugins_with_circular_deps.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+source src/dev/ci_setup/setup_env.sh
+
+checks-reporter-with-killswitch "Check plugins with circular dependencies" \
+  node scripts/find_plugins_with_circular_deps
diff --git a/vars/tasks.groovy b/vars/tasks.groovy
@@ -12,6 +12,7 @@ def check() {
     kibanaPipeline.scriptTask('Check i18n', 'test/scripts/checks/i18n.sh'),
     kibanaPipeline.scriptTask('Check File Casing', 'test/scripts/checks/file_casing.sh'),
     kibanaPipeline.scriptTask('Check Licenses', 'test/scripts/checks/licenses.sh'),
+    kibanaPipeline.scriptTask('Check Plugins With Circular Dependencies', 'test/scripts/checks/plugins_with_circular_deps.sh'),
     kibanaPipeline.scriptTask('Verify NOTICE', 'test/scripts/checks/verify_notice.sh'),
     kibanaPipeline.scriptTask('Test Projects', 'test/scripts/checks/test_projects.sh'),
     kibanaPipeline.scriptTask('Test Hardening', 'test/scripts/checks/test_hardening.sh'),

diff --git a/yarn.lock b/yarn.lock
@@ -4626,6 +4626,13 @@
   dependencies:
     "@types/jquery" "*"
 
+"@types/fs-extra@^8.0.0":
+  version "8.1.1"
+  resolved "https://registry.yarnpkg.com/@types/fs-extra/-/fs-extra-8.1.1.tgz#1e49f22d09aa46e19b51c0b013cb63d0d923a068"
+  integrity sha512-TcUlBem321DFQzBNuz8p0CLLKp0VvF/XH9E4KHNmgwyp4E3AfgI5cjiIVZWlbfThBop2qxFIh4+LeY6hVWWZ2w==
+  dependencies:
+    "@types/node" "*"
+
 "@types/geojson@*", "@types/geojson@7946.0.7":
   version "7946.0.7"
   resolved "https://registry.yarnpkg.com/@types/geojson/-/geojson-7946.0.7.tgz#c8fa532b60a0042219cdf173ca21a975ef0666ad"
@@ -11938,6 +11945,22 @@ dotignore@^0.1.2:
   dependencies:
     minimatch "^3.0.4"
 
+dpdm@3.5.0:
+  version "3.5.0"
+  resolved "https://registry.yarnpkg.com/dpdm/-/dpdm-3.5.0.tgz#414402f21928694bc86cfe8e3583dc8fc97d013e"
+  integrity sha512-bff2gDpYyzmIOMwRp0Bsk0T4e/qgLRCeuGHZYEsJV0LRzuTUkXirCiLcme7Ebu/LVoQ8yAKiody5/1e51tsmFw==
+  dependencies:
+    "@types/fs-extra" "^8.0.0"
+    "@types/glob" "^7.1.1"
+    "@types/yargs" "^13.0.0"
+    chalk "^2.4.2"
+    fs-extra "^8.1.0"
+    glob "^7.1.4"
+    ora "^4.0.3"
+    tslib "^1.10.0"
+    typescript "^3.5.3"
+    yargs "^13.3.0"
+
 dtrace-provider@~0.8:
   version "0.8.8"
   resolved "https://registry.yarnpkg.com/dtrace-provider/-/dtrace-provider-0.8.8.tgz#2996d5490c37e1347be263b423ed7b297fb0d97e"
@@ -14125,6 +14148,15 @@ fs-extra@^7.0.0, fs-extra@^7.0.1, fs-extra@~7.0.1:
     jsonfile "^4.0.0"
     universalify "^0.1.0"
 
+fs-extra@^8.1.0:
+  version "8.1.0"
+  resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-8.1.0.tgz#49d43c45a88cd9677668cb7be1b46efdb8d2e1c0"
+  integrity sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==
+  dependencies:
+    graceful-fs "^4.2.0"
+    jsonfile "^4.0.0"
+    universalify "^0.1.0"
+
 fs-extra@^9.0.0, fs-extra@^9.0.1:
   version "9.0.1"
   resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-9.0.1.tgz#910da0062437ba4c39fedd863f1675ccfefcb9fc"
@@ -21339,7 +21371,7 @@ ora@^3.0.0:
     strip-ansi "^5.2.0"
     wcwidth "^1.0.1"
 
-ora@^4.0.4:
+ora@^4.0.3, ora@^4.0.4:
   version "4.1.1"
   resolved "https://registry.yarnpkg.com/ora/-/ora-4.1.1.tgz#566cc0348a15c36f5f0e979612842e02ba9dddbc"
   integrity sha512-sjYP8QyVWBpBZWD6Vr1M/KwknSw6kJOz41tvGMlwWeClHBtYKTbHMki1PsLZnxKpXMPbTKv9b3pjQu3REib96A==
@@ -27649,7 +27681,7 @@ typescript-tuple@^2.2.1:
   dependencies:
     typescript-compare "^0.0.2"
 
-typescript@4.0.2, typescript@^3.0.3, typescript@^3.2.2, typescript@^3.3.3333, typescript@^3.4.5, typescript@~3.7.2:
+typescript@4.0.2, typescript@^3.0.3, typescript@^3.2.2, typescript@^3.3.3333, typescript@^3.4.5, typescript@^3.5.3, typescript@~3.7.2:
   version "4.0.2"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.0.2.tgz#7ea7c88777c723c681e33bf7988be5d008d05ac2"
   integrity sha512-e4ERvRV2wb+rRZ/IQeb3jm2VxBsirQLpQhdxplZ2MEzGvDkkMmPglecnNDfSUBivMjP93vRbngYYDQqQ/78bcQ==