multi-forge 0.2.0__py3-none-any.whl

forge/guard/deterministic/base.py

@@ -0,0 +1,158 @@
+"""Base class for deterministic policies."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from forge.guard.types import ActionContext, PolicyDecision, Violation
+
+
+class DeterministicPolicy(ABC):
+    """Base class for deterministic (non-LLM) policies.
+
+    Subclasses implement:
+    - policy_id: Unique identifier (e.g., "tdd.tests-before-impl")
+    - description: Human-readable description
+    - intent: Why this policy exists (shown to models on deny so they
+      understand the goal and surface conflicts instead of working around them)
+    - _evaluate: The actual evaluation logic
+
+    The base class provides:
+    - Default applies_to() for Write/Edit filtering
+    - Path normalization helpers
+    - Common pattern matching utilities
+    """
+
+    @property
+    @abstractmethod
+    def policy_id(self) -> str:
+        """Unique identifier for this policy."""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description."""
+        ...
+
+    @property
+    @abstractmethod
+    def intent(self) -> str:
+        """Why this policy exists.
+
+        Shown to models on deny so they understand the goal behind the rule.
+        This helps models surface conflicts to the user instead of finding
+        creative workarounds that satisfy the letter but not the spirit.
+        """
+        ...
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Return True if this policy should evaluate the action.
+
+        Default: applies to Write and Edit tools only.
+        Override for more specific filtering.
+        """
+        return context.tool_name in ("Write", "Edit")
+
+    def evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Evaluate the action and return a decision.
+
+        Wraps _evaluate() with common setup. Subclasses override _evaluate().
+        """
+        return self._evaluate(context)
+
+    @abstractmethod
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Implement policy-specific evaluation logic."""
+        ...
+
+    # --- Helper methods ---
+
+    def _normalize_path(self, path: str | None, repo_root: str) -> str | None:
+        """Normalize a path relative to repo root.
+
+        Returns the path relative to repo_root, or None if path is None.
+        """
+        if path is None:
+            return None
+
+        try:
+            abs_path = Path(path).resolve()
+            root = Path(repo_root).resolve()
+            return str(abs_path.relative_to(root))
+        except (ValueError, RuntimeError):
+            # Path not under repo root, return as-is
+            return path
+
+    def _is_under_directory(self, path: str | None, directory: str) -> bool:
+        """Check if path is under a directory (e.g., 'tests/' or 'src/')."""
+        if path is None:
+            return False
+
+        # Normalize separators and ensure consistent format
+        normalized = path.replace("\\", "/")
+
+        # Check if path starts with directory or contains /directory/
+        return normalized.startswith(f"{directory}/") or f"/{directory}/" in normalized
+
+    def _matches_any_pattern(self, content: str | None, patterns: list[str]) -> list[str]:
+        """Return list of matched patterns from content.
+
+        Args:
+            content: Text to search
+            patterns: List of regex patterns
+
+        Returns:
+            List of patterns that matched (empty if none)
+        """
+        if content is None:
+            return []
+
+        matched = []
+        for pattern in patterns:
+            if re.search(pattern, content, re.MULTILINE):
+                matched.append(pattern)
+
+        return matched
+
+    def _allow(self) -> PolicyDecision:
+        """Return an allow decision."""
+        return PolicyDecision(decision="allow", policy_id=self.policy_id)
+
+    def _deny(self, violations: list[Violation]) -> PolicyDecision:
+        """Return a deny decision with violations and policy intent."""
+        return PolicyDecision(
+            decision="deny",
+            policy_id=self.policy_id,
+            violations=violations,
+            intent=self.intent,
+        )
+
+    def _warn(self, warnings: list[str]) -> PolicyDecision:
+        """Return a warn decision."""
+        return PolicyDecision(
+            decision="warn",
+            policy_id=self.policy_id,
+            warnings=warnings,
+        )
+
+
+class StatefulDeterministicPolicy(DeterministicPolicy):
+    """Base class for deterministic policies that track state.
+
+    State is persisted to the session manifest between hook invocations.
+    Subclasses implement get_state() and set_state() for their specific state.
+    """
+
+    @abstractmethod
+    def get_state(self) -> dict[str, Any]:
+        """Return current state for persistence."""
+        ...
+
+    @abstractmethod
+    def set_state(self, state: dict[str, Any]) -> None:
+        """Restore state from persisted data."""
+        ...

forge/guard/deterministic/coding_standards.py

@@ -0,0 +1,256 @@
+"""Coding standards bundle policies.
+
+Enforces coding conventions from docs/developer/coding-standards.md:
+- no-TYPE_CHECKING: Block TYPE_CHECKING import workarounds
+- no-backward-compat: Block backward compatibility hacks
+- no-emoji: Block colorful emoji in code files (monospace matters)
+"""
+
+from __future__ import annotations
+
+import re
+
+from forge.guard.deterministic.base import DeterministicPolicy
+from forge.guard.types import ActionContext, PolicyDecision, Violation
+
+# Patterns indicating TYPE_CHECKING workarounds
+TYPE_CHECKING_PATTERNS = [
+    r"if\s+TYPE_CHECKING\s*:",
+    r"from\s+typing\s+import.*TYPE_CHECKING",
+]
+
+# Patterns indicating backward compatibility hacks
+BACKWARD_COMPAT_PATTERNS = [
+    r"#\s*backward\s*compat",
+    r"#\s*backwards?\s*compat",
+    r"#\s*legacy\b",
+    r"#\s*deprecated\b",
+    r"#\s*TODO.*remove.*later",
+    r"#\s*for\s+backward",
+    r"#\s*DEPRECATED\b",
+    r"#\s*LEGACY\b",
+    r"#\s*compat(?:ibility)?\s*(?:layer|shim|wrapper)",
+]
+
+
+class NoTypeCheckingPolicy(DeterministicPolicy):
+    """Block TYPE_CHECKING import workarounds.
+
+    From coding-standards.md:
+    > No TYPE_CHECKING workarounds: Fix circular imports architecturally
+    > instead of using `if TYPE_CHECKING:` blocks
+
+    TYPE_CHECKING blocks are a symptom of circular imports that should be
+    fixed by restructuring the code (e.g., moving types to a separate module).
+    """
+
+    @property
+    def policy_id(self) -> str:
+        return "coding_standards.no-type-checking"
+
+    @property
+    def description(self) -> str:
+        return "Block TYPE_CHECKING workarounds (fix circular imports architecturally)"
+
+    @property
+    def intent(self) -> str:
+        return (
+            "Circular imports indicate an architectural problem. TYPE_CHECKING blocks "
+            "hide the symptom instead of fixing the dependency structure. This policy "
+            "ensures clean module boundaries."
+        )
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Apply to Write/Edit on Python files with content."""
+        if context.tool_name not in ("Write", "Edit"):
+            return False
+
+        if context.new_content is None:
+            return False
+
+        # Only check Python files
+        path = context.target_path
+        return path is not None and path.endswith(".py")
+
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Check for TYPE_CHECKING patterns."""
+        matched = self._matches_any_pattern(context.new_content, TYPE_CHECKING_PATTERNS)
+
+        if matched:
+            violations = [
+                Violation(
+                    rule_id=self.policy_id,
+                    message="TYPE_CHECKING blocks are not allowed",
+                    severity="medium",
+                    evidence=f"Found TYPE_CHECKING pattern(s): {', '.join(matched)}",
+                    suggested_fix=(
+                        "Fix circular imports architecturally by:\n"
+                        "1. Moving shared types to a separate types.py module\n"
+                        "2. Using dependency injection\n"
+                        "3. Restructuring the module hierarchy"
+                    ),
+                )
+            ]
+            return self._deny(violations)
+
+        return self._allow()
+
+
+class NoBackwardCompatPolicy(DeterministicPolicy):
+    """Block backward compatibility hacks.
+
+    From coding-standards.md:
+    > No Backward Compatibility Wrappers: Update callers directly, don't create adapters
+    > Clean Refactoring: Fix underlying issues over compatibility layers
+    > No Fallback Logic: When replacing a component, remove the old one completely
+
+    This policy detects common backward-compat patterns in comments and code.
+    """
+
+    @property
+    def policy_id(self) -> str:
+        return "coding_standards.no-backward-compat"
+
+    @property
+    def description(self) -> str:
+        return "Block backward compatibility hacks (update callers directly)"
+
+    @property
+    def intent(self) -> str:
+        return (
+            "Compatibility layers accumulate technical debt. This project prefers clean "
+            "breaks: update all callers directly and remove old code completely rather "
+            "than maintaining shims or fallback logic."
+        )
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Apply to Write/Edit on Python files with content."""
+        if context.tool_name not in ("Write", "Edit"):
+            return False
+
+        if context.new_content is None:
+            return False
+
+        # Only check Python files
+        path = context.target_path
+        return path is not None and path.endswith(".py")
+
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Check for backward compatibility patterns."""
+        matched = self._matches_any_pattern(context.new_content, BACKWARD_COMPAT_PATTERNS)
+
+        if matched:
+            violations = [
+                Violation(
+                    rule_id=self.policy_id,
+                    message="Backward compatibility patterns are not allowed",
+                    severity="medium",
+                    evidence=f"Found backward-compat pattern(s): {', '.join(matched)}",
+                    suggested_fix=(
+                        "Instead of compatibility layers:\n"
+                        "1. Update all callers directly\n"
+                        "2. Remove the old implementation completely\n"
+                        "3. Delete obsolete tests (don't skip them)"
+                    ),
+                )
+            ]
+            return self._deny(violations)
+
+        return self._allow()
+
+
+# Colorful emoji ranges — double-width characters that break monospace rendering.
+# Excludes text-safe dingbats (checkmark, cross, diamond, warning, arrows) that render
+# properly in fixed-width terminals.
+_EMOJI_PATTERN = re.compile(
+    "["
+    "\U0001f300-\U0001f5ff"  # Misc symbols & pictographs
+    "\U0001f600-\U0001f64f"  # Emoticons (faces)
+    "\U0001f680-\U0001f6ff"  # Transport & map symbols
+    "\U0001f700-\U0001f77f"  # Alchemical symbols
+    "\U0001f900-\U0001f9ff"  # Supplemental symbols & pictographs
+    "\U0001fa00-\U0001faff"  # Chess, extended-A symbols
+    "]"
+)
+
+_CODE_EXTENSIONS = frozenset(
+    {
+        ".py",
+        ".js",
+        ".ts",
+        ".jsx",
+        ".tsx",
+        ".sh",
+        ".bash",
+        ".java",
+        ".go",
+        ".rs",
+        ".c",
+        ".cpp",
+        ".h",
+        ".hpp",
+        ".rb",
+        ".swift",
+        ".kt",
+        ".scala",
+    }
+)
+
+
+class NoEmojiPolicy(DeterministicPolicy):
+    """Block colorful emoji in code files.
+
+    Monospace rendering matters in code. Double-width emoji characters break
+    alignment in terminals, diffs, and code review tools. Text-safe symbols
+    (checkmark, cross, arrows, warning) are allowed — only colorful pictographs
+    are blocked.
+    """
+
+    @property
+    def policy_id(self) -> str:
+        return "coding_standards.no-emoji"
+
+    @property
+    def description(self) -> str:
+        return "Block colorful emoji in code (monospace matters)"
+
+    @property
+    def intent(self) -> str:
+        return (
+            "Double-width emoji break alignment in terminals, diffs, and code review "
+            "tools. Source code should stay ASCII-clean for consistent monospace "
+            "rendering. This includes Unicode escapes that produce emoji at runtime."
+        )
+
+    def applies_to(self, context: ActionContext) -> bool:
+        """Apply to Write/Edit on code files with content."""
+        if context.tool_name not in ("Write", "Edit"):
+            return False
+        if context.new_content is None:
+            return False
+        path = context.target_path
+        if path is None:
+            return False
+        for ext in _CODE_EXTENSIONS:
+            if path.endswith(ext):
+                return True
+        return False
+
+    def _evaluate(self, context: ActionContext) -> PolicyDecision:
+        """Check for colorful emoji in content."""
+        assert context.new_content is not None
+        found = _EMOJI_PATTERN.findall(context.new_content)
+        if found:
+            unique = list(dict.fromkeys(found))  # dedupe, preserve order
+            sample = " ".join(unique[:5])
+            violations = [
+                Violation(
+                    rule_id=self.policy_id,
+                    message=f"Emoji characters found in code: {sample}",
+                    severity="low",
+                    evidence=f"Found {len(found)} emoji character(s): {sample}",
+                    suggested_fix="Use ASCII equivalents or text-safe symbols instead of colorful emoji.",
+                )
+            ]
+            return self._deny(violations)
+        return self._allow()

forge/guard/deterministic/registry.py

@@ -0,0 +1,148 @@
+"""Bundle registry for deterministic policies.
+
+Maps bundle names to policy classes. Bundles are collections of related
+policies that can be enabled together.
+
+Available bundles:
+- tdd: Test-driven development workflow enforcement
+- coding_standards: Code style and architecture conventions
+- workflow: Config-driven tagger → branch → stage pipelines
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forge.guard.deterministic.coding_standards import (
+    NoBackwardCompatPolicy,
+    NoEmojiPolicy,
+    NoTypeCheckingPolicy,
+)
+from forge.guard.deterministic.tdd import (
+    NoSkipTestsPolicy,
+    TDDEnforcementPolicy,
+)
+from forge.guard.protocols import Policy
+
+# Bundle name -> list of policy classes
+# Each class is instantiated fresh when get_bundle_policies() is called
+BUNDLES: dict[str, list[type]] = {
+    "tdd": [
+        TDDEnforcementPolicy,
+        NoSkipTestsPolicy,
+    ],
+    "coding_standards": [
+        NoTypeCheckingPolicy,
+        NoBackwardCompatPolicy,
+        NoEmojiPolicy,
+    ],
+}
+
+# Map policy_id to bundle for reverse lookup
+POLICY_TO_BUNDLE: dict[str, str] = {
+    "tdd.tests-before-impl": "tdd",
+    "tdd.no-skip-tests": "tdd",
+    "coding_standards.no-type-checking": "coding_standards",
+    "coding_standards.no-backward-compat": "coding_standards",
+    "coding_standards.no-emoji": "coding_standards",
+}
+
+
+def get_bundle_policies(bundle: str, *, config: dict[str, Any] | None = None) -> list[Policy]:
+    """Get instantiated policies for a bundle.
+
+    Args:
+        bundle: Bundle name (e.g., "tdd", "coding_standards", "workflow")
+        config: Per-bundle configuration dict. For the "tdd" bundle:
+            - ``{"strict": False}`` -> TDDEnforcementPolicy warns instead of denying
+            - ``{"strict": True}`` or ``{}`` or ``None`` -> strict mode (default)
+
+            For the "workflow" bundle:
+            - ``{"workflows": [{...}, ...]}`` -> one WorkflowPolicy per entry
+
+    Returns:
+        List of policy instances. Empty list if bundle not found.
+
+    Raises:
+        ValueError: If config contains invalid types (e.g., ``strict`` is not bool).
+
+    Example:
+        >>> policies = get_bundle_policies("tdd")
+        >>> [p.policy_id for p in policies]
+        ['tdd.tests-before-impl', 'tdd.no-skip-tests']
+    """
+    if bundle == "workflow":
+        return _build_workflow_policies(config)
+
+    policy_classes = BUNDLES.get(bundle, [])
+    policies: list[Policy] = []
+    for cls in policy_classes:
+        if bundle == "tdd" and cls is TDDEnforcementPolicy:
+            strict = True  # default
+            if config and "strict" in config:
+                val = config["strict"]
+                if not isinstance(val, bool):
+                    raise ValueError(f"bundle_config.tdd.strict must be bool, got {type(val).__name__}")
+                strict = val
+            policies.append(cls(strict=strict))
+        else:
+            policies.append(cls())
+    return policies
+
+
+def _build_workflow_policies(config: dict[str, Any] | None) -> list[Policy]:
+    """Instantiate WorkflowPolicy instances from workflow config.
+
+    Lazy-imports workflow module to avoid pulling LLM dependencies
+    unless the workflow bundle is actually used.
+    """
+    import dacite
+
+    from forge.guard.workflow.config import WorkflowConfig
+    from forge.guard.workflow.policy import WorkflowPolicy
+
+    if not config:
+        return []
+    workflows = config.get("workflows", [])
+    if not isinstance(workflows, list):
+        raise ValueError(f"bundle_config.workflow.workflows must be a list, got {type(workflows).__name__}")
+    policies: list[Policy] = []
+    for wf_dict in workflows:
+        wf_config = dacite.from_dict(WorkflowConfig, wf_dict)
+        policies.append(WorkflowPolicy(config=wf_config))
+    return policies
+
+
+def get_all_bundles() -> list[str]:
+    """Get list of all available bundle names."""
+    return list(BUNDLES.keys()) + ["workflow"]
+
+
+def get_bundle_for_policy(policy_id: str) -> str | None:
+    """Get the bundle name for a policy ID.
+
+    Args:
+        policy_id: Policy identifier (e.g., "tdd.tests-before-impl")
+
+    Returns:
+        Bundle name or None if not found.
+    """
+    if policy_id.startswith("workflow."):
+        return "workflow"
+    return POLICY_TO_BUNDLE.get(policy_id)
+
+
+def get_policy_ids_for_bundle(bundle: str) -> list[str]:
+    """Get list of policy IDs in a bundle.
+
+    For the "workflow" bundle, returns ``[]`` because workflow policy IDs
+    are dynamic (``workflow.<name>``) and only known at runtime with config.
+
+    Args:
+        bundle: Bundle name
+
+    Returns:
+        List of policy IDs. Empty list if bundle not found.
+    """
+    policies = get_bundle_policies(bundle)
+    return [p.policy_id for p in policies]