tasktree 0.0.1__py3-none-any.whl

tasktree/parser.py

@@ -0,0 +1,300 @@
+"""Parse recipe YAML files and handle imports."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class CircularImportError(Exception):
+    """Raised when a circular import is detected."""
+    pass
+
+
+@dataclass
+class Task:
+    """Represents a task definition."""
+
+    name: str
+    cmd: str
+    desc: str = ""
+    deps: list[str] = field(default_factory=list)
+    inputs: list[str] = field(default_factory=list)
+    outputs: list[str] = field(default_factory=list)
+    working_dir: str = ""
+    args: list[str] = field(default_factory=list)
+    source_file: str = ""  # Track which file defined this task
+
+    def __post_init__(self):
+        """Ensure lists are always lists."""
+        if isinstance(self.deps, str):
+            self.deps = [self.deps]
+        if isinstance(self.inputs, str):
+            self.inputs = [self.inputs]
+        if isinstance(self.outputs, str):
+            self.outputs = [self.outputs]
+        if isinstance(self.args, str):
+            self.args = [self.args]
+
+
+@dataclass
+class Recipe:
+    """Represents a parsed recipe file with all tasks."""
+
+    tasks: dict[str, Task]
+    project_root: Path
+
+    def get_task(self, name: str) -> Task | None:
+        """Get task by name.
+
+        Args:
+            name: Task name (may be namespaced like 'build.compile')
+
+        Returns:
+            Task if found, None otherwise
+        """
+        return self.tasks.get(name)
+
+    def task_names(self) -> list[str]:
+        """Get all task names."""
+        return list(self.tasks.keys())
+
+
+def find_recipe_file(start_dir: Path | None = None) -> Path | None:
+    """Find recipe file (tasktree.yaml or tt.yaml) in current or parent directories.
+
+    Args:
+        start_dir: Directory to start searching from (defaults to cwd)
+
+    Returns:
+        Path to recipe file if found, None otherwise
+    """
+    if start_dir is None:
+        start_dir = Path.cwd()
+
+    current = start_dir.resolve()
+
+    # Search up the directory tree
+    while True:
+        for filename in ["tasktree.yaml", "tt.yaml"]:
+            recipe_path = current / filename
+            if recipe_path.exists():
+                return recipe_path
+
+        # Move to parent directory
+        parent = current.parent
+        if parent == current:
+            # Reached root
+            break
+        current = parent
+
+    return None
+
+
+def parse_recipe(recipe_path: Path) -> Recipe:
+    """Parse a recipe file and handle imports recursively.
+
+    Args:
+        recipe_path: Path to the main recipe file
+
+    Returns:
+        Recipe object with all tasks (including recursively imported tasks)
+
+    Raises:
+        FileNotFoundError: If recipe file doesn't exist
+        CircularImportError: If circular imports are detected
+        yaml.YAMLError: If YAML is invalid
+        ValueError: If recipe structure is invalid
+    """
+    if not recipe_path.exists():
+        raise FileNotFoundError(f"Recipe file not found: {recipe_path}")
+
+    project_root = recipe_path.parent
+
+    # Parse main file - it will recursively handle all imports
+    tasks = _parse_file(recipe_path, namespace=None, project_root=project_root)
+
+    return Recipe(tasks=tasks, project_root=project_root)
+
+
+def _parse_file(
+    file_path: Path,
+    namespace: str | None,
+    project_root: Path,
+    import_stack: list[Path] | None = None,
+) -> dict[str, Task]:
+    """Parse a single YAML file and return tasks, recursively processing imports.
+
+    Args:
+        file_path: Path to YAML file
+        namespace: Optional namespace prefix for tasks
+        project_root: Root directory of the project
+        import_stack: Stack of files being imported (for circular detection)
+
+    Returns:
+        Dictionary of task name to Task objects
+
+    Raises:
+        CircularImportError: If a circular import is detected
+        FileNotFoundError: If an imported file doesn't exist
+        ValueError: If task structure is invalid
+    """
+    # Initialize import stack if not provided
+    if import_stack is None:
+        import_stack = []
+
+    # Detect circular imports
+    if file_path in import_stack:
+        chain = " → ".join(str(f.name) for f in import_stack + [file_path])
+        raise CircularImportError(f"Circular import detected: {chain}")
+
+    # Add current file to stack
+    import_stack.append(file_path)
+
+    # Load YAML
+    with open(file_path, "r") as f:
+        data = yaml.safe_load(f)
+
+    if data is None:
+        data = {}
+
+    tasks: dict[str, Task] = {}
+    file_dir = file_path.parent
+
+    # Default working directory is the file's directory
+    default_working_dir = str(file_dir.relative_to(project_root)) if file_dir != project_root else "."
+
+    # Track local import namespaces for dependency rewriting
+    local_import_namespaces: set[str] = set()
+
+    # Process nested imports FIRST
+    imports = data.get("import", [])
+    if imports:
+        for import_spec in imports:
+            child_file = import_spec["file"]
+            child_namespace = import_spec["as"]
+
+            # Track this namespace as a local import
+            local_import_namespaces.add(child_namespace)
+
+            # Build full namespace chain
+            full_namespace = f"{namespace}.{child_namespace}" if namespace else child_namespace
+
+            # Resolve import path relative to current file's directory
+            child_path = file_path.parent / child_file
+            if not child_path.exists():
+                raise FileNotFoundError(f"Import file not found: {child_path}")
+
+            # Recursively process with namespace chain and import stack
+            nested_tasks = _parse_file(
+                child_path,
+                full_namespace,
+                project_root,
+                import_stack.copy(),  # Pass copy to avoid shared mutation
+            )
+
+            tasks.update(nested_tasks)
+
+    # Process local tasks
+    for task_name, task_data in data.items():
+        # Skip import declarations
+        if task_name == "import":
+            continue
+
+        if not isinstance(task_data, dict):
+            raise ValueError(f"Task '{task_name}' must be a dictionary")
+
+        if "cmd" not in task_data:
+            raise ValueError(f"Task '{task_name}' missing required 'cmd' field")
+
+        # Apply namespace if provided
+        full_name = f"{namespace}.{task_name}" if namespace else task_name
+
+        # Set working directory
+        working_dir = task_data.get("working_dir", default_working_dir)
+
+        # Rewrite dependencies with namespace
+        deps = task_data.get("deps", [])
+        if isinstance(deps, str):
+            deps = [deps]
+        if namespace:
+            # Rewrite dependencies: only prefix if it's a local reference
+            # A dependency is local if:
+            # 1. It has no dots (simple name like "init")
+            # 2. It starts with a local import namespace (like "base.setup" when "base" is imported)
+            rewritten_deps = []
+            for dep in deps:
+                if "." not in dep:
+                    # Simple name - always prefix
+                    rewritten_deps.append(f"{namespace}.{dep}")
+                else:
+                    # Check if it starts with a local import namespace
+                    dep_root = dep.split(".", 1)[0]
+                    if dep_root in local_import_namespaces:
+                        # Local import reference - prefix it
+                        rewritten_deps.append(f"{namespace}.{dep}")
+                    else:
+                        # External reference - keep as-is
+                        rewritten_deps.append(dep)
+            deps = rewritten_deps
+
+        task = Task(
+            name=full_name,
+            cmd=task_data["cmd"],
+            desc=task_data.get("desc", ""),
+            deps=deps,
+            inputs=task_data.get("inputs", []),
+            outputs=task_data.get("outputs", []),
+            working_dir=working_dir,
+            args=task_data.get("args", []),
+            source_file=str(file_path),
+        )
+
+        tasks[full_name] = task
+
+    # Remove current file from stack
+    import_stack.pop()
+
+    return tasks
+
+
+def parse_arg_spec(arg_spec: str) -> tuple[str, str, str | None]:
+    """Parse argument specification.
+
+    Format: name:type=default
+    - name is required
+    - type is optional (defaults to 'str')
+    - default is optional
+
+    Args:
+        arg_spec: Argument specification string
+
+    Returns:
+        Tuple of (name, type, default)
+
+    Examples:
+        >>> parse_arg_spec("environment")
+        ('environment', 'str', None)
+        >>> parse_arg_spec("region=eu-west-1")
+        ('region', 'str', 'eu-west-1')
+        >>> parse_arg_spec("port:int=8080")
+        ('port', 'int', '8080')
+    """
+    # Split on = to separate name:type from default
+    if "=" in arg_spec:
+        name_type, default = arg_spec.split("=", 1)
+    else:
+        name_type = arg_spec
+        default = None
+
+    # Split on : to separate name from type
+    if ":" in name_type:
+        name, arg_type = name_type.split(":", 1)
+    else:
+        name = name_type
+        arg_type = "str"
+
+    return name, arg_type, default

tasktree/state.py

@@ -0,0 +1,119 @@
+"""State file management and pruning."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class TaskState:
+    """State for a single task execution."""
+
+    last_run: float
+    input_state: dict[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "last_run": self.last_run,
+            "input_state": self.input_state,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TaskState":
+        """Create from dictionary loaded from JSON."""
+        return cls(
+            last_run=data["last_run"],
+            input_state=data.get("input_state", {}),
+        )
+
+
+class StateManager:
+    """Manages the .tasktree-state file."""
+
+    STATE_FILE = ".tasktree-state"
+
+    def __init__(self, project_root: Path):
+        """Initialize state manager.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root
+        self.state_path = project_root / self.STATE_FILE
+        self._state: dict[str, TaskState] = {}
+        self._loaded = False
+
+    def load(self) -> None:
+        """Load state from file if it exists."""
+        if self.state_path.exists():
+            try:
+                with open(self.state_path, "r") as f:
+                    data = json.load(f)
+                    self._state = {
+                        key: TaskState.from_dict(value)
+                        for key, value in data.items()
+                    }
+            except (json.JSONDecodeError, KeyError) as e:
+                # If state file is corrupted, start fresh
+                self._state = {}
+        self._loaded = True
+
+    def save(self) -> None:
+        """Save state to file."""
+        data = {key: value.to_dict() for key, value in self._state.items()}
+        with open(self.state_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def get(self, cache_key: str) -> TaskState | None:
+        """Get state for a task.
+
+        Args:
+            cache_key: Cache key (task_hash or task_hash__args_hash)
+
+        Returns:
+            TaskState if found, None otherwise
+        """
+        if not self._loaded:
+            self.load()
+        return self._state.get(cache_key)
+
+    def set(self, cache_key: str, state: TaskState) -> None:
+        """Set state for a task.
+
+        Args:
+            cache_key: Cache key (task_hash or task_hash__args_hash)
+            state: TaskState to store
+        """
+        if not self._loaded:
+            self.load()
+        self._state[cache_key] = state
+
+    def prune(self, valid_task_hashes: set[str]) -> None:
+        """Remove state entries for tasks that no longer exist.
+
+        Args:
+            valid_task_hashes: Set of valid task hashes from current recipe
+        """
+        if not self._loaded:
+            self.load()
+
+        # Find keys to remove
+        keys_to_remove = []
+        for cache_key in self._state.keys():
+            # Extract task hash (before __ if present)
+            task_hash = cache_key.split("__")[0]
+            if task_hash not in valid_task_hashes:
+                keys_to_remove.append(cache_key)
+
+        # Remove stale entries
+        for key in keys_to_remove:
+            del self._state[key]
+
+    def clear(self) -> None:
+        """Clear all state (useful for testing)."""
+        self._state = {}
+        self._loaded = True

tasktree/tasks.py

@@ -0,0 +1,8 @@
+import subprocess
+
+from typing import Dict
+
+
+def run(task_tree: Dict) -> None:
+    for _, params in task_tree.items():
+        _ = subprocess.run(params["cmd"], shell=True)

tasktree/types.py

@@ -0,0 +1,130 @@
+"""Custom Click parameter types for task argument validation."""
+
+import re
+from datetime import datetime
+from ipaddress import IPv4Address, IPv6Address, ip_address
+from pathlib import Path
+from typing import Any
+
+import click
+
+
+class HostnameType(click.ParamType):
+    """Validates hostname format (not DNS resolution)."""
+
+    name = "hostname"
+
+    # Simple hostname validation (RFC 1123)
+    HOSTNAME_PATTERN = re.compile(
+        r"^(?=.{1,253}$)(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})*\.?$"
+    )
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        if isinstance(value, str):
+            if self.HOSTNAME_PATTERN.match(value):
+                return value
+        self.fail(f"{value!r} is not a valid hostname", param, ctx)
+
+
+class EmailType(click.ParamType):
+    """Validates email format (not deliverability)."""
+
+    name = "email"
+
+    # Basic email validation (RFC 5322 simplified)
+    EMAIL_PATTERN = re.compile(
+        r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"
+    )
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        if isinstance(value, str):
+            if self.EMAIL_PATTERN.match(value):
+                return value
+        self.fail(f"{value!r} is not a valid email address", param, ctx)
+
+
+class IPType(click.ParamType):
+    """Validates IP address (IPv4 or IPv6)."""
+
+    name = "ip"
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        try:
+            ip_address(value)
+            return str(value)
+        except ValueError:
+            self.fail(f"{value!r} is not a valid IP address", param, ctx)
+
+
+class IPv4Type(click.ParamType):
+    """Validates IPv4 address."""
+
+    name = "ipv4"
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        try:
+            IPv4Address(value)
+            return str(value)
+        except ValueError:
+            self.fail(f"{value!r} is not a valid IPv4 address", param, ctx)
+
+
+class IPv6Type(click.ParamType):
+    """Validates IPv6 address."""
+
+    name = "ipv6"
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        try:
+            IPv6Address(value)
+            return str(value)
+        except ValueError:
+            self.fail(f"{value!r} is not a valid IPv6 address", param, ctx)
+
+
+class DateTimeType(click.ParamType):
+    """Validates datetime in format YYYY-MM-DDTHH:MM:SS."""
+
+    name = "datetime"
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        if isinstance(value, str):
+            try:
+                datetime.fromisoformat(value)
+                return value
+            except ValueError:
+                pass
+        self.fail(f"{value!r} is not a valid datetime (expected YYYY-MM-DDTHH:MM:SS format)", param, ctx)
+
+
+# Type registry for dynamic parameter creation
+TYPE_MAPPING = {
+    "str": click.STRING,
+    "int": click.INT,
+    "float": click.FLOAT,
+    "bool": click.BOOL,
+    "path": click.Path(),
+    "datetime": DateTimeType(),
+    "hostname": HostnameType(),
+    "email": EmailType(),
+    "ip": IPType(),
+    "ipv4": IPv4Type(),
+    "ipv6": IPv6Type(),
+}
+
+
+def get_click_type(type_name: str) -> click.ParamType:
+    """Get Click parameter type by name.
+
+    Args:
+        type_name: Type name from task definition (e.g., 'str', 'int', 'hostname')
+
+    Returns:
+        Click parameter type instance
+
+    Raises:
+        ValueError: If type_name is not recognized
+    """
+    if type_name not in TYPE_MAPPING:
+        raise ValueError(f"Unknown type: {type_name}")
+    return TYPE_MAPPING[type_name]