tasktree 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

tasktree/cli.py

@@ -14,8 +14,8 @@ from rich.tree import Tree
 
 from tasktree import __version__
 from tasktree.executor import Executor
-from tasktree.graph import build_dependency_tree
-from tasktree.hasher import hash_task
+from tasktree.graph import build_dependency_tree, resolve_execution_order
+from tasktree.hasher import hash_task, hash_args
 from tasktree.parser import Recipe, find_recipe_file, parse_arg_spec, parse_recipe
 from tasktree.state import StateManager
 from tasktree.types import get_click_type
@@ -137,7 +137,8 @@ def _list_tasks(tasks_file: Optional[str] = None):
 
 def _show_task(task_name: str, tasks_file: Optional[str] = None):
     """Show task definition with syntax highlighting."""
-    recipe = _get_recipe(tasks_file)
+    # Pass task_name as root_task for lazy variable evaluation
+    recipe = _get_recipe(tasks_file, root_task=task_name)
     if recipe is None:
         console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
         raise typer.Exit(1)
@@ -186,7 +187,8 @@ def _show_task(task_name: str, tasks_file: Optional[str] = None):
 
 def _show_tree(task_name: str, tasks_file: Optional[str] = None):
     """Show dependency tree structure."""
-    recipe = _get_recipe(tasks_file)
+    # Pass task_name as root_task for lazy variable evaluation
+    recipe = _get_recipe(tasks_file, root_task=task_name)
     if recipe is None:
         console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
         raise typer.Exit(1)
@@ -372,11 +374,13 @@ def _clean_state(tasks_file: Optional[str] = None) -> None:
         console.print(f"[yellow]No state file found at {state_path}[/yellow]")
 
 
-def _get_recipe(recipe_file: Optional[str] = None) -> Optional[Recipe]:
+def _get_recipe(recipe_file: Optional[str] = None, root_task: Optional[str] = None) -> Optional[Recipe]:
     """Get parsed recipe or None if not found.
 
     Args:
         recipe_file: Optional path to recipe file. If not provided, searches for recipe file.
+        root_task: Optional root task for lazy variable evaluation. If provided, only variables
+                  reachable from this task will be evaluated (performance optimization).
     """
     if recipe_file:
         recipe_path = Path(recipe_file)
@@ -398,7 +402,7 @@ def _get_recipe(recipe_file: Optional[str] = None) -> Optional[Recipe]:
         project_root = None
 
     try:
-        return parse_recipe(recipe_path, project_root)
+        return parse_recipe(recipe_path, project_root, root_task)
     except Exception as e:
         console.print(f"[red]Error parsing recipe: {e}[/red]")
         raise typer.Exit(1)
@@ -411,7 +415,8 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
     task_name = args[0]
     task_args = args[1:]
 
-    recipe = _get_recipe(tasks_file)
+    # Pass task_name as root_task for lazy variable evaluation
+    recipe = _get_recipe(tasks_file, root_task=task_name)
     if recipe is None:
         console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
         raise typer.Exit(1)
@@ -443,11 +448,34 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
     state.load()
     executor = Executor(recipe, state)
 
-    # Prune state before execution (compute hashes with effective environment and dependencies)
-    valid_hashes = {
-        hash_task(t.cmd, t.outputs, t.working_dir, t.args, executor._get_effective_env_name(t), t.deps)
-        for t in recipe.tasks.values()
-    }
+    # Resolve execution order to determine which tasks will actually run
+    # This is important for correct state pruning after template substitution
+    execution_order = resolve_execution_order(recipe, task_name, args_dict)
+
+    # Prune state based on tasks that will actually execute (with their specific arguments)
+    # This ensures template-substituted dependencies are handled correctly
+    valid_hashes = set()
+    for exec_task_name, exec_task_args in execution_order:
+        task = recipe.tasks[exec_task_name]
+        # Compute base task hash
+        task_hash = hash_task(
+            task.cmd,
+            task.outputs,
+            task.working_dir,
+            task.args,
+            executor._get_effective_env_name(task),
+            task.deps
+        )
+
+        # If task has arguments, append args hash to create unique cache key
+        if exec_task_args:
+            args_hash = hash_args(exec_task_args)
+            cache_key = f"{task_hash}__{args_hash}"
+        else:
+            cache_key = task_hash
+
+        valid_hashes.add(cache_key)
+
     state.prune(valid_hashes)
     state.save()
     try:

tasktree/executor.py

@@ -662,6 +662,60 @@ class Executor:
             except OSError:
                 pass  # Ignore cleanup errors
 
+    def _substitute_builtin_in_environment(self, env: Environment, builtin_vars: dict[str, str]) -> Environment:
+        """Substitute builtin and environment variables in environment fields.
+
+        Args:
+            env: Environment to process
+            builtin_vars: Built-in variable values
+
+        Returns:
+            New Environment with builtin and environment variables substituted
+
+        Raises:
+            ValueError: If builtin variable or environment variable is not defined
+        """
+        from dataclasses import replace
+
+        # Substitute in volumes (builtin vars first, then env vars)
+        substituted_volumes = [
+            self._substitute_env(self._substitute_builtin(vol, builtin_vars)) for vol in env.volumes
+        ] if env.volumes else []
+
+        # Substitute in env_vars values (builtin vars first, then env vars)
+        substituted_env_vars = {
+            key: self._substitute_env(self._substitute_builtin(value, builtin_vars))
+            for key, value in env.env_vars.items()
+        } if env.env_vars else {}
+
+        # Substitute in ports (builtin vars first, then env vars)
+        substituted_ports = [
+            self._substitute_env(self._substitute_builtin(port, builtin_vars)) for port in env.ports
+        ] if env.ports else []
+
+        # Substitute in working_dir (builtin vars first, then env vars)
+        substituted_working_dir = self._substitute_env(self._substitute_builtin(env.working_dir, builtin_vars)) if env.working_dir else ""
+
+        # Substitute in build args (for Docker environments, args is a dict)
+        # Apply builtin vars first, then env vars
+        if isinstance(env.args, dict):
+            substituted_args = {
+                key: self._substitute_env(self._substitute_builtin(str(value), builtin_vars))
+                for key, value in env.args.items()
+            }
+        else:
+            substituted_args = env.args
+
+        # Create new environment with substituted values
+        return replace(
+            env,
+            volumes=substituted_volumes,
+            env_vars=substituted_env_vars,
+            ports=substituted_ports,
+            working_dir=substituted_working_dir,
+            args=substituted_args
+        )
+
     def _run_task_in_docker(
         self, task: Task, env: Any, cmd: str, working_dir: Path,
         exported_env_vars: dict[str, str] | None = None
@@ -678,6 +732,13 @@ class Executor:
         Raises:
             ExecutionError: If Docker execution fails
         """
+        # Get builtin variables for substitution in environment fields
+        task_start_time = datetime.now(timezone.utc)
+        builtin_vars = self._collect_builtin_variables(task, working_dir, task_start_time)
+
+        # Substitute builtin variables in environment fields (volumes, env_vars, etc.)
+        env = self._substitute_builtin_in_environment(env, builtin_vars)
+
         # Resolve container working directory
         container_working_dir = docker_module.resolve_container_working_dir(
             env.working_dir, task.working_dir

tasktree/graph.py

@@ -5,7 +5,161 @@ from pathlib import Path
 from typing import Any
 
 from tasktree.hasher import hash_args
-from tasktree.parser import Recipe, Task, DependencyInvocation, parse_dependency_spec
+from tasktree.parser import (
+    Recipe,
+    Task,
+    DependencyInvocation,
+    parse_dependency_spec,
+    parse_arg_spec,
+)
+from tasktree.substitution import substitute_dependency_args
+
+
+def _get_exported_arg_names(task: Task) -> set[str]:
+    """Extract names of exported arguments from a task.
+
+    Exported arguments are identified by the '$' prefix in their definition.
+
+    Args:
+        task: Task to extract exported arg names from
+
+    Returns:
+        Set of exported argument names (without the '$' prefix)
+
+    Example:
+        Task with args: ["$server", "port"]
+        Returns: {"server"}
+    """
+    if not task.args:
+        return set()
+
+    exported = set()
+    for arg_spec in task.args:
+        if isinstance(arg_spec, str):
+            # Simple string format: "$argname" or "argname"
+            if arg_spec.startswith("$"):
+                exported.add(arg_spec[1:])  # Remove '$' prefix
+        elif isinstance(arg_spec, dict):
+            # Dictionary format: {"$argname": {...}} or {"argname": {...}}
+            for arg_name in arg_spec.keys():
+                if arg_name.startswith("$"):
+                    exported.add(arg_name[1:])  # Remove '$' prefix
+
+    return exported
+
+
+def resolve_dependency_invocation(
+    dep_spec: str | dict[str, Any],
+    parent_task_name: str,
+    parent_args: dict[str, Any],
+    parent_exported_args: set[str],
+    recipe: Recipe
+) -> DependencyInvocation:
+    """Parse dependency specification and substitute parent argument templates.
+
+    This function handles template substitution in dependency arguments. It:
+    1. Checks if dependency arguments contain {{ arg.* }} templates
+    2. Substitutes templates using parent task's arguments
+    3. Delegates to parse_dependency_spec for type conversion and validation
+
+    Args:
+        dep_spec: Dependency specification (str or dict with task name and args)
+        parent_task_name: Name of the parent task (for error messages)
+        parent_args: Parent task's argument values (for template substitution)
+        parent_exported_args: Set of parent's exported argument names
+        recipe: Recipe containing task definitions
+
+    Returns:
+        DependencyInvocation with typed, validated arguments
+
+    Raises:
+        ValueError: If template substitution fails, argument validation fails,
+                   or dependency task doesn't exist
+
+    Examples:
+        Simple string (no templates):
+        >>> resolve_dependency_invocation("build", "test", {}, set(), recipe)
+        DependencyInvocation("build", None)
+
+        Literal arguments (no templates):
+        >>> resolve_dependency_invocation({"build": ["debug"]}, "test", {}, set(), recipe)
+        DependencyInvocation("build", {"mode": "debug"})
+
+        Template substitution:
+        >>> resolve_dependency_invocation(
+        ...     {"build": ["{{ arg.env }}"]},
+        ...     "test",
+        ...     {"env": "production"},
+        ...     set(),
+        ...     recipe
+        ... )
+        DependencyInvocation("build", {"mode": "production"})
+    """
+    # Simple string case - no args to substitute
+    if isinstance(dep_spec, str):
+        return parse_dependency_spec(dep_spec, recipe)
+
+    # Dictionary case: {"task_name": args_spec}
+    if not isinstance(dep_spec, dict) or len(dep_spec) != 1:
+        # Invalid format, let parse_dependency_spec handle the error
+        return parse_dependency_spec(dep_spec, recipe)
+
+    task_name, arg_spec = next(iter(dep_spec.items()))
+
+    # Check if any argument values contain templates
+    has_templates = False
+    if isinstance(arg_spec, list):
+        # Positional args: check each value
+        for val in arg_spec:
+            if isinstance(val, str) and "{{ arg." in val:
+                has_templates = True
+                break
+    elif isinstance(arg_spec, dict):
+        # Named args: check each value
+        for val in arg_spec.values():
+            if isinstance(val, str) and "{{ arg." in val:
+                has_templates = True
+                break
+
+    # If no templates, use existing parser (fast path for backward compatibility)
+    if not has_templates:
+        return parse_dependency_spec(dep_spec, recipe)
+
+    # Template substitution path
+    # Substitute {{ arg.* }} in argument values
+    substituted_arg_spec: list[Any] | dict[str, Any]
+
+    if isinstance(arg_spec, list):
+        # Positional args: substitute each value that's a string
+        substituted_arg_spec = []
+        for val in arg_spec:
+            if isinstance(val, str):
+                substituted_val = substitute_dependency_args(
+                    val, parent_task_name, parent_args, parent_exported_args
+                )
+                substituted_arg_spec.append(substituted_val)
+            else:
+                # Non-string values (bool, int, etc.) pass through unchanged
+                substituted_arg_spec.append(val)
+    elif isinstance(arg_spec, dict):
+        # Named args: substitute each string value
+        substituted_arg_spec = {}
+        for arg_name, val in arg_spec.items():
+            if isinstance(val, str):
+                substituted_val = substitute_dependency_args(
+                    val, parent_task_name, parent_args, parent_exported_args
+                )
+                substituted_arg_spec[arg_name] = substituted_val
+            else:
+                # Non-string values pass through unchanged
+                substituted_arg_spec[arg_name] = val
+    else:
+        # Invalid format, let parse_dependency_spec handle it
+        return parse_dependency_spec(dep_spec, recipe)
+
+    # Create new dep_spec with substituted values and parse it
+    substituted_dep_spec = {task_name: substituted_arg_spec}
+    return parse_dependency_spec(substituted_dep_spec, recipe)
 
 
 class CycleError(Exception):
@@ -99,7 +253,7 @@ def resolve_execution_order(
         return seen_invocations[key]
 
     def build_graph(node: TaskNode) -> None:
-        """Recursively build dependency graph."""
+        """Recursively build dependency graph with template substitution."""
         if node in graph:
             # Already processed
             return
@@ -108,11 +262,21 @@ def resolve_execution_order(
         if task is None:
             raise TaskNotFoundError(f"Task not found: {node.task_name}")
 
-        # Parse and normalize dependencies
+        # Get parent task's exported argument names
+        parent_exported_args = _get_exported_arg_names(task)
+
+        # Parse and normalize dependencies with template substitution
         dep_nodes = set()
         for dep_spec in task.deps:
-            # Parse dependency specification
-            dep_inv = parse_dependency_spec(dep_spec, recipe)
+            # Resolve dependency specification with parent context
+            # This handles template substitution if {{ arg.* }} is present
+            dep_inv = resolve_dependency_invocation(
+                dep_spec,
+                parent_task_name=node.task_name,
+                parent_args=node.args or {},
+                parent_exported_args=parent_exported_args,
+                recipe=recipe
+            )
 
             # Create or get node for this dependency invocation
             dep_node = get_or_create_node(dep_inv.task_name, dep_inv.args)

tasktree/parser.py

@@ -89,6 +89,31 @@ class Task:
             )
 
 
+@dataclass
+class DependencySpec:
+    """Parsed dependency specification with potential template placeholders.
+
+    This represents a dependency as defined in the recipe file, before template
+    substitution. Argument values may contain {{ arg.* }} templates that will be
+    substituted with parent task's argument values during graph construction.
+
+    Attributes:
+        task_name: Name of the dependency task
+        arg_templates: Dictionary mapping argument names to string templates
+                      (None if no args specified). All values are strings, even
+                      for numeric types, to preserve template placeholders.
+    """
+    task_name: str
+    arg_templates: dict[str, str] | None = None
+
+    def __str__(self) -> str:
+        """String representation for display."""
+        if not self.arg_templates:
+            return self.task_name
+        args_str = ", ".join(f"{k}={v}" for k, v in self.arg_templates.items())
+        return f"{self.task_name}({args_str})"
+
+
 @dataclass
 class DependencyInvocation:
     """Represents a task dependency invocation with optional arguments.
@@ -140,7 +165,11 @@ class Recipe:
     environments: dict[str, Environment] = field(default_factory=dict)
     default_env: str = ""  # Name of default environment
     global_env_override: str = ""  # Global environment override (set via CLI --env)
-    variables: dict[str, str] = field(default_factory=dict)  # Global variables (resolved at parse time)
+    variables: dict[str, str] = field(default_factory=dict)  # Global variables (resolved at parse time) - DEPRECATED, use evaluated_variables
+    raw_variables: dict[str, Any] = field(default_factory=dict)  # Raw variable specs from YAML (not yet evaluated)
+    evaluated_variables: dict[str, str] = field(default_factory=dict)  # Evaluated variable values (cached after evaluation)
+    _variables_evaluated: bool = False  # Track if variables have been evaluated
+    _original_yaml_data: dict[str, Any] = field(default_factory=dict)  # Store original YAML data for lazy evaluation context
 
     def get_task(self, name: str) -> Task | None:
         """Get task by name.
@@ -168,6 +197,108 @@ class Recipe:
         """
         return self.environments.get(name)
 
+    def evaluate_variables(self, root_task: str | None = None) -> None:
+        """Evaluate variables lazily based on task reachability.
+
+        This method implements lazy variable evaluation, which only evaluates
+        variables that are actually reachable from the target task. This provides:
+        - Performance improvement: expensive { eval: ... } commands only run when needed
+        - Security improvement: sensitive { read: ... } files only accessed when needed
+        - Side-effect control: commands with side effects only execute when necessary
+
+        If root_task is provided, only variables used by reachable tasks are evaluated.
+        If root_task is None, all variables are evaluated (for --list command compatibility).
+
+        This method is idempotent - calling it multiple times is safe (uses caching).
+
+        Args:
+            root_task: Optional task name to determine reachability (None = evaluate all)
+
+        Raises:
+            ValueError: If variable evaluation or substitution fails
+
+        Example:
+            >>> recipe = parse_recipe(path)  # Variables not yet evaluated
+            >>> recipe.evaluate_variables("build")  # Evaluate only reachable variables
+            >>> # Now recipe.evaluated_variables contains only vars used by "build" task
+        """
+        if self._variables_evaluated:
+            return  # Already evaluated, skip (idempotent)
+
+        # Determine which variables to evaluate
+        if root_task:
+            # Lazy path: only evaluate reachable variables
+            # If root_task doesn't exist, fall back to eager evaluation
+            # (CLI will provide its own "Task not found" error)
+            try:
+                reachable_tasks = collect_reachable_tasks(self.tasks, root_task)
+                variables_to_eval = collect_reachable_variables(self.tasks, reachable_tasks)
+            except ValueError:
+                # Root task not found - fall back to eager evaluation
+                # This allows the recipe to be parsed even with invalid task names
+                # so the CLI can provide its own error message
+                variables_to_eval = set(self.raw_variables.keys())
+        else:
+            # Eager path: evaluate all variables (for --list command)
+            variables_to_eval = set(self.raw_variables.keys())
+
+        # Evaluate the selected variables using helper function
+        self.evaluated_variables = _evaluate_variable_subset(
+            self.raw_variables,
+            variables_to_eval,
+            self.recipe_path,
+            self._original_yaml_data
+        )
+
+        # Also update the deprecated 'variables' field for backward compatibility
+        self.variables = self.evaluated_variables
+
+        # Substitute evaluated variables into all tasks
+        from tasktree.substitution import substitute_variables
+
+        for task in self.tasks.values():
+            task.cmd = substitute_variables(task.cmd, self.evaluated_variables)
+            task.desc = substitute_variables(task.desc, self.evaluated_variables)
+            task.working_dir = substitute_variables(task.working_dir, self.evaluated_variables)
+            task.inputs = [substitute_variables(inp, self.evaluated_variables) for inp in task.inputs]
+            task.outputs = [substitute_variables(out, self.evaluated_variables) for out in task.outputs]
+            # Substitute in argument default values (in arg spec strings)
+            task.args = [substitute_variables(arg, self.evaluated_variables) for arg in task.args]
+
+        # Substitute evaluated variables into all environments
+        for env in self.environments.values():
+            if env.preamble:
+                env.preamble = substitute_variables(env.preamble, self.evaluated_variables)
+
+            # Substitute in volumes
+            if env.volumes:
+                env.volumes = [substitute_variables(vol, self.evaluated_variables) for vol in env.volumes]
+
+            # Substitute in ports
+            if env.ports:
+                env.ports = [substitute_variables(port, self.evaluated_variables) for port in env.ports]
+
+            # Substitute in env_vars values
+            if env.env_vars:
+                env.env_vars = {
+                    key: substitute_variables(value, self.evaluated_variables)
+                    for key, value in env.env_vars.items()
+                }
+
+            # Substitute in working_dir
+            if env.working_dir:
+                env.working_dir = substitute_variables(env.working_dir, self.evaluated_variables)
+
+            # Substitute in build args (dict for Docker environments)
+            if env.args and isinstance(env.args, dict):
+                env.args = {
+                    key: substitute_variables(str(value), self.evaluated_variables)
+                    for key, value in env.args.items()
+                }
+
+        # Mark as evaluated
+        self._variables_evaluated = True
+
 
 def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     """Find recipe file in current or parent directories.
@@ -800,7 +931,6 @@ def _resolve_variable_value(
             error_msg = str(e)
             if "not defined" in error_msg:
                 # Extract the variable name from the error message
-                import re
                 match = re.search(r"Variable '(\w+)' is not defined", error_msg)
                 if match:
                     undefined_var = match.group(1)
@@ -850,12 +980,145 @@ def _parse_variables_section(data: dict, file_path: Path) -> dict[str, str]:
     return resolved
 
 
+def _expand_variable_dependencies(
+    variable_names: set[str],
+    raw_variables: dict[str, Any]
+) -> set[str]:
+    """Expand variable set to include all transitively referenced variables.
+
+    If variable A references variable B, and B references C, then requesting A
+    should also evaluate B and C.
+
+    Args:
+        variable_names: Initial set of variable names
+        raw_variables: Raw variable definitions from YAML
+
+    Returns:
+        Expanded set including all transitively referenced variables
+
+    Example:
+        >>> raw_vars = {
+        ...     "a": "{{ var.b }}",
+        ...     "b": "{{ var.c }}",
+        ...     "c": "value"
+        ... }
+        >>> _expand_variable_dependencies({"a"}, raw_vars)
+        {"a", "b", "c"}
+    """
+    expanded = set(variable_names)
+    to_process = list(variable_names)
+    pattern = re.compile(r'\{\{\s*var\.(\w+)\s*\}\}')
+
+    while to_process:
+        var_name = to_process.pop(0)
+
+        if var_name not in raw_variables:
+            continue
+
+        raw_value = raw_variables[var_name]
+
+        # Extract referenced variables from the raw value
+        # Handle string values with {{ var.* }} patterns
+        if isinstance(raw_value, str):
+            for match in pattern.finditer(raw_value):
+                referenced_var = match.group(1)
+                if referenced_var not in expanded:
+                    expanded.add(referenced_var)
+                    to_process.append(referenced_var)
+        # Handle { read: filepath } variables - check file contents for variable references
+        elif isinstance(raw_value, dict) and 'read' in raw_value:
+            filepath = raw_value['read']
+            # For dependency expansion, we speculatively read files to find variable references
+            # This is acceptable because file reads are relatively cheap compared to eval commands
+            try:
+                # Try to read the file (may not exist yet, which is fine for dependency tracking)
+                # Skip if filepath is None or empty (validation error will be caught during evaluation)
+                if filepath and isinstance(filepath, str):
+                    from pathlib import Path
+                    if Path(filepath).exists():
+                        file_content = Path(filepath).read_text()
+                        # Extract variable references from file content
+                        for match in pattern.finditer(file_content):
+                            referenced_var = match.group(1)
+                            if referenced_var not in expanded:
+                                expanded.add(referenced_var)
+                                to_process.append(referenced_var)
+            except (IOError, OSError, TypeError):
+                # If file can't be read during expansion, that's okay
+                # The error will be caught during actual evaluation
+                pass
+        # Handle { env: VAR, default: ... } variables - check default value for variable references
+        elif isinstance(raw_value, dict) and 'env' in raw_value and 'default' in raw_value:
+            default_value = raw_value['default']
+            # Check if default value contains variable references
+            if isinstance(default_value, str):
+                for match in pattern.finditer(default_value):
+                    referenced_var = match.group(1)
+                    if referenced_var not in expanded:
+                        expanded.add(referenced_var)
+                        to_process.append(referenced_var)
+
+    return expanded
+
+
+def _evaluate_variable_subset(
+    raw_variables: dict[str, Any],
+    variable_names: set[str],
+    file_path: Path,
+    data: dict
+) -> dict[str, str]:
+    """Evaluate only specified variables from raw specs (for lazy evaluation).
+
+    This function is similar to _parse_variables_section but only evaluates
+    a subset of variables. This enables lazy evaluation where only reachable
+    variables are evaluated, improving performance and security.
+
+    Transitive dependencies are automatically included: if variable A references
+    variable B, both will be evaluated even if only A was explicitly requested.
+
+    Args:
+        raw_variables: Raw variable definitions from YAML (not yet evaluated)
+        variable_names: Set of variable names to evaluate
+        file_path: Recipe file path (for relative file resolution)
+        data: Full YAML data (for context in _resolve_variable_value)
+
+    Returns:
+        Dictionary of evaluated variable values (for specified variables and their dependencies)
+
+    Raises:
+        ValueError: For validation errors, undefined refs, or circular refs
+
+    Example:
+        >>> raw_vars = {"a": "{{ var.b }}", "b": "value", "c": "unused"}
+        >>> _evaluate_variable_subset(raw_vars, {"a"}, path, data)
+        {"a": "value", "b": "value"}  # "a" and its dependency "b", but not "c"
+    """
+    if not isinstance(raw_variables, dict):
+        raise ValueError("'variables' must be a dictionary")
+
+    # Expand variable set to include transitive dependencies
+    variables_to_eval = _expand_variable_dependencies(variable_names, raw_variables)
+
+    resolved = {}  # name -> resolved string value
+    resolution_stack = []  # For circular detection
+
+    # Evaluate variables in order (to handle references between variables)
+    for var_name, raw_value in raw_variables.items():
+        if var_name in variables_to_eval:
+            _validate_variable_name(var_name)
+            resolved[var_name] = _resolve_variable_value(
+                var_name, raw_value, resolved, resolution_stack, file_path, data
+            )
+
+    return resolved
+
+
 def _parse_file_with_env(
     file_path: Path,
     namespace: str | None,
     project_root: Path,
     import_stack: list[Path] | None = None,
-) -> tuple[dict[str, Task], dict[str, Environment], str, dict[str, str]]:
+) -> tuple[dict[str, Task], dict[str, Environment], str, dict[str, Any], dict[str, Any]]:
     """Parse file and extract tasks, environments, and variables.
 
     Args:
@@ -865,7 +1128,8 @@ def _parse_file_with_env(
         import_stack: Stack of files being imported (for circular detection)
 
     Returns:
-        Tuple of (tasks, environments, default_env_name, variables)
+        Tuple of (tasks, environments, default_env_name, raw_variables, yaml_data)
+        Note: Variables are NOT evaluated here - they're stored as raw specs for lazy evaluation
     """
     # Parse tasks normally
     tasks = _parse_file(file_path, namespace, project_root, import_stack)
@@ -873,29 +1137,23 @@ def _parse_file_with_env(
     # Load YAML again to extract environments and variables (only from root file)
     environments: dict[str, Environment] = {}
     default_env = ""
-    variables: dict[str, str] = {}
+    raw_variables: dict[str, Any] = {}
+    yaml_data: dict[str, Any] = {}
 
     # Only parse environments and variables from the root file (namespace is None)
     if namespace is None:
         with open(file_path, "r") as f:
             data = yaml.safe_load(f)
+            yaml_data = data or {}
 
-        # Parse variables first (so they can be used in environment preambles and tasks)
-        if data:
-            variables = _parse_variables_section(data, file_path)
-
-        # Apply variable substitution to all tasks
-        if variables:
-            from tasktree.substitution import substitute_variables
+        # Store raw variable specs WITHOUT evaluating them (lazy evaluation)
+        # Variable evaluation will happen later in Recipe.evaluate_variables()
+        if data and "variables" in data:
+            raw_variables = data["variables"]
 
-            for task in tasks.values():
-                task.cmd = substitute_variables(task.cmd, variables)
-                task.desc = substitute_variables(task.desc, variables)
-                task.working_dir = substitute_variables(task.working_dir, variables)
-                task.inputs = [substitute_variables(inp, variables) for inp in task.inputs]
-                task.outputs = [substitute_variables(out, variables) for out in task.outputs]
-                # Substitute in argument default values (in arg spec strings)
-                task.args = [substitute_variables(arg, variables) for arg in task.args]
+        # SKIP variable substitution here - defer to lazy evaluation phase
+        # Tasks and environments will contain {{ var.* }} placeholders until evaluation
+        # This allows us to only evaluate variables that are actually reachable from the target task
 
         if data and "environments" in data:
             env_data = data["environments"]
@@ -919,10 +1177,8 @@ def _parse_file_with_env(
                     preamble = env_config.get("preamble", "")
                     working_dir = env_config.get("working_dir", "")
 
-                    # Substitute variables in preamble
-                    if preamble and variables:
-                        from tasktree.substitution import substitute_variables
-                        preamble = substitute_variables(preamble, variables)
+                    # SKIP variable substitution in preamble - defer to lazy evaluation
+                    # preamble may contain {{ var.* }} placeholders
 
                     # Parse Docker-specific fields
                     dockerfile = env_config.get("dockerfile", "")
@@ -933,6 +1189,9 @@ def _parse_file_with_env(
                     extra_args = env_config.get("extra_args", [])
                     run_as_root = env_config.get("run_as_root", False)
 
+                    # SKIP variable substitution in environment fields - defer to lazy evaluation
+                    # Environment fields may contain {{ var.* }} placeholders
+
                     # Validate environment type
                     if not shell and not dockerfile:
                         raise ValueError(
@@ -989,19 +1248,180 @@ def _parse_file_with_env(
                         run_as_root=run_as_root
                     )
 
-    return tasks, environments, default_env, variables
+    return tasks, environments, default_env, raw_variables, yaml_data
+
+
+def collect_reachable_tasks(tasks: dict[str, Task], root_task: str) -> set[str]:
+    """Collect all tasks reachable from the root task via dependencies.
 
+    Uses BFS to traverse the dependency graph and collect all task names
+    that could potentially be executed when running the root task.
+
+    Args:
+        tasks: Dictionary mapping task names to Task objects
+        root_task: Name of the root task to start traversal from
+
+    Returns:
+        Set of task names reachable from root_task (includes root_task itself)
+
+    Raises:
+        ValueError: If root_task doesn't exist
 
-def parse_recipe(recipe_path: Path, project_root: Path | None = None) -> Recipe:
+    Example:
+        >>> tasks = {"a": Task("a", deps=["b"]), "b": Task("b", deps=[]), "c": Task("c", deps=[])}
+        >>> collect_reachable_tasks(tasks, "a")
+        {"a", "b"}
+    """
+    if root_task not in tasks:
+        raise ValueError(f"Root task '{root_task}' not found in recipe")
+
+    reachable = set()
+    queue = [root_task]
+
+    while queue:
+        task_name = queue.pop(0)
+
+        if task_name in reachable:
+            continue  # Already processed
+
+        reachable.add(task_name)
+
+        # Get task and process its dependencies
+        task = tasks.get(task_name)
+        if task is None:
+            # Task not found - will be caught during graph construction
+            continue
+
+        # Add dependency task names to queue
+        for dep_spec in task.deps:
+            # Extract task name from dependency specification
+            if isinstance(dep_spec, str):
+                dep_name = dep_spec
+            elif isinstance(dep_spec, dict) and len(dep_spec) == 1:
+                dep_name = next(iter(dep_spec.keys()))
+            else:
+                # Invalid format - will be caught during graph construction
+                continue
+
+            if dep_name not in reachable:
+                queue.append(dep_name)
+
+    return reachable
+
+
+def collect_reachable_variables(
+    tasks: dict[str, Task],
+    reachable_task_names: set[str]
+) -> set[str]:
+    """Extract variable names used by reachable tasks.
+
+    Searches for {{ var.* }} placeholders in task definitions to determine
+    which variables are actually needed for execution.
+
+    Args:
+        tasks: Dictionary mapping task names to Task objects
+        reachable_task_names: Set of task names that will be executed
+
+    Returns:
+        Set of variable names referenced by reachable tasks
+
+    Example:
+        >>> task = Task("build", cmd="echo {{ var.version }}")
+        >>> collect_reachable_variables({"build": task}, {"build"})
+        {"version"}
+    """
+    import re
+
+    # Pattern to match {{ var.name }}
+    var_pattern = re.compile(r'\{\{\s*var\s*\.\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}')
+
+    variables = set()
+
+    for task_name in reachable_task_names:
+        task = tasks.get(task_name)
+        if task is None:
+            continue
+
+        # Search in command
+        if task.cmd:
+            for match in var_pattern.finditer(task.cmd):
+                variables.add(match.group(1))
+
+        # Search in description
+        if task.desc:
+            for match in var_pattern.finditer(task.desc):
+                variables.add(match.group(1))
+
+        # Search in working_dir
+        if task.working_dir:
+            for match in var_pattern.finditer(task.working_dir):
+                variables.add(match.group(1))
+
+        # Search in inputs
+        if task.inputs:
+            for input_pattern in task.inputs:
+                for match in var_pattern.finditer(input_pattern):
+                    variables.add(match.group(1))
+
+        # Search in outputs
+        if task.outputs:
+            for output_pattern in task.outputs:
+                for match in var_pattern.finditer(output_pattern):
+                    variables.add(match.group(1))
+
+        # Search in argument defaults
+        if task.args:
+            for arg_spec in task.args:
+                if isinstance(arg_spec, dict):
+                    for arg_dict in arg_spec.values():
+                        if isinstance(arg_dict, dict) and "default" in arg_dict:
+                            default = arg_dict["default"]
+                            if isinstance(default, str):
+                                for match in var_pattern.finditer(default):
+                                    variables.add(match.group(1))
+
+        # Search in dependency argument templates
+        if task.deps:
+            for dep_spec in task.deps:
+                if isinstance(dep_spec, dict):
+                    for arg_spec in dep_spec.values():
+                        # Positional args (list)
+                        if isinstance(arg_spec, list):
+                            for val in arg_spec:
+                                if isinstance(val, str):
+                                    for match in var_pattern.finditer(val):
+                                        variables.add(match.group(1))
+                        # Named args (dict)
+                        elif isinstance(arg_spec, dict):
+                            for val in arg_spec.values():
+                                if isinstance(val, str):
+                                    for match in var_pattern.finditer(val):
+                                        variables.add(match.group(1))
+
+    return variables
+
+
+def parse_recipe(
+    recipe_path: Path,
+    project_root: Path | None = None,
+    root_task: str | None = None
+) -> Recipe:
     """Parse a recipe file and handle imports recursively.
 
+    This function now implements lazy variable evaluation: if root_task is provided,
+    only variables reachable from that task will be evaluated. This provides significant
+    performance and security benefits for recipes with many variables.
+
     Args:
         recipe_path: Path to the main recipe file
         project_root: Optional project root directory. If not provided, uses recipe file's parent directory.
                      When using --tasks option, this should be the current working directory.
+        root_task: Optional root task for lazy variable evaluation. If provided, only variables
+                  used by tasks reachable from root_task will be evaluated (optimization).
+                  If None, all variables will be evaluated (for --list command compatibility).
 
     Returns:
-        Recipe object with all tasks (including recursively imported tasks)
+        Recipe object with all tasks (including recursively imported tasks) and evaluated variables
 
     Raises:
         FileNotFoundError: If recipe file doesn't exist
@@ -1017,19 +1437,32 @@ def parse_recipe(recipe_path: Path, project_root: Path | None = None) -> Recipe:
         project_root = recipe_path.parent
 
     # Parse main file - it will recursively handle all imports
-    tasks, environments, default_env, variables = _parse_file_with_env(
+    # Variables are NOT evaluated here (lazy evaluation)
+    tasks, environments, default_env, raw_variables, yaml_data = _parse_file_with_env(
         recipe_path, namespace=None, project_root=project_root
     )
 
-    return Recipe(
+    # Create recipe with raw (unevaluated) variables
+    recipe = Recipe(
         tasks=tasks,
         project_root=project_root,
         recipe_path=recipe_path,
         environments=environments,
         default_env=default_env,
-        variables=variables,
+        variables={},  # Empty initially (deprecated field)
+        raw_variables=raw_variables,
+        evaluated_variables={},  # Empty initially
+        _variables_evaluated=False,
+        _original_yaml_data=yaml_data
     )
 
+    # Trigger lazy variable evaluation
+    # If root_task is provided: evaluate only reachable variables
+    # If root_task is None: evaluate all variables (for --list)
+    recipe.evaluate_variables(root_task)
+
+    return recipe
+
 
 def _parse_file(
     file_path: Path,

tasktree/substitution.py

@@ -48,6 +48,11 @@ def substitute_variables(text: str | dict[str, Any], variables: dict[str, str])
         else:
             raise ValueError("Empty arg dictionary")
     else:
+        # If not a string (e.g., int, float, bool, None), return unchanged
+        # This handles cases like: default: 5, min: 0, choices: [1, 2, 3]
+        if not isinstance(text, str):
+            return text
+
         def replace_match(match: re.Match) -> str:
             prefix = match.group(1)
             name = match.group(2)
@@ -195,6 +200,75 @@ def substitute_builtin_variables(text: str, builtin_vars: dict[str, str]) -> str
     return PLACEHOLDER_PATTERN.sub(replace_match, text)
 
 
+def substitute_dependency_args(
+    template_value: str,
+    parent_task_name: str,
+    parent_args: dict[str, Any],
+    exported_args: set[str] | None = None
+) -> str:
+    """Substitute {{ arg.* }} templates in dependency argument values.
+
+    This function substitutes parent task's arguments into dependency argument
+    templates. Only {{ arg.* }} placeholders are allowed in dependency arguments.
+
+    Args:
+        template_value: String that may contain {{ arg.* }} placeholders
+        parent_task_name: Name of parent task (for error messages)
+        parent_args: Parent task's argument values
+        exported_args: Set of parent's exported argument names
+
+    Returns:
+        String with {{ arg.* }} placeholders substituted
+
+    Raises:
+        ValueError: If template references undefined arg, uses exported arg,
+                   or contains non-arg placeholders ({{ var.* }}, {{ env.* }}, {{ tt.* }})
+
+    Example:
+        >>> substitute_dependency_args("{{ arg.mode }}", "build", {"mode": "debug"})
+        'debug'
+    """
+    # Check for disallowed placeholder types in dependency args
+    # Only {{ arg.* }} is allowed, not {{ var.* }}, {{ env.* }}, or {{ tt.* }}
+    for match in PLACEHOLDER_PATTERN.finditer(template_value):
+        prefix = match.group(1)
+        name = match.group(2)
+
+        if prefix == "var":
+            raise ValueError(
+                f"Task '{parent_task_name}': dependency argument contains {{ var.{name} }}\n"
+                f"Template: {template_value}\n\n"
+                f"Variables ({{ var.* }}) are not allowed in dependency arguments.\n"
+                f"Variables are substituted at parse time, use them directly in task definitions.\n"
+                f"In dependency arguments, only {{ arg.* }} templates are supported."
+            )
+        elif prefix == "env":
+            raise ValueError(
+                f"Task '{parent_task_name}': dependency argument contains {{ env.{name} }}\n"
+                f"Template: {template_value}\n\n"
+                f"Environment variables ({{ env.* }}) are not allowed in dependency arguments.\n"
+                f"In dependency arguments, only {{ arg.* }} templates are supported."
+            )
+        elif prefix == "tt":
+            raise ValueError(
+                f"Task '{parent_task_name}': dependency argument contains {{ tt.{name} }}\n"
+                f"Template: {template_value}\n\n"
+                f"Built-in variables ({{ tt.* }}) are not allowed in dependency arguments.\n"
+                f"In dependency arguments, only {{ arg.* }} templates are supported."
+            )
+
+    # Substitute {{ arg.* }} using parent's arguments
+    try:
+        return substitute_arguments(template_value, parent_args, exported_args)
+    except ValueError as e:
+        # Re-raise with more context
+        raise ValueError(
+            f"Task '{parent_task_name}': error in dependency argument substitution\n"
+            f"Template: {template_value}\n"
+            f"Error: {str(e)}"
+        ) from e
+
+
 def substitute_all(text: str, variables: dict[str, str], args: dict[str, Any]) -> str:
     """Substitute all placeholder types: variables, arguments, environment.
 

{tasktree-0.0.14.dist-info → tasktree-0.0.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.14
+Version: 0.0.16
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0

tasktree-0.0.16.dist-info/RECORD

@@ -0,0 +1,14 @@
+tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
+tasktree/cli.py,sha256=Uhv0RNFrogjvqxBYKYIfxEPd0SdYAIpXH7SPGIxQnmk,20136
+tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
+tasktree/executor.py,sha256=QQcABThmof0MLTtwpJKpyqh80hr3YRIqqs3NZ-Ry-Bk,44873
+tasktree/graph.py,sha256=yITp71RfhJ7sdC-2zRf89SHYZqQyF3XVAnaqX-XnMdE,15821
+tasktree/hasher.py,sha256=0GrnCfwAXnwq_kpnHFFb12B5_2VFNXx6Ng7hTdcCyXo,4415
+tasktree/parser.py,sha256=yOe6G1Fg2FqmEjaPD73FD2aiYP9sZisTx1DZPofx9wc,87049
+tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
+tasktree/substitution.py,sha256=qG7SyEHn1PAKteWA0AgA1dUNbJfwQTupCLRq9FvOBD0,10724
+tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
+tasktree-0.0.16.dist-info/METADATA,sha256=ssKlllByyOeVMGDuHa11XLDhcGoxPfepRRoO776A_Ig,37234
+tasktree-0.0.16.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.16.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.16.dist-info/RECORD,,

tasktree/tasks.py

@@ -1,8 +0,0 @@
-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-0.0.14.dist-info/RECORD

@@ -1,15 +0,0 @@
-tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
-tasktree/cli.py,sha256=ywaLXEehOHcMsBioL4RxPQ1vTWIG1V7Hb0TZ1YI2F_g,18820
-tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
-tasktree/executor.py,sha256=Q7Bks5B88i-IyZDpxGSps9MM3uflz0U3yn4Rtq_uHMM,42266
-tasktree/graph.py,sha256=oXLxX0Ix4zSkVBg8_3x9K7WxSFpg136sp4MF-d2mDEQ,9682
-tasktree/hasher.py,sha256=0GrnCfwAXnwq_kpnHFFb12B5_2VFNXx6Ng7hTdcCyXo,4415
-tasktree/parser.py,sha256=XdFuELqrrhHc45HeMpo6-gflopZM7kYTqO1lQcFwtFk,68782
-tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
-tasktree/substitution.py,sha256=UAq69YO4uGkvFfd5mtGy6CwFZ_uxZGf4HGpnvCBVBuc,7499
-tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
-tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
-tasktree-0.0.14.dist-info/METADATA,sha256=JnlgocAOtAq_Q-vWrOkYM6mofrCeH8xiGFKYqaQmX4M,37234
-tasktree-0.0.14.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.14.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.14.dist-info/RECORD,,