@gesslar/bedoc 1.1.0 → 1.3.0

package/src/core/Core.js

@@ -1,7 +1,7 @@
 import process from "node:process"
 
 import Discovery from "./Discovery.js"
-import {HooksManager} from "./HooksManager.js"
+import HookManager from "./HookManager.js"
 import Logger from "./Logger.js"
 import ParseManager from "./action/ParseManager.js"
 import PrintManager from "./action/PrintManager.js"
@@ -33,100 +33,85 @@ export default class Core {
   }
 
   static async new({options, source}) {
-    const configuration = new Configuration()
+    const config = new Configuration()
 
-    const validatedConfig = await configuration.validate({options, source})
-    if(validatedConfig.status === "error")
-      throw new AggregateError(validatedConfig.errors, "BeDoc configuration failed")
+    const validConfig = await config.validate({options, source})
+    if(validConfig.status === "error")
+      throw new AggregateError(validConfig.errors,"BeDoc configuration failed")
 
-    const instance = new Core({...validatedConfig, name: "BeDoc"})
+    const instance = new Core({...validConfig, name: "BeDoc"})
     const debug = instance.logger.newDebug()
 
-    debug("Creating new BeDoc instance with options: `%o`", 2, validatedConfig)
+    debug("Creating new BeDoc instance with options: `%o`", 2, validConfig)
 
     const discovery = new Discovery(instance)
-    const actionDefinitions = await discovery.discoverActions()
+    const {printer: validPrint, parser: validParse} = validConfig
 
-    const filteredActions = {
-      parse: [],
-      print: [],
-    }
+    const actionDefs = await discovery.discoverActions({
+      print: validPrint,
+      parse: validParse
+    })
 
-    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 validCrit = discovery.satisfyCriteria(actionDefs, validConfig)
+
+    debug("Actions that met criteria: `%o`", 2, validCrit)
 
-    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(Object.values(validCrit).some(arr => arr.length === 0))
+      throw new Error("No found matching parser and printer")
 
-        if(satisfied.status === "success")
-          matches.push({parse: parser, print: printer})
+    const validSchemas = {print: [], parse: []}
+    let printers = validCrit.print.length
+    while(printers--) {
+      const printer = validCrit.print[printers]
+      const printerSchema = printer.contract
+      const satisfied = []
+      for(const parser of validCrit.parse) {
+        const parserSchema = parser.contract
+        const result = schemaCompare(parserSchema, printerSchema)
+        if(result.status === "success")
+          satisfied.push(parser)
       }
-    }
 
-    // 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)
+      if(satisfied.length > 0) {
+        validSchemas.print.push(printer)
+        validSchemas.parse.push(...satisfied)
+      }
     }
 
-    debug("Found matching actions: `%o`", 3, matches)
-
-    const chosenActions = matches[0]
+    const finalActions = {}
+    for(const [key, value] of Object.entries(validSchemas)) {
+      if(value.length === 0)
+        throw new Error(`No matching ${key} found`)
 
-    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(value.length > 1)
+        throw new Error(`Multiple matching ${key} found`)
 
-    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}`,
-      )
+      finalActions[key] = validSchemas[key][0]
     }
 
     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,
+    instance.actions = {}
+    const managers = {print: PrintManager, parse: ParseManager}
+    for(const [, value] of Object.entries(finalActions)) {
+      const {action: actionType} = value.action.meta
+
+      debug("Attaching `%o` action to instance", 2, actionType)
+      instance.actions[actionType] = new managers[actionType](
+        value, instance.logger
+      )
+
+      if(validConfig.hooks) {
+        const hookManager = await HookManager.new({
+          action: actionType,
+          hooksFile: validConfig.hooks,
           logger: new Logger(instance.debugOptions),
-          timeout: validatedConfig.hooksTimeout,
+          timeout: validConfig.hooksTimeout,
         })
 
-        if(hooks)
-          manager.hooks = hooks
+        if(hookManager)
+          instance.actions[actionType].hookManager = hookManager
       }
     }
 
@@ -135,6 +120,7 @@ export default class Core {
 
   async processFiles(glob, startTime = process.hrtime()) {
     const debug = this.logger.newDebug()
+
     debug("Starting file processing with conveyor", 1)
 
     const {output} = this.options
@@ -145,8 +131,8 @@ export default class Core {
 
     // Instantiate the conveyor
     const conveyor = new Conveyor(
-      this.parser,
-      this.printer,
+      this.actions.parse,
+      this.actions.print,
       this.logger,
       output,
     )
@@ -171,12 +157,16 @@ export default class Core {
 
     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("")
+    if(errored.length > 0) {
+      // const failureRate = ((errored.length / totalFiles) * 100).toFixed(2)
+      // const errorMessage =
+      //   `Errors processing ${errored.length} files [${failureRate}%]`
+      // const errorLines = errored.map(r => {
+      //   const stackLine = log.lastStackLine(r.error, 0)
+      //   return `\n- ${r.input.module}: ${stackLine} - ${r.error.message}`
+      // }).join("")
 
-      this.logger.error(errorMessage)
+      // this.logger(errorMessage+errorLines)
     }
 
     debug("File processing complete", 1)

package/src/core/Discovery.js

@@ -5,30 +5,34 @@ 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
+  #debug
 
   constructor(core) {
     this.core = core
     this.#logger = core.logger
-    debug = this.#logger.newDebug()
+    this.#debug = this.#logger.newDebug()
   }
 
   /**
    * Discover actions from local or global node_modules
    *
+   * @param {object} [specific] Configuration options for action discovery
+   * @param {object} [specific.print] Print-related configuration options
+   * @param {object} [specific.parse] Parse-related configuration options
    * @returns {Promise<object>} A map of discovered modules
    */
-  async discoverActions() {
+  async discoverActions(specific = {}) {
+    const debug = this.#debug
+
+    debug("Discovering actions", 2)
+
     const bucket = []
     const options = this.core.options ?? {}
 
@@ -42,35 +46,53 @@ export default class Discovery {
         ])),
       )
     } else {
-      debug("Discovering actions", 2)
+      debug("Mock path not set, discovering actions in node_modules", 1)
 
-      for(const actionType of actionTypes) {
-        if(this.core.packageJson[actionType]) {
-          const action = this.core.packageJson[actionType]
+      debug("Looking for actions in project's package.json", 2)
+      if(this.core.packageJson?.bedoc?.modules) {
+        const actions = this.core.packageJson?.bedoc?.modules
 
-          debug("Found action in package.json: %o", 3, action)
+        debug("Found %d actions in package.json: %d", 3, actions)
+        debug("Actions found in package.json action in package.json: %o", 3, actions)
 
-          bucket.push(action)
-        }
+        if(actions && typeof(actions) === "object")
+          bucket.push(...actions)
+        else
+          debug("No actions found in package.json", 3)
+      } else {
+        debug("No actions found in project's package.json", 2)
       }
 
+      debug("Looking for actions in node_modules (global and locally installed", 2)
       const directories = [
-        // "c:/temp",
         "./node_modules",
         execSync("npm root -g").toString().trim(),
       ]
 
+      debug("Found %d directories to search for actions", 2, directories.length)
+      debug("Directories to search for actions: %o", 3, directories)
+
       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))
+
+        debug("Found %d directories in `%s`", 2,
+          dirs.length, moduleDirectory.absolutePath
+        )
+
+        const bedocDirs = dirs.filter(d => d.name.startsWith("bedoc-"))
+        debug("Found %d bedoc directories under %s", 2, bedocDirs.length, moduleDirectory.absolutePath)
+
+        const exports = bedocDirs.map(d => this.#getModuleExports(d))
+        debug("Found %d module exports under %s", 2, exports.length, moduleDirectory.absolutePath)
+
         bucket.push(...exports.flat())
       }
     }
 
-    return await this.#loadActionsAndContracts(bucket)
+    debug("Discovered %d actions", 2, bucket.length)
+
+    return await this.#loadActionsAndContracts(bucket, specific)
   }
 
   /**
@@ -80,11 +102,18 @@ export default class Discovery {
    * @returns {object[]} The discovered module exports
    */
   #getModuleExports(dirMap) {
+    const debug = this.#debug
+    debug("Getting module exports from `%s`", 3, dirMap.absolutePath)
+
     const packageJsonFile = resolveFilename("package.json", dirMap)
+    debug("Loading package.json from `%s`", 3, packageJsonFile.absolutePath)
+
     const packageJson = loadJson(packageJsonFile)
+    debug("Loaded package.json from `%s`", 3, packageJsonFile.absolutePath)
+
     const bedocPackageJsonModules = packageJson.bedoc?.modules ?? []
-    const bedocModuleFiles = bedocPackageJsonModules.map((file) =>
-      resolveFilename(file, dirMap),
+    const bedocModuleFiles = bedocPackageJsonModules.map(file =>
+      resolveFilename(file, dirMap)
     )
 
     return bedocModuleFiles
@@ -95,68 +124,114 @@ export default class Discovery {
    * respective contracts.
    *
    * @param {object[]} moduleFiles The module file objects to process
+   * @param {object} specific The specific actions to load
    * @returns {Promise<object>} The discovered action
    */
-  async #loadActionsAndContracts(moduleFiles) {
+  async #loadActionsAndContracts(moduleFiles, specific) {
+    const debug = this.#debug
+
+    debug("Loading actions and contracts", 2)
+    debug("Loading %d module files", 2, moduleFiles.length)
+    debug("Specific actions to load: %o", 2, specific)
+
     const resultActions = {}
+    actionTypes.forEach(actionType => (resultActions[actionType] = []))
+
+    // Tag the specific actions to load, so we can filter them later
+    for(const [type, file] of Object.entries(specific)) {
+      if(file) {
+        debug("Tagging specific action `%s` as `%s`", 3, file.absolutePath, type)
+        file.specificType = type
+      }
+    }
+
+    const toLoad = [
+      ...moduleFiles,
+      ...Object.values(specific).filter(Boolean),
+    ]
+
+    debug("Loading %d combined actions", 2, toLoad.length)
+    debug("Actions to load: %o", 3, toLoad)
+
+    const loadedActions = []
+    for(const file of toLoad) {
+      debug("Loading module `%s`", 2, file.absolutePath)
 
-    actionTypes.forEach((actionType) => (resultActions[actionType] = []))
+      const loading = await this.#loadModule(file)
+      const loaded = loading.actions.map((action, index) => {
+        const contract = yaml.parse(loading.contracts[index])
 
-    for(const moduleFile of moduleFiles) {
-      const result = {total: 0, accepted: 0}
-      const {actions, contracts} = await import(moduleFile.absoluteUri)
+        return {file, action, contract}
+      })
+      loadedActions.push(...loaded)
+    }
+
+    debug("Loaded %d actions", 2, loadedActions.length)
 
-      debug("Loaded actions from `%s`", 2, moduleFile.absoluteUri)
-      debug("Found %d actions and %d contracts", 3, actions.length, contracts.length)
+    const filtered = []
+    for(const actionType of actionTypes) {
+      const file = specific[actionType]
+      const matchingActions = []
+      if(file) {
+        debug("Filtering actions for specific `%s`", 2, actionType)
+        const found = loadedActions.find(
+          e => e.file.absolutePath === file.absolutePath
+        )
+
+        if(!found)
+          throw new Error(`Could not find specific action: ${file.absolutePath}`)
+
+        matchingActions.push(found)
+      } else {
+        debug("No specific action required for `%s`", 2, actionType)
+
+        const found = loadedActions.filter(
+          e => e.action.meta.action === actionType
+        )
+        matchingActions.push(...found)
+      }
 
-      assert(
-        actions.length === contracts.length,
-        "Actions and contracts must be the same length",
-        1,
+      debug("Filtered %d actions for `%s`", 2,
+        matchingActions.length, actionType
       )
 
-      result.total = actions.length
+      filtered.push(...matchingActions)
+    }
 
-      for(let i = actions.length; i--; ) {
-        const tempContract = contracts[i]
+    debug("Filtered %d actions", 2, filtered.length)
 
-        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}`)
+    // Now check the metas for validity
+    for(const e of filtered) {
+      const {action, contract, file: moduleFile} = e
+      const meta = action.meta
+      if(!meta)
+        throw new TypeError("Action has no meta object:\n" +
+          JSON.stringify(moduleFile, null, 2) + "\n" +
+          JSON.stringify(action, null, 2))
 
-        const curr = {
-          module: moduleFile.module,
-          action: actions[i],
-          contract: contracts[i],
-        }
+      const metaAction = meta.action
+      if(!metaAction)
+        throw new TypeError("Action has no meta action:\n" +
+          JSON.stringify(moduleFile, null, 2) + "\n" +
+          JSON.stringify(action, null, 2))
 
-        const meta = curr.action.meta
-        const metaAction = meta?.action
+      debug("Checking action `%s`", 2, metaAction)
 
-        debug("Checking action `%s`", 2, metaAction)
+      const isValid = this.#validMeta(metaAction, {action, contract})
 
-        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")
+      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)
-          }
-        }
+      if(isValid) {
+        debug("Action is a valid `%s` action", 3, metaAction)
 
-        debug("Processed action `%s`", 2, metaAction)
-        debug("Result: %d/%d actions accepted", 3, result.accepted, result.total)
+        resultActions[metaAction].push({file: moduleFile, action, contract})
+      } else {
+        debug("Action is not a valid `%s` action", 3, metaAction)
       }
 
-      debug("Processed %d actions from `%s`", 2, result.total, moduleFile.module)
+      debug("Processed action `%s`", 2, metaAction)
     }
 
     for(const actionType of actionTypes) {
@@ -168,13 +243,92 @@ export default class Discovery {
       return acc + resultActions[curr].length
     }, 0)
 
-    debug("Loaded %d action definitions from %d modules", 2, total, moduleFiles.length)
+    debug("Loaded %d action definitions from %d modules", 2,
+      total, moduleFiles.length
+    )
 
     return resultActions
   }
 
-  validMeta(actionType, toValidate) {
+  satisfyCriteria(actions, validatedConfig) {
+    const debug = this.#debug
+    const satisfied = {parse: [], print: []}
+    const toMatch = {
+      parse: {criterion: "language", config: "parser"},
+      print: {criterion: "format", config: "printer"}
+    }
+
+    debug("Satisfying criteria for actions", 2)
+    for(const [actionType, search] of Object.entries(toMatch)) {
+      debug("Satisfying criteria for `%s` actions", 2, actionType)
+
+      const {criterion, config} = search
+      debug("Criterion: %s, Config: %s", 3, criterion, config)
+
+      // First let's check if we wanted something specific
+      if(validatedConfig[config]) {
+        debug("Checking for specific `%s` action", 3, actionType)
+        const found = actions[actionType].find(
+          a => a.file.specificType === actionType
+        )
+        if(found) {
+          debug("Found specific `%s` action", 3, actionType)
+          satisfied[actionType].push(found)
+          continue
+        }
+
+        debug("No specific `%s` action found", 3, actionType)
+      }
+
+      // Hmm! We didn't find anything specific. Let's check the criterion
+      debug("Checking for `%s` actions with criterion `%s`", 3, actionType, criterion)
+      const found = actions[actionType].filter(a => {
+        debug("Meta criterion value: %o", 4, a.action.meta[criterion])
+        debug("Config criterion value: %o", 4, validatedConfig[criterion])
+        return a.action.meta[criterion] === validatedConfig[criterion]
+      })
+
+      debug("Found %d `%s` actions with criterion `%s`", 3,
+        found.length, actionType, criterion
+      )
+
+      // Shove them into the result!
+      satisfied[actionType].push(...found)
+
+      // That should about cover it!
+    }
+
+    return satisfied
+  }
+
+  /**
+   * Load a module and return its exports
+   *
+   * @param {object} module The module object to load
+   * @returns {Promise<object>} The module exports {actions, contracts}
+   */
+  async #loadModule(module) {
+    const debug = this.#debug
+
+    debug("Loading module `%j`", 2, module)
+
+    const {absoluteUri} = module
+    const moduleExports = await import(absoluteUri)
+
+    return {file: module, ...moduleExports}
+  }
+
+  /**
+   * Validates the meta requirements for an action
+   *
+   * @param {string} actionType The action type to validate
+   * @param {object} toValidate - The action object to validate
+   * @returns {boolean} Whether the action object meets the meta requirements
+   */
+  #validMeta(actionType, toValidate) {
+    const debug = this.#debug
     debug("Checking meta requirements for `%s`", 3, actionType)
+
     const requirements = actionMetaRequirements[actionType]
     if(!requirements)
       throw new Error(

package/src/core/{HooksManager.js → HookManager.js}

@@ -8,17 +8,17 @@ const {assert} = ValidUtil
 const freeze = Object.freeze
 
 const hookEvents = freeze(["start", "section_load", "enter", "exit", "end"])
-const hookPoints = freeze(
+export const hookPoints = freeze(
   await allocateObject(
     hookEvents.map((event) => event.toUpperCase()),
     hookEvents,
   ),
 )
 
-class HooksManager {
+export default class HookManager {
   #hooksFile = null
   #log = null
-  #hooks = {}
+  #hooks = null
   #action = null
   #timeout = 1
 
@@ -49,11 +49,19 @@ class HooksManager {
     return this.#timeout
   }
 
+  get setup() {
+    return this.hooks?.setup || null
+  }
+
+  get cleanup() {
+    return this.hooks?.cleanup || null
+  }
+
   static async new(arg) {
-    const instance = new HooksManager(arg)
+    const instance = new HookManager(arg)
     const debug = instance.log.newDebug()
 
-    debug("Creating new HooksManager instance with args: `%o`", 2, arg)
+    debug("Creating new HookManager instance with args: `%o`", 2, arg)
 
     const hooksFile = instance.hooksFile
 
@@ -116,7 +124,7 @@ class HooksManager {
         1,
       )
 
-      const hookExecution = await hook.call(this, ...args)
+      const hookExecution = await hook.call(this.hooks, ...args)
       const hookTimeout = this.parent.timeout
       const expireAsync = () =>
         timeoutPromise(
@@ -134,10 +142,3 @@ class HooksManager {
     }
   }
 }
-
-export {
-  // Class
-  HooksManager,
-  // Constants
-  hookPoints,
-}