@gesslar/bedoc 1.4.2 → 1.4.4

package/dist/types/core/ActionManager.d.ts

@@ -1,27 +1,51 @@
-import Logger from './Logger';
-import HookManager from './HookManager';
+import Logger from './Logger'
+import HookManager from './HookManager'
+
+export type MetaActionType = "print" | "parse"
+
+export interface MetaDefinition {
+  action: MetaActionType
+}
+
+export interface ParseMetaDefinition extends MetaDefinition {
+  action: "parse"
+  language: string
+}
+
+export interface PrintMetaDefinition extends MetaDefinition {
+  action: "print"
+  format: string
+}
+
+export type MetaType = ParseMetaDefinition | PrintMetaDefinition
 
 export interface ActionDefinition {
-  action: string;
-  contract: Record<string, unknown>;
-  meta: Record<string, unknown>;
+  meta: MetaType
+}
+
+export interface PrintActionDefinition {
+  meta: PrintMetaDefinition
+}
+
+export interface ParseActionDefinition {
+  meta: ParseMetaDefinition
 }
 
 export default class ActionManager {
-  constructor(actionDefinition: ActionDefinition, logger: Logger);
-  get action(): ActionDefinition;
-  set hookManager(hookManager: HookManager);
-  get hookManager(): HookManager;
-  get contract(): Record<string, unknown>;
-  get meta(): Record<string, unknown>;
-  get log(): Logger;
-  setupAction(): Promise<void>;
+  constructor(actionDefinition: ActionDefinition, logger: Logger)
+  get action(): ActionDefinition
+  set hookManager(hookManager: HookManager)
+  get hookManager(): HookManager
+  get contract(): string
+  get meta(): MetaType
+  get log(): Logger
+  setupAction(): Promise<void>
   runAction({ file, content }: {
-    file: string;
-    content: string;
-  }): Promise<string>;
-  cleanupAction(): Promise<void>;
-  toString(): string;
-  #private;
+    file: string
+    content: string
+  }): Promise<string>
+  cleanupAction(): Promise<void>
+  toString(): string
+  #private
 }
 //# sourceMappingURL=ActionManager.d.ts.map

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

@@ -36,46 +36,45 @@ export const fdTypes: readonly FDType[];
 /**
  * Compose a directory map from a path
  *
- * @param {string} directory - The directory
- * @returns {DirMap} A directory object
+ * @param directory - The directory
+ * @returns 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
+ * @param directoryNameorObject - The directory
+ * @param fileName - The file
+ * @returns 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
+ * @param fileName - The filename to deconstruct
+ * @returns 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
+ * @param pathName - The path to fix
+ * @returns 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.
+ * @param globPattern - The glob pattern(s) to search.
+ * @returns An array of file objects
+ * @throws 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.
+ * @param directory - The directory to list.
+ * @returns The files and sub-directories in the directory.
  */
 export function ls(directory: string): Promise<{
     files: FileMap[];
@@ -84,63 +83,89 @@ export function ls(directory: string): Promise<{
 /**
  * Map a directory to a DirMap
  *
- * @param {string} directoryName - The directory to map
- * @returns {DirMap} A directory object
+ * @param directoryName - The directory to map
+ * @returns 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
+ * @returns A file object
+ */
+
+/**
+ * Check if a file can be read
+ *
+ * @param fileObject - The file object to check
+ * @returns Whether the file can be read
+ */
+export function canReadFile(fileObject: FileMap): boolean;
+
+/**
+ * Check if a file can be written
+ *
+ * @param fileObject - The file object to check
+ * @returns Whether the file can be written
+ */
+export function canWriteFile(fileObject: FileMap): boolean;
+
+/**
+ * Check if a file exists
+ *
+ * @param fileObject - The file object to check
+ * @returns Whether the file exists
+ */
+export function fileExists(fileObject: FileMap): boolean;
+
+/**
+ * Returns a FileMap object for the specified file.
+ *
+ * @param fileName - The file to map
+ * @returns 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
+ * @param pathName - The path to convert
+ * @returns The URI
  */
 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
+ * @param fileObject - The file map containing the file path
+ * @returns 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}
+ * @param directoryName - The path to resolve
+ * @returns The directory object
  */
 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}
+ * @param fileName - The file to resolve
+ * @param directoryObject - The directory object to resolve the file in
+ * @returns A file object (validated)
  */
 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
+ * @param pathName - The URI to convert
+ * @returns The path
  */
 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
+ * @param fileObject - The file map containing the file path
+ * @param content - The content to write
  */
 export function writeFile(fileObject: FileMap, content: string): void;
 //# sourceMappingURL=FDUtil.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "main": "./src/core/Core.js",

package/src/core/Configuration.js

@@ -12,7 +12,8 @@ import * as FDUtil from "./util/FDUtil.js"
 
 const {loadJson} = ActionUtil
 const {isNothing, isType, mapObject} = DataUtil
-const {getFiles, resolveDirectory, resolveFilename} = FDUtil
+const {getFiles, composeFilename, fileExists} = FDUtil
+const {resolveDirectory, resolveFilename} = FDUtil
 const {fdType, fdTypes} = FDUtil
 
 export default class Configuration {
@@ -154,9 +155,11 @@ export default class Configuration {
 
     // Inject packageJson if not available
     if(!options.packageJson) {
-      const jsonFile = resolveFilename("package.json", dir)
-      const jsonObj = loadJson(jsonFile)
-      options.packageJson = {value: jsonObj, source}
+      const jsonFile = composeFilename(dir, "package.json")
+      if(fileExists(jsonFile)) {
+        const jsonObj = loadJson(jsonFile)
+        options.packageJson = {value: jsonObj, source}
+      }
     }
 
     // Add defaults which are missing

package/src/core/Core.js

@@ -28,7 +28,7 @@ export default class Core {
     this.options = options
     const {debug: debugMode, debugLevel} = options
     this.logger = new Logger({name: "BeDoc", debugMode, debugLevel})
-    this.packageJson = loadPackageJson()?.bedoc ?? {}
+    this.packageJson = loadPackageJson(options.basePath)?.bedoc ?? {}
     this.debugOptions = this.logger.options
   }
 

package/src/core/util/ActionUtil.js

@@ -1,6 +1,6 @@
 import * as FDUtil from "./FDUtil.js"
 
-const {readFile, resolveFilename} = FDUtil
+const {readFile, fileExists, composeFilename} = FDUtil
 
 const freeze = Object.freeze
 
@@ -27,14 +27,18 @@ function loadJson(jsonFileObject) {
 /**
  * Loads the package.json file asynchronously
  *
- * @param {string|object} basePath - The base path to use
- * @returns {object} The parsed package.json content
+ * @param {string|object|null} basePath - The base path to use
+ * @returns {object?} The parsed package.json content or null if the file does
+ *                    not exist
  */
 function loadPackageJson(basePath = null) {
-  const packageJsonFileObject = resolveFilename("./package.json", basePath)
-  const jsonContent = readFile(packageJsonFileObject)
-  const json = JSON.parse(jsonContent)
-  return json
+  const packageJsonFileObject = composeFilename(basePath, "./package.json")
+  if(fileExists(packageJsonFileObject)) {
+    const jsonContent = readFile(packageJsonFileObject)
+    const json = JSON.parse(jsonContent)
+    return json
+  } else
+    return null
 }
 
 export {

package/src/core/util/FDUtil.js

@@ -42,6 +42,51 @@ function pathToUri(pathName) {
   }
 }
 
+/**
+ * Check if a file can be read. Returns true if the file can be read, false
+ *
+ * @param {FileMap} FileMap - The file map to check
+ * @returns {boolean} Whether the file can be read
+ */
+function canReadFile(FileMap) {
+  try {
+    fs.accessSync(FileMap.absolutePath, fs.constants.R_OK)
+    return true
+  } catch(_error) {
+    return false
+  }
+}
+
+/**
+ * Check if a file can be written. Returns true if the file can be written,
+ *
+ * @param {FileMap} FileMap - The file map to check
+ * @returns {boolean} Whether the file can be written
+ */
+function canWriteFile(FileMap) {
+  try {
+    fs.accessSync(FileMap.absolutePath, fs.constants.W_OK)
+    return true
+  } catch(error) {
+    return false
+  }
+}
+
+/**
+ * Check if a file exists
+ *
+ * @param {FileMap} FileMap - The file map to check
+ * @returns {boolean} Whether the file exists
+ */
+function fileExists(FileMap) {
+  try {
+    fs.accessSync(FileMap.absolutePath)
+    return true
+  } catch(error) {
+    return false
+  }
+}
+
 /**
  * Convert a URI to a path
  *
@@ -78,14 +123,16 @@ function resolveFilename(fileName, directoryObject = null) {
     directoryObject = resolveDirectory(directoryNamePart)
 
   const fileObject = composeFilename(directoryObject, fileNamePart)
-  try {
-    fs.opendirSync(directoryObject.absolutePath).closeSync()
-  } catch(e) {
-    void e
+
+  if(!fileObject)
     throw new Error(
-      `Failed to resolve directory: ${directoryObject.absolutePath}, looking for file: ${fileNamePart}`,
+      `Failed to resolve file: ${fileName}, looking for file: ${fileNamePart}`,
+    )
+
+  if(!fileExists(fileObject))
+    throw new Error(
+      `Failed to resolve file: ${fileObject.absolutePath}`,
     )
-  }
 
   return {
     ...fileObject,
@@ -305,9 +352,12 @@ export {
   fdType,
   fdTypes,
   // Functions
+  canReadFile,
+  canWriteFile,
   composeDirectory,
   composeFilename,
   deconstructFilenameToParts,
+  fileExists,
   fixSlashes,
   getFiles,
   ls,