Metadata-Version: 2.4
Name: projectintel
Version: 0.1.4
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/)

Static analysis toolkit for Python codebases. ProjectIntel parses a project with the `ast` module, builds its dependency and call graphs, and reports on structural issues: circular imports, orphan files, dead code, and critical functions.

---

## Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Architecture](#architecture)
- [API Reference](#api-reference)
- [Output Examples](#output-examples)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

## Features

- Recursive project scanning that skips `venv`, `__pycache__`, and `.git`
- Import resolution, separating local and external dependencies
- Circular dependency detection
- Orphan file detection (files not imported anywhere in the project)
- Project-wide function call graph
- Entry point detection (`if __name__ == "__main__":`)
- Execution flow tracing from each entry point
- Function criticality ranking, by in-degree/out-degree in the call graph
- Unused function detection
- Reporting to the terminal or via the Python API

---

## Installation

Requires Python 3.10+.

```bash
pip install projectintel
```

The CLI script (`run.py`) is not part of the PyPI distribution. To use the CLI, clone the repository instead:

```bash
git clone https://github.com/Kishorestalin-AIML/ProjectIntel.git
cd ProjectIntel
pip install -e .
```

---

## Usage

### CLI

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

### Python API

```python
from projectintel.scanner.project_scanner import ProjectScanner
from projectintel.analyzer.dependency import DependencyBuilder, ReverseDependency, CycleDetector, OrphanDetector
from projectintel.analyzer.semantic import SemanticAnalyzer

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

# 2. Dependency analysis
DependencyBuilder(project).build()
ReverseDependency(project).build()
CycleDetector(project).detect()
OrphanDetector(project).detect()

# 3. Semantic analysis (call graph, entry points, critical/unused functions)
SemanticAnalyzer(project).analyze()

# 4. Read the results
print(f"Total functions: {project.total_functions}")
print(f"Circular dependencies: {project.cycles}")
print(f"Orphan files: {project.orphan_files}")

for func, score in project.critical_functions[:5]:
    print(f"{func}: {score}")
```

---

## Architecture

Analysis runs in four phases:

| Phase | Name | Responsibility |
| :--- | :--- | :--- |
| 1 | Discovery | Recursively finds `.py` files; extracts classes, functions, and imports. |
| 2 | Dependency | Resolves imports; builds the file-level dependency graph; detects cycles and orphan files. |
| 3 | Semantics | Extracts function calls; builds the call graph; detects entry points and unused functions. |
| 4 | Intelligence | *In progress.* Graph visualization and HTML report generation. |

---

## API Reference

### `ProjectScanner`

Entry point for scanning a directory (Phase 1).

- `__init__(root_path: str)`
- `scan_project() -> ProjectMetadata`

### `DependencyBuilder`, `ReverseDependency`, `CycleDetector`, `OrphanDetector`

Phase 2 analyzers. Each takes a `ProjectMetadata` instance and writes into it.

| Class | Method | Populates |
| :--- | :--- | :--- |
| `DependencyBuilder` | `build()` | `dependency_graph` |
| `ReverseDependency` | `build()` | `reverse_dependencies` |
| `CycleDetector` | `detect()` | `cycles` (requires `dependency_graph`) |
| `OrphanDetector` | `detect()` | `orphan_files` (requires `reverse_dependencies`) |

### `SemanticAnalyzer`

Runs the full Phase 3 pipeline in one call: `CallGraphBuilder`, `ReverseCallGraph`, `EntryPointDetector`, `ExecutionFlow`, `CriticalFunctionAnalyzer`, `UnusedFunctionDetector`.

- `__init__(project: ProjectMetadata)`
- `analyze()`

### `ProjectMetadata` (model)

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `files` | `List[FileMetadata]` | Metadata for every scanned file. |
| `dependency_graph` | `Dict[str, List[str]]` | `file -> [dependencies]` |
| `reverse_dependencies` | `Dict[str, List[str]]` | `file -> [dependents]` |
| `orphan_files` | `List[str]` | Files not imported anywhere in the project. |
| `cycles` | `List[List[str]]` | Files forming circular imports. |
| `call_graph` | `Dict[str, List[str]]` | `function -> [called_functions]` |
| `critical_functions` | `List[Tuple[str, int]]` | Functions ranked by call graph centrality. |
| `unused_functions` | `List[str]` | Functions with no detected callers. |
| `total_files`, `total_classes`, `total_functions` | `int` | Project-level counts. |

---

## Output Examples

**Cycle detection.** If `A.py` imports `B.py` and `B.py` imports `A.py`:

```python
# project.cycles
[['A.py', 'B.py', 'A.py']]
```

**Critical functions.** Scored by `incoming_calls + outgoing_calls`:

```text
Auth.login              Score: 8
Database.connect        Score: 5
utils.hash_password     Score: 3
```

---

## Roadmap

- [ ] Phase 4: export graphs to Graphviz (DOT) and interactive HTML
- [ ] Framework-specific entry point detection (FastAPI, Flask, Django)
- [ ] Call resolution using PEP 484 type hints
- [ ] Cyclomatic complexity (McCabe) per function

---

## Contributing

1. Fork the repository.
2. Create a feature branch: `git checkout -b feature/your-feature`.
3. Commit your changes: `git commit -m 'Add your feature'`.
4. Push the branch: `git push origin feature/your-feature`.
5. Open a pull request.

---

## License

MIT. See [`LICENSE`](LICENSE).

## Author

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