devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/constitution.py

@@ -0,0 +1,166 @@
+"""Loading the project constitution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from devflow.core.config import (
+  ConfigError,
+  DevFlowConfig,
+  validate_document_name,
+)
+from devflow.core.profile_manager import ProfileManager
+from devflow.models.profile import Profile
+
+
+class ConstitutionError(Exception):
+  """Raised when constitution documents cannot be loaded."""
+
+
+def _document_name(filename: str) -> str:
+  """Validate a constitution document name for this loader."""
+  try:
+    return validate_document_name(filename, "constitution")
+  except ConfigError as error:
+    raise ConstitutionError(str(error)) from error
+
+
+def _document_path(base_dir: Path, filename: str) -> Path:
+  """Resolve a constitution document without allowing path escapes."""
+  name = _document_name(filename)
+  base = base_dir.resolve()
+  candidate = (base / name).resolve()
+  try:
+    candidate.relative_to(base)
+  except ValueError as error:
+    msg = (
+      "Constitution document must stay inside the constitution "
+      f"directory: {filename}"
+    )
+    raise ConstitutionError(msg) from error
+  return candidate
+
+
+@dataclass(frozen=True)
+class ConstitutionDocument:
+  """A single constitution document."""
+
+  name: str
+  path: Path
+  content: str
+
+
+@dataclass(frozen=True)
+class Constitution:
+  """The set of guidelines governing a project."""
+
+  documents: tuple[ConstitutionDocument, ...]
+  profiles: tuple[Profile, ...]
+  warnings: tuple[str, ...] = ()
+
+  @property
+  def names(self) -> tuple[str, ...]:
+    """Return the loaded document names."""
+    return tuple(document.name for document in self.documents)
+
+
+class ConstitutionLoader:
+  """Load base and profile-specific constitution documents."""
+
+  def __init__(self, profile_manager: ProfileManager | None = None) -> None:
+    self.profile_manager = profile_manager or ProfileManager()
+
+  def load(
+    self,
+    config: DevFlowConfig,
+    profiles: list[Profile],
+  ) -> Constitution:
+    """Load configured and profile-specific constitution documents."""
+    base_dir = config.constitution.path
+    if not base_dir.is_dir():
+      msg = (
+        f"Constitution directory not found: {base_dir}. "
+        "Run 'devflow init' to restore the guidelines."
+      )
+      raise ConstitutionError(msg)
+
+    names: list[str] = [
+      _document_name(filename) for filename in config.constitution.files
+    ]
+    warnings: list[str] = []
+
+    selected_profiles: list[Profile] = []
+    if config.constitution.base:
+      selected_profiles.extend(
+        profile for profile in profiles if profile.name == "base"
+      )
+    if config.constitution.profile_specific:
+      selected_profiles.extend(
+        profile for profile in profiles if profile.name != "base"
+      )
+
+    for filename in self.profile_manager.constitution_documents(
+      selected_profiles
+    ):
+      name = _document_name(filename)
+      if name not in names:
+        candidate = _document_path(base_dir, name)
+        if candidate.is_file():
+          names.append(name)
+        else:
+          warnings.append(
+            f"Profile guideline is not installed: {name}"
+          )
+
+    if not names:
+      for path in sorted(base_dir.glob("*.md")):
+        try:
+          candidate = _document_path(base_dir, path.name)
+        except ConstitutionError:
+          warnings.append(
+            "Skipped constitution document outside "
+            f"{base_dir}: {path.name}"
+          )
+          continue
+        if candidate.is_file():
+          names.append(path.name)
+
+    if not names:
+      msg = f"No constitution documents found in {base_dir}."
+      raise ConstitutionError(msg)
+
+    documents: list[ConstitutionDocument] = []
+    seen: set[str] = set()
+    for filename in names:
+      if filename in seen:
+        continue
+      seen.add(filename)
+
+      path = _document_path(base_dir, filename)
+      if not path.is_file():
+        msg = (
+          f"Constitution document not found: {filename}. "
+          "Run 'devflow init' or update .devflow/config.yaml."
+        )
+        raise ConstitutionError(msg)
+
+      try:
+        content = path.read_text(encoding="utf-8")
+      except OSError as error:
+        msg = f"Could not read constitution document: {path}"
+        raise ConstitutionError(msg) from error
+
+      documents.append(
+        ConstitutionDocument(
+          name=filename,
+          path=path,
+          content=content,
+        )
+      )
+
+    return Constitution(
+      documents=tuple(documents),
+      profiles=tuple(profiles),
+      warnings=tuple(warnings),
+    )