Module

debug.base

Base classes and registry for Bengal debug tools.

Provides common infrastructure for all debug/diagnostic tools including output formatting, data collection patterns, and tool registration.

Key Components:

  • DebugTool: Base class for all debug tools
  • DebugReport: Structured output from debug tools
  • DebugRegistry: Tool discovery and registration

Related Modules:

  • bengal.debug.incremental_debugger: Incremental build debugging
  • bengal.debug.delta_analyzer: Build comparison
  • bengal.debug.dependency_visualizer: Dependency graph visualization

See Also:

  • bengal/cli/commands/debug.py: CLI integration
View source
5 Classes

Classes

Severity
Severity levels for debug findings.
2

Severity levels for debug findings.

Inherits from Enum

Methods 2

emoji property
Get emoji for severity level.
str 
def emoji(self) -> str

Get emoji for severity level.

Returns

str

color property
Get Rich color token for severity.
str 
def color(self) -> str

Get Rich color token for severity.

Returns

str

DebugFinding dataclass
A single finding from a debug tool. Represents an observation, issue, or insight discovered during…
2

A single finding from a debug tool.

Represents an observation, issue, or insight discovered during analysis. Findings can range from informational to critical and include actionable suggestions where applicable.

Attributes

Name Type Description
title str

Short title describing the finding
description str

Detailed explanation of what was found
severity Severity

Severity level (info, warning, error, critical)
category str

Category for grouping (e.g., "cache", "dependency", "performance")
location str | None

Optional file path or identifier related to finding
suggestion str | None

Optional actionable suggestion for resolution
metadata dict[str, Any]

Additional context-specific data
line int | None

Optional line number for file-based findings

Methods 2

format_short
Format as single line.
0 str 
def format_short(self) -> str

Format as single line.

Returns

str

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

Format with full details.

Returns

str

DebugReport dataclass
Structured output from a debug tool. Aggregates findings, statistics, and recommendations from a d…
8

Structured output from a debug tool.

Aggregates findings, statistics, and recommendations from a debug analysis. Provides multiple output formats for CLI, JSON, and markdown export.

Attributes

Name Type Description
tool_name str

Name of the tool that generated this report
timestamp datetime

When the report was generated
findings list[DebugFinding]

List of findings discovered during analysis
summary str

Brief summary of analysis results
statistics dict[str, Any]

Numeric statistics from analysis
recommendations list[str]

High-level recommendations based on findings
execution_time_ms float

How long the analysis took
metadata dict[str, Any]

Additional tool-specific data

Methods 8

findings_by_severity property
Group findings by severity level.
dict[Severity, list… 
def findings_by_severity(self) -> dict[Severity, list[DebugFinding]]

Group findings by severity level.

Returns

dict[Severity, list[DebugFinding]]

findings_by_category property
Group findings by category.
dict[str, list[Debu… 
def findings_by_category(self) -> dict[str, list[DebugFinding]]

Group findings by category.

Returns

dict[str, list[DebugFinding]]

has_issues property
Check if report contains warnings or errors.
bool 
def has_issues(self) -> bool

Check if report contains warnings or errors.

Returns

bool

error_count property
Count of error and critical findings.
int 
def error_count(self) -> int

Count of error and critical findings.

Returns

int

warning_count property
Count of warning findings.
int 
def warning_count(self) -> int

Count of warning findings.

Returns

int

add_finding
Add a finding to the report.
3 DebugFinding 
def add_finding(self, title: str, description: str, severity: Severity = Severity.INFO, **kwargs: Any) -> DebugFinding

Add a finding to the report.

Parameters 3
title str
description str
severity Severity
Returns

DebugFinding

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

Convert report to dictionary for JSON serialization.

Returns

dict[str, Any]

format_summary
Format a brief summary for CLI output.
0 str 
def format_summary(self) -> str

Format a brief summary for CLI output.

Returns

str

DebugTool abstract
Base class for all Bengal debug tools. Provides common infrastructure for analysis tools including…
4

Base class for all Bengal debug tools.

Provides common infrastructure for analysis tools including:

  • Standardized report generation
  • Access to site and cache data
  • Consistent output formatting

Subclasses implement analyze() to perform their specific analysis.

Creation:

Subclass and implement analyze() method.
Inherits from ABC

Attributes

Name Type Description
name str
description str

Methods 3

create_report
Create a new report for this tool.
0 DebugReport 
def create_report(self) -> DebugReport

Create a new report for this tool.

Returns

DebugReport

analyze
Perform analysis and return report. Subclasses must implement this method to p…
0 DebugReport 
def analyze(self) -> DebugReport

Perform analysis and return report.

Subclasses must implement this method to perform their specific analysis and return a DebugReport with findings.

Returns

DebugReport —

DebugReport containing analysis results

run
Run analysis with timing. Wraps analyze() with timing measurement.
0 DebugReport 
def run(self) -> DebugReport

Run analysis with timing.

Wraps analyze() with timing measurement.

Returns

DebugReport —

DebugReport with execution time populated

Internal Methods 1
__init__
Initialize debug tool.
3 None 
def __init__(self, site: Site | None = None, cache: BuildCache | None = None, root_path: Path | None = None)

Initialize debug tool.

Parameters 3
site Site | None

Optional Site instance for analysis
cache BuildCache | None

Optional BuildCache for cache inspection
root_path Path | None

Root path of the project (defaults to cwd)
DebugRegistry
Registry for debug tools. Enables tool discovery and provides CLI integration point. Usage: >…
4

Registry for debug tools.

Enables tool discovery and provides CLI integration point.

Usage:

>>> registry = DebugRegistry()
>>> registry.register(IncrementalBuildDebugger)
>>> tool = registry.get("incremental")

Attributes

Name Type Description
_tools dict[str, type[DebugTool]]

Methods 4

register classmethod
Register a debug tool class. Can be used as a decorator: @DebugRegistry.r…
1 type[DebugTool] 
def register(cls, tool_class: type[DebugTool]) -> type[DebugTool]

Register a debug tool class.

Can be used as a decorator:

@DebugRegistry.register
class MyTool(DebugTool):
    name = "my-tool"
    ...
Parameters 1
tool_class type[DebugTool]

The tool class to register
Returns

type[DebugTool] —

The tool class (for decorator usage)

get classmethod
Get a tool class by name.
1 type[DebugTool] | None 
def get(cls, name: str) -> type[DebugTool] | None

Get a tool class by name.

Parameters 1
name str
Returns

type[DebugTool] | None

list_tools classmethod
List all registered tools with descriptions.
0 list[tuple[str, str]] 
def list_tools(cls) -> list[tuple[str, str]]

List all registered tools with descriptions.

Returns

list[tuple[str, str]]

create classmethod
Create a tool instance by name.
3 DebugTool | None 
def create(cls, name: str, site: Site | None = None, cache: BuildCache | None = None, **kwargs: Any) -> DebugTool | None

Create a tool instance by name.

Parameters 3
name str

Tool name
site Site | None

Optional Site instance
cache BuildCache | None

Optional BuildCache instance **kwargs: Additional arguments passed to tool
Returns

DebugTool | None —

Tool instance or None if not found