Metadata-Version: 2.4
Name: wraith
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Summary: Deterministic linter for AI-generated Python code
Keywords: linter,ai,code-quality,hallucination,python,security
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/Seinarukiro2/codeguard

# wraith

*Catches what your AI forgot to check.*

Deterministic linter for AI-generated Python code. Detects hallucinated APIs, phantom packages, hardcoded secrets, AI artifacts, and supply chain risks.

## Install

```bash
pip install wraith
```

## Usage

```bash
wraith check .                          # scan current directory
wraith check . --fix --diff             # preview fixes
wraith check . --fix                    # apply fixes
wraith check . --select AG,VC001       # specific rules only
wraith check . --min-confidence 0.8    # high-confidence only
wraith check . --format sarif          # CI/CD output
wraith rules                           # list all 20 rules
```

## What it catches

### API Guard — hallucinated API detection

| Rule | What | Example |
|------|------|---------|
| AG001 | Non-existent attribute | `os.path.joinn()` → did you mean `join`? |
| AG002 | Non-existent kwarg | `makedirs(exst_ok=True)` → `exist_ok` |
| AG003 | Deprecated API | PEP 702 + source analysis, zero false positives |
| AG004 | Bare call without module | `read_csv()` → `pd.read_csv()` |
| AG005 | Missing import | `np.array()` without `import numpy` |
| AG006 | Contextual mismatch | `pd.read_excel("data.csv")` → wrong extension |

### Phantom — package validation

| Rule | What |
|------|------|
| PH001 | Package not found on PyPI (slopsquatting risk) |
| PH002 | Package not installed in current environment |
| PH003 | Suspicious package (typosquat, new, low downloads) |

### Vibe Check — AI artifact hygiene

| Rule | What |
|------|------|
| VC001 | Hardcoded secrets (entropy + prefix + bigram analysis) |
| VC002 | AI comments (`# Generated by Claude`, `# Copilot`) |
| VC003 | Debug code — print/breakpoint (pedantic, off by default) |
| VC004 | Debug imports (pdb, ipdb) |
| VC005 | Source map exposure |
| VC006 | Unauthed debug/admin endpoints |
| VC007 | Dangerous files in project (.env, .pem, credentials) |
| VC008 | Unpinned dependencies |
| VC009 | Missing lockfile |
| VC010 | Source map with full source disclosure |
| VC011 | Secret leaked to print/logging (taint analysis) |

## Inline suppression

```python
print("debug")           # noqa: VC003
API_KEY = "sk-secret"    # noqa: VC001
import pdb               # noqa
```

## Python API

```python
import wraith

results = wraith.check_source('API_KEY = "sk-secret"')
fixed = wraith.fix('import pdb\nbreakpoint()')
```

## How it works

- **Tree-sitter AST parsing** — no regex on source, proper syntax analysis
- **Symbol table with scope tracking** (PEP 227 LEGB) — distinguishes imports from local variables
- **Python introspection** — validates API calls against real installed modules
- **Layered secret detection** — known prefixes, Shannon entropy, bigram name classification, character class analysis
- **Taint analysis** — tracks data flow from secret sources to unsafe sinks
- **TYPE_CHECKING awareness** (PEP 484) — skips type-only imports

## Research

Based on:
- [AST Hallucination Guard](https://arxiv.org/abs/2601.19106) (FORGE '26) — API validation via introspection
- [Package Hallucinations in LLMs](https://arxiv.org/abs/2501.19012) — phantom package detection
- [Slopsquatting](https://arxiv.org/abs/2509.20277) — supply chain attack via hallucinated names
- [VibeGuard](https://arxiv.org/abs/2604.01052) — AI code artifact hygiene
- [Secrets in Source Code](https://scholar.google.com/scholar?q=Saha+2020+secrets+source+code) (Saha et al. 2020) — character class analysis
- [Argus](https://arxiv.org/abs/2512.08326) — hierarchical secret detection

