some review changes

Signed-off-by: flakey5 <[email protected]>

Author: flakey5

.c8rc.json

@@ -6,6 +6,6 @@
     "src/generators/legacy-html/assets",
     "src/generators/web/ui",
     "**/*.d.ts",
-    "tools/"
+    "scripts/"
   ]
 }

tools/generate-json-types.mjs scripts/generate-json-types.mjstools/generate-json-types.mjs renamed to scripts/generate-json-types.mjs

@@ -5,12 +5,21 @@
  */
 
 import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 
 import { compile } from 'json-schema-to-typescript';
 import { parse } from 'jsonc-parser';
 
-const SCHEMA_PATH = import.meta.resolve('../src/generators/json/schema.jsonc');
-const TYPES_PATH = import.meta.resolve('../src/generators/json/generated.d.ts');
+const GENERATOR_DIR = join(
+  import.meta.dirname,
+  '..',
+  'src',
+  'generators',
+  'json'
+);
+
+const SCHEMA_PATH = join(GENERATOR_DIR, 'schema.jsonc');
+const TYPES_PATH = join(GENERATOR_DIR, 'generated.d.ts');
 
 // Read the contents of the JSON schema
 const schemaString = await readFile(SCHEMA_PATH, 'utf8');

src/generators/json/generated.d.ts

@@ -10,11 +10,11 @@ export type NodeJsAPIDocumentationSchema = DocumentRoot & (Module | Text);
  * A JavaScript module.
  */
 export type Module = SectionBase & {
-  type: 'module';
+  type: "module";
   /**
    * https://jsdoc.app/tags-module
    */
-  '@module': string;
+  "@module": string;
   /**
    * Classes exported from this module.
    */
@@ -29,52 +29,47 @@ export type Module = SectionBase & {
   globals?: (Class | Method)[];
   properties?: Property[];
   events?: Event[];
-  [k: string]: unknown;
 };
 export type Text = SectionBase;
 /**
  * Node.js version number
  */
 export type NodeCoreVersion = string;
 export type Class = SectionBase & {
-  type: 'class';
-  '@constructor': MethodSignature[];
-  methods: Method[];
-  staticMethods: Method[];
-  properties: Property[];
+  type: "class";
+  "@constructor"?: MethodSignature[];
+  methods?: Method[];
+  staticMethods?: Method[];
+  properties?: Property[];
   events?: Event[];
-  [k: string]: unknown;
 };
 /**
  * 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?
    */
   mutable?: boolean;
-  [k: string]: unknown;
 };
 /**
  * An event that can be emitted by the parent object or class.
  */
 export type Event = SectionBase & {
-  type: 'event';
+  type: "event";
   parameters: MethodParameter[];
-  [k: string]: unknown;
 };
 
 /**
@@ -85,7 +80,6 @@ export interface DocumentRoot {
    * The path to the Markdown source used to generate this document. It is relative to the Node.js repository root.
    */
   source: string;
-  [k: string]: unknown;
 }
 /**
  * Common properties found in each section of a document.
@@ -94,31 +88,31 @@ export interface SectionBase {
   /**
    * Type of the section
    */
-  type: 'module' | 'class' | 'method' | 'property' | 'event' | 'text';
+  type: "module" | "class" | "method" | "property" | "event" | "text";
   /**
    * https://jsdoc.app/tags-name
    */
-  '@name': string;
+  "@name": string;
   /**
    * Description of the section.
    */
   description?: string;
   /**
    * https://jsdoc.app/tags-see
    */
-  '@see'?: string;
+  "@see"?: string;
   /**
    * Sections that just hold further text on this section.
    */
   text?: Text[];
   /**
    * 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.
@@ -127,13 +121,12 @@ export interface SectionBase {
   /**
    * https://jsdoc.app/tags-since
    */
-  '@since'?: NodeCoreVersion[];
+  "@since"?: NodeCoreVersion[];
   napiVersion?: number[];
   /**
    * Versions that this was removed in.
    */
   removedIn?: NodeCoreVersion[];
-  [k: string]: unknown;
 }
 /**
  * Describes the stability of an object.
@@ -147,7 +140,6 @@ export interface Stability {
    * Textual representation of the stability.
    */
   text: string;
-  [k: string]: unknown;
 }
 export interface Change {
   version: NodeCoreVersion[];
@@ -159,28 +151,25 @@ export interface Change {
    * Description of the change.
    */
   description: string;
-  [k: string]: unknown;
 }
 export interface MethodSignature {
-  parameters?: MethodParameter[];
-  '@returns'?: MethodReturnType;
-  [k: string]: unknown;
+  parameters: MethodParameter[];
+  "@returns": MethodReturnType;
 }
 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;
-  [k: string]: unknown;
+  "@default"?: string;
 }
 /**
  * A method signature's return type.
@@ -190,6 +179,5 @@ export interface MethodReturnType {
   /**
    * The method signature's return type.
    */
-  '@type': string | [string, ...string[]];
-  [k: string]: unknown;
+  "@type": string | [string, ...string[]];
 }

src/generators/json/index.mjs

@@ -76,7 +76,7 @@ export default {
       if (output) {
         writeFilePromises[i] = writeFile(
           join(output, `${node.api}.json`),
-          JSON.stringify(section, null, 2)
+          JSON.stringify(section)
         );
       }
     }

src/generators/json/schema.jsonc

@@ -3,7 +3,7 @@
    * NOTE: if you modify this, please:
    *  - Bump the version in the $id property
    *  - Bump the version of the `json` and `json-all` generator.
-   *  - Run `tools/generate-json-types.mjs` and ensure there aren't type errors
+   *  - Run `scripts/generate-json-types.mjs` and ensure there aren't type errors
    */
 
   "$schema": "http://json-schema.org/draft-07/schema#",
@@ -153,6 +153,7 @@
             },
           },
           "required": ["type", "@module", "@see"],
+          "additionalProperties": false
         },
       ],
     },
@@ -191,6 +192,7 @@
           "required": [
             "type",
           ],
+      "additionalProperties": false
         },
       ],
     },
@@ -212,6 +214,7 @@
             },
           },
           "required": ["type", "signatures"],
+      "additionalProperties": false
         },
       ],
     },
@@ -227,7 +230,8 @@
           "$ref": "#/definitions/MethodReturnType",
         },
       },
-      "required": ["parameters", "@returns"]
+      "required": ["parameters", "@returns"],
+      "additionalProperties": false
     },
 
     "MethodParameter": {
@@ -263,6 +267,7 @@
         },
       },
       "required": ["@name", "@type"],
+      "additionalProperties": false
     },
 
     "MethodReturnType": {
@@ -289,6 +294,7 @@
         },
       },
       "required": ["@type"],
+      "additionalProperties": false
     },
 
     "Global": {
@@ -331,6 +337,7 @@
             },
           },
           "required": ["type"],
+      "additionalProperties": false
         },
       ],
     },
@@ -352,6 +359,7 @@
             },
           },
           "required": ["type", "parameters"],
+      "additionalProperties": false
         },
       ],
     },
@@ -388,6 +396,7 @@
         },
       },
       "required": ["version", "description"],
+      "additionalProperties": false
     },
 
     "Stability": {
@@ -406,6 +415,7 @@
         },
       },
       "required": ["value", "text"],
+      "additionalProperties": false
     },
   },
 }

src/generators/json/utils/createParameterGroupings.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import { ParameterTree } from './parameter-tree.mjs';
+import { ParameterTree } from './parameterTree.mjs';
 
 /**
  * Parameters are declared in a section's header. This looks something like
@@ -34,25 +34,21 @@ export function createParameterGroupings(parameterNames) {
  * @returns {[ParameterTree, boolean]}
  */
 export function createParameterTree(parameterNames) {
-  /**
-   * @type {import('./parameter-tree.mjs').Counter}
-   */
-  const counter = { count: 0 };
-
-  let tree = new ParameterTree(counter);
+  let tree = new ParameterTree();
   let includeFirstChildren = false;
+
   for (let i = 0; i < parameterNames.length; i++) {
     /**
-     * @example 'length]]' -> add `length` to tree's parameters, close out optional depth
+     * @example 'length]]' -> add `length` to tree's parameters, close out child tree(s)
      * @example 'arrayBuffer[' -> add `arrayBuffer` to tree's parameters, start child tree
-     * @example '[sources[' -> start child tree for sources and another child tree for that child
-     * @example '[hello]' -> start child tree, add and end child tree
-     * @example '[hello' -> start child tree
-     * @example '[hello]['
-     * @example ']max['
-     * @example 'end' -> just add
+     * @example '[sources[' -> start child tree with parameter `sources`, then start another child tree
+     * @example '[hello]' -> start child tree, add `hello` to it, then end it
+     * @example '[hello' -> start child tree, add `hello` to it
+     * @example '[hello][' -> start child tree, end child tree, start another child tree
+     * @example ']max[' -> add `max` to parent tree, start another child tree, set includeFirstChildren to true
+     * @example 'end' -> add to tree's parameters
      */
-    let parameter = parameterNames[i].trim();
+    const parameter = parameterNames[i].trim();
 
     let nameStartIndex = 0;
     if (parameter.startsWith('[')) {

…generators/json/utils/parameter-tree.mjs …/generators/json/utils/parameterTree.mjssrc/generators/json/utils/parameter-tree.mjs renamed to src/generators/json/utils/parameterTree.mjs src/generators/json/utils/parameter-tree.mjs renamed to src/generators/json/utils/parameterTree.mjs

@@ -35,32 +35,11 @@ export class ParameterTree {
    * @param {Counter} counter
    * @param {ParameterTree} [parent=undefined]
    */
-  constructor(counter, parent = undefined) {
+  constructor(counter = { count: 0 }, parent = undefined) {
     this.#counter = counter;
     this.#parent = parent;
   }
 
-  /**
-   *
-   */
-  get parameters() {
-    return this.#parameters;
-  }
-
-  /**
-   *
-   */
-  get children() {
-    return this.#children;
-  }
-
-  /**
-   *
-   */
-  get counter() {
-    return this.#counter;
-  }
-
   /**
    *
    */