Skip to content

QUICK_START.md

Latest commit

 

History

History
256 lines (191 loc) · 6.08 KB

QUICK_START.md

File metadata and controls

256 lines (191 loc) · 6.08 KB

Quick Start - Test Failure Fix Implementation

Current Status

  • Tests Passing: 162/258 (62.8%)
  • Tests Failing: 90 (34.9%)
  • Goal: 250+/258 (96%+)

First-Time Setup

  • Run ./scripts/install-git-hooks.sh once after cloning to enable the local grammar-sync hook (scripts/check-grammar-sync.sh). This keeps the generated enums in src/languages/ current whenever you switch branches.

The ONE Critical Fix (Do This First!)

Time Required: 2 minutes

File: src/metrics/cognitive.rs

Line 243: Delete this line:

stats.boolean_seq.reset();

Full context (should look like this after edit):

#[inline]
fn increase_nesting(stats: &mut Stats, nesting: &mut usize, depth: usize, lambda: usize) {
    stats.nesting = *nesting + depth + lambda;
    increment(stats);
    *nesting += 1;
    // DELETED: stats.boolean_seq.reset();
}

Then run:

cargo test --lib metrics::cognitive:: 2>&1 | tail -5

Expected output:

test result: ok. 25 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

What This Fixes

  • ✅ 25 cognitive complexity tests
  • ✅ 4 cyclomatic complexity tests
  • ✅ Unlocks 61 more tests for Phase 2-4

Result: 162 → 191 tests passing (+14%)

Documentation to Read

For Understanding (5-10 minutes)

  1. ANALYSIS_SUMMARY.md - Executive summary
  2. PHASE1_IMPLEMENTATION_GUIDE.md - Detailed explanation

For Doing Remaining Work (Reference)

  1. TEST_FAILURE_CATEGORIZATION.md - Full categorization
  2. ACTIONABLE_FIXES_SUMMARY.md - Ranked by impact/effort

For Deep Dives (Optional)

  1. ROOT_CAUSE_SUMMARY.md - Original analysis
  2. BOOLEAN_OPERATOR_INVESTIGATION.md - Python limitation

4-Phase Implementation Plan

Phase 1: NOW (2 minutes)

  • Delete 1 line in cognitive.rs
  • Run: cargo test --lib metrics::cognitive::
  • Verify: 25 tests pass

Phase 2: NEXT (1-2 hours)

  • Fix LOC blank line detection
  • Review: src/metrics/loc.rs and src/comment_rm.rs
  • Expected: +12 tests

Phase 3: AFTER (3-4 hours)

  • Fix function parameter detection
  • Review: src/metrics/nargs.rs
  • Handle C macros specially
  • Expected: +31 tests

Phase 4: FINAL (1-2 hours)

  • Fix exit point detection
  • Edge case cleanup
  • Expected: +4 tests

Testing After Each Phase

# Phase 1: Cognitive
cargo test --lib metrics::cognitive:: 2>&1 | grep "test result"

# Phase 2: LOC
cargo test --lib metrics::loc:: 2>&1 | grep "test result"

# Phase 3: Parser fixes
cargo test --lib metrics::{nargs,nom,ops}:: 2>&1 | grep "test result"

# Full suite
cargo test --lib 2>&1 | grep "test result"

Expected Progress

Phase Time Result Rate
Start — 162 passing 62.8%
1 2 min 191 passing 74%
2 1-2 hrs 203 passing 79%
3 3-4 hrs 234 passing 91%
4 1-2 hrs 250+ passing 96%+

Failure Categories (For Reference)

Will Be Fixed by Phase 1 (29 tests)

Cognitive: 25 tests (Python, C, JavaScript boolean operators)
Cyclomatic: 4 tests (auto-fix from cognitive)

Will Be Fixed by Phase 2 (12 tests)

LOC: Blank line and comment detection (C/C++, Python)

Will Be Fixed by Phase 3 (31 tests)

NArgs: 14 tests (function parameters)
NOM: 4 tests (method counting)
Ops: 8 tests (operator counting)
Halstead: 5 tests (auto-fix from ops)

Will Be Fixed by Phase 4 (4 tests)

Exit: 4 tests (return statement detection)
Spaces: 1 test (scope operators)

May Remain Unfixable (8-10 tests)

Python boolean operators: Architectural limitation
C++ macros: Parser grammar limitation
Edge cases: Complex patterns

File References

File Changes
src/metrics/cognitive.rs Line 243: DELETE
src/metrics/loc.rs Phase 2 review
src/comment_rm.rs Phase 2 review
src/metrics/nargs.rs Phase 3 fix
src/metrics/nom.rs Phase 3 fix (depends on nargs)
src/metrics/ops.rs Phase 3 fix (depends on nargs)
src/c_langs_macros/ Phase 3: Special handling
src/metrics/exit.rs Phase 4 fix

Git Commands

# After Phase 1
git add src/metrics/cognitive.rs
git commit -m "fix: Remove aggressive boolean sequence reset in cognitive metrics

This fix allows boolean operators (and, or, &&, ||) to be counted
in cognitive complexity metrics, resolving 25 direct test failures
and 4 cascading cyclomatic complexity test failures."

# After each phase
git status  # Verify clean
cargo test --lib 2>&1 | tail -5  # Check progress

Success Checklist

Phase 1 Complete When:

  • Line 243 deleted from cognitive.rs
  • cargo test --lib metrics::cognitive:: shows all 25 pass
  • Full test suite shows 191 passing (up from 162)
  • Changes committed to git

All Phases Complete When:

  • 250+ tests passing
  • All 4 phases completed
  • Documentation updated
  • Changes committed and pushed

Common Issues

"Did I delete the right line?"

Open cognitive.rs, search for increase_nesting, verify the function has 4 lines only.

"Tests still failing after deletion"

Make sure you deleted the exact line. Use git diff to verify:

git diff src/metrics/cognitive.rs
# Should show exactly 1 line removed: stats.boolean_seq.reset();

"Compilation error"

Ensure indentation is correct. Use:

cargo fmt  # Auto-format
cargo build --lib  # Check compilation

Need More Detail?

Document For Time
ANALYSIS_SUMMARY.md Overview 5 min
PHASE1_IMPLEMENTATION_GUIDE.md Step-by-step guide 10 min
TEST_FAILURE_CATEGORIZATION.md Complete breakdown 20 min
ACTIONABLE_FIXES_SUMMARY.md Quick reference 10 min
ROOT_CAUSE_SUMMARY.md Technical deep dive 15 min

TL;DR

  1. Delete line 243 from src/metrics/cognitive.rs
  2. Run cargo test --lib
  3. See 191 tests passing (up from 162)
  4. Read ANALYSIS_SUMMARY.md for next steps
  5. Repeat Phases 2-4 for remaining 59 failures

Total time to 96% pass rate: 5-8 hours