@doc-kit/core 0.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # @doc-kit/core
 
+## 1.0.1
+
+### Patch Changes
+
+- [#1023](https://github.com/nodejs/doc-kit/pull/1023) [`27a412a`](https://github.com/nodejs/doc-kit/commit/27a412ac35ab06e977b03b559e6525c0c5c5356c) Thanks [@btea](https://github.com/btea)! - Fix empty paragraphs in API docs when a typed parameter list contains trailing non-parameter items
+
+  When a loose markdown list in the API docs starts with typed parameters (e.g. `actual`, `expected`, `Returns`) but also contains plain prose bullets (e.g. algorithm complexity notes), the entire list was previously treated as a parameter signature table. The non-parameter items had no name or type, causing them to render as empty `<section>` blocks on the built site.
+
+  The fix splits the list at the first non-parameter item: typed items become the `FunctionSignature` table, and the remaining items render as regular markdown content.
+
+- [#1045](https://github.com/nodejs/doc-kit/pull/1045) [`4a22c85`](https://github.com/nodejs/doc-kit/commit/4a22c85dca917f52c773aba084191da7c622687e) Thanks [@avivkeller](https://github.com/avivkeller)! - MDX nodes in the HTML-string pipelines are now dropped, and do not crash.
+
+- [#1049](https://github.com/nodejs/doc-kit/pull/1049) [`8cc1fd0`](https://github.com/nodejs/doc-kit/commit/8cc1fd010ac38b16dd3c9bcd422c0ce0e5eb483d) Thanks [@avivkeller](https://github.com/avivkeller)! - Render markdown summaries as markup instead of as their source
+
+## 1.0.0
+
+### Major Changes
+
+- [#961](https://github.com/nodejs/doc-kit/pull/961) [`c334823`](https://github.com/nodejs/doc-kit/commit/c334823a1ee7c1dc4642fa1b0dad90912de22f17) Thanks [@avivkeller](https://github.com/avivkeller)! - The doc-kit engine and CLI, previously published together as
+  `@node-core/doc-kit`, are now published as two packages: `@doc-kit/core`
+  (the engine) and `@doc-kit/cli` (the `doc-kit` command-line interface).
+  The `@node-core/doc-kit` name now contains only the Node.js-specific
+  generators (`api-links`, `addon-verify`, and `man-page`).
+
+- [#960](https://github.com/nodejs/doc-kit/pull/960) [`c734403`](https://github.com/nodejs/doc-kit/commit/c7344034d83dd5858250a5cc386fbe729f07ede0) Thanks [@avivkeller](https://github.com/avivkeller)! - The legacy-format generators (`legacy-html`, `legacy-html-all`,
+  `legacy-json`, and `legacy-json-all`) now live in the new
+  `@node-core/doc-kit-legacy` package and are loaded via import specifiers such
+  as `@node-core/doc-kit-legacy/legacy-html`. The corresponding
+  `@doc-kit/core/*` package exports have been removed. The CLI shorthand
+  names are unchanged.
+
+- [#961](https://github.com/nodejs/doc-kit/pull/961) [`c334823`](https://github.com/nodejs/doc-kit/commit/c334823a1ee7c1dc4642fa1b0dad90912de22f17) Thanks [@avivkeller](https://github.com/avivkeller)! - The Node.js-specific generators (`api-links`, `addon-verify`, and
+  `man-page`) now live in the `@node-core/doc-kit` package and are loaded
+  via import specifiers such as `@node-core/doc-kit/man-page`. The
+  corresponding package exports have been removed from the doc-kit engine.
+  The CLI shorthand names are unchanged.
+
+- [#959](https://github.com/nodejs/doc-kit/pull/959) [`ca36039`](https://github.com/nodejs/doc-kit/commit/ca3603916bee58fb80c1ea3a2e0023c13903fc63) Thanks [@avivkeller](https://github.com/avivkeller)! - The React/JSX-based generators (`html` — previously `web` —, `jsx-ast`,
+  `llms-txt`, `sitemap`, and `orama-db`) now live in the new
+  `@doc-kit/generator-react` package and are loaded via import specifiers such as
+  `@doc-kit/generator-react/html`. The corresponding `@doc-kit/core/*`
+  package exports have been removed. The `web` generator is renamed to `html`:
+  the CLI shorthand `web` keeps working as a deprecated alias, but the
+  configuration key is now `html` instead of `web`.
+
+### Minor Changes
+
+- [#939](https://github.com/nodejs/doc-kit/pull/939) [`7bd1b5b`](https://github.com/nodejs/doc-kit/commit/7bd1b5b15ba2a444bd9e746fb36236030919b273) Thanks [@avivkeller](https://github.com/avivkeller)! - Discover and load configuration files with `cosmiconfig`.
+
+- [#911](https://github.com/nodejs/doc-kit/pull/911) [`ada6540`](https://github.com/nodejs/doc-kit/commit/ada6540fe6c2c32cfa254187c159941b245ebf80) Thanks [@avivkeller](https://github.com/avivkeller)! - Add banner opt-out
+
+- [#958](https://github.com/nodejs/doc-kit/pull/958) [`0bd347d`](https://github.com/nodejs/doc-kit/commit/0bd347da847e21c2501732c0acbdee7db1b0f8f1) Thanks [@avivkeller](https://github.com/avivkeller)! - Generators are now loaded dynamically by import specifier instead of a static
+  registry. `--target` accepts either a built-in shorthand name (`web`,
+  `legacy-html`, …) or any import specifier resolving to a generator module
+  (e.g. `some-package/generator` or `./my-generator.mjs`), and a generator's
+  `dependsOn` is now a full import specifier. This lays the groundwork for
+  splitting the built-in generators into separate packages and enables
+  third-party generator packages.
+
+- [#937](https://github.com/nodejs/doc-kit/pull/937) [`43a09f7`](https://github.com/nodejs/doc-kit/commit/43a09f7ae9cdd4a1863e98b067abcf104e8937f2) Thanks [@avivkeller](https://github.com/avivkeller)! - Make the `web` generator bundler-neutral through a custom adapter contract,
+  with Vite 8.1 provided as the default adapter.
+
+### Patch Changes
+
+- [#964](https://github.com/nodejs/doc-kit/pull/964) [`96e1c26`](https://github.com/nodejs/doc-kit/commit/96e1c26482098aec1753d5fb1aeacb607f7e097f) Thanks [@avivkeller](https://github.com/avivkeller)! - Add `web.navigation`, which supplies the sidebar groups (`navigation.sidebar`)
+  and the navigation bar items (`navigation.navbar`) from configuration.
+
+- [#955](https://github.com/nodejs/doc-kit/pull/955) [`b80958f`](https://github.com/nodejs/doc-kit/commit/b80958ff53dd2388d33ce8ed282b14a67d3374f0) Thanks [@avivkeller](https://github.com/avivkeller)! - Close Orama search when the target link is on the same page
+
+- [#968](https://github.com/nodejs/doc-kit/pull/968) [`d3306a2`](https://github.com/nodejs/doc-kit/commit/d3306a20bf913d2c83739215bc5692434ceef166) Thanks [@pimterry](https://github.com/pimterry)! - Resolve unions and arrays of display-name types (`{HTTP/2 Headers Object | vm.Module}`, `{HTTP/2 Headers Object[]}`), and stop capturing prose such as `U+007B ({), and U+007D (}).` as a type annotation.
+
+- [#889](https://github.com/nodejs/doc-kit/pull/889) [`68751af`](https://github.com/nodejs/doc-kit/commit/68751af17a45cc0c8e76d36308fb1be3f1dec4af) Thanks [@bmuenzenmeyer](https://github.com/bmuenzenmeyer)! - Fix `relative()` URL resolution when the target path is a prefix of the current
+  page's path (e.g. `/generators` from `/generators/web`): the target's final
+  segment was consumed as a common directory, producing `.` instead of
+  `../generators`. Unreachable in flat page layouts; surfaced by sites with
+  nested input directories.
+
+- [#945](https://github.com/nodejs/doc-kit/pull/945) [`70b7526`](https://github.com/nodejs/doc-kit/commit/70b75269e9d0ed6b199c217bb268de96e65645c9) Thanks [@avivkeller](https://github.com/avivkeller)! - Moved the package into a `packages/core` workspace.
+
+- [#1002](https://github.com/nodejs/doc-kit/pull/1002) [`740b613`](https://github.com/nodejs/doc-kit/commit/740b613ded7326eada843c34809ea128c6a9d7b5) Thanks [@avivkeller](https://github.com/avivkeller)! - Defaults are now project-neutral instead of Node.js-specific
+
+- [#946](https://github.com/nodejs/doc-kit/pull/946) [`9ab2840`](https://github.com/nodejs/doc-kit/commit/9ab2840559d2f04a6db6b29bbf6c6d470a1dde0b) Thanks [@btea](https://github.com/btea)! - Fix missing spaces in the riscv64 multithreading warning message, which
+  previously concatenated as "failures whenallocating" and "spaceon riscv64".
+
+- [#933](https://github.com/nodejs/doc-kit/pull/933) [`b73b704`](https://github.com/nodejs/doc-kit/commit/b73b70474a2c499c1be315ebf2595e6932124e19) Thanks [@vsolano9](https://github.com/vsolano9)! - Use short `DEP` codes for deprecation heading anchors.
+
+- [#942](https://github.com/nodejs/doc-kit/pull/942) [`cef45ca`](https://github.com/nodejs/doc-kit/commit/cef45caf14cba83c77c373f59cee7f33f9f3df9b) Thanks [@btea](https://github.com/btea)! - Space union separators in type annotation values (`{string|URL}` is now rendered as `string | URL`).
+
+- [#934](https://github.com/nodejs/doc-kit/pull/934) [`e6f1769`](https://github.com/nodejs/doc-kit/commit/e6f176958f6323d054dc86c4437accc9340e6914) Thanks [@avivkeller](https://github.com/avivkeller)! - Switches `oxc-parser` for `@swc/wasm`, since `oxc-parser` does not provide the needed bindings.
+
+- [#919](https://github.com/nodejs/doc-kit/pull/919) [`d0f0de0`](https://github.com/nodejs/doc-kit/commit/d0f0de069e9061b6684269b412029bdd3dd288ba) Thanks [@MFA-G](https://github.com/MFA-G)! - Preserve deprecation codes in generated table-of-contents labels.
+
+- [#963](https://github.com/nodejs/doc-kit/pull/963) [`2f9defe`](https://github.com/nodejs/doc-kit/commit/2f9defe49cac2d0e95c6fb213075291509a50a5f) Thanks [@btea](https://github.com/btea)! - Sync the URL hash when following same-page search hits
+
+- [#955](https://github.com/nodejs/doc-kit/pull/955) [`b80958f`](https://github.com/nodejs/doc-kit/commit/b80958ff53dd2388d33ce8ed282b14a67d3374f0) Thanks [@avivkeller](https://github.com/avivkeller)! - Render markdown `code` snippets in the sidebar
+
+- Updated dependencies [[`1da2390`](https://github.com/nodejs/doc-kit/commit/1da239076622e792145a38d2045dee404c3ad75f), [`c734403`](https://github.com/nodejs/doc-kit/commit/c7344034d83dd5858250a5cc386fbe729f07ede0), [`4bafb28`](https://github.com/nodejs/doc-kit/commit/4bafb287eda25dc07be9525e16aa6bfc63ebad1d), [`c334823`](https://github.com/nodejs/doc-kit/commit/c334823a1ee7c1dc4642fa1b0dad90912de22f17), [`740b613`](https://github.com/nodejs/doc-kit/commit/740b613ded7326eada843c34809ea128c6a9d7b5), [`740b613`](https://github.com/nodejs/doc-kit/commit/740b613ded7326eada843c34809ea128c6a9d7b5), [`43673d1`](https://github.com/nodejs/doc-kit/commit/43673d1785642cd26a3c6b5406a34d9eea42c68d), [`bfa8f0e`](https://github.com/nodejs/doc-kit/commit/bfa8f0e3bb49cba6bcbe780a61caf3e785bcb23b), [`ca36039`](https://github.com/nodejs/doc-kit/commit/ca3603916bee58fb80c1ea3a2e0023c13903fc63)]:
+  - @doc-kit/generator-react@0.1.0
+  - @node-core/doc-kit-legacy@1.0.0
+  - @node-core/doc-kit@2.0.0
+
 ## 1.4.3
 
 ### Patch Changes

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@doc-kit/core",
   "type": "module",
-  "version": "0.0.0",
+  "version": "1.0.1",
   "description": "The doc-kit engine: the pipeline and shared APIs that power the doc-kit generators and CLI",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nodejs/doc-kit.git",
     "directory": "packages/core"
   },
+  "license": "MIT",
   "main": "./src/generators.mjs",
   "exports": {
     ".": "./src/generators.mjs",
@@ -18,7 +19,19 @@
     "./package.json": "./package.json",
     "./shiki.config.mjs": "./shiki.config.mjs",
     "./src/*": "./src/*",
-    "./*": "./src/*"
+    "./*": [
+      "./src/*",
+      "./src/*.d.ts"
+    ]
+  },
+  "imports": {
+    "#generators/*": "./src/generators/*",
+    "#logger/*": "./src/logger/*",
+    "#parsers/*": [
+      "./src/parsers/*",
+      "./src/parsers/*.d.ts"
+    ],
+    "#utils/*": "./src/utils/*"
   },
   "files": [
     "src",
@@ -64,9 +77,9 @@
     "hast-util-to-string": "^3.0.1"
   },
   "peerDependencies": {
-    "@node-core/doc-kit": "1.4.3",
-    "@node-core/doc-kit-legacy": "0.0.0",
-    "@doc-kit/generator-react": "0.0.0"
+    "@node-core/doc-kit": ">=2.0.0",
+    "@node-core/doc-kit-legacy": ">=1.0.0",
+    "@doc-kit/generator-react": ">=0.1.0"
   },
   "peerDependenciesMeta": {
     "@node-core/doc-kit": {

package/src/generators/ast/generate.mjs

@@ -7,11 +7,12 @@ import globParent from 'glob-parent';
 import { globSync } from 'tinyglobby';
 import { parse as parseYaml } from 'yaml';
 
+import getConfig from '#utils/configuration/index.mjs';
+import { withExt } from '#utils/file.mjs';
+import { QUERIES } from '#utils/queries/index.mjs';
+import { getRemark as remark, getRemarkMdx } from '#utils/remark.mjs';
+
 import { STABILITY_INDEX_URL } from './constants.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { withExt } from '../../utils/file.mjs';
-import { QUERIES } from '../../utils/queries/index.mjs';
-import { getRemark as remark, getRemarkMdx } from '../../utils/remark.mjs';
 
 /**
  * Determines whether a file should be parsed as MDX. A `.mdx` extension opts in

package/src/generators/ast-js/generate.mjs

@@ -6,7 +6,7 @@ import { extname } from 'node:path';
 import { parse } from 'acorn';
 import { globSync } from 'tinyglobby';
 
-import getConfig from '../../utils/configuration/index.mjs';
+import getConfig from '#utils/configuration/index.mjs';
 
 /**
  * Process a chunk of JavaScript files in a worker thread.

package/src/generators/json-simple/generate.mjs

@@ -4,9 +4,9 @@ import { join } from 'node:path';
 
 import { remove } from 'unist-util-remove';
 
-import getConfig from '../../utils/configuration/index.mjs';
-import { writeFile } from '../../utils/file.mjs';
-import { UNIST } from '../../utils/queries/index.mjs';
+import getConfig from '#utils/configuration/index.mjs';
+import { writeFile } from '#utils/file.mjs';
+import { UNIST } from '#utils/queries/index.mjs';
 
 /**
  * Generates the simplified JSON version of the API docs

package/src/generators/metadata/generate.mjs

@@ -1,8 +1,9 @@
 'use strict';
 
+import getConfig from '#utils/configuration/index.mjs';
+import { loadFromURL } from '#utils/loaders.mjs';
+
 import { parseApiDoc } from './utils/parse.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { loadFromURL } from '../../utils/loaders.mjs';
 
 /**
  * Process a chunk of API doc files in a worker thread.

package/src/generators/metadata/utils/parse.mjs

@@ -9,6 +9,15 @@ import { remove } from 'unist-util-remove';
 import { selectAll } from 'unist-util-select';
 import { SKIP, visit } from 'unist-util-visit';
 
+import {
+  DEPRECATION_HEADING_REGEX,
+  IGNORE_STABILITY_STEMS,
+} from '#generators/metadata/constants.mjs';
+import { UNIST } from '#utils/queries/index.mjs';
+import { getRemark as remark } from '#utils/remark.mjs';
+import { relative } from '#utils/url.mjs';
+
+import { resolveTypeAnnotations } from './resolveTypes.mjs';
 import createNodeSlugger from './slugger.mjs';
 import { transformNodeToHeading } from './transformers.mjs';
 import {
@@ -18,14 +27,6 @@ import {
   visitTextWithUnixManualNode,
   visitYAML,
 } from './visitors.mjs';
-import { UNIST } from '../../../utils/queries/index.mjs';
-import { getRemark as remark } from '../../../utils/remark.mjs';
-import { relative } from '../../../utils/url.mjs';
-import {
-  DEPRECATION_HEADING_REGEX,
-  IGNORE_STABILITY_STEMS,
-} from '../constants.mjs';
-import { resolveTypeAnnotations } from './resolveTypes.mjs';
 
 /**
  * This generator generates a flattened list of metadata entries from a API doc
@@ -87,7 +88,7 @@ export const parseApiDoc = ({ path, tree, mdx = false }, typeMap) => {
   // Handles the normalisation URLs that reference to API doc files with .md extension
   visit(tree, UNIST.isMarkdownUrl, node => visitMarkdownLink(node));
 
-  // If the document has no headings but it has content, we add a fake heading to the top
+  // If the document has no headings but it has content, we add a fake heading to the top, it will not be rendered
   if (headingNodes.length === 0 && tree.children.length > 0) {
     tree.children.unshift(createTree('heading', { depth: 1 }, []));
   }

package/src/generators/metadata/utils/resolveTypes.mjs

@@ -1,9 +1,10 @@
 import { parseSync } from '@swc/wasm';
 import { visit } from 'unist-util-visit';
 
+import logger from '#logger/index.mjs';
+import { walk } from '#utils/swc.mjs';
+
 import { lookupTypeName, resolveTypeReference } from './transformers.mjs';
-import logger from '../../../logger/index.mjs';
-import { walk } from '../../../utils/swc.mjs';
 
 // `null` is a keyword kind in SWC, unlike most parsers which treat it as a literal type
 const KEYWORDS = new Set([

package/src/generators/metadata/utils/slugger.mjs

@@ -2,7 +2,7 @@
 
 import GitHubSlugger, { slug as defaultSlugFn } from 'github-slugger';
 
-import { DOC_API_SLUGS_REPLACEMENTS } from '../constants.mjs';
+import { DOC_API_SLUGS_REPLACEMENTS } from '#generators/metadata/constants.mjs';
 
 /**
  * Creates a modified version of the GitHub Slugger

package/src/generators/metadata/utils/transformers.mjs

@@ -2,11 +2,12 @@ import {
   DOC_MAN_BASE_URL,
   DOC_API_HEADING_TYPES,
   MODULE_QUALIFIED_NAME,
-} from '../constants.mjs';
+} from '#generators/metadata/constants.mjs';
+import BUILTIN_TYPE_MAP from '#generators/metadata/maps/builtin.json' with { type: 'json' };
+import MDN_TYPE_MAP from '#generators/metadata/maps/mdn.json' with { type: 'json' };
+import { transformNodesToString } from '#utils/unist.mjs';
+
 import { slug } from './slugger.mjs';
-import { transformNodesToString } from '../../../utils/unist.mjs';
-import BUILTIN_TYPE_MAP from '../maps/builtin.json' with { type: 'json' };
-import MDN_TYPE_MAP from '../maps/mdn.json' with { type: 'json' };
 
 /**
  * @param {string} text The inner text

package/src/generators/metadata/utils/visitors.mjs

@@ -2,11 +2,12 @@
 
 import { SKIP } from 'unist-util-visit';
 
+import { QUERIES } from '#utils/queries/index.mjs';
+import { getRemark as remark } from '#utils/remark.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
 import { transformUnixManualToLink } from './transformers.mjs';
 import { extractYamlContent, parseYAMLIntoMetadata } from './yaml.mjs';
-import { QUERIES } from '../../../utils/queries/index.mjs';
-import { getRemark as remark } from '../../../utils/remark.mjs';
-import { transformNodesToString } from '../../../utils/unist.mjs';
 
 /**
  * Updates a Markdown link into a HTML link for API docs

package/src/generators/metadata/utils/yaml.mjs

@@ -2,7 +2,7 @@
 
 import yaml from 'yaml';
 
-import { QUERIES } from '../../../utils/queries/index.mjs';
+import { QUERIES } from '#utils/queries/index.mjs';
 
 /**
  * Extracts raw YAML content from a node

package/src/logger/transports/console.mjs

@@ -2,8 +2,8 @@
 
 import { styleText } from 'node:util';
 
-import { prettifyLevel } from '../utils/colors.mjs';
-import { prettifyTimestamp } from '../utils/time.mjs';
+import { prettifyLevel } from '#logger/utils/colors.mjs';
+import { prettifyTimestamp } from '#logger/utils/time.mjs';
 
 /**
  * Logs a formatted message to stdout for human-friendly CLI output.

package/src/logger/transports/github.mjs

@@ -2,9 +2,9 @@
 
 import { debug, notice, warning, error } from '@actions/core';
 
-import { LogLevel } from '../constants.mjs';
-import { prettifyLevel } from '../utils/colors.mjs';
-import { prettifyTimestamp } from '../utils/time.mjs';
+import { LogLevel } from '#logger/constants.mjs';
+import { prettifyLevel } from '#logger/utils/colors.mjs';
+import { prettifyTimestamp } from '#logger/utils/time.mjs';
 
 const actions = {
   [LogLevel.debug]: debug,

package/src/logger/utils/colors.mjs

@@ -2,7 +2,7 @@
 
 import { styleText } from 'node:util';
 
-import { levelTags, levelToColorMap } from '../constants.mjs';
+import { levelTags, levelToColorMap } from '#logger/constants.mjs';
 
 /**
  * Returns a styled, uppercase log level tag for CLI output with color mapping

package/src/parsers/markdown.mjs

@@ -2,7 +2,7 @@
 
 import { coerce } from 'semver';
 
-import { loadFromURL } from '../utils/loaders.mjs';
+import { loadFromURL } from '#utils/loaders.mjs';
 
 // A ReGeX for retrieving Node.js version headers from the CHANGELOG.md
 const NODE_VERSIONS_REGEX = /\* \[Node\.js ([0-9.]+)\]\S+ (.*)\r?\n/g;

package/src/threading/chunk-worker.mjs

@@ -1,5 +1,5 @@
-import { loadGenerator } from '../generators/loader.mjs';
-import { setConfig } from '../utils/configuration/index.mjs';
+import { loadGenerator } from '#generators/loader.mjs';
+import { setConfig } from '#utils/configuration/index.mjs';
 
 /**
  * Processes a chunk of items using the specified generator's processChunk method.

package/src/threading/index.mjs

@@ -1,6 +1,6 @@
 import Piscina from 'piscina';
 
-import logger from '../logger/index.mjs';
+import logger from '#logger/index.mjs';
 
 const poolLogger = logger.child('WorkerPool');
 

package/src/threading/parallel.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import logger from '../logger/index.mjs';
+import logger from '#logger/index.mjs';
 
 const parallelLogger = logger.child('parallel');
 

package/src/utils/configuration/index.mjs

@@ -11,12 +11,12 @@ import { coerce } from 'semver';
 import {
   loadGenerators,
   resolveGeneratorSpecifier,
-} from '../../generators/loader.mjs';
-import logger from '../../logger/index.mjs';
-import { parseChangelog, parseIndex } from '../../parsers/markdown.mjs';
-import { enforceArray } from '../array.mjs';
-import { leftHandAssign } from '../generators.mjs';
-import { deepMerge } from '../misc.mjs';
+} from '#generators/loader.mjs';
+import logger from '#logger/index.mjs';
+import { parseChangelog, parseIndex } from '#parsers/markdown.mjs';
+import { enforceArray } from '#utils/array.mjs';
+import { leftHandAssign } from '#utils/generators.mjs';
+import { deepMerge } from '#utils/misc.mjs';
 
 const configExplorer = cosmiconfig('doc-kit');
 

package/src/utils/configuration/types.d.ts

@@ -1,5 +1,5 @@
 import type { SemVer } from 'semver';
-import type { ReleaseEntry } from '../../parsers/types';
+import type { ReleaseEntry } from '#parsers/types';
 
 export type Configuration = {
   global: GlobalConfiguration;

package/src/utils/generators.mjs

@@ -2,6 +2,36 @@
 
 import { coerce, major } from 'semver';
 
+import { transformNodeToString } from './unist.mjs';
+
+/**
+ * Retrieves the description of a given API doc entry. It first checks whether
+ * the entry has a llm_description property. If not, it extracts the first
+ * paragraph from the entry's content.
+ *
+ * @param {import('../generators/metadata/types').MetadataEntry} entry
+ * @returns {string}
+ */
+export const getEntryDescription = entry => {
+  if (entry.llm_description) {
+    return entry.llm_description.trim();
+  }
+
+  const descriptionNode = entry.content.children.find(
+    child => child.type === 'paragraph'
+  );
+
+  if (!descriptionNode) {
+    return '';
+  }
+
+  return (
+    transformNodeToString(descriptionNode)
+      // Remove newlines and extra spaces
+      .replace(/[\r\n]+/g, '')
+  );
+};
+
 /**
  * Groups all the API metadata nodes by module (`api` property) so that we can process each different file
  * based on the module it belongs to.

package/src/utils/inline.mjs

@@ -0,0 +1,82 @@
+'use strict';
+
+import rehypeStringify from 'rehype-stringify';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+import { u as createTree } from 'unist-builder';
+import { SKIP, visit } from 'unist-util-visit';
+
+import { lazy } from './misc.mjs';
+
+/**
+ * Renders a `root` as just its children, since content placed directly on one
+ * is otherwise rendered with a line break between each node, which surfaces as
+ * stray whitespace.
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('unist').Parent} node
+ */
+const inlineRoot = (state, node) => ({
+  type: 'root',
+  children: state.all(node),
+});
+
+/**
+ * Retrieves an instance of Remark configured to parse plain markdown, without
+ * the extensions that only apply to whole documents.
+ */
+const getInlineParser = lazy(() => unified().use(remarkParse));
+
+/**
+ * Retrieves an instance of Remark configured to render inline nodes as an HTML
+ * string. Raw HTML is dropped rather than passed through, since the result is
+ * inserted into the page as-is.
+ */
+const getInlineRenderer = lazy(() =>
+  unified()
+    .use(remarkRehype, { handlers: { root: inlineRoot } })
+    .use(rehypeStringify)
+);
+
+/**
+ * Parses a single line of markdown (a change description, a summary, ...) into
+ * the inline nodes it is made of.
+ *
+ * @param {string} markdown - The markdown to parse.
+ * @param {boolean} [dropLinks] - Replace links with their text? Anchors cannot
+ * nest, so content rendered inside a link must not contain one.
+ * @returns {Array<import('mdast').PhrasingContent>} The parsed nodes.
+ */
+export const parseInline = (markdown, dropLinks = false) => {
+  const tree = getInlineParser().parse(markdown);
+
+  if (dropLinks) {
+    visit(tree, 'link', (node, index, parent) => {
+      parent.children.splice(index, 1, ...node.children);
+
+      return [SKIP, index];
+    });
+  }
+
+  const [first] = tree.children;
+
+  // A single line of prose parses into one paragraph, which is dropped so the
+  // nodes can be rendered inline
+  return tree.children.length === 1 && first.type === 'paragraph'
+    ? first.children
+    : tree.children;
+};
+
+/**
+ * Renders inline nodes as an HTML string, for the places that hand rendered
+ * markup to a component through a data channel rather than as an AST.
+ *
+ * @param {Array<import('mdast').PhrasingContent>} nodes - The nodes to render.
+ * @returns {string} The rendered HTML.
+ */
+export const renderAsHTML = nodes => {
+  const renderer = getInlineRenderer();
+
+  return renderer.stringify(renderer.runSync(createTree('root', nodes)));
+};

package/src/utils/queries/index.mjs

@@ -1,7 +1,8 @@
 'use strict';
 
-import { transformNodesToString } from '../unist.mjs';
-import { isTypedList } from './utils.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
+import { isTypedListItem, isTypedList } from './utils.mjs';
 
 // This defines the actual REGEX Queries
 export const QUERIES = {
@@ -71,6 +72,12 @@ export const UNIST = {
    */
   isLooselyTypedList: list => Boolean(isTypedList(list)),
 
+  /**
+   * @param {import('@types/mdast').ListItem} item
+   * @returns {boolean}
+   */
+  isTypedListItem,
+
   /**
    * @param {import('@types/mdast').List} list
    * @returns {boolean}

package/src/utils/queries/utils.mjs

@@ -2,20 +2,17 @@ import { VALID_JAVASCRIPT_PROPERTY } from './constants.mjs';
 import { QUERIES } from './index.mjs';
 
 /**
- * @param {import('@types/mdast').List} list
+ * Inspects the first phrasing node of a paragraph and returns how confidently
+ * it looks like the start of a typed parameter.
+ *
+ * @param {import('@types/mdast').PhrasingContent | undefined} firstNode
  * @returns {0 | 1 | 2} confidence
  *
- * 0: This is not a typed list
- * 1: This is a loosely typed list
- * 2: This is a strongly typed list
+ * 0: Not a typed parameter
+ * 1: Loosely typed (inlineCode + valid property name)
+ * 2: Strongly typed (typed list starter or direct type annotation)
  */
-export const isTypedList = list => {
-  if (!list || list.type !== 'list') {
-    return 0;
-  }
-
-  const firstNode = list.children?.[0]?.children?.[0]?.children[0];
-
+const getTypedConfidence = firstNode => {
   if (!firstNode) {
     return 0;
   }
@@ -43,3 +40,30 @@ export const isTypedList = list => {
 
   return 0;
 };
+
+/**
+ * Checks whether a single list item looks like a typed parameter — i.e. it
+ * starts with a property name (`inlineCode`), a Returns/Extends/Type prefix,
+ * or a direct type annotation.
+ *
+ * @param {import('@types/mdast').ListItem} item
+ * @returns {boolean}
+ */
+export const isTypedListItem = item =>
+  Boolean(getTypedConfidence(item?.children?.[0]?.children?.[0]));
+
+/**
+ * @param {import('@types/mdast').List} list
+ * @returns {0 | 1 | 2} confidence
+ *
+ * 0: This is not a typed list
+ * 1: This is a loosely typed list
+ * 2: This is a strongly typed list
+ */
+export const isTypedList = list => {
+  if (!list || list.type !== 'list') {
+    return 0;
+  }
+
+  return getTypedConfidence(list.children?.[0]?.children?.[0]?.children?.[0]);
+};

package/src/utils/remark.mjs

@@ -13,18 +13,33 @@ import { lazy } from './misc.mjs';
 import { typeAnnotationToHast } from './type-annotations/hast.mjs';
 import remarkTypeAnnotations from './type-annotations/remark.mjs';
 
-// MDX node types that may appear in trees parsed by `getRemarkMdx`; the
-// rehype pipelines pass them through untouched.
-const passThrough = [
-  'element',
-  'mdxJsxTextElement',
-  'mdxJsxFlowElement',
-  'mdxJsxAttribute',
-  'mdxJsxAttributeValueExpression',
-  'mdxFlowExpression',
-  'mdxTextExpression',
-  'mdxjsEsm',
-];
+// Nodes the rehype pipelines pass through untouched.
+const passThrough = ['element'];
+
+/**
+ * Renders an MDX JSX element as just its children, so the surrounding prose
+ * still renders in HTML-string output.
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('unist').Parent} node
+ */
+const mdxElementToChildren = (state, node) => state.all(node);
+
+/**
+ * Drops a node from HTML-string output.
+ */
+const dropNode = () => undefined;
+
+// The HTML-string pipelines cannot render MDX nodes (rendering those is the
+// React generators' job): JSX elements degrade to their children so the
+// surrounding prose still renders, and expressions/ESM are dropped.
+const mdxToHastHandlers = {
+  mdxJsxTextElement: mdxElementToChildren,
+  mdxJsxFlowElement: mdxElementToChildren,
+  mdxFlowExpression: dropNode,
+  mdxTextExpression: dropNode,
+  mdxjsEsm: dropNode,
+};
 
 /**
  * Retrieves an instance of Remark configured to parse GFM (GitHub Flavored Markdown)
@@ -64,7 +79,7 @@ export const getRemarkRehype = lazy(() =>
     .use(remarkRehype, {
       allowDangerousHtml: true,
       passThrough,
-      handlers: { typeAnnotation: typeAnnotationToHast },
+      handlers: { typeAnnotation: typeAnnotationToHast, ...mdxToHastHandlers },
     })
     // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
     // and we trust the sources of the Markdown files
@@ -86,7 +101,7 @@ export const getRemarkRehypeWithShiki = lazy(() =>
       allowDangerousHtml: true,
       passThrough,
       // legacy-html gets the minimal (unhighlighted) type rendering
-      handlers: { typeAnnotation: typeAnnotationToHast },
+      handlers: { typeAnnotation: typeAnnotationToHast, ...mdxToHastHandlers },
     })
     // This is a custom ad-hoc within the Shiki Rehype plugin, used to highlight code
     // and transform them into HAST nodes

package/src/utils/signature/parseList.mjs

@@ -1,12 +1,13 @@
+import { leftHandAssign } from '#utils/generators.mjs';
+import { QUERIES, UNIST } from '#utils/queries/index.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
 import {
   DEFAULT_EXPRESSION,
   LEADING_HYPHEN,
   NAME_EXPRESSION,
 } from './constants.mjs';
 import parseSignature from './parseSignature.mjs';
-import { leftHandAssign } from '../generators.mjs';
-import { QUERIES, UNIST } from '../queries/index.mjs';
-import { transformNodesToString } from '../unist.mjs';
 
 /**
  * Extracts and removes a specific pattern from a text string while storing the result in a key of the `current` object.

package/src/utils/type-annotations/hast.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import { highlighter } from '../highlighter.mjs';
+import { highlighter } from '#utils/highlighter.mjs';
 
 const [lightTheme, darkTheme] = highlighter.shiki.getLoadedThemes();