💫 Toolkit to help you get started with SDD or any other process!
"""Workflow overlay layer sources."""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
import yaml
from .schema import Overlay, _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN, validate_overlay_yaml
@dataclass
class Layer:
"""A single layer in the workflow overlay stack."""
content: Overlay
source: str
tier: str
priority: int
path: Path | None = None
class OverlayLoadError(ValueError):
"""Raised when an overlay file cannot be loaded or validated."""
def __init__(self, path: Path, errors: list[str]) -> None:
self.path = path
self.errors = errors
super().__init__(f"Invalid overlay {path}:\n - " + "\n - ".join(errors))
def _validate_workflow_id(workflow_id: str, context_path: Path) -> None:
"""Raise OverlayLoadError if workflow_id is not a safe path-segment identifier.
Mirrors the same check performed by WorkflowResolver so layer sources are
safe to call directly, without going through the resolver.
"""
if (
not isinstance(workflow_id, str)
or not _SAFE_ID_PATTERN.fullmatch(workflow_id)
or workflow_id in _RESERVED_WORKFLOW_IDS
):
raise OverlayLoadError(
context_path,
[f"Invalid workflow ID: {workflow_id!r}"],
)
def _ensure_contained_dir(path: Path, root: Path) -> None:
"""Raise OverlayLoadError if *path* is a symlink, a non-directory, or escapes *root*.
Mirrors the logic of ``_ensure_contained_dir`` in ``overlays/_commands.py``
but raises ``OverlayLoadError`` instead of ``typer.Exit`` so layer sources
can enforce the same invariants without a CLI dependency.
The caller is responsible for ensuring *root* itself is already validated
(e.g. via ``_resolve_project_overlay_root``).
"""
if path.is_symlink():
raise OverlayLoadError(path, ["Symlinked overlay directories are not allowed"])
if path.exists() and not path.is_dir():
raise OverlayLoadError(path, ["Overlay directory path is not a directory"])
try:
path.resolve().relative_to(root.resolve())
except ValueError:
raise OverlayLoadError(
path, ["Path traversal detected: directory escapes allowed root"]
) from None
def _resolve_workflows_root(project_root: Path) -> Path:
"""Return the workflow storage root after rejecting unsafe ancestors."""
project_root_resolved = project_root.resolve()
workflows_root = project_root / ".specify" / "workflows"
current = project_root
for part in (".specify", "workflows"):
current = current / part
if current.is_symlink():
raise OverlayLoadError(
current,
[f"Symlinked workflow directories are not allowed ({current})"],
)
if current.exists() and not current.is_dir():
raise OverlayLoadError(
current,
[f"Workflow directory path is not a directory ({current})"],
)
try:
workflows_root.resolve().relative_to(project_root_resolved)
except ValueError:
raise OverlayLoadError(
workflows_root,
["Workflow directory escapes the project root"],
) from None
return workflows_root
def _resolve_project_overlay_root(project_root: Path) -> Path:
"""Return the unresolved overlay root after rejecting unsafe ancestors."""
workflows_root = _resolve_workflows_root(project_root)
overlays_root = workflows_root / "overlays"
if overlays_root.is_symlink():
raise OverlayLoadError(
overlays_root,
[f"Symlinked overlay directories are not allowed ({overlays_root})"],
)
if overlays_root.exists() and not overlays_root.is_dir():
raise OverlayLoadError(
overlays_root,
[f"Overlay directory path is not a directory ({overlays_root})"],
)
return overlays_root
class ProjectOverlaySource:
"""Project-local overlays: ``.specify/workflows/overlays/<id>/*.yml``."""
tier = "project-overlay"
def __init__(self, project_root: Path) -> None:
self.project_root = project_root
self.overlays_dir = project_root / ".specify" / "workflows" / "overlays"
def collect(self, workflow_id: str, *, include_disabled: bool = False) -> list[Layer]:
"""Collect project-local overlays for the given workflow id.
Args:
workflow_id: Workflow identifier whose overlay directory to scan.
include_disabled: When True, return disabled overlays for
management/list views. Resolution paths keep the default False.
"""
self.overlays_dir = _resolve_project_overlay_root(self.project_root)
_validate_workflow_id(workflow_id, self.overlays_dir)
workflow_overlay_dir = self.overlays_dir / workflow_id
_ensure_contained_dir(workflow_overlay_dir, self.overlays_dir)
if not workflow_overlay_dir.is_dir():
return []
layers: list[Layer] = []
overlay_paths_by_id: dict[str, Path] = {}
try:
entries = sorted(workflow_overlay_dir.iterdir())
except OSError as exc:
raise OverlayLoadError(
workflow_overlay_dir, [f"Cannot enumerate overlays: {exc}"]
) from exc
for path in entries:
if not path.is_file() or path.suffix not in (".yml", ".yaml"):
continue
if path.is_symlink():
raise OverlayLoadError(path, ["Symlinked overlay files are not allowed"])
try:
text = path.read_text(encoding="utf-8")
# ``safe_load`` returns None for BOTH an empty document and an
# explicit null scalar (``null``, ``~``, ``Null``, ``NULL``), so
# it cannot tell them apart on its own. ``compose`` yields no
# node only for a genuinely empty document.
is_empty_document = yaml.compose(text) is None
data = yaml.safe_load(text)
except yaml.YAMLError as exc:
raise OverlayLoadError(path, [f"Invalid YAML: {exc}"]) from exc
except (OSError, UnicodeDecodeError) as exc:
raise OverlayLoadError(path, [f"Cannot load overlay: {exc}"]) from exc
# Only a genuinely EMPTY document becomes an empty mapping, so its
# missing-field errors are reported. Every non-mapping document --
# including an explicit ``null``/``~`` and the falsy shapes ``[]``,
# ``false``, ``0``, ``''`` that the previous ``or {}`` masked -- must
# reach ``validate_overlay_yaml`` unchanged so it reports the wrong
# manifest shape, like the truthy twins (``- a``, ``hello``) already
# do. The sibling reader for these same files, ``_read_overlay`` in
# overlays/_commands.py, does not coerce either.
if is_empty_document:
data = {}
if (
not include_disabled
and isinstance(data, dict)
and data.get("enabled", True) is False
):
continue
overlay, errors = validate_overlay_yaml(data)
if overlay is None or errors:
raise OverlayLoadError(path, errors)
if overlay.extends != workflow_id:
raise OverlayLoadError(
path,
[
f"Overlay extends {overlay.extends!r}, but is stored under "
f"workflow {workflow_id!r}."
],
)
first_path = overlay_paths_by_id.get(overlay.id)
if first_path is not None:
raise OverlayLoadError(
path,
[
f"Duplicate overlay id {overlay.id!r}; also declared in "
f"{first_path}."
],
)
overlay_paths_by_id[overlay.id] = path
layers.append(
Layer(
content=overlay,
source=f"project:{overlay.id}",
tier=self.tier,
priority=overlay.priority,
path=path,
)
)
return layers
class BaseWorkflowSource:
"""Base workflow layer: ``.specify/workflows/<id>/workflow.yml``."""
tier = "base"
def __init__(self, project_root: Path) -> None:
self.project_root = project_root
self.workflows_dir = project_root / ".specify" / "workflows"
def collect(self, workflow_id: str, *, include_disabled: bool = False) -> list[Layer]:
"""Return the base workflow as a single layer if it exists."""
self.workflows_dir = _resolve_workflows_root(self.project_root)
_validate_workflow_id(workflow_id, self.workflows_dir)
workflow_dir = self.workflows_dir / workflow_id
_ensure_contained_dir(workflow_dir, self.workflows_dir)
path = workflow_dir / "workflow.yml"
if path.is_symlink():
raise OverlayLoadError(path, ["Symlinked workflow files are not allowed"])
if not path.is_file():
return []
# The base layer is represented by an Overlay with empty edits.
overlay = Overlay(
id=workflow_id,
extends=workflow_id,
priority=0,
edits=[],
)
return [
Layer(
content=overlay,
source="base",
tier=self.tier,
priority=0,
path=path,
)
]