Решение проблем

Path-алиасы (@/foo) не резолвятся

Симптом: каждый импорт через алиас приходит unresolved (resolved: false в JSON, в панели warnings — «Import not resolved»).

Причина: Archora читает paths из tsconfig.json. Если ваш tsconfig.json extends другой конфиг, и алиасы живут в родителе, проверьте, что цепочка целая и резолвится из корня проекта.

Решение:

1. Запустите CLI с FRONTSCOPE_DEBUG=1:

   FRONTSCOPE_DEBUG=1 npx @archora/cli analyze . --quiet > /dev/null

   Увидите, какой tsconfig.json подцепился и какие paths подхватились.
2. Убедитесь, что каждый tsconfig.json в цепочке extends реально существует по тому пути, на который ссылается. Самая частая причина — workspace-relative путь, ломающийся при перемещении tsconfig.
3. Проверьте baseUrl. Алиасы без baseUrl резолвятся относительно содержащего tsconfig — это иногда удивляет в nested-workspace-ах.

Если алиасы намеренно не в tsconfig.json (например, только в vite.config.ts), Archora их не увидит. Зеркальте их в tsconfig.json — обычно это всё равно нужно для поддержки в редакторе.

Out of memory на > 5000 модулей

Симптом: Node падает с JavaScript heap out of memory посреди скана.

Причина: дефолтный heap Node (~1.5 GB) маловат для очень больших проектов с глубокими графами зависимостей.

Решение: поднять heap.

NODE_OPTIONS=--max-old-space-size=4096 npx @archora/cli analyze .

Если регулярно превышаете дефолт и хотите перманентный фикс — добавьте в окружение CI или shell-профиль.

Это известный scaling target — стремимся, чтобы ~5000 модулей было комфортно на дефолтных настройках, и принимаем, что очень большим монорепо (> 10k модулей) пока нужен heap-bump. Streaming-режим анализатора — в roadmap.

«Permission denied» на macOS

Симптом: при открытии проекта из десктопа выходит системный prompt про разрешения или silent fail при чтении файлов.

Причина: TCC-фреймворк macOS ограничивает доступ приложений к некоторым локациям (Documents, Downloads, Desktop, removable volumes) без явного разрешения.

Решение:

1. System Settings → Privacy & Security → Files and Folders → выдайте Archora доступ к нужной папке.
2. Если Archora не появляется в списке — запустите скан раз, prompt вытащит его в список.
3. Для неподписанных dev-сборок может потребоваться правый клик по .app и выбор Open в первый раз, чтобы обойти Gatekeeper.

Когда production-сборки будут signed + notarized, это станет one-time prompt вместо повторяющегося.

Неправильно определён язык / парсер

Симптом: .vue файлы репортятся как parse-ошибки или .ts файлы классифицируются как JavaScript.

Причина: определение по расширению. Если в проекте .vue файлы, но Vue нет в зависимостях, Archora всё равно может их парсить — но если ваши .vue используют нестандартный <script lang="?">, извлечение блока может падать.

Решение:

1. Проверьте панель warnings (десктоп) или warnings[] в JSON. У каждой ошибки есть путь и подсказка.
2. Если используете нестандартный <script lang> (типа транспилируемого языка), вернитесь к <script lang="ts"> или <script> — Archora понимает только TypeScript/JavaScript.
3. Для .vue в не-Vue проекте (редко) — открывайте issue. Возможно, эвристику детекта стоит ужесточить.

Часть импортов отсутствует в графе

Симптом: вы знаете, что модуль A импортирует модуль B на runtime, но граф этого ребра не показывает.

Причина: паттерны динамической загрузки, которые Archora не моделирует из коробки. Самые частые:

• import.meta.glob от Vite — поддерживается частично (только литеральные паттерны).
• Кастомные MFE/plugin-loader-ы, читающие пути из JSON или env.
• Webpack require.context — не поддерживается.

Решение:

// archora.config.js
export default {
  dynamicLoaders: [
    // hint: пути по этим глобам загружаются на runtime
    'src/plugins/**/index.ts',
    'src/locales/*.json',
  ],
};

Опция dynamicLoaders подключает эти глобы к графу как виртуальные рёбра от entry-точки — они участвуют в детекции isolated-cluster и не флагаются как unused.

Циклы, которые я «починил», всё ещё видны

Симптом: перевели import в import type, но цикл не пропал.

Причина: по умолчанию type-only рёбра исключены из графа циклов. Если цикл всё ещё показывается после такой замены, не все рёбра в нём были type-only — есть как минимум один runtime-импорт, который вы ещё не сконвертили.

Решение:

1. Откройте цикл в Insights.
2. Посмотрите на список «Imports that close the cycle» — это runtime-рёбра. Сконвертите (или инвертируйте) одно из них.
3. Перезапустите скан.

Если сконвертили всё, а цикл остался — FRONTSCOPE_DEBUG=1 покажет рёбра, которые видел анализатор. Чаще всего — закэшированный файл: если редактор автосохранением занят, проверьте, что файл реально записался.

CLI завершается с кодом 2, но сообщение непонятное

Симптом: archora check упал с 2 на parse-ошибке, и неясно, какой --fail-on был кривой.

Решение: в stderr-сообщении называется конкретное правило. Если у вас много --fail-on и сообщение теряется, упрощайтесь до одного правила за раз:

archora check . --fail-on grade:D     # это правило ок?
archora check . --fail-on cycles:0    # а это?

Частые ошибки парса: пропущенный : (grade D вместо grade:D), невалидная буква grade (grade:E), не-целое число (cycles:two).

Всё ещё застряли?

GitHub Issues. Приложите:

• Версию Archora (archora --version).
• ОС и версию Node.
• JSON-вывод скана, если уместен.
• Точную команду, которую запускали.