From c824195e297affb3435a4c0eec193e6d66ce09ce Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Tue, 18 Mar 2025 10:21:49 +0100 Subject: [PATCH 1/5] Add Orama db generator --- src/generators.mjs | 2 + src/generators/index.mjs | 2 + src/generators/orama-db/index.mjs | 110 ++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+) create mode 100644 src/generators/orama-db/index.mjs diff --git a/src/generators.mjs b/src/generators.mjs index 931f5834..b276d779 100644 --- a/src/generators.mjs +++ b/src/generators.mjs @@ -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, }; /** diff --git a/src/generators/index.mjs b/src/generators/index.mjs index 512271ce..19ba9073 100644 --- a/src/generators/index.mjs +++ b/src/generators/index.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, }; diff --git a/src/generators/orama-db/index.mjs b/src/generators/orama-db/index.mjs new file mode 100644 index 00000000..2aac679e --- /dev/null +++ b/src/generators/orama-db/index.mjs @@ -0,0 +1,110 @@ +'use strict'; + +import { writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { create } from '@orama/orama'; +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} Input + * + * @type {import('../types.d.ts').GeneratorMetadata} + */ +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} options + */ + async generate(input, { output }) { + 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 {import('./types.d.ts').OramaDbEntry} + */ + 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; + }; + + await Promise.all( + headNodes.map(async node => { + // Get the json for the node's section + const section = processModuleNodes(node); + + // Write it to the output file + if (output) { + await writeFile( + join(output, `${node.api}.json`), + JSON.stringify(section) + ); + } + }) + ); + + // Generate the JSON representation of the Orama db + const oramaDbJson = JSON.stringify(db); + + if (output) { + await writeFile(join(output, 'orama-db.json'), oramaDbJson); + } + + return db; + }, +}; From 165a81ed28f32484132b6528c04713675855ea92 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Tue, 18 Mar 2025 10:31:06 +0100 Subject: [PATCH 2/5] feat(generator/orama-db): clean implementaiton --- package-lock.json | 37 +++++++++++++++++++++++++++++++ package.json | 6 +++-- src/generators/orama-db/index.mjs | 29 +++++------------------- 3 files changed, 46 insertions(+), 26 deletions(-) diff --git a/package-lock.json b/package-lock.json index ee0b8e1c..1c720814 100644 --- a/package-lock.json +++ b/package-lock.json @@ -7,6 +7,8 @@ "name": "@node-core/api-docs-tooling", "dependencies": { "@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", "dedent": "^1.5.3", @@ -414,6 +416,35 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, + "node_modules/@msgpack/msgpack": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@msgpack/msgpack/-/msgpack-2.8.0.tgz", + "integrity": "sha512-h9u4u/jiIRKbq25PM+zymTyW6bhTzELvOoUd+AvYriWOAKpLGnIamaET3pnHYoI5iYphAHBI4ayx0MehR+VVPQ==", + "license": "ISC", + "engines": { + "node": ">= 10" + } + }, + "node_modules/@orama/orama": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/@orama/orama/-/orama-3.1.3.tgz", + "integrity": "sha512-UdtAMLe2RxtqvmfNDJSMpYoQYUpXgs+9qXVVFCO0BqHF86gp+uz8N6ftkaLe1p55OQXmliciw7BH34GFozKLnQ==", + "license": "Apache-2.0", + "engines": { + "node": ">= 16.0.0" + } + }, + "node_modules/@orama/plugin-data-persistence": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/@orama/plugin-data-persistence/-/plugin-data-persistence-3.1.3.tgz", + "integrity": "sha512-pUjq4mOfVgn0TAPROm+UwW4T2VL9TAqDboaP4ZjEGl8NC9TZuKrXzUZnSxpn8pnOd2rfh45+kTyl2ZHLtJdXyw==", + "license": "Apache-2.0", + "dependencies": { + "@msgpack/msgpack": "^2.7.2", + "@orama/orama": "3.1.3", + "dpack": "^0.6.22" + } + }, "node_modules/@pkgjs/parseargs": { "version": "0.11.0", "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz", @@ -1070,6 +1101,12 @@ "tslib": "^2.0.3" } }, + "node_modules/dpack": { + "version": "0.6.22", + "resolved": "https://registry.npmjs.org/dpack/-/dpack-0.6.22.tgz", + "integrity": "sha512-WGPNlW2OAE7Bj0eODMpAHUcEqxrlg01e9OFZDxQodminIgC194/cRHT7K04Z1j7AUEWTeeplYGrIv/xRdwU9Hg==", + "license": "MIT" + }, "node_modules/eastasianwidth": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", diff --git a/package.json b/package.json index 3563eee8..0c70a9ca 100644 --- a/package.json +++ b/package.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", diff --git a/src/generators/orama-db/index.mjs b/src/generators/orama-db/index.mjs index 2aac679e..3eb162a2 100644 --- a/src/generators/orama-db/index.mjs +++ b/src/generators/orama-db/index.mjs @@ -1,8 +1,7 @@ 'use strict'; -import { writeFile } from 'node:fs/promises'; -import { join } from 'node:path'; 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'; @@ -29,7 +28,7 @@ export default { * @param {Input} input * @param {Partial} options */ - async generate(input, { output }) { + async generate(input) { const buildSection = createSectionBuilder(); // Create the Orama instance with the schema @@ -83,27 +82,9 @@ export default { return section; }; - await Promise.all( - headNodes.map(async node => { - // Get the json for the node's section - const section = processModuleNodes(node); - - // Write it to the output file - if (output) { - await writeFile( - join(output, `${node.api}.json`), - JSON.stringify(section) - ); - } - }) - ); - - // Generate the JSON representation of the Orama db - const oramaDbJson = JSON.stringify(db); - - if (output) { - await writeFile(join(output, 'orama-db.json'), oramaDbJson); - } + headNodes.map(processModuleNodes); + + await persistToFile(db, 'json', './db.json'); return db; }, From 602df582eb87b0e3e170ce57ddeb7f5708809fd4 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Tue, 18 Mar 2025 10:32:50 +0100 Subject: [PATCH 3/5] setup(dependabot): add `orama` group --- .github/dependabot.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4c1e291e..5fb5b534 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -29,4 +29,7 @@ updates: - '@eslint/*' - 'globals' - 'stylelint-*' + orama: + patterns: + - '@orama/*' open-pull-requests-limit: 10 From 2227e3fda1255e6142a937d5bc7a2251287e7d21 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Tue, 18 Mar 2025 10:50:00 +0100 Subject: [PATCH 4/5] feat(generator/orama-db): fix output --- README.md | 2 +- src/generators/orama-db/index.mjs | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9ad61e41..9148a2a3 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,6 @@ Options: -o, --output Specify the relative or absolute output directory -v, --version Specify the target version of Node.js, semver compliant (default: "v22.6.0") -c, --changelog 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 ``` diff --git a/src/generators/orama-db/index.mjs b/src/generators/orama-db/index.mjs index 3eb162a2..1d604412 100644 --- a/src/generators/orama-db/index.mjs +++ b/src/generators/orama-db/index.mjs @@ -28,7 +28,7 @@ export default { * @param {Input} input * @param {Partial} options */ - async generate(input) { + async generate(input, { output, version }) { const buildSection = createSectionBuilder(); // Create the Orama instance with the schema @@ -84,7 +84,11 @@ export default { headNodes.map(processModuleNodes); - await persistToFile(db, 'json', './db.json'); + await persistToFile( + db, + 'json', + `${output}/${version.raw.replaceAll('.', '-')}-orama-db.json` + ); return db; }, From 387fb0030c71025423d3a11a81dcb07af96fed53 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Tue, 18 Mar 2025 14:08:22 +0100 Subject: [PATCH 5/5] fix: type def Co-Authored-By: Caner Akdas --- src/generators/orama-db/index.mjs | 5 ++--- src/generators/orama-db/types.d.ts | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 src/generators/orama-db/types.d.ts diff --git a/src/generators/orama-db/index.mjs b/src/generators/orama-db/index.mjs index 1d604412..d6624f90 100644 --- a/src/generators/orama-db/index.mjs +++ b/src/generators/orama-db/index.mjs @@ -2,6 +2,7 @@ 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'; @@ -56,7 +57,7 @@ export default { /** * @param {ApiDocMetadataEntry} head - * @returns {import('./types.d.ts').OramaDbEntry} + * @returns {void} */ const processModuleNodes = head => { const nodes = groupedModules.get(head.api); @@ -89,7 +90,5 @@ export default { 'json', `${output}/${version.raw.replaceAll('.', '-')}-orama-db.json` ); - - return db; }, }; diff --git a/src/generators/orama-db/types.d.ts b/src/generators/orama-db/types.d.ts new file mode 100644 index 00000000..65f8536c --- /dev/null +++ b/src/generators/orama-db/types.d.ts @@ -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;