core-runtime 0.1.1__py3-none-any.whl

mind/logic/engines/cli_gate/engine.py

@@ -0,0 +1,211 @@
+# src/mind/logic/engines/cli_gate/engine.py
+
+"""CLI Gate Engine.
+
+Audits the Typer command registry as a single context-level surface.
+Replaces the manual ``audit_cli_registry`` self-check path for the
+seven registry-interrogating rules and adds source-AST verification of
+``cli.discovery_strict`` against the CLI loader file.
+
+CONSTITUTIONAL ALIGNMENT:
+- All eight check_types are context-level (``is_context_level_for``
+  returns True) — the substrate is the live Typer app, not a per-file
+  walk, so the per-file dispatcher is never engaged.
+- The Typer app import is deferred to ``verify_context`` so engine
+  discovery at ``EngineRegistry.initialize`` time does NOT trigger the
+  heavy module-level side effects in ``cli.admin_cli``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from mind.logic.engines.base import BaseEngine, EngineResult
+from mind.logic.engines.cli_gate.base_check import CliCheck
+from mind.logic.engines.cli_gate.checks import (
+    AsyncExecutionCheck,
+    DangerousExplicitCheck,
+    DiscoveryStrictCheck,
+    HelpRequiredCheck,
+    NoDuplicatesCheck,
+    NoLayerExposureCheck,
+    ResourceFirstCheck,
+    StandardVerbsCheck,
+)
+from shared.logger import getLogger
+from shared.models import AuditFinding, AuditSeverity
+from shared.path_resolver import PathResolver
+
+
+if TYPE_CHECKING:
+    from mind.governance.audit_context import AuditorContext
+
+logger = getLogger(__name__)
+
+_CONTEXT_CHECK_TYPES: frozenset[str] = frozenset(
+    {
+        "resource_first",
+        "no_layer_exposure",
+        "standard_verbs",
+        "dangerous_explicit",
+        "async_execution",
+        "discovery_strict",
+        "help_required",
+        "no_duplicates",
+    }
+)
+
+
+# ID: dc55a68d-d7f9-4645-984a-c9c432c472d8
+class CliGateEngine(BaseEngine):
+    """Context-level auditor for the Typer command registry."""
+
+    engine_id = "cli_gate"
+
+    @classmethod
+    # ID: 060dc0c2-6d54-4544-aaec-86e1ef978243
+    def is_context_level_for(cls, check_type: str | None) -> bool:
+        """All cli_gate check_types inspect the command registry or the
+        CLI loader as a whole — none consume a single ``file_path``.
+        """
+        return check_type in _CONTEXT_CHECK_TYPES
+
+    # ID: 31883c58-8573-48fa-b9c0-cb63c613f755
+    def __init__(self, path_resolver: PathResolver) -> None:
+        self._path_resolver = path_resolver
+
+        check_instances: list[CliCheck] = [
+            ResourceFirstCheck(),
+            NoLayerExposureCheck(),
+            StandardVerbsCheck(),
+            DangerousExplicitCheck(),
+            AsyncExecutionCheck(),
+            HelpRequiredCheck(),
+            NoDuplicatesCheck(),
+            DiscoveryStrictCheck(path_resolver=path_resolver),
+        ]
+
+        self._checks: dict[str, CliCheck] = {
+            check.check_type: check for check in check_instances
+        }
+
+        logger.debug(
+            "CliGateEngine initialized with %d check types: %s",
+            len(self._checks),
+            ", ".join(sorted(self._checks.keys())),
+        )
+
+    # ID: 934d1396-88a7-4ccd-991f-c9f198bed27d
+    async def verify_context(
+        self, context: AuditorContext, params: dict[str, Any]
+    ) -> list[AuditFinding]:
+        """Dispatch the requested check_type against the Typer command
+        registry. The Typer app is imported lazily here, once per call,
+        so engine discovery stays hermetic.
+        """
+        check_type = params.get("check_type")
+        if not check_type:
+            return [
+                AuditFinding(
+                    check_id="cli_gate.error",
+                    severity=AuditSeverity.BLOCK,
+                    message="Missing 'check_type' parameter in cli_gate mapping.",
+                    file_path="none",
+                )
+            ]
+
+        check_logic = self._checks.get(check_type)
+        if not check_logic:
+            return [
+                AuditFinding(
+                    check_id="cli_gate.error",
+                    severity=AuditSeverity.BLOCK,
+                    message=(
+                        f"cli_gate has no implementation for check_type '{check_type}'"
+                    ),
+                    file_path="none",
+                )
+            ]
+
+        try:
+            commands = self._walk_registry()
+        except Exception as exc:
+            logger.error(
+                "cli_gate failed to walk Typer registry: %s", exc, exc_info=True
+            )
+            return [
+                AuditFinding(
+                    check_id=f"cli_gate.{check_type}.error",
+                    severity=AuditSeverity.BLOCK,
+                    message=(
+                        f"cli_gate could not introspect the Typer registry: {exc}"
+                    ),
+                    file_path="none",
+                )
+            ]
+
+        try:
+            return check_logic.verify(commands, params)
+        except Exception as exc:
+            logger.error(
+                "cli_gate check '%s' failed: %s", check_type, exc, exc_info=True
+            )
+            return [
+                AuditFinding(
+                    check_id=f"cli_gate.{check_type}.error",
+                    severity=AuditSeverity.BLOCK,
+                    message=(f"Internal cli_gate error during {check_type}: {exc}"),
+                    file_path="none",
+                )
+            ]
+
+    # ID: df3b2825-4023-47f0-b55a-492f21ee2ba0
+    def _walk_registry(self) -> list[dict[str, Any]]:
+        """Lazily import the Typer app and walk it once.
+
+        The import is deferred so that EngineRegistry's import-time
+        discovery does not trigger ``cli.admin_cli``'s module-level
+        ``create_core_context`` bootstrap. The first audit run pays
+        the cost once; sys.modules caches the import for subsequent
+        runs in the same process.
+
+        Normalises ``cmd['file_path']`` to repo-relative before returning
+        (#486). The raw walker emits absolute paths via ``inspect.getfile``,
+        which other consumers (``self_check.py`` metascribe) rely on; the
+        normalisation is local to this engine so finding subjects emitted
+        downstream are repo-relative — matching every other engine and
+        keeping ``ViolationRemediator``'s crate validator from rejecting
+        cli_gate proposals.
+        """
+        from cli.admin_cli import app as main_app
+        from shared.cli.app_introspection import walk_typer_app
+
+        commands = walk_typer_app(main_app, include_missing_handlers=True)
+        repo_root = self._path_resolver.repo_root
+        for cmd in commands:
+            fp = cmd.get("file_path")
+            if not fp or fp in ("none", "unknown"):
+                continue
+            p = Path(fp)
+            if not p.is_absolute():
+                continue
+            try:
+                cmd["file_path"] = str(p.relative_to(repo_root))
+            except ValueError:
+                # Path outside the repo — leave as-is; downstream handles it.
+                continue
+        return commands
+
+    # ID: 70dce438-c504-4819-8f1b-d4bdf3362cf6
+    async def verify(self, file_path: Path, params: dict[str, Any]) -> EngineResult:
+        """Required by BaseEngine, never reached: every cli_gate
+        check_type is context-level, so the rule executor dispatches
+        through verify_context instead of iterating files.
+        """
+        return EngineResult(
+            ok=True,
+            message="cli_gate is context-level; per-file verify is not used.",
+            violations=[],
+            engine_id=self.engine_id,
+        )

mind/logic/engines/glob_gate.py

@@ -0,0 +1,214 @@
+# src/mind/logic/engines/glob_gate.py
+
+"""
+Deterministic Path Auditor.
+
+CONSTITUTIONAL ALIGNMENT:
+- Aligned with 'async.no_manual_loop_run'.
+- Promoted to natively async to satisfy the BaseEngine contract.
+- Complies with ASYNC230 by offloading blocking I/O to threads.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+from pathlib import Path
+from typing import Any
+
+from .base import BaseEngine, EngineResult
+
+
+# ID: 3af1be62-fd37-41f9-b842-8029e8fba49d
+def _count_lines_sync(path: Path) -> int:
+    """Helper to perform blocking file read in a thread."""
+    with open(path, encoding="utf-8") as f:
+        return sum(1 for _ in f)
+
+
+# ID: e9ab205c-263d-40c2-91ce-e44471308a21
+class GlobGateEngine(BaseEngine):
+    """
+    Deterministic Path Auditor.
+    Enforces architectural boundaries based on file location and glob patterns.
+    Also supports simple file metrics like line counts.
+    """
+
+    engine_id = "glob_gate"
+
+    # ID: 6576f3e8-c1f6-4180-bcd2-076f7cd7a491
+    async def verify(self, file_path: Path, params: dict[str, Any]) -> EngineResult:
+        """
+        Natively async verification.
+        Matches the BaseEngine contract to prevent loop-hijacking in orchestrators.
+        """
+        violations = []
+
+        # Normalize the path relative to project root for consistent matching
+        try:
+            target_path = str(file_path)
+        except Exception as e:
+            return EngineResult(
+                ok=False,
+                message=f"Invalid path: {e}",
+                violations=[],
+                engine_id=self.engine_id,
+            )
+
+        # --- CHECK TYPE DISPATCH ---
+        check_type = params.get("check_type")
+
+        if check_type == "allowed_top_level_dirs":
+            return self._check_allowed_top_level_dirs(target_path, params)
+
+        # --- max_lines with optional path-based thresholds ---
+        max_lines = params.get("max_lines")
+        thresholds = params.get("thresholds")
+
+        if max_lines or thresholds:
+            try:
+                # Use to_thread to prevent blocking the event loop during file I/O.
+                line_count = await asyncio.to_thread(_count_lines_sync, file_path)
+
+                # Determine the appropriate limit based on file path
+                limit = max_lines  # Default
+
+                if thresholds and isinstance(thresholds, list):
+                    # Check path-based thresholds in order
+                    for threshold in thresholds:
+                        if not isinstance(threshold, dict):
+                            continue
+
+                        pattern = threshold.get("path")
+                        threshold_limit = threshold.get("limit")
+
+                        if pattern and threshold_limit:
+                            # Convert to posix path for matching
+                            posix_path = target_path.replace("\\", "/")
+
+                            # Special handling for "default"
+                            if pattern == "default":
+                                if (
+                                    limit is None
+                                ):  # Only use default if no other limit set
+                                    limit = threshold_limit
+                            elif self._match(posix_path, pattern):
+                                limit = threshold_limit
+                                break  # First match wins
+
+                if limit and line_count > limit:
+                    violations.append(
+                        f"Module has {line_count} lines, exceeds limit of {limit}"
+                    )
+            except Exception:
+                # Don't fail the check if we can't read the file
+                pass
+
+        # 1. Fact: Extract patterns from parameters
+        patterns = (
+            params.get("patterns")
+            or params.get("forbidden_paths")
+            or params.get("patterns_prohibited", [])
+        )
+        if isinstance(patterns, str):
+            patterns = [patterns]
+
+        # 2. Fact: Check for pattern matches (The Violation)
+        for pattern in patterns:
+            if self._match(target_path, pattern):
+                action_type = params.get("action", "block")
+                violations.append(
+                    f"Resource '{target_path}' matches restricted pattern '{pattern}' (Action: {action_type})"
+                )
+
+        # 3. Fact: Check Exclusions (Exceptions)
+        exceptions = params.get("exceptions", [])
+        if violations and exceptions:
+            # Filter out violations that are actually exceptions
+            violations = [
+                v
+                for v in violations
+                if not any(self._match(target_path, exc) for exc in exceptions)
+            ]
+
+        if not violations:
+            return EngineResult(
+                ok=True,
+                message="Path authorization verified.",
+                violations=[],
+                engine_id=self.engine_id,
+            )
+
+        return EngineResult(
+            ok=False,
+            message="Boundary Violation: Attempted access to protected zone.",
+            violations=violations,
+            engine_id=self.engine_id,
+        )
+
+    # ID: 9596f97f-c126-4644-8821-b7a1713cedb2
+    def _check_allowed_top_level_dirs(
+        self, target_path: str, params: dict[str, Any]
+    ) -> EngineResult:
+        """
+        Whitelist check: file must reside within one of the allowed directories.
+
+        This is the perimeter walk — it answers "does anything exist outside
+        the constitutional boundary?" rather than "does this file access
+        something forbidden?"
+
+        Params:
+            allowed: List of glob patterns for permitted locations.
+                     e.g. ["src/mind/**", "src/body/**", "src/will/**",
+                            "src/shared/**", "src/api/**"]
+        """
+        allowed = params.get("allowed", [])
+        if not allowed:
+            return EngineResult(
+                ok=False,
+                message="Configuration error: allowed_top_level_dirs requires 'allowed' list",
+                violations=["No allowed patterns specified"],
+                engine_id=self.engine_id,
+            )
+
+        posix_path = target_path.replace("\\", "/")
+        # Strip repo root to get relative path for matching against patterns
+        src_idx = posix_path.find("/src/")
+        if src_idx != -1:
+            posix_path = posix_path[src_idx + 1 :]  # "src/body/..."
+        is_allowed = any(self._match(posix_path, pat) for pat in allowed)
+
+        if is_allowed:
+            return EngineResult(
+                ok=True,
+                message="File resides within constitutional boundary.",
+                violations=[],
+                engine_id=self.engine_id,
+            )
+
+        return EngineResult(
+            ok=False,
+            message="Perimeter Violation: File exists outside constitutional layers.",
+            violations=[
+                f"File '{posix_path}' exists outside constitutional layers. "
+                f"Allowed: {', '.join(allowed)}"
+            ],
+            engine_id=self.engine_id,
+        )
+
+    # ID: 3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c
+    def _match(self, path: str, pattern: str) -> bool:
+        """
+        Implements robust glob matching including recursive (**) support.
+        """
+        path = path.replace("\\", "/")
+        pattern = pattern.replace("\\", "/")
+
+        if "**" in pattern:
+            parts = pattern.split("/**")
+            prefix = parts[0]
+            if not prefix:
+                return path.endswith(parts[1]) if len(parts) > 1 else True
+            return path.startswith(prefix)
+
+        return fnmatch.fnmatch(path, pattern)