Review update 3 plus support for links in class interface heritage clause

Author: Stacey Gammon

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

@@ -64,7 +64,11 @@ export function extractImportReferences(
         texts.push({
           pluginId: plugin.manifest.id,
           scope: getScopeFromPath(path, plugin, log),
-          docId: getPluginApiDocId(plugin.manifest.id, plugin.manifest.serviceFolders, path),
+          docId: getPluginApiDocId(plugin.manifest.id, {
+            serviceFolders: plugin.manifest.serviceFolders,
+            apiPath: path,
+            directory: plugin.directory,
+          }),
           section,
           text: name,
         });

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

@@ -49,7 +49,10 @@ export function getSignature(
     // Need to tack on manually any type parameters or "extends/implements" section.
     const heritageClause = node
       .getHeritageClauses()
-      .map((h) => h.getText())
+      .map((h) => {
+        const heritance = h.getText().indexOf('implements') > -1 ? 'implements' : 'extends';
+        return `${heritance} ${h.getTypeNodes().map((n) => n.getType().getText())}`;
+      })
       .join(' ');
     signature = `${node.getType().getText()}${heritageClause ? ' ' + heritageClause : ''}`;
   } else {

packages/kbn-docs-utils/src/api_docs/mdx/split_apis_by_folder.test.ts

@@ -38,7 +38,7 @@ beforeAll(() => {
 });
 
 test('foo service has all exports', () => {
-  expect(doc?.client.length).toBe(32);
+  expect(doc?.client.length).toBe(33);
   const split = splitApisByFolder(doc);
   expect(split.length).toBe(2);
 
@@ -47,5 +47,5 @@ test('foo service has all exports', () => {
 
   expect(fooDoc?.common.length).toBe(1);
   expect(fooDoc?.client.length).toBe(2);
-  expect(mainDoc?.client.length).toBe(30);
+  expect(mainDoc?.client.length).toBe(31);
 });

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

@@ -7,7 +7,7 @@
  */
 
 import { ToolingLog } from '@kbn/dev-utils';
-import { getServiceForPath, snakeToCamel } from '../utils';
+import { snakeToCamel } from '../utils';
 import { PluginApi, ApiDeclaration } from '../types';
 import { writePluginDoc } from './write_plugin_mdx_docs';
 
@@ -44,7 +44,9 @@ function addSection(
   pluginServices: { [key: string]: PluginApi },
   serviceFolders: readonly string[]
 ) {
-  const serviceFolderName = getServiceForPath(dec.source.path);
+  const scopeFolder = scope === 'client' ? 'public' : scope;
+  const matchGroup = dec.source.path.match(`.*?\/${scopeFolder}\/([^\/]*?)\/`);
+  const serviceFolderName = matchGroup ? matchGroup[1] : undefined;
 
   if (serviceFolderName && serviceFolders.find((f) => f === serviceFolderName)) {
     const service = snakeToCamel(serviceFolderName);

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

@@ -40,3 +40,6 @@ export enum DayOfWeek {
 export type MultipleDeclarationsType = TypeWithGeneric<typeof DayOfWeek>;
 
 export type IRefANotExportedType = ImNotExportedFromIndex | { zed: 'hi' };
+export interface ImAnObject {
+  foo: FnWithGeneric;
+}

packages/kbn-docs-utils/src/api_docs/tests/api_doc_suite.test.ts

@@ -314,23 +314,31 @@ describe('interfaces and classes', () => {
     expect(exampleInterface?.signature).toBeDefined();
     expect(exampleInterface?.type).toBe(TypeKind.InterfaceKind);
 
-    expect(linkCount(exampleInterface?.signature!)).toBe(1);
+    expect(linkCount(exampleInterface?.signature!)).toBe(2);
 
     // TODO: uncomment if the bug is fixed.
     // This is wrong, the link should be to `AnotherInterface`
     // Another bug, this link is not being captured.
-    // expect(exampleInterface?.signature).toMatchInlineSnapshot(`
-    //   Array [
-    //     "",
-    //     Object {
-    //       "docId": "kibPluginAPluginApi",
-    //       "section": "def-public.ExampleInterface",
-    //       "text": "ExampleInterface",
-    //     },
-    //     " extends AnotherInterface<string>",
-    //   ]
-    // `);
-    // expect(typeof exampleInterface!.signature![2]).toBe('Object');
+    expect(exampleInterface?.signature).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "docId": "kibPluginAPluginApi",
+          "pluginId": "pluginA",
+          "scope": "public",
+          "section": "def-public.ExampleInterface",
+          "text": "ExampleInterface",
+        },
+        " extends ",
+        Object {
+          "docId": "kibPluginAPluginApi",
+          "pluginId": "pluginA",
+          "scope": "public",
+          "section": "def-public.AnotherInterface",
+          "text": "AnotherInterface",
+        },
+        "<string>",
+      ]
+    `);
   });
 
   it('Non arrow function on interface is exported as function type', () => {
@@ -356,10 +364,26 @@ describe('interfaces and classes', () => {
           "section": "def-public.CrazyClass",
           "text": "CrazyClass",
         },
-        "<P> extends ExampleClass<WithGen<P>>",
+        "<P> extends ",
+        Object {
+          "docId": "kibPluginAPluginApi",
+          "pluginId": "pluginA",
+          "scope": "public",
+          "section": "def-public.ExampleClass",
+          "text": "ExampleClass",
+        },
+        "<",
+        Object {
+          "docId": "kibPluginAPluginApi",
+          "pluginId": "pluginA",
+          "scope": "public",
+          "section": "def-public.WithGen",
+          "text": "WithGen",
+        },
+        "<P>>",
       ]
     `);
-    expect(clss?.signature?.length).toBe(2);
+    expect(linkCount(clss?.signature!)).toBe(3);
   });
 
   it('Function with generic inside interface is exported with function type', () => {

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

@@ -27,13 +27,22 @@ it('test getPluginForPath', () => {
 });
 
 it('test getServiceForPath', () => {
-  expect(getServiceForPath('src/plugins/embed/public/service/file.ts')).toBe('service');
-  expect(getServiceForPath('src/plugins/embed/public/service/subfolder/file.ts')).toBe('service');
-  expect(getServiceForPath('src/plugins/embed/public/file.ts')).toBeUndefined();
-  expect(getServiceForPath('src/plugins/embed/server/another_service/file.ts')).toBe(
-    'another_service'
+  expect(getServiceForPath('src/plugins/embed/public/service/file.ts', 'src/plugins/embed')).toBe(
+    'service'
   );
-  expect(getServiceForPath('src/plugins/embed/server/f.ts')).toBeUndefined();
+  expect(
+    getServiceForPath('src/plugins/embed/public/service/subfolder/file.ts', 'src/plugins/embed')
+  ).toBe('service');
+  expect(
+    getServiceForPath('src/plugins/embed/public/file.ts', 'src/plugins/embed')
+  ).toBeUndefined();
+  expect(
+    getServiceForPath('src/plugins/embed/server/another_service/file.ts', 'src/plugins/embed')
+  ).toBe('another_service');
+  expect(
+    getServiceForPath('src/plugins/embed/server/routes/public/foo/index.ts', 'src/plugins/embed')
+  ).toBe('routes');
+  expect(getServiceForPath('src/plugins/embed/server/f.ts', 'src/plugins/embed')).toBeUndefined();
 });
 
 it('test removeBrokenLinks', () => {

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

@@ -59,10 +59,11 @@ export function groupPluginApi(declarations: ApiDeclaration[]): ScopeApi {
  * 'src/plugin/data/server/file.ts' would return undefined.
  * @param path
  */
-export function getServiceForPath(path: string): string | undefined {
-  const publicMatchGroups = path.match(/.*\/public\/(.*?)\/.*/);
-  const serverMatchGroups = path.match(/.*\/server\/(.*?)\/.*/);
-  const commonMatchGroups = path.match(/.*\/common\/(.*?)\/.*/);
+export function getServiceForPath(path: string, pluginDirectory: string): string | undefined {
+  const publicMatchGroups = path.match(`${pluginDirectory}/public\/([^\/]*)\/`);
+  const serverMatchGroups = path.match(`${pluginDirectory}/server\/([^\/]*)\/`);
+  const commonMatchGroups = path.match(`${pluginDirectory}/common\/([^\/]*)\/`);
+
   if (publicMatchGroups && publicMatchGroups.length > 1) {
     return publicMatchGroups[1];
   } else if (serverMatchGroups && serverMatchGroups.length > 1) {
@@ -74,14 +75,17 @@ export function getServiceForPath(path: string): string | undefined {
 
 export function getPluginApiDocId(
   id: string,
-  serviceFolders?: readonly string[],
-  apiPath?: string
+  serviceInfo?: {
+    serviceFolders: readonly string[];
+    apiPath: string;
+    directory: string;
+  }
 ) {
   let service = '';
   const cleanName = id.replace('.', '_');
-  if (apiPath) {
-    const serviceName = getServiceForPath(apiPath);
-    const serviceFolder = serviceFolders?.find((f) => f === serviceName);
+  if (serviceInfo) {
+    const serviceName = getServiceForPath(serviceInfo.apiPath, serviceInfo.directory);
+    const serviceFolder = serviceInfo.serviceFolders?.find((f) => f === serviceName);
 
     if (serviceFolder) {
       service = snakeToCamel(serviceFolder);