typeprobe

typeprobe

typeprobe は TypeScript コンパイラーに推論内容（型、補完、型エラー）を問い合わせるため、AI コーディングエージェントやテストが推測する必要はありません。次の形で利用できます。

• コーディングエージェント（Claude Code、Codex、Cursor、VS Code、Gemini CLI、あらゆる stdio クライアント）向けの MCP サーバー
• 推論された型を文字列として返す typeprobe/testing。スナップショットテストで利用できます
• CLI と同期ライブラリー API

typeprobe は 4.0.0 まで prinfer という名前でした。prinfer からの移行をご覧ください。

クイックスタート

エージェントにコンパイラーを使わせます。

npx -y typeprobe setup claude    # or codex, cursor, vscode, gemini; see Install

エージェントは hover_by_name(file: "src/utils.ts", name: "names") を呼び出して Type: string[] を取得したり、編集後に diagnostics(file) を呼び出したりできるようになります。

API の型推論結果をテスト（Vitest、Jest、Bun、またはスナップショットを扱える任意のテストランナー）で固定します。

import { expect, test } from "vitest"; // or "bun:test"
import { inferredType } from "typeprobe/testing";
import { groupBy, type User } from "../src/users";

const users: User[] = [{ name: "Ada", role: "admin" }];
const byRole = groupBy(users, (user) => user.role);

test("groupBy keys the result by the callback's return type", () => {
  expect(inferredType(import.meta.url, { name: "byRole" }))
    .toMatchInlineSnapshot(`"Record<Role, User[]>"`);
});

マッチャーを空のまま（toMatchInlineSnapshot()）記述すると、テストランナーが値を埋めます。リファクタリングで型が変わると、テストが失敗します。

インストール

すべてのコマンドは npx 経由で実行されるため、事前にインストールする必要はありません。npm i -g typeprobe の実行後は、npx -y のプレフィックスを省略できます。その後のセットアップでは typeprobe-mcp バイナリーが登録され、起動のたびに npx が行うパッケージ確認をスキップできます。

Claude Code。 プラグインには MCP サーバーと、Claude がいつ使うべきかを伝えるスキルが同梱されています。

/plugin marketplace add clockblocker/typeprobe
/plugin install typeprobe@typeprobe

その他のクライアント、またはプラグインを使わない Claude Code の場合：

クライアント	コマンド	書き込み先
Claude Code	npx -y typeprobe setup claude	claude mcp add。共有 .mcp.json には --scope project
Codex	npx -y typeprobe setup codex	codex mcp add（~/.codex/config.toml）
Cursor	npx -y typeprobe setup cursor	~/.cursor/mcp.json。--scope project の場合：.cursor/mcp.json
VS Code	npx -y typeprobe setup vscode	code --add-mcp。--scope project の場合：.vscode/mcp.json
Gemini CLI	npx -y typeprobe setup gemini	~/.gemini/settings.json。--scope project の場合：.gemini/settings.json

その他の MCP クライアントの場合：typeprobe は npx -y typeprobe mcp で起動する stdio サーバーです。

{
  "mcpServers": {
    "typeprobe": { "command": "npx", "args": ["-y", "typeprobe", "mcp"] }
  }
}

MCP レジストリーでは io.github.clockblocker/typeprobe として、Smitheryにも掲載されています。

セットアップのオプション：

• --print は、適用せずにコマンドや設定の変更内容を表示します。
• --npx は、typeprobe-mcp がインストール済みでも npx -y typeprobe mcp を登録します。クライアントが typeprobe-mcp を見つけられない場合に使用してください。シェルの外から起動したエディターでは、nvm、fnm、volta のパスが見つからないことがよくあります。
• セットアップを再実行すると、typeprobe エントリーのコマンドが更新され、他のサーバーはそのまま残ります。JSON 設定では、env など、エントリーに追加したキーが維持されます。解析できない JSON 設定は変更されず、セットアップによって手動で追加するエントリーが表示されます。
• 名前変更前の prinfer エントリーがある場合、新しいエントリーの隣に残すのではなく置き換えます。claude と codex はそれを削除し、JSON 設定では他のキーを維持したまま、その場で typeprobe に置き換えます（PRINFER_* 環境変数名は TYPEPROBE_* に変更されます）。
• Windows では、クライアントがシェルを介さずにサーバーを起動し、npm の .cmd シムを実行できないため、サーバーは cmd /c npx -y typeprobe mcp（または cmd /c typeprobe-mcp）として登録されます。

エージェントに使用タイミングを伝える

ツールの説明だけでは十分ではなく、エージェントは依然として tsc を使ったり、手作業で型注釈を書いたりします。指示ファイルに短い使用ガイダンスを追加してください（Claude Code プラグインには同じガイダンスがスキルとして同梱されています）。

npx -y typeprobe setup agents-md                  # ./AGENTS.md
npx -y typeprobe setup agents-md --file CLAUDE.md

このブロックは と の間に配置します。再実行するとその場で更新され、prinfer が記述したブロック（``）も置き換えられます。

MCP ツール

ツール	用途
hover_by_name	名前付きシンボルの型を調べます。まずはこちらを使ってください。
hover	行上のトークンの型を調べます。コールバックパラメーター、式、繰り返し現れる名前などが対象です。
batch_hover	1 回の呼び出しで、ファイルをまたいで最大 100 件を検索します。
completions	文字列リテラルのユニオンメンバーなど、カーソル位置で TypeScript が提示する候補を調べます。
diagnostics	プロジェクト全体をチェックせずに、1 つのファイルの型エラーを調べます。
annotations	TypeScript が推論するアノテーションを確認します。

共通パラメーター：

• file は絶対パス、またはサーバーの作業ディレクトリからの相対パスです。行番号と列番号は 1 から始まります。
• project は tsconfig.json のパスです。デフォルトでは、ファイルより上の階層にある最も近いものが使われます。
• backend（デフォルトは typescript7、または typescript6）は、ホバーツールと diagnostics で指定します。呼び出しが失敗する場合や、TypeScript 7 で結果が不正に見える場合は、typescript6 で再試行してください。バックエンドとコンパイラーを参照してください。
• ホバーツールでは、include_docs（JSDoc）、include_cost（型コストの上限を参照）、full、max_chars を指定できます。型のテキストは型ごとに 4000 文字までで、途中で切られた型の末尾には、… truncated: 187 chars total, union of 4 members. Pass max_chars: N to see more (0 for no limit). のような行が付きます。full: true を指定すると、TypeScript 独自の省略表示（{ ...; }、... 12 more ...）を無効にし、すべてのオーバーロードを一覧表示します。構造化コンテンツが切り詰められることはありません。

hover_by_name

hover_by_name(file: "src/utils.ts", name: "names")
hover_by_name(file: "src/utils.ts", name: "names", line: 11)   # line picks among same-named symbols

Type: string[]
Name: names
Kind: const
Position: 11:14

名前が複数回宣言されている場合、検索では宣言が優先され、どの宣言が選択されたかが示されます。Matched line 8 of 2 declarations (also 12); pass line to choose. のように表示されます。構造化された結果では、ほかの宣言が alternatives: [{ line, column, kind }] として一覧表示されます。該当する宣言がない line を指定すると SYMBOL_NOT_FOUND が返され、宣言行が declaredAt に一覧表示されます。if 内の box.value のように、名前が宣言ではなく使用されている行を指定すると、その位置での型が返され、周囲のコードに基づいて絞り込まれます。

オーバーロードされた関数では、最初のシグネチャに続いて最大 3 つが表示されます（full: true ではすべてが表示され、構造化された overloads には常にすべてが含まれます）。

Type: (value: string): number (+1 overload)
Overloads:
  (value: number): string
Returns: number
Name: parse
Kind: function
Position: 1:17

hover

行からコピーした text を渡すと、typeprobe が列を特定します。識別子全体が最初に照合されます。たとえば、users.map((user) => user.name) では、text: "user" は users を飛ばしてコールバックパラメーターに一致し、occurrence: 2 を指定すると次の user が選択されます。行に識別子全体の一致がない場合に限り、text は部分文字列として照合されます。column は text の代わりに使用できます。ジェネリック関数の呼び出しでは、エディターと同様に、インスタンス化された型が表示されます。

hover(file: "src/utils.ts", line: 11, text: "user")

Type: { id: number; name: string; }
Name: user
Kind: parameter
Position: 11:33
Target: "user" at 11:33

指定したテキストが行にない場合、エラーにはその行が引用されます。

Error [SYMBOL_NOT_FOUND]: Text "nope" not found on line 11 of /project/src/utils.ts
Nearby identifiers: name, names, map, user, users
Suggestion: Line 11 reads: "export const names = users.map((user) => user.name);". Copy text exactly from it, or give a column instead.

batch_hover

各項目は {name, line?}、{line, text, occurrence?}、または {line, column} です。省略可能な file を指定すると、共有のトップレベル file が上書きされます。ファイルが見つからない場合も含め、失敗は項目ごとに処理されるため、1 件の検索に失敗しても残りの結果は失われません。

batch_hover(file: "src/utils.ts", positions: [
  {name: "users"},
  {line: 11, text: "user"},
  {file: "src/missing.ts", line: 1, column: 1}
])

Batch hover results: 2 succeeded, 1 failed

--- src/utils.ts:users:6 ---
Type: { id: number; name: string; }[]
...

--- src/missing.ts:1:1 ---
Error [FILE_NOT_FOUND]: File not found: /project/src/missing.ts
Suggestion: Check the path. Relative paths resolve against the MCP server's working directory (/project); pass an absolute path to be sure.

ファイルの範囲外の行または列を指定すると、有効な範囲を示す INVALID_ARGUMENT エラーが返されます。

ホバー結果

すべてのホバーは、すべてのバックエンドとサーフェスで同じフィールドを返します。

• signature：型のテキストのみを1行で返します。エディターのホバーに表示される宣言キーワードや名前は含みません。変数の場合は string[]、関数の場合は (value: string): number、呼び出しの場合はインスタンス化されたシグネチャです。型エイリアスでは名前と型パラメーターが保持されます（type Event = { kind: "open"; ... } | ...）。インターフェースとクラスの場合は名前が返されます（Box<T>）。オプションのメンバーは、宣言内で tsc が記述する形式で返されます。つまり digits?: number となり、| undefined が付くのは、ソースに記述されている場合、または型が注釈の型ではない場合（インスタンス化されたジェネリックや Partial<T>）のみです。
• display：エディターのホバーテキストです（const names: string[]）。これを報告するのは TypeScript 7 言語サーバーのみです。
• kind：エディターのラベル（function、method、const、parameter、property、type、interface、class、enum など）に加え、呼び出しの呼び出し対象には call が付きます。
• 該当する場合は returnType、documentation、overloads、unionMembers、alternatives。
• include_cost: true の場合の cost：{ instantiations, types }。
• compiler：回答したコンパイラーの { name, version, source }。

補完

カーソルは column の文字の直前にあります。文字列のユニオン型では、開始引用符のすぐ内側に置いてください。

completions(file: "src/utils.ts", line: 14, column: 30)
completions(file: "src/utils.ts", line: 20, column: 1, prefix: "use", limit: 20)

エントリーは TypeScript のランキング順で並びます。最初にローカル、メンバー、リテラル値が続き、次にグローバル（同じランクのほかのエントリーの後にキーワード）、最後に自動インポートが並びます。返される数は最大 limit 件です（デフォルトは 50、最大 500）。一致するものがさらにある場合、テキストの末尾に … 947 more; pass prefix to narrow, or raise limit と表示され、構造化された結果には total と truncated: true が含まれます。

prefix を指定すると、大文字と小文字を区別せず、その文字列で始まる名前だけが残ります。指定しない場合は、カーソルの左側に入力したテキストで、エディターと同じようにリストが絞り込まれます（useSt 内の use の後では、use… の名前のみ）。prefix: "" にすると、この絞り込みは無効になります。任意のキーを受け付けるオブジェクトリテラルのキー（Record<string, number>）では、typeprobe はすべてのグローバルを返す代わりに、エントリーを返さず、その旨を示す note を返します。completions は常に TypeScript 6 で実行されます。

診断

編集した各ファイルで実行してください。エラーが報告されなくなれば、編集は完了です。

diagnostics(file: "src/utils.ts")
diagnostics(file: "src/utils.ts", include_suggestions: true)   # also TS6133 unused variables etc.

src/utils.ts:16:14 error TS2322: Type 'string' is not assignable to type 'number'.
1 error, 0 warnings.

問題のないファイルでは No type errors. が返されます。

注釈

annotations(file: "src/utils.ts")

src/utils.ts:2:55 redundant return type of format: declared string, inferred string (exported)
src/utils.ts:14:19 widening drink: declared Drink, inferred "tea" (exported)
2 redundant, 2 widening (5 annotations checked).
redundant: delete the annotation; the type stays the same.
widening: the annotation is wider than the inferred type; keep it if the wider type is intended.

redundant の注釈は、型を変更せずに削除できます。widening の注釈は意図的な場合が多いため（後から任意の Drink を受け入れる必要がある変数や、エクスポートされたコントラクトなど）、要確認として扱ってください。初期値または推論対象となる本体を持つ注釈のみがチェックされます。構造化された各検出結果には、: Type テキストの範囲、declared、inferred、exported、suggestion が含まれます。annotations は常に TypeScript 6 で実行されます。

エラー

すべてのツールは、テキストと構造化コンテンツ（{ version: 1, ok: true, result } または { version: 1, ok: false, error }）を返します。多くのクライアントではモデルにテキストしか表示されないため、失敗時のテキストにはコード、メッセージ、復旧のヒントが含まれます。

Error [SYMBOL_NOT_FOUND]: No symbol named "nmes" at line 11 found in src/utils.ts
Did you mean: names, name?
Suggestion: Check the spelling against candidates, pass line to pick the match on a known line, or call hover with that line and text copied from it.

error には code（INVALID_ARGUMENT、FILE_NOT_FOUND、SYMBOL_NOT_FOUND、TYPESCRIPT_ERROR、INTERNAL_ERROR のいずれか）、message、suggestion、および該当する場合は file、line、column、project、candidates（ファイル内の類似した識別子、または該当行付近の識別子）、declaredAt が含まれます。各ツールの outputSchema は、両方の結果を1つのエンベロープで扱い、エージェントが復旧に使用するエラーフィールドを列挙します。それ以外のフィールドも送信されます。CLI の --json 出力と、エクスポートされた zod スキーマ（hoverSuccessSchema、contractErrorResponseSchema など）でも、同じコントラクトが使用されます。

型テスト

typeprobe/testing はエディターに表示される型を返すため、expectTypeOf や tsd とは異なり、スナップショットを手動で書く必要はありません。また、リテラルのユニオン型が string に拡大する場合も含め、変更はすべて反映されます。意図した変更の後は、ランナーの更新フラグ（vitest -u、bun test --update-snapshots）でスナップショットを更新してください。どちらのバックエンドでも検索ヘルパーは同期的に動作するため、await し忘れる心配はありません。

import { inferredCompletions, inferredType } from "typeprobe/testing";

// Another module: resolve it against the test file.
expect(inferredType(new URL("../src/users.ts", import.meta.url), { name: "groupBy" }))
  .toMatchInlineSnapshot(`"<T, K extends PropertyKey>(items: readonly T[], key: (item: T) => K): Record<K, T[]>"`);

// Line 7 of this test file reads: const fallback: Role = "member";
expect(inferredCompletions(import.meta.url, { line: 7, text: '"' }))
  .toMatchInlineSnapshot(`
    [
      "admin",
      "member",
    ]
  `);

ヘルパー	戻り値
inferredType(file, selector)	出力された型（signature）。
inferredTypeInfo(file, selector)	ホバー結果全体：名前、種類、戻り値の型、ドキュメント、コスト。
inferredCompletions(file, selector)	TypeScript 7 で、フィルターや上限なしにカーソル位置に表示されるすべての補完候補名。
inferredTypeCost(file, selector)	{ instantiations, types }。型コストの予算を参照してください。
inferredTypeIssues(file, selector)	読みやすさの問題。読みやすさのチェックを参照してください。
typeReadabilityIssues(text, rules?)	任意の出力された型テキストに含まれる読みやすさの問題。
expectType(file, selector)	テキスト、コスト、読みやすさを一度にチェックします。expectTypeを参照してください。
expectTypes(file, selector)	複数の対象に対するexpectTypeに加え、それらすべてに対する予算を設定します。expectTypesを参照してください。
closeTestingSessions()	TypeScript 7 のコンパイラーを早期に停止します。テストでの TypeScript 7を参照してください。

ファイルには、テストファイル自体のimport.meta.url、またはそれを基準に解決したURLを指定します。通常の文字列パスはprocess.cwd()を基準に解決されます。ファイルは、最も近いtsconfig.jsonまたはprojectを介して読み込まれます。

セレクターで対象を選択します。

• { name, line? }：名前で宣言を指定します。lineを指定すると、同じ名前の宣言から選択できます。
• { line, text, occurrence? }：指定した行でtextが始まるトークンを指定します。hoverツールのtextと同じ方法で照合されます。inferredCompletionsでは、一致箇所の直後にカーソルが置かれるため、text: "user."はメンバーを一覧表示し、text: '"'は文字列リテラルのメンバーを一覧表示します。cursor: "start"を指定すると、一致箇所の前に置かれます。
• { line, column }：1始まりの位置を指定します（補完の場合、カーソルはその列の直前に置かれます）。

オプションは同じオブジェクトに指定します。例：{ name: "byRole", backend: "typescript7" }。3つ目の引数を指定するとエラーになります。

オプション	デフォルト	効果
backend	"typescript6"	"typescript7"を指定すると、TypeScript 7 の出力を表示します。inferredCompletionsは常に TypeScript 7 を使用します。
full	true	falseにすると、エディターの短縮形式（{ ...; }）になります。
sort_unions	false	ユニオンを固定順で出力します。以下を参照してください。
include_docs	false	inferredTypeInfoにdocumentationを追加します。
include_cost	false	inferredTypeInfoにcostを追加します（TypeScript 6 のみ）。
project	最も近いtsconfig.json	ファイルを読み込む際に使用する tsconfig です。
compiler	TYPEPROBE_COMPILER、未設定の場合は"bundled"	使用する TypeScript を指定します。同梱コンパイラーまたはプロジェクトのコンパイラーを参照してください。
timeout	60000	TypeScript 7 の呼び出しがタイムアウトしてエラーを投げるまでにブロックできる時間（ミリ秒）です。
strict	false	不明なキーがあると、最も近い有効なキー名を示してエラーを投げます。テストランナーはテストファイルの型チェックを行わないため、これを指定しないと、camelCase のsortUnionsを指定しても何も起こりません。

検索に失敗すると、修正方法をメッセージに含めてエラーを投げます。不明な名前の場合は、最も近い宣言が一覧表示されます。テキストが見つからない場合は、その行が引用されます。相対パスが見つからない場合は、テストファイルを基準に解決する方法が説明されます。

typeprobe/vitestは、非推奨となったtypeprobe/testingの別名です。

安定したユニオンの順序

TypeScript 6 と TypeScript 7 ではユニオンメンバーの出力順が異なるため（一方は "idle" | "error"、もう一方は "error" | "idle"）、一方のバックエンドで作成したスナップショットはもう一方では失敗します。sort_unions: true を指定すると、どの深さのユニオンも両方のバックエンドで同じ順序で出力されます。メンバーはテキスト順（UTF-16 コード単位順のため、1 | 10 | 2 となります）で並べられ、null と undefined は最後に配置されます。

expect(inferredType(import.meta.url, { name: "status", sort_unions: true }))
  .toMatchInlineSnapshot(`""error" | "idle" | "loading" | null"`);

移動するのはユニオンメンバーだけです。プロパティの順序は依然として異なる場合があります。cond ? { ok: true, value: 1 } : { ok: false, error: "e" } は、TypeScript 6 では { ok: false; error: string; value?: undefined; }、TypeScript 7 では { value?: undefined; ok: false; error: string; } と出力されます。また、キーのユニオンに対するマップ型は、各バックエンドでのユニオンの順序でプロパティを列挙します。ライブラリのホバーオプションと CLI（--sort-unions）でもこのオプションを指定できます。

値がない場合の型

値を持たない引数について関数が推論する型を固定するには、フィクスチャファイルでその引数を宣言します。テストファイル自体に declare const を記述しても実行時の値はないため、テストを実行すると ReferenceError が発生します。

// test/groupBy.fixture.ts, read for types only, never run
import { groupBy, type User } from "../src/users";
declare const input: User[];
export const byName = groupBy(input, (user) => user.name);

// test/users.test.ts
expect(inferredType(new URL("./groupBy.fixture.ts", import.meta.url), { name: "byName" }))
  .toMatchInlineSnapshot(`"Record<string, User[]>"`);

読みやすさのチェック

型が正しくても、読者が内容を読み解かなければならない形式で出力されることがあります。inferredTypeIssues(file, selector) は、対象の出力された型の中で該当する箇所を返します（空の配列は該当なし）。typeReadabilityIssues(text, rules?) は任意の型テキストをチェックします。デフォルトのルールは次のとおりです。

• utility-type：型引数を持つ未解決のユーティリティ型。深さは問いません。対象は Omit、Pick、Partial、Required、Readonly、Exclude、Extract、NonNullable、ReturnType、Parameters、ConstructorParameters、InstanceType、Awaited、ThisParameterType、OmitThisParameter です（DEFAULT_UTILITY_TYPES としてエクスポートされます）。ネストしたものは最も外側だけが報告されます。出力されたシグネチャの型パラメーターに対するもの（<T>(value: T) => Omit<T, "id"> の Omit<T, "id"> など）は報告されません。T が判明するまでは解決できないためです。Record、Promise、Array、その他のジェネリック型はフラグの対象になりません。
• object-intersection：User & { id: string; } やマップ型など、オブジェクト型との交差型です。リテラルの候補を保持する string & {} はフラグの対象になりません。
• truncation：... 3 more ...、{ ...; }、... のプレースホルダー、および長さ制限で途中までになったテキストです。ヘルパーは full: false でない限り、型を省略せずに出力するため、主に full: false や他の場所から取得したテキストが対象になります。

テキストの解析には TypeScript のスキャナーとパーサーを使用するため、"Omit<" や "..." のような文字列リテラル型はフラグの対象になりません。レストパラメーターやスプレッドタプルも同様です。各問題は { rule, text, offset, message } です。省略マーカーを取り除いても解析できないテキスト（長さ制限で途中までになったもの）では、truncation の問題だけが返されます。

rules には utilityTypes（フラグの対象とする名前。例：[...DEFAULT_UTILITY_TYPES, "DeepPartial"]、または false）、objectIntersections と truncation（false にすると無効になります）、および出力されたままでも問題のない断片を指定する allow を指定します。

expect(
  inferredTypeIssues(import.meta.url, { name: "userId", rules: { allow: ['string & { readonly __brand: "UserId"; }'] } }),
).toEqual([]);

型コストの予算

inferredTypeCost は、ある型に対して TypeScript が行う処理量をカウントするため、高コストな型のコストがさらに増えるのをテストで防げます。

import { inferredTypeCost } from "typeprobe/testing";

test("userSchema stays cheap to infer", () => {
  expect(inferredTypeCost(import.meta.url, { name: "userSchema" }).instantiations)
    .toBeLessThan(5_000);
});

{ instantiations, types } を返します。これは、型のインスタンス化数（tsc --extendedDiagnostics が Instantiations として報告する値）と、ターゲットを解決して省略されていない型を書き出す際に、新しい TypeScript 6 チェッカーが作成する型の数です。カウントごとに新しいチェッカーを使うため、数値は実行ごと、プロセスごと、テスト順ごと、表示オプションごとに変わりません。変わるのはコード、コンパイラーオプション、TypeScript のバージョンだけです。カウントには、compiler: "project" を渡さない限り、typeprobe に同梱された TypeScript 6 を使います。どちらを使う場合も、型の予算を設定するプロジェクトではそのバージョンを固定してください。コストの非列挙プロパティ compiler は、カウントに使ったコンパイラーを示します。同じ実行でも数倍の時間差が生じるため、typeprobe は実時間を報告しません。

カウントの対象は、ターゲットの型に必要な処理です。const x = expr では expr の型チェック、戻り値の型注釈がない関数では戻り値の型の推論が対象です。型が依存しないコードはカウントされません。たとえば、型注釈のある初期化子（const x: T = expr）では、型は T から取得されます。式をカウントするには、{ line, text } を使って式をターゲットにしてください。

1 つのファイル内の複数のターゲットをカウントするには、名前を指定したレコードには names を、順番に並んだ配列には（オプションを含まない任意のセレクター形式の）targets を渡します。これらと並べて指定できるのは project、compiler、strict だけです。strict: true の場合、バッチでは full などの表示オプションは拒否されます。

const costs = inferredTypeCost(import.meta.url, { names: ["userSchema", "orderSchema"] });
expect(costs.userSchema.instantiations).toBeLessThan(5_000);

const [first, second] = inferredTypeCost(import.meta.url, {
  targets: [{ name: "userSchema" }, { line: 12, text: "parse(" }],
});

バッチでのカウント結果は、単独で呼び出した場合とまったく同じです。共有されるのは読み込みです。1 つのプロセス内では、プロジェクトのファイルはコンパイラーごとに 1 回だけ解析されます。そのため、別のファイルをカウントする際の追加時間は約 300 ms ではなく 30〜70 ms です（typeprobe 自体のリポジトリの場合）。変更されていないターゲットは 1 回だけカウントされます。カウント自体は共有されません。インスタンス化に 80,000 回かかる型のカウントには、約 250 ms かかります。bun test はすべてのテストファイルを 1 つのプロセスで実行するため、プロジェクトの読み込みは 1 回だけです。Vitest のデフォルトの分離設定では、テストファイルごとに再度読み込まれます。

TypeScript 7 ではインスタンス化数が公開されないため、コストを取得できるのは TypeScript 6 だけです。backend: "typescript7" を指定すると、inferredTypeCost と include_cost はエラーをスローします。それ以外の場合、include_cost（MCP、ライブラリ）と --cost（CLI）を指定すると、同じ数値がホバー結果に追加されます。

TypeScript 7 で型チェックを行う場合でも、TypeScript 6 のカウントはおおよその目安になります。10 個の単一宣言プロジェクトを対象に、--extendedDiagnostics（TypeScript 7.0.2 では --checkers 1 を指定し、6.0.3 と比較）で測定したところ、7 個ではインスタンス化数が同じで、2 個では差が 2% 以下でした。再帰的なドット区切りパスの型では、TypeScript 7 のほうが 17% 多くカウントされました。コスト順に並べると、宣言はほぼ同じ順序になりました。測定したすべてのケースで、20% の余裕を設けた予算で対応できました。再帰的なキー型やパス型では、さらに余裕を持たせてください。TypeScript 7 との比較には --checkers 1 を指定してください。そうしないと、並列で動作するチェッカーのカウントが合算されます。

expectType

expectTypeは、1回の呼び出しで対象の出力された型、コスト、読みやすさをチェックし、失敗したすべてのチェックを列挙した1つのエラーをスローします。

import { expectType } from "typeprobe/testing";

test("user stays readable and cheap", () => {
  expectType(import.meta.url, {
    name: "user",
    printed: "{ id: string; name: string; }",
    maxInstantiations: 500,
    readable: true,
  });
});

expectType failed 3 checks for "user" at test/users.test.ts:9:14:
- printed: the type differs at character 1.
    expected: { id: string; name: string; }
    actual:   Omit<User, "email">
              ^
- maxInstantiations: 612 instantiations, over the budget of 500 by 112 (counted and printed on typescript 6.0.3, bundled).
- readable: 1 readability issue:
    utility-type: Omit<User, "email"> is unresolved: TypeScript printed Omit<...> instead of the type it produces.

セレクターはinferredTypeのセレクターに加え、少なくとも1つのチェックが必要です。

• printed：同じセレクターに対してinferredTypeが返すテキストそのものです（backend、compiler、sort_unions、fullが適用されます）。
• maxInstantiations、maxTypes：コストの上限です。backend: "typescript7"の場合でも、コストは常にTypeScript 6でカウントされます。backendはテキストの取得元だけを選択します。backend: "typescript7"かつcompiler: "project"の場合、プロジェクトにTypeScript 6があればそれが使われ、なければバンドル版が使われます。
• readable：デフォルトの読みやすさルールを使う場合はtrue、またはルールオブジェクトを指定します。

costCompiler（"bundled"、"project"、"auto"のいずれか。デフォルトはcompilerの値）は、コストをカウントするTypeScript 6を選択します。そのため、テキストとコストの取得元が異なる場合があります。たとえば、{ backend: "typescript7", costCompiler: "project" }では、バンドル版のTypeScript 7で出力し、プロジェクトのTypeScript 6でカウントします。上限に達した場合のエラーには、両方のコンパイラーが記載されます。inferredTypeCostはカウントのみを行うため、そこでのcompilerはカウントに使うコンパイラーとなり、costCompilerを指定するとエラーになります。

エラーはTypeExpectationErrorで、failuresにすべての失敗が含まれます。テキストが異なる場合はactualとexpectedも含まれるため、VitestとJestで差分が表示されます。すべてのチェックに合格すると、expectTypeは{ printed, cost? }を返します。

expectTypes

expectTypesは、1つのファイル内の複数の対象に対してexpectTypeを実行し、それらすべてに対する上限を設定して、失敗したすべてのチェックを列挙した1つのエラーをスローします。

expectTypes(import.meta.url, {
  types: [
    { name: "userSchema", maxInstantiations: 3_000 },
    { name: "User", printed: "{ id: string; name: string; }" },
    { name: "orderSchema" },
  ],
  maxInstantiations: 8_000,
  backend: "typescript7",
  costCompiler: "project",
});

グループのmaxInstantiationsとmaxTypesは、すべての対象を解決する新しいTypeScript 6チェッカー1つでカウントされます。そのため、対象間で共有される処理（すべての対象が参照するスキーマなど）は、モジュールの型チェックと同じように1回だけカウントされます。チェッカーのカウントは、型を処理する順序によって数件ほど変わることがあるため、対象は常にソースコードの順序で解決されます。したがって、typesの順序を変えても合計は同じです。各エントリ個別の上限は引き続き個別にカウントされます。グループの上限に達した場合、エラーには各エントリ単独のカウントが列挙され、それらを合計すると全体のカウントを上回ります。

各エントリはexpectTypeのセレクターを受け取り、グループに上限がない場合に限り、個別のチェックが必要です。グループのbackend、full、sort_unions、readable、timeoutは、すべてのエントリのデフォルトになります。合計は1つのプログラムでカウントされるため、project、compiler、costCompilerはグループにのみ指定します。失敗にはエントリのindexが含まれますが、グループの上限には含まれません。戻り値は{ types, cost? }です。各エントリのexpectTypeの結果（グループに上限がある場合は、各エントリ固有のコストを含む）と、グループのコストが含まれます。

テストでのTypeScript 7

TypeScript 7はワーカースレッド内で実行され、プロジェクトごとに1つのコンパイラープロセスを使います。各呼び出しは、コンパイラーが応答するまでブロックします。どちらもテストプロセスを存続させないため、後処理は不要です。

テストランナーのタイムアウトではブロック中の呼び出しを中断できないため、typeprobeには独自のタイムアウトがあります。timeoutミリ秒以内（デフォルトは60000）に応答がない呼び出しはエラーをスローしてそのコンパイラーを停止し、次の呼び出しでは新しいコンパイラーを起動します。コンパイラーがハングしても、実行全体を停止させずに1つのテストだけが失敗します。読み込みに時間がかかるプロジェクトでは、const ts7 = { backend: "typescript7", timeout: 120_000 } as constのような共有セレクターを使い、すべての呼び出しでタイムアウトを延長してください。コンパイラープロセスが終了した場合、実行中の呼び出しは1回だけ再試行されます。

closeTestingSessions()はコンパイラーを早期に停止しますが、呼び出しを省略しても問題ありません。呼び出す場合は、テストファイルごとではなく、最後のテストの後に実行全体で1回だけ呼び出してください。次のTypeScript 7の呼び出しでは新しいコンパイラーが起動し、プロジェクトを再度読み込みます（typeprobeのリポジトリでは約190 ms。ウォーム状態の呼び出しは2 msです）。bun testでは、--preloadファイル（bunfig.tomlのpreload）にafterAll(closeTestingSessions)を記述してください。Vitestでは省略してください。setupFilesはテストファイルごとに実行され、globalSetupはセッションのないプロセスで実行されます。プログラムが読み込み済みのまま保持されるTypeScript 6には影響しません。

CLI

# Type by name, optionally with a line hint
typeprobe src/utils.ts:format
typeprobe src/utils.ts:names:11
typeprobe 'src/store.ts:$store'          # any JavaScript identifier

# Type of a token: text copied from the line, or a column
typeprobe src/utils.ts:11:user
typeprobe src/utils.ts:11 --text user --occurrence 2
typeprobe src/utils.ts:11:33

typeprobe src/utils.ts:format --docs
typeprobe src/utils.ts:largeType --full --max-chars 0
typeprobe src/utils.ts:status --sort-unions
typeprobe src/utils.ts:format --cost
typeprobe src/utils.ts:format -p ./tsconfig.json --compiler project

# Completions: the top 50, filtered by the text left of the cursor
typeprobe complete src/utils.ts:14:30
typeprobe complete src/utils.ts:11:user.  # cursor right after the text
typeprobe complete src/utils.ts:20:1 --prefix use --limit 20

typeprobe check src/utils.ts              # type errors in one file
typeprobe annotations src/utils.ts        # annotations TypeScript would infer anyway

$ typeprobe src/utils.ts:format --docs
(value: number, digits?: number): string
returns: string
name: format
kind: function
docs: Formats a number with a fixed number of digits.

型の検索と check は、--backend typescript7 を渡さない限り TypeScript 6 を使用します。complete と annotations は常に TypeScript 6 を使用します。すべてのオプションについては typeprobe --help を実行してください。

• <file>:<line>:<text> では、行番号の後はすべてテキストとして扱われ、コロンやピリオドも含まれます。数字だけのテキストは列番号として解釈されるため、--text を指定して渡してください。
• 値を取るオプションは --opt value または --opt=value の形式で指定します。不明なオプションや、コマンドが受け付けないオプションを指定するとエラーになります。
• $ を含む引数はシングルクォートで囲んでください。シェルは $store を展開し、zsh は "$F:root" の $F:r を修飾子として解釈します。
• 失敗すると、エラー、Did you mean: …? の候補、提案が標準エラー出力に表示され、終了コード 1 で終了します。check はファイルに型エラーがある場合も終了コード 1 で終了します（警告は対象外です）。annotations は検出内容にかかわらず終了コード 0 で終了します。
• --json はバージョン管理されたコントラクトを標準出力に出力します。出力は上限で切り詰められず、標準エラー出力には何も出力されません。実行の失敗と、ファイルに型エラーがある場合を区別するには、ok を確認してください。

$ typeprobe src/utils.ts:names --json
{"version":1,"ok":true,"result":{"signature":"string[]","line":11,"column":14,"kind":"const","name":"names","compiler":{...}}}

typeprobe mcp は、typeprobe-mcp バイナリと同様に、標準入出力で MCP サーバーを起動します。typeprobe setup については、インストールを参照してください。

ライブラリ API

ライブラリは同期処理で、TypeScript 6 上で実行されます。失敗時には例外をスローします。ほとんどの場合は、typeprobe および typeprobe/testing からエクスポートされる TypeprobeError で、code と suggestion を持ちます。contractError(error) を使うと、捕捉したエラーをコントラクトの形式に変換できます。

import { annotations, batchHover, completions, diagnostics, hover } from "typeprobe";

hover("./src/utils.ts", "format");
// => { signature: "(value: number, digits?: number): string", returnType: "string",
//      line: 2, column: 17, kind: "function", name: "format" }
hover("./src/utils.ts", "names", { line: 11 });          // line hint for repeated names
hover("./src/utils.ts", 11, 33);                         // by position
hover("./src/utils.ts", "format", { include_docs: true, include_cost: true });

// Several positions in one file, one program load; bad positions fail per item
batchHover("./src/utils.ts", [{ line: 11, column: 14 }, { line: 11, column: 33 }]);
// => { items: [...], successCount: 2, errorCount: 0 }

// Every entry, ranked, unless you pass prefix or limit
completions("./src/utils.ts", 14, 30).entries.map((entry) => entry.name);
// => ["coffee", "tea"]

diagnostics("./src/utils.ts", { include_suggestions: false });
// => { file, errorCount: 1, warningCount: 0, diagnostics: [{ line: 16, column: 14, code: 2322, ... }] }

annotations("./src/utils.ts").findings.map((finding) => `${finding.kind} ${finding.name}`);
// => ["redundant format", "widening drink", "redundant label", "widening mode"]

オプションは project、compiler です。ホバーでは、これらに加えて include_docs、include_cost、full、sort_unions を指定できます。

バックエンドとコンパイラ

対象	型の検索	補完	型エラー	アノテーション
MCP サーバー	TS7；backend: "typescript6"	TS6、上位 50 件	TS7；backend: "typescript6"	TS6
CLI	TS6；--backend typescript7	TS6、上位 50 件	TS6；--backend typescript7	TS6
ライブラリ	TS6	TS6、全エントリ	TS6	TS6
typeprobe/testing	TS6；backend: "typescript7"	TS7、すべての名前	なし	なし

typescript7 はネイティブの TypeScript 7 言語サーバーを実行します。プロジェクトごとに 1 つのウォームセッションが起動し、リクエスト間で共有されます。その出力はエディターに表示される内容に最も近いものです（typeprobe/testing は代わりに TypeScript 7 のコンパイラ API を使用します）。typescript6 は TypeScript 6 のコンパイラ API をプロセス内で使用します。型のコストは、どこでも TypeScript 6 を使って計算されます。

TypeScript 7 バックエンドは実験的な機能です。プログラム API やホバーの形式は、今後変更される可能性があります。どちらのバックエンドも、同じ名前に対して同じシンボルを選び、その名前トークンの位置を報告します。また、TypeScript と同じ方法で行数を数えます（CR、LF、CRLF、U+2028、U+2029 は行末として扱われ、先頭の BOM は無視されます）。既知の違いは次のとおりです。

• display を報告するのは言語サーバーだけです。
• 言語サーバーが自動的に選択しない project（最も近い tsconfig.json、またはそれが参照するプロジェクトを使用します）、たとえば参照されていない tsconfig.test.json は、TypeScript 7 API を通じて同じセッションで開かれるため、ホバーに display はありません。その tsconfig には、include、files、またはインポートによって対象ファイルが含まれている必要があります。含まれていない場合、呼び出しは INVALID_ARGUMENT で失敗します。TypeScript 6 は、どのプロジェクトにもファイルを追加します。
• 相対インポートでたどられたファイルへの編集は、すぐに反映されます。diagnostics は tsconfig の include ディレクトリも再スキャンします（範囲には上限があり、node_modules、ビルド出力、ドットディレクトリはスキップされます）。それ以外の、まだ開かれていないファイルへの編集は、ファイルウォッチャーを通じて少し遅れて言語サーバーに反映されます。

バンドル版またはプロジェクトのコンパイラー

デフォルトでは、typeprobe は依存している TypeScript 6 と 7（typescript 6、および typescript 7 のエイリアスである @typescript/native）で出力とカウントを行うため、プロジェクトに何がインストールされていても、どのマシンでも結果は同じです。独自のコンパイラーが推論する内容を取得し、アップグレードに合わせてスナップショットや予算も変わるようにするには、プロジェクトのコンパイラーを使用します。

モード	TypeScript 6 バックエンド	TypeScript 7 バックエンド
bundled（デフォルト）	typeprobe の typescript	typeprobe の @typescript/native
project	プロジェクトの typescript、5.0～6.x	プロジェクトの typescript 7、@typescript/native、または @typescript/native-preview 7.0.0-dev.20260624.1 以降
auto	対応していればプロジェクトのもの、そうでなければバンドル版	対応していればプロジェクトのもの、そうでなければバンドル版

compiler（ライブラリーオプションおよび typeprobe/testing セレクター）、--compiler（CLI）、または TYPEPROBE_COMPILER（MCP サーバーを含むすべてのインターフェース）で設定します。明示的なオプションが優先されます。パッケージは、Node が tsconfig.json のあるディレクトリー（または project のディレクトリー）からインポートを解決する方法で解決されます。TypeScript 7 の場合、typescript 7、@typescript/native、@typescript/native-preview のうち、最も近いパッケージが優先され、同じ階層にある場合はこの順になります。typeprobe は、そのパッケージ独自の API クライアントとコンパイラーのバイナリーを実行します。パッケージマネージャーが typeprobe 自身の typescript と @typescript/native をホイストすると、それらはプロジェクトからも解決される場所に配置されます。そのコピーがプロジェクトのものとして扱われるのは、プロジェクトの最も近い package.json またはそのワークスペースルートがパッケージを宣言している場合に限られ、その場合はバンドル版コンパイラーとして実行・報告されます。

project では、バックエンド用のコンパイラーがプロジェクトにない場合に TYPESCRIPT_ERROR が発生します。また、サポート対象外のコンパイラーがある場合は、パッケージ名、バージョン、パスが示されます。該当するのは、5.0 より前の typescript、TypeScript 6 の出力を要求された typescript 7、または 7.0.0-dev.20260624.1 より古い @typescript/native-preview です。auto はバンドル版コンパイラーにフォールバックし、プロジェクトのコンパイラーがサポート対象外の場合は stderr に警告を 1 回出力します。TypeScript 5.0～5.8 では、一部の型とメッセージが TypeScript 6 とは異なる形式で出力されるため、切り替え時にスナップショットが変わることを想定してください。

各結果には、コンパイラーが compiler: { name, version, source } として記載されます。source は "bundled" または "project" です。ライブラリーおよびテストの結果ではこれは列挙不可のため、コンパイラーだけを変更してもスナップショット、toEqual、JSON.stringify の結果は変わりません。値は直接参照できます（inferredTypeInfo(...).compiler）。CLI の --json 出力と MCP の構造化コンテンツでは result に含まれ、コスト行にも名前が記載されます。例：cost: 412 instantiations, 96 types (typescript 6.0.3, bundled)。

1 つのプロセスで同時に実行できる TypeScript 7 コンパイラーは 1 つです。別のコンパイラーを必要とする呼び出しがあると、実行中の呼び出しが完了するまで待ち、そのセッションを終了してから、別のコンパイラーを起動します。

環境変数

変数	効果
TYPEPROBE_BACKEND=typescript6	MCP サーバーのみ：ホバーツールと diagnostics のデフォルトバックエンドです。明示的な backend 引数、または include_cost が優先されます。
TYPEPROBE_COMPILER=project	すべてのインターフェースで bundled、project、または auto を指定します。上記を参照してください。

prinfer 時代の名前である PRINFER_BACKEND と PRINFER_COMPILER は非推奨ですが、TYPEPROBE_* 変数が設定されていない場合は引き続き読み取られます。

要件

Node.js 20 以降。typeprobe は TypeScript 6 と 7 を独自にバンドルしているため、プロジェクトのコンパイラーを選択しない限り、プロジェクトの typescript のバージョンは関係ありません。TypeScript 7 の呼び出しで必要になった場合にのみ、TypeScript 7 のパッケージが読み込まれます。

prinfer からの移行

prinfer は 4.0.0 で typeprobe に名称変更されました。error.name が "TypeprobeError" になった点を除き、結果、スナップショット、JSON コントラクトに変更はありません。最後の prinfer である 3.5.0 は typeprobe に依存して転送するため（prinfer および prinfer-mcp コマンドと、prinfer、prinfer/testing、prinfer/vitest のインポート）、切り替えるまで既存のセットアップは引き続き動作します。CLI は stderr に 1 行の通知を出力します。MCP サーバーは何も出力しません。

prinfer 3.x	typeprobe 4
npm i -D prinfer	npm rm prinfer && npm i -D typeprobe
import { inferredType } from "prinfer/testing"	import { inferredType } from "typeprobe/testing" （typeprobe、typeprobe/vitest も利用できます）
prinfer、prinfer-mcp、npx -y prinfer mcp	typeprobe、typeprobe-mcp、npx -y typeprobe mcp
MCP サーバー prinfer	MCP サーバー typeprobe：npx -y typeprobe setup <client> を再実行すると、prinfer のエントリが置き換えられます
PRINFER_BACKEND、PRINFER_COMPILER	TYPEPROBE_BACKEND、TYPEPROBE_COMPILER（新しい名前が設定されていない場合は、古い名前も引き続き読み取られます）
エラー名 PrinferError	TypeprobeError（エクスポートされるようになりました）。PrinferError は同じクラスの非推奨エイリアスなので、どちらを使っても instanceof は機能します
Claude Code プラグイン prinfer@prinfer	/plugin uninstall prinfer@prinfer、/plugin marketplace remove prinfer の順に実行し、続けて インストール の 2 つのコマンドを実行します
MCP Registry io.github.clockblocker/prinfer、Smithery clockblocker/prinfer	io.github.clockblocker/typeprobe、clockblocker/typeprobe
AGENTS.md 内の `` block	npx -y typeprobe setup agents-md で置き換えられます

ユーザースコープでの setup vscode は code --add-mcp を経由しますが、このコマンドではサーバーを削除できません。VS Code の MCP リストから古い prinfer サーバーを手動で削除してください。

開発

bun install
bun run ci    # typecheck, build, biome check, tests

このリポジトリは TypeScript 7 で型チェックします（bun run typecheck）。宣言ファイルのバンドルには TypeScript 6 を使用します。

ユーザー向けの変更には changeset を追加してください（bun run changeset）。リリースするには、bun run version を実行します（changeset を適用し、バージョンを server.json、プラグインマニフェスト、MCPB マニフェストにコピーします）。その後コミットし、手動で公開してください。bun run release は npm に公開し、bun run mcpb は Smithery 用のバンドルをパッケージ化します。

名称変更の公開（typeprobe 4.0.0 と prinfer 3.5.0）

shim/prinfer/ は prinfer の最終リリースです。プレーンな JavaScript で、ビルドは不要であり、typeprobe のパッケージには含まれません。typeprobe@^4.0.0 に依存しているため、typeprobe 4.0.0 が npm に公開された後にのみ公開してください。

1. 通常どおり typeprobe をリリースします。bun run version を実行し、chore: release typeprobe 4.0.0 をコミットしてから、bun run release（npm）を実行し、v4.0.0 タグを付けます。npx -y [email protected] --version で確認してください。
2. shim を公開します。bun run shim:pack を実行し（prinfer-3.5.0.tgz が生成されます）、続けて npm publish prinfer-3.5.0.tgz を実行します。通知と 4.0.0 が出力されることを npx -y [email protected] --version で確認してください。
3. shim を含むすべての prinfer バージョンを非推奨にし、各インストールが typeprobe を参照するようにします（shim は引き続き動作します）。

   npm deprecate prinfer "prinfer is now typeprobe: npm i -D typeprobe. Migration guide: https://github.com/clockblocker/typeprobe#migrating-from-prinfer"
   

4. MCP Registry：mcp-publisher login github、mcp-publisher publish の順に実行します（io.github.clockblocker/typeprobe が登録されます。レジストリはこれを typeprobe の package.json にある mcpName と照合します）。その後、古い名前を非推奨にします。

   mcp-publisher status --status deprecated --all-versions \
     --message "Renamed to io.github.clockblocker/typeprobe (npm: typeprobe)" \
     io.github.clockblocker/prinfer
   

5. Smithery：bun run mcpb を実行し、続けて npx -y [email protected] mcp publish ./typeprobe.mcpb -n clockblocker/typeprobe を実行します（SMITHERY_API_KEY が必要です）。Smithery の設定で、古い clockblocker/prinfer の掲載を新しい掲載にリンクするか、掲載を取り下げてください。

ライセンス

MIT