feat: Introduce review commands for diff analysis and reporting

- Added `review_cmds.py` to handle various review commands including:
  - `review_diff_cmd`: Review standard diff results.
  - `review_stats_cmd`: Review column-level statistics for a diff.
  - `review_missing_cmd`: Review rows that exist only on one side.
  - `review_columns_cmd`: List available columns in the diff data.
  - `review_export_cmd`: Export diff results to an XLSX report.
  - `review_meta_cmd`: Emit JSON metadata for AI/LLM analysis.

- Created `run.py` to manage different run commands for comparing tables, files, and SQL queries, including:
  - `run_file_cmd`: Compare two CSV/XLSX files.
  - `run_query_cmd`: Compare two SQL query results.
  - `run_unified_cmd`: A concise command to run comparisons based on mode.
  - `run_dataset_cmd`: Compare datasets defined in YAML configuration.

- Implemented `run_auto.py` for automatic detection of input types (tables, files, SQL) and comparison execution.

- Added `run_stats.py` for comparing table statistics without row-by-row comparison.

- Developed `run_table.py` for detailed comparison of two tables or CSV/XLSX files.

- Updated tests to reflect changes in command structure from `inspect` to `review`, ensuring all functionalities are covered.

- Refactored CLI commands to improve usability and maintainability.

Author: luisggoncalves

README.md

@@ -5,7 +5,7 @@ When you modify logic, filters, or inputs, it lets you compare the previous and
 
 You can compare datasets in two complementary ways:
 
-1) Row-by-row comparison (with an ID): detect missing rows on either side, identify the columns with the most changes, and inspect before/after values for any record.
+1) Row-by-row comparison (with an ID): detect missing rows on either side, identify the columns with the most changes, and review before/after values for any record.
 2) Statistical comparison: compare column-level statistics such as null counts, distinct counts, and other aggregates to quickly understand overall impact.
 
 ---
@@ -49,56 +49,55 @@ Compare two tables on a key:
 
 ```bash
 export SQLCOMPARE_CONN_DEFAULT="postgresql://<user>:<pass>@<host>/<db>"
-sqlcompare run analytics.fact_sales analytics.fact_sales_new id
+sqlcompare run table analytics.fact_sales analytics.fact_sales_new id
 ```
 
 That command prints a **diff_id**. Use it for follow-up analysis:
 
 ```bash
-sqlcompare inspect <diff_id> --stats
-sqlcompare inspect <diff_id> --column revenue --limit 100
-sqlcompare inspect <diff_id> --missing-current
-sqlcompare diff-queries <diff_id>
-sqlcompare inspect <diff_id> --save summary
-sqlcompare inspect <diff_id> --save complete --file-path ./reports/full_diff.xlsx
+sqlcompare review stats <diff_id>
+sqlcompare review diff <diff_id> --column revenue --limit 100
+sqlcompare review missing <diff_id> --side current
+sqlcompare review meta <diff_id>
+sqlcompare review export <diff_id> --mode summary
+sqlcompare review export <diff_id> --mode complete --output ./reports/full_diff.xlsx
 ```
 
-## Inspect report export (XLSX)
+## Review report export (XLSX)
 
-You can export inspect results as a multi-tab Excel report using `--save`.
+You can export review results as a multi-tab Excel report using `review export`.
 
 Modes:
 
-* `--save none` (default): no file output
-* `--save summary`: creates `Overview` + per-column tabs (top 200 rows each) + `SQL Reference`
-* `--save complete`: same tabs, but without the 200-row cap (limited only by XLSX limits)
+* `--mode summary` (default): creates `Overview` + per-column tabs (top 200 rows each) + `SQL Reference`
+* `--mode complete`: same tabs, but without the 200-row cap (limited only by XLSX limits)
 
 Examples:
 
 ```bash
 # Save summary report in current directory with generated timestamped filename
-sqlcompare inspect <diff_id> --save summary
+sqlcompare review export <diff_id> --mode summary
 
 # Save full report to a specific location
-sqlcompare inspect <diff_id> --save complete --file-path ./reports/full_diff.xlsx
+sqlcompare review export <diff_id> --mode complete --output ./reports/full_diff.xlsx
 
 # Save a single-column summary report
-sqlcompare inspect <diff_id> --column revenue --save summary --file-path ./reports/revenue_diff.xlsx
+sqlcompare review export <diff_id> --mode summary --column revenue --output ./reports/revenue_diff.xlsx
 ```
 
 Notes:
 
-* `--file-path` is optional; if omitted, SQLCompare generates a readable timestamped filename.
-* `--save summary|complete` is for the standard diff view and should not be combined with `--stats`, `--missing-current`, `--missing-previous`, or `--list-columns`.
+* `--output` is optional; if omitted, SQLCompare generates a readable timestamped filename.
+* `review export` is for the standard diff view and should not be combined with `review stats`, `review missing`, or `review columns`.
 
 ---
 
-## diff-queries (AI-friendly metadata)
+## review meta (AI-friendly metadata)
 
-Use `diff-queries` to get a JSON payload describing the queryable tables and ready-to-run SQL templates for a given `diff_id`. This is especially useful for AI agents that need structured context before running analysis queries.
+Use `review meta` to get a JSON payload describing the queryable tables and ready-to-run SQL templates for a given `diff_id`. This is especially useful for AI agents that need structured context before running analysis queries.
 
 ```bash
-sqlcompare diff-queries <diff_id>
+sqlcompare review meta <diff_id>
 ```
 
 Output (JSON):
@@ -137,7 +136,7 @@ SQLCompare does two things:
 Best for production validation and regression checks across supported connectors.
 
 ```bash
-sqlcompare run analytics.users analytics.users_new user_id,tenant_id
+sqlcompare run table analytics.users analytics.users_new user_id,tenant_id
 ```
 
 Why it’s useful:
@@ -154,17 +153,17 @@ Use this when tables aren’t materialized yet or you want a filtered slice.
 Inline SQL:
 
 ```bash
-sqlcompare run \
-  "SELECT * FROM analytics.orders WHERE order_date < '2024-01-01'" \
-  "SELECT * FROM analytics.orders WHERE order_date >= '2024-01-01'" \
-  order_id \
+sqlcompare run query \
+  --previous "SELECT * FROM analytics.orders WHERE order_date < '2024-01-01'" \
+  --current "SELECT * FROM analytics.orders WHERE order_date >= '2024-01-01'" \
+  --index order_id \
   -c snowflake_prod
 ```
 
 SQL files:
 
 ```bash
-sqlcompare run queries/previous.sql queries/current.sql order_id -c snowflake_prod
+sqlcompare run query --previous queries/previous.sql --current queries/current.sql --index order_id -c snowflake_prod
 ```
 
 Or create a dataset config:
@@ -184,7 +183,7 @@ new:
 Run the compare:
 
 ```bash
-sqlcompare dataset path/to/dataset.yaml
+sqlcompare run dataset path/to/dataset.yaml
 ```
 
 Why it’s useful:
@@ -216,7 +215,7 @@ new:
 Set a local default connector and run:
 
 ```bash
-sqlcompare run path/to/previous.csv path/to/current.xlsx id
+sqlcompare run file path/to/previous.csv path/to/current.xlsx id
 ```
 
 Why it’s useful:
@@ -232,7 +231,7 @@ Use this when your data lives in a local `.duckdb` file.
 
 ```bash
 export SQLCOMPARE_CONN_LOCAL="duckdb:////absolute/path/to/warehouse.duckdb"
-sqlcompare run raw.customers staged.customers id -c local
+sqlcompare run table raw.customers staged.customers id -c local
 ```
 
 Why it’s useful:

examples/row_compare.md

@@ -5,7 +5,7 @@ Compare rows using a dataset YAML with file inputs
 ## Command
 
 ```bash
-sqlcompare dataset tests/datasets/row_compare/dataset.yaml
+sqlcompare run dataset tests/datasets/row_compare/dataset.yaml
 ```
 
 ## Output
@@ -45,6 +45,6 @@ Rows only in previous dataset: 1
 | 1  |  name  | alpha  |  alfa   |
 | 1  | amount |   10   |   11    |
 +----+--------+--------+---------+
-🔎 To review the diff, run: sqlcompare inspect compare_sqlcompare_dataset_dataset_998aa249_previous_sqlcompare_dataset_dataset_998aa249_new_20260104_025829_b28946b5
-💡 Tips: --stats for per-column counts, --missing-current/--missing-previous for row-only, --column <name> to filter, --list-columns to inspect available fields.
+🔎 To review the diff, run: sqlcompare review compare_sqlcompare_dataset_dataset_998aa249_previous_sqlcompare_dataset_dataset_998aa249_new_20260104_025829_b28946b5
+💡 Tips: sqlcompare review stats <diff_id> for per-column counts, sqlcompare review missing <diff_id> --side current|previous for row-only, sqlcompare review diff <diff_id> --column <name> to filter, sqlcompare review columns <diff_id> to inspect available fields.
 ```

examples/stats_compare.md

@@ -5,7 +5,7 @@ Compare statistics between two CSV files
 ## Command
 
 ```bash
-sqlcompare stats tests/datasets/stats_compare/previous.csv tests/datasets/stats_compare/current.csv
+sqlcompare run stats tests/datasets/stats_compare/previous.csv tests/datasets/stats_compare/current.csv
 ```
 
 ## Output

skills/sqlcompare-connection-debug/SKILL.md

@@ -62,7 +62,7 @@ Use these to isolate authentication vs query issues.
 1. Simple query against the target connector.
 `sqlcompare query "SELECT 1" -c <name>`
 2. List available diffs to confirm local metadata access.
-`sqlcompare list-diffs`
+`sqlcompare history`
 
 ## Common Fixes
 1. Use `-c <name>` explicitly to avoid accidental default selection.

skills/sqlcompare-core-run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sqlcompare-core-run
-description: Run SQLCompare core comparisons across tables, SQL queries, and files to produce a diff_id. Use when the user wants to compare two datasets, choose index keys, set connectors, or run dataset configs via sqlcompare run/table/dataset/stats/query.
+description: Run SQLCompare core comparisons across tables, SQL queries, and files to produce a diff_id. Use when the user wants to compare two datasets, choose index keys, set connectors, or run dataset configs via sqlcompare run subcommands or sqlcompare query.
 ---
 
 # SQLCompare Core Run
@@ -17,23 +17,23 @@ Run the primary SQLCompare commands that create comparison artifacts and return
 Use these patterns to pick the right entry point.
 
 1. Compare two tables or views.
-`sqlcompare run analytics.fact_sales analytics.fact_sales_new id`
+`sqlcompare run table analytics.fact_sales analytics.fact_sales_new id`
 2. Compare two SQL queries (inline or .sql files).
-`sqlcompare run "SELECT ..." "SELECT ..." id -c snowflake_prod`
-`sqlcompare run queries/previous.sql queries/current.sql id -c snowflake_prod`
+`sqlcompare run query --previous "SELECT ..." --current "SELECT ..." --index id -c snowflake_prod`
+`sqlcompare run query --previous queries/previous.sql --current queries/current.sql --index id -c snowflake_prod`
 3. Compare local files (CSV/XLSX) with DuckDB.
-`sqlcompare run path/to/previous.csv path/to/current.xlsx id`
+`sqlcompare run file path/to/previous.csv path/to/current.xlsx id`
 4. Use a dataset config for repeatable runs.
-`sqlcompare dataset path/to/dataset.yaml`
+`sqlcompare run dataset path/to/dataset.yaml`
 5. Run a fast statistical comparison (no diff_id needed for row-level drilldown).
-`sqlcompare stats analytics.users analytics.users_new -c snowflake_prod`
+`sqlcompare run stats analytics.users analytics.users_new -c snowflake_prod`
 6. Run a quick sanity query against a connector.
 `sqlcompare query "SELECT COUNT(*) FROM analytics.users" -c snowflake_prod`
 
 ## Inputs And Keys
 1. Provide index columns that exist in both datasets.
 2. Use comma-separated keys for composite indexes.
-`sqlcompare run analytics.users analytics.users_new user_id,tenant_id`
+`sqlcompare run table analytics.users analytics.users_new user_id,tenant_id`
 3. Fully qualify or quote identifiers when required by your database.
 
 ## Connections And Defaults

skills/sqlcompare-output-analysis/SKILL.md

@@ -1,48 +1,48 @@
 ---
 name: sqlcompare-output-analysis
-description: Analyze SQLCompare outputs after a core run. Use when the user has a diff_id and needs to inspect stats, missing rows, column-level diffs, exports, or AI-friendly diff-queries.
+description: Analyze SQLCompare outputs after a core run. Use when the user has a diff_id and needs to review stats, missing rows, column-level diffs, exports, or AI-friendly meta output.
 ---
 
 # SQLCompare Output Analysis
 
 ## Overview
-Interpret and drill into a SQLCompare diff_id using inspect, list-diffs, and diff-queries. Produce summaries, targeted column reviews, and exportable reports.
+Interpret and drill into a SQLCompare diff_id using review, history, and review meta. Produce summaries, targeted column reviews, and exportable reports.
 
 ## Start From A diff_id
 1. If you already have a diff_id, proceed to inspection commands.
 2. If you do not, list recent diffs and pick the correct one.
-`sqlcompare list-diffs`
-`sqlcompare list-diffs users`
+`sqlcompare history`
+`sqlcompare history users`
 
 ## Core Inspection Commands
 1. Overall statistics summary.
-`sqlcompare inspect <diff_id> --stats`
-2. Inspect a specific column with row samples.
-`sqlcompare inspect <diff_id> --column revenue --limit 100`
+`sqlcompare review stats <diff_id>`
+2. Review a specific column with row samples.
+`sqlcompare review diff <diff_id> --column revenue --limit 100`
 3. Show rows missing on either side.
-`sqlcompare inspect <diff_id> --missing-current`
-`sqlcompare inspect <diff_id> --missing-previous`
+`sqlcompare review missing <diff_id> --side current`
+`sqlcompare review missing <diff_id> --side previous`
 4. List available columns.
-`sqlcompare inspect <diff_id> --list-columns`
+`sqlcompare review columns <diff_id>`
 
 ## Export Reports (XLSX)
 1. Summary report with capped row samples per column.
-`sqlcompare inspect <diff_id> --save summary`
+`sqlcompare review export <diff_id> --mode summary`
 2. Full report without per-column row caps.
-`sqlcompare inspect <diff_id> --save complete --file-path ./reports/full_diff.xlsx`
+`sqlcompare review export <diff_id> --mode complete --output ./reports/full_diff.xlsx`
 3. Single-column summary report.
-`sqlcompare inspect <diff_id> --column revenue --save summary --file-path ./reports/revenue_diff.xlsx`
+`sqlcompare review export <diff_id> --column revenue --mode summary --output ./reports/revenue_diff.xlsx`
 
 Notes:
-1. `--save summary|complete` is for the standard diff view.
-2. Do not combine `--save summary|complete` with `--stats`, `--missing-current`, `--missing-previous`, or `--list-columns`.
+1. `review export --mode summary|complete` is for the standard diff view.
+2. Do not combine `review export` with `review stats`, `review missing`, or `review columns`.
 
 ## AI-Friendly Diff Queries
-Use diff-queries to get structured metadata and SQL templates.
-`sqlcompare diff-queries <diff_id>`
+Use review meta to get structured metadata and SQL templates.
+`sqlcompare review meta <diff_id>`
 
 ## Interpretation Hints
 1. Start with `--stats` to see which columns change most.
 2. Use `--missing-current` and `--missing-previous` to find dropped or new rows.
-3. Use `--column` to inspect high-impact fields.
+3. Use `--column` to review high-impact fields.
 4. Export a summary report for sharing, then refine analysis with targeted column checks.

sqlcompare/cli.py

@@ -2,27 +2,34 @@
 
 import typer
 
-from sqlcompare.dataset import dataset_cmd
-from sqlcompare.diff_queries import diff_queries_cmd
-from sqlcompare.run_cmd import run_cmd
-from sqlcompare.inspect import inspect_cmd
-from sqlcompare.list_diffs import list_diffs_cmd
 from sqlcompare.query import query_cmd
-from sqlcompare.stats import stats_cmd
-from sqlcompare.table import table_cmd
-
-app = typer.Typer(help="Compare database tables and inspect diffs.")
-
-# Register all commands
-app.command("table")(table_cmd)
-app.command("run")(run_cmd)
-app.command("inspect")(inspect_cmd)
-app.command("diff-queries")(diff_queries_cmd)
-app.command("stats")(stats_cmd)
-app.command("list-diffs")(list_diffs_cmd)
+from sqlcompare.history import history_cmd
+from sqlcompare.review_cmds import (
+    review_columns_cmd,
+    review_diff_cmd,
+    review_export_cmd,
+    review_meta_cmd,
+    review_missing_cmd,
+    review_stats_cmd,
+)
+from sqlcompare.run import run_unified_cmd
+
+app = typer.Typer(help="Compare datasets and review diffs.")
+
+review_app = typer.Typer(help="Review diff results and export reports.")
+
+app.command("run")(run_unified_cmd)
+app.add_typer(review_app, name="review")
+app.command("history")(history_cmd)
+
 app.command("query")(query_cmd)
-app.command("dataset")(dataset_cmd)
 
+review_app.command("diff")(review_diff_cmd)
+review_app.command("stats")(review_stats_cmd)
+review_app.command("missing")(review_missing_cmd)
+review_app.command("columns")(review_columns_cmd)
+review_app.command("export")(review_export_cmd)
+review_app.command("meta")(review_meta_cmd)
 
 def main() -> None:
     app()

sqlcompare/compare/comparator.py

@@ -455,6 +455,6 @@ def compare(
         save_test_runs(runs)
 
         log.debug(f"\U0001f4c1 Analysis data saved with ID: {diff_id}")
-        log.debug(f"Use 'sqlcompare inspect {diff_id}' to review differences")
+        log.debug(f"Use 'sqlcompare review {diff_id}' to review differences")
 
         return diff_id

sqlcompare/list_diffs.py sqlcompare/history.pysqlcompare/list_diffs.py renamed to sqlcompare/history.py

@@ -10,7 +10,7 @@
 from sqlcompare.log import log
 
 
-def list_diffs(pattern: str | None, test: str | None) -> None:
+def list_history(pattern: str | None, test: str | None) -> None:
     """List available diff data files and runs."""
     tests_folder = get_tests_folder()
     search_pattern = f"{tests_folder}/*/diffs/*.pkl"
@@ -59,7 +59,7 @@ def list_diffs(pattern: str | None, test: str | None) -> None:
         )
 
 
-def list_diffs_cmd(
+def history_cmd(
     pattern: str | None = typer.Argument(None, help="Match diff IDs"),
     test: str | None = typer.Option(None, "--test", help="Filter by test name"),
 ) -> None:
@@ -69,15 +69,15 @@ def list_diffs_cmd(
 
     Examples:
         # List all diffs
-        sqlcompare list-diffs
+        sqlcompare history
 
         # Filter by pattern
-        sqlcompare list-diffs users
+        sqlcompare history users
 
         # Filter by test name
-        sqlcompare list-diffs --test migration_check
+        sqlcompare history --test migration_check
 
     Output:
         Displays: diff_id, test name, file size, creation date
     """
-    list_diffs(pattern, test)
+    list_history(pattern, test)