Fix Bug

Step 2: Hypothesise

Common root causes by symptom:

Step 3: Experiment

Add targeted debug output:

use log::debug;

debug!("Instance: {:#?}", instance);
debug!("State before: {:?}", instance.state.borrow());

Search for related code:

# Find where state is assigned
ast-grep -p 'InstanceState::fixable' src/visit_packages/

# Find similar patterns
ast-grep -p 'PATTERN' src/

Step 4: Validate

Write a failing test FIRST (TDD):

#[test]
fn reproduces_the_bug() {
    let ctx = TestBuilder::new()
        .with_packages(vec![/* minimal reproduction */])
        .build_and_visit_packages();

    // Assert expected behaviour (will fail initially)
}

Then fix the code until the test passes.

Step 5: Verify

just test        # All tests pass
cargo clippy     # No warnings

Where to Look

By component

By phase

Common Fixes

Instance state not being assigned

Check:

1. Is the instance's version group variant handled in visit_packages.rs?
2. Is there an early return skipping this instance?
3. Is another validation assigning a state first?

Test assertion failing

Check:

1. Is build_and_visit_packages() called (not just build())?
2. Is the location string format correct? ("{dep} in {location} of {package}")
3. Are there multiple instances of the same dependency?

Command not found

Verify registration in all three places:

1. src/cli.rs — Subcommand enum
2. src/main.rs — match arm
3. src/commands.rs — module declaration

Debugging Tips

• Isolate — Create minimal reproduction
• Binary search — Comment out code to narrow down
• Print early — Add debug output before suspected area
• Check order — Validation order matters (first match wins)
• Read tests — Existing tests show expected behaviour

Anti-Patterns

❌ Changing code without understanding the cause ❌ Removing code just to make tests pass ❌ Fixing symptoms instead of root cause ❌ Skipping the test-first step