@doc-kit/core 1.1.0 → 1.2.1

package/src/generators/json/utils/entry.mjs

@@ -0,0 +1,87 @@
+'use strict';
+
+import { getEntryDescription } from '#utils/generators.mjs';
+import { splitTypedItems, UNIST } from '#utils/queries/index.mjs';
+import { extractListItem } from '#utils/signature/extractListItem.mjs';
+
+import { KINDS_WITH_TYPED_LIST } from '../constants.mjs';
+import { toChanges, toNumbers, toStability, toVersions } from './lifecycle.mjs';
+import { blocksToMarkdown, extractExamples } from './markdown.mjs';
+
+/**
+ * Whether a node is a stability index the metadata generator recognised.
+ *
+ * @param {import('mdast').RootContent} node
+ */
+const isStabilityIndex = node =>
+  node.type === 'blockquote' && node.data?.index !== undefined;
+
+/**
+ * An entry's body: its content without its heading and, when the entry
+ * carries one, its stability index.
+ *
+ * @param {import('../../metadata/types').MetadataEntry} entry
+ * @returns {Array<import('mdast').RootContent>}
+ */
+export const entryBody = entry =>
+  entry.content.children.filter(
+    node =>
+      !UNIST.isHeading(node) && !(entry.stability && isStabilityIndex(node))
+  );
+
+/**
+ * Lifts the leading typed items of the body's first typed list out of the
+ * body, for the kinds that turn them into data.
+ *
+ * @param {Array<import('mdast').RootContent>} body
+ * @param {string} kind The node's kind
+ * @returns {{ body: Array<import('mdast').RootContent>, items: Array<import('mdast').ListItem> }}
+ */
+export const takeTypedItems = (body, kind) => {
+  const index = KINDS_WITH_TYPED_LIST.has(kind)
+    ? body.findIndex(UNIST.isStronglyTypedList)
+    : -1;
+
+  if (index === -1) {
+    return { body, items: [] };
+  }
+
+  const list = body[index];
+  const { typed: items, rest } = splitTypedItems(list);
+
+  if (
+    kind === 'class' &&
+    !items.some(item => extractListItem(item).prefix === 'Extends')
+  ) {
+    return { body, items: [] };
+  }
+
+  return {
+    body: body.toSpliced(
+      index,
+      1,
+      ...(rest.length ? [{ ...list, children: rest }] : [])
+    ),
+    items,
+  };
+};
+
+/**
+ * Builds an entry's metadata and body.
+ *
+ * @param {import('../../metadata/types').MetadataEntry} entry
+ * @param {Array<import('mdast').RootContent>} body The entry's body, minus anything lifted out of it
+ * @returns {import('../types').Entry}
+ */
+export const buildEntry = (entry, body) => ({
+  title: entry.heading.data.text,
+  stability: toStability(entry.stability, entry.mdx),
+  added: toVersions(entry.added),
+  deprecated: toVersions(entry.deprecated),
+  removed: toVersions(entry.removed),
+  napiVersion: toNumbers(entry.napiVersion),
+  changes: toChanges(entry.changes),
+  description: blocksToMarkdown(body, entry.mdx),
+  summary: getEntryDescription(entry),
+  examples: extractExamples(body),
+});

package/src/generators/json/utils/lifecycle.mjs

@@ -0,0 +1,61 @@
+'use strict';
+
+import { enforceArray } from '#utils/array.mjs';
+import { removeStabilityPrefix } from '#utils/stability.mjs';
+
+import { blocksToMarkdown } from './markdown.mjs';
+
+/**
+ * Normalises a YAML version field
+ *
+ * @param {unknown} value
+ * @returns {Array<string>}
+ */
+export const toVersions = value =>
+  value == null ? [] : enforceArray(value).map(String);
+
+/**
+ * Normalises a YAML number field
+ *
+ * @param {unknown} value
+ * @returns {Array<number>}
+ */
+export const toNumbers = value =>
+  value == null ? [] : enforceArray(value).map(Number);
+
+/**
+ * Normalises a YAML `changes` list
+ *
+ * @param {unknown} changes
+ * @returns {Array<import('../types').Change>}
+ */
+export const toChanges = changes =>
+  enforceArray(changes ?? []).map(change => ({
+    versions: toVersions(change.version),
+    prUrl: change['pr-url'] == null ? null : String(change['pr-url']),
+    commit: change.commit == null ? null : String(change.commit),
+    description: String(change.description ?? '').trim(),
+  }));
+
+/**
+ * Builds an entry's stability index
+ *
+ * @param {import('../../metadata/types').StabilityNode | undefined} node
+ * @param {boolean} [mdx] Whether the node comes from an MDX document
+ * @returns {import('../types').Stability | null}
+ */
+export const toStability = (node, mdx) => {
+  if (!node) {
+    return null;
+  }
+
+  const { index, description } = node.data;
+  const body = removeStabilityPrefix(node);
+
+  return {
+    index: String(index),
+    description: body?.children.length
+      ? blocksToMarkdown(body.children, mdx)
+      : description,
+  };
+};

package/src/generators/json/utils/markdown.mjs

@@ -0,0 +1,57 @@
+'use strict';
+
+import { u as createTree } from 'unist-builder';
+import { visit } from 'unist-util-visit';
+
+import { getRemark, getRemarkMdx } from '#utils/remark.mjs';
+
+import { DISPLAY_NAME } from '../constants.mjs';
+
+/**
+ * Serialises block nodes back to Markdown.
+ *
+ * @param {Array<import('mdast').RootContent>} nodes
+ * @param {boolean} [mdx] Whether the nodes come from an MDX document
+ * @returns {string}
+ */
+export const blocksToMarkdown = (nodes, mdx = false) => {
+  if (nodes.length === 0) {
+    return '';
+  }
+
+  const processor = mdx ? getRemarkMdx() : getRemark();
+
+  return processor.stringify(createTree('root', nodes)).trim();
+};
+
+/**
+ * Serialises phrasing (inline) nodes back to Markdown.
+ *
+ * @param {Array<import('mdast').PhrasingContent>} nodes
+ * @param {boolean} [mdx] Whether the nodes come from an MDX document
+ * @returns {string}
+ */
+export const inlineToMarkdown = (nodes, mdx) =>
+  nodes.length === 0
+    ? ''
+    : blocksToMarkdown([createTree('paragraph', nodes)], mdx);
+
+/**
+ * Collects the fenced code blocks of a body
+ *
+ * @param {Array<import('mdast').RootContent>} nodes
+ * @returns {Array<import('../types').Example>}
+ */
+export const extractExamples = nodes => {
+  const examples = [];
+
+  visit(createTree('root', nodes), 'code', node => {
+    examples.push({
+      language: node.lang ?? null,
+      displayName: DISPLAY_NAME.exec(node.meta ?? '')?.[1] ?? null,
+      code: node.value,
+    });
+  });
+
+  return examples;
+};

package/src/generators/json/utils/node.mjs

@@ -0,0 +1,153 @@
+'use strict';
+
+import { toString } from 'mdast-util-to-string';
+
+import { transformNodeToHeading } from '#generators/metadata/utils/transformers.mjs';
+
+import {
+  CALLABLE_KINDS,
+  EXTENDS_CLAUSE,
+  KINDS,
+  SECTION_KIND,
+} from '../constants.mjs';
+import { buildEntry, entryBody, takeTypedItems } from './entry.mjs';
+import {
+  buildEventParameters,
+  buildExtends,
+  buildPropertyType,
+  buildSignature,
+} from './signature.mjs';
+
+/**
+ * Classifies an entry: the kind its heading documents and, when a `global`
+ * override replaced that classification, the scope it sets instead.
+ *
+ * @param {import('../../metadata/types').MetadataEntry} entry
+ * @returns {{ kind: string, scope?: 'global' }}
+ */
+export const classify = entry => {
+  const { type } = entry.heading.data;
+
+  if (type === 'global') {
+    const { type: structural } = transformNodeToHeading(entry.heading);
+
+    return { kind: KINDS[structural] ?? SECTION_KIND, scope: 'global' };
+  }
+
+  return { kind: KINDS[type] ?? SECTION_KIND };
+};
+
+/**
+ * The bare identifier an entry documents
+ *
+ * @param {import('../../metadata/types').MetadataEntry} entry
+ * @param {string} kind The entry's kind
+ * @returns {string}
+ */
+export const nodeName = (entry, kind) => {
+  if (typeof entry.name === 'string') {
+    return entry.name;
+  }
+
+  const { name } = entry.heading.data;
+
+  switch (kind) {
+    case SECTION_KIND:
+      return toString(entry.heading.children).trim();
+    case 'class':
+    case 'constructor':
+      // `http.Server`, `buffer.Blob`, `Foo extends Bar`
+      return name.split(EXTENDS_CLAUSE)[0].split('.').at(-1);
+    default:
+      return name;
+  }
+};
+
+/**
+ * The properties a node has on top of its entry, by kind.
+ *
+ * @param {string} kind
+ * @param {import('../../metadata/types').MetadataEntry} entry
+ * @param {Array<import('mdast').ListItem>} items The entry's typed list items
+ * @returns {{ properties: object, description?: string }}
+ */
+const kindProperties = (kind, entry, items) => {
+  if (CALLABLE_KINDS.has(kind)) {
+    return {
+      properties: {
+        signature: buildSignature(entry.heading, items, entry.mdx),
+      },
+    };
+  }
+
+  switch (kind) {
+    case 'class':
+      return { properties: { extends: buildExtends(entry.heading, items) } };
+    case 'property': {
+      const {
+        type,
+        default: value,
+        description,
+      } = buildPropertyType(items, entry.mdx);
+
+      return { properties: { type, default: value }, description };
+    }
+    case 'event':
+      return {
+        properties: { parameters: buildEventParameters(items, entry.mdx) },
+      };
+    default:
+      return { properties: {} };
+  }
+};
+
+/**
+ * Builds a node and its subtree from a hierarchized entry.
+ *
+ * @param {import('#utils/hierarchy.mjs').HierarchizedEntry} node
+ * @param {'module' | 'global'} scope The document's scope
+ * @returns {import('../types').Node}
+ */
+export const buildNode = ({ entry, children }, scope) => {
+  const { kind, scope: entryScope = scope } = classify(entry);
+  const { body, items } = takeTypedItems(entryBody(entry), kind);
+  const { properties, description: typeDescription } = kindProperties(
+    kind,
+    entry,
+    items
+  );
+
+  const {
+    title,
+    stability,
+    added,
+    deprecated,
+    removed,
+    napiVersion,
+    changes,
+    description,
+    summary,
+    examples,
+  } = buildEntry(entry, body);
+
+  return {
+    kind,
+    id: entry.heading.data.slug,
+    name: nodeName(entry, kind),
+    title,
+    scope: entryScope,
+    overloadOf: entry.heading.data.overloadOf ?? null,
+    stability,
+    added,
+    deprecated,
+    removed,
+    napiVersion,
+    changes,
+    ...properties,
+    // A property's type item may describe it; that comes first
+    description: [typeDescription, description].filter(Boolean).join('\n\n'),
+    summary,
+    examples,
+    children: children.map(child => buildNode(child, scope)),
+  };
+};

package/src/generators/json/utils/schema.mjs

@@ -0,0 +1,15 @@
+'use strict';
+
+import { populate } from '#utils/configuration/templates.mjs';
+
+import { SCHEMA_VERSION } from '../constants.mjs';
+
+/**
+ * The `$schema` URL a generator's output carries: its `schemaURL` option with
+ * the schema version filled in.
+ *
+ * @param {{ schemaURL: string }} config The generator's configuration
+ * @returns {string}
+ */
+export const resolveSchemaURL = config =>
+  populate(config.schemaURL, { ...config, schemaVersion: SCHEMA_VERSION });

package/src/generators/json/utils/signature.mjs

@@ -0,0 +1,185 @@
+'use strict';
+
+import { u as createTree } from 'unist-builder';
+
+import {
+  extractListItem,
+  removeDefault,
+} from '#utils/signature/extractListItem.mjs';
+import parseSignature from '#utils/signature/parseSignature.mjs';
+
+import {
+  CODE_SPAN,
+  DECLARED_DEFAULT,
+  EXTENDS_CLAUSE,
+  REST_MARKER,
+} from '../constants.mjs';
+import { blocksToMarkdown } from './markdown.mjs';
+import { plainType, toType } from './types.mjs';
+
+// What a parameter declared in a heading but absent from the typed list has
+const EMPTY_ITEM = {
+  name: undefined,
+  prefix: undefined,
+  annotation: undefined,
+  text: [],
+  blocks: [],
+  default: undefined,
+  items: [],
+};
+
+/**
+ * The Markdown of a list item's description
+ *
+ * @param {import('#utils/signature/extractListItem.mjs').ExtractedListItem} item
+ * @param {boolean} [mdx] Whether the item comes from an MDX document
+ * @returns {string}
+ */
+export const itemDescription = ({ text, blocks }, mdx) => {
+  const description = removeDefault(text);
+
+  return blocksToMarkdown(
+    [
+      ...(description.length ? [createTree('paragraph', description)] : []),
+      ...blocks,
+    ],
+    mdx
+  );
+};
+
+/**
+ * A default value as authored, without the code span around it.
+ *
+ * @param {string | undefined} value
+ * @returns {string | null}
+ */
+const toDefault = value =>
+  value === undefined
+    ? null
+    : value.replace(DECLARED_DEFAULT, '').replace(CODE_SPAN, '$1');
+
+/**
+ * Builds a parameter from its list item and, for a callable, its declaration
+ * in the heading.
+ *
+ * @param {import('#utils/signature/extractListItem.mjs').ExtractedListItem} item
+ * @param {import('#utils/signature/types').Parameter} [declared] The heading's declaration
+ * @param {boolean} [mdx] Whether the item comes from an MDX document
+ * @returns {import('../types').Parameter}
+ */
+export const toParameter = (item, declared = {}, mdx) => {
+  const name = declared.name ?? item.name ?? '';
+  const value = item.default ?? declared.default;
+
+  return {
+    name: name.replace(REST_MARKER, ''),
+    type: toType(item.annotation),
+    description: itemDescription(item, mdx),
+    default: toDefault(value),
+    optional: Boolean(declared.optional) || value !== undefined,
+    rest: REST_MARKER.test(name),
+    properties: item.items.map(nested =>
+      toParameter(extractListItem(nested), undefined, mdx)
+    ),
+  };
+};
+
+/**
+ * Wraps an extracted item the way `parseSignature` matches parameters
+ * (by name, with the nested items as `options`)
+ *
+ * @param {import('#utils/signature/extractListItem.mjs').ExtractedListItem} item
+ */
+const toMarkdownParameter = item => ({
+  name: item.prefix
+    ? item.prefix === 'Returns'
+      ? 'return'
+      : item.prefix.toLowerCase()
+    : item.name,
+  options: item.items.map(nested =>
+    toMarkdownParameter(extractListItem(nested))
+  ),
+  item,
+});
+
+/**
+ * Builds a return value from its `Returns:` item.
+ *
+ * @param {import('#utils/signature/extractListItem.mjs').ExtractedListItem} item
+ * @param {boolean} [mdx] Whether the item comes from an MDX document
+ * @returns {import('../types').Return}
+ */
+const toReturn = (item, mdx) => ({
+  type: toType(item.annotation),
+  description: itemDescription(item, mdx),
+});
+
+/**
+ * Builds the parameters a callable heading declares
+ *
+ * @param {import('../../metadata/types').HeadingNode} heading
+ * @param {Array<import('mdast').ListItem>} items The typed list's items
+ * @param {boolean} [mdx] Whether the items come from an MDX document
+ * @returns {import('../types').Signature}
+ */
+export const buildSignature = (heading, items, mdx) => {
+  const signature = parseSignature(
+    heading.data.text,
+    items.map(item => toMarkdownParameter(extractListItem(item)))
+  );
+
+  return {
+    parameters: signature.params.map(declared =>
+      toParameter(declared.item ?? EMPTY_ITEM, declared, mdx)
+    ),
+    returns: signature.return ? toReturn(signature.return.item, mdx) : null,
+  };
+};
+
+/**
+ * @param {import('../../metadata/types').HeadingNode} heading
+ * @param {Array<import('mdast').ListItem>} items The typed list's items
+ * @returns {import('../types').Type | null}
+ */
+export const buildExtends = (heading, items) => {
+  const item = items
+    .map(extractListItem)
+    .find(({ prefix }) => prefix === 'Extends');
+
+  if (item) {
+    return toType(item.annotation);
+  }
+
+  const [, base] = heading.data.name.split(EXTENDS_CLAUSE);
+
+  return base ? plainType(base) : null;
+};
+
+/**
+ * A property's basic metadata
+ *
+ * @param {Array<import('mdast').ListItem>} items The typed list's items
+ * @param {boolean} [mdx] Whether the items come from an MDX document
+ * @returns {{ type: import('../types').Type | null, default: string | null, description: string }}
+ */
+export const buildPropertyType = (items, mdx) => {
+  const [item] = items.map(extractListItem);
+
+  return item
+    ? {
+        type: toType(item.annotation),
+        default: toDefault(item.default),
+        description: itemDescription(item, mdx),
+      }
+    : { type: null, default: null, description: '' };
+};
+
+/**
+ * The arguments an event's listeners receive.
+ *
+ * @param {Array<import('mdast').ListItem>} items The typed list's items
+ * @param {boolean} [mdx] Whether the items come from an MDX document
+ * @returns {Array<import('../types').Parameter>}
+ */
+export const buildEventParameters = (items, mdx) =>
+  items.map(item => toParameter(extractListItem(item), undefined, mdx));

package/src/generators/json/utils/types.mjs

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Builds a type from a resolved `typeAnnotation` node.
+ *
+ * @param {import('mdast').Node | undefined} node
+ * @returns {import('../types').Type | null}
+ */
+export const toType = node =>
+  node
+    ? {
+        text: node.value,
+        links: (node.data?.links ?? []).map(({ text, href, start, end }) => ({
+          name: text,
+          href,
+          start,
+          end,
+        })),
+      }
+    : null;
+
+/**
+ * Builds a type from bare text, with nothing resolved.
+ *
+ * @param {string} text
+ * @returns {import('../types').Type}
+ */
+export const plainType = text => ({ text, links: [] });

package/src/generators/json-all/README.md

@@ -0,0 +1,31 @@
+# `json-all` Generator
+
+The `json-all` generator bundles the documents of the [`json`](./json.md)
+generator into a single `all.json` file.
+
+```sh
+npx @doc-kit/cli generate -t json-all -i "doc/api/*.md" -o out --index doc/api/index.md
+```
+
+```json
+{
+  "$schema": "https://doc-kit.nodejs.org/schemas/api-doc-all/1.0.0.json",
+  "documents": []
+}
+```
+
+`documents` holds every document in the order of the configured `index`,
+then the rest by `id`. The bundle's schema, shipped as
+`@doc-kit/core/generators/json-all/schema.json`, refers to the `json`
+generator's schema for the documents.
+
+## Configuring
+
+- `output` {string} The directory where `all.json` will be written.
+- `minify` {boolean} Whether to minify the output. Inherited from `global`.
+  **Default:** `true`.
+- `index` {Array} The `{ api }` objects defining the document order. Inherited
+  from `global`.
+- `schemaURL` {string} Where the bundle's schema is published.
+  `{schemaVersion}` is filled in. **Default:**
+  `'https://doc-kit.nodejs.org/schemas/api-doc-all/{schemaVersion}.json'`.

package/src/generators/json-all/constants.mjs

@@ -0,0 +1,5 @@
+'use strict';
+
+// Where a version of the bundle's schema is published.
+export const SCHEMA_URL =
+  'https://doc-kit.nodejs.org/schemas/api-doc-all/{schemaVersion}.json';

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

@@ -0,0 +1,35 @@
+'use strict';
+
+import { join } from 'node:path';
+
+import getConfig from '#utils/configuration/index.mjs';
+import { writeJSON } from '#utils/file.mjs';
+
+import { resolveSchemaURL } from '../json/utils/schema.mjs';
+
+/**
+ * Bundles the `json` generator's documents into one `all.json` file.
+ *
+ * @type {import('./types').Generator['generate']}
+ */
+export async function generate(input) {
+  const config = getConfig('json-all');
+
+  // Documents follow the configured index; the rest go after it, by id
+  const order = new Map(config.index?.map(({ api }, i) => [api, i]));
+
+  const documents = input.toSorted(
+    (a, b) =>
+      (order.get(a.id) ?? Infinity) - (order.get(b.id) ?? Infinity) ||
+      a.id.localeCompare(b.id)
+  );
+
+  /** @type {import('./types').Bundle} */
+  const bundle = { $schema: resolveSchemaURL(config), documents };
+
+  if (config.output) {
+    await writeJSON(join(config.output, 'all.json'), bundle, config.minify);
+  }
+
+  return bundle;
+}

package/src/generators/json-all/index.mjs

@@ -0,0 +1,25 @@
+'use strict';
+
+import { SCHEMA_URL } from './constants.mjs';
+import { generate } from './generate.mjs';
+
+/**
+ * This generator bundles the documents of the `json` generator into a single
+ * `all.json` file
+ *
+ * @type {import('./types').Generator}
+ */
+export default {
+  name: 'json-all',
+
+  description:
+    'Bundles the documents of the `json` generator into a single `all.json` file',
+
+  dependsOn: '@doc-kit/core/json',
+
+  defaultConfiguration: {
+    schemaURL: SCHEMA_URL,
+  },
+
+  generate,
+};