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

Ensure sdist builds without .git metadata have a valid .git_archival.txt
for setuptools-scm version resolution. Replaces existing invalid files
unconditionally. Creates new files only when generate_git_archival is
enabled in package settings, since bare versions break custom tag_regex.

Co-Authored-By: Claude <claude@anthropic.com>
Closes: #961
Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

Author: LalatenduMohanty

src/fromager/packagesettings/_models.py

@@ -147,6 +147,9 @@ class BuildOptions(pydantic.BaseModel):
     exclusive_build: bool = False
     """If true, this package must be built on its own (not in parallel with other packages). Default: False."""
 
+    generate_git_archival: bool = False
+    """If true, create a ``.git_archival.txt`` when missing for setuptools-scm version resolution. Default: False."""
+
 
 class ProjectOverride(pydantic.BaseModel):
     """Override pyproject.toml settings

src/fromager/packagesettings/_pbi.py

@@ -409,6 +409,10 @@ def project_override(self) -> ProjectOverride:
     def exclusive_build(self) -> bool:
         return self._ps.build_options.exclusive_build
 
+    @property
+    def generate_git_archival(self) -> bool:
+        return self._ps.build_options.generate_git_archival
+
     @property
     def variants(self) -> Mapping[Variant, VariantInfo]:
         """Get the variant configuration for the current package"""

src/fromager/sources.py

@@ -532,6 +532,15 @@ def prepare_source(
                 f"do not know how to unpack {prepare_source_details}, expected 1 or 2 members"
             )
     write_build_meta(source_root_dir.parent, req, source_filename, version)
+    # Ensure .git_archival.txt is valid before the build backend is
+    # imported — setuptools-scm resolves the version during
+    # get_requires_for_build_wheel().
+    ensure_git_archival(
+        ctx=ctx,
+        req=req,
+        sdist_root_dir=source_root_dir,
+        version=version,
+    )
     if source_root_dir is not None:
         logger.info(f"prepared source for {req} at {source_root_dir}")
     return source_root_dir
@@ -771,6 +780,93 @@ def ensure_pkg_info(
     return had_pkg_info
 
 
+# Template .git_archival.txt files contain "$Format:…$" placeholders that
+# `git archive` expands into real values.  setuptools-scm detects the string
+_UNPROCESSED_ARCHIVAL_MARKER = "%(describe"
+_REQUIRED_ARCHIVAL_FIELDS = {"describe-name"}
+_GIT_ARCHIVAL_CONTENT = "describe-name: {version}\n"
+
+
+def _is_valid_git_archival(content: str) -> bool:
+    """Check whether ``.git_archival.txt`` content has the required fields."""
+    if _UNPROCESSED_ARCHIVAL_MARKER in content:
+        return False
+    fields: dict[str, str] = {}
+    for line in content.splitlines():
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        fields[key.strip()] = value.strip()
+    return _REQUIRED_ARCHIVAL_FIELDS <= set(fields) and all(
+        fields.get(f) for f in _REQUIRED_ARCHIVAL_FIELDS
+    )
+
+
+def _has_git_metadata(sdist_root_dir: pathlib.Path, build_dir: pathlib.Path) -> bool:
+    """Check whether ``.git`` exists in sdist root or build directory."""
+    if build_dir.joinpath(".git").exists():
+        return True
+    return sdist_root_dir != build_dir and sdist_root_dir.joinpath(".git").exists()
+
+
+def _write_git_archival(archival_file: pathlib.Path, version: Version) -> None:
+    """Write a ``.git_archival.txt`` with the given version."""
+    archival_file.write_text(_GIT_ARCHIVAL_CONTENT.format(version=version))
+
+
+def ensure_git_archival(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    sdist_root_dir: pathlib.Path,
+    version: Version,
+) -> bool | None:
+    """Ensure ``.git_archival.txt`` is valid for setuptools-scm version resolution.
+
+    Behaviour:
+
+    * Skips packages with ``.git`` metadata (git clones need no fix).
+    * Replaces existing files that are unprocessed or missing required fields.
+    * Creates a new file **only** when ``generate_git_archival`` is enabled
+      in package settings (bare versions break custom ``tag_regex``).
+
+    Returns ``True`` (valid file present), ``False`` (created/replaced),
+    or ``None`` (no action taken).
+    """
+    pbi = ctx.package_build_info(req)
+    build_dir = pbi.build_dir(sdist_root_dir)
+
+    if _has_git_metadata(sdist_root_dir, build_dir):
+        logger.debug("git metadata found, skipping .git_archival.txt for %s", req.name)
+        return True
+
+    if not build_dir.is_dir():
+        logger.debug("build directory %s does not exist, skipping", build_dir)
+        return None
+
+    archival_file = build_dir / ".git_archival.txt"
+
+    # Existing file: validate and replace if invalid
+    if archival_file.is_file():
+        if _is_valid_git_archival(archival_file.read_text()):
+            logger.debug("valid .git_archival.txt already present in %s", build_dir)
+            return True
+        logger.info("replacing invalid .git_archival.txt in %s", build_dir)
+        _write_git_archival(archival_file, version)
+        return False
+
+    # No file: create only when config opt-in is enabled
+    if pbi.generate_git_archival:
+        logger.info(
+            "creating .git_archival.txt for %s (generate_git_archival enabled)",
+            req.name,
+        )
+        _write_git_archival(archival_file, version)
+        return False
+
+    return None
+
+
 def validate_sdist_filename(
     req: Requirement,
     version: Version,

tests/test_bootstrapper.py

@@ -261,7 +261,7 @@ def test_build_from_source_returns_dataclass(tmp_context: WorkContext) -> None:
     bt = bootstrapper.Bootstrapper(tmp_context)
 
     mock_sdist_root = tmp_context.work_dir / "package-1.0.0" / "package-1.0.0"
-    mock_sdist_root.parent.mkdir(parents=True, exist_ok=True)
+    mock_sdist_root.mkdir(parents=True, exist_ok=True)
     mock_source_file = tmp_context.work_dir / "package-1.0.0.tar.gz"
     mock_wheel = tmp_context.work_dir / "package-1.0.0-py3-none-any.whl"
     expected_unpack_dir = mock_sdist_root.parent

tests/test_packagesettings.py

@@ -41,6 +41,7 @@
         "cpu_cores_per_job": 4,
         "memory_per_job_gb": 4.0,
         "exclusive_build": False,
+        "generate_git_archival": False,
     },
     "changelog": {
         Version("1.0.1"): ["fixed bug"],
@@ -119,6 +120,7 @@
         "cpu_cores_per_job": 1,
         "memory_per_job_gb": 1.0,
         "exclusive_build": False,
+        "generate_git_archival": False,
     },
     "changelog": {},
     "config_settings": {},
@@ -156,6 +158,7 @@
         "cpu_cores_per_job": 1,
         "memory_per_job_gb": 1.0,
         "exclusive_build": False,
+        "generate_git_archival": False,
     },
     "changelog": {
         Version("1.0.1"): ["onboard"],

tests/test_sources.py

@@ -312,3 +312,174 @@ def test_scan_compiled_extensions(
         assert matches == [pathlib.Path(filename)]
     else:
         assert matches == []
+
+
+class TestEnsureGitArchival:
+    """Tests for ensure_git_archival()."""
+
+    @pytest.fixture()
+    def mock_ctx(self, tmp_path: pathlib.Path) -> Mock:
+        """Create a mock context whose build_dir returns sdist_root_dir."""
+        ctx = Mock(spec=context.WorkContext)
+        mock_pbi = Mock()
+        mock_pbi.build_dir.side_effect = lambda d: d
+        mock_pbi.generate_git_archival = False
+        ctx.package_build_info.return_value = mock_pbi
+        return ctx
+
+    @pytest.fixture()
+    def req(self) -> Requirement:
+        """Create a test requirement."""
+        return Requirement("test-package")
+
+    def test_skips_when_no_file_exists(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify no file is created when none existed before."""
+        version = Version("1.2.3")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+        archival = tmp_path / ".git_archival.txt"
+
+        assert result is None
+        assert not archival.is_file()
+
+    def test_replaces_unprocessed_file(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> 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(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 4.5.6\n" in content
+        assert "%(describe" not in content
+
+    def test_preserves_valid_file(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> 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(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+
+        assert result is True
+        assert archival.read_text() == original
+
+    def test_preserves_valid_file_describe_name_only(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify a file with only describe-name is valid."""
+        archival = tmp_path / ".git_archival.txt"
+        original = "describe-name: 2.0.0\n"
+        archival.write_text(original)
+        version = Version("9.9.9")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+
+        assert result is True
+        assert archival.read_text() == original
+
+    def test_replaces_truncated_file(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> 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(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+
+        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, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify a file with required fields but empty values is replaced."""
+        archival = tmp_path / ".git_archival.txt"
+        archival.write_text("describe-name:\n")
+        version = Version("5.0.0")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+
+        assert result is False
+        content = archival.read_text()
+        assert "describe-name: 5.0.0\n" in content
+
+    def test_skips_when_build_dir_missing(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify no error when build directory does not exist."""
+        nonexistent = tmp_path / "no-such-dir"
+        version = Version("1.0.0")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=nonexistent, version=version
+        )
+
+        assert result is None
+        assert not nonexistent.exists()
+
+    def test_skips_when_git_dir_exists(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify no file is created when .git directory exists."""
+        (tmp_path / ".git").mkdir()
+        version = Version("1.0.0")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+
+        assert result is True
+        assert not (tmp_path / ".git_archival.txt").exists()
+
+    def test_creates_file_when_config_enabled(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify file is created when generate_git_archival is enabled."""
+        mock_ctx.package_build_info.return_value.generate_git_archival = True
+        version = Version("1.2.3")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+        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
+
+    def test_skips_creation_when_config_disabled(
+        self, tmp_path: pathlib.Path, mock_ctx: Mock, req: Requirement
+    ) -> None:
+        """Verify no file is created when generate_git_archival is disabled."""
+        version = Version("1.2.3")
+        result = sources.ensure_git_archival(
+            ctx=mock_ctx, req=req, sdist_root_dir=tmp_path, version=version
+        )
+        archival = tmp_path / ".git_archival.txt"
+
+        assert result is None
+        assert not archival.is_file()