fix(orama): fix various bugs in Orama-DB generator (#286)

Author: avivkeller

src/generators/orama-db/index.mjs

@@ -1,11 +1,55 @@
 'use strict';
 
-import { create } from '@orama/orama';
+import { create, insert } from '@orama/orama';
 import { persistToFile } from '@orama/plugin-data-persistence/server';
 
+import { enforceArray } from '../../utils/array.mjs';
 import { groupNodesByModule } from '../../utils/generators.mjs';
 import { createSectionBuilder } from '../legacy-json/utils/buildSection.mjs';
 
+/**
+ * Schema definition for the Orama database
+ */
+const ORAMA_SCHEMA = {
+  name: 'string',
+  type: 'string',
+  desc: 'string',
+  stability: 'number',
+  stabilityText: 'string',
+  meta: {
+    changes: 'string[]',
+    added: 'string[]',
+    napiVersion: 'string[]',
+    deprecated: 'string[]',
+    removed: 'string[]',
+  },
+};
+
+/**
+ * Transforms a section into the format expected by Orama
+ * @param {import('../legacy-json/types.d.ts').ModuleSection} node - The section to transform
+ */
+function transformSectionForOrama(node) {
+  return {
+    name: node.name,
+    type: node.type,
+    desc: node.desc,
+    // Account for duplicate stability nodes
+    stability: enforceArray(node.stability)[0],
+    stabilityText: enforceArray(node.stabilityText)[0],
+    meta: {
+      changes:
+        node.meta?.changes?.map(
+          c => `${enforceArray(c.version).join(', ')}: ${c.description}`
+        ) ?? [],
+      added: node.meta?.added ?? [],
+      napiVersion: node.meta?.napiVersion ?? [],
+      deprecated: node.meta?.deprecated ?? [],
+      removed: node.meta?.removed ?? [],
+    },
+  };
+}
+
 /**
  * This generator is responsible for generating the Orama database for the
  * API docs. It is based on the legacy-json generator.
@@ -16,11 +60,8 @@ import { createSectionBuilder } from '../legacy-json/utils/buildSection.mjs';
  */
 export default {
   name: 'orama-db',
-
   version: '1.0.0',
-
   description: 'Generates the Orama database for the API docs.',
-
   dependsOn: 'ast',
 
   /**
@@ -30,65 +71,35 @@ export default {
    * @param {Partial<GeneratorOptions>} options
    */
   async generate(input, { output, version }) {
-    const buildSection = createSectionBuilder();
+    if (!input?.length) {
+      throw new Error('Input data is required and must not be empty');
+    }
 
-    // Create the Orama instance with the schema
-    const db = create({
-      schema: {
-        name: 'string',
-        type: 'string',
-        desc: 'string',
-        stability: 'number',
-        stabilityText: 'string',
-        meta: {
-          changes: 'string[]',
-          added: 'string[]',
-          napiVersion: 'string[]',
-          deprecated: 'string[]',
-          removed: 'string[]',
-        },
-      },
-    });
+    if (!output || !version) {
+      throw new Error('Output path and version are required');
+    }
 
+    const db = create({ schema: ORAMA_SCHEMA });
+    const buildSection = createSectionBuilder();
     const groupedModules = groupNodesByModule(input);
+    const headNodes = input.filter(node => node.heading?.depth === 1);
 
-    // Gets the first nodes of each module, which is considered the "head"
-    const headNodes = input.filter(node => node.heading.depth === 1);
-
-    /**
-     * @param {ApiDocMetadataEntry} head
-     * @returns {void}
-     */
-    const processModuleNodes = head => {
-      const nodes = groupedModules.get(head.api);
+    // Process each head node and insert into database
+    headNodes.forEach(headNode => {
+      const nodes = groupedModules.get(headNode.api);
 
-      const section = buildSection(head, nodes);
+      const section = buildSection(headNode, nodes);
+      const node = (section.modules || section.globals || section.miscs)[0];
+      if (!node) return;
 
-      // Insert data into the Orama instance
-      db.insert({
-        name: section.name,
-        type: section.type,
-        desc: section.desc,
-        stability: section.stability,
-        stabilityText: section.stabilityText,
-        meta: {
-          changes: section.meta.changes,
-          added: section.meta.added,
-          napiVersion: section.meta.napiVersion,
-          deprecated: section.meta.deprecated,
-          removed: section.meta.removed,
-        },
-      });
-
-      return section;
-    };
+      const oramaData = transformSectionForOrama(node);
+      insert(db, oramaData);
+    });
 
-    headNodes.map(processModuleNodes);
+    // Generate output filename and persist database
+    const sanitizedVersion = version.raw.replaceAll('.', '-');
+    const outputFilename = `${output}/${sanitizedVersion}-orama-db.json`;
 
-    await persistToFile(
-      db,
-      'json',
-      `${output}/${version.raw.replaceAll('.', '-')}-orama-db.json`
-    );
+    await persistToFile(db, 'json', outputFilename);
   },
 };