[7.x] Add plugin list to docs that is generated from the repo (#71731) (#72138)

Co-authored-by: Stacey Gammon <gammon@elastic.co>
Co-authored-by: spalger <spalger@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
# Conflicts:
#	src/dev/ci_setup/setup.sh

.ci/pipeline-library/src/test/prChanges.groovy

@@ -84,4 +84,17 @@ class PrChangesTest extends KibanaBasePipelineTest {
 
     assertFalse(prChanges.areChangesSkippable())
   }
+
+  @Test
+  void 'areChangesSkippable() with skippable changes that are in notSkippablePaths'() {
+    props([
+      githubPrs: [
+        getChanges: { [
+          [filename: 'docs/developer/architecture/code-exploration.asciidoc'],
+        ] },
+      ],
+    ])
+
+    assertFalse(prChanges.areChangesSkippable())
+  }
 }

docs/developer/architecture/code-exploration.asciidoc

@@ -0,0 +1,586 @@
+////
+
+NOTE:
+  This is an automatically generated file. Please do not edit directly. Instead, run the
+  following from within the kibana repository:
+
+    node scripts/build_plugin_list_docs
+
+  You can update the template within packages/kbn-dev-utils/target/plugin_list/generate_plugin_list.js
+
+////
+
+[[code-exploration]]
+=== Exploring Kibana code
+
+The goals of our folder heirarchy are:
+
+- Easy for developers to know where to add new services, plugins and applications.
+- Easy for developers to know where to find the code from services, plugins and applications.
+- Easy to browse and understand our folder structure.
+
+To that aim, we strive to:
+
+- Avoid too many files in any given folder.
+- Choose clear, unambigious folder names.
+- Organize by domain.
+- Every folder should contain a README that describes the contents of that folder.
+
+[discrete]
+[[kibana-services-applications]]
+==== Services and Applications
+
+[discrete]
+===== src/plugins
+
+- {kib-repo}blob/{branch}/src/plugins/advanced_settings[advancedSettings]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/apm_oss[apmOss]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/bfetch/README.md[bfetch]
+
+bfetch allows to batch HTTP requests and streams responses back.
+
+
+- {kib-repo}blob/{branch}/src/plugins/charts/README.md[charts]
+
+The Charts plugin is a way to create easier integration of shared colors, themes, types and other utilities across all Kibana charts and visualizations.
+
+
+- {kib-repo}blob/{branch}/src/plugins/console[console]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/dashboard[dashboard]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/data/README.md[data]
+
+data plugin provides common data access services.
+
+
+- {kib-repo}blob/{branch}/src/plugins/dev_tools/README.md[devTools]
+
+The ui/registry/dev_tools is removed in favor of the devTools plugin which exposes a register method in the setup contract.
+Registering app works mostly the same as registering apps in core.application.register.
+Routing will be handled by the id of the dev tool - your dev tool will be mounted when the URL matches /app/dev_tools#/<YOUR ID>.
+This API doesn't support angular, for registering angular dev tools, bootstrap a local module on mount into the given HTML element.
+
+
+- {kib-repo}blob/{branch}/src/plugins/discover[discover]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/embeddable/README.md[embeddable]
+
+Embeddables are re-usable widgets that can be rendered in any environment or plugin. Developers can embed them directly in their plugin. End users can dynamically add them to any embeddable containers.
+
+
+- {kib-repo}blob/{branch}/src/plugins/es_ui_shared[esUiShared]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/expressions/README.md[expressions]
+
+This plugin provides methods which will parse & execute an expression pipeline
+string for you, as well as a series of registries for advanced users who might
+want to incorporate their own functions, types, and renderers into the service
+for use in their own application.
+
+
+- {kib-repo}blob/{branch}/src/plugins/home/README.md[home]
+
+Moves the legacy ui/registry/feature_catalogue module for registering "features" that should be shown in the home page's feature catalogue to a service within a "home" plugin. The feature catalogue refered to here should not be confused with the "feature" plugin for registering features used to derive UI capabilities for feature controls.
+
+
+- {kib-repo}blob/{branch}/src/plugins/index_pattern_management[indexPatternManagement]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/input_control_vis[inputControlVis]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/inspector/README.md[inspector]
+
+The inspector is a contextual tool to gain insights into different elements
+in Kibana, e.g. visualizations. It has the form of a flyout panel.
+
+
+- {kib-repo}blob/{branch}/src/plugins/kibana_legacy/README.md[kibanaLegacy]
+
+This plugin will contain several helpers and services to integrate pieces of the legacy Kibana app with the new Kibana platform.
+
+
+- {kib-repo}blob/{branch}/src/plugins/kibana_react/README.md[kibanaReact]
+
+Tools for building React applications in Kibana.
+
+
+- {kib-repo}blob/{branch}/src/plugins/kibana_usage_collection/README.md[kibanaUsageCollection]
+
+This plugin registers the basic usage collectors from Kibana:
+
+
+- {kib-repo}blob/{branch}/src/plugins/kibana_utils/README.md[kibanaUtils]
+
+Utilities for building Kibana plugins.
+
+
+- {kib-repo}blob/{branch}/src/plugins/legacy_export[legacyExport]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/management[management]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/maps_legacy[mapsLegacy]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/navigation/README.md[navigation]
+
+The navigation plugins exports the TopNavMenu component.
+It also provides a stateful version of it on the start contract.
+
+
+- {kib-repo}blob/{branch}/src/plugins/newsfeed[newsfeed]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/region_map[regionMap]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/saved_objects[savedObjects]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/saved_objects_management[savedObjectsManagement]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/share/README.md[share]
+
+Replaces the legacy ui/share module for registering share context menus.
+
+
+- {kib-repo}blob/{branch}/src/plugins/status_page[statusPage]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/telemetry/README.md[telemetry]
+
+Telemetry allows Kibana features to have usage tracked in the wild. The general term "telemetry" refers to multiple things:
+
+
+- {kib-repo}blob/{branch}/src/plugins/telemetry_collection_manager/README.md[telemetryCollectionManager]
+
+Telemetry's collection manager to go through all the telemetry sources when fetching it before reporting.
+
+
+- {kib-repo}blob/{branch}/src/plugins/telemetry_management_section/README.md[telemetryManagementSection]
+
+This plugin adds the Advanced Settings section for the Usage Data collection (aka Telemetry).
+
+
+- {kib-repo}blob/{branch}/src/plugins/tile_map[tileMap]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/timelion[timelion]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/ui_actions/README.md[uiActions]
+
+An API for:
+
+
+- {kib-repo}blob/{branch}/src/plugins/usage_collection/README.md[usageCollection]
+
+Usage Collection allows collecting usage data for other services to consume (telemetry and monitoring).
+To integrate with the telemetry services for usage collection of your feature, there are 2 steps:
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_markdown[visTypeMarkdown]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_metric[visTypeMetric]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_table[visTypeTable]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_tagcloud[visTypeTagcloud]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_timelion/README.md[visTypeTimelion]
+
+If your grammar was changed in public/chain.peg you need to re-generate the static parser. You could use a grunt task:
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_timeseries[visTypeTimeseries]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_vega[visTypeVega]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_vislib[visTypeVislib]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/vis_type_xy[visTypeXy]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/visualizations[visualizations]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/src/plugins/visualize[visualize]
+
+WARNING: Missing README.
+
+
+[discrete]
+===== x-pack/plugins
+
+- {kib-repo}blob/{branch}/x-pack/plugins/actions/README.md[actions]
+
+The Kibana actions plugin provides a framework to create executable actions. You can:
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/alerting_builtins/README.md[alertingBuiltins]
+
+This plugin provides alertTypes shipped with Kibana for use with the
+the alerts plugin.  When enabled, it will register
+the built-in alertTypes with the alerting plugin, register associated HTTP
+routes, etc.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/alerts/README.md[alerts]
+
+The Kibana alerting plugin provides a common place to set up alerts. You can:
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/apm/readme.md[apm]
+
+To access an elasticsearch instance that has live data you have two options:
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/audit_trail[auditTrail]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/beats_management[beats_management]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/canvas/README.md[canvas]
+
+"Never look back. The past is done. The future is a blank canvas." ― Suzy Kassem, Rise Up and Salute the Sun
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/case/README.md[case]
+
+Experimental Feature
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/cloud[cloud]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/code[code]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/console_extensions[consoleExtensions]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/cross_cluster_replication/README.md[crossClusterReplication]
+
+You can run a local cluster and simulate a remote cluster within a single Kibana directory.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/dashboard_enhanced/README.md[dashboardEnhanced]
+
+- {kib-repo}blob/{branch}/x-pack/plugins/dashboard_mode[dashboardMode]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/data_enhanced[dataEnhanced]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/discover_enhanced[discoverEnhanced]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/embeddable_enhanced/README.md[embeddableEnhanced]
+
+- {kib-repo}blob/{branch}/x-pack/plugins/encrypted_saved_objects/README.md[encryptedSavedObjects]
+
+The purpose of this plugin is to provide a way to encrypt/decrypt attributes on the custom Saved Objects that works with
+security and spaces filtering as well as performing audit logging.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/enterprise_search/README.md[enterpriseSearch]
+
+This plugin's goal is to provide a Kibana user interface to the Enterprise Search solution's products (App Search and Workplace Search). In it's current MVP state, the plugin provides the following with the goal of gathering user feedback and raising product awareness:
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/event_log/README.md[eventLog]
+
+The purpose of this plugin is to provide a way to persist a history of events
+occuring in Kibana, initially just for the Make It Action project - alerts
+and actions.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/features[features]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/file_upload[fileUpload]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/global_search/README.md[globalSearch]
+
+The GlobalSearch plugin provides an easy way to search for various objects, such as applications
+or dashboards from the Kibana instance, from both server and client-side plugins
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/global_search_providers[globalSearchProviders]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/graph/README.md[graph]
+
+This is the main source folder of the Graph plugin. It contains all of the Kibana server and client source code. x-pack/test/functional/apps/graph contains additional functional tests.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/grokdebugger/README.md[grokdebugger]
+
+- {kib-repo}blob/{branch}/x-pack/plugins/index_lifecycle_management/README.md[indexLifecycleManagement]
+
+You can test that the Frozen badge, phase filtering, and lifecycle information is surfaced in
+Index Management by running this series of requests in Console:
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/index_management[indexManagement]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/infra/README.md[infra]
+
+This is the home of the infra plugin, which aims to provide a solution for
+the infrastructure monitoring use-case within Kibana.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/ingest_manager/README.md[ingestManager]
+
+Fleet needs to have Elasticsearch API keys enabled, and also to have TLS enabled on kibana, (if you want to run Kibana without TLS you can provide the following config flag --xpack.ingestManager.fleet.tlsCheckDisabled=false)
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/ingest_pipelines/README.md[ingestPipelines]
+
+The ingest_pipelines plugin provides Kibana support for Elasticsearch's ingest nodes. Please refer to the Elasticsearch documentation for more details.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/lens/readme.md[lens]
+
+Run all tests from the x-pack root directory
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/license_management[licenseManagement]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/licensing/README.md[licensing]
+
+The licensing plugin retrieves license data from Elasticsearch at regular configurable intervals.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/lists/README.md[lists]
+
+README.md for developers working on the backend lists on how to get started
+using the CURL scripts in the scripts folder.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/logstash[logstash]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/maps/README.md[maps]
+
+Visualize geo data from Elasticsearch or 3rd party geo-services.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/maps_legacy_licensing/README.md[mapsLegacyLicensing]
+
+This plugin provides access to the detailed tile map services from Elastic.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/ml[ml]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/monitoring[monitoring]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/observability/README.md[observability]
+
+This plugin provides shared components and services for use across observability solutions, as well as the observability landing page UI.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/oss_telemetry[ossTelemetry]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/painless_lab[painlessLab]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/remote_clusters[remoteClusters]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/reporting/README.md[reporting]
+
+An awesome Kibana reporting plugin
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/rollup/README.md[rollup]
+
+Welcome to the Kibana rollup plugin! This plugin provides Kibana support for Elasticsearch's rollup feature. Please refer to the Elasticsearch documentation to understand rollup indices and how to create rollup jobs.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/searchprofiler[searchprofiler]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/security/README.md[security]
+
+See Configuring security in Kibana.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/security_solution[securitySolution]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/snapshot_restore/README.md[snapshotRestore]
+
+or
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/spaces[spaces]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/task_manager[taskManager]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/telemetry_collection_xpack/README.md[telemetryCollectionXpack]
+
+Gathers all usage collection, retrieving them from both: OSS and X-Pack plugins.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/transform[transform]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/translations[translations]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/triggers_actions_ui/README.md[triggers_actions_ui]
+
+The Kibana alerts and actions UI plugin provides a user interface for managing alerts and actions.
+As a developer you can reuse and extend built-in alerts and actions UI functionality:
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/ui_actions_enhanced/README.md[uiActionsEnhanced]
+
+- {kib-repo}blob/{branch}/x-pack/plugins/upgrade_assistant[upgradeAssistant]
+
+WARNING: Missing README.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/uptime/README.md[uptime]
+
+The purpose of this plugin is to provide users of Heartbeat more visibility of what's happening
+in their infrastructure.
+
+
+- {kib-repo}blob/{branch}/x-pack/plugins/watcher/README.md[watcher]
+
+This plugins adopts some conventions in addition to or in place of conventions in Kibana (at the time of the plugin's creation):
+

docs/developer/architecture/index.asciidoc

@@ -17,9 +17,12 @@ A few notable services are called out below.
 * <<development-security>>
 * <<add-data-tutorials>>
 * <<development-visualize-index>>
+* <<code-exploration>>
 
 include::add-data-tutorials.asciidoc[leveloffset=+1]
 
 include::development-visualize-index.asciidoc[leveloffset=+1]
 
 include::security/index.asciidoc[leveloffset=+1]
+
+include::code-exploration.asciidoc[leveloffset=+1]

packages/kbn-dev-utils/package.json

@@ -17,6 +17,7 @@
     "exit-hook": "^2.2.0",
     "getopts": "^2.2.5",
     "load-json-file": "^6.2.0",
+    "normalize-path": "^3.0.0",
     "moment": "^2.24.0",
     "rxjs": "^6.5.5",
     "tree-kill": "^1.2.2",

packages/kbn-dev-utils/src/index.ts

@@ -39,3 +39,5 @@ export { KbnClient } from './kbn_client';
 export * from './axios';
 export * from './stdio';
 export * from './ci_stats_reporter';
+export * from './plugin_list';
+export * from './simple_kibana_platform_plugin_discovery';

packages/kbn-dev-utils/src/plugin_list/discover_plugins.ts

@@ -0,0 +1,69 @@
+/*
+ * 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 Path from 'path';
+import Fs from 'fs';
+
+import MarkdownIt from 'markdown-it';
+import cheerio from 'cheerio';
+
+import { REPO_ROOT } from '../repo_root';
+import { simpleKibanaPlatformPluginDiscovery } from '../simple_kibana_platform_plugin_discovery';
+
+export interface Plugin {
+  id: string;
+  relativeDir?: string;
+  relativeReadmePath?: string;
+  readmeSnippet?: string;
+}
+
+export type Plugins = Plugin[];
+
+const getReadmeName = (directory: string) =>
+  Fs.readdirSync(directory).find((name) => name.toLowerCase() === 'readme.md');
+
+export const discoverPlugins = (pluginsRootDir: string): Plugins =>
+  simpleKibanaPlatformPluginDiscovery([pluginsRootDir], []).map(
+    ({ directory, manifest: { id } }): Plugin => {
+      const readmeName = getReadmeName(directory);
+
+      let relativeReadmePath: string | undefined;
+      let readmeSnippet: string | undefined;
+      if (readmeName) {
+        const readmePath = Path.resolve(directory, readmeName);
+        relativeReadmePath = Path.relative(REPO_ROOT, readmePath);
+
+        const md = new MarkdownIt();
+        const parsed = md.render(Fs.readFileSync(readmePath, 'utf8'));
+        const $ = cheerio.load(parsed);
+
+        const firstParagraph = $('p')[0];
+        if (firstParagraph) {
+          readmeSnippet = $(firstParagraph).text();
+        }
+      }
+
+      return {
+        id,
+        relativeReadmePath,
+        relativeDir: relativeReadmePath || Path.relative(REPO_ROOT, directory),
+        readmeSnippet,
+      };
+    }
+  );

packages/kbn-dev-utils/src/plugin_list/generate_plugin_list.ts

@@ -0,0 +1,84 @@
+/*
+ * 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 Path from 'path';
+
+import normalizePath from 'normalize-path';
+
+import { REPO_ROOT } from '../repo_root';
+import { Plugins } from './discover_plugins';
+
+function* printPlugins(plugins: Plugins) {
+  for (const plugin of plugins) {
+    const path = plugin.relativeReadmePath || plugin.relativeDir;
+    yield '';
+    yield `- {kib-repo}blob/{branch}/${path}[${plugin.id}]`;
+
+    if (!plugin.relativeReadmePath || plugin.readmeSnippet) {
+      yield '';
+      yield plugin.readmeSnippet || 'WARNING: Missing README.';
+      yield '';
+    }
+  }
+}
+
+export function generatePluginList(ossPlugins: Plugins, xpackPlugins: Plugins) {
+  return `////
+
+NOTE:
+  This is an automatically generated file. Please do not edit directly. Instead, run the
+  following from within the kibana repository:
+
+    node scripts/build_plugin_list_docs
+
+  You can update the template within ${normalizePath(
+    Path.relative(REPO_ROOT, Path.resolve(__dirname, __filename))
+  )}
+
+////
+
+[[code-exploration]]
+=== Exploring Kibana code
+
+The goals of our folder heirarchy are:
+
+- Easy for developers to know where to add new services, plugins and applications.
+- Easy for developers to know where to find the code from services, plugins and applications.
+- Easy to browse and understand our folder structure.
+
+To that aim, we strive to:
+
+- Avoid too many files in any given folder.
+- Choose clear, unambigious folder names.
+- Organize by domain.
+- Every folder should contain a README that describes the contents of that folder.
+
+[discrete]
+[[kibana-services-applications]]
+==== Services and Applications
+
+[discrete]
+===== src/plugins
+${Array.from(printPlugins(ossPlugins)).join('\n')}
+
+[discrete]
+===== x-pack/plugins
+${Array.from(printPlugins(xpackPlugins)).join('\n')}
+`;
+}

packages/kbn-dev-utils/src/plugin_list/index.ts

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+
+export * from './run_plugin_list_cli';

packages/kbn-dev-utils/src/plugin_list/run_plugin_list_cli.ts

@@ -0,0 +1,49 @@
+/*
+ * 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 Path from 'path';
+import Fs from 'fs';
+
+import { run } from '../run';
+import { REPO_ROOT } from '../repo_root';
+
+import { discoverPlugins } from './discover_plugins';
+import { generatePluginList } from './generate_plugin_list';
+
+const OSS_PLUGIN_DIR = Path.resolve(REPO_ROOT, 'src/plugins');
+const XPACK_PLUGIN_DIR = Path.resolve(REPO_ROOT, 'x-pack/plugins');
+const OUTPUT_PATH = Path.resolve(
+  REPO_ROOT,
+  'docs/developer/architecture/code-exploration.asciidoc'
+);
+
+export function runPluginListCli() {
+  run(async ({ log }) => {
+    log.info('looking for oss plugins');
+    const ossPlugins = discoverPlugins(OSS_PLUGIN_DIR);
+    log.success(`found ${ossPlugins.length} plugins`);
+
+    log.info('looking for x-pack plugins');
+    const xpackPlugins = discoverPlugins(XPACK_PLUGIN_DIR);
+    log.success(`found ${xpackPlugins.length} plugins`);
+
+    log.info('writing plugin list to', OUTPUT_PATH);
+    Fs.writeFileSync(OUTPUT_PATH, generatePluginList(ossPlugins, xpackPlugins));
+  });
+}

packages/kbn-dev-utils/src/simple_kibana_platform_plugin_discovery.ts

@@ -0,0 +1,86 @@
+/*
+ * 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 Path from 'path';
+
+import globby from 'globby';
+import loadJsonFile from 'load-json-file';
+
+export interface KibanaPlatformPlugin {
+  readonly directory: string;
+  readonly manifestPath: string;
+  readonly manifest: {
+    id: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Helper to find the new platform plugins.
+ */
+export function simpleKibanaPlatformPluginDiscovery(scanDirs: string[], paths: string[]) {
+  const patterns = Array.from(
+    new Set([
+      // find kibana.json files up to 5 levels within the scan dir
+      ...scanDirs.reduce(
+        (acc: string[], dir) => [
+          ...acc,
+          `${dir}/*/kibana.json`,
+          `${dir}/*/*/kibana.json`,
+          `${dir}/*/*/*/kibana.json`,
+          `${dir}/*/*/*/*/kibana.json`,
+          `${dir}/*/*/*/*/*/kibana.json`,
+        ],
+        []
+      ),
+      ...paths.map((path) => `${path}/kibana.json`),
+    ])
+  );
+
+  const manifestPaths = globby.sync(patterns, { absolute: true }).map((path) =>
+    // absolute paths returned from globby are using normalize or something so the path separators are `/` even on windows, Path.resolve solves this
+    Path.resolve(path)
+  );
+
+  return manifestPaths.map(
+    (manifestPath): KibanaPlatformPlugin => {
+      if (!Path.isAbsolute(manifestPath)) {
+        throw new TypeError('expected new platform manifest path to be absolute');
+      }
+
+      const manifest = loadJsonFile.sync(manifestPath);
+      if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+        throw new TypeError('expected new platform plugin manifest to be a JSON encoded object');
+      }
+
+      if (typeof manifest.id !== 'string') {
+        throw new TypeError('expected new platform plugin manifest to have a string id');
+      }
+
+      return {
+        directory: Path.dirname(manifestPath),
+        manifestPath,
+        manifest: {
+          ...manifest,
+          id: manifest.id,
+        },
+      };
+    }
+  );
+}

packages/kbn-optimizer/src/optimizer/kibana_platform_plugins.ts

@@ -17,10 +17,7 @@
  * under the License.
  */
 
-import Path from 'path';
-
-import globby from 'globby';
-import loadJsonFile from 'load-json-file';
+import { simpleKibanaPlatformPluginDiscovery } from '@kbn/dev-utils';
 
 export interface KibanaPlatformPlugin {
   readonly directory: string;
@@ -30,72 +27,32 @@ export interface KibanaPlatformPlugin {
   readonly extraPublicDirs: string[];
 }
 
+const isArrayOfStrings = (input: any): input is string[] =>
+  Array.isArray(input) && input.every((p) => typeof p === 'string');
+
 /**
  * Helper to find the new platform plugins.
  */
 export function findKibanaPlatformPlugins(scanDirs: string[], paths: string[]) {
-  return globby
-    .sync(
-      Array.from(
-        new Set([
-          ...scanDirs.map(nestedScanDirPaths).reduce((dirs, current) => [...dirs, ...current], []),
-          ...paths.map((path) => `${path}/kibana.json`),
-        ])
-      ),
-      {
-        absolute: true,
+  return simpleKibanaPlatformPluginDiscovery(scanDirs, paths).map(
+    ({ directory, manifestPath, manifest }): KibanaPlatformPlugin => {
+      let extraPublicDirs: string[] | undefined;
+      if (manifest.extraPublicDirs) {
+        if (!isArrayOfStrings(manifest.extraPublicDirs)) {
+          throw new TypeError(
+            'expected new platform plugin manifest to have an array of strings `extraPublicDirs` property'
+          );
+        }
+        extraPublicDirs = manifest.extraPublicDirs;
       }
-    )
-    .map((path) =>
-      // absolute paths returned from globby are using normalize or something so the path separators are `/` even on windows, Path.resolve solves this
-      readKibanaPlatformPlugin(Path.resolve(path))
-    );
-}
 
-function nestedScanDirPaths(dir: string): string[] {
-  // down to 5 level max
-  return [
-    `${dir}/*/kibana.json`,
-    `${dir}/*/*/kibana.json`,
-    `${dir}/*/*/*/kibana.json`,
-    `${dir}/*/*/*/*/kibana.json`,
-    `${dir}/*/*/*/*/*/kibana.json`,
-  ];
-}
-
-function readKibanaPlatformPlugin(manifestPath: string): KibanaPlatformPlugin {
-  if (!Path.isAbsolute(manifestPath)) {
-    throw new TypeError('expected new platform manifest path to be absolute');
-  }
-
-  const manifest = loadJsonFile.sync(manifestPath);
-  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
-    throw new TypeError('expected new platform plugin manifest to be a JSON encoded object');
-  }
-
-  if (typeof manifest.id !== 'string') {
-    throw new TypeError('expected new platform plugin manifest to have a string id');
-  }
-
-  let extraPublicDirs: string[] | undefined;
-  if (manifest.extraPublicDirs) {
-    if (
-      !Array.isArray(manifest.extraPublicDirs) ||
-      !manifest.extraPublicDirs.every((p) => typeof p === 'string')
-    ) {
-      throw new TypeError(
-        'expected new platform plugin manifest to have an array of strings `extraPublicDirs` property'
-      );
+      return {
+        directory,
+        manifestPath,
+        id: manifest.id,
+        isUiPlugin: !!manifest.ui,
+        extraPublicDirs: extraPublicDirs || [],
+      };
     }
-
-    extraPublicDirs = manifest.extraPublicDirs as string[];
-  }
-
-  return {
-    directory: Path.dirname(manifestPath),
-    manifestPath,
-    id: manifest.id,
-    isUiPlugin: !!manifest.ui,
-    extraPublicDirs: extraPublicDirs || [],
-  };
+  );
 }

scripts/build_plugin_list_docs.js

@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+
+require('../src/setup_node_env/prebuilt_dev_only_entry');
+require('@kbn/dev-utils').runPluginListCli();

src/dev/ci_setup/setup.sh

@@ -49,3 +49,19 @@ if [ "$GIT_CHANGES" ]; then
   echo -e "$GIT_CHANGES\n"
   exit 1
 fi
+
+###
+### rebuild plugin list to ensure it's not out of date
+###
+echo " -- building plugin list docs"
+node scripts/build_plugin_list_docs
+
+###
+### verify no git modifications
+###
+GIT_CHANGES="$(git ls-files --modified)"
+if [ "$GIT_CHANGES" ]; then
+  echo -e "\n${RED}ERROR: 'node scripts/build_plugin_list_docs' caused changes to the following files:${C_RESET}\n"
+  echo -e "$GIT_CHANGES\n"
+  exit 1
+fi

vars/prChanges.groovy

@@ -2,6 +2,8 @@ import groovy.transform.Field
 
 public static @Field PR_CHANGES_CACHE = []
 
+// if all the changed files in a PR match one of these regular
+// expressions then CI will be skipped for that PR
 def getSkippablePaths() {
   return [
     /^docs\//,
@@ -14,6 +16,15 @@ def getSkippablePaths() {
   ]
 }
 
+// exclusion regular expressions that will invalidate paths that
+// match one of the skippable path regular expressions
+def getNotSkippablePaths() {
+  return [
+    // this file is auto-generated and changes to it need to be validated with CI
+    /^docs\/developer\/architecture\/code-exploration.asciidoc$/,
+  ]
+}
+
 def areChangesSkippable() {
   if (!githubPr.isPr()) {
     return false
@@ -21,6 +32,7 @@ def areChangesSkippable() {
 
   try {
     def skippablePaths = getSkippablePaths()
+    def notSkippablePaths = getNotSkippablePaths()
     def files = getChangedFiles()
 
     // 3000 is the max files GH API will return
@@ -29,7 +41,8 @@ def areChangesSkippable() {
     }
 
     files = files.findAll { file ->
-      return !skippablePaths.find { regex -> file =~ regex}
+      def skippable = skippablePaths.find { regex -> file =~ regex} && !notSkippablePaths.find { regex -> file =~ regex }
+      return !skippable
     }
 
     return files.size() < 1