feat(sources): generate .git_archival.txt for setuptools-scm builds

Synthesize .git_archival.txt with the resolved version for packages
built from source archives without .git metadata, enabling
setuptools-scm to resolve the version without environment variable
overrides.

Closes: #961

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

Author: LalatenduMohanty

src/fromager/sources.py

@@ -690,6 +690,14 @@ def default_build_sdist(
         sdist_root_dir=sdist_root_dir,
         build_dir=build_dir,
     )
+    has_git_metadata = build_dir.joinpath(".git").exists() or (
+        sdist_root_dir != build_dir and sdist_root_dir.joinpath(".git").exists()
+    )
+    if not has_git_metadata:
+        ensure_git_archival(
+            version=version,
+            target_dir=build_dir,
+        )
     # The format argument is specified based on
     # https://peps.python.org/pep-0517/#build-sdist.
     with tarfile.open(sdist_filename, "x:gz", format=tarfile.PAX_FORMAT) as sdist:
@@ -771,6 +779,74 @@ def ensure_pkg_info(
     return had_pkg_info
 
 
+# Template .git_archival.txt files contain "$Format:…$" placeholders that
+# `git archive` expands into real values.  If they survive unexpanded,
+# setuptools-scm detects "$FORMAT" in the node field and returns no version
+# (see setuptools_scm.git.archival_to_version).
+_UNPROCESSED_ARCHIVAL_MARKER = "$Format:"
+
+# Dummy commit hash used when synthesizing .git_archival.txt without a
+# real git repository.  The value is never interpreted by setuptools-scm
+# beyond checking that it is not an unprocessed $Format:…$ placeholder.
+_DUMMY_NODE = "0" * 40
+
+# Fields that must be present for setuptools-scm to resolve a version.
+_REQUIRED_ARCHIVAL_FIELDS = {"node", "describe-name"}
+
+_GIT_ARCHIVAL_CONTENT = """\
+node: {node}
+describe-name: {version}
+"""
+
+
+def ensure_git_archival(
+    *,
+    version: Version,
+    target_dir: pathlib.Path,
+) -> bool:
+    """Ensure that sdist has a usable ``.git_archival.txt`` for setuptools-scm.
+
+    When building from source archives without a ``.git`` directory,
+    setuptools-scm cannot determine the package version.  A synthesized
+    ``.git_archival.txt`` provides the version through the ``describe-name``
+    field so that setuptools-scm resolves it without requiring an environment
+    variable override.
+
+    See https://setuptools-scm.readthedocs.io/en/latest/usage/#git-archives
+
+    Returns True if a valid archival file was already present (no changes
+    made), False if a new file was written (file was missing or contained
+    unprocessed placeholders).
+    """
+    archival_file = target_dir.joinpath(".git_archival.txt")
+
+    if archival_file.is_file():
+        content = archival_file.read_text()
+        parsed_fields: dict[str, str] = {}
+        for line in content.splitlines():
+            if ":" not in line:
+                continue
+            key, _, value = line.partition(":")
+            parsed_fields[key.strip()] = value.strip()
+        if (
+            _UNPROCESSED_ARCHIVAL_MARKER not in content
+            and _REQUIRED_ARCHIVAL_FIELDS <= set(parsed_fields)
+            and all(parsed_fields.get(f) for f in _REQUIRED_ARCHIVAL_FIELDS)
+        ):
+            logger.debug("valid .git_archival.txt already present in %s", target_dir)
+            return True
+        logger.warning("replacing invalid .git_archival.txt in %s", target_dir)
+
+    archival_file.write_text(
+        _GIT_ARCHIVAL_CONTENT.format(
+            node=_DUMMY_NODE,
+            version=str(version),
+        )
+    )
+    logger.info("created .git_archival.txt for version %s in %s", version, target_dir)
+    return False
+
+
 def validate_sdist_filename(
     req: Requirement,
     version: Version,

tests/test_sources.py

@@ -312,3 +312,74 @@ def test_scan_compiled_extensions(
         assert matches == [pathlib.Path(filename)]
     else:
         assert matches == []
+
+
+class TestEnsureGitArchival:
+    """Tests for ensure_git_archival()."""
+
+    def test_creates_file_when_missing(self, tmp_path: pathlib.Path) -> None:
+        """Verify file is created with correct content when absent."""
+        version = Version("1.2.3")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+        archival = tmp_path / ".git_archival.txt"
+
+        assert result is False
+        assert archival.is_file()
+        content = archival.read_text()
+        assert "describe-name: 1.2.3\n" in content
+        assert "node: " in content
+        assert "$Format:" not in content
+
+    def test_replaces_unprocessed_file(self, tmp_path: pathlib.Path) -> None:
+        """Verify unprocessed template file is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text(
+            "node: $Format:%H$\n"
+            "node-date: $Format:%cI$\n"
+            "describe-name: $Format:%(describe:tags=true)$\n"
+        )
+        version = Version("4.5.6")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 4.5.6\n" in content
+        assert "$Format:" not in content
+
+    def test_preserves_valid_file(self, tmp_path: pathlib.Path) -> None:
+        """Verify a valid archival file is left untouched."""
+        archival = tmp_path / ".git_archival.txt"
+        original = (
+            "node: abc123\n"
+            "node-date: 2025-01-01T00:00:00+00:00\n"
+            "describe-name: v1.0.0-0-gabc123\n"
+        )
+        archival.write_text(original)
+        version = Version("9.9.9")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is True
+        assert archival.read_text() == original
+
+    def test_replaces_truncated_file(self, tmp_path: pathlib.Path) -> None:
+        """Verify a truncated file missing required fields is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text("node-date: 2025-01-01T00:00:00+00:00\n")
+        version = Version("3.0.0")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 3.0.0\n" in content
+
+    def test_replaces_file_with_empty_values(self, tmp_path: pathlib.Path) -> None:
+        """Verify a file with required fields but empty values is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text("node:\ndescribe-name:\n")
+        version = Version("5.0.0")
+        result = sources.ensure_git_archival(version=version, target_dir=tmp_path)
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 5.0.0\n" in content
+