tg-flowmap 0.1.0__tar.gz

tg_flowmap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tg-flowmap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tg_flowmap-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: tg-flowmap
+Version: 0.1.0
+Summary: Static AST visualizer, flow mapper, and dead-end linter for Telegram bots
+Author: w1bbex
+License: MIT
+Keywords: telegram,telegram-bot,ast,flowchart,visualizer,linter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dast
+Requires-Dist: telethon<1.45,>=1.36; extra == "dast"
+Provides-Extra: cli
+Requires-Dist: rich>=13.0; extra == "cli"
+Requires-Dist: questionary>=2.0; extra == "cli"
+Provides-Extra: full
+Requires-Dist: tg-flowmap[cli,dast]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# 🧭 tg-flowmap
+
+> **Unified Telegram Bot Analysis & Benchmarking Suite: Static Code AST (SAST) + Dynamic Userbot Crawler (DAST) + AI UX Benchmarking.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python: 3.10+](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)]()
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)]()
+[![Tests: 259 passed](https://img.shields.io/badge/tests-258%20passed-brightgreen.svg)]()
+
+`tg-flowmap` — комплексный инженерный инструмент для аудита, визуализации и сравнения Telegram-ботов:
+1. **SAST (Static AST)**: сканирует исходный код вашего бота **без запуска**, находит тупики, битые коллбеки, забытые команды меню и нарушения спецификации Telegram Bot API за 50 мс без единой зависимости.
+2. **DAST (Telethon Crawler)**: аккуратно обходит интерфейс **чужого бота-конкурента** юзерботом по графу Дейкстры (без лишних `/start`, со стилями кнопок Telethon 1.44 и защитой от бана).
+3. **AI UX Benchmarker**: сопоставляет вашего бота с ботом оппонента и формирует готовый промпт для ChatGPT / Claude (*«Сравни моего бота с конкурентом и дай 5 жестких UX-советов по воронке продаж»*).
+
+---
+
+## ⚡ Быстрый старт (Zero-Boilerplate)
+
+Никаких сложных флагов. Все отчёты и данные автоматически сохраняются в `output/`.
+
+### 1. Установка
+
+```bash
+# Базовый легковесный режим (SAST, 0 зависимостей):
+pip install tg-flowmap
+
+# Режим краулера (с Telethon для обхода внешних ботов):
+pip install "tg-flowmap[dast]"
+
+# Полный комплект (DAST + интерактивный терминальный интерфейс Rich/Questionary):
+pip install "tg-flowmap[full]"
+```
+
+### 2. Анализ своего бота (SAST)
+
+```bash
+tg-flowmap sast path/to/my_bot
+```
+> Выводит аудит в консоль и автоматически сохраняет Markdown-отчёт: `output/my_bot_report.md`.  
+> *Хотите интерактивный холст? Просто добавьте флаг `--html`.*
+
+### 3. Исследование чужого бота (DAST)
+
+```bash
+tg-flowmap dast @competitor_bot
+```
+> Обходит интерфейс конкурента, сохраняет структуру меню, карточки и отчёт в `output/@competitor_bot/`.
+
+### 4. Ультимативное сравнение с конкурентом (AI Benchmark)
+
+```bash
+tg-flowmap compare path/to/my_bot @competitor_bot
+```
+> Генерирует сравнительную матрицу `output/comparison.md` и готовый к отправке в ИИ файл **`output/llm_prompt.md`**!
+
+### 💡 Быстрый интерактивный запуск на Windows (1-Click)
+
+Дважды кликните **`run.bat`** (или перетащите файл/папку бота прямо на иконку `run.bat`):
+- Откроется удобное меню с выбором режима и встроенным мастером настройки Telegram API (`config.json`).
+- Пункт `[4]` сразу же строит карту для встроенного демо-бота `examples/sample_bot.py` и открывает её в браузере.
+
+---
+
+## 🔍 Интеллектуальный линтинг SAST v2
+
+Статический анализатор проверяет десятки потенциальных дефектов архитектуры Telegram-интерфейса:
+
+- ⚠️ **`[ORPHAN_COMMAND]`**: команда есть в коде (`/help`, `/settings`), но не зарегистрирована в системном меню через `set_my_commands` (пользователи о ней не узнают из autocomplete-подсказки).
+- ⚠️ **`[GHOST_COMMAND]`**: пункт зарегистрирован в `set_my_commands`, но в кодовой базе нет обработчика (нажатие приведёт к тишине).
+- ⚠️ **`[MISSING_BACK]`**: на вложенном экране отсутствует кнопка возврата («Назад» / «В меню»).
+- ⚠️ **`[DEAD_END]`**: кнопка или переход ведут в тупик без последующих действий.
+- ⚠️ **`[DANGLING_HANDLER]`**: обработчик существует, но ни одна кнопка или команда на него не ссылается.
+- 🎨 **Telegram Premium Emojis**: автоматическое извлечение и валидация `icon_custom_emoji_id` с локальным кэшированием.
+- 🐍 **Современный синтаксис**: полная поддержка Python 3.10+ `match / case`, aiogram 3 magic-фильтров (`F.data == ...`), Telebot и процедурных билдеров.
+
+---
+
+## 📊 Пример терминального вывода (SAST)
+
+```text
+============================================================
+  🧭 TG-FLOWMAP — Telegram Bot Analyzer (SAST)
+============================================================
+Цель:              C:\Projects\my_shop_bot
+Всего экранов:     54
+Всего связей:      35
+Клавиатур найдено: 31
+Тупиков (Dead-end):0
+Ошибок эмодзи:     0
+Без кнопки Назад:  2
+------------------------------------------------------------
+
+🔍 НАЙДЕННЫЕ ДЕФЕКТЫ И ПРЕДУПРЕЖДЕНИЯ:
+  1. ⚠️ [ORPHAN_COMMAND] Команда '/promo' объявлена в хэндлере, но отсутствует в 'set_my_commands'.
+  2. ⚠️ [MISSING_BACK] В экране 'catalog:filter' нет кнопки возврата (« Назад / В меню »).
+  3. ℹ️ [DANGLING_HANDLER] Обработчик 'admin_dump' определён в коде, но ни одна кнопка на него не ссылается.
+
+📄 Отчёт сохранён: output/my_shop_bot_report.md
+📦 JSON-структура сохранена: output/my_shop_bot_data.json
+```
+
+---
+
+## 🤖 Пример сгенерированного AI-промпта (`llm_prompt.md`)
+
+```markdown
+# Telegram Bot UX Benchmark: my_bot vs @competitor_bot
+
+| Метрика | my_bot (Мой бот) | @competitor_bot (Конкурент) |
+|---|---|---|
+| Всего экранов | 14 | 32 |
+| Всего кнопок | 28 | 64 |
+| Тупиковые кнопки | 0 | 0 |
+| Экраны без кнопки «Назад» | 0 | 2 |
+
+[Структура экранов и кнопок обоих ботов...]
+
+### Запрос для нейросети:
+"Ты — ведущий UX/CPO архитектор Telegram-ботов. На основе структуры выше проведи
+глубокий аудит: где мой бот проигрывает конкуренту по скорости оформления заказа
+и какие 5 конкретных правок меню поднимут конверсию?"
+```
+
+---
+
+## 🛠️ Архитектура модулей
+
+- `tg_flowmap/core/`: единая модель графа (`BotMap`), движок сравнения (`comparator.py`) и генератор промптов (`llm_exporter.py`).
+- `tg_flowmap/sast/`: статический двухпроходный AST-парсер, вычисление выражений без `eval()`, двусторонний линтер Bot API.
+- `tg_flowmap/dast/`: Telethon-краулер, навигация по Дейкстре, контекстный фильтр безопасности `safety.py`, SQLite state.
+- `tg_flowmap/visualizer/`: компилятор автономных HTML5/SVG интерактивных карт (ForceAtlas2, ClearType DirectWrite).
+- `tg_flowmap/cli.py`: единый CLI-интерфейс с поддержкой команд `sast`, `dast`, `compare`.
+
+---
+
+## 🧪 Тестирование
+
+```bash
+pytest tests -v
+```
+**258 passing tests** (SAST, DAST, Safety, State, Regression) с полным контролем бюджета памяти и производительности.

tg_flowmap-0.1.0/README.md

@@ -0,0 +1,141 @@
+# 🧭 tg-flowmap
+
+> **Unified Telegram Bot Analysis & Benchmarking Suite: Static Code AST (SAST) + Dynamic Userbot Crawler (DAST) + AI UX Benchmarking.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python: 3.10+](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)]()
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)]()
+[![Tests: 259 passed](https://img.shields.io/badge/tests-258%20passed-brightgreen.svg)]()
+
+`tg-flowmap` — комплексный инженерный инструмент для аудита, визуализации и сравнения Telegram-ботов:
+1. **SAST (Static AST)**: сканирует исходный код вашего бота **без запуска**, находит тупики, битые коллбеки, забытые команды меню и нарушения спецификации Telegram Bot API за 50 мс без единой зависимости.
+2. **DAST (Telethon Crawler)**: аккуратно обходит интерфейс **чужого бота-конкурента** юзерботом по графу Дейкстры (без лишних `/start`, со стилями кнопок Telethon 1.44 и защитой от бана).
+3. **AI UX Benchmarker**: сопоставляет вашего бота с ботом оппонента и формирует готовый промпт для ChatGPT / Claude (*«Сравни моего бота с конкурентом и дай 5 жестких UX-советов по воронке продаж»*).
+
+---
+
+## ⚡ Быстрый старт (Zero-Boilerplate)
+
+Никаких сложных флагов. Все отчёты и данные автоматически сохраняются в `output/`.
+
+### 1. Установка
+
+```bash
+# Базовый легковесный режим (SAST, 0 зависимостей):
+pip install tg-flowmap
+
+# Режим краулера (с Telethon для обхода внешних ботов):
+pip install "tg-flowmap[dast]"
+
+# Полный комплект (DAST + интерактивный терминальный интерфейс Rich/Questionary):
+pip install "tg-flowmap[full]"
+```
+
+### 2. Анализ своего бота (SAST)
+
+```bash
+tg-flowmap sast path/to/my_bot
+```
+> Выводит аудит в консоль и автоматически сохраняет Markdown-отчёт: `output/my_bot_report.md`.  
+> *Хотите интерактивный холст? Просто добавьте флаг `--html`.*
+
+### 3. Исследование чужого бота (DAST)
+
+```bash
+tg-flowmap dast @competitor_bot
+```
+> Обходит интерфейс конкурента, сохраняет структуру меню, карточки и отчёт в `output/@competitor_bot/`.
+
+### 4. Ультимативное сравнение с конкурентом (AI Benchmark)
+
+```bash
+tg-flowmap compare path/to/my_bot @competitor_bot
+```
+> Генерирует сравнительную матрицу `output/comparison.md` и готовый к отправке в ИИ файл **`output/llm_prompt.md`**!
+
+### 💡 Быстрый интерактивный запуск на Windows (1-Click)
+
+Дважды кликните **`run.bat`** (или перетащите файл/папку бота прямо на иконку `run.bat`):
+- Откроется удобное меню с выбором режима и встроенным мастером настройки Telegram API (`config.json`).
+- Пункт `[4]` сразу же строит карту для встроенного демо-бота `examples/sample_bot.py` и открывает её в браузере.
+
+---
+
+## 🔍 Интеллектуальный линтинг SAST v2
+
+Статический анализатор проверяет десятки потенциальных дефектов архитектуры Telegram-интерфейса:
+
+- ⚠️ **`[ORPHAN_COMMAND]`**: команда есть в коде (`/help`, `/settings`), но не зарегистрирована в системном меню через `set_my_commands` (пользователи о ней не узнают из autocomplete-подсказки).
+- ⚠️ **`[GHOST_COMMAND]`**: пункт зарегистрирован в `set_my_commands`, но в кодовой базе нет обработчика (нажатие приведёт к тишине).
+- ⚠️ **`[MISSING_BACK]`**: на вложенном экране отсутствует кнопка возврата («Назад» / «В меню»).
+- ⚠️ **`[DEAD_END]`**: кнопка или переход ведут в тупик без последующих действий.
+- ⚠️ **`[DANGLING_HANDLER]`**: обработчик существует, но ни одна кнопка или команда на него не ссылается.
+- 🎨 **Telegram Premium Emojis**: автоматическое извлечение и валидация `icon_custom_emoji_id` с локальным кэшированием.
+- 🐍 **Современный синтаксис**: полная поддержка Python 3.10+ `match / case`, aiogram 3 magic-фильтров (`F.data == ...`), Telebot и процедурных билдеров.
+
+---
+
+## 📊 Пример терминального вывода (SAST)
+
+```text
+============================================================
+  🧭 TG-FLOWMAP — Telegram Bot Analyzer (SAST)
+============================================================
+Цель:              C:\Projects\my_shop_bot
+Всего экранов:     54
+Всего связей:      35
+Клавиатур найдено: 31
+Тупиков (Dead-end):0
+Ошибок эмодзи:     0
+Без кнопки Назад:  2
+------------------------------------------------------------
+
+🔍 НАЙДЕННЫЕ ДЕФЕКТЫ И ПРЕДУПРЕЖДЕНИЯ:
+  1. ⚠️ [ORPHAN_COMMAND] Команда '/promo' объявлена в хэндлере, но отсутствует в 'set_my_commands'.
+  2. ⚠️ [MISSING_BACK] В экране 'catalog:filter' нет кнопки возврата (« Назад / В меню »).
+  3. ℹ️ [DANGLING_HANDLER] Обработчик 'admin_dump' определён в коде, но ни одна кнопка на него не ссылается.
+
+📄 Отчёт сохранён: output/my_shop_bot_report.md
+📦 JSON-структура сохранена: output/my_shop_bot_data.json
+```
+
+---
+
+## 🤖 Пример сгенерированного AI-промпта (`llm_prompt.md`)
+
+```markdown
+# Telegram Bot UX Benchmark: my_bot vs @competitor_bot
+
+| Метрика | my_bot (Мой бот) | @competitor_bot (Конкурент) |
+|---|---|---|
+| Всего экранов | 14 | 32 |
+| Всего кнопок | 28 | 64 |
+| Тупиковые кнопки | 0 | 0 |
+| Экраны без кнопки «Назад» | 0 | 2 |
+
+[Структура экранов и кнопок обоих ботов...]
+
+### Запрос для нейросети:
+"Ты — ведущий UX/CPO архитектор Telegram-ботов. На основе структуры выше проведи
+глубокий аудит: где мой бот проигрывает конкуренту по скорости оформления заказа
+и какие 5 конкретных правок меню поднимут конверсию?"
+```
+
+---
+
+## 🛠️ Архитектура модулей
+
+- `tg_flowmap/core/`: единая модель графа (`BotMap`), движок сравнения (`comparator.py`) и генератор промптов (`llm_exporter.py`).
+- `tg_flowmap/sast/`: статический двухпроходный AST-парсер, вычисление выражений без `eval()`, двусторонний линтер Bot API.
+- `tg_flowmap/dast/`: Telethon-краулер, навигация по Дейкстре, контекстный фильтр безопасности `safety.py`, SQLite state.
+- `tg_flowmap/visualizer/`: компилятор автономных HTML5/SVG интерактивных карт (ForceAtlas2, ClearType DirectWrite).
+- `tg_flowmap/cli.py`: единый CLI-интерфейс с поддержкой команд `sast`, `dast`, `compare`.
+
+---
+
+## 🧪 Тестирование
+
+```bash
+pytest tests -v
+```
+**258 passing tests** (SAST, DAST, Safety, State, Regression) с полным контролем бюджета памяти и производительности.

tg_flowmap-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tg-flowmap"
+version = "0.1.0"
+description = "Static AST visualizer, flow mapper, and dead-end linter for Telegram bots"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "w1bbex" }]
+keywords = ["telegram", "telegram-bot", "ast", "flowchart", "visualizer", "linter"]
+dependencies = []
+
+[project.optional-dependencies]
+dast = [
+    "telethon>=1.36,<1.45",
+]
+cli = [
+    "rich>=13.0",
+    "questionary>=2.0",
+]
+full = [
+    "tg-flowmap[dast,cli]",
+]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+tg-flowmap = "tg_flowmap.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tg_flowmap*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+tg_flowmap = [
+    "visualizer/templates/*",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+addopts = "--basetemp=.pytest_tmp -p no:cacheprovider"
+
+

tg_flowmap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tg_flowmap-0.1.0/tests/test_regressions.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from tg_flowmap.core.comparator import BotComparator
+from tg_flowmap.dast.auth import create_client
+from tg_flowmap.dast.capture import extract_buttons
+from tg_flowmap.dast.config import Config
+from tg_flowmap.dast.crawler import BotCrawler
+from tg_flowmap.dast.models import ButtonRef, CallbackResult, PressOutcome
+from tg_flowmap.dast.navigation_graph import NavigationGraph
+from tg_flowmap.dast.safety import SafetyFilter, WALLET_REGEXES
+from tg_flowmap.dast.screen_identity import buttons_signature, match_button_instance
+from tg_flowmap.dast.state import State
+from tg_flowmap.dast.timeline_log import ActionLogger, TimelineWriter
+from tg_flowmap.dast.utf16 import utf16_length
+from tg_flowmap.sast.analyzer import GraphAnalyzer
+from tg_flowmap.sast.emoji import fetch_custom_emojis, load_cached_emoji
+import run
+
+
+def test_run_wizard_no_name_error(tmp_path: Path) -> None:
+    """Verifies that run.py functions use cfg_path and do not contain undefined cfg_file references."""
+    source = inspect.getsource(run.run_telegram_config_wizard)
+    assert "os.startfile(cfg_file)" not in source
+    assert "os.startfile(cfg_path)" in source
+
+
+def test_screen_identity_buttons_signature_none_url_comparison() -> None:
+    """Verifies that buttons with None URL do not crash sorted() when compared with string URLs."""
+    btn1 = {"row": 0, "col": 0, "label": "Btn", "button_type": "url", "url": None}
+    btn2 = {"row": 0, "col": 0, "label": "Btn", "button_type": "url", "url": "https://example.com"}
+    sig = buttons_signature([btn1, btn2])
+    assert len(sig) == 1
+    assert len(sig[0]) == 2
+
+
+def test_screen_identity_row_col_none_fallback() -> None:
+    """Verifies that explicit None in row/col does not cause TypeError in int()."""
+    btn = {"row": None, "col": None, "label": "Test", "button_type": "callback"}
+    sig = buttons_signature([btn])
+    assert len(sig) == 1
+
+    matched, conf, _ = match_button_instance({"row": None, "col": None, "label": "Test", "button_type": "callback"}, [btn])
+    assert matched is not None
+    assert conf == 1.0
+
+
+def test_dast_config_to_dict_json_serializable(tmp_path: Path) -> None:
+    """Verifies that custom_output_dir Path does not break json serialization in to_dict() and save()."""
+    cfg = Config(root=tmp_path, custom_output_dir=tmp_path / "custom")
+    d = cfg.to_dict()
+    assert isinstance(d["custom_output_dir"], str)
+    dumped = json.dumps(d)
+    assert "custom" in dumped
+
+    save_file = tmp_path / "cfg.json"
+    cfg.save(save_file)
+    assert save_file.exists()
+
+
+def test_capture_empty_callback_data_preserved() -> None:
+    """Verifies that b'' callback_data is preserved and not replaced by None."""
+    class DummyButton:
+        text = "Separator"
+        data = b""
+
+    class DummyRow:
+        buttons = [DummyButton()]
+
+    class DummyReplyMarkup:
+        rows = [DummyRow()]
+
+    buttons = extract_buttons(DummyReplyMarkup(), message_id=1)
+    assert len(buttons) == 1
+    assert buttons[0].callback_data == b""
+
+
+def test_emoji_load_cached_invalid_ntfs_chars(tmp_path: Path) -> None:
+    """Verifies that invalid filename characters in emoji_id do not throw WinError 123."""
+    res = load_cached_emoji("$ICONS[star]*:?", tmp_path)
+    assert res is None
+
+
+def test_emoji_fetch_custom_emojis_filters_non_digits(tmp_path: Path) -> None:
+    """Verifies that non-digit emoji IDs are filtered out without making requests."""
+    res = fetch_custom_emojis("test_token", ["$VAR_ICON", "star*"], cache_dir=tmp_path)
+    assert res == {}
+
+
+def test_comparator_extract_metrics_nodes_list() -> None:
+    """Verifies that extract_metrics_from_bot_map supports bot_map with nodes as a list (DAST format)."""
+    bot_map = {
+        "nodes": [
+            {
+                "id": "screen_1",
+                "keyboard": {
+                    "rows": [[{"label": "Btn1"}], [{"label": "Btn2"}]]
+                }
+            }
+        ],
+        "issues": [{"issue_type": "dead_end"}],
+    }
+    metrics = BotComparator.extract_metrics_from_bot_map(bot_map)
+    assert metrics["screens_count"] == 1
+    assert metrics["buttons_count"] == 2
+    assert metrics["dead_ends"] == 1
+
+
+def test_safety_manual_answers_without_at_prefix() -> None:
+    """Verifies manual_answer lookup works regardless of whether @ prefix is present."""
+    manual = {
+        "testbot": {
+            "screens": [{"match": "Enter promo", "answer": "12345"}]
+        }
+    }
+    ans = SafetyFilter.manual_answer(manual, "@testbot", "Enter promo")
+    assert ans == "12345"
+
+    ans2 = SafetyFilter.manual_answer(manual, "testbot", "Enter promo")
+    assert ans2 == "12345"
+
+
+def test_safety_tron_regex_case_sensitivity() -> None:
+    """Verifies that TRON wallet regex requires capital T and is case-sensitive."""
+    tron_pat = WALLET_REGEXES[1]
+    valid_tron = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
+    lowercase_false_positive = "t1234567890abcdef1234567890abcdef1"
+
+    assert tron_pat.search(valid_tron) is not None
+    assert tron_pat.search(lowercase_false_positive) is None
+
+
+def test_crawler_continue_on_stale_button(tmp_path: Path) -> None:
+    async def _run():
+        db_file = tmp_path / "state.db"
+        state = State(db_file)
+        cfg = Config()
+        writer = TimelineWriter(tmp_path / "timeline.jsonl")
+        logger = ActionLogger(state, writer)
+        safety = SafetyFilter(cfg)
+        nav = MagicMock()
+        nav.press_button = AsyncMock(
+            return_value=PressOutcome(kind="answer_only", callback=CallbackResult(message="Alert", alert=True))
+        )
+        crawler = BotCrawler(cfg, state, logger, safety, nav, {}, "test_bot", media_dir=tmp_path / "media")
+
+        crawler._current_msg = MagicMock(id=123)
+        crawler._current_msg_rowid = 1
+        crawler._current_screen_id = "screen_1"
+
+        state._exec(
+            "INSERT INTO messages (id, bot, chat_id, message_id, event_type, captured_at) VALUES (?, ?, ?, ?, ?, ?)",
+            (1, "test_bot", 12345, 123, "new", "2026-01-01T00:00:00Z"),
+        )
+        state._exec(
+            "INSERT INTO buttons (id, bot, screen_id, row, col, label, button_type, callback_data) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (1, "test_bot", "screen_1", 0, 0, "Stale Button", "callback", b"stale"),
+        )
+        state._exec(
+            "INSERT INTO buttons (id, bot, screen_id, row, col, label, button_type, callback_data) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (2, "test_bot", "screen_1", 0, 1, "Valid Button", "callback", b"valid"),
+        )
+        state._exec(
+            "INSERT INTO button_instances (bot, message_rowid, row, col, label, callback_data, action_id, button_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            ("test_bot", 1, 0, 1, "Valid Button", "valid", "act_valid", "callback"),
+        )
+
+        item = {"screen_id": "screen_1", "path": [], "depth": 1}
+        await crawler._explore(item)
+
+        assert nav.press_button.call_count == 1
+
+    asyncio.run(_run())
+
+
+def test_navigation_graph_persists_unstable_edges_to_sqlite(tmp_path: Path) -> None:
+    db_file = tmp_path / "state.db"
+    state = State(db_file)
+    graph = NavigationGraph(state=state, bot="test_bot")
+
+    graph.record_transition("scr_a", "act_1", "scr_b", "edit", success=True)
+    graph.record_transition("scr_a", "act_1", "scr_c", "edit", success=True)
+
+    edges_in_db = state.graph_edges_all("test_bot")
+    assert len(edges_in_db) == 2
+    for e in edges_in_db:
+        assert e["is_stable"] == 0
+        assert e["confidence"] <= 0.5
+
+
+def test_comparator_dast_routing_and_screens_fallback(tmp_path: Path) -> None:
+    dast_a = {
+        "summary": {"screens": 5, "buttons": 12, "routes": 4, "dead_ends": 1, "max_depth": 3},
+        "nodes": [{"id": "s1"}, {"id": "s2"}],
+    }
+    dast_b = {
+        "summary": {"screens": 3, "buttons": 8, "routes": 2, "dead_ends": 0, "max_depth": 2},
+        "nodes": [{"id": "s1"}],
+    }
+    comp = BotComparator("BotA", dast_a, "BotB", dast_b)
+    metrics_a, metrics_b = comp._resolve_metrics()
+
+    assert metrics_a["buttons_count"] == 12
+    assert metrics_b["buttons_count"] == 8
+
+    out = comp.export(tmp_path)
+    prompt_content = out["llm_prompt"].read_text(encoding="utf-8")
+    assert "BotA" in prompt_content
+    assert "BotB" in prompt_content
+
+
+def test_analyzer_dynamic_callback_placeholder() -> None:
+    analyzer = GraphAnalyzer({}, {})
+    target, kind = analyzer._resolve_target("$user_id")
+    assert kind == "dynamic"
+    assert target == "dynamic:$user_id"
+
+
+def test_emoji_tgs_and_webm_support(tmp_path: Path) -> None:
+    (tmp_path / "12345.tgs").write_bytes(b"tgs_data")
+    (tmp_path / "67890.webm").write_bytes(b"webm_data")
+
+    res_tgs = load_cached_emoji("12345", tmp_path)
+    assert res_tgs is not None
+    assert res_tgs.startswith("data:application/x-tgsticker;base64,")
+
+    res_webm = load_cached_emoji("67890", tmp_path)
+    assert res_webm is not None
+    assert res_webm.startswith("data:video/webm;base64,")
+
+
+def test_utf16_surrogatepass() -> None:
+    lone_surrogate = "\ud800"
+    length = utf16_length(lone_surrogate)
+    assert length == 1
+
+
+def test_auth_put_your_api_id() -> None:
+    async def _run():
+        cfg = Config()
+        cfg.api_id = "PUT_YOUR_API_ID"
+        cfg.api_hash = "valid_hash_123"
+
+        with pytest.raises(RuntimeError, match="API credentials \u043d\u0435 \u043d\u0430\u0441\u0442\u0440\u043e\u0435\u043d\u044b"):
+            await create_client(cfg)
+
+    asyncio.run(_run())

tg_flowmap-0.1.0/tg_flowmap/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from tg_flowmap.cli import main
+
+if __name__ == "__main__":
+    main()

tg_flowmap-0.1.0/tg_flowmap/analyzer.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from tg_flowmap.sast.analyzer import GraphAnalyzer
+
+__all__ = ["GraphAnalyzer"]

tg_flowmap-0.1.0/tg_flowmap/ast_evaluator.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from tg_flowmap.sast.evaluator import (
+    _ast_to_value,
+    evaluate_ast_node,
+    extract_module_constants,
+)
+
+__all__ = [
+    "_ast_to_value",
+    "evaluate_ast_node",
+    "extract_module_constants",
+]