Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

3.3 KB
Raw Blame
"""Namespace construction and dot-path resolution for workflow expressions.

Leaf module: no dependencies on the evaluator, the filters, or the
diagnostics. ``_INDEXED_SEGMENT`` is the one definition of an indexed path
segment; both ``_resolve_dot_path`` and the condition diagnostics read it from
here so widening what indexing accepts cannot leave them disagreeing.
"""

from __future__ import annotations

import re
from typing import Any


# The one definition of an indexed path segment. _resolve_dot_path matches
# against it, and the condition gate below reuses it rather than describing the
# same shape a second time, so widening what indexing accepts cannot leave the
# evaluator and the gate disagreeing.
_INDEXED_SEGMENT = re.compile(r"^([\w-]+)\[(-?\d+)\]$")

_PLAIN_SEGMENT = re.compile(r"^[\w-]+$")


def _resolve_dot_path(obj: Any, path: str) -> Any:
    """Resolve a dotted path like ``steps.specify.output.file`` against *obj*.

    Supports dict key access and list indexing, including the negative form
    Python and Jinja2 both accept (e.g., ``task_list[0]``, ``task_list[-1]``).
    """
    parts = path.split(".")
    current = obj
    for part in parts:
        # Handle list indexing: name[0], name[-1]
        idx_match = _INDEXED_SEGMENT.match(part)
        if idx_match:
            key, idx = idx_match.group(1), int(idx_match.group(2))
            if isinstance(current, dict):
                current = current.get(key)
            else:
                return None
            if isinstance(current, list) and -len(current) <= idx < len(current):
                current = current[idx]
            else:
                return None
        elif isinstance(current, dict):
            current = current.get(part)
        else:
            return None
        if current is None:
            return None
    return current


def _build_namespace(context: Any) -> dict[str, Any]:
    """Build the variable namespace from a StepContext."""
    ns: dict[str, Any] = {}
    if hasattr(context, "inputs"):
        ns["inputs"] = context.inputs or {}
    if hasattr(context, "steps"):
        ns["steps"] = context.steps or {}
    if hasattr(context, "item"):
        ns["item"] = context.item
    if hasattr(context, "fan_in"):
        ns["fan_in"] = context.fan_in or {}
    # Engine-managed runtime metadata. Always present (even outside a
    # run) so templates referencing it never error: `run_id` falls back
    # to an empty string when no run is active (dry-run, validation,
    # ad-hoc evaluator usage). The value is the same one Spec Kit
    # prints as `Run ID:` at the end of `workflow run` β€” auto-generated
    # runs use an 8-character uuid4 hex; operator-supplied ids may be
    # any alphanumeric string with hyphens or underscores.
    run_id = getattr(context, "run_id", None) or ""
    workflow_dir = getattr(context, "workflow_dir", None) or ""
    ns["context"] = {"run_id": run_id, "workflow_dir": workflow_dir}
    return ns


# The roots _build_namespace supplies. A reference to anything else resolves to
# None, so a correction built on one turns a truthy condition false.
_NAMESPACE_ROOTS = ("inputs", "steps", "item", "fan_in", "context")


def _is_path_segment(segment: str) -> bool:
    """Whether _resolve_dot_path can walk *segment*: a name, or a name it indexes."""
    return bool(_PLAIN_SEGMENT.match(segment) or _INDEXED_SEGMENT.match(segment))