🛡️ Hexaqual

Universal Python quality gates, architectural boundary enforcement, and release engineering toolchain.

Hexaqual provides an opinionated, high-velocity quality harness designed for modular Python architectures, monorepos, and single-package projects. It unifies linting, type-checking, cognitive complexity enforcement, __all__ integrity, 1:1 test symmetry, and automated PyPI release workflows into a cohesive, workflow-driven developer CLI.

🚀 Key Features

• Workflow-Driven Sanity Checks: Multi-stage DAG pipeline powered by Hexaflow for parallel linting, typechecking, and testing.
• Architectural Invariants: First-class support for hexagonal layer enforcement (domain, ports, adapters, infra).
• Test Parity Enforcement: 1:1 symmetry verification between source modules and unit test suites.
• Public API Integrity: Automatic sorting, deduplication, and AST validation of __all__ exports.
• Smart PyPI Publishing: Dependency-ordered, reproducible builds with automatic skip-if-exists checks.

📦 Installation

# Add as a development dependency
uv add --dev hexaqual

# Or install globally
uv tool install hexaqual

🛠️ Unified CLI (hexaqual)

Hexaqual subsumes all developer quality tools into a single unified entrypoint (hexaqual). It dynamically detects workspace layout:

• Multi-package workspaces (packages/ exists): accepts -p / --package to filter focus across packages, or -a / --all for the whole workspace.
• Single-package projects (no packages/): automatically focuses on the root package without requiring -p.
• Examples support: if an examples/ directory exists, -e / --example allows targeted auditing of example projects.

Command Overview

# Run sanity checks on specific packages in a workspace
hexaqual check -p core -p cqrs

# Run sanity check with auto-formatting on a single-package repo
hexaqual check --fix

# Audit __all__ integrity across all packages
hexaqual statements check

# Run pytest on tests impacted by recent git changes
hexaqual test impact

# Examine a GitHub Pull Request dashboard with live polling
hexaqual gh pr 42 --watch

# Verify USAGE.md catalog is up to date
hexaqual docs usage --check

For the complete unrolled CLI reference and full option listings for every subcommand, see USAGE.md.

🪝 Pre-Commit Integration

Add Hexaqual to your .pre-commit-config.yaml to enforce all static quality gates in under a second:

repos:
  - repo: local
    hooks:
      - id: hexaqual-sanity
        name: hexaqual sanity check
        entry: uv run hexaqual sanity --skip-tests
        language: system
        pass_filenames: false

🐕 Dogfooding Hexaflow: Workflows as Architecture

Hexaqual serves as the primary real-world dogfooding ground for Hexaflow, demonstrating how lightweight, in-memory workflow DAGs can orchestrate high-performance developer tooling without complexity or latency.

The Sanity Workflow DAG

Rather than executing checks in a rigid, monolithic sequence or maintaining ad-hoc shell orchestration, hexaqual sanity compiles each target's verification into a declarative hexaflow.Workflow:

graph LR
    subgraph stage1 ["Stage 1: Leaf Static Checks"]
        Lint["Ruff Lint & Format"]
        Statements["__all__ Integrity"]
        Parity["1:1 Test Symmetry"]
    end

    subgraph stage2 ["Stage 2: Static Analysis"]
        Typecheck["Ty Typecheck"]
        Complexity["Cognitive Complexity <= 25"]
    end

    subgraph stage3 ["Stage 3: Dynamic Verification"]
        Pytest["Pytest Test Suites"]
    end

    Lint --> Typecheck
    Statements --> Typecheck
    Parity --> Complexity
    Typecheck --> Pytest
    Complexity --> Pytest

Why Dogfooding Hexaflow Matters:

1. Deterministic Staging & Fail-Fast: Ultra-fast leaf AST checks (Ruff, __all__, test symmetry) execute in Stage 1 (~0.05s), providing immediate feedback before heavier static analysis (Ty, complexipy) or test suites run.
2. Granular Step Checkpoints: Each verification step executes within a discrete StepContext, recording execution metrics, structured findings, and pass/fail states into an InMemoryStateStore.
3. Zero-Latency Overhead: Hexaflow's minimal runtime footprint adds virtually zero overhead—the entire 5-stage static check pipeline runs in under 0.6 seconds.
4. Resilient Error Isolation: If a step fails, the workflow gracefully preserves partial reports, enabling the Rich presenter to render complete multi-target dashboards showing exact failure context.

🏛️ Architecture & Documentation

• Architecture & Design Guide: Hexagonal boundaries, CQRS command bus, and architectural invariants.
• CLI Reference Catalog: Full unrolled command and subcommand trees with exhaustive option listings.

📄 License

Apache-2.0. See LICENSE for details.