Module

debug.delta_analyzer

Build delta analyzer for comparing builds and explaining changes.

Provides tools for comparing two builds to understand what changed, why pages were added/removed/modified, and tracking build evolution over time.

Key Features:

  • Compare two build snapshots
  • Identify added, removed, and changed pages
  • Explain timing differences between builds
  • Track build history and trends

Related Modules:

  • bengal.utils.build_stats: Build statistics
  • bengal.cache.build_cache: Build cache with timestamps
  • bengal.debug.base: Debug tool infrastructure

See Also:

  • bengal/debug/incremental_debugger.py: For cache-specific debugging
View source
4 Classes

Classes

BuildSnapshot dataclass
Snapshot of a build state for comparison. Captures key metrics and file lists from a build for del…
4

Snapshot of a build state for comparison.

Captures key metrics and file lists from a build for delta analysis.

Attributes

Name Type Description
timestamp datetime

When the build occurred
build_time_ms float

Total build time
page_count int

Number of pages built
asset_count int

Number of assets processed
pages set[str]

Set of page paths in this build
output_files set[str]

Set of output file paths
phase_times dict[str, float]

Timing by phase (discovery, rendering, etc.)
config_hash str | None

Hash of configuration at build time
metadata dict[str, Any]

Additional build metadata

Methods 4

from_build_stats classmethod
Create snapshot from BuildStats.
2 BuildSnapshot 
def from_build_stats(cls, stats: BuildStats, pages: set[str]) -> BuildSnapshot

Create snapshot from BuildStats.

Parameters 2
stats BuildStats

BuildStats from a completed build
pages set[str]

Set of page paths that were built
Returns

BuildSnapshot —

BuildSnapshot capturing the build state

from_cache classmethod
Create snapshot from BuildCache.
1 BuildSnapshot 
def from_cache(cls, cache: BuildCache) -> BuildSnapshot

Create snapshot from BuildCache.

Parameters 1
cache BuildCache

BuildCache with build state
Returns

BuildSnapshot —

BuildSnapshot capturing cached state

to_dict
Convert to dictionary for JSON serialization.
0 dict[str, Any] 
def to_dict(self) -> dict[str, Any]

Convert to dictionary for JSON serialization.

Returns

dict[str, Any]

from_dict classmethod
Create from dictionary.
1 BuildSnapshot 
def from_dict(cls, data: dict[str, Any]) -> BuildSnapshot

Create from dictionary.

Parameters 1
data dict[str, Any]
Returns

BuildSnapshot

BuildDelta dataclass
Difference between two builds. Captures what changed between builds including added/removed pages,…
6

Difference between two builds.

Captures what changed between builds including added/removed pages, timing changes, and configuration differences.

Attributes

Name Type Description
before BuildSnapshot

The earlier build snapshot
after BuildSnapshot

The later build snapshot
added_pages set[str]

Pages in 'after' but not in 'before'
removed_pages set[str]

Pages in 'before' but not in 'after'
time_change_ms float

Change in build time (positive = slower)
time_change_pct float

Percentage change in build time
phase_changes dict[str, float]

Changes in phase timings
config_changed bool

Whether configuration hash changed

Methods 5

page_change_count property
Total pages added or removed.
int 
def page_change_count(self) -> int

Total pages added or removed.

Returns

int

is_significant property
Check if delta represents significant changes.
bool 
def is_significant(self) -> bool

Check if delta represents significant changes.

Returns

bool

compute classmethod
Compute delta between two builds.
2 BuildDelta 
def compute(cls, before: BuildSnapshot, after: BuildSnapshot) -> BuildDelta

Compute delta between two builds.

Parameters 2
before BuildSnapshot

Earlier build snapshot
after BuildSnapshot

Later build snapshot
Returns

BuildDelta —

BuildDelta with computed differences

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

Internal Methods 1
_format_time_change
Format time change with color indicators.
2 str 
def _format_time_change(self, ms: float, pct: float) -> str

Format time change with color indicators.

Parameters 2
ms float
pct float
Returns

str

BuildHistory
Tracks build history for trend analysis. Stores snapshots of builds over time and provides trend a…
7

Tracks build history for trend analysis.

Stores snapshots of builds over time and provides trend analysis.

Attributes

Name Type Description
snapshots —

List of build snapshots in chronological order
max_snapshots —

Maximum number of snapshots to keep

Methods 4

add
Add a snapshot to history.
1 None 
def add(self, snapshot: BuildSnapshot) -> None

Add a snapshot to history.

Parameters 1
snapshot BuildSnapshot
get_latest
Get the N most recent snapshots.
1 list[BuildSnapshot] 
def get_latest(self, n: int = 1) -> list[BuildSnapshot]

Get the N most recent snapshots.

Parameters 1
n int
Returns

list[BuildSnapshot]

get_baseline
Get the baseline (first) snapshot.
0 BuildSnapshot | None 
def get_baseline(self) -> BuildSnapshot | None

Get the baseline (first) snapshot.

Returns

BuildSnapshot | None

compute_trend
Compute trend statistics over history.
0 dict[str, Any] 
def compute_trend(self) -> dict[str, Any]

Compute trend statistics over history.

Returns

dict[str, Any]

Internal Methods 3
__init__
Initialize build history.
2 None 
def __init__(self, storage_path: Path | None = None, max_snapshots: int = 50)

Initialize build history.

Parameters 2
storage_path Path | None

Path to store history (defaults to .bengal/build_history.json)
max_snapshots int

Maximum snapshots to retain
_load
Load history from disk.
0 None 
def _load(self) -> None

Load history from disk.

_save
Save history to disk.
0 None 
def _save(self) -> None

Save history to disk.

BuildDeltaAnalyzer
Debug tool for comparing builds and explaining changes. Helps understand what changed between buil…
8

Debug tool for comparing builds and explaining changes.

Helps understand what changed between builds, why build times changed, and track build evolution over time.

Creation:

Direct instantiation or via DebugRegistry:
    analyzer = BuildDeltaAnalyzer(site=site, cache=cache)
Inherits from DebugTool

Methods 5

analyze
Analyze build deltas and trends.
0 DebugReport 
def analyze(self) -> DebugReport

Analyze build deltas and trends.

Returns

DebugReport —

DebugReport with findings about build changes

compare_snapshots
Compare two specific snapshots.
2 BuildDelta 
def compare_snapshots(self, before: BuildSnapshot, after: BuildSnapshot) -> BuildDelta

Compare two specific snapshots.

Parameters 2
before BuildSnapshot

Earlier snapshot
after BuildSnapshot

Later snapshot
Returns

BuildDelta —

BuildDelta with comparison results

compare_to_previous
Compare current state to most recent snapshot.
0 BuildDelta | None 
def compare_to_previous(self) -> BuildDelta | None

Compare current state to most recent snapshot.

Returns

BuildDelta | None —

BuildDelta or None if no history available

compare_to_baseline
Compare current state to baseline (first) snapshot.
0 BuildDelta | None 
def compare_to_baseline(self) -> BuildDelta | None

Compare current state to baseline (first) snapshot.

Returns

BuildDelta | None —

BuildDelta or None if no baseline available

save_baseline
Save current state as new baseline (clears history).
0 None 
def save_baseline(self) -> None

Save current state as new baseline (clears history).

Internal Methods 3
__init__
Initialize build delta analyzer.
4 None 
def __init__(self, site: Site | None = None, cache: BuildCache | None = None, root_path: Path | None = None, history: BuildHistory | None = None)

Initialize build delta analyzer.

Parameters 4
site Site | None

Site instance for current state
cache BuildCache | None

BuildCache for cache inspection
root_path Path | None

Root path of the project
history BuildHistory | None

Optional BuildHistory for trend analysis
_get_current_snapshot
Get snapshot of current state.
0 BuildSnapshot | None 
def _get_current_snapshot(self) -> BuildSnapshot | None

Get snapshot of current state.

Returns

BuildSnapshot | None

_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]