1.4 Implement the context service and when-clause evaluator

[goofmint]

Part of Phase 1 — Core skeleton (tasks.md Task 1.4).

Summary

Implement tecode.context (flat context map) and the when-clause parser/evaluator used by keybindings and command visibility.

Details

• Context service: set(key, value) / get(key) over a flat Map<string, unknown> with a change event.
• Recursive-descent parser for the MVP grammar (design.md §6.4):

  expr := or
  or := and ("||" and)*
  and := unary ("&&" unary)*
  unary := "!" unary | primary
  primary:= key | key "==" value | "(" expr ")"
  

• Clauses parse once into a cached AST at registration; evaluation runs per lookup.
• Unknown context keys evaluate to undefined (falsy). Malformed clauses fail at parse time with a clear error (binding is skipped and reported, not crashing).

Completion requirements

• Table-driven tests cover: bare keys, == string comparison (editorLangId == 'ts'), !, &&/|| precedence, parentheses, unknown keys falsy, malformed input
• AST caching verified (parse called once per clause)
• Context change event fires on set with changed key
• bun test and lint pass

References

• requirements.md: Req 4.5, 4.6
• design.md: §6.4

Dependencies

Blocked by: 1.2 (#3). Parallelizable with 1.3, 1.5–1.10.

[goofmint]

@coderabbitai make plan in Japanese

---

Generated by Claude Code

[coderabbitai]

Coding Plan

Summary

when句評価器をpackages/core/src/keymap/when.tsに、コンテキストサービスをpackages/core/src/keymap/context.tsに実装する。design.md §6.4とkeymapディレクトリの役割に合わせる。

compileWhenが句を一度だけ解析してASTを返す設計により、AST再利用（キャッシュ）を保証する。評価はget(key)だけに依存し、コンテキストサービスと疎結合にする。

公開API型ContextNamespaceは変更しない。内部ContextServiceが@tecode/apiのEvent<T>規約でonDidChangeを提供する。

不正な句は解析時に専用エラーで報告し、クラッシュさせない。バインディングのスキップは下流の消費者（Task 1.5）に委ねる。bun:testのテーブル駆動テストとspyOnで全完了条件を検証する。

Design Choices

Design Choice 1: コンテキストサービスのファイル配置をどこにするか

Options Considered:

1. packages/core/src/keymap/context.tsに配置する。when評価器と同じモジュールにまとめる。
2. packages/core/src/context/という新規ディレクトリを作る。
3. packages/core/src/keymap/index.tsに直接実装する。

Chosen Option: 1

Rationale: design.md §2のkeymapディレクトリ説明とTask 1.4のまとめ方に一致し、新規ディレクトリの追加を避けられる。design.mdはコンテキストサービスに専用パスを与えていない。core/keymap/のディレクトリ説明が「when-clause evaluator」を含むため、keymapモジュール配下が自然である。

Design Choice 2: コンテキストの変更イベントを公開APIにどう表現するか

Options Considered:

1. 内部のContextServiceクラスがonDidChangeをEvent<T>パターンで公開する。公開ContextNamespaceにはset/getだけを射影する。
2. packages/apiのContextNamespaceにonDidChangeを追加する。

Chosen Option: 1

Rationale: 公開API型の変更を避け、内部実装だけが変更イベントを持つ。既存のConfigNamespace.onDidChangeと同じEvent<T>規約に従う。ContextNamespaceはset/getのみを持ち、onDidChangeを宣言していない。しかしチケットは変更イベントを要求する。

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: when句のパーサと評価器

このフェーズはwhen句の字句解析、構文解析、AST評価を実装する。文法はdesign.md §6.4に従う。登録時に一度だけ解析し、ルックアップごとに評価する。不正な句は解析時に明確なエラーを出す。

Task 1: AST型とトークナイザを定義する

when句のトークンとAST節点の型を定義する。

• packages/core/src/keymap/when.tsを新規作成する。
• トークン種別を定義する。対象は識別子（コンテキストキー）、文字列リテラル（'ts'など）、演算子==、&&、||、!、括弧(、)である。
• 判別可能ユニオンでAST節点型を定義する。節点は「キー参照」「等価比較（キーと文字列値）」「否定」「論理積」「論理和」を表す。
• 値フィールドはunknownを使う。anyを使わない。
• トークナイザは入力文字列を走査し、空白を無視し、トークン配列を返す。認識できない文字は明確なエラーで報告する。

Task 2: 再帰下降パーサを実装する

文法に従いトークン列をASTへ変換する。演算子優先順位を守る。

• packages/core/src/keymap/when.tsにパーサを追加する。
• 文法の各生成規則に対応する関数を実装する。or（||）、and（&&）、unary（!）、primary（キー / key == value / 括弧式）。
• noUncheckedIndexedAccessが無効なため、トークン配列の位置参照は手動で境界を確認する。または末尾にEOFトークン番兵を置く。
• 解析後にトークンが残る場合、または必要なトークンが無い場合は、明確なメッセージを持つ専用のエラー型（例: WhenParseError）を投げる。
• エラーメッセージには問題の内容と対象の句を含める。呼び出し側（Task 1.5のバインディングテーブル）がこのエラーを捕捉し、バインディングをスキップして報告する。このタスクはクラッシュせず明確なエラーを投げることまでを担当する。

Task 3: 評価器とコンパイル（キャッシュ）ヘルパを実装する

ASTをコンテキストに対して評価する。句を一度だけ解析するコンパイル関数を提供する。

• packages/core/src/keymap/when.tsに評価器を追加する。
• 公開するcompileWhen(clause: string)は、句を一度だけ解析してAST（またはASTを保持する評価関数）を返す。これによりASTキャッシュが設計上保証される。
• 評価は、キー参照が真偽値（値が真値か）を返し、等価比較が文字列値と一致するかを返し、! / && / ||を論理的に評価する。
• 未知のコンテキストキーはundefinedに解決し、偽として扱う。キー欠落で例外を投げない。
• 評価器はコンテキストの読み取りインタフェース（get(key)）だけに依存する。Task 1.4のコンテキストサービスと疎結合にする。

Task 4: when句のテーブル駆動テストを追加する

文法とキャッシュ動作を検証する。

• packages/core/src/keymap/when.test.tsを新規作成する。bun:testを使う。
• テーブル駆動で次を検証する。ベアキー、editorLangId == 'ts'の文字列比較、!、&&と||の優先順位、括弧、未知キーが偽になること、不正入力がエラーになること。
• ASTキャッシュを検証する。spyOnまたはmockで内部の解析処理を監視し、同じコンパイル済み句を複数回評価しても解析は一度だけ呼ばれることをtoHaveBeenCalledTimes(1)で確認する。
• 不正な句が明確なエラーを投げ、プロセスをクラッシュさせないことを確認する。

🤖 Prompt for AI agents

`when`句の字句解析、構文解析、AST評価を`packages/core/src/keymap/when.ts`に実装する。文法はdesign.md
§6.4に従う。句は登録時に一度だけ解析し、ルックアップごとに評価する。不正な句は解析時に明確なエラーで報告する。

手順:
-
トークン種別（識別子、文字列リテラル、`==`、`&&`、`||`、`!`、`(`、`)`）とAST節点の判別可能ユニオン型（キー参照、等価比較、否定、論理積、論理和）を定義する。値フィールドには`unknown`を使い、`any`は使わない。
- 空白を無視し、認識できない文字を明確なエラーで報告するトークナイザを実装する。
- 演算子優先順位（`or` > `and` > `unary` >
`primary`）に従う再帰下降パーサを実装する。`noUncheckedIndexedAccess`が無効なため、トークン配列の境界を手動で確認するか、EOFトークン番兵を使う。解析エラーは専用のエラー型（例:
`WhenParseError`）で、問題内容と対象の句を含むメッセージとともに投げる。呼び出し側がこのエラーを捕捉できるようにする。
- 句を一度だけ解析してASTを返す`compileWhen(clause:
string)`を実装し、AST再利用を保証する。評価器は`get(key)`インタフェースのみに依存させ、キー参照は真偽値評価、等価比較は文字列値の一致判定、`!`
/ `&&` / `||`は論理演算とする。未知キーは`undefined`として偽扱いにし、例外を投げない。
-
`packages/core/src/keymap/when.test.ts`に`bun:test`でテーブル駆動テストを追加する。ベアキー、文字列比較、否定、優先順位、括弧、未知キー、不正入力のエラーを検証する。`spyOn`または`mock`で解析処理が一度だけ呼ばれること（`toHaveBeenCalledTimes(1)`）を確認し、キャッシュ動作を検証する。

Phase 2: コンテキストサービス

このフェーズはフラットなコンテキストマップと変更イベントを実装する。ContextNamespaceのset/get契約を満たす。

Task 1: ContextServiceクラスを実装する

Map<string, unknown>上にset/getと変更イベントを実装する。

• packages/core/src/keymap/context.tsを新規作成する。
• 内部にMap<string, unknown>を持つContextServiceクラスを実装する。
• set(key, value)とget<T = unknown>(key): T | undefinedを実装する。ContextNamespaceの型契約に一致させる。
• @tecode/apiのEvent<T> / Listener<T> / DisposableパターンでonDidChangeを実装する。既存のConfigNamespace.onDidChangeと同じ規約に従う。
• setが値を変更したとき、変更されたキーを含むイベントを発火する。リスナ登録はDisposableを返す。
• 公開API向けにはset/getだけを射影する薄いオブジェクトを別途提供できる形にする。onDidChangeは内部利用（フォーカス追跡やパレット）向けとする。

Task 2: モジュールのエクスポートを整える

新しいコンテキストとwhenの成果物を公開する。

• packages/core/src/keymap/index.tsのプレースホルダを更新する。when.tsとcontext.tsの公開シンボル（compileWhen、AST/エラー型、ContextService）を再エクスポートする。
• 既存のKEYMAP_PLACEHOLDERへの依存を壊さないよう、packages/core/src/index.tsのバレル再エクスポートを確認して必要なら調整する。

Task 3: コンテキストサービスのテストを追加する

set/getと変更イベントを検証する。

• packages/core/src/keymap/context.test.tsを新規作成する。bun:testを使う。
• set後にgetが正しい値を返すことを確認する。
• 未設定キーでgetがundefinedを返すことを確認する。
• setが変更イベントを発火し、イベントが変更されたキーを含むことを確認する。
• onDidChangeが返すDisposableでdispose後にリスナが呼ばれないことを確認する。

🤖 Prompt for AI agents

フラットなコンテキストマップと変更イベントを`packages/core/src/keymap/context.ts`に実装する。`ContextNamespace`の`set`/`get`契約を満たす。

手順:
- 内部に`Map<string, unknown>`を持つ`ContextService`クラスを実装する。`set(key, value)`と`get<T
= unknown>(key): T | undefined`を`ContextNamespace`の型契約に一致させて実装する。
- `@tecode/api`の`Event<T>` / `Listener<T>` /
`Disposable`パターンで`onDidChange`を実装し、既存の`ConfigNamespace.onDidChange`と同じ規約に従う。`set`が値を変更したとき、変更されたキーを含むイベントを発火する。リスナ登録は`Disposable`を返す。
-
公開API向けには`set`/`get`だけを射影する薄いオブジェクトを別途提供できるようにする。`onDidChange`は内部利用（フォーカス追跡やパレット）向けとする。
-
`packages/core/src/keymap/index.ts`のプレースホルダを更新し、`when.ts`と`context.ts`の公開シンボル（`compileWhen`、AST/エラー型、`ContextService`）を再エクスポートする。既存の`KEYMAP_PLACEHOLDER`への依存を壊さないよう、`packages/core/src/index.ts`のバレル再エクスポートを確認し、必要なら調整する。
-
`packages/core/src/keymap/context.test.ts`に`bun:test`でテストを追加する。`set`後に`get`が正しい値を返すこと、未設定キーで`get`が`undefined`を返すこと、`set`が変更されたキーを含む変更イベントを発火すること、`onDidChange`が返す`Disposable`で`dispose`後にリスナが呼ばれないことを検証する。

Research

このリポジトリはBunワークスペースのモノレポである。公開APIは@tecode/apiにある。

packages/api/src/namespaces.tsはContextNamespace（set(key, value) / get<T>(key)）を既に型定義している。

packages/api/src/manifest.tsはCommandMeta.when?とKeybindingContribution.when?を定義する。

packages/api/src/primitives.tsはEvent<T> / Listener<T> / Disposableの変更イベント規約を定義する。

packages/core/srcの各モジュール（keymap、commands、configなど）は現在すべてプレースホルダのスタブである。設計上、when句評価器はcore/keymap/when.tsに置く（design.md §6.4）。コンテキストサービスの配置は明示されていない。

テストはbun:testを使う。TypeScriptはstrict: trueだがnoUncheckedIndexedAccessは無効である。値はanyではなくunknownを使う。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

`when`句の字句解析、構文解析、AST評価を`packages/core/src/keymap/when.ts`に実装する。文法はdesign.md
§6.4に従う。句は登録時に一度だけ解析し、ルックアップごとに評価する。不正な句は解析時に明確なエラーで報告する。

手順:
-
トークン種別（識別子、文字列リテラル、`==`、`&&`、`||`、`!`、`(`、`)`）とAST節点の判別可能ユニオン型（キー参照、等価比較、否定、論理積、論理和）を定義する。値フィールドには`unknown`を使い、`any`は使わない。
- 空白を無視し、認識できない文字を明確なエラーで報告するトークナイザを実装する。
- 演算子優先順位（`or` > `and` > `unary` >
`primary`）に従う再帰下降パーサを実装する。`noUncheckedIndexedAccess`が無効なため、トークン配列の境界を手動で確認するか、EOFトークン番兵を使う。解析エラーは専用のエラー型（例:
`WhenParseError`）で、問題内容と対象の句を含むメッセージとともに投げる。呼び出し側がこのエラーを捕捉できるようにする。
- 句を一度だけ解析してASTを返す`compileWhen(clause:
string)`を実装し、AST再利用を保証する。評価器は`get(key)`インタフェースのみに依存させ、キー参照は真偽値評価、等価比較は文字列値の一致判定、`!`
/ `&&` / `||`は論理演算とする。未知キーは`undefined`として偽扱いにし、例外を投げない。
-
`packages/core/src/keymap/when.test.ts`に`bun:test`でテーブル駆動テストを追加する。ベアキー、文字列比較、否定、優先順位、括弧、未知キー、不正入力のエラーを検証する。`spyOn`または`mock`で解析処理が一度だけ呼ばれること（`toHaveBeenCalledTimes(1)`）を確認し、キャッシュ動作を検証する。
===============================================================================

Task: 2

フラットなコンテキストマップと変更イベントを`packages/core/src/keymap/context.ts`に実装する。`ContextNamespace`の`set`/`get`契約を満たす。

手順:
- 内部に`Map<string, unknown>`を持つ`ContextService`クラスを実装する。`set(key, value)`と`get<T
= unknown>(key): T | undefined`を`ContextNamespace`の型契約に一致させて実装する。
- `@tecode/api`の`Event<T>` / `Listener<T>` /
`Disposable`パターンで`onDidChange`を実装し、既存の`ConfigNamespace.onDidChange`と同じ規約に従う。`set`が値を変更したとき、変更されたキーを含むイベントを発火する。リスナ登録は`Disposable`を返す。
-
公開API向けには`set`/`get`だけを射影する薄いオブジェクトを別途提供できるようにする。`onDidChange`は内部利用（フォーカス追跡やパレット）向けとする。
-
`packages/core/src/keymap/index.ts`のプレースホルダを更新し、`when.ts`と`context.ts`の公開シンボル（`compileWhen`、AST/エラー型、`ContextService`）を再エクスポートする。既存の`KEYMAP_PLACEHOLDER`への依存を壊さないよう、`packages/core/src/index.ts`のバレル再エクスポートを確認し、必要なら調整する。
-
`packages/core/src/keymap/context.test.ts`に`bun:test`でテストを追加する。`set`後に`get`が正しい値を返すこと、未設定キーで`get`が`undefined`を返すこと、`set`が変更されたキーを含む変更イベントを発火すること、`onDidChange`が返す`Disposable`で`dispose`後にリスナが呼ばれないことを検証する。

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---