Introducing Graph-Powered Code Analysis

Why Traditional Linters Aren't Enough

Traditional static analysis tools like ESLint, Pylint, and Ruff are excellent at catching syntax errors, style violations, and common bugs. But they share a fundamental limitation: **they analyze files in isolation**.

When you run `ruff check`, each file is parsed and validated independently. The tool has no understanding of how your modules connect, which functions call which, or how changes in one file ripple through your codebase.

This isolation means traditional tools miss some of the most impactful issues:

- **Circular dependencies** that make code impossible to test

- **Architectural bottlenecks** where a single module has 100+ dependents

- **Dead code** that's exported but never imported

- **Feature envy** where functions constantly reach into other modules

Enter Knowledge Graphs

Repotoire takes a different approach. Instead of analyzing files one by one, we build a **knowledge graph** of your entire codebase:

Codebase → Parser (AST) → Entities + Relationships → Neo4j Graph → Detectors → Health Report

Every function, class, module, and import becomes a node in the graph. Relationships like `IMPORTS`, `CALLS`, `INHERITS`, and `USES` connect them together.

This graph-first approach enables queries that would be impossible with file-based analysis:

// Find all circular dependencies

MATCH path = (a:Module)-[:IMPORTS*]->(a)

WHERE length(path) > 1

RETURN path

// Find bottleneck modules (high in-degree)

MATCH (m:Module)<-[:IMPORTS]-(dependent)

WITH m, count(dependent) as importers

WHERE importers > 20

RETURN m.name, importers

ORDER BY importers DESC

The Three-Layer Analysis

Repotoire combines three types of analysis:

1. **Structural (AST)**: Parse code into abstract syntax trees, extract entities and relationships

2. **Semantic (NLP + AI)**: Understand naming patterns, detect code smells using natural language

3. **Relational (Graph)**: Run graph algorithms to find architectural issues

Each layer catches different types of issues. Together, they provide a holistic view of code health that no single tool can match.

Getting Started

Try Repotoire on your codebase today:

pip install repotoire

repotoire ingest /path/to/repo

repotoire analyze /path/to/repo -o report.html

The HTML report shows your health score broken down by Structure, Quality, and Architecture, with specific issues and fix suggestions.