[docs-utils] Add fix-package-docs skill#257577
Merged
clintandrewhall merged 9 commits intoelastic:mainfrom Mar 20, 2026
Merged
Conversation
Adds structured flat-stats JSON output to check_package_docs and a Claude Code skill that uses it to systematically fix API documentation issues in Kibana plugins and packages — without needing an MCP server. - Extract `getLink` into a shared `get_link.ts` module (was inline in `report_metrics.ts`); `flat_stats.ts` reuses it without duplication. - Add `flat_stats.ts` with `buildFlatStatsForPlugin`/`writeFlatStatsFiles` that serialise per-plugin issue lists (path, lineNumber, type, link) to `<pluginDir>/target/api_docs/stats.json`. - Add `--write` flag to the `check_package_docs` CLI (CliFlags, CliOptions, parse_cli_flags, runner) that triggers `writeFlatStatsFiles`. - Add `.agents/skills/fix-package-docs/SKILL.md` — a Claude Code skill that replaces the MCP-tool approach. The skill runs the CLI with `--write`, reads the structured JSON, and guides an agent through every actionable issue category (missingComments, missingReturns, paramDocMismatches, missingComplexTypeInfo, isAnyType) with concrete JSDoc templates and conventions, then re-verifies.
clintandrewhall
added
review
release_note:skip
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “fix-package-docs” agent skill and extends check_package_docs --write output so unnamed validation results are persisted to disk in target/api_docs/stats.json.
Changes:
- Added a new agent skill guide for fixing
check_package_docsvalidation findings. - Introduced
--writeCLI flag plumbing and flatstats.jsonwriting per plugin/package, includingunnamedExports. - Refactored GitHub link generation into a shared
get_link.tshelper.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/kbn-docs-utils/src/types.ts | Corrects UnnamedExport JSDoc to reflect actual cause (anonymous default exports). |
| packages/kbn-docs-utils/src/cli/types.ts | Adds --write flag and writeStats option to control stats file emission. |
| packages/kbn-docs-utils/src/cli/tasks/report_metrics.ts | Reuses shared getLink helper instead of local implementation. |
| packages/kbn-docs-utils/src/cli/tasks/get_link.ts | New shared GitHub source-link builder for API declarations. |
| packages/kbn-docs-utils/src/cli/tasks/flat_stats.ts | New flat stats builder/writer including unnamedExports persisted to JSON. |
| packages/kbn-docs-utils/src/cli/parse_cli_flags.ts | Parses --write into writeStats. |
| packages/kbn-docs-utils/src/check_package_docs_cli.ts | Wires --write to write target/api_docs/stats.json. |
| .agents/skills/fix-package-docs/SKILL.md | New step-by-step skill for fixing API docs validation issues. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix FlatStatEntry.type to use ApiDeclaration['type'] instead of string - Eliminate duplicate missingApiItems[pluginId] lookup in buildFlatStatsForPlugin - Fix pluginId shadowing in unnamedExports map callback - Update stats.json example in skill to match full FlatStats schema (add apiCount, noReferences) - Move unnamedExports to "skip; flag for human review" — fixing anonymous default exports changes the public API surface, violating the "never change runtime behavior" rule
Fixes all actionable check_package_docs validation issues: - Add description to RisonValue type alias. - Add full JSDoc (description, @param, @returns) to encodeUnknown, which was previously undocumented. - Add @param and @returns to encode, decode, safeDecode, encodeArray, and decodeArray, which had descriptions but no parameter or return docs. - Document why obj/array params are typed as `any`: these functions intentionally accept arbitrary runtime values (application URL state) whose shape is not known at compile time. Skipped: - isAnyType (encodeUnknown, encode): `any` is semantically correct; changing to `RisonValue` would break callers that pass untyped state objects. - unnamedExports: re-export group in index.ts; requires restructuring exports.
Fixes all check_package_docs validation issues: - Add description to the Theme type alias. - Add description text to the deprecated tag, version, and darkMode constants; the @deprecated tag alone was not sufficient to satisfy the missing-comments check. - Add description and @param to _setDarkMode. - Add inline descriptions to euiLightVars and euiDarkVars, pointing callers toward euiThemeVars for dynamic theme support. - Add full JSDoc (@param with dot-notation, @returns) to getEuiThemeVars.
Adds full JSDoc (description, @param, @returns) to all exported functions in the package. Converts existing inline comment-style param docs in props.ts to standard @param tags with dot-notation for nested opts properties. Notes the intentional use of any for JSON value parameters in setCompilerOption and setProp.
clintandrewhall
changed the title
fix-package-docs skill
tylersmalley
approved these changes
Mar 20, 2026
Contributor
💔 Build Failed
Failed CI Steps
Test Failures
Metrics [docs]Public APIs missing comments
History
|
jeramysoucy
pushed a commit
to jeramysoucy/kibana
that referenced
this pull request
Mar 26, 2026
There are test failures that are not at all germane to the changes made, and are in other tracked branches. Saving an additional CI run and merging.
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
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.
Summary
Two related changes:
New agent skill — adds
.agents/skills/fix-package-docs/SKILL.md, a step-by-step guide for an AI agent to systematically find and fix all actionable API documentation issues in a Kibana plugin or package usingcheck_package_docs --write.unnamedExportsinstats.json— theunnamedvalidation check was already run bycheck_package_docsbut its results were never written to thestats.jsonfile produced by--write. This PR addsunnamedExportstoFlatStatsso agents (and humans) can read it from disk alongside the other categories.Skill coverage
The skill covers all four default validation checks (
any,comments,exports,unnamed) with accurate fix guidance for each category:missingComments/** ... */above the declarationmissingReturns@returns@returnsto existing JSDocparamDocMismatches@paramcoverage (some but not all params documented)@paramtagsmissingComplexTypeInfoisAnyTypeanyunknownunnamedExportsexport defaultexpressions with no identifiable namemissingExportsThe skill also documents the dot-notation
@paramconvention for destructured parameters introduced in #250813, and the partial-param-doc detection introduced in #250820.flat_stats.tschangesgetLinkinto its own file (get_link.ts) so it can be shared betweenreport_metrics.tsand the newflat_stats.ts.FlatUnnamedExportEntrytype and includesunnamedExportsin bothFlatStats.countsand the top-level array.UnnamedExportJSDoc intypes.ts, which incorrectly described the cause as "a JSDoc comment above a non-declaration" — it's actually an anonymousexport defaultexpression.Demonstrated against real packages
To validate the skill, it was applied to two
kibana-operations-owned runtime packages and one additional package. All actionable issues were resolved in each case:@kbn/risonmissingComments: 6, missingReturns: 6, paramDocMismatches: 5@kbn/ui-thememissingComments: 7, missingReturns: 2, paramDocMismatches: 2, missingComplexTypeInfo: 1@kbn/json-astmissingComments: 29, missingReturns: 11, paramDocMismatches: 11, missingComplexTypeInfo: 3Test plan
node scripts/check_package_docs.js --plugin dashboard --writeand confirmtarget/api_docs/stats.jsonincludesunnamedExportsin bothcountsand as an array.check_package_docs --package @kbn/rison,--package @kbn/ui-theme, and--package @kbn/json-astall report zero actionable issues after applying skill-guided fixes.