chore: attempt to improve hdyration (#516)

Author: ovflowd

bin/commands/generate.mjs

@@ -148,6 +148,7 @@ export default {
     await runGenerators({
       generators: opts.target,
       input: opts.input,
+      ignore: opts.ignore,
       output: opts.output && resolve(opts.output),
       version: coerce(opts.version),
       releases: await parseChangelog(opts.changelog),

npm-shrinkwrap.json

@@ -61,7 +61,7 @@
     "lightningcss": "^1.30.2",
     "mdast-util-slice-markdown": "^2.0.1",
     "piscina": "^5.1.4",
-    "preact": "^10.28.0",
+    "preact": "^11.0.0-beta.0",
     "preact-render-to-string": "^6.6.3",
     "reading-time": "^1.5.0",
     "recma-jsx": "^1.0.1",

package.json

@@ -56,12 +56,12 @@ export default {
    * @param {Partial<GeneratorOptions>} options
    * @returns {AsyncGenerator<Output>}
    */
-  async *generate(_, { input = [], worker }) {
-    const source = globSync(input).filter(path => extname(path) === '.js');
+  async *generate(_, { input = [], ignore, worker }) {
+    const files = globSync(input, { ignore }).filter(p => extname(p) === '.js');
 
     // Parse the Javascript sources into ASTs in parallel using worker threads
     // source is both the items list and the fullInput since we use sliceInput
-    for await (const chunkResult of worker.stream(source, source)) {
+    for await (const chunkResult of worker.stream(files, files)) {
       yield chunkResult;
     }
   },

src/generators/ast-js/index.mjs

@@ -61,8 +61,8 @@ export default {
    * @param {Partial<GeneratorOptions>} options
    * @returns {AsyncGenerator<Output>}
    */
-  async *generate(_, { input = [], worker }) {
-    const files = globSync(input).filter(path => extname(path) === '.md');
+  async *generate(_, { input = [], ignore, worker }) {
+    const files = globSync(input, { ignore }).filter(p => extname(p) === '.md');
 
     // Parse markdown files in parallel using worker threads
     for await (const chunkResult of worker.stream(files, files)) {

src/generators/ast/index.mjs

@@ -33,4 +33,4 @@ const headingSortFn = (a, b) => {
  * @returns {Array<ApiDocMetadataEntry>}
  */
 export const getSortedHeadNodes = entries =>
-  entries.filter(node => node.heading.depth === 1).sort(headingSortFn);
+  entries.filter(node => node.heading.depth === 1).toSorted(headingSortFn);

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

@@ -113,7 +113,9 @@ export default {
 
     const headNodes = input
       .filter(node => node.heading.depth === 1)
-      .sort((a, b) => a.heading.data.name.localeCompare(b.heading.data.name));
+      .toSorted((a, b) =>
+        a.heading.data.name.localeCompare(b.heading.data.name)
+      );
 
     const indexOfFiles = index
       ? index.map(({ api, section }) => ({ api, heading: getHeading(section) }))

src/generators/legacy-html/index.mjs

@@ -29,7 +29,7 @@ export default {
    * @param {Partial<GeneratorOptions>} options
    * @returns {Promise<Output>}
    */
-  async generate(input, { output }) {
+  async generate(input, { output, index }) {
     /**
      * The consolidated output object that will contain
      * combined data from all sections in the input.
@@ -49,8 +49,26 @@ export default {
      */
     const propertiesToCopy = Object.keys(generatedValue);
 
+    // Create a map of api name to index position for sorting
+    const indexOrder = new Map(
+      index?.map(({ api }, position) => [`doc/api/${api}.md`, position]) ?? []
+    );
+
+    // Sort input by index order (documents not in index go to the end)
+    const sortedInput = input.toSorted((a, b) => {
+      const aOrder = indexOrder.get(a.source) ?? Infinity;
+      const bOrder = indexOrder.get(b.source) ?? Infinity;
+
+      return aOrder - bOrder;
+    });
+
     // Aggregate all sections into the output
-    for (const section of input) {
+    for (const section of sortedInput) {
+      // Skip index.json - it has no useful content, just navigation
+      if (section.api === 'index') {
+        continue;
+      }
+
       for (const property of propertiesToCopy) {
         const items = section[property];
 

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

@@ -45,12 +45,14 @@ export const createSectionBuilder = () => {
     removed_in = [],
     changes,
   }) => {
-    const meta = { changes };
+    const meta = {};
 
     if (added_in?.length) {
       meta.added = enforceArray(added_in);
     }
 
+    meta.changes = changes;
+
     if (n_api_version?.length) {
       meta.napiVersion = enforceArray(n_api_version);
     }
@@ -81,8 +83,8 @@ export const createSectionBuilder = () => {
     const section = {
       textRaw: transformNodesToString(head.children),
       name: head.data.name,
-      type: head.data.type,
       introduced_in: entry.introduced_in,
+      type: head.data.type,
     };
 
     const meta = createMeta(entry);
@@ -135,8 +137,11 @@ export const createSectionBuilder = () => {
    * @param {import('../../types.d.ts').NodeWithData} heading - The heading node of the section.
    */
   const addAdditionalMetadata = (section, parent, heading) => {
-    if (!section.type) {
+    if (!section.type || section.type === 'module') {
       section.name = section.textRaw.toLowerCase().trim().replace(/\s+/g, '_');
+    }
+
+    if (!section.type) {
       section.displayName = heading.data.name;
       section.type = parent.type === 'misc' ? 'misc' : 'module';
     }

src/generators/legacy-json/utils/buildSection.mjs

@@ -37,6 +37,9 @@ declare global {
     // be a glob when passed to a generator.
     input: string | string[];
 
+    // The path or glob patterns used to ignore files from the input source files.
+    ignore?: string | string[];
+
     // The path used to output generated files, this is to be considered
     // the base path that any generator will use for generating files
     // This parameter accepts globs but when passed to generators will contain