@gesslar/bedoc 1.4.1 → 1.4.3

package/dist/types/cli.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map
+export {}
+//# sourceMappingURL=cli.d.ts.map

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

@@ -2,26 +2,26 @@ import Logger from './Logger';
 import HookManager from './HookManager';
 
 export interface ActionDefinition {
-    action: string;
-    contract: Record<string, unknown>;
-    meta: Record<string, unknown>;
+  action: string;
+  contract: Record<string, unknown>;
+  meta: Record<string, unknown>;
 }
 
 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>;
-    runAction({ file, content }: {
-        file: string;
-        content: string;
-    }): Promise<string>;
-    cleanupAction(): Promise<void>;
-    toString(): string;
-    #private;
+  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>;
+  runAction({ file, content }: {
+    file: string;
+    content: string;
+  }): Promise<string>;
+  cleanupAction(): Promise<void>;
+  toString(): string;
+  #private;
 }
 //# sourceMappingURL=ActionManager.d.ts.map

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

@@ -1,27 +1,27 @@
 import { EnvironmentType } from './Core';
 
 interface ConfigurationOption {
-    value: unknown;
-    source: string;
+  value: unknown;
+  source: string;
 }
 
 interface ConfigurationOptions {
-    [key: string]: ConfigurationOption;
+  [key: string]: ConfigurationOption;
 }
 
 interface ValidateParams {
-    options: ConfigurationOptions;
-    source: EnvironmentType;
+  options: ConfigurationOptions;
+  source: EnvironmentType;
 }
 
 interface ValidationResult {
-    status: 'success';
-    validated: boolean;
-    [key: string]: unknown;
+  status: 'success';
+  validated: boolean;
+  [key: string]: unknown;
 }
 
 export default class Configuration {
-    validate({ options, source }: ValidateParams): Promise<ValidationResult>;
-    #private;
+  validate({ options, source }: ValidateParams): Promise<ValidationResult>;
+  #private;
 }
 //# sourceMappingURL=Configuration.d.ts.map

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

@@ -1,36 +1,36 @@
 import TypeSpec from './util/TypeSpec';
 
 interface PathConfig {
-    type: 'file' | 'directory';
-    mustExist: boolean;
+  type: 'file' | 'directory';
+  mustExist: boolean;
 }
 
 interface ConfigurationParameter {
-    short: string;
-    param?: string;
-    description: string;
-    type: TypeSpec;
-    required: boolean;
-    default?: boolean | number | string;
-    path?: PathConfig;
-    exclusiveOf?: string;
+  short: string;
+  param?: string;
+  description: string;
+  type: TypeSpec;
+  required: boolean;
+  default?: boolean | number | string;
+  path?: PathConfig;
+  exclusiveOf?: string;
 }
 
 interface ConfigurationParametersType {
-    input: ConfigurationParameter;
-    exclude: ConfigurationParameter;
-    language: ConfigurationParameter;
-    format: ConfigurationParameter;
-    maxConcurrent: ConfigurationParameter;
-    hooks: ConfigurationParameter;
-    output: ConfigurationParameter;
-    parser: ConfigurationParameter;
-    printer: ConfigurationParameter;
-    hookTimeout: ConfigurationParameter;
-    mock: ConfigurationParameter;
-    config: ConfigurationParameter;
-    debug: ConfigurationParameter;
-    debugLevel: ConfigurationParameter;
+  input: ConfigurationParameter;
+  exclude: ConfigurationParameter;
+  language: ConfigurationParameter;
+  format: ConfigurationParameter;
+  maxConcurrent: ConfigurationParameter;
+  hooks: ConfigurationParameter;
+  output: ConfigurationParameter;
+  parser: ConfigurationParameter;
+  printer: ConfigurationParameter;
+  hookTimeout: ConfigurationParameter;
+  mock: ConfigurationParameter;
+  config: ConfigurationParameter;
+  debug: ConfigurationParameter;
+  debugLevel: ConfigurationParameter;
 }
 
 export const ConfigurationParameters: Readonly<ConfigurationParametersType>;

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

@@ -3,45 +3,47 @@ import Logger from './Logger';
 import { FileMap } from './util/FDUtil';
 
 interface ProcessResult {
-    status: 'success' | 'error' | 'warning';
-    file?: FileMap;
-    error?: Error;
-    warning?: string;
-    result?: string;
-    destFile?: string;
-    content?: string;
+  status: 'success' | 'error' | 'warning';
+  file?: FileMap;
+  error?: Error;
+  warning?: string;
+  result?: string;
+  destFile?: string;
+  content?: string;
 }
 
-interface ConveyResult {
-    succeeded: Array<{ input: FileMap; output: FileMap }>;
-    errored: Array<{ input: FileMap; error: Error }>;
+export interface ConveyResult {
+  succeeded: Array<{ input: FileMap; output: FileMap }>;
+  errored: Array<{ input: FileMap; error: Error }>;
+  warned: Array<{ input: FileMap; warning: string }>;
 }
 
 export default class Conveyor {
-    constructor(
-        parse: ActionManager,
-        print: ActionManager,
-        logger: Logger,
-        output: FileMap
-    );
+  constructor(
+    parse: ActionManager,
+    print: ActionManager,
+    logger: Logger,
+    output: FileMap
+  );
 
-    readonly parse: ActionManager;
-    readonly print: ActionManager;
-    readonly logger: Logger;
-    readonly output: FileMap;
+  readonly parse: ActionManager;
+  readonly print: ActionManager;
+  readonly logger: Logger;
+  readonly output: FileMap;
 
-    /**
-     * Processes files with a concurrency limit.
-     *
-     * @param files - List of files to process.
-     * @param maxConcurrent - Maximum number of concurrent tasks.
-     * @returns Resolves when all files are processed.
-     */
-    convey(files: FileMap[], maxConcurrent?: number): Promise<ConveyResult>;
+  /**
+   * Processes files with a concurrency limit.
+   *
+   * @param files - List of files to process.
+   * @param maxConcurrent - Maximum number of concurrent tasks.
+   * @returns Resolves when all files are processed.
+   */
+  convey(files: FileMap[], maxConcurrent?: number): Promise<ConveyResult>;
 
-    #succeeded: Array<{ input: FileMap; output: FileMap }>;
-    #errored: Array<{ input: FileMap; error: Error }>;
-    #processFile(file: FileMap): Promise<ProcessResult>;
-    #writeOutput(destFile: string, content: string): Promise<ProcessResult>;
+  #succeeded: Array<{ input: FileMap; output: FileMap }>;
+  #errored: Array<{ input: FileMap; error: Error }>;
+  #warned: Array<{ input: FileMap; warning: string }>;
+  #processFile(file: FileMap): Promise<ProcessResult>;
+  #writeOutput(destFile: string, content: string): Promise<ProcessResult>;
 }
 //# sourceMappingURL=Conveyor.d.ts.map

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

@@ -1,53 +1,48 @@
 import Logger from './Logger';
 import ActionManager from './ActionManager';
-import { FileMap } from './util/FDUtil';
+import { ConveyResult} from './Conveyor';
 
 export const Environment: Readonly<{
-    EXTENSION: 'extension';
-    NPM: 'npm';
-    ACTION: 'action';
-    CLI: 'cli';
+  EXTENSION: 'extension';
+  NPM: 'npm';
+  ACTION: 'action';
+  CLI: 'cli';
 }>;
 
 export type EnvironmentType = typeof Environment[keyof typeof Environment];
 
 interface CoreOptions {
-    debug?: boolean;
-    debugLevel?: number;
-    name?: string;
-    [key: string]: unknown;
+  debug?: boolean;
+  debugLevel?: number;
+  name?: string;
+  [key: string]: unknown;
 }
 
 interface CoreConstructorOptions extends CoreOptions {
-    hooks?: string;
-    hooksTimeout?: number;
-    output?: string;
-    maxConcurrent?: number;
+  hooks?: string;
+  hooksTimeout?: number;
+  output?: string;
+  maxConcurrent?: number;
 }
 
 interface NewParams {
-    options: CoreOptions;
-    source: EnvironmentType;
-}
-
-interface ProcessResult {
-    succeeded: Array<{ input: FileMap; output: FileMap }>;
-    errored: Array<{ input: FileMap; error: Error }>;
+  options: CoreOptions;
+  source: EnvironmentType;
 }
 
 export default class Core {
-    static new({ options, source }: NewParams): Promise<Core>;
+  static new({ options, source }: NewParams): Promise<Core>;
 
-    constructor(options: CoreConstructorOptions);
+  constructor(options: CoreConstructorOptions);
 
-    readonly options: CoreConstructorOptions;
-    readonly logger: Logger;
-    readonly packageJson: Record<string, unknown>;
-    readonly debugOptions: {
-        name: string | null;
-        debugLevel: number;
-    };
-    readonly actions: Record<string, ActionManager>;
+  readonly options: CoreConstructorOptions;
+  readonly logger: Logger;
+  readonly packageJson: Record<string, unknown>;
+  readonly debugOptions: {
+    name: string | null;
+    debugLevel: number;
+  };
+  readonly actions: Record<string, ActionManager>;
 
-    processFiles(glob: string | string[], startTime?: [number, number]): Promise<ProcessResult>;
+  processFiles(glob: string | string[], startTime?: [number, number]): Promise<ConveyResult>;
 }

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.1",
+  "version": "1.4.3",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "main": "./src/core/Core.js",
@@ -18,6 +18,13 @@
     ".": {
       "import": "./src/core/Core.js",
       "types": "./dist/types/core/Core.d.ts"
+    },
+    "./BeDoc": {
+      "import": "./src/core/Core.js",
+      "types": "./dist/types/core/Core.d.ts"
+    },
+    "./*": {
+      "types": "./dist/types/*"
     }
   },
   "type": "module",
@@ -38,6 +45,8 @@
   },
   "devDependencies": {
     "@stylistic/eslint-plugin-js": "^3.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.22.0",
+    "@typescript-eslint/parser": "^8.22.0",
     "axios": "^1.7.9",
     "chokidar": "^4.0.3",
     "eslint": "^9.18.0",

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,