Metadata-Version: 2.4
Name: truemend
Version: 1.1.1
Summary: TrueMend — Autonomous Code Improvement Engine. Detects anti-patterns and fixes them using AST-based analysis.
Author-email: Al Sajoo <support@truemend.dev>
License: MIT
Project-URL: Homepage, https://github.com/alsajoo/truemend
Project-URL: Documentation, https://truemend.dev/docs
Project-URL: Repository, https://github.com/alsajoo/truemend
Project-URL: Issues, https://github.com/alsajoo/truemend/issues
Keywords: code-quality,ast,anti-patterns,mcp,refactoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ast-grep-py<1.0,>=0.11.0
Requires-Dist: colorama<1.0,>=0.4.6
Requires-Dist: fastmcp<4.0,>=3.0.0
Requires-Dist: google-re2<2.0,>=1.0
Requires-Dist: joserfc>=1.6.3
Requires-Dist: tree-sitter<1.0,>=0.22.0
Requires-Dist: tree-sitter-language-pack>=0.1.0
Provides-Extra: pdf
Requires-Dist: python-docx<2.0,>=0.8.11; extra == "pdf"
Requires-Dist: reportlab<5.0,>=4.0; extra == "pdf"
Provides-Extra: batch
Requires-Dist: anthropic<1.0,>=0.25.0; extra == "batch"
Provides-Extra: crypto
Requires-Dist: cryptography>=46.0.6; extra == "crypto"
Provides-Extra: clone
Requires-Dist: datasketch<2.0,>=1.6.0; extra == "clone"
Provides-Extra: bench
Requires-Dist: semgrep<2.0,>=1.168; extra == "bench"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
Requires-Dist: pytest-cov<6.0,>=4.0; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15.0; extra == "dev"
Requires-Dist: bandit<2.0,>=1.7.0; extra == "dev"
Requires-Dist: mypy<2.0,>=1.0; extra == "dev"
Requires-Dist: nuitka<3.0,>=2.0; extra == "dev"
Requires-Dist: ordered-set<5.0,>=4.0; extra == "dev"
Requires-Dist: datasketch<2.0,>=1.6.0; extra == "dev"
Requires-Dist: jsonschema<5.0,>=4.20; extra == "dev"
Requires-Dist: import-linter<3.0,>=2.1; extra == "dev"
Provides-Extra: all
Requires-Dist: truemend[batch,clone,crypto,dev,pdf]; extra == "all"
Dynamic: license-file

# TrueMend — The AI Code Quality Engine

> Your codebase is 40% AI-generated. Most of it has bugs you haven't found yet.

[![CI](https://github.com/alsajoo/truemend/actions/workflows/ci.yml/badge.svg)](https://github.com/alsajoo/truemend/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## The Problem

AI coding tools write code fast. They also:
- Wrap everything in try-catch blocks that swallow errors silently
- Leave `console.log` debugging statements in production code
- Generate redundant comments that describe *what* the code does, not *why*
- Copy-paste similar logic 15 times instead of extracting a function
- Add defensive checks that can never fail
- Leave placeholder TODOs that look like finished code
- Generate 300-line functions no human would write

**You can't see it. Your team can't review it all. Your CI doesn't catch it.**

## The Solution

```bash
git clone https://github.com/alsajoo/truemend.git
cd truemend
pip install -e .
truemend .
```

TrueMend finds AI-generated code quality issues using AST analysis — no LLM calls, no API keys, no cloud. It runs in seconds, finds the patterns humans miss, and can fix many of them automatically.

```
$ truemend src/

  Health 6.6/10  |  47 files  |  312 issues  (1 high, 38 medium)

Severity  Pattern                    File                Line  Description
--------  -------------------------  ------------------  ----  ---------------------------------------
high      guardrails_pii_no_filter   src/api/handler.py  142   LLM output returned without PII filter
high      ai_unchecked_tool_output   src/api/handler.py  88    Tool output used without validation
medium    slop_redundant_comment     src/utils.ts        15    Comment restates the code below it
medium    unnecessary_try_catch      src/db/query.ts     34    try-catch wraps code that can't throw

  ... 308 findings hidden (use --verbose to show all)
```

## What TrueMend Detects

Detection specs covering the things AI gets wrong most often:

| Category | Examples |
|----------|----------|
| **AI Slop** | Redundant comments, placeholder text, verbose variable names, TODOs disguised as code |
| **Error Handling** | Empty try-catch, catch-and-swallow, catch-rethrow, missing error types |
| **LLM Safety** | Unchecked model output, missing guardrails, PII in prompts, unvalidated tool results |
| **Agent Patterns** | Missing retry logic, no timeout on API calls, unbounded context, hallucinated imports |
| **Microsoft AI** | Semantic Kernel prompt injection, Azure OpenAI hardcoded keys, Foundry citation gaps, ML.NET untrusted models |
| **Azure Infrastructure** | PSRule-mirrored Terraform detectors: TLS, NSG wildcards, KeyVault permissions, storage exposure |
| **Code Hygiene** | console.log, debugger statements, unused imports, var instead of const/let |
| **Structural** | 300-line functions, copy-paste duplicates, deep nesting, passthrough wrappers |

22 languages: TypeScript, TSX, JavaScript, Python, C#, Go, Rust, Java, Kotlin, Swift, Dart, Ruby, Bash, SCSS, PowerShell, SQL, Dockerfile, YAML, C, CPP, PHP, and Terraform.

Plus framework-specific patterns for React, Next.js, Flutter, Django, FastAPI, Express, Spring Boot, and 60+ more frameworks — including deep Microsoft/.NET coverage: ASP.NET Core, EF Core, Blazor, Azure Functions, Semantic Kernel, Microsoft.Extensions.AI, Azure OpenAI, Azure AI Foundry, and ML.NET.

## Fix It Automatically

Many issues don't need human review. TrueMend fixes them with deterministic AST transforms — guaranteed correct, zero risk:

```bash
truemend fix src/ --apply
```

Built-in transforms: remove try-catch-rethrow, strip console.log, remove unused imports, convert var to const/let, eliminate double negation, and more. Every transform produces a unified diff and verifies the result re-parses cleanly. Original source restored on failure.

## AI Code Analysis

TrueMend understands AI patterns specifically — not just generic code quality:

- **20 semantic dimensions** via Python AST analysis: runtime resilience, error transparency, concurrency safety, data completeness, code quality
- **AI/LLM detection specs**: OpenAI, Bedrock, voice AI, and more (additional provider surfaces ship opt-in)
- **Agent framework patterns**: missing retries, unbounded context, tool output validation, state management
- **AI debt score**: measures what percentage of your codebase shows AI-generated patterns and how severe they are

```bash
truemend slop src/              # focused AI slop detection
truemend src/ --verbose         # show all findings including low severity
truemend src/ --ci              # exit 0/1/2 for CI pipelines
```

## Works Where You Work

### CLI
```bash
truemend .                      # analyze current directory
truemend src/ --quick           # metrics only (<2s)
truemend fix src/ --apply       # apply safe fixes
truemend audit .                # deep quality audit
```

### MCP Server (Claude Code, Cursor, Copilot, etc.)
```json
{
  "mcpServers": {
    "truemend": {
      "command": "npx",
      "args": ["-y", "truemend-mcp"]
    }
  }
}
```
Or via Claude Code CLI:
```bash
claude mcp add truemend -- npx -y truemend-mcp
```
The `npx truemend-mcp` launcher auto-bootstraps the Python engine (via `uv` or
`pip`) — no manual Python setup needed. See
[full setup guide](docs/how-to/mcp-client-setup.md) for Cursor, VS Code, and more.

### Skills (Agent Overlays)

TrueMend ships instruction files that teach your AI coding agent how to drive the analyze → fix → verify loop:

```bash
truemend install-skill --agent claude     # Claude Code (default)
truemend install-skill --agent cursor     # Cursor
truemend install-skill --agent copilot    # GitHub Copilot
truemend install-skill --all              # all 10 supported agents
```

Supported agents: Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini, Aider, Roo, Amazon Q, Zed. Each overlay writes the right file for that agent (`.cursorrules`, `AGENTS.md`, `.github/copilot-instructions.md`, etc.).

Once installed, your agent gets a `/truemend` command set — `next` (jump to the highest-impact issue), `fix`, `verify`, `dashboard`. Ask it to review your code and it'll work the remediation loop without you typing CLI commands.

**Framework skills** add detection intelligence for specific stacks. They auto-load when TrueMend detects the framework in your project, but you can install them explicitly:

```bash
truemend skill list                       # browse 67 built-in skills
truemend skill install react              # add to ./.truemend/skills/
```

Framework skills cover React, Next.js, Django, FastAPI, Flask, Express, Spring Boot, Prisma, Drizzle, Kubernetes, Terraform, and more. See [creating skills](docs/how-to/creating-skills.md) to author your own.

### CI/CD
```yaml
# GitHub Actions
- uses: alsajoo/truemend@v1
  with:
    targets: 'src/'
    aggression: 'recommended'
```

```yaml
# Pre-commit hook
repos:
  - repo: https://github.com/alsajoo/truemend
    rev: v1.0.0
    hooks:
      - id: truemend
```

## Three-Tier Fix System

Not every issue should be fixed the same way:

| Tier | When | How | Risk |
|------|------|-----|------|
| **Deterministic** | Safe, mechanical fixes | AST transforms | Zero — verified re-parse |
| **Cataloged Refactor** | Pattern-based improvements | Guided LLM prompt | Low — constrained scope |
| **Structural Rewrite** | Architecture-level changes | Human decision | Requires review |

TrueMend knows which tier each issue belongs in. You don't have to decide.

## Plans

TrueMend is open-core. Everything you need to find and fix AI code issues is free, forever — the paid tiers add reporting, constrained-LLM refactors, deeper structural analysis, and team features.

| | Free | Pro | Max | Teams |
|---|:---:|:---:|:---:|:---:|
| AST analysis — all languages & specs | ✓ | ✓ | ✓ | ✓ |
| Deterministic auto-fixes (core transforms) | ✓ | ✓ | ✓ | ✓ |
| MCP server | ✓ | ✓ | ✓ | ✓ |
| SARIF / CI integration | ✓ | ✓ | ✓ | ✓ |
| Cataloged (constrained-LLM) refactors | — | ✓ | ✓ | ✓ |
| PDF & UX-audit reports | — | ✓ | ✓ | ✓ |
| Anthropic Batch-API delta scoring | — | ✓ | ✓ | ✓ |
| Component decomposition | — | ✓ | ✓ | ✓ |
| Structural rewrites & deep analysis | — | — | ✓ | ✓ |
| Custom rules | — | — | ✓ | ✓ |
| Cross-file analysis | — | — | ✓ | ✓ |
| Discovery / planning workflows | — | — | ✓ | ✓ |
| Seats, org management & priority support | — | — | — | ✓ |

**Free** is for individuals — analyze, fix, and run as an MCP server in your editor, no account or API key. **Pro** and **Max** add the reporting and deeper analysis for power users; **Teams** layers on multi-seat org features for companies. Clone and `pip install -e .` to run.

## Why TrueMend, Not [X]?

| | TrueMend | SonarQube | Semgrep | ESLint |
|---|---|---|---|---|
| AI slop detection | Built-in | No | No | No |
| LLM pattern detection | Built-in | No | No | No |
| Deterministic auto-fix | AST transforms | Limited | No | Yes |
| Function-level scoring | Per-function | Per-file | Per-file | Per-rule |
| Zero config | `truemend .` | Server setup | Config file | Config file |
| MCP integration | Built-in | No | No | No |
| Languages | 22 | 30+ | 30+ | JS/TS only |
| Runs offline | Yes | No | Yes | Yes |
| Cost | Free (open-core) | $150+/mo | Free/Enterprise | Free |

**Benchmarking data:** See [VERIFIED_METRICS.md](VERIFIED_METRICS.md) for current performance metrics, precision rates, and speed measurements.

## Quick Start

```bash
git clone https://github.com/alsajoo/truemend.git
cd truemend
pip install -e .
cd /path/to/your-project
truemend .
```

Not yet published to PyPI — install from source until it is. No config, no API keys, no setup.

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -x -q           # 11,300+ tests
python cli.py src/            # analyze TrueMend itself
```

## License

MIT
