@gesslar/bedoc 1.6.0 → 1.7.0

package/package.json

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

@@ -3,6 +3,7 @@
 import {program} from "commander"
 import console from "node:console"
 import process from "node:process"
+import {fileURLToPath,URL} from "node:url"
 
 import BeDoc, {Environment} from "./core/Core.js"
 import {ConfigurationParameters} from "./core/ConfigurationParameters.js"
@@ -10,18 +11,21 @@ import {ConfigurationParameters} from "./core/ConfigurationParameters.js"
 import * as ActionUtil from "./core/util/ActionUtil.js"
 import * as FDUtil from "./core/util/FDUtil.js"
 
-const {loadPackageJson} = ActionUtil
-const {resolveDirectory} = FDUtil
+const {loadJson} = ActionUtil
+const {resolveFilename,resolveDirectory} = FDUtil
 
 // Main entry point
 ;(async() => {
   try {
     // Get package info
     const basePath = resolveDirectory(process.cwd())
-    const packageJson = loadPackageJson(basePath)
+    const thisPath = resolveDirectory(fileURLToPath(new URL("..", import.meta.url)))
+    const bedocPackageJson = loadJson(resolveFilename("package.json", thisPath))
 
     // Setup program
-    program.name(packageJson.name).description(packageJson.description)
+    program
+      .name(bedocPackageJson.name)
+      .description(bedocPackageJson.description)
 
     // Build CLI
     for(const [name, parameter] of Object.entries(ConfigurationParameters)) {
@@ -42,7 +46,7 @@ const {resolveDirectory} = FDUtil
 
     // Add version option last
     program.version(
-      packageJson.version,
+      bedocPackageJson.version,
       "-v, --version",
       "Output the version number",
     )
@@ -68,10 +72,10 @@ const {resolveDirectory} = FDUtil
         options: {
           ...optionsWithSources,
           basePath: {value: basePath, source: "cli"},
-          packageJson: {value: packageJson, source: "cli"},
         },
         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
 
@@ -137,7 +145,7 @@ export default class Configuration {
     }
   }
 
-  #mapEntryOptions({options, source}) {
+  #mapEntryOptions({options = {}, source}) {
     // CLI already has done all the work via commander
     if(source === Environment.CLI)
       return options
@@ -154,15 +162,6 @@ export default class Configuration {
     if(!options.basePath)
       options.basePath = {value: dir, source}
 
-    // Inject packageJson if not available
-    if(!options.packageJson) {
-      const jsonFile = composeFilename(dir, "package.json")
-      if(fileExists(jsonFile)) {
-        const jsonObj = loadJson(jsonFile)
-        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)
@@ -213,25 +212,33 @@ export default class Configuration {
    */
   #findAllOptions(entryOptions) {
     const allOptions = []
-
     const environmentVariables = this.#getEnvironmentVariables()
     if(environmentVariables)
       allOptions.push({source: "environment", options: environmentVariables})
 
     const packageJson = entryOptions?.packageJson
-    if(packageJson?.bedoc)
-      allOptions.push({source: "packageJson", options: packageJson.bedoc})
+    if(packageJson) {
+      allOptions.push({source: "packageJson", options: packageJson})
+    } else {
+      const packageJsonFile = composeFilename(process.cwd(), "package.json")
+      if(fileExists(packageJsonFile)) {
+        const packageJson = loadJson(packageJsonFile)
+
+        if(packageJson.bedoc)
+          allOptions.push({source: "packageJson", options: packageJson.bedoc})
+      }
+    }
 
     // Then the config file, if the options specified a config file
     const useConfig =
       entryOptions?.config ||
-      packageJson?.bedoc?.config ||
+      packageJson?.config ||
       environmentVariables?.config
 
     if(useConfig) {
       const configFile =
-        packageJson?.bedoc?.config
-          ? resolveFilename(packageJson?.bedoc?.config)
+        packageJson?.config
+          ? resolveFilename(packageJson?.config)
           : entryOptions.config?.value
             ? resolveFilename(entryOptions.config.value)
             : null
@@ -287,7 +294,8 @@ export default class Configuration {
     )
     const optionsOnly = nonEntryOptions.map(option => option.options)
     const mergedOptions = optionsOnly.reduce((acc, options) => {
-      for(const [key, value] of Object.entries(options)) acc[key] = value
+      for(const [key, value] of Object.entries(options))
+        acc[key] = value
 
       return acc
     }, {})

package/src/core/Conveyor.js

@@ -6,7 +6,7 @@ const {readFile, writeFile, composeFilename} = FDUtil
 
 export default class Conveyor {
   #succeeded = []
-  #warned  = []
+  #warned = []
   #errored = []
 
   constructor(parse, print, logger, output) {
@@ -83,11 +83,11 @@ export default class Conveyor {
     const {parse, print} = this
 
     try {
-      debug("Processing file: `%s`", 2, file.path)
+      debug("Processing file: %o", 2, file.path)
 
       // Step 1: Read file
       const fileContent = readFile(file)
-      debug("Read file content `%s` (%d bytes)", 2, file.path, fileContent.length)
+      debug("Read file content %o (%o bytes)", 2, file.path, fileContent.length)
 
       // Step 2: Parse file
       const parseResult = await parse.runAction({
@@ -98,12 +98,12 @@ export default class Conveyor {
         return parseResult
 
       if(parseResult.status === "warning")
-        debug("Parsed file successfully, but with warnings: `%s`", 2, file.path)
+        debug("Parsed file successfully, but with warnings: %o", 2, file.path)
       else
-        debug("Parsed file successfully: `%s`", 2, file.path)
+        debug("Parsed file successfully: %o", 2, file.path)
 
       if(!parseResult.result) {
-        const mess = format("No content found in `%s`. No file written.", file.path)
+        const mess = format("No content found in %o. No file written.", file.path)
         return {status: "warning", file, warning: mess}
       }
 
@@ -115,7 +115,7 @@ export default class Conveyor {
       if(printResult.status === "error")
         return printResult
 
-      debug("Printed file successfully: `%s`", 2, file.path)
+      debug("Printed file successfully: %o", 2, file.path)
 
       // Step 4: Write output
       const {status: printStatus, destFile, destContent} = printResult
@@ -129,7 +129,7 @@ export default class Conveyor {
           if(isNullish(destFile) || isNullish(destContent))
             return {
               status: "warning",
-              warning: format("No content or destination file for %s", file.path)
+              warning: format("No content or destination file for %o", file.path)
             }
 
           break
@@ -137,14 +137,21 @@ export default class Conveyor {
           throw new Error(`Invalid status received from printing ${file.module}`)
       }
 
-      const writeResult = await this.#writeOutput(destFile, destContent)
+      if(this.output) {
+        const writeResult = await this.#writeOutput(destFile, destContent)
 
-      if(writeResult.status === "success")
-        debug("Wrote output for: `%s` (%d bytes)", 2, file.path, destContent.length)
-      else
-        debug("Error writing output for: `%s`", 2, file.path)
+        if(writeResult.status === "success")
+          debug("Wrote output %o (%o bytes)", 2, writeResult.file.path, destContent.length)
+        else
+          debug("Error writing output for: `%s`", 2, file.path)
+
+        return writeResult
+      }
+
+      debug("Output not specified. Writing skipped.", 2)
+
+      return {status: "success"}
 
-      return writeResult
     } catch(error) {
       return {status: "error", file, error}
     }
@@ -158,8 +165,12 @@ export default class Conveyor {
    * @returns {Promise<object>} - Resolves when the file is written.
    */
   async #writeOutput(destFile, destContent) {
+    const debug = this.logger.newDebug()
+
     const destFileMap = composeFilename(this.output.path, destFile)
 
+    debug("Writing output to %o => %o", 2, destFile, destFileMap.absolutePath)
+
     try {
       writeFile(destFileMap, destContent)
 

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,11 +34,13 @@ export default class Discovery {
 
     debug("Discovering actions", 2)
 
+    debug("Specific modules provided: %o", 2, specific)
+
     const bucket = []
     const options = this.core.options ?? {}
 
     if(options?.mockPath) {
-      debug("Discovering mock actions in `%s`", 1, options.mockPath)
+      debug("Discovering mock actions in `%s`", 2, options.mockPath)
 
       bucket.push(
         ...(await getFiles([
@@ -47,13 +49,13 @@ export default class Discovery {
         ])),
       )
     } else {
-      debug("Mock path not set, discovering actions in node_modules", 1)
+      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?.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
       )