projectintel 0.1.2

A Python toolkit for static analysis, project understanding, and automated code insights.

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.

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

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

Using the Python API

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:

# Output from project.cycles
[['A.py', 'B.py', 'A.py']]

Critical Functions

Functions are scored by incoming_calls + outgoing_calls.

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

---

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