feat(metadata): new meta format (#651)

Author: avivkeller

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/__tests__/metadata.test.mjs

@@ -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/addon-verify/types.d.ts

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

src/generators/ast/constants.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/ast/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/generate.mjs

@@ -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/json-simple/types.d.ts

@@ -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/constants.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/generate.mjs

@@ -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]>
   >