[ES|QL] Displays The Command License Availability In Our Inline Docs

src/platform/packages/private/kbn-language-documentation/package.json

@@ -7,7 +7,7 @@
     "*.scss"
   ],
   "scripts": {
-    "make:docs": "ts-node --transpileOnly scripts/generate_esql_docs.ts",
+    "make:docs": "./scripts/make_docs.sh",
     "postmake:docs": "yarn run lint:fix",
     "lint:fix": "cd ../../../../.. && node ./scripts/eslint --fix ./src/platform/packages/private/kbn-language-documentation/src/sections/generated"
   }

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_command_docs.ts

@@ -0,0 +1,231 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+/* eslint-disable no-console */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  processingCommandsIntro,
+  processingCommandsItems,
+} from './resources/commands/processing_data';
+import { sourceCommandsIntro, sourceCommandsItems } from './resources/commands/source_data';
+import { CommandDefinition, MultipleLicenseInfo } from '../src/types';
+import { getLicenseInfoForCommand } from '../src/utils/get_license_info';
+import {
+  DEFINITION_DIR_SUFFIX,
+  ELASTISEARCH_ESQL_DOCS_BASE_PATH,
+  OUTPUT_DIR,
+} from './scripts.constants';
+import { loadElasticDefinitions } from '../src/utils/load_elastic_definitions';
+
+const ELASTIC_COMMAND_DIR_PATH = path.join(
+  ELASTISEARCH_ESQL_DOCS_BASE_PATH,
+  DEFINITION_DIR_SUFFIX,
+  'commands'
+);
+
+interface CommandItemMetadata {
+  name: string;
+  labelDefaultMessage: string;
+  descriptionDefaultMessage: string;
+  descriptionOptions?: {
+    ignoreTag?: boolean;
+    description?: string;
+  };
+  openLinksInNewTab?: boolean;
+  preview?: boolean;
+  license?: MultipleLicenseInfo;
+}
+
+interface CommandSectionMetadata {
+  labelKey: string;
+  labelDefaultMessage: string;
+  descriptionKey: string;
+  descriptionDefaultMessage: string;
+  items: CommandItemMetadata[];
+  outputFile: string;
+}
+
+const commandsData: CommandSectionMetadata[] = [
+  {
+    ...sourceCommandsIntro,
+    items: sourceCommandsItems,
+    outputFile: `${OUTPUT_DIR}/source_commands.tsx`,
+  },
+  {
+    ...processingCommandsIntro,
+    items: processingCommandsItems,
+    outputFile: `${OUTPUT_DIR}/processing_commands.tsx`,
+  },
+];
+
+/**
+ * This script generates the ESQL inline command documentation files by merging
+ * the source and processing commands with Elasticsearch definitions.
+ *
+ * Step 1: Load the Elasticsearch command definitions from the specified path.
+ * Step 2: Merge the loaded definitions with the source and processing commands.
+ * Step 3: Generate separate documentation files for each command type, including the extra information, such as license details.
+ * Step 4: Write the generated content to the output files in the specified directory.
+ */
+(function () {
+  try {
+    console.log(`Start generating commands documentation`);
+
+    const pathToElasticsearch = process.argv[2];
+    if (!pathToElasticsearch) {
+      throw new Error(
+        'No Elasticsearch path provided, generating without license info for testing...'
+      );
+    }
+
+    const esCommandDirPath = path.join(pathToElasticsearch, ELASTIC_COMMAND_DIR_PATH);
+    const cmdDefinitions = loadElasticDefinitions<CommandDefinition>(esCommandDirPath);
+    const commands = commandsData.map((cmd) => addDefinitionsToCommands(cmd, cmdDefinitions));
+    const docContents = commands.map((cmd) => generateDoc(cmd));
+
+    // Ensure the output directory exists
+    if (!fs.existsSync(OUTPUT_DIR)) {
+      fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+    }
+
+    // Write each generated documentation file
+    docContents.forEach((content, i) => fs.writeFileSync(`${commands[i].outputFile}`, content));
+    console.log(`Sucessfully generated commands documentation files`);
+  } catch (error) {
+    console.error(`Error writing documentation files: ${error.message}`);
+    process.exit(1);
+  }
+})();
+
+/**
+ * Adds Elasticsearch information, such as license details, to commands
+ */
+function addDefinitionsToCommands(
+  data: CommandSectionMetadata,
+  definitions: Map<string, CommandDefinition>
+): CommandSectionMetadata {
+  return {
+    ...data,
+    items: data.items.map((item) => {
+      const commandDef = definitions.get(item.name);
+      const licenseInfo = getLicenseInfoForCommand(commandDef);
+
+      if (licenseInfo) {
+        return {
+          ...item,
+          license: licenseInfo,
+        };
+      }
+      return item;
+    }),
+  };
+}
+
+/**
+ * Generates the full content for a single command documentation file.
+ */
+function generateDoc(data: CommandSectionMetadata): string {
+  return `
+import React from 'react';
+import { i18n } from '@kbn/i18n';
+import { Markdown as SharedUXMarkdown } from '@kbn/shared-ux-markdown';
+
+const Markdown = (props: Parameters<typeof SharedUXMarkdown>[0]) => (
+  <SharedUXMarkdown {...props} readOnly enableSoftLineBreaks />
+);
+
+// Do not edit manually... automatically generated by scripts/generate_esql_command_docs.ts
+
+export const commands = ${generateCommandSectionDoc(data)};
+`;
+}
+
+/**
+ * Generates a documentation for a specific group of commands.
+ */
+function generateCommandSectionDoc({
+  items,
+  labelKey,
+  labelDefaultMessage,
+  descriptionKey,
+  descriptionDefaultMessage,
+}: CommandSectionMetadata): string {
+  const commandsContentDoc = items.map((item) => generateCommandItemDoc(item)).join(',\n    ');
+
+  return `{
+  label: i18n.translate('${labelKey}', {
+    defaultMessage: '${labelDefaultMessage}',
+  }),
+  description: i18n.translate('${descriptionKey}', {
+    defaultMessage: \`${descriptionDefaultMessage}\`,
+  }),
+  items: [
+    ${commandsContentDoc}
+  ],
+}`;
+}
+
+/**
+ * Generates a single command documentation.
+ */
+function generateCommandItemDoc({
+  name,
+  labelDefaultMessage,
+  descriptionDefaultMessage,
+  openLinksInNewTab,
+  descriptionOptions,
+  preview,
+  license,
+}: CommandItemMetadata): string {
+  function generateMarkdownProps(props: { openLinksInNewTab?: boolean }): string {
+    return props.openLinksInNewTab ? ' openLinksInNewTab={true}' : '';
+  }
+
+  function generateDescriptionOptions(
+    options: {
+      ignoreTag?: boolean;
+      description?: string;
+    } = {}
+  ) {
+    const formattedDescriptionOptions = Object.entries(options || {}).map(([key, value]) =>
+      typeof value === 'boolean'
+        ? `${key}: ${value},`
+        : `${key}: '${String(value).replace(/'/g, "\\'")}',`
+    );
+
+    return formattedDescriptionOptions.length > 0
+      ? `,\n ${formattedDescriptionOptions.join('\n')}`
+      : '';
+  }
+
+  // Sample (as a command) use a special suffix to avoid conflict with the same function name
+  const labelKey = `languageDocumentation.documentationESQL.${
+    name === 'sample' ? name + 'Command' : name
+  }`;
+  const descriptionKey = `${labelKey}.markdown`;
+  const previewProp = preview !== undefined ? `\n preview: ${preview},` : '';
+  const licenseProp = license ? `\n license: ${JSON.stringify(license)},` : '';
+  // replace(/`/g, '\\`') escape backticks for nested template literals in the generated file
+  const description = descriptionDefaultMessage.replace(/`/g, '\\`');
+
+  return `{
+      label: i18n.translate('${labelKey}', {
+        defaultMessage: '${labelDefaultMessage}',
+      }),${previewProp}
+      description: (
+        <Markdown${generateMarkdownProps({ openLinksInNewTab })}
+          markdownContent={i18n.translate('${descriptionKey}', {
+            defaultMessage: \`${description}\`${generateDescriptionOptions(descriptionOptions)}
+          })}
+        />
+      ),${licenseProp}
+}`;
+}

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_docs.ts

@@ -12,13 +12,14 @@ const n = recast.types.namedTypes;
 import fs from 'fs';
 import path from 'path';
 import { functions } from '../src/sections/generated/scalar_functions';
-import { getLicenseInfo } from '../src/utils/get_license_info';
-import { FunctionDefinition } from '../src/types';
+import { getLicenseInfoForFunctions } from '../src/utils/get_license_info';
+import { FunctionDefinition, MultipleLicenseInfo } from '../src/types';
+import { loadElasticDefinitions } from '../src/utils/load_elastic_definitions';
 
 interface DocsSectionContent {
   description: string;
   preview: boolean;
-  license: ReturnType<typeof getLicenseInfo> | undefined;
+  license: MultipleLicenseInfo | undefined;
 }
 
 (function () {
@@ -87,9 +88,8 @@ function loadFunctionDocs({
   // Read the directory
   const docsFiles = fs.readdirSync(pathToDocs);
 
-  const ESFunctionDefinitions = fs
-    .readdirSync(pathToDefs)
-    .map((file) => JSON.parse(fs.readFileSync(`${pathToDefs}/${file}`, 'utf-8')));
+  const fnDefinitionsMap = loadElasticDefinitions<FunctionDefinition>(pathToDefs);
+  const ESFunctionDefinitions = Array.from(fnDefinitionsMap.values());
 
   const docs = new Map<string, DocsSectionContent>();
 
@@ -118,20 +118,14 @@ function loadFunctionDocs({
         functionDefinition.titleName ? functionDefinition.titleName : baseFunctionName
       }${functionDefinition.operator ? ` (${functionDefinition.operator})` : ''}`;
 
-      // Create a map of function definitions for quick lookup
-      const fnDefinitionMap: Map<string, FunctionDefinition> = new Map();
-      ESFunctionDefinitions.forEach((def) => {
-        fnDefinitionMap.set(def.name, def);
-      });
-
       // Find corresponding function definition for license information
-      const fnDefinition = fnDefinitionMap.get(baseFunctionName);
+      const fnDefinition = fnDefinitionsMap.get(baseFunctionName);
 
       // Add the function name and content to the map
       docs.set(functionName, {
         description: content,
         preview: functionDefinition.preview,
-        license: getLicenseInfo(fnDefinition),
+        license: getLicenseInfoForFunctions(fnDefinition),
       });
     }
   }

src/platform/packages/private/kbn-language-documentation/scripts/make_docs.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Wrapper script to handle path parameter for make:defs
+if [ -z "$1" ]; then
+    echo "Error: Path to Elasticsearch is required"
+    echo "Usage: $0 /path/to/elasticsearch"
+    exit 1
+fi
+
+ELASTICSEARCH_PATH="$1"
+
+# Run both scripts with the provided path
+ts-node --transpileOnly ./scripts/generate_esql_command_docs.ts "$ELASTICSEARCH_PATH" && \
+ts-node --transpileOnly ./scripts/generate_esql_docs.ts "$ELASTICSEARCH_PATH"