[docs-utils] 4️⃣ Add complex type validation

packages/kbn-docs-utils/scripts/update_fixture_comments.js

@@ -13,6 +13,7 @@ const path = require('node:path');
 const categories = [
   { key: 'missingComments', title: 'missing comments' },
   { key: 'paramDocMismatches', title: 'param doc mismatches' },
+  { key: 'missingComplexTypeInfo', title: 'missing complex type info' },
   { key: 'isAnyType', title: 'any usage' },
   { key: 'noReferences', title: 'no references' },
 ];

packages/kbn-docs-utils/src/__test_helpers__/mocks.ts

@@ -66,6 +66,7 @@ export const createMockPluginStats = (overrides: Partial<ApiStats> = {}): ApiSta
   isAnyType: [],
   noReferences: [],
   paramDocMismatches: [],
+  missingComplexTypeInfo: [],
   missingExports: 0,
   deprecatedAPIsReferencedCount: 0,
   unreferencedDeprecatedApisCount: 0,
@@ -97,6 +98,7 @@ export const createMockPluginMetaInfo = (
   isAnyType: [],
   noReferences: [],
   paramDocMismatches: [],
+  missingComplexTypeInfo: [],
   missingExports: 0,
   deprecatedAPIsReferencedCount: 0,
   unreferencedDeprecatedApisCount: 0,

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

@@ -40,6 +40,7 @@ const createPlugin = (id: string, isPlugin = true): PluginOrPackage => ({
 const createBaseStats = (pluginId: string): AllPluginStats => ({
   [pluginId]: {
     missingComments: [],
+    missingComplexTypeInfo: [],
     isAnyType: [],
     noReferences: [],
     paramDocMismatches: [],

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

@@ -85,7 +85,9 @@ export const getValidationResults = (
       const hasAnyIssues = shouldCheckAny && pluginStats.isAnyType.length > 0;
       const hasCommentIssues =
         shouldCheckComments &&
-        (pluginStats.missingComments.length > 0 || pluginStats.paramDocMismatches.length > 0);
+        (pluginStats.missingComments.length > 0 ||
+          pluginStats.paramDocMismatches.length > 0 ||
+          pluginStats.missingComplexTypeInfo.length > 0);
       const hasExportIssues = shouldCheckExports && missingExports > 0;
 
       return {

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

@@ -78,6 +78,7 @@ describe('collectStats', () => {
       isAnyType: [],
       noReferences: [],
       paramDocMismatches: [],
+      missingComplexTypeInfo: [],
       missingExports: 0,
       deprecatedAPIsReferencedCount: 0,
       unreferencedDeprecatedApisCount: 0,

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

@@ -78,6 +78,7 @@ describe('reportMetrics', () => {
       'test-plugin': {
         apiCount: 5,
         missingComments: [],
+        missingComplexTypeInfo: [],
         isAnyType: [],
         noReferences: [],
         paramDocMismatches: [],

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

@@ -90,6 +90,7 @@ describe('writeDocs', () => {
       'test-plugin': {
         apiCount: 5,
         missingComments: [],
+        missingComplexTypeInfo: [],
         isAnyType: [],
         noReferences: [],
         paramDocMismatches: [],

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts

@@ -17,6 +17,8 @@ export interface ImACommonType {
 //   missing comments (2):
 //     line 12 - ImACommonType
 //     line 13 - goo
+//   missing complex type info (1):
+//     line 12 - ImACommonType
 //   no references (2):
 //     line 12 - ImACommonType
 //     line 13 - goo

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts

@@ -132,6 +132,9 @@ export interface IReturnAReactComponent {
 //     line 52 - Constructor
 //     line 91 - anOptionalFn
 //     line 101 - fnTypeWithGeneric
+//   missing complex type info (2):
+//     line 50 - component
+//     line 117 - component
 //   no references (23):
 //     line 28 - WithGen
 //     line 32 - t

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts

@@ -91,6 +91,8 @@ export const literalString = 'HI';
 //     line 19 - notAnArrowFn
 //     line 24 - aPropertyMisdirection
 //     line 29 - aPropertyInlineFn
+//   missing complex type info (1):
+//     line 32 - a
 //   no references (14):
 //     line 18 - aPretendNamespaceObj
 //     line 19 - notAnArrowFn

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts

@@ -112,6 +112,10 @@ export const iShouldBeInternalFn = () => 'hi';
 //   param doc mismatches (2):
 //     line 83 - fnWithNonExportedRef
 //     line 85 - NotAnArrowFnType
+//   missing complex type info (3):
+//     line 27 - d
+//     line 27 - d
+//     line 27 - d
 //   no references (40):
 //     line 13 - notAnArrowFn
 //     line 24 - a

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts

@@ -47,6 +47,10 @@ export function plugin() {
 //     line 30 - new
 //   param doc mismatches (1):
 //     line 30 - new
+//   missing complex type info (3):
+//     line 24 - InterfaceWithIndexSignature
+//     line 28 - ClassConstructorWithStaticProperties
+//     line 30 - config
 //   any usage (1):
 //     line 20 - imAnAny
 //   no references (9):

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts

@@ -188,6 +188,8 @@ export class PluginA implements PluginMock<Setup, Start> {
 //     line 135 - param
 //   param doc mismatches (1):
 //     line 135 - fn
+//   missing complex type info (1):
+//     line 135 - foo
 //   no references (23):
 //     line 19 - SearchSpec
 //     line 24 - username

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts

@@ -84,6 +84,11 @@ export type AReactElementFn = () => ReactElement<MyProps>;
 //     line 30 - FnTypeWithGeneric
 //     line 54 - foo
 //     line 62 - bar
+//   missing complex type info (4):
+//     line 36 - p
+//     line 36 - p
+//     line 53 - ImAnObject
+//     line 60 - MyProps
 //   no references (21):
 //     line 14 - StringOrUndefinedType
 //     line 19 - TypeWithGeneric

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

@@ -153,11 +153,13 @@ beforeAll(async () => {
       missingExports: pluginAStats.missingExports,
       missingComments: pluginAStats.missingComments.length,
       paramDocMismatches: pluginAStats.paramDocMismatches.length,
+      missingComplexTypeInfo: pluginAStats.missingComplexTypeInfo.length,
       isAnyType: pluginAStats.isAnyType.length,
       noReferences: pluginAStats.noReferences.length,
     },
     missingComments: pluginAStats.missingComments.map(mapStat),
     paramDocMismatches: pluginAStats.paramDocMismatches.map(mapStat),
+    missingComplexTypeInfo: pluginAStats.missingComplexTypeInfo.map(mapStat),
     isAnyType: pluginAStats.isAnyType.map(mapStat),
     noReferences: pluginAStats.noReferences.map(mapStat),
   };

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.stats.json

@@ -4,6 +4,7 @@
     "missingExports": 2,
     "missingComments": 64,
     "paramDocMismatches": 13,
+    "missingComplexTypeInfo": 15,
     "isAnyType": 1,
     "noReferences": 135
   },
@@ -627,6 +628,128 @@
       "columnNumber": 3
     }
   ],
+  "missingComplexTypeInfo": [
+    {
+      "id": "def-public.Setup.fnWithInlineParams.$1.fn.$1",
+      "label": "foo",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts",
+      "type": "Object",
+      "lineNumber": 135,
+      "columnNumber": 15
+    },
+    {
+      "id": "def-public.InterfaceWithIndexSignature",
+      "label": "InterfaceWithIndexSignature",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts",
+      "type": "Interface",
+      "lineNumber": 24,
+      "columnNumber": 1
+    },
+    {
+      "id": "def-public.ClassConstructorWithStaticProperties",
+      "label": "ClassConstructorWithStaticProperties",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts",
+      "type": "Interface",
+      "lineNumber": 28,
+      "columnNumber": 1
+    },
+    {
+      "id": "def-public.ClassConstructorWithStaticProperties.new.$1",
+      "label": "config",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts",
+      "type": "Object",
+      "lineNumber": 30,
+      "columnNumber": 16
+    },
+    {
+      "id": "def-public.NotAnArrowFnType.$4",
+      "label": "d",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts",
+      "type": "CompoundType",
+      "lineNumber": 27,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.ExampleClass.component",
+      "label": "component",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts",
+      "type": "CompoundType",
+      "lineNumber": 50,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.ExampleInterface.fnTypeWithGeneric.$2",
+      "label": "p",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Object",
+      "lineNumber": 36,
+      "columnNumber": 43
+    },
+    {
+      "id": "def-public.IReturnAReactComponent.component",
+      "label": "component",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts",
+      "type": "CompoundType",
+      "lineNumber": 117,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.aPretendNamespaceObj.notAnArrowFn.$4",
+      "label": "d",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts",
+      "type": "CompoundType",
+      "lineNumber": 27,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.aPretendNamespaceObj.aPropertyMisdirection.$4",
+      "label": "d",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts",
+      "type": "CompoundType",
+      "lineNumber": 27,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.aPretendNamespaceObj.aPropertyInlineFn.$1",
+      "label": "a",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts",
+      "type": "CompoundType",
+      "lineNumber": 32,
+      "columnNumber": 23
+    },
+    {
+      "id": "def-public.FnTypeWithGeneric.$2",
+      "label": "p",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Object",
+      "lineNumber": 36,
+      "columnNumber": 43
+    },
+    {
+      "id": "def-public.ImAnObject",
+      "label": "ImAnObject",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Interface",
+      "lineNumber": 53,
+      "columnNumber": 1
+    },
+    {
+      "id": "def-public.MyProps",
+      "label": "MyProps",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Interface",
+      "lineNumber": 60,
+      "columnNumber": 1
+    },
+    {
+      "id": "def-common.ImACommonType",
+      "label": "ImACommonType",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts",
+      "type": "Interface",
+      "lineNumber": 12,
+      "columnNumber": 1
+    }
+  ],
   "isAnyType": [
     {
       "id": "def-public.imAnAny",

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

@@ -27,6 +27,7 @@ export function collectApiStatsForPlugin(doc: PluginApi, issues: IssuesByPlugin)
     isAnyType: [],
     noReferences: [],
     paramDocMismatches: [],
+    missingComplexTypeInfo: [],
     deprecatedAPIsReferencedCount: 0,
     unreferencedDeprecatedApisCount: 0,
     adoptionTrackedAPIs: [],
@@ -75,6 +76,7 @@ function collectStatsForApi(doc: ApiDeclaration, stats: ApiStats, pluginApi: Plu
   }
 
   trackParamDocMismatches(doc, stats);
+  trackMissingComplexTypeInfo(doc, stats);
 
   if (doc.type === TypeKind.AnyKind) {
     stats.isAnyType.push(doc);
@@ -130,6 +132,22 @@ const trackParamDocMismatches = (doc: ApiDeclaration, stats: ApiStats): void =>
   }
 };
 
+/**
+ * Tracks complex types (objects, interfaces, compound types) missing descriptions.
+ */
+const trackMissingComplexTypeInfo = (doc: ApiDeclaration, stats: ApiStats): void => {
+  const complexKinds = new Set<TypeKind>([
+    TypeKind.ObjectKind,
+    TypeKind.InterfaceKind,
+    TypeKind.CompoundTypeKind,
+  ]);
+  if (!complexKinds.has(doc.type)) return;
+  const hasDescription = doc.description !== undefined && doc.description.length > 0;
+  if (!hasDescription) {
+    stats.missingComplexTypeInfo.push(doc);
+  }
+};
+
 function countApiForPlugin(doc: PluginApi) {
   return (
     doc.client.reduce((sum, def) => {

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

@@ -294,6 +294,7 @@ export interface ApiStats {
   isAnyType: ApiDeclaration[];
   noReferences: ApiDeclaration[];
   paramDocMismatches: ApiDeclaration[];
+  missingComplexTypeInfo: ApiDeclaration[];
   apiCount: number;
   missingExports: number;
   deprecatedAPIsReferencedCount: number;