@gesslar/bedoc 1.4.10 → 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.10",
+  "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/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 {status: printStatus, destFile, destContent} = 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}
+      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/HookManager.js

@@ -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
     }
   }
 }