feat(generator): add node.config.json

Author: avivkeller

src/generators/index.mjs

@@ -10,6 +10,7 @@ import addonVerify from './addon-verify/index.mjs';
 import apiLinks from './api-links/index.mjs';
 import oramaDb from './orama-db/index.mjs';
 import astJs from './ast-js/index.mjs';
+import nodeConfigSchema from './node-config-schema/index.mjs';
 
 export const publicGenerators = {
   'json-simple': jsonSimple,
@@ -21,6 +22,7 @@ export const publicGenerators = {
   'addon-verify': addonVerify,
   'api-links': apiLinks,
   'orama-db': oramaDb,
+  'node-config-schema': nodeConfigSchema,
 };
 
 export const allGenerators = {

src/generators/node-config-schema/constants.mjs

@@ -0,0 +1,74 @@
+// Constants and Error Messages
+
+// Error messages related to missing files or invalid input
+export const ERRORS = {
+  missingCCandHFiles:
+    'Both node_options.cc and node_options.h must be provided.',
+  headerTypeNotFound:
+    'Header type for "{{headerKey}}" not found in the header file.',
+  missingTypeDefinition:
+    'No type definition found for header type "{{headerType}}" in TYPE_DEFINITION_MAP.',
+};
+
+// Regular Expressions for Option Matching
+
+/**
+ * Regex pattern to match calls to AddOption function.
+ * - Captures the option name (inside quotes) and its parameters (if any).
+ */
+export const ADD_OPTION_REGEX =
+  /AddOption[\s\n\r]*\([\s\n\r]*"([^"]+)"(.*?)\);/gs;
+
+/**
+ * Regex pattern to match header keys in the Options class.
+ * - Captures the key name following 'Options::', e.g., Options::key_name.
+ */
+export const OPTION_HEADER_KEY_REGEX = /Options::(\w+)/;
+
+// JSON Schema Definitions
+
+/**
+ * JSON schema for validating the configuration structure.
+ * - Ensures no additional properties beyond the defined ones are allowed.
+ * - Defines properties such as $schema and nodeOptions.
+ */
+export const BASIC_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  additionalProperties: false, // Disallows extra properties outside the defined schema
+  properties: {
+    // The $schema property, which must always be a string
+    $schema: {
+      type: 'string',
+    },
+    // The nodeOptions property, which must be an object with no additional properties
+    nodeOptions: {
+      additionalProperties: false,
+      properties: {}, // Can be extended if more node options are needed in the future
+      type: 'object',
+    },
+  },
+  type: 'object', // Defines that the root of the schema is an object
+};
+
+// Schema Definition Map for Data Types
+/**
+ * Maps C++ data types to JSON schema definitions.
+ * - Defines mappings for types like std::vector<std::string>, uint64_t, etc.
+ * - Ensures correct data structure for each type.
+ */
+export const TYPE_DEFINITION_MAP = {
+  'std::vector<std::string>': {
+    oneOf: [
+      { type: 'string' }, // Single string case
+      {
+        items: { type: 'string', minItems: 1 }, // Array of strings, ensuring at least one item
+        type: 'array',
+      },
+    ],
+  },
+  uint64_t: { type: 'number' }, // 64-bit unsigned integer maps to a number
+  int64_t: { type: 'number' }, // 64-bit signed integer maps to a number
+  HostPort: { type: 'number' }, // HostPort is a number, like 4000
+  'std::string': { type: 'string' }, // String type
+  bool: { type: 'boolean' }, // Boolean type
+};

src/generators/node-config-schema/index.mjs

@@ -0,0 +1,119 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import {
+  ERRORS,
+  ADD_OPTION_REGEX,
+  BASIC_SCHEMA,
+  OPTION_HEADER_KEY_REGEX,
+  TYPE_DEFINITION_MAP,
+} from './constants.mjs';
+import { join } from 'node:path';
+
+/**
+ * This generator generates the `node.config.json` schema.
+ *
+ * @typedef {Array<ApiDocMetadataEntry>} Input
+ *
+ * @type {GeneratorMetadata<Input, string>}
+ */
+export default {
+  name: 'node-config-schema',
+
+  version: '1.0.0',
+
+  description: 'Generates the node.config.json schema.',
+
+  /**
+   * Generates the `node.config.json` schema.
+   * @param {unknown} _ - Unused parameter
+   * @param {Partial<GeneratorOptions>} options - Options containing the input file paths
+   * @throws {Error} If the required files node_options.cc or node_options.h are missing or invalid.
+   */
+  async generate(_, options) {
+    let ccFile, hFile;
+
+    // Ensure input files are provided and capture the paths
+    for (const filePath of options.input) {
+      if (filePath.endsWith('node_options.cc')) {
+        ccFile = filePath;
+      } else if (filePath.endsWith('node_options.h')) {
+        hFile = filePath;
+      }
+    }
+
+    // Error handling if either cc or h file is missing
+    if (!ccFile || !hFile) {
+      throw new Error(ERRORS.missingCCandHFiles);
+    }
+
+    // Read the contents of the cc and h files
+    const ccContent = await readFile(ccFile, 'utf-8');
+    const hContent = await readFile(hFile, 'utf-8');
+
+    // Clone the BASIC_SCHEMA to avoid mutating the original schema object
+    /** @type {typeof BASIC_SCHEMA} */
+    const schema = Object.assign({}, BASIC_SCHEMA);
+    const { nodeOptions } = schema.properties;
+
+    // Process the cc content and match AddOption calls
+    for (const [, option, config] of ccContent.matchAll(ADD_OPTION_REGEX)) {
+      // If config doesn't include 'kAllowedInEnvvar', skip this option
+      if (!config.includes('kAllowedInEnvvar')) {
+        continue;
+      }
+
+      const headerKey = config.match(OPTION_HEADER_KEY_REGEX)?.[1];
+      // If there's no header key, it's either a V8 option or a no-op
+      if (!headerKey) {
+        continue;
+      }
+
+      // Try to find the corresponding header type in the hContent
+      const headerTypeMatch = hContent.match(
+        new RegExp(`\\s*(.+)\\s${headerKey}[^\\B_]`)
+      );
+
+      // Error handling if header type is not found
+      if (!headerTypeMatch) {
+        throw new Error(
+          formatErrorMessage(ERRORS.headerTypeNotFound, { headerKey })
+        );
+      }
+
+      const headerType = headerTypeMatch[1].trim();
+
+      // Ensure the headerType exists in the TYPE_DEFINITION_MAP
+      const typeDefinition = TYPE_DEFINITION_MAP[headerType];
+      if (!typeDefinition) {
+        throw new Error(
+          formatErrorMessage(ERRORS.missingTypeDefinition, { headerType })
+        );
+      }
+
+      // Add the option to the schema after removing the '--' prefix
+      nodeOptions.properties[option.replace('--', '')] = typeDefinition;
+    }
+
+    nodeOptions.properties = Object.fromEntries(
+      Object.keys(nodeOptions.properties)
+        .sort()
+        .map(key => [key, nodeOptions.properties[key]])
+    );
+
+    await writeFile(
+      join(options.output, 'node-config-schema.json'),
+      JSON.stringify(schema, null, 2) + '\n'
+    );
+
+    return schema;
+  },
+};
+
+/**
+ * Helper function to replace placeholders in error messages with dynamic values.
+ * @param {string} message - The error message with placeholders.
+ * @param {Object} params - The values to replace the placeholders.
+ * @returns {string} - The formatted error message.
+ */
+function formatErrorMessage(message, params) {
+  return message.replace(/{{(\w+)}}/g, (_, key) => params[key] || `{{${key}}}`);
+}