From 2d5bd26c362dcf8f3107b4159385dcc8fc27bca5 Mon Sep 17 00:00:00 2001
From: yukkop <hectic.yukkop@gmail.com>
Date: Wed, 10 Jun 2026 12:26:16 +0000
Subject: [PATCH] docs: `migrator`: ~ logs & comments

---
 package/migrator/migrator.sh                  | 19 ++++----
 .../migrator/test/postgresql/arguments.sh     | 46 ++++++++++++++++++-
 2 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/package/migrator/migrator.sh b/package/migrator/migrator.sh
index f1ed5856..5f1df375 100644
--- a/package/migrator/migrator.sh
+++ b/package/migrator/migrator.sh
@@ -154,11 +154,11 @@ init() {
         shift 2
       ;;
       --*|-*)
-        printf 'init argument %s does not exists' "$1"
+        log error "init argument ${WHITE}$1${NC} does not exists"
         exit 9
       ;;
       *)
-        printf 'init command %s does not exists' "$1"
+        log error "init subcommand ${WHITE}$1${NC} does not exists"
         exit 9
       ;;
     esac
@@ -633,7 +633,8 @@ migrate() {
   db_mig_count=$(printf '%s' "$db_migrations" | wc -l)
   log debug "mig count: $db_mig_count"
 
-  # Log migration lists for debugging
+  # These counts are useful even at normal verbosity because they summarize the
+  # migration state before any validation or apply/revert work begins.
   fs_mig_count=$(printf '%s' "$fs_migrations" | wc -l)
   log info "Filesystem migrations found: ${WHITE}$fs_mig_count"
   log info "Database migrations applied: ${WHITE}$db_mig_count"
@@ -699,15 +700,15 @@ migrate() {
   target_migration="$("migrate_$MIGRATE_SUBCOMMAND" "$@")"
 
   if [ -z "$db_migrations" ]; then
-    log info "it'll firs migration"
+    log info "starting from clean migration state"
     current_idx=0
   else
     current_migration=$(printf '%s\n' "$db_migrations" | tail -n1)
     current_idx=$(index_of "$fs_migrations" "$current_migration")
   fi
 
-  log debug "[$WHITE$fs_migrations$NC]"
-  log debug "$target_migration"
+  log debug "filesystem migrations: ${WHITE}$fs_migrations${NC}"
+  log debug "requested target migration: ${WHITE}${target_migration:-<clean state>}${NC}"
 
   if [ -z "$target_migration" ]; then
     target_idx=0
@@ -715,7 +716,7 @@ migrate() {
     target_idx=$(index_of "$fs_migrations" "$target_migration")
   fi
 
-  log debug "indexes $WHITE$current_idx$NC $WHITE${target_idx}"
+  log debug "migration indexes: current=${WHITE}$current_idx${NC} target=${WHITE}$target_idx${NC}"
 
   if [ "$target_idx" -eq "$current_idx" ]; then
     if [ "$target_idx" -eq 0 ]; then
@@ -903,11 +904,11 @@ list() {
         shift
       ;;
       --*|-*)
-        log error "init argument $1 does not exists"
+        log error "list argument ${WHITE}$1${NC} does not exists"
         exit 9
       ;;
       *)
-        log error "init subcommand $1 does not exists"
+        log error "list subcommand ${WHITE}$1${NC} does not exists"
         exit 9
       ;;
     esac
diff --git a/test/package/migrator/test/postgresql/arguments.sh b/test/package/migrator/test/postgresql/arguments.sh
index b4d7e09d..826706c6 100644
--- a/test/package/migrator/test/postgresql/arguments.sh
+++ b/test/package/migrator/test/postgresql/arguments.sh
@@ -1,6 +1,6 @@
 log notice "test case: ${WHITE}error: ambiguous command"
 set +e
-migrator --inherits tablename --inherits 'table name' list migrate
+migrator --inherits tablename --inherits 'table name' list migrate >/tmp/migrator-arguments-1.out 2>&1
 error_code=$?
 set -e
 
@@ -12,9 +12,14 @@ elif [ "$error_code" != 2 ]; then
   exit 1
 fi
 
+if ! grep -q 'ambiguous subcommand' /tmp/migrator-arguments-1.out; then
+  log error "test failed: ${WHITE}missing ambiguous subcommand diagnostic"
+  exit 1
+fi
+
 log notice "test case: ${WHITE}error: ambiguous migrate command"
 set +e
-migrator --inherits tablename --inherits 'table name' migrate to up
+migrator --inherits tablename --inherits 'table name' migrate to up >/tmp/migrator-arguments-2.out 2>&1
 error_code=$?
 set -e
 
@@ -25,3 +30,40 @@ elif [ "$error_code" != 2 ]; then
   log error "test failed: ${WHITE}unexpected error code"
   exit 1
 fi
+
+if ! grep -q 'ambiguous migrate subcommand' /tmp/migrator-arguments-2.out; then
+  log error "test failed: ${WHITE}missing ambiguous migrate diagnostic"
+  exit 1
+fi
+
+log notice "test case: ${WHITE}error: init invalid argument is logged"
+set +e
+migrator init --wat >/tmp/migrator-arguments-3.out 2>&1
+error_code=$?
+set -e
+
+if [ "$error_code" != 9 ]; then
+  log error "test failed: ${WHITE}expected exit code 9 for invalid init argument, got $error_code"
+  exit 1
+fi
+
+if ! grep -q 'init argument .*--wat.* does not exists' /tmp/migrator-arguments-3.out; then
+  log error "test failed: ${WHITE}missing init invalid argument diagnostic"
+  exit 1
+fi
+
+log notice "test case: ${WHITE}error: list invalid argument is logged with correct command name"
+set +e
+migrator list --wat >/tmp/migrator-arguments-4.out 2>&1
+error_code=$?
+set -e
+
+if [ "$error_code" != 9 ]; then
+  log error "test failed: ${WHITE}expected exit code 9 for invalid list argument, got $error_code"
+  exit 1
+fi
+
+if ! grep -q 'list argument .*--wat.* does not exists' /tmp/migrator-arguments-4.out; then
+  log error "test failed: ${WHITE}missing list invalid argument diagnostic"
+  exit 1
+fi