class

Hwaro::Core::Build::Cache

Inherits Reference / Object

Build cache manager for tracking file changes

Constants

CACHE_FILE = ".hwaro_cache.json"

Default cache filename - uses dot prefix to hide from directory listings and 'hwaro_' prefix to identify it as project-specific cache

Constructors

new(enabled : Bool = true, cache_path : String = CACHE_FILE)

Source

Class methods

compute_config_hash(config_path : String = "config.toml") : String

Compute a checksum for the config file

Source

compute_config_hash(config : Models::Config, env : String | Nil = nil) : String

Compute a checksum for the effective (env-merged, env-substituted) config plus the active env name and resolved base_url. Hashing the parsed config.raw rather than the raw config.toml bytes means an env override file (config.<env>.toml), changed ${ENV_VAR} substitutions, or a --base-url override all invalidate the per-page cache — none of which the file-bytes hash above can detect — while a formatting-only edit to config.toml no longer forces a full rebuild.

Source

compute_templates_hash(templates : Hash(String, String)) : String

Compute a combined checksum for a set of template files. Fields are length-prefixed (see DigestUtils) so adjacent name/content pairs can't produce the same byte stream across boundaries, which would have failed to invalidate.

Source

Instance methods

changed?(file_path : String, output_path : String = "", cascade_hash : String = "", template_hash : String | Nil = nil, extra_outputs : Array(String) = [] of String) : Bool

Check if a file has changed since last build. template_hash is the page's template closure fingerprint; nil skips the comparison (non-page entries, or dependency tracking off). extra_outputs are secondary sibling output files (see [outputs]) that must also still exist on disk — a manually deleted index.json forces a rebuild just like a deleted index.html does.

Source

clear

Clear all cache entries

Source

compute_file_hash(file_path : String) : String

Compute MD5 checksum of a file's content (streaming to avoid loading large files entirely into memory)

Source

enabled?

Check if caching is enabled

Source

filter_changed(files : Array(String)) : Array(String)

Check multiple files for changes (returns changed files)

Source

invalidate(file_path : String)

Remove entry from cache

Source

load

Load cache from disk

Source

output_paths_for(file_path : String) : Array(String)

Secondary output files (beyond the primary HTML output) recorded for file_path on the last build, or [] when the entry has none (or doesn't exist). Used to detect a manually deleted sibling format file and to locate stale files when a page's source is removed (see Builder#stale_outputs_for_removed).

Source

page_set_changed?(fingerprint : String) : Bool

Has the global page set (content page metadata that listings render — path/url/title/date/weight/draft/section) changed since last build?

Source

record_set_fingerprints(page_set : String, section_set : String) : Nil

Record the current page/section-set fingerprints so the next build can detect a change; marks the cache dirty when either value moves.

Source

save

Save cache to disk using atomic write (temp file + rename) to prevent corruption from partial writes (e.g. disk full, crash). No-op when nothing changed since load — a warm all-hits build otherwise re-serializes every entry just to write identical bytes.

Source

section_set_changed?(fingerprint : String) : Bool

Has the section set (section metadata that nav/menus render) changed?

Source

set_global_checksums(template_hash : String, config_hash : String, invalidate_on_template_change : Bool = true)

Set the current build's template and config checksums. A config change always invalidates all entries. A template change invalidates all entries only when invalidate_on_template_change is true — with template dependency tracking active, the builder passes false and per-page closure hashes (see changed?) decide which pages a template edit actually affects.

Source

stats

Get cache statistics

Source

update(file_path : String, output_path : String = "", cascade_hash : String = "", template_hash : String | Nil = nil, output_paths : Array(String) = [] of String)

Update cache entry for a file. template_hash is the page's template closure fingerprint; nil stores the global templates checksum (non-page entries). output_paths are the secondary sibling output files this page emitted (see [outputs]); empty when the feature isn't in use. Thread-safe: protected by mutex for concurrent parallel builds.

Source