typescript-lsp

TypeScript LSP スキル

目的

このスキルは、TypeScript／JavaScript のコードベースを調査して理解するための TypeScript Language Server Protocol 統合を提供します。

重要：*.ts、*.tsx、*.js、*.jsx ファイルを扱う場合は、Grep／Glob よりも LSP ツールを優先してください。LSP はインポート、エクスポート、シンボル間の関係を理解した、型を考慮した結果を提供します。

これらのツールは次の用途に使用できます。

• コードベースの調査 - シンボルを見つけ、モジュール構造を理解し、実装を特定します
• 参照の検索 - コードベース全体を型を考慮して検索します（シンボルの場合、grep よりも優れています）
• 型の理解 - 型シグネチャ、ジェネリクス、ドキュメントをすべて取得します
• 編集前の確認 - エクスポートを変更または削除する前に、すべての使用箇所を確認します
• コード内の移動 - 定義へ移動し、実装を探します

各ツールの使いどころ

ツール	目的
Glob	パターンでファイルを検索します
Grep	テキスト内容を検索します
lsp-find	TypeScript のシンボルを検索します
lsp-hover	型情報と TSDoc ドキュメントを取得します
lsp-refs	シンボルへのすべての参照を検索します
lsp-analyze	ファイル構造を一括分析します

LSP と Grep／Glob の比較

タスク	LSP を使用	Grep／Glob を使用
関数／型のすべての使用箇所を検索する	✅ lsp-refs	❌ 再エクスポートやエイリアスを見逃します
名前でシンボルを検索する	✅ lsp-find	❌ 文字列やコメントにも一致します
型シグネチャと TSDoc を取得する	✅ lsp-hover	❌ できません
ファイルのエクスポートを理解する	✅ lsp-analyze --exports	❌ 再エクスポートを解決できません
パターンでファイルを検索する	❌	✅ Glob
TS 以外のファイル（md、json）を検索する	❌	✅ Grep
コメント／文字列内のテキストを検索する	❌	✅ Grep

使用するタイミング

コードの調査（LSP を優先）：

• lsp-find を実行して、ワークスペース全体からシンボルを検索します
• lsp-symbols を実行して、ファイル構造の概要を取得します
• lsp-analyze --exports を実行して、モジュールが提供するものを確認します

コードを編集する前：

• 変更する予定のシンボルの使用箇所をすべて検索するため、lsp-references を実行します
• 現在の型シグネチャを確認するため、lsp-hover を実行します

コードを書く前：

• 類似のパターンや関連シンボルを検索するため、lsp-find を実行します
• 使用する予定の API に対して lsp-hover を実行します

パスの解決

すべてのスクリプトは、次の 3 種類のファイルパスを受け付けます。

• 絶対パス：/Users/name/project/src/file.ts
• 相対パス：./src/file.ts または ../other/file.ts
• パッケージエクスポートパス：my-package/src/module.ts（Bun.resolve() を使用して解決）

パッケージエクスポートパスは、移植性が高く、パッケージの exports フィールドとの一貫性も保てるため、推奨されます。

スクリプト

個別のスクリプト

lsp-hover

指定した位置の型情報を取得します。

bunx @plaited/development-skills lsp-hover <file> <line> <char>

引数：

• file：TypeScript／JavaScript ファイルへのパス
• line：行番号（0 始まり）
• char：文字位置（0 始まり）

例：

bunx @plaited/development-skills lsp-hover src/utils/parser.ts 42 10

lsp-symbols

ファイル内のすべてのシンボルを一覧表示します。

bunx @plaited/development-skills lsp-symbols <file>

例：

bunx @plaited/development-skills lsp-symbols src/utils/parser.ts

lsp-references

シンボルへのすべての参照を検索します。

bunx @plaited/development-skills lsp-refs <file> <line> <char>

例：

bunx @plaited/development-skills lsp-refs src/utils/parser.ts 42 10

lsp-find

ワークスペース全体からシンボルを検索します。

bunx @plaited/development-skills lsp-find <query> [context-file]

引数：

• query：シンボル名または部分名
• context-file：プロジェクトのコンテキストを開くための任意のファイル

例：

bunx @plaited/development-skills lsp-find parseConfig
bunx @plaited/development-skills lsp-find validateInput src/lib/validator.ts

一括スクリプト

lsp-analyze

効率化のため、1 回のセッションで複数の分析を実行します。

bunx @plaited/development-skills lsp-analyze <file> [options]

オプション：

• --symbols, -s：すべてのシンボルを一覧表示します
• --exports, -e：エクスポートされたシンボルのみを一覧表示します
• --hover <line:char>：型情報を取得します（複数指定可能）
• --refs <line:char>：参照を検索します（複数指定可能）
• --all：symbols と exports の分析を実行します

例：

# Get file overview
bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --all

# Check multiple positions
bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --hover 50:10 --hover 75:5

# Before refactoring: find all references
bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --refs 42:10

よくあるワークフロー

ファイルを理解する

# 1. Get exports overview
bunx @plaited/development-skills lsp-analyze path/to/file.ts --exports

# 2. For specific type info, hover on interesting symbols
bunx @plaited/development-skills lsp-hover path/to/file.ts <line> <char>

エクスポートを変更する前に

# 1. Find all references first
bunx @plaited/development-skills lsp-refs path/to/file.ts <line> <char>

# 2. Check what depends on it
# Review the output to understand impact

パターンを見つける

# Search for similar implementations
bunx @plaited/development-skills lsp-find handleRequest
bunx @plaited/development-skills lsp-find parseConfig

実装前の確認

# Before writing code that uses an API, verify its signature
bunx @plaited/development-skills lsp-hover path/to/api.ts <line> <char>

出力形式

すべてのスクリプトは JSON を標準出力に出力します。エラーは標準エラー出力に出力されます。

Hover の出力：

{
  "contents": {
    "kind": "markdown",
    "value": "```typescript\nconst parseConfig: (options: Options) => Config\n```"
  },
  "range": { "start": {...}, "end": {...} }
}

Symbols の出力：

[
  {
    "name": "symbolName",
    "kind": 13,
    "range": { "start": {...}, "end": {...} }
  }
]

Analyze の出力：

{
  "file": "path/to/file.ts",
  "exports": [
    { "name": "exportName", "kind": "Constant", "line": 139 }
  ]
}

パフォーマンス

スクリプトを呼び出すたびに、以下を実行します。

1. TypeScript Language Server を起動します（約300～500ms）。
2. LSP 接続を初期化します。
3. ドキュメントを開きます。
4. クエリを実行します。
5. ドキュメントを閉じて、サーバーを停止します。

同じファイルに対して複数のクエリを実行する場合は、lsp-analyze を使って1つのセッションに操作をまとめてください。

関連スキル

• code-documentation：ドキュメント作成のための TSDoc 規約