intguard 1.1.0
A Hierarchical Static Analysis Engine for Business Logic.
Requires Python: >=3.8

# IntentGuard 

**A Hierarchical Static Analysis Engine for Business Logic.**

[![PyPI version](https://badge.fury.io/py/intguard.svg)](https://badge.fury.io/py/intguard)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

IntentGuard is a hierarchical static analysis engine that enforces non-negotiable business and security rules using explicit organizational authority.

Unlike traditional linters that focus on syntax and style, IntentGuard focuses on organizational intent: rules defined by security teams, architects, or developers that represent hard constraints on system behavior.

## Motivation

Most production failures are not caused by invalid syntax, but by valid code that should never have been allowed:

- Floating-point arithmetic used for money
- Secrets hardcoded into source code  
- Debug logic leaking into production paths
- Architectural rules enforced only by convention

These rules are often documented informally and enforced inconsistently. IntentGuard makes such rules explicit, enforceable, and non-ignorable.

## Core Idea: Authority-Aware Enforcement

IntentGuard models real organizational structure by assigning rules to explicit authority layers.

| Layer | Owner | Purpose | Enforcement |
| --- | --- | --- | --- |
| GLOBAL | Security / Compliance | System safety | BLOCK |
| TEAM | Tech Lead | Architectural consistency | WARN |
| PERSONAL | Developer | Local workflow | NUDGE |

When multiple rules apply, all are evaluated, and the highest severity always wins. Lower-authority rules can never override higher-authority mandates.

## Key Features

### Hierarchical Rule Resolution

Rules are evaluated across Global, Team, and Personal layers with deterministic conflict resolution. All decisions are reported with clear reasoning.

### AST-Based Analysis

IntentGuard uses Tree-sitter to analyze Abstract Syntax Trees, allowing semantic detection rather than fragile pattern matching.

This enables detection such as:

- Floats used for financial values
- Unsafe logic in production paths
- Context-aware rule enforcement

### Business Logic Constraints

IntentGuard is designed for enforcing high-risk rules such as:

- Financial precision constraints
- Secret leakage prevention
- Production safety invariants

### Simple CLI Workflow

Runs locally or in CI environments with readable output. Designed to enforce safety without disrupting developer workflows.

### Installation

```bash
pip install intguard
```

Requires Python 3.8+

##  Quick Start

Navigate to your project folder:

```bash
cd my-project
```

Run a scan:

```bash
intguard scan
```

View the Authority Report: IntentGuard will output violations categorized by their authority level.

### Example Output

```
[GLOBAL][BLOCK] global.no-secrets
    Location: src/auth.py:12
    Mandate:   SECURITY: Do not hardcode secrets!

[TEAM][WARN] team.no-print
    Location: src/main.py:45
    Mandate:  Avoid print() in production code.
```

## Configuration

Define your rules in a `rules.yaml` file. IntentGuard supports complex pattern matching on AST nodes.

### Example: Blocking Floats for Money

```yaml
rules:
  - id: "global.no-float-money"
    layer: GLOBAL
    severity: BLOCK
    message: " CRITICAL: Do not use floats for money! Use Decimal."
    scope:
      include: ["src/payments/**"]
    pattern:
      type: "assignment"
      target_matches: "price|salary|balance"
      value_type: "float"
```

##  The Authority Hierarchy

* **GLOBAL (Layer 3):** Security & Compliance rules. Cannot be ignored.
* **TEAM (Layer 2):** Project-specific architectural standards.
* **PERSONAL (Layer 1):** Local workflow preferences (e.g., allow TODOs).

## How IntentGuard Differs from Other Tools

| Tool | Focus | Authority Model | Business Logic |
| --- | --- | --- | --- |
| flake8 / pylint | Style, syntax | None | No |
| Semgrep | Pattern matching | Flat | Limited |
| SonarQube | Metrics | Centralized | Indirect |
| IntentGuard | System constraints | Explicit hierarchy | Yes |

IntentGuard does not replace linters or security scanners.
It adds a missing enforcement layer for rules that must never be broken.

## Current Scope

- **Language support:** Python
- **Analysis method:** AST (Tree-sitter)
- **Interface:** CLI
- **Enforcement:** Local and CI-safe
- **Status:** MVP / active development

## Design Principles

- Rules should outlive individuals
- Authority should be explicit, not implicit
- Critical violations should be impossible to ignore

## License

This project is licensed under the MIT License - see the LICENSE file for details.