egl-cli 0.1.0

Eagle — Android Commit Impact Engine for AAOS System Apps

🦅 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

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

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

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

pip install -e .                    # Editable dev install
pip install -e ".[all]"             # Everything (indexing, mapping, build tools, dev)

Build a pip-installable wheel (universal)

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

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)

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

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

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

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

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

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.