Metadata-Version: 2.4
Name: nextropy
Version: 0.1.0
Summary: Temporal code quality observatory — track metrics across git history to measure AI impact
Project-URL: Homepage, https://github.com/Nexapp/NexTropy
Project-URL: Repository, https://github.com/Nexapp/NexTropy
Project-URL: Issues, https://github.com/Nexapp/NexTropy/issues
Author: Nexapp
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: plotly>=5.0
Requires-Dist: polars>=1.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: radon>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: ruptures>=1.1
Provides-Extra: csharp
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == 'csharp'
Requires-Dist: tree-sitter>=0.24; extra == 'csharp'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: kotlin
Requires-Dist: tree-sitter-kotlin>=0.23; extra == 'kotlin'
Requires-Dist: tree-sitter>=0.24; extra == 'kotlin'
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == 'llm'
Description-Content-Type: text/markdown

# NexTropy

Temporal code quality observatory -- track metrics across git history to measure AI impact.

## Installation

```bash
pip install -e .

# Optional: enable LLM interpretation
pip install -e ".[llm]"
```

## System Requirements

- **Python 3.12+**
- **git** -- used for history walking and worktree management
- **Node.js + npm** *(optional)* -- enables TypeScript/JavaScript analysis. If missing, TS/JS files are silently skipped.

## How to Use

### Step 1 -- Scan the current codebase

Run a one-shot scan on your repository to compute quality metrics (cyclomatic complexity, SLOC, erosion ratio, etc.) and store a snapshot.

```bash
nextropy scan
```

Options:
- `--source-dir PATH` -- directory to scan (default: auto-detected git root)
- `--format json|markdown|html` -- output format (default: markdown)
- `--label "pre-AI"` -- attach a human-readable label to the snapshot
- `--no-store` -- print results without saving a snapshot

### Step 2 -- Walk git history

Build a time-series of snapshots by scanning multiple points in your git history.

```bash
# Scan at every tag (default strategy)
nextropy history

# Only tags matching a pattern
nextropy history --tag-pattern "v*"

# Scan one commit per week
nextropy history --strategy weekly

# Scan one commit per month
nextropy history --strategy monthly

# Scan every commit (sampled down to --max-snapshots)
nextropy history --strategy commits
```

Strategies:

| Strategy | What it scans | Useful when |
|----------|--------------|-------------|
| `tags` (default) | Every annotated or lightweight tag | Releases are tagged |
| `weekly` | One representative commit per ISO week | You want regular time intervals |
| `monthly` | One representative commit per month | Long-lived repos with many commits |
| `commits` | Every Nth commit (stride = total / max-snapshots) | You need fine-grained history |

Filtering and limits:

```bash
# Restrict to a date range
nextropy history --since 2024-01-01 --until 2024-06-30

# Cap the number of snapshots
nextropy history --strategy commits --max-snapshots 20

# Increase parallelism for faster scans
nextropy history --strategy monthly --parallelism 8

# Skip refs already stored (useful when re-running)
nextropy history --resume

# Attach a label to every snapshot
nextropy history --label "pre-AI"
```

### Step 3 -- Check stored data

List all stored snapshots and their date ranges.

```bash
nextropy status
```

### Step 4 -- Generate reports

Produce a report from stored snapshots.

```bash
# Markdown summary of the latest snapshot
nextropy report

# Interactive HTML dashboard with charts
nextropy report --format html

# Filter by date range
nextropy report --since 2024-01-01 --until 2024-06-30

# Include an AI-generated narrative (requires ANTHROPIC_API_KEY)
nextropy report --format html --with-llm
```

### Step 5 -- Track metric trends

Follow a specific metric over time.

```bash
# Default: erosion_ratio
nextropy trend

# Track average cyclomatic complexity
nextropy trend --metric avg_cc

# With changepoint detection
nextropy trend --metric erosion_ratio --detect-changepoints

# JSON output for scripting
nextropy trend --metric total_sloc --format json
```

Available metrics: `erosion_ratio`, `avg_cc`, `total_sloc`, `total_functions`, `high_functions`, `max_cc`, `p90_cc`, `total_files`, `total_mass`, `comment_density`, `test_to_code_ratio`, `boilerplate_ratio`, `naming_consistency`, `error_handling_entropy`.

### Step 6 -- Compare two refs

Side-by-side comparison of any two git refs (tags, branches, SHAs). NexTropy uses stored snapshots when available and scans on-the-fly otherwise.

```bash
nextropy compare v1.0 v2.0

# HTML output
nextropy compare main feat/refactor --format html
```

This also prints the **AI Impact Index**, a composite score indicating improvement or degradation.

### Step 7 -- Detect anomalies

Flag unusual metric spikes or drops in the time-series using rolling z-scores.

```bash
nextropy anomaly

# Adjust sensitivity
nextropy anomaly --window 10 --threshold 3.0
```

### Step 8 -- LLM interpretation

Get a natural-language narrative analysis of your metrics (requires `ANTHROPIC_API_KEY`).

```bash
# Interpret trends across all stored snapshots
nextropy interpret

# Focus on a specific topic
nextropy interpret --focus "erosion score trend"

# Interpret a comparison between two refs
nextropy interpret --compare v1.0 v2.0
```

## Configuration

NexTropy reads settings from environment variables and `.nextropy.toml`. Key settings:

| Variable | Description |
|----------|-------------|
| `ANTHROPIC_API_KEY` | Enables LLM interpretation features |
| `NEXTROPY_CC_THRESHOLD` | Cyclomatic complexity threshold for high-mass functions (default: 10) |
| `NEXTROPY_EROSION_WARN` | Erosion ratio warning threshold |
| `NEXTROPY_EROSION_BLOCK` | Erosion ratio that causes `scan` to exit with code 1 |
