moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/tag_system/atomic_ops.py

@@ -0,0 +1,117 @@
+"""Atomic file operations for TAG System.
+
+Provides safe file write operations with atomic semantics
+to prevent race conditions and data corruption.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def atomic_write_text(
+    file_path: Path | str,
+    content: str,
+    encoding: str = "utf-8",
+    make_dirs: bool = True,
+) -> bool:
+    """Atomically write text content to a file.
+
+    Uses write-to-temp-then-rename pattern to prevent race conditions
+    and partial writes from corrupting data.
+
+    Args:
+        file_path: Path to the file
+        content: Content to write
+        encoding: File encoding (default: utf-8)
+        make_dirs: Create parent directories if needed (default: True)
+
+    Returns:
+        True if write succeeded, False otherwise
+    """
+    path = Path(file_path)
+
+    if make_dirs:
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Write to temporary file first
+        fd, temp_path = tempfile.mkstemp(dir=path.parent, prefix=".tmp_", suffix=path.suffix or ".tmp")
+        try:
+            # Write content to temp file
+            with os.fdopen(fd, "w", encoding=encoding) as f:
+                f.write(content)
+
+            # Atomic rename (overwrites target if exists)
+            os.replace(temp_path, path)
+            return True
+        except Exception:
+            # Clean up temp file on error
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+            return False
+    except (OSError, ValueError):
+        return False
+
+
+def atomic_write_json(
+    file_path: Path | str,
+    data: Any,
+    indent: int = 2,
+    encoding: str = "utf-8",
+    ensure_ascii: bool = True,
+    make_dirs: bool = True,
+) -> bool:
+    """Atomically write JSON data to a file.
+
+    Uses write-to-temp-then-rename pattern to prevent race conditions
+    and partial writes from corrupting data.
+
+    Args:
+        file_path: Path to the file
+        data: Data to serialize as JSON
+        indent: JSON indentation (default: 2)
+        encoding: File encoding (default: utf-8)
+        ensure_ascii: Escape non-ASCII characters (default: True)
+        make_dirs: Create parent directories if needed (default: True)
+
+    Returns:
+        True if write succeeded, False otherwise
+    """
+    path = Path(file_path)
+
+    if make_dirs:
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Write to temporary file first
+        fd, temp_path = tempfile.mkstemp(dir=path.parent, prefix=".tmp_", suffix=".json")
+        try:
+            # Write JSON to temp file
+            with os.fdopen(fd, "w", encoding=encoding) as f:
+                json.dump(data, f, indent=indent, ensure_ascii=ensure_ascii)
+
+            # Atomic rename (overwrites target if exists)
+            os.replace(temp_path, path)
+            return True
+        except Exception:
+            # Clean up temp file on error
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+            return False
+    except (OSError, ValueError, TypeError):
+        return False
+
+
+__all__ = [
+    "atomic_write_text",
+    "atomic_write_json",
+]

moai_adk/tag_system/linkage.py

@@ -0,0 +1,335 @@
+"""TAG linkage manager module for TAG System v2.0.
+
+Implements T4: Linkage Manager for bidirectional TAG↔CODE mapping
+with atomic database operations.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from . import atomic_ops, validator
+
+logger = logging.getLogger(__name__)
+
+
+# Re-export atomic_write functions for tests
+atomic_write_text = atomic_ops.atomic_write_text
+atomic_write_json = atomic_ops.atomic_write_json
+
+
+def spec_document_exists(spec_id: str) -> bool:
+    """Check if SPEC document exists in .moai/specs/.
+
+    Args:
+        spec_id: SPEC identifier to check
+
+    Returns:
+        True if SPEC document exists, False otherwise
+    """
+    # Get specs directory from current working directory
+    specs_dir = Path.cwd() / ".moai" / "specs"
+
+    if not specs_dir.exists():
+        return False
+
+    # Check for SPEC directory
+    spec_dir = specs_dir / spec_id
+    return spec_dir.exists() and spec_dir.is_dir()
+
+
+class LinkageManager:
+    """Manage bidirectional TAG↔CODE mapping database.
+
+    Provides atomic database operations for TAG tracking,
+    with support for TAG→Files and File→TAGs lookups.
+
+    Attributes:
+        db_path: Path to linkage database file
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        """Initialize linkage manager.
+
+        Args:
+            db_path: Path to linkage database JSON file
+        """
+        self.db_path = Path(db_path)
+        self._ensure_database()
+
+    def _ensure_database(self) -> None:
+        """Ensure database file exists with proper structure."""
+        if not self.db_path.exists():
+            # Create new database with empty structure
+            self._write_database({"tags": [], "files": {}})
+
+    def _load_database(self) -> dict[str, Any]:
+        """Load database from disk.
+
+        Returns:
+            Database dictionary with 'tags' and 'files' keys
+        """
+        try:
+            if not self.db_path.exists():
+                return {"tags": [], "files": {}}
+
+            with open(self.db_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            # Validate structure
+            if not isinstance(data, dict):
+                logger.warning(f"Invalid database structure in {self.db_path}")
+                return {"tags": [], "files": {}}
+
+            if "tags" not in data:
+                data["tags"] = []
+            if "files" not in data:
+                data["files"] = {}
+
+            return data
+
+        except (json.JSONDecodeError, OSError) as e:
+            logger.error(f"Error loading database {self.db_path}: {e}")
+            return {"tags": [], "files": {}}
+
+    def _write_database(self, data: dict[str, Any]) -> bool:
+        """Write database to disk atomically.
+
+        Args:
+            data: Database dictionary to write
+
+        Returns:
+            True if write succeeded, False otherwise
+        """
+        return atomic_write_json(self.db_path, data)
+
+    def add_tag(self, tag: validator.TAG) -> bool:
+        """Add TAG to linkage database.
+
+        Args:
+            tag: TAG object to add
+
+        Returns:
+            True if TAG added successfully, False otherwise
+
+        Examples:
+            >>> tag = TAG("SPEC-AUTH-001", Path("auth.py"), 10)
+            >>> manager.add_tag(tag)
+            True
+        """
+        try:
+            data = self._load_database()
+
+            # Create TAG entry
+            tag_entry = {
+                "spec_id": tag.spec_id,
+                "verb": tag.verb,
+                "file_path": str(tag.file_path),
+                "line": tag.line,
+            }
+
+            # Check for duplicate
+            if tag_entry not in data["tags"]:
+                data["tags"].append(tag_entry)
+
+            # Update file index
+            file_key = str(tag.file_path)
+            if file_key not in data["files"]:
+                data["files"][file_key] = []
+
+            if tag.spec_id not in data["files"][file_key]:
+                data["files"][file_key].append(tag.spec_id)
+
+            # Write database atomically
+            return self._write_database(data)
+
+        except Exception as e:
+            logger.error(f"Error adding TAG to database: {e}")
+            return False
+
+    def remove_tag(self, tag: validator.TAG) -> bool:
+        """Remove specific TAG from database.
+
+        Args:
+            tag: TAG object to remove
+
+        Returns:
+            True if TAG removed successfully, False otherwise
+        """
+        try:
+            data = self._load_database()
+
+            tag_entry = {
+                "spec_id": tag.spec_id,
+                "verb": tag.verb,
+                "file_path": str(tag.file_path),
+                "line": tag.line,
+            }
+
+            # Remove from tags list
+            if tag_entry in data["tags"]:
+                data["tags"].remove(tag_entry)
+
+            # Update file index
+            file_key = str(tag.file_path)
+            if file_key in data["files"] and tag.spec_id in data["files"][file_key]:
+                data["files"][file_key].remove(tag.spec_id)
+
+                # Clean up empty file entries
+                if not data["files"][file_key]:
+                    del data["files"][file_key]
+
+            return self._write_database(data)
+
+        except Exception as e:
+            logger.error(f"Error removing TAG from database: {e}")
+            return False
+
+    def remove_file_tags(self, file_path: Path) -> bool:
+        """Remove all TAGs for a file.
+
+        Args:
+            file_path: Path to file whose TAGs should be removed
+
+        Returns:
+            True if TAGs removed successfully, False otherwise
+
+        Examples:
+            >>> manager.remove_file_tags(Path("deleted.py"))
+            True
+        """
+        try:
+            data = self._load_database()
+
+            file_key = str(file_path)
+
+            # Remove all TAGs for this file
+            data["tags"] = [tag for tag in data["tags"] if tag["file_path"] != file_key]
+
+            # Remove file index
+            if file_key in data["files"]:
+                del data["files"][file_key]
+
+            return self._write_database(data)
+
+        except Exception as e:
+            logger.error(f"Error removing file TAGs: {e}")
+            return False
+
+    def get_all_tags(self) -> list[dict[str, Any]]:
+        """Get all TAGs in database.
+
+        Returns:
+            List of TAG dictionaries
+        """
+        data = self._load_database()
+        return data.get("tags", [])
+
+    def get_code_locations(self, spec_id: str) -> list[dict[str, Any]]:
+        """Get all code locations for a SPEC-ID.
+
+        Args:
+            spec_id: SPEC identifier to query
+
+        Returns:
+            List of location dictionaries with file_path, line, and verb
+
+        Examples:
+            >>> locations = manager.get_code_locations("SPEC-AUTH-001")
+            >>> len(locations)
+            3
+        """
+        data = self._load_database()
+        tags = data.get("tags", [])
+
+        # Filter TAGs by spec_id
+        locations = [
+            {
+                "file_path": tag["file_path"],
+                "line": tag["line"],
+                "verb": tag["verb"],
+            }
+            for tag in tags
+            if tag["spec_id"] == spec_id
+        ]
+
+        return locations
+
+    def get_tags_by_file(self, file_path: Path) -> list[dict[str, Any]]:
+        """Get all TAGs for a specific file.
+
+        Args:
+            file_path: Path to file
+
+        Returns:
+            List of TAG dictionaries for the file
+
+        Examples:
+            >>> tags = manager.get_tags_by_file(Path("auth.py"))
+            >>> len(tags)
+            2
+        """
+        data = self._load_database()
+        tags = data.get("tags", [])
+        file_key = str(file_path)
+
+        # Filter TAGs by file_path
+        return [
+            {
+                "spec_id": tag["spec_id"],
+                "verb": tag["verb"],
+                "file_path": tag["file_path"],
+                "line": tag["line"],
+            }
+            for tag in tags
+            if tag["file_path"] == file_key
+        ]
+
+    def get_all_spec_ids(self) -> list[str]:
+        """Get all unique SPEC-IDs in database.
+
+        Returns:
+            Sorted list of unique SPEC-ID strings
+        """
+        data = self._load_database()
+        tags = data.get("tags", [])
+
+        spec_ids = {tag["spec_id"] for tag in tags}
+        return sorted(spec_ids)
+
+    def find_orphaned_tags(self) -> list[dict[str, Any]]:
+        """Find TAGs referencing nonexistent SPEC documents.
+
+        Returns:
+            List of orphaned TAG dictionaries
+
+        Examples:
+            >>> orphans = manager.find_orphaned_tags()
+            >>> len(orphans)
+            1
+        """
+        data = self._load_database()
+        tags = data.get("tags", [])
+
+        orphans = [tag for tag in tags if not spec_document_exists(tag["spec_id"])]
+
+        return orphans
+
+    def clear(self) -> bool:
+        """Clear all TAGs from database.
+
+        Returns:
+            True if database cleared successfully, False otherwise
+        """
+        return self._write_database({"tags": [], "files": {}})
+
+
+__all__ = [
+    "spec_document_exists",
+    "LinkageManager",
+    "atomic_write_json",
+    "atomic_write_text",
+]

moai_adk/tag_system/parser.py

@@ -0,0 +1,176 @@
+"""TAG parser module for TAG System v2.0.
+
+Implements T2: TAG Parser for extracting TAG annotations from
+Python source code comments using AST parsing.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+from pathlib import Path
+from typing import List
+
+from . import validator
+
+logger = logging.getLogger(__name__)
+
+
+def extract_tags_from_source(source: str, file_path: Path) -> List[validator.TAG]:
+    """Extract all @SPEC TAGs from Python source code.
+
+    Args:
+        source: Python source code as string
+        file_path: Path to the source file
+
+    Returns:
+        List of TAG objects found in the source
+
+    Examples:
+        >>> source = "# @SPEC SPEC-AUTH-001\\ndef func(): pass"
+        >>> tags = extract_tags_from_source(source, Path("test.py"))
+        >>> len(tags)
+        1
+    """
+    tags: List[validator.TAG] = []
+
+    if not isinstance(source, str):
+        return tags
+
+    # Split source into lines and extract TAGs from comments
+    lines = source.splitlines()
+
+    for line_number, line in enumerate(lines, start=1):
+        # Handle both standalone comments and inline comments
+        # Find the comment portion if it exists
+        comment_start = line.find("#")
+
+        if comment_start == -1:
+            # No comment in this line
+            continue
+
+        # Extract the comment portion (from # to end of line)
+        comment_portion = line[comment_start:]
+
+        # Parse TAG from comment
+        tag = validator.parse_tag_string(comment_portion, file_path, line_number)
+
+        if tag is not None:
+            tags.append(tag)
+
+    return tags
+
+
+def extract_tags_from_file(file_path: Path) -> List[validator.TAG]:
+    """Extract all @SPEC TAGs from a Python file.
+
+    Args:
+        file_path: Path to the Python file
+
+    Returns:
+        List of TAG objects found in the file, empty list if file doesn't exist or has errors
+
+    Examples:
+        >>> tags = extract_tags_from_file(Path("auth.py"))
+        >>> len(tags)
+        2
+    """
+    if not isinstance(file_path, Path):
+        file_path = Path(file_path)
+
+    # Check if file exists
+    if not file_path.exists():
+        logger.warning(f"File not found: {file_path}")
+        return []
+
+    # Check if file is readable
+    if not file_path.is_file():
+        logger.warning(f"Not a file: {file_path}")
+        return []
+
+    try:
+        # Read file content
+        source = file_path.read_text(encoding="utf-8")
+
+        # Validate Python syntax
+        try:
+            ast.parse(source)
+        except SyntaxError as e:
+            logger.warning(f"Syntax error in {file_path}: {e}")
+            return []
+
+        # Extract TAGs
+        return extract_tags_from_source(source, file_path)
+
+    except Exception as e:
+        logger.error(f"Error reading file {file_path}: {e}")
+        return []
+
+
+def extract_tags_from_files(file_paths: List[Path]) -> List[validator.TAG]:
+    """Extract TAGs from multiple files.
+
+    Args:
+        file_paths: List of file paths to process
+
+    Returns:
+        List of all TAGs found across all files
+
+    Examples:
+        >>> files = [Path("a.py"), Path("b.py")]
+        >>> tags = extract_tags_from_files(files)
+        >>> len(tags)
+        5
+    """
+    all_tags: List[validator.TAG] = []
+
+    for file_path in file_paths:
+        tags = extract_tags_from_file(file_path)
+        all_tags.extend(tags)
+
+    return all_tags
+
+
+def extract_tags_from_directory(
+    directory: Path,
+    pattern: str = "*.py",
+    recursive: bool = True,
+) -> List[validator.TAG]:
+    """Extract TAGs from all Python files in a directory.
+
+    Args:
+        directory: Directory path to search
+        pattern: File pattern to match (default: "*.py")
+        recursive: Whether to search recursively (default: True)
+
+    Returns:
+        List of all TAGs found in matching files
+
+    Examples:
+        >>> tags = extract_tags_from_directory(Path("src/"))
+        >>> len(tags)
+        42
+    """
+    if not isinstance(directory, Path):
+        directory = Path(directory)
+
+    if not directory.exists() or not directory.is_dir():
+        logger.warning(f"Not a directory: {directory}")
+        return []
+
+    # Find matching files
+    if recursive:
+        files = list(directory.rglob(pattern))
+    else:
+        files = list(directory.glob(pattern))
+
+    # Extract TAGs from all files
+    return extract_tags_from_files(files)
+
+
+__all__ = [
+    "extract_tags_from_source",
+    "extract_tags_from_file",
+    "extract_tags_from_files",
+    "extract_tags_from_directory",
+]