diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4c1e291..5fb5b53 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 diff --git a/README.md b/README.md index 9ad61e4..9148a2a 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/package-lock.json b/package-lock.json index ee0b8e1..1c72081 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 3563eee..0c70a9c 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.mjs b/src/generators.mjs index 931f583..b276d77 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 512271c..19ba907 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 0000000..d6624f9 --- /dev/null +++ b/src/generators/orama-db/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} 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, 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` + ); + }, +}; diff --git a/src/generators/orama-db/types.d.ts b/src/generators/orama-db/types.d.ts new file mode 100644 index 0000000..65f8536 --- /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;