hexastack-qual 0.7.0__py3-none-any.whl

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/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/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/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/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",
+]

hexastack_qual/adapters/cqrs/queries.py

@@ -0,0 +1,90 @@
+"""CQRS queries for hexastack-qual.
+
+Notes/Architectural Intent:
+    Encapsulates read-only inspections for quality scorecards, mutant reports,
+    git test impact, and PR diagnostics.
+"""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from hexastack_core.domain import Query
+from hexastack_qual.domain.models import (
+    MutantReport,
+    PrHealthSummary,
+    QualityScorecard,
+)
+
+
+class GetQualityScorecardQuery(Query[QualityScorecard]):
+    """Query to retrieve quality health metrics and sanity status.
+
+    Notes/Architectural Intent:
+        Produces a comprehensive scorecard without side-effects.
+    """
+
+    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 InspectMutantsQuery(Query[MutantReport]):
+    """Query to inspect surviving mutants and triage classifications.
+
+    Notes/Architectural Intent:
+        Reads mutation cache and classifies surviving mutants without running tests.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    package: str | None = Field(
+        default=None,
+        description="Target package name or None for workspace.",
+    )
+    actionable_only: bool = Field(
+        default=True,
+        description="If True, filters only critical actionable mutants.",
+    )
+
+
+class GetTestImpactQuery(Query[list[str]]):
+    """Query to compute test suites impacted by git diff changes.
+
+    Notes/Architectural Intent:
+        Identifies impacted test targets to enable smart scoped testing.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    base_ref: str = Field(
+        default="origin/main",
+        description="Git base reference or branch.",
+    )
+
+
+class GetPrHealthQuery(Query[PrHealthSummary]):
+    """Query to inspect pull request CI checks, CodeQL alerts, and review threads.
+
+    Notes/Architectural Intent:
+        Fetches GitHub PR diagnostic state.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    pr_number: int = Field(description="GitHub pull request number.")
+
+
+__all__ = [
+    "GetPrHealthQuery",
+    "GetQualityScorecardQuery",
+    "GetTestImpactQuery",
+    "InspectMutantsQuery",
+]

hexastack_qual/adapters/events/__init__.py

@@ -0,0 +1,13 @@
+"""Event publisher adapters for hexastack-qual.
+
+Notes/Architectural Intent:
+    Exports QualityEventPublisherAdapter for CQRS event bus broadcasting.
+"""
+
+from __future__ import annotations
+
+from hexastack_qual.adapters.events.publisher import QualityEventPublisherAdapter
+
+__all__ = [
+    "QualityEventPublisherAdapter",
+]

hexastack_qual/adapters/events/publisher.py

@@ -0,0 +1,105 @@
+"""Event publisher adapter for hexastack-qual domain events.
+
+Notes/Architectural Intent:
+    Provides convenience methods for emitting quality gate failures, mutant
+    survival notices, and asset drift notifications across the CQRS EventBusPort.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexastack_qual.domain.events import (
+    AgentAssetDriftDetectedEvent,
+    CriticalMutantSurvivingEvent,
+    QualityGateFailedEvent,
+    StatementsFixedEvent,
+)
+
+if TYPE_CHECKING:
+    from hexastack_cqrs.ports.buses import EventBusPort
+
+
+class QualityEventPublisherAdapter:
+    """Adapter publishing quality domain events across the CQRS event bus.
+
+    Notes/Architectural Intent:
+        Encapsulates event instantiation and publishing to decouple caller logic
+        from specific event models.
+    """
+
+    def __init__(self, event_bus: EventBusPort) -> None:
+        """Initialize publisher with event bus.
+
+        Args:
+            event_bus: The CQRS EventBusPort implementation.
+        """
+        self._event_bus = event_bus
+
+    def publish_quality_gate_failed(
+        self,
+        target: str,
+        failed_checks: list[str],
+    ) -> None:
+        """Publish QualityGateFailedEvent when checks fail.
+
+        Args:
+            target: Target component or package.
+            failed_checks: List of failing sanity check names.
+        """
+        event = QualityGateFailedEvent(target=target, failed_checks=failed_checks)
+        self._event_bus.publish(event)
+
+    def publish_critical_mutant_surviving(
+        self,
+        package: str,
+        mutant_id: str,
+        file_path: str,
+        line_number: int,
+    ) -> None:
+        """Publish CriticalMutantSurvivingEvent when an actionable mutant survives.
+
+        Args:
+            package: Target package name.
+            mutant_id: Identifier of surviving mutant.
+            file_path: Source file path where mutation occurred.
+            line_number: Line number of mutation.
+        """
+        event = CriticalMutantSurvivingEvent(
+            package=package,
+            mutant_id=mutant_id,
+            file_path=file_path,
+            line_number=line_number,
+        )
+        self._event_bus.publish(event)
+
+    def publish_statements_fixed(
+        self,
+        target: str,
+        files_modified: int,
+    ) -> None:
+        """Publish StatementsFixedEvent when files are auto-formatted.
+
+        Args:
+            target: Target component or workspace.
+            files_modified: Number of files modified.
+        """
+        event = StatementsFixedEvent(target=target, files_modified=files_modified)
+        self._event_bus.publish(event)
+
+    def publish_agent_asset_drift(
+        self,
+        outdated_assets: list[str],
+    ) -> None:
+        """Publish AgentAssetDriftDetectedEvent when agent assets drift.
+
+        Args:
+            outdated_assets: List of outdated agent asset paths.
+        """
+        event = AgentAssetDriftDetectedEvent(outdated_assets=outdated_assets)
+        self._event_bus.publish(event)
+
+
+__all__ = [
+    "QualityEventPublisherAdapter",
+]

hexastack_qual/adapters/hexaqual/__init__.py

@@ -0,0 +1,14 @@
+"""Hexaqual engine adapters for hexastack-qual.
+
+Notes/Architectural Intent:
+    Exports HexaqualRunnerAdapter which implements QualityAuditorPort,
+    MutationInspectorPort, and PrDiagnosticPort using the Hexaqual engine.
+"""
+
+from __future__ import annotations
+
+from hexastack_qual.adapters.hexaqual.runner import HexaqualRunnerAdapter
+
+__all__ = [
+    "HexaqualRunnerAdapter",
+]