test_workspace.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_core/test_workspace.py
 
"""
Purpose
-------
Unit tests for ``oct.core.workspace`` (F1, leanest first cut). The
loader validates the manifest schema and resolves subproject paths
relative to the workspace root; the discovery helper walks upward
to find the manifest.
 
Responsibilities
----------------
- Manifest validation: each malformed input produces a
  :class:`WorkspaceError` with a useful message.
- Manifest happy path: valid input produces the expected
  :class:`Workspace` with absolute, root-resolved subproject paths.
- ``find_workspace_root`` walks upward until it finds the manifest,
  returning ``None`` when none exists.
 
Diagnostics
-----------
Domain: CORE-TESTS
Levels:
    L2 -- test lifecycle
    L3 -- assertion details
"""
 
import json
from pathlib import Path
 
import pytest
 
from oct.core.workspace import (
    Subproject,
    Workspace,
    WorkspaceError,
    assign_to_subproject,
    find_workspace_root,
    load_workspace,
    matches_workspace_files,
)
 
 
# =====================================================================
# Helpers
# =====================================================================
 
 
def _make_manifest(root: Path, payload: dict) -> Path:
    """Drop a workspace manifest at *root* with the given payload."""
    root.mkdir(parents=True, exist_ok=True)
    path = root / ".option_c_workspace.json"
    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
    return path
 
 
# =====================================================================
# Happy path
# =====================================================================
 
 
class TestLoadWorkspaceHappy:
 
    def test_minimal_manifest(self, tmp_path: Path) -> None:
        (tmp_path / "a").mkdir()
        (tmp_path / "b").mkdir()
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "Demo",
            "subprojects": [
                {"path": "a", "name": "a"},
                {"path": "b", "name": "b", "profile": "strict"},
            ],
        })
        ws = load_workspace(tmp_path)
        assert isinstance(ws, Workspace)
        assert ws.name == "Demo"
        assert ws.root == tmp_path.resolve()
        assert len(ws.subprojects) == 2
        assert ws.subprojects[0].path == (tmp_path / "a").resolve()
        assert ws.subprojects[1].profile == "strict"
 
    def test_no_subprojects_is_valid(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "Empty",
            "subprojects": [],
        })
        ws = load_workspace(tmp_path)
        assert ws.subprojects == ()
 
    def test_subprojects_field_optional(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "Empty2",
        })
        ws = load_workspace(tmp_path)
        assert ws.subprojects == ()
 
 
# =====================================================================
# Validation failures
# =====================================================================
 
 
class TestLoadWorkspaceErrors:
 
    def test_missing_manifest(self, tmp_path: Path) -> None:
        with pytest.raises(WorkspaceError, match="not found"):
            load_workspace(tmp_path)
 
    def test_malformed_json(self, tmp_path: Path) -> None:
        (tmp_path / ".option_c_workspace.json").write_text(
            "not json", encoding="utf-8",
        )
        with pytest.raises(WorkspaceError, match="failed to read"):
            load_workspace(tmp_path)
 
    def test_top_level_not_object(self, tmp_path: Path) -> None:
        (tmp_path / ".option_c_workspace.json").write_text(
            "[]", encoding="utf-8",
        )
        with pytest.raises(WorkspaceError, match="must be a JSON object"):
            load_workspace(tmp_path)
 
    def test_wrong_version(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "9.9",
            "name": "X",
        })
        with pytest.raises(WorkspaceError, match="unsupported"):
            load_workspace(tmp_path)
 
    def test_empty_name(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "",
        })
        with pytest.raises(WorkspaceError, match="non-empty string"):
            load_workspace(tmp_path)
 
    def test_subproject_absolute_path_rejected(
        self, tmp_path: Path,
    ) -> None:
        # Use a real absolute path that's properly anchored on the
        # current platform (drive letter on Windows, "/" on Unix).
        abs_path_raw = str((tmp_path / "abs").resolve())
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "X",
            "subprojects": [{"path": abs_path_raw, "name": "abs"}],
        })
        with pytest.raises(WorkspaceError, match="absolute path"):
            load_workspace(tmp_path)
 
    def test_subproject_path_escape_rejected(
        self, tmp_path: Path,
    ) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "X",
            "subprojects": [{"path": "../escape", "name": "out"}],
        })
        with pytest.raises(WorkspaceError, match="escapes the workspace"):
            load_workspace(tmp_path)
 
    def test_subproject_duplicate_path_rejected(
        self, tmp_path: Path,
    ) -> None:
        (tmp_path / "a").mkdir()
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "X",
            "subprojects": [
                {"path": "a", "name": "a"},
                {"path": "a", "name": "a-dup"},
            ],
        })
        with pytest.raises(WorkspaceError, match="duplicate"):
            load_workspace(tmp_path)
 
    def test_subproject_invalid_profile(self, tmp_path: Path) -> None:
        (tmp_path / "a").mkdir()
        _make_manifest(tmp_path, {
            "version": "1.0",
            "name": "X",
            "subprojects": [
                {"path": "a", "name": "a", "profile": "extreme"},
            ],
        })
        with pytest.raises(WorkspaceError, match="profile"):
            load_workspace(tmp_path)
 
 
# =====================================================================
# find_workspace_root
# =====================================================================
 
 
class TestFindWorkspaceRoot:
 
    def test_finds_at_start(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
        })
        result = find_workspace_root(tmp_path)
        assert result == tmp_path.resolve()
 
    def test_finds_at_parent(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
        })
        nested = tmp_path / "a" / "b" / "c"
        nested.mkdir(parents=True)
        result = find_workspace_root(nested)
        assert result == tmp_path.resolve()
 
    def test_returns_none_when_absent(self, tmp_path: Path) -> None:
        nested = tmp_path / "deep"
        nested.mkdir()
        # No manifest anywhere along the chain (within tmp_path scope).
        assert find_workspace_root(nested) is None or \
            find_workspace_root(nested).is_relative_to(tmp_path) is False
 
 
# =====================================================================
# F1 fan-out: workspace_profile / workspace_files / ignore_at_workspace_scope
# =====================================================================
 
 
class TestWorkspaceProfileField:
 
    def test_default_when_absent(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
        })
        ws = load_workspace(tmp_path)
        assert ws.workspace_profile == "compact"
 
    def test_explicit_strict(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_profile": "strict",
        })
        ws = load_workspace(tmp_path)
        assert ws.workspace_profile == "strict"
 
    def test_invalid_value_rejected(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_profile": "extreme",
        })
        with pytest.raises(WorkspaceError, match="workspace_profile"):
            load_workspace(tmp_path)
 
 
class TestWorkspaceFilesField:
 
    def test_default_empty(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
        })
        ws = load_workspace(tmp_path)
        assert ws.workspace_files == ()
 
    def test_happy_path(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_files": [
                "CLAUDE.md", ".github/**", "docs/**",
            ],
        })
        ws = load_workspace(tmp_path)
        assert ws.workspace_files == (
            "CLAUDE.md", ".github/**", "docs/**",
        )
 
    def test_must_be_list(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_files": "CLAUDE.md",  # not a list
        })
        with pytest.raises(WorkspaceError, match="must be a list"):
            load_workspace(tmp_path)
 
    def test_negation_pattern_rejected(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_files": ["!CLAUDE.md"],
        })
        with pytest.raises(WorkspaceError, match="negation"):
            load_workspace(tmp_path)
 
    def test_absolute_pattern_rejected(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_files": ["/abs/path"],
        })
        with pytest.raises(WorkspaceError, match="absolute"):
            load_workspace(tmp_path)
 
    def test_unsafe_chars_rejected(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "workspace_files": ["bad pattern with spaces"],
        })
        with pytest.raises(WorkspaceError, match="safe set"):
            load_workspace(tmp_path)
 
 
class TestIgnoreAtWorkspaceScopeField:
 
    def test_default_empty(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
        })
        ws = load_workspace(tmp_path)
        assert ws.ignore_at_workspace_scope == ()
 
    def test_happy_path(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "ignore_at_workspace_scope": [
                ".claude/settings.local.json",
                ".claude/worktrees/**",
            ],
        })
        ws = load_workspace(tmp_path)
        assert ws.ignore_at_workspace_scope == (
            ".claude/settings.local.json",
            ".claude/worktrees/**",
        )
 
    def test_must_be_list(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "ignore_at_workspace_scope": "*.tmp",
        })
        with pytest.raises(WorkspaceError, match="must be a list"):
            load_workspace(tmp_path)
 
    def test_invalid_pattern_rejected(self, tmp_path: Path) -> None:
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "ignore_at_workspace_scope": ["!negate"],
        })
        with pytest.raises(WorkspaceError, match="negation"):
            load_workspace(tmp_path)
 
 
class TestSubprojectsByName:
 
    def test_lookup_index(self, tmp_path: Path) -> None:
        (tmp_path / "a").mkdir()
        (tmp_path / "b").mkdir()
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "subprojects": [
                {"path": "a", "name": "alpha"},
                {"path": "b", "name": "beta", "profile": "strict"},
            ],
        })
        ws = load_workspace(tmp_path)
        idx = ws.subprojects_by_name
        assert set(idx.keys()) == {"alpha", "beta"}
        assert idx["beta"].profile == "strict"
 
 
# =====================================================================
# matches_workspace_files
# =====================================================================
 
 
class TestMatchesWorkspaceFiles:
 
    def test_empty_patterns_returns_false(self) -> None:
        assert matches_workspace_files("CLAUDE.md", ()) is False
 
    def test_exact_match(self) -> None:
        assert matches_workspace_files(
            "CLAUDE.md", ("CLAUDE.md",),
        ) is True
        assert matches_workspace_files(
            "OTHER.md", ("CLAUDE.md",),
        ) is False
 
    def test_single_star_within_segment(self) -> None:
        assert matches_workspace_files("foo.py", ("*.py",)) is True
        # ``*`` does NOT cross segment boundaries.
        assert matches_workspace_files(
            "src/foo.py", ("*.py",),
        ) is False
 
    def test_double_star_crosses_segments(self) -> None:
        assert matches_workspace_files(
            "src/foo.py", ("**/*.py",),
        ) is True
        assert matches_workspace_files(
            "a/b/c.py", ("**/*.py",),
        ) is True
 
    def test_dir_prefix_with_double_star(self) -> None:
        assert matches_workspace_files(
            "docs/README.md", ("docs/**",),
        ) is True
        assert matches_workspace_files(
            "docs/sub/file.md", ("docs/**",),
        ) is True
        assert matches_workspace_files(
            "src/file.md", ("docs/**",),
        ) is False
 
    def test_question_mark(self) -> None:
        assert matches_workspace_files(
            "a.txt", ("?.txt",),
        ) is True
        assert matches_workspace_files(
            "ab.txt", ("?.txt",),
        ) is False
 
    def test_any_of_multiple_patterns(self) -> None:
        patterns = ("CLAUDE.md", ".github/**", "docs/**")
        assert matches_workspace_files("CLAUDE.md", patterns) is True
        assert matches_workspace_files(".github/CI.yml", patterns) is True
        assert matches_workspace_files("docs/foo.md", patterns) is True
        assert matches_workspace_files("src/foo.py", patterns) is False
 
 
# =====================================================================
# assign_to_subproject
# =====================================================================
 
 
class TestAssignToSubproject:
 
    def test_file_inside_subproject(self, tmp_path: Path) -> None:
        (tmp_path / "a").mkdir()
        (tmp_path / "a" / "src").mkdir()
        (tmp_path / "a" / "src" / "foo.py").write_text(
            "x = 1\n", encoding="utf-8",
        )
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "subprojects": [{"path": "a", "name": "alpha"}],
        })
        ws = load_workspace(tmp_path)
        sp = assign_to_subproject(
            tmp_path / "a" / "src" / "foo.py", ws,
        )
        assert sp is not None
        assert sp.name == "alpha"
 
    def test_file_outside_any_subproject_returns_none(
        self, tmp_path: Path,
    ) -> None:
        (tmp_path / "a").mkdir()
        (tmp_path / "CLAUDE.md").write_text("x", encoding="utf-8")
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "subprojects": [{"path": "a", "name": "alpha"}],
        })
        ws = load_workspace(tmp_path)
        sp = assign_to_subproject(tmp_path / "CLAUDE.md", ws)
        assert sp is None
 
    def test_longest_prefix_wins_for_nested(self, tmp_path: Path) -> None:
        # ``a`` and ``a/b`` are both subprojects (rare nested case).
        # A file at ``a/b/foo.py`` must resolve to ``a/b``, not ``a``.
        (tmp_path / "a" / "b").mkdir(parents=True)
        (tmp_path / "a" / "b" / "foo.py").write_text(
            "x", encoding="utf-8",
        )
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
            "subprojects": [
                {"path": "a", "name": "outer"},
                {"path": "a/b", "name": "inner"},
            ],
        })
        ws = load_workspace(tmp_path)
        sp = assign_to_subproject(
            tmp_path / "a" / "b" / "foo.py", ws,
        )
        assert sp is not None
        assert sp.name == "inner"
 
    def test_empty_subprojects_returns_none(self, tmp_path: Path) -> None:
        (tmp_path / "x.py").write_text("x", encoding="utf-8")
        _make_manifest(tmp_path, {
            "version": "1.0", "name": "X",
        })
        ws = load_workspace(tmp_path)
        assert assign_to_subproject(tmp_path / "x.py", ws) is None