nextropy 0.1.0

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

NexTropy

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

Installation

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.

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.

# 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:

# 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.

nextropy status

Step 4 -- Generate reports

Produce a report from stored snapshots.

# 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.

# 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.

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.

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).

# 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