# Анализ кода

Навигация уровня IDE для LaTeX и Typst: переход к определению, поиск использований, переименование по всему проекту, всплывающие карточки, предпросмотр формул, структура документа, а также подсказки сигнатур и форматирование в Typst.

Oleafly индексирует весь проект, включая каждую метку `\label`, каждый ключ цитирования, пользовательский макрос, теорему, элемент глоссария и граф `\input`, связывающий ваши файлы. Этот индекс обеспечивает навигацию между файлами. Для файлов Typst действуют те же сочетания клавиш, их обрабатывает сервер языка Typst; см. [Файлы Typst](#typst-files) ниже.

Сочетания клавиш указаны для macOS. В Windows и Linux читайте ⌘ как Ctrl.

## Переход к определению: F12 или ⌘-клик

Поставьте курсор на `\ref`, ключ `\cite`, пользовательский макрос, `\begin{env}` для определённой вами среды или термин из глоссария и нажмите F12 (или удерживайте ⌘ и щёлкните по нему). Редактор переходит к месту определения и открывает файл с определением, если тот находится в другом месте проекта.

Если нажать F12, когда курсор уже стоит на определении, действие переключается на поиск его использований — так же, как принято в IDE.

## Поиск использований: ⇧F12

Shift+F12 выводит все использования символа на панель **Источники** в левой колонке: по одной строке на вхождение с файлом, номером строки и предпросмотром, а на самом определении стоит значок «def». Щёлкните по строке, чтобы перейти. Это самый быстрый способ ответить на вопросы «можно ли удалить эту метку?» и «где процитирована эта работа?».

![Метка уравнения, переименованная сразу в двух файлах, и список ссылок на неё.](https://cdn.oleafly.com/images/gifs/desktop/rename-symbol.gif?v=2)

## Переименование символа: F2

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

Переименование `fig:overview` в `fig:architecture`, за которым следуют все шесть `\ref`, занимает две секунды.

Если курсор стоит на пути к файлу, например на аргументе `\input` или `\includegraphics`, F2 переименовывает этот файл и обновляет пути, которые на него указывают. То же самое работает для `#include` и `image()` в Typst, а также для ссылок и изображений в Markdown. См. [Пути следуют за перемещённым файлом](/docs/files/#paths-follow-a-moved-file).

## Всплывающие карточки

Наведите указатель на любой символ, и карточка объяснит его:

- Для **ссылки**: тип символа, предпросмотр источника и расположение. После успешной сборки LaTeX поддерживаемые ссылки показывают также скомпилированный номер и страницу.
- Для **определения**: сколько на него ссылок по всему проекту.
- Для чего-либо **неразрешённого**: ясная пометка «Неразрешено» — самое раннее предупреждение об опечатке в `\ref` или об отсутствующей записи в `.bib`.

Удерживайте ⌘ (Ctrl) во время наведения, и щёлкаемые символы подчёркиваются как ссылки; щёлкните, чтобы перейти.

## Предпросмотр формул при наведении

Наведите указатель на встроенную математику `$…$`, `\(…\)` или выключную `\[…\]`, чтобы отрисовать её через KaTeX без компиляции. Выключные формулы отображаются в выключном стиле. Для ошибочного выражения выводится его ошибка.

## Панель «Оглавление»

Под деревом файлов панель **Оглавление** показывает структуру документа: разделы с отступами по уровням, а также включения `\input`, по всем файлам. У элементов из других файлов есть значок с именем файла. Щёлкните по любому элементу, чтобы сразу перейти к нему. Для диссертации, разбитой на дюжину файлов с главами, это и есть оглавление, по которому вы перемещаетесь.

Заголовки разделов отображаются как обычный текст, поэтому цветовая команда, переключение шрифта или `\nameref` в заголовке не появляются как сырой LaTeX. Заголовки, созданные вашими собственными макросами, обёртками `\section`, попадают в список, а заголовки внутри определения макроса — нет.

Разделитель между деревом и оглавлением можно перетаскивать, изменяя размер.

## Где размещены панель инструментов и меню

Все три команды навигации есть также в меню **Анализ кода** на панели инструментов редактора (значок с фигурными скобками) и в контекстном меню, поэтому их можно найти и до того, как сочетания клавиш станут мышечной памятью.

## Файлы Typst

В файлах `.typ` большинство этих команд выполняет Tinymist, сервер языка Typst. Oleafly запускает выпуск Tinymist, соответствующий версии Typst проекта (см. [Проекты Typst](/docs/typst/#the-language-server-follows-the-version)).

- F12 или ⌘-клик переходит к определению метки, переменной или функции, в том числе находящемуся в другом файле.
- ⇧F12 перечисляет все использования на панели **Источники**.
- F2 переименовывает метку, переменную или функцию по всему проекту.
- Наведите указатель на функцию, чтобы прочитать её документацию. Наведите указатель на импорт `@preview`, чтобы получить ссылку на пакет в Typst Universe.

Те же три команды находятся в меню **Анализ кода** на панели инструментов Typst, в контекстном меню и в палитре ⌘K. Метки в файлах Typst и LaTeX хранятся раздельно, поэтому метка, используемая в обоих, не попадает в отчёт дважды, и переименование одной не затрагивает другую.

### Подсказки сигнатур и имён параметров

Введите `(` после имени функции, и карточка покажет её параметры, выделяя тот, который вы вводите. Esc закрывает её. Чтобы имена параметров писались перед каждым аргументом в вызовах функций, включите **Подсказки имён параметров** в разделе **Настройки → Внешний вид → Редактор**, в группе **Typst**.

Значения цветов, например `rgb("#1f77b4")`, получают рядом небольшой образец. ⌘-щёлкните по ссылке или пути к файлу в исходнике, чтобы открыть его.

### Форматирование файла Typst

**Форматировать документ** приводит весь файл в порядок с помощью typstyle. Нажмите ⇧⌥F (Shift+Alt+F), щёлкните правой кнопкой мыши в редакторе или найдите команду в палитре ⌘K. **Форматировать выделенное** форматирует только выбранные строки.

Группа **Typst** в разделе **Настройки → Внешний вид → Редактор** управляет форматированием:

- **Форматировать при сохранении** форматирует файл Typst при каждом нажатии ⌘S (Ctrl+S). Автосохранение файл не трогает. По умолчанию выключено.
- **Ширина строки при форматировании** задаёт, где typstyle переносит длинные строки. По умолчанию 120 символов.
- **Отступ при форматировании** — количество пробелов на уровень. По умолчанию 2.
- **Проверки кода Typst** ищут вероятные ошибки при каждом сохранении. Включение или выключение перезапускает сервер языка.

## Несколько документов в одной папке

В одной папке может лежать несколько статей, например `manuscript.tex` рядом с `manuscript_v1.tex` или результатом `latexdiff`. Каждый файл LaTeX со своим `\documentclass` считается отдельным документом вместе с файлами, которые он подключает через `\input`, `\include` или `\subfile`. Метки, теоремы, записи глоссария и макросы принадлежат своему документу, поэтому метка в трёх копиях статьи не считается определённой три раза.

Переход к определению, поиск использований, переименование, автодополнение, [предпроверка](/docs/preflight/) и `oleafly check` остаются внутри документа, в котором вы работаете. `\ref` на метку, которую определяет только другой документ, показывается как неопределённая ссылка, и то же самое говорит компиляция. Файлы, которые пока не включает ни один документ, по-прежнему видят все метки, а проект с одним документом это не затрагивает.

## ИИ видит тот же индекс

У [ИИ-ассистента](/docs/ai-chat/) есть инструмент `project_map`, построенный на этом же индексе: оглавление, метки, цитирования, макросы, граф файлов и все неразрешённые ссылки. Когда вы спрашиваете его о «разделе о методологии», он действительно может его найти.
