Functions

List of functions in the ude.doxygen_cache namespace.

Entity Name	Description
build_source_manifest	Walks `root_dirs` recursively and returns a sorted `(relpath, size, sha256)` manifest.
compute_source_manifest_hash	Hashes an already-sorted `(relpath, size, sha256)` manifest.
compute_doxygen_binary_id	Identity of the doxygen binary: resolved path + size + mtime.
_normalize_doxyfile_for_hash	Strips `OUTPUT_DIRECTORY` and rewrites absolute repo paths to repo-relative POSIX.
compute_doxyfile_hash	Hashes the merged Doxyfile content after path/OUTPUT_DIRECTORY normalization.
compute_project_key	Content-derived cache-directory key (Opus S5) – not a naming convention.
compute_project_key_and_dir	Computes the project key and its persistent directory path.
compute_parser_config_hash	Hashes the parser-level config (`exclude_swig_internals`, `export_macros`, …).
_hash_code_under_roots	Hashes every `.py` file under the given repo-relative `roots`, keyed by (repo-relative path, sha256), sorted for a deterministic combined digest. Shared by `compute_engine_code_id` and `compute_collector_code_id`.
compute_engine_code_id	Computed hash of the engine code the parser actually depends on.
compute_collector_code_id	Computed hash of the collector code the doxygen.exe invocation itself depends on (currently: `ude/collectors/**`, which includes `dom_ignore_filter.py` – an external INPUT_FILTER process Doxygen has no way to notice changed on its own). See `_COLLECTOR_CODE_ROOTS`.
compute_xml_fingerprint	Gates the doxygen.exe skip decision (Piece B).
compute_ir_fingerprint	Gates persisted-`ProjectCatalog` reuse (Piece B/E).
count_compounds	Counts `<compound>` entries in a Doxygen `index.xml` – the cheap signal used for the verified-successful-run floor (Opus S3): doxygen exits 0 even on a misconfigured, substantially empty run, so return-code alone is not sufficient evidence that a run’s output is trustworthy to cache.
load_fingerprint	Loads a `.ude_fingerprint.json` sidecar, or None if absent/corrupt.
write_fingerprint_atomically	Writes the fingerprint sidecar via write-then-rename, never a partial file in place.

Generated with Flude

Directory & Entity Index

Entity Name Summary / Description

_hash_code_under_roots function

Hashes every .py file under the given repo-relative roots, keyed by (repo-relative path, sha256), sorted for a deterministic combined digest. Shared by compute_engine_code_id and compute_collector_code_id.

Methods

_hash_code_under_roots

_hash_code_under_roots(engine_root: Union, roots: tuple) -> str

Parameter	Type	Description
engine_root	`Union`
roots	`tuple`

Generated with Flude

_normalize_doxyfile_for_hash function

Strips OUTPUT_DIRECTORY and rewrites absolute repo paths to repo-relative POSIX.

OUTPUT_DIRECTORY is derived FROM the fingerprint (via project_key) – including it would be circular. Absolute paths in INPUT/EXCLUDE differ across every checkout with a different workspace root (e.g. CI runners), which would otherwise make the hash differ for functionally identical configs.

Methods

_normalize_doxyfile_for_hash

_normalize_doxyfile_for_hash(doxy_content: str, repo_root: Path) -> str

Strips OUTPUT_DIRECTORY and rewrites absolute repo paths to repo-relative POSIX.

build_source_manifest function

Walks root_dirs recursively and returns a sorted (relpath, size, sha256) manifest.

Safe-asymmetric matching: honors exclude_dirs (exact resolved paths – unambiguous) but deliberately does not replicate Doxygen’s exclude_patterns/file_patterns wildcard matching – Doxygen interprets those itself, and a client-side reimplementation risks silently diverging. Over-including a file Doxygen ignores costs an occasional extra rebuild (safe); under-including a file Doxygen actually uses risks silently stale docs (unsafe).

Returns:

A list of (relpath, size, sha256) tuples, sorted by relpath, where

compute_collector_code_id function

Computed hash of the collector code the doxygen.exe invocation itself depends on (currently: ude/collectors/**, which includes dom_ignore_filter.py – an external INPUT_FILTER process Doxygen has no way to notice changed on its own). See _COLLECTOR_CODE_ROOTS.

Methods

compute_collector_code_id

compute_collector_code_id(engine_root: Union) -> str

compute_doxyfile_hash function

Hashes the merged Doxyfile content after path/OUTPUT_DIRECTORY normalization.

Methods

compute_doxyfile_hash

compute_doxyfile_hash(doxy_content: str, repo_root: Path) -> str

Hashes the merged Doxyfile content after path/OUTPUT_DIRECTORY normalization.

Parameter	Type	Description
doxy_content	`str`
repo_root	`Path`

Generated with Flude

compute_doxygen_binary_id function

Identity of the doxygen binary: resolved path + size + mtime.

Cheaper than spawning doxygen --version as an extra subprocess, and still reacts to a binary replacement (upgrade/downgrade).

Methods

compute_doxygen_binary_id

compute_doxygen_binary_id(doxygen_path: Union) -> str

Identity of the doxygen binary: resolved path + size + mtime.

Cheaper than spawning doxygen --version as an extra subprocess, and still reacts to a binary replacement (upgrade/downgrade).

Parameter	Type	Description
doxygen_path	`Union`

Generated with Flude

compute_engine_code_id function

Computed hash of the engine code the parser actually depends on.

Deliberately not a hand-bumped version constant: this repo’s two worst recent incidents (the disk-full temp leak, the silently-forced --format html bug) were both stale defaults nobody re-checked. A computed hash over ude/parsers/** + normalizer.py + models.py is self-maintaining and cheap (a few dozen files).

Methods

compute_engine_code_id

compute_engine_code_id(engine_root: Union) -> str

Computed hash of the engine code the parser actually depends on.

compute_ir_fingerprint function

Gates persisted-ProjectCatalog reuse (Piece B/E).

Deliberately built on top of xml_fingerprint (so any source/Doxyfile/ binary change also invalidates it) plus the parser-level inputs xml_fingerprint does not cover – this is the fix for Opus review finding B3.

Methods

compute_ir_fingerprint

compute_ir_fingerprint(xml_fingerprint: str, parser_config_hash: str, engine_code_id: str) -> str

Gates persisted-ProjectCatalog reuse (Piece B/E).

compute_parser_config_hash function

Hashes the parser-level config (exclude_swig_internals, export_macros, …).

Methods

compute_parser_config_hash

compute_parser_config_hash(parser_cfg: dict) -> str

Hashes the parser-level config (exclude_swig_internals, export_macros, …).

Parameter	Type	Description
parser_cfg	`dict`

Generated with Flude

compute_project_key function

Content-derived cache-directory key (Opus S5) – not a naming convention.

Two projects with genuinely identical collector config + source dirs + language share a directory (and therefore one doxygen run); any future divergence automatically gets its own directory instead of silently colliding under a string-munged name like stripping a _hugo suffix.

Methods

compute_project_key

compute_project_key(collector_cfg: dict, resolved_src_dirs: List, language: str, repo_root: Path, prefix: str) -> str

Content-derived cache-directory key (Opus S5) – not a naming convention.

compute_project_key_and_dir function

Computes the project key and its persistent directory path.

Refactored out of doxygen.py to be reusable for read-only lookups (e.g., baseline diffing) without invoking the collector.

Returns:

A tuple of (project_key, project_dir).

Methods

compute_project_key_and_dir

compute_project_key_and_dir(config: dict, collector_cfg: dict, src_dirs: List, base_dir: Path, cache_root: Path) -> Tuple[str, Path]

Computes the project key and its persistent directory path.

Refactored out of doxygen.py to be reusable for read-only lookups (e.g., baseline diffing) without invoking the collector.

compute_source_manifest_hash function

Hashes an already-sorted (relpath, size, sha256) manifest.

Methods

compute_source_manifest_hash

compute_source_manifest_hash(manifest: List]) -> str

Hashes an already-sorted (relpath, size, sha256) manifest.

Parameter	Type	Description
manifest	`List]`

Generated with Flude

compute_xml_fingerprint function

Gates the doxygen.exe skip decision (Piece B).

collector_code_id defaults to "" for callers that haven’t been updated yet (harmless – an empty component still participates in the hash, it just means “not tracked” rather than raising), but every real caller should pass compute_collector_code_id(engine_root).

Methods

compute_xml_fingerprint

compute_xml_fingerprint(doxygen_binary_id: str, doxyfile_hash: str, source_manifest_hash: str, collector_code_id: str, fp_version: int) -> str

Gates the doxygen.exe skip decision (Piece B).

count_compounds function

Counts <compound> entries in a Doxygen index.xml – the cheap signal used for the verified-successful-run floor (Opus S3): doxygen exits 0 even on a misconfigured, substantially empty run, so return-code alone is not sufficient evidence that a run’s output is trustworthy to cache.

Methods

count_compounds

count_compounds(index_xml_path: Union) -> int

load_fingerprint function

Loads a .ude_fingerprint.json sidecar, or None if absent/corrupt.

Methods

load_fingerprint

load_fingerprint(fingerprint_path: Union) -> Optional[dict]

Loads a .ude_fingerprint.json sidecar, or None if absent/corrupt.

Parameter	Type	Description
fingerprint_path	`Union`

Generated with Flude

write_fingerprint_atomically function

Writes the fingerprint sidecar via write-then-rename, never a partial file in place.

Methods

write_fingerprint_atomically

write_fingerprint_atomically(fingerprint_path: Union, data: dict)

Writes the fingerprint sidecar via write-then-rename, never a partial file in place.

Parameter	Type	Description
fingerprint_path	`Union`
data	`dict`

Generated with Flude