From 9d9d06058021258bbb4f53dcdce744c1cf5c8b97 Mon Sep 17 00:00:00 2001 From: Aviv Keller Date: Thu, 30 Jul 2026 14:21:39 -0700 Subject: [PATCH] refactor(legacy): extract @doc-kittens/legacy package --- .changeset/legacy-kitten-package.md | 9 ++++ eslint.config.mjs | 2 +- package-lock.json | 16 +++++- packages/core/package.json | 4 -- packages/core/src/generators/index.mjs | 8 +-- .../src/utils/__tests__/generators.test.mjs | 44 --------------- packages/core/src/utils/generators.mjs | 52 ------------------ .../core/src/utils/signature/parseList.mjs | 2 +- packages/legacy/package.json | 32 +++++++++++ .../src}/legacy-html-all/README.md | 0 .../src}/legacy-html-all/generate.mjs | 7 +-- .../src}/legacy-html-all/index.mjs | 2 +- .../src}/legacy-html-all/types.d.ts | 0 .../src}/legacy-html/README.md | 0 .../src}/legacy-html/assets/api.js | 0 .../src}/legacy-html/assets/js-flavor-cjs.svg | 0 .../src}/legacy-html/assets/js-flavor-esm.svg | 0 .../src}/legacy-html/assets/style.css | 0 .../src}/legacy-html/generate.mjs | 11 ++-- .../src}/legacy-html/index.mjs | 3 +- .../src}/legacy-html/template.html | 0 .../src}/legacy-html/types.d.ts | 2 +- .../utils/__tests__/buildContent.test.mjs | 3 +- .../utils/__tests__/slugger.test.mjs | 0 .../src}/legacy-html/utils/buildContent.mjs | 26 ++++----- .../src}/legacy-html/utils/buildDropdowns.mjs | 8 +-- .../legacy-html/utils/buildExtraContent.mjs | 6 +-- .../utils/replaceTemplateValues.mjs | 5 +- .../src}/legacy-html/utils/slugger.mjs | 2 +- .../legacy-html/utils/tableOfContents.mjs | 8 +-- .../src}/legacy-json-all/README.md | 0 .../src}/legacy-json-all/generate.mjs | 5 +- .../src}/legacy-json-all/index.mjs | 2 +- .../src}/legacy-json-all/types.d.ts | 0 .../src}/legacy-json/README.md | 0 .../src}/legacy-json/constants.mjs | 0 .../src}/legacy-json/generate.mjs | 8 +-- .../src}/legacy-json/index.mjs | 0 .../src}/legacy-json/types.d.ts | 4 +- .../utils/__tests__/buildHierarchy.test.mjs | 0 .../utils/__tests__/buildSection.test.mjs | 0 .../src}/legacy-json/utils/buildHierarchy.mjs | 4 +- .../src}/legacy-json/utils/buildSection.mjs | 23 ++++---- .../src/utils/__tests__/legacyToJSON.test.mjs | 47 ++++++++++++++++ packages/legacy/src/utils/legacyToJSON.mjs | 53 +++++++++++++++++++ 45 files changed, 231 insertions(+), 167 deletions(-) create mode 100644 .changeset/legacy-kitten-package.md create mode 100644 packages/legacy/package.json rename packages/{core/src/generators => legacy/src}/legacy-html-all/README.md (100%) rename packages/{core/src/generators => legacy/src}/legacy-html-all/generate.mjs (90%) rename packages/{core/src/generators => legacy/src}/legacy-html-all/index.mjs (94%) rename packages/{core/src/generators => legacy/src}/legacy-html-all/types.d.ts (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/README.md (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/assets/api.js (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/assets/js-flavor-cjs.svg (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/assets/js-flavor-esm.svg (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/assets/style.css (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/generate.mjs (90%) rename packages/{core/src/generators => legacy/src}/legacy-html/index.mjs (92%) rename packages/{core/src/generators => legacy/src}/legacy-html/template.html (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/types.d.ts (86%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/__tests__/buildContent.test.mjs (93%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/__tests__/slugger.test.mjs (100%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/buildContent.mjs (88%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/buildDropdowns.mjs (90%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/buildExtraContent.mjs (78%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/replaceTemplateValues.mjs (88%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/slugger.mjs (90%) rename packages/{core/src/generators => legacy/src}/legacy-html/utils/tableOfContents.mjs (80%) rename packages/{core/src/generators => legacy/src}/legacy-json-all/README.md (100%) rename packages/{core/src/generators => legacy/src}/legacy-json-all/generate.mjs (93%) rename packages/{core/src/generators => legacy/src}/legacy-json-all/index.mjs (90%) rename packages/{core/src/generators => legacy/src}/legacy-json-all/types.d.ts (100%) rename packages/{core/src/generators => legacy/src}/legacy-json/README.md (100%) rename packages/{core/src/generators => legacy/src}/legacy-json/constants.mjs (100%) rename packages/{core/src/generators => legacy/src}/legacy-json/generate.mjs (86%) rename packages/{core/src/generators => legacy/src}/legacy-json/index.mjs (100%) rename packages/{core/src/generators => legacy/src}/legacy-json/types.d.ts (96%) rename packages/{core/src/generators => legacy/src}/legacy-json/utils/__tests__/buildHierarchy.test.mjs (100%) rename packages/{core/src/generators => legacy/src}/legacy-json/utils/__tests__/buildSection.test.mjs (100%) rename packages/{core/src/generators => legacy/src}/legacy-json/utils/buildHierarchy.mjs (91%) rename packages/{core/src/generators => legacy/src}/legacy-json/utils/buildSection.mjs (83%) create mode 100644 packages/legacy/src/utils/__tests__/legacyToJSON.test.mjs create mode 100644 packages/legacy/src/utils/legacyToJSON.mjs diff --git a/.changeset/legacy-kitten-package.md b/.changeset/legacy-kitten-package.md new file mode 100644 index 00000000..5c5e27bb --- /dev/null +++ b/.changeset/legacy-kitten-package.md @@ -0,0 +1,9 @@ +--- +'@doc-kittens/legacy': major +'@node-core/doc-kit': minor +--- + +The legacy-format generators (`legacy-html`, `legacy-html-all`, +`legacy-json`, and `legacy-json-all`) now live in the new +`@doc-kittens/legacy` package and are loaded via import specifiers such as +`@doc-kittens/legacy/legacy-html`. The CLI shorthand names are unchanged. diff --git a/eslint.config.mjs b/eslint.config.mjs index 9e92946a..f8dceaa5 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -95,7 +95,7 @@ export default defineConfig([ }, { files: [ - 'packages/core/src/generators/legacy-html/assets/*.js', + 'packages/legacy/src/legacy-html/assets/*.js', 'packages/react/src/html/ui/**/*', ], languageOptions: { diff --git a/package-lock.json b/package-lock.json index d2ad6593..9c8ad678 100644 --- a/package-lock.json +++ b/package-lock.json @@ -405,6 +405,10 @@ "url": "https://github.com/prettier/prettier?sponsor=1" } }, + "node_modules/@doc-kittens/legacy": { + "resolved": "packages/legacy", + "link": true + }, "node_modules/@doc-kittens/react": { "resolved": "packages/react", "link": true @@ -11380,9 +11384,19 @@ "doc-kit": "bin/cli.mjs" } }, + "packages/legacy": { + "name": "@doc-kittens/legacy", + "version": "0.0.0", + "dependencies": { + "@node-core/doc-kit": "^1.4.3", + "hastscript": "^9.0.1", + "unist-builder": "^4.0.0", + "unist-util-visit": "^5.1.0" + } + }, "packages/react": { "name": "@doc-kittens/react", - "version": "1.0.0", + "version": "0.0.0", "dependencies": { "@fontsource-variable/open-sans": "^5.3.0", "@fontsource/ibm-plex-mono": "^5.3.0", diff --git a/packages/core/package.json b/packages/core/package.json index 0852355e..b0a870c0 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -23,10 +23,6 @@ "./ast": "./src/generators/ast/index.mjs", "./ast-js": "./src/generators/ast-js/index.mjs", "./json-simple": "./src/generators/json-simple/index.mjs", - "./legacy-html": "./src/generators/legacy-html/index.mjs", - "./legacy-html-all": "./src/generators/legacy-html-all/index.mjs", - "./legacy-json": "./src/generators/legacy-json/index.mjs", - "./legacy-json-all": "./src/generators/legacy-json-all/index.mjs", "./man-page": "./src/generators/man-page/index.mjs", "./metadata": "./src/generators/metadata/index.mjs", "./package.json": "./package.json", diff --git a/packages/core/src/generators/index.mjs b/packages/core/src/generators/index.mjs index 9e6d313a..ae94a6b2 100644 --- a/packages/core/src/generators/index.mjs +++ b/packages/core/src/generators/index.mjs @@ -11,11 +11,11 @@ */ export const publicGenerators = { 'json-simple': '@node-core/doc-kit/json-simple', - 'legacy-html': '@node-core/doc-kit/legacy-html', - 'legacy-html-all': '@node-core/doc-kit/legacy-html-all', + 'legacy-html': '@doc-kittens/legacy/legacy-html', + 'legacy-html-all': '@doc-kittens/legacy/legacy-html-all', 'man-page': '@node-core/doc-kit/man-page', - 'legacy-json': '@node-core/doc-kit/legacy-json', - 'legacy-json-all': '@node-core/doc-kit/legacy-json-all', + 'legacy-json': '@doc-kittens/legacy/legacy-json', + 'legacy-json-all': '@doc-kittens/legacy/legacy-json-all', 'addon-verify': '@node-core/doc-kit/addon-verify', 'api-links': '@node-core/doc-kit/api-links', 'orama-db': '@doc-kittens/react/orama-db', diff --git a/packages/core/src/utils/__tests__/generators.test.mjs b/packages/core/src/utils/__tests__/generators.test.mjs index cd0c48eb..d6ef025b 100644 --- a/packages/core/src/utils/__tests__/generators.test.mjs +++ b/packages/core/src/utils/__tests__/generators.test.mjs @@ -6,7 +6,6 @@ import { getVersionFromSemVer, coerceSemVer, getCompatibleVersions, - legacyToJSON, } from '../generators.mjs'; describe('groupNodesByModule', () => { @@ -80,46 +79,3 @@ describe('getCompatibleVersions', () => { assert.equal(result.length, 2); }); }); - -describe('legacyToJSON', () => { - const base = { - type: 'module', - source: 'lib/fs.js', - introduced_in: 'v0.10.0', - meta: {}, - stability: 2, - stabilityText: 'Stable', - classes: [], - methods: ['readFile'], - properties: [], - miscs: [], - modules: ['fs'], - globals: [], - }; - - it('serialises a normal section with all keys', () => { - const result = JSON.parse(legacyToJSON({ ...base, api: 'fs' })); - assert.ok('type' in result); - assert.ok('methods' in result); - assert.ok('modules' in result); - }); - - it('omits modules key for index sections', () => { - const result = JSON.parse(legacyToJSON({ ...base, api: 'index' })); - assert.ok(!('modules' in result)); - }); - - it('uses all.json key order when api is null', () => { - const result = JSON.parse(legacyToJSON({ ...base, api: null })); - // all.json only includes miscs, modules, classes, globals, methods - assert.ok('miscs' in result); - assert.ok('modules' in result); - assert.ok(!('type' in result)); - assert.ok(!('source' in result)); - }); - - it('passes extra args to JSON.stringify (e.g. indentation)', () => { - const result = legacyToJSON({ ...base, api: 'fs' }, null, 2); - assert.ok(result.includes('\n')); - }); -}); diff --git a/packages/core/src/utils/generators.mjs b/packages/core/src/utils/generators.mjs index 48430853..ea2d97df 100644 --- a/packages/core/src/utils/generators.mjs +++ b/packages/core/src/utils/generators.mjs @@ -69,55 +69,3 @@ export const getCompatibleVersions = (introduced, releases) => { */ export const leftHandAssign = (target, source) => Object.keys(source).forEach(k => k in target || (target[k] = source[k])); - -/** - * Transforms an object to JSON output consistent with the JSON version. - * @param {import('../generators/legacy-json/types').Section} section - The source object - * @param {any[]} args - * @returns {string} - The JSON output - */ -export const legacyToJSON = ( - { - api, - type, - source, - introduced_in, - meta, - stability, - stabilityText, - classes, - methods, - properties, - miscs, - modules, - globals, - }, - ...args -) => - JSON.stringify( - api == null - ? { - // all.json special order - miscs, - modules, - classes, - globals, - methods, - } - : { - type, - source, - introduced_in, - meta, - stability, - stabilityText, - classes, - methods, - properties, - miscs, - // index.json shouldn't have a `modules` key: - ...(api === 'index' ? undefined : { modules }), - globals, - }, - ...args - ); diff --git a/packages/core/src/utils/signature/parseList.mjs b/packages/core/src/utils/signature/parseList.mjs index 9839b594..a9ca2cad 100644 --- a/packages/core/src/utils/signature/parseList.mjs +++ b/packages/core/src/utils/signature/parseList.mjs @@ -85,7 +85,7 @@ export function parseListItem(child) { /** * Parses a list of nodes and updates the corresponding section object with the extracted information. * Handles different section types such as methods, properties, and events differently. - * @param {import('../../generators/legacy-json/types').Section} section + * @param {{ [key: string]: unknown }} section - The section object to populate with the parsed values * @param {import('@types/mdast').RootContent[]} nodes */ export function parseList(section, nodes) { diff --git a/packages/legacy/package.json b/packages/legacy/package.json new file mode 100644 index 00000000..a1cd7e20 --- /dev/null +++ b/packages/legacy/package.json @@ -0,0 +1,32 @@ +{ + "name": "@doc-kittens/legacy", + "type": "module", + "version": "0.0.0", + "description": "Legacy-format generators for @node-core/doc-kit: legacy-html, legacy-html-all, legacy-json, and legacy-json-all", + "repository": { + "type": "git", + "url": "git+https://github.com/nodejs/doc-kit.git", + "directory": "packages/legacy" + }, + "exports": { + "./legacy-html": "./src/legacy-html/index.mjs", + "./legacy-html-all": "./src/legacy-html-all/index.mjs", + "./legacy-json": "./src/legacy-json/index.mjs", + "./legacy-json-all": "./src/legacy-json-all/index.mjs", + "./package.json": "./package.json" + }, + "files": [ + "src", + "!src/**/*.test.mjs", + "!src/**/__tests__", + "CHANGELOG.md", + "LICENSE", + "README.md" + ], + "dependencies": { + "@node-core/doc-kit": "^1.4.3", + "hastscript": "^9.0.1", + "unist-builder": "^4.0.0", + "unist-util-visit": "^5.1.0" + } +} diff --git a/packages/core/src/generators/legacy-html-all/README.md b/packages/legacy/src/legacy-html-all/README.md similarity index 100% rename from packages/core/src/generators/legacy-html-all/README.md rename to packages/legacy/src/legacy-html-all/README.md diff --git a/packages/core/src/generators/legacy-html-all/generate.mjs b/packages/legacy/src/legacy-html-all/generate.mjs similarity index 90% rename from packages/core/src/generators/legacy-html-all/generate.mjs rename to packages/legacy/src/legacy-html-all/generate.mjs index 1aa7bfdf..348fa23d 100644 --- a/packages/core/src/generators/legacy-html-all/generate.mjs +++ b/packages/legacy/src/legacy-html-all/generate.mjs @@ -3,9 +3,10 @@ import { readFile, writeFile } from 'node:fs/promises'; import { join } from 'node:path'; -import getConfig from '../../utils/configuration/index.mjs'; -import { minifyHTML } from '../../utils/html-minifier.mjs'; -import { getRemarkRehype as remark } from '../../utils/remark.mjs'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { minifyHTML } from '@node-core/doc-kit/utils/html-minifier.mjs'; +import { getRemarkRehype as remark } from '@node-core/doc-kit/utils/remark.mjs'; + import { replaceTemplateValues } from '../legacy-html/utils/replaceTemplateValues.mjs'; import tableOfContents from '../legacy-html/utils/tableOfContents.mjs'; diff --git a/packages/core/src/generators/legacy-html-all/index.mjs b/packages/legacy/src/legacy-html-all/index.mjs similarity index 94% rename from packages/core/src/generators/legacy-html-all/index.mjs rename to packages/legacy/src/legacy-html-all/index.mjs index 4d6f1d35..e2b97406 100644 --- a/packages/core/src/generators/legacy-html-all/index.mjs +++ b/packages/legacy/src/legacy-html-all/index.mjs @@ -18,7 +18,7 @@ export default { description: 'Generates the `all.html` file from the `legacy-html` generator, which includes all the modules in one single file', - dependsOn: '@node-core/doc-kit/legacy-html', + dependsOn: '@doc-kittens/legacy/legacy-html', defaultConfiguration: { templatePath: legacyHtml.defaultConfiguration.templatePath, diff --git a/packages/core/src/generators/legacy-html-all/types.d.ts b/packages/legacy/src/legacy-html-all/types.d.ts similarity index 100% rename from packages/core/src/generators/legacy-html-all/types.d.ts rename to packages/legacy/src/legacy-html-all/types.d.ts diff --git a/packages/core/src/generators/legacy-html/README.md b/packages/legacy/src/legacy-html/README.md similarity index 100% rename from packages/core/src/generators/legacy-html/README.md rename to packages/legacy/src/legacy-html/README.md diff --git a/packages/core/src/generators/legacy-html/assets/api.js b/packages/legacy/src/legacy-html/assets/api.js similarity index 100% rename from packages/core/src/generators/legacy-html/assets/api.js rename to packages/legacy/src/legacy-html/assets/api.js diff --git a/packages/core/src/generators/legacy-html/assets/js-flavor-cjs.svg b/packages/legacy/src/legacy-html/assets/js-flavor-cjs.svg similarity index 100% rename from packages/core/src/generators/legacy-html/assets/js-flavor-cjs.svg rename to packages/legacy/src/legacy-html/assets/js-flavor-cjs.svg diff --git a/packages/core/src/generators/legacy-html/assets/js-flavor-esm.svg b/packages/legacy/src/legacy-html/assets/js-flavor-esm.svg similarity index 100% rename from packages/core/src/generators/legacy-html/assets/js-flavor-esm.svg rename to packages/legacy/src/legacy-html/assets/js-flavor-esm.svg diff --git a/packages/core/src/generators/legacy-html/assets/style.css b/packages/legacy/src/legacy-html/assets/style.css similarity index 100% rename from packages/core/src/generators/legacy-html/assets/style.css rename to packages/legacy/src/legacy-html/assets/style.css diff --git a/packages/core/src/generators/legacy-html/generate.mjs b/packages/legacy/src/legacy-html/generate.mjs similarity index 90% rename from packages/core/src/generators/legacy-html/generate.mjs rename to packages/legacy/src/legacy-html/generate.mjs index a4d5de62..756641a6 100644 --- a/packages/core/src/generators/legacy-html/generate.mjs +++ b/packages/legacy/src/legacy-html/generate.mjs @@ -3,14 +3,15 @@ import { readFile, cp } from 'node:fs/promises'; import { basename, join } from 'node:path'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { writeFile } from '@node-core/doc-kit/utils/file.mjs'; +import { groupNodesByModule } from '@node-core/doc-kit/utils/generators.mjs'; +import { minifyHTML } from '@node-core/doc-kit/utils/html-minifier.mjs'; +import { getRemarkRehypeWithShiki as remark } from '@node-core/doc-kit/utils/remark.mjs'; + import buildContent from './utils/buildContent.mjs'; import { replaceTemplateValues } from './utils/replaceTemplateValues.mjs'; import tableOfContents from './utils/tableOfContents.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { writeFile } from '../../utils/file.mjs'; -import { groupNodesByModule } from '../../utils/generators.mjs'; -import { minifyHTML } from '../../utils/html-minifier.mjs'; -import { getRemarkRehypeWithShiki as remark } from '../../utils/remark.mjs'; /** * Creates a heading object with the given name. diff --git a/packages/core/src/generators/legacy-html/index.mjs b/packages/legacy/src/legacy-html/index.mjs similarity index 92% rename from packages/core/src/generators/legacy-html/index.mjs rename to packages/legacy/src/legacy-html/index.mjs index 68c4ea9f..fd9ecbb1 100644 --- a/packages/core/src/generators/legacy-html/index.mjs +++ b/packages/legacy/src/legacy-html/index.mjs @@ -2,8 +2,9 @@ import { join } from 'node:path'; +import { GITHUB_EDIT_URL } from '@node-core/doc-kit/utils/configuration/templates.mjs'; + import { generate, processChunk } from './generate.mjs'; -import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs'; /** * diff --git a/packages/core/src/generators/legacy-html/template.html b/packages/legacy/src/legacy-html/template.html similarity index 100% rename from packages/core/src/generators/legacy-html/template.html rename to packages/legacy/src/legacy-html/template.html diff --git a/packages/core/src/generators/legacy-html/types.d.ts b/packages/legacy/src/legacy-html/types.d.ts similarity index 86% rename from packages/core/src/generators/legacy-html/types.d.ts rename to packages/legacy/src/legacy-html/types.d.ts index 19b2cf7d..d7c5c8fe 100644 --- a/packages/core/src/generators/legacy-html/types.d.ts +++ b/packages/legacy/src/legacy-html/types.d.ts @@ -1,4 +1,4 @@ -import type { MetadataEntry } from '../metadata/types'; +import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; export interface TemplateValues { api: string; diff --git a/packages/core/src/generators/legacy-html/utils/__tests__/buildContent.test.mjs b/packages/legacy/src/legacy-html/utils/__tests__/buildContent.test.mjs similarity index 93% rename from packages/core/src/generators/legacy-html/utils/__tests__/buildContent.test.mjs rename to packages/legacy/src/legacy-html/utils/__tests__/buildContent.test.mjs index ac40da98..1e21095d 100644 --- a/packages/core/src/generators/legacy-html/utils/__tests__/buildContent.test.mjs +++ b/packages/legacy/src/legacy-html/utils/__tests__/buildContent.test.mjs @@ -3,7 +3,8 @@ import assert from 'node:assert/strict'; import { before, describe, it } from 'node:test'; -import { setConfig } from '../../../../utils/configuration/index.mjs'; +import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs'; + import buildContent from '../buildContent.mjs'; const createEntry = slug => { diff --git a/packages/core/src/generators/legacy-html/utils/__tests__/slugger.test.mjs b/packages/legacy/src/legacy-html/utils/__tests__/slugger.test.mjs similarity index 100% rename from packages/core/src/generators/legacy-html/utils/__tests__/slugger.test.mjs rename to packages/legacy/src/legacy-html/utils/__tests__/slugger.test.mjs diff --git a/packages/core/src/generators/legacy-html/utils/buildContent.mjs b/packages/legacy/src/legacy-html/utils/buildContent.mjs similarity index 88% rename from packages/core/src/generators/legacy-html/utils/buildContent.mjs rename to packages/legacy/src/legacy-html/utils/buildContent.mjs index fd643ab8..4cf2e5d7 100644 --- a/packages/core/src/generators/legacy-html/utils/buildContent.mjs +++ b/packages/legacy/src/legacy-html/utils/buildContent.mjs @@ -1,23 +1,23 @@ 'use strict'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { + GITHUB_BLOB_URL, + populate, +} from '@node-core/doc-kit/utils/configuration/templates.mjs'; +import { UNIST } from '@node-core/doc-kit/utils/queries/index.mjs'; +import { getRemarkRehypeWithShiki as remark } from '@node-core/doc-kit/utils/remark.mjs'; import { h as createElement } from 'hastscript'; import { u as createTree } from 'unist-builder'; import { SKIP, visit } from 'unist-util-visit'; import buildExtraContent from './buildExtraContent.mjs'; import { createLegacySlugger } from './slugger.mjs'; -import getConfig from '../../../utils/configuration/index.mjs'; -import { - GITHUB_BLOB_URL, - populate, -} from '../../../utils/configuration/templates.mjs'; -import { UNIST } from '../../../utils/queries/index.mjs'; -import { getRemarkRehypeWithShiki as remark } from '../../../utils/remark.mjs'; /** * Builds a Markdown heading for a given node * - * @param {import('../../metadata/types').HeadingNode} node The node to build the Markdown heading for + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} node The node to build the Markdown heading for * @param {number} index The index of the current node * @param {import('unist').Parent} parent The parent node of the current node * @returns {import('hast').Element} The HTML AST tree of the heading content @@ -54,7 +54,7 @@ const buildHeading = ({ data, children, depth }, index, parent, legacySlug) => { /** * Builds an HTML Stability element * - * @param {import('../../metadata/types').StabilityNode} node The HTML AST tree of the Stability Index content + * @param {import('@node-core/doc-kit/generators/metadata/types').StabilityNode} node The HTML AST tree of the Stability Index content * @param {number} index The index of the current node * @param {import('unist').Parent} parent The parent node of the current node */ @@ -77,7 +77,7 @@ const buildStability = ({ children, data }, index, parent) => { /** * Creates a history table row. * - * @param {import('../../metadata/types').ChangeEntry} change + * @param {import('@node-core/doc-kit/generators/metadata/types').ChangeEntry} change */ const createHistoryTableRow = ({ version: changeVersions, description }) => { const descriptionNode = remark().parse(description); @@ -94,7 +94,7 @@ const createHistoryTableRow = ({ version: changeVersions, description }) => { /** * Builds the Metadata Properties into content * - * @param {import('../../metadata/types').MetadataEntry} node The node to build the properties from + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} node The node to build the properties from * @returns {import('unist').Parent} The HTML AST tree of the properties content */ const buildMetadataElement = node => { @@ -202,8 +202,8 @@ const buildMetadataElement = node => { /** * Builds the whole content of a given node (API module) * - * @param {Array} headNodes The API metadata Nodes that are considered the "head" of each module - * @param {Array} metadataEntries The API metadata Nodes to be transformed into HTML content + * @param {Array} headNodes The API metadata Nodes that are considered the "head" of each module + * @param {Array} metadataEntries The API metadata Nodes to be transformed into HTML content */ export default (headNodes, metadataEntries) => { const getLegacySlug = createLegacySlugger(); diff --git a/packages/core/src/generators/legacy-html/utils/buildDropdowns.mjs b/packages/legacy/src/legacy-html/utils/buildDropdowns.mjs similarity index 90% rename from packages/core/src/generators/legacy-html/utils/buildDropdowns.mjs rename to packages/legacy/src/legacy-html/utils/buildDropdowns.mjs index 7a2c3be8..6e961b23 100644 --- a/packages/core/src/generators/legacy-html/utils/buildDropdowns.mjs +++ b/packages/legacy/src/legacy-html/utils/buildDropdowns.mjs @@ -1,11 +1,11 @@ 'use strict'; -import getConfig from '../../../utils/configuration/index.mjs'; -import { populate } from '../../../utils/configuration/templates.mjs'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; import { getCompatibleVersions, getVersionFromSemVer, -} from '../../../utils/generators.mjs'; +} from '@node-core/doc-kit/utils/generators.mjs'; /** * Builds the Dropdown for the current Table of Contents @@ -50,7 +50,7 @@ export const buildNavigation = navigationContents => * * @param {string} path The current API node name * @param {string} added The version the API was added - * @param {Array} versions All available Node.js releases + * @param {Array} versions All available Node.js releases */ export const buildVersions = (path, added, versions) => { const config = getConfig('legacy-html'); diff --git a/packages/core/src/generators/legacy-html/utils/buildExtraContent.mjs b/packages/legacy/src/legacy-html/utils/buildExtraContent.mjs similarity index 78% rename from packages/core/src/generators/legacy-html/utils/buildExtraContent.mjs rename to packages/legacy/src/legacy-html/utils/buildExtraContent.mjs index 6f9ef45f..6a95496d 100644 --- a/packages/core/src/generators/legacy-html/utils/buildExtraContent.mjs +++ b/packages/legacy/src/legacy-html/utils/buildExtraContent.mjs @@ -6,7 +6,7 @@ import { u as createTree } from 'unist-builder'; /** * Generates the Stability Overview table based on the API metadata nodes. * - * @param {Array} headMetadata The API metadata nodes to be used for the Stability Overview + * @param {Array} headMetadata The API metadata nodes to be used for the Stability Overview */ const buildStabilityOverview = headMetadata => { const headNodesWithStability = headMetadata.filter(entry => entry.stability); @@ -46,8 +46,8 @@ const buildStabilityOverview = headMetadata => { /** * Generates extra "special" HTML content based on extra metadata that a node may have. * - * @param {Array} headNodes The API metadata nodes to be used for the Stability Overview - * @param {import('../../metadata/types').MetadataEntry} node The current API metadata node to be transformed into HTML content + * @param {Array} headNodes The API metadata nodes to be used for the Stability Overview + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} node The current API metadata node to be transformed into HTML content * @returns {import('unist').Parent} The HTML AST tree for the extra content */ export default (headNodes, node) => { diff --git a/packages/core/src/generators/legacy-html/utils/replaceTemplateValues.mjs b/packages/legacy/src/legacy-html/utils/replaceTemplateValues.mjs similarity index 88% rename from packages/core/src/generators/legacy-html/utils/replaceTemplateValues.mjs rename to packages/legacy/src/legacy-html/utils/replaceTemplateValues.mjs index baec0754..b206f567 100644 --- a/packages/core/src/generators/legacy-html/utils/replaceTemplateValues.mjs +++ b/packages/legacy/src/legacy-html/utils/replaceTemplateValues.mjs @@ -1,5 +1,7 @@ 'use strict'; +import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs'; + import { buildToC, buildNavigation, @@ -7,13 +9,12 @@ import { buildGitHub, } from './buildDropdowns.mjs'; import tableOfContents from './tableOfContents.mjs'; -import { populate } from '../../../utils/configuration/templates.mjs'; /** * Replaces the template values in the API template with the given values. * @param {string} apiTemplate - The HTML template string * @param {import('../types').TemplateValues} values - The values to replace the template values with - * @param {import('../../../utils/configuration/types').GlobalConfiguration} config + * @param {import('@node-core/doc-kit/utils/configuration/types').GlobalConfiguration} config * @param {{ skipGitHub?: boolean; skipGtocPicker?: boolean }} [options] - Optional settings * @returns {string} The replaced template values */ diff --git a/packages/core/src/generators/legacy-html/utils/slugger.mjs b/packages/legacy/src/legacy-html/utils/slugger.mjs similarity index 90% rename from packages/core/src/generators/legacy-html/utils/slugger.mjs rename to packages/legacy/src/legacy-html/utils/slugger.mjs index 43d805cb..714b9e66 100644 --- a/packages/core/src/generators/legacy-html/utils/slugger.mjs +++ b/packages/legacy/src/legacy-html/utils/slugger.mjs @@ -1,6 +1,6 @@ 'use strict'; -import { DEPRECATION_HEADING_REGEX } from '../../metadata/constants.mjs'; +import { DEPRECATION_HEADING_REGEX } from '@node-core/doc-kit/generators/metadata/constants.mjs'; /** * Creates a stateful slugger for legacy anchor links. diff --git a/packages/core/src/generators/legacy-html/utils/tableOfContents.mjs b/packages/legacy/src/legacy-html/utils/tableOfContents.mjs similarity index 80% rename from packages/core/src/generators/legacy-html/utils/tableOfContents.mjs rename to packages/legacy/src/legacy-html/utils/tableOfContents.mjs index 6a8f86d9..c6d342ff 100644 --- a/packages/core/src/generators/legacy-html/utils/tableOfContents.mjs +++ b/packages/legacy/src/legacy-html/utils/tableOfContents.mjs @@ -8,8 +8,8 @@ * * This generates a Markdown string containing a list as the ToC for the API documentation. * - * @param {Array} entries The API metadata nodes to be used for the ToC - * @param {{ maxDepth: number; parser: (metadata: import('../../metadata/types').MetadataEntry) => string }} options The optional ToC options + * @param {Array} entries The API metadata nodes to be used for the ToC + * @param {{ maxDepth: number; parser: (metadata: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry) => string }} options The optional ToC options */ const tableOfContents = (entries, options) => { // Filter out the entries that have a name property / or that have empty content @@ -33,7 +33,7 @@ const tableOfContents = (entries, options) => { /** * Builds the Label with extra metadata to be used in the ToC * - * @param {import('../../metadata/types').MetadataEntry} metadata The current node that is being parsed + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} metadata The current node that is being parsed */ tableOfContents.parseNavigationNode = ({ api, heading }) => `${heading.data.name}`; @@ -41,7 +41,7 @@ tableOfContents.parseNavigationNode = ({ api, heading }) => /** * Builds the Label with extra metadata to be used in the ToC * - * @param {import('../../metadata/types').MetadataEntry} metadata + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} metadata */ tableOfContents.parseToCNode = ({ stability, api, heading }) => { const fullSlug = `${api}.html#${heading.data.slug}`; diff --git a/packages/core/src/generators/legacy-json-all/README.md b/packages/legacy/src/legacy-json-all/README.md similarity index 100% rename from packages/core/src/generators/legacy-json-all/README.md rename to packages/legacy/src/legacy-json-all/README.md diff --git a/packages/core/src/generators/legacy-json-all/generate.mjs b/packages/legacy/src/legacy-json-all/generate.mjs similarity index 93% rename from packages/core/src/generators/legacy-json-all/generate.mjs rename to packages/legacy/src/legacy-json-all/generate.mjs index bc04f9aa..76bae144 100644 --- a/packages/core/src/generators/legacy-json-all/generate.mjs +++ b/packages/legacy/src/legacy-json-all/generate.mjs @@ -3,8 +3,9 @@ import { writeFile } from 'node:fs/promises'; import { join } from 'node:path'; -import getConfig from '../../utils/configuration/index.mjs'; -import { legacyToJSON } from '../../utils/generators.mjs'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; + +import { legacyToJSON } from '../utils/legacyToJSON.mjs'; /** * Generates the legacy JSON `all.json` file. diff --git a/packages/core/src/generators/legacy-json-all/index.mjs b/packages/legacy/src/legacy-json-all/index.mjs similarity index 90% rename from packages/core/src/generators/legacy-json-all/index.mjs rename to packages/legacy/src/legacy-json-all/index.mjs index 38af8498..b33b9d59 100644 --- a/packages/core/src/generators/legacy-json-all/index.mjs +++ b/packages/legacy/src/legacy-json-all/index.mjs @@ -14,7 +14,7 @@ export default { description: 'Generates the `all.json` file from the `legacy-json` generator, which includes all the modules in one single file.', - dependsOn: '@node-core/doc-kit/legacy-json', + dependsOn: '@doc-kittens/legacy/legacy-json', defaultConfiguration: { minify: false, diff --git a/packages/core/src/generators/legacy-json-all/types.d.ts b/packages/legacy/src/legacy-json-all/types.d.ts similarity index 100% rename from packages/core/src/generators/legacy-json-all/types.d.ts rename to packages/legacy/src/legacy-json-all/types.d.ts diff --git a/packages/core/src/generators/legacy-json/README.md b/packages/legacy/src/legacy-json/README.md similarity index 100% rename from packages/core/src/generators/legacy-json/README.md rename to packages/legacy/src/legacy-json/README.md diff --git a/packages/core/src/generators/legacy-json/constants.mjs b/packages/legacy/src/legacy-json/constants.mjs similarity index 100% rename from packages/core/src/generators/legacy-json/constants.mjs rename to packages/legacy/src/legacy-json/constants.mjs diff --git a/packages/core/src/generators/legacy-json/generate.mjs b/packages/legacy/src/legacy-json/generate.mjs similarity index 86% rename from packages/core/src/generators/legacy-json/generate.mjs rename to packages/legacy/src/legacy-json/generate.mjs index b19f2e5d..e13d8bde 100644 --- a/packages/core/src/generators/legacy-json/generate.mjs +++ b/packages/legacy/src/legacy-json/generate.mjs @@ -2,10 +2,12 @@ import { join } from 'node:path'; +import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs'; +import { writeFile, withExt } from '@node-core/doc-kit/utils/file.mjs'; +import { groupNodesByModule } from '@node-core/doc-kit/utils/generators.mjs'; + import { createSectionBuilder } from './utils/buildSection.mjs'; -import getConfig from '../../utils/configuration/index.mjs'; -import { writeFile, withExt } from '../../utils/file.mjs'; -import { groupNodesByModule, legacyToJSON } from '../../utils/generators.mjs'; +import { legacyToJSON } from '../utils/legacyToJSON.mjs'; const buildSection = createSectionBuilder(); diff --git a/packages/core/src/generators/legacy-json/index.mjs b/packages/legacy/src/legacy-json/index.mjs similarity index 100% rename from packages/core/src/generators/legacy-json/index.mjs rename to packages/legacy/src/legacy-json/index.mjs diff --git a/packages/core/src/generators/legacy-json/types.d.ts b/packages/legacy/src/legacy-json/types.d.ts similarity index 96% rename from packages/core/src/generators/legacy-json/types.d.ts rename to packages/legacy/src/legacy-json/types.d.ts index 058ffc65..40f7580a 100644 --- a/packages/core/src/generators/legacy-json/types.d.ts +++ b/packages/legacy/src/legacy-json/types.d.ts @@ -1,6 +1,6 @@ import { ListItem } from '@types/mdast'; -import { MetadataEntry } from '../metadata/types'; -import { MethodSignature } from '../../utils/signature/types'; +import { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types'; +import { MethodSignature } from '@node-core/doc-kit/utils/signature/types'; /** * A node in the entry hierarchy. diff --git a/packages/core/src/generators/legacy-json/utils/__tests__/buildHierarchy.test.mjs b/packages/legacy/src/legacy-json/utils/__tests__/buildHierarchy.test.mjs similarity index 100% rename from packages/core/src/generators/legacy-json/utils/__tests__/buildHierarchy.test.mjs rename to packages/legacy/src/legacy-json/utils/__tests__/buildHierarchy.test.mjs diff --git a/packages/core/src/generators/legacy-json/utils/__tests__/buildSection.test.mjs b/packages/legacy/src/legacy-json/utils/__tests__/buildSection.test.mjs similarity index 100% rename from packages/core/src/generators/legacy-json/utils/__tests__/buildSection.test.mjs rename to packages/legacy/src/legacy-json/utils/__tests__/buildSection.test.mjs diff --git a/packages/core/src/generators/legacy-json/utils/buildHierarchy.mjs b/packages/legacy/src/legacy-json/utils/buildHierarchy.mjs similarity index 91% rename from packages/core/src/generators/legacy-json/utils/buildHierarchy.mjs rename to packages/legacy/src/legacy-json/utils/buildHierarchy.mjs index 1b17edec..511bc11a 100644 --- a/packages/core/src/generators/legacy-json/utils/buildHierarchy.mjs +++ b/packages/legacy/src/legacy-json/utils/buildHierarchy.mjs @@ -1,7 +1,7 @@ /** * Recursively finds the most suitable parent node for a given `entry` based on heading depth. * - * @param {import('../../metadata/types').MetadataEntry} entry + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry * @param {Array} nodes * @param {number} startIdx * @returns {import('../types.d.ts').HierarchizedEntry} @@ -39,7 +39,7 @@ export function findParent(entry, nodes, startIdx) { * found by looping through entries in reverse starting at the current * index - 1. * - * @param {Array} entries + * @param {Array} entries * @returns {Array} */ export function buildHierarchy(entries) { diff --git a/packages/core/src/generators/legacy-json/utils/buildSection.mjs b/packages/legacy/src/legacy-json/utils/buildSection.mjs similarity index 83% rename from packages/core/src/generators/legacy-json/utils/buildSection.mjs rename to packages/legacy/src/legacy-json/utils/buildSection.mjs index 41b2d222..db978160 100644 --- a/packages/core/src/generators/legacy-json/utils/buildSection.mjs +++ b/packages/legacy/src/legacy-json/utils/buildSection.mjs @@ -1,8 +1,9 @@ +import { enforceArray } from '@node-core/doc-kit/utils/array.mjs'; +import { getRemarkRehype as remark } from '@node-core/doc-kit/utils/remark.mjs'; +import { parseList } from '@node-core/doc-kit/utils/signature/parseList.mjs'; +import { transformNodesToString } from '@node-core/doc-kit/utils/unist.mjs'; + import { buildHierarchy } from './buildHierarchy.mjs'; -import { enforceArray } from '../../../utils/array.mjs'; -import { getRemarkRehype as remark } from '../../../utils/remark.mjs'; -import { parseList } from '../../../utils/signature/parseList.mjs'; -import { transformNodesToString } from '../../../utils/unist.mjs'; import { SECTION_TYPE_PLURALS, UNPROMOTED_KEYS } from '../constants.mjs'; /** @@ -33,7 +34,7 @@ export const promoteMiscChildren = (section, parent) => { export const createSectionBuilder = () => { /** * Creates metadata from a metadata entry. - * @param {import('../../metadata/types').MetadataEntry} entry - The entry to create metadata from. + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The entry to create metadata from. * @returns {import('../types.d.ts').Meta | undefined} The created metadata, or undefined if all fields are empty. */ const createMeta = ({ @@ -73,8 +74,8 @@ export const createSectionBuilder = () => { /** * Creates a section from an entry and its heading. - * @param {import('../../metadata/types').MetadataEntry} entry - The AST entry. - * @param {import('../../metadata/types').HeadingNode} head - The head node of the entry. + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The AST entry. + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} head - The head node of the entry. * @returns {import('../types.d.ts').Section} The created section. */ const createSection = (entry, head) => { @@ -98,7 +99,7 @@ export const createSectionBuilder = () => { * Parses stability metadata and adds it to the section. * @param {import('../types.d.ts').Section} section - The section to update. * @param {Array} nodes - The remaining AST nodes. - * @param {import('../../metadata/types').MetadataEntry} entry - The entry providing stability information. + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The entry providing stability information. */ const parseStability = (section, nodes, { stability, content }) => { if (stability) { @@ -135,7 +136,7 @@ export const createSectionBuilder = () => { * Adds additional metadata to the section based on its type. * @param {import('../types.d.ts').Section} section - The section to update. * @param {import('../types.d.ts').Section} parent - The parent section. - * @param {import('../../metadata/types').HeadingNode} heading - The heading node of the section. + * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} heading - The heading node of the section. */ const addAdditionalMetadata = (section, parent, heading) => { if (!section.type || section.type === 'module') { @@ -180,8 +181,8 @@ export const createSectionBuilder = () => { /** * Builds the module section from head metadata and entries. - * @param {import('../../metadata/types').MetadataEntry} head - The head metadata entry. - * @param {Array} entries - The list of metadata entries. + * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} head - The head metadata entry. + * @param {Array} entries - The list of metadata entries. * @returns {import('../types.d.ts').ModuleSection} The constructed module section. */ return (head, entries) => { diff --git a/packages/legacy/src/utils/__tests__/legacyToJSON.test.mjs b/packages/legacy/src/utils/__tests__/legacyToJSON.test.mjs new file mode 100644 index 00000000..65619717 --- /dev/null +++ b/packages/legacy/src/utils/__tests__/legacyToJSON.test.mjs @@ -0,0 +1,47 @@ +import assert from 'node:assert/strict'; +import { describe, it } from 'node:test'; + +import { legacyToJSON } from '../legacyToJSON.mjs'; + +describe('legacyToJSON', () => { + const base = { + type: 'module', + source: 'lib/fs.js', + introduced_in: 'v0.10.0', + meta: {}, + stability: 2, + stabilityText: 'Stable', + classes: [], + methods: ['readFile'], + properties: [], + miscs: [], + modules: ['fs'], + globals: [], + }; + + it('serialises a normal section with all keys', () => { + const result = JSON.parse(legacyToJSON({ ...base, api: 'fs' })); + assert.ok('type' in result); + assert.ok('methods' in result); + assert.ok('modules' in result); + }); + + it('omits modules key for index sections', () => { + const result = JSON.parse(legacyToJSON({ ...base, api: 'index' })); + assert.ok(!('modules' in result)); + }); + + it('uses all.json key order when api is null', () => { + const result = JSON.parse(legacyToJSON({ ...base, api: null })); + // all.json only includes miscs, modules, classes, globals, methods + assert.ok('miscs' in result); + assert.ok('modules' in result); + assert.ok(!('type' in result)); + assert.ok(!('source' in result)); + }); + + it('passes extra args to JSON.stringify (e.g. indentation)', () => { + const result = legacyToJSON({ ...base, api: 'fs' }, null, 2); + assert.ok(result.includes('\n')); + }); +}); diff --git a/packages/legacy/src/utils/legacyToJSON.mjs b/packages/legacy/src/utils/legacyToJSON.mjs new file mode 100644 index 00000000..2b1a1f95 --- /dev/null +++ b/packages/legacy/src/utils/legacyToJSON.mjs @@ -0,0 +1,53 @@ +'use strict'; + +/** + * Transforms an object to JSON output consistent with the JSON version. + * @param {import('../legacy-json/types').Section} section - The source object + * @param {any[]} args + * @returns {string} - The JSON output + */ +export const legacyToJSON = ( + { + api, + type, + source, + introduced_in, + meta, + stability, + stabilityText, + classes, + methods, + properties, + miscs, + modules, + globals, + }, + ...args +) => + JSON.stringify( + api == null + ? { + // all.json special order + miscs, + modules, + classes, + globals, + methods, + } + : { + type, + source, + introduced_in, + meta, + stability, + stabilityText, + classes, + methods, + properties, + miscs, + // index.json shouldn't have a `modules` key: + ...(api === 'index' ? undefined : { modules }), + globals, + }, + ...args + );