hexastack-qual 0.7.0__tar.gz

hexastack_qual-0.7.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: hexastack-qual
+Version: 0.7.0
+Summary: Hexagonal quality, governance, and release adapter integrating hexaqual with CQRS, MCP, UI, and Events
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: hexaqual[all]>=0.9.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: hexastack-qual[events,mcp,ui] ; extra == 'all'
+Requires-Dist: hexastack-events ; extra == 'events'
+Requires-Dist: hexastack-mcp ; extra == 'mcp'
+Requires-Dist: hexastack-ui ; extra == 'ui'
+Requires-Python: >=3.13
+Provides-Extra: all
+Provides-Extra: events
+Provides-Extra: mcp
+Provides-Extra: ui
+Description-Content-Type: text/markdown
+
+# hexastack-qual
+
+> 🛡️ **Hexagonal quality, governance, and release adapter integrating hexaqual with CQRS, MCP, UI, and Events.**
+
+Part of the [Hexastack](https://dopplereffect.us/hexastack/) ecosystem.
+
+---
+
+## 🌟 Overview
+
+`hexastack-qual` bridges [**Hexaqual**](https://github.com/TheTrueSCU/hexaqual) into Hexastack applications:
+- **CQRS Execution Pipeline**: Execute sanity checks, statement formatting, and mutant audits via decoupled `Command` and `Query` objects with full OpenTelemetry tracing and structured logging.
+- **Model Context Protocol (MCP)**: Expose `@mcp_tool` and `@mcp_resource` endpoints for AI coding assistants (Claude Desktop, Cursor, Antigravity) to audit complexity, test parity, and mutant resilience.
+- **DevTools Console Panel**: Mount a reactive NiceGUI dashboard in `/devtools` showing live quality gauges and one-click remediation actions.
+- **Distributed Event Publishing**: Emit domain events (`QualityGateFailedEvent`, `CriticalMutantSurvivingEvent`) over `hexastack-events` to Apprise or NATS.
+
+---
+
+## 📦 Installation
+
+```bash
+# Core adapter (CQRS pipeline + Hexaqual runner)
+pip install hexastack-qual
+
+# With Model Context Protocol (MCP) server support
+pip install "hexastack-qual[mcp]"
+
+# With NiceGUI DevTools console tab
+pip install "hexastack-qual[ui]"
+
+# With distributed event publishing
+pip install "hexastack-qual[events]"
+
+# All extras
+pip install "hexastack-qual[all]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. CQRS Pipeline Execution
+
+```python
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+from hexastack_qual.adapters.cqrs.commands import RunSanityCheckCommand
+from hexastack_qual.adapters.cqrs.queries import GetQualityScorecardQuery
+
+# Dispatch queries and commands via the CQRS pipeline
+scorecard = await pipeline.execute(GetQualityScorecardQuery(package="core"))
+print(
+    f"Healthy: {scorecard.is_healthy}, Violations: {len(scorecard.complexity_violations)}"
+)
+
+result = await pipeline.execute(RunSanityCheckCommand(package="core", skip_tests=True))
+print(f"Sanity status: {result.success}")
+```
+
+### 2. Exposing Quality over MCP
+
+```python
+from hexastack_qual.adapters.mcp import get_quality_tools
+
+# Attach quality inspection tools to an AI agent
+agent = create_cqrs_agent(
+    pipeline=pipeline,
+    tools=get_quality_tools(),
+    system_prompt="You are an autonomous refactoring agent with self-verification tools.",
+)
+```
+
+---
+
+## 🏛️ Architecture
+
+```
+hexastack_qual/
+├── domain/       # Pure models (QualityScorecard, ComplexityMetric), exceptions, and events
+├── ports/        # QualityAuditorPort, MutationInspectorPort, PrDiagnosticPort
+├── adapters/     # Hexaqual runner, CQRS handlers, MCP tools, NiceGUI panel, Events publisher
+└── infra/        # QualBootstrapper (DI container registration) and Typer CLI
+```

hexastack_qual-0.7.0/README.md

@@ -0,0 +1,82 @@
+# hexastack-qual
+
+> 🛡️ **Hexagonal quality, governance, and release adapter integrating hexaqual with CQRS, MCP, UI, and Events.**
+
+Part of the [Hexastack](https://dopplereffect.us/hexastack/) ecosystem.
+
+---
+
+## 🌟 Overview
+
+`hexastack-qual` bridges [**Hexaqual**](https://github.com/TheTrueSCU/hexaqual) into Hexastack applications:
+- **CQRS Execution Pipeline**: Execute sanity checks, statement formatting, and mutant audits via decoupled `Command` and `Query` objects with full OpenTelemetry tracing and structured logging.
+- **Model Context Protocol (MCP)**: Expose `@mcp_tool` and `@mcp_resource` endpoints for AI coding assistants (Claude Desktop, Cursor, Antigravity) to audit complexity, test parity, and mutant resilience.
+- **DevTools Console Panel**: Mount a reactive NiceGUI dashboard in `/devtools` showing live quality gauges and one-click remediation actions.
+- **Distributed Event Publishing**: Emit domain events (`QualityGateFailedEvent`, `CriticalMutantSurvivingEvent`) over `hexastack-events` to Apprise or NATS.
+
+---
+
+## 📦 Installation
+
+```bash
+# Core adapter (CQRS pipeline + Hexaqual runner)
+pip install hexastack-qual
+
+# With Model Context Protocol (MCP) server support
+pip install "hexastack-qual[mcp]"
+
+# With NiceGUI DevTools console tab
+pip install "hexastack-qual[ui]"
+
+# With distributed event publishing
+pip install "hexastack-qual[events]"
+
+# All extras
+pip install "hexastack-qual[all]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. CQRS Pipeline Execution
+
+```python
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+from hexastack_qual.adapters.cqrs.commands import RunSanityCheckCommand
+from hexastack_qual.adapters.cqrs.queries import GetQualityScorecardQuery
+
+# Dispatch queries and commands via the CQRS pipeline
+scorecard = await pipeline.execute(GetQualityScorecardQuery(package="core"))
+print(
+    f"Healthy: {scorecard.is_healthy}, Violations: {len(scorecard.complexity_violations)}"
+)
+
+result = await pipeline.execute(RunSanityCheckCommand(package="core", skip_tests=True))
+print(f"Sanity status: {result.success}")
+```
+
+### 2. Exposing Quality over MCP
+
+```python
+from hexastack_qual.adapters.mcp import get_quality_tools
+
+# Attach quality inspection tools to an AI agent
+agent = create_cqrs_agent(
+    pipeline=pipeline,
+    tools=get_quality_tools(),
+    system_prompt="You are an autonomous refactoring agent with self-verification tools.",
+)
+```
+
+---
+
+## 🏛️ Architecture
+
+```
+hexastack_qual/
+├── domain/       # Pure models (QualityScorecard, ComplexityMetric), exceptions, and events
+├── ports/        # QualityAuditorPort, MutationInspectorPort, PrDiagnosticPort
+├── adapters/     # Hexaqual runner, CQRS handlers, MCP tools, NiceGUI panel, Events publisher
+└── infra/        # QualBootstrapper (DI container registration) and Typer CLI
+```

hexastack_qual-0.7.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "hexastack-qual"
+version = "0.7.0"
+description = "Hexagonal quality, governance, and release adapter integrating hexaqual with CQRS, MCP, UI, and Events"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "hexaqual[all]>=0.9.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+events = ["hexastack-events"]
+mcp = ["hexastack-mcp"]
+ui = ["hexastack-ui"]
+all = ["hexastack-qual[events,mcp,ui]"]
+
+[project.entry-points."hexastack.bootstrappers"]
+qual = "hexastack_qual.infra.bootstrap:QualBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.uv.sources.hexastack-events]
+workspace = true
+
+[tool.uv.sources.hexastack-mcp]
+workspace = true
+
+[tool.uv.sources.hexastack-ui]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_qual"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_qual"]
+layers = [
+    "infra",
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[tool.mutmut]
+runner = 'pytest -x --assert=plain -o addopts=""'
+paths_to_mutate = "src"
+
+[tool.pytest-gremlins]
+paths = ["src"]
+operators = [
+    "arithmetic",
+    "boolean",
+    "boundary",
+    "comparison",
+    "return",
+]
+workers = "auto"
+batch_size = 10
+cache = true

hexastack_qual-0.7.0/pyproject.toml.orig

@@ -0,0 +1,68 @@
+[project]
+name = "hexastack-qual"
+version = "0.7.0"
+description = "Hexagonal quality, governance, and release adapter integrating hexaqual with CQRS, MCP, UI, and Events"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexaqual[all]>=0.9.0",
+    "hexastack-core",
+    "hexastack-cqrs",
+]
+
+[project.optional-dependencies]
+events = [
+    "hexastack-events",
+]
+mcp = [
+    "hexastack-mcp",
+]
+ui = [
+    "hexastack-ui",
+]
+all = [
+    "hexastack-qual[events,mcp,ui]",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+qual = "hexastack_qual.infra.bootstrap:QualBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+hexastack-events = { workspace = true }
+hexastack-mcp = { workspace = true }
+hexastack-ui = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_qual"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_qual"]
+layers = [
+    "infra",
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[tool.mutmut]
+runner = "pytest -x --assert=plain -o addopts=\"\""
+paths_to_mutate = "src"
+
+[tool.pytest-gremlins]
+paths = ["src"]
+operators = ["arithmetic", "boolean", "boundary", "comparison", "return"]
+workers = "auto"
+batch_size = 10
+cache = true

hexastack_qual-0.7.0/src/hexastack_qual/__init__.py

@@ -0,0 +1,18 @@
+"""Hexastack Quality & Governance Adapter.
+
+Bridges the Hexaqual engine into Hexastack applications, providing CQRS
+dispatching, MCP server tools, reactive DevTools panels, and distributed event
+publishing.
+
+Notes/Architectural Intent:
+    Serves as the root package for hexastack-qual. Exports package version
+    and core domain models while preserving lazy loading for optional extras.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "__version__",
+]

hexastack_qual-0.7.0/src/hexastack_qual/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Adapters for hexastack-qual.
+
+Notes/Architectural Intent:
+    Houses concrete adapters for Hexaqual engine, CQRS message handlers, MCP
+    tool endpoints, NiceGUI DevTools panels, and distributed event publishers.
+"""
+
+from __future__ import annotations
+
+from hexastack_qual.adapters.hexaqual.runner import HexaqualRunnerAdapter
+
+__all__ = [
+    "HexaqualRunnerAdapter",
+]

hexastack_qual-0.7.0/src/hexastack_qual/adapters/cqrs/__init__.py

@@ -0,0 +1,50 @@
+"""CQRS messages and handlers for hexastack-qual.
+
+Notes/Architectural Intent:
+    Exports Commands, Queries, and corresponding Handlers for dispatching
+    quality audits through the Hexastack ExecutionPipeline.
+"""
+
+from __future__ import annotations
+
+from hexastack_qual.adapters.cqrs.commands import (
+    FormatStatementsCommand,
+    RunMutationTestingCommand,
+    RunSanityCheckCommand,
+    SyncAgentAssetsCommand,
+)
+from hexastack_qual.adapters.cqrs.handlers import (
+    FormatStatementsHandler,
+    GetPrHealthHandler,
+    GetQualityScorecardHandler,
+    GetTestImpactHandler,
+    InspectMutantsHandler,
+    RunMutationTestingHandler,
+    RunSanityCheckHandler,
+    SyncAgentAssetsHandler,
+)
+from hexastack_qual.adapters.cqrs.queries import (
+    GetPrHealthQuery,
+    GetQualityScorecardQuery,
+    GetTestImpactQuery,
+    InspectMutantsQuery,
+)
+
+__all__ = [
+    "FormatStatementsCommand",
+    "FormatStatementsHandler",
+    "GetPrHealthHandler",
+    "GetPrHealthQuery",
+    "GetQualityScorecardHandler",
+    "GetQualityScorecardQuery",
+    "GetTestImpactHandler",
+    "GetTestImpactQuery",
+    "InspectMutantsHandler",
+    "InspectMutantsQuery",
+    "RunMutationTestingCommand",
+    "RunMutationTestingHandler",
+    "RunSanityCheckCommand",
+    "RunSanityCheckHandler",
+    "SyncAgentAssetsCommand",
+    "SyncAgentAssetsHandler",
+]

hexastack_qual-0.7.0/src/hexastack_qual/adapters/cqrs/commands.py

@@ -0,0 +1,88 @@
+"""CQRS commands for hexastack-qual.
+
+Notes/Architectural Intent:
+    Encapsulates state-changing intent: running sanity gates, auto-fixing
+    statements, executing mutation tests, and syncing agent assets.
+"""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from hexastack_core.domain import Command
+
+
+class RunSanityCheckCommand(Command):
+    """Command to execute full or scoped sanity check quality gate.
+
+    Notes/Architectural Intent:
+        Triggers cognitive complexity, test parity, and __all__ validation.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    package: str | None = Field(
+        default=None,
+        description="Target package name or None for workspace.",
+    )
+    skip_tests: bool = Field(
+        default=True,
+        description="Whether to skip unit test suites.",
+    )
+
+
+class FormatStatementsCommand(Command):
+    """Command to auto-format and sort __all__ export statements.
+
+    Notes/Architectural Intent:
+        Modifies target files in-place to enforce casefold ordering.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    package: str | None = Field(
+        default=None,
+        description="Target package name or None for workspace.",
+    )
+
+
+class RunMutationTestingCommand(Command):
+    """Command to execute mutation testing across target components.
+
+    Notes/Architectural Intent:
+        Executes mutmut runner and compiles surviving mutant scorecards.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    package: str | None = Field(
+        default=None,
+        description="Target package name or None for workspace.",
+    )
+    reset: bool = Field(
+        default=False,
+        description="Whether to clear existing mutation cache before running.",
+    )
+
+
+class SyncAgentAssetsCommand(Command):
+    """Command to re-synchronize universal AI agent rules and workflows.
+
+    Notes/Architectural Intent:
+        Materializes latest hexaqual agent assets into .agents/.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    dry_run: bool = Field(
+        default=False,
+        description="If True, verifies sync without writing files.",
+    )
+
+
+__all__ = [
+    "FormatStatementsCommand",
+    "RunMutationTestingCommand",
+    "RunSanityCheckCommand",
+    "SyncAgentAssetsCommand",
+]

hexastack_qual-0.7.0/src/hexastack_qual/adapters/cqrs/handlers.py

@@ -0,0 +1,187 @@
+"""CQRS command and query handlers for hexastack-qual.
+
+Notes/Architectural Intent:
+    Connects CQRS message dispatching to QualityAuditorPort, MutationInspectorPort,
+    and PrDiagnosticPort, with optional event emission across EventBusPort.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexaqual.adapters.agents import FileSystemAgentAssetAdapter
+from hexaqual.adapters.workspace import get_repo_root
+
+from hexastack_qual.adapters.cqrs.commands import (
+    FormatStatementsCommand,
+    RunMutationTestingCommand,
+    RunSanityCheckCommand,
+    SyncAgentAssetsCommand,
+)
+from hexastack_qual.adapters.cqrs.queries import (
+    GetPrHealthQuery,
+    GetQualityScorecardQuery,
+    GetTestImpactQuery,
+    InspectMutantsQuery,
+)
+from hexastack_qual.domain.events import (
+    QualityGateFailedEvent,
+    StatementsFixedEvent,
+)
+from hexastack_qual.domain.models import (
+    MutantReport,
+    PrHealthSummary,
+    QualityScorecard,
+)
+
+if TYPE_CHECKING:
+    from hexastack_cqrs.ports.buses import EventBusPort
+    from hexastack_qual.ports.auditor import QualityAuditorPort
+    from hexastack_qual.ports.diagnostics import PrDiagnosticPort
+    from hexastack_qual.ports.mutator import MutationInspectorPort
+
+
+class RunSanityCheckHandler:
+    """Handler for RunSanityCheckCommand."""
+
+    def __init__(
+        self,
+        auditor: QualityAuditorPort,
+        event_bus: EventBusPort | None = None,
+    ) -> None:
+        """Initialize handler with auditor port and optional event bus."""
+        self._auditor = auditor
+        self._event_bus = event_bus
+
+    async def __call__(self, command: RunSanityCheckCommand) -> QualityScorecard:
+        """Execute sanity check and emit failure event if unhealthy."""
+        scorecard = self._auditor.run_sanity(
+            package=command.package,
+            skip_tests=command.skip_tests,
+        )
+        if not scorecard.is_healthy and self._event_bus:
+            failed_names = [
+                c.check_name for c in scorecard.checks if c.status == "fail"
+            ]
+            event = QualityGateFailedEvent(
+                target=scorecard.target,
+                failed_checks=failed_names,
+            )
+            await self._event_bus.publish(event)
+        return scorecard
+
+
+class FormatStatementsHandler:
+    """Handler for FormatStatementsCommand."""
+
+    def __init__(
+        self,
+        auditor: QualityAuditorPort,
+        event_bus: EventBusPort | None = None,
+    ) -> None:
+        """Initialize handler with auditor port and optional event bus."""
+        self._auditor = auditor
+        self._event_bus = event_bus
+
+    async def __call__(self, command: FormatStatementsCommand) -> int:
+        """Fix statement formatting and emit event if files modified."""
+        modified_count = self._auditor.fix_statements(package=command.package)
+        if modified_count > 0 and self._event_bus:
+            event = StatementsFixedEvent(
+                target=command.package or "workspace",
+                files_modified=modified_count,
+            )
+            await self._event_bus.publish(event)
+        return modified_count
+
+
+class RunMutationTestingHandler:
+    """Handler for RunMutationTestingCommand."""
+
+    def __init__(self, mutator: MutationInspectorPort) -> None:
+        """Initialize handler with mutation inspector port."""
+        self._mutator = mutator
+
+    async def __call__(self, command: RunMutationTestingCommand) -> MutantReport:
+        """Execute mutation testing runner."""
+        return self._mutator.run_mutation_testing(
+            package=command.package,
+            reset=command.reset,
+        )
+
+
+class SyncAgentAssetsHandler:
+    """Handler for SyncAgentAssetsCommand."""
+
+    async def __call__(self, command: SyncAgentAssetsCommand) -> int:
+        """Synchronize universal AI agent rules and workflows."""
+        root = get_repo_root()
+        adapter = FileSystemAgentAssetAdapter()
+        res = adapter.sync_assets(root, dry_run=command.dry_run)
+        return res.created_count + res.updated_count
+
+
+class GetQualityScorecardHandler:
+    """Handler for GetQualityScorecardQuery."""
+
+    def __init__(self, auditor: QualityAuditorPort) -> None:
+        """Initialize handler with auditor port."""
+        self._auditor = auditor
+
+    async def __call__(self, query: GetQualityScorecardQuery) -> QualityScorecard:
+        """Execute sanity check and return scorecard."""
+        return self._auditor.run_sanity(
+            package=query.package,
+            skip_tests=query.skip_tests,
+        )
+
+
+class InspectMutantsHandler:
+    """Handler for InspectMutantsQuery."""
+
+    def __init__(self, mutator: MutationInspectorPort) -> None:
+        """Initialize handler with mutator port."""
+        self._mutator = mutator
+
+    async def __call__(self, query: InspectMutantsQuery) -> MutantReport:
+        """Inspect surviving mutants."""
+        return self._mutator.inspect_surviving_mutants(
+            package=query.package,
+            actionable_only=query.actionable_only,
+        )
+
+
+class GetTestImpactHandler:
+    """Handler for GetTestImpactQuery."""
+
+    def __init__(self, diagnostics: PrDiagnosticPort) -> None:
+        """Initialize handler with diagnostics port."""
+        self._diagnostics = diagnostics
+
+    async def __call__(self, query: GetTestImpactQuery) -> list[str]:
+        """Compute impacted test suites."""
+        return self._diagnostics.get_test_impact(base_ref=query.base_ref)
+
+
+class GetPrHealthHandler:
+    """Handler for GetPrHealthQuery."""
+
+    def __init__(self, diagnostics: PrDiagnosticPort) -> None:
+        """Initialize handler with diagnostics port."""
+        self._diagnostics = diagnostics
+
+    async def __call__(self, query: GetPrHealthQuery) -> PrHealthSummary:
+        """Inspect pull request diagnostic health."""
+        return self._diagnostics.get_pr_health(pr_number=query.pr_number)
+
+
+__all__ = [
+    "FormatStatementsHandler",
+    "GetPrHealthHandler",
+    "GetQualityScorecardHandler",
+    "GetTestImpactHandler",
+    "InspectMutantsHandler",
+    "RunMutationTestingHandler",
+    "RunSanityCheckHandler",
+    "SyncAgentAssetsHandler",
+]