fix: ignore and json gen improvements

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),

src/generators/ast-js/index.mjs

@@ -56,12 +56,16 @@ 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 toIgnore = globSync(ignore);
+
+    const files = globSync(input)
+      .filter(path => extname(path) === '.js')
+      .filter(path => !toIgnore.includes(path));
 
     // 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/index.mjs

@@ -55,14 +55,18 @@ export default {
   },
 
   /**
-   * Generates AST trees from markdown input files.
+   * Generates AST trees from markdown input fileAs.
    *
    * @param {Input} _ - Unused (top-level generator)
    * @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 toIgnore = globSync(ignore);
+
+    const files = globSync(input)
+      .filter(path => extname(path) === '.md')
+      .filter(path => !toIgnore.includes(path));
 
     // Parse markdown files in parallel using worker threads
     for await (const chunkResult of worker.stream(files, files)) {

src/generators/legacy-json-all/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].sort((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/utils/buildSection.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/types.d.ts

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