codeui-python 0.1.0__py3-none-any.whl

codeui/core/ir.py

@@ -0,0 +1,218 @@
+"""Intermediate Representation (IR) data structures for codeui."""
+from dataclasses import dataclass, asdict
+from enum import Enum
+from typing import Any, Dict
+
+class StrEnum(str, Enum):
+    """String enum for Python 3.10+ compatibility.
+    Example:
+        >>> class Color(StrEnum):
+        ...     RED = "red"
+        >>> str(Color.RED)
+        'red'
+    """
+    def __str__(self) -> str:
+        return str(self.value)
+
+class Visibility(StrEnum):
+    """Symbol visibility scope."""
+    PUBLIC = "public"
+    PROTECTED = "protected"
+    PRIVATE = "private"
+    INTERNAL = "internal"
+
+class LayerKind(StrEnum):
+    """Architectural classification layer for files and modules.
+    Example:
+        >>> str(LayerKind.FRONTEND)
+        'frontend'
+    """
+    ENTRY = "entry"
+    FRONTEND = "frontend"
+    BACKEND = "backend"
+    HOOKS = "hooks"
+    SHARED = "shared"
+    TEST = "test"
+    CONFIG = "config"
+    OTHER = "other"
+
+@dataclass(frozen=True, slots=True)
+class FileClassification:
+    """Architectural classification for a source file.
+    Example:
+        >>> c = FileClassification(LayerKind.FRONTEND, "auth", "components")
+        >>> str(c.layer)
+        'frontend'
+    """
+    layer: LayerKind
+    feature: str
+    module: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert classification to dictionary.
+        Example:
+            >>> c = FileClassification(LayerKind.BACKEND, "api", "server")
+            >>> c.to_dict()["layer"]
+            'backend'
+        """
+        return {
+            "layer": str(self.layer),
+            "feature": self.feature,
+            "module": self.module,
+        }
+
+class SymbolKind(StrEnum):
+    """Kind of programming symbol."""
+    FILE = "file"
+    MODULE = "module"
+    NAMESPACE = "namespace"
+    CLASS = "class"
+    INTERFACE = "interface"
+    STRUCT = "struct"
+    ENUM = "enum"
+    FUNCTION = "function"
+    METHOD = "method"
+    PROPERTY = "property"
+    VARIABLE = "variable"
+    CONSTANT = "constant"
+    TYPE_ALIAS = "type_alias"
+    IMPORT = "import"
+    EXPORT = "export"
+
+@dataclass(frozen=True, slots=True)
+class Location:
+    """Source code range location.
+    Example:
+        >>> loc = Location("app.py", 1, 0, 10, 5)
+        >>> loc.file_id
+        'app.py'
+    """
+    file_id: str
+    start_line: int
+    start_col: int
+    end_line: int
+    end_col: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert Location to dictionary.
+        Example:
+            >>> loc = Location("a.py", 1, 0, 1, 10)
+            >>> loc.to_dict()["file_id"]
+            'a.py'
+        """
+        return asdict(self)
+
+@dataclass(frozen=True, slots=True)
+class Symbol:
+    """Code symbol node in graph.
+    Example:
+        >>> loc = Location("a.py", 1, 0, 2, 0)
+        >>> sym = Symbol("s1", "foo", "a.foo", SymbolKind.FUNCTION, "python", loc, None, "def foo():", Visibility.PUBLIC, (), "hash1")
+        >>> sym.name
+        'foo'
+    """
+    id: str
+    name: str
+    qualified_name: str
+    kind: SymbolKind
+    language: str
+    location: Location
+    parent_id: str | None
+    signature: str | None
+    visibility: Visibility
+    modifiers: tuple[str, ...]
+    content_hash: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert Symbol to dictionary representation.
+        Example:
+            >>> loc = Location("a.py", 1, 0, 2, 0)
+            >>> sym = Symbol("s1", "foo", "a.foo", SymbolKind.FUNCTION, "python", loc, None, "def foo():", Visibility.PUBLIC, (), "hash1")
+            >>> sym.to_dict()["name"]
+            'foo'
+        """
+        d = asdict(self)
+        d["kind"] = str(self.kind)
+        d["visibility"] = str(self.visibility)
+        return d
+
+class EdgeKind(StrEnum):
+    """Kinds of directed relationship edges."""
+    CONTAINS = "contains"
+    IMPORTS = "imports"
+    EXPORTS = "exports"
+    CALLS = "calls"
+    REFERENCES = "references"
+    INHERITS = "inherits"
+    IMPLEMENTS = "implements"
+    OVERRIDES = "overrides"
+    READS = "reads"
+    WRITES = "writes"
+    RETURNS = "returns"
+    INSTANTIATES = "instantiates"
+    DEPENDS_ON = "depends_on"
+    TESTS = "tests"
+    DOCUMENTS = "documents"
+    DUPLICATES = "duplicates"
+
+@dataclass(frozen=True, slots=True)
+class Edge:
+    """Directed edge between two symbols or nodes.
+    Example:
+        >>> edge = Edge("s1", "s2", EdgeKind.CALLS, 1.0, 1.0, None)
+        >>> edge.kind
+        <EdgeKind.CALLS: 'calls'>
+    """
+    source_id: str
+    target_id: str
+    kind: EdgeKind
+    weight: float
+    confidence: float
+    location: Location | None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert Edge to dictionary representation.
+        Example:
+            >>> edge = Edge("s1", "s2", EdgeKind.CALLS, 1.0, 1.0, None)
+            >>> edge.to_dict()["kind"]
+            'calls'
+        """
+        d = asdict(self)
+        d["kind"] = str(self.kind)
+        return d
+
+class Severity(StrEnum):
+    """Finding severity level."""
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """Defect finding report.
+    Example:
+        >>> loc = Location("a.py", 1, 0, 1, 10)
+        >>> f = Finding("f1", "undefined_symbol", "Symbol x undefined", Severity.ERROR, loc, "s1", "Import x or define it", 1.0)
+        >>> f.rule_id
+        'undefined_symbol'
+    """
+    id: str
+    rule_id: str
+    message: str
+    severity: Severity
+    location: Location
+    symbol_id: str | None
+    fix_hint: str | None
+    confidence: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert Finding to dictionary.
+        Example:
+            >>> loc = Location("a.py", 1, 0, 1, 10)
+            >>> f = Finding("f1", "undefined_symbol", "Symbol x undefined", Severity.ERROR, loc, "s1", "Import x", 1.0)
+            >>> f.to_dict()["severity"]
+            'error'
+        """
+        d = asdict(self)
+        d["severity"] = str(self.severity)
+        return d

codeui/core/override.py

@@ -0,0 +1,230 @@
+"""In-memory OverrideStore for non-destructive code editing."""
+import difflib
+import hashlib
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional
+from codeui.core.ir import StrEnum
+from codeui.errors import OverrideConflictError
+
+class OverrideKind(StrEnum):
+    """Kind of override modification."""
+    RENAME_SYMBOL = "rename_symbol"
+    RETYPE_SYMBOL = "retype_symbol"
+    REPLACE_SYMBOL_BODY = "replace_symbol_body"
+    REPLACE_FILE = "replace_file"
+    TOGGLE_EDGE = "toggle_edge"
+    TRIAGE_FINDING = "triage_finding"
+
+@dataclass
+class Override:
+    """Represents an active override on a target symbol, file, or edge.
+    Example:
+        >>> o = Override("sym_1", OverrideKind.RENAME_SYMBOL, "hash123", "new_name", "user", "2026-01-01T00:00:00Z")
+        >>> o.target_id
+        'sym_1'
+    """
+    target_id: str
+    kind: OverrideKind
+    original_hash: str
+    new_value: Any
+    author: str
+    created_at: str
+    note: str | None = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert override to serializable dict.
+        Example:
+            >>> o = Override("sym_1", OverrideKind.RENAME_SYMBOL, "hash123", "new_name", "user", "2026-01-01T00:00:00Z")
+            >>> o.to_dict()["kind"]
+            'rename_symbol'
+        """
+        d = asdict(self)
+        d["kind"] = str(self.kind)
+        return d
+
+@dataclass(frozen=True)
+class Conflict:
+    """Override conflict descriptor.
+    Example:
+        >>> c = Conflict("src/main.py", "hash1", "hash2", "File on disk changed")
+        >>> c.file_path
+        'src/main.py'
+    """
+    file_path: str
+    expected_hash: str
+    actual_hash: str
+    reason: str
+
+class OverrideStore:
+    """Manages active overrides without writing to disk.
+    Example:
+        >>> store = OverrideStore()
+        >>> o = Override("file.py", OverrideKind.REPLACE_FILE, "h1", "print('hello')", "agent", "2026-01-01")
+        >>> store.set(o)
+        >>> store.get("file.py").new_value
+        "print('hello')"
+    """
+    def __init__(self) -> None:
+        self._overrides: Dict[str, Override] = {}
+        self._file_contents: Dict[str, str] = {}
+        self._original_file_contents: Dict[str, str] = {}
+
+    def get(self, target_id: str) -> Override | None:
+        """Retrieve active override for target ID.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.get("nonexistent") is None
+            True
+        """
+        return self._overrides.get(target_id)
+
+    def has_override(self, target_id: str) -> bool:
+        """Check if target has an active override.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.has_override("test.py")
+            False
+        """
+        return target_id in self._overrides
+
+    def set(self, override: Override) -> None:
+        """Set or update an override.
+        Example:
+            >>> store = OverrideStore()
+            >>> o = Override("t1", OverrideKind.RENAME_SYMBOL, "h1", "new", "user", "2026")
+            >>> store.set(o)
+            >>> store.get("t1").new_value
+            'new'
+        """
+        self._overrides[override.target_id] = override
+
+    def set_file_override(self, file_path: str, original_content: str, new_content: str, author: str = "user", note: str | None = None) -> None:
+        """Register full file replacement override.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a.py", "x = 1", "x = 2")
+            >>> store.get_file_content("a.py")
+            'x = 2'
+        """
+        now = datetime.now(timezone.utc).isoformat()
+        self._original_file_contents[file_path] = original_content
+        self._file_contents[file_path] = new_content
+        override = Override(
+            target_id=file_path,
+            kind=OverrideKind.REPLACE_FILE,
+            original_hash=hashlib.sha256(original_content.encode("utf-8")).hexdigest(),
+            new_value=new_content,
+            author=author,
+            created_at=now,
+            note=note,
+        )
+        self._overrides[file_path] = override
+
+    def get_file_content(self, file_path: str) -> str | None:
+        """Return overridden file content if present.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a.py", "old", "new")
+            >>> store.get_file_content("a.py")
+            'new'
+        """
+        return self._file_contents.get(file_path)
+
+    def revert(self, target_id: str) -> None:
+        """Revert override for specific target ID or file path across all key variations.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a/b.py", "old", "new")
+            >>> store.revert("b.py")
+            >>> store.get("a/b.py") is None
+            True
+        """
+        if not target_id:
+            return
+        clean_target = target_id.split("::")[0].replace("module::", "").replace("\\", "/").strip().lstrip("./")
+        keys_to_remove = set()
+        for k in list(self._overrides.keys()) + list(self._file_contents.keys()):
+            k_clean = k.split("::")[0].replace("module::", "").replace("\\", "/").strip().lstrip("./")
+            if k == target_id or k_clean == clean_target or k_clean.endswith("/" + clean_target) or clean_target.endswith("/" + k_clean):
+                keys_to_remove.add(k)
+        for k in keys_to_remove:
+            self._overrides.pop(k, None)
+            self._file_contents.pop(k, None)
+            self._original_file_contents.pop(k, None)
+
+    def revert_all(self) -> None:
+        """Revert all overrides in the store.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a.py", "old", "new")
+            >>> store.revert_all()
+            >>> len(list(store.list()))
+            0
+        """
+        self._overrides.clear()
+        self._file_contents.clear()
+
+    def list(self) -> Iterable[Override]:
+        """List all current overrides in deterministic order.
+        Example:
+            >>> store = OverrideStore()
+            >>> list(store.list())
+            []
+        """
+        return sorted(self._overrides.values(), key=lambda o: o.target_id)
+
+    def to_patch_files(self) -> Dict[str, str]:
+        """Export map of path to modified file content.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a.py", "old", "new")
+            >>> store.to_patch_files()["a.py"]
+            'new'
+        """
+        return dict(self._file_contents)
+
+    def to_diff(self) -> str:
+        """Generate unified diff string across all overridden files.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a.py", "old", "new")
+            >>> '--- a/a.py' in store.to_diff()
+            True
+        """
+        diff_chunks: List[str] = []
+        for file_path in sorted(self._file_contents.keys()):
+            orig = self._original_file_contents.get(file_path, "").splitlines(keepends=True)
+            mod = self._file_contents[file_path].splitlines(keepends=True)
+            lines = list(difflib.unified_diff(
+                orig,
+                mod,
+                fromfile=f"a/{file_path}",
+                tofile=f"b/{file_path}",
+            ))
+            if lines:
+                diff_chunks.extend(lines)
+        return "".join(diff_chunks)
+
+    def check_conflicts(self, disk_state: Dict[str, str]) -> List[Conflict]:
+        """Check for conflicts between overrides and current disk files.
+        Example:
+            >>> store = OverrideStore()
+            >>> store.set_file_override("a.py", "v1", "v2")
+            >>> conflicts = store.check_conflicts({"a.py": "v1_changed"})
+            >>> len(conflicts)
+            1
+        """
+        conflicts: List[Conflict] = []
+        for file_path, override in self._overrides.items():
+            if override.kind == OverrideKind.REPLACE_FILE and file_path in disk_state:
+                current_disk_content = disk_state[file_path]
+                expected_original = self._original_file_contents.get(file_path, "")
+                if current_disk_content != expected_original:
+                    conflicts.append(Conflict(
+                        file_path=file_path,
+                        expected_hash=override.original_hash,
+                        actual_hash=hashlib.sha256(current_disk_content.encode("utf-8")).hexdigest(),
+                        reason="File content on disk changed since override creation",
+                    ))
+        return conflicts

codeui/core/repo.py

@@ -0,0 +1,85 @@
+"""Git repository cloning and remote URL resolution helper."""
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional, Tuple
+from codeui.errors import RepositoryCloneError
+
+DEFAULT_REPOSITORY_URL = "https://github.com/AAlsubari/codeUI"
+
+def get_library_repo_url() -> str:
+    """Retrieve the official GitHub repository URL for the codeui library.
+    Example:
+        >>> get_library_repo_url()
+        'https://github.com/AAlsubari/codeUI'
+    """
+    return os.environ.get("CODEUI_GITHUB_REPO_URL", DEFAULT_REPOSITORY_URL)
+
+def is_git_url(target: str) -> bool:
+    """Check if target string represents a remote Git repository URL.
+    Example:
+        >>> is_git_url("https://github.com/psf/black")
+        True
+        >>> is_git_url("git@github.com:psf/black.git")
+        True
+        >>> is_git_url("./local/path")
+        False
+    """
+    if not isinstance(target, str):
+        return False
+    t = target.strip()
+    if t.startswith(("http://", "https://", "git@", "git://", "ssh://")):
+        return True
+    if t.startswith("github.com/") or t.startswith("gitlab.com/") or t.startswith("bitbucket.org/"):
+        return True
+    if t.endswith(".git") and (":" in t or "/" in t):
+        return True
+    return False
+
+def clone_git_repo(repo_url: str, dest_dir: Optional[Path] = None) -> Tuple[Path, Optional[tempfile.TemporaryDirectory]]:
+    """Clone a remote Git repository with depth 1 into destination or temporary directory.
+    Example:
+        >>> is_git_url("https://github.com/example/repo")
+        True
+    """
+    git_bin = shutil.which("git")
+    if not git_bin:
+        raise RepositoryCloneError(repo_url, "Git executable not found in system PATH")
+
+    url = repo_url.strip()
+    if url.startswith("github.com/"):
+        url = f"https://{url}"
+    elif url.startswith("gitlab.com/"):
+        url = f"https://{url}"
+    elif url.startswith("bitbucket.org/"):
+        url = f"https://{url}"
+
+    temp_obj: Optional[tempfile.TemporaryDirectory] = None
+    if dest_dir is None:
+        temp_obj = tempfile.TemporaryDirectory(prefix="codeui_repo_")
+        target_path = Path(temp_obj.name).resolve()
+    else:
+        target_path = dest_dir.resolve()
+        target_path.mkdir(parents=True, exist_ok=True)
+
+    cmd = [git_bin, "clone", "--depth", "1", "--quiet", url, str(target_path)]
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+        if res.returncode != 0:
+            if temp_obj:
+                temp_obj.cleanup()
+            raise RepositoryCloneError(repo_url, res.stderr.strip() or f"Git clone failed with code {res.returncode}")
+    except subprocess.TimeoutExpired:
+        if temp_obj:
+            temp_obj.cleanup()
+        raise RepositoryCloneError(repo_url, "Git clone timed out after 120s")
+    except Exception as e:
+        if temp_obj:
+            temp_obj.cleanup()
+        if isinstance(e, RepositoryCloneError):
+            raise
+        raise RepositoryCloneError(repo_url, str(e))
+
+    return target_path, temp_obj