Metadata-Version: 2.4
Name: egl-cli
Version: 0.1.1
Summary: Eagle — Android Commit Impact Engine for AAOS System Apps
Author-email: Abhinnav <abhinnav@example.com>
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pygit2>=1.14.0
Requires-Dist: neo4j>=5.20.0
Requires-Dist: tree-sitter>=0.22.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-kotlin>=0.1.0
Requires-Dist: tree-sitter-xml>=0.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: celery[redis]>=5.3.0
Requires-Dist: redis>=5.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: requests>=2.31.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: click>=8.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: orjson>=3.10.0
Provides-Extra: dev
Requires-Dist: pytest>=8.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.9.0; extra == "dev"
Requires-Dist: black>=24.3.0; extra == "dev"
Provides-Extra: indexing
Requires-Dist: cocoindex>=0.1.0; extra == "indexing"
Provides-Extra: mapping
Requires-Dist: graphifyy>=0.1.0; extra == "mapping"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == "build"
Requires-Dist: build>=1.0.0; extra == "build"
Provides-Extra: all
Requires-Dist: eagle[build,dev,indexing,mapping]; extra == "all"

# 🦅 Eagle — Android Commit Impact Engine

**Analyze the blast radius of every commit across your AAOS system apps.**

Eagle builds a source code knowledge graph from your Android repositories and uses it to compute the impact area of any commit — identifying affected classes, methods, mandatory test areas, historical Jira ticket risks, and producing a composite **Eagle Score** (0-100).

---

## Features

- **🔍 Knowledge Graph**: Full code structure in Neo4j — classes, methods, fields, inheritance, call chains, XML layouts, Android components
- **💥 Blast Radius**: Cypher-based traversal to find all impacted code at configurable depth
- **🧪 Test Mapping**: Automatic identification of mandatory test areas (graph-based + convention-based)
- **📊 Eagle Score**: Composite 0-100 risk score (change volume, fan-out, test coverage, code churn, static analysis, bug density)
- **🔗 Jira Correlation**: Link commits to historical tickets and find open bugs in the blast radius
- **⚡ Incremental Updates**: Only re-parse changed files on each commit (CocoIndex integration)
- **🤖 CI/CD Integration**: Webhooks for Gerrit/GitHub with automatic PR comment posting and merge gating
- **🌐 REST API**: FastAPI backend exposing all functionality
- **📱 Android-Specific**: Java, Kotlin, XML (layouts, manifests, navigation), Gradle module dependencies

## Tech Stack

| Layer | Technology |
|---|---|
| Orchestration | Python 3.11+ |
| Git Integration | pygit2 (libgit2) |
| Java AST | Tree-sitter + JavaParser (JVM service) |
| Kotlin AST | Tree-sitter + Kotlin Analysis API |
| XML AST | Tree-sitter XML + Android-aware extraction |
| Knowledge Graph | Neo4j 5.x |
| Incremental Index | CocoIndex |
| Graph RAG | GitNexus |
| Structural Map | Graphify |
| API | FastAPI |
| Task Queue | Celery + Redis |
| Metadata DB | PostgreSQL |

## Quick Start

### 1. Prerequisites
The only requirement to run Eagle's analysis engine is **Docker**. 
*(Note: If using the standalone binary, even Python is not required on the host machine).*

### 2. Install Eagle CLI
```bash
# From source
pip install -e .

# Or download the pre-built 'egl' binary for your platform
```

### 3. Start the Background Engine
Eagle manages its own infrastructure (Neo4j, Postgres, Redis) via Docker. Start it once:
```bash
egl daemon start
```

### 4. Initialize a Project
Eagle supports a **Hybrid Storage Model**:
- **Local Repos:** Run `egl init` inside an existing Git repo. It creates a local `.egl/` config.
- **Remote Repos:** Run `egl init <name> <url>` to clone a repo centrally into `~/.egl/repos/`.

```bash
# Example: Local project
cd ~/projects/my-android-app
egl init
egl index
egl impact symbol method com.example.MyClass.myMethod
```

## Architecture & Storage

Eagle uses a **Hybrid Configuration** to balance powerful graph analysis with a clean developer experience:

- **Global Storage (`~/.egl`):** This is the "brain" of Eagle. It stores the shared Neo4j knowledge graph, global metadata, and any centrally cloned repositories. This ensures that cross-repository impact analysis is fast and consistent.
- **Local Project Config (`.egl/`):** When you run `egl init` in a local folder, Eagle creates a small hidden `.egl/` directory. This tells the CLI to treat the current folder as a project and link it to the global background engine.
- **Zero-Installation Backend:** By using `egl daemon start`, the CLI automatically pulls and configures the necessary Docker containers (Neo4j 5, Postgres 16). You never have to manually install or configure a database.

## Packaging & Distribution

### Install from source (any platform)
```bash
pip install -e .                    # Editable dev install
pip install -e ".[all]"             # Everything (indexing, mapping, build tools, dev)
```

### Build a pip-installable wheel (universal)
```bash
pip install build
python -m build
# Output: dist/eagle-0.1.0-py3-none-any.whl  (works on Linux & Windows)
pip install dist/eagle-0.1.0-py3-none-any.whl
```

### Build standalone executables
```bash
pip install -e ".[build]"

# Build for your current platform
python scripts/build.py

# Output:
#   Windows: dist/egl-windows-x86_64.exe
#   Linux:   dist/egl-linux-x86_64

# Clean + rebuild
python scripts/build.py --clean
```

### Cross-platform CI build (GitLab CI example)
```yaml
# .gitlab-ci.yml
stages: [build]

build-linux:
  stage: build
  image: python:3.11
  script:
    - pip install -e ".[build]"
    - python scripts/build.py
  artifacts:
    paths: [dist/egl-linux-*]

build-windows:
  stage: build
  tags: [windows]
  script:
    - pip install -e ".[build]"
    - python scripts/build.py
  artifacts:
    paths: [dist/egl-windows-*]
```

### Install from Git (for CI/CD pipelines)
```bash
pip install git+https://your-git-server.com/eagle.git
```

After installation, both `eagle` and `egl` commands are available globally.

## CLI Command Reference

### Git-Like Workflow
```bash
egl init <name> <url>        # Register + clone
egl status                   # Show repo info
egl fetch                    # Fetch remote updates
egl log [-n 15]              # Commit history table
egl checkout <branch>        # Switch branches
```

### Analysis
```bash
egl commit analyze <sha>     # Single commit analysis
egl commit analyze A..B      # Range analysis
egl diff <sha>               # Entity-level diff
egl test-map <sha>           # Mandatory test discovery
egl jira <sha>               # Jira ticket correlation
egl query <symbol>           # Symbol blast radius
egl usages <type> <fqn>      # Smart find usages (Graph + Text)
egl impact symbol <type> <fqn> # Single symbol blast radius
```

### Graph & Indexing
```bash
egl index                    # Build knowledge graph
egl stats                    # Graph statistics
egl clear                    # Wipe graph data
egl scan [path]              # Classify source files
egl sync                     # Incremental index sync
egl enrich [--force] [--mcp] # Deep call-chain enrichment
egl map                      # Structural code mapping
```

### Fine-Grained AST Parsing
```bash
egl parse java <file>        # Java AST + call graph
egl parse kotlin <file>      # Kotlin AST
egl parse xml <file>         # Android XML (layout/manifest/nav)
egl parse gradle <file>      # Gradle dependencies
egl parse soong <file>       # Android.bp modules
```

## API Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/api/health` | GET | Health check |
| `/api/repos` | GET/POST | List/register repositories |
| `/api/repos/{id}/clone` | POST | Clone a repository |
| `/api/repos/{id}/analyze` | POST | Build knowledge graph |
| `/api/commits/{sha}/impact` | GET | Blast radius analysis |
| `/api/commits/{sha}/score` | GET | Eagle Score breakdown |
| `/api/graph/{repo}/stats` | GET | Graph statistics |
| `/api/webhooks/push` | POST | CI/CD push webhook |

## Eagle Score

| Range | Level | Action |
|---|---|---|
| 0–30 | 🟢 Low | Standard review |
| 31–60 | 🟡 Medium | Extended testing recommended |
| 61–80 | 🟠 High | Blast radius review + senior sign-off |
| 81–100 | 🔴 Critical | Full regression test required |

## License

Proprietary — Internal use only.

