VS Code 統合 内部仕様書

対象読者: コア実装に手を入れる開発者。ユーザー向けセットアップや機能紹介は IronHSP 仕様書 §11 参照。

最終更新: 2026-04-20 / ブランチ: update-hsp3net / 関連コミット: a025002b 〜 1e5a3fee

1. 全体アーキテクチャ

VS Code 統合は 3 つの独立した機能の集合体で、それぞれ別プロセス/別バイナリで動作します:

これら全てを vscode-nhsp 拡張 から起動/接続します (既存の .nhsp 拡張に .hsp 機能を追加した形)。

2. 該当ファイル/ディレクトリマップ

3. DAP デバッガ実装詳細

3.1 プロセス構成と起動フロー

3.2 2-pipe アーキテクチャの理由

3.3 hsp3net ランタイム改変箇所

hsp3code.cpp

HSP3_DAP_MODE 下でのみ有効な追加 export:

// exe が export するシンボル (DLL から GetProcAddress で解決)
extern "C" __declspec(dllexport) volatile int hsp3dap_bp_count = 0;
extern "C" __declspec(dllexport) void hsp3dap_register_bp_check(fn);
extern "C" __declspec(dllexport) void hsp3dap_force_step(void);
extern "C" __declspec(dllexport) int  hsp3dap_get_var_type(const char*);
extern "C" __declspec(dllexport) int  hsp3dap_set_var_int(name, idx[], num_idx, value);
extern "C" __declspec(dllexport) int  hsp3dap_set_var_int64(...);
extern "C" __declspec(dllexport) int  hsp3dap_set_var_double(...);
extern "C" __declspec(dllexport) int  hsp3dap_set_var_str(...);   // sbStrCopy 経由
extern "C" __declspec(dllexport) int  hsp3dap_set_var_wstr(...);  // UTF-8 → UTF-16

// dispatch loop の 4 箇所に追加された条件 (HSP3_DAP_MODE 時のみ):
if (dbgmode || hsp3dap_bp_count > 0) code_dbgtrace();

// code_dbgtrace() 内で BP ヒット検知:
if (g_hsp3dap_bp_check && hsp3dap_bp_count > 0) {
    bp_hit = g_hsp3dap_bp_check(dbginfo.fname, dbginfo.line);
}
if (dbgmode || bp_hit) { runmode = STOP; msgfunc(); }

win32/hsp3cl.cpp

// 修正前: x86 stdcall decorated name のみ
dbgwin = GetProcAddress(h_dbgwin, "_debugini@16");

// 修正後: x64 bare name 優先、失敗時 x86 decorated へ fallback
dbgwin = GetProcAddress(h_dbgwin, "debugini");
if (dbgwin == NULL) dbgwin = GetProcAddress(h_dbgwin, "_debugini@16");

// hsp3cl_stop() の GetMessage ループ:
// 修正前: while(1) { GetMessage(...); if (runmode != STOP) break; }
//         → runmode が既に RUN でも GetMessage で blocking (msg 無し)
// 修正後: while (runmode == STOP) { GetMessage(...); ... }
//         → dbgnotice で runmode=RUN なら即抜ける

win32/main.cpp

#ifdef HSP3_DAP_MODE
    // 子プロセスで stdout を redirect される時に block-buffered になって
    // mes 出力が end まで届かない問題を回避
    setvbuf(stdout, NULL, _IONBF, 0);
    setvbuf(stderr, NULL, _IONBF, 0);
#endif

3.4 IPC wire protocol

名前付きパイプ \\.\pipe\hsp3dap_<pid>_evt / _cmd、UTF-8 改行区切り (LF) JSON。

DLL → adapter (events) — _evt パイプ経由

{"evt":"ready"}
{"evt":"stopped","reason":"entry|breakpoint|step|pause|exception","line":N,"file":"path"}
{"evt":"terminated","exit":N}

adapter → DLL (commands) — _cmd パイプ経由

{"cmd":"set_bp","file":"path","lines":[10,20]}      → {"resp":"bp_ack"}
{"cmd":"continue"|"step_over"|"step_in"|"step_out"|"pause"}
{"cmd":"get_vars"}                                   → {"resp":"vars","items":[...]}
{"cmd":"get_callstack"}                              → {"resp":"callstack","frames":[...]}
{"cmd":"set_var","name":"x","indices":[0,1],"value":"42"}
                                                     → {"resp":"set_var","ok":1}
{"cmd":"evaluate","expr":"iarr(1,1) = 77"}           → {"resp":"evaluate","ok":1,"result":"77"}
{"cmd":"disconnect"}

BP パスマッチングは両側で Path.GetFileName().ToLowerInvariant() に正規化して比較 (VS Code は絶対パス、HSP runtime は相対パスを送ってくるため)。

3.5 setVariable / evaluate 実装

5 種の HSP 変数型に対応。配列・モジュール変数透過。

ランタイム側の書き込みロジック

// int / int64 / double: pv->pt から要素 offset 計算して直接代入
int* arr = (int*)pv->pt;
arr[offset] = value;

// str: HSP の文字列は sbAlloc 可変長バッファで管理 (pv->pt は char*、
// 配列時は (char**)pv->master[idx] が各要素の buffer ptr)。
// sbStrCopy() で安全に再確保 (memcpy 直書きは NG)。
char** pp = (off == 0) ? &pv->pt : &((char**)pv->master)[off];
sbStrCopy(pp, (char*)value);

// wstr: UTF-8 → UTF-16 変換して固定長 wchar_t バッファへ
MultiByteToWideChar(CP_UTF8, 0, value_utf8, -1, base, elem_chars);

evaluate の式パース

DLL 側の handle_command("evaluate", ...) で簡易 LHS parser を走らせる:

expr = "iarr(1,1) = 77"
 → split by '='
 → lhs = "iarr(1,1)", rhs = "77"
 → paren split: name = "iarr", indices = [1, 1]
 → hsp3dap_get_var_type("iarr") → HSPVAR_FLAG_INT
 → hsp3dap_set_var_int("iarr", [1,1], 2, 77)

expr = "m_val@mymod = 555"
 → name = "m_val@mymod" (そのまま HSP 名前解決に渡せる)
 → hsp3dap_get_var_type("m_val@mymod") → HSPVAR_FLAG_INT
 → hsp3dap_set_var_int("m_val@mymod", NULL, 0, 555)

4. LSP サーバ (hspls) 実装詳細

4.1 プロセス構成

VS Code 拡張が hspls.exe を spawn。拡張からの LSP 要求に応じて、 hspls が hspcmp64.exe を subprocess で呼び出し、出力を LSP レスポンスに変換する。

4.2 hspcmp 出力パース

シンボルリスト (-ll / -lv / -ls)

出力書式: <kind> <name> <line>:<file>

dmac の分類 — ファイル由来で意味が変わる

ビルトインキーワード (-lk)

出力書式: <name>\t,<kind> (例: goto\t,sys|func)。 hspls 起動時に 1 回だけ呼んで HashSet 化、Symbol テーブルに未登録な識別子の fallback 分類に使う。

診断 (エラー/警告)

書式: <file>(<line>) : error <code> : <message> (または warning)

test.hsp(2) : error 2 : 文法が間違っています (2行目)

4.3 temp file 方式

現在は同じディレクトリに foo.__hspls.hsp のサイドカー temp file を書いて hspcmp に食わせ、出力の file フィールドを本ファイル名に rewrite した後 temp を削除する。

同じ dir に書く理由は、HSP の #include "common/..." 等の相対 path 解決を壊さないため。

5. セマンティックトークン実装

LSP の textDocument/semanticTokens/full で、識別子単位の 4 分類色分けを提供。 TextMate grammar の regex では判別不能な「ユーザ定義 vs 外部 DLL」を実シンボル情報で区別する。

Token legend (LspServer.cs)

tokenTypes: [
  "function",   // 0: user #deffunc/#defcfunc (.hsp 由来 dfnc)
  "method",     // 1: external DLL (.as 由来 dexc or dfnc)
  "macro",      // 2: HSP3 built-in (hspcmp -lk or hspdef.as dmac)
  "variable",   // 3: reserved
  "keyword",    // 4: control flow (if/else/repeat/loop/…)
]
tokenModifiers: []  (未使用)

分類アルゴリズム (LspServer.ClassifyIdentifier)

// 1. 制御構文キーワードは最優先で keyword
if (ControlKeywords.Contains(word)) return TYPE_KEYWORD;

// 2. ワークスペース symbol table lookup
if (syms.TryGetValue(word.ToLowerInvariant(), out hits)) {
    foreach (var s in hits) {
        bool isAs     = fname.EndsWith(".as");
        bool isHspdef = fname == "hspdef.as";
        switch (s.Kind) {
            case "dfnc": return (isAs && !isHspdef) ? METHOD : FUNCTION;
            case "dexc": return METHOD;
            case "dmac":
                if (isHspdef) return MACRO;        // ビルトイン定数
                if (isAs)     return METHOD;        // DLL binding
                return FUNCTION;                    // ユーザ #define
        }
    }
}

// 3. hspcmp -lk のビルトインキーワード集合
if (_builtins.Contains(word)) return TYPE_MACRO;

// 4. それ以外 — TextMate grammar に委譲
return -1;

トークナイザ (LspServer.TokenizeHsp)

独自 mini-lexer。行単位で walk、;/////* *//"..."/{"..."} をスキップ。 識別子は [A-Za-z_][A-Za-z_0-9@]* (@ は name@module の区切りとして含める)。

Delta encoding (LSP 仕様)

// token = [deltaLine, deltaStart, length, typeIdx, modifierMask]
// deltaLine = 前トークンとの行差
// deltaStart = 同じ行なら前トークンとの列差、違う行なら行頭からの列
// 全 token を (line, col) 昇順でソート済であること

5.5 ドキュメントコメント (;;; / ///) の仕組み

nhspc/HspLanguageServer/DocCommentParser.cs で実装。 hspcmp によるシンボル抽出の後に source を 1 パス舐める。

アルゴリズム (疑似コード)

docBuf = []
for line in source.split('\n'):
    trimmed = line.trimStart()
    if trimmed.startsWith(";;;") or trimmed.startsWith("///"):
        docBuf.append(stripMarker(trimmed))
        continue
    if trimmed.isEmpty: continue               # 1行空けは許容
    if trimmed.startsWith(";") or "//":
        continue                                # 普通のコメントはスルー (重要)
    # 実行可能 or 宣言行
    m = DeclRx.match(line)   # #deffunc / #defcfunc / #func / ... / #const / #define / #enum
    if m and docBuf.nonEmpty:
        attachDocsToSymbol(name = m[2], declLine, docBuf)
    docBuf.clear()

宣言との結びつきは名前 + 行番号の近傍一致 (±2 行) で検証。hspcmp の kind ごとの行番号のズレを吸収。@param name desc / @return desc (@arg / @returns は alias) を分離、残りは description。

ホバー出力フォーマット

```hsp
(function) distance
```
<description>

**Parameters:**
- `name` — desc
- ...

**Returns:** ...

_— file.hsp:NN_

5.6 signatureHelp の実装

LSP の textDocument/signatureHelp で、関数呼び出し中に シグネチャ + activeParameter を返す。

シグネチャデータ (DocCommentParser.ExtractSigParams)

宣言行を regex で切り出し、引数リストを HspSigParam { Type, Name } の 配列に変換して HspSymbol.SigParams に保存。宣言種別 (#deffunc 等) は別フィールド DeclKind に保存 (hspcmp の Kind=dfnc だけでは #deffunc と #defcfunc が区別できないため)。

// 命令形式 (名前付き)
#deffunc foo str _name, int _age
  → SigParams = [{Type:"str", Name:"_name"}, {Type:"int", Name:"_age"}]
    DeclKind = "#deffunc"

// 関数形式 (名前付き)
#defcfunc bar int _a, int _b
  → SigParams = [{Type:"int", Name:"_a"}, {Type:"int", Name:"_b"}]
    DeclKind = "#defcfunc"

// DLL バインディング (名前なし)
#func Beep "Beep" sptr, sptr
  → SigParams = [{Type:"sptr", Name:""}, {Type:"sptr", Name:""}]
    DeclKind = "#func"

local _tmp の内部 scratch パラメータは除外。文字列/括弧ネストを 考慮した top-level 分割 (DocCommentParser.SplitTopLevel) で foo(a, b) のような型修飾内の , を誤認しないように。

TryLocateCall: カーソル位置から呼び出しを特定

カーソル位置から source を backward scan:

1. 未マッチの ( を探す () でカウント減)
2. 見つかれば paren 形式: その直前の識別子が関数名、 ( とカーソル間の top-level コンマ数が activeParameter
3. 無ければ statement 形式 fallback: 現在行の行頭から最初の 識別子が関数名、識別子後からカーソルまでのコンマ数が activeParameter

文字列リテラル "..." の中の ( / ) / , は無視。 制御構文キーワード (if/else/repeat/loop/ goto/gosub/return/end 等) は関数として 扱わない (偽陽性回避)。

ラベル書式 (命令 vs 関数)

統一せず DeclKind で書式切替。HSP のユーザはコードで両者を 使い分けるので、log_kv "y", y に対して log_kv(str _key, int _val) と括弧付きで出すと紛らわしい。

statementStyle = DeclKind ∈ { "#deffunc", "#func", "#modfunc", "#comfunc" }
  ↓
  命令形式:   "name type1 arg1, type2 arg2"   (括弧なし)
  関数形式:   "name(type1 arg1, type2 arg2)"  (括弧あり)

パラメータ documentation

LSP の ParameterInformation は label と documentation (optional) を持つ。activeParameter のときに VS Code が下部に表示する。

各 SigParam に対応する DocParam を検索して attach:

1. 名前一致: SigParam.Name == DocParam.Name で探す
2. 順序フォールバック: 名前なし (#func 等) なら i 番目の SigParam に i 番目の DocParam をペアリング

5.7 ;;; / /// の自動テンプレ展開

VS Code 拡張の onDidChangeTextDocument で単一文字 / / ; の挿入を検知。現在行が trim 後 exactly /// / ;;; で、 直下の非空非コメント行がマッチする宣言なら vscode.SnippetString で placeholder 付きテンプレに置換。

// 再入防止フラグ _hspDocTemplateBusy で自前の edit がループしないように
// protect。setTimeout(..., 0) で change handler 終了後に defer する。
const snippet = new vscode.SnippetString(
    `${marker} \${1:説明}\n` +
    `${indent}${marker} @param ${paramName} \${2:説明}\n` +
    `${indent}${marker} @return \${3:戻り値の説明}`
);
editor.insertSnippet(snippet, markerRange);

宣言種別を regex で判定:

• HSP_DECL_RX: #deffunc / #defcfunc / #func / #cfunc / #cfuncd/#cfuncf/#cfuncst / #comfunc / #modfunc / #modcfunc / #const / #define / #enum
• HSP_VAR_DECL_RX: dim / sdim / ddim / ldim / dim64 / wdim / dimtype
• HSP_VAR_ASSIGN_RX: ^\s*([A-Za-z_]\w*)\s*=(?!=) (== や arr(0) = 1 を除外)

関数系は戻り値有無を kind で判定 (#defcfunc/#cfunc*/#modcfunc は @return 行付き)。変数系・暗黙宣言は description 1 行のみ。

5.8 BP verified 判定

nhspdap/DapSession.SetBreakpoints で各 BP 行を簡易チェック:

実行可能行の判定は heuristic (regex ^\s*[^;/#\s] 相当)。 ブロックコメント /* */ の中身は不正確に true 返すが許容。

unverified な BP は DLL への set_bp コマンドの lines 配列に 含めない → bp_count が余分にインクリされず runtime のホットパスを 軽く保てる。

6. ビルド手順

全部入りビルド (初回)

# C# (nhspdap / hspls / nhspls)
cd nhspc
dotnet build NhspCompiler.sln -c Release

# C++ (hsp3debug_dap.dll)
MSBuild.exe plugins/win32/hsp3debug_dap/hsp3debug_dap.vcxproj \
    -p:Configuration=Release -p:Platform=x64

# C++ (hsp3cl_net_dbg_64.exe)
MSBuild.exe hsp3net/hsp3cl_net_dbg_64.vcxproj \
    -p:Configuration=Release -p:Platform=x64

VS Code 拡張 (dev モード)

# 拡張自体は node.js なのでビルド不要
# VS Code で nhspc/vscode-nhsp/ を開いて F5 で Extension Development Host が起動

7. 既知の罠 (踏みやすい順)

1. hspcmp64 の -d だけでは DLL がロードされない。
   -d はデバッグ情報を .ax に埋め込むだけ。hsp3debug.dll がロードされるためには HSPHED_BOOTOPT_DEBUGWIN が立っている必要があり、これは -w (debug window force) で立つ。 結論: デバッグ対象は必ず hspcmp64 -d -w -i foo.hsp でコンパイルする。
2. /clr mixed-mode + 同一 duplex pipe の concurrent ReadFile + WriteFile は壊れる。
   ERROR_BROKEN_PIPE (109) が ReadFile 直後に発生。2 本の simplex pipe に分けるのが唯一の解。
3. HSP の str 変数は sbAlloc 可変長バッファ。memcpy で直書きすると死ぬ。
   pv->pt は「文字列バッファへの char*」であって「バッファ本体」ではない。 書換は sbStrCopy(&pv->pt, new_value) で行う (可変長なので再確保が必要)。
4. hspcmp に絶対 path を渡すと -ll/-lv/-ls の file 欄も絶対 path になる。
   basename 正規化で比較するコードが両側 (DLL の BP マッチャ、LSP の Local フィルタ) に要る。
5. stackTrace の source.path は絶対 path 必須。
   VS Code が相対 path で source を開けず内部エラー (Cannot read properties of undefined) で落ちる。 setBreakpoints 時に basename → absolute path マップを保持して、stackTrace 時に絶対化する。
6. 子プロセスの stdout は block-buffered になる。
   親 (nhspdap) が pipe 経由で読むとき、HSP runtime の fputs(mes, stdout) は end/exit まで 溜まる。setvbuf(stdout, NULL, _IONBF, 0) で runtime 起動時に無効化。
7. CLR /clr exe の __declspec(dllexport) 変数は動く、ただし .cpp が /clr でない時のみ安全。
   hsp3code.cpp は <CompileAs>CompileAsCpp</CompileAs> でネイティブビルド指定。 /clr ファイルに dllexport 変数を書くと AppDomain 分離等で挙動が不安定。
8. std::mutex は non-recursive。
   set_bp ハンドラが g_bp_mutex を保持したまま sync_bp_count_to_exe を呼び、そこで再ロックすると 例外になる。_locked サフィックスで「lock 済前提」を明示する命名規則で統一。
9. package.json の languageModelTools は canBeReferencedInPrompt で modelDescription + toolReferenceName 必須。
   VS Code の API が変わった。legacy に無い型で Extension CANNOT register tool エラー。
10. .hsp → hsp 言語マッピングが無いと BP を置けない。
    package.json の contributes.languages に {id:"hsp", extensions:[".hsp"]} を 登録しないと、breakpoints: [{language:"hsp"}] が効かない。
11. HSP runtime は空行を dispatch しない。
    BP を blank 行に設定しても絶対ヒットしない。adapter 側で「最も近い次の実行行」にスナップする 機能は未実装 (v2)。ユーザに _bp_target = 1 のような明示的な BP 行を用意してもらう想定。
12. 外部 DLL 関数の hspcmp kind は dfnc でも dmac でもなく dexc。
    正規表現 (dfnc|dlab|dvar|dmac|dmod) だけでパースすると GetTickCount 等が 未分類になる (method カラーが出ない)。dexc を必ず含める。
13. DLL が stopped event を送る時 fname を JSON エスケープしないと死ぬ。
    dbginfo.fname は j:\HNWorks\... 形式の Windows パス。JSON 文字列に 直入れすると \H \t 等が無効エスケープとして扱われ、adapter の JObject.Parse が silently fail。try/catch で continue されるためエラー ログにも出ず、VS Code から見ると「BP ヒットしても何も起きない」状態に。 相対パスでコンパイルしていた頃は地雷が見えなかった。必ず json_esc() を通す。
14. line 1 (最初の実行行) の BP は force_step entry stop に吸収される。
    force_step を debugini で即呼ぶと、adapter の set_bp が pipe に到達する前に debug_notice が発火し、g_breakpoints が空のため reason="breakpoint" に 分類できない。解決: debugini を g_start_event で待機させ、 adapter の configurationDone 受信時に {"cmd":"start","stopOnEntry":N} を送って DLL 側が初めて force_step 要否を判断する流れに変更。ついでに launch.json の stopOnEntry が実際に効くようになる。
15. .NET subprocess で stdout + stderr を両方 ReadToEnd() すると deadlock。
    典型的な .NET trap。stderr が満杯 → hspcmp ブロック → stdout EOF 来ない → ReadToEnd ずっと blocking → WaitForExit すら呼べない。OutputDataReceived / ErrorDataReceived イベント + BeginOutputReadLine / BeginErrorReadLine で async 読み取りにする。
16. hspcmp のエラー出力は UTF-8 でなく ANSI code page (日本語環境なら CP932)。
    -i (UTF-8 入力モード) を付けても ERROR MESSAGE は実行環境の ANSI。 .NET 側で StandardOutputEncoding = GetEncoding(ANSICodePage) で受け取り、 内部で UTF-16 に変換してから VS Code (UTF-8) へ渡す。一方 HSP ランタイム (HSPUTF8 ビルド) の stdout は UTF-8 なので読み取り側を使い分ける。
17. MessageBoxA + UTF-8 バイト列はエラーメッセージ文字化けの温床。
    HSPUTF8 ビルドでは errmsg が UTF-8 バイト列。A 系 Win32 API は ANSI として解釈するので日本語環境で必ず文字化け。MultiByteToWideChar(CP_UTF8) で UTF-16 変換してから MessageBoxW を使う。
18. LSP で didChange 時に再解析しないと hover が陳腐化する。
    didSave 限定の再解析はエディタバッファ編集や外部ツールによるディスク書換に 追従できない。didChange 内で毎回 ReparseDoc を呼ぶのが最短。hspcmp は 小規模 .hsp なら数十ms で回るので打鍵毎でも許容範囲。大規模プロジェクト なら debouncer を追加検討。
19. signatureHelp の ParameterInformation に documentation を渡し忘れる。
    LSP 応答側で parameter.documentation を送っても、VS Code 拡張側で new vscode.ParameterInformation(label) と 1 引数だけで作ると popup に 出ない。第 2 引数 (MarkdownString) に p.documentation.value を包んで渡す。
20. hspcmp の Kind は #deffunc と #defcfunc を区別しない。
    両方とも dfnc として emit される。signatureHelp の書式切替 (括弧の有無) や命令/関数の意味的差異は、source から DeclKind を直接拾って HspSymbol に 保持しておく必要がある。
21. HSP の変数は「最初の出現位置」が定義扱い。
    x = 10 を 3 箇所で書いても hspcmp は 1 個の dvar エントリしか emit しない (一番上)。DocCommentParser の ±2 行マッチング条件により自然と 「最初の doc 勝ち」になるが、これは HSP の semantics と一致。 後続の再代入上の ;;; は silently 無視される。

8. 拡張方法

新しい LSP メソッドを追加する

1. nhspc/HspLanguageServer/LspServer.cs の HandleRequest switch に case 追加
2. ハンドラメソッドを実装 (例: HandleReferences(ps))
3. capabilities にプロパティ追加 (BuildInitializeResult)
4. nhspc/vscode-nhsp/src/hsp-lsp-client.js にラッパメソッド追加
5. extension.js で VS Code Provider 登録 (vscode.languages.registerReferenceProvider 等)

新しい変数型の書換サポート

1. hsp3net/hsp3code.cpp に hsp3dap_set_var_<type> を export として追加
2. DLL の hsp3debug_dap.cpp で:
   • 関数ポインタ型を定義
   • g_fn_set_<type> グローバル追加
   • debugini で GetProcAddress 解決
   • handle_command("set_var"/"evaluate") で HSPVAR_FLAG を見て dispatch
3. HSPVAR_FLAG 定数を hsp3debug_dap.cpp の enum に追加

新しいセマンティックトークンカテゴリ

1. LspServer.cs の TokenTypes 配列に追加 (順序 = ABI)
2. 対応する TYPE_<X> 定数追加
3. ClassifyIdentifier にロジック追加
4. extension.js の SemanticTokensLegend を同じ順に揃える

新しい DAP イベント/コマンド

1. DLL の handle_command に case 追加 or debug_notice で evt 送信
2. adapter の DapSession.HandleRequest に case 追加
3. adapter の DebuggeeBridge.SendRequest で同期往復
4. 必要なら VS Code capabilities を Initialize で true に