[kbn-docs-utils] Improve CLI output and single-plugin/package build performance

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

@@ -82,11 +82,13 @@ describe('build_api_docs_cli', () => {
   });
 
   it('runs build flow when stats are not provided', async () => {
+    const mockPlugins = [
+      { id: 'p1', manifest: { owner: { name: 'team' }, serviceFolders: [] }, isPlugin: true },
+    ];
     const setupResult = {
       project: {},
-      plugins: [
-        { id: 'p1', manifest: { owner: { name: 'team' }, serviceFolders: [] }, isPlugin: true },
-      ],
+      plugins: mockPlugins,
+      allPlugins: mockPlugins,
     };
     const apiMapResult = {
       pluginApiMap: {},
@@ -107,6 +109,7 @@ describe('build_api_docs_cli', () => {
     expect(buildApiMap).toHaveBeenCalledWith(
       setupResult.project,
       setupResult.plugins,
+      setupResult.allPlugins,
       log,
       mockTx,
       { stats: undefined, collectReferences: false }

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

@@ -85,6 +85,7 @@ export function runBuildApiDocsCli() {
       const apiMapResult = buildApiMap(
         setupResult.project,
         setupResult.plugins,
+        setupResult.allPlugins,
         log,
         transaction,
         options

packages/kbn-docs-utils/src/check_package_docs_cli.run.test.ts

@@ -90,7 +90,7 @@ describe('runCheckPackageDocs', () => {
     expect(reportMetrics).toHaveBeenCalled();
     expect(process.exitCode).toBe(1);
     expect(log.error).toHaveBeenCalledWith(
-      expect.stringContaining('Validation failed for 1 plugin')
+      expect.stringContaining('Validation failed for 1 package')
     );
     expect(mockTx.end).toHaveBeenCalled();
   });
@@ -129,7 +129,7 @@ describe('runCheckPackageDocs', () => {
     await runCheckPackageDocs(log as any, { plugin: 'plugin-a' } as any);
 
     expect(process.exitCode).toBeUndefined();
-    expect(log.info).toHaveBeenCalledWith('All plugins passed validation.');
+    expect(log.info).toHaveBeenCalledWith('All packages passed validation.');
     expect(mockTx.end).toHaveBeenCalled();
   });
 });

packages/kbn-docs-utils/src/check_package_docs_cli.ts

@@ -129,6 +129,7 @@ export const runCheckPackageDocs = async (log: ToolingLog, flags: CliFlags) => {
     const apiMapResult = buildApiMap(
       setupResult.project,
       setupResult.plugins,
+      setupResult.allPlugins,
       log,
       transaction,
       optionsWithChecks
@@ -160,13 +161,13 @@ export const runCheckPackageDocs = async (log: ToolingLog, flags: CliFlags) => {
 
     if (failingPlugins.length > 0) {
       log.error(
-        `Validation failed for ${failingPlugins.length} plugin(s): ${failingPlugins
-          .map((plugin) => plugin.pluginId)
+        `Validation failed for ${failingPlugins.length} package(s): ${failingPlugins
+          .map(({ pluginId }) => pluginId)
           .join(', ')}.`
       );
       process.exitCode = 1;
     } else {
-      log.info('All plugins passed validation.');
+      log.info('All packages passed validation.');
     }
   } catch (error) {
     transaction?.setOutcome('failure');

packages/kbn-docs-utils/src/cli/tasks/build_api_map.test.ts

@@ -67,9 +67,10 @@ describe('buildApiMap', () => {
       pluginFilter: ['test-plugin'],
     };
 
-    buildApiMap(project, plugins, log, transaction, options);
+    const allPlugins = [...plugins, { id: 'other-plugin' }];
+    buildApiMap(project, plugins, allPlugins, log, transaction, options);
 
-    expect(getPluginApiMap).toHaveBeenCalledWith(project, plugins, log, {
+    expect(getPluginApiMap).toHaveBeenCalledWith(project, plugins, allPlugins, log, {
       collectReferences: true,
       pluginFilter: ['test-plugin'],
     });
@@ -80,7 +81,7 @@ describe('buildApiMap', () => {
       collectReferences: false,
     };
 
-    const result = buildApiMap(project, plugins, log, transaction, options);
+    const result = buildApiMap(project, plugins, plugins, log, transaction, options);
 
     expect(result).toBeDefined();
     expect(result.pluginApiMap).toBeDefined();
@@ -95,7 +96,7 @@ describe('buildApiMap', () => {
       collectReferences: false,
     };
 
-    buildApiMap(project, plugins, log, transaction, options);
+    buildApiMap(project, plugins, plugins, log, transaction, options);
 
     expect(transaction.startSpan).toHaveBeenCalledWith('build_api_docs.getPluginApiMap', 'setup');
   });

packages/kbn-docs-utils/src/cli/tasks/build_api_map.ts

@@ -25,6 +25,7 @@ import type { BuildApiMapResult, CliOptions } from '../types';
  *
  * @param project - TypeScript project instance.
  * @param plugins - List of plugins and packages to analyze.
+ * @param allPlugins - All plugins/packages for cross-reference resolution.
  * @param log - Tooling log instance.
  * @param transaction - APM transaction for tracking.
  * @param options - CLI options including collectReferences and pluginFilter.
@@ -33,6 +34,7 @@ import type { BuildApiMapResult, CliOptions } from '../types';
 export function buildApiMap(
   project: Project,
   plugins: PluginOrPackage[],
+  allPlugins: PluginOrPackage[],
   log: ToolingLog,
   transaction: Transaction,
   options: CliOptions
@@ -46,7 +48,7 @@ export function buildApiMap(
     referencedDeprecations,
     adoptionTrackedAPIs,
     unnamedExports,
-  } = getPluginApiMap(project, plugins, log, {
+  } = getPluginApiMap(project, plugins, allPlugins, log, {
     collectReferences: options.collectReferences,
     pluginFilter: options.pluginFilter,
   });

packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts

@@ -55,6 +55,7 @@ describe('collectStats', () => {
       plugins: [mockPlugin],
       pathsByPlugin: new Map([[mockPlugin, ['src/plugins/test/public/index.ts']]]),
       project: {} as any,
+      allPlugins: [mockPlugin],
     };
 
     apiMapResult = {

packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts

@@ -64,6 +64,7 @@ describe('reportMetrics', () => {
       plugins: [mockPlugin],
       pathsByPlugin: new Map(),
       project: {} as any,
+      allPlugins: [mockPlugin],
     };
 
     apiMapResult = {

packages/kbn-docs-utils/src/cli/tasks/report_metrics.ts

@@ -16,10 +16,17 @@ import type { AllPluginStats, BuildApiMapResult, CliOptions, SetupProjectResult
 /**
  * Generates a link to the GitHub source for an API declaration.
  *
+ * TODO: clintandrewhall - allow `base` to be overridden in the instance of a CI build
+ * associated with a PR.
+ *
  * @param declaration - API declaration to generate link for.
  * @returns GitHub link to the source code.
  */
 function getLink(declaration: ApiDeclaration): string {
+  const base = `https://github.com/elastic/kibana/blob/main/${declaration.path}`;
+  if (declaration.lineNumber) {
+    return `${base}#L${declaration.lineNumber}`;
+  }
   return `https://github.com/elastic/kibana/tree/main/${
     declaration.path
   }#:~:text=${encodeURIComponent(declaration.label)}`;
@@ -53,10 +60,38 @@ export function reportMetrics(
   const { missingApiItems, referencedDeprecations } = apiMapResult;
   const reporter = CiStatsReporter.fromEnv(log);
 
+  const printIssueTable = (title: string, rows: Array<{ id: string; link: string }>) => {
+    const count = rows.length;
+    if (count === 0) {
+      log.info(`${title}: none`);
+      return;
+    }
+    log.info(`${title} (${count})`);
+    // eslint-disable-next-line no-console
+    console.table(rows);
+  };
+
+  const printMissingExportsTable = (
+    title: string,
+    entries: Array<{ source: string; references: string }>
+  ) => {
+    const header = title.toUpperCase();
+    const count = entries.length;
+    if (count === 0) {
+      log.info(`${header}: none`);
+      return;
+    }
+    log.info(`${header} (${count})`);
+    // eslint-disable-next-line no-console
+    console.table(
+      entries.map(({ source, references }) => ({
+        'Not exported source': source,
+        references,
+      }))
+    );
+  };
+
   for (const plugin of plugins) {
-    // Note that the filtering is done here (per-plugin), rather than earlier in the pipeline.
-    // This keeps the metrics task aligned with how other docs tasks process plugins and ensures
-    // that all plugin data has been collected before selectively reporting metrics.
     if (options.pluginFilter && !options.pluginFilter.includes(plugin.id)) {
       continue;
     }
@@ -162,7 +197,7 @@ export function reportMetrics(
         // eslint-disable-next-line no-console
         console.table(referencedDeprecations[id]);
       } else {
-        log.info(`No referenced deprecations for plugin ${plugin.id}`);
+        log.info(`No referenced deprecations for ${plugin.id}`);
       }
       if (pluginStats.noReferences.length > 0) {
         // eslint-disable-next-line no-console
@@ -173,7 +208,7 @@ export function reportMetrics(
           }))
         );
       } else {
-        log.info(`No unused APIs for plugin ${plugin.id}`);
+        log.info(`No unused APIs for ${plugin.id}`);
       }
     }
 
@@ -184,25 +219,22 @@ export function reportMetrics(
         pluginStats.deprecatedAPIsReferencedCount === 0 &&
         (!missingApiItems[id] || Object.keys(missingApiItems[id]).length === 0);
 
-      log.info(`--- Plugin '${id}' ${passesAllChecks ? 'passes all checks ----' : '----'}`);
+      log.info(`--- '${id}' ${passesAllChecks ? 'passes all checks ----' : '----'}`);
 
       if (!passesAllChecks) {
-        log.info(`${pluginStats.isAnyType.length} API items with ANY`);
-
         if (options.stats.includes('any')) {
-          // eslint-disable-next-line no-console
-          console.table(
+          printIssueTable(
+            'API items with ANY',
             pluginStats.isAnyType.map((d) => ({
               id: d.id,
               link: getLink(d),
             }))
           );
         }
 
-        log.info(`${pluginStats.missingComments.length} API items missing comments`);
         if (options.stats.includes('comments')) {
-          // eslint-disable-next-line no-console
-          console.table(
+          printIssueTable(
+            'API items missing comments',
             pluginStats.missingComments.map((d) => ({
               id: d.id,
               link: getLink(d),
@@ -211,15 +243,12 @@ export function reportMetrics(
         }
 
         if (missingApiItems[id]) {
-          log.info(`${Object.keys(missingApiItems[id]).length} referenced API items not exported`);
           if (options.stats.includes('exports')) {
-            // eslint-disable-next-line no-console
-            console.table(
-              Object.keys(missingApiItems[id]).map((key) => ({
-                'Not exported source': key,
-                references: missingApiItems[id][key].join(', '),
-              }))
-            );
+            const exportsTable = Object.keys(missingApiItems[id]).map((key) => ({
+              source: key,
+              references: missingApiItems[id][key].join(', '),
+            }));
+            printMissingExportsTable('Referenced API items not exported', exportsTable);
           }
         }
       }

packages/kbn-docs-utils/src/cli/tasks/setup_project.test.ts

@@ -11,6 +11,7 @@ import Path from 'path';
 import { ToolingLog } from '@kbn/tooling-log';
 import { setupProject } from './setup_project';
 import type { CliContext, CliOptions } from '../types';
+import type { FindPluginsOptions } from '../../find_plugins';
 
 // Mock dependencies - order matters: mock get_all_doc_file_ids first to prevent globby from loading
 jest.mock('../../mdx/get_all_doc_file_ids', () => ({
@@ -112,6 +113,7 @@ describe('setupProject', () => {
     const result = await setupProject(context, options);
 
     expect(result.plugins).toBeDefined();
+    expect(result.allPlugins).toBeDefined();
     expect(result.pathsByPlugin).toBeDefined();
     expect(result.project).toBeDefined();
   });
@@ -134,9 +136,21 @@ describe('setupProject', () => {
     const Fs = jest.requireMock('fs');
     Fs.existsSync.mockReturnValue(true);
 
-    (findPlugins as jest.Mock).mockReturnValue([
-      { id: 'test-plugin', isPlugin: true, directory: '/tmp/test' },
-    ]);
+    const mockPlugin = {
+      id: 'test-plugin',
+      directory: '/mock/repo/root/src/plugins/test',
+      isPlugin: true,
+      manifest: { id: 'test-plugin', owner: { name: 'test-team' }, serviceFolders: [] },
+      manifestPath: '/mock/repo/root/src/plugins/test/kibana.json',
+    };
+
+    // Return all plugins for allPlugins, filtered for filteredPlugins
+    (findPlugins as jest.Mock).mockImplementation((options?: FindPluginsOptions) => {
+      if (options?.pluginFilter) {
+        return [mockPlugin];
+      }
+      return [mockPlugin, { ...mockPlugin, id: 'other-plugin' }];
+    });
 
     const options: CliOptions = {
       collectReferences: false,
@@ -173,4 +187,76 @@ describe('setupProject', () => {
       "expected --package '@kbn/nonexistent-package' was not found"
     );
   });
+
+  it('scopes TypeScript project to single plugin directory when pluginFilter has one plugin', async () => {
+    const { Project } = jest.requireMock('ts-morph');
+    const mockProject = Project();
+
+    jest.clearAllMocks();
+
+    const mockPlugin = {
+      id: 'single-plugin',
+      directory: '/mock/repo/root/src/plugins/single',
+      isPlugin: true,
+      manifest: { id: 'single-plugin', owner: { name: 'test-team' }, serviceFolders: [] },
+      manifestPath: '/mock/repo/root/src/plugins/single/kibana.json',
+    };
+
+    // Return all plugins for allPlugins, filtered for plugins
+    (findPlugins as jest.Mock).mockImplementation((options?: FindPluginsOptions) => {
+      if (options?.pluginFilter) {
+        return [mockPlugin];
+      }
+      return [mockPlugin, { ...mockPlugin, id: 'other-plugin' }];
+    });
+
+    const options: CliOptions = {
+      collectReferences: false,
+      pluginFilter: ['single-plugin'],
+    };
+
+    await setupProject(context, options);
+
+    // Should use the single plugin's tsconfig
+    expect(Project).toHaveBeenCalledWith({
+      tsConfigFilePath: '/mock/repo/root/src/plugins/single/tsconfig.json',
+      skipAddingFilesFromTsConfig: true,
+    });
+
+    // Should only add files from the single plugin directory
+    expect(mockProject.addSourceFilesAtPaths).toHaveBeenCalledWith([
+      '/mock/repo/root/src/plugins/single/**/*.ts',
+      '!**/*.d.ts',
+    ]);
+
+    // Should NOT call resolveSourceFileDependencies for single-plugin builds
+    expect(mockProject.resolveSourceFileDependencies).not.toHaveBeenCalled();
+  });
+
+  it('loads full codebase and resolves dependencies when no pluginFilter', async () => {
+    const { Project } = jest.requireMock('ts-morph');
+    const mockProject = Project();
+
+    jest.clearAllMocks();
+
+    (findPlugins as jest.Mock).mockReturnValue([]);
+
+    const options: CliOptions = {
+      collectReferences: false,
+    };
+
+    await setupProject(context, options);
+
+    // Should use the repo root tsconfig
+    expect(Project).toHaveBeenCalledWith({
+      tsConfigFilePath: '/mock/repo/root/tsconfig.json',
+      skipAddingFilesFromTsConfig: true,
+    });
+
+    // Should add files from all directories
+    expect(mockProject.addSourceFilesAtPaths).toHaveBeenCalledTimes(8);
+
+    // Should call resolveSourceFileDependencies for full builds
+    expect(mockProject.resolveSourceFileDependencies).toHaveBeenCalled();
+  });
 });