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
3Classes

Classes

AssetReference 3 ▼
Reference to an asset from a page.

Reference to an asset from a page.

Attributes

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

Cache entry for asset dependencies.

Implements the Cacheable protocol for type-safe serialization.

Attributes

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

Methods

to_cache_dict 0 dict[str, Any] ▼
Serialize to cache-friendly dictionary (Cacheable protocol).
def to_cache_dict(self) -> dict[str, Any]
Returns
dict[str, Any]
from_cache_dict 1 AssetDependencyEntry ▼
Deserialize from cache dictionary (Cacheable protocol).
classmethod
def from_cache_dict(cls, data: dict[str, Any]) -> AssetDependencyEntry
Parameters
Name Type Description
data —
Returns
AssetDependencyEntry
AssetDependencyMap 17 ▼
Persistent map of page-to-asset dependencies for incremental discovery. Purpose: - Track which ass…

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

save_to_disk 0 ▼
Save asset dependencies to disk.
def save_to_disk(self) -> None
track_page_assets 2 ▼
Track assets referenced by a page.
def track_page_assets(self, source_path: Path, assets: set[str]) -> None
Parameters
Name Type Description
source_path —

Path to source page
assets —

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

Path to source page
Returns
set[str] | None Set of asset URLs if found and valid, None otherwise
has_assets 1 bool ▼
Check if page has tracked assets.
def has_assets(self, source_path: Path) -> bool
Parameters
Name Type Description
source_path —

Path to source page
Returns
bool True if page has valid asset tracking
get_all_assets 0 set[str] ▼
Get all unique assets referenced by any page.
def get_all_assets(self) -> set[str]
Returns
set[str] Set of all asset URLs across all pages
get_assets_for_pages 1 set[str] ▼
Get all assets referenced by a set of pages.
def get_assets_for_pages(self, source_paths: list[Path]) -> set[str]
Parameters
Name Type Description
source_paths —

List of page paths to find assets for
Returns
set[str] Set of all asset URLs referenced by the given pages
invalidate 1 ▼
Mark a page's asset tracking as invalid.
def invalidate(self, source_path: Path) -> None
Parameters
Name Type Description
source_path —

Path to source page
invalidate_all 0 ▼
Invalidate all asset tracking entries.
def invalidate_all(self) -> None
clear 0 ▼
Clear all asset tracking.
def clear(self) -> None
get_valid_entries 0 dict[str, set[str]] ▼
Get all valid asset tracking entries.
def get_valid_entries(self) -> dict[str, set[str]]
Returns
dict[str, set[str]] Dictionary mapping source_path to asset set for valid entries
get_invalid_entries 0 dict[str, set[str]] ▼
Get all invalid asset tracking entries.
def get_invalid_entries(self) -> dict[str, set[str]]
Returns
dict[str, set[str]] Dictionary mapping source_path to asset set for invalid entries
get_asset_pages 1 set[str] ▼
Get all pages that reference a specific asset.
def get_asset_pages(self, asset_url: str) -> set[str]
Parameters
Name Type Description
asset_url —

Asset URL to find references for
Returns
set[str] Set of page paths that reference this asset
stats 0 dict[str, Any] ▼
Get asset dependency map statistics.
def stats(self) -> dict[str, Any]
Returns
dict[str, Any] Dictionary with cache stats
Internal Methods 4 ▼
__init__ 1 ▼
Initialize asset dependency map.
def __init__(self, cache_path: Path | None = None)
Parameters
Name Type Description
cache_path —

Path to cache file (defaults to .bengal/asset_deps.json)

Default:None
_deserialize 1 ▼
Deserialize loaded data into cache state.
def _deserialize(self, data: dict[str, Any]) -> None
Parameters
Name Type Description
data —
_serialize 0 dict[str, Any] ▼
Serialize cache state for saving.
def _serialize(self) -> dict[str, Any]
Returns
dict[str, Any]
_on_version_mismatch 0 ▼
Clear state on version mismatch.
def _on_version_mismatch(self) -> None