Skip to content

💫 Toolkit to help you get started with SDD or any other process!

3.5 KB
Raw Blame
"""Workflow overlay resolver."""

from __future__ import annotations

from pathlib import Path

from ..engine import WorkflowDefinition
from .composer import StepListComposer
from .layer_sources import (
    BaseWorkflowSource,
    Layer,
    ProjectOverlaySource,
)
from .merge import ComposedStep
from .schema import _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN


def _validate_workflow_id(workflow_id: str) -> None:
    """Reject workflow IDs that are unsafe as installed-storage path segments."""
    if (
        not isinstance(workflow_id, str)
        or not _SAFE_ID_PATTERN.fullmatch(workflow_id)
        or workflow_id in _RESERVED_WORKFLOW_IDS
    ):
        raise ValueError(f"Invalid workflow ID: {workflow_id!r}")


class WorkflowResolver:
    """Resolves a workflow ID to its composed ``WorkflowDefinition``.

    Collects layers from two tiers:
    - project-local overlays (``.specify/workflows/overlays/<id>/*.yml``)
    - the base workflow itself (``.specify/workflows/<id>/workflow.yml``)

    Resolution is lower-wins: overlays with lower priority numbers are applied
    later and override earlier edits on the same anchors.
    """

    def __init__(self, project_root: Path) -> None:
        self.project_root = project_root
        self._sources = [
            ProjectOverlaySource(project_root),
            BaseWorkflowSource(project_root),
        ]
        self._composer = StepListComposer()

    def collect_all_layers(
        self, workflow_id: str, *, include_disabled: bool = False
    ) -> list[Layer]:
        """Collect overlays sorted by precedence, followed by the base layer.

        Lower priority numbers win. Ties are sorted alphabetically by source,
        matching ``PresetRegistry.list_by_priority()``. The base workflow is a
        foundation rather than a precedence candidate, so it is kept separate.
        """
        _validate_workflow_id(workflow_id)

        all_layers: list[Layer] = []
        for source in self._sources:
            all_layers.extend(
                source.collect(workflow_id, include_disabled=include_disabled)
            )

        overlays = [layer for layer in all_layers if layer.tier != "base"]
        base_layers = [layer for layer in all_layers if layer.tier == "base"]
        return (
            sorted(overlays, key=lambda layer: (layer.priority, layer.source))
            + base_layers
        )

    def resolve(self, workflow_id: str) -> WorkflowDefinition:
        """Resolve a workflow ID to its composed definition.

        This method composes layers but does not validate workflow semantics;
        callers should validate the returned definition when needed.

        Raises:
            FileNotFoundError: if the workflow cannot be found.
            ValueError: if layer collection/composition fails.
        """
        layers = self.collect_all_layers(workflow_id)
        definition, _ = self._composer.compose(layers)
        if definition is None:
            raise FileNotFoundError(f"Workflow not found: {workflow_id}")
        return definition

    def resolve_with_layers(
        self, workflow_id: str
    ) -> tuple[WorkflowDefinition, list[Layer], list[ComposedStep]]:
        """Resolve a workflow and return its definition plus layer attribution."""
        layers = self.collect_all_layers(workflow_id)
        definition, attribution = self._composer.compose(layers)
        if definition is None:
            raise FileNotFoundError(f"Workflow not found: {workflow_id}")
        return definition, layers, attribution