fix(fingerprint): trust dependencies_complete for Jinja2 transforms

Merged
OG
4mo ago
+224-34

Why

Make the commit-id fold gate builder-aware instead of uniform. A Jinja2 transform with a complete dependency closure now produces a stable fingerprint without an explicit watch declaration, so unrelated commits no longer churn its fingerprint.

Jinja2 completeness is sound: it comes from a real transitive parse of the template include/import/extends graph, so a complete closure alone is enough. A dynamic or unresolvable reference still drops completeness to False and keeps the commit id folded. Python transforms and generators are unchanged - their completeness flag is only the package-directory floor, so a present watch remains required to omit the commit id.

Amends spec FR-016/FR-019 with a builder-aware note.

Ref: IFC-2952

What changed

What changed

Made the fingerprint commit-id fold gate builder-aware so a Jinja2 transform with a
fully-resolved dependency closure no longer needs an explicit watch: declaration to get a
stable fingerprint.

Previously the gate was uniform: whenever watch was absent (None), the commit id was
folded into the fingerprint regardless of closure completeness, so a Jinja2 transform's
fingerprint churned on every commit - even when the change touched none of its real
dependencies. The only workaround was to declare a no-op watch: {}, which was pure
ceremony.

The gate now branches on the builder:

  • Jinja2 trusts dependencies_complete on its own. It comes from a real transitive parse
    of the template include/import/extends graph and is only True when every reference
    resolved to a tracked template, so a complete closure yields a stable, precise fingerprint
    with no watch needed. A dynamic or unresolvable reference drops completeness to False,
    which keeps the commit id folded.
  • Python transforms and generators are unchanged. Their dependencies_complete = True is
    only the unsound package-directory floor (an out-of-directory import is silently missed), so
    a present watch remains the only signal trusted to omit the commit id.

Files

  • backend/infrahub/git/fingerprint/composer.py - fold_commit_id gains a watch_required
    flag; compose_transformation sets it from the input type (False for Jinja2, True for
    Python), and generators pass True.
  • backend/tests/unit/git/fingerprint/test_composer_transformation.py,
    test_watch_state.py - parametrized unit coverage of the builder-aware truth table.
  • backend/tests/integration/git/test_fingerprint_transformation.py - end-to-end test: an
    unrelated commit leaves a complete, watch-free Jinja2 transform's fingerprint stable while
    still changing a watch-free Python transform's fingerprint.
  • dev/specs/ifc-2844-definition-fingerprint/spec.md - amendment notes on FR-016/FR-019.

Safety

No under-regeneration is introduced. Python and generators are untouched, incomplete Jinja2
closures still fold the commit id, and an unresolved connected query still folds it too. No
consumer reads the fingerprint yet, so the only observable effect is that some Jinja2
fingerprints stop churning - a safe over-regeneration → stable transition.

Checklist

  • Tests added/updated
  • Internal .md docs updated (internal knowledge and AI code tools knowledge)
  • I have reviewed AI generated content