@gesslar/bedoc 1.6.0 → 1.6.1

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.6.0",
+  "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",
@@ -63,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/Configuration.js

@@ -42,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
@@ -79,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
 
@@ -213,7 +221,6 @@ export default class Configuration {
    */
   #findAllOptions(entryOptions) {
     const allOptions = []
-
     const environmentVariables = this.#getEnvironmentVariables()
     if(environmentVariables)
       allOptions.push({source: "environment", options: environmentVariables})

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 ?? {}
 
@@ -53,7 +55,7 @@ export default class Discovery {
       if(this.core.packageJson?.modules) {
         const actions = this.core.packageJson?.modules
 
-        debug("Found %d actions in package.json", 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,34 +129,35 @@ 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) {
@@ -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
         }
@@ -283,7 +293,6 @@ export default class Discovery {
         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)
       debug("Validated config to check against: %o", 3, validatedConfig)
@@ -293,7 +302,7 @@ export default class Discovery {
         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
       )