属性制約向けの意味ベースASTと可読表示を追加

.agents/skills/python-coding-style/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: python-coding-style
+description: Pythonコードを作成・修正するときに使用。
+---
+
+# 全般
+* できるだけ型ヒントを付ける。
+    * できるだけ汎用的な型ヒントをつける。たとえばlistでもsetでも良いならば、`Collection`や`Iterable`を使う。
+    * 特に理由がない限り、`object`や`Any`は避ける。
+* docstring は Google スタイルで記述する。
+* ログメッセージやコメントは日本語で記述する
+* 戻り値をtupleで返そうとする場合は、`NamedTuple`, `dataclass`, pydantic modelの使用を検討して、本当にtupleが適切かどうかを判断する。
+* モジュールレベルの定数、クラス属性、インスタンス属性などには直後に docstring として記述する。VSCodeのtooltipに表示させるため。
+* dictから値を取得する際、必須なキーならばブラケット記法を使う。キーが必須がどうか分からない場合は、必須とみなす。
+* match文が利用できる箇所では、if文よりもmatch文を使用する。
+    * 必要ならば `annofabapi.util.type_util.assert_noreturn` を使用して、match文の網羅性を保証する。
+

.agents/skills/test-writing/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: test-writing
+description: Pythonのテストコードを作成・修正するときに使用。
+---
+
+## テスト方針
+* `DummyApi`、`DummyService`、`FakeClient` のような自前の疑似実装は原則追加しない。
+* `monkeypatch` や `mock` は、外部API、ネットワーク、時刻、環境変数、ファイルシステム外の副作用など、テストで制御しないと不安定になる境界に限定して使用する。
+* 関数呼び出しの詳細に強く結びついたテストは、原則として追加しないでください。
+* `mock.assert_called_once_with(...)` のような配線確認だけのテストは、明確な回帰防止上の理由がある場合に限って追加してください。
+* テストを書くときは「そのテストが将来の設計変更を不必要に妨げないか」を確認してください。
+* ただし、外部API連携、ジョブ投入、通知送信、永続化など、副作用の境界にある処理では、呼び出し確認テストを許可します。
+* `argparse`などのCLIパーサーで制御している部分はテストを作成しないでください。たとえば必須引数が指定されない場合のエラーなどです。これはライブラリの責務だからです。
+
+
+## テストの実行方法
+* `uv run pytest` を使う。
+
+## テストコードの具体的なスタイル
+* テストファイルのディレクトリ構成やファイル名は、`annofabcli/`配下のプロダクションコードと対応させる。
+* 例外確認には `pytest.raises` を使用する。
+* `pytest.raises` ではエラーメッセージ文字列の確認は行わない。
+* 一時ディレクトリが必要な場合は `tmp_path` fixture を使う。
+* WebAPI にアクセスするテストには `pytest.mark.access_webapi` を付与する。CLI テストは、引数上はローカル処理に見えても共通ログイン処理を通る場合があるので注意する。
+

.codex/config.toml

@@ -0,0 +1,24 @@
+# 承認ポリシー。
+# "never" は、Codex がコマンド実行や権限昇格のたびに確認せず進む設定です。
+approval_policy = "never"
+
+# sandbox の種類。
+# "workspace-write" は、workspace 内と許可された追加パスへの書き込みを許可します。
+sandbox_mode = "workspace-write"
+
+[shell_environment_policy.set]
+# uv のキャッシュ先を /tmp 配下に固定し、ユーザー名依存のパスを避けます。
+UV_CACHE_DIR = "/tmp/uv-cache"
+
+[sandbox_workspace_write]
+# workspace-write sandbox 内で外向きネットワーク通信を許可します。
+network_access = true
+
+# workspace に加えて書き込みを許可する追加ディレクトリ一覧です。
+# 今回は uv キャッシュと一時ファイル用途を想定して /tmp を許可しています。
+writable_roots = [
+  "/tmp",
+]
+
+[features]
+codex_hooks = true

.github/copilot-instructions.md

@@ -1,40 +1,3 @@
 # copilot-instructions.md
 
-## プロジェクトの目的
-AnnofabのWebAPIのPythonクライアントライブラリです。
-
-## 開発でよく使うコマンド
-* コードのフォーマット: `make format`
-* Lintの実行: `make lint`
-* テストの実行: `make test`
-* ドキュメントの実行: `make docs`
-
-## 技術スタック
-* Python 3.9 以上
-* テストフレームワーク: Pytest v8 以上
-
-## ディレクトリ構造概要
-
-* `annofabcli/**`: アプリケーションのソースコード
-* `tests/**`: テストコード
-    * `tests/data/**`: テストコードが参照するリソース
-* `docs/*`: ドキュメント
-
-## コーディングスタイル
-
-### Python
-* dictから値を取得する際、必須なキーならばブラケット記法を使う。キーが必須がどうか分からない場合は、必須とみなす。
-* できるだけ`os.path`でなく`pathlib.Path`を使う（Lint`flake8-use-pathlib`に従う）
-* Noneの判定、空文字列の判定、長さが0のコレクションの判定は、falsyとして判定するのでなく、`if a is not None:`のように判定内容を明記してください。
-* 型ヒントを`dict`にする場合、`dict[str, Any]`のようにキーと値の型を指定する。
-
-### テストコード
-* Errorの確認は、`pytest.raises`を使用する。エラーメッセージの確認は行わない。
-* 一時ディレクトリを使用する場合は、`tmp_path` fixtureを利用する。
-
-
-## 作業の進め方
-* コードの修正が完了したら`make format`を実行してフォーマットを行い、その後`make lint`を実行してLintエラーがないことを確認する。
-
-## レビュー
-* PRレビューの際は、日本語でレビューを行う
+`AGENTS.md`や`.agents/skills/`以下のファイルを参照してください。

AGENTS.md

@@ -0,0 +1,15 @@
+
+## 想定する実行環境 
+* AIによる指摘や応答は日本語で書く。
+
+## コードの修正方針
+* 原則、破壊的変更を行って修正してください。コードをシンプルにするためです。
+* 何かを判断する際、コードの修正量は無視してください。AIが修正するので、そこは問題になりません。
+* リンターにより行数が長すぎるなどのエラーが発生した場合、必要ならばそのエラーを無視してください。読みやすさやシンプルさを優先してください。
+
+## Coding Agent による作業の進め方
+1. コードを修正する。関連するテストコードやドキュメントも修正する。
+2. 自分自身でレビューする
+3. `make format`, `make lint`を実行する。
+4. 関連するテストコードを実行する。
+5. Git にコミットする。ただしmainブランチで作業している場合は、pull requestを作成する。

annofabapi/util/annotation_specs.py

@@ -1,11 +1,49 @@
-from typing import Any, Literal
+from typing import Any, Literal, TypedDict, cast
 
 import more_itertools
 
 from annofabapi.models import Lang
+from annofabapi.pydantic_models.additional_data_definition_type import AdditionalDataDefinitionType
 
 
-def get_english_message(internationalization_message: dict[str, Any]) -> str:
+class InternationalizationMessageItem(TypedDict):
+    """多言語メッセージの1要素です。"""
+
+    lang: str
+    message: str
+
+
+class InternationalizationMessage(TypedDict):
+    """多言語メッセージです。"""
+
+    messages: list[InternationalizationMessageItem]
+
+
+class AttributeChoice(TypedDict):
+    """属性の選択肢です。"""
+
+    choice_id: str
+    name: InternationalizationMessage
+
+
+class AttributeDefinition(TypedDict):
+    """アノテーション仕様上の属性定義です。"""
+
+    additional_data_definition_id: str
+    name: InternationalizationMessage
+    type: AdditionalDataDefinitionType
+    choices: list[AttributeChoice] | None
+
+
+class LabelDefinition(TypedDict):
+    """アノテーション仕様上のラベル定義です。"""
+
+    label_id: str
+    label_name: InternationalizationMessage
+    additional_data_definitions: list[str]
+
+
+def get_english_message(internationalization_message: InternationalizationMessage | dict[str, Any]) -> str:
     """
     `InternationalizationMessage`クラスの値から、英語メッセージを取得します。
     英語メッセージが見つからない場合は ``ValueError`` をスローします。
@@ -22,7 +60,7 @@ def get_english_message(internationalization_message: dict[str, Any]) -> str:
     Raises:
         ValueError: 英語メッセージが見つからない場合
     """
-    messages: list[dict[str, str]] = internationalization_message["messages"]
+    messages = cast(list[InternationalizationMessageItem], internationalization_message["messages"])
     result = more_itertools.first_true(messages, pred=lambda e: e["lang"] == Lang.EN_US.value)
     if result is not None:
         return result["message"]
@@ -36,7 +74,7 @@ def get_english_message(internationalization_message: dict[str, Any]) -> str:
 """
 
 
-def get_message_with_lang(internationalization_message: dict[str, Any], lang: Lang | STR_LANG) -> str | None:
+def get_message_with_lang(internationalization_message: InternationalizationMessage | dict[str, Any], lang: Lang | STR_LANG) -> str | None:
     """
     `InternationalizationMessage`クラスの値から、指定した ``lang`` に対応するメッセージを取得します。
 
@@ -48,7 +86,7 @@ def get_message_with_lang(internationalization_message: dict[str, Any], lang: La
         指定した言語に対応するメッセージ。見つからない場合はNoneを返します。
 
     """
-    messages: list[dict[str, str]] = internationalization_message["messages"]
+    messages = cast(list[InternationalizationMessageItem], internationalization_message["messages"])
     if isinstance(lang, Lang):
         str_lang = lang.value
     else:
@@ -60,7 +98,7 @@ def get_message_with_lang(internationalization_message: dict[str, Any], lang: La
     return None
 
 
-def get_choice(choices: list[dict[str, Any]], *, choice_id: str | None = None, choice_name: str | None = None) -> dict[str, Any]:
+def get_choice(choices: list[AttributeChoice], *, choice_id: str | None = None, choice_name: str | None = None) -> AttributeChoice:
     """
     選択肢情報を取得します。
 
@@ -90,12 +128,12 @@ def get_choice(choices: list[dict[str, Any]], *, choice_id: str | None = None, c
 
 
 def get_attribute(
-    additionals: list[dict[str, Any]],
+    additionals: list[AttributeDefinition],
     *,
     attribute_id: str | None = None,
     attribute_name: str | None = None,
-    label: dict[str, Any] | None = None,
-) -> dict[str, Any]:
+    label: LabelDefinition | None = None,
+) -> AttributeDefinition:
     """
     属性情報を取得します。
 
@@ -133,7 +171,7 @@ def get_attribute(
     return result[0]
 
 
-def get_label(labels: list[dict[str, Any]], *, label_id: str | None = None, label_name: str | None = None) -> dict[str, Any]:
+def get_label(labels: list[LabelDefinition], *, label_id: str | None = None, label_name: str | None = None) -> LabelDefinition:
     """
     ラベル情報を取得します。
 
@@ -172,12 +210,12 @@ class AnnotationSpecsAccessor:
 
     def __init__(self, annotation_specs: dict[str, Any]) -> None:
         self.annotation_specs = annotation_specs
-        self.labels = annotation_specs["labels"]
-        self.additionals = annotation_specs["additionals"]
+        self.labels: list[LabelDefinition] = annotation_specs["labels"]
+        self.additionals: list[AttributeDefinition] = annotation_specs["additionals"]
 
     def get_attribute(
-        self, *, attribute_id: str | None = None, attribute_name: str | None = None, label: dict[str, Any] | None = None
-    ) -> dict[str, Any]:
+        self, *, attribute_id: str | None = None, attribute_name: str | None = None, label: LabelDefinition | None = None
+    ) -> AttributeDefinition:
         """
         属性情報を取得します。
 
@@ -192,7 +230,7 @@ def get_attribute(
         """
         return get_attribute(self.additionals, attribute_id=attribute_id, attribute_name=attribute_name, label=label)
 
-    def get_label(self, *, label_id: str | None = None, label_name: str | None = None) -> dict[str, Any]:
+    def get_label(self, *, label_id: str | None = None, label_name: str | None = None) -> LabelDefinition:
         """
         ラベル情報を取得します。