Metadata-Version: 2.4
Name: truemend
Version: 1.3.2
Summary: TrueMend — Autonomous Code Improvement Engine. Detects anti-patterns and fixes them using AST-based analysis.
Author-email: Al Sajoo <support@truemend.dev>
License: Apache-2.0 for the engine; Elastic-2.0 for specs/ and skills/ — see LICENSING.md
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 :: Other/Proprietary 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
License-File: LICENSE-ELASTIC-2.0
License-File: NOTICE
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: lint
Requires-Dist: ruff<0.16,>=0.15.0; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy<2.0,>=1.0; extra == "typecheck"
Provides-Extra: security
Requires-Dist: bandit<2.0,>=1.7.0; extra == "security"
Provides-Extra: arch
Requires-Dist: import-linter<3.0,>=2.1; extra == "arch"
Provides-Extra: schema
Requires-Dist: jsonschema<5.0,>=4.20; extra == "schema"
Provides-Extra: test
Requires-Dist: pytest<9.0,>=7.0; extra == "test"
Requires-Dist: pytest-cov<6.0,>=4.0; extra == "test"
Requires-Dist: pytest-xdist<4.0,>=3.6; extra == "test"
Provides-Extra: dev
Requires-Dist: truemend[arch,lint,schema,security,test,typecheck]; 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: tomli<3.0,>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: all
Requires-Dist: truemend[batch,clone,crypto,dev,pdf]; extra == "all"
Dynamic: license-file

# TrueMend

**Find the bugs your AI coding assistant left behind — deterministically, offline, in seconds.**

[![Engine: Apache 2.0](https://img.shields.io/badge/engine-Apache%202.0-blue.svg)](LICENSE)
[![Detection content: Elastic 2.0](https://img.shields.io/badge/detection%20content-Elastic%202.0-orange.svg)](LICENSE-ELASTIC-2.0)
[![PyPI](https://img.shields.io/pypi/v/truemend.svg)](https://pypi.org/project/truemend/)

TrueMend reads your code as a syntax tree and reports what is wrong with it —
swallowed exceptions, leftover debug statements, duplicated logic, unguarded LLM
output, dead code. It never calls a language model to decide what is a defect,
so the same input always produces the same findings, and nothing leaves your
machine.

Then it fixes what can be fixed safely, and tells you honestly which problems
need a human.

## Install

```bash
pip install truemend
```

Or run it with no install at all — as an MCP server inside your editor:

```bash
claude mcp add truemend -- npx -y truemend-mcp
```

Standalone binaries for Linux, macOS and Windows are attached to
[every release](https://github.com/alsajoo/truemend-engine/releases).

## Use it

```bash
truemend .                  # analyze the current directory
truemend audit .            # full quality audit with a readiness verdict
truemend fix src/ --apply   # apply only the fixes proven safe
```

A real run looks like this:

```
  Health score:      93.4/100
  Files analyzed:    247
  Anti-patterns:     639

  PRODUCTION READINESS: READY WITH WARNINGS

  Warnings:
    [WARN] 2 high-severity findings
    [WARN] 18 dead code blocks (114 lines)
    [WARN] 208 duplicate clusters (404 functions)

  Passing:
    [PASS] No critical-severity anti-patterns
    [PASS] No empty catch blocks
    [PASS] No hardcoded secrets detected
```

No configuration file, no API key, no account, no network call.

## What it looks for

The detector library is generated into [`facts.json`](facts.json) and currently
carries **4,709 detectors across 24 languages**:

| Area | Detectors |
|---|---:|
| Core languages | 2,376 |
| Quality & cross-cutting | 410 |
| Backend frameworks | 405 |
| AI / ML SDKs | 380 |
| DevOps & infrastructure | 378 |
| Web frontend | 333 |
| Database & ORM | 239 |
| Mobile | 188 |

Beyond pattern matching, it also does whole-project analysis: an import and call
graph, duplicate-cluster detection, orphaned-file detection, and 20 behavioural
dimensions derived from the Python AST.

Full inventory: **[Features](docs/FEATURES.md)** · **[Languages & frameworks](docs/LANGUAGES.md)**

## How it fixes things

Not every problem deserves the same treatment, so TrueMend sorts every finding
into one of three tiers and never blurs the line between them:

| Tier | What happens | Risk |
|---|---|---|
| **Deterministic** | An AST transform rewrites the code, then re-parses to verify | None — reverted if the result does not parse |
| **Cataloged refactor** | A constrained prompt for your own LLM, scoped to one pattern | Low — you review the diff |
| **Structural rewrite** | Described, never applied | Yours to decide |

> [!IMPORTANT]
> A transform is only run by default if it has a test and a catalog entry.
> 15 of the 82 registered transforms meet that bar; the rest are opt-in by name.
> This is deliberate — see the [changelog](CHANGELOG.md) for what happened the
> last time every registered transform ran automatically.

## Where it runs

| Surface | Setup |
|---|---|
| **CLI** | `pip install truemend` |
| **Editor (MCP)** | 28 tools and 10 resources over stdio — **[setup guide](docs/mcp-setup.md)** |
| **CI** | GitHub Actions, GitLab, pre-commit — **[CI guide](docs/ci-integration.md)** |
| **Coding agents** | `truemend install-skill --agent claude` writes overlays for 10 agents |

```yaml
# .github/workflows/truemend.yml
- uses: alsajoo/truemend-engine@v1.3.0
  with:
    targets: 'src/'
```

## Documentation

| | |
|---|---|
| [User guide](docs/user-guide.md) | Every command and flag |
| [MCP setup](docs/mcp-setup.md) | Claude Code, Cursor, VS Code, Claude Desktop |
| [CI integration](docs/ci-integration.md) | Pipelines, exit codes, SARIF |
| [API reference](docs/api-reference.md) | Using the engine as a library |
| [Editions](docs/editions.md) | What is free, what is licensed |
| [Comparison](docs/comparison.md) | How it differs from SonarQube, Semgrep, ESLint |
| [How-to guides](docs/how-to/) | Adding languages, writing detectors, authoring skills |

## Licensing in one paragraph

TrueMend is open core. The **engine is Apache 2.0** — `src/`, `cli.py`,
`truemend_mcp.py`, and the launchers. The **detection content is Elastic 2.0** —
the anti-pattern library and the agent skills. Internal use, modification and
self-hosting are all permitted; reselling TrueMend as a hosted service is not.
`pip install truemend` includes the core-language detectors; the framework,
AI/LLM, database and DevOps libraries require a licence.

[LICENSING.md](LICENSING.md) is the authoritative map of which licence covers
which path. [`docs/editions.md`](docs/editions.md) explains what each edition
actually contains.

