@gesslar/bedoc 1.6.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.6.1",
+  "version": "1.9.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "author": "gesslar",

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,7 +72,6 @@ const {resolveDirectory} = FDUtil
         options: {
           ...optionsWithSources,
           basePath: {value: basePath, source: "cli"},
-          packageJson: {value: packageJson, source: "cli"},
         },
         source: Environment.CLI
       })

package/src/core/ActionManager.js

@@ -7,10 +7,12 @@ export default class ActionManager {
   #log
   #debug
   #file
+  #variables
 
-  constructor(actionDefinition, logger) {
+  constructor({actionDefinition, logger, variables}) {
     this.#log = logger
     this.#debug = this.#log.newDebug()
+    this.#variables = variables
 
     this.#initialize(actionDefinition)
   }
@@ -65,6 +67,10 @@ export default class ActionManager {
     return this.#log
   }
 
+  get variables() {
+    return this.#variables
+  }
+
   async #setupAction() {
     const setup = this.action?.setup
 
@@ -90,7 +96,11 @@ export default class ActionManager {
       return
 
     await this.hookManager.setup.call(
-      this.hookManager.hooks, {parent: this.action, log: this.#log}
+      this.hookManager.hooks, {
+        action: this.action,
+        variables: this.#variables,
+        log: this.#log
+      }
     )
   }
 

package/src/core/Configuration.js

@@ -145,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
@@ -162,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)
@@ -226,19 +217,28 @@ export default class Configuration {
       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
@@ -246,9 +246,22 @@ export default class Configuration {
       if(!configFile)
         throw new Error("No config file specified")
 
-      const config = loadJson(configFile)
+      const configObject = loadJson(configFile)
+      const subConfigName =
+        entryOptions?.sub ||
+        packageJson?.sub ||
+        environmentVariables?.sub
+
+      // If we didn't specify a subconfiguration, let's just remove
+      // it so it doesn't pollute anything.
+      if(!subConfigName)
+        delete configObject.sub
+
+      const finalConfig = subConfigName?.value
+        ? this.#resolveSubconfigs(configObject, subConfigName.value)
+        : configObject
 
-      allOptions.push({source: "config", options: config})
+      allOptions.push({source: "config", options: finalConfig})
     }
 
     allOptions.push({source: "entry", options: entryOptions})
@@ -256,6 +269,21 @@ export default class Configuration {
     return allOptions
   }
 
+  #resolveSubconfigs(configObject, subConfigName) {
+    const subConfig = configObject.sub?.find(sub => sub.name === subConfigName)
+
+    if(!subConfig)
+      throw new Error(`No such subconfiguration \`${subConfigName}\``)
+
+    // We don't need this anymore
+    delete subConfig.name
+
+    for(const [key,val] of Object.entries(subConfig))
+      configObject[key] = val
+
+    return configObject
+  }
+
   /**
    * Get environment variables
    *
@@ -294,7 +322,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/ConfigurationParameters.js

@@ -120,6 +120,14 @@ const ConfigurationParameters = Object.freeze({
       mustExist: true,
     },
   },
+  sub: {
+    short: "s",
+    param: "name",
+    description: "Specify a subconfiguration",
+    type: newTypeSpec("string"),
+    required: false,
+    dependent: "config",
+  },
   debug: {
     short: "d",
     description: "Enable debug mode",

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

@@ -91,14 +91,18 @@ export default class Core {
 
     // Adding to instance
     instance.actions = {}
+    const {variables} = validConfig
     const managers = {print: PrintManager, parse: ParseManager}
-    for(const [, value] of Object.entries(finalActions)) {
-      const {action: actionType} = value.action.meta
+    for(const [, actionDefinition] of Object.entries(finalActions)) {
+      const {action: actionType} = actionDefinition.action.meta
 
       debug("Attaching %o action to instance", 2, actionType)
-      instance.actions[actionType] = new managers[actionType](
-        value, instance.logger
-      )
+      instance.actions[actionType] =
+        new managers[actionType] ({
+          actionDefinition,
+          logger: instance.logger,
+          variables
+        })
 
       if(validConfig.hooks) {
         const hookManager = await HookManager.new({

package/src/core/Discovery.js

@@ -7,7 +7,7 @@ import * as ActionUtil from "./util/ActionUtil.js"
 import * as DataUtil from "./util/DataUtil.js"
 import {composeDirectory,directoryExists} from "./util/FDUtil.js"
 
-const {ls,resolveFilename,getFiles} = FDUtil
+const {ls,fileExists,composeFilename,getFiles} = FDUtil
 const {actionTypes, actionMetaRequirements, loadJson} = ActionUtil
 const {isType} = DataUtil
 
@@ -40,7 +40,7 @@ export default class Discovery {
     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([
@@ -49,9 +49,10 @@ 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
 
@@ -66,30 +67,46 @@ export default class Discovery {
         debug("No actions found in project's package.json", 2)
       }
 
-      debug("Looking for actions in node_modules (global and locally installed", 2)
+      debug("Looking for actions in node_modules (global and locally installed)", 2)
       const directories = [
-        "./node_modules",
+        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)
 
-      const moduleDirectories = directories
-        .map(composeDirectory)
-        .filter(directoryExists)
-      for(const moduleDirectory of moduleDirectories) {
-        const {directories: dirs} = await ls(moduleDirectory.absolutePath)
+      for(const nodeModulesDir of nodeModulesDirs) {
+        const dirsToSearch = []
+        const {directories: moduleDirs} = await ls(nodeModulesDir.absolutePath)
 
-        debug("Found %o directories in `%s`", 2,
-          dirs.length, moduleDirectory.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("@"))
 
-        const bedocDirs = dirs.filter(d => d.name.startsWith("bedoc-"))
-        debug("Found %o bedoc directories under %s", 2, bedocDirs.length, moduleDirectory.absolutePath)
+        dirsToSearch.push(...moduleDirs)
 
-        const exports = bedocDirs.map(d => this.#getModuleExports(d))
-        debug("Found %o module exports under %s", 2, exports.length, moduleDirectory.absolutePath)
+        // 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)
+
+          dirsToSearch.push(...scopedPackages)
+        }
+
+        debug("Found %o directories to search for actions", 2, dirsToSearch.length)
+
+        const exports = dirsToSearch
+          .filter(d => !d.name.startsWith("."))
+          .map(d => this.#getModuleExports(d))
+
+        debug("Found %o module exports under %o", 2, exports.length, nodeModulesDir.absolutePath)
 
         bucket.push(...exports.flat())
       }
@@ -108,18 +125,27 @@ export default class Discovery {
    */
   #getModuleExports(dirMap) {
     const debug = this.#debug
-    debug("Getting module exports from `%s`", 3, dirMap.absolutePath)
+    debug("Getting module exports from %o", 3, dirMap.absolutePath)
+
+    const packageJsonFile = composeFilename(dirMap, "package.json")
+    if(!fileExists(packageJsonFile))
+      return []
 
-    const packageJsonFile = resolveFilename("package.json", dirMap)
-    debug("Loading package.json from `%s`", 3, packageJsonFile.absolutePath)
+    debug("Loading package.json from %o", 3, packageJsonFile.absolutePath)
 
     const packageJson = loadJson(packageJsonFile)
-    debug("Loaded package.json from `%s`", 3, packageJsonFile.absolutePath)
+    debug("Loaded package.json from %o", 3, packageJsonFile.absolutePath)
 
     const bedocPackageJsonModules = packageJson.bedoc?.modules ?? []
-    const bedocModuleFiles = bedocPackageJsonModules.map(file =>
-      resolveFilename(file, dirMap)
-    )
+
+    debug("Discovered %o published modules", 2, bedocPackageJsonModules.length)
+    debug("Published modules %o", 3, bedocPackageJsonModules)
+
+    const bedocModuleFiles = bedocPackageJsonModules
+      .map(m => composeFilename(dirMap, m))
+      .filter(m => fileExists(m))
+
+    debug("Composed modules %o", 3, bedocModuleFiles)
 
     return bedocModuleFiles
   }
@@ -225,7 +251,7 @@ export default class Discovery {
           JSON.stringify(moduleFile, null, 2) + "\n" +
           JSON.stringify(action, null, 2))
 
-      debug("Checking action `%s`", 2, metaAction)
+      debug("Checking action %o", 2, metaAction)
 
       const isValid = this.#validMeta(metaAction, {action, contract})
 
@@ -246,7 +272,7 @@ export default class Discovery {
 
     for(const actionType of actionTypes) {
       const total = resultActions[actionType].length
-      debug("Found %o `%o` actions", 2, total, actionType)
+      debug("Found %o %o actions", 2, total, actionType)
     }
 
     const total = Object.keys(resultActions).reduce((acc, curr) => {
@@ -280,7 +306,7 @@ export default class Discovery {
 
       // First let's check if we wanted something specific
       if(validatedConfig[config]) {
-        debug("Checking for specific `%s` action", 3, actionType)
+        debug("Checking for specific %o action", 3, actionType)
         const found = actions[actionType].find(
           a => a.file.specificType.includes(actionType)
         )
@@ -294,7 +320,7 @@ 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("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])
@@ -341,7 +367,7 @@ export default class Discovery {
    */
   #validMeta(actionType, toValidate) {
     const debug = this.#debug
-    debug("Checking meta requirements for `%s`", 3, actionType)
+    debug("Checking meta requirements for %o", 3, actionType)
 
     const requirements = actionMetaRequirements[actionType]
     if(!requirements)