fix-bug

name	fix-bug
description	Debug and fix bugs in Syncpack using scientific debugging methodology. Use when a test is failing, unexpected behaviour occurs, or investigating issues. Covers hypothesis-driven debugging and TDD-based fixes.

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:

Symptom	Likely Cause
State is Unknown	visit_packages not called or instance skipped
Wrong state assigned	Validation logic order, earlier check overriding
Instance not found	Package/dependency name mismatch, location format
Command not running	Missing registration in cli.rs, main.rs, or commands.rs
Panic/unwrap failure	Unexpected None or Err value

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

Issue with...	Check...
CLI parsing	src/cli.rs
Config loading	src/config.rs, src/rcfile.rs
Package reading	src/packages.rs, src/package_json.rs
State assignment	src/visit_packages/*.rs
Command output	src/commands/*.rs, src/commands/ui/
Version parsing	src/specifier/*.rs

By phase

Phase	What happens	Files
Create	Read config, packages, collect instances	context.rs, packages.rs
Inspect	Assign InstanceState	visit_packages.rs, visit_packages/*.rs
Run	Process instances, output/write	commands/*.rs

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