# コードインテリジェンス

LaTeX と Typst 向けの IDE 級のナビゲーション。定義へ移動、参照の検索、プロジェクト全体での名前変更、ホバーカード、数式プレビュー、ドキュメントのアウトライン、Typst のシグネチャヘルプと整形。

Oleafly はプロジェクト全体を索引化します。すべての `\label`、引用キー、カスタムマクロ、定理、用語集の項目、そしてファイル同士をつなぐ `\input` のグラフも対象です。この索引が、ファイルをまたぐナビゲーションを支えています。Typst ファイルでも同じショートカットが使え、応答するのは Typst の言語サーバーです。下の [Typst ファイル](#typst-files)をご覧ください。

ショートカットは macOS のキーで示しています。Windows と Linux では、⌘ を Ctrl と読み替えてください。

## 定義へ移動: F12 または ⌘ クリック

`\ref`、`\cite` のキー、カスタムマクロ、自分で定義した環境の `\begin{env}`、用語集の用語にカーソルを置いて F12 を押します (または ⌘ を押しながらクリックします)。エディタが定義の場所に移動します。定義がプロジェクト内の別のファイルにある場合は、そのファイルを開きます。

すでに定義の上にいるときに F12 を押すと、その参照の検索に切り替わります。IDE と同じ慣例です。

## 参照を検索: ⇧F12

Shift+F12 を押すと、左側のレールの**参考文献**パネルに、そのシンボルのすべての使用箇所が一覧表示されます。1 件につき 1 行で、ファイル、行、プレビューが表示され、定義そのものには「def」のバッジが付きます。行をクリックするとその場所に移動します。「このラベルは削除してよいか」「この論文をどこで引用したか」を調べるには、これがいちばん速い方法です。

![数式のラベルを 2 つのファイルで同時に名前変更し、その参照を一覧表示するところ。](https://cdn.oleafly.com/images/gifs/desktop/rename-symbol.gif?v=2)

## シンボルの名前を変更: F2

F2 を押すと、ラベル、引用キー、マクロ、定理、用語集の項目、環境の名前を、プロジェクト全体で一度に変更できます。開いているファイルはその場で更新され、ほかのファイルはディスク上で書き換えられ、索引が再構築されます。新しい名前がすでに存在する場合は、衝突が起きる前に名前の変更がブロックされます。トーストには、何件の編集が何個のファイルに反映されたかが表示されます。

`fig:overview` を `fig:architecture` に変更して、6 か所の `\ref` がすべて追従するのは、2 秒の作業です。

カーソルを `\input` や `\includegraphics` の引数のようなファイルパスに置いた場合は、F2 でそのファイルの名前を変更し、それを指すパスも更新します。Typst の `#include` と `image()`、Markdown のリンクと画像でも同じように使えます。[パスは移動したファイルに追従する](/docs/files/#paths-follow-a-moved-file)をご覧ください。

## ホバーカード

シンボルにポインタを合わせると、カードで説明が表示されます。

- **参照**の場合: シンボルの種類、ソースのプレビュー、場所。LaTeX のビルドに成功したあとは、対応する参照にコンパイル後の番号とページも表示されます。
- **定義**の場合: プロジェクト全体での参照の数。
- **未解決**のものの場合: 「未解決」というはっきりしたラベル。`\ref` の打ち間違いや、`.bib` の項目の不足を、いちばん早く知らせてくれます。

⌘ (Ctrl) を押しながらポインタを合わせると、クリックできるシンボルにリンクのような下線が付きます。クリックするとその場所に移動します。

## ホバーでの数式プレビュー

インラインの `$…$`、`\(…\)`、またはディスプレイの `\[…\]` の数式にポインタを合わせると、コンパイルせずに KaTeX で描画されます。ディスプレイ数式にはディスプレイスタイルが使われます。式が壊れている場合は、そのエラーが表示されます。

## アウトラインパネル

ファイルツリーの下の**アウトライン**パネルには、ドキュメントの構造が表示されます。セクションがレベルごとにインデントされ、`\input` による取り込みも、すべてのファイルにわたって表示されます。ほかのファイルの項目にはファイル名のバッジが付きます。どれかをクリックすると、そこへ直接移動します。十数個の章のファイルに分かれた学位論文では、これが移動に使う目次になります。

セクションのタイトルはプレーンテキストで表示されるので、タイトル中の色のコマンド、フォントの切り替え、`\nameref` が、生の LaTeX として表示されることはありません。`\section` を包む自作のマクロで作った見出しは一覧に載りますが、マクロ定義の中にある見出しは載りません。

ツリーとアウトラインの間の仕切りはドラッグして、大きさを変えられます。

## ツールバーとメニューでの場所

3 つのナビゲーションのコマンドは、エディタのツールバーの**コードインテリジェンス**メニュー (波括弧のアイコン) と、右クリックメニューにもあります。ショートカットが身に付く前でも、見つけやすくなっています。

## Typst ファイル

`.typ` ファイルでは、Typst の言語サーバーである Tinymist が、これらのコマンドの大部分に応答します。Oleafly は、プロジェクトの Typst のバージョンに合った Tinymist のリリースを実行します ([Typst プロジェクト](/docs/typst/#the-language-server-follows-the-version)をご覧ください)。

- F12 または ⌘ クリックで、ラベル、変数、関数の定義に移動します。別のファイルにあるものも対象です。
- ⇧F12 で、 **参考文献**パネルにすべての使用箇所が一覧表示されます。
- F2 で、ラベル、変数、関数の名前を、プロジェクト全体で変更します。
- 関数にポインタを合わせると、そのドキュメントを読めます。`@preview` のインポートにポインタを合わせると、Typst Universe 上のパッケージへのリンクが表示されます。

同じ 3 つのコマンドは、Typst のツールバーの**コードインテリジェンス**メニュー、右クリックメニュー、⌘K のパレットにもあります。Typst と LaTeX のファイルのラベルは別々に扱われるので、両方で使われているラベルが二重に報告されることはなく、一方の名前を変更してももう一方はそのままです。

### シグネチャヘルプとパラメーターのヒント

関数名のあとに `(` を入力すると、カードにその関数のパラメーターが表示され、入力中のものが強調されます。Esc で閉じます。関数呼び出しの各引数の前にパラメーター名を表示するには、 **設定 → 外観 → エディタ**の **Typst** にある**パラメーター名のヒント**をオンにします。

`rgb("#1f77b4")` のような色の値には、横に小さな色見本が付きます。ソース内のリンクやファイルパスを ⌘ クリックすると、それを開けます。

### Typst ファイルを整形する

**文書を整形**は、typstyle でファイル全体を整えます。⇧⌥F (Shift+Alt+F) を押すか、エディタで右クリックするか、⌘K のパレットから探します。 **選択範囲を整形**は、選択した行だけを整形します。

**設定 → 外観 → エディタ**の **Typst** グループで、フォーマッターを制御します。

- **保存時に整形**は、⌘S (Ctrl+S) を押して Typst ファイルを保存するたびに整形します。自動保存では整形されません。既定ではオフです。
- **フォーマッターの行幅**は、typstyle が長い行を折り返す位置です。既定は 120 文字です。
- **フォーマッターのインデント**は、1 レベルあたりのスペースの数です。既定は 2 です。
- **Typst の lint チェック**は、保存のたびに、間違いの可能性が高い箇所を探します。オンとオフを切り替えると、言語サーバーが再起動します。

## 1 つのフォルダに複数のドキュメントがあるとき

1 つのフォルダに、複数の論文を置くことがあります。たとえば `manuscript.tex` の隣に `manuscript_v1.tex` や `latexdiff` の出力がある場合です。自分の `\documentclass` を持つ LaTeX ファイルは、それぞれ別のドキュメントとして扱われ、`\input`、`\include`、`\subfile` で読み込むファイルもそのドキュメントに含まれます。ラベル、定理、用語集の項目、マクロは、それぞれのドキュメントに属するので、論文の 3 つのコピーにあるラベルが、3 回定義されたとは表示されません。

定義へ移動、参照の検索、名前の変更、補完、[プリフライト](/docs/preflight/)、`oleafly check` は、作業中のドキュメントの中にとどまります。別のドキュメントだけが定義しているラベルへの `\ref` は未定義と表示され、これはコンパイルの結果と同じです。どのドキュメントにもまだ含まれていないファイルからは、引き続きすべてのラベルが見え、ドキュメントが 1 つだけのプロジェクトは影響を受けません。

## AI も同じ索引を使う

[AI アシスタント](/docs/ai-chat/)には、この同じ索引をもとにした `project_map` ツールがあります。アウトライン、ラベル、引用、マクロ、ファイルのグラフ、未解決の参照を扱えます。「手法のセクション」について尋ねたときに、アシスタントはそれを実際に見つけられます。
