tmp

Author: flakey5

src/generators/json/generated.d.ts

@@ -10,15 +10,15 @@ export type NodeJsAPIDocumentationSchema = DocumentRoot & (Module | Text);
  * A JavaScript module.
  */
 export type Module = SectionBase & {
-  type: "module";
+  type: 'module';
   /**
    * https://jsdoc.app/tags-see
    */
-  "@see": string;
+  '@see': string;
   /**
    * https://jsdoc.app/tags-module
    */
-  "@module": string;
+  '@module': string;
   /**
    * Classes exported from this module.
    */
@@ -39,8 +39,8 @@ export type Module = SectionBase & {
  */
 export type NodeCoreVersion = string;
 export type Class = SectionBase & {
-  type: "class";
-  "@constructor"?: MethodSignature[];
+  type: 'class';
+  '@constructor'?: MethodSignature[];
   methods?: Method[];
   staticMethods?: Method[];
   properties?: Property[];
@@ -50,19 +50,19 @@ export type Class = SectionBase & {
  * A JavaScript function.
  */
 export type Method = SectionBase & {
-  type: "method";
+  type: 'method';
   signatures: MethodSignature[];
   [k: string]: unknown;
 };
 /**
  * A property on a JavaScript object or class.
  */
 export type Property = SectionBase & {
-  type: "property";
+  type: 'property';
   /**
    * JavaScript type of the property.
    */
-  "@type": string | [string, ...string[]];
+  '@type': string | [string, ...string[]];
   /**
    * Is this property modifiable by user code?
    */
@@ -88,23 +88,23 @@ export interface SectionBase {
   /**
    * Type of the section
    */
-  type: "module" | "class" | "method" | "property" | "text";
+  type: 'module' | 'class' | 'method' | 'property' | 'text';
   /**
    * https://jsdoc.app/tags-name
    */
-  "@name": string;
+  '@name': string;
   /**
    * Description of the section.
    */
   description?: string;
   /**
    * https://jsdoc.app/tags-example
    */
-  "@example"?: string | string[];
+  '@example'?: string | string[];
   /**
    * https://jsdoc.app/tags-deprecated
    */
-  "@deprecated"?: NodeCoreVersion[];
+  '@deprecated'?: NodeCoreVersion[];
   stability?: Stability;
   /**
    * The changes this API has underwent.
@@ -113,7 +113,7 @@ export interface SectionBase {
   /**
    * https://jsdoc.app/tags-since
    */
-  "@since"?: NodeCoreVersion[];
+  '@since'?: NodeCoreVersion[];
   /**
    * todo what does this describe lol
    */
@@ -155,22 +155,22 @@ export interface MethodSignature {
   /**
    * The method signature's return type.
    */
-  "@returns"?: string | [string, ...string[]];
+  '@returns'?: string | [string, ...string[]];
   [k: string]: unknown;
 }
 export interface MethodParameter {
   /**
    * Name of the parameter.
    */
-  "@name": string;
+  '@name': string;
   /**
    * Type of the parameter
    */
-  "@type": string | [string, ...string[]];
+  '@type': string | [string, ...string[]];
   description?: string;
   /**
    * The parameter's default value
    */
-  "@default"?: string;
+  '@default'?: string;
   [k: string]: unknown;
 }

src/generators/json/index.mjs

@@ -24,7 +24,8 @@ import { createSectionBuilder } from './utils/createSection.mjs';
 export default {
   name: 'json',
 
-  version: '1.0.0',
+  // This should be kept in sync with the JSON schema version
+  version: '2.0.0',
 
   description: 'TODO',
 
@@ -73,10 +74,10 @@ export default {
 
       // Write it to the output file
       if (output) {
-        // await writeFile(
-        //   join(output, `${node.api}.json`),
-        //   JSON.stringify(section)
-        // );
+        await writeFile(
+          join(output, `${node.api}.json`),
+          JSON.stringify(section)
+        );
       }
     });
 

src/generators/json/schema.jsonc

@@ -1,8 +1,8 @@
 {
-  // TODO vscode doesn't support the latest schema https://github.com/microsoft/vscode/issues/155379
-  // "$schema": "https://json-schema.org/draft/2020-12/schema",
+  // TODO vscode doesn't support 2020-12 yet
+  //  https://github.com/microsoft/vscode/issues/165219
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "[email protected]",
+  "$id": "[email protected]", // This should be kept in sync with the generator version
   "title": "Node.js API Documentation Schema",
   "readOnly": true,
 
@@ -11,7 +11,7 @@
     {
       "oneOf": [
         { "$ref": "#/definitions/Module" },
-        { "$ref": "#/definitions/Text" }
+        { "$ref": "#/definitions/Text" },
       ],
     },
   ],
@@ -48,6 +48,11 @@
           "type": "string",
           "description": "Description of the section.",
         },
+        "text": {
+          "type": "array",
+          "description": "Sections that just hold further text on this section.",
+          "items": { "$ref": "#/definitions/Text" },
+        },
         "@example": {
           "description": "https://jsdoc.app/tags-example",
           "oneOf": [
@@ -136,11 +141,6 @@
               "type": "array",
               "items": { "$ref": "#/definitions/Property" },
             },
-            "text": {
-              "type": "array",
-              "description": "Sections that just hold further text on this module.",
-              "items": { "$ref": "#/definitions/Text" }
-            }
           },
           // TODO what else to be required
           "required": ["type", "@module", "@see"],
@@ -175,7 +175,13 @@
               "items": { "$ref": "#/definitions/Property" },
             },
           },
-          "required": ["type"],
+          "required": [
+            "type",
+            "@constructor",
+            "methods",
+            "staticMethods",
+            "properties",
+          ],
         },
       ],
     },
@@ -307,9 +313,7 @@
     },
 
     "Text": {
-      "allOf": [
-        { "$ref": "#/definitions/SectionBase" },
-      ]
+      "allOf": [{ "$ref": "#/definitions/SectionBase" }],
     },
 
     "NodeCoreVersion": {

src/generators/json/types.d.ts

@@ -1,3 +1,20 @@
-import { Class, Method, Module, Property, SectionBase, Text } from './generated.d.ts';
+import {
+  Class,
+  Method,
+  Module,
+  Property,
+  SectionBase,
+  Text,
+} from './generated.d.ts';
 
-export type Section = SectionBase & (Module | Class | Method | Property | Text);
+export type Section = SectionBase &
+  (Module | Class | Method | Property | Text) &
+  GeneratorMetadata;
+
+/**
+ * This is metadata that's only relevant to the generator and should be removed
+ * before the file is output.
+ */
+export type GeneratorMetadata = {
+  parent?: Section;
+};

src/generators/json/utils/createClassSection.mjs

@@ -0,0 +1,36 @@
+// @ts-check
+'use strict';
+
+import { findParentSection } from './findParentSection.mjs';
+
+/**
+ * @typedef {import('../../legacy-json/types.d.ts').HierarchizedEntry} HierarchizedEntry
+ */
+
+export const createClassSectionBuilder = () => {
+  /**
+   * Adds the properties expected in a class section to an object.
+   * @param {import('../generated.d.ts').Class} section The class section
+   */
+  return section => {
+    section['@constructor'] = [];
+
+    section.methods = [];
+
+    section.staticMethods = [];
+
+    section.properties = [];
+
+    const parent = findParentSection(section, 'module');
+
+    if (parent) {
+      if (!Array.isArray(parent.classes)) {
+        throw new TypeError(
+          `expected parent.classes to be an array, got ${typeof parent.classes}`
+        );
+      }
+
+      parent.classes.push(section);
+    }
+  };
+};

src/generators/json/utils/createMethodSection.mjs

@@ -0,0 +1,41 @@
+// @ts-check
+'use strict';
+
+import { findParentSection } from './findParentSection.mjs';
+
+/**
+ * @typedef {import('../../legacy-json/types.d.ts').HierarchizedEntry} HierarchizedEntry
+ */
+
+export const createMethodSectionBuilder = () => {
+  /**
+   * @param {HierarchizedEntry} entry The AST entry
+   * @param {import('../generated.d.ts').Method} section The method section
+   */
+  const parseSignatures = (entry, section) => {
+    section.signatures = [];
+  };
+
+  /**
+   * Adds the properties expected in a method section to an object.
+   * @param {HierarchizedEntry} entry The AST entry
+   * @param {import('../generated.d.ts').Method} section The method section
+   */
+  return (entry, section) => {
+    parseSignatures(entry, section);
+
+    // TODO are there any other places that an exposed method can be defined?
+    const parent = findParentSection(section, ['class', 'module']);
+
+    // Add this section to the parent if it exists
+    if (parent) {
+      if (!Array.isArray(parent.methods)) {
+        throw new TypeError(
+          `expected parent.methods to be an array, got type ${typeof parent.methods} instead (parent type=${parent.type})`
+        );
+      }
+
+      parent.methods.push(section);
+    }
+  };
+};

src/generators/json/utils/createModuleSection.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+'use strict';
+
+import { DOC_NODE_VERSION } from '../../../constants.mjs';
+
+/**
+ * @typedef {import('../../legacy-json/types.d.ts').HierarchizedEntry} HierarchizedEntry
+ */
+
+export const createModuleSectionBuilder = () => {
+  /**
+   * Adds the properties expected in a module section to an object.
+   * @param {HierarchizedEntry} entry The AST entry
+   * @param {import('../generated.d.ts').Module} section The module section
+   */
+  return (entry, section) => {
+    section['@see'] =
+      `https://nodejs.org/dist/${DOC_NODE_VERSION}/doc/api/${entry.api}.html`;
+
+    section['@module'] = `node:${entry.api}`;
+
+    section.classes = [];
+
+    section.methods = [];
+
+    section.globals = [];
+
+    section.properties = [];
+  };
+};