projectintel 1.0.0

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

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
• Installation
• Usage
• Architecture
• API Reference
• Output Examples
• Roadmap
• Contributing
• 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+.

pip install projectintel

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

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

---

Usage

CLI

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

Python API

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:

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

Critical functions. Scored by incoming_calls + outgoing_calls:

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

---

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.

Author

Kishore Stalin — GitHub