Metadata-Version: 2.4
Name: aja-codeintel
Version: 0.1.9
Summary: CodeIntel CLI tool
Author: Shiva Areti
License: MIT License
        
        Copyright (c) 2026 Shiva Areti
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: cli,java,python,codebase,intelligence
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.21.1
Dynamic: license-file

# AJA – Code Intelligence for Java & Python

**Understand your codebase. Not just files — architecture.**

AJA is a codebase intelligence CLI for Java and Python projects. It gives you structural visibility that no IDE provides by default — how services connect to models, what depends on what, and where code actually lives across layers.

Built for developers who work in real, messy, large codebases — not toy projects.

---

## Why AJA?

Standard IDE tools give you:
- Go to definition
- File search
- Text grep

That's not enough in real codebases where:
- A single service touches a dozen models
- Relationships are implicit and never documented
- "Go to definition" sends you three layers deep with no map back

AJA gives you the layer above all of that:

> **Architectural navigation — understand the system, not just the file.**

---

## Core Workflow

AJA is built around three actions:

### 🔍 Analyze
Scan your project once. AJA builds a structural map of every service, model, repository, controller, and their relationships — across your entire codebase.

### 🧭 Jump
Navigate instantly to any file, model, or service by name. No folder browsing. No tab switching. No guessing.

### 📋 Act
Extract exactly the right context for code review, refactoring, documentation, or AI-assisted analysis.

---

## Key Features

| Feature | Details |
|---|---|
| Java & Python support | Static analysis, no compilation needed |
| Service → model → repository mapping | Full architectural layer visibility |
| Forward dependency traversal | What does this file depend on? |
| Reverse dependency traversal | What depends on this file? |
| Symbol-level relationships | Classes, methods, interfaces across files |
| Offline & local | No network, no server, no telemetry |
| Read-only | Zero modification to your project, ever |

---

## Getting Started

```bash
pip install aja-codeintel
cd your-project/
aja scan .
aja tree .
```

That's it. AJA is now aware of your project structure.

---

## Commands — Full Reference

---

### `aja scan .`

**What it does:** Indexes all Java and Python source files in your project. Builds the internal graph of imports, dependencies, and relationships that every other command relies on.

**When to use it:** Once when you first open a project. Again after major structural changes (adding services, moving files).

```bash
aja scan .
```

> Run this first. Everything else depends on it.

---

### `aja tree .`

**What it does:** Prints a clean, source-only tree of your project. Filters out build artifacts, cache folders, and non-source files so you see only what matters.

**When to use it:** Getting your bearings in an unfamiliar codebase. Understanding folder structure at a glance.

```bash
aja tree .
```

Example output:
```
project/
├── controller/
│   └── UserController.java
├── service/
│   └── UserService.java
├── model/
│   └── User.java
└── repository/
    └── UserRepository.java
```

---

### `aja open <name>`

**What it does:** Fuzzy-searches your indexed project and opens the best matching file. You don't need the full path or exact name.

**When to use it:** When you know roughly what you're looking for but don't want to browse folders.

```bash
aja open UserService
aja open EmailService
aja open AppConfig
```

> Saves you from clicking through 6 folders to find one file.

---

### `aja servicemap <service>`

**What it does:** Maps a service to everything it touches — controllers that call it, models it uses, and repositories it depends on. Gives you a full architectural picture of one service in seconds.

**When to use it:** Before modifying a service. During code review. When onboarding to understand how a service fits into the system.

```bash
aja servicemap userservice
```

Example output:
```
UserService
├── Called by → UserController
├── Uses model → User, Address
└── Depends on → UserRepository, EmailService
```

> This is the command that replaces 20 minutes of manual tracing.

---

### `aja modeltree <model>`

**What it does:** Shows everywhere a domain model is referenced — which services use it, which repositories store it, which controllers expose it. Full vertical slice through your architecture for one model.

**When to use it:** Before renaming or modifying a model. Understanding the full impact of a data structure change.

```bash
aja modeltree User
aja modeltree Address
aja modeltree Order
```

Example output:
```
User (model)
├── UserService (service)
├── UserRepository (repository)
├── UserController (controller)
├── UserResponse (dto)
└── UserCreateRequest (dto)
```

> Know the full blast radius before you touch anything.

---

### `aja related <file> --depth <n>`

**What it does:** Shows all files that the given file directly or transitively imports and depends on. Depth controls how many layers deep to traverse.

**When to use it:** Understanding what a file pulls in. Checking for bloated dependencies. Preparing for a refactor.

```bash
aja related UserService --depth 1   # direct dependencies only
aja related UserService --depth 2   # dependencies of dependencies
aja related UserService --depth 3   # full transitive graph
```

> Start at depth 1, go deeper only when you need to.

---

### `aja rrelated <file>`

**What it does:** The reverse of `related`. Shows every file in your project that imports or depends on the given file. This is what standard IDEs almost never show you clearly.

**When to use it:** Before deleting or renaming a file. Understanding who will break if you change this. Identifying high-impact files in your codebase.

```bash
aja rrelated User
aja rrelated EmailService
aja rrelated ValidationUtil
```

Example output:
```
User.java is depended on by:
├── UserService.java
├── UserRepository.java
├── UserController.java
└── UserResponse.java
```

> If this list is long, think twice before changing that file.

---

### `aja relsymbols <file>`

**What it does:** Goes deeper than file-level relationships. Shows which specific classes, methods, and interfaces from this file are used across other files — and exactly where.

**When to use it:** Refactoring a class or method. Understanding which parts of a file are actually used vs. dead code candidates.

```bash
aja relsymbols UserService
aja relsymbols ValidationUtil
```

Example output:
```
UserService
├── createUser() → used in UserController.java
├── getUserById() → used in UserController.java, AdminService.java
└── deleteUser() → used in AdminController.java
```

> Symbol-level precision, not just file-level noise.

---

### `aja imports <file>`

**What it does:** Lists all local imports found in a given file — what it directly pulls in from your project (not third-party libraries).

**When to use it:** Quick check of what a file depends on without running the full graph.

```bash
aja imports UserService.java
aja imports orders.py
```

---

### `aja resolve <import-path>`

**What it does:** Converts a logical import path (like a Java package path or Python module path) into the actual file location on disk.

**When to use it:** When you see an import in code and want to jump to the real file fast.

```bash
aja resolve com.example.service.UserService
aja resolve app.domain.entity.user
```

---

### `aja where <file>`

**What it does:** The reverse of `resolve`. Takes a file path and tells you its import path — what you'd write if you were importing it from another file.

**When to use it:** When you need to write an import and don't want to manually construct the package path.

```bash
aja where src/main/java/com/example/service/UserService.java
aja where app/domain/entity/user.py
```

---

### `aja folder <path>`

**What it does:** Lists all source files under a given folder recursively. Respects AJA's source-file filtering (Java and Python only).

**When to use it:** Quickly auditing what's inside a specific module or package folder.

```bash
aja folder src/main/java/com/example/service
aja folder app/domain
```

---

### `aja models`

**What it does:** Lists all domain models and entities found in your project, detected from conventional model/entity folder patterns.

**When to use it:** Getting a full inventory of your data models. Onboarding. Architecture review.

```bash
aja models
```

---

### `aja fastapi-scan .`

**What it does:** Full FastAPI project scan — resolves complete route paths including `APIRouter` prefixes and `include_router` prefix stacking, extracts Pydantic DTOs (with required/optional fields, default values, nested models), and extracts SQLAlchemy entity models (columns, types, primary keys, foreign keys, relationships). Produces structured JSON matching the same schema as the Java Spring Boot scanner.

**When to use it:** Deep analysis of a FastAPI codebase. Generating API + data model inventory. Feeding structured metadata into AI tools or documentation pipelines.

```bash
# JSON report (default) — same schema as Java scanner
aja fastapi-scan .

# Human-readable text
aja fastapi-scan . --format text

# Only paths under /api
aja fastapi-scan . --only-api

# Skip DTOs or models from output
aja fastapi-scan . --no-dtos
aja fastapi-scan . --no-models
```

**Output schema (JSON):**
```json
{
  "endpoints": [
    {
      "method": "POST",
      "path": "/api/v1/users",
      "file": "app/routers/users.py",
      "line": 24,
      "handler": "create_user",
      "framework": "fastapi",
      "controller": "CreateUserRequest"
    }
  ],
  "dtos": [
    {
      "name": "CreateUserRequest",
      "file": "app/schemas/user.py",
      "kind": "pydantic",
      "bases": ["BaseModel"],
      "fields": [
        { "name": "name",  "type": "str",          "required": true,  "default": null },
        { "name": "email", "type": "str",          "required": true,  "default": null },
        { "name": "age",   "type": "Optional[int]","required": false, "default": "None" }
      ]
    }
  ],
  "models": [
    {
      "name": "User",
      "file": "app/models/user.py",
      "kind": "sqlalchemy",
      "table": "users",
      "columns": [
        { "name": "id",    "type": "Integer", "primary_key": true,  "foreign_key": null },
        { "name": "email", "type": "String",  "primary_key": false, "foreign_key": null }
      ],
      "relationships": [
        { "name": "posts", "target": "Post", "kind": "relationship" }
      ]
    }
  ]
}
```

**What the FastAPI scanner resolves:**

| Pattern | Resolved path |
|---|---|
| `APIRouter(prefix="/users")` + `@router.get("/")` | `/users` |
| `app.include_router(router, prefix="/api")` | `/api/users` |
| `app.include_router(router, prefix="/v1")` + router prefix `/api` | `/v1/api/users` |
| `@router.api_route("/ping", methods=["GET","HEAD"])` | `GET /ping` + `HEAD /ping` |

**What the Pydantic extractor captures:**

- `class X(BaseModel)` — direct BaseModel subclass
- `class X(SomeBase)` — inherited from another Pydantic model in the same project
- Required vs optional fields (`Optional[T]`, `T | None`, `Field(...)`, no default)
- Default values including `Field(default=…)`
- List types (`List[str]`, `list[int]`)

**What the SQLAlchemy extractor captures:**

- Classic declarative style: `Column(Integer, primary_key=True)`
- Modern mapped style: `id: Mapped[int] = mapped_column(primary_key=True)`
- Foreign keys: `Column(Integer, ForeignKey("users.id"))`
- Relationships: `relationship("Post", back_populates="author")`
- `__tablename__`

---

### `aja copy <file>`

**What it does:** Copies the full contents of a file (or multiple files) to your clipboard — ready to paste into a code review, chat, or AI tool.

**When to use it:** Preparing context for AI-assisted analysis. Sharing code in reviews. Extracting content without opening the file.

```bash
aja copy src/main/java/com/example/service/UserService.java
```

---

### `aja context <file>`

**What it does:** Builds a layered context bundle around a file — the file itself plus its most relevant related files. Designed to give AI tools or code reviewers exactly the right amount of context, nothing more.

**When to use it:** Before asking an AI tool to review or refactor a component. Preparing a PR description.

```bash
aja context UserService
aja context UserService --depth 2
```

---

### `aja version`

```bash
aja version
```

Prints the current AJA version.

---

## Supported Languages

| Language | Analysis | Imports | Symbols | Services | Models | Endpoints |
|----------|----------|---------|---------|----------|--------|-----------|
| Java (Spring Boot) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Python (FastAPI) | ✅ | ✅ | ✅ | ✅ | ✅ (Pydantic + SQLAlchemy) | ✅ (prefix-resolved) |

> Static analysis only — no compilation, no runtime, no build tools required.

---

## When to Use AJA

| Situation | Best Command |
|---|---|
| Just opened an unfamiliar codebase | `aja tree .` → `aja models` |
| About to modify a service | `aja servicemap <service>` |
| About to delete or rename a file | `aja rrelated <file>` |
| Reviewing a PR | `aja related <file> --depth 2` |
| Want to understand a model's impact | `aja modeltree <model>` |
| Preparing context for AI tools | `aja context <file>` or `aja copy <file>` |
| Tracing an import to its source | `aja resolve <import>` |

---

## What AJA Is NOT

| ❌ Not this | ✅ It's this instead |
|---|---|
| A debugger | A static structure analyzer |
| A build tool | A read-only intelligence layer |
| A language server | A fast, offline graph query tool |
| Cloud-dependent | Fully local, no telemetry |
| An IDE replacement | A complement to your IDE |

---

## Design Principles

- **Zero configuration** — point it at any project and it works
- **Read-only always** — AJA never writes to or modifies your project
- **Human-readable output** — designed for terminals and humans, not just machines
- **Deterministic** — same input always produces the same output
- **Fast** — sub-second responses on most commands

---

## Requirements

- Python 3.8+
- Java or Python project (or both)

---


---

>If IDEs help you write code,
> **AJA helps you understand it.**
