Add pluggable parsers architecture

Author: xnuinside

ARCHITECTURE.md

@@ -14,7 +14,12 @@ codegraph/
 │   ├── __init__.py         # Package init, version definition
 │   ├── main.py             # CLI entry point (click-based)
 │   ├── core.py             # Core graph building logic
-│   ├── parser.py           # Python source code parser
+│   ├── parser.py           # Python token parser (legacy, used by PythonParser)
+│   ├── parsers/            # Pluggable language parsers
+│   │   ├── base.py          # Parser interface
+│   │   ├── python_parser.py # Python parser implementation
+│   │   ├── rust_parser.py   # Rust parser stub
+│   │   ├── registry.py      # Parser registry / discovery
 │   ├── utils.py            # Utility functions
 │   └── vizualyzer.py       # Visualization (D3.js + matplotlib)
 ├── tests/                  # Test suite
@@ -30,10 +35,28 @@ codegraph/
 
 ## Core Components
 
-### 1. Parser (`codegraph/parser.py`)
+### 1. Parser Layer (`codegraph/parsers/`)
+
+Parser implementations are pluggable via a registry. Each parser exposes:
+- `get_source_files()` for language-specific file discovery
+- `parse_files()` to produce module objects
+- `usage_graph()` to build dependencies
+- `get_entity_metadata()` for entity stats
+
+This allows adding new languages without changing core graph orchestration.
+
+#### Python Parser (`codegraph/parsers/python_parser.py`)
+
+Uses the legacy token-based parser in `codegraph/parser.py` to extract classes,
+functions, imports, and line ranges.
 
 The parser uses Python's `tokenize` module to extract code structure from source files.
 
+#### Rust Parser (`codegraph/parsers/rust_parser.py`)
+
+Currently a stub to establish extension points. The intent is to parse `.rs` files,
+extract functions/structs/impl blocks, and build dependency edges using a Rust-aware parser.
+
 **Key Classes:**
 - `_Object` - Base class for all parsed objects (lineno, endno, name, parent)
 - `Function` - Represents a function definition
@@ -52,16 +75,15 @@ The parser uses Python's `tokenize` module to extract code structure from source
 
 ### 2. Core (`codegraph/core.py`)
 
-The core module builds the dependency graph from parsed data.
+The core module orchestrates parsing and visualization by delegating language-specific
+work to the selected parser.
 
 **Key Classes:**
 - `CodeGraph` - Main class that orchestrates graph building
 
 **Key Functions:**
-- `get_code_objects(paths_list)` - Parse all files and return dict of module → objects
-- `get_imports_and_entities_lines()` - Extract imports and entity line ranges
-- `collect_entities_usage_in_modules()` - Find where entities are used
-- `search_entity_usage()` - Check if entity is used in a line
+- `usage_graph()` - Delegates to the active parser
+- `get_entity_metadata()` - Delegates to the active parser
 
 **Data Flow:**
 ```

SUGGESTIONS.md

@@ -0,0 +1,40 @@
+# Предложения по доработке и расширению CodeGraph
+
+Ниже — идеи по развитию проекта, опираясь на текущую архитектуру и кодовую базу.
+
+## 1) Точность анализа и качество графа
+- **Перейти на `ast`/`libcst` для разбора**: токенизация ломается на сложных кейсах (f-строки, переносы, декораторы, match/case). AST даст корректные границы сущностей, типы, базовые классы и вызовы.
+- **Поддержать относительные импорты**: `from . import x`, `from ..pkg import y`. Сейчас `get_imports_and_entities_lines` работает только с абсолютными именами.
+- **Разрешение алиасов и импортов**: хранить карту `alias -> full.module` и подставлять при поиске зависимостей (сейчас глобальный `aliases` рискованен при многомодульном анализе).
+- **Улучшить поиск использования сущностей**: вместо простого `name + "("` анализировать вызовы/атрибуты (`ast.Call`, `ast.Attribute`), чтобы уменьшить ложные срабатывания.
+- **Связи "module -> module" отдельно от "entity -> entity"**: сейчас модульные связи строятся через `_`, что усложняет трактовку; можно выделить явный тип связи.
+
+## 2) Производительность и масштабирование
+- **Параллельный разбор файлов**: `get_code_objects` можно распараллелить (ProcessPool), особенно на больших репозиториях.
+- **Кэширование результатов**: сохранять AST/объекты по хэшу файла для инкрементального анализа.
+- **Фильтрация файлов**: опции CLI для исключения `tests/`, `migrations/`, `__pycache__` и т.п.
+
+## 3) Расширение форматов и интеграций
+- **Экспорт в DOT/GraphML/JSON**: добавить форматы, чтобы легко импортировать в Gephi, Neo4j, yEd.
+- **CLI-вывод для CI**: режим `--json` или `--report` для автоматических проверок связности/циклов.
+- **Плагинная архитектура визуализаторов**: единый интерфейс `Visualizer` + регистрация (D3, matplotlib, webview).
+
+## 4) Визуализация и UX
+- **Группировка по пакетам**: кластеризация по папкам/пакетам, возможность свернуть директорию.
+- **Фильтры по типам связей**: переключатели module/module, entity/entity, external.
+- **Подсветка циклов**: детект циклических зависимостей и отдельная визуальная маркировка.
+- **Панель статистики**: топ-узлов по degree, число циклов, изолированные модули.
+
+## 5) Надежность и тестирование
+- **Тесты на сложные импорты и алиасы**: `from pkg import a as b`, `import pkg.sub as s`, относительные импорты.
+- **Снапшот-тесты на D3 JSON**: фиксировать структуру узлов/связей для регрессий.
+- **Отдельные тесты на performance**: большие наборы файлов, ограничение по времени.
+
+## 6) Архитектурные улучшения
+- **Убрать глобальное состояние**: `aliases` как состояние внутри `CodeGraph`.
+- **Четкая модель данных**: dataclasses для узлов/ребер + типы связей; сейчас используется разнородный dict.
+- **Единая карта модулей**: хранить `module_path -> module_name` и обратное соответствие для устойчивых ссылок.
+
+---
+
+Если нужно, могу предложить приоритетный roadmap (MVP улучшений + быстрые wins) или подготовить первые PR-изменения.