@gesslar/bedoc 1.1.0 → 1.3.0

package/dist/types/core/util/FDUtil.d.ts

@@ -0,0 +1,146 @@
+export type FDType = 'file' | 'directory';
+
+export interface FileMap {
+    path: string;
+    uri: string;
+    absolutePath: string;
+    absoluteUri: string;
+    name: string;
+    module: string;
+    extension: string;
+    isFile: true;
+    isDirectory: false;
+    directory?: DirMap;
+}
+
+export interface DirMap {
+    path: string;
+    uri: string;
+    absolutePath: string;
+    absoluteUri: string;
+    name: string;
+    separator: string;
+    isFile: false;
+    isDirectory: true;
+}
+
+export interface FilenameParts {
+    basename: string;
+    dirname: string;
+    extname: string;
+}
+
+export const fdType: Readonly<Record<Uppercase<FDType>, FDType>>;
+export const fdTypes: readonly FDType[];
+
+/**
+ * Compose a directory map from a path
+ *
+ * @param {string} directory - The directory
+ * @returns {DirMap} A directory object
+ */
+export function composeDirectory(directory: string): DirMap;
+/**
+ * Compose a file path from a directory and a file
+ *
+ * @param {string|DirMap} directoryNameorObject - The directory
+ * @param {string} fileName - The file
+ * @returns {FileMap} A file object
+ */
+export function composeFilename(directoryNameorObject: string | DirMap, fileName: string): FileMap;
+/**
+ * Deconstruct a filename into parts
+ *
+ * @param {string} fileName - The filename to deconstruct
+ * @returns {FilenameParts} The filename parts
+ */
+export function deconstructFilenameToParts(fileName: string): FilenameParts;
+/**
+ * Fix slashes in a path
+ *
+ * @param {string} pathName - The path to fix
+ * @returns {string} The fixed path
+ */
+export function fixSlashes(pathName: string): string;
+/**
+ * Retrieve all files matching a specific glob pattern.
+ *
+ * @param {string|string[]} globPattern - The glob pattern(s) to search.
+ * @returns {Promise<FileMap[]>} An array of file objects
+ * @throws {Error} Throws an error for invalid input or search failure.
+ */
+export function getFiles(globPattern: string | string[]): Promise<FileMap[]>;
+/**
+ * Lists the contents of a directory.
+ *
+ * @param {string} directory - The directory to list.
+ * @returns {Promise<{files: FileMap[], directories: DirMap[]}>} The files and
+ * directories in the directory.
+ */
+export function ls(directory: string): Promise<{
+    files: FileMap[];
+    directories: DirMap[];
+}>;
+/**
+ * Map a directory to a DirMap
+ *
+ * @param {string} directoryName - The directory to map
+ * @returns {DirMap} A directory object
+ */
+export function mapDirectory(directoryName: string): DirMap;
+/**
+ * Map a file to a FileMap
+ *
+ * @param {string} fileName - The file to map
+ * @returns {FileMap} A file object
+ */
+export function mapFilename(fileName: string): FileMap;
+/**
+ * Convert a path to a URI
+ *
+ * @param {string} pathName - The path to convert
+ * @returns {string} The URI
+ * @throws {Error} If the path is not a valid file path
+ */
+export function pathToUri(pathName: string): string;
+/**
+ * Reads the content of a file synchronously.
+ *
+ * @param {FileMap} fileObject - The file map containing the file path
+ * @returns {string} The file contents
+ */
+export function readFile(fileObject: FileMap): string;
+/**
+ * Resolves a path to an absolute path
+ *
+ * @param {string} directoryName - The path to resolve
+ * @returns {DirMap} The directory object
+ * @throws {Error}
+ */
+export function resolveDirectory(directoryName: string): DirMap;
+/**
+ * Resolves a file to an absolute path
+ *
+ * @param {string} fileName - The file to resolve
+ * @param {DirMap} [directoryObject] - The directory object to resolve the
+ *                                     file in
+ * @returns {FileMap} A file object (validated)
+ * @throws {Error}
+ */
+export function resolveFilename(fileName: string, directoryObject?: DirMap | null): FileMap;
+/**
+ * Convert a URI to a path
+ *
+ * @param {string} pathName - The URI to convert
+ * @returns {string} The path
+ * @throws {Error} If the URI is not a valid file URL
+ */
+export function uriToPath(pathName: string): string;
+/**
+ * Writes content to a file synchronously.
+ *
+ * @param {FileMap} fileObject - The file map containing the file path
+ * @param {string} content - The content to write
+ */
+export function writeFile(fileObject: FileMap, content: string): void;
+//# sourceMappingURL=FDUtil.d.ts.map

package/dist/types/core/util/FDUtil.d.ts.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "file": "FDUtil.d.ts",
+  "sourceRoot": "",
+  "sources": [
+    "../../../../src/core/util/FDUtil.js"
+  ],
+  "names": [],
+  "mappings": "AAgBA,yBAAkE;AAFlE,0BAA6C;AA0N7C;;;;;GAKG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAjJD;;;;;;GAMG;AACH,uDAJW,MAAM,GAAC,MAAM,YACb,MAAM,GACJ,MAAM,CAiBlB;AAyCD;;;;;GAKG;AACH,qDAHW,MAAM,GACJ,MAAM,CAMlB;AAtJD;;;;;GAKG;AACH,qCAHW,MAAM,GACJ,MAAM,CAIlB;AAgJD;;;;;;GAMG;AACH,sCAJW,MAAM,GAAC,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CA+B7B;AAqCD;;;;;;GAMG;AACH,8BAJW,MAAM,GACJ,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC,CAsB7D;AAjID;;;;;GAKG;AACH,4CAHW,MAAM,GACJ,MAAM,CAalB;AArCD;;;;;GAKG;AACH,sCAHW,MAAM,GACJ,MAAM,CAclB;AA7GD;;;;;;GAMG;AACH,oCAJW,MAAM,GACJ,MAAM,CAUlB;AAoOD;;;;;GAKG;AACH,qCAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAW3B;AA9ED;;;;;;GAMG;AACH,gDAJW,MAAM,GACJ,MAAM,CAmBlB;AA1KD;;;;;;;;GAQG;AACH,0CANW,MAAM,oBACN,MAAM,GAEJ,MAAM,CA2BlB;AAjDD;;;;;;GAMG;AACH,oCAJW,MAAM,GACJ,MAAM,CAUlB;AAqOD;;;;;GAKG;AACH,sCAHW,MAAM,WACN,MAAM,QAShB"
+}

package/dist/types/core/util/ModuleUtil.d.ts

@@ -0,0 +1,27 @@
+import { FileMap } from './FDUtil';
+
+export default class ModuleUtil {
+    /**
+     * Requires a module synchronously
+     *
+     * @param {FileMap} fileObject - The file to require
+     * @returns {unknown} The required module
+     */
+    static require(fileObject: FileMap): unknown;
+
+    /**
+     * Loads a JSON file asynchronously
+     *
+     * @param {FileMap} jsonFileObject - The JSON file to load
+     * @returns {Promise<Record<string, unknown>>} The parsed JSON content
+     */
+    static loadJson(jsonFileObject: FileMap): Promise<Record<string, unknown>>;
+
+    /**
+     * Loads the package.json file asynchronously
+     *
+     * @returns {Promise<Record<string, unknown>>} The parsed package.json content
+     */
+    static loadPackageJson(): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=ModuleUtil.d.ts.map

package/dist/types/core/util/ModuleUtil.d.ts.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "file": "ModuleUtil.d.ts",
+  "sourceRoot": "",
+  "sources": [
+    "../../../../src/core/util/ModuleUtil.js"
+  ],
+  "names": [],
+  "mappings": "AAGA;IACE;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,gCAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAO3B;IAED;;;;OAIG;IACH,0BAFa,OAAO,CAAC,MAAM,CAAC,CAO3B;CACF"
+}

package/dist/types/core/util/StringUtil.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Capitalizes the first letter of a string
+ */
+export function capitalize(str: string): string;
+//# sourceMappingURL=StringUtil.d.ts.map

package/dist/types/core/util/StringUtil.d.ts.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "file": "StringUtil.d.ts",
+  "sourceRoot": "",
+  "sources": [
+    "../../../../src/core/util/StringUtil.js"
+  ],
+  "names": [],
+  "mappings": "AAAA;;;;;GAKG;AACH,gCAHW,MAAM,GACJ,MAAM,CAIlB"
+}

package/dist/types/core/util/TypeSpec.d.ts

@@ -0,0 +1,42 @@
+import { DataType } from './DataUtil';
+
+interface TypeSpecification {
+    typeName: DataType;
+    array: boolean;
+}
+
+interface TypeSpecOptions {
+    delimiter?: string;
+    allowEmpty?: boolean;
+}
+
+interface TypeSpecJSON {
+    specs: TypeSpecification[];
+    length: number;
+    stringRepresentation: string;
+}
+
+export default class TypeSpec {
+    constructor(typeString: string, options?: TypeSpecOptions);
+
+    readonly specs: readonly TypeSpecification[];
+    readonly length: number;
+    readonly stringRepresentation: string;
+
+    toString(): string;
+    toJSON(): TypeSpecJSON;
+
+    forEach(callback: (spec: TypeSpecification) => void): void;
+    every(callback: (spec: TypeSpecification) => boolean): boolean;
+    some(callback: (spec: TypeSpecification) => boolean): boolean;
+    filter(callback: (spec: TypeSpecification) => boolean): TypeSpecification[];
+    map<T>(callback: (spec: TypeSpecification) => T): T[];
+    reduce<T>(callback: (acc: T, spec: TypeSpecification) => T, initialValue: T): T;
+    find(callback: (spec: TypeSpecification) => boolean): TypeSpecification | undefined;
+
+    match(value: unknown, options?: TypeSpecOptions): boolean;
+
+    #specs: TypeSpecification[];
+    #parse(typeString: string, options?: TypeSpecOptions): void;
+}
+//# sourceMappingURL=TypeSpec.d.ts.map

package/dist/types/core/util/TypeSpec.d.ts.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "file": "TypeSpec.d.ts",
+  "sourceRoot": "",
+  "sources": [
+    "../../../../src/core/util/TypeSpec.js"
+  ],
+  "names": [],
+  "mappings": "AAIA;IAGE,uCAQC;IAJC,aAAwB;IACxB,eAAgC;IAChC,6BAA2C;IAI7C,mBAMC;IAED;;;;MAOC;IAED,6BAEC;IACD,8BAEC;IACD,6BAEC;IACD,6BAEC;IACD,0BAEC;IACD,8CAEC;IACD,yBAEC;IAED,yCAqCC;;CAoBF"
+}

package/dist/types/core/util/ValidUtil.d.ts

@@ -0,0 +1,29 @@
+import TypeSpec from './TypeSpec';
+
+interface ValidTypeOptions {
+    allowEmpty?: boolean;
+}
+
+/**
+ * Validates a value against a type
+ *
+ * @throws {Error} If the value does not match the expected type
+ */
+export function validType(
+    value: unknown,
+    type: string | TypeSpec,
+    options?: ValidTypeOptions,
+    depth?: number
+): void;
+
+/**
+ * Asserts a condition
+ *
+ * @throws {Error} If the condition is not met, with optional argument in message
+ */
+export function assert(
+    condition: boolean,
+    message: string,
+    arg?: number | null
+): asserts condition;
+//# sourceMappingURL=ValidUtil.d.ts.map

package/dist/types/core/util/ValidUtil.d.ts.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "file": "ValidUtil.d.ts",
+  "sourceRoot": "",
+  "sources": [
+    "../../../../src/core/util/ValidUtil.js"
+  ],
+  "names": [],
+  "mappings": "AAsBA;;;;;;;;GAQG;AACH,kCANW,OAAO,WACP,MAAM,QAEN,MAAM,QAmBhB;AAzCD;;;;;;;GAOG;AACH,iCALW,GAAC,QACD,MAAM,YAEN,MAAM,QAQhB"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "main": "./src/core/Core.js",
@@ -14,12 +14,20 @@
   "bin": {
     "bedoc": "src/cli.js"
   },
+  "exports": {
+    ".": {
+      "import": "./src/core/Core.js",
+      "types": "./dist/types/core/Core.d.ts"
+    }
+  },
   "type": "module",
+  "types": "dist/types/index.d.ts",
   "scripts": {
     "lint:check": "npx eslint .",
     "lint:fix": "npx eslint . --fix"
   },
   "dependencies": {
+    "@gesslar/bedoc": "^1.2.0",
     "commander": "^13.0.0",
     "dotenv": "^16.4.7",
     "error-stack-parser": "^2.1.4",
@@ -27,11 +35,10 @@
     "globby": "^14.0.2",
     "micromatch": "^4.0.8",
     "node-fetch": "^3.3.2",
-    "vscode-uri": "^3.0.8",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin-js": "^2.13.0",
+    "@stylistic/eslint-plugin-js": "^3.0.0",
     "axios": "^1.7.9",
     "chokidar": "^4.0.3",
     "eslint": "^9.18.0",

package/src/cli.js

@@ -63,7 +63,7 @@ const {resolveDirectory} = FDUtil
     }
 
     // Create core instance with validated config
-    BeDoc
+    const bedoc = await BeDoc
       .new({
         options: {
           ...optionsWithSources,
@@ -72,19 +72,20 @@ const {resolveDirectory} = FDUtil
         },
         source: Environment.CLI
       })
-  } catch(e) {
-    if(e instanceof Error) {
-      if(e instanceof AggregateError) {
-        for(const error of e.errors) {
-          console.error(`Error: ${error.message}`)
-        }
-      } else if(e.stack) {
-        console.error(e.stack)
+    const filesToProcess = bedoc.options.input.map(f => f.absolutePath)
+    const result = await bedoc.processFiles(filesToProcess)
+    const errored = result.errored
+    if(errored.length > 0)
+      throw new AggregateError(errored.map(e => e.error), "Error processing files")
+  } catch(error) {
+    if(error instanceof Error) {
+      if(error instanceof AggregateError) {
+        error.errors.forEach(e => console.error(e))
       } else {
-        console.error(`Error: ${e.message}`)
+        console.error(error.message, error.stack)
       }
     } else {
-      console.error(`Error: ${e}`)
+      console.error("Error: %o", error)
     }
 
     process.exit(1)

package/src/core/ActionManager.js

@@ -1,27 +1,26 @@
-import {hookPoints} from "./HooksManager.js"
+import {hookPoints} from "./HookManager.js"
 
 export default class ActionManager {
   #action = null
-  #meta = {}
-  #hooks = null
+  #hookManager = null
   #contract
-  #module
   #log
   #debug
+  #file
 
   constructor(actionDefinition, logger) {
     this.#log = logger
     this.#debug = this.#log.newDebug()
 
-    this.#setupAction(actionDefinition)
+    this.#initialize(actionDefinition)
   }
 
-  #setupAction(actionDefinition) {
+  #initialize(actionDefinition) {
     const debug = this.#debug
 
     debug("Setting up action", 2)
 
-    const {action, contract, module, meta} = actionDefinition
+    const {action, file, contract} = actionDefinition
 
     if(!action)
       throw new Error("Action is required")
@@ -29,13 +28,9 @@ export default class ActionManager {
     if(!contract)
       throw new Error("Contract is required")
 
-    if(!module)
-      throw new Error("Module is required")
-
-    this.#module = module
     this.#action = action
     this.#contract = contract
-    this.#meta = meta
+    this.#file = file
 
     debug("Action setup complete", 2)
   }
@@ -44,33 +39,101 @@ export default class ActionManager {
     return this.#action
   }
 
-  get hooks() {
-    return this.#hooks
+  get hookManager() {
+    return this.#hookManager
   }
 
-  set hooks(hookManager) {
-    if(this.hooks)
+  set hookManager(hookManager) {
+    if(this.hookManager)
       throw new Error("Hooks already set")
 
     this.action.hook = hookManager.on.bind(this.action)
     this.action.HOOKS = hookPoints
+    this.#hookManager = hookManager
     this.action.hooks = hookManager.hooks
-    this.#hooks = hookManager
   }
 
   get contract() {
     return this.#contract
   }
 
-  get module() {
-    return this.#module
-  }
-
   get meta() {
-    return this.#meta
+    return this.#action.meta
   }
 
   get log() {
     return this.#log
   }
+
+  async #setupAction() {
+    const setup = this.action?.setup
+
+    if(!setup)
+      return
+
+    await this.action.setup.call(
+      this.action, {parent: this, log: this.#log}
+    )
+  }
+
+  async #cleanupAction() {
+    const cleanup = this.action?.cleanup
+
+    if(!cleanup)
+      return
+
+    await this.action.cleanup.call(this.action)
+  }
+
+  async #setupHooks() {
+    const setup = this.hookManager?.setup
+
+    if(!setup)
+      return
+
+    await this.hookManager.setup.call(
+      this.hookManager.hooks, {parent: this.action, log: this.#log}
+    )
+  }
+
+  async #cleanupHooks() {
+    const cleanup = this.hookManager?.cleanup
+
+    if(!cleanup)
+      return
+
+    await this.hookManager.cleanup.call(this.hookManager.hooks)
+  }
+
+  async setupAction() {
+    this.#debug("Setting up action for %s", 2, this.meta.action)
+
+    await this.#setupHooks()
+    await this.#setupAction()
+  }
+
+  async runAction({file,content}) {
+    const func = this.action.run
+
+    if(!func)
+      throw new Error(`No \`run\` function found for action \`${this.meta.action}\``)
+
+    const actionResult = await func.call(
+      this.action, {module: file.module, content}
+    )
+
+    return actionResult
+  }
+
+  async cleanupAction() {
+    this.#debug("Post action", 2)
+    this.#debug("Cleaning up action for %s", 2, this.meta.action)
+
+    await this.#cleanupHooks()
+    await this.#cleanupAction()
+  }
+
+  toString() {
+    return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
+  }
 }

package/src/core/Conveyor.js

@@ -1,3 +1,5 @@
+import {format} from "node:util"
+
 import * as FDUtil from "./util/FDUtil.js"
 
 const {readFile, writeFile, composeFilename} = FDUtil
@@ -6,9 +8,9 @@ export default class Conveyor {
   #succeeded = []
   #errored = []
 
-  constructor(parser, printer, logger, output) {
-    this.parser = parser
-    this.printer = printer
+  constructor(parse, print, logger, output) {
+    this.parse = parse
+    this.print = print
     this.logger = logger
     this.output = output
   }
@@ -23,15 +25,19 @@ export default class Conveyor {
   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")
+        if(result.status === "success" || result.status === "warning")
           this.#succeeded.push({input: file, output: result.file})
-        else
+        else {
           this.#errored.push({input: file, error: result.error})
+        }
       }))
       semaphore.shift() // Remove the oldest promise
     }
@@ -39,6 +45,10 @@ export default class Conveyor {
     // Wait for all tasks to complete
     await Promise.all(semaphore)
 
+    // Clean up actions
+    await this.parse.cleanupAction()
+    await this.print.cleanupAction()
+
     return {succeeded: this.#succeeded, errored: this.#errored}
   }
 
@@ -50,6 +60,8 @@ 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)
@@ -59,26 +71,36 @@ export default class Conveyor {
       debug("Read file content `%s` (%d bytes)", 2, file.path, fileContent.length)
 
       // Step 2: Parse file
-      const parseResult = await this.parser.parse(file, fileContent)
+      const parseResult = await parse.runAction({
+        file,
+        content: fileContent
+      })
       if(parseResult.status === "error")
         return parseResult
 
       debug("Parsed file successfully: `%s`", 2, file.path)
 
       // Step 3: Print file
-      const printResult = await this.printer.print(
+      const printResult = await print.runAction({
         file,
-        parseResult.result,
-      )
+        content: parseResult.result,
+      })
       if(printResult.status === "error")
         return printResult
 
       debug("Printed file successfully: `%s`", 2, file.path)
 
       // Step 4: Write output
-      const {destFile, content} = printResult
-      if(!destFile || !content)
-        return {status: "error", message: "Invalid print result"}
+      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 writeResult = await this.#writeOutput(destFile, content)
 
@@ -87,9 +109,7 @@ export default class Conveyor {
 
       return writeResult
     } catch(error) {
-      const mess = `Error processing file ${file.path}: ${error.message}\n${error.stack}`
-      this.logger.error(mess)
-      return {status: "error", error}
+      return {status: "error", file, error}
     }
   }