Quick Start

This guide walks you through running your first review and understanding the results.

Run Your First Review

Navigate to your project directory and run:

unfault review

Unfault parses your code locally and shows what it finds:

Worth looking out for

  🟡  main.py:12  · The Slow Death
     FastAPI app `app` has no request timeout middleware
     ↳ puts  App A Availability SLO  at risk  (100%)
     A downstream dependency slows down and your service holds
     threads/connections until it saturates and dies.
     Tradeoff
     ↳ Simplicity              no timeout means less code and fewer
                               configuration decisions at call time.
     ↳ Systemic Availability   a single slow dependency can exhaust the thread
                               pool and take down the entire service.

  🟡  main.py:36  · The Retry Storm
     HTTP call via `httpx`.AsyncClient has no retry policy
     ↳ puts  App A Availability SLO  at risk  (100%)
     During an outage your service retries failures instantly, preventing the
     downstream service from ever recovering.
     Tradeoff
     ↳ Local Availability      retries transparently mask transient failures
                               from the caller, improving perceived reliability.
     ↳ Systemic Metastability  synchronized retries with no backoff create
                               thunderstorms that prevent downstream services
                               from ever recovering.

 app-a   python  ·  fastapi  ·  1 file   [ parse 5ms  engine 0ms  fetch 7849ms ]

Each finding names the failure mode, links it to any discovered SLOs at risk, explains the tradeoff, and gives a file and line number.

Drilling Into Details

To see full findings with suggested fixes:

unfault review --output full

This shows each finding with its location, explanation, and a suggested code change.

Output Formats

Choose the format that fits your workflow:

# Header + summary (good for the terminal)
unfault review

# Statistics only
unfault review --output concise

# Full findings with diffs
unfault review --output full

# Machine-readable for CI/CD or scripting
unfault review --output json

# GitHub Code Scanning
unfault review --output sarif

Filtering by Dimension

Focus on specific types of issues:

# Only stability issues
unfault review --dimension stability

# Only performance issues
unfault review --dimension performance

# Multiple dimensions
unfault review --dimension stability --dimension correctness

Available dimensions: stability, correctness, performance, scalability.

CI/CD Integration

Use exit codes to gate deployments:

unfault review
if [ $? -eq 5 ]; then
  echo "Findings detected. Blocking deployment."
  exit 1
fi

Explore the Code Graph

Before a refactor, check what depends on a file:

unfault graph impact src/api/auth.py

Find the most heavily-connected files:

unfault graph critical

See all files using a library:

unfault graph library requests