fix: make app-folder resolution and its tests cross-platform

Fixes the four Windows CI failures (all pre-existing: this PR had only
touched base.py and tests/test_base.py) and one real Windows bug found
while investigating.

Code fix -- Windows 'cache' collided with 'data'/'state':
  APP_FOLDER_STANDARDS described the Windows cache root as
  FolderSpec("LOCALAPPDATA", join(%LOCALAPPDATA%, "Temp")). Since the
  fallback is only used when the env var is *absent*, and LOCALAPPDATA is
  always set on Windows, the "Temp" default was dead code: cache resolved
  to %LOCALAPPDATA%, exactly the data/state root. Clearing an app's cache
  would have deleted the user's data. FolderSpec gains a `subpath` field
  that expresses "a kind that lives inside another kind's root", so cache
  is now the documented %LOCALAPPDATA%\Temp.

  The table also snapshotted os.getenv() into its own fallbacks at import
  time, which made those fallbacks untestable and unreachable. They are now
  declarative literals (~\AppData\Roaming etc.), so a missing env var yields
  a real absolute root instead of "" -- an empty root would have degraded
  os.path.join(root, app_name) into a *relative* path.

  The single os.name branch is now app_folder_standards(os_name), so either
  platform's table can be resolved from any platform, and
  system_default_for_app_data_folder takes it via an optional keyword. That
  makes Windows behaviour testable on Linux/macOS -- see the new
  tests/test_platform_standards.py, which loops over both platforms.

Test fixes -- assertions that were POSIX-shaped, not wrong behaviour:
  - test_app_data.py steered app folders with XDG_CONFIG_HOME/XDG_DATA_HOME.
    XDG is a POSIX standard and is correctly ignored on Windows, so the
    redirection silently did nothing there: two tests failed on the location
    assertion and five others passed while writing into the runner's real
    user profile. They now use config2py's own CONFIG2PY_<KIND>_DIR override,
    which is honoured on every platform, and compare resolved Path objects
    rather than strings. Location is now asserted in 5 tests, up from 2.
  - test_sync_store.py::test_store_repr asserted a separator literal
    (`temp_file in repr(store)`); pathlib's repr always spells paths with
    forward slashes, so the native Windows form never appears. It now
    asserts the store's filepath identity plus the separator-free filename.

Doctest fix:
  get_app_folder's doctest expected '.../.config/config2py'. Rather than
  skipping it, it now asserts the properties that hold on every platform:
  the result is absolute, is named after the app, and sits directly inside
  the 'config' root. That is strictly more coverage than the ELLIPSIS form.

Also corrected get_app_rootdir's docstring, which advertised the override
variables under wrong names (CONFIG2PY_*_FOLDER instead of CONFIG2PY_*_DIR)
and implied XDG works everywhere.

pytest config: testpaths named "tests", which does not exist (tests live in
config2py/tests/), so pytest warned and fell back to recursive discovery from
the CWD. Set to ["config2py"]. doctest_optionflags now match what the wads
run-tests-uv action passes on the command line (ELLIPSIS,
IGNORE_EXCEPTION_DETAIL) -- it overrides the file, so NORMALIZE_WHITESPACE
here meant local runs and CI applied different rules.

Collected tests: 106 -> 127 (+20 platform tests, +1 doctest), no warnings.
Dependents gate (29 suites) unchanged before/after: 25 pass, 2 pre-existing
failures (smart-cv, yp), 1 no-tests, 1 tests-disabled.

Claude-Session: https://claude.ai/code/session_01Kug7UUbVeCQgruvNXUq63c

Author: thorwhalen

config2py/tests/test_app_data.py

@@ -7,18 +7,42 @@
 
 import pytest
 
-from config2py.util import ensure_seeded, AppData
+from config2py.util import ensure_seeded, AppData, config2py_env_var
+
+
+def _redirect_app_root(folder_kind: str, target):
+    """Redirect a config2py app-root folder kind at *target* for the test.
+
+    Uses config2py's own ``CONFIG2PY_<KIND>_DIR`` override, which is honoured on
+    every platform.  The XDG_* variables must NOT be used here: they are a POSIX
+    standard and are ignored on Windows, so tests keyed on them silently write
+    into the real user profile instead of the temp dir.
+    """
+    env_var = getattr(config2py_env_var, folder_kind)
+    return patch.dict(os.environ, {env_var: str(target)})
+
+
+def _same_path(a, b) -> bool:
+    """Compare two paths by identity-on-disk, not by their string spelling.
+
+    ``resolve()`` on both sides normalises the differences that make naive
+    string comparison fail per-platform: macOS ``/var`` -> ``/private/var``
+    symlinks, and Windows 8.3 short names (``RUNNER~1`` -> ``runneradmin``).
+    """
+    return Path(a).resolve() == Path(b).resolve()
 
 
 # ---------------------------------------------------------------------------
 # Helpers — mock importlib.resources for isolated testing
 # ---------------------------------------------------------------------------
 
+
 def _mock_importlib_files(seed_store: dict):
     """Return a mock for importlib.resources.files that reads from *seed_store*.
 
     *seed_store* maps ``(subpackage, filename)`` to ``bytes`` content.
     """
+
     def fake_files(package_path: str):
         # Extract subpackage from e.g. "mypkg._seed_data.resources"
         parts = package_path.split(".")
@@ -36,6 +60,7 @@ def __truediv__(self, filename):
                 return mock_ref
 
         return FakeTraversable()
+
     return fake_files
 
 
@@ -110,6 +135,7 @@ def test_returns_path_object(self, tmp_path, mock_seeds_for_ensure):
     def test_custom_seed_data_dir(self, tmp_path):
         """Ensure the seed_data_dir parameter is used in the package path."""
         calls = []
+
         def fake_files(pkg_path):
             calls.append(pkg_path)
             mock = MagicMock()
@@ -121,7 +147,10 @@ def fake_files(pkg_path):
         target = tmp_path / "file.txt"
         with patch("importlib.resources.files", side_effect=fake_files):
             ensure_seeded(
-                target, "mypkg", "resources", "file.txt",
+                target,
+                "mypkg",
+                "resources",
+                "file.txt",
                 seed_data_dir="my_seeds",
             )
         assert calls[0] == "mypkg.my_seeds.resources"
@@ -145,21 +174,22 @@ def test_custom_package_name(self):
         assert app.package_name == "my_app"
 
     def test_app_folder_creates_directory(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_DATA_HOME": str(tmp_path)}):
+        with _redirect_app_root("data", tmp_path):
             app = AppData("testapp")
             folder = app.app_folder(folder_kind="data")
             assert folder.is_dir()
             assert folder.name == "testapp"
+            assert _same_path(folder, tmp_path / "testapp")
 
     def test_app_folder_config(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_CONFIG_HOME": str(tmp_path)}):
+        with _redirect_app_root("config", tmp_path):
             app = AppData("testapp")
             folder = app.app_folder(folder_kind="config")
             assert folder.is_dir()
-            assert folder == tmp_path / "testapp"
+            assert _same_path(folder, tmp_path / "testapp")
 
     def test_get_resource_seeds_when_missing(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_DATA_HOME": str(tmp_path)}):
+        with _redirect_app_root("data", tmp_path):
             with patch(
                 "importlib.resources.files",
                 side_effect=_mock_importlib_files(SEED_STORE),
@@ -168,10 +198,12 @@ def test_get_resource_seeds_when_missing(self, tmp_path):
                 path = app.get_resource("hello.txt")
                 assert path.exists()
                 assert path.read_bytes() == b"hello world\nline two\n"
-                assert "resources" in str(path)
+                assert _same_path(
+                    path, tmp_path / "testapp" / "resources" / "hello.txt"
+                )
 
     def test_get_resource_preserves_user_edits(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_DATA_HOME": str(tmp_path)}):
+        with _redirect_app_root("data", tmp_path):
             with patch(
                 "importlib.resources.files",
                 side_effect=_mock_importlib_files(SEED_STORE),
@@ -184,7 +216,7 @@ def test_get_resource_preserves_user_edits(self, tmp_path):
                 assert path2.read_text() == "edited by user"
 
     def test_get_config_seeds_when_missing(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_CONFIG_HOME": str(tmp_path)}):
+        with _redirect_app_root("config", tmp_path):
             with patch(
                 "importlib.resources.files",
                 side_effect=_mock_importlib_files(SEED_STORE),
@@ -194,16 +226,17 @@ def test_get_config_seeds_when_missing(self, tmp_path):
                 assert path.exists()
                 data = json.loads(path.read_text())
                 assert data["tempo"] == 120
+                assert _same_path(path, tmp_path / "testapp" / "defaults.json")
 
     def test_get_artifact_dir_creates_subdir(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_DATA_HOME": str(tmp_path)}):
+        with _redirect_app_root("data", tmp_path):
             app = AppData("testapp")
             midi_dir = app.get_artifact_dir("midi")
             assert midi_dir.is_dir()
-            assert midi_dir == tmp_path / "testapp" / "artifacts" / "midi"
+            assert _same_path(midi_dir, tmp_path / "testapp" / "artifacts" / "midi")
 
     def test_get_artifact_dir_multiple_kinds(self, tmp_path):
-        with patch.dict(os.environ, {"XDG_DATA_HOME": str(tmp_path)}):
+        with _redirect_app_root("data", tmp_path):
             app = AppData("testapp")
             for kind in ("midi", "audio", "exports"):
                 d = app.get_artifact_dir(kind)

config2py/tests/test_platform_standards.py

@@ -0,0 +1,102 @@
+"""Cross-platform tests for the app-folder standards table.
+
+``config2py.util.app_folder_standards`` is the single place where config2py
+branches on the operating system.  Because it takes the ``os.name`` to resolve
+for as an argument, these tests exercise *both* platforms' tables from whatever
+platform happens to be running -- Windows behaviour is verified on Linux/macOS
+and vice versa.
+"""
+
+import os
+from typing import get_args
+
+import pytest
+
+from config2py.util import (
+    APP_FOLDER_STANDARDS,
+    AppFolderKind,
+    app_folder_standards,
+    config2py_env_var,
+    get_app_rootdir,
+    system_default_for_app_data_folder,
+)
+
+#: The ``os.name`` values config2py distinguishes between.
+OS_NAMES = ("nt", "posix")
+
+#: Every folder kind config2py knows about.
+FOLDER_KINDS = tuple(APP_FOLDER_STANDARDS)
+
+#: Environment values standing in for a real Windows user profile.
+WINDOWS_ENV = {
+    "APPDATA": r"C:\Users\someone\AppData\Roaming",
+    "LOCALAPPDATA": r"C:\Users\someone\AppData\Local",
+    "TEMP": r"C:\Users\someone\AppData\Local\Temp",
+}
+
+
+@pytest.mark.parametrize("os_name", OS_NAMES)
+def test_every_kind_is_specified_on_every_platform(os_name):
+    """Both platform tables cover exactly the kinds the type allows."""
+    standards = app_folder_standards(os_name)
+    assert set(standards) == set(get_args(AppFolderKind))
+
+
+@pytest.mark.parametrize("os_name", OS_NAMES)
+@pytest.mark.parametrize("folder_kind", FOLDER_KINDS)
+def test_defaults_are_nonempty(os_name, folder_kind, monkeypatch):
+    """A missing platform env var must still yield a usable root, never ''.
+
+    An empty root silently degrades ``os.path.join(root, app_name)`` into a
+    *relative* path, which would scatter app folders into the CWD.
+    """
+    standards = app_folder_standards(os_name)
+    for spec in standards.values():
+        monkeypatch.delenv(spec.env_var, raising=False)
+    resolved = system_default_for_app_data_folder(folder_kind, standards=standards)
+    assert resolved
+    assert not resolved.endswith(("/", "\\"))
+
+
+def test_windows_cache_is_not_the_data_folder(monkeypatch):
+    """Regression: on Windows 'cache' must not collide with 'data'/'state'.
+
+    Both are rooted at %LOCALAPPDATA%, so 'cache' has to live in a sub-folder.
+    When they collided, clearing an app's cache would delete the user's data.
+    """
+    standards = app_folder_standards("nt")
+    for name, value in WINDOWS_ENV.items():
+        monkeypatch.setenv(name, value)
+    resolved = {
+        kind: system_default_for_app_data_folder(kind, standards=standards)
+        for kind in standards
+    }
+    assert resolved["cache"] != resolved["data"]
+    assert resolved["cache"] != resolved["state"]
+    # ... and it is the documented %LOCALAPPDATA%\Temp, i.e. *inside* the root
+    assert os.path.basename(resolved["cache"]) == "Temp"
+    assert os.path.dirname(resolved["cache"]) == resolved["data"]
+
+
+@pytest.mark.parametrize("os_name", OS_NAMES)
+def test_posix_only_xdg_vars_are_absent_from_the_windows_table(os_name):
+    """XDG_* is a POSIX standard; the Windows table must not name those vars."""
+    standards = app_folder_standards(os_name)
+    env_vars = {spec.env_var for spec in standards.values()}
+    if os_name == "nt":
+        assert not any(v.startswith("XDG_") for v in env_vars)
+    else:
+        assert all(v.startswith("XDG_") for v in env_vars)
+
+
+@pytest.mark.parametrize("folder_kind", FOLDER_KINDS)
+def test_config2py_override_wins_on_every_platform(folder_kind, tmp_path, monkeypatch):
+    """``CONFIG2PY_<KIND>_DIR`` is the platform-neutral override.
+
+    Unlike XDG_*, it is honoured on Windows too -- which is what makes it the
+    right knob for tests and for users who need to relocate app folders.
+    """
+    target = tmp_path / folder_kind
+    monkeypatch.setenv(getattr(config2py_env_var, folder_kind), str(target))
+    rootdir = get_app_rootdir(folder_kind, ensure_exists=True)
+    assert os.path.realpath(rootdir) == os.path.realpath(str(target))

config2py/tests/test_sync_store.py

@@ -270,7 +270,14 @@ def test_store_repr():
     try:
         file_store = FileStore(temp_file)
         assert "FileStore" in repr(file_store)
-        assert temp_file in repr(file_store)
+        # The repr embeds ``repr(self.filepath)``, and pathlib's repr always
+        # spells the path with forward slashes (``PurePath.__repr__`` uses
+        # ``as_posix()``) -- so on Windows it never contains the native
+        # backslash form of ``temp_file``. Assert the *identity* of the path the
+        # store is bound to, plus the separator-free filename in the repr,
+        # rather than comparing separator-laden strings.
+        assert file_store.filepath == Path(temp_file)
+        assert Path(temp_file).name in repr(file_store)
 
         file_store_with_path = FileStore(temp_file, key_path="section")
         assert "key_path" in repr(file_store_with_path)