[docs-utils] 2️⃣ Refactor build_api_docs_cli into modular tasks by clintandrewhall · Pull Request #247713 · elastic/kibana

clintandrewhall · 2026-01-02T03:55:00Z

Summary

Decompose the monolithic build_api_docs_cli.ts into a modular, task-based architecture for improved testability and maintainability.

Note

This PR is a subset of #247688 for ease of review.

This PR was written with Cursor and claude-4.5-opus-high.

Changes

Extract CLI flag parsing into parse_cli_flags.ts with validation logic
Create discrete task modules in cli/tasks/:
- setup_project - Plugin discovery, path resolution, TypeScript project setup
- build_api_map - TypeScript analysis and API extraction
- collect_stats - Plugin statistics gathering (ESLint disable counts, Enzyme imports, API stats)
- report_metrics - CI stats reporting and validation result logging
- write_docs - Documentation file generation and nav cleanup
Add shared type definitions in cli/types.ts (CliFlags, CliOptions, CliContext, task result interfaces)
Simplify main CLI runner to orchestrate tasks sequentially

Testing

Add unit tests for each task module
Add unit tests for CLI flag parsing and validation

The main CLI file is reduced from ~450 lines to ~115 lines, with all business logic now isolated in testable, single-responsibility modules.

Decompose the monolithic build_api_docs_cli.ts into a modular, task-based architecture for improved testability and maintainability. Changes: - Extract CLI flag parsing into parse_cli_flags.ts with validation logic - Create discrete task modules in cli/tasks/: - setup_project - Plugin discovery, path resolution, TypeScript project setup - build_api_map - TypeScript analysis and API extraction - collect_stats - Plugin statistics gathering (ESLint disable counts, Enzyme imports, API stats) - report_metrics - CI stats reporting and validation result logging - write_docs - Documentation file generation and nav cleanup - Add shared type definitions in cli/types.ts (CliFlags, CliOptions, CliContext, task result interfaces) - Simplify main CLI runner to orchestrate tasks sequentially Testing: - Add unit tests for each task module - Add unit tests for CLI flag parsing and validation The main CLI file is reduced from ~450 lines to ~115 lines, with all business logic now isolated in testable, single-responsibility modules.

elasticmachine · 2026-01-02T03:55:04Z

Pinging @elastic/kibana-operations (Team:Operations)

elasticmachine · 2026-01-02T03:55:05Z

Pinging @elastic/appex-sharedux (Team:SharedUX)

Copilot

Pull request overview

This PR refactors the monolithic build_api_docs_cli.ts file into a modular, task-based architecture to improve testability and maintainability. The main CLI file is reduced from ~450 lines to ~115 lines by extracting business logic into discrete, testable modules.

Key changes:

Extracted CLI flag parsing with validation into a dedicated module
Created five distinct task modules with single responsibilities (setup, build, collect, report, write)
Added comprehensive unit tests for all new modules
Introduced shared type definitions for better type safety across the codebase

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`packages/kbn-docs-utils/src/cli/types.ts`	Defines shared TypeScript interfaces for CLI flags, options, context, and task results
`packages/kbn-docs-utils/src/cli/parse_cli_flags.ts`	Extracts and validates CLI flag parsing logic with proper error handling
`packages/kbn-docs-utils/src/cli/parse_cli_flags.test.ts`	Provides comprehensive test coverage for flag parsing validation
`packages/kbn-docs-utils/src/cli/tasks/setup_project.ts`	Isolates plugin discovery, path resolution, and TypeScript project setup
`packages/kbn-docs-utils/src/cli/tasks/setup_project.test.ts`	Tests setup task including plugin discovery and folder management
`packages/kbn-docs-utils/src/cli/tasks/build_api_map.ts`	Encapsulates TypeScript analysis and API extraction logic
`packages/kbn-docs-utils/src/cli/tasks/build_api_map.test.ts`	Tests API map building functionality
`packages/kbn-docs-utils/src/cli/tasks/collect_stats.ts`	Consolidates plugin statistics gathering (ESLint, Enzyme, API stats)
`packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts`	Tests statistics collection for plugins
`packages/kbn-docs-utils/src/cli/tasks/report_metrics.ts`	Handles CI stats reporting and validation logging
`packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts`	Tests metrics reporting functionality
`packages/kbn-docs-utils/src/cli/tasks/write_docs.ts`	Manages documentation file generation and nav cleanup
`packages/kbn-docs-utils/src/cli/tasks/write_docs.test.ts`	Tests documentation writing with proper mocking
`packages/kbn-docs-utils/src/cli/tasks/index.ts`	Provides clean exports for all task modules
`packages/kbn-docs-utils/src/cli/index.ts`	Exports CLI-related functions and types
`packages/kbn-docs-utils/src/build_api_docs_cli.ts`	Simplified main CLI runner orchestrating tasks sequentially

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

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

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

elasticmachine · 2026-01-13T03:00:13Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: 2a881ed

Failed CI Steps

Metrics [docs]

Unknown metric groups

Unreferenced deprecated APIs

id	before	after	diff
`@kbn/ai-tools`	0	1	+1
`@kbn/alerting-types`	0	26	+26
`@kbn/alerts-ui-shared`	0	6	+6
`@kbn/check-saved-objects-cli`	0	2	+2
`@kbn/cloud-security-posture`	0	16	+16
`@kbn/cloud-security-posture-graph`	0	2	+2
`@kbn/content-management-table-list-view`	0	2	+2
`@kbn/core`	0	334	+334
`@kbn/elastic-assistant`	0	8	+8
`@kbn/esql-composer`	0	5	+5
`@kbn/esql-editor`	0	3	+3
`@kbn/esql-language`	2	0	-2
`@kbn/esql-utils`	0	4	+4
`@kbn/inference-endpoint-ui-common`	0	1	+1
`@kbn/lens-embeddable-utils`	0	36	+36
`@kbn/management-settings-field-definition`	0	1	+1
`@kbn/migrator-test-kit`	0	4	+4
`@kbn/ml-data-view-utils`	0	1	+1
`@kbn/react-kibana-context-styled`	0	1	+1
`@kbn/react-query`	1	0	-1
`@kbn/reporting-export-types-pdf`	0	3	+3
`@kbn/reporting-public`	0	2	+2
`@kbn/response-ops-alerts-apis`	0	1	+1
`@kbn/response-ops-alerts-table`	0	2	+2
`@kbn/response-ops-rule-form`	0	8	+8
`@kbn/response-ops-rules-apis`	0	4	+4
`@kbn/scout`	17	3	-14
`@kbn/scout-oblt`	16	0	-16
`@kbn/scout-search`	16	0	-16
`@kbn/scout-security`	16	0	-16
`@kbn/search-errors`	0	1	+1
`@kbn/security-authorization-core`	0	237	+237
`@kbn/security-plugin-types-server`	0	1	+1
`@kbn/security-role-management-model`	0	3	+3
`@kbn/security-ui-components`	0	3	+3
`@kbn/securitysolution-data-table`	0	13	+13
`@kbn/securitysolution-io-ts-list-types`	0	11	+11
`@kbn/securitysolution-list-hooks`	0	2	+2
`@kbn/securitysolution-utils`	0	6	+6
`@kbn/shared-ux-link-redirect-app`	3	0	-3
`@kbn/test-jest-helpers`	4	0	-4
`@kbn/test-suites-security-solution-apis`	0	27	+27
`@kbn/test-suites-src`	0	11	+11
`@kbn/test-suites-xpack-observability`	0	13	+13
`@kbn/test-suites-xpack-platform`	0	78	+78
`@kbn/test-suites-xpack-security`	0	2	+2
`@kbn/ui-theme`	3	0	-3
`@kbn/unified-field-list`	0	3	+3
`@kbn/zod`	3	0	-3
`actions`	0	41	+41
`agentBuilder`	0	33	+33
`aiAssistantManagementSelection`	0	2	+2
`aiops`	0	1	+1
`alerting`	1	61	+60
`apm`	0	26	+26
`apmSourcesAccess`	0	1	+1
`banners`	0	1	+1
`canvas`	0	78	+78
`cases`	1	79	+78
`cloudDefend`	0	15	+15
`cloudLinks`	0	1	+1
`cloudSecurityPosture`	0	18	+18
`console`	0	1	+1
`controls`	0	1	+1
`crossClusterReplication`	0	1	+1
`customBranding`	0	1	+1
`dashboard`	0	11	+11
`dashboardEnhanced`	0	3	+3
`data`	6	36	+30
`datasetQuality`	0	2	+2
`dataViewEditor`	0	1	+1
`dataViewFieldEditor`	0	7	+7
`dataViewManagement`	0	49	+49
`dataViews`	0	36	+36
`dataVisualizer`	0	8	+8
`discover`	0	23	+23
`embeddable`	0	5	+5
`encryptedSavedObjects`	0	5	+5
`enterpriseSearch`	0	29	+29
`entityManager`	0	12	+12
`esUiShared`	0	9	+9
`eventAnnotation`	0	1	+1
`eventAnnotationListing`	0	2	+2
`exploratoryView`	0	22	+22
`expressionGauge`	2	0	-2
`expressionPartitionVis`	0	8	+8
`files`	0	2	+2
`filesManagement`	0	1	+1
`fleet`	0	157	+157
`globalSearchProviders`	0	2	+2
`graph`	0	47	+47
`home`	2	3	+1
`indexLifecycleManagement`	0	30	+30
`indexManagement`	0	10	+10
`inference`	0	18	+18
`infra`	0	16	+16
`inputControlVis`	0	7	+7
`interactiveSetup`	0	5	+5
`kibanaOverview`	0	1	+1
`kibanaUtils`	0	5	+5
`kubernetesSecurity`	0	1	+1
`lens`	0	87	+87
`licenseManagement`	0	1	+1
`licensing`	2	5	+3
`links`	0	5	+5
`lists`	4	51	+47
`logstash`	0	1	+1
`maintenanceWindows`	2	6	+4
`management`	0	10	+10
`maps`	0	21	+21
`ml`	0	63	+63
`mockIdpPlugin`	0	4	+4
`monitoring`	0	14	+14
`monitoringCollection`	0	2	+2
`navigation`	2	0	-2
`observability`	1	41	+40
`observabilityAIAssistant`	0	2	+2
`observabilityAIAssistantApp`	0	9	+9
`observabilityAiAssistantManagement`	0	2	+2
`observabilityOnboarding`	0	10	+10
`observabilityShared`	0	2	+2
`osquery`	0	45	+45
`painlessLab`	0	3	+3
`presentationPanel`	0	7	+7
`presentationUtil`	0	2	+2
`productDocBase`	0	3	+3
`profiling`	0	13	+13
`reindexService`	0	10	+10
`remoteClusters`	0	1	+1
`reporting`	0	8	+8
`rollup`	0	1	+1
`ruleRegistry`	0	5	+5
`savedObjects`	1	11	+10
`savedObjectsManagement`	0	28	+28
`savedObjectsTagging`	0	16	+16
`savedObjectsTaggingOss`	0	8	+8
`savedSearch`	0	7	+7
`searchAssistant`	0	9	+9
`searchPlayground`	0	17	+17
`searchprofiler`	0	3	+3
`security`	2	51	+49
`securitySolution`	0	439	+439
`serverlessSearch`	0	2	+2
`share`	0	3	+3
`slo`	0	17	+17
`snapshotRestore`	0	1	+1
`spaces`	0	19	+19
`stackAlerts`	0	19	+19
`stackConnectors`	0	1	+1
`streamsApp`	0	4	+4
`synthetics`	0	38	+38
`taskManager`	1	14	+13
`taskManagerDependencies`	0	2	+2
`telemetry`	0	5	+5
`timelines`	0	1	+1
`transform`	0	6	+6
`triggersActionsUi`	0	13	+13
`uiActionsEnhanced`	0	11	+11
`unifiedSearch`	0	11	+11
`upgradeAssistant`	0	14	+14
`uptime`	0	42	+42
`usageCollection`	0	1	+1
`ux`	0	18	+18
`visDefaultEditor`	0	3	+3
`visTypeGauge`	0	2	+2
`visTypePie`	0	6	+6
`visTypeTagcloud`	0	2	+2
`visTypeTimelion`	0	2	+2
`visTypeTimeseries`	0	31	+31
`visTypeVega`	0	1	+1
`visualizations`	1	21	+20
`watcher`	0	2	+2
`workflowsManagement`	0	2	+2
`workplaceAIApp`	0	9	+9
total			+3059

History

💛 Build #377714 was flaky 2024b16
💛 Build #377579 was flaky 88f3074
💛 Build #377441 was flaky 2820aec
💔 Build #377440 failed ff54f71
💔 Build #377439 failed 35be748

clintandrewhall requested a review from a team as a code owner January 2, 2026 03:55

clintandrewhall requested review from a team and Copilot January 2, 2026 03:55

Copilot AI reviewed Jan 2, 2026

View reviewed changes

packages/kbn-docs-utils/src/cli/tasks/report_metrics.ts Outdated Show resolved Hide resolved

packages/kbn-docs-utils/src/cli/tasks/write_docs.ts Outdated Show resolved Hide resolved

packages/kbn-docs-utils/src/cli/tasks/report_metrics.ts Outdated Show resolved Hide resolved

kibanamachine and others added 5 commits January 2, 2026 04:06

Changes from node scripts/notice

ff54f71

Changes from node scripts/eslint_all_files --no-cache --fix

2820aec

Merge branch 'main' into feat/docs-utils/2-taskify-cli

88f3074

Merge branch 'main' into feat/docs-utils/2-taskify-cli

2024b16

Merge branch 'main' into feat/docs-utils/2-taskify-cli

2a881ed

tylersmalley approved these changes Jan 15, 2026

View reviewed changes

Address feedback

7fb8396

clintandrewhall enabled auto-merge (squash) January 15, 2026 17:32

Merge branch 'main' into feat/docs-utils/2-taskify-cli

3dd2bc1

clintandrewhall merged commit 984c6cb into elastic:main Jan 15, 2026
13 checks passed

clintandrewhall deleted the feat/docs-utils/2-taskify-cli branch January 15, 2026 19:15

clintandrewhall mentioned this pull request Jan 29, 2026

[meta] Updating @kbn/docs-utils, add MCP tools #247688

Draft

13 tasks

clintandrewhall changed the title ~~[kbn-docs-util] Phase 2: Refactor build_api_docs_cli into modular tasks~~ [docs-utils] 2️⃣ Refactor build_api_docs_cli into modular tasks Jan 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs-utils] 2️⃣ Refactor build_api_docs_cli into modular tasks#247713

[docs-utils] 2️⃣ Refactor build_api_docs_cli into modular tasks#247713
clintandrewhall merged 8 commits intoelastic:mainfrom
clintandrewhall:feat/docs-utils/2-taskify-cli

clintandrewhall commented Jan 2, 2026 •

edited

Loading

Uh oh!

elasticmachine commented Jan 2, 2026

Uh oh!

elasticmachine commented Jan 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elasticmachine commented Jan 13, 2026 •

edited

Loading

Unreferenced deprecated APIs

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

clintandrewhall commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Testing

Uh oh!

elasticmachine commented Jan 2, 2026

Uh oh!

elasticmachine commented Jan 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elasticmachine commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💛 Build succeeded, but was flaky

Failed CI Steps

Metrics [docs]

Unreferenced deprecated APIs

History

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

clintandrewhall commented Jan 2, 2026 •

edited

Loading

elasticmachine commented Jan 13, 2026 •

edited

Loading