feat(generator/orama-db): introduce (#213)

Author: AugustinMauroy

.github/dependabot.yml

@@ -29,4 +29,7 @@ updates:
           - '@eslint/*'
           - 'globals'
           - 'stylelint-*'
+      orama:
+        patterns:
+          - '@orama/*'
     open-pull-requests-limit: 10

README.md

@@ -40,6 +40,6 @@ Options:
   -o, --output <path>        Specify the relative or absolute output directory
   -v, --version <semver>     Specify the target version of Node.js, semver compliant (default: "v22.6.0")
   -c, --changelog <url>      Specify the path (file: or https://) to the CHANGELOG.md file (default: "https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md")
-  -t, --target [mode...]     Set the processing target modes (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page", "legacy-json", "legacy-json-all", "addon-verify", "api-links")
+  -t, --target [mode...]     Set the processing target modes (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page", "legacy-json", "legacy-json-all", "addon-verify", "api-links", "orama-db")
   -h, --help                 display help for command
 ```

package-lock.json

@@ -33,11 +33,13 @@
     "prettier": "3.5.2"
   },
   "dependencies": {
-    "acorn": "^8.14.0",
     "@actions/core": "^1.11.1",
+    "@orama/orama": "^3.1.3",
+    "@orama/plugin-data-persistence": "^3.1.3",
+    "acorn": "^8.14.0",
     "commander": "^13.1.0",
-    "estree-util-visit": "^2.0.0",
     "dedent": "^1.5.3",
+    "estree-util-visit": "^2.0.0",
     "github-slugger": "^2.0.0",
     "glob": "^11.0.1",
     "hast-util-to-string": "^3.0.1",

package.json

@@ -2,12 +2,14 @@
 
 import publicGenerators from './generators/index.mjs';
 import astJs from './generators/ast-js/index.mjs';
+import oramaDb from './generators/orama-db/index.mjs';
 
 const availableGenerators = {
   ...publicGenerators,
   // This one is a little special since we don't want it to run unless we need
   // it and we also don't want it to be publicly accessible through the CLI.
   'ast-js': astJs,
+  'orama-db': oramaDb,
 };
 
 /**

src/generators.mjs

@@ -8,6 +8,7 @@ import legacyJson from './legacy-json/index.mjs';
 import legacyJsonAll from './legacy-json-all/index.mjs';
 import addonVerify from './addon-verify/index.mjs';
 import apiLinks from './api-links/index.mjs';
+import oramaDb from './orama-db/index.mjs';
 
 export default {
   'json-simple': jsonSimple,
@@ -18,4 +19,5 @@ export default {
   'legacy-json-all': legacyJsonAll,
   'addon-verify': addonVerify,
   'api-links': apiLinks,
+  'orama-db': oramaDb,
 };

src/generators/index.mjs

@@ -0,0 +1,94 @@
+'use strict';
+
+import { create } from '@orama/orama';
+import { persistToFile } from '@orama/plugin-data-persistence/server';
+
+import { groupNodesByModule } from '../../utils/generators.mjs';
+import { createSectionBuilder } from '../legacy-json/utils/buildSection.mjs';
+
+/**
+ * This generator is responsible for generating the Orama database for the
+ * API docs. It is based on the legacy-json generator.
+ *
+ * @typedef {Array<ApiDocMetadataEntry>} Input
+ *
+ * @type {import('../types.d.ts').GeneratorMetadata<Input, import('./types.d.ts').OramaDb>}
+ */
+export default {
+  name: 'orama-db',
+
+  version: '1.0.0',
+
+  description: 'Generates the Orama database for the API docs.',
+
+  dependsOn: 'ast',
+
+  /**
+   * Generates the Orama database.
+   *
+   * @param {Input} input
+   * @param {Partial<GeneratorOptions>} options
+   */
+  async generate(input, { output, version }) {
+    const buildSection = createSectionBuilder();
+
+    // 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[]',
+        },
+      },
+    });
+
+    const groupedModules = groupNodesByModule(input);
+
+    // 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);
+
+      const section = buildSection(head, nodes);
+
+      // 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;
+    };
+
+    headNodes.map(processModuleNodes);
+
+    await persistToFile(
+      db,
+      'json',
+      `${output}/${version.raw.replaceAll('.', '-')}-orama-db.json`
+    );
+  },
+};

src/generators/orama-db/index.mjs

@@ -0,0 +1,24 @@
+import { Orama } from '@orama/orama';
+
+/**
+ * Schema for the Orama database entry
+ */
+export interface OramaDbEntry {
+  name: string;
+  type: string;
+  desc: string;
+  stability: number;
+  stabilityText: string;
+  meta: {
+    changes: string[];
+    added: string[];
+    napiVersion: string[];
+    deprecated: string[];
+    removed: string[];
+  };
+}
+
+/**
+ * Represents the Orama database for API docs
+ */
+export type OramaDb = Orama<OramaDbEntry>;