Metadata-Version: 2.4
Name: lmtrust
Version: 0.5.1
Summary: Deep Blind Spot Testing — systematic discovery and testing of code blind spots
Author: LMTrust Team
License: MIT
Project-URL: Homepage, https://github.com/user/lmtrust
Project-URL: Repository, https://github.com/user/lmtrust
Project-URL: Issues, https://github.com/user/lmtrust/issues
Keywords: testing,blind-spot,mutation-testing,llm,pytest,test-generation,code-quality
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mutmut>=2.4; extra == "dev"
Provides-Extra: hypothesis
Requires-Dist: hypothesis>=6.0; extra == "hypothesis"
Provides-Extra: analyze
Requires-Dist: openai>=1.0; extra == "analyze"

# LMTrust — Deep Blind Spot Testing

> Система глубокого тестирования «слепых зон» — находит ошибки, недоступные
> обычным тестам: нарушение неявных предположений, композиционные сбои,
> негативное пространство.

## Installation

```bash
pip install lmtrust

# With LLM analysis support (OpenAI, Ollama, etc.):
pip install lmtrust[analyze]

# With hypothesis property-based testing:
pip install lmtrust[hypothesis]

# Full dev setup:
pip install lmtrust[dev,analyze,hypothesis]
```

## Quick Example

```bash
# Run the full pipeline on a Python file (requires LLM):
lmtrust run src/mymodule.py --base-url http://localhost:11434/v1 --model qwen2.5-coder:7b

# Check test coverage matrix:
lmtrust coverage tests/test_mymodule.py

# Scaffold test skeletons from source:
lmtrust scaffold src/mymodule.py --layers L0,L1,L4,L9
```

## Что это

LMTrust — методология и скилл для LLM, который систематически находит слепые
зоны в коде и генерирует тесты-нарушители для каждой из них.

**Обычные тесты спрашивают:** «Код делает то, что должен?»

**Blind spot тесты спрашивают:** «Что код делает, чего НЕ должен? Какие
предположения он делает? Что происходит, когда они ломаются? Что НЕ
тестируется?»

## Architecture

LMTrust uses an **11-layer × 10-direction coverage matrix** (110 cells) to
systematically categorize test coverage:

- **Layers (L0–L9 + L4b):** Smoke, Contract, Boundary, Property, Adversarial,
  Fallback, State, Cross-System, Compositional, Temporal, Negative Space
- **Directions (D1–D10):** Range, State/Transition, Scale, Error Handling,
  Resource, Concurrency, Contract, Security, Performance, Negative

The pipeline has 5 steps:

```
Source Code → 1. Analyze → 2. Map → 3. Generate → 4. Verify → 5. Report
```

| Step | What it does | LLM or Mechanical? |
|------|-------------|-------------------|
| Analyze | Extract assumptions and invariants from code | LLM (semantics) |
| Map | Cross-reference assumptions with coverage matrix | Mechanical |
| Generate | Create pytest tests that violate each assumption | LLM (semantics) |
| Verify | Run mutation testing (mutmut) for kill score | Mechanical |
| Report | Generate markdown/JSON report | Mechanical |

**Principle:** Framework = mechanics, LLM = semantics. The framework handles
prompt construction, API calls, parsing, coverage matrices, and reporting.
The LLM provides the semantic understanding of what assumptions the code makes.

## Быстрый старт

1. **Прочитай `SKILL.md`** — главный файл. Содержит полную методологию:
   - 11 слоёв тестов (L0–L9 + L4b)
   - 10 направлений (D1–D10) + 2 именованных паттерна
   - Дерево решений для выбора слоёв по типу кода
   - 4 примера (чистая функция, stateful объект, файловый I/O, внешний API)
   - 8 антипаттернов
   - Pre-merge checklist
   - Шаг Verification (mutmut/Stryker)

2. **Используй шаблоны** из `templates/` — отправная точка для каждого слоя
   тестов

3. **Запусти Verification** — после генерации тестов, проверь их через
   мутационное тестирование:
   - Python: `mutmut run --paths-to-mutate=<module> --tests-dir=tests/`
   - C#/.NET: `dotnet stryker --project <project>.csproj`

## Структура

```
LMTrust/
├── SKILL.md              # Главный продукт — скилл для LLM
├── README.md             # Этот файл
├── references/
│   └── examples/         # Примеры использования
├── templates/            # Python-шаблоны для каждого слоя
│   ├── l0_smoke.py
│   ├── l1_contract.py
│   ├── l2_boundary.py
│   ├── l3_property.py
│   ├── l4_adversarial.py
│   ├── l4b_fallback.py
│   ├── l5_state.py
│   ├── l6_integration.py
│   ├── l7_compositional.py
│   ├── l8_temporal.py
│   └── l9_negative_space.py
├── src/lmtrust/          # Phase 2 — Python фреймворк + CLI
│   ├── __init__.py
│   ├── analyze.py        # LLM-based извлечение предположений (Step 1)
│   ├── map.py            # Cross-reference assumptions → blind spots (Step 2)
│   ├── generate.py       # LLM-based генерация тестов-нарушителей (Step 3)
│   ├── sandbox.py        # Pytest sandbox runner для Runtime Healing
│   ├── cli.py            # CLI entry point (click)
│   ├── scaffold.py       # Генератор тестовых скелетов из AST
│   ├── verify.py         # mutmut wrapper: запуск, парсинг, kill score
│   ├── report.py         # Генерация отчётов (markdown/json)
│   └── coverage.py       # Матрица Layer × Direction
├── tests/                # Unit-тесты фреймворка
│   ├── conftest.py
│   ├── test_analyze.py
│   ├── test_map.py
│   ├── test_generate.py
│   ├── test_sandbox.py
│   ├── test_coverage.py
│   ├── test_verify.py
│   ├── test_report.py
│   └── test_scaffold.py
├── tests/dogfood/        # Blind-spot тесты (dogfooding)
│   ├── test_analyze.py
│   ├── test_coverage.py
│   ├── test_cross_system.py   # L6+L7+L8: cross-module, compositional, temporal
│   ├── test_fallback.py       # L4b: fallback behavior
│   ├── test_generate.py
│   ├── test_map.py
│   ├── test_property.py       # L3: invariant/property tests
│   ├── test_report.py
│   ├── test_scaffold.py
│   └── test_verify.py
└── pyproject.toml        # Packaging (pip install -e .)
```

## CLI (Phase 2)

```bash
# Установка
pip install -e ".[dev]"

# Scaffold: извлечь функции из .py, сгенерировать скелет тестов
lmtrust scaffold <file.py> [--output tests/] [--layers L0,L1,L4,L9]

# Coverage: показать матрицу Layer × Direction для тестового файла
lmtrust coverage <test_file.py> [--format markdown|json]

# Verify: запустить mutmut на модуле, отчёт kill score
lmtrust verify <module> [--tests-dir tests/] [--kill-threshold 0.5]

# Analyze: извлечь предположения и инварианты через LLM (Step 1)
#   Требует OPENAI_API_KEY или --base-url. Установите: pip install lmtrust[analyze]
lmtrust analyze <file.py> [--model gpt-4o-mini] [--format markdown|json] [--output report.md]

# Map: предположения → слепые зоны (Step 2) — сверка с coverage matrix
lmtrust map <file.py> [--test-file tests/test_foo.py] [--format markdown|json] [--output blind_spots.md]

# Generate: сгенерировать тесты-нарушители для слепых зон (Step 3)
lmtrust generate <file.py> [--test-file tests/test_foo.py] [--output tests/] [--model gpt-4o-mini]

# Report: сгенерировать отчёт
lmtrust report <file.py> [--format markdown|json] [--test-file tests/test_foo.py]

# Run: полный пайплайн в одной команде (Analyze → Map → Generate → [Verify] → Report)
#   Требует OPENAI_API_KEY или --base-url. Установите: pip install lmtrust[analyze]
#   --runtime-heal: запуск сгенерированных тестов в песочнице, лечение ERROR-ошибок
lmtrust run <file.py> [--test-file tests/test_foo.py] [--output tests/] \
           [--report report.md] [--verify] [--model gpt-4o-mini] [--base-url URL] \
           [--format markdown|json] [--runtime-heal] [--heal-retries 3]

# Пример с Ollama:
lmtrust run src/lmtrust/coverage.py --base-url http://localhost:11434/v1 \
           --model qwen2.5-coder:7b -o reports/generated -r reports/demo.md
```

### Pipeline (5 шагов)

```
Код → 1. Analyze → 2. Map → 3. Generate → 4. Verify → 5. Report
```

| Шаг | CLI | Модуль | Что делает |
|-----|-----|--------|------------|
| 1. Analyze | `lmtrust analyze` | `analyze.py` | LLM извлекает предположения и инварианты |
| 2. Map | `lmtrust map` | `map.py` | Сверка с coverage matrix → слепые зоны |
| 3. Generate | `lmtrust generate` | `generate.py` | LLM генерирует тесты-нарушители |
| 4. Verify | `lmtrust verify` | `verify.py` | mutmut: kill score |
| 5. Report | `lmtrust report` | `report.py` | Markdown/JSON отчёт |
| **All** | **`lmtrust run`** | **all** | **Полный пайплайн в одной команде** |

### Analyze (LLM-based)

Команда `analyze` отправляет код в LLM с контекстом SKILL.md (таблица предположений,
слои, направления) и получает структурированный JSON. Фреймворк предоставляет
механику (промпт, API-вызов, парсинг, форматирование) — LLM обеспечивает семантику.

Provider-агностичный: любой OpenAI-совместимый endpoint через `--base-url`
(Ollama, LM Studio, Azure). Для кастомных интеграций — `CallableProvider`.

### Map (Step 2)

Команда `map` берёт предположения из `analyze` (где LLM уже определил `suggested_layer`,
`suggested_direction`, `severity`) и сверяет с coverage matrix. Непокрытые ячейки = слепые зоны.
Механика без эвристик — вся семантика от LLM.

### Generate (Step 3)

Команда `generate` берёт непокрытые слепые зоны из `map` и просит LLM сгенерировать
реальные pytest-тесты, которые нарушают каждое предположение. Тесты **должны падать** —
так находятся слепые зоны. Каждый тест получает `@pytest.mark.lmtrust` маркер.

### Runtime Healing (Phase 5)

Флаг `--runtime-heal` в команде `run` запускает сгенерированные тесты в песочнице
pytest прямо внутри конвейера. Если тесты падают с `ERROR` (неверные импорты,
отсутствующие фикстуры, неверные моки), ошибки отправляются обратно в LLM для
исправления. Цикл повторяется до успеха или до `--heal-retries` попыток.

**Важно:** лечатся только `ERROR` (сломан сам тест). `FAILED` (слепая зона найдена —
тест упал на assertion) НЕ лечатся — это цель тестирования.

```bash
# Пример с Runtime Healing:
lmtrust run src/mymodule.py --base-url http://localhost:11434/v1 \
           --model kimi-k2.7-code:cloud --runtime-heal --heal-retries 3
```

### Coverage markers

Для точного отслеживания покрытия используйте pytest markers в тестах:

```python
@pytest.mark.lmtrust(layer="L4", direction="D1")
def test_nan_crit(self):
    ...
```

`lmtrust coverage` парсит markers из AST — надёжно, без ложных срабатываний.
Если markers отсутствуют, используется fallback: имя класса → слой, имя метода → направление.

## Слои тестов

| Слой | Вопрос | Слепая зона |
| ------ | -------- | ------------- |
| L0: Smoke | Оно вообще живое? | Код не запускается |
| L1: Contract | Делает то, что говорит? | Нарушает контракт |
| L2: Boundary | Что на краях? | Ломается на границах |
| L3: Property | Что ВСЕГДА истинно? | Нарушает инварианты |
| L4: Adversarial | Что если предположения — ложь? | Ломается при нарушении |
| L4b: Fallback | Что когда основной путь недоступен? | Fallback ломается |
| L5: State | Все ли состояния достижимы? | Ломается при переходах |
| L6: Cross-System | A+B ломается? | Взаимодействие проваливается |
| L7: Compositional | Две вещи ломаются одновременно? | Комбинация сбоев |
| L8: Temporal | Зависит ли порядок? | Ломается в другом порядке |
| L9: Negative Space | Что НЕ должно происходить? | Делает лишнее |

## Интеграция с Kern Gate

Для критической математической и бизнес логики — используй [Kern Gate](https://pypi.org/project/kern-gate/) 
для формальной верификации контрактов и инвариантов. LMTrust дополняет

## Лицензия

MIT
