[docs-utils] 4️⃣ pre-req: Prepare for new validations

packages/kbn-docs-utils/src/README.md

@@ -1,25 +1,26 @@
-# Autogenerated API documentation
+# Autogenerated API documentation.
 
-[RFC](https://github.com/elastic/kibana/blob/main/legacy_rfcs/text/0014_api_documentation.md))
+[RFC](https://github.com/elastic/kibana/blob/main/legacy_rfcs/text/0014_api_documentation.md).
 
-This is an experimental api documentation system that is managed by the Kibana Tech Leads until
-we determine the value of such a system and what kind of maintenance burden it will incur.
+This package builds and validates API documentation for Kibana plugins and packages. Use `node scripts/build_api_docs` to emit docs to `api_docs/`, or `node scripts/check_package_docs` to validate JSDoc without writing files.
 
-To generate the docs run 
+## CLI commands.
 
-```
-node scripts/build_api_docs
-```
+### Build API docs (`node scripts/build_api_docs`).
+- Generates docs into `api_docs/` using [`src/build_api_docs_cli.ts`](./build_api_docs_cli.ts).
+- `--plugin <id>` limits to a single plugin or package; `--package` is an alias.
+- `--references` collects references for API items.
+- `--stats <any|comments|exports>` is deprecated and routes validation to `check_package_docs` without writing docs.
 
-To validate documentation without writing files, run
+### Check package docs (`node scripts/check_package_docs`).
+- Runs validation only (no docs written) via [`src/check_package_docs_cli.ts`](./check_package_docs_cli.ts); output folder is `api_docs_check/`.
+- `--plugin <id>` and `--package <id>` filter targets; omit to check all plugins.
+- `--check <any|comments|exports|all>` selects checks; defaults to `all` (equivalent to `any`, `comments`, and `exports`).
+- Multiple `--check` flags combine checks.
+- Exits with a non-zero code if any selected checks fail.
 
-```
-node scripts/check_package_docs --plugin <pluginId>
-```
-
-You can use `--plugin` to filter by plugin id and `--package` to filter by package id (manifest.id). These filters can be used independently or together. Validation flags:
-
-- `--check <any|comments|exports|all>` (optional, defaults to `all`).
-- You may pass multiple `--check` flags to combine specific checks.
-
-The `--stats` flag on `build_api_docs` is deprecated and routes to `check_package_docs`.
+## Validation rules.
+- `any` check: fails when API declarations use `any` (`TypeKind.AnyKind`).
+- `comments` check: fails when descriptions are missing for API items.
+- `exports` check: fails when public API items are missing from plugin exports discovered during analysis.
+- Third-party code under `node_modules/` is ignored for validation.

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

@@ -61,12 +61,11 @@ export async function collectStats(
     allPluginStats[id] = {
       ...(await countEslintDisableLines(paths)),
       ...(await countEnzymeImports(paths)),
-      ...collectApiStatsForPlugin(
-        pluginApi,
+      ...collectApiStatsForPlugin(pluginApi, {
         missingApiItems,
         referencedDeprecations,
-        adoptionTrackedAPIs
-      ),
+        adoptionTrackedAPIs,
+      }),
       owner: plugin.manifest.owner,
       description: plugin.manifest.description,
       isPlugin: plugin.isPlugin,

packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts

@@ -124,18 +124,16 @@ beforeAll(async () => {
 
   doc = pluginApiMap.pluginA;
 
-  pluginAStats = collectApiStatsForPlugin(
-    doc,
+  pluginAStats = collectApiStatsForPlugin(doc, {
     missingApiItems,
     referencedDeprecations,
-    adoptionTrackedAPIs
-  );
-  pluginBStats = collectApiStatsForPlugin(
-    pluginApiMap.pluginB,
+    adoptionTrackedAPIs,
+  });
+  pluginBStats = collectApiStatsForPlugin(pluginApiMap.pluginB, {
     missingApiItems,
     referencedDeprecations,
-    adoptionTrackedAPIs
-  );
+    adoptionTrackedAPIs,
+  });
 
   mdxOutputFolder = Path.resolve(__dirname, 'snapshots');
   await Promise.all([

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.mdx

@@ -8,7 +8,7 @@ slug: /kibana-dev-docs/api/pluginA
 title: "pluginA"
 image: https://source.unsplash.com/400x175/?github
 description: API docs for the pluginA plugin
-date: 2025-12-31
+date: 2026-01-28
 tags: ['contributor', 'dev', 'apidocs', 'kibana', 'pluginA']
 ---
 import pluginAObj from './plugin_a.devdocs.json';

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a_foo.mdx

@@ -8,7 +8,7 @@ slug: /kibana-dev-docs/api/pluginA-foo
 title: "pluginA.foo"
 image: https://source.unsplash.com/400x175/?github
 description: API docs for the pluginA.foo plugin
-date: 2025-12-31
+date: 2026-01-28
 tags: ['contributor', 'dev', 'apidocs', 'kibana', 'pluginA.foo']
 ---
 import pluginAFooObj from './plugin_a_foo.devdocs.json';

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_b.mdx

@@ -8,7 +8,7 @@ slug: /kibana-dev-docs/api/pluginB
 title: "pluginB"
 image: https://source.unsplash.com/400x175/?github
 description: API docs for the pluginB plugin
-date: 2025-12-31
+date: 2026-01-28
 tags: ['contributor', 'dev', 'apidocs', 'kibana', 'pluginB']
 ---
 import pluginBObj from './plugin_b.devdocs.json';