@gesslar/bedoc 1.0.0

package/src/core/Configuration.js

@@ -0,0 +1,330 @@
+import process from "node:process"
+import {Environment} from "./Core.js"
+
+import {
+  ConfigurationParameters,
+  ConfigurationPriorityKeys,
+} from "./ConfigurationParameters.js"
+
+import * as ActionUtil from "./util/ActionUtil.js"
+import * as DataUtil from "./util/DataUtil.js"
+import * as FDUtil from "./util/FDUtil.js"
+
+const {loadJson} = ActionUtil
+const {isNothing, isType, mapObject} = DataUtil
+const {getFiles, resolveDirectory, resolveFilename} = FDUtil
+const {fdType, fdTypes} = FDUtil
+
+export default class Configuration {
+  async validate({options, source}) {
+    const finalOptions = {}
+
+    this.#mapEntryOptions({options, source})
+
+    // While the entry points do wrap the entire process in a try/catch, we
+    // should also do this here, so we can trap everything and instead
+    // of throwing, return friendly messages back!
+
+    // If the configuration parameters are invalid, we can't proceed. No error
+    // collection is needed here, because the ConfigurationParameters object
+    // is a static object and should be correct. OUT WITH THE TRASH!!! (I mean
+    // the error collection, not the ConfigurationParameters object)
+    // (Edit: No, I mean the ConfigurationParameters object. It's trash. Fix it
+    // if you get this error.)
+    const configValidationErrors = this.#validateConfigurationParameters()
+    if(configValidationErrors.length > 0)
+      throw new AggregateError(
+        configValidationErrors,
+        `ConfigurationParameters validation errors: `+
+          `${configValidationErrors.join(", ")}`,
+      )
+
+    const allOptions = this.#findAllOptions(options)
+    Object.assign(finalOptions, await this.#mergeOptions(allOptions))
+    this.#fixOptionValues(finalOptions)
+
+    // Priority keys are those which must be processed first. They are
+    // specified in order of priority.
+    // Find them and add them to an array; the rest will be in pushed to the
+    // end of the priority array.
+    const orderedSections = []
+    ConfigurationPriorityKeys.forEach((key) => {
+      if(!ConfigurationParameters[key])
+        throw new Error(`Invalid priority key: ${key}`)
+
+      if(finalOptions[key])
+        orderedSections.push({key, value: finalOptions[key]})
+    })
+
+    const remainingSections = Object.keys(ConfigurationParameters).filter(
+      (key) => !ConfigurationPriorityKeys.includes(key),
+    )
+    orderedSections.push(
+      ...remainingSections.map((key) => {
+        return {key, value: finalOptions[key]}
+      }),
+    )
+
+    // Check exclusive options
+    for(const [key, param] of Object.entries(ConfigurationParameters)) {
+      if(
+        param.exclusiveOf &&
+        finalOptions[key] &&
+        finalOptions[param.exclusiveOf]
+      )
+        throw new SyntaxError(
+          `Options \`${key}\` and \`${param.exclusiveOf}\` are mutually exclusive`,
+        )
+    }
+
+    for(const section of orderedSections) {
+      const {key} = section
+
+      // Skipping config, we've already handled it
+      if(key === "config")
+        continue
+
+      let {value} = section
+      const nothing = isNothing(value)
+      const param = ConfigurationParameters[key]
+      const {required, path} = param
+
+      if(nothing) {
+        if(required === true)
+          throw new SyntaxError(`Option \`${key}\` is required`)
+        else
+          continue
+      }
+
+      // Additional path validation if needed
+      if(path && !nothing) {
+        const {mustExist, type: pathType} = path
+
+        // Special for `input` and `exclude` because they can be a comma-
+        // separated list of glob patterns.
+        if(key === "input" || key === "exclude") {
+          if(isType(value, "array"))
+            value = await Promise.all(
+              value.map((pattern) => getFiles(pattern)),
+            )
+          else if(isType(value, "string"))
+            value = await getFiles(value)
+          else
+            throw new TypeError(
+              `Option \`${key}\` must be a string or an array of strings`,
+            )
+
+          finalOptions[key] = value.flat()
+
+          continue
+        } else {
+          if(mustExist === true) {
+            finalOptions[key] =
+              pathType === fdType.FILE
+                ? resolveFilename(value)
+                : resolveDirectory(value)
+          }
+        }
+      }
+    }
+
+    return {
+      status: "success",
+      validated: true,
+      ...finalOptions,
+    }
+  }
+
+  #mapEntryOptions({options, source}) {
+    // CLI already has done all the work via commander
+    if(source === Environment.CLI)
+      return options
+
+    for(const [key, value] of Object.entries(options)) {
+      options[key] = {value, source}
+    }
+
+    // We will need to inject some options if they are not available
+    const cwd = process.cwd()
+    const dir = resolveDirectory(cwd)
+
+    // Inject basePath if not available
+    if(!options.basePath)
+      options.basePath = {value: dir, source}
+
+    // Inject packageJson if not available
+    if(!options.packageJson) {
+      const jsonFile = resolveFilename("package.json", dir)
+      const jsonObj = loadJson(jsonFile)
+      options.packageJson = {value: jsonObj, source}
+    }
+
+    return options
+  }
+
+  /**
+   * Validate the ConfigurationParameters object. This is a sanity check to
+   * ensure that the ConfigurationParameters object is valid.
+   *
+   * @returns {string[]} Errors
+   */
+  #validateConfigurationParameters() {
+    const errors = []
+
+    for(const [key, param] of Object.entries(ConfigurationParameters)) {
+      // Type
+      if(!param.type) {
+        errors.push(`Option \`${key}\` has no type`)
+        continue
+      }
+
+      // Paths
+      if(param.subtype?.path) {
+        const pathType = param.subtype.path?.type
+
+        // Check if pathType is defined
+        if(!pathType)
+          errors.push(`Option \`${key}\` has no path type`)
+
+        // Check if pathType is a valid key in FdTypes
+        if(!fdTypes.includes(pathType))
+          errors.push(`Option \`${key}\` has invalid path type: ${pathType}`)
+      }
+    }
+
+    return errors
+  }
+
+  /**
+   * Find all options from all sources
+   *
+   * @param {object} entryOptions - The command line options.
+   * @returns {Promise<object[]>} All options from all sources.
+   */
+  #findAllOptions(entryOptions) {
+    const allOptions = []
+
+    const environmentVariables = this.#getEnvironmentVariables()
+    if(environmentVariables)
+      allOptions.push({source: "environment", options: environmentVariables})
+
+    const packageJson = entryOptions.packageJson
+    if(packageJson?.bedoc)
+      allOptions.push({source: "packageJson", options: packageJson.bedoc})
+
+    // Then the config file, if the options specified a config file
+    const useConfig =
+      entryOptions?.config ||
+      packageJson?.bedoc?.config ||
+      environmentVariables?.config
+
+    if(useConfig) {
+      const configFilename = packageJson?.bedoc?.config || entryOptions.config
+
+      if(!configFilename)
+        throw new Error("No config file specified")
+
+      const configFile = resolveFilename(configFilename)
+      const config = loadJson(configFile)
+
+      allOptions.push({source: "config", options: config})
+    }
+
+    allOptions.push({source: "entry", options: entryOptions})
+
+    return allOptions
+  }
+
+  /**
+   * Get environment variables
+   *
+   * @returns {object} Environment variables
+   */
+  #getEnvironmentVariables() {
+    const environmentVariables = {}
+    const params = Object.keys(ConfigurationParameters).map((param) => {
+      return {
+        param,
+        env: `bedoc_${param}`.toUpperCase(),
+      }
+    })
+
+    for(const param of params) {
+      if(process.env[param.env])
+        environmentVariables[param.param] = process.env[param.env]
+    }
+
+    return environmentVariables
+  }
+
+  /**
+   * Merge all options into one object
+   *
+   * @param {object[]} allOptions - All options from all sources.
+   * @returns {Promise<object>} The merged options.
+   */
+  async #mergeOptions(allOptions) {
+    const entryIndex = allOptions.findIndex(
+      option => option.source && option.source === "entry",
+    )
+    const entryOptions = allOptions[entryIndex].options
+    const nonEntryOptions = allOptions.filter(
+      option => option.source && option.source !== "entry",
+    )
+    const optionsOnly = nonEntryOptions.map((option) => option.options)
+    const mergedOptions = optionsOnly.reduce((acc, options) => {
+      for(const [key, value] of Object.entries(options)) acc[key] = value
+
+      return acc
+    }, {})
+
+    const mappedOptions = await mapObject(mergedOptions, (option, value) => {
+      const {value: entryValue, source: entrySource} = entryOptions[option] ?? {
+        value: undefined,
+        source: undefined,
+      }
+
+      const entryDefaulted = entrySource === "default"
+
+      if(entryValue && value !== entryValue)
+        return entryDefaulted ? value : entryValue
+
+      return value
+    })
+
+    // Last, but not least, add any defaulted options that are not in the
+    // mapped options
+    for(const [key, value] of Object.entries(entryOptions)) {
+      if(!mappedOptions[key]) {
+        if(value.source)
+          mappedOptions[key] = value.value
+      } else {
+        if(value.source !== "default")
+          mappedOptions[key] = value.value
+      }
+    }
+
+    return mappedOptions
+  }
+
+  /**
+   * Fix option values. This operation is performed in place.
+   *
+   * @param {object} options - The options to fix.
+   */
+  #fixOptionValues(options) {
+    for(const [key, param] of Object.entries(ConfigurationParameters)) {
+      // If the options passed includes this configuration parameter
+      if(options[key]) {
+        if(typeof options[key] === "string" && param.type !== "string") {
+          switch(param.type.toString()) {
+            case "boolean":
+            case "number":
+              options[key] = JSON.parse(options[key])
+              break
+          }
+        }
+      }
+    }
+  }
+}

package/src/core/ConfigurationParameters.js

@@ -0,0 +1,142 @@
+import * as DataUtil from "./util/DataUtil.js"
+
+const {newTypeSpec} = DataUtil
+
+const ConfigurationParameters = Object.freeze({
+  input: {
+    short: "i",
+    param: "file",
+    description: "Comma-separated glob patterns to match files",
+    type: newTypeSpec("string|string[]"),
+    required: true,
+    path: {
+      type: "file",
+      mustExist: true,
+    },
+  },
+  exclude: {
+    short: "x",
+    param: "file",
+    description: "Comma-separated glob patterns to exclude files",
+    type: newTypeSpec("string|string[]"),
+    required: false,
+  },
+  language: {
+    short: "l",
+    param: "lang",
+    description: "Language parser to use",
+    type: newTypeSpec("string"),
+    required: false,
+    exclusiveOf: "parser",
+  },
+  format: {
+    short: "f",
+    description: "Output format",
+    type: newTypeSpec("string"),
+    required: false,
+    exclusiveOf: "printer",
+  },
+  maxConcurrent: {
+    short: "C",
+    param: "num",
+    description: "Maximum number of concurrent tasks",
+    type: newTypeSpec("number"),
+    required: false,
+    default: 10,
+  },
+  hooks: {
+    short: "k",
+    param: "file",
+    description: "Custom hooks JS file",
+    type: newTypeSpec("string"),
+    required: false,
+    path: {
+      type: "file",
+      mustExist: true,
+    },
+  },
+  output: {
+    short: "o",
+    param: "dir",
+    description: "Output directory",
+    type: newTypeSpec("string"),
+    required: false,
+    path: {
+      type: "directory",
+      mustExist: true,
+    },
+  },
+  parser: {
+    short: "p",
+    param: "file",
+    description: "Custom parser JS file",
+    type: newTypeSpec("string"),
+    required: false,
+    exclusiveOf: "language",
+    path: {
+      type: "file",
+      mustExist: true,
+    },
+  },
+  printer: {
+    short: "P",
+    param: "file",
+    description: "Custom printer JS file",
+    type: newTypeSpec("string"),
+    required: false,
+    exclusiveOf: "format",
+    path: {
+      type: "file",
+      mustExist: true,
+    },
+  },
+  hookTimeout: {
+    short: "T",
+    param: "ms",
+    description: "Timeout in milliseconds for hook execution",
+    type: newTypeSpec("number"),
+    required: false,
+    default: 5000,
+  },
+  mock: {
+    short: "m",
+    param: "dir",
+    description: "Path to mock parsers and printers",
+    type: newTypeSpec("string"),
+    required: false,
+    path: {
+      type: "directory",
+      mustExist: true,
+    },
+  },
+  config: {
+    short: "c",
+    param: "file",
+    description: "Use JSON config file",
+    type: newTypeSpec("string"),
+    required: false,
+    path: {
+      type: "file",
+      mustExist: true,
+    },
+  },
+  debug: {
+    short: "d",
+    description: "Enable debug mode",
+    type: newTypeSpec("boolean"),
+    required: false,
+    default: false,
+  },
+  debugLevel: {
+    short: "D",
+    param: "level",
+    description: "Debug level",
+    type: newTypeSpec("number"),
+    required: false,
+    default: 0,
+  },
+})
+
+const ConfigurationPriorityKeys = Object.freeze(["exclude", "input"])
+
+export {ConfigurationParameters, ConfigurationPriorityKeys}

package/src/core/Conveyor.js

@@ -0,0 +1,113 @@
+import * as FDUtil from "./util/FDUtil.js"
+
+const {readFile, writeFile, composeFilename} = FDUtil
+
+export default class Conveyor {
+  #succeeded = []
+  #errored = []
+
+  constructor(parser, printer, logger, output) {
+    this.parser = parser
+    this.printer = printer
+    this.logger = logger
+    this.output = output
+  }
+
+  /**
+   * Processes files with a concurrency limit.
+   *
+   * @param {Array} files - List of files to process.
+   * @param {number} maxConcurrent - Maximum number of concurrent tasks.
+   * @returns {Promise<object>} - Resolves when all files are processed.
+   */
+  async convey(files, maxConcurrent = 10) {
+    const semaphore = Array(maxConcurrent).fill(Promise.resolve())
+
+    for(const file of files) {
+      const slot = Promise.race(semaphore) // Wait for an available slot
+      semaphore.push(slot.then(async() => {
+        const result = await this.#processFile(file)
+
+        if(result.status === "success")
+          this.#succeeded.push({input: file, output: result.file})
+        else
+          this.#errored.push({input: file, error: result.error})
+      }))
+      semaphore.shift() // Remove the oldest promise
+    }
+
+    // Wait for all tasks to complete
+    await Promise.all(semaphore)
+
+    return {succeeded: this.#succeeded, errored: this.#errored}
+  }
+
+  /**
+   * Processes a single file.
+   *
+   * @param {object} file - FileMap object representing a file.
+   * @returns {Promise<object>} - Resolves when the file is processed
+   */
+  async #processFile(file) {
+    const debug = this.logger.newDebug()
+
+    try {
+      debug("Processing file: `%s`", 2, file.path)
+
+      // Step 1: Read file
+      const fileContent = await readFile(file)
+      debug("Read file content `%s` (%d bytes)", 2, file.path, fileContent.length)
+
+      // Step 2: Parse file
+      const parseResult = await this.parser.parse(file, fileContent)
+      if(parseResult.status === "error")
+        return parseResult
+
+      debug("Parsed file successfully: `%s`", 2, file.path)
+
+      // Step 3: Print file
+      const printResult = await this.printer.print(
+        file,
+        parseResult.result,
+      )
+      if(printResult.status === "error")
+        return printResult
+
+      debug("Printed file successfully: `%s`", 2, file.path)
+
+      // Step 4: Write output
+      const {destFile, content} = printResult
+      if(!destFile || !content)
+        return {status: "error", message: "Invalid print result"}
+
+      const writeResult = await this.#writeOutput(destFile, content)
+
+      if(writeResult.status === "success")
+        debug("Wrote output for: `%s` (%d bytes)", 2, file.path, content.length)
+
+      return writeResult
+    } catch(error) {
+      const mess = `Error processing file ${file.path}: ${error.message}\n${error.stack}`
+      this.logger.error(mess)
+      return {status: "error", error}
+    }
+  }
+
+  /**
+   * Writes the output to the destination.
+   *
+   * @param {string} destFile - Destination file path.
+   * @param {string} content - File content.
+   * @returns {Promise<object>} - Resolves when the file is written.
+   */
+  async #writeOutput(destFile, content) {
+    const destFileMap = composeFilename(this.output.path, destFile)
+    try {
+      writeFile(destFileMap, content)
+
+      return {status: "success", file: destFileMap}
+    } catch(error) {
+      return {status: "error", output: destFileMap, error}
+    }
+  }
+}