diff --git a/dashboard.sh b/dashboard.sh index 99796dc..866bacb 100755 --- a/dashboard.sh +++ b/dashboard.sh @@ -41,17 +41,18 @@ _error() { printf '[ERROR] %s\n' "$1" >&2 } -REPORTER_TO_RUN="" -REPORTER_ARGS=() +OVERVIEW_TO_RUN="" +OVERVIEW_ARGS=() usage() { echo "Usage: $(basename "$0") [options] [module]" - echo " or: $(basename "$0") -r [reporter_options]" + echo " or: $(basename "$0") -o [overview_options]" echo echo "Options:" echo " -f, --format Set the output format for module runs." echo " Supported formats: ${VALID_FORMATS[*]}" - echo " -r, --reporter Run a specific reporter." + echo " -o, --overview Run a specific overview." + echo " -v, --verbose Enable verbose (debug) mode." echo " -h, --help Display this help message." echo echo "To save a data collection report, redirect the output to a file:" @@ -66,17 +67,17 @@ usage() { done echo " ${modules[*]}" echo - echo "Available reporters:" - local reporters=() - for reporter in "${SCRIPT_DIR}/reporters"/*; do - if [ -x "$reporter" ]; then - reporters+=("$(basename "$reporter" .sh)") + echo "Available overviews:" + local overviews=() + for overview in "${SCRIPT_DIR}/overviews"/*.sh; do + if [ -x "$overview" ]; then + overviews+=("$(basename "$overview" .sh)") fi done - echo " ${reporters[*]}" + echo " ${overviews[*]}" echo echo "If a module name (e.g., 'github') is provided, only that module will be run." - echo "If a reporter is specified with -r, it will be run with any subsequent arguments." + echo "If an overview is specified with -o, it will be run with any subsequent arguments." } _debug "$DASHBOARD_NAME v$DASHBOARD_VERSION" @@ -86,16 +87,20 @@ _debug 'parsing command-line arguments' while [[ $# -gt 0 ]]; do key="$1" case $key in - -r|--reporter) - REPORTER_TO_RUN="$2" + -o|--overview) + OVERVIEW_TO_RUN="$2" shift 2 - REPORTER_ARGS=("$@") - break # Stop parsing, the rest of the args are for the reporter + OVERVIEW_ARGS=("$@") + break # Stop parsing, the rest of the args are for the overview ;; -f|--format) FORMAT="$2" shift 2 ;; + -v|--verbose) + DASHBOARD_DEBUG=1 + shift + ;; -h|--help) usage exit 0 @@ -115,27 +120,27 @@ done # --- Main Execution Flow ---------------------------------------------------- -if [ -n "$REPORTER_TO_RUN" ]; then - # --- Reporter Execution ------------------------------------------------- - _debug "Attempting to run reporter: $REPORTER_TO_RUN" - REPORTER_PATH="${SCRIPT_DIR}/reporters/${REPORTER_TO_RUN}.sh" - if [ ! -f "$REPORTER_PATH" ]; then +if [ -n "$OVERVIEW_TO_RUN" ]; then + # --- Overview Execution ------------------------------------------------- + _debug "Attempting to run overview: $OVERVIEW_TO_RUN" + OVERVIEW_PATH="${SCRIPT_DIR}/overviews/${OVERVIEW_TO_RUN}.sh" + if [ ! -f "$OVERVIEW_PATH" ]; then # try without .sh extension for convenience - REPORTER_PATH="${SCRIPT_DIR}/reporters/${REPORTER_TO_RUN}" - if [ ! -f "$REPORTER_PATH" ]; then - _error "Error: Reporter '${REPORTER_TO_RUN}' not found." + OVERVIEW_PATH="${SCRIPT_DIR}/overviews/${OVERVIEW_TO_RUN}" + if [ ! -f "$OVERVIEW_PATH" ]; then + _error "Error: Overview '${OVERVIEW_TO_RUN}' not found." exit 1 fi fi - if [ ! -x "$REPORTER_PATH" ]; then - _error "Error: Reporter '${REPORTER_TO_RUN}' is not executable." + if [ ! -x "$OVERVIEW_PATH" ]; then + _error "Error: Overview '${OVERVIEW_TO_RUN}' is not executable." exit 1 fi - _debug "Executing reporter '$REPORTER_PATH' with args: ${REPORTER_ARGS[*]}" + _debug "Executing overview '$OVERVIEW_PATH' with args: ${OVERVIEW_ARGS[*]}" # shellcheck source=/dev/null - "$REPORTER_PATH" "${REPORTER_ARGS[@]}" + "$OVERVIEW_PATH" "${OVERVIEW_ARGS[@]}" else # --- Module Data Collection --------------------------------------------- @@ -169,6 +174,9 @@ else fi generate_report() { + if [ ${#OUTPUTS[@]} -eq 0 ]; then + return + fi # The OUTPUTS array contains TSV data from the modules. # We now format it based on the user's requested FORMAT. @@ -344,7 +352,11 @@ else fi done - generate_report + if [ ${#OUTPUTS[@]} -eq 0 ]; then + echo "No data collected. Use --verbose for more details." + else + generate_report + fi fi _debug 'Done.' diff --git a/docs/dashboard-reporters.md b/docs/dashboard-overviews.md similarity index 63% rename from docs/dashboard-reporters.md rename to docs/dashboard-overviews.md index eb3a089..656dd18 100644 --- a/docs/dashboard-reporters.md +++ b/docs/dashboard-overviews.md @@ -1,39 +1,39 @@ -# Reporters +# Overviews -Reporters are scripts that analyze the historical data collected by the modules. While the modules are responsible for _gathering_ data, reporters are responsible for _interpreting_ it. +Overviews are scripts that analyze the historical data collected by the modules. While the modules are responsible for _gathering_ data, overviews are responsible for _interpreting_ it. -## How to Run a Reporter +## How to Run an Overview -You can run any reporter using the `-r` flag on the main `dashboard.sh` script: +You can run any overview using the `-o` flag on the main `dashboard.sh` script: ```bash -./dashboard.sh -r [reporter_options] +./dashboard.sh -o [overview_options] ``` -For example, to run the `top-stars` reporter, you would use: +For example, to run the `top-stars` overview, you would use: ```bash -./dashboard.sh -r top-stars +./dashboard.sh -o top-stars ``` -Some reporters accept their own arguments, which you can pass after the reporter's name: +Some overviews accept their own arguments, which you can pass after the overview's name: ```bash -./dashboard.sh -r top-stars 5 +./dashboard.sh -o top-stars 5 ``` -## Available Reporters +## Available Overviews -Here is a list of the currently available reporters. +Here is a list of the currently available overviews. ### `trending` -The `trending` reporter shows the change in each metric over a period of time, but it only includes metrics that have actually changed. It reads all the `.tsv` report files from the `reports/` directory and calculates the difference between the first and last recorded values for each metric, filtering out any that have a change of zero. +The `trending` overview shows the change in each metric over a period of time, but it only includes metrics that have actually changed. It reads all the `.tsv` report files from the `reports/` directory and calculates the difference between the first and last recorded values for each metric, filtering out any that have a change of zero. **Usage:** ```bash -./dashboard.sh -r trending [days] +./dashboard.sh -o trending [days] ``` - **`[days]`** (optional): The number of days of history to analyze. @@ -57,12 +57,12 @@ Change Last Value First Value Metrics ### `top-stars` -The `top-stars` reporter finds the most recent report file and lists the top repositories by their star count. +The `top-stars` overview finds the most recent report file and lists the top repositories by their star count. **Usage:** ```bash -./dashboard.sh -r top-stars [count] +./dashboard.sh -o top-stars [count] ``` - **`[count]`** (optional): The number of top repositories to display. Defaults to 10. @@ -76,14 +76,14 @@ Rank Stars Repository 1 1 attogram/dashboard ``` -## Creating Your Own Reporter +## Creating Your Own Overview -You can easily create your own reporter by adding a new executable shell script to the `reporters/` directory. +You can easily create your own overview by adding a new executable shell script to the `overviews/` directory. -A reporter script should: +An overview script should: -1. Be placed in the `reporters/` directory. -2. Be executable (`chmod +x reporters/my_reporter.sh`). +1. Be placed in the `overviews/` directory. +2. Be executable (`chmod +x overviews/my_overview.sh`). 3. Read data from the `.tsv` files in the `reports/` directory. The path to the reports directory can be found relative to the script's own location: `REPORTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../reports"`. 4. Parse its own arguments if needed. 5. Print its analysis to standard output. diff --git a/docs/dashboard-script.md b/docs/dashboard-script.md index 8d6c72e..99eb32f 100644 --- a/docs/dashboard-script.md +++ b/docs/dashboard-script.md @@ -1,6 +1,6 @@ # The Main Script (`dashboard.sh`) -The `dashboard.sh` script is the main entry point for the application. It serves as an orchestrator, responsible for parsing arguments, loading configuration, and running modules for data collection, or running reporters for data analysis. +The `dashboard.sh` script is the main entry point for the application. It serves as an orchestrator, responsible for parsing arguments, loading configuration, and running modules for data collection, or running overviews for data analysis. ## Usage @@ -10,16 +10,17 @@ To collect data from modules: ./dashboard.sh [options] [module] ``` -To run a reporter: +To run an overview: ``` -./dashboard.sh -r [reporter_options] +./dashboard.sh -o [overview_options] ``` ### Options - `-f, --format `: (For module runs only) Specify the output format. See [Output Formats](./dashboard-output-formats.md) for a full list of supported formats. If not provided, the default is `tsv`. -- `-r, --reporter `: Run a specific reporter from the `reporters/` directory. Any subsequent arguments will be passed to the reporter script. +- `-o, --overview `: Run a specific overview from the `overviews/` directory. Any subsequent arguments will be passed to the overview script. +- `-v, --verbose`: Enable verbose (debug) mode, which prints detailed messages about the script's execution to standard error. - `-h, --help`: Display a help message with usage information and exit. ### Arguments @@ -32,7 +33,7 @@ The script has two main modes of operation: data collection and reporting. ### Data Collection Mode -This is the default mode when the `-r` flag is not used. +This is the default mode when the `-o` flag is not used. 1. **Argument Parsing**: It parses command-line options (`-f`, `-h`) and an optional module name. @@ -46,10 +47,10 @@ This is the default mode when the `-r` flag is not used. 5. **Report Generation**: The script collects the output from each executed module. For structured formats like `json`, `xml`, and `html`, it wraps the collected outputs with the appropriate root elements. For simpler formats like `plain` or `csv`, it concatenates the outputs. The final report is printed to standard output, which can be redirected to a file. -### Reporter Mode +### Overview Mode -This mode is triggered by the `-r` flag. +This mode is triggered by the `-o` flag. -1. **Argument Parsing**: The script looks for the `-r` flag. When found, it takes the next argument as the reporter's name. All following arguments are passed directly to the reporter. +1. **Argument Parsing**: The script looks for the `-o` flag. When found, it takes the next argument as the overview's name. All following arguments are passed directly to the overview. -2. **Reporter Execution**: The script looks for an executable file with the given name in the `reporters/` directory and runs it, passing along any reporter-specific arguments. The output of the reporter is printed to standard output. +2. **Overview Execution**: The script looks for an executable file with the given name in the `overviews/` directory and runs it, passing along any overview-specific arguments. The output of the overview is printed to standard output. diff --git a/modules/crypto.sh b/modules/crypto.sh index 863dfc4..e71fdbb 100755 --- a/modules/crypto.sh +++ b/modules/crypto.sh @@ -57,10 +57,17 @@ get_provider() { # --- Provider Implementations --- fetch_from_local_btc() { - if ! command -v bitcoin-cli &> /dev/null; then return 1; fi - local btc_info wallet_name balance display_name + if ! command -v bitcoin-cli &> /dev/null; then + echo "[ERROR] bitcoin-cli not found. Please install Bitcoin Core and ensure bitcoin-cli is in your PATH." >&2 + return 1 + fi + local btc_info btc_info=$(bitcoin-cli getwalletinfo 2>/dev/null) - if [ $? -ne 0 ]; then return 1; fi + if [ $? -ne 0 ]; then + echo "[ERROR] bitcoin-cli command failed. Please ensure your Bitcoin node is running and configured correctly." >&2 + return 1 + fi + local wallet_name balance display_name wallet_name=$(echo "$btc_info" | jq -r '.walletname') balance=$(echo "$btc_info" | jq -r '.balance') display_name="local node ($wallet_name)" diff --git a/overviews/README.md b/overviews/README.md new file mode 100644 index 0000000..d87afff --- /dev/null +++ b/overviews/README.md @@ -0,0 +1,16 @@ +# Overviews + +This directory contains scripts that analyze the historical data collected by the modules. + +## Available Overviews + +Here is a list of the currently available overviews: + +- **`trending`**: Shows the change in each metric over a period of time. +- **`top-stars`**: Lists the top repositories by their star count from the most recent report. + +## Creating Your Own Overview + +You can easily create your own overview by adding a new executable shell script to this directory. An overview script should be executable and placed in this directory. + +For more detailed documentation, please see the main project documentation in the `docs/` directory. diff --git a/reporters/top-stars.sh b/overviews/top-stars.sh similarity index 100% rename from reporters/top-stars.sh rename to overviews/top-stars.sh diff --git a/reporters/trending.sh b/overviews/trending.sh similarity index 99% rename from reporters/trending.sh rename to overviews/trending.sh index 6b1442d..95260d8 100755 --- a/reporters/trending.sh +++ b/overviews/trending.sh @@ -106,5 +106,5 @@ END { ( echo -e "Change\tLast\tFirst\tmodule\tchannels\tnamespace" echo -e "------\t----\t-----\t------\t--------\t---------" - sort -k1,1nr + sort -k1,1gr ) diff --git a/reporters/README.md b/reporters/README.md deleted file mode 100644 index 676c344..0000000 --- a/reporters/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Reporters - -This directory contains scripts that analyze the historical data collected by the modules. - -## Known Issues - -### Date-based Filtering - -The `timespan` reporter is intended to support filtering by a number of days. The `hot` reporter (not yet implemented) would also rely on this functionality. - -Currently, this feature is **not functional** due to limitations in the `date` command available in the execution environment. The `date -d` command is unable to parse the ISO-8601-like timestamps from the report filenames, which prevents the scripts from reliably filtering reports by date. - -Because of this environmental constraint: - -- The `timespan` reporter will always analyze the full history of reports, regardless of the `[days]` argument. -- The `hot` reporter has not been implemented, as its core logic is not possible to build reliably. - -This issue will need to be resolved by either fixing the `date` utility in the environment or by providing an alternative date parsing method. diff --git a/test/crypto.bats b/test/crypto.bats index 11a248b..95f8642 100644 --- a/test/crypto.bats +++ b/test/crypto.bats @@ -55,6 +55,7 @@ teardown() { CRYPTO_WALLET_BTC="test_btc_address" \ bash modules/crypto.sh [ "$status" -eq 0 ] + echo "Blockcypher Output: $output" [[ "$output" =~ .*${tab}crypto${tab}balance${tab}crypto.BTC.test_btc_address.BTC${tab}0.12345678$ ]] } @@ -64,6 +65,7 @@ teardown() { CRYPTO_WALLET_ETH="test_eth_address" \ bash modules/crypto.sh [ "$status" -eq 0 ] + echo "Covalent Output: $output" [[ "$output" =~ .*${tab}crypto${tab}balance${tab}crypto.ETH.test_eth_address.ETH${tab}1.234$ ]] } diff --git a/test/dashboard.bats b/test/dashboard.bats old mode 100644 new mode 100755 index 72977de..99084fc --- a/test/dashboard.bats +++ b/test/dashboard.bats @@ -33,9 +33,9 @@ teardown() { @test "dashboard.sh --help should show usage" { run ./dashboard.sh --help echo "$output" | grep -q "Usage: dashboard.sh \[options\] \[module\]" - echo "$output" | grep -q -- "-r, --reporter " + echo "$output" | grep -q -- "-o, --overview " echo "$output" | grep -q "Available modules:" - echo "$output" | grep -q "Available reporters:" + echo "$output" | grep -q "Available overviews:" } # --- Integration Tests for Centralized Output Formatting ---