fix(plugins/plugin-client-common): improve Missing titles in guide steps

This PR detects when we don't have enough context for a code block, and if so looks for the nearest enclosing heading (or tip title) to add that missing context.

Author: starpit

plugins/plugin-client-common/src/components/Content/Markdown/components/code/rehype-code-indexer.ts

@@ -24,6 +24,8 @@ import isExecutable from './isCodeBlock'
 import { isTab } from '../../rehype-tabbed'
 import isElementWithProperties from '../../isElement'
 import toMarkdownString, { Node } from '../../toMarkdownString'
+import { getTipTitle, isTipWithFullTitle, isTipWithoutFullTitle } from '../../rehype-tip'
+
 import {
   isHeading,
   isHeadingOrRemovedHeading,
@@ -67,9 +69,9 @@ function findNearestEnclosingTitle(grandparent: Parent, parent: Node) {
   if (grandparent && parentIdx >= 0 && isElementWithProperties(grandparent)) {
     for (let idx = parentIdx - 1; idx >= 0; idx--) {
       const child = grandparent.children[idx]
-      if (isHeadingOrRemovedHeading(child)) {
+      if (isHeadingOrRemovedHeading(child) || isTipWithFullTitle(child)) {
         return {
-          title: isHeading(child) ? toString(child) : '',
+          title: isHeading(child) ? toString(child) : isTipWithFullTitle(child) ? getTipTitle(child) : '',
           source: grandparent.children
             .slice(idx, parentIdx + 1)
             .map(toMarkdownString)
@@ -217,6 +219,31 @@ export default function plugin(uuid: string) {
               if (attributes.nesting) {
                 attributes.nesting = attributes.nesting.reverse()
                 reserialize()
+
+                let parent = ancestors[ancestors.length - 1]
+                let grandparent = ancestors[ancestors.length - 2]
+
+                if (isTipWithoutFullTitle(grandparent)) {
+                  parent = grandparent
+                  grandparent = ancestors[ancestors.length - 3]
+                }
+
+                if (parent && grandparent && attributes.nesting.length === 1) {
+                  // Hmm, we don't have much context for this code
+                  // block. Try adding a bit more context by looking for
+                  // an enclosing heading.
+                  const parentHeading = findNearestEnclosingTitle(grandparent, parent)
+                  if (parentHeading && parentHeading.title) {
+                    const { title, source } = parentHeading
+                    addNesting(attributes, {
+                      kind: 'Import',
+                      source,
+                      title,
+                      key: title,
+                      filepath: ''
+                    })
+                  }
+                }
               }
 
               // go from bottom to top stopping at the first import,

plugins/plugin-client-common/src/components/Content/Markdown/rehype-tip/index.ts

@@ -14,8 +14,11 @@
  * limitations under the License.
  */
 
+import { Node, Element } from 'hast'
 import { i18n } from '@kui-shell/core'
 
+import isElementWithProperties from '../isElement'
+
 const strings = i18n('plugin-client-common', 'markdown')
 
 const RE_TIP = /^([?!][?!][?!])(\+?)\s+(tip|todo|bug|info|note|warning|caution|success|question)(\s+"(.+)"\s*)?(\s+inline)?(\s+inline\s+end)?(\n(.|[\n\r])*)?$/i
@@ -25,6 +28,22 @@ const RE_TIP_END = /^(.*)"\s*(\n(.|[\n\r])*)?$/
 export const START_OF_TIP = `<!-- ____KUI_START_OF_TIP____ -->`
 export const END_OF_TIP = `<!-- ____KUI_END_OF_TIP____ -->`
 
+export function isTip(node: Node): node is Element {
+  return isElementWithProperties(node) && node.tagName === 'tip'
+}
+
+export function getTipTitle(elt: Element) {
+  return elt.properties.title.toString()
+}
+
+export function isTipWithFullTitle(node: Node): node is Element {
+  return isTip(node) && !!node.properties.fullTitle
+}
+
+export function isTipWithoutFullTitle(node: Node): node is Element {
+  return isTip(node) && !node.properties.fullTitle
+}
+
 export default function plugin(/* options */) {
   return function transformer(tree) {
     let currentTip
@@ -108,6 +127,7 @@ export default function plugin(/* options */) {
                     properties: {
                       className: startMatch[3].toLowerCase(), // e.g. tip, todo, bug, warning, ...
                       float: startMatch[6] ? 'left' : startMatch[7] ? 'right' : undefined,
+                      hasFullTitle: !!startMatch[5],
                       title: startMatch[5] || strings(startMatch[3]),
                       open: !!startMatch[2] || startMatch[1] === '!!!'
                     },
@@ -127,6 +147,7 @@ export default function plugin(/* options */) {
                       tagName: 'tip',
                       properties: {
                         className: startMatch[3].toLowerCase(), // e.g. tip, todo, bug, warning, ...
+                        hasFullTitle: !!startMatch[5],
                         title: startMatch[5] || strings(startMatch[3]),
                         open: !!startMatch[2] || startMatch[1] === '!!!',
                         partial: true

plugins/plugin-client-common/src/components/Content/Markdown/toMarkdownString.ts

@@ -21,6 +21,7 @@ import { Node } from 'hast-util-to-mdast/lib'
 import { visit, CONTINUE, SKIP } from 'unist-util-visit'
 import { toMarkdown } from 'mdast-util-to-markdown'
 
+import { isTip } from './rehype-tip'
 import { isImports } from './remark-import'
 import indent, { indentAll } from './indent'
 import isElementWithProperties from './isElement'
@@ -109,7 +110,7 @@ ${tabContent}
         delete node.children
         delete node.properties
         return SKIP
-      } else if (node.tagName === 'tip') {
+      } else if (isTip(node)) {
         const { className, title, open } = node.properties
 
         const tipContent = node.children