@gesslar/bedoc 1.0.2 → 1.2.0

package/README.md

@@ -1,13 +1,13 @@
-# BeDoc
-
 [![CodeQL Advanced](https://github.com/gesslar/BeDoc/actions/workflows/codeql.yml/badge.svg)](https://github.com/gesslar/BeDoc/actions/workflows/codeql.yml)
 [![Dependabot Updates](https://github.com/gesslar/BeDoc/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/gesslar/BeDoc/actions/workflows/dependabot/dependabot-updates)
 [![Auto PR and Merge - dev 🤗](https://github.com/gesslar/BeDoc/actions/workflows/autopr-dev.yml/badge.svg?branch=dev)](https://github.com/gesslar/BeDoc/actions/workflows/autopr-dev.yml)
 
-
 # BeDoc
 
-**BeDoc** is a powerful, pluggable documentation generator designed to handle any programming language and output format. With its extensible framework, you can easily create custom parsers and printers to generate structured documentation for your projects.
+**BeDoc** is a powerful, pluggable documentation generator designed to handle
+any programming language and output format. With its extensible framework, you
+can easily create custom parsers and printers to generate structured
+documentation for your projects.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "main": "./src/core/Core.js",
@@ -27,7 +27,6 @@
     "globby": "^14.0.2",
     "micromatch": "^4.0.8",
     "node-fetch": "^3.3.2",
-    "vscode-uri": "^3.0.8",
     "yaml": "^2.7.0"
   },
   "devDependencies": {

package/src/cli.js

@@ -63,7 +63,7 @@ const {resolveDirectory} = FDUtil
     }
 
     // Create core instance with validated config
-    BeDoc
+    const bedoc = await BeDoc
       .new({
         options: {
           ...optionsWithSources,
@@ -72,19 +72,20 @@ const {resolveDirectory} = FDUtil
         },
         source: Environment.CLI
       })
-  } catch(e) {
-    if(e instanceof Error) {
-      if(e instanceof AggregateError) {
-        for(const error of e.errors) {
-          console.error(`Error: ${error.message}`)
-        }
-      } else if(e.stack) {
-        console.error(e.stack)
+    const filesToProcess = bedoc.options.input.map(f => f.absolutePath)
+    const result = await bedoc.processFiles(filesToProcess)
+    const errored = result.errored
+    if(errored.length > 0)
+      throw new AggregateError(errored.map(e => e.error), "Error processing files")
+  } catch(error) {
+    if(error instanceof Error) {
+      if(error instanceof AggregateError) {
+        error.errors.forEach(e => console.error(e))
       } else {
-        console.error(`Error: ${e.message}`)
+        console.error(error.message, error.stack)
       }
     } else {
-      console.error(`Error: ${e}`)
+      console.error("Error: %o", error)
     }
 
     process.exit(1)

package/src/core/ActionManager.js

@@ -1,27 +1,26 @@
-import {hookPoints} from "./HooksManager.js"
+import {hookPoints} from "./HookManager.js"
 
 export default class ActionManager {
   #action = null
-  #meta = {}
-  #hooks = null
+  #hookManager = null
   #contract
-  #module
   #log
   #debug
+  #file
 
   constructor(actionDefinition, logger) {
     this.#log = logger
     this.#debug = this.#log.newDebug()
 
-    this.#setupAction(actionDefinition)
+    this.#initialize(actionDefinition)
   }
 
-  #setupAction(actionDefinition) {
+  #initialize(actionDefinition) {
     const debug = this.#debug
 
     debug("Setting up action", 2)
 
-    const {action, contract, module, meta} = actionDefinition
+    const {action, file, contract} = actionDefinition
 
     if(!action)
       throw new Error("Action is required")
@@ -29,13 +28,9 @@ export default class ActionManager {
     if(!contract)
       throw new Error("Contract is required")
 
-    if(!module)
-      throw new Error("Module is required")
-
-    this.#module = module
     this.#action = action
     this.#contract = contract
-    this.#meta = meta
+    this.#file = file
 
     debug("Action setup complete", 2)
   }
@@ -44,33 +39,101 @@ export default class ActionManager {
     return this.#action
   }
 
-  get hooks() {
-    return this.#hooks
+  get hookManager() {
+    return this.#hookManager
   }
 
-  set hooks(hookManager) {
-    if(this.hooks)
+  set hookManager(hookManager) {
+    if(this.hookManager)
       throw new Error("Hooks already set")
 
     this.action.hook = hookManager.on.bind(this.action)
     this.action.HOOKS = hookPoints
+    this.#hookManager = hookManager
     this.action.hooks = hookManager.hooks
-    this.#hooks = hookManager
   }
 
   get contract() {
     return this.#contract
   }
 
-  get module() {
-    return this.#module
-  }
-
   get meta() {
-    return this.#meta
+    return this.#action.meta
   }
 
   get log() {
     return this.#log
   }
+
+  async #setupAction() {
+    const setup = this.action?.setup
+
+    if(!setup)
+      return
+
+    await this.action.setup.call(
+      this.action, {parent: this, log: this.#log}
+    )
+  }
+
+  async #cleanupAction() {
+    const cleanup = this.action?.cleanup
+
+    if(!cleanup)
+      return
+
+    await this.action.cleanup.call(this.action)
+  }
+
+  async #setupHooks() {
+    const setup = this.hookManager?.setup
+
+    if(!setup)
+      return
+
+    await this.hookManager.setup.call(
+      this.hookManager.hooks, {parent: this.action, log: this.#log}
+    )
+  }
+
+  async #cleanupHooks() {
+    const cleanup = this.hookManager?.cleanup
+
+    if(!cleanup)
+      return
+
+    await this.hookManager.cleanup.call(this.hookManager.hooks)
+  }
+
+  async setupAction() {
+    this.#debug("Setting up action for %s", 2, this.meta.action)
+
+    await this.#setupHooks()
+    await this.#setupAction()
+  }
+
+  async runAction({file,content}) {
+    const func = this.action.run
+
+    if(!func)
+      throw new Error(`No \`run\` function found for action \`${this.meta.action}\``)
+
+    const actionResult = await func.call(
+      this.action, {module: file.module, content}
+    )
+
+    return actionResult
+  }
+
+  async cleanupAction() {
+    this.#debug("Post action", 2)
+    this.#debug("Cleaning up action for %s", 2, this.meta.action)
+
+    await this.#cleanupHooks()
+    await this.#cleanupAction()
+  }
+
+  toString() {
+    return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
+  }
 }

package/src/core/Configuration.js

@@ -159,6 +159,12 @@ export default class Configuration {
       options.packageJson = {value: jsonObj, source}
     }
 
+    // Add defaults which are missing
+    for(const [key, param] of Object.entries(ConfigurationParameters)) {
+      if(options[key] === undefined && param.default !== undefined)
+        options[key] = {value: param.default, source: "default"}
+    }
+
     return options
   }
 

package/src/core/Conveyor.js

@@ -6,9 +6,9 @@ export default class Conveyor {
   #succeeded = []
   #errored = []
 
-  constructor(parser, printer, logger, output) {
-    this.parser = parser
-    this.printer = printer
+  constructor(parse, print, logger, output) {
+    this.parse = parse
+    this.print = print
     this.logger = logger
     this.output = output
   }
@@ -23,11 +23,14 @@ export default class Conveyor {
   async convey(files, maxConcurrent = 10) {
     const semaphore = Array(maxConcurrent).fill(Promise.resolve())
 
+    // Set up the actions
+    await this.parse.setupAction()
+    await this.print.setupAction()
+
     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
@@ -39,6 +42,10 @@ export default class Conveyor {
     // Wait for all tasks to complete
     await Promise.all(semaphore)
 
+    // Clean up actions
+    await this.parse.cleanupAction()
+    await this.print.cleanupAction()
+
     return {succeeded: this.#succeeded, errored: this.#errored}
   }
 
@@ -50,6 +57,7 @@ export default class Conveyor {
    */
   async #processFile(file) {
     const debug = this.logger.newDebug()
+    const {parse, print} = this
 
     try {
       debug("Processing file: `%s`", 2, file.path)
@@ -59,17 +67,20 @@ export default class Conveyor {
       debug("Read file content `%s` (%d bytes)", 2, file.path, fileContent.length)
 
       // Step 2: Parse file
-      const parseResult = await this.parser.parse(file, fileContent)
+      const parseResult = await parse.runAction({
+        file,
+        content: 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(
+      const printResult = await print.runAction({
         file,
-        parseResult.result,
-      )
+        content: parseResult.result,
+      })
       if(printResult.status === "error")
         return printResult
 
@@ -87,9 +98,7 @@ export default class Conveyor {
 
       return writeResult
     } catch(error) {
-      const mess = `Error processing file ${file.path}: ${error.message}\n${error.stack}`
-      this.logger.error(mess)
-      return {status: "error", error}
+      return {status: "error", file, error}
     }
   }
 

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,32 @@ 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[]} specified The specified actions to discover
    * @returns {Promise<object>} A map of discovered modules
    */
-  async discoverActions() {
+  async discoverActions({print, parse} = {}) {
+    const debug = this.#debug
+
+    debug("Discovering actions", 2)
+
     const bucket = []
     const options = this.core.options ?? {}
 
@@ -42,35 +44,55 @@ 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, {print: print, parse: parse}
+    )
   }
 
   /**
@@ -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),
+    ]
 
-    actionTypes.forEach((actionType) => (resultActions[actionType] = []))
+    debug("Loading %d combined actions", 2, toLoad.length)
+    debug("Actions to load: %o", 3, toLoad)
 
-    for(const moduleFile of moduleFiles) {
-      const result = {total: 0, accepted: 0}
-      const {actions, contracts} = await import(moduleFile.absoluteUri)
+    const loadedActions = []
+    for(const file of toLoad) {
+      debug("Loading module `%s`", 2, file.absolutePath)
 
-      debug("Loaded actions from `%s`", 2, moduleFile.absoluteUri)
-      debug("Found %d actions and %d contracts", 3, actions.length, contracts.length)
+      const loading = await this.#loadModule(file)
+      const loaded = loading.actions.map((action, index) => {
+        const contract = yaml.parse(loading.contracts[index])
+
+        return {file, action, contract}
+      })
+      loadedActions.push(...loaded)
+    }
 
-      assert(
-        actions.length === contracts.length,
-        "Actions and contracts must be the same length",
-        1,
+    debug("Loaded %d actions", 2, loadedActions.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)
+      }
+
+      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,
-}

package/src/core/Logger.js

@@ -119,8 +119,8 @@ export default class Logger {
     return `[${this.#name}] ${loggerColours[level]}${tag}${loggerColours.reset}: ${message}`
   }
 
-  lastStackLine(stepsRemoved = 3) {
-    const stack = ErrorStackParser.parse(new Error())
+  lastStackLine(error = new Error(), stepsRemoved = 3) {
+    const stack = ErrorStackParser.parse(error)
     return stack[stepsRemoved]
   }
 

package/src/core/action/ParseManager.js

@@ -4,23 +4,4 @@ export default class ParseManager extends ActionManager {
   constructor(actionDefinition, logger) {
     super(actionDefinition, logger)
   }
-
-  async parse(fileMap, content) {
-    const log = this.log
-    const debug = log.newDebug()
-
-    debug("Parsing file `%j`", 3, fileMap)
-
-    if(this.action.init)
-      this.action.init({parent: this, log})
-
-    if(!this.action.parse)
-      throw new Error(`No parse function found for action: ${this.module}`)
-
-    const result = await this.action.parse(fileMap.path, content)
-
-    debug("Parse complete of file `%j`", 3, fileMap)
-
-    return result
-  }
 }

package/src/core/action/PrintManager.js

@@ -4,23 +4,4 @@ export default class PrintManager extends ActionManager {
   constructor(actionDefinition, logger) {
     super(actionDefinition, logger)
   }
-
-  async print(fileMap, content) {
-    const log = this.log
-    const debug = log.newDebug()
-
-    debug("Printing data for `%s`", 3, fileMap.module)
-
-    if(this.action.init)
-      this.action.init({parent: this, log})
-
-    if(!this.action.print)
-      throw new Error(`No print function found for action: ${this.module}`)
-
-    const result = await this.action.print(fileMap.module, content)
-
-    debug("Print complete for `%s`", 3, fileMap.module)
-
-    return result
-  }
 }