インストール

Timeline DSL はCLIツールとして利用します。初期サイトでは Homebrew 経由の導入を前提に案内します。

brew tap keroway/tap
brew install tdsl

インストール後、CLIが実行できることを確認します。

tdsl --help

必要な環境

• macOS または Linux（Homebrew / ワンラインインストール）
• Windows（PowerShell ワンラインインストール / バイナリ手動インストール）
• Git

Homebrew 以外の導入方法（macOS / Linux ワンラインインストール、Windows PowerShell、cargo-binstall、cargo）は Homebrewとその他の導入方法 を参照してください。

VS Code 拡張

v1.0.0 以降、構文ハイライトを提供する VS Code 拡張機能があります。v1.2.0 から Marketplace で公開されており、v1.4.0 以降はスニペットも利用できます。

インストール

VS Code の拡張機能パネル（Ctrl+Shift+X / Cmd+Shift+X）で Timeline DSL を検索してインストールします。または以下のコマンドを実行します。

code --install-extension keroway.timeline-dsl

利用可能なスニペット

| プレフィックス | 展開内容 | | -------------- | ------------------------------------------------------------------------------ | | timeline | timeline ブロックのテンプレート（title、unit、range、calendar 込み） | | lane | lane 定義のテンプレート（kind、order 込み） | | span | span イベントのテンプレート（開始・終了日時付き） |

スニペットはファイル拡張子が .tdsl のファイルで有効です。

VS Code 拡張は構文ハイライトとスニペットに加え、tdsl CLI が見つかる環境では組み込み LSP クライアントとして tdsl lsp を自動起動します。診断・補完・ホバー・定義ジャンプなどの対話的な機能は、次の言語サーバ（LSP）が担当します。

言語サーバ (LSP)

v1.11.0 以降、tdsl lsp で Timeline DSL の言語サーバ（LSP）を起動できます。LSP は標準入出力（stdio）で通信するため、LSP クライアントを持つエディタ（VS Code・Neovim・Helix・Emacs など）から接続して、.tdsl 編集中に対話的な支援を受けられます。VS Code 拡張は v1.19.0 以降で tdsl lsp を自動起動する LSP クライアントを内蔵しています。

| 機能 | 内容 | バージョン | | --------------------------------------- | ---------------------------------------------- | ---------- | | 診断（Diagnostics） | 構文・意味エラーを編集中にリアルタイム表示する | v1.11.0〜 | | 補完（Completion） | DSL キーワードを補完する | v1.12.0〜 | | ホバー（Hover） | lane ID / QID のホバー情報を表示する | v1.12.0〜 | | 定義ジャンプ（Goto Definition） | lane 参照から lane 宣言へジャンプする | v1.12.0〜 | | 参照検索（References） | lane ID の宣言・全参照位置を返す | v1.13.0〜 | | リネーム（Rename） | lane ID を宣言・全参照まとめて一括置換する | v1.13.0〜 | | コードアクション（Code Action） | lint の自動修正を quick fix として提供する | v1.13.0〜 | | ドキュメントシンボル（Document Symbol） | timeline > lane > 項目の階層シンボルを返す | v1.13.0〜 | | ドキュメント整形（Formatting） | 全文を正準スタイルに整形する | v1.14.0〜 |

起動コマンドは引数を取りません。

tdsl lsp

各エディタからは、コマンド tdsl lsp を .tdsl（言語 ID: tdsl）に紐づく言語サーバとして登録します。Neovim（0.10 以降のコア LSP、プラグイン不要）の例:

vim.filetype.add({ extension = { tdsl = "tdsl" } })

vim.api.nvim_create_autocmd("FileType", {
  pattern = "tdsl",
  callback = function()
    vim.lsp.start({
      name = "tdsl-lsp",
      cmd = { "tdsl", "lsp" },
      root_dir = vim.fs.root(0, { ".git" }),
    })
  end,
})

Helix の場合は languages.toml に登録します。

~/.config/helix/languages.toml

[language-server.tdsl-lsp]
command = "tdsl"
args = ["lsp"]

[[language]]
name = "tdsl"
scope = "source.tdsl"
file-types = ["tdsl"]
language-servers = ["tdsl-lsp"]

VS Code では Timeline DSL 拡張 が tdsl バイナリを PATH から解決し、tdsl lsp を自動起動します。必要に応じて拡張設定 timelineDsl.serverPath に tdsl の絶対パスを指定できます。Neovim / Helix などでは上記のように手動登録します。

各機能の使い方

• 診断 / 補完 / ホバー / 定義ジャンプ: 編集中に構文・意味エラーがリアルタイム表示され、DSL キーワードの補完、lane ID / QID のホバー、lane 参照から宣言へのジャンプが使えます。
• 参照検索（References）: lane の宣言または参照箇所にカーソルを置くと、その lane ID の全参照（lane 宣言・span / event / event_range の lane 指定・map の lane プロパティ）が一覧されます。
• リネーム（Rename）: lane ID 上でリネームすると宣言と全参照が一括置換されます。lane ID 以外（キーワードや文字列リテラル）の上ではリネームできません。
• ドキュメントシンボル（Document Symbol）: timeline > lane > 項目（span / event / event_range）の階層でアウトラインを返します。
• ドキュメント整形（Formatting）: エディタの整形コマンドで全文を正準スタイルに整形します（v1.14.0〜）。CLI の tdsl fmt と同一の整形エンジンを使います。コメントは tdsl fmt と同様に保持されますが、ブロック内コメントは正準位置へ移動する場合があります。

すべての機能はソーステキストの静的解析で動き、ネットワーク I/O は不要（offline）です。

コードアクションと fixable / non-fixable lint

コードアクションは tdsl lint --fix 相当の自動修正を quick fix として提示します。lint には自動修正できるものとできないものがあります。

| 種別 | 対象 lint | コードアクション | | ----------- | ----------------------------------------------- | --------------------------------------------------- | | fixable | start_gt_end / invalid_tags / missing_id | quick fix「自動修正可能な lint をすべて修正」を提示 | | non-fixable | unknown_lane / duplicate_id / empty_label | quick fix は出ない（手で修正する） |

fixable な issue が 1 件も無い場合、quick fix は表示されません。適用すると tdsl lint --fix と同一の emitter でドキュメント全文が整形・置換されます。コメントは可能な限り保持されますが、ブロック内コメントは正準位置へ移動する場合があります。出力は tdsl lint --fix と一致します。

tdsl lsp の概要は Commands も参照してください。