診断と規則のリファレンス

English · 日本語（このファイル）

karasu は問題を 2 つのレイヤーの語彙で報告する。

• 規則（rule）は 概念 — 言語が何を許し何を禁じるか（「edge はその所属 ブロックの内側から originate する」）。規則は、著者とこの spec が制約を語る ときの単位である。
• 診断（diagnostic）は メカニズム — 規則の具体的な違反 1 つを検出したとき に発火する、名前付きの検査（edge-source-mismatch）。

1 つの規則はしばしば複数の診断で強制され、1 つの診断はちょうど 1 つの規則に 属する。本書は両者を対応づけるカタログである。

本カタログの読み方

• 診断コードは安定 API である。 code 文字列（例: edge-source-mismatch） は LSP・app・下流ツールが消費する。規則の言い回しに合わせてコードを rename することはしない。規則名は概念、コードは契約であり、両者は別レイヤー（altitude） に位置する。規則がその診断名とは別の言い回しの方が自然なのは想定どおり。
• すべての診断コードは下記いずれか 1 つの規則ファミリーに属し、core が定義 する全コード（DiagnosticParamsByCode・WarningKind）が本書に現れる。この 完全性は meta-test で強制される（カタログの完全性 を参照）ため、新規コードは カタログ項目なしには出荷できない。
• 発火条件 列に具体的なトリガを記す。severity は core が emit する値。

register と severity

診断は severity を持つ: error / warning / info。

• error — モデルが不正で、該当構文は拒否される。
• warning — 著者が直すべき実際の欠陥（dangling な参照、スタイル衝突など）。
• info — 欠陥ではなく 事実。外部の流派が smell と呼びうる構造（共有 database、領域分散など）を、誤りと断じずに surface する。これが 事実 vs 流派 の register 区別である — TPL-1386 を参照。

karasu は未解決参照に対し warn-don’t-error（spec §S6）に従う。未解決の関係は 落とすが、参照元の node は保存し、レンダー全体を失敗させずに warning として報告 する。

規則ファミリー

宣言・edge の配置・構造

何をどこに宣言できるか、edge の起点が何でありうるか。service / domain ブロック 内に書いた edge はそのブロックの id を起点にする。infra ブロックと legend は配置 が固定。sync edge は循環してはならない。

Code	Severity	発火条件
edge-source-mismatch	error	service / domain / entity ブロック内の explicit な edge source が所属ブロック id と一致しない（edge origin scope 規則。entity では関連の向き — 起点 = 参照を保持する側 — を強制する）。
edge-endpoint-not-at-scope	warning	edge の endpoint がマージ後のモデルに存在するが、その edge を宣言したスコープの peer ではない（edge endpoint scope 規則）。例: service 配下の domain である A・B を system スコープで A -> B と書いた場合。この edge はどのビューにも描画されないため、source のブロック内に書くか、cross-domain の entity 参照は限定子付きにする。dotted ref とモデルに存在しない id は対象外（後者は unresolved-edge-endpoint が担当）。domain → domain は暗黙の service edge に集約されて描画されるため除外。
ambiguous-edge-base	warning	同じ from → to の base を持つ edge が複数あり、識別する author id が無い。
service-outside-system	warning	service が system の外で宣言されている。
infra-not-in-context	error	infra ブロック（database / queue / storage）が system の直接の子でない。
boundary-not-in-context	error	自身のキャンバスを持たない kind（entity / resource / user / client / infra leaf）の中に boundary ブロックが宣言されており、囲む対象が存在しない。
entity-not-in-domain	error	entity が domain の子以外の場所で宣言されている。
node-not-in-context	warning	論理ノードが、その親の 含められるもの 列に載っていない入れ子で宣言されている（例: client 内の usecase）。ノードは保持され描画もされるが、その位置での意味は定義されていない。言語 v2.0 で error 化予定（roadmap §Syntax 2.0）。
legend-not-top-level	error	legend ブロックがトップレベル以外で宣言されている。
top-level-declaration	error	user またはエッジが system ブロック内ではなくトップレベルで宣言されている。
system-property-conflict	warning	merge された import 間で system の label / description が衝突する。
cyclic-dependency	warning	sync edge（->）が依存の循環を形成する。

id の一意性

id は宣言 scope 内で一意であること。ownership は primary owner を高々 1 つに割り 当てる。

Code	Severity	発火条件
duplicate-edge-id	error	author 指定の edge id が別の edge id と衝突する。
duplicate-node-id-parent	error	node id が直近の親の中で重複する（1 つの domain 配下で usecase と entity が同じ id を持つケースも含む）。
entity-anchor-collision	warning	entity deep-link の名前空間（{全 domain id} ∪ {全 entity id}）で id が複数のターゲットに使われている — entity id が複数 domain にまたがって重複、または entity id が domain id と一致。deep-link の解決が曖昧になるが描画自体は成立する。
duplicate-node-in-system	error	node id が system 内で重複する。
duplicate-node-in-deploy	error	node id が deploy ブロック内で重複する。
duplicate-team-id	error	team id が重複する。
duplicate-team-in-organization	error	team id が organization 内で重複する。
duplicate-resource-operation	warning	1 つの resource に CRUD verb が複数回並ぶ。
duplicate-crud-decoration-target	warning	CRUD decoration が同じ operation を複数回対象にする。
duplicate-owner-assignment	info	node が複数の team に owned として割り当てられる（事実。ADR-1566 参照）。
duplicate-boundary-assignment	info	node が複数の boundary に所属する（事実。所属は 1:N — ビュー側の解決規則は syntax.ja.md を参照）。
boundary-membership-not-drawn	info	Group by: boundary で、非メンバーを覆わずに boundary の枠をメンバーまで広げられなかったため、その所属をカード上の ◇ タブで示した。model の事実を述べる duplicate-boundary-assignment と違い、この描画が何をしたかを述べる。したがって位置情報を持たず、この軸でのみ出る。
duplicate-boundary-id	error	同じ親ノード内の 2 つの boundary ブロックが同じ id を宣言しており、2 つ目を指し示せない。top-level のブロックは対象外。
duplicate-facet-id	error	2 つの facet ブロックが同じ id を宣言しており、facets の参照がどちらのメタデータを指すか決まらない。マージ後のモデルで判定するのでファイルをまたぐ重複も検出する。参照が解決するのは最初の宣言。
positional-label-removed	error	boundary / facet / organization / team / member の id 直後にラベル文字列が置かれている。ADR-19 で label はプロパティ化されており、位置ラベル記法は spec に存在しない。experimental な boundary / facet は deprecation を挟まず削除し（#2133）、残りは deprecation を経て削除した（#2208）。復帰動作は異なり、boundary / facet は文字列を捨てるが、organization / team / member は label として保持し、修正されるまで組織図が読める状態を保つ。
node-id-multiple-locations	warning	同じ node id が複数の場所に現れる。

cross-reference 解決（warn-don’t-error, §S6）

参照された id は宣言済み node に解決されること。解決できない場合、参照元 node は 保存し、未解決の関係を報告する（致命的エラーにはしない）— syntax spec §S6 参照。

Code	Severity	発火条件
owns-target-not-found	warning	team が、マージ後のモデルでどのノードも指さない id を owns する。kind と深さは問わないため、宣言済みの user や entity はここでは「見つかる」扱いで、kind による拒否は invalid-owns が行う。capability はノードではなくプロパティなのでどのノードにも解決せず、ここで報告される。マージ後のツリーから導出するため、判定は import の書き方にも宣言位置にも依存しない。import 結合の診断であり、未解決の import が残るドキュメントでは判定しない（LSP の単一ドキュメント文脈では沈黙し、App / CLI がマージ後モデルで判定する）。
invalid-owns	warning	owns 先がノードに解決され、その kind が所有できない。メッセージはその kind を名指す。どのノードにも解決しない id は本診断の担当ではなく owns-target-not-found が報告するため、1 つの誤りに対して出るのは 2 つのうち必ず一方だけ。その結果として import 結合になる: 単一ドキュメント文脈では cross-file の対象は何にも解決しないため何も報告しない。所有できる kind は service / domain / client と infra ブロック（深さは問わない。OWNS_TARGET_KINDS。これを読むのは本診断だけで、存在検査は kind を問わない）。infra leaf（table / queue-item / bucket）と capability は存在はするが所有の単位ではないため、それらを弾くのは本診断の担当。なお system view のカードに team チップが出るのは論理 kind だけだが、所有された infra も Group by: team のフレーム（id で解決）と org view には現れる。
contains-target-not-found	warning	import 結合の診断であり、未解決の import が残るドキュメントでは判定しない（member が import 先で宣言されている場合があり、スコープ内 contains が名指す子は cross-file の system 再オープンで後から増えうる）。それ以外の場合: boundary の contains 先が存在しない — top-level ブロックはマージ後の system 階層のどこにも無い場合（存在検証は per-file でなく cross-file マージ後）、スコープブロックは宣言ノードの直下の子に無い場合。
facet-not-declared	warning	facets の参照先の facet ブロックが宣言されていない（存在検証はマージ後のモデルで行うので、import 先の宣言も有効）。near-miss の annotation ヒントと違い、宣言集合が「正」を与えるためこの検査は完全で、著者定義の名前どうしの取り違えも検出する。
import-id-not-found	error	named import の id パスが解決できない。
import-path-not-found	error	import パスがいずれかのセグメントで解決できない。
unresolved-edge-endpoint	warning	edge の端点 id が merge 後のモデルのどこにも見つからない。
unresolved-handles	warning	handles 対象の domain が one-hop expose 規則で到達できない。
unresolved-realizes	warning	deploy node が論理層に無い対象を realizes する。
legend-ref-unresolved	warning	legend の ref がどのスタイル規則にも node にも一致しない。
cross-system-ref-unresolved	warning	cross-system edge（Sys.Svc）の対象が見つからない。
cross-system-ref-implicit-external	warning	cross-system edge が [external] 未付与の system に跨る。
delivers-target-not-client	warning	delivers の対象が client node でない。

infra の単一宣言・fan-in

infra node は 1 度だけ宣言される。複数 service から参照される store は surface する価値のある事実。

Code	Severity	発火条件
infra-redeclared-across-files	info	同じ database / queue / storage id が複数の merge 対象ファイルで宣言される。
infra-leaf-redeclared-silently	info	table / queue-item / bucket の leaf が親 infra 内で再宣言される。
shared-infra-fan-in	info	2 つ以上の service が 1 つの system 内で同じ store に依存する（欠陥ではなく事実）。
cross-domain-store-access	info	ある domain の usecase が、別の domain が所有する infra leaf を読み書きする（1 system 内。欠陥ではなく境界越えの事実）。所有は entity マッピングから導出、leaf 粒度で判定、[external] と役割タグ付き（[index] / [cache] / [analytics]）の store は除外。shared-infra-fan-in とは直交。

CRUD decoration の文法

resource への operation / CRUD decoration の文法。

Code	Severity	発火条件
invalid-crud-decoration	error	CRUD decoration が認識されない verb / letter を使う。
empty-crud-decoration	warning	verb: decoration の右辺が空。
unknown-resource-operation	warning	resource operation の verb が create / read / update / delete のいずれでもない。

割り当てと凝集

構造 node が owner / 親に割り当てられているか、domain と deploy 対象の配線に関する 凝集の事実。

Code	Severity	発火条件
unassigned-service	warning	service が team 割り当てなしにトップレベルに置かれる。
unassigned-domain	warning	domain がどの service にも割り当てられていない（トップレベル、または system 直下に置かれている）。2 つの配置は同じモデリング状態を表すため両方で発火する（#2184）。(Unassigned) 擬似 system に包まれるのはトップレベル形のみ。
unassigned-usecase	warning	usecase が domain の親なしに service の直接の子になる。
unassigned-client	warning	client が team 割り当てなしにトップレベルに置かれる。
unassigned-database	warning	database が team 割り当てなしにトップレベルに置かれる。
unassigned-queue	warning	queue が team 割り当てなしにトップレベルに置かれる。
unassigned-storage	warning	storage が team 割り当てなしにトップレベルに置かれる。
unassigned-resource	warning	bare resource <id> がどのストアにも解決しない（dot-notation でも [external] でも一意な entity でもない）。parser ではなく resolver がモデル全体で判定するため、一致する entity が宣言されると編集ゼロで昇格し警告は消える。曖昧（一致する entity が複数）な bare id は未解決のまま残り、衝突自体は entity-anchor-collision が報告する。
domain-dispersal	info	1 つの domain id が scope 内の複数 service にまたがる（事実）。
missing-realizes	info	deploy node に realizes プロパティが無い。
missing-runtime	info	deploy node に runtime プロパティが無い。

annotation・lifecycle

annotation パラメータ、削除・非推奨になったプロパティ、および非 builtin の tag / annotation 語彙の v1.x deprecation（構文 v2.0 はツール語彙のみを受理 — tags-annotations.ja.md 参照）。

Code	Severity	発火条件
annotation-param-unsupported	warning	annotation のパラメータ key がその annotation で認識されない。
annotation-possible-typo	info	annotation 名が builtin の near-match（typo の示唆）。
tag-not-builtin	warning	tag 名がツール語彙（builtin + system-assigned tag）の外にある。v1.x で非推奨。抑制条件なし。
tag-not-applicable	warning	組み込み tag が適用範囲外の kind に書かれている（例: service Api [index] — [index] は database に適用）。その場所では効果を持たない。tag-not-builtin と同時には発火しない（builtin 外の名前には違反する適用範囲が無いため）。
annotation-not-builtin	warning	annotation 名が builtin 集合の外にある。v1.x で非推奨。抑制条件なし。
style-tag-selector-not-builtin	warning	.krs.style のセレクタがツール語彙の外の tag 名を狙っている（例 [pci] { … }）。v1.x で非推奨 — ルール自体は引き続き一致する。構文 v2.0 はツール語彙のみに一致する。facet セレクタ（[facets=<id>]）へ移行する。モデル側の tag-not-builtin とは独立にセレクタ単位で発火する（両者は別々の編集を指しており、片方だけ警告すると残った方が見つからない）。builtin テーマや注入された system sheet では発火しない。
style-annotation-selector-not-builtin	warning	.krs.style のセレクタが builtin 集合の外の annotation 名を狙っている（例 @canary { … }）。契約は style-tag-selector-not-builtin と同じ。
team-property-removed	error	削除済みの team プロパティが使われる（ADR-1564 参照）。

import とファイル

import 宣言とスタイル import をファイルシステムに対して解決する。

Code	Severity	発火条件
circular-import	warning	node import が循環を形成する。
circular-style-import	warning	スタイル import が循環を形成する。
file-not-found	error	import されたファイルが存在しない。
directory-not-found	error	import されたディレクトリが存在しない。
style-file-not-found	warning	import されたスタイルファイルが存在しない。

スタイル検証

.krs.style のプロパティ名と値を検証する。

Code	Severity	発火条件
style-unknown-property	warning	スタイルのプロパティ名が認識されない。
style-invalid-enum-value	error	スタイル値が許可された enum に無い。
style-invalid-hex-color	error	スタイルの hex color が不正。
style-invalid-length-unit	error	スタイルの length が許可されない単位を使う。
style-missing-length-unit	error	スタイルの length に必要な単位が無い。
style-out-of-range	error	スタイルの数値が min / max の範囲外。
style-token-type-mismatch	error	スタイルの token が期待された型と一致しない。
expected-style-property-name	error	スタイルパーサがプロパティ名を期待した。
expected-semicolon-between-properties	error	スタイルパーサがプロパティ間の ; を期待した。
unknown-edge-selector-attribute	error	セレクタが from / to / facets 以外の属性を使っている（例: edge[source=X]）。コード名は facets より前からあるもので、facets は edge 限定ではなくノードセレクタでも受理される。
style-conflict	warning	セレクタが複数のユーザースタイルシートで定義される。
style-column-invalid-value	warning	スタイル column 値が left / center / right でない。
style-column-ignored-non-system-view	warning	column ヒントが deploy / org ビューに適用される（無視）。
style-grid-columns-invalid-value	warning	スタイル grid-columns 値が正の整数でない（ヒントは破棄され、レイアウトは自動バランスにフォールバック）。

client・capability

client サブ言語: storage kind と capability。

Code	Severity	発火条件
client-resource-invalid-kind	error	client の resource storage kind が予約値のいずれでもない。
client-capability-duplicate	warning	client が同じ capability 名を 2 度宣言する。

構文・パースレベルのエラー

token が妥当な構文を成さないときに上がる低レベルのパーサエラー。本質的にメカニズム レベルであり、「規則」は文法そのもの。

Code	Severity	発火条件
token-type-mismatch	error	token がパーサの期待した型と一致しない。
unexpected-token-root	error	root レベルに予期しない token。
unexpected-token-in-block	error	ブロック内に予期しない token。
expected-brace-or-string	error	パーサが { か string literal を期待した。
expected-identifier	error	パーサが identifier を期待した。
expected-string-after	error	パーサがプロパティ keyword の後に string を期待した。
expected-id-or-string	error	パーサが id か string を期待した。
expected-node-id	error	パーサが node id を期待した。
expected-property-value	error	パーサがプロパティ値を期待した。
expected-id-after	error	パーサがプロパティ keyword の後に id を期待した。
invalid-node-kind	error	node kind の keyword が認識されない。
property-not-for-node-kind	error	プロパティがその node kind に対して妥当でない。
link-url-scheme-not-allowed	warning	link URL の scheme が許可集合（http / https / mailto）に無い。

アプリケーションレベルのフォールバック

throw された compile / parse エラーを app が包むときに使う合成コード。

Code	Severity	発火条件
app-project-compile-error	error	compile() が throw し、app が汎用の compile 失敗を報告する。
app-org-parse-error	error	org パースが throw し、app が汎用の parse 失敗を報告する。
generic-text	error	構造化パラメータを持たない、事前生成のフォールバックメッセージ文字列。

カタログの完全性

DiagnosticParamsByCode と WarningKind（packages/core/src/types）の全メンバーは、 本書に code として現れなければならない。meta-test （packages/core/src/types/diagnostics-catalog.test.ts）が双方向でこれを assert するため、カタログが emit されるコードから無言で drift することはない。背景の規律は TPL-1623 に記録する。

Related TPLs: TPL-1623（カタログ ↔ コードの完全性）, TPL-1386（事実 vs 流派の register）, TPL-2171（spec が約束する診断は実装されている）, TPL-1296（spec ↔ source-of-truth 同期）.