Merge pull request #94 from PyAutoLabs/feature/default-branch-release-to-main

feat(workspace): add version-mismatch check helper

Author: Jammy2211

autoconf/__init__.py

@@ -19,6 +19,7 @@
 from .setup_colab import for_autolens
 from .setup_notebook import setup_notebook
 from .test_mode import test_mode_level, is_test_mode, skip_fit_output, skip_visualization, skip_checks
+from .workspace import check_version, WorkspaceVersionMismatchError
 
 
 __version__ = "2026.4.13.6"

autoconf/workspace.py

@@ -0,0 +1,52 @@
+import os
+import warnings
+from pathlib import Path
+
+from autoconf import exc
+
+
+class WorkspaceVersionMismatchError(exc.ConfigException):
+    pass
+
+
+def check_version(library_version, workspace_root=None):
+    """
+    Verify that the workspace at ``workspace_root`` matches ``library_version``.
+
+    Reads ``version.txt`` from ``workspace_root`` (defaults to the current
+    working directory, which is where users run workspace scripts from).
+    Raises ``WorkspaceVersionMismatchError`` if the file's version differs
+    from ``library_version``. If ``version.txt`` does not exist (e.g. an
+    older workspace clone or one cloned from ``main`` outside a release tag)
+    a warning is emitted and the check is skipped.
+
+    Set ``PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1`` to disable the check
+    entirely — intended for developers running source checkouts where
+    workspace and library versions intentionally diverge.
+    """
+    if os.environ.get("PYAUTO_SKIP_WORKSPACE_VERSION_CHECK") == "1":
+        return
+
+    root = Path(workspace_root) if workspace_root else Path.cwd()
+    version_file = root / "version.txt"
+
+    if not version_file.exists():
+        warnings.warn(
+            f"No version.txt found at {version_file}. Cannot verify that the "
+            f"workspace matches the installed library version ({library_version}). "
+            f"If you cloned the workspace from main rather than a release tag, "
+            f"set PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1 to silence this warning."
+        )
+        return
+
+    workspace_version = version_file.read_text().strip()
+
+    if workspace_version != library_version:
+        raise WorkspaceVersionMismatchError(
+            f"Workspace version ({workspace_version}) at {root} does not match "
+            f"the installed library version ({library_version}). Re-clone the "
+            f"workspace at the matching tag:\n\n"
+            f"    git clone --branch {library_version} <workspace-repo-url>\n\n"
+            f"Or set PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1 to override (intended "
+            f"for source-checkout development)."
+        )

test_autoconf/test_workspace.py

@@ -0,0 +1,38 @@
+import pytest
+
+from autoconf.workspace import check_version, WorkspaceVersionMismatchError
+
+
+def test_match(tmp_path):
+    (tmp_path / "version.txt").write_text("2026.4.13.6\n")
+    check_version("2026.4.13.6", workspace_root=tmp_path)
+
+
+def test_mismatch_raises(tmp_path):
+    (tmp_path / "version.txt").write_text("2026.4.13.6\n")
+    with pytest.raises(WorkspaceVersionMismatchError) as info:
+        check_version("2025.1.1.1", workspace_root=tmp_path)
+    assert "2026.4.13.6" in str(info.value)
+    assert "2025.1.1.1" in str(info.value)
+
+
+def test_missing_file_warns(tmp_path):
+    with pytest.warns(UserWarning, match="No version.txt"):
+        check_version("2026.4.13.6", workspace_root=tmp_path)
+
+
+def test_env_override_skips_mismatch(tmp_path, monkeypatch):
+    monkeypatch.setenv("PYAUTO_SKIP_WORKSPACE_VERSION_CHECK", "1")
+    (tmp_path / "version.txt").write_text("2025.1.1.1\n")
+    check_version("2026.4.13.6", workspace_root=tmp_path)
+
+
+def test_env_override_skips_missing_file(tmp_path, monkeypatch):
+    monkeypatch.setenv("PYAUTO_SKIP_WORKSPACE_VERSION_CHECK", "1")
+    check_version("2026.4.13.6", workspace_root=tmp_path)
+
+
+def test_default_root_is_cwd(tmp_path, monkeypatch):
+    (tmp_path / "version.txt").write_text("2026.4.13.6\n")
+    monkeypatch.chdir(tmp_path)
+    check_version("2026.4.13.6")