API docs (#92827) (#92940)

Co-authored-by: Stacey Gammon <gammon@elastic.co>

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_api_declaration.ts

@@ -50,7 +50,6 @@ export function buildApiDeclaration(
   name?: string
 ): ApiDeclaration {
   const apiName = name ? name : isNamedNode(node) ? node.getName() : 'Unnamed';
-  log.debug(`Building API Declaration for ${apiName} of kind ${node.getKindName()}`);
   const apiId = parentApiId ? parentApiId + '.' + apiName : apiName;
   const anchorLink: AnchorLink = { scope, pluginName, apiName: apiId };
 

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_arrow_fn_dec.ts

@@ -47,9 +47,6 @@ export function getArrowFunctionDec(
   anchorLink: AnchorLink,
   log: ToolingLog
 ) {
-  log.debug(
-    `Getting Arrow Function doc def for node ${node.getName()} of kind ${node.getKindName()}`
-  );
   return {
     id: getApiSectionId(anchorLink),
     type: TypeKind.FunctionKind,

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_function_dec.ts

@@ -39,7 +39,6 @@ export function buildFunctionDec(
   const label = Node.isConstructorDeclaration(node)
     ? 'Constructor'
     : node.getName() || '(WARN: Missing name)';
-  log.debug(`Getting function doc def for node ${label} of kind ${node.getKindName()}`);
   return {
     id: getApiSectionId(anchorLink),
     type: TypeKind.FunctionKind,

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_variable_dec.ts

@@ -45,7 +45,6 @@ export function buildVariableDec(
   anchorLink: AnchorLink,
   log: ToolingLog
 ): ApiDeclaration {
-  log.debug('buildVariableDec for ' + node.getName());
   const initializer = node.getInitializer();
   // Recusively list object properties as children.
   if (initializer && Node.isObjectLiteralExpression(initializer)) {

packages/kbn-docs-utils/src/api_docs/build_api_declarations/extract_import_refs.test.ts

@@ -6,6 +6,7 @@
  * Side Public License, v 1.
  */
 
+import { REPO_ROOT } from '@kbn/utils';
 import { KibanaPlatformPlugin, ToolingLog } from '@kbn/dev-utils';
 import { getPluginApiDocId } from '../utils';
 import { extractImportReferences } from './extract_import_refs';
@@ -82,7 +83,43 @@ it('test extractImportReference with unknown imports', () => {
   expect(results.length).toBe(3);
   expect(results[0]).toBe('<I extends ');
   expect(results[1]).toBe('FooFoo');
-  expect(results[2]).toBe('>');
+});
+
+it('test full file imports with no matching plugin', () => {
+  const refs = extractImportReferences(
+    `typeof import("${REPO_ROOT}/src/plugins/data/common/es_query/kuery/node_types/function")`,
+    plugins,
+    log
+  );
+  expect(refs).toMatchInlineSnapshot(`
+    Array [
+      "typeof ",
+      "src/plugins/data/common/es_query/kuery/node_types/function",
+    ]
+  `);
+  expect(refs.length).toBe(2);
+});
+
+it('test full file imports with a matching plugin', () => {
+  const refs = extractImportReferences(
+    `typeof import("${plugin.directory}/public/foo/index") something`,
+    plugins,
+    log
+  );
+  expect(refs).toMatchInlineSnapshot(`
+    Array [
+      "typeof ",
+      Object {
+        "docId": "kibPluginAPluginApi",
+        "pluginId": "pluginA",
+        "scope": "public",
+        "section": undefined,
+        "text": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index",
+      },
+      " something",
+    ]
+  `);
+  expect(refs.length).toBe(3);
 });
 
 it('test single link', () => {

packages/kbn-docs-utils/src/api_docs/build_api_declarations/extract_import_refs.ts

@@ -9,6 +9,7 @@
 import { KibanaPlatformPlugin, ToolingLog } from '@kbn/dev-utils';
 import { getApiSectionId, getPluginApiDocId, getPluginForPath } from '../utils';
 import { ApiScope, TextWithLinks } from '../types';
+import { getRelativePath } from './utils';
 
 /**
  *
@@ -54,6 +55,9 @@ export function extractImportReferences(
         const str = textSegment.substr(index + length - name.length, name.length);
         if (str && str !== '') {
           texts.push(str);
+        } else {
+          // If there is no ".Name" then use the full path. You can see things like "typeof import("file")"
+          texts.push(getRelativePath(path));
         }
       } else {
         const section = getApiSectionId({
@@ -69,10 +73,12 @@ export function extractImportReferences(
             apiPath: path,
             directory: plugin.directory,
           }),
-          section,
-          text: name,
+          section: name && name !== '' ? section : undefined,
+          text: name && name !== '' ? name : getRelativePath(path),
         });
       }
+
+      // Prep textSegment to skip past the `import`, then check for more.
       textSegment = textSegment.substr(index + length);
     } else {
       if (textSegment && textSegment !== '') {
@@ -87,10 +93,10 @@ export function extractImportReferences(
 function extractImportRef(
   str: string
 ): { path: string; name: string; index: number; length: number } | undefined {
-  const groups = str.match(/import\("(.*?)"\)\.(\w*)/);
+  const groups = str.match(/import\("(.*?)"\)\.?(\w*)/);
   if (groups) {
     const path = groups[1];
-    const name = groups[2];
+    const name = groups.length > 2 ? groups[2] : '';
     const index = groups.index!;
     const length = groups[0].length;
     return { path, name, index, length };

packages/kbn-docs-utils/src/api_docs/build_api_declarations/utils.ts

@@ -17,7 +17,7 @@ export function isPrivate(node: ParameterDeclaration | ClassMemberTypes): boolea
 /**
  * Change the absolute path into a relative one.
  */
-function getRelativePath(fullPath: string): string {
+export function getRelativePath(fullPath: string): string {
   return Path.relative(REPO_ROOT, fullPath);
 }
 

packages/kbn-docs-utils/src/api_docs/mdx/write_plugin_mdx_docs.ts

@@ -84,7 +84,7 @@ import ${json} from './${fileName}.json';
     common: groupPluginApi(doc.common),
     server: groupPluginApi(doc.server),
   };
-  fs.writeFileSync(Path.resolve(folder, fileName + '.json'), JSON.stringify(scopedDoc));
+  fs.writeFileSync(Path.resolve(folder, fileName + '.json'), JSON.stringify(scopedDoc, null, 2));
 
   mdx += scopApiToMdx(scopedDoc.client, 'Client', json, 'client');
   mdx += scopApiToMdx(scopedDoc.server, 'Server', json, 'server');

packages/kbn-docs-utils/src/api_docs/tests/snapshots/plugin_a_foo.json

@@ -1 +1,77 @@
-{"id":"pluginA.foo","client":{"classes":[],"functions":[{"id":"def-public.doTheFooFnThing","type":"Function","children":[],"signature":["() => void"],"description":[],"label":"doTheFooFnThing","source":{"path":"/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts","lineNumber":9,"link":"https://github.com/elastic/kibana/tree/master/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L9"},"returnComment":[],"initialIsOpen":false}],"interfaces":[],"enums":[],"misc":[{"id":"def-public.FooType","type":"Type","label":"FooType","description":[],"source":{"path":"/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts","lineNumber":11,"link":"https://github.com/elastic/kibana/tree/master/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L11"},"signature":["() => \"foo\""],"initialIsOpen":false}],"objects":[]},"server":{"classes":[],"functions":[],"interfaces":[],"enums":[],"misc":[],"objects":[]},"common":{"classes":[],"functions":[],"interfaces":[],"enums":[],"misc":[{"id":"def-common.commonFoo","type":"string","label":"commonFoo","description":[],"source":{"path":"/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts","lineNumber":9,"link":"https://github.com/elastic/kibana/tree/master/packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts#L9"},"signature":["\"COMMON VAR!\""],"initialIsOpen":false}],"objects":[]}}
+{
+  "id": "pluginA.foo",
+  "client": {
+    "classes": [],
+    "functions": [
+      {
+        "id": "def-public.doTheFooFnThing",
+        "type": "Function",
+        "children": [],
+        "signature": [
+          "() => void"
+        ],
+        "description": [],
+        "label": "doTheFooFnThing",
+        "source": {
+          "path": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts",
+          "lineNumber": 9,
+          "link": "https://github.com/elastic/kibana/tree/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L9"
+        },
+        "returnComment": [],
+        "initialIsOpen": false
+      }
+    ],
+    "interfaces": [],
+    "enums": [],
+    "misc": [
+      {
+        "id": "def-public.FooType",
+        "type": "Type",
+        "label": "FooType",
+        "description": [],
+        "source": {
+          "path": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts",
+          "lineNumber": 11,
+          "link": "https://github.com/elastic/kibana/tree/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/foo/index.ts#L11"
+        },
+        "signature": [
+          "() => \"foo\""
+        ],
+        "initialIsOpen": false
+      }
+    ],
+    "objects": []
+  },
+  "server": {
+    "classes": [],
+    "functions": [],
+    "interfaces": [],
+    "enums": [],
+    "misc": [],
+    "objects": []
+  },
+  "common": {
+    "classes": [],
+    "functions": [],
+    "interfaces": [],
+    "enums": [],
+    "misc": [
+      {
+        "id": "def-common.commonFoo",
+        "type": "string",
+        "label": "commonFoo",
+        "description": [],
+        "source": {
+          "path": "packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts",
+          "lineNumber": 9,
+          "link": "https://github.com/elastic/kibana/tree/masterpackages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/common/foo/index.ts#L9"
+        },
+        "signature": [
+          "\"COMMON VAR!\""
+        ],
+        "initialIsOpen": false
+      }
+    ],
+    "objects": []
+  }
+}

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

@@ -97,7 +97,7 @@ export interface Reference {
   pluginId: string;
   scope: ApiScope;
   docId: string;
-  section: string;
+  section?: string;
   text: string;
 }
 

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

@@ -91,9 +91,6 @@ export function getPluginApiDocId(
   const cleanName = id.replace('.', '_');
   if (serviceInfo) {
     const serviceName = getServiceForPath(serviceInfo.apiPath, serviceInfo.directory);
-    log.debug(
-      `Service for path ${serviceInfo.apiPath} and ${serviceInfo.directory} is ${serviceName}`
-    );
     const serviceFolder = serviceInfo.serviceFolders?.find((f) => f === serviceName);
 
     if (serviceFolder) {

src/dev/ci_setup/setup.sh

@@ -87,3 +87,19 @@ if [ "$GIT_CHANGES" ]; then
   echo -e "$GIT_CHANGES\n"
   exit 1
 fi
+
+###
+### rebuild plugin api docs to ensure it's not out of date
+###
+echo " -- building api docs"
+node scripts/build_api_docs
+
+###
+### verify no api changes
+###
+GIT_CHANGES="$(git ls-files --modified)"
+if [ "$GIT_CHANGES" ]; then
+  echo -e "\n${RED}ERROR: 'node scripts/build_api_docs' caused changes to the following files:${C_RESET}\n"
+  echo -e "$GIT_CHANGES\n"
+  exit 1
+fi