Track unreferenced deprecated apis count (#121809)

* Track unreferenced deprecated apis count

* Update api docs

packages/kbn-docs-utils/src/api_docs/build_api_docs_cli.ts

@@ -14,7 +14,7 @@ import { REPO_ROOT } from '@kbn/utils';
 import { Project } from 'ts-morph';
 
 import { writePluginDocs } from './mdx/write_plugin_mdx_docs';
-import { ApiDeclaration, PluginMetaInfo } from './types';
+import { ApiDeclaration, ApiStats, PluginMetaInfo } from './types';
 import { findPlugins } from './find_plugins';
 import { pathsOutsideScopes } from './build_api_declarations/utils';
 import { getPluginApiMap } from './get_plugin_api_map';
@@ -70,7 +70,7 @@ export function runBuildApiDocsCli() {
       }
       const collectReferences = flags.references as boolean;
 
-      const { pluginApiMap, missingApiItems, unReferencedDeprecations, referencedDeprecations } =
+      const { pluginApiMap, missingApiItems, unreferencedDeprecations, referencedDeprecations } =
         getPluginApiMap(project, plugins, log, {
           collectReferences,
           pluginFilter: pluginFilter as string[],
@@ -88,7 +88,7 @@ export function runBuildApiDocsCli() {
           isPlugin: plugin.isPlugin,
         };
         return acc;
-      }, {} as { [key: string]: PluginMetaInfo });
+      }, {} as { [key: string]: PluginMetaInfo & ApiStats });
 
       writePluginDirectoryDoc(outputFolder, pluginApiMap, allPluginStats, log);
 
@@ -106,6 +106,12 @@ export function runBuildApiDocsCli() {
         const pluginTeam = plugin.manifest.owner.name;
 
         reporter.metrics([
+          {
+            id,
+            meta: { pluginTeam },
+            group: 'Unreferenced deprecated APIs',
+            value: unreferencedDeprecations[id] ? unreferencedDeprecations[id].length : 0,
+          },
           {
             id,
             meta: { pluginTeam },
@@ -224,7 +230,7 @@ export function runBuildApiDocsCli() {
         writeDeprecationDocByApi(
           outputFolder,
           referencedDeprecations,
-          unReferencedDeprecations,
+          unreferencedDeprecations,
           log
         );
       });

packages/kbn-docs-utils/src/api_docs/get_plugin_api_map.ts

@@ -15,6 +15,7 @@ import {
   PluginApi,
   PluginOrPackage,
   ReferencedDeprecationsByPlugin,
+  UnreferencedDeprecationsByPlugin,
 } from './types';
 import { removeBrokenLinks } from './utils';
 
@@ -27,7 +28,7 @@ export function getPluginApiMap(
   pluginApiMap: { [key: string]: PluginApi };
   missingApiItems: MissingApiItemMap;
   referencedDeprecations: ReferencedDeprecationsByPlugin;
-  unReferencedDeprecations: ApiDeclaration[];
+  unreferencedDeprecations: UnreferencedDeprecationsByPlugin;
 } {
   log.debug('Building plugin API map, getting missing comments, and collecting deprecations...');
   const pluginApiMap: { [key: string]: PluginApi } = {};
@@ -47,21 +48,21 @@ export function getPluginApiMap(
   const missingApiItems: { [key: string]: { [key: string]: string[] } } = {};
   const referencedDeprecations: ReferencedDeprecationsByPlugin = {};
 
-  const unReferencedDeprecations: ApiDeclaration[] = [];
+  const unreferencedDeprecations: UnreferencedDeprecationsByPlugin = {};
 
   plugins.forEach((plugin) => {
     const id = plugin.manifest.id;
     const pluginApi = pluginApiMap[id];
     removeBrokenLinks(pluginApi, missingApiItems, pluginApiMap, log);
-    collectDeprecations(pluginApi, referencedDeprecations, unReferencedDeprecations);
+    collectDeprecations(pluginApi, referencedDeprecations, unreferencedDeprecations);
   });
-  return { pluginApiMap, missingApiItems, referencedDeprecations, unReferencedDeprecations };
+  return { pluginApiMap, missingApiItems, referencedDeprecations, unreferencedDeprecations };
 }
 
 function collectDeprecations(
   pluginApi: PluginApi,
   referencedDeprecations: ReferencedDeprecationsByPlugin,
-  unReferencedDeprecations: ApiDeclaration[]
+  unReferencedDeprecations: UnreferencedDeprecationsByPlugin
 ) {
   (['client', 'common', 'server'] as Array<'client' | 'server' | 'common'>).forEach((scope) => {
     pluginApi[scope].forEach((api) => {
@@ -73,7 +74,7 @@ function collectDeprecations(
 function collectDeprecationsForApi(
   api: ApiDeclaration,
   referencedDeprecations: ReferencedDeprecationsByPlugin,
-  unReferencedDeprecations: ApiDeclaration[]
+  unreferencedDeprecations: UnreferencedDeprecationsByPlugin
 ) {
   if ((api.tags || []).find((tag) => tag === 'deprecated')) {
     if (api.references && api.references.length > 0) {
@@ -87,12 +88,15 @@ function collectDeprecationsForApi(
         });
       });
     } else {
-      unReferencedDeprecations.push(api);
+      if (unreferencedDeprecations[api.parentPluginId] === undefined) {
+        unreferencedDeprecations[api.parentPluginId] = [];
+      }
+      unreferencedDeprecations[api.parentPluginId].push(api);
     }
   }
   if (api.children) {
     api.children.forEach((child) =>
-      collectDeprecationsForApi(child, referencedDeprecations, unReferencedDeprecations)
+      collectDeprecationsForApi(child, referencedDeprecations, unreferencedDeprecations)
     );
   }
 }

packages/kbn-docs-utils/src/api_docs/mdx/write_deprecations_doc_by_api.ts

@@ -11,17 +11,17 @@ import dedent from 'dedent';
 import fs from 'fs';
 import Path from 'path';
 import {
-  ApiDeclaration,
   ApiReference,
   ReferencedDeprecationsByAPI,
   ReferencedDeprecationsByPlugin,
+  UnreferencedDeprecationsByPlugin,
 } from '../types';
 import { getPluginApiDocId } from '../utils';
 
 export function writeDeprecationDocByApi(
   folder: string,
   deprecationsByPlugin: ReferencedDeprecationsByPlugin,
-  unReferencedDeprecations: ApiDeclaration[],
+  unReferencedDeprecations: UnreferencedDeprecationsByPlugin,
   log: ToolingLog
 ): void {
   const deprecationReferencesByApi = Object.values(deprecationsByPlugin).reduce(
@@ -92,14 +92,18 @@ ${tableMdx}
 
 Safe to remove.
 
-| Deprecated API |
-| ---------------|
-${unReferencedDeprecations
-  .map(
-    (api) =>
-      `| <DocLink id="${getPluginApiDocId(api.parentPluginId)}" section="${api.id}" text="${
-        api.label
-      }"/> |`
+| Deprecated API |  Plugin Id |
+| ---------------|------------|
+${Object.values(unReferencedDeprecations)
+  .map((apis) =>
+    apis
+      .map(
+        (api) =>
+          `| <DocLink id="${getPluginApiDocId(api.parentPluginId)}" section="${api.id}" text="${
+            api.label
+          }"/> | ${api.parentPluginId} | `
+      )
+      .join('\n')
   )
   .join('\n')}
 

packages/kbn-docs-utils/src/api_docs/stats.ts

@@ -25,6 +25,7 @@ export function collectApiStatsForPlugin(
     isAnyType: [],
     noReferences: [],
     deprecatedAPIsReferencedCount: 0,
+    unreferencedDeprecatedApisCount: 0,
     apiCount: countApiForPlugin(doc),
     missingExports: Object.values(missingApiItems[doc.id] ?? {}).length,
   };

packages/kbn-docs-utils/src/api_docs/types.ts

@@ -234,6 +234,11 @@ export interface ReferencedDeprecationsByPlugin {
   [key: string]: Array<{ deprecatedApi: ApiDeclaration; ref: ApiReference }>;
 }
 
+export interface UnreferencedDeprecationsByPlugin {
+  // Key is the plugin id.
+  [key: string]: ApiDeclaration[];
+}
+
 // A mapping of deprecated API id to the places that are still referencing it.
 export interface ReferencedDeprecationsByAPI {
   [key: string]: { deprecatedApi: ApiDeclaration; references: ApiReference[] };
@@ -246,6 +251,7 @@ export interface ApiStats {
   apiCount: number;
   missingExports: number;
   deprecatedAPIsReferencedCount: number;
+  unreferencedDeprecatedApisCount: number;
 }
 
 export type PluginMetaInfo = ApiStats & {