feat(json): add legacy JSON generator

Co-Authored-By: flakey5 <[email protected]>

Author: flakey5

README.md

@@ -39,6 +39,6 @@ Options:
   -o, --output <path>        Specify the relative or absolute output directory
   -v, --version <semver>     Specify the target version of Node.js, semver compliant (default: "v22.6.0")
   -c, --changelog <url>      Specify the path (file: or https://) to the CHANGELOG.md file (default: "https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md")
-  -t, --target [mode...]     Set the processing target modes (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page")
+  -t, --target [mode...]     Set the processing target modes (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page", "legacy-json", "legacy-json-all")
   -h, --help                 display help for command
 ```

shiki.config.mjs

@@ -30,7 +30,7 @@ export default {
   // Only register the languages that the API docs use
   // and override the JavaScript language with the aliases
   langs: [
-    { ...javaScriptLanguage[0], aliases: ['mjs', 'cjs', 'js'] },
+    ...httpLanguage,
     ...jsonLanguage,
     ...typeScriptLanguage,
     ...shellScriptLanguage,
@@ -40,7 +40,7 @@ export default {
     ...diffLanguage,
     ...cLanguage,
     ...cPlusPlusLanguage,
-    ...httpLanguage,
     ...coffeeScriptLanguage,
+    { ...javaScriptLanguage[0], aliases: ['mjs', 'cjs', 'js'] },
   ],
 };

src/constants.mjs

@@ -58,24 +58,31 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
 // is a specific type of API Doc entry (e.g., Event, Class, Method, etc)
 // and to extract the inner content of said Heading to be used as the API doc entry name
 export const DOC_API_HEADING_TYPES = [
-  { type: 'method', regex: /^`?([A-Z]\w+(?:\.[A-Z]\w+)*\.\w+)\([^)]*\)`?$/i },
+  {
+    type: 'method',
+    regex:
+      /^`?(?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\])\.?)*((?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\]))\([^)]*\)`?$/i,
+  },
   { type: 'event', regex: /^Event: +`?['"]?([^'"]+)['"]?`?$/i },
   {
     type: 'class',
     regex:
-      /^Class: +`?([A-Z]\w+(?:\.[A-Z]\w+)*(?: +extends +[A-Z]\w+(?:\.[A-Z]\w+)*)?)`?$/i,
+      /^class: +`?((?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\])\.?)*[A-Z]\w+)(?: +extends +(?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\])\.?)*[A-Z]\w+)?`?$/i,
   },
   {
     type: 'ctor',
-    regex: /^(?:Constructor: +)?`?new +([A-Z]\w+(?:\.[A-Z]\w+)*)\([^)]*\)`?$/i,
+    regex:
+      /^(?:Constructor: +)?`?new +((?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\])\.?)*[A-Z]\w+)\([^)]*\)`?$/i,
   },
   {
     type: 'classMethod',
-    regex: /^Static method: +`?([A-Z]\w+(?:\.[A-Z]\w+)*\.\w+)\([^)]*\)`?$/i,
+    regex:
+      /^Static method: +`?(?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\])\.?)*((?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\]))\([^)]*\)`?$/i,
   },
   {
     type: 'property',
-    regex: /^(?:Class property: +)?`?([A-Z]\w+(?:\.[A-Z]\w+)*\.\w+)`?$/i,
+    regex:
+      /^(?:Class property: +)?`?(?:(?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\])\.?)+((?:(?:(?:\\?_)+|\b)\w+\b|\\?\[[\w.]+\\?\]))`?$/i,
   },
 ];
 

src/generators/index.mjs

@@ -4,10 +4,14 @@ import jsonSimple from './json-simple/index.mjs';
 import legacyHtml from './legacy-html/index.mjs';
 import legacyHtmlAll from './legacy-html-all/index.mjs';
 import manPage from './man-page/index.mjs';
+import legacyJson from './legacy-json/index.mjs';
+import legacyJsonAll from './legacy-json-all/index.mjs';
 
 export default {
   'json-simple': jsonSimple,
   'legacy-html': legacyHtml,
   'legacy-html-all': legacyHtmlAll,
   'man-page': manPage,
+  'legacy-json': legacyJson,
+  'legacy-json-all': legacyJsonAll,
 };

src/generators/legacy-html/assets/api.js

@@ -165,8 +165,6 @@
 
         let code = '';
 
-        console.log(parentNode);
-
         if (flavorToggle) {
           if (flavorToggle.checked) {
             code = parentNode.querySelector('.mjs').textContent;

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

@@ -0,0 +1,58 @@
+'use strict';
+
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @typedef {Array<import('../legacy-json/types.d.ts').Section>} Input
+ *
+ * @type {import('../types.d.ts').GeneratorMetadata<Input, import('./types.d.ts').Output>}
+ */
+export default {
+  name: 'legacy-json-all',
+
+  version: '1.0.0',
+
+  description:
+    'Generates the `all.json` file from the `legacy-json` generator, which includes all the modules in one single file.',
+
+  dependsOn: 'legacy-json',
+
+  async generate(input, { output }) {
+    /**
+     * @type {import('./types.d.ts').Output}
+     */
+    const generatedValue = {
+      miscs: [],
+      modules: [],
+      classes: [],
+      globals: [],
+      methods: [],
+    };
+
+    const propertiesToCopy = [
+      'miscs',
+      'modules',
+      'classes',
+      'globals',
+      'methods',
+    ];
+
+    input.forEach(section => {
+      // Copy the relevant properties from each section into our output
+      propertiesToCopy.forEach(property => {
+        if (section[property]) {
+          generatedValue[property].push(...section[property]);
+        }
+      });
+    });
+
+    await writeFile(
+      join(output, 'all.json'),
+      JSON.stringify(generatedValue),
+      'utf8'
+    );
+
+    return generatedValue;
+  },
+};

src/generators/legacy-json-all/types.d.ts

@@ -0,0 +1,14 @@
+import {
+  MiscSection,
+  Section,
+  SignatureSection,
+  ModuleSection,
+} from '../legacy-json/types';
+
+export interface Output {
+  miscs: Array<MiscSection>;
+  modules: Array<Section>;
+  classes: Array<SignatureSection>;
+  globals: Array<ModuleSection | { type: 'global' }>;
+  methods: Array<SignatureSection>;
+}

src/generators/legacy-json/constants.mjs

@@ -0,0 +1,18 @@
+// Grabs a method's return value
+export const RETURN_EXPRESSION = /^returns?\s*:?\s*/i;
+
+// Grabs a method's name
+export const NAME_EXPRESSION = /^['`"]?([^'`": {]+)['`"]?\s*:?\s*/;
+
+// Denotes a method's type
+export const TYPE_EXPRESSION = /^\{([^}]+)\}\s*/;
+
+// Checks if there's a leading hyphen
+export const LEADING_HYPHEN = /^-\s*/;
+
+// Grabs the default value if present
+export const DEFAULT_EXPRESSION = /\s*\*\*Default:\*\*\s*([^]+)$/i;
+
+// Grabs the parameters from a method's signature
+//  ex/ 'new buffer.Blob([sources[, options]])'.match(PARAM_EXPRESSION) === ['([sources[, options]])', '[sources[, options]]']
+export const PARAM_EXPRESSION = /\((.+)\);?$/;

src/generators/legacy-json/index.mjs

@@ -0,0 +1,68 @@
+'use strict';
+
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { groupNodesByModule } from '../../utils/generators.mjs';
+import buildSection from './utils/buildSection.mjs';
+
+/**
+ * This generator is responsible for generating the legacy JSON files for the
+ *  legacy API docs for retro-compatibility. It is to be replaced while we work
+ *  on the new schema for this file.
+ *
+ * This is a top-level generator, intaking the raw AST tree of the api docs.
+ * It generates JSON files to the specified output directory given by the
+ *  config.
+ *
+ * @typedef {Array<ApiDocMetadataEntry>} Input
+ *
+ * @type {import('../types.d.ts').GeneratorMetadata<Input, import('./types.d.ts').Section[]>}
+ */
+export default {
+  name: 'legacy-json',
+
+  version: '1.0.0',
+
+  description: 'Generates the legacy version of the JSON API docs.',
+
+  dependsOn: 'ast',
+
+  async generate(input, { output }) {
+    // This array holds all the generated values for each module
+    const generatedValues = [];
+
+    const groupedModules = groupNodesByModule(input);
+
+    // Gets the first nodes of each module, which is considered the "head"
+    const headNodes = input.filter(node => node.heading.depth === 1);
+
+    /**
+     * @param {ApiDocMetadataEntry} head
+     * @returns {import('./types.d.ts').ModuleSection}
+     */
+    const processModuleNodes = head => {
+      const nodes = groupedModules.get(head.api);
+
+      const section = buildSection(head, nodes);
+      generatedValues.push(section);
+
+      return section;
+    };
+
+    await Promise.all(
+      headNodes.map(async node => {
+        // Get the json for the node's section
+        const section = processModuleNodes(node);
+
+        // Write it to the output file
+        await writeFile(
+          join(output, `${node.api}.json`),
+          JSON.stringify(section),
+          'utf8'
+        );
+      })
+    );
+
+    return generatedValues;
+  },
+};

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

@@ -0,0 +1,83 @@
+import { ListItem } from 'mdast';
+
+export interface HierarchizedEntry extends ApiDocMetadataEntry {
+  hierarchyChildren: Array<ApiDocMetadataEntry>;
+}
+
+export interface Meta {
+  changes: Array<ApiDocMetadataChange>;
+  added?: Array<string>;
+  napiVersion?: Array<string>;
+  deprecated?: Array<string>;
+  removed?: Array<string>;
+}
+
+export interface SectionBase {
+  type: string;
+  name: string;
+  textRaw: string;
+  displayName?: string;
+  desc: string;
+  shortDesc?: string;
+  stability?: number;
+  stabilityText?: string;
+  meta?: Meta;
+}
+
+export interface ModuleSection extends SectionBase {
+  type: 'module';
+  source: string;
+  miscs?: Array<MiscSection>;
+  modules?: Array<ModuleSection>;
+  classes?: Array<SignatureSection>;
+  methods?: Array<MethodSignature>;
+  properties?: Array<PropertySection>;
+  globals?: ModuleSection | { type: 'global' };
+  signatures?: Array<SignatureSection>;
+}
+
+export interface SignatureSection extends SectionBase {
+  type: 'class' | 'ctor' | 'classMethod' | 'method';
+  signatures: Array<MethodSignature>;
+}
+
+export type Section =
+  | SignatureSection
+  | PropertySection
+  | EventSection
+  | MiscSection;
+
+export interface Parameter {
+  name: string;
+  optional?: boolean;
+  default?: string;
+}
+
+export interface MethodSignature {
+  params: Array<Parameter>;
+  return?: string;
+}
+
+export interface PropertySection extends SectionBase {
+  type: 'property';
+  [key: string]: string | undefined;
+}
+
+export interface EventSection extends SectionBase {
+  type: 'event';
+  params: Array<ListItem>;
+}
+
+export interface MiscSection extends SectionBase {
+  type: 'misc';
+  [key: string]: string | undefined;
+}
+
+export interface List {
+  textRaw: string;
+  desc?: string;
+  name: string;
+  type?: string;
+  default?: string;
+  options?: List;
+}