Metadata-Version: 2.4
Name: warden-core
Version: 1.8.4
Summary: Warden - AI Code Guardian for comprehensive code validation
Home-page: https://github.com/alperduzgun/warden-core
Author: Warden Team
Author-email: warden@example.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: textual>=0.60.0
Requires-Dist: textual-dev>=1.0.0
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: tree-sitter-go>=0.21.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: grpcio>=1.59.0
Requires-Dist: grpcio-tools>=1.59.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: chromadb>=0.4.0
Requires-Dist: sentence-transformers>=2.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: cloud
Requires-Dist: qdrant-client>=1.7.0; extra == "cloud"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Warden Core - The AI Code Guardian

> "AI writes the code. Warden guards the production."

![Status](https://img.shields.io/badge/Status-Production%20Ready-success)
![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
![AI Ready](https://img.shields.io/badge/AI-Native-purple)

**Warden** is an AI-native security and quality gate designed to validate code generated by LLMs (Claude, GPT-4, etc.) before it enters your codebase. It acts as a strict, impartial judge that enforcing architectural rules, preventing security vulnerabilities, and maintaining code hygiene.

---

## 🤖 Why Warden?

AI coding assistants are powerful but prone to:
*   **Hallucinations:** Inventing non-existent APIs or libraries.
*   **Subtle Bugs:** Introducing edge cases that human reviewers miss.
*   **Security Flaws:** Hardcoding secrets or using unsafe patterns.
*   **Drift:** Deviating from established project architecture.

Warden provides the **"Verify-Loop"** mechanism to ensure every AI-generated change is validated against a rigorous set of rules.

---

## 🚀 Core Features

### 1. 🧠 AI-Native Integration (MCP & Hooks)
Warden is built to integrate directly with your AI Agent:
*   **Context Loading:** Automatically injects `.warden/AI_RULES.md` into every session via Claude `SessionStart` hooks.
*   **Protocol Enforcement:** Instructs AI agents to follow the **Plan -> Execute -> Verify** loop.
*   **Feedback Loop:** Provides JSON/SARIF reports that AI agents can read to self-correct.

### 2. 🛡️ The 6-Frame Validation Pipeline
Warden runs your code through 6 specialized "Frames":
1.  **SecurityFrame (Critical):** Detects SQLi, XSS, and hardcoded secrets.
2.  **ChaosEngineeringFrame (High):** Validates error handling and resilience patterns.
3.  **FuzzTestingFrame (High):** Checks for type safety and edge case handling.
4.  **PropertyTestingFrame (Medium):** Verifies idempotency and invariants.
5.  **ArchitecturalConsistencyFrame (Medium):** Enforces SOLID principles and file limits.
6.  **StressTestingFrame (Low):** Identifies performance bottlenecks (N+1 queries).

### 3. 🚦 False Positive Management
Warden gives you granular control over what to check:
*   **Inline Suppression:** Use `# warden-ignore: rule-id` to suppress specific issues.
*   **Global Config:** Define suppressions in `.warden/suppressions.yaml`.
*   **File Exclusion:** Respects `.gitignore` and supports `.warden/ignore.yaml`.

---

## 🏁 Quick Start

### Installation

```bash
pip install warden-core
```

### Initialization (The Critical Step)

To setup Warden for your project and **configure your AI Agent**:

```bash
warden init --agent
```

This command:
1.  Analyzes your project structure.
2.  Creates `.warden/AI_RULES.md`.
3.  Configures Claude Code hooks (`.claude/settings.json`) to auto-load rules.
4.  Sets up MCP configuration.
5.  Creates `.env` and `.env.example` for your API keys.

### The "Verify-Loop" Protocol

AI Agents working in a Warden project follow this strict protocol:

1.  **PLAN:** Design the change (Task or Phase).
2.  **EXECUTE:** Implement the code.
3.  **VERIFY:** Run `warden scan` at the end of the task/phase.
    *   **IF PASS:** Display **Quality Score (X/10)** 🚀
    *   **IF FAIL:** Fix issues and Repeat.

---

## 🛠️ Command Reference

| Command | Description |
| :--- | :--- |
| `warden scan` | Runs the full validation pipeline on the project. |
| `warden validate <file>` | Scans a single file for immediate feedback. |
| `warden serve` | Starts the MCP Server for AI integration. |
| `warden doctor` | Checks project health and configuration status. |
| `warden install` | Installs/Updates validation frames. |
| `warden search <query>` | Searches Warden Hub or local codebase. |

---

## 📂 Project Structure

```
.
├── .warden/
│   ├── AI_RULES.md          # Protocol for AI Agents
│   ├── config.yaml          # Pipeline configuration
│   ├── ignore.yaml          # File exclusions
│   ├── suppressions.yaml    # False positive rules
│   └── reports/             # Scan results (JSON, SARIF)
├── .claude/
│   └── settings.json        # Hooks for auto-loading context
└── src/                     # Your source code
```

---

## 🧩 Architecture

Warden is designed with modular "Frames" and extends easily:

*   **Pipes & Filters:** Sequential execution pipeline.
*   **Priority Groups:** Critical security checks run first (Fail-Fast).
*   **LSP Synergy:** Uses Language Server Protocol for deep code understanding.
*   **Vector Search:** Semantic search for context-aware fixes.

---

## 📄 License

[License Info]
