CodeInsight

Lightweight Static Code Analysis Tool for Python

Analyze Python source code safely using the Abstract Syntax Tree (AST) without executing it.

---

Overview

CodeInsight is a lightweight command-line static code analysis tool for Python. It analyzes Python source code without executing it, providing structural insights, syntax validation, code metrics, and code quality warnings using Python's built-in Abstract Syntax Tree (AST) module.

The project was built with a strong emphasis on clean architecture, modularity, maintainability, automated testing, and software engineering best practices.

---

Highlights

• ⚡ AST-based static analysis
• 📂 Recursive folder analysis
• 📊 Code metrics and reporting
• ✅ Static syntax validation
• 🧪 Unit tested
• 🔄 GitHub Actions CI
• 🏗 Modular architecture

---

Table of Contents

Table of Contents

• Overview
• Project Motivation
• Why AST?
• Features
• Design Principles
• Project Architecture
• Analysis Workflow
• Project Structure
• Technologies Used
• Installation
• Usage
• Running Unit Tests
• Project Roadmap
• Key Engineering Concepts Demonstrated

---

Project Motivation

Understanding source code without executing it is an important capability in modern software development. Static analysis helps developers detect issues early, understand project structure, and improve maintainability before runtime.

CodeInsight demonstrates how Python's built-in AST module can be used to safely inspect source code while applying professional software engineering practices such as modular architecture, separation of concerns, automated testing, and continuous integration.

---

Why AST?

Unlike regular expressions or string-based parsing, Python's Abstract Syntax Tree (AST) provides a structured representation of source code.

Using the built-in ast module allows CodeInsight to accurately identify functions, classes, imports, and other language constructs without executing the program, making the analysis both safe and reliable.

---

Features

Code Structure Analysis

• Count total lines
• Count blank lines
• Count comment lines
• Count functions
• Count classes
• Count imports

Code Element Extraction

• Extract function names
• Extract class names
• Extract imported modules

Static Syntax Validation

• Detect Python syntax errors
• Display syntax error line number
• Display syntax error message

Code Quality Insights

• Detect TODO comments
• Detect large functions
• Warn about low comment coverage
• Generate code health summary
• Generate recommendations

Folder Analysis

• Analyze a single Python file
• Recursively analyze an entire directory
• Generate individual reports for each Python file
• Display project summary

Report Generation

• Console report
• Text report
• Separate report for each analyzed file

Software Engineering Practices

• Modular architecture
• Separation of concerns
• Configuration management
• Unit testing
• GitHub Actions CI
• Clean project organization

---

Design Principles

• Single Responsibility Principle (SRP)
• Separation of Concerns
• Modular Architecture
• Configuration over hard-coded values
• Maintainability
• Testability

---

Project Architecture

---

Analysis Workflow

User Input
      │
      ▼
Select File / Folder
      │
      ▼
Validate Source Code
      │
      ▼
Parse with AST
      │
      ▼
Calculate Metrics
      │
      ▼
Detect Warnings
      │
      ▼
Generate Reports

---

Project Structure

CodeInsight/
│
├── analyzer.py
├── config.py
├── file_utils.py
├── main.py
├── metrics.py
├── parser.py
├── report.py
├── utils.py
├── validator.py
├── sample_code/
├── reports/
├── tests/
├── docs/
├── .github/
├── README.md
├── requirements.txt
└── .gitignore

---

Technologies Used

• Python 3.13
• Python Standard Library
  • ast
  • pathlib
  • unittest
• Git
• GitHub
• GitHub Actions

---

Installation

Clone the repository:

git clone https://github.com/Jatin048/CodeInsight.git
cd CodeInsight

Create a virtual environment:

python -m venv .venv

Activate it:

Windows

.venv\Scripts\activate

Linux / macOS

source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

---

Usage

Run:

python main.py

Example input:

sample_code

or

sample_code/sample1.py

Generated reports are automatically saved inside the reports/ directory.

---

Running Unit Tests

python -m unittest discover tests

The test suite also runs automatically on every push and pull request using GitHub Actions.

---

Sample Output

============================================================
PROJECT SUMMARY
============================================================

Files Found       : 4
Successful        : 3
Failed            : 1
Reports Generated : 3

---

Project Roadmap

Version 2

• Cyclomatic Complexity
• Dead Code Detection
• Duplicate Code Detection
• PEP 8 Naming Checks

Version 3

• HTML reports
• JSON reports
• PDF export

Long-Term Vision

• Command-line arguments (argparse)
• Plugin architecture
• Docker support

---

Key Engineering Concepts Demonstrated

• Static code analysis using Python AST
• Abstract Syntax Tree traversal
• Modular software architecture
• Separation of concerns
• Recursive file system traversal
• Static syntax validation
• Configuration management
• Automated unit testing
• Continuous Integration with GitHub Actions
• Report generation

---

Acknowledgements

This project leverages Python's built-in AST module and other standard library components to perform safe and efficient static code analysis.

---

License

This project is licensed under the MIT License.

---

Project Status

• ✅ Feature Complete
• ✅ Unit Tested
• ✅ GitHub Actions Enabled
• 🚀 Stable Release: v1.1.0

---

Author

Jatin Arora

Feel free to open an issue for bug reports, feature requests, or general feedback. Contributions and discussions are always welcome.