Module

debug.incremental_debugger

Incremental build debugger for diagnosing rebuild issues.

Provides diagnostic tools for understanding why pages rebuild, identifying phantom rebuilds, validating cache consistency, and simulating changes.

Key Features:

  • Explain why a specific page was rebuilt
  • Find pages that rebuild without apparent cause (phantom rebuilds)
  • Validate cache integrity and consistency
  • Simulate what would rebuild if a file changed

Related Modules:

  • bengal.cache.build_cache: Cache storage and tracking
  • bengal.cache.dependency_tracker: Dependency graph construction
  • bengal.orchestration.incremental: Incremental build logic

See Also:

  • bengal/debug/base.py: Debug tool infrastructure
  • plan/active/rfc-incremental-builds.md: Incremental build design
View source
5 Classes

Classes

RebuildReason
Reasons why a page might be rebuilt.
1

Reasons why a page might be rebuilt.

Inherits from Enum

Methods 1

description property
Human-readable description of the reason.
str 
def description(self) -> str

Human-readable description of the reason.

Returns

str

RebuildExplanation dataclass
Detailed explanation of why a page was rebuilt. Provides comprehensive information about what trig…
3

Detailed explanation of why a page was rebuilt.

Provides comprehensive information about what triggered a rebuild, including the chain of dependencies that led to the rebuild.

Attributes

Name Type Description
page_path str

Path to the page that was rebuilt
reasons list[RebuildReason]

List of reasons why the page was rebuilt
changed_dependencies list[str]

Files that changed and caused the rebuild
cache_status str

Status of the page in the cache
timestamps dict[str, str]

Relevant timestamps (content mtime, cache time, etc.)
dependency_chain list[str]

Chain of dependencies that triggered rebuild
suggestions list[str]

Suggestions for optimization if applicable

Methods 3

primary_reason property
Get the primary (first) reason for rebuild.
RebuildReason 
def primary_reason(self) -> RebuildReason

Get the primary (first) reason for rebuild.

Returns

RebuildReason

format_summary
Format as brief summary.
0 str 
def format_summary(self) -> str

Format as brief summary.

Returns

str

format_detailed
Format with full details.
0 str 
def format_detailed(self) -> str

Format with full details.

Returns

str

PhantomRebuild dataclass
A page that rebuilds without apparent cause. Phantom rebuilds are pages that rebuild even though n…
0

A page that rebuilds without apparent cause.

Phantom rebuilds are pages that rebuild even though none of their known dependencies changed. These indicate missing dependency tracking or cache issues.

Attributes

Name Type Description
page_path str

Path to the page with phantom rebuild
rebuild_count int

Number of times this page has phantom rebuilt
last_rebuild datetime | None

When the page last rebuilt
suspected_causes list[str]

Possible causes of the phantom rebuild
investigation_notes list[str]

Notes from investigation
CacheConsistencyReport dataclass
Report on cache consistency and integrity.
1

Report on cache consistency and integrity.

Attributes

Name Type Description
total_entries int

Total entries in cache
valid_entries int

Entries that pass validation
invalid_entries int

Entries that fail validation
orphaned_entries list[str]

Entries for files that no longer exist
missing_entries list[str]

Files that should be cached but aren't
issues list[str]

Specific issues found

Methods 1

health_score property
Calculate cache health as percentage.
float 
def health_score(self) -> float

Calculate cache health as percentage.

Returns

float

IncrementalBuildDebugger
Debug tool for incremental build issues. Helps diagnose why pages rebuild, find phantom rebuilds, …
9

Debug tool for incremental build issues.

Helps diagnose why pages rebuild, find phantom rebuilds, and validate cache consistency.

Creation:

Direct instantiation or via DebugRegistry:
    debugger = IncrementalBuildDebugger(site=site, cache=cache)
    debugger = DebugRegistry.create("incremental", site=site, cache=cache)
Inherits from DebugTool

Methods 5

analyze
Perform comprehensive incremental build analysis. Analyzes cache consistency, …
0 DebugReport 
def analyze(self) -> DebugReport

Perform comprehensive incremental build analysis.

Analyzes cache consistency, identifies phantom rebuilds, and provides optimization recommendations.

Returns

DebugReport —

DebugReport with findings and recommendations

explain_rebuild
Explain why a specific page was rebuilt. Analyzes the page's dependencies, cac…
1 RebuildExplanation 
def explain_rebuild(self, page_path: str) -> RebuildExplanation

Explain why a specific page was rebuilt.

Analyzes the page's dependencies, cache status, and file timestamps to determine why it was rebuilt (or would be rebuilt).

Parameters 1
page_path str

Path to the page (relative to content dir or absolute)
Returns

RebuildExplanation —

RebuildExplanation with detailed analysis

find_phantom_rebuilds
Find pages that rebuilt without apparent dependency changes. Phantom rebuilds …
0 list[PhantomRebuild] 
def find_phantom_rebuilds(self) -> list[PhantomRebuild]

Find pages that rebuilt without apparent dependency changes.

Phantom rebuilds indicate missing dependency tracking or cache issues.

Returns

list[PhantomRebuild] —

List of PhantomRebuild instances

validate_cache_consistency
Validate cache integrity and consistency. Checks for: - Orphaned entries (file…
0 CacheConsistencyReport 
def validate_cache_consistency(self) -> CacheConsistencyReport

Validate cache integrity and consistency.

Checks for:

  • Orphaned entries (files no longer exist)
  • Missing entries (files should be cached but aren't)
  • Invalid entries (corrupted or malformed)
Returns

CacheConsistencyReport —

CacheConsistencyReport with validation results

simulate_change
Simulate what would rebuild if a file changed. Useful for understanding the bl…
1 list[str] 
def simulate_change(self, file_path: str) -> list[str]

Simulate what would rebuild if a file changed.

Useful for understanding the blast radius of a change before making it.

Parameters 1
file_path str

Path to the file that would change
Returns

list[str] —

List of page paths that would need to rebuild

Internal Methods 4
__init__
Initialize incremental build debugger.
4 None 
def __init__(self, site: Site | None = None, cache: BuildCache | None = None, root_path: Path | None = None, rebuild_log: list[str] | None = None)

Initialize incremental build debugger.

Parameters 4
site Site | None

Site instance for page access
cache BuildCache | None

BuildCache for cache inspection
root_path Path | None

Root path of the project
rebuild_log list[str] | None

Optional list of paths that were rebuilt (from last build)
_build_dependency_chain
Build the chain of dependencies from changed file to target.
3 list[str] 
def _build_dependency_chain(self, target: str, changed: str, visited: set[str] | None = None) -> list[str]

Build the chain of dependencies from changed file to target.

Parameters 3
target str
changed str
visited set[str] | None
Returns

list[str]

_analyze_dependency_health
Analyze the health of dependency tracking.
0 list[DebugFinding] 
def _analyze_dependency_health(self) -> list[DebugFinding]

Analyze the health of dependency tracking.

Returns

list[DebugFinding]

_generate_recommendations
Generate recommendations based on analysis.
1 list[str] 
def _generate_recommendations(self, report: DebugReport) -> list[str]

Generate recommendations based on analysis.

Parameters 1
report DebugReport
Returns

list[str]