feat(devtools): asap_planner text output is terse by default; --verbose prints the details (#1261)

README.md

@@ -6,7 +6,7 @@ ASAPPlanner turns SQL, PromQL, and MetricsQL query workloads into legal candidat
 
 - New to the repository? Read the [planner pipeline](docs/design_docs/concepts/planner-pipeline.md), then the [glossary](docs/design_docs/concepts/glossary.md).
 - Want to run a query? Follow [Run and inspect a query](docs/user_guide_docs/run-a-query.md).
-- Want to see how a workload is planned, stage by stage? Use the [Stage Viewer](docs/user_guide_docs/stage-viewer.md).
+- Want to see how a workload is planned, stage by stage? Use the [Plan Viewer](docs/user_guide_docs/plan-viewer.md).
 - Embedding Planner? Use the [library API guide](docs/develop_docs/library-api.md).
 - Extending Planner? Read the [planning stages design](docs/design_docs/proposals/planner-layering.md), then the [ASAP-aware mapping architecture](docs/develop_docs/asap-aware-mapping-architecture.md), which maps each stage to its code, then [extend ASAP-aware mapping](docs/develop_docs/extend-asap-aware-mapping.md).
 - Evaluating a design? Browse the [design documentation](docs/design_docs/README.md), [developer documentation](docs/develop_docs/README.md), and [user guides](docs/user_guide_docs/README.md).

crates/devtools/src/bin/asap_planner.rs

@@ -8,11 +8,10 @@
 // `--run-until` (`stage0`, `stage1_pass1`, `stage1_pass2`, `stage2` or
 // `stage3`) and writes each stage's output, as text (`--format text`, the default;
 // `asap_devtools::planning_stages_text`) or as an `asap-stage-pipeline/v2`
-// document for the Stage Viewer (`--format json`), to `--out` or standard
-// output. The text folds each memo group's candidates that differ only in
-// θ into one line (their indices, each θ parameter's values, how many Pass
-// 2 pruned by cause), printing in full only those Pass 2 kept, and counts
-// the pruned lists per cause; `--printing-full-candidates` prints every candidate, edge and
+// document for the Plan Viewer (`--format json`), to `--out` or standard
+// output. The text is terse by default (a legend per stage, folded θ
+// variants, producer ids per input, pruned counts per cause); `--verbose`
+// prints every candidate, edge with its reason, group's properties and
 // pruned candidate.
 //
 // The stages run as `run_planning` runs them
@@ -136,7 +135,7 @@ use asap_types::workload::{
 use serde_json::{json, Value};
 
 const USAGE: &str = "usage: asap_planner (--workload <file>)... \
---run-until stage0|stage1_pass1|stage1_pass2|stage2|stage3 [--format text|json] [--printing-full-candidates] [--out <file>] \
+--run-until stage0|stage1_pass1|stage1_pass2|stage2|stage3 [--format text|json] [--verbose] [--out <file>] \
 [--sql-catalog-table <json>]... [--cost-inputs <file>] [--deployment-capabilities <file>] \
 [--ignore-accuracy-guarantees]";
 
@@ -182,7 +181,7 @@ fn run(args: Vec<String>) -> Result<(), Failure> {
     let mut cost_inputs = CostInputs::default();
     let mut deployment_capabilities = DeploymentCapabilities::default();
     let mut ignore_accuracy_guarantees = false;
-    let mut printing_full_candidates = false;
+    let mut verbose = false;
     let mut args = args.into_iter();
     while let Some(flag) = args.next() {
         let mut value = || {
@@ -206,7 +205,7 @@ fn run(args: Vec<String>) -> Result<(), Failure> {
             "--cost-inputs" => cost_inputs = read_json(&flag, &value()?)?,
             "--deployment-capabilities" => deployment_capabilities = read_json(&flag, &value()?)?,
             "--ignore-accuracy-guarantees" => ignore_accuracy_guarantees = true,
-            "--printing-full-candidates" => printing_full_candidates = true,
+            "--verbose" => verbose = true,
             other => return Err(Failure::Usage(format!("unknown argument {other}"))),
         }
     }
@@ -288,9 +287,7 @@ fn run(args: Vec<String>) -> Result<(), Failure> {
         serde_json::to_string_pretty(&document).map_err(|e| e.to_string())? + "\n"
     } else {
         let mut text = match result {
-            Ok(run) => {
-                planning_stages_text(&run, evidence, plan_cost.as_ref(), printing_full_candidates)
-            }
+            Ok(run) => planning_stages_text(&run, evidence, plan_cost.as_ref(), verbose),
             Err(PlanningStagesError::Pass1(error)) => format!("error: Pass 1: {error}\n"),
             Err(error) => return Err(error.to_string().into()),
         };