deviatdd 2.5.1__py3-none-any.whl

deviate/core/commands.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import importlib.resources
+import re
+from pathlib import Path
+
+
+def _resolve_commands_root(commands_root: Path | None = None) -> Path:
+    if commands_root is not None:
+        return commands_root
+    try:
+        return Path(importlib.resources.files("deviate.prompts").joinpath("commands"))
+    except (ModuleNotFoundError, TypeError, FileNotFoundError):
+        fallback = Path("src/deviate/prompts/commands")
+        if fallback.exists():
+            return fallback
+        return Path() / "src" / "deviate" / "prompts" / "commands"
+
+
+def discover_commands(commands_root: Path | None = None) -> list[str]:
+    root = _resolve_commands_root(commands_root)
+    if not root.exists():
+        return []
+    return sorted(p.stem for p in root.glob("*.md") if p.is_file())
+
+
+def resolve_command(name: str, commands_root: Path | None = None) -> Path:
+    root = _resolve_commands_root(commands_root)
+    command_path = root / f"{name}.md"
+    if not command_path.exists():
+        raise FileNotFoundError(f"Command '{name}' not found at {command_path}")
+    return command_path
+
+
+# ---------------------------------------------------------------------------
+# Layer prefix for cache-invariant command composition
+# ---------------------------------------------------------------------------
+
+_LAYER_RE = re.compile(r"^layer:\s*(.+)\s*$", re.MULTILINE)
+_YAML_FM_RE = re.compile(r"^(---\n.*?\n---)\n", re.DOTALL)
+
+
+def _read_text(path: Path) -> str | None:
+    return path.read_text(encoding="utf-8") if path.is_file() else None
+
+
+def _resolve_core_dir() -> Path | None:
+    try:
+        return Path(importlib.resources.files("deviate.prompts").joinpath("core"))
+    except (ModuleNotFoundError, TypeError):
+        fallback = Path("src/deviate/prompts/core")
+        return fallback if fallback.exists() else None
+
+
+def compose_command_body(raw: str, core_dir: Path) -> str | None:
+    """Compose a command body by prepending core.md and layer-command.md.
+
+    Returns the full composed text (frontmatter + prefix + original body),
+    or *None* if *raw* has no valid YAML frontmatter.
+
+    The *core_dir* must contain ``core.md`` and ``{layer}-command.md`` files.
+    """
+    fm_match = _YAML_FM_RE.match(raw)
+    if not fm_match:
+        return None
+
+    frontmatter = fm_match.group(1)
+    body = raw[fm_match.end() :].lstrip()
+
+    parts: list[str] = []
+    core = _read_text(core_dir / "core.md")
+    if core:
+        parts.append(core)
+
+    layer_match = _LAYER_RE.search(frontmatter)
+    if layer_match:
+        layer = layer_match.group(1).strip()
+        layer_content = _read_text(core_dir / f"{layer}-command.md")
+        if layer_content:
+            parts.append(layer_content)
+
+    prefix = "\n\n".join(parts) if parts else None
+    if prefix:
+        body = f"{prefix}\n\n{body}"
+
+    return f"{frontmatter}\n\n{body}"
+
+
+def _emit_platform_frontmatter(agent: str, name: str, description: str) -> str:
+    """Build a minimal per-platform YAML frontmatter block.
+
+    Emits only fields the platform actually recognizes — keeps the
+    on-disk command free of DeviaTDD-internal keys (`category`,
+    `version`, `aliases`, `layer`) that would clutter slash-command
+    autocomplete across heterogeneous backends.
+    """
+    name_line = f"name: {name}\n" if name else ""
+    description_line = f"description: {description}\n" if description else ""
+    body = f"---\n{name_line}{description_line}---\n"
+    return body
+
+
+def _strip_deviate_frontmatter(frontmatter: str, name: str) -> tuple[str, str]:
+    """Pull `description` out of the source frontmatter and drop internal keys.
+
+    Returns ``(emitted_frontmatter_block, description)``. The emitted
+    block is passed to :func:`_emit_platform_frontmatter` to assemble
+    the on-disk frontmatter; the description drives ``description:`` in
+    every platform's slash-command UI.
+    """
+    description = ""
+    for line in frontmatter.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("description:"):
+            description = stripped.split(":", 1)[1].strip().strip("'\"")
+            break
+    return "", description
+
+
+def _read_graphite_routing() -> str | None:
+    """Read the conditional `## Graphite Routing` block for deviate-pr."""
+    try:
+        path = Path(
+            importlib.resources.files("deviate.prompts").joinpath(
+                "extras/deviate-pr-graphite-routing.md"
+            )
+        )
+        return path.read_text(encoding="utf-8")
+    except (ModuleNotFoundError, FileNotFoundError, OSError):
+        return None
+
+
+def _graphite_enabled(workdir: Path) -> bool:
+    """Late-bound import to keep `core` free of `state` deps at module load."""
+    from deviate.state.config import resolve_graphite_config
+
+    try:
+        return resolve_graphite_config(workdir)
+    except Exception:
+        return False
+
+
+def install_command(
+    name: str,
+    target_dir: Path,
+    commands_root: Path | None = None,
+    workdir: Path | None = None,
+    agent: str = "claude",
+) -> bool:
+    """Install a command as a flat .md file at ``target_dir/<name>.md``.
+
+    Returns ``True`` when the file was created or rewritten, ``False``
+    when the on-disk copy already matches the composed output.
+    """
+    command_path = resolve_command(name, commands_root)
+    target_path = target_dir / f"{name}.md"
+
+    raw = _read_text(command_path)
+    if raw is None:
+        return False
+
+    core_dir = _resolve_core_dir()
+    if core_dir is None:
+        return False
+
+    composed = compose_command_body(raw, core_dir)
+    if composed is None:
+        return False
+
+    if name == "deviate-pr" and workdir is not None and _graphite_enabled(workdir):
+        routing = _read_graphite_routing()
+        if routing:
+            composed = f"{composed}\n\n{routing.rstrip()}"
+
+    fm_match = _YAML_FM_RE.match(composed)
+    if fm_match:
+        _, description = _strip_deviate_frontmatter(fm_match.group(1), name)
+        emitted_fm = _emit_platform_frontmatter(agent, name, description)
+        composed = f"{emitted_fm}\n{composed[fm_match.end() :]}"
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if target_path.exists() and target_path.read_text(encoding="utf-8") == composed:
+        return False
+
+    target_path.write_text(composed, encoding="utf-8")
+    return True
+
+
+def detect_agents(workdir: Path | None = None) -> list[str]:
+    """Detect agent platforms from cwd directories.
+
+    Scans *workdir* for ``.claude/``, ``.opencode/``, ``.factory/``,
+    ``.pi/``, and ``.omp/`` subdirectories and returns the matching
+    agent names.
+    """
+    workdir = workdir or Path.cwd()
+    agents: list[str] = []
+    for name in ("claude", "opencode", "factory", "pi", "omp"):
+        if (workdir / f".{name}").is_dir():
+            agents.append(name)
+    return sorted(agents)

deviate/core/commit.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from deviate.core._shared import git_env as _git_env
+
+
+def _has_changes_to_stage(files: list[Path], repo: Path) -> bool:
+    """Check if any of the given files have unstaged changes or are untracked."""
+    for f in files:
+        result = subprocess.run(
+            ["git", "status", "--porcelain", "--", str(f)],
+            cwd=repo,
+            env=_git_env(),
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"git status failed for {f}: {result.stderr.strip()}")
+        if result.stdout.strip():
+            return True
+    return False
+
+
+def stage_and_commit(
+    message: str,
+    files: list[Path],
+    repo: Path | None = None,
+    no_verify: bool = False,
+) -> str | None:
+    repo = repo or Path.cwd()
+
+    if not _has_changes_to_stage(files, repo):
+        return None
+
+    commit_cmd = ["git", "commit", "-m", message]
+    if no_verify:
+        commit_cmd.append("--no-verify")
+
+    subprocess.run(
+        ["git", "add", "--"] + [str(f) for f in files],
+        cwd=repo,
+        env=_git_env(),
+        check=True,
+    )
+    subprocess.run(
+        commit_cmd,
+        cwd=repo,
+        env=_git_env(),
+        check=True,
+    )
+    result = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=repo,
+        env=_git_env(),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+def stage_files(files: list[Path], repo: Path | None = None) -> None:
+    """Stage specific files without committing."""
+    repo = repo or Path.cwd()
+    if not _has_changes_to_stage(files, repo):
+        return
+    subprocess.run(
+        ["git", "add", "--"] + [str(f) for f in files],
+        cwd=repo,
+        env=_git_env(),
+        check=True,
+    )
+
+
+def commit_artifact(
+    path: Path,
+    message: str,
+    repo: Path | None = None,
+    no_verify: bool = False,
+) -> str | None:
+    repo = repo or Path.cwd()
+    return stage_and_commit(
+        message=message, files=[path], repo=repo, no_verify=no_verify
+    )

deviate/core/complexity.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = [
+    "ClassificationResult",
+    "ComplexityGate",
+]
+
+
+@dataclass(frozen=True)
+class ClassificationResult:
+    level: Literal["LOW", "MEDIUM", "HIGH"]
+    execution_mode: Literal["DIRECT", "TDD"]
+
+
+class ComplexityGate:
+    _CLASSIFICATION_TABLE = {
+        "LOW": ClassificationResult(level="LOW", execution_mode="DIRECT"),
+        "MEDIUM": ClassificationResult(level="MEDIUM", execution_mode="DIRECT"),
+        "HIGH": ClassificationResult(level="HIGH", execution_mode="TDD"),
+    }
+
+    @classmethod
+    def classify(
+        cls,
+        description: str,
+        _stub: str | None = None,
+    ) -> ClassificationResult:
+        if _stub is not None:
+            if _stub not in cls._CLASSIFICATION_TABLE:
+                raise ValueError(f"Unknown stub value: {_stub}")
+            return cls._CLASSIFICATION_TABLE[_stub]
+
+        return cls._CLASSIFICATION_TABLE["LOW"]

deviate/core/constitution.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+_REQUIRED_PLACEHOLDERS: frozenset[str] = frozenset(
+    {
+        "PROJECT_NAME",
+        "REPO_ROOT",
+        "TARGET_BACKEND_FRAMEWORK",
+        "TARGET_PACKAGE_MANAGER",
+        "TARGET_TEST_RUNNER",
+        "TARGET_COVERAGE_MINIMUM",
+    }
+)
+
+_PLACEHOLDER_PATTERN = re.compile(r"\$\{(\w+)\}")
+
+
+@dataclass
+class PlaceholderAuditResult:
+    all_present: bool
+    variables: list[str] = field(default_factory=list)
+    missing: list[str] = field(default_factory=list)
+
+
+def validate_placeholders(seed_path: Path) -> PlaceholderAuditResult:
+    content = seed_path.read_text()
+    found = set(_PLACEHOLDER_PATTERN.findall(content))
+    variables = sorted(found & _REQUIRED_PLACEHOLDERS)
+    missing = sorted(_REQUIRED_PLACEHOLDERS - found)
+    return PlaceholderAuditResult(
+        all_present=len(missing) == 0,
+        variables=variables,
+        missing=missing,
+    )
+
+
+def resolve_constitution(repo_root: Path) -> Path:
+    path = repo_root / "specs" / "constitution.md"
+    if not path.exists():
+        raise FileNotFoundError(f"constitution.md not found at {path}")
+    return path
+
+
+def validate_constitution(path: Path) -> bool:
+    if not path.exists():
+        return False
+    content = path.read_text()
+    return len(content.strip()) > 0
+
+
+_COMMAND_KEYS: dict[str, str] = {
+    "TEST_COMMAND": "test_command",
+    "LINT_COMMAND": "lint_command",
+    "TYPE_CHECK_COMMAND": "type_check_command",
+}
+
+
+def _extract_value(line: str) -> str | None:
+    _, _, tail = line.partition(":")
+    value = tail.strip().strip("`").strip()
+    return value or None
+
+
+def validate_sections(path: Path, sections: list[str]) -> list[str]:
+    headings = set(re.findall(r"^(#{1,6}\s+.+)$", path.read_text(), re.MULTILINE))
+    return [s for s in sections if s not in headings]
+
+
+def extract_commands(path: Path) -> dict[str, str]:
+    content = path.read_text()
+    commands: dict[str, str] = {}
+    for line in content.splitlines():
+        stripped = line.strip()
+        if ":" not in stripped:
+            continue
+        for marker, key in _COMMAND_KEYS.items():
+            if marker in stripped:
+                value = _extract_value(stripped)
+                if value:
+                    commands[key] = value
+    return commands

deviate/core/contract.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+
+def emit_contract(data: dict, output_dir: Path) -> Path:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    path = output_dir / f"contract_{timestamp}.json"
+    path.write_text(json.dumps(data, indent=2, default=str))
+    return path
+
+
+def load_contract(path: Path) -> dict:
+    return json.loads(path.read_text())

deviate/core/convention.py

@@ -0,0 +1,147 @@
+"""Commit convention detection.
+
+Detects whether a repository uses emoji-prefixed conventional commits
+(by checking CONTRIBUTING.md / .commit-convention.md for emoji content,
+then falling back to sampling recent git history) and provides a
+formatter that prepends the correct emoji to commit messages.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from deviate.core._shared import git_env as _git_env
+
+# Default type → emoji mapping (gitmoji conventional-commit standard).
+TYPE_EMOJI_MAP: dict[str, str] = {
+    "feat": "✨",
+    "fix": "🐛",
+    "docs": "📚",
+    "style": "🎨",
+    "refactor": "♻️",
+    "perf": "🚀",
+    "test": "✅",
+    "build": "📦",
+    "ci": "👷",
+    "chore": "🔧",
+    "revert": "⏪",
+}
+
+# Per-phase emoji override for `test:` commits during the red-green TDD cycle.
+# RED commits a failing test (🚨); GREEN commits a passing test (✅). All other
+# types keep their `TYPE_EMOJI_MAP` entry. An unknown phase falls back to the
+# default for the type.
+PHASE_TEST_EMOJI: dict[str, str] = {
+    "red": "\U0001f6a8",  # 🚨 — failing test
+    "green": "\u2705",  # ✅ — passing test
+}
+
+# Conventional-commit type pattern at the start of a message.
+_TYPE_RE = re.compile(r"^(\w+)")
+
+
+def _read_convention_file(repo: Path) -> str | None:
+    """Return the content of a project commit-convention file, or None."""
+    for name in ("CONTRIBUTING.md", ".commit-convention.md"):
+        path = repo / name
+        if path.exists():
+            return path.read_text(encoding="utf-8")
+    return None
+
+
+# Emoji Unicode ranges (covers the standard gitmoji set and common emoji).
+_EMOJI_RANGE_RE = re.compile(
+    "["
+    "\U0001f600-\U0001f64f"  # emoticons
+    "\U0001f300-\U0001f5ff"  # symbols & pictographs
+    "\U0001f680-\U0001f6ff"  # transport & map symbols
+    "\U0001f1e0-\U0001f1ff"  # flags
+    "\U0001f900-\U0001f9ff"  # supplemental symbols
+    "\U0001fa00-\U0001fa6f"  # chess symbols
+    "\U0001fa70-\U0001faff"  # symbols extended-A
+    "\U00002702-\U000027b0"  # dingbats
+    "\U00002600-\U000026ff"  # misc symbols
+    "]+",
+    re.UNICODE,
+)
+
+
+def _file_has_emojis(content: str) -> bool:
+    """Check whether a text contains Unicode emoji characters."""
+    return bool(_EMOJI_RANGE_RE.search(content))
+
+
+def _git_log_has_emojis(repo: Path, n: int = 10) -> bool:
+    """Sample the last *n* commit subjects for emoji presence."""
+    try:
+        result = subprocess.run(
+            ["git", "log", f"-{n}", "--pretty=format:%s"],
+            cwd=repo,
+            env=_git_env(),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return False
+        return _file_has_emojis(result.stdout)
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def detect_uses_emojis(repo: Path) -> bool:
+    """Determine whether a repository uses emoji-prefixed commits.
+
+    Detection order:
+    1. CONTRIBUTING.md / .commit-convention.md — if the file contains
+       Unicode emoji characters, the project uses them.
+    2. Git history — sample the last 10 commit subjects.
+    3. Default: False (no emoji prefix).
+    """
+    convention_content = _read_convention_file(repo)
+    if convention_content is not None and _file_has_emojis(convention_content):
+        return True
+    return _git_log_has_emojis(repo)
+
+
+def _extract_type(message: str) -> str | None:
+    """Extract the conventional-commit type from a message string."""
+    m = _TYPE_RE.match(message)
+    return m.group(1) if m else None
+
+
+def format_commit_message(message: str, repo: Path, phase: str | None = None) -> str:
+    """Prepend the appropriate emoji to a conventional-commit message.
+
+    If the repository uses emoji prefixes (detected via CONTRIBUTING.md
+    or git history) and the message starts with a known type, the
+    corresponding emoji is prepended.  Otherwise the message is returned
+    unchanged.
+
+    The optional ``phase`` argument selects a per-phase emoji override for
+    ``test:`` commits during the red-green TDD cycle:
+
+    - ``phase="red"``   → 🚨 (failing test, RED phase commit)
+    - ``phase="green"`` → ✅ (passing test, GREEN phase commit)
+
+    For any other commit type the ``phase`` argument is ignored, and the
+    emoji falls back to ``TYPE_EMOJI_MAP``. An unknown ``phase`` value
+    also falls back to the type's default emoji.
+    """
+    if not detect_uses_emojis(repo):
+        return message
+
+    commit_type = _extract_type(message)
+    if commit_type is None:
+        return message
+
+    if commit_type == "test" and phase in PHASE_TEST_EMOJI:
+        emoji = PHASE_TEST_EMOJI[phase]
+    elif commit_type in TYPE_EMOJI_MAP:
+        emoji = TYPE_EMOJI_MAP[commit_type]
+    else:
+        return message
+
+    return f"{emoji} {message}"

deviate/core/epic.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _resolve_specs_root(specs_root: Path | None = None) -> Path:
+    return specs_root or Path("specs")
+
+
+def _discover_all(specs_root: Path | None = None) -> list[str]:
+    root = _resolve_specs_root(specs_root)
+    if not root.exists():
+        return []
+    return sorted(
+        d.name
+        for d in root.iterdir()
+        if d.is_dir()
+        and not d.name.startswith(".")
+        and (
+            (d / "explore.md").exists()  # Old format: specs/<slug>/explore.md
+            or _extract_prefix_num(d.name)
+            > 0  # New format: specs/NNN-slug/ (numbered bucket)
+        )
+    )
+
+
+def discover_epic(specs_root: Path | None = None) -> str:
+    slug_dirs = _discover_all(specs_root)
+    return slug_dirs[0] if slug_dirs else ""
+
+
+def discover_latest_epic(specs_root: Path | None = None) -> str:
+    slug_dirs = _discover_all(specs_root)
+    if not slug_dirs:
+        return ""
+    return max(slug_dirs, key=lambda s: _extract_prefix_num(s))
+
+
+def _extract_prefix_num(slug: str) -> int:
+    try:
+        return int(slug.split("-")[0])
+    except (ValueError, IndexError):
+        return 0
+
+
+def _find_next_epic_num(root: Path) -> int:
+    if not root.is_dir():
+        return 1
+    nums = [
+        _extract_prefix_num(d.name)
+        for d in root.iterdir()
+        if d.is_dir() and _extract_prefix_num(d.name) > 0
+    ]
+    return max(nums, default=0) + 1
+
+
+def allocate_feature_bucket(slug: str, specs_root: Path | None = None) -> Path:
+    root = _resolve_specs_root(specs_root)
+
+    if _extract_prefix_num(slug) > 0:
+        bucket = root / slug
+        bucket.mkdir(parents=True, exist_ok=True)
+        return bucket
+
+    next_num = _find_next_epic_num(root)
+    numbered_slug = f"{next_num:03d}-{slug}"
+    bucket = root / numbered_slug
+    bucket.mkdir(parents=True, exist_ok=True)
+    return bucket
+
+
+def resolve_active_feature(specs_root: Path | None = None) -> str:
+    return discover_latest_epic(specs_root)

deviate/core/issues.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from deviate.state.ledger import IssueRecord, resolve_issue_record
+
+
+def _resolve_ledger(path: Path | None = None) -> Path:
+    return path or Path("specs/issues.jsonl")
+
+
+def resolve_issue(issue_id: str, ledger_path: Path | None = None) -> IssueRecord | None:
+    return resolve_issue_record(issue_id, _resolve_ledger(ledger_path))
+
+
+def claim_issue(issue_id: str, ledger_path: Path | None = None) -> bool:
+    ledger_path = _resolve_ledger(ledger_path)
+    record = resolve_issue(issue_id, ledger_path)
+    if record is None:
+        return False
+    claimed = record.model_copy(
+        update={
+            "status": "SPECIFIED",
+            "timestamp": datetime.now(timezone.utc),
+        }
+    )
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+    with ledger_path.open("a", encoding="utf-8") as f:
+        f.write(claimed.model_dump_json() + "\n")
+    return True
+
+
+def read_issue_body(issue_id: str, ledger_path: Path | None = None) -> str:
+    ledger_path = _resolve_ledger(ledger_path)
+    record = resolve_issue(issue_id, ledger_path)
+    if record is None:
+        return ""
+    return record.model_dump_json(indent=2)
+
+
+def is_issue_completed(issue_id: str, ledger_path: Path | None = None) -> bool:
+    record = resolve_issue(issue_id, _resolve_ledger(ledger_path))
+    if record is None:
+        return False
+    return record.status == "COMPLETED"