@gevvos/tesnel

tesnel

Создано с помощью Claude Code

Статический анализатор графа зависимостей на уровне исходного кода с визуализацией для TypeScript, JavaScript и Vue проектов.

tesnel (տեսնել, произносится тес-нел) — «видеть» по-армянски.

Зачем

Понять, как файлы зависят друг от друга в большом проекте — сложно. IDE показывает импорты одного файла, но не даёт полной картины: какие модули связаны слишком сильно, где прячутся циклические зависимости и как изменение одного файла затронет остальные.

tesnel анализирует исходный код до любой сборки — без бандлера, компиляции или dev-сервера. Он читает сырые .ts, .vue и .js файлы, резолвит импорты (включая tsconfig алиасы и Nuxt автоимпорты) и генерирует интерактивный граф для исследования в браузере.

Это быстро: 290 файлов за ~400 мс, результат — один самодостаточный HTML.

Используйте, чтобы:

• Аудит архитектуры — увидеть реальную структуру зависимостей, а не воображаемую
• Найти циклические зависимости — до того, как они вызовут баги или сломают tree-shaking
• Онбординг в проект — понять границы модулей и ключевые файлы с первого взгляда
• Ревью рефакторинга — убедиться, что реструктуризация действительно снизила связанность
• Отфильтровать шум — скрыть тесты, type-only импорты или нерелевантные модули

Для AI-агентов

tesnel включает MCP-сервер, который даёт AI-агентам (Claude Code и др.) структурированный доступ к графу зависимостей. Без него агенту приходится читать файлы по одному — сотни вызовов и десятки тысяч токенов только чтобы понять структуру проекта. С tesnel один MCP-вызов возвращает полную картину: что импортирует что, кто зависит от данного файла, где циклы. Это как обходить город пешком улицу за улицей вместо того, чтобы посмотреть на карту.

Возможности

• Рекурсивный анализ зависимостей от entry point или директории
• Интерактивная визуализация графа — вложенные директории, файлы, стрелки зависимостей
• Детект циклов — циклические зависимости подсвечены красным
• Разделение type-imports — пунктирные линии для import type, можно отключить
• Контроль глубины — свернуть/развернуть вложенность директорий
• Фильтры — изолировать выбранный файл, показать только циклы, исключить по паттерну
• Поддержка Vue SFC — парсинг <script setup> из .vue файлов
• Поддержка Nuxt — определяет автоимпорты composables и stores через .nuxt/types/
• Поддержка Nest.js — работает из коробки с explicit imports
• tsconfig paths — резолвит @/, ~/ и кастомные алиасы
• Архитектурные метрики — Instability, Abstractness, Distance для каждой директории (Роберт Мартин)
• Сложность файлов — полоска цикломатической сложности на каждом файле (зелёный → красный)
• Статистика файлов — LOC, сложность, функции, глубина вложенности в sidebar
• Трекинг экспортов — список экспортов файла, клик → фильтрация графа до потребителей конкретного символа
• Линт циклов — tesnel lint с exit code 1 для CI пайплайнов
• MCP сервер — интеграция с Claude Code для запросов к графу зависимостей
• Single HTML — самодостаточный файл, работает офлайн через file://

Установка

npm install -g @gevvos/tesnel
# или
pnpm add -g @gevvos/tesnel

Использование

Анализ проекта

# От entry файла
tesnel analyze ./src/main.ts

# От директории (все .ts/.vue/.js файлы)
tesnel analyze ./src

# Кастомный путь вывода
tesnel analyze ./src/main.ts -o deps.json

# Ограничить глубину обхода
tesnel analyze ./src/main.ts --depth 3

# Только JSON, без HTML
tesnel analyze ./src/main.ts --no-html

Результат: .tesnel/output.json + .tesnel/output.html

Открыть визуализацию

Откройте .tesnel/output.html в любом браузере. Сервер не нужен.

Управление:

• Zoom — скролл или кнопки +/-
• Pan — перетаскивание
• Слайдер глубины — свернуть директории
• Клик на файл — sidebar со статистикой, экспортами, imports/importedBy
• Поиск — найти файл по имени
• Hide unrelated — изолировать связи выбранного файла
• Cycles only — показать только циклические зависимости
• Exclude — скрыть файлы по паттерну (например __tests__, .spec)
• Type imports — вкл/выкл type-only imports (пунктирные линии)
• Metrics — вкл/выкл оверлей архитектурных метрик на директориях

Архитектурные метрики

tesnel вычисляет метрики для каждой директории на основе принципов компонентов из Clean Architecture Роберта Мартина:

• Instability (I) = Fan-out / (Fan-in + Fan-out) — насколько модуль подвержен изменениям
• Abstractness (A) = type-only imports / все входящие imports — насколько модуль абстрактен
• Distance (D) = |A + I − 1| — расстояние от идеальной Main Sequence

Включите переключатель Metrics в хэдере визуализации, чтобы увидеть директории, раскрашенные по зонам:

Кликните на директорию в графе, чтобы увидеть полные метрики в sidebar. Кнопка ? открывает подробное объяснение.

Примечание: Нахождение в зоне — не приговор. Константы, конфиги и утилиты по природе в Zone of Pain — вопрос в том, вызовет ли изменение каскад поломок.

Метрики включены в JSON вывод в секции metrics.

Линт циклических зависимостей

# Проверка от entry файла
tesnel lint ./src/main.ts

# Проверка всей директории
tesnel lint ./src

# Ограничить глубину обхода
tesnel lint ./src --depth 3

Exit code 0 если циклов нет, 1 если есть. Удобно для CI:

- run: tesnel lint ./src

MCP сервер (Claude Code)

Даёт ИИ-агентам структурированный доступ к графу зависимостей — не нужно читать файлы по одному.

1. Сначала проанализируйте проект:

tesnel analyze ./src/main.ts

2. Подключите к Claude Code:

# npm
claude mcp add --transport stdio tesnel -- npx -y @gevvos/tesnel mcp

# pnpm
claude mcp add --transport stdio tesnel -- pnpm dlx @gevvos/tesnel mcp

Готово. Перезапустите Claude Code — инструменты доступны.

Как это работает: Claude Code запускает npx -y @gevvos/tesnel mcp в директории проекта. Сервер читает .tesnel/output.json и предоставляет 5 read-only инструментов через stdio.

Свой путь к данным:

claude mcp add --transport stdio tesnel -- npx -y @gevvos/tesnel mcp --data ./deps.json

Для всей команды — добавьте .mcp.json в корень репозитория:

{
  "mcpServers": {
    "tesnel": {
      "command": "npx",
      "args": ["-y", "@gevvos/tesnel", "mcp"]
    }
  }
}

Все, кто клонирует репо, получат MCP-сервер автоматически.

Или установите плагин Claude Code — MCP-инструменты + скилл /tesnel в одном пакете:

claude plugin marketplace add https://github.com/gevvos/tesnel
claude plugin install tesnel@tesnel-marketplace

Доступные инструменты:

Поддерживаемые проекты

Легенда графа

Разработка

pnpm install
pnpm test          # запуск тестов
pnpm build         # сборка UI + CLI
pnpm dev analyze ./src/main.ts  # запуск CLI в dev режиме

Стек

• oxc-parser — быстрый AST парсинг
• oxc-resolver — резолв модулей с поддержкой tsconfig
• ELK.js — иерархический layout графа
• Vue 3 + D3.js — интерактивная визуализация
• @modelcontextprotocol/sdk — MCP сервер
• Vite — сборка
• Vitest — тестирование

Лицензия

ISC