Fix Bug

Guide for debugging and fixing bugs in Syncpack.

Scientific Debugging Workflow

1. Observe — Understand the symptom precisely
2. Hypothesise — Form a theory about the root cause
3. Experiment — Test the hypothesis with targeted changes
4. Validate — Confirm the fix with tests
5. Verify — Run full test suite

Step 1: Observe

Gather information before changing code:

# Run the failing test with output
cargo test test_name -- --nocapture

# Run with backtrace
RUST_BACKTRACE=1 cargo test test_name

# Test against fixture
cd fixtures/fluid-framework
cargo run -- lint

Questions to answer:

• What is the exact error message?
• What input triggers it?
• What is the expected vs actual behaviour?

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