devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/architecture.py

@@ -0,0 +1,469 @@
+"""Declared architecture manifests for Greenfield specifications.
+
+DevFlow validates the structure and internal consistency of a manifest.
+It does not certify that the declared architecture is appropriate.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from devflow.core.artifacts.errors import ArtifactError
+from devflow.core.artifacts.store import ArtifactStore
+
+ARCHITECTURE_RELATIVE_PATH = Path(".devflow") / "architecture.yaml"
+SUPPORTED_MANIFEST_VERSIONS = (1,)
+MAX_MANIFEST_BYTES = 256_000
+
+
+class ArchitectureError(Exception):
+  """Raised when an architecture manifest is missing or invalid."""
+
+
+ARCHITECTURE_TEMPLATE = """\
+# DevFlow declared architecture manifest.
+# Edit this file before running a Greenfield specification.
+# DevFlow validates structure and internal consistency, not quality.
+version: 1
+style: ""
+summary: ""
+modules: []
+layers: []
+stack: {}
+constraints: {}
+quality_attributes: []
+fitness_functions: []
+"""
+
+
+@dataclass(frozen=True)
+class ArchitectureModule:
+  """A declared module or bounded context."""
+
+  name: str
+  responsibility: str
+  depends_on: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ArchitectureLayer:
+  """A declared architectural layer."""
+
+  name: str
+  may_depend_on: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ArchitectureManifest:
+  """A validated, reviewable declared architecture."""
+
+  path: Path
+  content: str
+  digest: str
+  version: int
+  style: str
+  summary: str
+  modules: tuple[ArchitectureModule, ...]
+  layers: tuple[ArchitectureLayer, ...]
+  stack: dict[str, tuple[str, ...]] = field(default_factory=dict)
+  constraints: dict[str, tuple[str, ...]] = field(default_factory=dict)
+  quality_attributes: tuple[str, ...] = ()
+  fitness_functions: tuple[str, ...] = ()
+  warnings: tuple[str, ...] = ()
+
+  def relative_path(self, root: Path) -> str:
+    """Return the manifest path relative to the project root."""
+    try:
+      return self.path.relative_to(root.resolve()).as_posix()
+    except ValueError:
+      return self.path.as_posix()
+
+  def render_appendix(self, root: Path) -> str:
+    """Render the declared manifest as a specification appendix."""
+    lines = [
+      "## Appendix A: Declared Architecture Manifest",
+      "",
+      "| Field | Value |",
+      "| --- | --- |",
+      f"| Manifest | `{self.relative_path(root)}` |",
+      f"| Digest | `{self.digest}` |",
+      f"| Version | `{self.version}` |",
+      f"| Style | {self.style} |",
+      "",
+      "The digest above identifies the exact manifest used to prepare "
+      "this specification. If the manifest changes, generate and approve "
+      "the specification again.",
+      "",
+      "```yaml",
+      self.content.rstrip(),
+      "```",
+      "",
+    ]
+    return "\n".join(lines)
+
+
+class ArchitectureManifestLoader:
+  """Load and structurally validate `.devflow/architecture.yaml`."""
+
+  def load(
+    self,
+    root: Path,
+    *,
+    required: bool,
+  ) -> ArchitectureManifest | None:
+    """Load the manifest if present, or fail when it is required."""
+    project_root = root.resolve()
+    path = project_root / ARCHITECTURE_RELATIVE_PATH
+
+    if path.is_symlink():
+      msg = (
+        "Architecture manifest must not be a symbolic link: "
+        f"{ARCHITECTURE_RELATIVE_PATH.as_posix()}"
+      )
+      raise ArchitectureError(msg)
+    if not path.is_file():
+      if required:
+        msg = (
+          "Greenfield mode requires a declared architecture manifest at "
+          f"{ARCHITECTURE_RELATIVE_PATH.as_posix()}. Run 'devflow init "
+          "--project-mode greenfield' to create a template, then edit it."
+        )
+        raise ArchitectureError(msg)
+      return None
+
+    store = ArtifactStore(project_root)
+    try:
+      content = store.read(path)
+      digest = store.digest_text(content)
+    except ArtifactError as error:
+      raise ArchitectureError(str(error)) from error
+
+    if len(content.encode("utf-8")) > MAX_MANIFEST_BYTES:
+      msg = (
+        "Architecture manifest is too large. Keep it below "
+        f"{MAX_MANIFEST_BYTES} bytes."
+      )
+      raise ArchitectureError(msg)
+
+    try:
+      data = yaml.safe_load(content)
+    except yaml.YAMLError as error:
+      msg = (
+        "Invalid YAML in architecture manifest "
+        f"{ARCHITECTURE_RELATIVE_PATH.as_posix()}: {error}"
+      )
+      raise ArchitectureError(msg) from error
+
+    if not isinstance(data, dict):
+      msg = "Architecture manifest must contain a mapping."
+      raise ArchitectureError(msg)
+
+    version = data.get("version")
+    if (
+      not isinstance(version, int)
+      or isinstance(version, bool)
+      or version not in SUPPORTED_MANIFEST_VERSIONS
+    ):
+      supported = ", ".join(
+        str(item) for item in SUPPORTED_MANIFEST_VERSIONS
+      )
+      msg = (
+        "architecture.version must be one of: "
+        f"{supported}. Found: {version!r}."
+      )
+      raise ArchitectureError(msg)
+
+    style = self._required_text(data.get("style"), "style")
+    summary = self._required_text(data.get("summary"), "summary")
+    modules = self._modules(data.get("modules"))
+    layers = self._layers(data.get("layers"))
+    stack = self._values_mapping(data.get("stack"), "stack")
+    constraints = self._values_mapping(
+      data.get("constraints"),
+      "constraints",
+    )
+    quality_attributes = self._text_list(
+      data.get("quality_attributes"),
+      "quality_attributes",
+    )
+    fitness_functions = self._text_list(
+      data.get("fitness_functions"),
+      "fitness_functions",
+    )
+
+    self._check_references(modules, layers)
+    warnings = self._cycles(modules, layers)
+
+    return ArchitectureManifest(
+      path=path,
+      content=content,
+      digest=digest,
+      version=version,
+      style=style,
+      summary=summary,
+      modules=modules,
+      layers=layers,
+      stack=stack,
+      constraints=constraints,
+      quality_attributes=quality_attributes,
+      fitness_functions=fitness_functions,
+      warnings=warnings,
+    )
+
+  def _required_text(self, value: Any, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+      msg = f"architecture.{field_name} must be a non-empty string."
+      raise ArchitectureError(msg)
+    return value.strip()
+
+  def _text_list(self, value: Any, field_name: str) -> tuple[str, ...]:
+    if value is None:
+      return ()
+    if not isinstance(value, list):
+      msg = f"architecture.{field_name} must be a list of strings."
+      raise ArchitectureError(msg)
+    items: list[str] = []
+    for item in value:
+      if not isinstance(item, str) or not item.strip():
+        msg = (
+          f"architecture.{field_name} entries must be non-empty "
+          "strings."
+        )
+        raise ArchitectureError(msg)
+      items.append(item.strip())
+    return tuple(items)
+
+  def _values_mapping(
+    self,
+    value: Any,
+    field_name: str,
+  ) -> dict[str, tuple[str, ...]]:
+    if value is None:
+      return {}
+    if not isinstance(value, dict):
+      msg = f"architecture.{field_name} must be a mapping."
+      raise ArchitectureError(msg)
+
+    result: dict[str, tuple[str, ...]] = {}
+    for key, item in value.items():
+      if not isinstance(key, str) or not key.strip():
+        msg = (
+          f"architecture.{field_name} keys must be non-empty strings."
+        )
+        raise ArchitectureError(msg)
+      result[key.strip()] = self._scalar_values(
+        item,
+        f"{field_name}.{key}",
+      )
+    return result
+
+  def _scalar_values(self, value: Any, field_name: str) -> tuple[str, ...]:
+    if isinstance(value, list):
+      values = value
+    else:
+      values = [value]
+    if not values:
+      msg = f"architecture.{field_name} must not be empty."
+      raise ArchitectureError(msg)
+
+    result: list[str] = []
+    for item in values:
+      if isinstance(item, bool) or not isinstance(
+        item,
+        (str, int, float),
+      ):
+        msg = (
+          f"architecture.{field_name} values must be strings or "
+          "numbers."
+        )
+        raise ArchitectureError(msg)
+      text = str(item).strip()
+      if not text:
+        msg = (
+          f"architecture.{field_name} values must not be empty."
+        )
+        raise ArchitectureError(msg)
+      result.append(text)
+    return tuple(result)
+
+  def _modules(self, value: Any) -> tuple[ArchitectureModule, ...]:
+    if value is None:
+      msg = "architecture.modules must declare at least one module."
+      raise ArchitectureError(msg)
+    if not isinstance(value, list) or not value:
+      msg = "architecture.modules must be a non-empty list."
+      raise ArchitectureError(msg)
+
+    modules: list[ArchitectureModule] = []
+    seen: set[str] = set()
+    for index, item in enumerate(value, start=1):
+      if not isinstance(item, dict):
+        msg = f"architecture.modules[{index}] must be a mapping."
+        raise ArchitectureError(msg)
+      name = self._required_text(
+        item.get("name"),
+        f"modules[{index}].name",
+      )
+      if name in seen:
+        msg = f"architecture.modules contains duplicate name: {name}."
+        raise ArchitectureError(msg)
+      seen.add(name)
+      responsibility = self._required_text(
+        item.get("responsibility"),
+        f"modules[{index}].responsibility",
+      )
+      depends_on = self._text_list(
+        item.get("depends_on"),
+        f"modules[{index}].depends_on",
+      )
+      modules.append(
+        ArchitectureModule(
+          name=name,
+          responsibility=responsibility,
+          depends_on=depends_on,
+        )
+      )
+    return tuple(modules)
+
+  def _layers(self, value: Any) -> tuple[ArchitectureLayer, ...]:
+    if value is None:
+      return ()
+    if not isinstance(value, list):
+      msg = "architecture.layers must be a list."
+      raise ArchitectureError(msg)
+
+    layers: list[ArchitectureLayer] = []
+    seen: set[str] = set()
+    for index, item in enumerate(value, start=1):
+      if not isinstance(item, dict):
+        msg = f"architecture.layers[{index}] must be a mapping."
+        raise ArchitectureError(msg)
+      name = self._required_text(
+        item.get("name"),
+        f"layers[{index}].name",
+      )
+      if name in seen:
+        msg = f"architecture.layers contains duplicate name: {name}."
+        raise ArchitectureError(msg)
+      seen.add(name)
+      may_depend_on = self._text_list(
+        item.get("may_depend_on"),
+        f"layers[{index}].may_depend_on",
+      )
+      layers.append(
+        ArchitectureLayer(
+          name=name,
+          may_depend_on=may_depend_on,
+        )
+      )
+    return tuple(layers)
+
+  def _check_references(
+    self,
+    modules: tuple[ArchitectureModule, ...],
+    layers: tuple[ArchitectureLayer, ...],
+  ) -> None:
+    module_names = {module.name for module in modules}
+    for module in modules:
+      unknown = sorted(set(module.depends_on) - module_names)
+      if unknown:
+        msg = (
+          f"architecture module '{module.name}' depends on unknown "
+          "module(s): " + ", ".join(unknown) + "."
+        )
+        raise ArchitectureError(msg)
+
+    layer_names = {layer.name for layer in layers}
+    for layer in layers:
+      unknown = sorted(set(layer.may_depend_on) - layer_names)
+      if unknown:
+        msg = (
+          f"architecture layer '{layer.name}' depends on unknown "
+          "layer(s): " + ", ".join(unknown) + "."
+        )
+        raise ArchitectureError(msg)
+
+  def _cycles(
+    self,
+    modules: tuple[ArchitectureModule, ...],
+    layers: tuple[ArchitectureLayer, ...],
+  ) -> tuple[str, ...]:
+    warnings: list[str] = []
+    module_cycles = _find_cycles(
+      {module.name: module.depends_on for module in modules}
+    )
+    for cycle in module_cycles:
+      warnings.append(
+        "architecture modules contain a dependency cycle: "
+        + " -> ".join(cycle)
+        + "."
+      )
+
+    layer_cycles = _find_cycles(
+      {layer.name: layer.may_depend_on for layer in layers}
+    )
+    for cycle in layer_cycles:
+      warnings.append(
+        "architecture layers contain a dependency cycle: "
+        + " -> ".join(cycle)
+        + "."
+      )
+    return tuple(warnings)
+
+
+def create_architecture_template(root: Path) -> Path | None:
+  """Create the Greenfield manifest template without overwriting files."""
+  project_root = root.resolve()
+  path = project_root / ARCHITECTURE_RELATIVE_PATH
+  if path.is_symlink():
+    msg = (
+      "Architecture manifest must not be a symbolic link: "
+      f"{ARCHITECTURE_RELATIVE_PATH.as_posix()}"
+    )
+    raise ArchitectureError(msg)
+  if path.exists():
+    return None
+
+  try:
+    ArtifactStore(project_root).write(path, ARCHITECTURE_TEMPLATE)
+  except ArtifactError as error:
+    raise ArchitectureError(str(error)) from error
+  return path
+
+
+def _find_cycles(graph: dict[str, tuple[str, ...]]) -> list[tuple[str, ...]]:
+  """Return one representative path per strongly connected cycle."""
+  visited: set[str] = set()
+  active: list[str] = []
+  active_set: set[str] = set()
+  cycles: list[tuple[str, ...]] = []
+  reported: set[frozenset[str]] = set()
+
+  def visit(node: str) -> None:
+    if node in active_set:
+      start = active.index(node)
+      cycle = tuple(active[start:] + [node])
+      key = frozenset(cycle[:-1])
+      if key and key not in reported:
+        reported.add(key)
+        cycles.append(cycle)
+      return
+    if node in visited:
+      return
+
+    visited.add(node)
+    active.append(node)
+    active_set.add(node)
+    for dependency in graph.get(node, ()):
+      if dependency in graph:
+        visit(dependency)
+    active.pop()
+    active_set.remove(node)
+
+  for node in graph:
+    visit(node)
+  return cycles

devflow/core/artifacts/__init__.py

@@ -0,0 +1,29 @@
+"""Artifact storage and lifecycle metadata."""
+
+from devflow.core.artifacts.errors import (
+  ArtifactError,
+  ArtifactNotFoundError,
+  ArtifactOutsideProjectError,
+  ArtifactWriteError,
+)
+from devflow.core.artifacts.models import (
+  ARTIFACT_SOURCES,
+  ARTIFACT_STATUSES,
+  ArtifactRecord,
+  ArtifactSource,
+  ArtifactStatus,
+)
+from devflow.core.artifacts.store import ArtifactStore
+
+__all__ = [
+  "ARTIFACT_SOURCES",
+  "ARTIFACT_STATUSES",
+  "ArtifactError",
+  "ArtifactNotFoundError",
+  "ArtifactOutsideProjectError",
+  "ArtifactRecord",
+  "ArtifactSource",
+  "ArtifactStatus",
+  "ArtifactStore",
+  "ArtifactWriteError",
+]

devflow/core/artifacts/errors.py

@@ -0,0 +1,19 @@
+"""Artifact-related errors."""
+
+from __future__ import annotations
+
+
+class ArtifactError(Exception):
+  """Raised when an artifact cannot be read, written or verified."""
+
+
+class ArtifactNotFoundError(ArtifactError):
+  """Raised when an expected artifact does not exist."""
+
+
+class ArtifactOutsideProjectError(ArtifactError):
+  """Raised when an artifact path escapes the project root."""
+
+
+class ArtifactWriteError(ArtifactError):
+  """Raised when an artifact cannot be written atomically."""

devflow/core/artifacts/models.py

@@ -0,0 +1,82 @@
+"""Artifact data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ArtifactStatus(str, Enum):
+  """Lifecycle state of a generated artifact."""
+
+  GENERATED = "generated"
+  VALIDATED = "validated"
+  APPROVED = "approved"
+  REJECTED = "rejected"
+  STALE = "stale"
+
+
+class ArtifactSource(str, Enum):
+  """Origin of an artifact."""
+
+  AGENT = "agent"
+  DETERMINISTIC = "deterministic"
+  EXISTING = "existing"
+  HUMAN = "human"
+  SYSTEM = "system"
+
+
+ARTIFACT_STATUSES = tuple(status.value for status in ArtifactStatus)
+ARTIFACT_SOURCES = tuple(source.value for source in ArtifactSource)
+
+
+@dataclass(frozen=True)
+class ArtifactRecord:
+  """Metadata for one stored artifact."""
+
+  kind: str
+  path: str
+  digest: str
+  status: str
+  source: str
+  version: int = 1
+  updated_at: str = ""
+  validated_at: str = ""
+  approved_at: str = ""
+  stale_at: str = ""
+  metadata: dict[str, Any] = field(default_factory=dict)
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "kind": self.kind,
+      "path": self.path,
+      "digest": self.digest,
+      "status": self.status,
+      "source": self.source,
+      "version": self.version,
+      "updated_at": self.updated_at,
+      "validated_at": self.validated_at,
+      "approved_at": self.approved_at,
+      "stale_at": self.stale_at,
+      "metadata": dict(self.metadata),
+    }
+
+  @classmethod
+  def from_dict(cls, data: dict[str, Any]) -> ArtifactRecord:
+    metadata = data.get("metadata") or {}
+    if not isinstance(metadata, dict):
+      metadata = {}
+    return cls(
+      kind=str(data["kind"]),
+      path=str(data["path"]),
+      digest=str(data["digest"]),
+      status=str(data["status"]),
+      source=str(data["source"]),
+      version=int(data.get("version", 1)),
+      updated_at=str(data.get("updated_at", "")),
+      validated_at=str(data.get("validated_at", "")),
+      approved_at=str(data.get("approved_at", "")),
+      stale_at=str(data.get("stale_at", "")),
+      metadata=metadata,
+    )