Merge pull request #20 from attogram/fix/trending-report-and-verbose-mode

attogram · web-flow · commit 08261dc6340d · 2025-09-20T23:23:19.000+02:00
Fix trending report order and add verbose mode
diff --git 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> [reporter_options]"
+    echo "   or: $(basename "$0") -o <overview> [overview_options]"
     echo
     echo "Options:"
     echo "  -f, --format <format>    Set the output format for module runs."
     echo "                           Supported formats: ${VALID_FORMATS[*]}"
-    echo "  -r, --reporter <name>    Run a specific reporter."
+    echo "  -o, --overview <name>    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-overviews.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_name> [reporter_options]
+./dashboard.sh -o <overview_name> [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
@@ -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_name> [reporter_options]
+./dashboard.sh -o <overview_name> [overview_options]
 ```
 
 ### Options
 
 - `-f, --format <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 <name>`: Run a specific reporter from the `reporters/` directory. Any subsequent arguments will be passed to the reporter script.
+- `-o, --overview <name>`: 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
@@ -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
@@ -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/overviews/top-stars.sh b/overviews/top-stars.sh
diff --git a/overviews/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
diff --git 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
@@ -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 <name>"
+  echo "$output" | grep -q -- "-o, --overview <name>"
   echo "$output" | grep -q "Available modules:"
-  echo "$output" | grep -q "Available reporters:"
+  echo "$output" | grep -q "Available overviews:"
 }
 
 # --- Integration Tests for Centralized Output Formatting ---

Original file line number	Diff line number	Diff line change
`@@ -106,5 +106,5 @@ END {`
`106`	`106`	`(`
`107`	`107`	`echo -e "Change\tLast\tFirst\tmodule\tchannels\tnamespace"`
`108`	`108`	`echo -e "------\t----\t-----\t------\t--------\t---------"`
`109`		`- sort -k1,1nr`
	`109`	`+ sort -k1,1gr`
`110`	`110`	`)`
Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,7 @@ teardown() {`
`55`	`55`	`CRYPTO_WALLET_BTC="test_btc_address" \`
`56`	`56`	`bash modules/crypto.sh`
`57`	`57`	`[ "$status" -eq 0 ]`
	`58`	`+ echo "Blockcypher Output: $output"`
`58`	`59`	`[[ "$output" =~ .*${tab}crypto${tab}balance${tab}crypto.BTC.test_btc_address.BTC${tab}0.12345678$ ]]`
`59`	`60`	`}`
`60`	`61`
`@@ -64,6 +65,7 @@ teardown() {`
`64`	`65`	`CRYPTO_WALLET_ETH="test_eth_address" \`
`65`	`66`	`bash modules/crypto.sh`
`66`	`67`	`[ "$status" -eq 0 ]`
	`68`	`+ echo "Covalent Output: $output"`
`67`	`69`	`[[ "$output" =~ .*${tab}crypto${tab}balance${tab}crypto.ETH.test_eth_address.ETH${tab}1.234$ ]]`
`68`	`70`	`}`
`69`	`71`