feat: explicit variant declarations with complexity metadata

[GiggleLiu]

Summary

• DeclaredVariant trait — marker trait for compile-time enforcement that all reduction source/target types are explicitly declared
• VariantEntry inventory — new struct registered via declare_variants! macro, carrying per-variant complexity metadata (e.g., "2^num_vertices")
• declare_variants! macro — used in all 18 model files to declare concrete type instantiations with complexity
• #[reduction] proc macro — now checks DeclaredVariant at compile time, so undeclared variants cause build errors
• ReductionGraph — two-phase construction: nodes from VariantEntry first, then edges from ReductionEntry
• JSON export — nodes now include a complexity field
• CLI pred show — displays complexity per variant in both text and JSON output
• Deterministic variant ordering — variants_for() sorts variants so the default (SimpleGraph/i32) always comes first

Test plan

• make check passes (fmt + clippy + all tests including --include-ignored)
• All 1507 unit tests + 106 CLI tests + 43 doc tests pass
• Compile-time enforcement verified (commenting out a variant causes build error)
• pred show MIS displays complexity for all 4 variants
• JSON output includes complexity per variant
• CI pipeline passes

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.97315% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.89%. Comparing base (a7b271a) to head (16ec316).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rules/maximumindependentset_casts.rs	33.33%	2 Missing ⚠️
src/rules/unitdiskmapping/traits.rs	0.00%	2 Missing ⚠️
src/rules/graph.rs	97.77%	1 Missing ⚠️
src/rules/unitdiskmapping/ksg/gadgets.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #102      +/-   ##
==========================================
- Coverage   96.90%   96.89%   -0.01%     
==========================================
  Files         196      198       +2     
  Lines       26811    26904      +93     
==========================================
+ Hits        25980    26068      +88     
- Misses        831      836       +5     

☔ 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.

[Copilot]

Pull request overview

This pull request introduces explicit variant declarations with complexity metadata for all problem types. It implements a compile-time enforcement system where variants must be explicitly declared using a new declare_variants! macro, and the #[reduction] proc macro verifies that all reduction source/target types are declared.

Changes:

• Adds infrastructure for explicit variant registration with DeclaredVariant trait, VariantEntry inventory, and declare_variants! macro
• Updates all 18 model files to declare their concrete variants with time complexity expressions
• Modifies ReductionGraph to use two-phase construction: nodes from VariantEntry, edges from ReductionEntry
• Enhances CLI and MCP outputs to display per-variant complexity and reduction overhead information

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/traits.rs	Adds DeclaredVariant marker trait for compile-time checking
src/registry/variant.rs	New module with VariantEntry struct and inventory collection
src/registry/mod.rs	Exports VariantEntry from registry module
src/variant.rs	Implements declare_variants! macro for variant registration
src/lib.rs	Re-exports inventory crate for macro usage
problemreductions-macros/src/lib.rs	Adds compile-time DeclaredVariant assertions to #[reduction] macro
src/rules/graph.rs	Two-phase graph construction, adds complexity field to nodes, variant ordering
src/unit_tests/rules/graph.rs	Tests for VariantEntry inventory and complexity retrieval
src/models/graph/*.rs	Declares variants with complexity for 9 graph problems
src/models/optimization/*.rs	Declares variants with complexity for QUBO, SpinGlass, ILP
src/models/satisfiability/*.rs	Declares variants with complexity for SAT and KSAT
src/models/set/*.rs	Declares variants with complexity for set covering and packing
src/models/specialized/*.rs	Declares variants with complexity for CircuitSAT and Factoring
problemreductions-cli/src/commands/graph.rs	Displays complexity and overhead in show command
problemreductions-cli/src/commands/create.rs	Supports geometry graph variants with positions parameter
problemreductions-cli/src/mcp/tools.rs	MCP support for geometry variants and complexity display
problemreductions-cli/src/cli.rs	Updated help text for geometry variants
problemreductions-cli/tests/cli_tests.rs	Tests for geometry graph creation via CLI
.gitignore	Adds wildcard pattern for JSON files
docs/plans/*.md	Design and implementation plan documents

Comments suppressed due to low confidence (1)

problemreductions-cli/src/mcp/tools.rs:205

• The MCP show_problem_inner output does not include the overhead information in the reduces_to and reduces_from edges (lines 194-205), while the CLI version in commands/graph.rs does include it (via the edge_to_json closure). This creates an inconsistency where the same information is presented differently depending on whether it's accessed via CLI or MCP. Consider using the same edge serialization logic in both places for consistency.

            "reduces_to": outgoing.iter().map(|e| {
                serde_json::json!({
                    "source": {"name": e.source_name, "variant": e.source_variant},
                    "target": {"name": e.target_name, "variant": e.target_variant},
                })
            }).collect::<Vec<_>>(),
            "reduces_from": incoming.iter().map(|e| {
                serde_json::json!({
                    "source": {"name": e.source_name, "variant": e.source_variant},
                    "target": {"name": e.target_name, "variant": e.target_variant},
                })
            }).collect::<Vec<_>>(),

---

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

[Copilot]

There is significant code duplication between problemreductions-cli/src/commands/create.rs and problemreductions-cli/src/mcp/tools.rs. Both files contain nearly identical implementations of: lcg_step, lcg_init, create_random_int_positions, create_random_float_positions, parse_positions, and ser_vertex_weight_problem_generic. Consider extracting these shared functions into a common module (e.g., problemreductions-cli/src/utils/random.rs and problemreductions-cli/src/utils/geometry.rs) to reduce duplication and ensure consistency.

[Copilot]

The LCG step function has a normalization issue. The right shift by 33 bits produces a 31-bit value, but dividing by (1u64 << 31) gives values in the range [0, 2), not [0, 1). This should be (1u64 << 31) as f64 to ensure the divisor matches the range of the numerator, producing values correctly in [0, 1).

[Copilot]

The variant_to_full_slash function uses BTreeMap::values() which returns values in key-sorted order. While BTreeMap guarantees this ordering is deterministic, it means the slash notation depends on the alphabetical order of variant parameter names (e.g., "graph", "k", "weight"). This could produce unintuitive results - for example, a variant with keys {graph: "SimpleGraph", k: "K3", weight: "i32"} would become "/SimpleGraph/K3/i32" (alphabetical: g, k, w). Consider documenting this ordering behavior or using a more explicit parameter ordering scheme.

[Copilot]

The doc comment example uses text` instead of ignore or ````rust,ignore. While this is functionally equivalent, using ````ignore` is more conventional for Rust documentation examples that should not be tested. This is a minor style consistency issue.

[Copilot]

The design document at line 59 shows UnitDiskGraph, f64 as an example variant, but in the actual implementation in maximum_independent_set.rs line 166, only UnitDiskGraph, i32 is declared. This is a minor inconsistency between the design doc and implementation. While this doesn't affect correctness, it would be clearer if the design document matched the actual implementation or explained why the example differs.

Suggested change

	MaximumIndependentSet<UnitDiskGraph, f64> => "2^num_vertices",
	MaximumIndependentSet<UnitDiskGraph, i32> => "2^num_vertices",

[Copilot]

The LCG step function has a normalization issue. The right shift by 33 bits produces a 31-bit value, but dividing by (1u64 << 31) gives values in the range [0, 2), not [0, 1). This should be (1u64 << 31) as f64 to ensure the divisor matches the range of the numerator, producing values correctly in [0, 1). The same issue exists in the inline implementation at line 590 of create_random_graph.

[Copilot]

The deterministic sorting logic for variants has a potential issue. The default_rank function counts non-default values to rank variants, but this approach may not be stable across different variant maps with the same number of non-default values. Consider two variants: {graph: "KingsSubgraph", weight: "i32"} and {graph: "SimpleGraph", weight: "f64"} — both have one non-default value and would be ranked equally, falling back to lexicographic comparison. This is probably fine, but the comment claims "variants[0] is the base variant" which may not always be true if no variant is fully default. Consider adding a check that the first variant actually has rank 0 (all default values), or clarify the documentation.

[Copilot]

Pull request overview

Copilot reviewed 40 out of 41 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]

ReductionEdgeInfo is publicly exported (via rules/mod.rs) and has public fields. Adding the new overhead field is a breaking change for downstream crates that construct the struct via literals or pattern-match it. Consider either (a) treating this as a semver-major change, or (b) avoiding public fields (provide accessors / constructor) and/or switching the type to #[non_exhaustive] going forward so future additions don't keep breaking downstream code.