# Aston AI

Aston is a code intelligence system for parsing, analyzing, and finding test coverage gaps in your code.

# Explain
aston init → creates chunks + nodes
aston graph build → uses those to create edges

## Installation

```bash
# Install from PyPI
pip install astonai

# For LLM-powered features (optional)
pip install "astonai[llm]"
```

## Quick Start

```bash
# Initialize your repository
aston init --offline

# Generate knowledge graph relationships
aston graph build

# View knowledge graph statistics
aston graph stats

# Smart incremental updates (recommended for ongoing development)
aston refresh

# Find critical paths and generate test suggestions
aston coverage --critical-path
aston test-suggest core/auth.py
```

## Core Commands

### Repository Initialization

```bash
# Initialize repository and create knowledge graph
aston init [--offline] [--preset PRESET] [--include PATTERN] [--exclude PATTERN]

# Incremental rechunk - fast updates for changed files only
aston init --rechunk [--offline]

# Force full rebuild
aston init --force [--offline]
```

**Advanced Filtering Options:**
- `--preset`: Apply preset configurations (`python-only`, `no-tests`, `source-only`, `minimal`)
- `--include`, `-i`: Include only files matching these glob patterns (can be used multiple times)
- `--exclude`, `-e`: Exclude files matching these glob patterns in addition to defaults (can be used multiple times)
- `--include-regex`: Include only files matching these regex patterns (can be used multiple times)
- `--exclude-regex`: Exclude files matching these regex patterns (can be used multiple times)
- `--dry-run`: Show which files would be processed without actually processing them
- `--show-patterns`: Display all active filter patterns and exit
- `--create-astonignore`: Create a template .astonignore file for persistent filtering

**Incremental Updates:**
- `--rechunk`: Process only files that have changed since last run (fast incremental updates)
- `--force`: Force complete rebuild even if knowledge graph exists

**Default Excludes**: Common directories are automatically excluded:
- `venv*/**`, `.venv*/**`, `env/**`, `.env/**`
- `node_modules/**`, `.git/**`, `.svn/**`, `.hg/**`
- `__pycache__/**`, `*.pyc`, `.pytest_cache/**`
- `build/**`, `dist/**`, `*.egg-info/**`
- `.idea/**`, `.vscode/**`, and more

**Examples:**
```bash
# Use preset configurations
aston init --preset python-only --offline
aston init --preset no-tests --offline

# Incremental rechunk for fast updates
aston init --rechunk --offline

# Custom filtering with patterns
aston init --include "src/**/*.py" --include "lib/**/*.py" --offline
aston init --exclude "legacy/**" --exclude "deprecated/**" --offline

# Use regex patterns for advanced filtering
aston init --include-regex ".*/(core|utils)/.*\.py$" --offline

# Preview what would be processed
aston init --preset minimal --dry-run

# Create .astonignore template for persistent rules
aston init --create-astonignore
```

**Environment Variables:**
- `ASTON_INCLUDE_PATTERNS`: Comma-separated include patterns
- `ASTON_EXCLUDE_PATTERNS`: Comma-separated exclude patterns

### Intelligent Refresh

```bash
# Smart incremental updates with change analysis
aston refresh [--strategy auto|incremental|full] [--force-full] [--dry-run]
```

The `refresh` command provides intelligent updates:
- **Auto Strategy**: Automatically chooses between incremental and full refresh based on changes
- **Change Detection**: Uses file hashes to detect actual modifications
- **Dry Run**: Preview what would be updated without making changes
- **Force Full**: Override auto-detection and force complete rebuild

**Examples:**
```bash
# Smart refresh (recommended)
aston refresh

# Preview changes without applying
aston refresh --dry-run

# Force full refresh
aston refresh --force-full

# Use specific strategy
aston refresh --strategy incremental
```

### Test Coverage

```bash
# Run tests with coverage
aston test

# Find testing gaps
aston coverage [--threshold 80] [--json results.json] [--exit-on-gap]

# Identify critical implementation nodes
aston coverage --critical-path [--n 50] [--weight loc]
```

Options:
- `--threshold`: Minimum coverage percentage (default: 0)
- `--json`: Output results in JSON format
- `--exit-on-gap`: Return code 1 if gaps found (useful for CI)
- `--coverage-file`: Specify custom coverage file location
- `--critical-path`: Identify critical code paths that need testing
- `--n`: Number of critical nodes to return (default: 50)
- `--weight`: Weight function for critical path (loc, calls, churn)

### Knowledge Graph

```bash
# Build edge relationships between nodes with advanced filtering
aston graph build [--preset PRESET] [--include PATTERN] [--exclude PATTERN]

# View statistics about the knowledge graph
aston graph stats

# Export graph to DOT format
aston graph export [--output graph.dot] [--filter CALLS,IMPORTS] [--open]

# Open interactive graph viewer in browser
aston graph view [--filter CALLS,IMPORTS]
```


**Advanced Filtering for Graph Build:**
- `--preset`: Apply preset configurations (`python-only`, `no-tests`, `source-only`, `minimal`)
- `--include`, `-i`: Include only files matching these glob patterns (can be used multiple times)
- `--exclude`, `-e`: Exclude files matching these glob patterns in addition to defaults (can be used multiple times)
- `--include-regex`: Include only files matching these regex patterns (can be used multiple times)
- `--exclude-regex`: Exclude files matching these regex patterns (can be used multiple times)
- `--dry-run`: Show which files would be processed without actually processing them
- `--show-patterns`: Display all active filter patterns and exit

**Examples:**
```bash
# Build with preset filtering
aston graph build --preset no-tests

# Include only specific directories
aston graph build --include "src/**/*.py" --include "lib/**/*.py"

# Use regex patterns for advanced filtering
aston graph build --include-regex ".*/(core|utils)/.*\.py$"

# Preview what would be processed
aston graph build --preset python-only --dry-run
```

The graph command provides:
- `build`: Analyzes your codebase to extract CALLS and IMPORTS edges with advanced filtering
- `stats`: Displays node and edge statistics
- `export`: Exports to Graphviz DOT format for external visualization
- `view`: Opens interactive D3-force based viewer in browser

### Test Suggestions

```bash
# Generate test suggestions for a file or function
aston test-suggest <file_or_node> [--k 5] [--llm] [--model gpt-4o]

# Generate rich context for developers or AI agents
aston test-suggest <file_or_node> --prompt [--llm]

# Debug path resolution issues
aston test-suggest <file_or_node> --debug
```

Options:
- `--k`: Number of suggestions to generate (default: 5)
- `--llm`: Use LLM fallback if heuristics fail
- `--model`: LLM model to use (default: gpt-4o)
- `--budget`: Maximum cost per suggestion (default: $0.03)
- `--prompt`, `-p`: Generate rich context for test development
- `--debug`: Enable detailed debugging output
- `--json`/`--yaml`: Output results in structured format

### Environment Check

```bash
# Check if all required dependencies are installed
aston check
```

Options:
- `--no-env-check`: Skip environment dependency check (also works with any command)

## Repository-Centric Design

Aston follows a repository-centric approach:
- All operations are relative to the repository root (current directory)
- Data is stored in `.testindex` directory at the repository root
- Path resolution is normalized for consistent matching
- Works with both offline and Neo4j storage

## Environment Variables

```
DEBUG=1                      # Enable debug logging
NEO4J_URI=bolt://localhost:7687  # Optional Neo4j connection
NEO4J_USER=neo4j            # Optional Neo4j username
NEO4J_PASS=password         # Optional Neo4j password
ASTON_NO_ENV_CHECK=1        # Skip environment dependency check
OPENAI_API_KEY=sk-...       # Required for --llm features
```

