@gesslar/bedoc 1.5.2 → 1.6.1

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
+  "author": "gesslar",
+  "license": "Unlicense",
   "main": "./src/core/Core.js",
   "repository": {
     "type": "git",
@@ -39,6 +41,7 @@
     "dotenv": "^16.4.7",
     "error-stack-parser": "^2.1.4",
     "globby": "^14.0.2",
+    "json5": "^2.2.3",
     "micromatch": "^4.0.8",
     "node-fetch": "^3.3.2",
     "yaml": "^2.7.0"
@@ -49,8 +52,8 @@
     "@typescript-eslint/parser": "^8.22.0",
     "axios": "^1.7.9",
     "chokidar": "^4.0.3",
-    "eslint-plugin-jsdoc": "^50.6.3",
     "eslint": "^9.18.0",
+    "eslint-plugin-jsdoc": "^50.6.3",
     "form-data": "^4.0.1"
   },
   "keywords": [
@@ -62,19 +65,5 @@
     "language",
     "format",
     "hooks"
-  ],
-  "author": "gesslar",
-  "license": "Unlicense",
-  "contributes": {
-    "commands": [
-      {
-        "command": "vscode-bedoc.generateDocs",
-        "title": "BeDoc: Generate Documentation"
-      }
-    ]
-  },
-  "extensionKind": [
-    "workspace",
-    "ui"
   ]
 }

package/src/cli.js

@@ -72,6 +72,7 @@ const {resolveDirectory} = FDUtil
         },
         source: Environment.CLI
       })
+
     const filesToProcess = bedoc.options.input.map(f => f.absolutePath)
     const result = await bedoc.processFiles(filesToProcess)
     const errored = result.errored

package/src/core/ActionManager.js

@@ -71,9 +71,7 @@ export default class ActionManager {
     if(!setup)
       return
 
-    await this.action.setup.call(
-      this.action, {parent: this, log: this.#log}
-    )
+    await this.action.setup.call(this.action, {log: this.#log})
   }
 
   async #cleanupAction() {

package/src/core/Configuration.js

@@ -1,5 +1,6 @@
 import process from "node:process"
 import {Environment} from "./Core.js"
+import JSON5 from "json5"
 
 import {
   ConfigurationParameters,
@@ -41,7 +42,9 @@ export default class Configuration {
       )
 
     const allOptions = this.#findAllOptions(options)
+
     Object.assign(finalOptions, await this.#mergeOptions(allOptions))
+
     this.#fixOptionValues(finalOptions)
 
     // Priority keys are those which must be processed first. They are
@@ -78,6 +81,12 @@ export default class Configuration {
         )
     }
 
+    // Check for mandatory values
+    for(const [key, {required}] of Object.entries(ConfigurationParameters)) {
+      if(required && !orderedSections.find(s => s.key === key))
+        throw new SyntaxError(`Missing mandatory key \`${key}\``)
+    }
+
     for(const section of orderedSections) {
       const {key} = section
 
@@ -212,12 +221,11 @@ export default class Configuration {
    */
   #findAllOptions(entryOptions) {
     const allOptions = []
-
     const environmentVariables = this.#getEnvironmentVariables()
     if(environmentVariables)
       allOptions.push({source: "environment", options: environmentVariables})
 
-    const packageJson = entryOptions.packageJson
+    const packageJson = entryOptions?.packageJson
     if(packageJson?.bedoc)
       allOptions.push({source: "packageJson", options: packageJson.bedoc})
 
@@ -228,12 +236,16 @@ export default class Configuration {
       environmentVariables?.config
 
     if(useConfig) {
-      const configFilename = packageJson?.bedoc?.config || entryOptions.config
-
-      if(!configFilename)
+      const configFile =
+        packageJson?.bedoc?.config
+          ? resolveFilename(packageJson?.bedoc?.config)
+          : entryOptions.config?.value
+            ? resolveFilename(entryOptions.config.value)
+            : null
+
+      if(!configFile)
         throw new Error("No config file specified")
 
-      const configFile = resolveFilename(configFilename)
       const config = loadJson(configFile)
 
       allOptions.push({source: "config", options: config})
@@ -303,7 +315,7 @@ export default class Configuration {
 
     // Last, but not least, add any defaulted options that are not in the
     // mapped options
-    for(const [key, value] of Object.entries(entryOptions)) {
+    for(const [key, value] of Object.entries(entryOptions ?? {})) {
       if(!mappedOptions[key]) {
         if(value.source)
           mappedOptions[key] = value.value
@@ -329,7 +341,7 @@ export default class Configuration {
           switch(param.type.toString()) {
             case "boolean":
             case "number":
-              options[key] = JSON.parse(options[key])
+              options[key] = JSON5.parse(options[key])
               break
           }
         }

package/src/core/Core.js

@@ -45,11 +45,9 @@ export default class Core {
     debug("Creating new BeDoc instance with options: `%o`", 2, validConfig)
 
     const discovery = new Discovery(instance)
-    const {printer: validPrint, parser: validParse} = validConfig
-
     const actionDefs = await discovery.discoverActions({
-      print: validPrint,
-      parse: validParse
+      print: validConfig.printer,
+      parse: validConfig.parser
     })
 
     const validCrit = discovery.satisfyCriteria(actionDefs, validConfig)
@@ -97,7 +95,7 @@ export default class Core {
     for(const [, value] of Object.entries(finalActions)) {
       const {action: actionType} = value.action.meta
 
-      debug("Attaching `%o` action to instance", 2, actionType)
+      debug("Attaching %o action to instance", 2, actionType)
       instance.actions[actionType] = new managers[actionType](
         value, instance.logger
       )

package/src/core/Discovery.js

@@ -34,6 +34,8 @@ export default class Discovery {
 
     debug("Discovering actions", 2)
 
+    debug("Specific modules provided: %o", 2, specific)
+
     const bucket = []
     const options = this.core.options ?? {}
 
@@ -50,10 +52,10 @@ export default class Discovery {
       debug("Mock path not set, discovering actions in node_modules", 1)
 
       debug("Looking for actions in project's package.json", 2)
-      if(this.core.packageJson?.bedoc?.modules) {
-        const actions = this.core.packageJson?.bedoc?.modules
+      if(this.core.packageJson?.modules) {
+        const actions = this.core.packageJson?.modules
 
-        debug("Found %d actions in package.json: %d", 3, actions)
+        debug("Found %o actions in package.json", 3, actions)
         debug("Actions found in package.json action in package.json: %o", 3, actions)
 
         if(actions && typeof(actions) === "object")
@@ -70,7 +72,7 @@ export default class Discovery {
         execSync("npm root -g").toString().trim(),
       ]
 
-      debug("Found %d directories to search for actions", 2, directories.length)
+      debug("Found %o directories to search for actions", 2, directories.length)
       debug("Directories to search for actions: %o", 3, directories)
 
       const moduleDirectories = directories
@@ -79,15 +81,15 @@ export default class Discovery {
       for(const moduleDirectory of moduleDirectories) {
         const {directories: dirs} = await ls(moduleDirectory.absolutePath)
 
-        debug("Found %d directories in `%s`", 2,
+        debug("Found %o 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)
+        debug("Found %o 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)
+        debug("Found %o module exports under %s", 2, exports.length, moduleDirectory.absolutePath)
 
         bucket.push(...exports.flat())
       }
@@ -127,38 +129,39 @@ export default class Discovery {
    * respective contracts.
    *
    * @param {object[]} moduleFiles The module file objects to process
-   * @param {object} specific The specific actions to load
+   * @param {object} specificModules The specific modules to load
    * @returns {Promise<object>} The discovered action
    */
-  async #loadActionsAndContracts(moduleFiles, specific) {
+  async #loadActionsAndContracts(moduleFiles, specificModules) {
     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)
+    debug("Specific modules to load: %o", 2, 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(specific)) {
+    for(const [type, file] of Object.entries(specificModules)) {
       if(file) {
-        debug("Tagging specific action `%s` as `%s`", 3, file.absolutePath, type)
-        file.specificType = type
+        debug("Tagging specific module `%s` as `%s`", 3, file.absolutePath, type)
+        file.specificType = file.specificType || []
+        file.specificType.push(type)
       }
     }
 
     const toLoad = [
       ...moduleFiles,
-      ...Object.values(specific).filter(Boolean),
+      ...Object.values(specificModules).filter(Boolean),
     ]
 
-    debug("Loading %d combined actions", 2, toLoad.length)
-    debug("Actions to load: %o", 3, toLoad)
+    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.absolutePath)
+      debug("Loading module `%s`", 2, file.absoluteUri)
 
       const loading = await this.#loadModule(file)
       const loaded = loading.actions.map((action, index) => {
@@ -170,19 +173,21 @@ export default class Discovery {
     }
 
     debug("Loaded %d actions", 2, loadedActions.length)
+    debug("Loaded actions", 3, loadedActions)
 
-    const filtered = []
+    const filteredActions = []
     for(const actionType of actionTypes) {
-      const file = specific[actionType]
+      const module = specificModules[actionType]
       const matchingActions = []
-      if(file) {
-        debug("Filtering actions for specific `%s`", 2, actionType)
+      if(module) {
+        debug("Filtering actions for specific: %o", 2, actionType)
         const found = loadedActions.find(
-          e => e.file.absolutePath === file.absolutePath
+          e => e.file.specificType?.includes(actionType) &&
+               e.action.meta?.action === actionType
         )
 
         if(!found)
-          throw new Error(`Could not find specific action: ${file.absolutePath}`)
+          throw new Error(`Could not find specific action: ${module.absolutePath}`)
 
         matchingActions.push(found)
       } else {
@@ -198,15 +203,17 @@ export default class Discovery {
         matchingActions.length, actionType
       )
 
-      filtered.push(...matchingActions)
+      filteredActions.push(...matchingActions)
     }
 
-    debug("Filtered %d actions", 2, filtered.length)
+    debug("Filtered %d actions", 2, filteredActions.length)
+    debug("Filtered actions %o", 3, filteredActions)
 
     // Now check the metas for validity
-    for(const e of filtered) {
-      const {action, contract, file: moduleFile} = e
+    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" +
@@ -222,7 +229,7 @@ export default class Discovery {
 
       const isValid = this.#validMeta(metaAction, {action, contract})
 
-      debug("Action `%o` in `%s` is %s", 3,
+      debug("Meta in action %o in %o is %o", 3,
         metaAction, moduleFile.module, isValid ? "valid" : "invalid"
       )
 
@@ -239,7 +246,7 @@ export default class Discovery {
 
     for(const actionType of actionTypes) {
       const total = resultActions[actionType].length
-      debug("Found %d `%s` actions", 2, total, actionType)
+      debug("Found %o `%o` actions", 2, total, actionType)
     }
 
     const total = Object.keys(resultActions).reduce((acc, curr) => {
@@ -255,6 +262,9 @@ export default class Discovery {
 
   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"},
@@ -272,10 +282,10 @@ export default class Discovery {
       if(validatedConfig[config]) {
         debug("Checking for specific `%s` action", 3, actionType)
         const found = actions[actionType].find(
-          a => a.file.specificType === actionType
+          a => a.file.specificType.includes(actionType)
         )
         if(found) {
-          debug("Found specific `%s` action", 3, actionType)
+          debug("Found specific %o action", 3, actionType)
           satisfied[actionType].push(found)
           continue
         }
@@ -285,13 +295,14 @@ export default class Discovery {
 
       // Hmm! We didn't find anything specific. Let's check the criterion
       debug("Checking for `%s` actions with criterion `%s`", 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 %d `%s` actions with criterion `%s`", 3,
+      debug("Found %o %o actions with criterion %o", 3,
         found.length, actionType, criterion
       )
 

package/src/core/HookManager.js

@@ -90,6 +90,7 @@ export default class HookManager {
       return null
 
     hooksObj.log = instance.log
+    hooksObj.timeout = this.timeout
     instance.#hooks = hooksObj
 
     debug("Hooks loaded successfully for `%s`", 2, instance.action)
@@ -121,7 +122,7 @@ export default class HookManager {
       assert(isType(hook, "function"), `Hook "${event}" is not a function`, 1)
 
       const hookExecution = await hook.call(this.hooks, args)
-      const hookTimeout = this.parent.timeout
+      const hookTimeout = this.timeout
       const expireAsync = () =>
         timeoutPromise(
           hookTimeout,

package/src/core/util/ActionUtil.js

@@ -1,4 +1,6 @@
 import * as FDUtil from "./FDUtil.js"
+import process from "node:process"
+import JSON5 from "json5"
 
 const {readFile, fileExists, composeFilename} = FDUtil
 
@@ -20,7 +22,7 @@ const actionMetaRequirements = freeze({
 function loadJson(jsonFileObject) {
   // Read the file
   const jsonContent = readFile(jsonFileObject)
-  const json = JSON.parse(jsonContent)
+  const json = JSON5.parse(jsonContent)
   return json
 }
 
@@ -31,11 +33,11 @@ function loadJson(jsonFileObject) {
  * @returns {object?} The parsed package.json content or null if the file does
  *                    not exist
  */
-function loadPackageJson(basePath = null) {
+function loadPackageJson(basePath = process.cwd()) {
   const packageJsonFileObject = composeFilename(basePath, "./package.json")
   if(fileExists(packageJsonFileObject)) {
     const jsonContent = readFile(packageJsonFileObject)
-    const json = JSON.parse(jsonContent)
+    const json = JSON5.parse(jsonContent)
     return json
   } else
     return null

package/src/core/util/ModuleUtil.js

@@ -1,5 +1,6 @@
 import {createRequire} from "module"
 import FDUtil from "./FDUtil.js"
+import JSON5 from "json5"
 
 export default class ModuleUtil {
   /**
@@ -21,7 +22,7 @@ export default class ModuleUtil {
   static async loadJson(jsonFileObject) {
     // Read the file
     const jsonContent = await FDUtil.readFile(jsonFileObject)
-    const json = JSON.parse(jsonContent)
+    const json = JSON5.parse(jsonContent)
     return json
   }
 
@@ -33,7 +34,7 @@ export default class ModuleUtil {
   static async loadPackageJson() {
     const packageJsonFileObject = FDUtil.resolveFilename("./package.json")
     const jsonContent = await FDUtil.readFile(packageJsonFileObject)
-    const json = JSON.parse(jsonContent)
+    const json = JSON5.parse(jsonContent)
     return json
   }
 }