# Zenith Tooling Stack

Zenith replaces fragmented Python tooling with a fast, Rust-based toolchain configured with automated quality checks.

## Tool Architecture & Categories

The diagram below maps the complete Zenith tool ecosystem across four operational pillars:

```
flowchart TB
    subgraph Build["🛠️ Build & Workflow"]
        direction TB
        uv["uv<br/><i>Package Manager & Builds</i>"]
        poe["Poe the Poet<br/><i>Hermetic Task Runner</i>"]
        prek["prek<br/><i>Git Hook Automation</i>"]
        typer["Typer<br/><i>Type-Safe CLI Framework</i>"]
        cc["Cookiecutter<br/><i>Template Scaffolding</i>"]
    end

    subgraph Quality["🛡️ Code Quality & Architecture"]
        direction TB
        ruff["Ruff<br/><i>Linter & Formatter</i>"]
        pyrefly["Pyrefly<br/><i>Strict Type Checker</i>"]
        tach["Tach<br/><i>Boundary Enforcer</i>"]
        deptry["Deptry<br/><i>Dependency Checker</i>"]
        complex["complexipy<br/><i>Complexity Ceiling</i>"]
        griffe["Griffe<br/><i>API Change Detector</i>"]
        typos["typos<br/><i>Source Spell Checker</i>"]
    end

    subgraph Test["🧪 Testing & Security"]
        direction TB
        pytest["pytest<br/><i>Parallel Test Engine</i>"]
        cov["Coverage.py<br/><i>100% Branch Coverage</i>"]
        mutmut["mutmut<br/><i>Fast Local Mutation</i>"]
        cosmic["Cosmic Ray<br/><i>Deep AST Mutation</i>"]
        zizmor["zizmor<br/><i>CI Security Analyzer</i>"]
    end

    subgraph Docs["📚 Documentation & Formatting"]
        direction TB
        zensical["Zensical<br/><i>Fast Docs Generator</i>"]
        rumdl["rumdl<br/><i>Markdown Linter</i>"]
        taplo["Taplo<br/><i>TOML Formatter</i>"]
        prettier["Prettier<br/><i>YAML & CSS Formatter</i>"]
        typst["Typst<br/><i>SVG Layout Engine</i>"]
        termy["Termynal<br/><i>Animated Terminal</i>"]
    end

    click uv "uv/" "Explore uv documentation"
    click poe "poethepoet/" "Explore Poe the Poet documentation"
    click prek "prek/" "Explore prek documentation"
    click typer "typer/" "Explore Typer documentation"
    click cc "cookiecutter/" "Explore Cookiecutter documentation"
    click ruff "ruff/" "Explore Ruff documentation"
    click pyrefly "pyrefly/" "Explore Pyrefly documentation"
    click tach "tach/" "Explore Tach documentation"
    click deptry "deptry/" "Explore Deptry documentation"
    click complex "complexipy/" "Explore complexipy documentation"
    click griffe "griffe/" "Explore Griffe documentation"
    click typos "typos/" "Explore typos documentation"
    click pytest "pytest/" "Explore pytest documentation"
    click cov "coverage/" "Explore Coverage.py documentation"
    click mutmut "mutmut/" "Explore mutmut documentation"
    click cosmic "cosmic-ray/" "Explore Cosmic Ray documentation"
    click zizmor "zizmor/" "Explore zizmor documentation"
    click zensical "zensical/" "Explore Zensical documentation"
    click rumdl "rumdl/" "Explore rumdl documentation"
    click taplo "taplo/" "Explore Taplo documentation"
    click prettier "prettier/" "Explore Prettier documentation"
    click typst "typst/" "Explore Typst documentation"
    click termy "termynal/" "Explore Termynal documentation"
```

Click any tool above to view its technical specifications, architectural rationale in Zenith, configuration showcases, and upstream references.

## Two-Tier Tooling Architecture: Daily Essentials Vs. Hardening

Seeing over twenty tools can feel overwhelming. Zenith organizes its tooling into two distinct tiers so developers can focus immediately on shipping code:

| Tier | Tools | When You Use Them | Interaction Pattern |
| :--- | :--- | :--- | :--- |
| **Tier 1: Daily Velocity Essentials** | **`uv`**, **`ruff`**, **`pytest`**, **`poe`**, **`typer`** | Every minute while writing code | Direct commands: `uv run poe test`, `uv run poe fix`, `uv add` |
| **Tier 2: Hardening &amp; Auditing** | **`tach`**, **`complexipy`**, **`pyrefly`**, **`deptry`**, **`griffe`**, **`mutmut`**, **`zizmor`** | Background guardrails before PR merge | Automated: Runs in `uv run poe code-quality` and CI pipelines |

You do not need to learn or configure Tier 2 tools on Day 1. They operate as automated safety nets that prevent architectural rot, loose typing, and security leaks.

## Customizing or Pruning Tools

Zenith's tools are decoupled and modular. If your team does not need architectural boundary enforcement (`tach`), complexity ceilings (`complexipy`), or mutation testing (`mutmut`), you can prune them in three simple steps without breaking other tasks:

1. **Remove from Composite Tasks (`poe_tasks.toml`)**: Open `poe_tasks.toml` and remove the tool's command from the `code-quality` task array.
2. **Remove from Git Hooks (`prek.toml`)**: Open `prek.toml` and remove the hook entry so `git commit` does not execute it.
3. **Remove from Dependencies (`pyproject.toml`)**: Remove the package from `[dependency-groups.dev]` in `pyproject.toml` and run `uv sync`. You can then safely delete the tool's standalone `.toml` configuration file.

## Dedicated Configuration Files

Most modern Python tools—such as Ruff, Pytest, Coverage, and Taplo—support defining configuration directly inside `pyproject.toml` using `[tool.*]` tables. While consolidating settings into a single file appears convenient, Zenith intentionally standardizes on **separate, dedicated configuration files per tool** whenever possible (`ruff.toml`, `pyrefly.toml`, `complexipy.toml`, `tach.toml`, `poe_tasks.toml`, `pytest.ini`, `.coveragerc`, `.taplo.toml`, `prek.toml`):

- **Focused, High-Signal Code Reviews**: Updating a linter rule, adjusting type check settings, or revising task scripts creates a clean Git diff in that tool's specific file. Pull requests remain easy to review without noise in the core packaging manifest.
- **Prevents Monolithic File Bloat**: Storing configuration for 15+ developer tools in `pyproject.toml` results in a file stretching hundreds of lines. This bloat obscures essential PEP 621 package metadata, dependencies, and build specifications.
- **Granular Git Blame &amp; History**: Each tool configuration retains an independent commit history. Inspecting `git log ruff.toml` or `git blame tach.toml` surfaces the exact context, author, and pull request for architectural decisions over time.
- **Tool-Native Schema Support**: Dedicated files allow language servers, editors, and formatters to attach dedicated JSON/TOML schemas directly without schema interference.

> [!TIP]
>
> **Consolidation Is Supported**: If your organization prefers a single unified `pyproject.toml`, modern tools like Ruff, Coverage, Taplo, and Mutmut natively support `[tool.*]` tables. You can freely consolidate sections into `pyproject.toml` and delete the standalone config files without breaking tool behavior.

## Tooling Matrix

| Tool | Group | Primary Role | Upstream Documentation |
| --- | --- | --- | --- |
| **[uv](<https://bwrob.dev/zenith/tools/uv/index.md>)** | Build &amp; Workflow | Package manager, virtual environments, lockfiles, and PEP 517 builds | [docs.astral.sh/uv](<https://docs.astral.sh/uv/>) |
| **[Poe the Poet](<https://bwrob.dev/zenith/tools/poethepoet/index.md>)** | Build &amp; Workflow | Declarative development task runner integrated with uv | [poethepoet.natn.io](<https://poethepoet.natn.io/>) |
| **[prek](<https://bwrob.dev/zenith/tools/prek/index.md>)** | Build &amp; Workflow | Rust Git hook runner and local quality gate automation | [prek.j178.dev](<https://prek.j178.dev/>) |
| **[Typer](<https://bwrob.dev/zenith/tools/typer/index.md>)** | Build &amp; Workflow | Type-safe CLI framework with Rich terminal rendering | [typer.tiangolo.com](<https://typer.tiangolo.com/>) |
| **[Cookiecutter](<https://bwrob.dev/zenith/tools/cookiecutter/index.md>)** | Build &amp; Workflow | Project templating engine powering Zenith generation | [cookiecutter.readthedocs.io](<https://cookiecutter.readthedocs.io/>) |
| **[Ruff](<https://bwrob.dev/zenith/tools/ruff/index.md>)** | Code Quality | Fast Python linter and formatter with preview rules | [docs.astral.sh/ruff](<https://docs.astral.sh/ruff/>) |
| **[Pyrefly](<https://bwrob.dev/zenith/tools/pyrefly/index.md>)** | Code Quality | Meta's strict type checker and 100% type coverage engine | [github.com/facebook/pyrefly](<https://github.com/facebook/pyrefly>) |
| **[Tach](<https://bwrob.dev/zenith/tools/tach/index.md>)** | Code Quality | Modular boundary enforcement, circular dependency blocker | [github.com/gauge-sh/tach](<https://github.com/gauge-sh/tach>) |
| **[Deptry](<https://bwrob.dev/zenith/tools/deptry/index.md>)** | Code Quality | Detect missing, unused, and transitive package dependencies | [github.com/osprey-oss/deptry](<https://github.com/osprey-oss/deptry>) |
| **[complexipy](<https://bwrob.dev/zenith/tools/complexipy/index.md>)** | Code Quality | Fast cognitive complexity analyzer enforcing max \<= 10 | [github.com/rohaquinlop/complexipy](<https://github.com/rohaquinlop/complexipy>) |
| **[Griffe](<https://bwrob.dev/zenith/tools/griffe/index.md>)** | Code Quality | Static AST analysis and breaking public API change detector | [mkdocstrings.github.io/griffe](<https://mkdocstrings.github.io/griffe/>) |
| **[typos](<https://bwrob.dev/zenith/tools/typos/index.md>)** | Code Quality | High-performance source code and doc spell checker | [github.com/crate-ci/typos](<https://github.com/crate-ci/typos>) |
| **[pytest](<https://bwrob.dev/zenith/tools/pytest/index.md>)** | Testing &amp; Security | Fixture-based test framework with parallel, property, and snapshot plugins | [docs.pytest.org](<https://docs.pytest.org/>) |
| **[Coverage.py](<https://bwrob.dev/zenith/tools/coverage/index.md>)** | Testing &amp; Security | 100% statement and branch test coverage engine | [coverage.readthedocs.io](<https://coverage.readthedocs.io/>) |
| **[mutmut](<https://bwrob.dev/zenith/tools/mutmut/index.md>)** | Testing &amp; Security | Fast AST mutation testing for local TDD loops (macOS/Linux) | [mutmut.readthedocs.io](<https://mutmut.readthedocs.io/>) |
| **[Cosmic Ray](<https://bwrob.dev/zenith/tools/cosmic-ray/index.md>)** | Testing &amp; Security | AST mutation testing evaluating test suite assertiveness | [cosmic-ray.readthedocs.io](<https://cosmic-ray.readthedocs.io/>) |
| **[zizmor](<https://bwrob.dev/zenith/tools/zizmor/index.md>)** | Testing &amp; Security | Static security analysis tool for GitHub Actions workflows | [woodruffw.github.io/zizmor](<https://woodruffw.github.io/zizmor/>) |
| **[Zensical](<https://bwrob.dev/zenith/tools/zensical/index.md>)** | Documentation &amp; Formatting | Fast TOML-based static documentation generator | [github.com/zensical/zensical](<https://github.com/zensical/zensical>) |
| **[rumdl](<https://bwrob.dev/zenith/tools/rumdl/index.md>)** | Documentation &amp; Formatting | Rust-native Markdown linter and embedded code checker | [github.com/rvben/rumdl](<https://github.com/rvben/rumdl>) |
| **[Taplo](<https://bwrob.dev/zenith/tools/taplo/index.md>)** | Documentation &amp; Formatting | Consistent TOML formatting and schema validation | [taplo.tamasfe.dev](<https://taplo.tamasfe.dev/>) |
| **[Prettier](<https://bwrob.dev/zenith/tools/prettier/index.md>)** | Documentation &amp; Formatting | Opinionated formatter for YAML workflows and CSS stylesheets | [prettier.io](<https://prettier.io/>) |
| **[Typst](<https://bwrob.dev/zenith/tools/typst/index.md>)** | Documentation &amp; Formatting | Markup-based layout engine for compiling SVG documentation assets | [typst.app/docs](<https://typst.app/docs/>) |
| **[Termynal](<https://bwrob.dev/zenith/tools/termynal/index.md>)** | Documentation &amp; Formatting | Lightweight terminal animation widget for documentation | [github.com/ines/termynal](<https://github.com/ines/termynal>) |