Module

cache.asset_dependency_map

Asset Dependency Map for incremental builds.

Tracks which pages reference which assets to enable on-demand asset discovery. This allows incremental builds to discover only assets needed for changed pages, skipping asset discovery for unchanged pages.

Architecture:

  • Mapping: source_path → set[asset_urls] (which pages use which assets)
  • Storage: .bengal/asset_deps.json (compact format)
  • Tracking: Built during page parsing by extracting asset references
  • Incremental: Only discover assets for changed pages

Performance Impact:

  • Asset discovery skipped for unchanged pages (~50ms saved per 100 pages)
  • Focus on only needed assets in incremental builds
  • Incremental asset fingerprinting possible

Asset Types Tracked:

  • Images: img src, picture sources
  • Stylesheets: link href
  • Scripts: script src
  • Fonts: @font-face urls
  • Other: data URLs, imports, includes
View source
3 Classes

Classes

AssetReference dataclass
Reference to an asset from a page.
0

Reference to an asset from a page.

Attributes

Name Type Description
url str
type str
source_page str
AssetDependencyEntry dataclass
Cache entry for asset dependencies. Implements the Cacheable protocol for type-safe serialization.
4

Cache entry for asset dependencies.

Implements the Cacheable protocol for type-safe serialization.

Inherits from Cacheable

Attributes

Name Type Description
assets set[str]
tracked_at str
is_valid bool

Methods 4

to_cache_dict
Serialize to cache-friendly dictionary (Cacheable protocol).
0 dict[str, Any] 
def to_cache_dict(self) -> dict[str, Any]

Serialize to cache-friendly dictionary (Cacheable protocol).

Returns

dict[str, Any]

from_cache_dict classmethod
Deserialize from cache dictionary (Cacheable protocol).
1 AssetDependencyEntry 
def from_cache_dict(cls, data: dict[str, Any]) -> AssetDependencyEntry

Deserialize from cache dictionary (Cacheable protocol).

Parameters 1
data dict[str, Any]
Returns

AssetDependencyEntry

to_dict
Alias for to_cache_dict (test compatibility).
0 dict[str, Any] 
def to_dict(self) -> dict[str, Any]

Alias for to_cache_dict (test compatibility).

Returns

dict[str, Any]

from_dict classmethod
Alias for from_cache_dict (test compatibility).
1 AssetDependencyEntry 
def from_dict(cls, data: dict[str, Any]) -> AssetDependencyEntry

Alias for from_cache_dict (test compatibility).

Parameters 1
data dict[str, Any]
Returns

AssetDependencyEntry

AssetDependencyMap
Persistent map of page-to-asset dependencies for incremental discovery. Purpose: - Track which ass…
15

Persistent map of page-to-asset dependencies for incremental discovery.

Purpose:

  • Track which assets each page references
  • Enable on-demand asset discovery
  • Skip asset discovery for unchanged pages
  • Support incremental asset fingerprinting

Cache Format (JSON): { "version": 1, "pages": { "content/index.md": { "assets": [ "/images/logo.png", "/css/style.css", "/fonts/inter.woff2" ], "tracked_at": "2025-10-16T12:00:00", "is_valid": true } } }

Methods 13

save_to_disk
Save asset dependencies to disk.
0 None 
def save_to_disk(self) -> None

Save asset dependencies to disk.

track_page_assets
Track assets referenced by a page.
2 None 
def track_page_assets(self, source_path: Path, assets: set[str]) -> None

Track assets referenced by a page.

Parameters 2
source_path Path

Path to source page
assets set[str]

Set of asset URLs/paths referenced by the page
get_page_assets
Get assets referenced by a page.
1 set[str] | None 
def get_page_assets(self, source_path: Path) -> set[str] | None

Get assets referenced by a page.

Parameters 1
source_path Path

Path to source page
Returns

set[str] | None —

Set of asset URLs if found and valid, None otherwise

has_assets
Check if page has tracked assets.
1 bool 
def has_assets(self, source_path: Path) -> bool

Check if page has tracked assets.

Parameters 1
source_path Path

Path to source page
Returns

bool —

True if page has valid asset tracking

get_all_assets
Get all unique assets referenced by any page.
0 set[str] 
def get_all_assets(self) -> set[str]

Get all unique assets referenced by any page.

Returns

set[str] —

Set of all asset URLs across all pages

get_assets_for_pages
Get all assets referenced by a set of pages.
1 set[str] 
def get_assets_for_pages(self, source_paths: list[Path]) -> set[str]

Get all assets referenced by a set of pages.

Parameters 1
source_paths list[Path]

List of page paths to find assets for
Returns

set[str] —

Set of all asset URLs referenced by the given pages

invalidate
Mark a page's asset tracking as invalid.
1 None 
def invalidate(self, source_path: Path) -> None

Mark a page's asset tracking as invalid.

Parameters 1
source_path Path

Path to source page
invalidate_all
Invalidate all asset tracking entries.
0 None 
def invalidate_all(self) -> None

Invalidate all asset tracking entries.

clear
Clear all asset tracking.
0 None 
def clear(self) -> None

Clear all asset tracking.

get_valid_entries
Get all valid asset tracking entries.
0 dict[str, set[str]] 
def get_valid_entries(self) -> dict[str, set[str]]

Get all valid asset tracking entries.

Returns

dict[str, set[str]] —

Dictionary mapping source_path to asset set for valid entries

get_invalid_entries
Get all invalid asset tracking entries.
0 dict[str, set[str]] 
def get_invalid_entries(self) -> dict[str, set[str]]

Get all invalid asset tracking entries.

Returns

dict[str, set[str]] —

Dictionary mapping source_path to asset set for invalid entries

stats
Get asset dependency map statistics.
0 dict[str, Any] 
def stats(self) -> dict[str, Any]

Get asset dependency map statistics.

Returns

dict[str, Any] —

Dictionary with cache stats

get_asset_pages
Get all pages that reference a specific asset.
1 set[str] 
def get_asset_pages(self, asset_url: str) -> set[str]

Get all pages that reference a specific asset.

Parameters 1
asset_url str

Asset URL to find references for
Returns

set[str] —

Set of page paths that reference this asset

Internal Methods 2
__init__
Initialize asset dependency map.
1 None 
def __init__(self, cache_path: Path | None = None)

Initialize asset dependency map.

Parameters 1
cache_path Path | None

Path to cache file (defaults to .bengal/asset_deps.json)
_load_from_disk
Load asset dependencies from disk if file exists.
0 None 
def _load_from_disk(self) -> None

Load asset dependencies from disk if file exists.