feat(metadata): new meta format

docs/generators.md

@@ -137,7 +137,7 @@ export async function generate(input, worker) {
 
 /**
  * Transform metadata entries to MyFormat
- * @param {Array<ApiDocMetadataEntry>} entries
+ * @param {Array<MetadataEntry>} entries
  * @param {import('semver').SemVer} version
  * @returns {string}
  */

src/generators/addon-verify/types.d.ts

@@ -1,4 +1,6 @@
+import type { MetadataEntry } from '../metadata/types';
+
 export type Generator = GeneratorMetadata<
   {},
-  Generate<Array<ApiDocMetadataEntry>, Promise<Record<string, string>>>
+  Generate<Array<MetadataEntry>, Promise<Record<string, string>>>
 >;

src/generators/ast/constants.mjs

@@ -0,0 +1 @@
+export const STABILITY_INDEX_URL = 'documentation.html#stability-index';

src/generators/ast/generate.mjs

@@ -6,12 +6,11 @@ import { extname } from 'node:path';
 import { globSync } from 'tinyglobby';
 import { VFile } from 'vfile';
 
+import { STABILITY_INDEX_URL } from './constants.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
-import createQueries from '../../utils/queries/index.mjs';
+import { QUERIES } from '../../utils/queries/index.mjs';
 import { getRemark } from '../../utils/remark.mjs';
 
-const { updateStabilityPrefixToLink } = createQueries();
-
 const remarkProcessor = getRemark();
 
 /**
@@ -26,9 +25,14 @@ export async function processChunk(inputSlice, itemIndices) {
   const results = [];
 
   for (const path of filePaths) {
-    const vfile = new VFile({ path, value: await readFile(path, 'utf-8') });
-
-    updateStabilityPrefixToLink(vfile);
+    const content = await readFile(path, 'utf-8');
+    const vfile = new VFile({
+      path,
+      value: content.replace(
+        QUERIES.stabilityIndexPrefix,
+        match => `[${match}](${STABILITY_INDEX_URL})`
+      ),
+    });
 
     results.push({
       tree: remarkProcessor.parse(vfile),

src/generators/json-simple/generate.mjs

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 import { remove } from 'unist-util-remove';
 
 import getConfig from '../../utils/configuration/index.mjs';
-import createQueries from '../../utils/queries/index.mjs';
+import { UNIST } from '../../utils/queries/index.mjs';
 
 /**
  * Generates the simplified JSON version of the API docs
@@ -16,17 +16,14 @@ import createQueries from '../../utils/queries/index.mjs';
 export async function generate(input) {
   const config = getConfig('json-simple');
 
-  // Iterates the input (ApiDocMetadataEntry) and performs a few changes
+  // Iterates the input (MetadataEntry) and performs a few changes
   const mappedInput = input.map(node => {
     // Deep clones the content nodes to avoid affecting upstream nodes
     const content = JSON.parse(JSON.stringify(node.content));
 
     // Removes numerous nodes from the content that should not be on the "body"
     // of the JSON version of the API docs as they are already represented in the metadata
-    remove(content, [
-      createQueries.UNIST.isStabilityNode,
-      createQueries.UNIST.isHeading,
-    ]);
+    remove(content, [UNIST.isStabilityNode, UNIST.isHeading]);
 
     return { ...node, content };
   });

src/generators/json-simple/types.d.ts

@@ -1,4 +1,6 @@
+import type { MetadataEntry } from '../metadata/types';
+
 export type Generator = GeneratorMetadata<
   {},
-  Generate<Array<ApiDocMetadataEntry>, Promise<Array<ApiDocMetadataEntry>>>
+  Generate<Array<MetadataEntry>, Promise<Array<MetadataEntry>>>
 >;

src/generators/jsx-ast/constants.mjs

@@ -43,9 +43,9 @@ export const TAG_TRANSFORMS = {
  * API lifecycle change labels
  */
 export const LIFECYCLE_LABELS = {
-  added_in: 'Added in',
-  deprecated_in: 'Deprecated in',
-  removed_in: 'Removed in',
+  added: 'Added in',
+  deprecated: 'Deprecated in',
+  removed: 'Removed in',
   introduced_in: 'Introduced in',
 };
 

src/generators/jsx-ast/generate.mjs

@@ -46,6 +46,7 @@ export async function* generate(input, worker) {
   const config = getConfig('jsx-ast');
 
   const groupedModules = groupNodesByModule(input);
+
   const headNodes = getSortedHeadNodes(input);
 
   // Pre-compute docPages once in main thread

src/generators/jsx-ast/types.d.ts

@@ -1,10 +1,11 @@
+import type { MetadataEntry } from '../metadata/types';
 import type { JSXContent } from './utils/buildContent.mjs';
 
 export type Generator = GeneratorMetadata<
   {},
-  Generate<Array<ApiDocMetadataEntry>, AsyncGenerator<JSXContent>>,
+  Generate<Array<MetadataEntry>, AsyncGenerator<JSXContent>>,
   ProcessChunk<
-    { head: ApiDocMetadataEntry; entries: Array<ApiDocMetadataEntry> },
+    { head: MetadataEntry; entries: Array<MetadataEntry> },
     JSXContent,
     Array<[string, string]>
   >

src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs

@@ -70,7 +70,7 @@ describe('buildMetaBarProps', () => {
   it('creates meta bar properties from entries', () => {
     const head = {
       api: 'fs',
-      added_in: 'v1.0.0',
+      added: 'v1.0.0',
     };
 
     const entries = [
@@ -106,7 +106,7 @@ describe('buildMetaBarProps', () => {
     assert.ok(Array.isArray(result.headings));
   });
 
-  it('falls back to introduced_in if added_in is missing', () => {
+  it('falls back to introduced_in if added is missing', () => {
     const head = {
       api: 'fs',
       introduced_in: 'v2.0.0',

src/generators/jsx-ast/utils/buildBarProps.mjs

@@ -19,7 +19,7 @@ import { TOC_MAX_HEADING_DEPTH } from '../constants.mjs';
 /**
  * Generate a combined plain text string from all MDAST entries for estimating reading time.
  *
- * @param {Array<ApiDocMetadataEntry>} entries - API documentation entries
+ * @param {Array<import('../../metadata/types').MetadataEntry>} entries - API documentation entries
  */
 export const extractTextContent = entries => {
   return entries.reduce((acc, entry) => {
@@ -32,17 +32,17 @@ export const extractTextContent = entries => {
 
 /**
  * Determines if an entry should be included in the Table of Contents.
- * @param {ApiDocMetadataEntry} entry
+ * @param {import('../../metadata/types').MetadataEntry} entry
  */
 const shouldIncludeEntryInToC = ({ heading }) =>
   // Only include headings with text,
   heading?.data?.text.length &&
   // and whose depth <= the maximum allowed.
-  heading?.data?.depth <= TOC_MAX_HEADING_DEPTH;
+  heading?.depth <= TOC_MAX_HEADING_DEPTH;
 
 /**
  * Extracts and formats heading information from an API documentation entry.
- * @param {ApiDocMetadataEntry} entry
+ * @param {import('../../metadata/types').MetadataEntry} entry
  */
 const extractHeading = entry => {
   const data = entry.heading.data;
@@ -72,7 +72,7 @@ const extractHeading = entry => {
   return {
     depth: entry.heading.depth,
     value: heading,
-    stability: parseInt(entry.stability?.children[0]?.data.index ?? 2),
+    stability: parseInt(entry.stability?.data.index ?? 2),
     slug: data.slug,
     data: { id: data.slug, type: data.type },
   };
@@ -81,23 +81,23 @@ const extractHeading = entry => {
 /**
  * Build the list of heading metadata for sidebar navigation.
  *
- * @param {Array<ApiDocMetadataEntry>} entries - All API metadata entries
+ * @param {Array<import('../../metadata/types').MetadataEntry>} entries - All API metadata entries
  */
 export const extractHeadings = entries =>
   entries.filter(shouldIncludeEntryInToC).map(extractHeading);
 
 /**
  * Builds metadata for the meta bar (right panel).
  *
- * @param {ApiDocMetadataEntry} head - Main API metadata entry (used as reference point)
- * @param {Array<ApiDocMetadataEntry>} entries - All documentation entries for a given API item
+ * @param {import('../../metadata/types').MetadataEntry} head - Main API metadata entry (used as reference point)
+ * @param {Array<import('../../metadata/types').MetadataEntry>} entries - All documentation entries for a given API item
  */
 export const buildMetaBarProps = (head, entries) => {
   const config = getConfig('jsx-ast');
 
   return {
     headings: extractHeadings(entries),
-    addedIn: head.introduced_in || head.added_in || '',
+    addedIn: head.added || head.introduced_in || '',
     readingTime: readingTime(extractTextContent(entries)).text,
     viewAs: [
       ['JSON', `${head.api}.json`],
@@ -110,7 +110,7 @@ export const buildMetaBarProps = (head, entries) => {
 /**
  * Converts a compatible version entry into a version label and link.
  *
- * @param {Array<ApiDocReleaseEntry>} compatibleVersions - Compatible versions
+ * @param {Array<import('../../../parsers/types').ReleaseEntry>} compatibleVersions - Compatible versions
  * @param {string} api - API identifier (used in link)
  */
 export const formatVersionOptions = (compatibleVersions, api) => {
@@ -140,7 +140,7 @@ export const formatVersionOptions = (compatibleVersions, api) => {
 /**
  * Builds metadata for the sidebar (left panel).
  *
- * @param {ApiDocMetadataEntry} entry - Current documentation entry
+ * @param {import('../../metadata/types').MetadataEntry} entry - Current documentation entry
  * @param {Array<[string, string]>} docPages - Available doc pages for sidebar navigation
  */
 export const buildSideBarProps = (entry, docPages) => {