@gesslar/bedoc 1.4.8 → 1.5.0

package/README.md

@@ -1,6 +1,7 @@
 [![CodeQL Advanced](https://github.com/gesslar/BeDoc/actions/workflows/codeql.yml/badge.svg)](https://github.com/gesslar/BeDoc/actions/workflows/codeql.yml)
 [![Dependabot Updates](https://github.com/gesslar/BeDoc/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/gesslar/BeDoc/actions/workflows/dependabot/dependabot-updates)
 [![Auto PR and Merge - dev 🤗](https://github.com/gesslar/BeDoc/actions/workflows/autopr-dev.yml/badge.svg?branch=dev)](https://github.com/gesslar/BeDoc/actions/workflows/autopr-dev.yml)
+[![CodeFactor](https://www.codefactor.io/repository/github/gesslar/bedoc/badge)](https://www.codefactor.io/repository/github/gesslar/bedoc)
 
 # BeDoc
 

package/jsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "target": "ES2024",
+    "allowImportingTsExtensions": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true
+  },
+  "exclude": [
+    "node_modules",
+    "**/node_modules/*"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "main": "./src/core/Core.js",
@@ -37,7 +37,6 @@
     "commander": "^13.0.0",
     "dotenv": "^16.4.7",
     "error-stack-parser": "^2.1.4",
-    "eslint-plugin-jsdoc": "^50.6.2",
     "globby": "^14.0.2",
     "micromatch": "^4.0.8",
     "node-fetch": "^3.3.2",
@@ -49,6 +48,7 @@
     "@typescript-eslint/parser": "^8.22.0",
     "axios": "^1.7.9",
     "chokidar": "^4.0.3",
+    "eslint-plugin-jsdoc": "^50.6.3",
     "eslint": "^9.18.0",
     "form-data": "^4.0.1"
   },

package/src/core/ActionManager.js

@@ -119,7 +119,7 @@ export default class ActionManager {
       throw new Error(`No \`run\` function found for action \`${this.meta.action}\``)
 
     const actionResult = await func.call(
-      this.action, {module: file.module, content}
+      this.action, {moduleName: file.module, moduleContent: content}
     )
 
     return actionResult

package/src/core/Configuration.js

@@ -49,7 +49,7 @@ export default class Configuration {
     // Find them and add them to an array; the rest will be in pushed to the
     // end of the priority array.
     const orderedSections = []
-    ConfigurationPriorityKeys.forEach((key) => {
+    ConfigurationPriorityKeys.forEach(key => {
       if(!ConfigurationParameters[key])
         throw new Error(`Invalid priority key: ${key}`)
 
@@ -58,10 +58,10 @@ export default class Configuration {
     })
 
     const remainingSections = Object.keys(ConfigurationParameters).filter(
-      (key) => !ConfigurationPriorityKeys.includes(key),
+      key => !ConfigurationPriorityKeys.includes(key),
     )
     orderedSections.push(
-      ...remainingSections.map((key) => {
+      ...remainingSections.map(key => {
         return {key, value: finalOptions[key]}
       }),
     )
@@ -106,7 +106,7 @@ export default class Configuration {
         if(key === "input" || key === "exclude") {
           if(isType(value, "array"))
             value = await Promise.all(
-              value.map((pattern) => getFiles(pattern)),
+              value.map(pattern => getFiles(pattern)),
             )
           else if(isType(value, "string"))
             value = await getFiles(value)
@@ -251,7 +251,7 @@ export default class Configuration {
    */
   #getEnvironmentVariables() {
     const environmentVariables = {}
-    const params = Object.keys(ConfigurationParameters).map((param) => {
+    const params = Object.keys(ConfigurationParameters).map(param => {
       return {
         param,
         env: `bedoc_${param}`.toUpperCase(),
@@ -280,7 +280,7 @@ export default class Configuration {
     const nonEntryOptions = allOptions.filter(
       option => option.source && option.source !== "entry",
     )
-    const optionsOnly = nonEntryOptions.map((option) => option.options)
+    const optionsOnly = nonEntryOptions.map(option => option.options)
     const mergedOptions = optionsOnly.reduce((acc, options) => {
       for(const [key, value] of Object.entries(options)) acc[key] = value
 

package/src/core/Conveyor.js

@@ -24,33 +24,46 @@ export default class Conveyor {
    * @returns {Promise<object>} - Resolves when all files are processed.
    */
   async convey(files, maxConcurrent = 10) {
-    const semaphore = Array(maxConcurrent).fill(Promise.resolve())
-
-    // Set up the actions
-    await this.parse.setupAction()
-    await this.print.setupAction()
-
-    for(const file of files) {
-      const slot = Promise.race(semaphore) // Wait for an available slot
-      semaphore.push(slot.then(async() => {
-        const result = await this.#processFile(file)
-        if(result.status === "success")
-          this.#succeeded.push({input: file, output: result.file})
-        else if(result.status === "warning")
-          this.#warned.push({input: file, warning: result.warning})
-        else {
-          this.#errored.push({input: file, error: result.error})
+    const fileQueue = [...files]
+    const activePromises = []
+
+    await Promise.all([
+      this.parse.setupAction(),
+      this.print.setupAction()
+    ])
+
+    const processNextFile = file => {
+      return this.#processFile(file).then(processedResult => {
+        // Store result
+        if(processedResult.status === "success") {
+          this.#succeeded.push({input: file, output: processedResult.file})
+        } else if(processedResult.status === "warning") {
+          this.#warned.push({input: file, warning: processedResult.warning})
+        } else {
+          this.#errored.push({input: file, error: processedResult.error})
         }
-      }))
-      semaphore.shift() // Remove the oldest promise
+
+        // Start next job if queue isn't empty
+        if(fileQueue.length > 0) {
+          const nextFile = fileQueue.shift()
+          return processNextFile(nextFile)
+        }
+      })
+    }
+
+    // Initial fill of the worker pool
+    while(activePromises.length < maxConcurrent && fileQueue.length > 0) {
+      const file = fileQueue.shift()
+      activePromises.push(processNextFile(file))
     }
 
-    // Wait for all tasks to complete
-    await Promise.all(semaphore)
+    // Wait for all processing to complete
+    await Promise.all(activePromises)
 
-    // Clean up actions
-    await this.parse.cleanupAction()
-    await this.print.cleanupAction()
+    await Promise.all([
+      this.parse.cleanupAction(),
+      this.print.cleanupAction()
+    ])
 
     return {
       succeeded: this.#succeeded,
@@ -67,14 +80,13 @@ export default class Conveyor {
    */
   async #processFile(file) {
     const debug = this.logger.newDebug()
-    const warn = (...arg) => this.logger.warn(...arg)
     const {parse, print} = this
 
     try {
       debug("Processing file: `%s`", 2, file.path)
 
       // Step 1: Read file
-      const fileContent = await readFile(file)
+      const fileContent = readFile(file)
       debug("Read file content `%s` (%d bytes)", 2, file.path, fileContent.length)
 
       // Step 2: Parse file
@@ -90,8 +102,8 @@ export default class Conveyor {
       else
         debug("Parsed file successfully: `%s`", 2, file.path)
 
-      if(!parseResult.result?.functions?.length) {
-        const mess = format("No functions found in `%s`. No file written.", file.path)
+      if(!parseResult.result) {
+        const mess = format("No content found in `%s`. No file written.", file.path)
         return {status: "warning", file, warning: mess}
       }
 
@@ -106,21 +118,31 @@ export default class Conveyor {
       debug("Printed file successfully: `%s`", 2, file.path)
 
       // Step 4: Write output
-      const {status: printStatus, destFile, content} = printResult
-      const isNullish = (value) => value == null // Checks null or undefined
-
-      if(printStatus !== "success" || isNullish(destFile) || isNullish(content)) {
-        return {status: "error", file, error: new Error("Invalid print result")}
-      } else if(!destFile || !content) {
-        const mess = format("No content or destination file for %s", file.path)
-        warn(mess)
-        return {status: "warning", file, warning: mess}
+      const {status: printStatus, destFile, destContent} = printResult
+      const isNullish = value => value == null // Checks null or undefined
+
+      switch(printStatus) {
+        case "warning":
+        case "error":
+          return printResult
+        case "success":
+          if(isNullish(destFile) || isNullish(destContent))
+            return {
+              status: "warning",
+              warning: format("No content or destination file for %s", file.path)
+            }
+
+          break
+        default:
+          throw new Error(`Invalid status received from printing ${file.module}`)
       }
 
-      const writeResult = await this.#writeOutput(destFile, content)
+      const writeResult = await this.#writeOutput(destFile, destContent)
 
       if(writeResult.status === "success")
-        debug("Wrote output for: `%s` (%d bytes)", 2, file.path, content.length)
+        debug("Wrote output for: `%s` (%d bytes)", 2, file.path, destContent.length)
+      else
+        debug("Error writing output for: `%s`", 2, file.path)
 
       return writeResult
     } catch(error) {
@@ -132,13 +154,14 @@ export default class Conveyor {
    * Writes the output to the destination.
    *
    * @param {string} destFile - Destination file path.
-   * @param {string} content - File content.
+   * @param {string} destContent - File content.
    * @returns {Promise<object>} - Resolves when the file is written.
    */
-  async #writeOutput(destFile, content) {
+  async #writeOutput(destFile, destContent) {
     const destFileMap = composeFilename(this.output.path, destFile)
+
     try {
-      writeFile(destFileMap, content)
+      writeFile(destFileMap, destContent)
 
       return {status: "success", file: destFileMap}
     } catch(error) {

package/src/core/Core.js

@@ -1,8 +1,8 @@
-import process from "node:process"
+import {hrtime} from "node:process"
 
 import Discovery from "./Discovery.js"
 import HookManager from "./HookManager.js"
-import Logger, {loggerColours} from "./Logger.js"
+import Logger from "./Logger.js"
 import ParseManager from "./action/ParseManager.js"
 import PrintManager from "./action/PrintManager.js"
 import Conveyor from "./Conveyor.js"
@@ -118,7 +118,7 @@ export default class Core {
     return instance
   }
 
-  async processFiles(glob, startTime = process.hrtime()) {
+  async processFiles(glob) {
     const debug = this.logger.newDebug()
 
     debug("Starting file processing with conveyor", 1)
@@ -137,46 +137,23 @@ export default class Core {
       output,
     )
 
-    const processStart = process.hrtime()
+    const processStart = hrtime.bigint()
 
     // Initiate the conveyor
-    const result = await conveyor.convey(input, this.options.maxConcurrent)
+    const processResult = await conveyor.convey(
+      input, this.options.maxConcurrent
+    )
 
     debug("Conveyor complete", 1)
 
-    const endTime = (process.hrtime(startTime)[1] / 1_000_000).toFixed(2)
-    const processEnd = (process.hrtime(processStart)[1] / 1_000_000).toFixed(2)
-
-    // Grab the results
-    const totalFiles = input.length
-    const succeeded = result.succeeded
-    const warned = result.warned
-    const errored = result.errored
-
-    const {
-      info: succeedColour, warn: warnColour, error: errorColour, reset
-    } = loggerColours
-
-
-    const success = `${succeedColour}${succeeded.length}${reset}`
-    const warn = `${warnColour}${warned.length}${reset}`
-    const error = `${errorColour}${errored.length}${reset}`
-
-    const message = `Processed ${totalFiles} files: ${success} succeeded, ${error} errored, ` +
-      `${warn} warned in ${processEnd}ms [total: ${endTime}ms]`
-
-    this.logger.debug(message, 1)
-
-    if(errored.length > 0) {
-      // const failureRate = ((errored.length / totalFiles) * 100).toFixed(2)
-      // const errorMessage =
-      //   `Errors processing ${errored.length} files [${failureRate}%]`
-      // const errorLines = errored.map(r => {
-      //   const stackLine = log.lastStackLine(r.error, 0)
-      //   return `\n- ${r.input.module}: ${stackLine} - ${r.error.message}`
-      // }).join("")
+    const processEnd = hrtime.bigint()
 
-      // this.logger(errorMessage+errorLines)
+    const result = {
+      totalFiles: input.length,
+      succeeded: processResult.succeeded,
+      warned: processResult.warned,
+      errored: processResult.errored,
+      duration: ((Number(processEnd - processStart)) / 1_000_000).toFixed(2)
     }
 
     debug("File processing complete", 1)

package/src/core/Discovery.js

@@ -5,8 +5,9 @@ import {execSync} from "child_process"
 import * as FDUtil from "./util/FDUtil.js"
 import * as ActionUtil from "./util/ActionUtil.js"
 import * as DataUtil from "./util/DataUtil.js"
+import {composeDirectory,directoryExists} from "./util/FDUtil.js"
 
-const {ls, resolveDirectory, resolveFilename, getFiles} = FDUtil
+const {ls,resolveFilename,getFiles} = FDUtil
 const {actionTypes, actionMetaRequirements, loadJson} = ActionUtil
 const {isType} = DataUtil
 
@@ -72,7 +73,9 @@ export default class Discovery {
       debug("Found %d directories to search for actions", 2, directories.length)
       debug("Directories to search for actions: %o", 3, directories)
 
-      const moduleDirectories = directories.map(resolveDirectory)
+      const moduleDirectories = directories
+        .map(composeDirectory)
+        .filter(directoryExists)
       for(const moduleDirectory of moduleDirectories) {
         const {directories: dirs} = await ls(moduleDirectory.absolutePath)
 
@@ -310,9 +313,9 @@ export default class Discovery {
   async #loadModule(module) {
     const debug = this.#debug
 
-    debug("Loading module `%j`", 2, module)
+    debug("2 Loading module `%j`", 2, module)
 
-    const {absoluteUri} = module
+    const {absolutePath: absoluteUri} = module
     const moduleExports = await import(absoluteUri)
 
     return {file: module, ...moduleExports}

package/src/core/HookManager.js

@@ -10,7 +10,7 @@ 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.map(event => event.toUpperCase()),
     hookEvents,
   ),
 )
@@ -101,10 +101,10 @@ export default class HookManager {
    * Trigger a hook
    *
    * @param {string} event - The type of hook to trigger
-   * @param {...any} args - The hook arguments
+   * @param {object} args - The hook arguments as an object
    * @returns {Promise<any>} The result of the hook
    */
-  async on(event, ...args) {
+  async on(event, args) {
     const debug = this.log.newDebug()
 
     debug("Triggering hook for event `%s`", 4, event)
@@ -113,18 +113,14 @@ export default class HookManager {
       throw new Error("Event type is required for hook invocation")
 
     if(!hookEvents.includes(event))
-      throw new Error(`[HookManager.on] Invalid event type: ${event}`)
+      throw new Error(`Invalid event type: ${event}`)
 
     const hook = this.hooks[event]
 
     if(hook) {
-      assert(
-        isType(hook, "function"),
-        `[HookManager.on] Hook "${event}" is not a function`,
-        1,
-      )
+      assert(isType(hook, "function"), `Hook "${event}" is not a function`, 1)
 
-      const hookExecution = await hook.call(this.hooks, ...args)
+      const hookExecution = await hook.call(this.hooks, args)
       const hookTimeout = this.parent.timeout
       const expireAsync = () =>
         timeoutPromise(
@@ -139,6 +135,8 @@ export default class HookManager {
       debug("Hook executed successfully for event: `%s`", 4, event)
 
       return result
+    } else {
+      return null
     }
   }
 }

package/src/core/util/DataUtil.js

@@ -38,7 +38,7 @@ const constructors = [
   "Float64Array",
 ]
 
-const dataTypes = [...primitives, ...constructors.map((c) => c.toLowerCase())]
+const dataTypes = [...primitives, ...constructors.map(c => c.toLowerCase())]
 
 const emptyableTypes = ["string", "array", "object"]
 
@@ -96,7 +96,7 @@ function isArrayUnique(arr) {
  * @returns {Array} The intersection of the two arrays.
  */
 function arrayIntersection(arr1, arr2) {
-  return arr1.filter((value) => arr2.includes(value))
+  return arr1.filter(value => arr2.includes(value))
 }
 
 /**
@@ -390,7 +390,7 @@ function deepFreezeObject(obj) {
  * @returns {boolean} - True if valid, throws an error otherwise.
  */
 function schemaCompare(schema, definition, stack = [], logger = new Logger()) {
-  const breadcrumb = (key) => (stack.length ? `@${stack.join(".")}` : key)
+  const breadcrumb = key => (stack.length ? `@${stack.join(".")}` : key)
   const tag = "[DataUtil.schemaCompare]"
   const pad = `${" ".repeat(stack.length * 2)}${stack.length ? "└─ " : ""}`
   const debug = (message, key) =>

package/src/core/util/FDUtil.js

@@ -10,10 +10,10 @@ import * as ValidUtil from "./ValidUtil.js"
 const {isArrayUniform, isType, allocateObject} = DataUtil
 const {validType} = ValidUtil
 
-const freeze = (ob) => Object.freeze(ob)
+const freeze = ob => Object.freeze(ob)
 
 const fdTypes = freeze(["file", "directory"])
-const upperFdTypes = freeze(fdTypes.map((type) => type.toUpperCase()))
+const upperFdTypes = freeze(fdTypes.map(type => type.toUpperCase()))
 const fdType = freeze(await allocateObject(upperFdTypes, fdTypes))
 
 /**
@@ -67,7 +67,7 @@ function canWriteFile(FileMap) {
   try {
     fs.accessSync(FileMap.absolutePath, fs.constants.W_OK)
     return true
-  } catch(error) {
+  } catch(_error) {
     return false
   }
 }
@@ -82,7 +82,22 @@ function fileExists(FileMap) {
   try {
     fs.accessSync(FileMap.absolutePath)
     return true
-  } catch(error) {
+  } catch(_error) {
+    return false
+  }
+}
+
+/**
+ * Check if a directory exists
+ *
+ * @param {object} DirectoryMap - The directory map to check
+ * @returns {boolean} Whether the directory exists
+ */
+function directoryExists(DirectoryMap) {
+  try {
+    fs.accessSync(DirectoryMap.absolutePath)
+    return true
+  } catch(_error) {
     return false
   }
 }
@@ -231,9 +246,9 @@ async function getFiles(globPattern) {
       ? globPattern
       : globPattern
         .split("|")
-        .map((g) => g.trim())
+        .map(g => g.trim())
         .filter(Boolean)
-  ).map((g) => fixSlashes(g))
+  ).map(g => fixSlashes(g))
 
   if(
     Array.isArray(globbyArray) &&
@@ -246,7 +261,7 @@ async function getFiles(globPattern) {
 
   // Use Globby to fetch matching files
   const filesArray = await globby(globbyArray)
-  const files = filesArray.map((file) => mapFilename(file))
+  const files = filesArray.map(file => mapFilename(file))
 
   // Flatten the result and remove duplicates
   return files
@@ -297,7 +312,7 @@ function composeDirectory(directory) {
 async function ls(directory) {
   const found = await fs.promises.readdir(directory, {withFileTypes: true})
   const results = await Promise.all(
-    found.map(async(dirent) => {
+    found.map(async dirent => {
       const fullPath = path.join(directory, dirent.name)
       const stat = await fs.promises.stat(fullPath)
       return {dirent, stat, fullPath}
@@ -357,6 +372,7 @@ export {
   composeDirectory,
   composeFilename,
   deconstructFilenameToParts,
+  directoryExists,
   fileExists,
   fixSlashes,
   getFiles,

package/src/core/util/TypeSpec.js

@@ -17,7 +17,7 @@ export default class TypeSpec {
 
   toString() {
     return this.#specs
-      .map((spec) => {
+      .map(spec => {
         return `${spec.typeName}${spec.array ? "[]" : ""}`
       })
       .join("|")
@@ -61,7 +61,7 @@ export default class TypeSpec {
     // If we have a list of types, because the string was validly parsed,
     // we need to ensure that all of the types that were parsed are valid types
     // in JavaScript.
-    if(this.length && !this.every((t) => isValidType(t.typeName)))
+    if(this.length && !this.every(t => isValidType(t.typeName)))
       return false
 
     // Now, let's do some checking with the types, respecting the array flag
@@ -71,7 +71,7 @@ export default class TypeSpec {
 
     // We need to ensure that we match the type and the consistency of the types
     // in an array, if it is an array and an array is allowed.
-    const matchingTypeSpec = this.filter((spec) => {
+    const matchingTypeSpec = this.filter(spec => {
       const {typeName: allowedType, array: allowedArray} = spec
 
       if(valueType === allowedType && !isArray && !allowedArray)
@@ -97,7 +97,7 @@ export default class TypeSpec {
     const delimiter = options?.delimiter ?? "|"
     const parts = string.split(delimiter)
 
-    this.#specs = parts.map((part) => {
+    this.#specs = parts.map(part => {
       const typeMatches = /(\w+)(\[\])?/.exec(part)
       if(!typeMatches || typeMatches.length !== 3)
         throw new TypeError(`Invalid type: ${part}`)

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "include": ["src/**/*.js"], // Match all .js files in the src/ directory
-  "exclude": ["node_modules"], // Ignore node_modules/ (but NOT src/)
-  "compilerOptions": {
-    "target": "ES2022", // Modern JavaScript output
-    "allowJs": true, // Process .js files
-    "declaration": true, // Generate .d.ts files
-    "emitDeclarationOnly": true, // Only output .d.ts files
-    "declarationMap": true, // Generate .d.ts.map for IDE support
-    "module": "NodeNext", // Use ESM-compatible Node.js modules
-    "moduleResolution": "nodenext", // Resolve ESM imports properly
-    "rootDir": "src", // Base input directory
-    "outDir": "dist/types", // Emit .d.ts files to a separate directory
-    "strict": true, // Enable strict type-checking
-    "esModuleInterop": true, // Interoperability for CommonJS modules
-    "forceConsistentCasingInFileNames": true, // Avoid case-sensitive issues
-    "skipLibCheck": true, // Skip checking .d.ts files in node_modules/
-    "noEmitOnError": true // Prevent output if there are errors
-  }
-}