@gesslar/bedoc 1.11.0 → 2.0.0

package/src/core/Discovery.js

@@ -1,403 +0,0 @@
-import {execSync} from "child_process"
-import path from "node:path"
-
-import ContractManager from "./ContractManager.js"
-import * as FDUtil from "./util/FDUtil.js"
-import * as ActionUtil from "./util/ActionUtil.js"
-import * as DataUtil from "./util/DataUtil.js"
-
-const {composeDirectory,directoryExists,resolveDirectory} = FDUtil
-const {newContract,parse} = ContractManager
-const {ls,fileExists,composeFilename,getFiles} = FDUtil
-const {actionTypes, actionMetaRequirements,loadDataFile} = ActionUtil
-const {isType} = DataUtil
-
-export default class Discovery {
-  #logger
-  #debug
-
-  constructor(core) {
-    this.core = core
-    this.#logger = core.logger
-    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(specific = {}) {
-    const debug = this.#debug
-
-    debug("Discovering actions", 2)
-
-    debug("Specific modules provided: %o", 2, Object.values(specific).filter(Boolean).length)
-    debug("Specific modules provided: %o", 3, specific)
-
-    const files = []
-    const options = this.core.options ?? {}
-
-    if(options?.mockPath) {
-      debug("Discovering mock actions in `%s`", 2, options.mockPath)
-
-      files.push(
-        ...(await getFiles([
-          `${options.mockPath}/bedoc-*-printer.js`,
-          `${options.mockPath}/bedoc-*-parser.js`,
-        ])),
-      )
-    } else {
-      debug("Mock path not set, discovering actions in node_modules", 2)
-
-      debug("Looking for actions in project's package.json", 2)
-      if(this.core.packageJson) {
-        const exported = (this.core.packageJson.modules || [])
-          .map(m => composeFilename(options.basePath, m))
-          .flat()
-
-        debug("Found %o modules in project's package.json", 2, exported.length)
-        debug("Found modules in project's package.json: %o", 2, exported)
-
-        files.push(...exported)
-      } else {
-        debug("No modules found in project's package.json", 2)
-      }
-
-      debug("Looking for modules in node_modules (global and locally installed)", 2)
-      const directories = [
-        execSync("npm root").toString().trim(),
-        execSync("npm root -g").toString().trim(),
-      ].filter(Boolean)
-
-      const nodeModulesDirs = directories
-        .map(composeDirectory)
-        .filter(directoryExists)
-
-      debug("Found %o directories to search for actions", 2, directories.length)
-      debug("Directories to search for actions: %o", 3, directories)
-
-      for(const nodeModulesDir of nodeModulesDirs) {
-        const dirsToSearch = []
-        const {directories: moduleDirs} = await ls(nodeModulesDir.absolutePath)
-
-        debug("Found %o directories in %o", 2, moduleDirs.length, nodeModulesDir.absolutePath)
-
-        // Handle scoped packages (e.g., @bedoc/something)
-        const scopedDirs = moduleDirs.filter(d => d.name.startsWith("@"))
-
-        dirsToSearch.push(...moduleDirs)
-
-        // If we find a scope (e.g., "@bedoc"), look inside it for bedoc modules
-        for(const scopedDir of scopedDirs) {
-          const {directories: scopedPackages} = await ls(scopedDir.absolutePath)
-
-          debug("Found %o directories under scoped package %o", 2, directories.length, scopedDir.name)
-          debug("Found directories under scoped package %o\n%o", 2, scopedDir.absolutePath, scopedPackages.map(d => d.absolutePath))
-
-          dirsToSearch.push(...scopedPackages)
-        }
-
-        debug("1 Found %o directories to search for actions", 2, dirsToSearch.length)
-        debug("2 Found directories to search for actions: %o", 3, dirsToSearch)
-
-        const visibleDirs = dirsToSearch.filter(d => !d.name.startsWith("."))
-
-        for(const dir of visibleDirs) {
-          const packageJsonFile = composeFilename(dir, "package.json")
-
-          if(!fileExists(packageJsonFile))
-            continue
-
-          const packageJson = loadDataFile(packageJsonFile)
-          if(!packageJson.bedoc)
-            continue
-
-          const {modules} = packageJson.bedoc ?? null
-          if(!modules || !Array.isArray(modules))
-            continue
-
-          const moduleFiles = modules
-            .map(f => composeFilename(dir, f))
-            .filter(f => fileExists(f))
-
-          debug("Discovered %d modules from package.json file: %o", 2,
-            modules.length,
-            packageJsonFile.absolutePath
-          )
-          debug("Discovered from package.json files: %o", 3, modules)
-
-          files.push(...moduleFiles)
-        }
-      }
-    }
-
-    debug("Discovered %d modules", 2, files.length)
-    debug("Discovered modules", 2, files.map(f => f.path))
-    debug("Discovered modules %o", 3, files)
-
-    // const available = files.map(f => this.#getModuleExports(f))
-
-    return await this.#loadActionsAndContracts(files, specific)
-  }
-
-  /**
-   * Process the discovered file objects and return the action and their
-   * respective contracts.
-   *
-   * @param {object[]} moduleFiles The module file objects to process
-   * @param {object} specificModules The specific modules to load
-   * @returns {Promise<object>} The discovered action
-   */
-  async #loadActionsAndContracts(moduleFiles, specificModules) {
-    const debug = this.#debug
-
-    debug("Loading actions and contracts", 2)
-    debug("Loading %d module files", 2, moduleFiles.length)
-    debug("Specific modules to load: %o", 3, specificModules)
-
-    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(specificModules)) {
-      if(file) {
-        debug("Tagging specific module `%s` as `%s`", 3, file.absolutePath, type)
-        file.specificType = file.specificType || []
-        file.specificType.push(type)
-      }
-    }
-
-    const toLoad = [
-      ...moduleFiles,
-      ...Object.values(specificModules).filter(Boolean),
-    ]
-
-    debug("Loading %d discovered modules", 2, toLoad.length)
-    debug("Modules to load: %o", 3, toLoad)
-
-    const loadedActions = []
-    for(const file of toLoad) {
-      debug("Loading module `%s`", 2, file.absoluteUri)
-
-      const loading = await this.#loadModule(file)
-      for(let index = 0; index < loading.actions.length; index++) {
-        const action = loading.actions[index]
-
-        if(!file.directory)
-          file.directory = resolveDirectory(path.dirname(file.path))
-
-        debug(`Loading %o contract from %o`, 2, action.meta.action, file.path)
-
-        const terms = parse(loading.contracts[index], file.directory)
-        const contract = await newContract(action.meta.action, terms)
-
-        loadedActions.push({file, action, contract})
-      }
-    }
-
-    debug("Loaded %d actions", 2, loadedActions.length)
-    debug("Loaded actions", 3, loadedActions)
-
-    const filteredActions = []
-    for(const actionType of actionTypes) {
-      const module = specificModules[actionType]
-      const matchingActions = []
-      if(module) {
-        debug("Filtering actions for specific: %o", 2, actionType)
-        const found = loadedActions.find(
-          e => e.file.specificType?.includes(actionType) &&
-               e.action.meta?.action === actionType
-        )
-
-        if(!found)
-          throw new Error(`Could not find specific action: ${module.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
-      )
-
-      filteredActions.push(...matchingActions)
-    }
-
-    debug("Filtered %d actions", 2, filteredActions.length)
-    debug("Filtered actions %o", 3, filteredActions)
-
-    // Now check the metas for validity
-    for(const filtered of filteredActions) {
-      const {action, contract, file: moduleFile} = filtered
-      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 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))
-
-      debug("Checking action %o", 2, metaAction)
-
-      const isValid = this.#validMeta(metaAction, {action, contract})
-
-      debug("Meta in action %o in %o is %o", 3,
-        metaAction, moduleFile.module, isValid ? "valid" : "invalid"
-      )
-
-      if(isValid) {
-        debug("Action is a valid `%s` action", 3, metaAction)
-
-        resultActions[metaAction].push({file: moduleFile, action, contract})
-      } else {
-        debug("Action is not a valid `%s` action", 3, metaAction)
-      }
-
-      debug("Processed action `%s`", 2, metaAction)
-    }
-
-    for(const actionType of actionTypes) {
-      const total = resultActions[actionType].length
-      debug("Found %o %o 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
-  }
-
-  satisfyCriteria(actions, validatedConfig) {
-    const debug = this.#debug
-
-    debug("Available actions to check %o", 3, actions)
-
-    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 %o action", 3, actionType)
-        const found = actions[actionType].find(
-          a => a.file.specificType.includes(actionType)
-        )
-        if(found) {
-          debug("Found specific %o 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 %o actions with criterion %o", 3, actionType, criterion)
-      debug("Validated config to check against: %o", 3, validatedConfig)
-      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 %o %o actions with criterion %o", 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 %o", 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/HookManager.js

@@ -1,143 +0,0 @@
-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"])
-export const HookPoints = freeze(
-  await allocateObject(
-    hookEvents.map(event => event.toUpperCase()),
-    hookEvents,
-  ),
-)
-
-export default class HookManager {
-  #hooksFile = null
-  #log = null
-  #hooks = null
-  #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
-  }
-
-  get setup() {
-    return this.hooks?.setup || null
-  }
-
-  get cleanup() {
-    return this.hooks?.cleanup || null
-  }
-
-  static async new(arg) {
-    const instance = new HookManager(arg)
-    const debug = instance.log.newDebug()
-
-    debug("Creating new HookManager 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
-    hooksObj.timeout = this.timeout
-    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 {object} args - The hook arguments as an object
-   * @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(`Invalid event type: ${event}`)
-
-    const hook = this.hooks[event]
-
-    if(hook) {
-      assert(isType(hook, "function"), `Hook "${event}" is not a function`, 1)
-
-      const hookExecution = await hook.call(this.hooks, args)
-      const hookTimeout = this.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
-    } else {
-      return null
-    }
-  }
-}

package/src/core/action/ParseManager.js

@@ -1,7 +0,0 @@
-import ActionManager from "../ActionManager.js"
-
-export default class ParseManager extends ActionManager {
-  constructor(actionDefinition, logger) {
-    super(actionDefinition, logger)
-  }
-}

package/src/core/action/PrintManager.js

@@ -1,7 +0,0 @@
-import ActionManager from "../ActionManager.js"
-
-export default class PrintManager extends ActionManager {
-  constructor(actionDefinition, logger) {
-    super(actionDefinition, logger)
-  }
-}

package/src/core/contract/ParseContract.js

@@ -1,7 +0,0 @@
-import {Contract} from "../ContractManager.js"
-
-export default class ParseContract extends Contract {
-  constructor(actionDefinition, logger) {
-    super(actionDefinition, logger)
-  }
-}

package/src/core/contract/PrintContract.js

@@ -1,7 +0,0 @@
-import {Contract} from "../ContractManager.js"
-
-export default class PrintContract extends Contract {
-  constructor(actionDefinition, logger) {
-    super(actionDefinition, logger)
-  }
-}

package/src/core/util/ActionUtil.js

@@ -1,62 +0,0 @@
-import * as FDUtil from "./FDUtil.js"
-import process from "node:process"
-import JSON5 from "json5"
-import YAML from "yaml"
-
-const {readFile, fileExists, composeFilename} = FDUtil
-
-const freeze = Object.freeze
-
-const actionTypes = freeze(["parse", "print"])
-
-const actionMetaRequirements = freeze({
-  parse: [{action: "parse"}, "language"],
-  print: [{action: "print"}, "format"],
-})
-
-/**
- * Loads an object from JSON or YAML provided a fileMap
- *
- * @param {object} fileMap - The FileObj file to load containing
- *  JSON or YAML text.
- * @returns {object} The parsed data object.
- */
-function loadDataFile(fileMap) {
-  const content = readFile(fileMap)
-
-  try {
-    return JSON5.parse(content)
-  } catch{
-    try {
-      return YAML.parse(content)
-    } catch{
-      throw new Error("Content is neither valid JSON nor valid YAML")
-    }
-  }
-}
-
-/**
- * Loads the package.json file asynchronously
- *
- * @param {string|object|null} basePath - The base path to use
- * @returns {object?} The parsed package.json content or null if the file does
- *                    not exist
- */
-function loadPackageJson(basePath = process.cwd()) {
-  const packageJsonFileObject = composeFilename(basePath, "./package.json")
-  if(fileExists(packageJsonFileObject)) {
-    const jsonContent = readFile(packageJsonFileObject)
-    const json = JSON5.parse(jsonContent)
-    return json
-  } else
-    return null
-}
-
-export {
-  // Constants
-  actionMetaRequirements,
-  actionTypes,
-  // Functions
-  loadDataFile,
-  loadPackageJson,
-}

package/src/core/util/ContractUtil.js

@@ -1,63 +0,0 @@
-import fetch from "node-fetch"
-import JSON5 from "json5"
-import Ajv from "ajv"
-import {fileURLToPath,URL} from "node:url"
-
-import * as FDUtil from "./FDUtil.js"
-
-const {composeFilename,fileExists,readFile,writeFile} = FDUtil
-
-const schemaUrl = "https://bedoc.gesslar.dev/schemas/v1/bedoc.action.json"
-const localSchema = "./dist/bedoc.action.json"
-
-/**
- * Takes a schema and returns a validator function
- *
- * @param {object} schema The schema to compile
- * @returns {Function} The schema validator function
- */
-function getValidator(schema) {
-  const ajv = new Ajv({allErrors: true, verbose: true})
-  const f = ajv.compile(schema)
-
-  return f
-}
-
-/**
- * Downloads and preserves a copy of the action schema
- * within the dist/ folder.
- *
- * @returns {object} The schema validator
- */
-async function fetchSchema() {
-  const response = await fetch(schemaUrl)
-  const schema = await response.text()
-
-  const output = composeFilename(fileURLToPath(new URL("../../../", import.meta.url)), localSchema)
-  writeFile(output, schema)
-
-  return JSON5.parse(schema)
-}
-
-/**
- * Loads a schema from file or fetches it if it is missing.
- *
- * @returns {object} The schema object
- */
-async function loadSchema() {
-  const schemaFile = composeFilename(fileURLToPath(new URL("../../../", import.meta.url)), localSchema)
-
-  if(fileExists(schemaFile)) {
-    const schema = readFile(schemaFile)
-
-    return JSON5.parse(schema)
-  }
-
-  return await fetchSchema()
-}
-
-export {
-  fetchSchema,
-  getValidator,
-  loadSchema,
-}