コードインテリジェンスとファイル管理

Posted at 2025-11-19

コードインテリジェンスとファイル管理

「このAPIを変更したら、どこに影響が出るだろう？」「この関数、どこで定義されているんだっけ？」大規模なコードベースでの開発では、こうした疑問が日常的に発生します。従来はIDEを開いて調べるか、grepで地道に検索していました。しかし、GitLab.comではブラウザ上で直接これらの情報にアクセスできます。本記事では、開発効率を向上させる2つの機能、コードインテリジェンスとファイル管理機能について解説します。

1. コードインテリジェンスが解決する課題

1.1. 従来の課題とLSIFによる解決

コードレビュー中に「この変数、他でも使われているのか？」と疑問に思ったとき、従来は以下のような手間がかかりました。

ローカルにリポジトリをクローンしてIDEで開く
全文検索で該当箇所を探す
文字列の一致だけでは、同名の別の変数も引っかかる

GitLabのコードインテリジェンスは、LSIF（Language Server Index Format）という技術を使ってこの問題を解決します。LSIFは、コードの構造を事前に解析し、シンボル（変数、関数、クラスなど）の定義と参照の関係をインデックス化します。これにより、単純な文字列検索ではなく、言語の文法を理解した正確なナビゲーションが可能になります。

LSIFの特徴

事前計算: ビルド時にインデックスを生成するため、ブラウザでの表示が高速
言語理解: 文字列の一致ではなく、言語の構文を理解した解析
プロジェクト全体の把握: ファイルをまたいだ参照関係も追跡可能

1.2. 実際の開発シーンでの活用

シーン1: コードレビュー時の影響範囲確認

マージリクエストで関数のシグネチャが変更されている場合、その関数の呼び出し箇所をすべて確認できます。ブラウザ上で関数名をクリックし、「参照」を選択するだけで、プロジェクト全体での使用箇所が一覧表示されます。

シーン2: 不慣れなコードベースの理解

新しいプロジェクトに参加したとき、コードの流れを追うのは大変です。コードインテリジェンスを使えば、関数の定義にジャンプし、その関数が呼び出している他の関数へと次々に移動できます。IDEを開かずに、ブラウザだけでコードの全体像を把握できます。

シーン3: ドキュメント作成時の正確な参照

イシューやマージリクエストのコメントで特定のコード箇所を参照する際、パーマリンクと組み合わせることで、正確な位置を共有できます。

2. コードインテリジェンスの導入

2.1. 対応言語の確認

GitLab.comでは、以下の言語に対応したCI/CDコンポーネントが提供されています。

Go: バージョン1.21以降
TypeScript / JavaScript: Node.jsプロジェクト
Java: バージョン8, 11, 17, 21
Python: GitLab 17.9以降
.Net/C#: GitLab 18.0以降

これらの言語以外でも、LSIFまたはSCIPインデクサーが存在すれば利用可能です。

2.2. 最も簡単な導入方法：CI/CDコンポーネント

GitLabが提供するCI/CDコンポーネントを使えば、数行の設定だけでコードインテリジェンスを有効化できます。

Goプロジェクトの例

.gitlab-ci.ymlに以下を追加します。

include:
  - component: ${CI_SERVER_FQDN}/components/code-intelligence/golang-code-intel@v0.0.3
    inputs:
      golang_version: ${GO_VERSION}

TypeScript/JavaScriptプロジェクトの例

include:
  - component: ${CI_SERVER_FQDN}/components/code-intelligence/typescript-code-intel@v0.0.3

Javaプロジェクトの例

include:
  - component: ${CI_SERVER_FQDN}/components/code-intelligence/java-code-intel@v0.0.3
    inputs:
      java_version: "17"

設定後、デフォルトブランチにプッシュすると、パイプラインが自動的にLSIFファイルを生成します。

2.3. カスタム設定：手動でのCI/CDジョブ追加

より細かい制御が必要な場合や、CI/CDコンポーネントが対応していない言語の場合は、手動でジョブを追加できます。

LSIFインデクサーを直接使用する場合（Go）

code_navigation:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
  image: sourcegraph/lsif-go:v1
  allow_failure: true
  script:
    - lsif-go
  artifacts:
    reports:
      lsif: dump.lsif

SCIPインデクサーを使用する場合（TypeScript）

SCIPは次世代のインデックス形式です。GitLabはネイティブサポートしていませんが、LSIF形式に変換することで利用できます。

code_navigation:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
  image: node:latest
  stage: test
  allow_failure: true
  script:
    - npm install -g @sourcegraph/scip-typescript
    - npm install
    - scip-typescript index
    - |
      env \
      TAG="v0.4.0" \
      OS="$(uname -s | tr '[:upper:]' '[:lower:]')" \
      ARCH="$(uname -m | sed -e 's/x86_64/amd64/')" \
      bash -c 'curl --location "https://github.com/sourcegraph/scip/releases/download/$TAG/scip-$OS-$ARCH.tar.gz"' \
      | tar xzf - scip
    - chmod +x scip
    - ./scip convert --from index.scip --to dump.lsif
  artifacts:
    reports:
      lsif: dump.lsif

2.4. 注意点と制限事項

アーティファクトサイズの制限

GitLab.comでは、LSIFアーティファクトのサイズを200MBに制限しています。大規模なプロジェクトでこの制限に達する場合は、以下の対策を検討してください。

モノレポの場合、サブプロジェクトごとに分割
不要なファイルをインデックス対象から除外

ブランチごとのサポート

現在、GitLabは1プロジェクトにつき1つのLSIFファイルのみを処理します。通常はデフォルトブランチに対してのみジョブを実行する設定にします。

allow_failure: trueの推奨

コードインテリジェンスのジョブが失敗しても、パイプライン全体を失敗させないようにallow_failure: trueを設定することを推奨します。これにより、インデックス生成に問題があっても、他のテストやデプロイは継続できます。

3. コードインテリジェンスの使い方

3.1. 基本的な操作

パイプラインが成功し、LSIFファイルが生成されると、すぐにコードインテリジェンス機能が利用できます。

コード > リポジトリからファイルを開きます
コード内のシンボル（変数、関数、クラスなど）にマウスカーソルを合わせます
点線が表示されたシンボルは、コードインテリジェンス情報が利用可能です
シンボルをクリックすると、ポップアップが表示されます

3.2. 定義へのジャンプ

関数やクラスの定義箇所を確認したいとき、以下の手順で移動できます。

シンボルをクリック
ポップアップで定義を選択
定義が記述されているファイルの該当行に直接ジャンプします

別のファイルに定義がある場合でも、瞬時に移動できます。

3.3. 参照の検索

「この関数、どこで使われているんだろう？」という疑問に答えるのが参照検索です。

シンボルをクリック
ポップアップで参照を選択
プロジェクト全体でそのシンボルが使用されている箇所の一覧が表示されます
一覧から任意の箇所を選択すると、該当ファイルの該当行に移動します

3.4. 実践的な活用例

リファクタリング前の影響範囲調査

関数名を変更する前に、その関数がどこで使われているかを確認します。参照検索で全使用箇所を把握し、変更の影響範囲を見積もれます。

APIの使用例の確認

社内ライブラリのAPIを使いたいとき、そのAPIの定義を確認し、さらに参照検索で実際の使用例を見つけられます。ドキュメントがなくても、実際のコードから使い方を学べます。

コードレビューでの深掘り

マージリクエストで変更されたコードを見ているとき、変更箇所で使われている関数の定義や、その関数の他の使用箇所を確認することで、変更の妥当性を判断できます。

4. ファイル管理機能との連携

コードインテリジェンスは、GitLabのファイル管理機能と組み合わせることで、さらに強力になります。

4.1. ファイルファインダーとの組み合わせ

プロジェクト内の任意の場所でtを押すと、ファイルファインダーが起動します。ファジー検索により、ファイル名の一部を入力するだけで目的のファイルを素早く見つけられます。

検索のコツ

ファイル名の頭文字を連続して入力: UserController.java → uc
パスの一部を含める: src/main/UserController.java → sm/uc
拡張子で絞り込む: .javaを含めて検索

ファイルを開いた後、コードインテリジェンスで関数の定義や参照を追跡できます。

4.2. パーマリンクでの正確な共有

コードインテリジェンスで見つけた重要な箇所を、チームメンバーと共有したいことがあります。パーマリンクを使えば、特定のコミット時点のコードを永続的に参照できます。

パーマリンクの作成手順

共有したいコード箇所を表示します
単一行の場合は行番号をクリック、複数行の場合はShiftを押しながら範囲選択します
yを押すか、アクション > パーマリンクをコピーを選択します
生成されたURLには、コミットSHAが含まれており、将来コードが変更されても同じ内容を参照できます

活用シーン

イシューでバグの発生箇所を正確に指摘
マージリクエストのコメントで、関連するコードを参照
ドキュメントに実装例のリンクを記載

4.3. オープンマージリクエストの確認

ファイルを表示すると、そのファイルを変更しているオープンマージリクエストの数がバッジで表示されます（GitLab 18.2以降）。これにより、以下のことがわかります。

自分が変更しようとしているファイルに、他の人の変更が入る予定があるか
コンフリクトが発生する可能性があるか
関連する変更を事前に確認できるか

確認手順

ファイルを開きます
画面右上のファイル名の横に、緑色のバッジが表示されます
バッジをクリックすると、過去30日間に作成されたオープンマージリクエストの一覧が表示されます
任意のマージリクエストを選択して、変更内容を確認できます

5. ファイルレンダリング機能

GitLabは、さまざまなファイル形式を自動的に整形して表示します。これにより、ブラウザ上で快適にドキュメントやデータを閲覧できます。

5.1. マークアップ言語のサポート

以下のマークアップ言語が自動的にレンダリングされます。

マークアップ言語	拡張子	用途
Markdown	`md`, `markdown`, `mdown`, `mkd`, `mkdn`	一般的なドキュメント
AsciiDoc	`adoc`, `ad`, `asciidoc`	技術文書
reStructuredText	`rst`	Pythonドキュメント
Org mode	`org`	Emacsユーザー向け
MediaWiki	`wiki`, `mediawiki`	Wiki形式

5.2. READMEの自動表示

リポジトリやディレクトリにREADMEファイルがあると、自動的に表示されます。GitLab 18.5以降では、_index.mdもサポートされています。

優先順位

複数のREADMEファイルがある場合、以下の順序で選択されます。

README.adoc
README.md
README.rst
README（プレーンテキスト）

この仕組みにより、プロジェクトのトップページやディレクトリごとの説明を、自動的に表示できます。

5.3. OpenAPI仕様のレンダリング

API開発では、OpenAPI（Swagger）仕様ファイルを使うことが一般的です。GitLabは、以下の命名規則に従ったファイルを自動的にレンダリングします。

有効なファイル名

openapi.yml, openapi.yaml, openapi.json
swagger.yml, swagger.yaml, swagger.json
openapi_gitlab.yml, gitlab.openapi.yml

レンダリング方法

OpenAPIファイルを開きます
レンダリングされたファイルを表示を選択します
APIのエンドポイント、パラメータ、レスポンスが整形されて表示されます

operationIdの表示

URLに?displayOperationId=trueを追加すると、各操作のIDが表示されます。これは、コード生成ツールを使う際に便利です。

5.4. その他の特殊ファイル

GeoJSON: 地図として視覚化されます
Jupyter Notebook: レンダリングされたHTMLとして表示され、コードと実行結果を確認できます

6. Git履歴の活用

6.1. ファイル履歴の確認

ファイルがどのように変更されてきたかを確認できます。

Gitファイル履歴: ファイル全体のコミット履歴を時系列で表示
Git blame: 各行が最後に変更されたコミットと作成者を表示

活用シーン

「なぜこのコードが書かれたのか」をコミットメッセージから理解
特定の行を変更した人に質問する
バグが混入したコミットを特定

6.2. コードインテリジェンスとの組み合わせ

コードインテリジェンスで気になる関数を見つける
Git blameでその関数がいつ追加されたかを確認
コミット履歴から、その変更の背景を理解
必要に応じて、コミット作成者に質問

このフローにより、コードの「なぜ」を深く理解できます。

7. `.gitattributes`によるカスタマイズ

7.1. ファイル処理の制御

.gitattributesファイルを使うと、GitLabがファイルをどう扱うかを制御できます。

構文ハイライトの指定

*.config linguist-language=YAML

拡張子が.configのファイルをYAMLとして扱い、構文ハイライトを適用します。

生成ファイルの折りたたみ

package-lock.json linguist-generated=true

マージリクエストの差分表示で、生成されたファイルを自動的に折りたたみます。

大きなファイルの扱い

*.psd filter=lfs diff=lfs merge=lfs -text

Photoshopファイルなどの大きなバイナリファイルをGit LFSで管理します。

7.2. トラブルシューティング：CPU使用率の問題

GitLabは、リポジトリの言語を判定するためにRuby gemを使用します。特定のファイルタイプ（.txtや未定義のXML拡張子）を解析する際、CPUを過度に使用することがあります。

解決方法

.gitattributesで明示的に言語を指定します。

*.txt linguist-language=Text
*.xml linguist-language=XML

これにより、ヒューリスティック解析をスキップし、CPU使用率を削減できます。

8. 段階的な導入ガイド

8.1. ステップ1: 小規模プロジェクトで試す

まずは、小さなプロジェクトでコードインテリジェンスを有効化してみましょう。

CI/CDコンポーネントを使って設定（2.2節参照）
デフォルトブランチにプッシュ
パイプラインが成功したら、ブラウザでコードを開いて動作を確認

確認ポイント

シンボルに点線が表示されるか
定義へのジャンプが正しく動作するか
参照検索で期待通りの結果が得られるか

8.2. ステップ2: チームでの活用

動作を確認したら、チームメンバーに使い方を共有します。

効果的な共有方法

コードレビュー時に実際に使ってみせる
「この関数の使用箇所を確認したい」というシーンで参照検索を実演
パーマリンクを使ったコメントの例を示す

8.3. ステップ3: 大規模プロジェクトへの展開

小規模プロジェクトで効果を実感したら、大規模プロジェクトにも展開します。

注意点

アーティファクトサイズの制限（200MB）を確認
必要に応じて、インデックス対象を絞り込む
パイプラインの実行時間への影響を測定

8.4. ステップ4: ワークフローへの組み込み

コードインテリジェンスを日常的なワークフローに組み込みます。

推奨プラクティス

コードレビュー時、変更箇所の参照検索を習慣化
リファクタリング前に必ず影響範囲を確認
新規参加メンバーのオンボーディングで、コードインテリジェンスの使い方を説明

9. まとめ

GitLab.comのコードインテリジェンスとファイル管理機能は、ブラウザ上での開発体験を大きく向上させます。

コードインテリジェンスの価値

IDEを開かずに、ブラウザだけでコードの構造を理解できる
コードレビューの質が向上し、見落としが減る
リファクタリングの影響範囲を正確に把握できる

ファイル管理機能の価値

ファイルファインダーで素早く目的のファイルにアクセス
パーマリンクで正確なコード参照を共有
マークアップファイルやOpenAPI仕様が自動的に整形表示される

導入のハードルの低さ

CI/CDコンポーネントを使えば、数行の設定で有効化
GitLab.comでは追加コストなしで利用可能
既存のワークフローを大きく変更する必要がない

まだ使っていない方は、まず小さなプロジェクトで試してみてください。.gitlab-ci.ymlにCI/CDコンポーネントを追加し、デフォルトブランチにプッシュするだけです。ブラウザ上でのコードナビゲーションの快適さを、ぜひ体験してください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

コードインテリジェンスとファイル管理

コードインテリジェンスとファイル管理

1. コードインテリジェンスが解決する課題

1.1. 従来の課題とLSIFによる解決

1.2. 実際の開発シーンでの活用

2. コードインテリジェンスの導入

2.1. 対応言語の確認

2.2. 最も簡単な導入方法：CI/CDコンポーネント

2.3. カスタム設定：手動でのCI/CDジョブ追加

2.4. 注意点と制限事項

3. コードインテリジェンスの使い方

3.1. 基本的な操作

3.2. 定義へのジャンプ

3.3. 参照の検索

3.4. 実践的な活用例

4. ファイル管理機能との連携

4.1. ファイルファインダーとの組み合わせ

4.2. パーマリンクでの正確な共有

4.3. オープンマージリクエストの確認

5. ファイルレンダリング機能

5.1. マークアップ言語のサポート

5.2. READMEの自動表示

5.3. OpenAPI仕様のレンダリング

5.4. その他の特殊ファイル

6. Git履歴の活用

6.1. ファイル履歴の確認

6.2. コードインテリジェンスとの組み合わせ

7. .gitattributesによるカスタマイズ

7.1. ファイル処理の制御

7.2. トラブルシューティング：CPU使用率の問題

8. 段階的な導入ガイド

8.1. ステップ1: 小規模プロジェクトで試す

8.2. ステップ2: チームでの活用

8.3. ステップ3: 大規模プロジェクトへの展開

8.4. ステップ4: ワークフローへの組み込み

9. まとめ

7. `.gitattributes`によるカスタマイズ