Metadata-Version: 2.4
Name: projectintel
Version: 0.1.2
Summary: A Python toolkit for static analysis, project understanding, and automated code insights.
Author-email: Kishore Stalin <kishorestalin75@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Kishorestalin-AIML/ProjectIntel
Project-URL: Repository, https://github.com/Kishorestalin-AIML/ProjectIntel
Project-URL: Issues, https://github.com/Kishorestalin-AIML/ProjectIntel/issues
Keywords: python,static-analysis,code-analysis,project-analysis,developer-tools,automation,software-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ProjectIntel

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI Version](https://img.shields.io/pypi/v/projectintel.svg)](https://pypi.org/project/projectintel/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/projectintel)](https://pypi.org/project/projectintel/)


**ProjectIntel** is a high-performance static analysis toolkit designed to transform raw source code into actionable intelligence. By leveraging Python's Abstract Syntax Trees (AST), ProjectIntel maps project structures, resolves complex dependency graphs, and builds semantic call graphs to help developers understand, maintain, and optimize large-scale Python codebases.

---

## Overview

Modern Python projects often suffer from hidden architectural debt: circular dependencies, orphan files, and "dead" functions that are never called. ProjectIntel provides a multi-phase analysis pipeline that "scans" a directory and produces a comprehensive metadata model of the entire project.

### Why use ProjectIntel?

*   **Architectural Clarity:** Visualize how modules interact and identify tight coupling.
*   **Dependency Auditing:** Automatically detect circular dependencies and orphan modules.
*   **Semantic Deep-Dive:** Trace execution flows from entry points to leaf functions.
*   **Code Cleanup:** Identify unused functions and modules with high-confidence static analysis.
*   **Onboarding:** Quickly generate reports for new developers to understand the "critical paths" of a repository.

---

## Features

*   **Recursive Project Scanning:** Automatically ignores environments (`venv`), caches (`__pycache__`), and git metadata.
*   **Dependency Analysis:**
    *   Local vs. External import resolution.
    *   Circular dependency detection (Cycle detection).
    *   Orphan file detection (files not imported by any other project file).
*   **Semantic Analysis:**
    *   **Project-wide Call Graphs:** Maps function-to-function calls across different files.
    *   **Entry Point Detection:** Automatically identifies `if __name__ == "__main__":` blocks.
    *   **Execution Flow:** Traces the recursive path of execution from entry points.
    *   **Function Criticality:** Ranks functions based on their centrality (in-degree/out-degree) in the call graph.
*   **Structured Reporting:** Generate summaries, dependency maps, and semantic insights directly to the terminal or via API.

---

## Installation

ProjectIntel requires **Python 3.10 or higher**.

```bash
# Clone the repository
git clone https://github.com/Kishorestalin-AIML/ProjectIntel.git
cd ProjectIntel

# Install via pip
pip install .
```

---

## Quick Start

### Using the CLI

Analyze any Python project directory by running:

```bash
python run.py /path/to/your/project
```

### Using the Python API

```python
from projectintel.scanner.project_scanner import ProjectScanner
from projectintel.analyzer.dependency.dependency_builder import DependencyBuilder
from projectintel.analyzer.semantic.semantic_analyzer import SemanticAnalyzer

# 1. Scan the project structure
scanner = ProjectScanner("./my_project")
project = scanner.scan_project()

# 2. Run Dependency Analysis
DependencyBuilder(project).build()

# 3. Run Semantic Analysis (Call Graphs, etc.)
SemanticAnalyzer(project).analyze()

# 4. Access the intelligence
print(f"Total Functions: {project.total_functions}")
print(f"Detected Cycles: {project.cycles}")
for func, score in project.critical_functions[:5]:
    print(f"Critical Path: {func} (Score: {score})")
```

---

## Architecture

ProjectIntel operates in four distinct phases:

| Phase | Name | Responsibility |
| :--- | :--- | :--- |
| **Phase 1** | **Discovery** | Recursively finds `.py` files; extracts classes and function names. |
| **Phase 2** | **Dependency** | Resolves imports; builds file-level directed graphs; detects cycles. |
| **Phase 3** | **Semantics** | Extracts function calls; builds call graphs; identifies entry points. |
| **Phase 4** | **Intelligence** | (In Progress) Data visualization, HTML reports, and dashboard generation. |

---

## API Reference

### `ProjectScanner`
The entry point for scanning a directory.

*   **`__init__(root_path: str)`**: Initializes the scanner with the project root.
*   **`scan_project() -> ProjectMetadata`**: Executes Phase 1 analysis.
    *   **Returns:** A `ProjectMetadata` object containing a list of `FileMetadata`.

### `DependencyBuilder`
Constructs the module-level dependency graph.

*   **`__init__(metadata: ProjectMetadata)`**: Requires scanned metadata.
*   **`build() -> dict`**: Resolves all imports and populates `project.dependency_graph`.

### `SemanticAnalyzer`
Orchestrates the Phase 3 semantic pipeline.

*   **`analyze()`**: Runs the following internal sub-analyzers:
    *   `CallGraphBuilder`: Maps function calls.
    *   `EntryPointDetector`: Finds script start points.
    *   `CriticalFunctionAnalyzer`: Scores functions by importance.
    *   `UnusedFunctionDetector`: Identifies potential dead code.

### `ProjectMetadata` (Model)
The central data structure containing the project's state.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `files` | `List[FileMetadata]` | Metadata for every individual file. |
| `dependency_graph` | `Dict[str, List[str]]` | Map of `file -> [dependencies]`. |
| `call_graph` | `Dict[str, List[str]]` | Map of `function -> [called_functions]`. |
| `critical_functions` | `List[Tuple[str, int]]` | Functions ranked by call frequency. |
| `cycles` | `List[List[str]]` | Lists of files forming circular imports. |

---

## Use Cases

1.  **Refactoring:** Identify "Orphan Files" that are no longer imported and can be safely deleted.
2.  **Onboarding:** Use the "Execution Flow" to show new developers exactly what happens when the main script runs.
3.  **Risk Management:** Find "Critical Functions." If a function has a high score, a bug inside it will likely impact the entire system.
4.  **Architecture Validation:** Ensure that your `utils` module doesn't accidentally depend on your `main` module (Cycle Detection).

---

## Code Examples & Expected Outputs

### Detecting Cycles
If `A.py` imports `B.py`, and `B.py` imports `A.py`:
```python
# Output from project.cycles
[['A.py', 'B.py', 'A.py']]
```

### Critical Functions
Functions are scored by `incoming_calls + outgoing_calls`.
```text
Critical Functions:
Auth.login                     Score : 8
Database.connect               Score : 5
utils.hash_password            Score : 3
```

---

## Roadmap

*   [ ] **Phase 4 Visualization:** Export graphs to Graphviz (DOT) and interactive HTML.
*   [ ] **Framework Support:** Specialized entry-point detection for FastAPI, Flask, and Django.
*   [ ] **Type Hint Analysis:** Improve call resolution using PEP 484 type hints.
*   [ ] **Complexity Metrics:** Integration of Cyclomatic Complexity (McCabe) per function.

---

## Contributing

Contributions are welcome! Please follow these steps:
1. Fork the Project.
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`).
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`).
4. Push to the Branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.

---

## License

Distributed under the **MIT License**. See `LICENSE` for more information.

## Author

**Kishore Stalin** - [GitHub Profile](https://github.com/Kishorestalin-AIML)

---
*Documentation generated by ProjectIntel - Understanding code, one AST at a time.*
