superqode 0.1.5__py3-none-any.whl

superqode/workspace/__init__.py

@@ -0,0 +1,75 @@
+"""
+SuperQode Workspace Module.
+
+Provides ephemeral-edit workspace with immutable repo guarantee.
+Agents can freely modify code for QA without touching the repo permanently.
+
+Features:
+- Git worktree-based isolation
+- QE session coordination with locking
+- Diff tracking for patch generation
+- Artifact management
+- Git-based snapshots for robust state tracking
+- Real-time file system watching
+"""
+
+from .manager import WorkspaceManager, WorkspaceState
+from .artifacts import ArtifactManager, ArtifactType
+from .git_guard import GitGuard, GitOperationBlocked
+from .snapshot import SnapshotManager
+from .worktree import GitWorktreeManager, WorktreeInfo, prepare_qe_worktree
+from .coordinator import QECoordinator, QELock, notify_file_change
+from .diff_tracker import DiffTracker, ChangeType, generate_patch_file
+
+# New advanced features
+from .git_snapshot import (
+    GitSnapshotManager,
+    Snapshot,
+    FileChange as SnapshotFileChange,
+    FileStatus,
+    create_git_snapshot_manager,
+)
+from .watcher import (
+    DirectoryWatcher,
+    PollingWatcher,
+    WatcherConfig,
+    FileChange as WatcherFileChange,
+    ChangeType as WatcherChangeType,
+    create_watcher,
+)
+
+__all__ = [
+    # Core managers
+    "WorkspaceManager",
+    "WorkspaceState",
+    "ArtifactManager",
+    "ArtifactType",
+    "GitGuard",
+    "GitOperationBlocked",
+    "SnapshotManager",
+    # Git worktree
+    "GitWorktreeManager",
+    "WorktreeInfo",
+    "prepare_qe_worktree",
+    # Coordination
+    "QECoordinator",
+    "QELock",
+    "notify_file_change",
+    # Diff tracking
+    "DiffTracker",
+    "ChangeType",
+    "generate_patch_file",
+    # Git-based snapshots
+    "GitSnapshotManager",
+    "Snapshot",
+    "SnapshotFileChange",
+    "FileStatus",
+    "create_git_snapshot_manager",
+    # Directory watching
+    "DirectoryWatcher",
+    "PollingWatcher",
+    "WatcherConfig",
+    "WatcherFileChange",
+    "WatcherChangeType",
+    "create_watcher",
+]

superqode/workspace/artifacts.py

@@ -0,0 +1,472 @@
+"""
+Artifact Manager for SuperQode QE Sessions.
+
+Manages preservation of QE artifacts that survive the ephemeral workspace reset:
+- Candidate fixes / patch files
+- Generated tests (unit, integration, fuzz, API, load, regression)
+- QIRs (Quality Investigation Reports)
+- Test results and evidence
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import hashlib
+
+
+class ArtifactType(Enum):
+    """Types of artifacts generated during QE."""
+
+    # Patches and fixes
+    PATCH = "patch"  # Unified diff patch file
+    SUGGESTED_FIX = "fix"  # Suggested code fix
+
+    # Generated tests
+    TEST_UNIT = "test_unit"
+    TEST_INTEGRATION = "test_integration"
+    TEST_API = "test_api"
+    TEST_CONTRACT = "test_contract"
+    TEST_FUZZ = "test_fuzz"
+    TEST_LOAD = "test_load"
+    TEST_REGRESSION = "test_regression"
+    TEST_E2E = "test_e2e"
+    TEST_SECURITY = "test_security"
+
+    # Reports
+    QR = "qr"  # Quality Report
+    COVERAGE = "coverage"  # Coverage report
+    SUMMARY = "summary"  # Session summary
+
+    # Evidence
+    LOG = "log"  # Execution logs
+    SCREENSHOT = "screenshot"  # Visual evidence
+    TRACE = "trace"  # Execution trace
+    ERROR = "error"  # Error capture
+
+
+@dataclass
+class Artifact:
+    """A single artifact from QE session."""
+
+    id: str
+    type: ArtifactType
+    name: str
+    path: Path  # Relative to artifacts dir
+    description: str = ""
+    created_at: datetime = field(default_factory=datetime.now)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    # For patches/fixes
+    original_file: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "id": self.id,
+            "type": self.type.value,
+            "name": self.name,
+            "path": str(self.path),
+            "description": self.description,
+            "created_at": self.created_at.isoformat(),
+            "metadata": self.metadata,
+            "original_file": self.original_file,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Artifact":
+        """Deserialize from dictionary."""
+        return cls(
+            id=data["id"],
+            type=ArtifactType(data["type"]),
+            name=data["name"],
+            path=Path(data["path"]),
+            description=data.get("description", ""),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            metadata=data.get("metadata", {}),
+            original_file=data.get("original_file"),
+        )
+
+
+class ArtifactManager:
+    """
+    Manages QE artifacts that persist after ephemeral workspace reset.
+
+    Directory structure:
+    .superqode/
+    └── qe-artifacts/
+        ├── manifest.json           # Index of all artifacts
+        ├── patches/                # Suggested fixes as patches
+        │   └── fix-001-user-service.patch
+        ├── generated-tests/        # Tests generated by QE
+        │   ├── unit/
+        │   ├── integration/
+        │   ├── api/
+        │   ├── fuzz/
+        │   └── ...
+        ├── qr/                    # Quality Investigation Reports
+        │   └── qr-2024-01-08-001.md
+        ├── coverage/               # Coverage reports
+        ├── logs/                   # Execution logs
+        └── evidence/               # Screenshots, traces, etc.
+    """
+
+    ARTIFACTS_DIR = "qe-artifacts"
+    MANIFEST_FILE = "manifest.json"
+
+    # Subdirectory mapping
+    TYPE_DIRS = {
+        ArtifactType.PATCH: "patches",
+        ArtifactType.SUGGESTED_FIX: "patches",
+        ArtifactType.TEST_UNIT: "generated-tests/unit",
+        ArtifactType.TEST_INTEGRATION: "generated-tests/integration",
+        ArtifactType.TEST_API: "generated-tests/api",
+        ArtifactType.TEST_CONTRACT: "generated-tests/contract",
+        ArtifactType.TEST_FUZZ: "generated-tests/fuzz",
+        ArtifactType.TEST_LOAD: "generated-tests/load",
+        ArtifactType.TEST_REGRESSION: "generated-tests/regression",
+        ArtifactType.TEST_E2E: "generated-tests/e2e",
+        ArtifactType.TEST_SECURITY: "generated-tests/security",
+        ArtifactType.QR: "qr",
+        ArtifactType.COVERAGE: "coverage",
+        ArtifactType.SUMMARY: ".",
+        ArtifactType.LOG: "logs",
+        ArtifactType.SCREENSHOT: "evidence",
+        ArtifactType.TRACE: "evidence",
+        ArtifactType.ERROR: "logs",
+    }
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root.resolve()
+        self.superqode_dir = self.project_root / ".superqode"
+        self.artifacts_dir = self.superqode_dir / self.ARTIFACTS_DIR
+        self.manifest_path = self.artifacts_dir / self.MANIFEST_FILE
+
+        self._artifacts: Dict[str, Artifact] = {}
+        self._artifact_counter = 0
+        self._session_id: Optional[str] = None
+
+    def initialize(self, session_id: str) -> None:
+        """Initialize the artifacts directory for a new session."""
+        self._session_id = session_id
+
+        # Create directory structure
+        self.artifacts_dir.mkdir(parents=True, exist_ok=True)
+
+        for subdir in set(self.TYPE_DIRS.values()):
+            if subdir != ".":
+                (self.artifacts_dir / subdir).mkdir(parents=True, exist_ok=True)
+
+        # Load existing manifest if present
+        self._load_manifest()
+
+    def _load_manifest(self) -> None:
+        """Load existing manifest file."""
+        if self.manifest_path.exists():
+            try:
+                data = json.loads(self.manifest_path.read_text())
+                for artifact_data in data.get("artifacts", []):
+                    artifact = Artifact.from_dict(artifact_data)
+                    self._artifacts[artifact.id] = artifact
+                self._artifact_counter = data.get("counter", 0)
+            except (json.JSONDecodeError, KeyError):
+                pass
+
+    def _save_manifest(self) -> None:
+        """Save manifest file."""
+        data = {
+            "session_id": self._session_id,
+            "updated_at": datetime.now().isoformat(),
+            "counter": self._artifact_counter,
+            "artifacts": [a.to_dict() for a in self._artifacts.values()],
+        }
+        self.manifest_path.write_text(json.dumps(data, indent=2))
+
+    def _generate_id(self, artifact_type: ArtifactType) -> str:
+        """Generate a unique artifact ID."""
+        self._artifact_counter += 1
+        type_prefix = artifact_type.value.replace("_", "-")
+        return f"{type_prefix}-{self._artifact_counter:03d}"
+
+    def _get_artifact_path(self, artifact_type: ArtifactType, filename: str) -> Path:
+        """Get the full path for an artifact file."""
+        subdir = self.TYPE_DIRS.get(artifact_type, "misc")
+        return self.artifacts_dir / subdir / filename
+
+    def save_patch(
+        self,
+        original_file: str,
+        original_content: str,
+        modified_content: str,
+        description: str = "",
+    ) -> Artifact:
+        """
+        Save a patch file showing changes to a source file.
+
+        Creates a unified diff patch that can be applied with `patch` or `git apply`.
+        """
+        artifact_id = self._generate_id(ArtifactType.PATCH)
+
+        # Generate unified diff
+        original_lines = original_content.splitlines(keepends=True)
+        modified_lines = modified_content.splitlines(keepends=True)
+
+        diff = difflib.unified_diff(
+            original_lines,
+            modified_lines,
+            fromfile=f"a/{original_file}",
+            tofile=f"b/{original_file}",
+        )
+        patch_content = "".join(diff)
+
+        # Save patch file
+        safe_filename = original_file.replace("/", "-").replace("\\", "-")
+        filename = f"{artifact_id}-{safe_filename}.patch"
+        artifact_path = self._get_artifact_path(ArtifactType.PATCH, filename)
+        artifact_path.write_text(patch_content)
+
+        artifact = Artifact(
+            id=artifact_id,
+            type=ArtifactType.PATCH,
+            name=filename,
+            path=artifact_path.relative_to(self.artifacts_dir),
+            description=description or f"Suggested fix for {original_file}",
+            original_file=original_file,
+            metadata={
+                "lines_added": sum(
+                    1 for line in patch_content.splitlines() if line.startswith("+")
+                ),
+                "lines_removed": sum(
+                    1 for line in patch_content.splitlines() if line.startswith("-")
+                ),
+            },
+        )
+
+        self._artifacts[artifact_id] = artifact
+        self._save_manifest()
+
+        return artifact
+
+    def save_generated_test(
+        self,
+        test_type: ArtifactType,
+        filename: str,
+        content: str,
+        description: str = "",
+        target_file: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Artifact:
+        """
+        Save a generated test file.
+
+        Args:
+            test_type: Type of test (TEST_UNIT, TEST_INTEGRATION, etc.)
+            filename: Name for the test file
+            content: Test file content
+            description: Description of what the test covers
+            target_file: Source file the test is for
+            metadata: Additional metadata
+        """
+        if not test_type.value.startswith("test_"):
+            raise ValueError(f"Invalid test type: {test_type}")
+
+        artifact_id = self._generate_id(test_type)
+
+        # Save test file
+        artifact_path = self._get_artifact_path(test_type, filename)
+        artifact_path.write_text(content)
+
+        artifact = Artifact(
+            id=artifact_id,
+            type=test_type,
+            name=filename,
+            path=artifact_path.relative_to(self.artifacts_dir),
+            description=description,
+            original_file=target_file,
+            metadata=metadata or {},
+        )
+
+        self._artifacts[artifact_id] = artifact
+        self._save_manifest()
+
+        return artifact
+
+    def save_qir(
+        self,
+        content: str,
+        session_id: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Artifact:
+        """Save a Quality Investigation Report."""
+        artifact_id = self._generate_id(ArtifactType.QR)
+        timestamp = datetime.now().strftime("%Y-%m-%d")
+        filename = f"qr-{timestamp}-{session_id[:8]}.md"
+
+        artifact_path = self._get_artifact_path(ArtifactType.QR, filename)
+        artifact_path.write_text(content)
+
+        # Also save JSON version for CI
+        json_filename = filename.replace(".md", ".json")
+        json_path = self._get_artifact_path(ArtifactType.QR, json_filename)
+        json_path.write_text(json.dumps(metadata or {}, indent=2))
+
+        artifact = Artifact(
+            id=artifact_id,
+            type=ArtifactType.QR,
+            name=filename,
+            path=artifact_path.relative_to(self.artifacts_dir),
+            description="Quality Investigation Report",
+            metadata=metadata or {},
+        )
+
+        self._artifacts[artifact_id] = artifact
+        self._save_manifest()
+
+        return artifact
+
+    def save_log(
+        self,
+        name: str,
+        content: str,
+        log_type: str = "execution",
+    ) -> Artifact:
+        """Save an execution log."""
+        artifact_id = self._generate_id(ArtifactType.LOG)
+        timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        filename = f"{log_type}-{timestamp}.log"
+
+        artifact_path = self._get_artifact_path(ArtifactType.LOG, filename)
+        artifact_path.write_text(content)
+
+        artifact = Artifact(
+            id=artifact_id,
+            type=ArtifactType.LOG,
+            name=filename,
+            path=artifact_path.relative_to(self.artifacts_dir),
+            description=name,
+            metadata={"log_type": log_type},
+        )
+
+        self._artifacts[artifact_id] = artifact
+        self._save_manifest()
+
+        return artifact
+
+    def save_file(
+        self,
+        artifact_type: ArtifactType,
+        filename: str,
+        content: str | bytes,
+        description: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Artifact:
+        """Save a generic artifact file."""
+        artifact_id = self._generate_id(artifact_type)
+        artifact_path = self._get_artifact_path(artifact_type, filename)
+
+        if isinstance(content, bytes):
+            artifact_path.write_bytes(content)
+        else:
+            artifact_path.write_text(content)
+
+        artifact = Artifact(
+            id=artifact_id,
+            type=artifact_type,
+            name=filename,
+            path=artifact_path.relative_to(self.artifacts_dir),
+            description=description,
+            metadata=metadata or {},
+        )
+
+        self._artifacts[artifact_id] = artifact
+        self._save_manifest()
+
+        return artifact
+
+    def get_artifact(self, artifact_id: str) -> Optional[Artifact]:
+        """Get an artifact by ID."""
+        return self._artifacts.get(artifact_id)
+
+    def get_artifacts_by_type(self, artifact_type: ArtifactType) -> List[Artifact]:
+        """Get all artifacts of a specific type."""
+        return [a for a in self._artifacts.values() if a.type == artifact_type]
+
+    def get_all_artifacts(self) -> List[Artifact]:
+        """Get all artifacts."""
+        return list(self._artifacts.values())
+
+    def get_artifact_content(self, artifact_id: str) -> Optional[str]:
+        """Get the content of an artifact."""
+        artifact = self._artifacts.get(artifact_id)
+        if not artifact:
+            return None
+
+        full_path = self.artifacts_dir / artifact.path
+        if full_path.exists():
+            return full_path.read_text()
+        return None
+
+    def list_patches(self) -> List[Artifact]:
+        """List all patch artifacts."""
+        return self.get_artifacts_by_type(ArtifactType.PATCH)
+
+    def list_generated_tests(self) -> List[Artifact]:
+        """List all generated test artifacts."""
+        test_types = [t for t in ArtifactType if t.value.startswith("test_")]
+        result = []
+        for t in test_types:
+            result.extend(self.get_artifacts_by_type(t))
+        return result
+
+    def list_qirs(self) -> List[Artifact]:
+        """List all QIR artifacts."""
+        return self.get_artifacts_by_type(ArtifactType.QR)
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Get a summary of all artifacts."""
+        summary = {
+            "total_artifacts": len(self._artifacts),
+            "by_type": {},
+            "patches": len(self.list_patches()),
+            "generated_tests": len(self.list_generated_tests()),
+            "qirs": len(self.list_qirs()),
+        }
+
+        for artifact_type in ArtifactType:
+            count = len(self.get_artifacts_by_type(artifact_type))
+            if count > 0:
+                summary["by_type"][artifact_type.value] = count
+
+        return summary
+
+    def cleanup(self, keep_qirs: bool = True) -> int:
+        """
+        Clean up artifact directory.
+
+        Args:
+            keep_qirs: If True, keep QIR files
+
+        Returns:
+            Number of files removed
+        """
+        removed = 0
+
+        for artifact_id, artifact in list(self._artifacts.items()):
+            if keep_qirs and artifact.type == ArtifactType.QR:
+                continue
+
+            full_path = self.artifacts_dir / artifact.path
+            if full_path.exists():
+                full_path.unlink()
+                removed += 1
+
+            del self._artifacts[artifact_id]
+
+        self._save_manifest()
+        return removed