Querying the Codebase

The unfault graph commands let you ask structural questions about your codebase. Before making changes, running a migration, or onboarding to unfamiliar code, these queries help you understand what’s there and what might break.

What You Can Ask

All graph commands run locally against the code graph built during analysis. No network required.

What depends on a file?

unfault graph impact src/api/auth.py

Shows direct and transitive dependents. Use this before refactoring to understand blast radius.

What depends on a function?

unfault graph function-impact src/api/auth.py:validate_token

Narrower than file-level impact. Useful when you’re changing a single function, not an entire module.

What does this file depend on?

unfault graph deps src/api/routes/payments.py

Shows internal imports and external libraries. Helps you understand the full picture before touching a file.

Which files use a library?

unfault graph library requests

Useful when migrating dependencies, auditing security vulnerabilities, or understanding how broadly a library is used.

Which files are the most critical?

unfault graph critical

Returns files sorted by how many other files depend on them. These are your load-bearing files, the ones where changes have the widest effect.

What does the codebase look like at a glance?

unfault graph stats

A quick overview: file count, function count, total edges, external library usage.

Combining Queries

A practical workflow before a significant change:

# 1. Understand how central the file is
unfault graph impact src/core/models.py

# 2. See what it depends on
unfault graph deps src/core/models.py

# 3. Find files using any libraries involved
unfault graph library sqlalchemy

JSON Output

All graph commands support --json for programmatic use or scripting:

unfault graph impact --json src/api/auth.py
unfault graph critical --json --limit 5
unfault graph library --json requests

This is useful for CI checks, custom tooling, or feeding context to AI assistants.

Review as a Query

The review command itself is a form of query: “what patterns in this codebase tend to cause production problems?”

# Everything
unfault review

# Only stability patterns
unfault review --dimension stability

# Only performance patterns
unfault review --dimension performance

# Detailed output with suggested fixes
unfault review --output full

# Machine-readable output
unfault review --output json