@gesslar/bedoc 1.0.0

package/src/core/Core.js

@@ -0,0 +1,186 @@
+import process from "node:process"
+
+import Discovery from "./Discovery.js"
+import {HooksManager} from "./HooksManager.js"
+import Logger from "./Logger.js"
+import ParseManager from "./action/ParseManager.js"
+import PrintManager from "./action/PrintManager.js"
+import Conveyor from "./Conveyor.js"
+import Configuration from "./Configuration.js"
+
+import * as ActionUtil from "./util/ActionUtil.js"
+import * as DataUtil from "./util/DataUtil.js"
+import * as FDUtil from "./util/FDUtil.js"
+
+const {loadPackageJson} = ActionUtil
+const {schemaCompare} = DataUtil
+const {getFiles} = FDUtil
+
+export const Environment = Object.freeze({
+  EXTENSION: "extension",
+  NPM: "npm",
+  ACTION: "action",
+  CLI: "cli",
+})
+
+export default class Core {
+  constructor(options) {
+    this.options = options
+    const {debug: debugMode, debugLevel} = options
+    this.logger = new Logger({name: "BeDoc", debugMode, debugLevel})
+    this.packageJson = loadPackageJson()?.bedoc ?? {}
+    this.debugOptions = this.logger.options
+  }
+
+  static async new({options, source}) {
+    const configuration = new Configuration()
+
+    const validatedConfig = await configuration.validate({options, source})
+    if(validatedConfig.status === "error")
+      throw new AggregateError(validatedConfig.errors, "BeDoc configuration failed")
+
+    const instance = new Core({...validatedConfig, name: "BeDoc"})
+    const debug = instance.logger.newDebug()
+
+    debug("Creating new BeDoc instance with options: `%o`", 2, validatedConfig)
+
+    const discovery = new Discovery(instance)
+    const actionDefinitions = await discovery.discoverActions()
+
+    const filteredActions = {
+      parse: [],
+      print: [],
+    }
+
+    for(const search of [{parse: "language", print: "format"}]) {
+      for(const [actionType, criterion] of Object.entries(search)) {
+        filteredActions[actionType] = actionDefinitions[actionType].filter(
+          (a) => a.action.meta[criterion] === validatedConfig[criterion],
+        )
+      }
+    }
+
+    const matches = []
+    // Now let us find the ones that agree to a contract
+    for(const printer of filteredActions.print) {
+      for(const parser of filteredActions.parse) {
+        const satisfied = schemaCompare(parser.contract, printer.contract)
+
+        if(satisfied.status === "success")
+          matches.push({parse: parser, print: printer})
+      }
+    }
+
+    // We only want one!
+    if(matches.length > 1) {
+      const message =
+        `Multiple matching actions found: ` +
+        `${matches.map((m) => m.print.name).join(", ")}`
+      throw new Error(message)
+    }
+
+    debug("Found matching actions: `%o`", 3, matches)
+
+    const chosenActions = matches[0]
+
+    if(Object.values(chosenActions).some(a => !a))
+      throw new Error("No found matching parser and printer")
+
+    const satisfied = schemaCompare(
+      chosenActions.parse.contract,
+      chosenActions.print.contract,
+    )
+
+    if(satisfied.status === "error") {
+      instance.logger.error(
+        `[Core.new] action contract failed: ${satisfied.errors}`,
+      )
+      throw new AggregateError(satisfied.errors, "Action contract failed")
+    } else if(satisfied.status !== "success") {
+      throw new Error(
+        `[Core.new] Action contract failed: ${satisfied.message}`,
+      )
+    }
+
+    debug("Contracts satisfied between parser and printer", 2)
+
+    // Adding to instance
+    debug("Attaching parse action to instance: `%o`", 2, chosenActions.parse.module)
+    instance.parser = new ParseManager(chosenActions.parse, instance.logger)
+
+    debug("Attaching print action to instance: `%o`", 2, chosenActions.print.module)
+    instance.printer = new PrintManager(chosenActions.print, instance.logger)
+
+    // Setup and attach hooks
+    for(const target of [
+      {manager: instance.parser, action: "parse"},
+      {manager: instance.printer, action: "print"},
+    ]) {
+      if(validatedConfig.hooks) {
+        const {manager, action} = target
+        const hooks = await HooksManager.new({
+          action: action,
+          hooksFile: validatedConfig.hooks,
+          logger: new Logger(instance.debugOptions),
+          timeout: validatedConfig.hooksTimeout,
+        })
+
+        if(hooks)
+          manager.hooks = hooks
+      }
+    }
+
+    return instance
+  }
+
+  async processFiles(glob, startTime = process.hrtime()) {
+    const debug = this.logger.newDebug()
+    debug("Starting file processing with conveyor", 1)
+
+    const {output} = this.options
+
+    const input = await getFiles(glob)
+    if(!input?.length)
+      throw new Error("No input files specified")
+
+    // Instantiate the conveyor
+    const conveyor = new Conveyor(
+      this.parser,
+      this.printer,
+      this.logger,
+      output,
+    )
+
+    const processStart = process.hrtime()
+
+    // Initiate the conveyor
+    const result = await conveyor.convey(input, this.options.maxConcurrent)
+
+    debug("Conveyor complete", 1)
+
+    const endTime = (process.hrtime(startTime)[1] / 1_000_000).toFixed(2)
+    const processEnd = (process.hrtime(processStart)[1] / 1_000_000).toFixed(2)
+
+    // Grab the results
+    const totalFiles = input.length
+    const errored = result.errored
+    const succeeded = result.succeeded
+
+    const message = `Processed ${totalFiles} files: ${succeeded.length} succeeded, ${errored.length} errored ` +
+      `in ${processEnd}ms [total: ${endTime}ms]`
+
+    this.logger.debug(message, 1)
+
+    if(errored. length > 0) {
+      const failureRate = ((errored.length / totalFiles) * 100).toFixed(2)
+      const errorMessage = `Errors processing ${errored.length} files [${failureRate}%]` +
+        errored.map(r => `\n- ${r.file.module}: ${r.result.message}`).join("")
+
+      this.logger.error(errorMessage)
+    }
+
+    debug("File processing complete", 1)
+
+    return result
+  }
+}

package/src/core/Discovery.js

@@ -0,0 +1,208 @@
+// import {process} from "node:process"
+import yaml from "yaml"
+import {execSync} from "child_process"
+
+import * as FDUtil from "./util/FDUtil.js"
+import * as ActionUtil from "./util/ActionUtil.js"
+import * as DataUtil from "./util/DataUtil.js"
+import * as ValidUtil from "./util/ValidUtil.js"
+
+const {ls, resolveDirectory, resolveFilename, getFiles} = FDUtil
+const {actionTypes, actionMetaRequirements, loadJson} = ActionUtil
+const {isType} = DataUtil
+const {assert} = ValidUtil
+
+let debug
+
+export default class Discovery {
+  #logger
+
+  constructor(core) {
+    this.core = core
+    this.#logger = core.logger
+    debug = this.#logger.newDebug()
+  }
+
+  /**
+   * Discover actions from local or global node_modules
+   *
+   * @returns {Promise<object>} A map of discovered modules
+   */
+  async discoverActions() {
+    const bucket = []
+    const options = this.core.options ?? {}
+
+    if(options?.mockPath) {
+      debug("Discovering mock actions in `%s`", 1, options.mockPath)
+
+      bucket.push(
+        ...(await getFiles([
+          `${options.mockPath}/bedoc-*-printer.js`,
+          `${options.mockPath}/bedoc-*-parser.js`,
+        ])),
+      )
+    } else {
+      debug("Discovering actions", 2)
+
+      for(const actionType of actionTypes) {
+        if(this.core.packageJson[actionType]) {
+          const action = this.core.packageJson[actionType]
+
+          debug("Found action in package.json: %o", 3, action)
+
+          bucket.push(action)
+        }
+      }
+
+      const directories = [
+        // "c:/temp",
+        "./node_modules",
+        execSync("npm root -g").toString().trim(),
+      ]
+
+      const moduleDirectories = directories.map(resolveDirectory)
+      for(const moduleDirectory of moduleDirectories) {
+        const {directories: dirs} = await ls(moduleDirectory.absolutePath)
+        debug("Found %d directories in `%s`", 2, dirs.length, moduleDirectory.absolutePath)
+        const bedocDirs = dirs.filter((d) => d.name.startsWith("bedoc-"))
+        const exports = bedocDirs.map((d) => this.#getModuleExports(d))
+        bucket.push(...exports.flat())
+      }
+    }
+
+    return await this.#loadActionsAndContracts(bucket)
+  }
+
+  /**
+   * Get the exports from a module's package.json file, resolved to file paths
+   *
+   * @param {object} dirMap The directory map object
+   * @returns {object[]} The discovered module exports
+   */
+  #getModuleExports(dirMap) {
+    const packageJsonFile = resolveFilename("package.json", dirMap)
+    const packageJson = loadJson(packageJsonFile)
+    const bedocPackageJsonModules = packageJson.bedoc?.modules ?? []
+    const bedocModuleFiles = bedocPackageJsonModules.map((file) =>
+      resolveFilename(file, dirMap),
+    )
+
+    return bedocModuleFiles
+  }
+
+  /**
+   * Process the discovered file objects and return the action and their
+   * respective contracts.
+   *
+   * @param {object[]} moduleFiles The module file objects to process
+   * @returns {Promise<object>} The discovered action
+   */
+  async #loadActionsAndContracts(moduleFiles) {
+    const resultActions = {}
+
+    actionTypes.forEach((actionType) => (resultActions[actionType] = []))
+
+    for(const moduleFile of moduleFiles) {
+      const result = {total: 0, accepted: 0}
+      const {actions, contracts} = await import(moduleFile.absoluteUri)
+
+      debug("Loaded actions from `%s`", 2, moduleFile.absoluteUri)
+      debug("Found %d actions and %d contracts", 3, actions.length, contracts.length)
+
+      assert(
+        actions.length === contracts.length,
+        "Actions and contracts must be the same length",
+        1,
+      )
+
+      result.total = actions.length
+
+      for(let i = actions.length; i--; ) {
+        const tempContract = contracts[i]
+
+        if(isType(tempContract, "string"))
+          contracts[i] = yaml.parse(tempContract)
+        else if(isType(tempContract, "object"))
+          contracts[i] = tempContract
+        else
+          throw new Error(`Invalid contract type: ${typeof tempContract}`)
+
+        const curr = {
+          module: moduleFile.module,
+          action: actions[i],
+          contract: contracts[i],
+        }
+
+        const meta = curr.action.meta
+        const metaAction = meta?.action
+
+        debug("Checking action `%s`", 2, metaAction)
+
+        for(const actionType of actionTypes) {
+          const isValid = this.validMeta(actionType, curr)
+          debug("Action `%o` in `%s` is %s", 3, metaAction, moduleFile.module, isValid ? "valid" : "invalid")
+
+          if(isValid && metaAction === actionType) {
+            debug("Action is a valid `%s` action", 3, actionType)
+            result.accepted++
+            resultActions[actionType].push(curr)
+            continue
+          } else {
+            debug("Action is not a valid `%s` action", 3, actionType)
+          }
+        }
+
+        debug("Processed action `%s`", 2, metaAction)
+        debug("Result: %d/%d actions accepted", 3, result.accepted, result.total)
+      }
+
+      debug("Processed %d actions from `%s`", 2, result.total, moduleFile.module)
+    }
+
+    for(const actionType of actionTypes) {
+      const total = resultActions[actionType].length
+      debug("Found %d `%s` actions", 2, total, actionType)
+    }
+
+    const total = Object.keys(resultActions).reduce((acc, curr) => {
+      return acc + resultActions[curr].length
+    }, 0)
+
+    debug("Loaded %d action definitions from %d modules", 2, total, moduleFiles.length)
+
+    return resultActions
+  }
+
+  validMeta(actionType, toValidate) {
+    debug("Checking meta requirements for `%s`", 3, actionType)
+    const requirements = actionMetaRequirements[actionType]
+    if(!requirements)
+      throw new Error(
+        `No meta requirements found for action type \`${actionType}\``,
+      )
+
+    for(const requirement of requirements) {
+      debug("Checking requirement %o", 4, requirement)
+
+      if(isType(requirement, "object")) {
+        for(const [key, value] of Object.entries(requirement)) {
+          debug("Checking object requirement %o", 4, {key, value})
+
+          if(toValidate.action.meta[key] !== value)
+            return false
+
+          debug("Requirement met: %o", 4, {key, value})
+        }
+      } else if(isType(requirement, "string")) {
+        debug("Checking string requirement: %s", 4, requirement)
+
+        if(!toValidate.action.meta[requirement])
+          return false
+
+        debug("Requirement met: %s", 4, requirement)
+      }
+    }
+
+    return true
+  }
+}

package/src/core/HooksManager.js

@@ -0,0 +1,143 @@
+import {setTimeout as timeoutPromise} from "timers/promises"
+import * as DataUtil from "./util/DataUtil.js"
+import * as ValidUtil from "./util/ValidUtil.js"
+
+const {isEmpty, isType, allocateObject} = DataUtil
+const {assert} = ValidUtil
+
+const freeze = Object.freeze
+
+const hookEvents = freeze(["start", "section_load", "enter", "exit", "end"])
+const hookPoints = freeze(
+  await allocateObject(
+    hookEvents.map((event) => event.toUpperCase()),
+    hookEvents,
+  ),
+)
+
+class HooksManager {
+  #hooksFile = null
+  #log = null
+  #hooks = {}
+  #action = null
+  #timeout = 1
+
+  constructor({action, hooksFile, logger, timeOut: timeout}) {
+    this.#action = action
+    this.#hooksFile = hooksFile
+    this.#log = logger
+    this.#timeout = timeout
+  }
+
+  get action() {
+    return this.#action
+  }
+
+  get hooksFile() {
+    return this.#hooksFile
+  }
+
+  get hooks() {
+    return this.#hooks
+  }
+
+  get log() {
+    return this.#log
+  }
+
+  get timeout() {
+    return this.#timeout
+  }
+
+  static async new(arg) {
+    const instance = new HooksManager(arg)
+    const debug = instance.log.newDebug()
+
+    debug("Creating new HooksManager instance with args: `%o`", 2, arg)
+
+    const hooksFile = instance.hooksFile
+
+    debug("Loading hooks from `%s", 2, hooksFile.absoluteUri)
+
+    debug("Checking hooks file exists: %j", 2, hooksFile)
+    const hooksFileContent = await import(hooksFile.absoluteUri)
+
+    debug("Hooks file loaded successfully", 2)
+
+    if(!hooksFileContent)
+      throw new Error(`Hooks file is empty: ${hooksFile.absoluteUri}`)
+
+    const hooks = hooksFileContent.default || hooksFileContent.Hooks
+
+    if(!hooks)
+      throw new Error(`\`${hooksFile.absoluteUri}\` contains no hooks.`)
+
+    const hooksObj = hooks[instance.action]
+    if(isEmpty(hooksObj))
+      return null
+
+    debug("Hooks found for action: `%s`", 2, instance.action)
+
+    if(!hooksObj)
+      return null
+
+    hooksObj.log = instance.log
+    instance.#hooks = hooksObj
+
+    debug("Hooks loaded successfully for `%s`", 2, instance.action)
+
+    return instance
+  }
+
+  /**
+   * Trigger a hook
+   *
+   * @param {string} event - The type of hook to trigger
+   * @param {...any} args - The hook arguments
+   * @returns {Promise<any>} The result of the hook
+   */
+  async on(event, ...args) {
+    const debug = this.log.newDebug()
+
+    debug("Triggering hook for event `%s`", 4, event)
+
+    if(!event)
+      throw new Error("Event type is required for hook invocation")
+
+    if(!hookEvents.includes(event))
+      throw new Error(`[HookManager.on] Invalid event type: ${event}`)
+
+    const hook = this.hooks[event]
+
+    if(hook) {
+      assert(
+        isType(hook, "function"),
+        `[HookManager.on] Hook "${event}" is not a function`,
+        1,
+      )
+
+      const hookExecution = await hook.call(this, ...args)
+      const hookTimeout = this.parent.timeout
+      const expireAsync = () =>
+        timeoutPromise(
+          hookTimeout,
+          new Error(`Hook execution exceeded timeout of ${hookTimeout}ms`),
+        )
+      const result = await Promise.race([hookExecution, expireAsync()])
+
+      if(result?.status === "error")
+        throw result.error
+
+      debug("Hook executed successfully for event: `%s`", 4, event)
+
+      return result
+    }
+  }
+}
+
+export {
+  // Class
+  HooksManager,
+  // Constants
+  hookPoints,
+}