feat(cli): CLI UX improvements

[GiggleLiu]

Summary

Comprehensive CLI UX improvements based on systematic analysis of pitfalls, missing features, and HCI violations (plan: docs/plans/2026-02-19-cli-ux-improvements.md).

Pitfall Fixes

• P1: create without -o now prints JSON to stdout (data no longer lost)
• P2: reduce shows human-readable summary by default, --json flag for raw JSON
• P4: export-graph uses global -o flag instead of positional arg (consistency)
• P5: Solve hint only shows when stderr is a TTY (not noisy for scripts)
• P6: ILP auto-reduction now visible in human output (Solver: ilp (via ILP))
• P7: Accept - for stdin in solve, evaluate, reduce (enables piping)

New Features

• F1: pred inspect command for problem/bundle introspection (type, size, solvers, reductions)
• F2: Global -q/--quiet flag to suppress informational stderr messages
• F4: pred create --random for random graph instance generation (Erdos-Renyi model)

HCI Improvements

• H1: Fuzzy matching for unknown problem names with "Did you mean ...?" suggestions

Additional

• cli-demo Makefile target for end-to-end CLI testing
• 86 CLI integration tests (up from ~45)

Test plan

• make test — all tests pass
• make clippy — no warnings
• make fmt-check — formatting clean
• CLI integration tests cover all new features (86 tests)
• Pipe tests: create | solve -, create | evaluate -, create | reduce -, create | inspect -
• Quiet mode tested: hint suppression, wrote suppression, stdout preserved
• Random generation tested: determinism, edge cases, unsupported types

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.75785% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.36%. Comparing base (6e36c4a) to head (6767d56).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rules/graph.rs	95.04%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #84      +/-   ##
==========================================
+ Coverage   96.33%   96.36%   +0.03%     
==========================================
  Files         197      197              
  Lines       27037    27210     +173     
==========================================
+ Hits        26047    26222     +175     
+ Misses        990      988       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GiggleLiu]

please reply give me some using examples of cli to reflect this change. Must be reproducible by user, and please update all documents.

[GiggleLiu]

if completion requires manul setup, then it seems not useful.

[GiggleLiu]

Removed the completions command and the clap_complete dependency since it requires manual shell setup.

[GiggleLiu]

needs to check the visual outout. please run the command line and comment under pr.

[GiggleLiu]

Posted CLI output examples as a PR comment above.

[GiggleLiu]

a lot of places used table formating, consider wrapping it into a function.

[GiggleLiu]

Extracted table formatting into a reusable format_table() helper in output.rs. The list command now uses it.

[GiggleLiu]

Check if we have an existing function for this type of query?

[GiggleLiu]

Yes — there's an existing private lookup_node() method (line 402) with identical logic. Refactored find_node_index() to delegate to self.lookup_node(name, variant).

[Copilot]

Pull request overview

This pull request implements three CLI v2 features for the pred tool: shell completions, colored terminal output, and k-neighbor graph exploration.

Changes:

• Added BFS-based k-neighbor exploration to ReductionGraph in the core library with k_neighbors() method and supporting types (NeighborInfo, TraversalDirection)
• Added colored terminal output support using owo-colors with TTY detection and NO_COLOR environment variable respect
• Added shell completions command using clap_complete for bash, zsh, and fish
• Enhanced pred list with aligned table layout showing variant and reduction counts
• Extended pred show with --hops and --direction flags for neighbor exploration with tree rendering
• Added comprehensive test coverage: 5 new library unit tests for k-neighbors BFS, 8 new CLI integration tests (3 completions + 5 k-neighbor)

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/rules/graph.rs	Added k_neighbors() BFS method and helper methods (find_node_index, neighbor_indices, node_name) for graph traversal
src/rules/mod.rs	Exported new NeighborInfo and TraversalDirection types
src/unit_tests/reduction_graph.rs	Added 5 unit tests for k-neighbor BFS covering different directions and edge cases
problemreductions-cli/Cargo.toml	Added clap_complete, owo-colors, and petgraph dependencies
problemreductions-cli/src/output.rs	Added color helper functions with TTY and NO_COLOR support
problemreductions-cli/src/cli.rs	Added Completions command and --hops/--direction flags to Show command
problemreductions-cli/src/main.rs	Added dispatch for completions command and updated show command signature
problemreductions-cli/src/commands/graph.rs	Implemented aligned column layout for list, colors for show and path, and tree rendering for k-neighbor exploration
problemreductions-cli/tests/cli_tests.rs	Added 8 integration tests for completions and k-neighbor features
Various test files	Formatting improvements (line breaks) for better readability
Examples	Minor import reordering for consistency
docs/plans/*.md	Added detailed design and implementation plan documents

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The function fmt_arrow_out() is defined but never used in the codebase. This is dead code that should be removed. The code uses fmt_outgoing() with a Unicode arrow character directly instead of calling this function.

Suggested change

	/// Format an outgoing arrow (green when color is enabled).
	pub fn fmt_arrow_out() -> &'static str {
	// We return static str, so we use ANSI directly for the arrow
	"\u{2192}"
	}

[GiggleLiu]

Removed fmt_arrow_out() dead code.

[GiggleLiu]

CLI Output Examples

pred list

Registered problems: 17 types, 50 reductions, 25 variant nodes

  Problem                Aliases     Variants  Reduces to
  ─────────────────────  ──────────  ────────  ──────────
  CircuitSAT                                1           2
  Factoring                                 1           2
  ILP                                       1           1
  KColoring                                 2           3
  KSatisfiability        3SAT, KSAT         3           7
  MaxCut                                    1           1
  MaximumClique                             1           1
  MaximumIndependentSet  MIS                4          10
  MaximumMatching                           1           2
  MaximumSetPacking                         2           4
  MinimumDominatingSet                      1           1
  MinimumSetCovering                        1           1
  MinimumVertexCover     MVC                1           4
  QUBO                                      1           2
  Satisfiability         SAT                1           5
  SpinGlass                                 2           3
  TravelingSalesman      TSP                1           1

Use `pred show <problem>` to see variants, reductions, and fields.

pred show MIS

MaximumIndependentSet
  Find maximum weight independent set in a graph

Variants (4):
  {graph=SimpleGraph, weight=i32}
  {graph=UnitDiskGraph, weight=i32}
  {graph=TriangularSubgraph, weight=i32}
  {graph=KingsSubgraph, weight=i32}

Fields (2):
  graph (G) -- The underlying graph G=(V,E)
  weights (Vec<W>) -- Vertex weights w: V -> R

Size fields (2):
  num_vertices
  num_edges

Reduces to (10):
  MaximumIndependentSet {graph=UnitDiskGraph, weight=i32} → MaximumIndependentSet {graph=SimpleGraph, weight=i32}
  MaximumIndependentSet {graph=TriangularSubgraph, weight=i32} → MaximumIndependentSet {graph=UnitDiskGraph, weight=i32}
  MaximumIndependentSet {graph=KingsSubgraph, weight=i32} → MaximumIndependentSet {graph=UnitDiskGraph, weight=i32}
  MaximumIndependentSet {graph=UnitDiskGraph, weight=i32} → MaximumIndependentSet {graph=KingsSubgraph, weight=i32}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} → MaximumIndependentSet {graph=KingsSubgraph, weight=i32}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} → MaximumIndependentSet {graph=TriangularSubgraph, weight=i32}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} → ILP (default)
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} → MinimumVertexCover {graph=SimpleGraph, weight=i32}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} → QUBO {weight=f64}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} → MaximumSetPacking {weight=i32}

Reduces from (9):
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} ← Satisfiability (default)
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} ← MaximumIndependentSet {graph=UnitDiskGraph, weight=i32}
  MaximumIndependentSet {graph=UnitDiskGraph, weight=i32} ← MaximumIndependentSet {graph=TriangularSubgraph, weight=i32}
  MaximumIndependentSet {graph=UnitDiskGraph, weight=i32} ← MaximumIndependentSet {graph=KingsSubgraph, weight=i32}
  MaximumIndependentSet {graph=KingsSubgraph, weight=i32} ← MaximumIndependentSet {graph=UnitDiskGraph, weight=i32}
  MaximumIndependentSet {graph=KingsSubgraph, weight=i32} ← MaximumIndependentSet {graph=SimpleGraph, weight=i32}
  MaximumIndependentSet {graph=TriangularSubgraph, weight=i32} ← MaximumIndependentSet {graph=SimpleGraph, weight=i32}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} ← MinimumVertexCover {graph=SimpleGraph, weight=i32}
  MaximumIndependentSet {graph=SimpleGraph, weight=i32} ← MaximumSetPacking {weight=i32}

pred show MIS --hops 2

MaximumIndependentSet — 2-hop neighbors (outgoing)

MaximumIndependentSet
├── ILP
├── MaximumIndependentSet
│   └── MaximumIndependentSet
├── MaximumIndependentSet
├── MaximumSetPacking
│   └── MaximumSetPacking
├── MinimumVertexCover
│   └── MinimumSetCovering
└── QUBO
    └── SpinGlass

7 reachable problems in 2 hops

pred path MIS QUBO

Path (1 steps): MaximumIndependentSet {graph: "SimpleGraph", weight: "i32"} → QUBO {weight: "f64"}

  Step 1: MaximumIndependentSet {graph: "SimpleGraph", weight: "i32"} → QUBO {weight: "f64"}
    num_vars = num_vertices

pred path Factoring SpinGlass

Path (2 steps): Factoring → CircuitSAT → SpinGlass {graph: "SimpleGraph", weight: "i32"}

  Step 1: Factoring → CircuitSAT
    num_variables = num_bits_first * num_bits_second
    num_assignments = num_bits_first * num_bits_second

  Step 2: CircuitSAT → SpinGlass {graph: "SimpleGraph", weight: "i32"}
    num_spins = num_assignments
    num_interactions = num_assignments

pred create + pred solve

$ pred create MIS --edges 0-1,1-2,2-3 -o problem.json
Wrote problem.json

$ pred solve problem.json
Problem: MaximumIndependentSet
Solver: ilp
Solution: [1, 0, 0, 1]
Evaluation: Valid(2)

Hint: use -o to save full solution details as JSON.

pred reduce + pred solve (bundle)

$ pred reduce problem.json --to QUBO -o reduced.json
Reduced MaximumIndependentSet to QUBO (1 steps)
Wrote reduced.json

$ pred solve reduced.json --solver brute-force
Problem: MaximumIndependentSet
Solver: brute-force (via QUBO)
Solution: [0, 1, 0, 1]
Evaluation: Valid(2)

Hint: use -o to save full solution details (including intermediate results) as JSON.

pred evaluate

$ pred evaluate problem.json --config 1,0,1,0
Valid(2)

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

find_node_index/neighbor_indices/node_name/node_variant expose petgraph types (NodeIndex, petgraph::Direction) in the public problemreductions API. This couples downstream users to the exact petgraph version and makes future refactors harder. Consider keeping these pub(crate) and adding a higher-level API for tree building (e.g., returning neighbors with parent links) so the CLI doesn’t need to depend on graph internals.

[GiggleLiu]

Latest changes (902d31c)

Addresses review feedback:

1. Unified name+variant formatting

Added fmt_node(name, variant) as a single function for displaying problem names with their variants. Ensures consistent formatting everywhere: bold name + plain {variant}.

Fixed: pred path header was showing names as plain text instead of bold.

2. Move tree-building into core library (Copilot review item)

• Added ReductionGraph::k_neighbor_tree() → returns Vec<NeighborTree>
• Removed find_node_index(), neighbor_indices(), node_name(), node_variant() which exposed petgraph::NodeIndex in the public API
• Removed petgraph dependency from CLI crate — CLI no longer depends on graph internals

3. Removed dimming on aliases

Aliases in pred list table are now plain text (not dimmed).

All 93 CLI tests + 1506 lib tests pass, clippy clean.