Track builder state to skip redundant rebuilds

Write builder configuration to appose.json after each successful build,
and compare it on subsequent builds to skip unnecessary reinstallation.
Each builder (Pixi, Mamba, Uv) contributes its specific fields via
_add_state_fields, with base fields (content, scheme, channels, flags,
envVars) provided by BaseBuilder. Programmatic pixi builds now wipe
envDir before reinitializing to avoid conflicts with stale state.

As per apposed/appose-java@8401825

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ctrueden

src/appose/builder/__init__.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import sys
@@ -508,6 +509,32 @@ def flags(self, *flags: str) -> BaseBuilder:
 
     # -- Helper methods --
 
+    def _add_state_fields(self, state: dict) -> None:
+        """Populate state dict for appose.json comparison. Subclasses override, calling super first."""
+        state["content"] = self._content
+        state["scheme"] = self._scheme.name() if self._scheme is not None else None
+        state["channels"] = list(self._channels)
+        state["flags"] = list(self._flags)
+        state["envVars"] = dict(sorted(self._env_vars.items()))
+
+    def _build_state_string(self) -> str:
+        """Build deterministic JSON string of current builder state."""
+        state: dict = {"builder": self.env_type()}
+        self._add_state_fields(state)
+        return json.dumps(state, separators=(",", ":"))
+
+    def _is_up_to_date(self, env_dir: Path) -> bool:
+        """Returns True if appose.json matches current builder state."""
+        appose_json = env_dir / "appose.json"
+        if not appose_json.is_file():
+            return False
+        return appose_json.read_text(encoding="utf-8") == self._build_state_string()
+
+    def _write_appose_state_file(self, env_dir: Path) -> None:
+        """Write current builder state to appose.json after a successful build."""
+        appose_json = env_dir / "appose.json"
+        appose_json.write_text(self._build_state_string(), encoding="utf-8")
+
     def _resolve_env_dir(self) -> Path:
         """Determine the environment directory path."""
         if self._env_dir:

src/appose/builder/mamba.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import shutil
 from pathlib import Path
 
 from . import BaseBuilder, BuildException, Builder, BuilderFactory
@@ -50,31 +51,19 @@ def build(self) -> Environment:
                 f"Cannot use MambaBuilder: environment already managed by uv/venv at {env_dir}",
             )
 
-        # Create Mamba tool instance early so it's available for wrapping
-        mamba = Mamba()
-
-        # Is this env_dir an already-existing conda directory?
-        is_conda_dir = (env_dir / "conda-meta").is_dir()
-        if is_conda_dir:
-            # Environment already exists, just wrap it
-            return self._create_environment(mamba, env_dir)
-
-        # Building a new environment - config content is required
-        if self._content is None:
-            raise BuildException(
-                self, "No source specified for MambaBuilder. Use .file() or .content()"
-            )
-
-        # Infer scheme if not explicitly set
-        if self._scheme is None:
+        # Infer scheme from content if not explicitly set.
+        if self._content is not None and self._scheme is None:
             self._scheme = scheme_from_content(self._content)
 
-        if self._scheme.name() != "environment.yml":
+        if self._scheme is not None and self._scheme.name() != "environment.yml":
             raise BuildException(
                 self,
-                f"MambaBuilder only supports environment.yml scheme, got: {self.scheme}",
+                f"MambaBuilder only supports environment.yml scheme, got: {self._scheme.name()}",
             )
 
+        # Create Mamba tool instance early so it's available for wrapping
+        mamba = Mamba()
+
         # Set up progress/output consumers
         mamba.set_output_consumer(
             lambda msg: [sub(msg) for sub in self._output_subscribers]
@@ -104,6 +93,24 @@ def build(self) -> Environment:
         try:
             mamba.install()
 
+            # If the env state matches our current configuration,
+            # skip all package management and return immediately.
+            if self._is_up_to_date(env_dir):
+                return self._create_environment(mamba, env_dir)
+
+            if self._content is None:
+                # No source specified; wrap externally-managed conda env if present.
+                if (env_dir / "conda-meta").is_dir():
+                    return self._create_environment(mamba, env_dir)
+                raise BuildException(
+                    self,
+                    "No source specified for MambaBuilder. Use .file() or .content()",
+                )
+
+            # Wipe existing env directory to avoid conflicts with stale state.
+            if env_dir.exists():
+                shutil.rmtree(env_dir)
+
             # Two-step build: create empty env, write config, then update
             # Step 1: Create empty environment
             mamba.create(env_dir)
@@ -115,6 +122,7 @@ def build(self) -> Environment:
             # Step 3: Update environment from yml
             mamba.update(env_dir, env_yaml)
 
+            self._write_appose_state_file(env_dir)
             return self._create_environment(mamba, env_dir)
 
         except (IOError, KeyboardInterrupt) as e:

src/appose/builder/pixi.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import shutil
 from pathlib import Path
 
 from . import BaseBuilder, BuildException, Builder, BuilderFactory
@@ -75,6 +76,12 @@ def pypi(self, *packages: str) -> PixiBuilder:
     def env_type(self) -> str:
         return "pixi"
 
+    def _add_state_fields(self, state: dict) -> None:
+        super()._add_state_fields(state)
+        state["condaPackages"] = list(self._conda_packages)
+        state["pypiPackages"] = list(self._pypi_packages)
+        state["pixiEnvironment"] = self._pixi_environment
+
     def build(self) -> Environment:
         """
         Build the Pixi environment.
@@ -134,21 +141,10 @@ def build(self) -> Environment:
         try:
             pixi.install()
 
-            # Check if this is already a pixi project
-            is_pixi_dir = (
-                (env_dir / "pixi.toml").is_file()
-                or (env_dir / "pyproject.toml").is_file()
-                or (env_dir / ".pixi").is_dir()
-            )
-
-            if (
-                is_pixi_dir
-                and self._content is None
-                and not self._conda_packages
-                and not self._pypi_packages
-            ):
-                # Environment already exists, just use it
-                return self._create_environment(pixi, env_dir)
+            # If the env state matches our current configuration,
+            # skip all package management and return immediately.
+            if self._is_up_to_date(env_dir):
+                return self._build_pixi_environment(pixi, env_dir)
 
             # Handle source-based build (file or content)
             if self._content is not None:
@@ -181,13 +177,10 @@ def build(self) -> Environment:
                 if self._channels:
                     pixi.add_channels(env_dir, *self._channels)
             else:
-                # Programmatic package building
-                if is_pixi_dir:
-                    # Already initialized, just use it
-                    return self._create_environment(pixi, env_dir)
-
-                if not env_dir.exists():
-                    env_dir.mkdir(parents=True, exist_ok=True)
+                # Programmatic package building: wipe and reinitialize to avoid stale state.
+                if env_dir.exists():
+                    shutil.rmtree(env_dir)
+                env_dir.mkdir(parents=True, exist_ok=True)
 
                 pixi.init(env_dir)
 
@@ -212,21 +205,21 @@ def build(self) -> Environment:
                     pixi.add_pypi_packages(env_dir, *self._pypi_packages)
 
                 # Verify that appose was included when building programmatically
-                prog_build = bool(self._conda_packages) or bool(self._pypi_packages)
-                if prog_build:
-                    import re
-
-                    has_appose = any(
-                        re.match(r"^appose\b", pkg) for pkg in self._conda_packages
-                    ) or any(re.match(r"^appose\b", pkg) for pkg in self._pypi_packages)
-                    if not has_appose:
-                        raise BuildException(
-                            self,
-                            "Appose package must be explicitly included when building programmatically. "
-                            'Add .conda("appose") or .pypi("appose") to your builder.',
-                        )
+                import re
 
-            return self._create_environment(pixi, env_dir)
+                has_appose = any(
+                    re.match(r"^appose\b", pkg) for pkg in self._conda_packages
+                ) or any(re.match(r"^appose\b", pkg) for pkg in self._pypi_packages)
+                if not has_appose:
+                    raise BuildException(
+                        self,
+                        "Appose package must be explicitly included when building programmatically. "
+                        'Add .conda("appose") or .pypi("appose") to your builder.',
+                    )
+
+            self._run_pixi_install(pixi, env_dir)
+            self._write_appose_state_file(env_dir)
+            return self._build_pixi_environment(pixi, env_dir)
 
         except (IOError, KeyboardInterrupt) as e:
             raise BuildException(self, cause=e)
@@ -268,13 +261,25 @@ def wrap(self, env_dir: str | Path) -> Environment:
         self.base(env_path)
         return self.build()
 
-    def _create_environment(self, pixi: Pixi, env_dir: Path) -> Environment:
+    def _run_pixi_install(self, pixi: Pixi, env_dir: Path) -> None:
+        """Run pixi install for the given environment directory."""
+        env_dir_abs = env_dir.absolute()
+        manifest_file = env_dir_abs / "pyproject.toml"
+        if not manifest_file.exists():
+            manifest_file = env_dir_abs / "pixi.toml"
+
+        install_cmd = ["install", "--manifest-path", str(manifest_file.absolute())]
+        if self._pixi_environment is not None:
+            install_cmd.extend(["--environment", self._pixi_environment])
+        pixi.exec(*install_cmd)
+
+    def _build_pixi_environment(self, pixi: Pixi, env_dir: Path) -> Environment:
         """
-        Create an Environment for the given Pixi directory.
+        Construct an Environment object for the given Pixi directory.
 
         Args:
-            env_dir: The Pixi environment directory
             pixi: The Pixi tool instance
+            env_dir: The Pixi environment directory
 
         Returns:
             Environment configured for this Pixi installation
@@ -287,12 +292,6 @@ def _create_environment(self, pixi: Pixi, env_dir: Path) -> Environment:
         if not manifest_file.exists():
             manifest_file = env_dir_abs / "pixi.toml"
 
-        # Ensure the pixi environment is fully installed.
-        install_cmd = ["install", "--manifest-path", str(manifest_file.absolute())]
-        if self._pixi_environment is not None:
-            install_cmd.extend(["--environment", self._pixi_environment])
-        pixi.exec(*install_cmd)
-
         base = str(env_dir_abs)
         env_name = self._pixi_environment or "default"
 

src/appose/builder/uv.py

@@ -58,6 +58,11 @@ def include(self, *packages: str) -> UvBuilder:
     def env_type(self) -> str:
         return "uv"
 
+    def _add_state_fields(self, state: dict) -> None:
+        super()._add_state_fields(state)
+        state["pythonVersion"] = self._python_version
+        state["packages"] = list(self._packages)
+
     def build(self) -> Environment:
         """
         Build the uv environment.
@@ -120,13 +125,16 @@ def build(self) -> Environment:
         try:
             uv.install()
 
-            # Check if this is already a uv virtual environment
-            is_uv_venv = (env_dir / "pyvenv.cfg").is_file()
-
-            if is_uv_venv and self._content is None and not self._packages:
-                # Environment already exists and no new config/packages, just use it
+            # If the env state matches our current configuration,
+            # skip all package management and return immediately.
+            if self._is_up_to_date(env_dir):
                 return self._create_environment(env_dir)
 
+            # Determine whether the venv already exists.
+            is_venv_built = (env_dir / "pyvenv.cfg").is_file() or (
+                env_dir / ".venv"
+            ).is_dir()
+
             # Handle source-based build (file or content)
             if self._content is not None:
                 if self._scheme.name() == "pyproject.toml":
@@ -144,7 +152,7 @@ def build(self) -> Environment:
                 else:
                     # Handle requirements.txt - traditional venv + pip install
                     # Create virtual environment if it doesn't exist
-                    if not is_uv_venv:
+                    if not is_venv_built:
                         uv.create_venv(env_dir, self._python_version)
 
                     # Write requirements.txt to envDir
@@ -155,7 +163,7 @@ def build(self) -> Environment:
                     uv.pip_install_from_requirements(env_dir, str(reqs_file.absolute()))
             else:
                 # Programmatic package building
-                if not is_uv_venv:
+                if not is_venv_built:
                     # Create virtual environment
                     uv.create_venv(env_dir, self._python_version)
 
@@ -167,6 +175,7 @@ def build(self) -> Environment:
                         all_packages.append("appose")
                     uv.pip_install(env_dir, *all_packages)
 
+            self._write_appose_state_file(env_dir)
             return self._create_environment(env_dir)
 
         except (IOError, KeyboardInterrupt) as e:

tests/builder/test_wrap.py

@@ -87,10 +87,7 @@ def test_wrap_uv():
             "uv environment should have no special launcher"
         )
     finally:
-        if pyvenv_cfg.exists():
-            pyvenv_cfg.unlink()
-        if uv_dir.exists():
-            uv_dir.rmdir()
+        delete_recursively(uv_dir)
 
 
 def test_wrap_custom():