@black-flag/core/dist/src/error.js

A declarative framework for building fluent, deeply hierarchical command line interfaces with yargs

"use strict";

Object.defineProperty(exports, "__esModule", {
  value: true
});
exports.GracefulEarlyExitError = exports.CommandNotImplementedError = exports.CliError = exports.BfErrorMessage = exports.AssertionFailedError = exports.$type = void 0;
exports.isCliError = isCliError;
exports.isCommandNotImplementedError = isCommandNotImplementedError;
exports.isGracefulEarlyExitError = isGracefulEarlyExitError;
exports.isYargsError = isYargsError;
var _types = require("node:util/types");
var _namedAppErrors = require("named-app-errors");
var _constant = require("./constant.js");
function isYargsError(parameter) {
  return (0, _types.isNativeError)(parameter) && parameter.name === 'YError';
}
const $type = exports.$type = Symbol.for('object-type-hint');
function isCliError(parameter) {
  return (0, _types.isNativeError)(parameter) && $type in parameter && Array.isArray(parameter[$type]) && parameter[$type].includes(CliError.name);
}
function isGracefulEarlyExitError(parameter) {
  return (0, _types.isNativeError)(parameter) && $type in parameter && Array.isArray(parameter[$type]) && parameter[$type].includes(GracefulEarlyExitError.name);
}
function isCommandNotImplementedError(parameter) {
  return (0, _types.isNativeError)(parameter) && $type in parameter && Array.isArray(parameter[$type]) && parameter[$type].includes(CommandNotImplementedError.name);
}
class CliError extends _namedAppErrors.AppError {
  suggestedExitCode = _constant.FrameworkExitCode.DefaultError;
  showHelp = 'default';
  dangerouslyFatal = false;
  [$type] = ['CliError'];
  constructor(reason, options = {}, message = undefined, superOptions = {}) {
    const {
      suggestedExitCode,
      showHelp,
      dangerouslyFatal
    } = options;
    let {
      cause
    } = options;
    message = message ?? (typeof reason === 'string' ? reason : reason?.message) ?? BfErrorMessage.Generic();
    if (!('cause' in options)) {
      cause = typeof reason === 'string' ? undefined : reason;
    }
    super(message, {
      cause,
      ...superOptions
    });
    if (suggestedExitCode !== undefined) {
      this.suggestedExitCode = suggestedExitCode;
    }
    if (showHelp !== undefined) {
      this.showHelp = showHelp === true ? 'short' : showHelp;
    }
    if (dangerouslyFatal !== undefined) {
      this.dangerouslyFatal = dangerouslyFatal;
    }
  }
}
exports.CliError = CliError;
(0, _namedAppErrors.makeNamedError)(CliError, 'CliError');
class CommandNotImplementedError extends CliError {
  [$type] = ['CommandNotImplementedError', 'CliError'];
  constructor(error, options) {
    super(error ? error.message : BfErrorMessage.CommandNotImplemented(), {
      ...(error ? {
        cause: error
      } : {}),
      showHelp: false,
      ...options,
      suggestedExitCode: _constant.FrameworkExitCode.NotImplemented
    });
  }
}
exports.CommandNotImplementedError = CommandNotImplementedError;
(0, _namedAppErrors.makeNamedError)(CommandNotImplementedError, 'CommandNotImplementedError');
class GracefulEarlyExitError extends CliError {
  [$type] = ['GracefulEarlyExitError', 'CliError'];
  constructor(reason, options) {
    super(reason ? typeof reason === 'string' ? reason : reason.message : BfErrorMessage.GracefulEarlyExit(), {
      ...(reason ? {
        cause: typeof reason === 'string' ? new Error(reason) : reason
      } : {}),
      showHelp: false,
      ...options,
      suggestedExitCode: _constant.FrameworkExitCode.Ok,
      dangerouslyFatal: false
    });
  }
}
exports.GracefulEarlyExitError = GracefulEarlyExitError;
(0, _namedAppErrors.makeNamedError)(GracefulEarlyExitError, 'GracefulEarlyExitError');
class AssertionFailedError extends CliError {
  [$type] = ['AssertionFailedError', 'CliError'];
  constructor(errorOrMessage, options) {
    super(typeof errorOrMessage === 'string' ? errorOrMessage : errorOrMessage?.message, {
      showHelp: false,
      ...options,
      suggestedExitCode: _constant.FrameworkExitCode.AssertionFailed,
      cause: errorOrMessage
    });
  }
}
exports.AssertionFailedError = AssertionFailedError;
(0, _namedAppErrors.makeNamedError)(AssertionFailedError, 'AssertionFailedError');
const BfErrorMessage = exports.BfErrorMessage = {
  GuruMeditation: _namedAppErrors.ErrorMessage.GuruMeditation,
  BuilderCalledOnInvalidPass(pass) {
    return `a builder function was invoked during Black Flag's ${pass.replace('-', ' ')} when it expected to be invoked during its ${pass === 'first-pass' ? 'second pass' : 'first pass'} instead`;
  },
  BuilderCannotBeAsync(commandName) {
    return `command "${commandName}" exported an asynchronous builder function, which triggers buggy behavior in Yargs. Black Flag supports exporting an asynchronous default function in CJS files and top-level await in ESM files, so hoist any async logic out of this command's builder. See the documentation for details`;
  },
  Generic() {
    return 'an error occurred that caused this software to crash';
  },
  CommandNotImplemented() {
    return 'this command is currently unimplemented';
  },
  InvalidSubCommandInvocation() {
    return 'invalid subcommand: you must call this with a valid subcommand argument';
  },
  FrameworkError(error) {
    return `UNHANDLED FRAMEWORK EXCEPTION: an error occurred due to a misconfiguration. This is typically due to developer error and as such cannot be fixed by end-users. Please report this incident to the developer of this application. For more information about this error, rerun the command with the DEBUG='bf:*' or DEBUG='*' environment variable set.\n\nException details: ${(0, _types.isNativeError)(error) ? error.stack || error : String(error)}`;
  },
  GracefulEarlyExit() {
    return 'execution is ending exceptionally early, which is not a bad thing!';
  },
  ConfigLoadFailure(path) {
    return `failed to load configuration from file: ${path}`;
  },
  InvalidConfigureArgumentsReturnType() {
    return 'configureArguments must return typeof process.argv';
  },
  InvalidConfigureExecutionEpilogueReturnType() {
    return 'configureExecutionEpilogue must return Arguments';
  },
  InvalidConfigureExecutionContextReturnType() {
    return 'configureExecutionContext must return ExecutionContext';
  },
  InvalidExecutionContextBadField(fieldName) {
    return `encountered invalid or impossible value for ExecutionContext field "${fieldName}"`;
  },
  InvalidCharacters(str, violation) {
    return `string "${str}" contains one or more illegal characters: ${violation}`;
  },
  PathIsNotDirectory() {
    return 'path is not a directory';
  },
  DuplicateCommandName(parentFullName, name1, type1, name2, type2) {
    return (parentFullName ? `one or more child commands of "${parentFullName}" are` : `the root command is`) + ` attempting to register conflicting command names and/or aliases: "${name1}" (${type1}) conflicts with "${name2}" (${type2})`;
  },
  InvalidCommandExportBadStart(name) {
    return `the ${name}'s command export must start with either "$0" or "$0 "`;
  },
  InvalidCommandExportBadPositionals(name) {
    return `the ${name}'s command export must be a valid Yargs command DSL string. See: https://github.com/yargs/yargs/blob/main/docs/advanced.md#positional-arguments for examples`;
  },
  NoConfigurationLoaded(path) {
    return `auto-discovery failed to find any valid configuration files or directories at path: ${path}`;
  },
  BadConfigurationPath(path) {
    return `auto-discovery failed because configuration module path is unreadable or does not exist: "${String(path)}"`;
  },
  InvocationNotAllowed(name) {
    return `invocation of method "${name}" is not allowed here. See documentation for details`;
  },
  CannotExecuteMultipleTimes() {
    return 'Yargs does not support safely calling "parse"/"parseAsync" more than once on the same instance. See documentation for details';
  },
  BadParameterCombination() {
    return 'must provide exactly one of the following options: configurationHooks, preExecutionContext';
  },
  UseParseAsyncInstead() {
    return '"parseSync" is not supported. Use "parseAsync" instead';
  }
};