[meta] Updating @kbn/docs-utils, add MCP tools#247688
Draft
clintandrewhall wants to merge 8 commits intomainfrom
Draft
[meta] Updating @kbn/docs-utils, add MCP tools#247688clintandrewhall wants to merge 8 commits intomainfrom
@kbn/docs-utils, add MCP tools#247688clintandrewhall wants to merge 8 commits intomainfrom
Conversation
bcef48e to
e4b7800
Compare
6fe6e96 to
5c57d1f
Compare
Contributor
|
🤖 Jobs for this PR can be triggered through checkboxes. 🚧
ℹ️ To trigger the CI, please tick the checkbox below 👇
|
5b4eb3e to
e7276f5
Compare
cd6cdf4 to
263ccfd
Compare
Contributor
💛 Build succeeded, but was flaky
Failed CI StepsThe CI Stats report is too large to be displayed here, check out the CI build annotation for this information. History
|
263ccfd to
5ba29e2
Compare
10 tasks
@kbn/docs-utils, add MCP tools@kbn/docs-utils, add MCP tools
5ba29e2 to
568fa8b
Compare
ccd6e0d to
ba1e673
Compare
This was referenced Jan 28, 2026
- Update collectStatsForApi to check for parent or property-level comments. - Don't flag as missing if property-level JSDoc exists. - Add validation for required vs optional parameter documentation.
- Handle interfaces with multiple call signatures. - Extract parameter documentation from first overload signature. - Add test cases for overloaded functions.
- Add UnnamedExport type. - Extend IssuesByPlugin with optional unnamedExports field. - Update getDeclarationNodesForPluginScope to detect unnamed exports. - Update getPluginApi to propagate unnamed exports. - Add --check unnamed CLI flag. - Add tests for unnamed export detection.
- Improve getLink to use line numbers when available. - Add printIssueTable helper for consistent output formatting. - Add printMissingExportsTable helper for missing exports output. - Refactor existing console output to use helper functions.
ba1e673 to
f0594a4
Compare
- Add --write CLI flag to check_package_docs to emit validation stats as flat JSON. - Write stats to each plugin's target/api_docs/stats.json. - Include line-anchored GitHub URLs when line numbers are present. Co-authored-by: Cursor <cursoragent@cursor.com>
- Create check_package_docs MCP tool for quick validation checks. - Create fix_package_docs MCP tool for detailed issue reporting with code snippets. - Both tools registered in kbn-mcp-dev-server. - Add usage docs and basic tests for the MCP tools.
- Optimize TypeScript project loading for single-plugin builds. - Add allPlugins to SetupProjectResult for cross-reference resolution. - Skip aggregate docs for filtered builds. - Update removeBrokenLinksFromApi to handle cross-package links. - Update tests for single-plugin project scoping.
- Add APM metrics for missingReturns count. - Add APM metrics for paramDocMismatches count. - Add APM metrics for missingComplexTypeInfo count. - Update passesAllChecks logic to include new fields. - Add CLI output for new validation fields under comments option. Co-authored-by: Cursor <cursoragent@cursor.com>
f0594a4 to
da7f162
Compare
This was referenced Feb 11, 2026
mistic
added a commit
that referenced
this pull request
Feb 23, 2026
## Summary
Improves the `missingComments` detection in `kbn-docs-utils` to avoid
false positives on destructured parameter nodes. Previously, a parameter
like `obj` in `crazyFunction(obj: {hi: string})` was flagged as missing
a comment even when its children (`obj.hi`) were individually documented
via JSDoc.
> [!NOTE]
> This PR is a subset of #247688
for ease of review.
>
> This PR was written with Cursor and `claude-4.5-opus-high`.
### Before / After Example
Given this JSDoc-annotated function:
```typescript
/**
* Who would write such a complicated function?? Ewwww.
*
* @param {Object} obj A very crazy parameter.
* @param {string} obj.hi Greeting on the obj.
*/
export const crazyFunction = (
obj: { hi: string },
) => { /* ... */ };
```
**Before this PR:**
The `obj` parameter node was flagged as "missing a comment" even though
its child `obj.hi` had a description extracted from `@param obj.hi`:
```json
{
"missingComments": [
{ "id": "def-public.crazyFunction.$1", "label": "obj" }
]
}
// obj flagged even though its children are documented!
```
**After this PR:**
Parameter nodes (identified by `.$` in their `id`) are no longer flagged
when at least one child has a description:
```json
{
"missingComments": []
}
// obj NOT flagged — child obj.hi has a description ✅
```
### Detection Logic
| Scenario | Flagged? | Reason |
|----------|----------|--------|
| No description, no children with descriptions | Yes | Genuinely
undocumented |
| No description, but child has description | **No** | Parent is
implicitly documented via children |
| Has own description | No | Directly documented |
| Non-parameter node without description | Yes | Not a parameter, normal
rules apply |
### Changes
- Refactor `missingComment` logic in `collectStatsForApi()` in
`stats.ts` to check for child descriptions on parameter nodes
- Un-skip the `does not flag destructured params when @param obj exists`
test
- Simplify the `does not flag destructured parameter children when
documented` test to assert the correct behavior directly
### Impact
- Reduces false positives in `missingComments` for plugins with
well-documented destructured parameters
Made with [Cursor](https://cursor.com)
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Tiago Costa <tiago.costa@elastic.co>
This was referenced Feb 25, 2026
bhapas
pushed a commit
to bhapas/kibana
that referenced
this pull request
Feb 25, 2026
## Summary
Improves the `missingComments` detection in `kbn-docs-utils` to avoid
false positives on destructured parameter nodes. Previously, a parameter
like `obj` in `crazyFunction(obj: {hi: string})` was flagged as missing
a comment even when its children (`obj.hi`) were individually documented
via JSDoc.
> [!NOTE]
> This PR is a subset of elastic#247688
for ease of review.
>
> This PR was written with Cursor and `claude-4.5-opus-high`.
### Before / After Example
Given this JSDoc-annotated function:
```typescript
/**
* Who would write such a complicated function?? Ewwww.
*
* @param {Object} obj A very crazy parameter.
* @param {string} obj.hi Greeting on the obj.
*/
export const crazyFunction = (
obj: { hi: string },
) => { /* ... */ };
```
**Before this PR:**
The `obj` parameter node was flagged as "missing a comment" even though
its child `obj.hi` had a description extracted from `@param obj.hi`:
```json
{
"missingComments": [
{ "id": "def-public.crazyFunction.$1", "label": "obj" }
]
}
// obj flagged even though its children are documented!
```
**After this PR:**
Parameter nodes (identified by `.$` in their `id`) are no longer flagged
when at least one child has a description:
```json
{
"missingComments": []
}
// obj NOT flagged — child obj.hi has a description ✅
```
### Detection Logic
| Scenario | Flagged? | Reason |
|----------|----------|--------|
| No description, no children with descriptions | Yes | Genuinely
undocumented |
| No description, but child has description | **No** | Parent is
implicitly documented via children |
| Has own description | No | Directly documented |
| Non-parameter node without description | Yes | Not a parameter, normal
rules apply |
### Changes
- Refactor `missingComment` logic in `collectStatsForApi()` in
`stats.ts` to check for child descriptions on parameter nodes
- Un-skip the `does not flag destructured params when @param obj exists`
test
- Simplify the `does not flag destructured parameter children when
documented` test to assert the correct behavior directly
### Impact
- Reduces false positives in `missingComments` for plugins with
well-documented destructured parameters
Made with [Cursor](https://cursor.com)
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Tiago Costa <tiago.costa@elastic.co>
qn895
pushed a commit
to qn895/kibana
that referenced
this pull request
Mar 11, 2026
## Summary
Improves the `missingComments` detection in `kbn-docs-utils` to avoid
false positives on destructured parameter nodes. Previously, a parameter
like `obj` in `crazyFunction(obj: {hi: string})` was flagged as missing
a comment even when its children (`obj.hi`) were individually documented
via JSDoc.
> [!NOTE]
> This PR is a subset of elastic#247688
for ease of review.
>
> This PR was written with Cursor and `claude-4.5-opus-high`.
### Before / After Example
Given this JSDoc-annotated function:
```typescript
/**
* Who would write such a complicated function?? Ewwww.
*
* @param {Object} obj A very crazy parameter.
* @param {string} obj.hi Greeting on the obj.
*/
export const crazyFunction = (
obj: { hi: string },
) => { /* ... */ };
```
**Before this PR:**
The `obj` parameter node was flagged as "missing a comment" even though
its child `obj.hi` had a description extracted from `@param obj.hi`:
```json
{
"missingComments": [
{ "id": "def-public.crazyFunction.$1", "label": "obj" }
]
}
// obj flagged even though its children are documented!
```
**After this PR:**
Parameter nodes (identified by `.$` in their `id`) are no longer flagged
when at least one child has a description:
```json
{
"missingComments": []
}
// obj NOT flagged — child obj.hi has a description ✅
```
### Detection Logic
| Scenario | Flagged? | Reason |
|----------|----------|--------|
| No description, no children with descriptions | Yes | Genuinely
undocumented |
| No description, but child has description | **No** | Parent is
implicitly documented via children |
| Has own description | No | Directly documented |
| Non-parameter node without description | Yes | Not a parameter, normal
rules apply |
### Changes
- Refactor `missingComment` logic in `collectStatsForApi()` in
`stats.ts` to check for child descriptions on parameter nodes
- Un-skip the `does not flag destructured params when @param obj exists`
test
- Simplify the `does not flag destructured parameter children when
documented` test to assert the correct behavior directly
### Impact
- Reduces false positives in `missingComments` for plugins with
well-documented destructured parameters
Made with [Cursor](https://cursor.com)
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Tiago Costa <tiago.costa@elastic.co>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improve
@kbn/docs-utilsvalidation, testing, and MCP toolingSummary
The
kbn-docs-utilspackage builds API documentation from TypeScript source code usingts-morph, and gathers statistics for CI and APM on inline code documentation. The statistics functionality currently checks for three main things:anyin TypeScript codeThis PR delivers significant improvements to the
@kbn/docs-utilspackage, including new and planned functionality, bug fixes, test coverage, performance optimizations, and more. It also splits the--statsfunctionality into its own CLI, making it easier for developers and agents to ensure all code is fully documented before a PR is created.The work follows a phased approach documented in
PLAN.md, delivering improved test coverage, modular CLI architecture, enhanced JSDoc validation, performance improvements for single-package builds, and new MCP tooling for AI-assisted documentation remediation.Note
These commits and PR are based on a feature branch containing several "Phases" of code that will be submitted as separate PRs for ease of review.
This PR was written using Cursor and
claude-4.5-opus-highTip
#247774 is a test run of this branch against the dashboard plugin.
Status
These are the PRs that have been extracted from this
metaPR. Drafts will be marked as ready for review as their predecessors allow:missingReturnsvalidation to API stats #250816New Features
Dedicated
check_package_docsCLIA new standalone CLI for validation-only workflows, separate from documentation generation:
This new CLI enables a faster feedback loop for developers focused on documentation quality, and for AI Agents to raise (and fix) issues before a PR is created.
New Validation Rules
@returnstag validation — Detects missing return documentation on non-void functions@paramcount doesn't match function signatureFlat Stats JSON Output
New
--writeflag emits machine-readable validation stats for CI and AI integration:<plugin|package>/target/api_docs/stats.jsonMCP Tools for AI-Assisted Documentation
Two new MCP tools registered in
kbn-mcp-dev-server:check_package_docs— Quick pass/fail validation with actionable vs. pending issue countsfix_package_docs— Detailed issue reporting with source context and mechanical fix templates for agent-assisted remediationPerformance Improvements for Single-Package Builds
Significant performance optimizations for building or validating individual plugins:
resolveSourceFileDependencies()for faster initializationKey Improvements
Dramatically Expanded Test Coverage (Phases 1–2)
js_doc_utils.test.ts— JSDoc parsing testsbuild_api_declaration.test.ts— replacing the minimal originalsetup_project,build_api_map,collect_stats,write_docs,report_metrics)Modular CLI Architecture (Phases 2–3)
build_api_docs_cli.tsinto discrete, testable tasks undersrc/cli/tasks/check_package_docsCLI separating validation from doc generationnode scripts/build_api_docsfor documentation generationnode scripts/check_package_docsfor validation-only workflows--statsflag with automatic routing to new CLIEnhanced Validation and Bug Fixes (Phase 4)
Phase 4 focused on fixing validation bugs and adding new validation rules:
@param options.name)@returnstag validation for non-void functionsDocumentation and Developer Experience (Phase 5)
README.mdwith comprehensive CLI usage documentationFlat Stats and MCP Tooling (Phase 6)
--writeflag to emit flatstats.jsonper plugin with:check_package_docsfor quick pass/fail statusfix_package_docsfor detailed issues with source context and fix templatesOptimized Single-Package Workflows (Phase 7)
Bugs Fixed
Destructured Parameter JSDoc Handling
Problem: The system only matched exact parameter names when extracting JSDoc comments. Property-level tags using dot notation (
@param options.name) were not recognized, causing false positives for "missing comments" on destructured parameter children.Fix: Updated
getJSDocParamCommentinjs_doc_utils.tsto support dot-notation property tags per the JSDoc specification. The system now correctly parses nested property access patterns like@param obj.nested.prop.Missing Property-Level Validation
Problem: When a parameter was an object type, children were created for each property, but validation didn't account for parent parameters having comments or property-level JSDoc tags.
Fix: Updated
buildApiDecsForParametersto pass JSDoc context through to child properties. Validation now only flags missing comments if both the parent parameter AND property-level tags are absent.ReactElement Signature Noise
Problem: ReactElement types included a noisy second generic parameter in their signatures, making the output cluttered and harder to read.
Fix: Normalized ReactElement signatures in
get_signature.tsto strip the second generic, restoring clean and expected output. Unskipped the previously failingTest ReactElement signaturetest.Inconsistent JSDoc Detection
Problem: The system used exact string matching for JSDoc parameter names, missing variations and edge cases.
Fix: Enhanced
js_doc_utils.tswith comprehensive parsing logic and added 380+ lines of unit tests covering edge cases.Breaking Changes
None. The
--statsflag onbuild_api_docsremains functional but emits a deprecation warning and routes to the newcheck_package_docsCLI.Testing
@kbn/docs-utils,@kbn/content-management-content-editor)Closes